Wave 1 — Contracts & schemas

.agents/docs/README.md

@@ -126,8 +126,15 @@ deno task check
 # Run tests
 deno task test
 
-# Run CLI E2E tests (expensive — run before merge)
+# Discover available CLI E2E suites and gates
+deno task e2e:cli suites
+deno task e2e:cli gates scaffold.runtime
+
+# Run the full CLI E2E smoke before merge
 deno task e2e:cli
+
+# Debug the explicit full suite with readable output
+deno task e2e:cli run scaffold.runtime --cleanup --format pretty
 ```
 
 ### Working with the harness

.llm/harness/debt/arch-debt.md

@@ -16,6 +16,11 @@ Seeded from
   feature slices, kernel adapters, template assets, binary edges, and executable CLI fitness gates
   now cover the former monoliths.
 - **Gate:** F-1, F-5, F-6, F-7
+- **Wave 1 closure evidence:** `feat-package-quality-wave1-contracts--contracts` slice 10 split
+  `packages/runtime-config/mod.ts` into `src/domain/types.ts`, `src/application/loader.ts`,
+  `src/application/watcher.ts`, and `src/diagnostics/summary.ts`; `deno check`, `deno doc --lint`,
+  `deno publish --dry-run --allow-dirty`, `deno test --allow-all`, `deno lint`, and
+  `deno fmt --check` pass for the package.
 
 ## packages/config — AP-1 / doctrine verdict Refactor (schema.ts 945 LOC)
 
@@ -28,6 +33,52 @@ Seeded from
   maintainer command graph; `deno task arch:check` enforces public/maintainer isolation.
 - **Gate:** F-1, F-5, F-10
 
+## packages/config — AP-16 root helpers.ts
+
+- **Reason:** Root `helpers.ts` held saga authoring input types behind a generic helper name.
+- **Owner:** Wave 1 contracts and schemas.
+- **Target:** S1 alpha package-quality wave.
+- **Linked plan:** `.llm/tmp/run/feat-package-quality-wave1-contracts--contracts/plan.md`
+- **Created:** 2026-06-06
+- **Status:** closed 2026-06-06 — slice 11 renamed `helpers.ts` to
+  `src/domain/saga-inputs.ts` and kept the public `defineSagas`/input type exports stable through
+  `src/public/mod.ts`.
+- **Gate:** F-11, AP-16, `deno check mod.ts`
+
+## packages/config/src/domain/mod.ts — justified domain barrel
+
+- **Reason:** `src/domain/mod.ts` is a sub-barrel, but it intentionally curates the domain schema
+  surface consumed by `src/public/mod.ts` and future docs/reference generation.
+- **Owner:** Wave 1 contracts and schemas.
+- **Target:** Revisit when generated reference tooling can crawl individual schema modules.
+- **Linked plan:** `.llm/tmp/run/feat-package-quality-wave1-contracts--contracts/plan.md`
+- **Created:** 2026-06-06
+- **Status:** open, DEBT_ACCEPTED — slice 17 added `arch:barrel-ok` justification in the file.
+- **Gate:** F-18, `Select-String -Path src/domain/mod.ts -Pattern 'arch:barrel-ok'`
+
+## packages/contracts — AP-16 helpers directory
+
+- **Reason:** Root `helpers/` held query and transform helpers behind a generic folder name.
+- **Owner:** Wave 1 contracts and schemas.
+- **Target:** S1 alpha package-quality wave.
+- **Linked plan:** `.llm/tmp/run/feat-package-quality-wave1-contracts--contracts/plan.md`
+- **Created:** 2026-06-06
+- **Status:** closed 2026-06-06 — slices 19 and 20 moved `paginated-query.ts` and
+  `transform.ts` into `src/application/` as role-named modules and removed the `helpers/`
+  directory.
+- **Gate:** F-11, AP-16, `deno check mod.ts`
+
+## packages/contracts/crud — accepted root subpath layout
+
+- **Reason:** `crud/` remains at the package root to preserve the established `./crud` subpath
+  export and avoid broad downstream import churn during S1.
+- **Owner:** Wave 1 contracts and schemas.
+- **Target:** Revisit when subpath exports can move without consumer breakage.
+- **Linked plan:** `.llm/tmp/run/feat-package-quality-wave1-contracts--contracts/plan.md`
+- **Created:** 2026-06-06
+- **Status:** open, DEBT_ACCEPTED — locked decision L8 keeps `contracts/crud/` at package root.
+- **Gate:** F-5/F-6 remain green for `@netscript/contracts`; consumer validation in slices 25-27.
+
 ## packages/cron — AP-17 / doctrine verdict Refactor
 
 - **Reason:** `interfaces/` should become `ports/`; adapter classes should be named by technology.

.llm/tmp/run/feat-package-quality-wave1-contracts--contracts/commits.md

@@ -0,0 +1,42 @@
+# Commits: Wave 1 — Contracts & schemas
+
+Append every commit created during the run immediately after creating it.
+
+Format:
+
+```md
+- <commit-sha>: <commit message>
+```
+
+## Log
+
+- 187f862: plan(wave1): research + plan & design for config, contracts, runtime-config
+- d0be0ad: refactor(runtime-config): scaffold domain types
+- 31b1464: refactor(runtime-config): extract loader application module
+- 617e7d4: refactor(runtime-config): extract watcher application module
+- 23e1480: feat(runtime-config): add structured config summary
+- f59f9ef: refactor(runtime-config): expose thin public barrel
+- f413fde: chore(runtime-config): add package tasks and publish config
+- 45a276b: docs(runtime-config): add package README
+- df8d087: docs(runtime-config): scaffold package docs
+- 7b83766: test(runtime-config): cover loader accessors and summary
+- a8a7caf: test(runtime-config): complete package gate sweep
+- 2b638df: refactor(config): rename saga input helpers
+- d60f43c: docs(config): export saga group input and document config types
+- fbcfee5: docs(config): fix merge subpath public types
+- 0ac2d8b: docs(config): harden plugin schema public docs
+- 43e51b4: docs(config): add recipes and advanced guide
+- 3c10baa: docs(config): justify domain barrel
+- 68f6d6d: test(config): complete package gate sweep
+- aab8d2f: refactor(contracts): move paginated query helper
+- 5062e76: refactor(contracts): move transform helpers
+- df7a919: docs(contracts): export subpath schema types
+- ec09969: docs(contracts): add getting started guide
+- eb545ca: docs(contracts): add advanced extending guide
+- b066da6: test(contracts): complete package gate sweep
+- f4cbd3c: test(workspace): validate cli consumer
+- cdff7f0: test(workspace): validate plugin consumers
+- ad0b232: test(workspace): verify final package publish dry runs
+- 936209a: docs(agents): clarify full cli e2e command
+- f6bf743: test(cli): restore full scaffold runtime e2e
+- b96ba0d: docs(agents): port durable claude guidance

.llm/tmp/run/feat-package-quality-wave1-contracts--contracts/context-pack.md

@@ -0,0 +1,87 @@
+# Context Pack: Wave 1 — Contracts & schemas
+
+| Field | Value |
+|-------|-------|
+| Run ID | `feat-package-quality-wave1-contracts--contracts` |
+| Branch | `feat/package-quality-wave1-contracts` |
+| Base | `feat/package-quality` (Wave 0 `shared` + Wave 0b harness/docs merged) |
+| Phase | **IMPL-EVAL complete → `FAIL_FIX`** (returns to generator for one fix) |
+| Units | `@netscript/config`, `@netscript/contracts`, `@netscript/runtime-config` |
+| Archetype | 1 — Small Contract (all three) |
+| Scope overlay | none (package wave) |
+
+## Goal
+
+Bring the 3 units to the S1 alpha bar: `deno publish --dry-run` with **0 slow-types**, `deno doc --lint` clean, README ≥ 150 LOC, `/docs` per STANDARDS § 7, archetype gate matrix green per unit. **S1 STOPS at publish-clean dry-run — do NOT publish.**
+
+## Status
+
+- [x] `research.md` — re-baselined with REAL dry-run numbers (0 slow types all three)
+- [x] `plan.md` — locked decisions, open-decision sweep, risk register, gate set selected
+- [x] `worklog.md` — Design checkpoint with public surface, domain vocabulary, 27 commit slices
+- [x] `drift.md` — re-baseline drift logged
+- [x] `commits.md` — scaffolded (no commits yet)
+- [x] `plan-eval.md` — **PLAN-EVAL PASS** (Arch-1 gate set adjusted: added F-14 Console-log, F-17 Abstract-derived co-location)
+- [x] Slice 1 — `runtime-config` domain types scaffolded; `deno doc --lint src/domain/types.ts` passed.
+- [x] Slice 2 — `runtime-config` loader extracted; `deno check src/application/loader.ts` passed.
+- [x] Slice 3 — `runtime-config` watcher extracted with no `console.*` in `src/`; `deno check src/application/watcher.ts` passed.
+- [x] Slice 4 — `runtime-config` structured summary added; `deno check src/diagnostics/summary.ts` passed.
+- [x] Slice 5 — `runtime-config` root barrel rewritten; `deno doc --lint mod.ts` passed.
+- [x] Slice 6 — `runtime-config` `deno.json` metadata/tasks/publish config added; `deno publish --dry-run --allow-dirty` passed.
+- [x] Slice 7 — `runtime-config` README added; line-count gate returned 346 lines.
+- [x] Slice 8 — `runtime-config` docs scaffold added; docs file-list gate returned 8 files.
+- [x] Slice 9 — `runtime-config` tests added; `deno test --allow-all` passed with 8 tests.
+- [x] Slice 10 — `runtime-config` gate sweep passed after lint/format/example fixes; current README line count is 339.
+- [x] Slice 11 — `config/helpers.ts` renamed to `src/domain/saga-inputs.ts`; `deno check mod.ts` passed.
+- [x] Slices 12-13 — `SagaGroupInput` exported and remaining `types.ts` JSDoc added; `deno doc --lint mod.ts` passed.
+- [x] Slice 14 — config merge subpath private-type-ref fixed; `deno doc --lint src/merge/mod.ts` passed.
+- [x] Slice 15 — config plugin schemas documented and Zod internal public type leak removed; `deno doc --lint src/schema/plugins/mod.ts` passed.
+- [x] Slice 16 — config docs recipes and advanced page added; docs file-list gate returned 7 files.
+- [x] Slice 17 — config domain barrel marked with `arch:barrel-ok`; grep gate passed.
+- [x] Slice 18 — config gate sweep passed after static cleanup, type split, and domain schema grouping; publish dry run remained at 0 slow types.
+- [x] Slice 19 — contracts paginated-query helper moved to `src/application`; `deno check mod.ts` passed.
+- [x] Slice 20 — contracts transform helper moved to `src/application`; `deno check mod.ts` and `deno check transform.ts` passed; `helpers/` removed.
+- [x] Slice 21 — contracts subpaths exported schema/procedure public types; `deno doc --lint crud.ts query.ts transform.ts` passed.
+- [x] Slice 22 — contracts `docs/getting-started.md` added and linked; docs file-list gate passed.
+- [x] Slice 23 — contracts `docs/advanced/extending.md` added and linked; docs file-list gate passed.
+- [x] Slice 24 — contracts gate sweep passed; helpers AP-16 debt closed and root `crud/` accepted debt recorded.
+- [x] Slice 25 — `packages/cli` consumer `deno check` passed with 0 errors.
+- [x] Slice 26 — `plugins/sagas` and `plugins/workers` consumer `deno check` passed with 0 errors.
+- [x] Slice 27 — final publish dry run passed for `runtime-config`, `config`, and `contracts` with 0 slow-type errors.
+
+## Key findings (re-baselined)
+
+| Unit | Slow types | `deno doc --lint` | README LOC | `/docs` | Tests |
+|------|-----------:|------------------:|-----------:|---------|-------|
+| `@netscript/config` | **0** | 33 errors | 255 ✓ | partial | exists |
+| `@netscript/contracts` | **0** | 21 errors | 424 ✓ | partial | exists |
+| `@netscript/runtime-config` | **0** | 34 errors | **0** ✗ | **missing** ✗ | **missing** ✗ |
+
+## Locked decisions (8)
+
+1. All three stay Archetype 1.
+2. `runtime-config/mod.ts` splits into `src/domain/`, `src/application/`, `src/diagnostics/`.
+3. `config/helpers.ts` → `src/domain/saga-inputs.ts`.
+4. `contracts/helpers/` → `src/application/` by role.
+5. `runtime-config` console usage → structured diagnostics (return values).
+6. Fix `private-type-ref` by exporting referenced types.
+7. Remove Zod internal (`z.ZodType`) from public signatures.
+8. Keep `crud/` at package root (subpath export stability).
+
+## Commit slices
+
+27 slices ordered by dependency: runtime-config (1–10), config (11–18), contracts (19–24), cross-cutting (25–27).
+
+## Operating reminders
+
+- Implementation has completed through slice 27.
+- **IMPL-EVAL verdict: `FAIL_FIX`** (`evaluate.md`) was addressed before the post-review CLI E2E
+  pass. The config `./paths` doc-lint gap was fixed and committed before this handoff.
+- Post-review CLI E2E gap is closed: bare `deno task e2e:cli` now runs the full
+  `scaffold.runtime` merge-readiness suite with cleanup instead of the narrow plugin scaffold
+  smoke. The suite scaffolds a project, initializes/generates/seeds the DB, launches Aspire,
+  adds plugins, validates generated checks, exercises worker/saga/trigger runtime endpoints, checks
+  plugin doctor, verifies OTEL trace linkage, and cleans up apphost/Docker resources.
+- Full CLI E2E evidence: `deno task e2e:cli` returned PASS with `passed=41 failed=0 skipped=0`.
+  `docker ps` was empty afterward, and `aspire ps` reported no running apphost.
+- Do not self-evaluate in the implementation session. Hand off to a separate IMPL-EVAL session.

.llm/tmp/run/feat-package-quality-wave1-contracts--contracts/drift.md

@@ -0,0 +1,103 @@
+# Drift Log: Wave 1 — Contracts & schemas
+
+Drift is append-only. Record facts that diverge from the plan, RFC, doctrine, or current-state documentation.
+
+## 2026-06-06 — Research re-baseline
+
+- **What:** The canonical audit (`.llm/tmp/run/copilot-evaluate-every-package-jsr-release--package-jsr-alpha-release/`) claimed slow-type counts of 35, 30, and 1 for config, contracts, and runtime-config. Re-derivation against `feat/package-quality` shows **0 slow types for all three**.
+- **Source:** `deno publish --dry-run --allow-dirty` per package.
+- **Expected:** Slow types exist and need fixing.
+- **Actual:** Workspace `compilerOptions.isolatedDeclarations: true` already enforces explicit types; all slow types were eliminated in prior waves.
+- **Severity:** minor
+- **Action:** accept — plan updated to reflect real state; slices for slow-type fixes removed.
+- **Evidence:** `research.md` findings #1, #12, #21.
+
+## 2026-06-06 — `runtime-config` archetype confirmation
+
+- **What:** Stale audit suggested `runtime-config` might pull toward Archetype 2 (Integration) due to `@std/path` and `Deno.*` usage.
+- **Source:** `docs/architecture/doctrine/06-archetypes.md` decision tree.
+- **Expected:** Might need ports/adapters.
+- **Actual:** Single file-system edge, no second backend planned. Value is still "clarity of types." Archetype 1 confirmed.
+- **Severity:** minor
+- **Action:** accept — locked in plan.md L1.
+- **Evidence:** `plan.md` § Archetype.
+
+## 2026-06-05 — PLAN-EVAL gate-set adjustment
+
+- **What:** The plan's selected Archetype-1 fitness gate set omitted **F-14 (Console-log lint)** and **F-17 (Abstract-derived co-location)**, both marked `required` for Arch 1 in `gates/archetype-gate-matrix.md`.
+- **Source:** PLAN-EVAL checklist walk vs. `.llm/harness/gates/archetype-gate-matrix.md`.
+- **Expected:** Gate set lists every `required` Arch-1 gate.
+- **Actual:** F-14 and F-17 missing; F-14 is materially relevant because L5 removes `runtime-config` console usage and F-14 is its proving gate.
+- **Severity:** minor
+- **Action:** adjust — added F-14 (mapped to L5) and F-17 (PENDING_SCRIPT, no violation) to `plan.md` §Fitness Gates + Validation Plan and `worklog.md` gate table. Plan-Gate "Gate set selected" box now satisfied; verdict PASS.
+- **Evidence:** `plan-eval.md`, `plan.md` §Fitness Gates.
+
+## 2026-06-06 — Config slices 12-13 gate dependency
+
+- **What:** Slice 12 exports `SagaGroupInput` and names `deno doc --lint mod.ts` as its gate, but
+  that gate still fails on the known 32 `types.ts` property JSDoc errors assigned to slice 13.
+- **Source:** `deno doc --lint mod.ts` after exporting `SagaGroupInput`.
+- **Expected:** Slice 12 gate passes after the private-type-ref export fix.
+- **Actual:** The private-type-ref issue is fixed, but doc-lint remains blocked until slice 13 adds
+  the missing JSDoc. The only honest green gate is after slices 12 and 13 are both present.
+- **Severity:** minor
+- **Action:** combine the implementation evidence for slices 12 and 13, then continue with slice
+  14 in order.
+- **Evidence:** `worklog.md` progress rows for slices 12 and 13.
+
+## 2026-06-06 — Config merge subpath type exports
+
+- **What:** Slice 14 planned to export `DatabaseEntry`, `ServiceContributionEntry`, and
+  `AppContributionEntry`, but `mergePartialConfig()` also publicly names `NetScriptConfig`.
+- **Source:** `deno doc --lint src/merge/mod.ts`.
+- **Expected:** Exporting the three contribution entry types is enough.
+- **Actual:** Exporting `NetScriptConfig` makes its referenced config section types public through
+  the `./merge` subpath too, so the subpath must export the config type family used by
+  `NetScriptConfig`.
+- **Severity:** minor
+- **Action:** export the referenced config types from `src/merge/mod.ts`; keep runtime behavior
+  unchanged.
+- **Evidence:** `deno doc --lint src/merge/mod.ts` passed after expanding the type exports.
+
+## 2026-06-06 — Config plugin schema public annotation
+
+- **What:** Slice 15 planned to remove `z.ZodType` public annotations by using inferred schema
+  types.
+- **Source:** `deno doc --lint src/schema/plugins/mod.ts`.
+- **Expected:** Removing explicit `z.ZodType` annotations is enough.
+- **Actual:** Doc-lint requires explicit types for exported schema constants, and
+  `ReturnType<typeof z.object<...>>` still leaks private Zod internals. A local
+  `PluginSettingsSchema<T>` parse/safeParse contract keeps the public surface documented without
+  naming Zod internals.
+- **Severity:** minor
+- **Action:** expose schema constants as `PluginSettingsSchema<T>`; runtime values remain Zod
+  schemas.
+- **Evidence:** `deno doc --lint src/schema/plugins/mod.ts` passed.
+
+## 2026-06-06 — Config sweep static and cardinality cleanup
+
+- **What:** Slice 18's full sweep surfaced several pre-existing static-gate issues not itemized as
+  standalone config slices: stale workspace test expectations, unversioned `@std/assert` imports in
+  tests, `console.` in public examples, explicit `z.ZodType` annotations in exported domain schema
+  constants, `types.ts` over 500 LOC, and `src/domain` over the 12-child cardinality limit.
+- **Source:** `deno test --allow-all`, `deno lint`, manual F-1/F-14/F-16 scans.
+- **Expected:** Slice 18 would mostly verify already-completed fixes.
+- **Actual:** The sweep required cleanup to make the package satisfy the whole Archetype-1 gate set.
+- **Severity:** minor
+- **Action:** fixed in slice 18 by updating workspace tests/imports/examples, using inferred schema
+  constant types, splitting public config types into section/root modules, and grouping schema files
+  under `src/domain/schemas/`.
+- **Evidence:** Config slice 18 sweep in `worklog.md`.
+
+## 2026-06-06 — Contracts subpath transitive schema type export
+
+- **What:** Slice 21 named `ContractSchema`, `ContractObjectSchema`, and `BaseContractProcedure`
+  as required public exports, but once those types were exported through `./crud` and `./query`,
+  `ContractSchema` publicly referenced `ContractParseResult`.
+- **Source:** `deno doc --lint crud.ts query.ts transform.ts`.
+- **Expected:** The three planned exports were sufficient.
+- **Actual:** The transitive parse-result type also had to be public on the affected subpaths.
+- **Severity:** minor
+- **Action:** export `ContractParseResult` from `crud.ts` and `query.ts` with the schema type
+  contracts.
+- **Evidence:** `deno doc --lint crud.ts query.ts transform.ts` passed.