Skip to content

Commit 4d5f0d7

Browse files
committed
docs(P-022): fold Codex review — bridge edges, span leaf, FFI consumer, snapshot keys
Four findings, all confirmed doc-consistency defects: - own-syntax added to own-bridge's edge set (P2): the bridge lowers facts to core-AST nodes, and the AST lives in own-syntax — without the edge the first cargo-metadata test would encode a boundary the bridge cannot satisfy (undeclared dep or a leaky re-export through own-cfg). Diagram, crate bullet, and fitness rule all updated. - Stale 'own-ir/own-syntax' in the topology prose (P3): own-diagnostics depends only on the span leaf in own-ir; the earlier paragraph still allowed the parser edge the bullet forbids. Now names only the leaf. - FFI vs only-own-cli (P2): the Why permits stdio OR FFI, but the fitness rule only allowed own-cli to depend on the bridge — which would forbid the stated extension shape. Rule now reads 'only entry-point crates' (own-cli today; future own-lsp / own-capi cdylib), never a core crate. - Snapshot regeneration on either key (P3): (corpus hash, py commit) keyed snapshots regenerate on a corpus/fixture change too, not only a Python change — otherwise CI diffs stale outputs or skips new inputs.
1 parent b3748e0 commit 4d5f0d7

1 file changed

Lines changed: 23 additions & 14 deletions

File tree

‎docs/proposals/P-022-rust-core-migration.md‎

Lines changed: 23 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -92,9 +92,10 @@ Arrow = "is depended on by" (dependency → dependent, i.e. build order):
9292
# own-analysis *constructs* Diagnostic/Evidence, so it depends on own-diagnostics;
9393
# own-diagnostics depends only on the span/location leaf — never on the solver.
9494
95-
own-ir + own-cfg + own-analysis + own-diagnostics ─▶ own-bridge
95+
own-ir + own-syntax + own-cfg + own-analysis + own-diagnostics ─▶ own-bridge
9696
# facts → core lowering + interprocedural MOS inference + verdict mapping
97-
# (today's ownir.py beyond the schema; the flagship C#→facts→verdicts path)
97+
# (today's ownir.py beyond the schema; the flagship C#→facts→verdicts path;
98+
# own-syntax is required — the lowering *constructs* core AST nodes)
9899
99100
{all of the above, incl. own-bridge} ─▶ own-cli (check / emit / cfg / report / ownir / explain)
100101
own-cli ◀─ own-oracle (dev/test: differential harness vs Python)
@@ -104,9 +105,9 @@ The non-obvious edge is **`own-analysis → own-diagnostics`**: the solver *cons
104105
`Diagnostic`/`Evidence` values (in Python, `analysis.py` imports and builds them from
105106
`diagnostics.py` using solver-internal state), and those types are *owned by*
106107
`own-diagnostics` — so analysis depends on diagnostics, **not the reverse**.
107-
`own-diagnostics` therefore stays upstream, depending only on span/location primitives
108-
(`own-ir`/`own-syntax`), never on the solver — which is exactly the fitness function
109-
below. `own-codegen` is the true **sibling**: it hangs off `own-cfg`/AST *only* and is
108+
`own-diagnostics` therefore stays upstream, depending only on the span/location leaf
109+
in `own-ir` (**not** `own-syntax` — the presentation crate must not drag in the
110+
parser), never on the solver — which is exactly the fitness function below. `own-codegen` is the true **sibling**: it hangs off `own-cfg`/AST *only* and is
110111
**verdict-independent** (Python `codegen.generate(mod)` takes just the AST — its policy
111112
comes from `_laminar_scopes`/`_buffer_modes`, not analysis conclusions). Codegen must
112113
not chain through diagnostics or reach into the solver; if Rust codegen ever *does* want
@@ -143,8 +144,9 @@ to flag on its own.
143144
minting, localmap kill-on-rebind), the interprocedural **MOS** inference
144145
(`_build_skeletons`, `_infer_return_skeleton`, `_infer_param_effect`, the BCL
145146
fresh-factory table), branch-local hoisting, and `check_facts`' fact→verdict
146-
mapping. Consumes `own-ir` facts, drives the `own-cfg`/`own-analysis` pipeline,
147-
constructs `own-diagnostics` findings. This is the flagship path (real C# → facts
147+
mapping. Consumes `own-ir` facts, **constructs `own-syntax` AST nodes** (the
148+
lowering's output), drives the `own-cfg`/`own-analysis` pipeline, constructs
149+
`own-diagnostics` findings. This is the flagship path (real C# → facts
148150
→ verdicts); **porting it is a named migration step**, and its inference semantics
149151
get a normative write-up *before* the port (today they are pinned only by
150152
`test_ownir.py` examples — see the tech-debt register, "OwnIR: formalize").
@@ -408,10 +410,13 @@ allowed edge set:
408410
for now — not on `own-analysis` either (codegen is verdict-independent). A future
409411
`own-codegen → own-analysis` edge is allowed only as a deliberate, reviewed change
410412
to the allowed set, never implicitly.
411-
- **`own-bridge` is the one deliberately wide consumer** (ir + cfg + analysis +
412-
diagnostics) — that width is its job. The constraint runs the other way: **nothing
413-
depends on `own-bridge` except `own-cli`**, so bridge inference can never leak into
414-
the core solver or the verdict layer.
413+
- **`own-bridge` is the one deliberately wide consumer** (ir + syntax + cfg +
414+
analysis + diagnostics) — that width is its job. The constraint runs the other way:
415+
**only *entry-point* crates may depend on `own-bridge`** — `own-cli` today, plus a
416+
future `own-lsp` server and/or `own-capi` (`cdylib`) when the IDE's FFI shape lands
417+
(the Why explicitly allows stdio *or* FFI, so the edge test must not forbid the
418+
stated extension shape). Never a core crate — bridge inference can never leak into
419+
the solver or the verdict layer.
415420

416421
## The differential oracle (Python repo = golden test)
417422

@@ -456,9 +461,13 @@ SARIF/JSON shapes. So:
456461
- **CI ratchet — against snapshots, not a live Python run.** Don't execute the Python
457462
core on every CI pass: commit its outputs as **golden snapshots keyed by
458463
(corpus hash, Python-core commit)** and diff Rust against the snapshots; regenerate
459-
only when Python itself changes (already the exception, not the rule). Otherwise CI
460-
time grows with corpus × Python and the ratchet gets disabled "temporarily" — the
461-
death of every ratchet. Coverage starts small and grows; the gate only tightens.
464+
when **either key changes** — a Python-core change *or* a corpus/fixture
465+
addition/edit (a new input under an unchanged Python commit still needs fresh
466+
expected outputs, or CI diffs Rust against stale ones / silently skips the new
467+
input). Both are the exception, not the rule; the steady state runs zero Python.
468+
Otherwise CI time grows with corpus × Python and the ratchet gets disabled
469+
"temporarily" — the death of every ratchet. Coverage starts small and grows; the
470+
gate only tightens.
462471
- **Error-text parity is fixture-backed.** Parser/diagnostic message texts live in
463472
shared fixtures asserted from *both* implementations; otherwise "identical error
464473
messages" rests on copy-paste and drifts silently.

0 commit comments

Comments
 (0)