P-022 step 6a: formalize OwnIR bridge semantics before the Rust port #258

Parent: #250
Recommended tier: strong, design-first
Depends on: #251

Goal

Write the normative contract for everything in the current Python OwnIR bridge that determines verdicts beyond the JSON schema, before any production Rust own-bridge implementation begins.

The bridge is not merely deserialization. It currently owns lowering, handle/RID creation, interprocedural MOS inference, call resolution, branch-local behavior, effect/DI fact preparation, and final fact-to-verdict mapping. These semantics must stop living only in examples and implementation accidents.

Sources of truth

• ownlang/ownir.py
• tests/test_ownir.py and related fixtures
• spec/OwnIR.md / schema
• interprocedural roadmap/TZ notes
• P-022 step 4: port own-analysis (worklist solver + ownership/lifetime/effect/DI) with layered diagnostic parity #214/feat(rust): P-022 step 4 — port own-analysis (worklist solver + ownership/lifetime/effect/DI) with layered parity (#214) #249 analysis contracts
• P-022 crate topology

Deliverable

Produce a normative bridge specification and a complete behavior inventory.

1. OwnIR validation

Define:

• supported version behavior;
• additive optional fields;
• unknown vocabulary handling;
• missing/duplicate IDs and names;
• invalid references;
• malformed locations;
• path rules;
• deterministic input ordering;
• fail-loud versus conservative fallback cases.

2. Fact lowering

Define:

• facts → core AST/CFG;
• RID/handle minting;
• resource identity;
• local map behavior;
• kill-on-rebind;
• branch-local hoisting/state;
• loops and merge behavior;
• unresolved or metadata-only symbols;
• source-location preservation.

3. Interprocedural MOS

Normatively define:

• Fresh;
• Borrow;
• Consume;
• Forward;
• mixed/unknown summaries;
• overload sig keys and fallback resolution;
• canonical/global-qualified names;
• first-party/external classification;
• recursion and cycles;
• duplicate definitions;
• return skeletons and parameter effects;
• BCL factory/fresh table;
• conservative behavior when inference is incomplete.

4. Facts into analyses

Define how the bridge constructs inputs for:

• ownership;
• lifetime;
• buffer policy;
• effect;
• DI.

The bridge may prepare facts but must not duplicate solver/DFS algorithms already owned by own-analysis.

5. Verdict mapping

Define the bridge's responsibility for:

• file/span mapping;
• source subject/resource names;
• preserving analysis-selected primary anchors;
• registration/context locations;
• diagnostic ordering.

The bridge must not repair a wrong analysis verdict by replacing its code or primary location.

Behavior matrix

Create a machine-readable or tabular inventory mapping every existing OwnIR test family to:

behavior name
Python source location
normative rule
existing tests/fixtures
Rust fixture required
ambiguities/open decisions

No test family may be silently omitted.

Ambiguity handling

If Python behavior appears buggy:

• do not silently specify a preferred Rust behavior;
• either document current Python behavior as the migration contract;
• or open a separate Python-first issue/PR to change it before the port.

Fixture plan

Specify three parity layers for the implementation issue:

1. OwnIR validation acceptance/rejection;
2. OwnIR → normalized lowered representation;
3. OwnIR → final normalized diagnostics.

Include explicit regeneration and zero-Python steady-state expectations.

Guardrails

• Design/docs/tests inventory only; no production own-bridge crate in this issue.
• No schema redesign.
• No new diagnostic behavior.
• No Rust optimization.
• No CLI work.
• No changing Python behavior merely to make the spec cleaner.

Acceptance

• Every current OwnIR verdict-determining behavior has a normative rule or an explicit open decision.
• Every test_ownir.py family is mapped.
• Bridge versus analysis ownership is explicit.
• Validation/lowering/MOS/verdict fixture plans are complete.
• Open ambiguities are separate issues, not hidden TODO comments.
• Independent review approves the spec before P-022 step 6b: implement Rust own-bridge with layered OwnIR parity #259 begins implementation.