Skip to content

Commit 48c71e6

Browse files
committed
docs(owen-ext): diagnostics model, E1/E2 IDE feasibility (E2 spike), alpha readiness
- owen-diagnostics-model.md (P8): the model already exists (own_bridge::Finding -> render_finding/build_sarif); no new layer. - owen-extension-ide-feasibility.md (P9/P10): E1 generic VSIX host NOT EXECUTED here (no Windows/VS), specified with its two blockers; E2 native Roslyn analyzer REJECT, measured on Linux (shadow copy defeats native resolution; only an explicit path via reflection-reached NativeLibrary works, .NET hosts only; the extractor cannot run inside an analyzer). - experiments/owen-e2-native-analyzer: the E2 spike (outside shipping and CI). - alpha-readiness.md: the PackageReference install path. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011ZFvhLx1fM9Gerg4dKsZcL
1 parent 89bdb86 commit 48c71e6

9 files changed

Lines changed: 415 additions & 0 deletions

File tree

‎docs/notes/alpha-readiness.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,39 @@ None of those is research; all are the difference between "interesting PoC" and
6868
standing between here and the day 1–30 milestone being *literally* copy-paste
6969
for a stranger.
7070

71+
## Update 2026-10-03: the extension path (OX-01)
72+
73+
**A second install path now exists beside A.** No `dotnet tool` and no command: a
74+
`PackageReference`.
75+
76+
```
77+
dotnet add package Owen.TypedBuilder
78+
dotnet build
79+
```
80+
81+
**What it does.**
82+
- The package depends on **`Owen.Build`**, the generic build host. `Owen.Build` carries the same program as `Owen.Cli` (`owen`), its bundled extractor, and the Rust core for `linux-x64` and `win-x64`.
83+
- On every build it runs Owen once for every active Owen extension.
84+
- Findings are ordinary MSBuild diagnostics, so `dotnet build`, CI logs and Visual Studio's Error List all show them. They are `warning` by default and `OwenSeverity=error` to fail the build.
85+
86+
The machine needs no Python, no Rust toolchain, no global tool and no checkout. The isolated
87+
consumer gate proves it on Linux and Windows CI (`scripts/owen_extension_gate.py`).
88+
89+
**Extension #1 is the Typed Builder:**
90+
- typed states and a typed builder generated from one annotated EF entity;
91+
- illegal transitions are compiler errors;
92+
- stale or copied states are `OWN` findings on build.
93+
94+
The contract a second extension uses is in [`spec/OwenExtension.md`](../../spec/OwenExtension.md). See
95+
[`owen-extension-alpha-report.md`](owen-extension-alpha-report.md) for the evidence, and
96+
[`owen-extension-ide-feasibility.md`](owen-extension-ide-feasibility.md) for live IDE diagnostics:
97+
- E1 (one generic VSIX host) is the direction, not built here;
98+
- E2 (a native Roslyn analyzer) was rejected.
99+
100+
**Still open.** Exactly the items that already gated A: nothing is published to nuget.org
101+
yet, and there is no license. `Owen.Build` and `Owen.TypedBuilder` are 0.1.0 candidates packed
102+
from source.
103+
71104
## The 20% rule (other stacks)
72105

73106
Other stacks are **proof of portability, not a second product.** Sanctioned now:
Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# Owen diagnostics: the model already exists (OX-01, P8)
2+
3+
**Question.** Is the renderer so tied to CLI strings that the extension substrate needs a new
4+
internal diagnostic model before `msbuild`, `github`, `sarif`, a future Visual Studio host or a
5+
future LSP can be served?
6+
7+
**Answer: no.** The model exists, it is the authoritative core's, and every surface is
8+
already one function of it. OX-01 adds **no** diagnostic layer. It consumes the existing one.
9+
10+
## The model
11+
12+
`own_bridge::verdict::Finding` (Rust, authoritative since the P-022 Stage 3 cutover; the Python
13+
reference mirrors it field for field):
14+
15+
| field | the brief's concept |
16+
|---|---|
17+
| `code` | code (`OWN001` …) |
18+
| `severity` (+ `advisory`) | severity. The host's `--severity` changes only how a finding is **shown**, never the verdict |
19+
| `message` | message |
20+
| `file`, `line`, `column` (optional) | file, start line, start column |
21+
| `related: Vec<Step>`, `flow: Vec<Step>` | related locations and the witness path |
22+
| `kind` (`[resource: …]`), `component`, `event`, `handler` | the resource the finding is about |
23+
| `ignore_reason` | suppression (`// own:ignore` …) |
24+
25+
**Renderers,** each a pure function of a `Finding`:
26+
27+
| function | output |
28+
|---|---|
29+
| `own_bridge::render_finding(f, "human" \| "github" \| "msbuild", severity)` | one line per surface |
30+
| `own_bridge::build_sarif` | a SARIF 2.1.0 log |
31+
32+
`own-cli ownir --format {human,github,msbuild,sarif}` exposes all four. `BR-V9` pins the
33+
bytes, and the CLI ledgers pin both engines.
34+
35+
## How OX-01 uses it
36+
37+
The build host (`owen build-check`) asks the core for `--format msbuild` and passes the lines
38+
through. It changes exactly one thing: it makes the **origin path** absolute against the project
39+
directory, so Visual Studio's Error List never has to guess a base. No message, code or
40+
severity is re-rendered by the host.
41+
42+
The host's own conditions are the `OWENB` codes (spec/OwenExtension.md §4):
43+
- a descriptor rejected;
44+
- no engine for the platform;
45+
- a refusal.
46+
47+
They are rendered by the host in the same canonical MSBuild shape. They are host
48+
diagnostics, not analysis findings, and they never reuse an `OWN` code.
49+
50+
## Gaps, recorded and not changed here
51+
52+
- **No column on the `msbuild` line.** `render_msbuild` prints `file(line)` although `Finding` carries an optional `column`.
53+
- **Effect:** the Error List navigates to the line, not the column.
54+
- **Why not here:** changing the line is a change to the core's pinned bytes (BR-V9, the CLI ledgers), which is foundation work.
55+
- **The line and the wording of state-protocol findings.** A stale state token is reported at the region entry, and in the generic resource wording ("IDisposable local … disposed"). This is issue **#393**, unchanged here.
56+
- **For a future IDE host or LSP:** both consume the same `Finding`. `--format sarif` already carries everything they need: code, level, message, region, related locations, code flows. A future `Owen.VisualStudio` or language server should read SARIF, or a structured JSON of the same `Finding`, from the one core, and never re-derive a finding.
Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
# Owen in the IDE: E1 and E2 feasibility (OX-01, P9 and P10)
2+
3+
This is a kill-first report, not a product. Nothing here ships. The shipped path in OX-01 is
4+
the **build host**:
5+
- `Owen.Build` runs Owen on every `dotnet build`;
6+
- its findings are canonical MSBuild diagnostics;
7+
- Visual Studio puts canonical MSBuild diagnostics in the Error List on build, with file and line navigation (spec/OwenExtension.md).
8+
9+
The question here is the next step: **live** diagnostics while typing.
10+
11+
## The architecture invariant (from the clang-tidy model)
12+
13+
One authoritative external analyzer and thin adapters. Concretely:
14+
- **An extension is not an IDE plugin.** There is no `Owen.TypedBuilder.VisualStudio`, no `Owen.Memory.VisualStudio`.
15+
- **At most one `Owen.VisualStudio`,** serving every active extension from the manifest the build host already writes (`obj/owen/extensions.json`).
16+
- **At most one Owen diagnostic/language server.**
17+
- **Every adapter reads findings produced by the one Rust core.** None re-derives a verdict in C# or TypeScript (owen-diagnostics-model.md).
18+
19+
clang-tidy's integration code is not copied; only the shape is borrowed.
20+
21+
## E1: a generic VSIX host (`IErrorTag` + `ITableDataSource` + a long-lived Owen process)
22+
23+
**Verdict: NOT EXECUTED in this environment.** The session runs on Linux with no Windows
24+
and no Visual Studio, so a VSIX cannot be built, deployed to an experimental instance or
25+
observed. Nothing below is measured. It is the specification of the spike, plus the two
26+
blockers already visible from the code.
27+
28+
**The acceptance the spike must meet** (as registered):
29+
1. an unsaved C# buffer;
30+
2. an OWN diagnostic;
31+
3. a squiggle (`IErrorTag`);
32+
4. an Error List entry (`ITableDataSource`);
33+
5. navigation to it;
34+
6. delete the offending line, and the diagnostic disappears.
35+
36+
**Blockers found by reading the code; both must be solved before E1 can pass:**
37+
1. **Unsaved buffers.**
38+
- **The gap:** the extractor reads **files** (`OwnSharp.Extractor/Program.cs::Expand`), and an unsaved buffer is not a file. Live diagnostics need an overlay input, "this path, these contents", or an in-memory workspace.
39+
- **Scope:** this is frontend work, not core semantics, and it is the precondition of any live host, E1 and E2 alike.
40+
2. **Latency.**
41+
- **The cost today:** one `owen check` spawns the extractor, compiles the project with Roslyn and runs the core: seconds per project. The build host pays that once per build, which is acceptable. A host that runs on every keystroke cannot.
42+
- **What E1 implies:** a **long-lived** Owen process with an incremental extractor, which does not exist today.
43+
- **What Snipper shows** (owen-extension-snipper-salvage.md): its long-lived process lifecycle is the part to **reject**. Stderr is lost, crashes are unwatched, and orphans are not prevented. A future host needs a lifecycle written for this, not that one.
44+
45+
**Salvage that applies when E1 is attempted** (from the Snipper audit):
46+
- **ADAPT** the mocked-VS integration tests;
47+
- **COPY** the fake two-pipe JSON-RPC server pattern;
48+
- **ADAPT** the `/rootsuffix` real-IDE smoke as a manual or nightly gate (not CI).
49+
50+
**Recommendation.** E1 is the right *shape* for live diagnostics, but it is a separate slice
51+
whose first task is the extractor overlay input (1) and a resident analysis process (2). It
52+
must be run on Windows with Visual Studio against the six-step acceptance above.
53+
54+
## E2: a NuGet-only Roslyn `DiagnosticAnalyzer` calling the native Rust core
55+
56+
**Verdict: REJECT** (for the Alpha and as the live-diagnostics route).
57+
58+
**What was run.** `experiments/owen-e2-native-analyzer/`, on Linux x64 with the .NET 8 SDK:
59+
- a `cdylib` exporting `owen_e2_check(facts) -> msbuild lines`, the SAME `own_bridge::check_facts` + `render_finding` as the CLI;
60+
- a `netstandard2.0` analyzer that P/Invokes it and maps the lines to `Location`s;
61+
- a consumer project.
62+
63+
| check | result |
64+
|---|---|
65+
| Linux, `dotnet build` (compiler server), variant 1: `DllImport` + `DllImportSearchPath.AssemblyDirectory` | **FAIL**: `DllNotFoundException` on every build. Roslyn shadow-copies analyzer assemblies and does not copy native files beside them. |
66+
| variant 2: explicit path via `CompilerVisibleProperty` + `NativeLibrary.Load`, reached by reflection (absent from `netstandard2.0`) | **works**: `C8.cs(18,1): warning OWNE2: OWN002: …` |
67+
| repeated builds through the compiler server | identical over 3 builds |
68+
| after `dotnet build-server shutdown` | identical |
69+
| the native file replaced under a live server | the next load fails; no stale fallback |
70+
| Windows, Visual Studio x64 in-proc / ServiceHub, unload/reload | **NOT EXECUTED** (no Windows here) |
71+
| no duplicate semantics in C# | holds for the **verdict**. **Fails for the facts**: an analyzer cannot run the extractor, a separate program that reads files. Extraction would have to move inside the analyzer, which is a second frontend host. |
72+
73+
**Why REJECT.**
74+
1. **Only a hand-built workaround works.** The default native-asset resolution, the thing a NuGet-only analyzer relies on, fails outright under the shadow copy.
75+
2. **The workaround is .NET-hosted only.** `NativeLibrary` exists only on .NET (Core) hosts. A .NET Framework compiler host needs a third, Windows-only `LoadLibrary` path.
76+
3. **Native libraries never unload.** On Windows they are locked by long-lived compiler and IDE processes, which fights package updates.
77+
4. **The analyzer would still need the extractor in process.** That duplicates the frontend host the build path already has.
78+
79+
**What would change the verdict:**
80+
- the same extractor overlay/library refactor that E1 needs;
81+
- a measured Windows + Visual Studio run of variant 2.
82+
83+
Until then the build host is the shipped path, and E1 is the live-diagnostics direction.
Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
native/target/
2+
native/Cargo.lock
Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# E2 spike: a Roslyn analyzer calling the native Rust core (OX-01)
2+
3+
**Experimental.** Outside every shipping path and every CI build. It exists to answer one
4+
kill-first question from `docs/notes/owen-extension-alpha-preregistration.md`: can live OWN
5+
diagnostics ship as a NuGet-only Roslyn analyzer that calls the Rust core in process?
6+
7+
**Verdict: REJECT for the Alpha.** The reasons and the evidence are in
8+
`docs/notes/owen-extension-ide-feasibility.md` (§ E2).
9+
10+
| piece | what it is |
11+
|---|---|
12+
| `native/` | a `cdylib` exporting `owen_e2_check(facts) -> msbuild lines`. It is the SAME `own_bridge::check_facts` + `render_finding` the CLI runs, with no semantics of its own, built in its own Cargo workspace |
13+
| `analyzer/` | a `netstandard2.0` `DiagnosticAnalyzer`. It reads OwnIR facts from an `AdditionalFiles` entry and maps the core's `file(line): warning CODE: text` lines onto `Location`s |
14+
15+
Run on Linux x64, .NET 8 SDK:
16+
17+
```sh
18+
(cd native && cargo build --release)
19+
(cd analyzer && dotnet build -c Release)
20+
# a consumer referencing analyzer/bin/Release/netstandard2.0/E2.Analyzer.dll as an <Analyzer>,
21+
# with an *.owen-facts.json AdditionalFile, and (variant 2)
22+
# <OwenNativeCore>/abs/path/libowen_e2.so</OwenNativeCore> + <CompilerVisibleProperty Include="OwenNativeCore" />
23+
```
24+
25+
**Variant 1: `DllImport` with `DllImportSearchPath.AssemblyDirectory`.**
26+
- **Result:** `DllNotFoundException` on every build, including after `dotnet build-server shutdown`.
27+
- **Why:** Roslyn shadow-copies analyzer assemblies and does not copy native files beside them.
28+
29+
**Variant 2: an explicit path, `CompilerVisibleProperty`, and `NativeLibrary` reached by reflection.**
30+
- **The finding arrives:** `C8.cs(18,1): warning OWNE2: OWN002: …`, identical across three builds through the compiler server and after a server restart.
31+
- **A replaced native file breaks loading:** after the native file was overwritten with garbage under a live server, loading failed. It did not fall back to a stale copy.
32+
- **`NativeLibrary` exists only on .NET-hosted compilers.** A .NET Framework compiler host has none.
Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
<Project Sdk="Microsoft.NET.Sdk">
2+
<PropertyGroup>
3+
<TargetFramework>netstandard2.0</TargetFramework>
4+
<LangVersion>12</LangVersion>
5+
<Nullable>enable</Nullable>
6+
<EnforceExtendedAnalyzerRules>true</EnforceExtendedAnalyzerRules>
7+
<AllowUnsafeBlocks>true</AllowUnsafeBlocks>
8+
<NoWarn>$(NoWarn);RS2008;RS1035</NoWarn>
9+
</PropertyGroup>
10+
<ItemGroup>
11+
<PackageReference Include="Microsoft.CodeAnalysis.CSharp" Version="4.8.0" PrivateAssets="all" />
12+
</ItemGroup>
13+
</Project>

0 commit comments

Comments
 (0)