|
| 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