Skip to content

Commit fc9b7a2

Browse files
committed
fix(ownir): fail-loud on unknown resource kind + spec the effects block
Review follow-ups on PR #172. - CodeRabbit (Major): a present-but-unknown resource kind fell through the §4 routing to the owned/subscription path and was mis-classified -- the same silent-misroute that N1 fixes for flow ops. load() now rejects a present-but-unknown "resource" against the known-kinds set (_KNOWN_RESOURCE_KINDS); an ABSENT field still defaults to "subscription" (additive). So a new kind is a vocabulary change that must bump OWNIR_VERSION -- spec/OwnIR.md section 2 table + IR3/IR4 updated, docstring corrected (field-vs-value). Pinned by two test_ownir checks (unknown kind raises; absent defaults). 213/213. - Codex (P2): the top-level "effects" block (OwnTS emits it, effects.py consumes it -> EFF001) was missing from the spec envelope -- generating types from the spec would drop/reject effect facts. Added to section 1 and a new section 7 documenting its shape (io/line/deps/bindings); Rules/Conformance renumbered; conformance updated. - Register section 2: correct the now-inaccurate "unknown kinds coerce to subscription" note to the closed-enum-for-present-values reality. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FJSfUpRbRXegrwJNV1rx1X
1 parent 6aad152 commit fc9b7a2

4 files changed

Lines changed: 107 additions & 33 deletions

File tree

‎docs/notes/tech-debt-register.md‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -125,10 +125,11 @@ The formalization stack, in order of actual protection delivered:
125125
3. **`spec/OwnIR.md`** ✅ (shipped) **+ `spec/ownir.schema.json`** (JSON Schema
126126
draft 2020-12, `ownir_version` as a `const`) — **the schema's trigger has now
127127
fired** (see the box below). Validate all `tests/fixtures/ownir/*.json` and
128-
each frontend's output against it. The schema must encode the *deliberate*
129-
open points — unknown resource kinds coerce to `subscription` by documented
130-
design (`ownir.py:66-70`), so the resource-kind enum is open; its job is
131-
shape/type/enum guarantees, not vocabulary closure.
128+
each frontend's output against it. The resource-kind enum is **closed** for
129+
*present* values — a present-but-unknown kind is rejected at load (it changes
130+
routing; a new kind bumps `OWNIR_VERSION`), while an *absent* `resource` field
131+
still defaults to `subscription`; the schema should mirror that (enum of known
132+
kinds, field optional). Its job is shape/type/enum guarantees.
132133
4. **A written evolution policy** ✅ *(now shipped in `spec/OwnIR.md` §2, rules
133134
IR1–IR6)*: additive optional fields / new resource kinds do not bump
134135
`OWNIR_VERSION`; a **new op or changed op semantics does**.

‎ownlang/ownir.py‎

Lines changed: 24 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -66,8 +66,11 @@
6666
advisory OWN050 "leakage analysis skipped" note, never a leak (P-014 Tier A).
6767
6868
An unreleased entry is the core's OWN001 (owned-but-not-released) at the C#
69-
`line`. The `resource`/`type` fields are additive and optional, so they do NOT
70-
bump `ownir_version`: an older core just reads every entry as a subscription.
69+
`line`. The `resource`/`type` FIELDS are additive and optional — an older core
70+
that predates them reads an entry with no `resource` as a subscription. But a new
71+
resource-kind VALUE is a vocabulary change, not additive metadata: the kind
72+
selects the analysis path, so a PRESENT-but-unknown kind is rejected at load
73+
(fail-loud), and introducing one MUST bump `ownir_version` (spec/OwnIR.md §2).
7174
A `capture` entry instead routes through the lifetime/region engine and surfaces
7275
as OWN014 (region escape) when its source provably outlives — see docs/proposals/
7376
P-004 and docs/lifetimes.md (the C# facts now reach the region core, not only the
@@ -214,6 +217,16 @@ def _esc_prop(s: str) -> str:
214217
"pool": ("PooledBuffer", "pooled buffer"),
215218
}
216219

220+
# Every resource-kind discriminator the core routes on (the `_RESOURCES` owned
221+
# kinds, plus `capture` — routed to the lifetime/region engine — and
222+
# `unresolved-subscription` — skipped to an advisory OWN050). The kind CHANGES the
223+
# analysis path (§4 of spec/OwnIR.md), so it is NOT metadata: a PRESENT-but-unknown
224+
# kind is rejected at load (fail-loud, like an unknown flow op), never silently
225+
# routed as a `subscription`. An ABSENT `resource` field still defaults to
226+
# `subscription` (an old extractor that predates the field). Consequence: adding a
227+
# new kind is a vocabulary change that MUST bump OWNIR_VERSION (spec/OwnIR.md §2).
228+
_KNOWN_RESOURCE_KINDS = frozenset(_RESOURCES) | {"capture", "unresolved-subscription"}
229+
217230
# --- P-004 region escape (the `capture` resource kind) ----------------------
218231
# A `capture` is a tokenless strong subscription routed NOT through the
219232
# acquire/release ownership model but through the lifetime/region engine
@@ -472,6 +485,15 @@ def load(path: str) -> dict[str, Any]:
472485
if not isinstance(r, str):
473486
raise OwnIRError(
474487
f"subscription 'resource' must be a string, got {r!r}")
488+
# A present-but-unknown kind changes routing (§4), so reject it rather
489+
# than let it fall through to the owned/subscription path and mis-route
490+
# — the same fail-loud rule as an unknown flow op. A new kind must bump
491+
# OWNIR_VERSION (spec/OwnIR.md §2). An absent field defaulted to
492+
# "subscription" above, which is known.
493+
if r not in _KNOWN_RESOURCE_KINDS:
494+
raise OwnIRError(
495+
f"unknown resource kind {r!r} — a new kind is a vocabulary "
496+
f"change that must bump OWNIR_VERSION (see spec/OwnIR.md §2)")
475497
t = s.get("type")
476498
if t is not None and not isinstance(t, str):
477499
raise OwnIRError(

‎spec/OwnIR.md‎

Lines changed: 62 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
> **Status: normative, descriptive.** This document specifies the OwnIR fact
44
> contract *as it is today*, derived from the working bridge
5-
> (`ownlang/ownir.py`) and pinned by tests (see [§8 Conformance](#8-conformance)).
5+
> (`ownlang/ownir.py`) and pinned by tests (see [§9 Conformance](#9-conformance)).
66
> Forward-looking ideas live in [`docs/proposals/`](../docs/proposals/), never
77
> here.
88
@@ -23,16 +23,17 @@ A facts document is a single JSON object:
2323
"module": "WpfApp",
2424
"components": [ /* §4 owned-resource records, grouped by type */ ],
2525
"functions": [ /* §5 flow bodies (intra-procedural CFG facts) */ ],
26-
"services": [ /* §6 DI registration graph */ ]
26+
"services": [ /* §6 DI registration graph */ ],
27+
"effects": [ /* §7 reactive-effect graph (EFF001) */ ]
2728
}
2829
```
2930

3031
`ownir_version` (int) and `module` (string) are required; `components`,
31-
`functions`, and `services` are each optional and default to empty. `load()`
32-
([`ownir.py`](../ownlang/ownir.py)) validates the shape and raises `OwnIRError`
33-
(a `ValueError`) with an actionable message on any violation — types, the
34-
`bool`-is-`int` trap, empty identity strings, and unknown DI lifetime enums are
35-
all rejected at load, before any analysis.
32+
`functions`, `services`, and `effects` are each optional and default to empty.
33+
`load()` ([`ownir.py`](../ownlang/ownir.py)) validates the shape and raises
34+
`OwnIRError` (a `ValueError`) with an actionable message on any violation — types,
35+
the `bool`-is-`int` trap, empty identity strings, unknown DI lifetime enums, and
36+
a present-but-unknown resource kind are all rejected at load, before any analysis.
3637

3738
## 2. Versioning and the evolution policy (normative)
3839

@@ -48,20 +49,29 @@ What bumps the version — the rule that keeps the three producers honest:
4849

4950
| Change | Bumps `OWNIR_VERSION`? |
5051
|---|---|
51-
| Add an **optional** field with a safe default (e.g. `resource`, `type`, `source_type`) | **No** — an older core reads the record without it (see §4). |
52-
| Add a new **resource kind** discriminator value (§4) | **No** — unknown kinds coerce to `subscription` by design; additive. |
52+
| Add an **optional** field with a safe default (e.g. `type`, `source_type`) | **No** — an older core reads the record without it (see §4). |
53+
| Add a new **resource kind** discriminator value (§4) | **Yes** — the kind selects the analysis path (§4 routing), so it is a vocabulary change, not additive metadata; a present-but-unknown kind is rejected at load. |
5354
| Add, rename, remove, or change the meaning of a **flow op** (§5) | **Yes** — vocabulary change (see the guard below). |
5455
| Remove or rename a required field, or change a field's semantics | **Yes** — not backward-readable. |
5556

56-
**Fail-loud guarantee (unknown flow op).** The flow lowerer (`_lower_flow`)
57-
handles exactly the ops in [§5](#5-flow-bodies-functions). Encountering any other
58-
op raises `OwnIRError` — it is **never** silently skipped, because skipping a
59-
compound op would drop the acquire/release facts nested inside it and flip
60-
verdicts (a fabricated leak from a lost release, or a hidden leak from a lost
61-
acquire) while every existing fixture still passes. A newer extractor that emits
62-
a new op against an un-bumped core therefore fails the run instead of
63-
mis-analyzing it. This is why a new op **must** bump `OWNIR_VERSION` per the
64-
table above.
57+
**Fail-loud guarantee (unknown vocabulary).** Two discriminators select an
58+
analysis path and so must never be silently mis-read:
59+
60+
- **Flow op (§5).** The flow lowerer (`_lower_flow`) handles exactly the ops in
61+
[§5](#5-flow-bodies-functions); any other op raises `OwnIRError` — never a
62+
silent skip, because skipping a compound op would drop the acquire/release facts
63+
nested inside it and flip verdicts (a fabricated leak from a lost release, or a
64+
hidden leak from a lost acquire) while every existing fixture still passes.
65+
- **Resource kind (§4).** A `resource` value the core does not know changes
66+
routing (`capture` → the region engine, `pool` → a pooled buffer, …), so a
67+
present-but-unknown kind raises at load rather than falling through to the
68+
`subscription` path and mis-classifying the fact. An **absent** `resource`
69+
field still defaults to `subscription` — that is the old-extractor-predates-the-
70+
field case, and adding the field is genuinely additive.
71+
72+
A newer extractor that introduces either against an un-bumped core therefore fails
73+
the run instead of mis-analyzing it — which is why both **must** bump
74+
`OWNIR_VERSION` per the table above.
6575

6676
## 3. What OwnIR is not
6777

@@ -144,32 +154,57 @@ source proven to outlive the subscriber escalates its OWN001 warning to **OWN014
144154
(a proven captive/region escape); a co-lifetimed-or-shorter source is refuted and
145155
silent; an unresolved `source_type` stays the honest OWN001 warning.
146156

147-
## 7. Rules
157+
## 7. Reactive effects (`effects[]`)
158+
159+
An optional top-level array feeding the **EFF001** effect-storm check (P-020, the
160+
OwnTS `Own.React` profile) — a separate core analysis
161+
([`ownlang/effects.py`](../ownlang/effects.py)) over an effect's dependency array
162+
and the stability of the render-scope values it closes over:
163+
164+
```json
165+
"effects": [
166+
{"io": true, "line": 20, "deps": ["query"],
167+
"bindings": [{"name": "query", "init": "useState", "refs": [], "line": 8}]}
168+
]
169+
```
170+
171+
Each effect carries `io` (bool — whether it performs I/O; default `false`),
172+
`line` (int), `deps` (array of dependency names), and `bindings` (the render-scope
173+
binding table: each a `{name, init, refs, line}` — an unstable dependency, e.g. an
174+
object/array rebuilt every render, re-triggers the effect). An I/O effect whose
175+
dep is unstable is EFF001 (the effect storm — "not all lifecycle bugs leak memory;
176+
some leak requests"). Like `services`, this block is additive/optional; the core
177+
decides identity stability, not the frontend.
178+
179+
## 8. Rules
148180

149181
- **IR1.** `ownir_version` must equal the core's `OWNIR_VERSION` (or be absent);
150182
otherwise `load()` raises `OwnIRError`.
151183
- **IR2.** Every producer stamps the same `OWNIR_VERSION`.
152-
- **IR3.** Additive optional fields and new resource-kind values do **not** bump
153-
the version; a new/changed/removed flow op or required field does.
154-
- **IR4.** An unknown flow op raises `OwnIRError` — never a silent skip.
184+
- **IR3.** Additive optional *fields* do **not** bump the version; a new/changed/
185+
removed **flow op** or **resource-kind value**, or a changed/removed required
186+
field, **does** (both are analysis-path vocabulary — see IR4).
187+
- **IR4.** A present-but-unknown **flow op** or **resource kind** raises
188+
`OwnIRError` — never a silent skip or a fall-through to the wrong path.
155189
- **IR5.** A core diagnostic the bridge cannot map to a fact handle raises —
156190
never a silently dropped verdict.
157191
- **IR6.** A frontend emits facts only; all verdicts come from the core.
158192

159-
## 8. Conformance
193+
## 9. Conformance
160194

161195
Pinned by [`tests/test_ownir.py`](../tests/test_ownir.py) (the bridge suite,
162196
`python tests/test_ownir.py`), not `test_spec.py` (OwnIR is a bridge contract,
163197
not a surface-language rule):
164198

165199
- **IR1/IR2** — a mismatched `ownir_version` raises; a versionless document is
166-
accepted as current.
167-
- **IR4** — a `functions[].body` containing an unknown op (`{"op": "try", …}`)
168-
raises `OwnIRError`.
200+
accepted as current; each frontend producer's `ownir_version` literal is
201+
asserted equal to the core's `OWNIR_VERSION`.
202+
- **IR4** — a `functions[].body` with an unknown op (`{"op": "try", …}`) raises
203+
`OwnIRError`; likewise a present-but-unknown `resource` kind.
169204
- **IR5** — the unmappable-diagnostic tripwire is an internal invariant
170205
exercised by the flow/escape fixtures (a broken handle mapping would raise
171206
"cannot map back" instead of reporting the leak), not a dedicated raise-test.
172-
- **§4/§5/§6** — the resource-kind, flow-op, and DI fixtures
207+
- **§4/§5/§6/§7** — the resource-kind, flow-op, DI, and effect fixtures
173208
(`tests/fixtures/ownir/*.facts.json`) each assert their expected code.
174209

175210
A change to this spec without a matching change under `tests/test_ownir.py` (or

‎tests/test_ownir.py‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -245,6 +245,22 @@ def _sub(source: str | None) -> list[Finding]:
245245
except OwnIRError:
246246
pass
247247

248+
# A present-but-unknown resource kind changes routing (§4), so load must reject
249+
# it (fail-loud) rather than fall through to the subscription path and
250+
# mis-classify. An ABSENT `resource` field still defaults to subscription.
251+
checks += 1
252+
bad_kind = {"ownir_version": OWNIR_VERSION, "module": "X",
253+
"components": [{"name": "C", "file": "C.cs", "subscriptions": [
254+
{"event": "e", "line": 1, "resource": "mutex"}]}]}
255+
if not _load_raises(bad_kind):
256+
fails.append("present-but-unknown resource kind was accepted (should raise OwnIRError)")
257+
checks += 1
258+
ok_absent = {"ownir_version": OWNIR_VERSION, "module": "X",
259+
"components": [{"name": "C", "file": "C.cs", "subscriptions": [
260+
{"event": "e", "line": 1}]}]} # no `resource` -> defaults to subscription
261+
if _load_raises(ok_absent):
262+
fails.append("an absent resource field was wrongly rejected (must default to subscription)")
263+
248264
# Version single-sourcing (IR2): every producer must stamp the SAME
249265
# ownir_version as the core. The literal is hand-kept in each frontend today —
250266
# once P-022's `own-ir` crate lands there are FOUR producers, so a schema will

0 commit comments

Comments
 (0)