Epic: NetScript DevTools contribution and host architecture

[rickylabs]

Epic: NetScript DevTools — the Aspire/Scalar satellite that drives the framework

Re-baselined 2026-08-11 onto RFC 0005 — DevTools contribution architecture, merged on main via PR #1450 and ratified by the owner.

What changed: this epic no longer invents its own discovery/registry/contribution mechanism, and the beta.6 framing and the S1–S13 screen list are retired. What survives verbatim: the ownership thesis and the three acceptance lines below — RFC 0005 §11 adopts them as normative acceptance criteria, not prose.

Ownership thesis — unchanged, and now normative in RFC 0005 §11.2

Aspire owns: resources, console/structured logs, raw traces, metrics, health, process lifecycle.

• Scalar owns: API reference, schemas, try-it, code samples.
• The dashboard owns: primitive run-state (executions/attempts, saga instances incl. compensating, trigger firings, stream deliveries), the runtime override/config layer including gated write-back, plugin-registry wiring + doctor + contribution axes, contract provenance/coverage/duality, route→contract binding, codegen/scaffold state (migrations, drift), the per-capability management loop (create → configure(tabs) → monitor), and the live request journey across framework seams (S13).

Product surfaces retained as RFC 0005 consumers

• S1 Shell & Wiring Home — [dashboard DDX-5] Fresh build-console shell + app-registration + IA #415 (v2: + quick-action strip mirroring top CLI verbs)
• S2 Config Resolution & Topology Hand-off — [dashboard DDX-6] Stack Map panel #416 (v2: + live-traffic edge overlay, Encore Flow model)
• S3 Runtime-Config Monitor & Control ⚑ flagship — [dashboard DDX-20] S3: Runtime-Config Monitor & Control (flagship) #551 (write-back gated on feat(runtime-config): mutation use-cases — set/unset + versioned current pointer bump (S3 write-back co-req) #556)
• S4 Service & Contract Catalog — [dashboard DDX-7] Service Catalog + API Explorer panel #417 (provenance/coverage/duality only; no try-it)
• S5 Plugin Control (dogfood centerpiece) — [dashboard DDX-10] Plugin Control host + registry/overview #420 (v2: + install/scaffold entry points, marketplace-lite)
• S6 Run Inspector + NetScript run-overlay — [dashboard DDX-9] Run Inspector panel #419 (run-centric)
• S7–S10 Workers / Sagas / Triggers / Streams consoles — [dashboard DDX-18a] workers per-capability dashboard section #428 [dashboard DDX-18b] sagas per-capability dashboard section #429 [dashboard DDX-18c] triggers per-capability dashboard section #430 [dashboard DDX-18d] streams per-capability dashboard section #431 (v2: each completes the create→configure→monitor→act management loop)
• S11 DB Migrations & Drift — [dashboard DDX-21] S11: DB Migrations & Drift #552 (DDX-21, new; beta.6-if-cheap; migrate/seed actions)
• S12 Dead-Letter Queues — [dashboard DDX-22] S12: Dead-Letter Queues (queue + trigger) #553 (gated on thin API slices)
• S13 Live Flow — request journey ⚑ flagship S1: package quality — slow-types + docs (supervisor) — Waves 0–6 ✅ merged  #2 — [dashboard DDX-8] S13: Live Flow — request journey across framework seams #418 (v2 REWRITE, was pass-1 waterfall: now the seam-event causal chain — request → payload → job → saga → fan-out — with per-node Aspire out-links)

Acceptance lines (MANDATORY, gate every slice)

Acceptance

1. Non-duplication. No dashboard screen may render, as an owned surface: an OTLP trace waterfall / span-bar gantt, a structured/console log tail, a metrics chart, a resource start/stop/restart panel, or an OpenAPI operation list / try-it console. Each is Aspire's or Scalar's job and MUST be a deep-link out. Every merged panel must pass "why can't this just deep-link to Aspire/Scalar?" with a NetScript-only answer recorded in its issue — only-NetScript state, only-NetScript action (CLI-mirroring), or framework-seam semantics raw OTLP cannot express.
2. One generator, two callers. Every dashboard mutation invokes the same contract route / CLI scaffolder the terminal does and renders its CLI-equivalent line (netscript … CodeBlock). No dashboard-only write paths, no forked codegen.
3. Flow ≠ waterfall. S13 renders a primitive-grouped causal chain with payloads at seams, assembled from NetScript's own seam events; the moment raw timing/span detail is needed it out-links to Aspire /traces/detail/{id}. No span bars, no time-proportional gantt, no log tails in S13 — ever.

Integration seams (four seams, one URL scheme)

1. Aspire → dashboard: WithUrl("NetScript Dashboard", /resource/{name}) on every scaffolded resource + two framework withCommands — typed links in [devtools W1b] add typed deep-link resolution #1472 and generated host/CLI wiring in [devtools W3a] generate the DevTools host and CLI command group #1477, Seam A widening (command/app kinds) on [dashboard DDX-1] @netscript/aspire command + app resource kinds #411, Seam B interim.
2. Dashboard → Aspire: correlation-only TelemetryQueryPort ([dashboard DDX-3] TelemetryQueryPort + aspire-otlp-http adapter #413) resolves a traceId, then out-links to {aspireBase}/traces/detail/{id}, /structuredlogs?resource=, /consolelogs/resource/, /metrics/resource/. Never re-renders OTLP. The S13 flow plane does not widen this port.
3. Dashboard → Scalar: /api/docs (+ operation anchor) deep-links only; externalDocs optional polish.
4. Data plane: owned /_netscript/* introspection ([dashboard DDX-13] Introspection endpoint (/_netscript/*) #423) over already-shipped oRPC contracts, plus /_netscript/flows (SSE): the DevTools data plane joins the shipped per-primitive streams on the stamped traceparent; co-req DDX-23 ([dashboard DDX-23] seam-event flow plane: unified envelope + HTTP boundary events (S13 co-req) #557) adds the unified seam-event envelope + HTTP boundary events.

Killed / folded surfaces (documented so they don't creep back)

• Raw OTLP waterfall renderer (pass-1 [dashboard DDX-8] S13: Live Flow — request journey across framework seams #418 scope → dead; [dashboard DDX-8] S13: Live Flow — request journey across framework seams #418 rescoped to the S13 seam-flow journey, which is not a waterfall — acceptance line 3).
• Logs panel ([dashboard DDX-11] Logs panel #421 → closed; correlated strip in S6 deep-links Aspire logs).
• Resource-control panel ([dashboard DDX-12] Resource Control panel #422 → closed; delivered as withCommand contributions inside Aspire).
• Service /health panel (→ Aspire State column via a proper withHealthCheck() wiring fix).
• Metrics charts + GenAI conversation view (→ Aspire, link only).
• Scalar-style operation list / try-it (→ Scalar /api/docs; the S4 catalog is provenance-only).

Slice map / dependencies

Plumbing: #410 (fresh-ui L3 blocks) → #412 (core scaffold, + FlowRecord) → #414 (thin plugin) · #411 (Seam A) · #413 (+#408 telemetry T7) · #423 (introspection + flows join) · #424 (CLI/deep-links/generator) · #427 (panel seam — the Directus-validated contribution axis).
Screens: #415, #416, #417, #418 (S13), #419, #420, #428–#431, DDX-20/21/22 (#551 #552 #553).
Management wave (beta.7): #432 elevated — "Add resource" scaffold-from-UI keystone; DDX-23 seam-event envelope #557; template-gallery create entries in S5/S7–S10.
Design evidence from completed #507 is ratified in RFC 0005. UI quality remains #509.
Gate: #426 (E2E join + panel smoke; v2 adds the S13 flow-chain assertion, still no owned-waterfall assertion).
Co-requisites (wave:defer): TriggerDlqPort contract route #554, queue DeadLetterStore CLI/API #555. Co-requisite (beta.7): runtime-config mutation use-cases #556 (S3 write-back — surface check 2026-07-06: the store is read+watch-only today).
Deferred convergences: in-dashboard AI-on-codegen (with #238), in-app plugin marketplace beyond S5 marketplace-lite.

Refs #301 (road to stable). Co-lands with epic:telemetry-revamp (#399) for T4–T7 correlation fidelity.

Architecture — now owned by RFC 0005

Question	Where it is answered
What DevTools is	§5 — a separate first-party host process: CLI-generated root, own Vite process, own port, loopback-bound, dev-only
Production behaviour	§5 — no production tier, enforced by two independent mechanisms
How plugins contribute	§6 — { family: 'devtools', major: 1 } on a family-neutral envelope in packages/devtools-core (owner fork F-1: self-contained, built first)
Which contribution kinds exist	§7 — three: panel, link, diagnostic (the last a reuse of the shipped plugin doctor seam). Each names a real first-party consumer
How a panel gets data	§8 — host-owned deny-by-default read contract; no URL-shaped input anywhere; worked end-to-end contributor path in §8 D-6.4b
Trust and threat model	§9 — exposure-graded tiers, INV-1/INV-2/INV-9, and threats labelled UNPROVEN where no gate exists yet
Information architecture	§11 — <base>/ is a ranked problem feed answering "what is broken?", with a full state matrix (10 surfaces × 9 arms)
Packages and gates	§13 — A1 packages/devtools-core + A6 CLI emission + A5 thin plugin; host app is generated userland
Roadmap	§14 — 16 slices, each naming files, the contract it introduces, and one proving command

Sub-issues

Filed 2026-08-11 from the ratified one-shot manifest. Ordered by RFC §14's dependency DAG.

• [devtools W0a] probe packaged island specifiers under Deno resolution #1469 — W0-a probe: package-shipped island specifiers
• [devtools W0b] probe a second route/island root in one Vite process #1470 — W0-b probe: second route/island root in one Vite process
• [devtools W1a] add contracts/v1, deterministic ordering, and architecture roots #1471 — W1-a devtools-core contracts/v1 + arch:check roots
• [devtools W1b] add typed deep-link resolution #1472 — W1-b typed deep-link helper
• [devtools W1c] enforce path containment and scoped generator subprocesses #1473 — W1-c path-containment invariant + scoped generator subprocess
• [devtools W1d] make plugin manifests forward-compatible before pointer fields #1474 — W1-d manifest .passthrough() precondition (F-3)
• [devtools W2a] generate the contribution registry transactionally #1475 — W2-a transactional replace-set registry generator
• [devtools W2b] diagnose the six contribution states in plugin doctor #1476 — W2-b doctor six-state taxonomy + quarantine
• [devtools W3a] generate the DevTools host and CLI command group #1477 — W3-a CLI-generated host root + devtools command group
• [devtools W3b] enforce production exclusion at build and runtime #1478 — W3-b dual production exclusion
• [dashboard DDX-17] DashboardPanelContribution seam (.withDashboardPanel) #427 — W4-a panel kind (folded into RFC 0005 §6/§7)
• [devtools W4b] wire typed link kinds and disabled reasons #1479 — W4-b link kind wiring
• [dashboard DDX-13] Introspection endpoint (/_netscript/*) #423 — W5-a DevTools read contract + in-process MCP (re-baselined)
• [devtools W5b] promote createSSEStream to the public Fresh export map #1480 — W5-b createSSEStream promotion
• [dashboard DDX-18a] workers per-capability dashboard section #428 — W6-a workers console (first real consumer)
• [dashboard DDX-18b] sagas per-capability dashboard section #429 / [dashboard DDX-18c] triggers per-capability dashboard section #430 / [dashboard DDX-18d] streams per-capability dashboard section #431 — W6-b sagas / triggers / streams consoles
• docs(rfc): ratify RFC 0005 — DevTools contribution architecture #1468 — RFC 0005 tracking issue

Relationship to existing boards

• Epic Epic: Frontend contribution layer — plugins that ship UI #922 (frontend contribution layer) is untouched. Its children — including [frontend-contrib S11] Workers dogfood: zone panel + console route + island #933 and [frontend-contrib S22] Sagas/triggers/streams dashboard-zone panels #944 — receive zero actions from this re-baseline. Both epics survive because they are different artifacts on different hosts: Epic: Frontend contribution layer — plugins that ship UI #922 owns app-surface zone panels, this epic owns DevTools-host consoles. Owner fork F-10.
• [dashboard DDX-2] plugin-dashboard-core scaffold + contract seam #412 is superseded in substance by packages/devtools-core ([devtools W1a] add contracts/v1, deterministic ordering, and architecture roots #1471).
• [dashboard DDX-14] CLI surface + auto-launch #424's flat URL scheme is superseded by RFC 0005 §11's entity-URL contract ([devtools W1b] add typed deep-link resolution #1472, [devtools W3a] generate the DevTools host and CLI command group #1477).
• [dashboard DDX-17] DashboardPanelContribution seam (.withDashboardPanel) #427 and feat(plugin): dashboard-panel contribution axis in the plugin manifest #734 fold into RFC 0005's contribution family.
• CR-DDX-HOSTAGNOSTIC (raised on this epic 2026-07-06 from Epic: NetScript Process Manager — bare-metal supervisor + admin console (pup/pm2 done right) #510, never resolved) is accepted — see the resolution comment below.

Notes (non-gating)

• Milestone train unchanged: children remain on 0.0.15 per the owner-ratified 2026-07-19 train; this epic stays on Backlog / Triage.
• Planning record: .llm/runs/plan-devtools-contribution--seed/.
• The Plan-Gate was cleared by written owner waiver (drift D-18). The formal evaluator returned FAIL_PLAN twice and no evaluator PASS exists — do not cite one.