Skip to content

Commit 49f5493

Browse files
committed
docs(owen-ext): OX-01 preregistration + Snipper salvage audit (base 88cb8cc)
Registers the Owen extension substrate slice before any code: kill-first findings (owen check is already the generic pipeline; explicit generated inputs reach the extractor; incremental generator matches the golden while an MSBuild pre-compile step is absent from design-time builds; a tool package cannot be PackageReference'd, NU1212), the Owen.Build host + Owen.TypedBuilder extension packages, the descriptor contract and its OWENB codes, platforms, isolated-consumer acceptance A-H, mutations M1-M7 and the verdict. The Snipper audit (read-only, PhysShell/snipper@43b395a) records COPY/ADAPT/REJECT per mechanism. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011ZFvhLx1fM9Gerg4dKsZcL
1 parent 88cb8cc commit 49f5493

2 files changed

Lines changed: 513 additions & 0 deletions

File tree

Lines changed: 292 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,292 @@
1+
# OX-01 — Owen extension substrate, with Typed Builder as extension #1: preregistration
2+
3+
**STATUS: REGISTERED BEFORE ANY PRODUCT CODE.** This commit holds this document and the
4+
Snipper salvage audit ([`owen-extension-snipper-salvage.md`](owen-extension-snipper-salvage.md)),
5+
and nothing else. A semantic change after this commit is an amendment, committed before the
6+
official run it affects.
7+
8+
**Base:** `main` = `88cb8cc31c49d730290613208947102d0737cad2` (merge of #391, TB-MVP-01). The
9+
base contains #391: `git merge-base --is-ancestor 04cb779a4ce8047e563d35edc72bdce9a13eaca8 88cb8cc3`
10+
holds. `main` has not moved since, and nothing under Typed Builder, `OwnSharp.Cli` or
11+
packaging changed after it.
12+
13+
## P0 — gates on the base
14+
15+
The results are in § *P0 results* at the end.
16+
17+
## Kill-first findings (throwaway spikes on the base, not committed)
18+
19+
**K-1 — the host already exists.** `owen check` (`frontend/roslyn/OwnSharp.Cli`, the `Owen.Cli` tool)
20+
is a complete generic pipeline:
21+
- bundled extractor, child process;
22+
- facts;
23+
- the authoritative Rust core `own-cli`, resolved only from an explicit locator or one computed packaged path (D3/D6, `RustCoreLocator.cs`);
24+
- `--format msbuild`;
25+
- a mapped exit-code contract.
26+
27+
On the Rust engine it needs **no Python**: the vendored core is unpacked only for `--engine python|compare`.
28+
29+
The core already renders the canonical VS Error List line itself (`own-cli ownir --format msbuild`).
30+
A second runner or a second renderer would duplicate the authoritative path, so none is built.
31+
32+
**K-2 — the protocol must reach the scan as source.** The extractor's directory and `.csproj`
33+
expansion skips `bin/`, `obj/` and `*.g.cs`. An **explicitly named** `.cs` input passes through
34+
unfiltered (`Program.cs::Expand`).
35+
36+
A probe confirmed the path end to end:
37+
1. the TB-MVP `OrderBackend` sources built with the generated protocol living only under `obj/.../generated/`;
38+
2. the extractor ran on `OrderBackend.csproj` plus that generated file named explicitly;
39+
3. `own-cli ownir --format msbuild` printed `C8.cs(18): error OWN002: …`.
40+
41+
No extractor change is needed.
42+
43+
**K-3 — generator delivery, both variants measured.**
44+
- **A (Roslyn incremental source generator).**
45+
- **Setup:** the existing generator's model and renderer, compiled unchanged into a `netstandard2.0` analyzer against Roslyn 4.8.0, run inside the ordinary compilation.
46+
- **Output:** text byte-identical to the committed golden `samples/OrderBackend/OrderBackend/Domain/Order.Protocol.cs`, 6880/6880 bytes. The only Roslyn-specific `string[1..]` uses were rewritten as `Substring(1)`, with the same output.
47+
- **One difference, compiler side:** generated sources compile with nullable annotations off, so the golden's `string?` warns CS8669. The generator wrapper therefore prepends exactly one line, `#nullable enable`, to the golden text. The shared renderer's output, and so the golden, do not change.
48+
- **B (MSBuild pre-compile Exec).**
49+
- **Full build:** works, adding about 0.5 s of `dotnet exec` per build.
50+
- **Design-time build (fails):** under the design-time build Visual Studio uses for IntelliSense (`-t:CompileDesignTime -p:DesignTimeBuild=true -p:SkipCompilerExecution=true -p:ProvideCommandLineArgs=true`), the generated file was **neither produced nor in the compile item list**. IntelliSense would show the typed API as missing until a full build, and an edit to the declaration would not regenerate it.
51+
- **Decision: A.** A runs in every compilation, the IDE's included, and keeps the golden. B is not shipped.
52+
53+
**K-4 — packaging.**
54+
- **Owen.Cli cannot be the reference.** It is a `DotnetTool` package, and NuGet refuses it as a `PackageReference` (NU1212). A referenceable host package is therefore needed.
55+
- **The exec bit.** A `.nupkg` does not carry Unix file modes. `RustCoreLocator.ResolvePackaged` already copies the packaged `own-cli` into a content-addressed cache `~/.owen/rust-core/<sha256>/` and marks it executable there. The host reuses that code path as is.
56+
57+
## Install UX (the claim)
58+
59+
```
60+
dotnet new web -n OrderBackend
61+
dotnet add package Owen.TypedBuilder --version 0.1.0
62+
dotnet build
63+
```
64+
65+
That is all. The machine needs no Own.NET checkout, no Python, no Rust toolchain, no global
66+
`owen` tool, no environment variable pointing at a repository, and no PATH lookup of a
67+
development binary. The only executable taken from the machine is the `dotnet` muxer that is
68+
already running the build: `DOTNET_HOST_PATH` as MSBuild sets it, then `DOTNET_ROOT`, then
69+
`dotnet`.
70+
71+
## Packages (exact)
72+
73+
| package | kind | why it exists |
74+
|---|---|---|
75+
| `Owen.Build` | generic build host | One shared host is needed. It must be referenceable (K-4), carry exactly one copy of the extractor and of each platform's Rust core however many extensions are active, and depend on no extension. It is the only new non-extension package; there is no `Owen.Toolchain` or `Owen.CoreAssets`, because nothing would separate them from it. |
76+
| `Owen.TypedBuilder` | extension #1 | The generator, the extension descriptor, and a dependency on `Owen.Build` of the same version. |
77+
| `Owen.TestExtension` | **test fixture, never shipped** | A synthetic second extension: a descriptor only, no analysis. It is built by the gate into the isolated feed and nowhere else. |
78+
79+
Version: `0.1.0` for both shipped packages, matching `Owen.Cli` 0.1.0, which the host payload is.
80+
Nothing is published to nuget.org. Every acceptance run uses a locally packed candidate in an
81+
isolated feed.
82+
83+
**`Owen.Build` layout:**
84+
85+
| path | contents |
86+
|---|---|
87+
| `tools/net8.0/any/` | the `OwnSharp.Cli` publish closure (`ownsharp.dll`, `ownsharp-extract.dll`, Roslyn), the same payload as the `Owen.Cli` tool, **without** the vendored Python core |
88+
| `tools/net8.0/any/rust-core/<platform-key>/own-cli[.exe]` | the packaged core, at the path `RustCoreLocator.PackagedPath` already computes |
89+
| `build/Owen.Build.props` · `build/Owen.Build.targets` | the generic MSBuild host |
90+
| `buildTransitive/…` | the same two files, so they flow through an extension's dependency |
91+
92+
**One source of truth for the platform inventory.** The set of supported platform keys and
93+
binary names, and the "pack fails when a staged binary is missing" check, move into one
94+
`frontend/roslyn/OwenRustCore.props`. Both `OwnSharp.Cli.csproj` and the `Owen.Build` project
95+
import it. The `Owen.Cli` package payload must stay **file-for-file identical** to its base
96+
payload, compared as a sorted file list plus per-file sha256.
97+
98+
## Extension discovery contract (exact)
99+
100+
An extension package adds, from its `buildTransitive/<Id>.props`:
101+
102+
```xml
103+
<OwenExtensionDescriptor Include="$(MSBuildThisFileDirectory)owen-extension.json" />
104+
```
105+
106+
The descriptor (`spec/OwenExtension.md`, `spec/owen-extension.schema.json`):
107+
108+
```json
109+
{
110+
"owen_extension": 1,
111+
"id": "Owen.TypedBuilder",
112+
"version": "0.1.0",
113+
"requires": {
114+
"host": "0.1.0",
115+
"ownir": 2,
116+
"capabilities": ["ownership", "state-protocol", "heap-effects", "proven-call"]
117+
},
118+
"frontend": { "generators": ["Owen.TypedBuilder.Generator"] }
119+
}
120+
```
121+
122+
**Host 0.1.0 supports:** OwnIR 2, and the capabilities `ownership`, `state-protocol`,
123+
`heap-effects` and `proven-call`. The host validates every descriptor before any analysis, and
124+
**every violation is a build error**, never a skip. The new code family is `OWENB`, the host's;
125+
no `OWN` code changes.
126+
127+
| condition | result |
128+
|---|---|
129+
| no descriptor at all (`Owen.Build` referenced alone) | warning `OWENB001` "no Owen extension is active; nothing was analysed". **Intentionally inactive, and loud about it.** |
130+
| `owen_extension` ≠ 1, a missing or ill-typed field, a duplicate `id` | error `OWENB002` |
131+
| `requires.ownir` ≠ 2, or `requires.host` newer than the host | error `OWENB003` (incompatible extension) |
132+
| a required capability the host does not have | error `OWENB004`, naming it and the extension |
133+
| no Rust core for this platform in the package, or an unsupported platform | error `OWENB005` (the locator's D3.1 message) |
134+
| the extractor refuses a construct (exit 2) | error `OWENB010` at the refused `file(line)` |
135+
| the core refuses the facts (exit 2, e.g. a `proven_call` not proven harmless) | error `OWENB011` at the `file(line)` the refusal names |
136+
| an internal failure of either child | error `OWENB012` |
137+
138+
**What the host does with valid descriptors.**
139+
- **Manifest.** It writes `obj/owen/extensions.json`, sorted by `id`: host version, OwnIR version, and each active extension's `id`, `version` and capabilities.
140+
- **Logging.** It logs `Owen: active extensions: <id> <version>, …` at high importance.
141+
- **Generator outputs.** It collects every `frontend.generators` name, takes the generated C# under `$(CompilerGeneratedFilesOutputPath)/<generator assembly>/**`, and passes those files to the extractor explicitly (K-2). The host props set `EmitCompilerGeneratedFiles=true`, so those files exist.
142+
- **Analysis.** It runs the existing check pipeline exactly once, whatever the number of extensions, with `--engine rust --format msbuild --severity $(OwenSeverity)`.
143+
144+
The host contains **no extension identifier**: the gate greps the host sources and targets for
145+
`TypedBuilder` and expects zero hits. Two extensions coexist by construction, because the
146+
descriptors are a list.
147+
148+
**Where it lives.**
149+
- **Validation, manifest, generated-file collection and refusal canonicalisation:** a new `owen build-check` subcommand of the same `OwnSharp.Cli` program. It is the generic host entry point the targets call, and it reuses `CheckCommand`'s pipeline rather than copying it.
150+
- **Analysis semantics:** none in the host; they stay in the Rust core.
151+
152+
**MSBuild properties:**
153+
- `OwenSeverity`: `warning` by default, `error` opt-in.
154+
- **Why warning is the default:** the first install never turns a legacy project red, because the existing `--severity` only changes how a finding is shown, never the verdict.
155+
- **Refusals are the exception:** OWENB010/011 are always errors. They only arise in a protocol the developer declared, and "cannot be checked" must never read as clean.
156+
- `OwenEnabled`: `true` by default, `false` to switch the host off.
157+
158+
The target runs after the build has copied its output, because the extractor binds against the
159+
built `bin/`. It is skipped in design-time builds and runs on every build, so warnings do not
160+
vanish on an incremental build.
161+
162+
## The Typed Builder extension (exact)
163+
164+
- **`Owen.TypedBuilder.Generator`:** a `netstandard2.0` `IIncrementalGenerator` over Roslyn 4.8.0.
165+
- **Shared core.** It and the existing CLI (`frontend/roslyn/Own.TypedBuilder`) share one model/renderer library, `Own.TypedBuilder.Core`. The CLI's output stays byte-identical to the golden, so `typed_builder_gate` keeps passing unchanged.
166+
- **The attribute vocabulary** (`TypedProtocol`, `ProtocolState`, `BuilderRequired`, `Transition`, `ProtocolToken`, `ProtocolRegion`) is emitted by the generator's post-initialisation step as `internal` types in the global namespace. A consumer therefore writes `[TypedProtocol]` with no `using` and no dependency, and the generated protocol text stays the golden.
167+
- **A refused declaration** is a generator error `OWENTB001` carrying the core's refusal line. It is never empty output.
168+
169+
## Supported platforms
170+
171+
`linux-x64` and `win-x64`: exactly the platforms `Owen.Cli` packs today. macOS is **not**
172+
claimed. On any other platform the host fails with `OWENB005`; it never skips.
173+
174+
## Foundations: unchanged
175+
176+
No change to:
177+
- OwnIR (version 2) or the ownership, state-protocol or H0/H1 semantics;
178+
- any `OWN` code or message;
179+
- the Rust core's analysis;
180+
- T0 or the P-022 harness.
181+
182+
`git diff --stat 88cb8cc3..HEAD -- ownlang rust spec/OwnIR.md spec/Bridge.md spec/ownir.schema.json frontend/roslyn/OwnSharp.Extractor docs/evidence/calibration scripts/perf_baseline.py`
183+
must be empty. If the substrate turns out to need one of these, the slice stops with a named
184+
blocker.
185+
186+
## Snipper (P1)
187+
188+
The salvage audit is committed alongside this document. **For this slice:**
189+
- **REJECT** Snipper's binary discovery (setting → bundled → PATH, with silent fall-through);
190+
- **ADAPT** pack-time bundling with a hard failure on a missing binary (already the `Owen.Cli` rule), and the one-shot child-process discipline (drain both streams, map the exit code, kill on cancel).
191+
192+
Everything else is for a future `Owen.VisualStudio` or LSP and is **not** built here.
193+
194+
## IDE: investigated only, not shipped
195+
196+
- **E1 (generic VSIX host: `IErrorTag` + `ITableDataSource` + a long-lived Owen process).** This environment has no Windows and no Visual Studio, so the spike can only be specified. The verdict will be recorded as **not executed**, with the reasons and the exact acceptance it would need. No VSIX is built.
197+
- **E2 (Roslyn `DiagnosticAnalyzer` → native Rust core).** A minimal experimental project under `experiments/owen-e2-native-analyzer/`, outside every shipping path and every CI build. It is exercised on Linux with `dotnet build` and repeated builds through the compiler server. Windows, the Visual Studio x64 in-proc compiler and unload/reload are recorded as not executed here. Verdict: `VIABLE` or `REJECT`.
198+
- **Architecture invariant.** An extension is not an IDE plugin. A future IDE host is exactly one `Owen.VisualStudio`, and a future server is exactly one Owen diagnostic/language server, both serving all active extensions. No `Owen.TypedBuilder.VisualStudio`.
199+
200+
## Acceptance
201+
202+
**Gate:** `scripts/owen_extension_gate.py`. It runs on Linux and Windows CI, packs the candidate
203+
packages, and tests them in an isolated consumer.
204+
205+
**The isolated consumer.**
206+
- **Location:** a fresh directory **outside the checkout**.
207+
- **Environment:**
208+
- `PATH` holds only the directory of the `dotnet` running the gate;
209+
- `HOME`, `DOTNET_CLI_HOME` and `NUGET_PACKAGES` are fresh temporary directories;
210+
- the `nuget.config` has `<clear/>`, the isolated feed and nuget.org, with package source mapping `Owen.*` → the isolated feed only.
211+
- **Preconditions:**
212+
- `python`, `python3`, `cargo`, `rustc` and `owen` resolve to nothing on that `PATH`;
213+
- the consumer contains no path into the checkout.
214+
215+
The gate fails if any precondition fails.
216+
217+
**Steps, every one PASS/FAIL:**
218+
219+
| id | step | PASS iff |
220+
|---|---|---|
221+
| U1 | `dotnet new web -n OrderBackend`, `dotnet add package Owen.TypedBuilder --version 0.1.0`, then copy in the TB-MVP domain/data/endpoints/Shipping sources. Not `Order.Protocol.cs` (now generated) and not `TypedBuilder.cs` (now provided). | the project file holds exactly one Owen `PackageReference` |
222+
| A | `dotnet build` | succeeds. The generated `Order.Protocol.g.cs` text = `#nullable enable\n` + the committed golden. `obj/owen/extensions.json` lists `Owen.TypedBuilder 0.1.0` and its capabilities |
223+
| B | stage `C1_draft_approve` | the build fails with CS1061 naming `Approve`, and no manual generator step ran |
224+
| C | stage `C8_stale_draft` with `OwenSeverity=error` | the build fails with `OWN002` |
225+
| D | the C build's output | holds a canonical `file(line): error OWN002: …` line, whose file resolves from the project directory to the staged file and whose line is 18. With the default severity, the same build succeeds and shows the line as `warning OWN002` |
226+
| E | U1–D under the stripped environment | all pass; the build logs contain no path into the Own.NET checkout |
227+
| F | the whole TB-MVP corpus (8 positive, 20 negative, 2 limits) through the package, `OwenSeverity=error` | compiler cases: their CS code; extractor cases: `OWENB010` with the registered text; core verdict cases: their `OWN` code(s); core refusals: `OWENB011` with the registered text; positives: no `OWN`/`OWENB` diagnostic. K1 gives `OWN001`, K2 is clean, P5 and P8 have the `proven_call` (from `--emit-facts`) |
228+
| G | the TB-MVP `Acceptance` runner against the consumer project | 44/44, with the transcript **byte-identical** to the committed `samples/OrderBackend/evidence/acceptance.txt` |
229+
| H | the consumer with both `Owen.TypedBuilder` and `Owen.TestExtension` | the manifest lists both, analysis runs once, and the result is unchanged |
230+
231+
**Mutation and negative controls, each run in the isolated consumer:**
232+
233+
| id | mutation | PASS iff |
234+
|---|---|---|
235+
| M1 | delete `owen-extension.json` from the installed `Owen.TypedBuilder` | `OWENB001` is shown, and C8 produces **no** `OWN002`: the acceptance's C check would fail, so the gate detects it |
236+
| M2 | add an unknown capability to the descriptor | error `OWENB004` naming it |
237+
| M3 | delete the bundled `own-cli` for this platform | error `OWENB005`, never a clean build |
238+
| M4 | `requires.ownir: 3`, and separately `requires.host: 9.0.0` | error `OWENB003` each |
239+
| M5 | remove the host's build target (empty `Owen.Build.targets`) | C8 produces no `OWN002` and the gate's C check reports the absence |
240+
| M6 | run from a consumer with no checkout | pass (it is E) |
241+
| M7 | add `Owen.TestExtension` | no file of the host changes (H), and the host source has 0 occurrences of `TypedBuilder` |
242+
243+
**The other gates, on the final head:**
244+
- `tests/run_tests.py`, `ruff`, `mypy`;
245+
- `cargo fmt --check`, `cargo clippy --all-targets`, `cargo test`;
246+
- `protocol_gate.py --rust`, `heap_effects_gate.py`, `typed_builder_gate.py --rust`;
247+
- the `Owen.Cli` pack/install gate (the payload byte-identity above, then install → check → `OWN001`);
248+
- the P-022 merge gate;
249+
- server CI on Linux and Windows.
250+
251+
## Verdict
252+
253+
**`GO_OWEN_EXTENSION_ALPHA`** iff A–H, M1–M7 and every listed gate pass:
254+
255+
`PackageReference Owen.TypedBuilder` → generated API → CS diagnostics → OWN diagnostics on build
256+
→ no external toolchain or setup → generic extension discovery proven.
257+
258+
Otherwise the verdict is **`NO_GO_OWEN_EXTENSION_ALPHA`**, with the exact blocker. The failing
259+
case is preserved, and no foundation change is made to get to green. If E fails because the
260+
package cannot run without a global Owen install, the verdict is NO_GO.
261+
262+
**Out of scope even after GO:**
263+
- a production VSIX, LSP or VS Code extension;
264+
- the Memory or TypeDisciplines extensions;
265+
- BCL summaries (#394), typed write targets (#395), affine tokens (#392), diagnostic wording (#393), concurrency (#396);
266+
- a second aggregate;
267+
- a repo-wide rename.
268+
269+
## P0 results
270+
271+
Run on `88cb8cc31c49d730290613208947102d0737cad2`, a clean tree except for the two documents of this commit:
272+
273+
| gate | result |
274+
|---|---|
275+
| `python tests/run_tests.py` | rc 0, zero `FAIL` lines (the one textual hit is an `ok[...]` line quoting the word) |
276+
| `ruff check .` / `mypy` | rc 0 / rc 0 |
277+
| `cargo fmt --check` / `cargo clippy --all-targets` / `cargo test --no-fail-fast` | rc 0 / rc 0 / rc 0, 290 passed, 0 failed |
278+
| `python scripts/protocol_gate.py --rust …/own-cli` | 0 failures |
279+
| `python scripts/heap_effects_gate.py` | PASS |
280+
| `python scripts/typed_builder_gate.py --rust …/own-cli` | 0 failures, transcript sha256 `ba447304cdf957ee` |
281+
| `Owen.Cli` pack/install (gate A, replayed locally) | pass |
282+
| P-022 merge gate | `success` on #391's final head `04cb779`, which became this base |
283+
284+
`protocol_gate.py` covered 29 documents byte-identical on both CLIs. `typed_builder_gate.py` covered 8 positive, 20 negative and 2 limit cases, with 44 acceptance checks run twice.
285+
286+
**Gate A, replayed locally.**
287+
- **Pack:** with this platform's release `own-cli` staged under `linux-x64/`.
288+
- **Install:** with `--tool-path` from an isolated feed, with a fresh `HOME` and `NUGET_PACKAGES`.
289+
- **Check:** `owen check` on a seeded leak gives `OWN001` with rc 1; on clean code it gives rc 0.
290+
- **One environmental detail:** this container's dotnet lives in `/root/.dotnet`, so the tool's native apphost needs `DOTNET_ROOT`. The first attempt, without it, failed in the apphost before Owen ran.
291+
292+
**K-4, observed rather than assumed.** A `PackageReference` to that same `Owen.Cli` 0.1.0 fails restore with `NU1212: Invalid project-package combination … DotnetToolReference project style can only contain references of the DotnetTool type`.

0 commit comments

Comments
 (0)