Skip to content

Commit 48e639d

Browse files
committed
docs(P-022): add the secondary and identity coordinate carriers
Third and last RED before the representation choice. The previous revision of this inventory stopped at `Diagnostic.line` and spoke as though that were the coordinate surface. Review found a whole second family in the same crate, and the omission was not cosmetic: two of its members are identity carriers, where changing a type is a comparison-key change and not a representation change. Added: `Evidence.line`, `DiagKey.line`, `EvidenceIdentity.line`, `DiagIdentity.line`, `LocatedDiagnostic::line()`, and — filed under projection rather than as semantic carriers — `sarif::Step.line`, `sarif::Region. start_line`, `sarif::phys`. The measurement that makes them worth separating: secondary coordinates do NOT behave like the primary one. Varying the validated `ctor_line` on a DI captive, and `services[].line` on its flow hop: ctor_line i64::MIN / -1 / 0 -> related is EMPTY, the location disappears ctor_line 1 / u32::MAX+1 / i64::MAX -> carried verbatim, past u32::MAX services[].line i64::MIN / 0 -> the captor hop is DROPPED from the flow services[].line i64::MAX -> the hop carries the value verbatim So a secondary coordinate is admission-gated at `>= 1` — `i64::MIN` drops the hop, so it is the `>= 1` predicate and not a truthiness test, which agree only at zero — while being unbounded upward exactly like the primary. It needs the raised ceiling and never sees a non-positive value. The primary `Diagnostic.line` needs the whole signed band, `0` and negatives included. Same conflation caught one layer out: `Region.start_line` and `Step.line` are `u32`, and the reference emits `startLine` at `i64::MAX`. SARIF's narrower ADMISSION domain (`>= 1`) had been read as a narrower numeric carrier, which the format does not ask for. It keeps the gate and loses the ceiling. `column` is explicitly excluded and stays `Option<NonZeroU32>`. Its 1-based contract is real and column-specific; `line` has none, which is what cp1's `accept-zero-line` and `accept-negative-line` controls pin. Widening it alongside `line` because both are "coordinates" would re-glue the two axes three censuses were spent separating — the exact substitution #250's stop condition 12 exists to catch. Refs #250, #259. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CJF7MBi1ijU5m9cJVWgQsM
1 parent 57ea57e commit 48e639d

1 file changed

Lines changed: 88 additions & 4 deletions

File tree

‎docs/notes/p022-coordinate-surface-inventory.md‎

Lines changed: 88 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,73 @@ strict door accepts. That is a parity boundary, not an implementation detail.
3737

3838
The seam is exactly at `own_lowered → own_syntax/own_cfg`.
3939

40+
#### Secondary and identity carriers
41+
42+
The first revision of this inventory stopped at `Diagnostic.line` and said
43+
"coordinate surfaces" as though that were all of them. It was not — review
44+
found a second family in the same crate, and the omission mattered because two
45+
of its members are *identity* carriers, where widening a type is not a
46+
representation change but a comparison-key change.
47+
48+
| where | type | class |
49+
|---|---|---|
50+
| `own_diagnostics::Evidence.line` (+ `Evidence::new`) | `u32` | secondary carrier |
51+
| `own_diagnostics::DiagKey.line` (+ `DiagKey::new`) | `u32` | **identity** |
52+
| `own_diagnostics::EvidenceIdentity.line` | `u32` | **identity** |
53+
| `own_diagnostics::DiagIdentity.line` | `u32` | **identity** |
54+
| `own_diagnostics::LocatedDiagnostic::line()` | `-> u32` | accessor |
55+
| `own_diagnostics::sarif::Step.line` | `u32` | projection |
56+
| `own_diagnostics::sarif::Region.start_line` | `u32` | projection |
57+
| `own_diagnostics::sarif::phys(file, line)` | `u32` | projection |
58+
59+
`Step` and `Region` belong to §4, not here: they are the SARIF shape, and their
60+
admissible domain is the format's.
61+
62+
#### Measured: what a secondary coordinate actually carries
63+
64+
Run against the reference, varying the **validated** `ctor_line`
65+
(spec/OwnIR.md §4.2) on a DI captive, which surfaces as a `related` location,
66+
and varying `services[].line`, which surfaces as a `flow` hop:
67+
68+
```
69+
ctor_line related
70+
i64::MIN () <- location ABSENT
71+
-1 () <- location ABSENT
72+
0 () <- location ABSENT
73+
1 (('Sing.cs', 1, 'consuming constructor…'),)
74+
u32::MAX+1 (('Sing.cs', 4294967296, …),)
75+
i64::MAX (('Sing.cs', 9223372036854775807, …),)
76+
77+
services[].line flow[0]
78+
i64::MIN ('S.cs', 2, 'captures scoped service…') <- captor hop DROPPED
79+
0 ('S.cs', 2, 'captures scoped service…') <- captor hop DROPPED
80+
i64::MAX ('S.cs', 9223372036854775807, 'singleton … (captor)')
81+
```
82+
83+
So secondary coordinates behave **differently from the primary one**, and the
84+
difference is the useful part:
85+
86+
* upward they are unbounded exactly like the primary — `i64::MAX` survives into
87+
`related` and into a `flow` hop verbatim, well past `u32::MAX`;
88+
* downward they are **admission-gated**: a non-positive coordinate makes the
89+
whole location *disappear* rather than appear at line 0. `i64::MIN` drops the
90+
hop, so the gate is `>= 1` and not a truthiness test — the two agree only at
91+
zero.
92+
93+
That is the §3 sentinel again, one level down. A secondary carrier therefore
94+
needs a wider **upper** bound and is never handed a non-positive value by its
95+
producer, while the primary `Diagnostic.line` must represent the full signed
96+
band including `0` and negatives.
97+
98+
#### Deliberately out of scope: `column`
99+
100+
`LocatedDiagnostic.column` is `Option<NonZeroU32>`, and its doc says why: it is
101+
the type-level mirror of `_check_column`'s 1-based contract. That contract is
102+
real and column-specific — `line` has no 1-based rule, which is exactly what
103+
cp1's `accept-zero-line` / `accept-negative-line` controls pin. Widening
104+
`column` alongside `line` because both are "coordinates" would re-glue the two
105+
axes three censuses were spent separating. It is not part of this change.
106+
40107
### 2. Conversion
41108

42109
There is **no** coordinate-narrowing conversion in the tree today — no `as
@@ -79,6 +146,12 @@ verdict may carry:
79146
| `own_diagnostics::sarif` :241 | `step.line >= 1 && !step.file.is_empty()` |
80147
| `ownlang/ownir.py::_sarif_result` | `if f.line >= 1: phys["region"] = {"startLine": f.line}` |
81148

149+
`Region.start_line` and `Step.line` are `u32` today, and the measurement below
150+
shows the reference emitting `startLine` well past `u32::MAX`. So the format's
151+
narrower **admission** domain (`>= 1`) is being conflated with a narrower
152+
**numeric carrier**, which the format does not ask for. SARIF keeps the gate
153+
and loses the ceiling.
154+
82155
Measured on the reference, over the same band:
83156

84157
```
@@ -122,7 +195,18 @@ The representation. The candidates the inventory leaves open:
122195

123196
Each has a different blast radius through §3 and §4, and the choice belongs to
124197
the next change with this inventory in front of it. What the inventory settles
125-
is smaller and more useful: the two `>= 1` predicates are already correct and
126-
must be preserved verbatim, so the work is a **width** change, not a semantics
127-
change — and any patch that alters either predicate while widening the carrier
128-
has done something the reference does not do.
198+
is smaller and more useful:
199+
200+
* every `>= 1` predicate — the DI sentinel, the SARIF gate, and the secondary
201+
admission gate measured above — is **already correct** and must survive
202+
verbatim. The work is a *width* change, not a semantics change, and a patch
203+
that touches any of those predicates while widening a carrier has done
204+
something the reference does not do.
205+
* the primary verdict line must represent the full signed band, `0` and
206+
negatives included; secondary carriers need only the raised ceiling, because
207+
their producers gate them at `>= 1` before construction.
208+
* three of the newly-found carriers are **identity** (`DiagKey`,
209+
`EvidenceIdentity`, `DiagIdentity`). Widening those is a comparison-key
210+
change, so whatever is chosen has to keep the #255 non-collapsing key
211+
non-collapsing — that is a property to re-prove, not to assume.
212+
* `column` is out of scope, and stays `NonZeroU32`.

0 commit comments

Comments
 (0)