docs(rfc): runtime-versioned workers/tasks & triggers — production architecture RFC

.llm/2026-08-11-rfc-runtime-versioned-automation.md

@@ -0,0 +1,10 @@
+# 2026-08-11 — runtime-versioned automation RFC orchestrator run
+
+Fable 5 medium supervisor run (owner override). Deliverables: the RFC
+(`rfcs/0000-runtime-versioned-automation.md`), legacy + current evidence reports with behavioral
+probes, 1444-impact memo (PR #1444), draft PR #1446. Two Codex Sol research slices (one thread,
+resumed) + a Sol·xhigh evaluator thread in a dedicated worktree. PLAN-EVAL: 2× FAIL_PLAN →
+per-protocol owner escalation with all findings fixed and verified. Lessons: (1) run-codex-slice
+forwards ONLY --launch-arg values; (2) one Codex sender per worktree — evaluator needs its own
+worktree; (3) NEVER patch by remembered strings after deno fmt — verify every replacement (drift
+D-7).

.llm/runs/docs-rfc-runtime-versioned-automation--supervisor/1444-impact.md

@@ -0,0 +1,91 @@
+# #1444 impact memo — control-plane / runtime split for plugin modules
+
+From: RFC orchestrator run `docs-rfc-runtime-versioned-automation--supervisor` (Fable 5,
+2026-08-11). Audience: the #1443/#1444 orchestrator. Scope: the immediate normative answer plus the
+compatibility constraints #1444 must honor so the runtime-versioned-automation RFC is not
+foreclosed. This memo does not ask #1444 to build anything beyond its current slices.
+
+## 1. Normative answer — the split is correct; keep it exactly this shape
+
+The owner's D-10 decision in
+`.llm/runs/orchestrator-1443-plugin-ai-next-canary--supervisor/drift.md` is **ratified from the RFC
+side**:
+
+```text
+workers/plugin.ts (configured module)  -> manifest-only, import-safe CONTROL PLANE
+workers/mod.ts, workers/runtime.ts     -> application/runtime surface (unchanged)
+workers/runtime/**                     -> versioned operator-managed definitions (unchanged)
+```
+
+Rationale the RFC will elaborate: a configured plugin manifest is _inventory metadata_ the control
+plane (CLI, `generate runtime-schemas`, doctor, future cockpit/management API) must read **without a
+running stack** — no DB, no Aspire env, no producers. Runtime initialization belongs to the barrel
+the app imports. Every credible external analogue (K8s CRD vs controller, Terraform provider schema
+vs apply, VS Code extension manifest vs activation) makes the same split: **declaration loads cold;
+activation runs hot.** The legacy `netscript-start` design conflated the two, which is one of the
+reasons its cockpit could not be made production-safe.
+
+## 2. Child-process loader — required, keep it
+
+Verdict: **the child-process loader remains required**, not a workaround. In-process `import()` from
+the CLI cannot honor the _consumer's_ import map / compiler options; only a child
+`deno run
+--config <project>/deno.json` resolves the module the way the consumer's own runtime will.
+`clearEnv:
+true` is load-bearing: it is the executable proof of the "loads under empty environment"
+contract — do not weaken it. The stdout marker-line protocol + JSON-serialized manifests is fine.
+
+## 3. Compatibility constraints #1444 must honor now
+
+C1. **Import-safety is a contract, not a convention.** The shared all-first-party contract test
+(D-10 "required proof") must pin: empty env, exactly one exported `PluginManifest`, no runtime
+construction at module scope. Keep it parameterized so future plugins are covered by default.
+
+C2. **Manifests stay data.** The child protocol serializes manifests over JSON. Never add function
+or class fields to `PluginManifest`; future capability declarations (e.g. "this plugin owns a
+versioned runtime tree at `workers/runtime/**`") must be declarative fields. The RFC will likely add
+such fields — see C3.
+
+C3. **Leave the manifest schema additively extensible.** `manifest.ts` is `.strict()`. Strict is
+fine for now, but version the schema (or reserve an optional namespaced extension field) so an older
+CLI meeting a newer plugin manifest fails with a _versioned_ error, not a generic Zod strip/throw.
+The RFC will propose `runtime` capability metadata on the manifest; #1444 does not need to add it —
+it only needs to not make adding it a breaking change.
+
+C4. **Do not couple identity to hardcoded names.** Installed-plugin identity must follow the
+configured module's exported manifest (S5 direction is right). The accepted registered-spec set
+(`plugins/<name>/plugin.ts`, `<name>/plugin.ts`, plus legacy `mod.ts` forms) is the migration bridge
+for existing consumers — keep accepting the legacy `mod.ts` registration until a deprecation cycle
+is declared, and surface a doctor hint instead of a hard failure when the configured module is
+`mod.ts`-shaped.
+
+C5. **`deno.jsonc` gap (flag, fix cheaply or record).** The loader branches on
+`readOptionalTextFile(join(projectRoot, 'deno.json')) === null` → falls back to in-process
+resolution. A consumer with `deno.jsonc` (valid for Deno) silently loses consumer-config resolution
+and will get the old failure mode. Either probe both filenames or record it as a known limitation +
+doctor check. (Scaffolded projects emit `deno.json`, so this is an edge, not a blocker.)
+
+C6. **`generate runtime-schemas` stays control-plane-only.** It must depend on manifests + schema
+metadata only — never on importing `mod.ts`/`runtime.ts` or on live services. That is what un-breaks
+#1445 for every plugin and is a boundary the RFC will build on (schema generation for
+operator-managed versioned documents will extend this path).
+
+C7. **Do not touch `workers/runtime/**` / `triggers/runtime/**` semantics.** Preserved exactly as
+scaffolded today, including the `current` pointer + versioned JSON documents consumed by
+`@netscript/runtime-config`. The redesign (atomic promotion, DB/object-store sync, multi-instance
+propagation, sandboxing, RBAC, cockpit) is this RFC's scope, not #1444's.
+
+C8. **Permission surface of the child loader.** `--allow-read --allow-net` with `clearEnv` is
+acceptable today (net is needed for cold jsr resolution). Note in the PR body that the loader
+executes consumer-controlled code with network access at _control-plane_ time; the RFC's threat
+model will formalize this (lockfile-pinned resolution, `--cached-only` fast path, and a future
+capability prompt are candidate hardenings). No action required in #1444 beyond the note.
+
+## 4. What #1444 must not absorb
+
+Per D-10's scope boundary: no versioned-tree redesign, no cockpit work, no DB synchronization, no
+sandbox/RBAC design, no static-config collapse, no deletion/neutering of runtime surfaces to green a
+gate. Anything in that list discovered mid-slice: record it and hand it to this RFC run.
+
+— End of memo. Full RFC (with evidence-backed legacy/current matrix) follows in
+`rfcs/0000-runtime-versioned-automation.md` on branch `docs/rfc-runtime-versioned-automation`.

.llm/runs/docs-rfc-runtime-versioned-automation--supervisor/briefs/current-state-brief.md

@@ -0,0 +1,121 @@
+use harness
+
+# Slice brief — Current-state capability matrix: runtime-versioned workers/tasks/triggers
+
+## SKILL
+
+Load and honor: `netscript-harness`, `netscript-doctrine`, `netscript-tools`,
+`netscript-deno-toolchain` (use `deno doc` / `deno doc --filter` before broad source reads),
+`netscript-cli`. Research slice inside
+`.llm/runs/docs-rfc-runtime-versioned-automation--supervisor/`.
+
+## Identity and hard constraints
+
+- Codex GPT-5.6 Sol research sub-agent for a Claude Fable 5 RFC supervisor.
+- Worktree: `/home/codex/repos/ns-rfc-runtime-versioned-automation`, branch
+  `docs/rfc-runtime-versioned-automation` (== origin/main @ 2256a67bf). **Do not commit, push, or
+  modify tracked files.** Writes allowed only under
+  `.llm/runs/docs-rfc-runtime-versioned-automation--supervisor/evidence/`.
+- Bounded disposable proofs ARE allowed and wanted: `deno check` probes, `deno doc`, targeted
+  `deno test` of existing suites, CLI invocations against throwaway scaffolds under
+  `.llm/tmp/rfc-probes/` (create, use, then note; do not leave services running). Do NOT run the
+  expensive `scaffold.runtime` E2E; do not start Aspire or containers. Do not run
+  `deno cache --reload` or touch lock files.
+- Prefix read-heavy git/grep/ls with `rtk`.
+- A prior report exists at `evidence/legacy-capability-map.md` (legacy `netscript-start`
+  archaeology). Read its executive summary first; your job is the CURRENT repo side of the same
+  story.
+
+## Mission
+
+Build the current-state half of a legacy → current → gap matrix for runtime-versioned
+workers/tasks/triggers. **Do not infer support from exported types alone** — for each high-value
+claim, either point at a test/E2E that proves it or run a bounded disposable proof yourself.
+Tag every capability `PROVEN` (test/E2E/probe evidence), `IMPLEMENTED-UNPROVEN` (code path
+complete, nothing exercises it), `PARTIAL`, or `ABSENT`.
+
+Context you must know: the owner has authorized a **complete redesign with no
+backward-compatibility layer** — this matrix decides what ideas/seams are worth KEEPING and what
+gets inventoried for REMOVAL, not how to migrate. So for every surface also record a
+keep/extract-idea/delete disposition hint, and be precise about which types/commands/files are
+exported-but-unused (they are removal candidates).
+
+## Parent hypotheses to verify or refute (each needs a verdict + evidence)
+
+H1. The versioned read model (`runtime-config` loader/watcher) and the CLI versioned store
+    (`runtime-config-store-port.ts`, `deno-runtime-config-store.ts` temp+rename activation,
+    `manage-runtime-overrides.ts`) both work, but **no production worker/trigger composition
+    consumes the snapshots** — `loadRuntimeConfig`/`watchRuntimeConfig`/`getRuntimeTask`/
+    `getTriggerOverride` are used only by the package's own docs/tests. Build the real call graph
+    (exclude generated/embedded assets like `agent-docs.generated.ts`).
+H2. Two drifting task schemas: permissive `RuntimeTask` (runtime-config domain, 7 runtimes) vs
+    rich `TaskDefinition` (plugin-workers-core domain). The executor executes `TaskDefinition`;
+    nothing feeds `RuntimeConfig.tasks` into it; `NETSCRIPT_TASKS_DIR` remaps entrypoint paths
+    rather than loading additive versioned definitions (`local-runtime-backend.ts::runTask`,
+    `plugins/workers/worker/job-execution.ts`).
+H3. Triggers: `TriggerOverride {id, enabled?, paths?}` is override-only (no additive runtime
+    trigger definitions); the trigger runtime processor (KV idempotency, DLQ, deferred replay,
+    OTel) loads generated TS registries (`project-trigger-registry.ts`) and does NOT compose
+    versioned overrides from runtime-config.
+H4. `generate runtime-schemas` plans/writes real JSON Schema objects and rejects duplicate topic
+    owners, but on this baseline `plugin-registry.ts::resolveRegisteredPluginSnapshot` collapses
+    declared `runtimeConfigTopics` to `runtimeConfig: { schemas: [] }` — so output is empty in
+    practice. (PR #1444 fixes configured-module loading; state what baseline behavior is, do not
+    re-derive #1444.)
+H5. Competing/duplicate CLI surfaces: generic `netscript config override` (real versioned store)
+    vs workers-plugin `config-edit`/`config-publish` writing `.netscript/runtime/<topic>.json`
+    without versioning/activation — unfinished duplicate DX.
+H6. The versioned store has: no optimistic concurrency/revision preconditions, no author/approval
+    metadata, no multi-instance propagation, local-fs atomicity only. Also check path-traversal
+    handling on topic/version inputs and partial multi-topic promotion consistency.
+
+## Behavioral proofs (bounded, disposable, highest value)
+
+Under `.llm/tmp/rfc-probes/` (throwaway scaffold or minimal fixture dirs; record commands + exit
+codes; leave nothing running):
+
+P1. Publish → activate → rollback via the real store adapter; verify temp+rename atomicity and
+    what a concurrent second writer does (best-effort observation).
+P2. Watcher reload: start a tiny consumer using `watchRuntimeConfig`, flip `current`, observe
+    callback; malformed version doc → observe silent-empty behavior.
+P3. `generate runtime-schemas` on a minimal consumer fixture: capture real output (or its
+    absence/emptiness) on baseline.
+P4. Additive task attempt: put a task into the versioned `tasks` topic and demonstrate whether ANY
+    existing execution path picks it up (expected: none — prove the disconnect).
+P5. Executor polyglot smoke: run one trivial deno + one shell/cmd task through
+    `MultiRuntimeTaskExecutor` directly (unit-level, no services) to confirm the engine executes.
+
+### Required coverage
+
+1. `packages/runtime-config` — types, loaders, accessors, `current` pointer semantics, version
+   document format, the watcher (`src/application/watcher.ts`): what triggers reload, atomicity,
+   error handling on malformed documents, who actually calls `loadRuntimeConfig`/the watcher in
+   apps/plugins/scaffold output.
+2. `netscript generate runtime-schemas` — implementation path, what it emits where, and its real
+   behavior on a clean consumer (note: PR #1444 is fixing the configured-module loader; document
+   the on-main behavior and mark the known #1445 breakage rather than re-deriving it).
+3. Workers: the workers CLI surface, `MultiRuntimeTaskExecutor`, runtime adapters (which runtimes
+   actually execute: deno/node/python/shell/...?), permission model per task, polyglot execution
+   reality. Where do runtime task definitions come from at execution time (versioned tree? static
+   registry?).
+4. Triggers: runtime processor, stores, streams integration, idempotency/dead-letter behavior,
+   how trigger definitions are loaded/reloaded.
+5. Plugin scaffold output: what `plugin install workers|triggers` actually emits today —
+   `workers/runtime.ts`, `triggers/runtime.ts`, `workers/runtime/**` config trees (`current`
+   pointer, `schema.json`, versioned JSON docs), and whether anything consumes them at runtime.
+6. Aspire wiring: how workers/triggers services are declared, env plumbing for runtime config dirs,
+   deployment/runtime reload behavior (does a deployed stack see pointer changes without restart?).
+7. Telemetry/management: any OTel spans/events/metrics for task/trigger execution; any management
+   API or UI endpoints touching runtime config; execution-history persistence.
+8. Test/docs/E2E truth: which of the above are covered by tests or `e2e:cli` suites (name them),
+   what the docs claim vs what is proven. List every claim that is documented but unproven.
+
+## Output contract
+
+- Full report → `evidence/current-state-matrix.md`. Start with a ≤25-line executive summary.
+- Include a `## Legacy → current mapping` table: for each legacy capability in the legacy report's
+  summary, state current equivalent, status tag, and gap.
+- Cite `path:line` for load-bearing claims; record every probe command + exit code in a
+  `## Probe log` section.
+- Final section `## Claims the supervisor should re-verify` (5 weakest inferences).
+- Reply exactly `DONE` on the final line, or `BLOCKED: <reason>`.

.llm/runs/docs-rfc-runtime-versioned-automation--supervisor/briefs/legacy-archaeology-brief.md

@@ -0,0 +1,77 @@
+use harness
+
+# Slice brief — Legacy capability archaeology: runtime-versioned workers/tasks/triggers
+
+## SKILL
+
+Load and honor: `netscript-harness` (run mechanics), `netscript-doctrine` (vocabulary only — the
+legacy repo predates doctrine; do not grade it), `netscript-tools` (rtk usage, evidence rules).
+This is a **research-only** slice inside the harness run
+`.llm/runs/docs-rfc-runtime-versioned-automation--supervisor/`.
+
+## Identity and hard constraints
+
+- You are a Codex GPT-5.6 Sol research sub-agent for a Claude Fable 5 RFC supervisor.
+- Working directory / git worktree: `/home/codex/repos/ns-rfc-runtime-versioned-automation`
+  (branch `docs/rfc-runtime-versioned-automation`). **Do not commit, push, stage, or modify any
+  tracked file.** Your only writes are new files under
+  `.llm/runs/docs-rfc-runtime-versioned-automation--supervisor/evidence/`.
+- Evidence subject: the legacy product repo at `/home/codex/repos/netscript-start-ref`
+  (HEAD `6ba9ba0`, branch master). It is **strictly read-only**: never run git mutations, never
+  edit files, never push. Reading files and running read-only `git log`/`git show` there is fine.
+- Do not start services, containers, or long-running processes. Static archaeology only.
+- Prefix read-heavy git/grep/ls with `rtk` to save tokens.
+
+## Mission
+
+Reconstruct — from code evidence, not aspiration — what an **operator** could actually do with the
+legacy runtime-versioned workers/tasks and triggers system in `netscript-start-ref`. This feeds a
+production RFC; wrong claims poison the RFC, so every claim must carry a file path (and line refs
+for load-bearing claims) and an explicit confidence tag: `IMPLEMENTED` (wired end-to-end),
+`PARTIAL` (code exists but path incomplete), `ASPIRATIONAL` (UI/schema/docs only), or `DEAD`
+(unreachable/unused).
+
+Known anchor points (verify and expand; do not assume this list is complete or correct):
+
+- `config/runtime/mod.ts`
+- `workers/runtime/tasks/v1.0.0.json`, `workers/runtime/current`, `workers/runtime/schema.json`
+- the corresponding `triggers/runtime/**` tree
+- cockpit routes under `apps/playground/routes/(dashboard)/dashboard/plugin/workers/tasks` and the
+  triggers dashboard equivalents
+- CLI: `netscript generate runtime-schemas` (find its implementation and what it emitted)
+
+## Required report sections (answer each concretely)
+
+1. **Version pointer + immutable version documents** — how `current` pointers and `vX.Y.Z.json`
+   documents worked: format, who read them, who wrote them, atomicity, validation on load.
+2. **Schema generation/validation** — how `schema.json` was produced and enforced; drift between
+   schema and actual loader behavior.
+3. **Hot add/update/rollback** — could an operator add or change a task/trigger on a *running*
+   stack without rebuild/restart? Trace the actual reload path (fs watch? poll? API mutation?
+   restart-required?). This is the single most load-bearing question — give the strongest evidence
+   either way.
+4. **Worker tasks + scheduled/background jobs** — task definition shape, runtimes supported,
+   scheduling, execution loop.
+5. **Triggers + event handling** — trigger definition shape, event sources, dispatch, coupling to
+   workers.
+6. **Execution history / status / observability** — what was persisted (tables/collections), what
+   the cockpit displayed, gaps.
+7. **Cockpit workflows** — enumerate the dashboard routes/components for workers tasks + triggers;
+   for each, which operations were wired to real APIs vs mock/dead UI.
+8. **Permissions, runtime selection, polyglot/legacy-wrapper support** — evidence of running
+   non-TS scripts (shell/python/etc), permission model per task, sandboxing if any.
+9. **Persistence/synchronization** — filesystem vs DB source of truth, sync between them,
+   multi-instance behavior, race/failure handling.
+10. **Operational limitations + why it was not production-ready** — concrete defects, TODOs,
+    missing auth, race conditions you can point at.
+
+## Output contract
+
+- Write the full report to
+  `.llm/runs/docs-rfc-runtime-versioned-automation--supervisor/evidence/legacy-capability-map.md`.
+- Start the report with a ≤25-line executive summary of what an operator could genuinely do.
+- Use the confidence tags everywhere. Cite `path:line` for every load-bearing claim.
+- Include a final section `## Claims the supervisor should re-verify` listing your 5 weakest
+  inferences.
+- When finished, reply with exactly `DONE` on the final line. If blocked, reply
+  `BLOCKED: <reason>`.