Curated Documentation Surface

CX Documentation

Kernel-owned proof path, live MCP workspace surface, and durable cognition notes.

This document records the internal interfaces that cx treats as stable architecture seams before any plugin or extension system is introduced.

These interfaces are not public package APIs, but they are internal contract surfaces. Changes to them should be deliberate, reviewed, and accompanied by tests and documentation updates.

RenderEngine

Defined in src/render/types.ts.

RenderEngine owns proof-path section rendering.

Responsibilities:

  • render section output for xml, markdown, json, and plain

  • return output token counts

  • return file content hashes

  • return spans where the style requires them

  • return structured plans and plan hashes when required

Rule:

  • proof-path callers depend on RenderEngine, not on a concrete renderer

StructuredRenderPlan

Defined in src/render/types.ts.

StructuredRenderPlan is the kernel-owned proof model for rendered section entries.

Responsibilities:

  • stable entry ordering

  • stable content identity

  • stable per-entry token counts

  • language tagging when available

Rule:

  • verification logic depends on the structured plan contract, not on adapter output shapes

TokenizerProvider

Defined in src/shared/tokenizer.ts.

TokenizerProvider owns deterministic token counting.

Responsibilities:

  • count tokens for in-memory text

  • count tokens for files on disk

  • provide a stable seam between callers and tokenizer implementations

Current default implementation:

Rule:

  • bundle planning, bundle reporting, and inspect reporting should depend on the provider interface instead of calling tokenizer implementations directly

ScannerPipeline

Defined in src/doctor/scanner.ts.

ScannerPipeline owns bundle-stage security scanning.

Responsibilities:

  • scan source files before proof artifacts are finalized

  • optionally scan rendered bundle artifacts before finalization

  • return structured findings with:

    • scanner id

    • profile

    • stage

    • severity

    • proof-blocking status

  • keep scanner selection explicit through known scanner IDs

  • enforce explicit fail/warn handling

Current default implementation:

  • the reference scanner bridge around the installed oracle scanner

Current bounded configuration:

  • explicit scanner IDs

  • source-stage scanning

  • optional post-pack artifact scanning

Non-goals:

  • plugin discovery

  • open-ended scanner loading

  • implicit proof-path scanner activation

Rule:

  • scanning behavior belongs to the pipeline contract, not to renderer helpers

Adapter-Oriented Expert Surfaces

The adapter/oracle seam and the cx adapter command family are expert diagnostic surfaces.

They exist for:

  • parity diagnostics

  • oracle capability inspection

  • migration and reference testing

They are not part of ordinary proof-path execution, and production bundle or verification flows must not depend on them.

Stability Rules

  • Add new internal interfaces only when they create a durable ownership boundary.

  • Refactors that cross these seams must preserve contract tests and runtime behavior.

  • Do not introduce plugin-facing variability into these interfaces until the plugin system itself is explicitly implemented.