Document preprocessor parity strategy outside core

[rlippmann]

Summary

Document the project decision that future acquisition-layer parity work is not a context-compiler-ts core deliverable and will instead be handled by a future TypeScript directive-drafter package/repository.

Problem this solves

The repository currently needs a clear architectural record for two facts that are both true at the same time:

• context-compiler-ts currently tracks the Python fixture baseline pinned in CI to Python context-compiler v0.7.9 (caf37689ee6c1c99ddf0067f6486daf6cc9bb0ed).
• Starting with context-compiler-ts 0.8, core is no longer the intended long-term owner for acquisition-layer behavior.

Without an explicit issue documenting the plan, it is easy to assume that any future preprocessor or directive-drafter parity catch-up against Python should continue to happen inside context-compiler-ts core. That expectation no longer matches the architecture after context-compiler-ts 0.8, where acquisition-layer ownership is being removed from core.

Proposed change

Background

• The Python reference implementation remains the source of truth for semantics.
• context-compiler-ts currently tracks a Python fixture baseline pinned in CI to commit caf37689ee6c1c99ddf0067f6486daf6cc9bb0ed, which corresponds to Python context-compiler v0.7.9.
• This means the architectural handoff is not being driven simply by an outdated fixture pin or a mistaken assumption that TypeScript is still tied to a much older Python release.
• Starting with context-compiler-ts 0.8, core no longer owns acquisition-layer behavior as a long-term responsibility.
• A future TypeScript directive-drafter package/repository will own acquisition-layer behavior, including future preprocessor or directive-drafter parity work against the Python line.

Decision

Future preprocessor or directive-drafter parity work against Python behavior will not be implemented in context-compiler-ts core.

Instead, that work will be deferred to the future TypeScript directive-drafter package/repository, which will own acquisition-layer concerns and any corresponding parity plan.

Rationale

• It keeps context-compiler-ts focused on the deterministic core compiler behavior that this repository is intended to port.
• It makes the ownership boundary explicit: the reason future acquisition-layer parity work is moving is package responsibility, not simply version lag.
• It avoids rebuilding acquisition-layer ownership inside a package that is explicitly moving away from that responsibility in 0.8.
• It reduces the risk of mixing core compiler parity work with preprocessor or directive-drafter behavior that belongs at a different layer.
• It creates a clear boundary for future parity discussions: core engine semantics stay here, acquisition-layer behavior moves to directive-drafter.
• It gives maintainers and contributors a stable answer when future acquisition-layer parity gaps are discovered relative to Python releases after the current core-aligned baseline.

Success criteria

• Maintainers can point to a single issue that explains why future preprocessor or directive-drafter parity work is out of scope for context-compiler-ts core.
• New parity work in this repository remains scoped to core compiler semantics, fixtures, and stateful engine behavior.
• Future directive-drafter planning can reference this issue as the handoff point for acquisition-layer ownership.
• Contributors do not open core fixes expecting context-compiler-ts to remain the long-term home for acquisition-layer parity work.

Scope and compatibility notes

• Does this change affect Python parity semantics?
• No. This records package/repository ownership boundaries rather than changing current runtime behavior.

Alternatives considered

• Continue implementing future preprocessor or directive-drafter parity work in context-compiler-ts core.
  • Rejected because it conflicts with the 0.8 ownership boundary and couples acquisition-layer work back into the core package.
• Leave the strategy undocumented and handle questions case-by-case.
  • Rejected because it invites repeated confusion about scope, parity expectations, and where future work belongs.

[rlippmann]

Update from TS directive-drafter port work:

A concrete preprocessor API-shape mismatch was found while enforcing the synced Python directive-drafter public-api-v1.json contract in context-compiler-directive-drafter-ts.

Findings:

• context-compiler-ts currently exposes preprocessHeuristic / preprocess_heuristic from the experimental preprocessor subpath with TS-core-style return shape:
  • { classification, output }
• Python context-compiler-directive-drafter exposes preprocess_heuristic with Python public API shape:
  • { outcome, directive, rule_id }
• The TS core preprocessor fixture runner has normalized heuristic results from the first fixture-runner commit, accepting either classification/output or outcome/directive and comparing normalized classification/output fixture semantics.
• Therefore TS core’s preprocessor fixtures proved heuristic behavior parity, but did not enforce public return-shape parity for preprocess_heuristic.
• The API-contract fixture checked required export names, but not return object shape.

Implication for this issue:

• Future acquisition-layer parity should remain out of scope for context-compiler-ts core, as already stated here.
• The dedicated TS directive-drafter package should own Python-parity behavior and public API shape going forward.
• During TS core 0.8 extraction/removal work, migration notes should call out that current TS core experimental preprocessHeuristic uses classification/output, while the directive-drafter package is expected to follow Python directive-drafter public shape outcome/directive/rule_id.
• Existing TS core docs/tests should avoid implying exact public API-shape parity for the experimental preprocessor; they currently establish behavior parity via normalized fixtures.