diff --git a/.llm/runs/docs-1377-content--leaf/audit.md b/.llm/runs/docs-1377-content--leaf/audit.md new file mode 100644 index 0000000000..8a597222f6 --- /dev/null +++ b/.llm/runs/docs-1377-content--leaf/audit.md @@ -0,0 +1,48 @@ +# Full-changeset documentation audit — PR #1541 + +## Verdict + +**PASS after in-place documentation corrections.** + +This was the opposite-family `docs_audit` pass over `cd24e1679..f3893df5b` as one changeset, +followed by a complete rerun with the audit fixes applied and focused reruns after the +orchestrator's xref-registry and plugin/core canonical-location findings. The generator's worklog +and PR claims were treated as input only. Evidence below came from this Codex session's commands +against the checked-out public package, CLI, and documentation wiring surfaces. + +## Gate log + +| Gate | Command(s) | Scope | Result | Findings | Proceeded | +| --- | --- | --- | --- | --- | --- | +| 1. Links | `rtk proxy deno task docs:links` | Full documentation tree with the complete PR-C changeset and audit fixes applied | **PASS** — exit 0; `docs=102 broken-links=0 broken-anchors=0 orphans=0` | No dangling links, anchors, or reported orphans. | Yes — continued to the remaining gates. | +| 2. Site build | `(cd docs/site && rtk proxy deno task build)` | Full Lume site, including all four new core-reference routes and changed navigation copy | **PASS** — exit 0; source format OK; Lume generated 630 files; rendered-output check passed for 224 HTML files with four documented syntax allowances | The recurring warning that `docs/site/deno.json` is outside the root workspace is non-fatal and pre-existing. | Yes — no build fix required. | +| 3. Internal wording | `git diff --unified=0 cd24e1679 -- README.md packages/sdk/README.md docs/site`; changed-line extraction with `sed`; internal-term scan with `rg` | Changed public lines only, including audit corrections | **PASS after fix** — no internal identifier/process leak remains; the sole final lexical hit is public phrase “test harness” | Found `(US-2)` and “tracked separately” in the changed reference index. The whole-site comparison also exposed legacy `US-2`/`US-8` wording on reference claims touched while reconciling Gate 9. | Yes — removed internal story/process wording in place. | +| 4. Versioned specifiers | Changed-line and whole-changed-file `rg` scans for bare `jsr:@netscript/`; `rg 'releaseSpecifier' docs/site/cli-reference.md`; `(cd /tmp && deno info jsr:@netscript/cli@0.0.5)` | All original public files in the PR-C changeset, plus root install instructions | **PASS** — no newly introduced bare pinnable package specifier; site commands concatenate `releaseSpecifier`; root README explicitly requires substituting ``; registry resolution of current `0.0.5` succeeded | The root README is static Markdown, so `` cannot use the site data variable; its substitution instruction and live release/JSR links make the placeholder explicit. | Yes — no specifier correction required; retained the explicit placeholder. | +| 5. Command/API accuracy | `deno run --no-lock --allow-read --allow-run=deno .llm/tmp/1377-doc-surface-audit.ts`; fresh `deno doc --json` for every declared subpath and `deno doc --filter` checks for the described root semantics; live `deno run -A packages/cli/bin/netscript.ts … --help` matrix; `deploy list --json`; router-source inspection; targeted CLI tests (10 passed); SDK query-factory tests (3 passed); `rtk proxy deno task docs:accuracy` | Every subpath/count and root table on the four exhaustive pages; all six newly documented CLI verbs, seven routed deploy families, deploy registry/router intersection, SDK query dialect, root README install target | **PASS after fixes** — exact package results: sagas 19/19 entrypoints and 41/41 root symbols; streams 4/4 and 51/51; triggers 12/12 and 106/106; workers 17/17 and 32/32; zero missing/extra entrypoints or symbols, count mismatches, or kind mismatches. CLI behavior tests: 10/10; SDK query tests: 3/3; docs accuracy PASS. | Found five documentation defects: nonexistent host-level `plugin ai --help`; `deploy list` advertised operations described as callable operations; desktop package target/default and release flags incomplete; jobs/tasks falsely split into handler-only versus entrypoint-only; root `createWorkersRuntime` falsely described as dependency-injected. Re-derived deploy surface as router intersection: Docker/Compose five verbs; five cloud targets three; `emit` advertised but unrouted. | Yes — fixed all five in place, including exact desktop flags/defaults and the root-versus-`/runtime` workers distinction. Source defect `emit` remains out of scope. | +| 6. Template/generated drift | `rtk proxy deno task check:assets-barrel`; immediate `git diff` of generated barrels and `rtk git status --short` | Repo-owned generated asset barrels affected by documentation/README assets | **PASS** — exit 0 and no generated-barrel diff | The gate did not alter any generated assets. A later targeted CLI invocation added one incidental `deno.lock` integrity row. | Yes — removed the incidental lock entry and retained no cache/lock change. | +| 7. Nav/front matter | Front-matter inspection for the four new pages; publishable-page inventory; `_config.ts`/`_data.ts` nav-source inspection; `deno eval` comparison of `docs/site/reference/` directories with exported `ref:` keys; Gates 1–2 rerun after the registry fix | New core pages, folder-derived navigation, xref registry, front matter, and path convention | **PASS after follow-up fix** — all four pages have `layout: layouts/base.vto` and exact package titles; Lume rendered all four; 35 publishable workspace members have pages; all 36 reference directories have exactly 36 registered `ref:` keys, with zero missing or extra entries | The initial audit verified folder-derived nav but missed the separate hand-maintained `REFERENCE_UNITS` registry. The four new `plugin-*-core` pages lacked xref keys. `_data.ts` no longer contains a mirrored executable list; it explicitly delegates `ref:` keys to `_data/xref.ts`. Two comments in `xref.ts` also carried stale counts (`32` and `28`) and one retained false “generated” provenance. | Yes — registered all four missing units, corrected both counts to 36, and documented that nav is independently folder-derived while the xref registry must stay aligned with `docs/site/reference/`. | +| 8. Prose quality | `deno run --no-lock --allow-read docs/site/_plugins/check-source-format.ts .`; heading-level Deno scan; `deno fmt --check README.md packages/sdk/README.md`; `git diff --check cd24e1679`; changed-line filler/callout/command scans; live command checks from Gate 5 | All changed public prose, headings, tables, callouts, and shown commands | **PASS after fixes** — source formatting OK; 45 changed Markdown files, zero heading jumps; both READMEs formatted; diff check clean | The shown `netscript plugin ai --help` command failed because the host pass-through does not own `--help`. Root README still contained separate hardcoded plugin-file/helper totals. Desktop wording omitted explicit-target behavior. | Yes — removed the invalid shown command, removed all hardcoded root-README file/directory/helper totals, qualified host targeting as the default, and added exact release setup flags. | +| 9. Cross-page contradiction | Whole-tree `rg` for generated-reference claims, deploy verb claims, SDK query shapes, scaffold totals, internal identifiers, and obsolete plugin/core convention statements; focused repo search for a reference writer; comparison to live surfaces from Gate 5; `rtk proxy deno task docs:accuracy` | Every changed claim against the rest of the public documentation tree | **PASS after follow-up fixes** — no obsolete “not a separate top-level reference entry,” “single-page internals convention,” or “not part of the public plugin contract” claim remains; docs accuracy exits 0 | The rewritten index said reference pages are hand-written, while many existing public pages still called them generated. A later polish pass found a second contradiction the initial audit missed: the four deployable-plugin pages duplicated their core packages' exhaustive surfaces, and the sagas/streams pages denied those separate core references should exist. Historical `_plan/` files retain their original planning language and are not public documentation. | Yes — selected one publishable package/one canonical reference page, retained focused cross-package examples, replaced four duplicated core tables with links to the canonical `plugin-*-core` pages, recorded the rule and rationale in the index, and retained the saga `spawn(...): never` contract required by the accuracy gate. The `Group F`/`T1` descriptions remain unchanged because they match authoritative published JSDoc and are tracked in #1554. | + +## Fix disposition + +Fixed in place: + +- removed internal `(US-2)` / process wording from the changed reference index; +- corrected the CLI reference for the `plugin ai` pass-through, deploy registry versus routed verbs, + desktop package/release flags and defaults, and five-versus-three routed deploy surface; +- corrected workers builder and runtime-composition claims against `deno doc` and the live types; +- removed all hardcoded file/directory/helper totals from the root README; +- reconciled public “generated reference” wording with the verified hand-maintained Markdown model; +- changed the public Reference-lane subtitle to “Every published symbol”; and +- registered the four new core-reference pages in the hand-maintained `ref:` xref surface, verified + exact 36-directory/36-key parity, and corrected its stale count/provenance comments; +- made each separately published `plugin-*-core` page canonical for its own exports, replacing the + four deployable-plugin pages' duplicated exhaustive tables with links and recording the convention + in the reference index; and +- removed incidental `deno.lock` churn. + +Flagged but not fixed: none. The unrouted adapter `emit` operation remains the separately owned +source defect and was not changed. Historical files under `docs/site/_plan/` are retained as records, +not treated as current public claims. The published-JSDoc terms `Group F` and `T1` remain in the +triggers-core page pending the separately filed source correction #1554. diff --git a/.llm/runs/docs-1377-content--leaf/context-pack.md b/.llm/runs/docs-1377-content--leaf/context-pack.md new file mode 100644 index 0000000000..298390798c --- /dev/null +++ b/.llm/runs/docs-1377-content--leaf/context-pack.md @@ -0,0 +1,85 @@ +# Context pack — docs-1377-content--leaf + +Resumable summary. Read with `supervisor.md`, `worklog.md`, `drift.md`. + +## What this run is + +PR-C of #1377 — the **content** half. Documentation authoring only. The gate half (a +`publish-readiness.ts` reference-page check that currently runs over zero packages, a +command-coverage gate, and the reference path-convention decision) is PR-D and is **out of scope**. + +`Refs #1377`, never `Closes` — the issue's gate acceptance rows are not this PR's to complete. + +## Coordinates + +| Field | Value | +| --- | --- | +| Worktree | `/home/codex/repos/ns006-1377-content` | +| Branch | `docs/1377-reference-ia-readme-truth` | +| Baseline | `cd24e1679` | +| PR | **#1541** (draft) | +| Run dir | `.llm/runs/docs-1377-content--leaf/` | + +Push with an explicit refspec: `git push origin HEAD:refs/heads/docs/1377-reference-ia-readme-truth`. + +## Slices + +| Slice | Commit | State | +| --- | --- | --- | +| S1 four `-core` reference pages + reference index | `e22a2f952` | landed, gated, commented | +| S2 `packages/sdk/README.md` query dialect | `68cf6f2e5` | landed, gated, commented | +| S3 root `README.md` scaffold count + specifier | `617b74884` | landed, gated, commented | +| S4 CLI reference — six verbs + two wrong claims | `f3893df5b` | landed, gated, commented | +| Audit corrections | `077a75716`, `13b6d118a`, `ef2b05670` | landed, gated, commented | +| Plugin/core canonical-location follow-up | this commit | four deployable-plugin pages point to canonical `plugin-*-core` pages; gated | + +## Measurements that must not be re-derived + +- **Alias row of #1377 is already satisfied.** `@contracts`, `@/lib/`, `api-clients` are at zero + under `docs/site/`, and `check-accuracy-and-discoverability.ts:57-58` actively forbids them. Tick + on measurement; do not "fix". +- **Reference pages: 35 effective-publish members, 0 missing** after S1 (was 4 missing). +- **Path convention:** 31 name-exact, 4 exceptions — the *deployable* plugins drop `plugin-`. +- **No generator writes into `docs/site/reference/`.** Pages are hand-written. +- **Reference xref registry:** navigation is folder-derived, but `_data/xref.ts` separately registers + all 36 reference directories. The audit follow-up restored exact 36-directory/36-key parity and + added the four new `plugin-*-core` keys. +- **Canonical reference location:** each separately published `plugin-*-core` page owns its + exhaustive exported-API documentation. The corresponding deployable-plugin page owns manifest and + integration coverage, links to the core page, and may retain focused cross-package examples. This + removes the prior duplicated tables and obsolete single-page-internals claims. +- **Deploy target operations, measured from source:** + + | Target(s) | Class | Operations | + | --- | --- | --- | + | `compose`, `docker` | `AspireComposeDeployTarget:64` | plan · emit · up · down · status · logs (**6**) | + | `kubernetes`, `azure-aca`, `azure-app-service`, `azure-aks`, `cloud-run` | `AspireCloudDeployTarget:125` | plan · emit · up · down (**4**) | + | `deno-deploy` | `deno-deploy-target.ts:57` | plan · up · down · status · logs (5) | + | `windows-service`, `linux-service` | `service-deploy-target.ts:21` | plan · emit · up · down · status · logs (6), +`rollback` with an `ActivationPort`, +`secrets` with a `SecretsStorePort` | + + Verb subcommands are generated from the target's `operations` + (`target-deploy-command.ts:58-66`), so both wrong claims are decidable from these arrays. +- **Six verbs confirmed undocumented** in `docs/site/`: `agent drift`, `deploy desktop`, + `deploy package-cli`, `deploy list`, `config list` → zero occurrences; `plugin ai` → one, at + `reference/plugin-ai/index.md:311`, absent from both command references. + +## Hard boundaries + +- **Do not open** the nine `docs/site` Tier-1 files PR-B is editing concurrently: `quickstart.vto`, + `index.vto`, `services-sdk/sdk.md`, `services-sdk/how-to/add-a-service.md`, and + `web-layer/{query,examples,interactive,form,query-bridge}.md`. +- No gate code, no checkers, no negative tests — PR-D. +- No `packages/**` or `plugins/**` change except `README.md`. +- Do not mark ready for review. Do not merge. A separate opposite-family Codex audit runs after this, + then a Fable prose polish. + +## Gate commands for this run + +```text +deno task docs:links +deno task docs:accuracy +deno task quality:gate +deno task publish:dry-run +cd docs/site && deno run --no-lock --allow-read _plugins/check-source-format.ts . +deno fmt # docs/site/**/*.md is excluded — see drift DR-4 +``` diff --git a/.llm/runs/docs-1377-content--leaf/drift.md b/.llm/runs/docs-1377-content--leaf/drift.md new file mode 100644 index 0000000000..2fc5e37ac5 --- /dev/null +++ b/.llm/runs/docs-1377-content--leaf/drift.md @@ -0,0 +1,124 @@ +# Drift — docs-1377-content--leaf (PR-C of #1377) + +Append-only. Everything found and **not** fixed in this slice, with why. + +## DR-1 — `reference/index.md` claimed pages are generated; nothing generates them + +**Severity:** significant. **Status:** fixed in this PR (in scope per the brief). + +`docs/site/reference/index.md:6-7` asserted the reference pages "are generated from the source code +with `deno doc`, so they always describe the published surface". No script writes into +`docs/site/reference/`; every tooling reference to that path reads or checks. Evidence in +`worklog.md` § D-1. Corrected. + +## DR-2 — The same false generation claim survives inside two existing pages + +**Severity:** minor. **Status:** NOT fixed — out of this slice's footprint. + +- `docs/site/reference/plugin-ai-core/index.md:10-11` — "This page is generated from the package's + public surface with `deno doc` (US-2)." +- `docs/site/reference/plugin-auth-core/index.md:9-10` — "This page is generated from the package's + public surface with `deno doc`." + +Both are the per-page form of DR-1 and are equally untrue. The four pages added here deliberately say +"written against the package's published exports and its `deno doc` surface" instead. Left alone +because editing pages this slice does not otherwise touch widens the diff into files a sibling slice +or PR-D may reach; a one-line correction each is enough whenever someone owns them. + +## DR-3 — `docs:accuracy` hardcodes a short reference path, and #1377 does not name it + +**Severity:** significant for PR-D. **Status:** NOT fixed — PR-D owns the decision. + +`.llm/tools/docs/check-accuracy-and-discoverability.ts:126` reads +`'docs/site/reference/sagas/index.md'` and `:29` reads `'docs/site/reference/sdk/index.md'`. #1377 +names only `.llm/tools/release/publish-readiness.ts` as the gate hardcoding a path. If the +path-convention decision moves the IA to the gate's name-exact rule, this file breaks too, along with +`publish-readiness.ts:302` and every inbound link. Carried forward from the orchestrator's research +(C-3) and re-confirmed by reading the file in this worktree. + +## DR-4 — `deno fmt` covers READMEs by explicit path but never `docs/site/**/*.md` + +**Severity:** minor, process-relevant. **Status:** NOT a defect to fix here. + +**Corrected after S2/S3.** The first recording of this entry (during S1) over-generalized from one +observation; the measured behaviour is: + +- `docs/site/**/*.md` — `deno fmt ` exits **1** with `No target files found`, because + `docs/site/deno.json` `fmt.exclude` lists `**/*.md` and an **exclude beats an explicit path + argument**. `docs/site/_plugins/check-source-format.ts` is the real formatting authority here. +- `README.md` files — `deno fmt ` **does** format them (exit 0). The root `fmt.include` is + `packages/**` / `plugins/**` TypeScript only, so a bare `deno fmt` never *discovers* a README, but + an explicit path argument is honoured because nothing excludes it. + +Consequence: READMEs are formattable but not covered by any discovery-based gate, so their formatting +is enforced by nobody. Both READMEs touched by this PR were formatted explicitly and re-verified with +`--check`. Worth deciding deliberately rather than discovering again — flagged for the orchestrator, +not changed here (fmt config is not this slice's scope). + +## DR-6 — `docs:readme:check` is red on `main` + +**Severity:** minor. **Status:** NOT fixed — pre-existing and out of scope (#767). + +`deno task docs:readme:check` exits **1** at the baseline commit and still does: + +```text +A2 README standard FAIL - 1/36 non-conformant: + packages/bench/README.md + - [install-section] missing '## Install' section +``` + +`packages/bench` is `"publish": false`, so this is not a publish blocker. README-standard +conformance is #767's territory and is explicitly out of this slice's scope; recorded rather than +swept in so the audit does not read it as regression from this PR. + +## DR-7 — `emit` is implemented on three adapters but unreachable from the CLI + +**Severity:** significant. **Status:** NOT fixed — source, not docs. Found while verifying #1377's +deploy claims. + +`ROUTED_OPERATIONS` (`packages/cli/src/public/features/deploy/target/target-deploy-command.ts:15-23`) +is `['plan', 'up', 'down', 'status', 'logs', 'rollback', 'secrets']` — **no `emit`**. The router +generates a subcommand only for an operation in that list that the adapter also advertises (`:59`). + +But `emit` **is** advertised and implemented: + +- `AspireComposeDeployTarget` — advertises it (`:64-71`), implements it (`:96`); +- `AspireCloudDeployTarget` — advertises it (`:125`), implements it (`:162`); +- `ServiceDeployTarget` — advertises it (`SERVICE_DEPLOY_OPERATIONS`, `:21-29`). + +It even has a router description (`OPERATION_DESCRIPTIONS.emit = 'Emit deployment artifacts'`, `:28`). +The only other `'emit'` under `packages/cli/src/public/` is in a test. So every adapter's `emit` +handler is dead code from the CLI's point of view, and `deploy list` reports an operation the user +cannot invoke — the same class of honesty defect that `service-deploy-target.ts:14-20` explicitly +guards against for `rollback`/`secrets` ("LD-4: omit rather than silent no-op"), applied in reverse. + +Either `emit` belongs in `ROUTED_OPERATIONS` or it should stop being advertised. Deciding that is a +source change and out of this slice's scope. The documentation this PR writes describes the +**reachable** surface and does not mention `emit` as a verb. + +## DR-8 — The research's C-2 correction was itself inaccurate + +**Severity:** significant, process. **Status:** resolved by measurement; recorded so the audit can +check the reasoning rather than the conclusion. + +The orchestrator's research told this slice that `reference/cli/commands.md:209` ("the same +three-verb lifecycle — `plan`, `up`, `down`") was "contradicted by the same array" and must be fixed, +and that the docker/compose surface "is six" against #1377's "five". + +Measured (see `worklog.md` § D-5): the CLI verb surface is the **intersection** of the adapter's +advertised `operations` with the router's `ROUTED_OPERATIONS`, and `emit` is absent from the latter. +So the cloud targets expose exactly three verbs — `:209` was **correct**, and applying the instructed +fix would have replaced a true statement with a false one. Docker/compose expose five, matching +#1377's original wording; the research's "six" counts advertised operations, not commands. + +Only the `cli-reference.md:246-249` "not wired — they only print help" claim was actually false, and +that one is fixed. `:209`'s three-verb statement is preserved verbatim inside a rewritten section. + +## DR-5 — Maintainer CLI reports `version('1.0.0')` + +**Severity:** significant. **Status:** NOT fixed — source, not docs. + +`.../maintainer-command-tree.ts:32` sets `.version('1.0.0')` while the public tree uses +`CLI_PACKAGE_VERSION`. Carried in from the orchestrator's research (item 9). The brief explicitly +routes this here rather than to a fix: it is framework source, and this run authors documentation +only. Needs a WSL Codex slice. diff --git a/.llm/runs/docs-1377-content--leaf/supervisor.md b/.llm/runs/docs-1377-content--leaf/supervisor.md new file mode 100644 index 0000000000..78ca9c4bcf --- /dev/null +++ b/.llm/runs/docs-1377-content--leaf/supervisor.md @@ -0,0 +1,49 @@ +# Supervisor — docs-1377-content--leaf + +Leaf documentation-authoring run for **PR-C of #1377** (content half) in the NetScript 0.0.6 +documentation lane. Authored under the CLAUDE.md **documentation-authoring exception (2026-06-18)**: +Markdown/prose only, no framework source, validated afterwards by a separate opposite-family session. + +## Identity + +| Field | Value | +| --- | --- | +| Run id | `docs-1377-content--leaf` | +| Role | Leaf implementation agent (generator only — does not self-certify) | +| Model / lane | Claude Opus 5, Tier-B documentation authoring | +| Host | WSL2 Linux, `codex@` | +| Worktree | `/home/codex/repos/ns006-1377-content` | +| Branch | `docs/1377-reference-ia-readme-truth` (no upstream at dispatch, by design) | +| Baseline | `cd24e1679f8732837883aaa84ab16aa61d733714` (= `origin/main` at dispatch) | +| Control worktree (read-only to this run) | `/home/codex/repos/netscript-006-docs` | +| Brief | `.llm/runs/release-0.0.6-docs--orchestration/slices/1377-content/implement.md` (control worktree) | +| Research input | `.llm/runs/release-0.0.6-docs--orchestration/slices/1377-content/research.md` (control worktree) | +| Issue | #1377 — **`Refs`, not `Closes`**; the gate half is PR-D | + +## Overlay and archetype + +- Scope overlay: `SCOPE-docs.md`. No archetype selected — this run authors Markdown only and changes + no `packages/**` or `plugins/**` source. The only files touched under `packages/**` are + `README.md` files, which the brief explicitly permits. +- PLAN-EVAL: **N/A**. The plan is the orchestrator's brief; the decision-heavy parts (path + convention, gate shape) are explicitly withheld from this slice and belong to PR-D. Recorded here + before implementation per the harness checklist. + +## Lanes + +| Lane | Session | Role | +| --- | --- | --- | +| Orchestrator | 0.0.6 docs orchestration supervisor | brief, merge authority, pre-merge `packages/**` audit | +| Generator (this run) | Claude Opus 5 | authoring, gates, draft PR, per-slice comments | +| Audit | separate opposite-family Codex session | full-changeset audit after this run | +| Prose polish | Fable session | after the audit | + +No lane self-certifies. This run stops at **draft** — it does not mark ready for review and does not +merge. + +## Sibling-slice conflict boundary + +PR-B is concurrently editing nine `docs/site` Tier-1 files +(`quickstart.vto`, `index.vto`, `services-sdk/sdk.md`, `services-sdk/how-to/add-a-service.md`, +`web-layer/{query,examples,interactive,form,query-bridge}.md`). This run does not open any of them. +Anything found there goes to `drift.md`. diff --git a/.llm/runs/docs-1377-content--leaf/worklog.md b/.llm/runs/docs-1377-content--leaf/worklog.md new file mode 100644 index 0000000000..6313533f9c --- /dev/null +++ b/.llm/runs/docs-1377-content--leaf/worklog.md @@ -0,0 +1,306 @@ +# Worklog — docs-1377-content--leaf (PR-C of #1377) + +## Design + +Four decisions were made before authoring; each is recorded with the measurement that settled it. + +### D-1 — The reference pages are hand-written; the index's generator claim was false + +The brief required resolving this before authoring. Searched the repository for anything that +*writes* into `docs/site/reference/`: + +```text +grep -rn "docs/site/reference" --include=*.ts --include=*.js --include=*.json --include=*.mjs . +``` + +Every hit is a **reader**, not a writer: + +- `.llm/tools/docs/check-exports-drift.ts` — checks 8 hardcoded pages against declared entrypoints. +- `.llm/tools/docs/check-accuracy-and-discoverability.ts:29,:126` — reads `reference/sdk/index.md` + and `reference/sagas/index.md`. +- `.llm/tools/release/publish-readiness.ts:302` — asserts a page path exists. +- `packages/mcp/tests/registry_test.ts:86,:121` — reads `reference/mcp/index.md`. +- `.llm/runs/beta5-impl--supervisor/slices/479-ai-docs/workflow.js:136-138` — a **past authoring + run** that hand-wrote `reference/ai/`, `reference/plugin-ai/`, and `reference/plugin-ai-core/`. + This is positive evidence of the hand-written route, not a generator. + +The only `deno doc` consumers in tooling are `.llm/tools/run-deno-doc-lint.ts` (a `deno doc --lint` +runner) and `.llm/tools/release/surface-diff.ts` (`deno doc --json` surface snapshots). Neither emits +Markdown. + +**Verdict: no generator exists.** `docs/site/reference/index.md:6-7` claimed the pages "are generated +from the source code with `deno doc`, so they always describe the published surface". Both halves +were false — nothing generates them, and therefore nothing guarantees they stay current. Correcting +that sentence was in scope per the brief; adding four hand-written pages beneath an unretracted +generation claim was not an option. + +### D-2 — Page depth and structure modelled on the existing `-core` pages + +`reference/plugin-auth-core/index.md` (88 lines, grouped symbol tables) and +`reference/plugin-ai-core/index.md` (266 lines, entrypoint table plus per-surface tables) are the two +existing pages for this archetype. The four new pages use both patterns: an **Entrypoints** table +with a measured export count per subpath, then grouped root-surface symbol tables, then the +behavioural notes that a symbol table alone cannot carry (ack-then-process ordering, replay-commit +semantics, typestate gating, synchronous-handler discipline). + +Every symbol row is derived from `deno doc --json` output for the package's **declared** exports — +not from source reads. Root-surface tables are exhaustive against that output; each page's grouped +tables sum to the count `deno doc` reports: + +| Package | Root exports | Rows on page | +| --- | --- | --- | +| `@netscript/plugin-sagas-core` | 41 | 41 | +| `@netscript/plugin-streams-core` | 51 | 51 | +| `@netscript/plugin-triggers-core` | 106 | 106 | +| `@netscript/plugin-workers-core` | 32 | 32 | + +Subpath entrypoints are described by their module doc plus their measured export names, so no page +names a symbol the package does not export. + +### D-3 — Path convention is described, not legislated + +Measured over the whole workspace: 35 effective-publish members, 31 pages at the name-exact segment +(`@netscript/` → `/reference//`), 4 exceptions where the **deployable** plugins drop the +`plugin-` prefix (`@netscript/plugin-sagas` → `/reference/sagas/`, and the same for streams, +triggers, workers). Their `-core` counterparts are name-exact, which is what makes the IA internally +inconsistent rather than uniformly divergent. + +The index now records exactly that, and states explicitly that it is a description of today's site, +not a rule to follow when the two forms disagree — reconciling them is PR-D's decision. + +### D-4 — `deno fmt` governs the READMEs but not `docs/site/**/*.md` + +The brief's formatting gate is `deno fmt `. Measured, it splits in two: + +- **`docs/site/**/*.md`** — exits **1** with `error: No target files found`, because + `docs/site/deno.json` `fmt.exclude` lists `**/*.md`, `**/*.mdx`, `**/*.vto`, and an exclude beats + an explicit path argument. The real formatting gate here is + `docs/site/_plugins/check-source-format.ts` (`deno task check:source-format` in that directory), + which this run uses in its place. +- **`README.md` files** — exit **0** and are reformatted. The root `fmt.include` is + `packages/**/*.{ts,tsx}` and `plugins/**/*.{ts,tsx}`, so a bare `deno fmt` never discovers a + README, but an explicit path is honoured because nothing excludes it. + +The S1 record of this decision claimed `deno fmt` covered neither, generalizing from the `docs/site` +observation before a README had been touched. Corrected here and in `drift.md` DR-4 during S2. The +rewrap hazard the brief warns about is therefore **real for the READMEs**: both were reformatted by +`deno fmt`, and the edited passages were re-read and grepped afterwards to confirm the edits survived +(they did). + +## Gate baselines (before any edit, at `cd24e1679`) + +| Gate | Exit | Result | +| --- | --- | --- | +| `deno task docs:links` | 0 | `docs=102 broken-links=0 broken-anchors=0 orphans=0` | +| `deno task docs:accuracy` | 0 | `PASS (… 192 published source pages …)` | + +Reference-page count before: **35 effective-publish members, 4 missing pages** +(`plugin-{sagas,streams,triggers,workers}-core`). + +## Slice 1 — four reference pages + reference index + +Files: + +- `docs/site/reference/plugin-sagas-core/index.md` (new) +- `docs/site/reference/plugin-streams-core/index.md` (new) +- `docs/site/reference/plugin-triggers-core/index.md` (new) +- `docs/site/reference/plugin-workers-core/index.md` (new) +- `docs/site/reference/index.md` (generator claim corrected; path convention recorded) + +| Gate | Command | Exit | Result | +| --- | --- | --- | --- | +| Internal doc links | `deno task docs:links` | 0 | `docs=102 broken-links=0 broken-anchors=0 orphans=0` | +| Docs accuracy | `deno task docs:accuracy` | 0 | `PASS (… 196 published source pages …)` — up 4, one per new page | +| Docs source format | `docs/site/_plugins/check-source-format.ts .` | 0 | `Docs source format: OK` | +| `deno fmt` (touched files) | `deno fmt <5 files>` | 1 | `No target files found` — see D-4; excluded for `docs/site` Markdown | +| Reference-page existence | own count | — | before 31/35, after **35/35**; 0 missing | + +## Slice 2 — `packages/sdk/README.md` (the JSR landing page) + +`jsr-package-settings.json:6` sets `readmeSource: "readme"`, so this file is the consumer-facing JSR +page. + +Two measurements that shaped the edit: + +1. **`createQueryFactory` is a real export**, not a wrong symbol name + (`packages/sdk/src/query/query-factory.ts:41`). It is the single-resource form; + `createQueryFactories` (`:192`) is the map form. The README's defect was emphasis, not naming. +2. **`createServiceQueryUtils` cannot simply be demoted out of the page.** `defineServices` builds + its returned `queryUtils.*` from it (`packages/sdk/src/presets/define-services.ts:9,:120`), so the + README's own Quick example already exercises both dialects. Removing the symbol would have made + the page describe an API the package does not have. + +Result: the golden path leads, and a new "Two query dialects" section frames `createServiceQueryUtils` +as the narrower helper — `queryOptions({ input })` versus `queryOptions(input)`, no server KV tier — +matching `docs/site/reference/sdk/index.md:111` rather than inventing a second framing. Call shapes +verified against source (`query-factory.ts:140-146`), not copied from the reference page. + +The `docs:accuracy` single-page exception for `createServiceQueryUtils` +(`check-accuracy-and-discoverability.ts:63-74`) walks `docs/site` only, so a mention in +`packages/sdk/README.md` does not contend with it — confirmed by the gate still passing. + +## Slice 3 — root `README.md` + +- Removed "The scaffold reports **183 files, 44 directories**", which contradicted + `quickstart.vto:51` ("treat the printed result—not a static number in this guide—as the + authority"). Replaced with a statement that the scaffold prints its own totals and why they vary. + `README.md:78-80` already described `--dry-run` as reporting the counts it would create, so the two + statements now agree. +- The install line's `jsr:@netscript/cli@` is left as a placeholder with an explicit + substitution instruction and a pointer to the latest release / JSR page, plus the note that bare + `jsr:@netscript/*` specifiers do not resolve on the pre-release line. Pinning it to `0.0.5` would + have reproduced the hardcoded-count defect one release later; the site can derive its specifier + (`_data.ts:30-33`) and a static README cannot. +- **Not changed:** `:148` "29 packages and 6 first-party plugins". Re-measured — 35 effective-publish + members, 6 of them under `plugins/`. The claim is correct. + +### Gates for slices 2 and 3 + +| Gate | Command | Exit | Result | +| --- | --- | --- | --- | +| Code quality | `deno task quality:gate` | 0 | pass; doctrine readiness `FAIL=0` for every package (WARN/INFO pre-existing) | +| Publish dry-run | `deno task publish:dry-run` | 0 | `Success Dry run complete` | +| Markdown format | `deno fmt README.md packages/sdk/README.md` | 0 | reformatted, `--check` clean, edits re-verified after rewrap | +| Internal doc links | `deno task docs:links` | 0 | `broken-links=0 broken-anchors=0 orphans=0` | +| Docs accuracy | `deno task docs:accuracy` | 0 | `PASS` | + +**#1417 side effect did not occur.** `git status --short` immediately after `publish:dry-run` was +empty — no catalog-backed manifest rewritten, nothing to revert, `deno.lock` untouched. + +## Slice 4 — CLI reference: six verbs and the deploy verb surface + +### D-5 — The deploy verb counts, measured + +The brief said to verify the operations array myself and not to copy #1377's wording. Doing so +produced a result that contradicts **the orchestrator's own research correction**, so it is set out +in full. + +There are **two** arrays, and only their intersection reaches the CLI: + +1. Each adapter advertises `operations`: + + | Target(s) | Source | Advertised | + | --- | --- | --- | + | `compose`, `docker` | `aspire-compose-deploy-target.ts:64-71` | plan · emit · up · down · status · logs | + | `kubernetes`, `azure-aca`, `azure-app-service`, `azure-aks`, `cloud-run` | `aspire-cloud-deploy-target.ts:125` | plan · emit · up · down | + | `deno-deploy` | `deno-deploy-target.ts:57-63` | plan · up · down · status · logs | + | `windows-service`, `linux-service` | `service-deploy-target.ts:21-29` | plan · emit · up · down · status · logs (+`rollback` with an `ActivationPort`, +`secrets` with a `SecretsStorePort`) | + +2. The router walks a **fixed candidate list** and skips anything the adapter does not advertise + (`target-deploy-command.ts:15-23`, gate at `:59`): + + ```ts + const ROUTED_OPERATIONS: readonly DeployOperation[] = [ + 'plan', 'up', 'down', 'status', 'logs', 'rollback', 'secrets', + ]; + ``` + + **`emit` is not in that list.** It has an entry in `OPERATION_DESCRIPTIONS` (`:28`) and is + implemented on the compose, cloud, and service adapters, but no public CLI path exposes it — the + only other `'emit'` occurrence under `packages/cli/src/public/` is in a test. + +So the CLI verb surface is the intersection: + +| Group | CLI verbs | Count | +| --- | --- | --- | +| `deploy docker`, `deploy compose` | plan · up · down · status · logs | **5** | +| `deploy kubernetes`, `azure-aca`, `azure-app-service`, `azure-aks`, `cloud-run` | plan · up · down | **3** | + +Consequences for the two claims this slice was sent to fix: + +- **`cli-reference.md:246-249` — wrong, corrected.** "`deploy docker` and `deploy compose` … are not + wired — they only print help" is false: each exposes five working verbs routed to + `AspireComposeDeployTarget`, whose `plan`/`emit`/`up`/`down`/`status`/`logs` methods are all + implemented (`:91`–`:152`). The bare group does print help, but so does every command group in the + CLI, including `deploy` itself — that is the default action, not evidence of a stub. +- **`reference/cli/commands.md:209` — CORRECT; deliberately not "fixed".** "the same three-verb + lifecycle — `plan`, `up`, `down`" describes the five cloud targets, and three is exactly what they + expose, because their advertised `emit` is not routed. The orchestrator's research (C-2) called + this claim contradicted and instructed fixing it; measuring shows the claim was right and the + correction would have introduced the error. The section was rewritten for coverage — it now names + `docker`/`compose` and their two extra verbs, and explains *why* the verb lists differ — but the + three-verb statement for the cloud targets was preserved because it is true. +- **#1377's "five-verb surface" for docker/compose — also correct**, at the CLI level. The research's + "it is six" counts the adapter's advertised operations, which is a different (and unreachable-by-one) + number. Both were describing real arrays; neither said which one the user types. + +### Content added + +`docs/site/reference/cli/commands.md` (the exhaustive page) gains all six previously undocumented +verbs, `docs/site/cli-reference.md` (the curated page) gains the five that fit its narrative: + +| Verb | Curated page | Exhaustive page | +| --- | --- | --- | +| `agent drift` (+ `drift record`) | yes | yes, with the 15-minute receipt gate | +| `plugin ai` | yes | yes, framed as a pass-through | +| `deploy list` | yes | yes, with the ten default targets | +| `deploy desktop` (+ `package`, `release`) | yes | yes | +| `deploy package-cli` | yes | yes, with all four flags and defaults | +| `config list` | — (no config section on the curated page) | yes, incl. the `(not read by the generator)` marker | + +Two behaviours were read from source rather than paraphrased from a description string, because the +description alone would have been misleading: + +- `agent drift record` refuses unless a diagnostic receipt for `--resource` exists, exited `0`, and + is under `DIAGNOSTIC_RECEIPT_TTL_MS` = **15 minutes** (`record-drift-flow.ts:5,:31-42`). The same + gate backs the MCP `record_drift` tool. +- `plugin ai` uses `.useRawArgs()`, strips only `--project-root`, and forwards everything else to the + installed `@netscript/plugin-ai` CLI in a child `deno run` (`ai-plugin-command.ts:49-68,:92-113`). + Its verbs therefore belong to that plugin's release, not to this reference — documenting a verb + list here would go stale on the plugin's schedule, not NetScript's. + +### Gates for slice 4 + +| Gate | Command | Exit | Result | +| --- | --- | --- | --- | +| Internal doc links | `deno task docs:links` | 0 | `broken-links=0 broken-anchors=0 orphans=0` | +| Docs accuracy | `deno task docs:accuracy` | 0 | `PASS` | +| Docs source format | `docs/site/_plugins/check-source-format.ts .` | 0 | `Docs source format: OK` | +| Six-verb coverage | own grep over `docs/site/` | — | all six present in `reference/cli/commands.md`; five also on `cli-reference.md` | +| Stale-claim removal | own grep | — | `not wired` / `only print help` gone from `docs/site/` | + +## Opposite-family audit follow-up — xref wiring + +The orchestrator found that Gate 7 had verified folder-derived navigation but not the independent +hand-maintained `REFERENCE_UNITS` registry in `docs/site/_data/xref.ts`. The four new core-reference +directories were absent, so their `ref:` shortcuts could not resolve. The same file also contained +stale `32` and `28 generated` count/provenance comments. + +`_data.ts` has no mirrored executable reference-unit list: its source comment explicitly says the +nav is folder-derived and the `ref:` keys live in `_data/xref.ts`. The fix therefore keeps behavior +unchanged, adds the four missing registry entries, and documents the real two-surface relationship. + +| Gate | Command | Exit | Result | +| --- | --- | --- | --- | +| Xref parity | `deno eval` import of `xref` plus directory/key set comparison | 0 | 36 directories, 36 registered `ref:` units, zero missing/extra; all four new URLs exact | +| Internal doc links | `deno task docs:links` | 0 | `docs=102 broken-links=0 broken-anchors=0 orphans=0` | +| Site build | `cd docs/site && deno task build` | 0 | source format OK; 630 files generated; rendered output OK for 224 HTML files | + +## Opposite-family audit follow-up — canonical plugin/core references + +The polish lane found a Gate 9 contradiction the first audit did not catch. The four new +`plugin-*-core` pages were intended to satisfy the one-page-per-publishable-package acceptance row, +but the deployable sagas and streams pages still denied that such top-level references should exist. +All four deployable-plugin pages also repeated their core package's exhaustive API documentation. + +Decision: **the separately published core package's page is canonical for its exported surface**. +This is the arrangement most consistent with #1377: one publishable workspace member has one +canonical reference page, so an API claim has one place to remain accurate. The four deployable +plugin pages retain their manifest/integration coverage and focused examples, but their exhaustive +core sections are now short pointers to `plugin-{sagas,streams,triggers,workers}-core`. The reference +index records this one-package/one-canonical-page rule and its rationale. + +`docs:accuracy` initially exposed one legacy checker dependency on the sagas page's exact +`options?: SpawnOptions): never` marker. The page therefore retains a focused explanation of the +unsupported `spawn(...)` contract while leaving the exhaustive core table canonical on +`plugin-sagas-core`. No gate code was changed. + +The `Group F` and `T1` descriptions in `plugin-triggers-core` were deliberately left unchanged: +they match `deno doc` and the published source JSDoc. Their source-level cleanup is tracked in #1554. + +| Gate | Command | Exit | Result | +| --- | --- | --- | --- | +| Internal doc links | `rtk proxy deno task docs:links` | 0 | `docs=102 broken-links=0 broken-anchors=0 orphans=0` | +| Docs accuracy | `rtk proxy deno task docs:accuracy` | 0 | PASS; 196 published source pages, spawn contract, preferred paths, and CLI mutation families checked | +| Obsolete convention scan | `rtk grep -n -E 'not a separate top-level reference entry\|single-page internals convention\|not part of the public plugin contract' docs/site/reference/*/index.md` | 1 | Expected no-match result; all three contradictory statements are absent | +| Core-page preservation | `rtk git diff -- docs/site/reference/plugin-{sagas,streams,triggers,workers}-core/index.md` | 0 | No diff; exhaustive canonical pages and `Group F`/`T1` descriptions untouched | diff --git a/README.md b/README.md index b158fc05af..2c7a50bfde 100644 --- a/README.md +++ b/README.md @@ -39,8 +39,14 @@ deno install --global --allow-all --name netscript jsr:@netscript/cli@ netscript init my-app --db postgres --service --yes ``` -The scaffold reports **183 files, 44 directories** and prints your numbered next steps — follow -them: +Replace `` with the current release — the +[latest tag](https://github.com/rickylabs/netscript/releases/latest), or the version shown on +[jsr.io/@netscript/cli](https://jsr.io/@netscript/cli). Bare `jsr:@netscript/*` specifiers do not +resolve on the pre-release line, so the pin is required rather than cosmetic. + +The scaffold reports its own file and directory totals — they vary with the database, service, +editor, and agent-tooling options you chose, so the printed output is the authority — and ends with +your numbered next steps. Follow them: ```bash # 3. Boot the whole stack: Postgres, cache, and every service come up together @@ -61,7 +67,8 @@ netscript db seed ``` The payoff: the Aspire dashboard shows every resource, trace, and log in one place, and your typed -service answers on its health probe (replace `` with the port assigned to your service in the scaffold console output or Aspire dashboard): +service answers on its health probe (replace `` with the port assigned to your service in the +scaffold console output or Aspire dashboard): ```bash curl http://localhost:/health @@ -121,13 +128,11 @@ gets there through the plugin system. A plugin is, at its core, a manifest: plai declaring what it contributes, inspected by hosts without executing plugin code. One manifest can contribute across **every layer** — CLI verbs, scaffolded code, runtime services, storage, stream topics, telemetry, Aspire resources — and the host materializes whatever it declares. One command, -four plugin files scaffolded and twelve Aspire helpers regenerated: +and every scaffolded plugin file and regenerated Aspire helper is itemized in its output: ```bash netscript plugin install worker --name workers # Installed worker plugin "workers" on port 49152. (Note: your scaffold's port will differ) -# Created 4 plugin files. -# Regenerated 12 Aspire helper files. ``` The same mechanism that ships the six first-party plugins below is how a team extends the framework diff --git a/docs/site/_components/nextPrev.vto b/docs/site/_components/nextPrev.vto index 483888b98f..ef347ac653 100644 --- a/docs/site/_components/nextPrev.vto +++ b/docs/site/_components/nextPrev.vto @@ -2,7 +2,7 @@ Two sources, front matter first: 1. Pages may set `prev`/`next` front-matter vars ({ label, href }) — the tutorial tracks keep per-chapter editorial control this way. - 2. Reference pages (32 generated units — unmaintainable by hand) auto-derive + 2. Reference pages auto-derive neighbours from the nav tree via nav.nextPage/previousPage(url, query, sort) — the verified v2.5.4 signature has NO basePath argument; the `url^=/reference/` query term scopes the walk to the reference lane. diff --git a/docs/site/_data.ts b/docs/site/_data.ts index 0ae52ac297..f9deecbab4 100644 --- a/docs/site/_data.ts +++ b/docs/site/_data.ts @@ -94,7 +94,7 @@ export const navLanes: NavLane[] = [ }, { label: "Reference", - subtitle: "Every symbol, generated", + subtitle: "Every published symbol", kind: "menu", roots: ["/reference/"], expandRoot: true, diff --git a/docs/site/_data/xref.ts b/docs/site/_data/xref.ts index 1bd93869aa..6c662a2c92 100644 --- a/docs/site/_data/xref.ts +++ b/docs/site/_data/xref.ts @@ -11,7 +11,7 @@ * tut: tutorial chapter/track (tut:first-workspace) * explain: explanation essay (explain:architecture) * concept: concept / mental-model page - * ref: generated reference unit (ref:sagas -> /reference/sagas/) + * ref: reference unit (ref:sagas -> /reference/sagas/) * and sub-paths (ref:sagas/presets -> /reference/sagas/presets/) * cli: CLI reference (cli:reference) * glossary: glossary (glossary: or glossary:) @@ -32,7 +32,11 @@ export interface XrefTarget { label: string; } -/** The 32 generated reference units (mirrors `referenceUnits` in `_data.ts`). */ +/** + * The 36 hand-maintained reference xref units. Navigation is independently + * folder-derived in `_data.ts`, so keep this registry aligned with the + * directories under `docs/site/reference/`. + */ const REFERENCE_UNITS = [ "ai", "auth", @@ -55,6 +59,10 @@ const REFERENCE_UNITS = [ "plugin-ai-core", "plugin-auth", "plugin-auth-core", + "plugin-sagas-core", + "plugin-streams-core", + "plugin-triggers-core", + "plugin-workers-core", "prisma-adapter-mysql", "queue", "runtime-config", @@ -198,7 +206,7 @@ export const xref: Record = { "cli:reference": { href: "/cli-reference/", label: "CLI reference" }, "glossary:": { href: "/glossary/", label: "Glossary" }, - // ─── Reference index + the 28 generated units (ref:) ─────────────────────── + // ─── Reference index + the 36 registered units (ref:) ────────────────────── "ref:index": { href: "/reference/", label: "Reference index" }, ...refEntries(), }; diff --git a/docs/site/ai/chat-ui.md b/docs/site/ai/chat-ui.md index 8eec14582b..103995007c 100644 --- a/docs/site/ai/chat-ui.md +++ b/docs/site/ai/chat-ui.md @@ -127,7 +127,7 @@ package boundary to work around. {{ comp.featureGrid({ items: [ { title: "Look up — @netscript/fresh-ui", - body: "The generated reference for the fresh-ui package, including the copy-registry manifest surface.", + body: "The API reference for the fresh-ui package, including the copy-registry manifest surface.", href: "/reference/fresh-ui/", icon: "≡" }, diff --git a/docs/site/ai/durable-chat.md b/docs/site/ai/durable-chat.md index bb859650d2..9eaa9f14c8 100644 --- a/docs/site/ai/durable-chat.md +++ b/docs/site/ai/durable-chat.md @@ -228,7 +228,7 @@ real today. Do not build on createNetScriptMcpSandbox yet. ## Reference -This page orients; the generated reference enumerates every exported symbol. +This page orients; the API reference enumerates every exported symbol. {{ comp.featureGrid({ items: [ { diff --git a/docs/site/ai/engine.md b/docs/site/ai/engine.md index 6852591065..6aa1dd8a1b 100644 --- a/docs/site/ai/engine.md +++ b/docs/site/ai/engine.md @@ -16,7 +16,7 @@ core that owns the domain vocabulary, the capability seams, the model registries the tool system, the agent loop, MCP transports, and opt-in provider adapters. It wraps `@tanstack/ai*` and `@standard-schema/spec` and adds no schema DSL of its own. We keep this page at the "which piece, and why" altitude; the exact symbol tables -live in the generated reference, linked at the end. +live in the API reference, linked at the end. {{ comp callout { type: "note", title: "Published in " + releaseVersion } }} @netscript/ai is published on JSR and installs today: @@ -179,7 +179,7 @@ Choosing between them is mostly a question of where your models live: chat: `.embed()` and `.analyze()`. Per-provider config fields and defaults are enumerated in the -[generated reference]({{ "ref:ai" |> xref |> url }}). +[API reference]({{ "ref:ai" |> xref |> url }}). ## Testing — deterministic fakes @@ -187,7 +187,7 @@ Per-provider config fields and defaults are enumerated in the without a network: fake chat model providers and agent loops that replay scripted turns and chunks, fake memory, embedding, and vision ports, an in-memory tool registry, and `createFakeTelemetryPort()` (whose `.records` capture emitted -telemetry). The full factory list lives in the generated reference. +telemetry). The full factory list lives in the API reference. ## Wiring tool and agent registries diff --git a/docs/site/ai/mcp.md b/docs/site/ai/mcp.md index d2b3d70066..291b2d2bb7 100644 --- a/docs/site/ai/mcp.md +++ b/docs/site/ai/mcp.md @@ -175,7 +175,7 @@ published and gate-tested. }, { title: "Look up — @netscript/ai", - body: "The generated reference for the engine package, including every ./mcp export.", + body: "The API reference for the engine package, including every ./mcp export.", href: "/reference/ai/", icon: "≡" } diff --git a/docs/site/cli-reference.md b/docs/site/cli-reference.md index 6395dc0f3e..3df613a9a4 100644 --- a/docs/site/cli-reference.md +++ b/docs/site/cli-reference.md @@ -175,7 +175,8 @@ internals stay in the installed dependency. { name: "Wire the registry", type: "netscript generate plugins", desc: "Regenerate the plugin registries from project source. Run this after every plugin install." }, { name: "Check health", type: "netscript plugin list · netscript plugin doctor · netscript plugin info workers", desc: "List registered plugins, run the wiring sanity check, and show a single plugin's details." }, { name: "Author your own", type: "netscript plugin new billing", desc: "Scaffold a new two-tier plugin: a JSR-publishable core package plus a thin connector. See author a plugin." }, - { name: "Discover & maintain", type: "netscript marketplace search · netscript plugin update · netscript plugin remove ", desc: "Search the plugin marketplace, re-pin and regenerate an installed plugin, or remove one and update workspace registration." } + { name: "Discover & maintain", type: "netscript marketplace search · netscript plugin update · netscript plugin remove ", desc: "Search the plugin marketplace, re-pin and regenerate an installed plugin, or remove one and update workspace registration." }, + { name: "Configure the AI plugin", type: "netscript plugin ai [...args]", desc: "Configure AI tools, agents, models, providers, and MCP servers. A pass-through: every argument after the verb is forwarded verbatim to the installed @netscript/plugin-ai CLI, so its verbs are documented by that plugin, not here. Only --project-root is consumed by NetScript." } ] }) }} @@ -244,23 +245,29 @@ The frontend is copy-source: components are copied into your repo under ## Deploy -Two deploy paths are wired today: the **Deno Deploy** cloud target and the -**Windows Service** (Servy) path. `netscript deploy docker` and `deploy compose` exist as -command groups but are not wired — they only print help. See +Deploy carries several paths: the **Deno Deploy** cloud target, the **OS service** (Servy) +path, the **container and cloud targets** routed through Aspire, and two packaging verbs +for shipping a binary. `netscript deploy list` prints every registered target with the +operations it advertises — start there rather than guessing. See [deploy]({{ "howto:deploy" |> xref }}) for the portability story. {{ comp.apiTable({ caption: "Deploy commands", rows: [ + { name: "Discover targets", type: "netscript deploy list [--json]", desc: "List every registered deploy target with its label and advertised operations. --json emits machine-readable descriptors." }, { name: "Deno Deploy: preflight", type: "netscript deploy deno-deploy plan", desc: "Run the unstable-API guard (scans for Deno.openKv, Deno.cron, BroadcastChannel, Temporal) without pushing. The same guard blocks up --prod on a violation; a preview push warns but proceeds." }, { name: "Deno Deploy: lifecycle", type: "netscript deploy deno-deploy up [--prod] · down · status · logs", desc: "Push, delete, and inspect the deployment. A thin router over the native deno deploy CLI — it must be on your PATH and handles authentication." }, - { name: "Windows Service: build", type: "netscript deploy build", desc: "Build the Windows Service deployment artifacts from a deployment manifest via Servy." }, - { name: "Windows Service: lifecycle", type: "netscript deploy install · start · stop · status · logs · upgrade · uninstall", desc: "Install, run, inspect, upgrade, and remove Windows Services from the manifest." } + { name: "OS service: build", type: "netscript deploy build", desc: "Compile services and generate the deployment artifacts from a deployment manifest via Servy." }, + { name: "OS service: lifecycle", type: "netscript deploy install · start · stop · status · logs · upgrade · uninstall", desc: "Register, run, inspect, upgrade, and remove OS services from the manifest." }, + { name: "Containers: Docker & Compose", type: "netscript deploy docker · netscript deploy compose ", desc: "Aspire-backed container targets. Both expose plan · up · down · status · logs — the bare group prints help, as every command group does, but the verbs run against a real adapter." }, + { name: "Cloud targets", type: "netscript deploy kubernetes · azure-aca · azure-app-service · azure-aks · cloud-run", desc: "Aspire-backed cloud targets, each exposing plan · up · down. See the command reference for why their verb list is shorter." }, + { name: "Package a desktop app", type: "netscript deploy desktop package · netscript deploy desktop release", desc: "Package an enabled desktop app into native Deno Desktop formats for the host OS/arch by default (or an explicit target), and prepare, sign, and serve a native release." }, + { name: "Package the CLI", type: "netscript deploy package-cli", desc: "Compile the NetScript CLI into a self-shippable Windows .exe. Flags: -o, --output-dir <dir> (default ./.deploy/windows), --target <triple> (default x86_64-pc-windows-msvc), --no-bundle, -v, --verbose." } ] }) }} The shared flags (`--org`, `--app`, `--entrypoint`, `--env-file`, `--project-root`), the -planning-only cloud targets, and the artifact-copy verbs are in the +per-target verb flags, and the artifact-copy verbs are in the [command reference](/reference/cli/commands/). ## Agent tooling @@ -269,7 +276,8 @@ planning-only cloud targets, and the artifact-copy verbs are in the caption: "AI agent commands", rows: [ { name: "Install agent tooling", type: "netscript agent init", desc: "Install NetScript MCP, consumer tools, and skills. Use --editor none|zed|vscode to apply editor-native setup to a new or existing project; one existing editor directory is detected by default. Use --host claude|vscode|all for agent hosts and --with-docs for the exact-version offline corpus." }, - { name: "Run the MCP server", type: "netscript agent mcp", desc: "Start the NetScript MCP server over standard input/output." } + { name: "Run the MCP server", type: "netscript agent mcp", desc: "Start the NetScript MCP server over standard input/output." }, + { name: "Record drift", type: "netscript agent drift record --resource --summary ", desc: "Record an evidence-gated drift note after a fresh successful diagnostic pass. The record is rejected unless the evidence for --resource is present on disk, so it cannot be written from memory. --details <text> is optional." } ] }) }} @@ -303,7 +311,7 @@ flag — spelled exactly as the installed CLI prints it — go to the }, { title: "@netscript/cli package", - body: "The generated package reference — the embeddable TypeScript surface, not the command tree.", + body: "The package API reference — the embeddable TypeScript surface, not the command tree.", href: "/reference/cli/", icon: "◇" } diff --git a/docs/site/explanation/architecture.md b/docs/site/explanation/architecture.md index 30c258bad5..71e661b47c 100644 --- a/docs/site/explanation/architecture.md +++ b/docs/site/explanation/architecture.md @@ -71,7 +71,7 @@ This is why "change the shape" is a type error you see at compile time rather than a 500 you discover in production. The contract machinery — `@orpc/contract`, zod, and `implement()` — is the subject of [Contracts & type flow]({{ comp.xref({ key: "explain:contracts" }) }}); the -generated reference is [`@netscript/contracts`]({{ comp.xref({ key: "ref:contracts" }) }}). +API reference is [`@netscript/contracts`]({{ comp.xref({ key: "ref:contracts" }) }}). ### 2. Packages and plugins — composing the substrate diff --git a/docs/site/identity-access/auth.md b/docs/site/identity-access/auth.md index c89993c982..8709869b47 100644 --- a/docs/site/identity-access/auth.md +++ b/docs/site/identity-access/auth.md @@ -362,7 +362,7 @@ Aspire-first ordering every plugin schema follows. ## Reference The auth runtime is a `@netscript/service`; the auth plugin, core contract package, and backend -adapters now have dedicated generated reference pages. +adapters now have dedicated reference pages. {{ comp.xref({ key: "ref:auth" }) }} {{ comp.xref({ key: "ref:service" }) }} diff --git a/docs/site/reference/ai/index.md b/docs/site/reference/ai/index.md index 1f00bd736a..c55c9a1b91 100644 --- a/docs/site/reference/ai/index.md +++ b/docs/site/reference/ai/index.md @@ -7,8 +7,8 @@ title: "@netscript/ai" The provider-agnostic AI engine core for NetScript: a composition root, a global model registry, the domain vocabulary and capability ports for chat/embeddings/vision/tools/agents/MCP, -and a set of opt-in provider adapters. This page is generated from the package's public surface -with `deno doc` (US-2). For the full index of packages and plugins return to the +and a set of opt-in provider adapters. This page is written against the package's public surface +reported by `deno doc`. For the full index of packages and plugins return to the [reference overview](/reference/). The base `@netscript/ai` entrypoint takes **no** `@netscript/*` runtime dependency and pulls no @@ -26,7 +26,7 @@ const handle = await getModel("anthropic:claude-sonnet-4-5"); ## Export map -The package publishes the following entrypoints. Each is generated from its own `deno doc` +The package publishes the following entrypoints. Each is documented against its own `deno doc` surface. | Export | Entrypoint | Purpose | diff --git a/docs/site/reference/aspire/index.md b/docs/site/reference/aspire/index.md index f5162b0c2f..8b7593434b 100644 --- a/docs/site/reference/aspire/index.md +++ b/docs/site/reference/aspire/index.md @@ -6,8 +6,8 @@ title: "@netscript/aspire" # `@netscript/aspire` SDK-neutral Aspire diagnostics, config parsing, contribution ports, and TypeScript AppHost -generation for NetScript plugin packages. This page is generated from the package's public -surface with `deno doc` (US-2). For the full index of packages and plugins return to the +generation for NetScript plugin packages. This page is written against the package's public +surface reported by `deno doc`. For the full index of packages and plugins return to the [reference overview](/reference/). > **Generated AppHost runtime behavior.** The TypeScript AppHost this package generates emits @@ -238,8 +238,8 @@ The production aggregate entrypoint re-exports all public config, schema, types, ## Sub-path exports -The following entrypoints are published alongside the root export. Each is generated from its own -`deno doc` surface and documented in the sections above. +The following entrypoints are published alongside the root export. Each is documented against its +own `deno doc` surface in the sections above. | Export | Entrypoint | Purpose | | --- | --- | --- | diff --git a/docs/site/reference/auth-better-auth/index.md b/docs/site/reference/auth-better-auth/index.md index e8057727ba..17be581efb 100644 --- a/docs/site/reference/auth-better-auth/index.md +++ b/docs/site/reference/auth-better-auth/index.md @@ -5,8 +5,8 @@ title: "@netscript/auth-better-auth" # `@netscript/auth-better-auth` -Better Auth integration, authenticator, and backend adapter for NetScript auth. This -page is generated from the package's public surface with `deno doc`. +Better Auth integration, authenticator, and backend adapter for NetScript auth. This page is +written against the package's public surface reported by `deno doc`. ## Factories diff --git a/docs/site/reference/auth-kv-oauth/index.md b/docs/site/reference/auth-kv-oauth/index.md index 8d18357faf..6d1214aab4 100644 --- a/docs/site/reference/auth-kv-oauth/index.md +++ b/docs/site/reference/auth-kv-oauth/index.md @@ -5,8 +5,8 @@ title: "@netscript/auth-kv-oauth" # `@netscript/auth-kv-oauth` -KV-backed OAuth2/OIDC relying-party backend for NetScript auth. This page is -generated from the package's public surface with `deno doc`. +KV-backed OAuth2/OIDC relying-party backend for NetScript auth. This page is written against the +package's public surface reported by `deno doc`. ## Backend and flow factories diff --git a/docs/site/reference/auth-workos/index.md b/docs/site/reference/auth-workos/index.md index 17ddc5a9bb..8be89bc989 100644 --- a/docs/site/reference/auth-workos/index.md +++ b/docs/site/reference/auth-workos/index.md @@ -5,8 +5,8 @@ title: "@netscript/auth-workos" # `@netscript/auth-workos` -WorkOS-backed authenticator and backend adapter for NetScript auth. This page is -generated from the package's public surface with `deno doc`. +WorkOS-backed authenticator and backend adapter for NetScript auth. This page is written against +the package's public surface reported by `deno doc`. ## Factories diff --git a/docs/site/reference/auth/index.md b/docs/site/reference/auth/index.md index 24f882d368..9d7de0efe3 100644 --- a/docs/site/reference/auth/index.md +++ b/docs/site/reference/auth/index.md @@ -6,8 +6,7 @@ title: "Auth reference" # Auth reference NetScript auth is split across one plugin manifest package, one core contract package, and -three backend adapters. This hub is generated from the public surfaces verified with -`deno doc`. +three backend adapters. This hub is written against the public surfaces reported by `deno doc`. For capability guidance, start with [Authentication](/capabilities/auth/). For the runtime service builder used by auth-api, see [@netscript/service](/reference/service/). diff --git a/docs/site/reference/cli/commands.md b/docs/site/reference/cli/commands.md index d8ccac2b91..197ea22ce7 100644 --- a/docs/site/reference/cli/commands.md +++ b/docs/site/reference/cli/commands.md @@ -8,8 +8,8 @@ title: "netscript command reference" The complete verb-and-flag surface of the published `netscript` binary (`@netscript/cli`). The [CLI reference](/cli-reference/) is the curated tour of the everyday path; this page is the exhaustive companion — every command group, -subcommand, and flag, spelled exactly as the installed CLI prints it. For the generated -package API surface (the embeddable helpers, not the command tree) see the +subcommand, and flag, spelled exactly as the installed CLI prints it. For the package API +surface (the embeddable helpers, not the command tree) see the [`@netscript/cli` package page](/reference/cli/). This page documents the **public `netscript` binary** — the CLI published as @@ -56,6 +56,23 @@ the [quickstart](/quickstart/); every flag is: | --- | --- | | `netscript agent init` | Install NetScript MCP, consumer diagnostic tools, and skills for detected agent hosts, and apply editor setup to a new or existing project. Claude Code writes `.mcp.json` and installs the skill bundle; VS Code writes `.vscode/mcp.json`; Zed writes `.zed/settings.json` `context_servers`. Flags: `--host ` (`claude`, `vscode`, or `all`); `--editor ` (`none`, `zed`, or `vscode`, inferred from one existing editor directory when omitted); `--with-docs` installs the expanded exact-version corpus. Unsupported editors fail with manual-configuration guidance. | | `netscript agent mcp` | Start the stdio MCP server for an MCP client. Interactive use prints Zed/VS Code setup guidance; see [Agent tooling](/ai/agent-tooling/). Flags: `--endpoint ` (telemetry endpoint), `--project-root `, `--docs-root ` (public documentation root). | +| `netscript agent drift ` | Manage evidence-gated agent drift records. The group itself prints help; `record` is its only subcommand. | + +### `agent drift` subcommands + +| Command | Description | +| --- | --- | +| `netscript agent drift record` | Record drift after a fresh successful diagnostic pass. Flags: `--resource ` (**required**), `--summary ` (**required**), `--details `. | + +The gate is the point. `record` appends an entry only when a diagnostic **receipt** for +`--resource` exists, exited `0`, and is **less than 15 minutes old**; the receipt itself is +embedded in the entry. Anything else — no receipt, a failed one, a future timestamp, or a +stale one — is refused with a non-zero exit and a message naming how to produce a fresh +receipt (`netscript plugin doctor --resource `, or the MCP `doctor`, telemetry, API +introspection, or `execute_command` tools). A drift note therefore cannot be written from +an agent's recollection of a run it did not just perform. + +The same gate backs the MCP `record_drift` tool, so both surfaces refuse identically. ## `config` — inspect and mutate configuration @@ -65,6 +82,7 @@ runtime overrides. | Command | Description | | --- | --- | | `netscript config inspect` | Inspect the resolved project configuration. Flags: `--project-root `, `--json` (emit the JSON-stable inspection report). | +| `netscript config list [filter]` | List the canonical `appsettings` paths the generator reads, with each path's current value. The optional positional `[filter]` narrows the listing. Paths present in `appsettings.json` but **not** read by the generator are marked `(not read by the generator)` — which is what makes this the command for finding a setting that is being ignored. Flags: `--project-root `, `--json`. | | `netscript config get ` | Read a resolved configuration value. Flags: `--project-root `, `--json`. | | `netscript config set ` | Set a generated `appsettings` configuration value. Flag: `--project-root `. | | `netscript config override ` | Manage runtime overrides (see below). | @@ -125,6 +143,14 @@ the [CLI reference](/cli-reference/#plugins). The full group also carries: | `netscript plugin disable [args...]` | Run a plugin's published `disable` command. Flag: `--project-root `. | | `netscript plugin setup [args...]` | Run a plugin's published `setup` command. Flag: `--project-root `. | | `netscript plugin auth ` | Configure auth and manage sessions (see below). | +| `netscript plugin ai [...args]` | Configure AI tools, agents, models, providers, and MCP servers. Flag: `--project-root ` (the only flag NetScript consumes). | + +`plugin ai` is a **pass-through**, not a command group with its own verbs. NetScript strips +`--project-root`, then runs the installed `@netscript/plugin-ai` package's CLI in a child +`deno run` process and forwards every remaining argument verbatim, printing its output and +propagating its exit code. The verb vocabulary therefore belongs to that plugin's release, +not to this reference; see the +[`@netscript/plugin-ai` reference](/reference/plugin-ai/). Invoking it with no verb is an error. ### `plugin auth` subcommands @@ -200,35 +226,74 @@ modified — your edits are never overwritten. See ## `deploy` — cloud and container targets -The [CLI reference](/cli-reference/#deploy) covers the wired Deno Deploy and Windows -Service (Servy) paths. The `deploy` group also exposes a family of cloud and container -targets, plus artifact-copy and log verbs. +The [CLI reference](/cli-reference/#deploy) covers the Deno Deploy and OS service (Servy) +paths. The `deploy` group also exposes a family of routed cloud and container targets, the +packaging verbs, and artifact-copy and log verbs. -### Cloud and container targets +### Discovering targets -Each target below shares the same three-verb lifecycle — `plan`, `up`, `down`: - -| Command group | Description | +| Command | Description | | --- | --- | -| `netscript deploy kubernetes ` | Manage the Kubernetes deployment target. | -| `netscript deploy azure-aca ` | Manage the Azure Container Apps deployment target. | -| `netscript deploy azure-app-service ` | Manage the Azure App Service deployment target. | -| `netscript deploy azure-aks ` | Manage the Azure Kubernetes Service deployment target. | -| `netscript deploy cloud-run ` | Manage the Google Cloud Run deployment target. | - -The three lifecycle verbs are: +| `netscript deploy list` | List registered deploy targets and operations. Prints `key`, advertised operations, and label per line. Flag: `--json` (emit machine-readable target descriptors). | + +`deploy list` reads the live registry, so it is the authoritative answer to which targets are +registered and which operations their adapters advertise. The advertised set can be wider than +the router's callable command set; use each target's help output or the routed-verb table below to +see which verbs the CLI exposes. Ten targets are +registered by default: `azure-aca`, `azure-aks`, `azure-app-service`, `cloud-run`, +`compose`, `deno-deploy`, `docker`, `kubernetes`, `linux-service`, `windows-service`. + +### Routed cloud and container targets + +These seven groups are generated by one router. Each is a thin command that parses flags and +dispatches to a registry-resolved adapter; the adapter holds all target-specific logic. + +| Command group | Verbs | Description | +| --- | --- | --- | +| `netscript deploy docker ` | `plan` `up` `down` `status` `logs` | Manage the Docker image deployment target. | +| `netscript deploy compose ` | `plan` `up` `down` `status` `logs` | Manage the Docker Compose deployment target. | +| `netscript deploy kubernetes ` | `plan` `up` `down` | Manage the Kubernetes deployment target. | +| `netscript deploy azure-aca ` | `plan` `up` `down` | Manage the Azure Container Apps deployment target. | +| `netscript deploy azure-app-service ` | `plan` `up` `down` | Manage the Azure App Service deployment target. | +| `netscript deploy azure-aks ` | `plan` `up` `down` | Manage the Azure Kubernetes Service deployment target. | +| `netscript deploy cloud-run ` | `plan` `up` `down` | Manage the Google Cloud Run deployment target. | + +The verb lists differ because **a target only gets a subcommand for an operation it +advertises**. The router walks a fixed candidate list — `plan`, `up`, `down`, `status`, +`logs`, `rollback`, `secrets` — and skips any operation missing from the adapter's +`operations`, so a target never exposes a verb it cannot perform. The two container targets +advertise `status` and `logs`; the five cloud targets do not. + +Running a target group with no verb prints help, as every command group in the CLI does. +That is the group's default action, not a sign that the target is unimplemented. | Verb | Description | | --- | --- | | `plan` | Emit or preflight deployment artifacts. | | `up` | Bring the deployment up. | | `down` | Bring the deployment down. | +| `status` | Show deployment status. | +| `logs` | Show deployment logs. | -Every verb on every target shares the same flags: `--project-root `, +Every routed verb on every target shares the same flags: `--project-root `, `--output-dir ` (directory for emitted deployment artifacts), `--environment ` (deployment environment passed to the target), `--clear-cache` (clear target deployment state and do not persist new values), and `--non-interactive`. +### Packaging + +| Command | Description | +| --- | --- | +| `netscript deploy desktop ` | Package and publish native Deno Desktop applications. The group prints help; `package` and `release` do the work. | +| `netscript deploy desktop package` | Package an enabled desktop app into Deno Desktop native formats. Flags: `--project-root `, `--app `, `--target `, `--all-targets`, repeatable `--format `, `--compression ` (default `xz`), `-o, --output-dir ` (default `.deploy/desktop/packages`). Without a target flag it uses the host OS and architecture; an unsupported target fails rather than producing a wrong artifact. | +| `netscript deploy desktop release ` | Prepare or serve a native release. The group prints help for its two subcommands. | +| `netscript deploy desktop release prepare` | Prepare and sign release metadata. Required flags: `--target `, `--version `, `--sequence `, `--current-runtime `, repeatable `--from =`, `--private-key-file `. Optional: `--project-root `, `--channel ` (default `stable`), `--release-dir ` (default `.deploy/desktop/releases`). | +| `netscript deploy desktop release serve` | Serve a prepared release directory. Flags: `--project-root `, `--release-dir ` (default `.deploy/desktop/releases`), `--hostname ` (default `127.0.0.1`), `--port ` (default `8787`), `--base-path ` (default `/`). | +| `netscript deploy package-cli` | Compile the NetScript CLI itself into a self-shippable Windows `.exe`. Flags: `-o, --output-dir ` (default `./.deploy/windows`; a `scripts/` subdirectory is used), `--target ` (default `x86_64-pc-windows-msvc`), `--no-bundle` (compile directly from source — larger output), `-v, --verbose`. | + +`package-cli` bundles before compiling by default and falls back to compiling from source if +the bundle step fails, so `--no-bundle` is a size/behaviour trade-off rather than a repair. + ### Artifact copy, logs, and upgrade | Command | Description | diff --git a/docs/site/reference/cli/index.md b/docs/site/reference/cli/index.md index 187c21c815..331f48da04 100644 --- a/docs/site/reference/cli/index.md +++ b/docs/site/reference/cli/index.md @@ -6,8 +6,8 @@ templateEngine: [vento, md] # `@netscript/cli` -Public and maintainer command-line tooling for NetScript workspaces. This page is generated -from the package's public surface with `deno doc` (US-2). For the full index of packages and +Public and maintainer command-line tooling for NetScript workspaces. This page is written against +the package's public surface reported by `deno doc`. For the full index of packages and plugins return to the [reference overview](/reference/). The root entrypoint (`@netscript/cli`) exposes the embeddable, programmatic CLI surface — the diff --git a/docs/site/reference/config/index.md b/docs/site/reference/config/index.md index 37fe14885e..f4d9440c55 100644 --- a/docs/site/reference/config/index.md +++ b/docs/site/reference/config/index.md @@ -5,7 +5,10 @@ title: "@netscript/config" # `@netscript/config` -Typed NetScript project configuration: schemas, loaders, environment helpers, workspace discovery, diagnostics, and scaffold constants. This page is generated from the package public surface with `deno doc` (US-2). For the full index of packages and plugins return to the [reference overview](/reference/). +Typed NetScript project configuration: schemas, loaders, environment helpers, workspace discovery, +diagnostics, and scaffold constants. This page is written against the package public surface +reported by `deno doc`. For the full index of packages and plugins return to the +[reference overview](/reference/). The root entrypoint (`@netscript/config`) exposes the authoring, loading, environment, workspace, and diagnostic contract. The usual path is to define a project config once with `defineConfig` in `netscript.config.ts`, load it at process startup with `initConfig`, and read the validated `NetScriptConfig` synchronously with `getConfig`. Schema-only APIs live on sub-paths so the public root surface does not leak Zod internals: diff --git a/docs/site/reference/contracts/index.md b/docs/site/reference/contracts/index.md index 44bcc43d9e..00494f098e 100644 --- a/docs/site/reference/contracts/index.md +++ b/docs/site/reference/contracts/index.md @@ -9,8 +9,8 @@ Contract vocabulary shared across NetScript package and plugin boundaries: the o contract, common error data, pagination schemas, result types, and schema helper factories. Because a contract's input schema is enforced at the transport boundary, a service handler never hand-parses or validates `req.json()` — a request that doesn't match the schema is rejected before -your code runs, and the same contract types the client that calls it. This page is generated from -the package's public surface with `deno doc` (US-2). For the full index of packages and plugins +your code runs, and the same contract types the client that calls it. This page is written against +the package's public surface reported by `deno doc`. For the full index of packages and plugins return to the [reference overview](/reference/). The root entrypoint (`@netscript/contracts`) carries the core contract primitives. Three diff --git a/docs/site/reference/cron/index.md b/docs/site/reference/cron/index.md index 92e21fc6f2..89ed4cbeff 100644 --- a/docs/site/reference/cron/index.md +++ b/docs/site/reference/cron/index.md @@ -8,8 +8,8 @@ title: "@netscript/cron" Runtime-agnostic cron scheduling abstraction for NetScript applications. Provides a consistent interface across different backends (native `Deno.cron` and an in-memory scheduler) with timezone support, job-lifecycle event emission, and runtime -auto-detection. This page is generated from the package public surface with `deno doc` -(US-2). For the full index of packages and plugins return to the +auto-detection. This page is written against the package public surface reported by `deno doc`. +For the full index of packages and plugins return to the [reference overview](/reference/). The root entrypoint (`@netscript/cron`) exposes the scheduler factory, the shared-instance @@ -85,7 +85,7 @@ Concrete implementations of `CronScheduler`, exported from `@netscript/cron/adap ## Sub-path exports The following entrypoints are published alongside the root export. Their reference surface is -generated from their own `deno doc` output. +documented against their own `deno doc` output. | Export | Entrypoint | Purpose | | --- | --- | --- | diff --git a/docs/site/reference/database/index.md b/docs/site/reference/database/index.md index 6a8899b2ce..77793c9eee 100644 --- a/docs/site/reference/database/index.md +++ b/docs/site/reference/database/index.md @@ -6,8 +6,8 @@ title: "@netscript/database" # `@netscript/database` Database adapter contracts, Prisma driver helpers, tracing, and schema tooling for -NetScript packages. This page is generated from the package's public surface with -`deno doc` (US-2). For the full index of packages and plugins return to the +NetScript packages. This page is written against the package's public surface reported by +`deno doc`. For the full index of packages and plugins return to the [reference overview](/reference/). The root entrypoint (`@netscript/database`) re-exports the port contracts, the PostgreSQL diff --git a/docs/site/reference/fresh-ui/index.md b/docs/site/reference/fresh-ui/index.md index 51b0495e99..78a1ad6c68 100644 --- a/docs/site/reference/fresh-ui/index.md +++ b/docs/site/reference/fresh-ui/index.md @@ -5,8 +5,8 @@ title: "@netscript/fresh-ui" # `@netscript/fresh-ui` -Fresh UI registry seams and interactive foundations for NetScript. This page is generated -from the package public surface with `deno doc` (US-2). For the full index of packages and +Fresh UI registry seams and interactive foundations for NetScript. This page is written against +the package public surface reported by `deno doc`. For the full index of packages and plugins return to the [reference overview](/reference/). The root entrypoint (`@netscript/fresh-ui`) intentionally stays small: copy-based registry diff --git a/docs/site/reference/fresh/index.md b/docs/site/reference/fresh/index.md index 9f7c937169..3d5cb0fe41 100644 --- a/docs/site/reference/fresh/index.md +++ b/docs/site/reference/fresh/index.md @@ -6,7 +6,7 @@ title: '@netscript/fresh' # `@netscript/fresh` Fresh runtime extensions, builders, forms, defer primitives, and route contracts for NetScript. This -page is generated from the public surface of the package with `deno doc` (US-2). For the full index +page is written against the public surface reported by `deno doc`. For the full index of packages and plugins return to the [reference overview](/reference/). The root entrypoint (`@netscript/fresh`) exposes only the cross-cutting page-loader cache helpers. diff --git a/docs/site/reference/index.md b/docs/site/reference/index.md index ab64b745e6..62fbf8f26f 100644 --- a/docs/site/reference/index.md +++ b/docs/site/reference/index.md @@ -4,7 +4,41 @@ title: Reference --- Reference is **information-oriented**: precise, exhaustive API documentation for every public -NetScript package and plugin. These pages are generated from the source code with `deno doc`, -so they always describe the published surface (US-2). For a guided introduction start with the -[tutorials](/tutorials/), for problem-solving recipes see the [how-to guides](/how-to/), and -for the ideas behind the API read the [explanation](/explanation/). +NetScript package and plugin. These pages are hand-written and derived from each package's published +export surface with `deno doc`, so they describe the published surface rather than the source tree +surface. For a guided introduction start with the [tutorials](/tutorials/), for problem-solving +recipes see the [how-to guides](/how-to/), and for the ideas behind the API read the +[explanation](/explanation/). + +There is no generator that writes these pages. `deno doc ` is the authority a page is written +against, and an automated drift check verifies a subset of pages against their packages' declared +entrypoints — so a page can fall behind its package, and one that has is a bug worth filing. + +## Page paths + +Every publishable workspace member has a page at `/reference//`. Today the segment is the +package name with the `@netscript/` scope stripped — `@netscript/sdk` at [`/reference/sdk/`](/reference/sdk/), +`@netscript/plugin-ai-core` at [`/reference/plugin-ai-core/`](/reference/plugin-ai-core/) — with four +exceptions, the deployable plugins, which drop the `plugin-` prefix: + +| Package | Page | +| --- | --- | +| `@netscript/plugin-sagas` | [`/reference/sagas/`](/reference/sagas/) | +| `@netscript/plugin-streams` | [`/reference/streams/`](/reference/streams/) | +| `@netscript/plugin-triggers` | [`/reference/triggers/`](/reference/triggers/) | +| `@netscript/plugin-workers` | [`/reference/workers/`](/reference/workers/) | + +Their `-core` counterparts use the name-exact form, so `@netscript/plugin-sagas-core` is at +[`/reference/plugin-sagas-core/`](/reference/plugin-sagas-core/) while `@netscript/plugin-sagas` is at +`/reference/sagas/`. This is a description of what the site does today, not a rule to follow when the +two forms disagree. + +Each publishable workspace member's own page is canonical for its exported API. The four deployable +plugin pages describe their manifests and integration entrypoints, then link to their separately +published `-core` packages instead of duplicating the core symbol tables inline. Focused examples may +use both packages, but exhaustive entrypoint and symbol documentation lives on the package that +exports it. This one-package/one-canonical-page rule keeps the reference consistent with the +publishable workspace surface and gives each API claim one place to stay current. + +Navigation is derived from the folder tree, so a new page is discoverable as soon as its directory +exists — no index or nav file lists the packages. diff --git a/docs/site/reference/kv/index.md b/docs/site/reference/kv/index.md index 609def5d75..afb98a5c30 100644 --- a/docs/site/reference/kv/index.md +++ b/docs/site/reference/kv/index.md @@ -6,8 +6,8 @@ title: "@netscript/kv" # `@netscript/kv` Reactive key-value storage with a unified API across Deno KV, Redis, and in-memory -backends. This page is generated from the package's public surface with `deno doc` -(US-2). For the full index of packages and plugins return to the +backends. This page is written against the package's public surface reported by `deno doc`. +For the full index of packages and plugins return to the [reference overview](/reference/). The root entrypoint (`@netscript/kv`) exposes the stable shared lifecycle API, the diff --git a/docs/site/reference/logger/index.md b/docs/site/reference/logger/index.md index f52f069392..2f78bd30a7 100644 --- a/docs/site/reference/logger/index.md +++ b/docs/site/reference/logger/index.md @@ -5,8 +5,8 @@ title: "@netscript/logger" # `@netscript/logger` -Structured logging for NetScript packages, services, workers, and jobs. This page is -generated from the package's public surface with `deno doc` (US-2). For the full index of +Structured logging for NetScript packages, services, workers, and jobs. This page is written +against the package's public surface reported by `deno doc`. For the full index of packages and plugins return to the [reference overview](/reference/). The root entrypoint (`@netscript/logger`) exposes the lightweight core surface only: diff --git a/docs/site/reference/plugin-ai-core/index.md b/docs/site/reference/plugin-ai-core/index.md index 56b5638c4b..bbc0e5ff45 100644 --- a/docs/site/reference/plugin-ai-core/index.md +++ b/docs/site/reference/plugin-ai-core/index.md @@ -7,8 +7,8 @@ title: "@netscript/plugin-ai-core" The contract-only core for the NetScript AI plugin: the oRPC `/v1/ai` route surface — an SSE-framed `chat` stream plus `models`, `tools/{name}`, `embed`, and `transcribe` — that a -connector implements and the typed client calls. This page is generated from the package's -public surface with `deno doc` (US-2). For the full index of packages and plugins return to the +connector implements and the typed client calls. This page is written against the package's +public surface reported by `deno doc`. For the full index of packages and plugins return to the [reference overview](/reference/). The package ships **zero service implementation** (Archetype 1 — Small Contract). It declares the @@ -20,7 +20,7 @@ contract. ## Entrypoints -The package publishes two entrypoints. Each is generated from its own `deno doc` surface. +The package publishes two entrypoints. Each is documented against its own `deno doc` surface. | Export | Entrypoint | Purpose | | --- | --- | --- | diff --git a/docs/site/reference/plugin-ai/index.md b/docs/site/reference/plugin-ai/index.md index c54511a665..38ec6af349 100644 --- a/docs/site/reference/plugin-ai/index.md +++ b/docs/site/reference/plugin-ai/index.md @@ -13,13 +13,14 @@ logic. The engine (providers, tools, agent loop, embeddings) lives in the versioned `/v1/ai` contract lives in [`@netscript/plugin-ai-core`](#internals-netscriptplugin-ai-core). This package is a manifest, a connector, and a set of scaffolders that emit typesafe userland glue importing those installed -dependencies directly. This page is generated from the package public surface with `deno doc` -(US-2). For the full index of packages and plugins return to the +dependencies directly. This page is written against the package public surface reported by +`deno doc`. For the full index of packages and plugins return to the [reference overview](/reference/). ## Entrypoints -The plugin publishes the following entrypoints. Each is generated from its own `deno doc` surface. +The plugin publishes the following entrypoints. Each is documented against its own `deno doc` +surface. | Export | Entrypoint | Purpose | | --- | --- | --- | @@ -336,7 +337,7 @@ export const summarizeTool = defineAiTool("summarize") > implementer factory. `@netscript/plugin-ai` re-exports its contract through > `@netscript/plugin-ai/contracts`, and the generated stream route imports `createAiRouter`, > `aiContractV1`, and `AiRouterImplementation` from it directly. It is published separately and -> documented on its own [reference page](/reference/plugin-ai-core/) (US-8). The runtime AI engine +> documented on its own [reference page](/reference/plugin-ai-core/). The runtime AI engine > itself — providers, the tool registry, the agent loop, and embeddings — lives in the separate > `@netscript/ai` package, and the durable-chat client/server runtime in `@netscript/fresh/ai`. diff --git a/docs/site/reference/plugin-auth-core/index.md b/docs/site/reference/plugin-auth-core/index.md index 39a4f7f6ea..acea4fd23d 100644 --- a/docs/site/reference/plugin-auth-core/index.md +++ b/docs/site/reference/plugin-auth-core/index.md @@ -6,8 +6,8 @@ title: "@netscript/plugin-auth-core" # `@netscript/plugin-auth-core` Auth plugin contracts, backend ports, stream schemas, config schemas, telemetry -primitives, and testing primitives for NetScript auth plugins. This page is generated -from the package's public surface with `deno doc`. +primitives, and testing primitives for NetScript auth plugins. This page is written against the +package's public surface reported by `deno doc`. ## Backend ports and errors diff --git a/docs/site/reference/plugin-auth/index.md b/docs/site/reference/plugin-auth/index.md index 45402219be..78e740d201 100644 --- a/docs/site/reference/plugin-auth/index.md +++ b/docs/site/reference/plugin-auth/index.md @@ -6,8 +6,8 @@ templateEngine: [vento, md] # `@netscript/plugin-auth` -Public plugin manifest for NetScript auth. This page is generated from the package's -public surface with `deno doc`. For the auth package map, return to the +Public plugin manifest for NetScript auth. This page is written against the package's +public surface reported by `deno doc`. For the auth package map, return to the [auth reference hub](/reference/auth/). The root entrypoint exposes the plugin manifest and auth metadata constants. Shared manifest diff --git a/docs/site/reference/plugin-sagas-core/index.md b/docs/site/reference/plugin-sagas-core/index.md new file mode 100644 index 0000000000..55a3890f1f --- /dev/null +++ b/docs/site/reference/plugin-sagas-core/index.md @@ -0,0 +1,156 @@ +--- +layout: layouts/base.vto +title: "@netscript/plugin-sagas-core" +--- + +# `@netscript/plugin-sagas-core` + +Saga DSL, runtime ports, adapters, telemetry, config, and testing primitives for NetScript sagas +plugins. This page is written against the package's public surface reported by `deno doc`. +For the full index of packages and plugins return to the [reference overview](/reference/). + +Sagas are the honest answer to distributed transactions: a sequence of steps, each with a +compensation, driven by messages that may arrive twice or out of order. `defineSaga` builds a +frozen, typed definition — state, handlers, compensations, signals, queries — and the runtime drives +it through explicit ports for storage, transport, clock, and idempotency. Nothing is global: +applications inject their own durability, and tests inject deterministic in-memory doubles. + +This is the core that the deployable [`@netscript/plugin-sagas`](/reference/sagas/) plugin binds to a +NetScript host. Use it directly for custom hosts, libraries, and tests. + +## Entrypoints + +The package publishes nineteen entrypoints. The root path carries the userland DSL; the remaining +subpaths expose the layers a host, adapter author, or test harness composes. + +| Export specifier | Module | Exports | Purpose | +| --- | --- | --- | --- | +| `@netscript/plugin-sagas-core` | `./mod.ts` | 41 | The userland saga DSL — `defineSaga`, the cascaded-message constructors, signals, queries, and the definition types they produce (documented below). | +| `@netscript/plugin-sagas-core/builders` | `./src/builders/mod.ts` | 27 | The builder layer behind the DSL, for tooling that constructs definitions programmatically. | +| `@netscript/plugin-sagas-core/domain` | `./src/domain/mod.ts` | 44 | Saga domain vocabulary and policy defaults (`DEFAULT_RETRY_POLICY`, `DEFAULT_IDEMPOTENCY_WINDOW_MS`, `DEFAULT_RETRY_MAX_ATTEMPTS`). | +| `@netscript/plugin-sagas-core/ports` | `./src/ports/mod.ts` | 61 | The port interfaces the runtime depends on — store, bus, transport, clock, idempotency, telemetry. | +| `@netscript/plugin-sagas-core/runtime` | `./src/runtime/mod.ts` | 83 | The engine: `createSagaRuntime`, `createSagaEngine`, `createSagaCompensator`, `createSagaScheduler`, and the idempotency-key helpers. | +| `@netscript/plugin-sagas-core/adapters` | `./src/adapters/mod.ts` | 68 | Concrete port adapters, including `createSagaBusBridge`. | +| `@netscript/plugin-sagas-core/transports` | `./src/transports/mod.ts` | 49 | Saga bus transports (`createNetScriptRedisTransport`, `createGarnetListTransport`) with their message and delayed-entry codecs. | +| `@netscript/plugin-sagas-core/stores` | `./src/stores/mod.ts` | 56 | KV-backed instance and applied-key stores, `openSagaRuntimeKv`, and `resolveSagaStoreBackend`. | +| `@netscript/plugin-sagas-core/middleware` | `./src/middleware/mod.ts` | 30 | Host middleware — `createSagaMiddleware`, `createSSEEventsMiddleware`, `emitSagaEvent`. | +| `@netscript/plugin-sagas-core/integration/workers` | `./src/integration/workers/mod.ts` | 14 | Explicit workers-port helpers (`triggerJob`, `triggerTask`, `createWorkerTriggers`) that dispatch work **outside** synchronous saga handlers. | +| `@netscript/plugin-sagas-core/integration/publisher` | `./src/integration/publisher/mod.ts` | 10 | Publisher port contracts for submitting saga messages from plugin surfaces. | +| `@netscript/plugin-sagas-core/telemetry` | `./src/telemetry/mod.ts` | 43 | Telemetry attributes and instrumentation helpers, including an OpenTelemetry tracer factory. | +| `@netscript/plugin-sagas-core/config` | `./src/config/mod.ts` | 24 | `defineSagaConfig` and the saga runtime configuration schemas. | +| `@netscript/plugin-sagas-core/contracts/v1` | `./src/contracts/v1/mod.ts` | 29 | Version 1 saga API schemas and contract route types (`sagasContract`, `sagasContractV1`). | +| `@netscript/plugin-sagas-core/streams` | `./src/streams/mod.ts` | 17 | Durable stream schemas for projected saga instance records (`sagasStreamSchema`). | +| `@netscript/plugin-sagas-core/presets` | `./src/presets/mod.ts` | 9 | Preset composition helpers — `startSagas`, `startSagaHandlers`. | +| `@netscript/plugin-sagas-core/abstracts` | `./src/abstracts/mod.ts` | 58 | Abstract runtime contracts and reserved extension-point base classes. | +| `@netscript/plugin-sagas-core/testing` | `./src/testing/mod.ts` | 59 | `createTestSagaRuntime` plus in-memory bus and store doubles for deterministic verification. | +| `@netscript/plugin-sagas-core/agent` | `./src/agent/mod.ts` | 2 | `defineAgent` — the agent-shaped builder over the same saga definition. | + +Export counts are the symbol counts `deno doc` reports for each entrypoint; subpaths overlap where a +type is re-exported through more than one layer. + +## Root surface (`@netscript/plugin-sagas-core`) + +### Defining a saga + +| Symbol | Kind | Description | +| --- | --- | --- | +| `defineSaga` | function | Start a userland saga definition chain. | +| `SagaBuilder` | interface | The userland fluent saga builder. | +| `SagaBuilderPhase` | type alias | Typestate phase for the userland saga builder. | +| `SagaDefinition` | type alias | Frozen saga definition produced by the fluent DSL. | +| `SagaState` | type alias | Base state shape accepted by saga definitions. | +| `SagaContext` | type alias | Handler context passed to pure saga projections. | +| `SagaHandler` | type alias | Synchronous saga handler that returns cascaded messages. | +| `SagaEvent` | type alias | Event shape inferred by `defineSaga().on(type, handler)`. | +| `SagaMessage` | type alias | Base event or command delivered to a saga handler. | + +### Cascaded messages + +A handler is a pure projection: it returns cascaded messages rather than performing effects. These +constructors are the only side-effect ledger a handler produces. + +| Symbol | Kind | Description | +| --- | --- | --- | +| `send` | function | Create a cascade that republishes an internal saga message onto the saga bus. | +| `schedule` | function | Create a cascaded scheduled message. | +| `sagaComplete` | function | Create a terminal saga completion message. | +| `sagaFail` | function | Create a terminal saga failure message. | +| `sagaCompensate` | function | Create a cascaded compensation message. | +| `spawn` | function | **Rejects** an unsupported child-saga spawn request — spawn cascades are not implemented. | +| `CASCADED_MESSAGE_KINDS` | variable | Cascaded message kinds emitted by saga handlers. | +| `CascadedMessage` | type alias | Message emitted by a saga handler as its only side-effect ledger. | +| `CascadedMessageKind` | type alias | Cascaded message discriminator. | +| `CascadedMessageOptions` | type alias | Common options accepted by cascaded message constructors. | +| `CascadedMessageTarget` | type alias | Cascaded message target for jobs, sagas, or arbitrary runtime adapters. | +| `SendOptions` | type alias | Options for republishing an internal saga message onto the saga bus. | +| `SagaScheduleDelay` | type alias | Delay accepted by the `schedule()` cascaded-message constructor. | +| `SpawnOptions` | type alias | Options reserved for the unsupported `spawn()` cascade. | + +### Signals and queries + +| Symbol | Kind | Description | +| --- | --- | --- | +| `defineSignal` | function | Define a signal that can be sent to a running saga instance. | +| `defineQuery` | function | Define a synchronous read-only query for a running saga instance. | +| `SignalDefinition` | type alias | Signal definition reserved by the public DSL. | +| `QueryDefinition` | type alias | Query definition reserved by the public DSL. | +| `SagaSignalHandler` | type alias | Signal handler reserved by the userland saga DSL. | +| `SagaQueryHandler` | type alias | Synchronous query handler reserved by the userland saga DSL. | +| `SyncQueryResult` | type alias | Synchronous query result accepted by `onQuery`; promises are rejected at type level. | + +### Correlation and identity + +| Symbol | Kind | Description | +| --- | --- | --- | +| `SagaCorrelation` | type alias | Extracts a correlation key from an incoming saga message. | +| `SagaCorrelationKey` | type alias | Branded correlation key used to route messages to saga instances. | +| `SagaCorrelationRule` | type alias | Named correlation rule stored on a saga definition. | +| `SagaId` | type alias | Branded saga definition identifier. | +| `SagaInstanceId` | type alias | Branded saga instance identifier. | +| `SagaMessageId` | type alias | Branded message identifier for runtime and diagnostics records. | + +### Policies + +| Symbol | Kind | Description | +| --- | --- | --- | +| `RetryPolicy` | type alias | Retry policy for saga handlers and cascaded messages. | +| `SagaConcurrencyOptions` | type alias | Concurrency options accepted by the saga builder. | +| `SagaConcurrencyPolicy` | type alias | Concurrency policy for a saga definition. | +| `SAGA_DURABILITY_TIERS` | variable | Durability tiers supported by saga definitions. | +| `SagaDurabilityTier` | type alias | Saga durability tier. | + +## Handlers are synchronous + +A saga handler is synchronous and returns cascaded messages; it does not `await`. That is what makes +replay deterministic and what keeps the compensation path a pure function of the transcript. Work +that must happen outside the handler — enqueueing a worker job, calling a service — is expressed as a +cascaded message the runtime dispatches, or through the explicit +`@netscript/plugin-sagas-core/integration/workers` helpers. + +`spawn()` is present in the surface but **rejects**: child-saga spawn cascades are unsupported, and +calling it raises rather than silently succeeding. Its return type is `never`, so a handler that +returns `spawn(...)` does not type-check into the cascade union by accident. + +## Composing a runtime + +`@netscript/plugin-sagas-core/runtime` exposes `createSagaRuntime`, which takes explicit ports rather +than reaching for globals. The store, transport, clock, and idempotency edges are all injected, so +the same definitions run against Redis or Garnet in production +(`@netscript/plugin-sagas-core/transports`) and against in-memory doubles in tests +(`@netscript/plugin-sagas-core/testing`). + +`@netscript/plugin-sagas-core/presets` collapses the common case: `startSagas` composes a runtime and +starts it, and `startSagaHandlers` binds a definition set to an already-composed runtime. + +## Related pages + +- [`@netscript/plugin-sagas`](/reference/sagas/) — the deployable plugin that binds this core to a + NetScript host. +- [`@netscript/plugin-workers-core`](/reference/plugin-workers-core/) — the worker primitives the + `integration/workers` helpers dispatch to. +- [`@netscript/plugin-streams-core`](/reference/plugin-streams-core/) — the producer behind the + projected instance stream. + +--- + +Back to the [reference overview](/reference/). diff --git a/docs/site/reference/plugin-streams-core/index.md b/docs/site/reference/plugin-streams-core/index.md new file mode 100644 index 0000000000..d524d90d5c --- /dev/null +++ b/docs/site/reference/plugin-streams-core/index.md @@ -0,0 +1,180 @@ +--- +layout: layouts/base.vto +title: "@netscript/plugin-streams-core" +--- + +# `@netscript/plugin-streams-core` + +Schema, producer, config, telemetry, testing, and diagnostics primitives for NetScript streams. This +page is written against the package's public surface reported by `deno doc`. For the full +index of packages and plugins return to the [reference overview](/reference/). + +Publishing change events sounds trivial until it has to be safe: typed payloads, idempotent appends, +one producer per stream path, and a clean flush on shutdown. `defineStreamSchema` declares the +collections a stream carries with standard-schema validation and a configured primary key; +`createDurableStream` returns a path-singleton producer whose `upsert`/`delete` appends are +idempotent and auto-claimed; and the diagnostics helpers inspect a schema or resolve the stream +endpoint without opening a socket. + +This is the layer the deployable [`@netscript/plugin-streams`](/reference/streams/) service builds +on, and the layer the other NetScript plugins use when they project entities — executions, saga +instances, sessions — into durable topics. + +## Entrypoints + +| Export specifier | Module | Exports | Purpose | +| --- | --- | --- | --- | +| `@netscript/plugin-streams-core` | `./mod.ts` | 51 | Schema definition, the durable producer, endpoint resolution, diagnostics, and the v1 producer port vocabulary (documented below). | +| `@netscript/plugin-streams-core/sse` | `./src/sse/mod.ts` | 33 | The single versioned authority for the stream SSE wire contract: named-frame parsing, validated consumer outcomes, and replay state. | +| `@netscript/plugin-streams-core/telemetry` | `./src/telemetry/mod.ts` | 33 | Telemetry registration, span names, attribute keys, and the meter/counter/gauge ports used by reconnect metrics. | +| `@netscript/plugin-streams-core/testing` | `./src/testing/mod.ts` | 4 | An in-memory producer and a small schema fixture for tests that must not open network sockets. | + +Export counts are the symbol counts `deno doc` reports for each entrypoint; a few domain types are +re-exported through more than one subpath. + +## Root surface (`@netscript/plugin-streams-core`) + +### Schema definition + +| Symbol | Kind | Description | +| --- | --- | --- | +| `defineStreamSchema` | function | Define a type-safe durable stream schema. | +| `StreamStateDefinition` | type alias | Input map accepted by `defineStreamSchema`. | +| `StateSchema` | type alias | Schema map returned by `defineStreamSchema`. | +| `CollectionDefinition` | interface | A single collection definition inside a durable stream schema. | +| `CollectionEventHelpers` | interface | Helper methods attached to collections by `@durable-streams/state`. | +| `CollectionWithHelpers` | type alias | Collection definition after durable-streams helper methods are attached. | +| `StreamStandardSchema` | interface | Package-owned Standard Schema surface used by durable stream collections. | +| `StreamSchemaIssue` | interface | One validation issue returned by a Standard Schema validator. | +| `StreamSchemaValidationOptions` | interface | Validation options accepted by Standard Schema validators. | +| `StreamSchemaValidationResult` | type alias | Result returned by a Standard Schema validator. | + +### Producers + +| Symbol | Kind | Description | +| --- | --- | --- | +| `createDurableStream` | function | Create or reuse a compatible durable stream producer for one stream path. | +| `createServiceStreamProducer` | function | Create a durable stream producer from a backend Service. | +| `DurableStreamProducer` | class | Server-side writer for a named durable stream. | +| `DurableStreamProducerOptions` | interface | Options accepted by `DurableStreamProducer`. | +| `ServiceStreamProducerOptions` | type alias | Options accepted by `createServiceStreamProducer`. | + +`createDurableStream` is a **path singleton**: two calls for the same stream path with compatible +options return the same producer rather than opening a second writer. + +### Events + +| Symbol | Kind | Description | +| --- | --- | --- | +| `ChangeEvent` | interface | Entity change event emitted by durable stream producers. | +| `ControlEvent` | interface | Control event emitted by durable streams for non-entity lifecycle changes. | +| `StateEvent` | type alias | Durable stream event union. | +| `Operation` | type alias | State Protocol operation names supported by durable streams. | + +### Endpoint resolution and diagnostics + +| Symbol | Kind | Description | +| --- | --- | --- | +| `getStreamsUrl` | function | Resolve the base URL of the durable streams server. | +| `getStreamsAuth` | function | Resolve authentication headers for the durable streams server. | +| `buildStreamUrl` | function | Build the full stream URL for a NetScript stream path. | +| `inspectStreamTopic` | function | Inspect a stream schema and optional producer metadata. | +| `StreamTopicInspectionInput` | interface | Input accepted by `inspectStreamTopic`. | +| `StreamTopicInspectionReport` | interface | Diagnostic report returned by `inspectStreamTopic`. | + +`inspectStreamTopic` is a pure diagnostic: it reports on a schema and optional producer metadata +without connecting to the streams server. + +### Producer port contract (v1) + +The `*V1` names are the versioned port contract a producer implementation satisfies and a supervisor +consumes. They describe write acceptance, delivery outcome, reconnection, and buffering as data, +which is what lets the retry policy live outside the transport. + +| Symbol | Kind | Description | +| --- | --- | --- | +| `StreamProducerPort` | interface | Port implemented by stream producers that publish State Protocol changes. | +| `StreamProducerTransportPort` | interface | Durable-stream protocol edge consumed by the producer supervisor. | +| `StreamProducerClockPort` | interface | Clock edge used by reconnect backoff. | +| `StreamProducerRandomPort` | interface | Randomness edge used only to jitter reconnect delays. | +| `StreamProducerIdentityV1` | interface | Exact producer identity retained across an append retry. | +| `StreamProducerConnectInputV1` | interface | Connection input for the durable stream transport edge. | +| `StreamProducerAppendInputV1` | interface | Append input retained byte-for-byte until acknowledgement. | +| `StreamProducerCloseInputV1` | interface | Terminal close input using the next sequence in the same producer epoch. | +| `StreamProducerAcknowledgementV1` | interface | Acknowledgement returned by an append or terminal close. | +| `StreamProducerStateSnapshotV1` | interface | Snapshot of producer readiness and buffered work. | +| `StreamProducerReadinessOptionsV1` | interface | Options for waiting on the next ready transition. | +| `StreamProducerBufferPolicyV1` | interface | Dual queue bounds for accepted durable stream writes. | +| `StreamProducerReconnectPolicyV1` | interface | Finite retry policy used for connection and delivery attempts. | +| `StreamProducerTransportFailureV1` | interface | Transport failure understood by the application supervisor. | +| `StreamProducerTransportFailureKindV1` | type alias | Stable failure categories translated by the durable-stream transport adapter. | +| `StreamProducerTransportResultV1` | type alias | Result of one transport operation without policy or retry decisions. | +| `StreamProducerLifecycleStateV1` | type alias | One legal lifecycle state for a reconnecting durable stream producer. | +| `STREAM_PRODUCER_LIFECYCLE_STATES_V1` | variable | Legal lifecycle states for a reconnecting durable stream producer. | +| `DEFAULT_STREAM_PRODUCER_BUFFER_POLICY_V1` | variable | Default bounded producer buffer policy. | +| `DEFAULT_STREAM_PRODUCER_RECONNECT_POLICY_V1` | variable | Default bounded reconnect policy. | + +### Write outcomes + +| Symbol | Kind | Description | +| --- | --- | --- | +| `StreamWriteContextV1` | interface | Per-write correlation and message identity accepted by stream producers. | +| `StreamWriteReceiptV1` | interface | Immediate acceptance plus eventual terminal outcome for one write. | +| `StreamWriteOutcomeV1` | type alias | Terminal outcome of one durable stream write. | +| `StreamWriteRejectionReasonV1` | type alias | Reasons a producer rejects a write before accepting it. | +| `StreamWriteCancellationReasonV1` | type alias | Reasons an accepted write is cancelled before its first delivery attempt. | +| `StreamWriteUnknownReasonV1` | type alias | Reasons an attempted write cannot be reported as delivered or rejected. | + +A write returns a **receipt**, not a boolean: acceptance is immediate, and the terminal outcome — +delivered, rejected, cancelled, or unknown — settles later. `unknown` is a distinct outcome rather +than a failure, because a producer that lost its connection mid-append cannot honestly report either +success or rejection. + +## The SSE contract (`@netscript/plugin-streams-core/sse`) + +The `./sse` subpath is the single runtime authority for NetScript's versioned stream SSE envelope. +It distinguishes the **wire** event names the durable-stream server emits from the **consumer** +event names a validated binding delivers, so a consumer never branches on an unvalidated frame. + +| Symbol | Kind | Description | +| --- | --- | --- | +| `STREAM_SSE_CONTRACT_V1` | variable | Single runtime authority for NetScript's versioned stream SSE envelope. | +| `STREAM_SSE_PROTOCOL_VERSION_V1` | variable | Version identifier for the first NetScript stream SSE consumer contract. | +| `STREAM_SSE_WIRE_EVENT_NAMES_V1` | variable | Actual event names emitted by the durable-stream SSE wire protocol. | +| `STREAM_SSE_CONSUMER_EVENT_NAMES_V1` | variable | Validated outcomes delivered by the NetScript SSE consumer binding. | +| `parseStreamSseEventV1` | function | Parse a named SSE frame through the single v1 contract authority. | +| `bindStreamEventSourceV1` | function | Bind named `data` and `control` listeners using schema-validated v1 outcomes. | +| `createStreamSseReplayStateV1` | function | Create an empty or caller-seeded v1 replay snapshot. | +| `reduceStreamSseReplayStateV1` | function | Apply one valid frame while committing replay progress only on a control frame. | +| `StreamEventSourceV1` | interface | Minimal native `EventSource` surface used at the browser edge and in tests. | +| `StreamEventSourceBindingV1` | interface | Disposable browser binding and immutable replay snapshot accessor. | +| `StreamSseReplayStateV1` | interface | Replay snapshot consumed by reconnect policy without owning that policy. | +| `StreamSseOffsetV1` | type alias | A server-owned replay token — opaque, never parsed or incremented by a consumer. | + +Replay progress commits **only on a control frame**: `reduceStreamSseReplayStateV1` applies a valid +data frame without advancing the committed offset, so a consumer that reconnects mid-batch replays +from the last acknowledged control point rather than skipping the tail of an interrupted batch. +Errors are normalized into `StreamSseErrorPayloadV1` and never advance replay state. + +## Telemetry and testing + +`@netscript/plugin-streams-core/telemetry` exposes `streamsInstrumentation` — a registration object +matching the minimal contract NetScript telemetry hosts understand — plus `StreamSpanNames`, +`StreamAttributes`, and `StreamProducerMetricNames`. The meter, counter, gauge, tracer, and span +ports are declared here as interfaces, so a producer emits reconnect metrics without importing an +OpenTelemetry SDK. + +`@netscript/plugin-streams-core/testing` provides `MemoryStreamProducer` (records +`MemoryStreamEvent`s instead of opening a socket) and `createStreamTopicFixture` (a small schema with +one `execution` collection). Tests written against these run without network permissions. + +## Related pages + +- [`@netscript/plugin-streams`](/reference/streams/) — the deployable streams plugin and service. +- [`@netscript/plugin-workers-core`](/reference/plugin-workers-core/) and + [`@netscript/plugin-sagas-core`](/reference/plugin-sagas-core/) — both project their records into + durable topics through this producer. + +--- + +Back to the [reference overview](/reference/). diff --git a/docs/site/reference/plugin-triggers-core/index.md b/docs/site/reference/plugin-triggers-core/index.md new file mode 100644 index 0000000000..6c7b3ff344 --- /dev/null +++ b/docs/site/reference/plugin-triggers-core/index.md @@ -0,0 +1,259 @@ +--- +layout: layouts/base.vto +title: "@netscript/plugin-triggers-core" +--- + +# `@netscript/plugin-triggers-core` + +Trigger DSL, runtime ports, adapters, telemetry, config, and testing primitives for NetScript trigger +plugins. This page is written against the package's public surface reported by `deno doc`. For +the full index of packages and plugins return to the [reference overview](/reference/). + +The hard part of triggers is not receiving them — it is surviving them: duplicate webhooks, senders +that retry on a slow response, crashes between the acknowledgement and the work. `defineWebhook`, +`defineScheduledTrigger`, and `defineFileWatch` take the handler first and a frozen spec second; +ingress verifies and persists an event before responding `202`; and the processor applies +idempotency, retry policy, bounded concurrency, dead-lettering, and circuit-breaking around every +dispatch — all through explicit ports you can swap. + +This is the core that the deployable [`@netscript/plugin-triggers`](/reference/triggers/) plugin binds +to a NetScript host. Use it directly for custom hosts, libraries, and tests. + +## Entrypoints + +| Export specifier | Module | Exports | Purpose | +| --- | --- | --- | --- | +| `@netscript/plugin-triggers-core` | `./mod.ts` | 106 | The full public surface — builders, runtime factories, ports, and the event model (documented below). | +| `@netscript/plugin-triggers-core/public` | `./src/public/mod.ts` | 106 | The same curated public surface the root re-exports, for consumers that prefer to name it explicitly. | +| `@netscript/plugin-triggers-core/builders` | `./src/builders/mod.ts` | 50 | The three definition builders and the handler-action constructors (`enqueueJob`). | +| `@netscript/plugin-triggers-core/domain` | `./src/domain/mod.ts` | 69 | Trigger domain vocabulary and policy defaults (concurrency limit, idempotency TTL, circuit-breaker thresholds, backoff multiplier). | +| `@netscript/plugin-triggers-core/ports` | `./src/ports/mod.ts` | 80 | The port interfaces the runtime depends on — event store, DLQ, idempotency, enabled-state, scheduler, verifier, subscription. | +| `@netscript/plugin-triggers-core/runtime` | `./src/runtime/mod.ts` | 97 | The runtime factories — `createTriggerIngress`, `createTriggerProcessor`, `createManualDispatcher`, `createEventSubscription`, `defaultRetryPolicy`. | +| `@netscript/plugin-triggers-core/adapters` | `./src/adapters/mod.ts` | 28 | Concrete adapters: the cron scheduler adapter, the file-watcher port, and the HMAC-SHA256 webhook verifier. | +| `@netscript/plugin-triggers-core/stores` | `./src/stores/mod.ts` | 40 | KV-backed store implementations and `openTriggerRuntimeKv`. | +| `@netscript/plugin-triggers-core/config` | `./src/config/mod.ts` | 17 | `defineTriggers` and the trigger configuration schemas. | +| `@netscript/plugin-triggers-core/contracts/v1` | `./src/contracts/v1/mod.ts` | 35 | Version 1 trigger API schemas and contract route types (`triggersContract`, `triggersContractV1`). | +| `@netscript/plugin-triggers-core/telemetry` | `./src/telemetry/mod.ts` | 37 | `createTriggerInstrumentation`, span names, and attribute keys for trigger dispatch. | +| `@netscript/plugin-triggers-core/testing` | `./src/testing/mod.ts` | 79 | In-memory and KV store doubles for deterministic runtime verification. | + +Export counts are the symbol counts `deno doc` reports for each entrypoint; the layered subpaths +re-export shared vocabulary, so the counts overlap rather than sum. + +## Root surface (`@netscript/plugin-triggers-core`) + +### Defining triggers + +Each builder takes the **handler first** and an immutable spec second, and returns a frozen +definition the runtime walker discovers. + +| Symbol | Kind | Description | +| --- | --- | --- | +| `defineWebhook` | function | Define a webhook trigger from a handler and static spec. | +| `WebhookHandler` | type alias | Webhook handler signature used by `defineWebhook`. | +| `WebhookSpec` | type alias | Webhook definition fields accepted by `defineWebhook`. | +| `WebhookDefinition` | type alias | Webhook trigger definition discovered by the runtime walker. | +| `defineScheduledTrigger` | function | Define a scheduled trigger from a handler and static cron spec. | +| `ScheduledTriggerHandler` | type alias | Scheduled trigger handler signature used by `defineScheduledTrigger`. | +| `DefineScheduledTriggerSpec` | type alias | Scheduled trigger definition fields accepted by `defineScheduledTrigger`. | +| `ScheduledTriggerSpec` | type alias | Static scheduled trigger spec consumed by scheduler ports and builders. | +| `ScheduledTriggerDefinition` | type alias | Scheduled trigger definition discovered by the runtime walker. | +| `defineFileWatch` | function | Define a file-watch trigger from a handler and static spec. | +| `FileWatchHandler` | type alias | File-watch handler signature used by `defineFileWatch`. | +| `FileWatchSpec` | type alias | File-watch definition fields accepted by `defineFileWatch`. | +| `FileWatchDefinition` | type alias | File-watch trigger definition discovered by the runtime walker. | +| `FileWatchLifecycle` | type alias | File lifecycle event names supported by file-watch triggers. | +| `FileWatchStabilityThreshold` | type alias | Stability threshold for network-filesystem tolerant file-watch triggers. | +| `CronExpression` | type alias | Cron expression accepted by scheduled trigger definitions. | + +### Handler context and actions + +A handler does not perform work directly; it returns **actions** the dispatcher carries out. + +| Symbol | Kind | Description | +| --- | --- | --- | +| `TriggerContext` | type alias | Context passed to trigger handlers by the processor. | +| `TriggerHandler` | type alias | Handler invoked by the processor for a trigger event. | +| `TriggerActionResult` | type alias | Action result emitted by trigger handlers. | +| `TriggerActionDispatcher` | type alias | Dispatches actions emitted by trigger handlers. | +| `enqueueJob` | function | Create an action that enqueues a typed worker job from a trigger handler. | +| `EnqueueJobAction` | type alias | Action emitted when a trigger should enqueue a worker job. | +| `EnqueueJobOptions` | type alias | Options for dispatching a worker job from a trigger handler. | +| `DeferAction` | type alias | Action emitted when a trigger yields without holding a worker slot. | +| `JobDefinition` | type alias | Root-surface job definition derived from the thin public schema. | +| `JobId` | type alias | Branded worker job identifier. | + +### Definition union and kinds + +| Symbol | Kind | Description | +| --- | --- | --- | +| `TriggerDefinition` | type alias | Trigger definitions known by the Group F public surface. | +| `TriggerDefinitionBase` | type alias | Common immutable fields shared by trigger definitions. | +| `TriggerKind` | type alias | Open trigger discriminator. | +| `TriggerKnownKind` | type alias | Canonical known trigger kind. | +| `TRIGGER_KINDS` | variable | Canonical trigger kinds known by Group F. | +| `ProcessableTriggerDefinition` | type alias | Trigger definition accepted by runtime processor ports. | +| `RuntimeTriggerDefinition` | type alias | Trigger definitions implemented by the Group F runtime. | +| `RuntimeWebhookDefinition` | type alias | Webhook definition shape accepted by the trigger ingress runtime. | +| `TriggerId` | type alias | Branded trigger definition identifier. | +| `WebhookId` | type alias | Branded webhook definition identifier. | + +`TriggerKind` is deliberately **open** while `TriggerKnownKind` is closed: a host may carry a kind the +core does not implement, and only the known kinds narrow into `RuntimeTriggerDefinition`. + +### Payloads + +| Symbol | Kind | Description | +| --- | --- | --- | +| `TriggerPayload` | type alias | Payload union for known Group F trigger kinds. | +| `WebhookTriggerPayload` | type alias | HTTP payload captured by webhook ingress before processing. | +| `ScheduledTriggerPayload` | type alias | Scheduled payload emitted by a scheduler adapter. | +| `FileWatchTriggerPayload` | type alias | Filesystem payload captured by a file-watch adapter. | + +### Reserved kinds + +These are declared in the type surface but **not executed** by the current runtime. They exist so a +host can carry the shape without the core pretending to run it. + +| Symbol | Kind | Description | +| --- | --- | --- | +| `ManualTriggerDefinition` | type alias | Reserved manual trigger definition for CLI/API fire paths. | +| `ManualTriggerPayload` | type alias | Reserved manual-fire payload for CLI and API dispatch. | +| `QueueTriggerDefinition` | type alias | Reserved queue-source trigger definition; runtime execution is deferred. | +| `QueueTriggerPayload` | type alias | Reserved queue-source payload; runtime execution is deferred. | +| `StreamTriggerDefinition` | type alias | Reserved stream-source trigger definition; runtime execution is deferred. | +| `StreamTriggerPayload` | type alias | Reserved stream-source payload; runtime execution is deferred. | + +### Ingress + +| Symbol | Kind | Description | +| --- | --- | --- | +| `createTriggerIngress` | function | Create an ack-then-process webhook ingress boundary. | +| `TriggerIngressPort` | interface | Fast ack-then-process ingress boundary. | +| `TriggerIngressOptions` | type alias | Options accepted by the trigger ingress composition root. | +| `TriggerIngressRequest` | type alias | Ingress request passed to trigger ingress adapters. | +| `TriggerIngressResponse` | type alias | Fast ack response returned by ingress adapters. | +| `TriggerIngressEventIdFactory` | type alias | Generates event ids for accepted ingress events. | + +Ingress **verifies the signature and persists the event before responding**. That ordering is the +contract: a slow handler never blocks the sender, and a crash after the acknowledgement replays from +the stored event rather than losing it. + +### Processor + +| Symbol | Kind | Description | +| --- | --- | --- | +| `createTriggerProcessor` | function | Create a trigger processor runtime from explicit dependencies. | +| `TriggerProcessor` | class | T1 trigger processor with idempotency, retry, concurrency, DLQ, and circuit breaker handling. | +| `TriggerProcessorPort` | interface | Processes unified trigger events through the T1 dispatch pipeline. | +| `TriggerProcessorOptions` | type alias | Options accepted by the trigger processor runtime. | +| `TriggerProcessorStopOptions` | type alias | Stop options for processor drain. | +| `TriggerProcessResult` | type alias | Result returned after processing a trigger event. | + +### Dispatch policies + +| Symbol | Kind | Description | +| --- | --- | --- | +| `TriggerRetryPolicy` | type alias | Retry policy applied by the trigger processor before DLQ handoff. | +| `TriggerConcurrencySpec` | type alias | Bounded dispatch concurrency for a trigger definition. | +| `TriggerDeduplicationSpec` | type alias | Event-boundary deduplication policy. | +| `TriggerCircuitBreakerSpec` | type alias | Circuit breaker policy for repeated trigger dispatch failures. | +| `TriggerDurabilityTier` | type alias | Trigger durability tier. | +| `TRIGGER_DURABILITY_TIERS` | variable | Durability tiers supported by trigger definitions. | + +### Events, stores, and idempotency + +| Symbol | Kind | Description | +| --- | --- | --- | +| `TriggerEvent` | type alias | Unified event envelope consumed by every trigger processor path. | +| `TriggerEventId` | type alias | Branded trigger event identifier. | +| `TriggerEventStatus` | type alias | Trigger event lifecycle status. | +| `TRIGGER_EVENT_STATUSES` | variable | Trigger event lifecycle statuses. | +| `TriggerEventStorePort` | interface | Persistent trigger event store boundary. | +| `TriggerEventListOptions` | type alias | Event store list filters. | +| `TriggerDlqPort` | interface | Dead-letter queue boundary for exhausted trigger events. | +| `TriggerDlqEntry` | type alias | Dead-letter entry recorded after trigger retry exhaustion. | +| `TriggerDlqListOptions` | type alias | Dead-letter list filters. | +| `TriggerIdempotencyPort` | interface | Event-boundary idempotency store with a TTL window. | +| `TriggerIdempotencyClaim` | type alias | Idempotency claim result. | +| `TriggerIdempotencyKeyInput` | type alias | Idempotency key resolution input. | +| `TriggerEnabledStatePort` | interface | Persistent enabled-state boundary for trigger enable/disable routes. | +| `TriggerEnabledStateOverride` | type alias | Stored enabled-state override for a trigger definition. | +| `createKvTriggerEnabledStateStore` | function | Create a KV-backed enabled-state store over the supplied adapter. | + +Every kind — webhook, scheduled, file-watch — converges on the same `TriggerEvent` envelope, which is +why one processor pipeline covers all of them. + +### Live event subscription + +| Symbol | Kind | Description | +| --- | --- | --- | +| `createEventSubscription` | function | Create a single-replica in-process trigger event subscription hub. | +| `TriggerEventSubscriptionPort` | interface | In-process live trigger event subscription boundary. | +| `TriggerEventSubscriptionFilter` | type alias | Subscription filter for live trigger event streams. | +| `TriggerEventSubscriptionMessage` | type alias | Message yielded by trigger event subscription ports. | +| `TriggerEventSubscriptionOptions` | type alias | Subscribe options for live trigger event streams. | +| `TriggerEventSubscriptionType` | type alias | Trigger lifecycle event emitted to live subscribers. | + +`createEventSubscription` is explicitly **single-replica** and in-process: it is a live-tail hub for +one host, not a distributed fan-out. + +### Scheduling + +| Symbol | Kind | Description | +| --- | --- | --- | +| `TriggerSchedulerPort` | interface | Scheduler boundary for scheduled trigger definitions. | +| `TriggerSchedulerStopOptions` | type alias | Scheduler stop options. | +| `ScheduledTriggerHandle` | type alias | Scheduled trigger handle returned by scheduler adapters. | +| `computeNextFireTimes` | function | Compute upcoming fire times for a 5-field scheduled trigger spec. | + +`computeNextFireTimes` is a pure preview over a **5-field** cron spec — it starts no scheduler and is +what the CLI and dashboards use to show "next runs". + +### Manual dispatch + +| Symbol | Kind | Description | +| --- | --- | --- | +| `createManualDispatcher` | function | Create a manual trigger dispatcher from explicit runtime ports. | +| `ManualDispatcher` | interface | Runtime port for explicit manual trigger dispatch. | +| `ManualDispatcherOptions` | type alias | Options accepted by the manual trigger dispatcher factory. | +| `ManualTriggerFireInput` | type alias | Manual trigger fire request consumed by the runtime dispatcher. | +| `ManualTriggerFireResponse` | type alias | Manual trigger fire response returned by the runtime dispatcher. | +| `ManualTriggerEventIdFactory` | type alias | Generates event ids for manual trigger fire events. | + +### Webhook verification and test delivery + +| Symbol | Kind | Description | +| --- | --- | --- | +| `WebhookVerifierPort` | interface | Verifies inbound webhook authenticity and extracts provider event ids. | +| `WebhookVerifierKind` | type alias | Webhook verifier selector declared by a webhook trigger. | +| `WebhookVerificationRequest` | type alias | Request shape passed to a webhook verifier adapter. | +| `WebhookVerificationResult` | type alias | Result returned by a webhook verifier adapter. | +| `createWebhookTestDelivery` | function | Create a webhook test-delivery helper over an ingress port. | +| `WebhookTestDelivery` | interface | Runtime helper for sending signed synthetic webhook test requests. | +| `WebhookTestDeliveryDefinition` | type alias | Webhook definition shape accepted by the test-delivery helper. | +| `WebhookTestDeliveryInput` | type alias | Webhook test delivery request consumed by the runtime helper. | +| `WebhookTestDeliveryOptions` | type alias | Options accepted by the webhook test-delivery helper factory. | +| `WebhookTestDeliveryResponse` | type alias | Webhook test delivery response mapped to the trigger fire contract shape. | + +A verifier extracts the **provider event id** as well as validating the signature; that id is what +lets deduplication recognize the sender's retry as the same event. + +`@netscript/plugin-triggers-core/adapters` ships `HmacSha256WebhookVerifier` as the default +implementation of `WebhookVerifierPort`. + +### Logging + +| Symbol | Kind | Description | +| --- | --- | --- | +| `LoggerPort` | interface | Structured logger boundary consumed by trigger runtime code. | + +## Related pages + +- [`@netscript/plugin-triggers`](/reference/triggers/) — the deployable plugin that binds this core to + a NetScript host. +- [`@netscript/plugin-workers-core`](/reference/plugin-workers-core/) — the job surface `enqueueJob` + hands work to. + +--- + +Back to the [reference overview](/reference/). diff --git a/docs/site/reference/plugin-workers-core/index.md b/docs/site/reference/plugin-workers-core/index.md new file mode 100644 index 0000000000..adcf5219bd --- /dev/null +++ b/docs/site/reference/plugin-workers-core/index.md @@ -0,0 +1,148 @@ +--- +layout: layouts/base.vto +title: "@netscript/plugin-workers-core" +--- + +# `@netscript/plugin-workers-core` + +Job, task, workflow, runtime, config, and testing primitives for NetScript workers plugins. This page +is written against the package's public surface reported by `deno doc`. For the full index of +packages and plugins return to the [reference overview](/reference/). + +Background-job definitions fail in two places: at definition time, when a job is missing an +execution target and nobody notices until production; and at runtime, when the executor and its +storage are welded together and untestable. This package attacks both. `defineJob`, `defineTask`, +and `defineWorkflow` are **typestate-gated** builders — `build()` only exists once an entrypoint or +handler is set, so an incomplete definition is a compile error rather than a runtime surprise. The +runtime composes from injected registry, worker, and storage ports with memory-backed defaults, so +the same definitions run in production and in permission-free tests. + +This is the core that the deployable [`@netscript/plugin-workers`](/reference/workers/) plugin binds +to a NetScript host. Use it directly for custom hosts, libraries, and tests. + +## Entrypoints + +The package publishes seventeen entrypoints. The root path carries the authoring surface; the +subpaths expose the runtime layers a host composes. + +| Export specifier | Module | Exports | Purpose | +| --- | --- | --- | --- | +| `@netscript/plugin-workers-core` | `./mod.ts` | 32 | The authoring surface — the three typestate builders, handler results and tools, schedule and permission presets, inspection, and the runtime entry points (documented below). | +| `@netscript/plugin-workers-core/builders` | `./src/builders/mod.ts` | 28 | The builder layer behind the DSL, including the builder-state types tooling needs. | +| `@netscript/plugin-workers-core/runtime` | `./src/runtime/mod.ts` | 132 | The full runtime: `createWorkersRuntime`, the in-process dispatcher and runner, execution records, and `resolveWorkerIdempotencyKey`. | +| `@netscript/plugin-workers-core/presets` | `./src/presets/mod.ts` | 28 | `startWorkers` and the runtime port shapes its default composition fills in. | +| `@netscript/plugin-workers-core/executor` | `./src/executor/mod.ts` | 33 | The multi-runtime task executor and its per-runtime adapters (Deno, .NET, `cmd`, generic executable) plus `runProcess`. | +| `@netscript/plugin-workers-core/workflow` | `./src/workflow/mod.ts` | 27 | The workflow builder, workflow events, workflow clock, and an in-memory workflow state store. | +| `@netscript/plugin-workers-core/registry` | `./src/registry/mod.ts` | 22 | KV-backed job and task registries with their filter and selector types. | +| `@netscript/plugin-workers-core/state` | `./src/state/mod.ts` | 9 | Execution state: records, statuses, trigger types, and the KV execution state store. | +| `@netscript/plugin-workers-core/stores` | `./src/stores/mod.ts` | 14 | The KV-backed worker idempotency store and its atomic KV primitives. | +| `@netscript/plugin-workers-core/streams` | `./src/streams/mod.ts` | 20 | Durable stream projection of executions and jobs (`workersStreamSchema`, `createWorkersStreamProducer`, the mutation hook). | +| `@netscript/plugin-workers-core/shutdown` | `./src/shutdown/mod.ts` | 5 | `ShutdownManager` and the resource/report types behind graceful drain. | +| `@netscript/plugin-workers-core/schemas` | `./src/domain/public-schema.ts` | 13 | Public structural schemas for worker definitions. | +| `@netscript/plugin-workers-core/contracts/v1` | `./src/contracts/v1/mod.ts` | 27 | Version 1 workers API schemas and contract route types (`workersContract`, `workersContractV1`). | +| `@netscript/plugin-workers-core/config` | `./src/config/mod.ts` | 32 | `defineWorkers`, `defineJobs`, and the queue-provider configuration schemas. | +| `@netscript/plugin-workers-core/telemetry` | `./src/telemetry/mod.ts` | 26 | Worker instrumentation abstractions and `applyWorkerInstrumentations`. | +| `@netscript/plugin-workers-core/abstracts` | `./src/abstracts/mod.ts` | 31 | Abstract runtime contracts and reserved extension-point base classes. | +| `@netscript/plugin-workers-core/testing` | `./src/testing/mod.ts` | 46 | `createTestWorkersRuntime` plus job, result, and execution-record fixtures. | + +Export counts are the symbol counts `deno doc` reports for each entrypoint; the layered subpaths +re-export shared vocabulary, so the counts overlap rather than sum. + +## Root surface (`@netscript/plugin-workers-core`) + +### Definition builders + +Each builder is typestate-gated: `build()` becomes available only after the definition is complete. + +| Symbol | Kind | Description | +| --- | --- | --- | +| `defineJob` | function | Start a worker job definition chain. | +| `JobBuilder` | interface | Root-surface job builder typestate API. | +| `JobDefinition` | type alias | Root-surface job definition derived from the thin public schema. | +| `defineJobHandler` | function | Define a worker job handler. | +| `JobHandlerContext` | type alias | Context passed to root-surface job handlers. | +| `JobResult` | type alias | Result returned by worker job handlers. | +| `JobId` | type alias | Branded worker job identifier. | +| `defineTask` | function | Start a worker task definition chain. | +| `TaskBuilder` | interface | Root-surface task builder typestate API. | +| `TaskDefinition` | type alias | Root-surface task definition derived from the thin public schema. | +| `TaskId` | type alias | Branded worker task identifier. | +| `defineWorkflow` | function | Start a worker workflow definition chain. | +| `WorkflowBuilder` | interface | Root-surface workflow builder typestate API. | +| `WorkflowDefinition` | type alias | Root-surface workflow definition derived from the thin public schema. | + +Jobs and tasks both accept either an in-process handler or a runtime-specific entrypoint; workflows +sequence their definitions. The three builders share the same typestate discipline. + +### Handler results and tools + +| Symbol | Kind | Description | +| --- | --- | --- | +| `createSuccessResult` | function | Create a successful job result. | +| `createFailureResult` | function | Create a failed job result. | +| `createJobTools` | function | Create handler tools backed by the active worker telemetry context. | +| `JobTools` | type alias | Runtime tools exposed to worker job handlers. | +| `JobToolSpan` | type alias | Span operations exposed to worker job handlers. | + +`JobTools` is how a handler reaches telemetry without importing an SDK: the span operations it +exposes are bound to the active worker instrumentation context. + +### Schedules and permissions + +| Symbol | Kind | Description | +| --- | --- | --- | +| `cron` | variable | Cron schedule helpers for worker jobs. | +| `CronHelpers` | type alias | Cron schedule helper surface for worker jobs. | +| `permissions` | variable | Permission presets for worker jobs and tasks. | +| `PermissionPresets` | type alias | Worker permission preset surface for common job execution modes. | + +### Runtime + +| Symbol | Kind | Description | +| --- | --- | --- | +| `startWorkers` | function | Create and start a workers runtime using default composition. | +| `createWorkersRuntime` | function | Create an unstarted workers runtime with the root surface's minimal options. | + +Two entry styles for one runtime: root `startWorkers()` creates and starts the memory-backed preset, +while root `createWorkersRuntime()` creates the same runtime without starting it. Import +`createWorkersRuntime` from `/runtime` when registries, executors, storage, or other runtime ports +must be injected explicitly. + +### Inspection + +| Symbol | Kind | Description | +| --- | --- | --- | +| `inspectJob` | function | Inspect a job definition without starting a runtime. | +| `inspectTask` | function | Inspect a task definition without starting a runtime. | +| `inspectWorkflow` | function | Inspect a workflow definition without starting a runtime. | + +These are what CLI listings and doctor checks call: they read a definition and report on it without +starting a runtime or touching storage. + +### Idempotency + +| Symbol | Kind | Description | +| --- | --- | --- | +| `WorkerIdempotencyPort` | interface | Durable applied-keys store used to make worker effects exactly-once-effective. | +| `WorkerIdempotencyInput` | type alias | Input used to resolve and claim an applied key for one worker delivery. | +| `WorkerIdempotencyClaim` | type alias | Result returned when a worker delivery attempts to claim an applied key. | +| `WorkerIdempotencySource` | type alias | How a worker delivery idempotency key was resolved. | + +Delivery is at-least-once; effects are exactly-once-effective. A key is resolved from a caller-supplied +key, the message id, or a payload hash — `WorkerIdempotencySource` records which — and then claimed +against the port before the effect runs. + +## Related pages + +- [`@netscript/plugin-workers`](/reference/workers/) — the deployable plugin that binds this core to a + NetScript host. +- [`@netscript/plugin-triggers-core`](/reference/plugin-triggers-core/) — trigger handlers enqueue + these jobs through `enqueueJob`. +- [`@netscript/plugin-sagas-core`](/reference/plugin-sagas-core/) — its `integration/workers` helpers + dispatch jobs and tasks from saga cascades. +- [`@netscript/plugin-streams-core`](/reference/plugin-streams-core/) — the producer behind the + projected execution stream. + +--- + +Back to the [reference overview](/reference/). diff --git a/docs/site/reference/plugin/index.md b/docs/site/reference/plugin/index.md index f27f07d58a..aea4bf37b6 100644 --- a/docs/site/reference/plugin/index.md +++ b/docs/site/reference/plugin/index.md @@ -5,8 +5,8 @@ title: "@netscript/plugin" # `@netscript/plugin` -Plugin manifest, validation, discovery, and host-context contracts for NetScript. This page -is generated from the package's public surface with `deno doc` (US-2). For the full index of +Plugin manifest, validation, discovery, and host-context contracts for NetScript. This page is +written against the package's public surface reported by `deno doc`. For the full index of packages and plugins return to the [reference overview](/reference/). The root entrypoint (`@netscript/plugin`) is the plugin authoring contract: the diff --git a/docs/site/reference/queue/index.md b/docs/site/reference/queue/index.md index 0bceaf2a94..6e11d446d4 100644 --- a/docs/site/reference/queue/index.md +++ b/docs/site/reference/queue/index.md @@ -8,8 +8,8 @@ title: "@netscript/queue" Provider-agnostic message queue abstraction for NetScript applications. It wraps [Fedify](https://fedify.dev/) battle-tested queue adapters behind a single, unified `MessageQueue` interface with optional Zod validation and Aspire-based backend -auto-discovery. This page is generated from the package public surface with `deno doc` -(US-2). For the full index of packages and plugins return to the +auto-discovery. This page is written against the package public surface reported by `deno doc`. +For the full index of packages and plugins return to the [reference overview](/reference/). The root entrypoint (`@netscript/queue`) re-exports the factory functions, the port diff --git a/docs/site/reference/runtime-config/index.md b/docs/site/reference/runtime-config/index.md index 578a3d26f2..4013aa006d 100644 --- a/docs/site/reference/runtime-config/index.md +++ b/docs/site/reference/runtime-config/index.md @@ -5,8 +5,8 @@ title: "@netscript/runtime-config" # `@netscript/runtime-config` -Hot-reloadable NetScript runtime override types, loaders, watchers, and diagnostics. This page -is generated from the package's public surface with `deno doc` (US-2). For the full index of +Hot-reloadable NetScript runtime override types, loaders, watchers, and diagnostics. This page is +written against the package's public surface reported by `deno doc`. For the full index of packages and plugins return to the [reference overview](/reference/). Runtime config files live under the configured runtime directory and are loaded through a diff --git a/docs/site/reference/sagas/index.md b/docs/site/reference/sagas/index.md index 6f53e11da9..9e8d79c705 100644 --- a/docs/site/reference/sagas/index.md +++ b/docs/site/reference/sagas/index.md @@ -6,18 +6,19 @@ title: "@netscript/plugin-sagas" # `@netscript/plugin-sagas` NetScript plugin for durable saga orchestration, workflow APIs, and saga runtime metadata. -This page is generated from the package's public surface with `deno doc` (US-2). For the full +This page is written against the package's public surface reported by `deno doc`. For the full index of packages and plugins return to the [reference overview](/reference/). The published plugin exposes the host-facing plugin manifest, the executable saga runtime and supervisor, the HTTP publisher, the versioned API contract, and the browser-safe stream surface. The userland saga DSL (`defineSaga`, the cascaded-message constructors) is authored against -[`@netscript/plugin-sagas-core`](#internals) and re-exported through the runtime entrypoint; the -core package is documented as an [Internals](#internals) subsection below. +[`@netscript/plugin-sagas-core`](/reference/plugin-sagas-core/) and re-exported through the runtime +entrypoint. That separately published package has its own canonical reference page. ## Entrypoints -The plugin publishes the following entrypoints. Each is generated from its own `deno doc` surface. +The plugin publishes the following entrypoints. Each is documented against its own `deno doc` +surface. | Export | Entrypoint | Purpose | | --- | --- | --- | @@ -52,7 +53,7 @@ is provided by `inspectPlugin` from `@netscript/plugin`. The runtime entrypoint provides the executable saga runtime and the building blocks a composition root wires together. It also re-exports the userland DSL types and cascaded-message vocabulary from -[`@netscript/plugin-sagas-core`](#internals). +[`@netscript/plugin-sagas-core`](/reference/plugin-sagas-core/). ### Runtime entry functions and classes @@ -145,82 +146,17 @@ Browser-safe stream exports for the sagas plugin. --- -## Internals +## Core package -> The following surface belongs to `@netscript/plugin-sagas-core`, the framework-internal package -> that implements the saga DSL, runtime ports, adapters, telemetry, config, and testing primitives. -> Application authors normally import these symbols through `@netscript/plugin-sagas`; the core -> package is documented here for completeness (US-8). It is not a separate top-level reference entry. +The separately published +[`@netscript/plugin-sagas-core`](/reference/plugin-sagas-core/) page is canonical for the saga DSL, +runtime ports, adapters, telemetry, configuration, and testing exports. This page stays focused on +the deployable plugin's manifest and integration entrypoints. The testing example below uses the core +package intentionally; exhaustive core entrypoint and symbol tables live only on its reference page. -### `@netscript/plugin-sagas-core` - -Saga DSL, runtime ports, adapters, telemetry, config, and testing primitives for NetScript sagas -plugins. Its root entrypoint (`./mod.ts`) is the authoring surface for saga definitions. - -#### DSL constructors (root export) - -| Symbol | Kind | Signature | Description | -| --- | --- | --- | --- | -| `defineSaga` | function | `defineSaga(id: TId): SagaBuilder` | Start a userland saga definition chain. | -| `defineQuery` | function | `defineQuery(name: TName): QueryDefinition` | Define a synchronous read-only query for a running saga instance. | -| `defineSignal` | function | `defineSignal(name: TName): SignalDefinition` | Define a signal that can be sent to a running saga instance. | -| `send` | function | `send(target, payload: unknown, options?: SendOptions): CascadedMessage` | Republish an internal message onto the saga bus; does not trigger workers. | -| `spawn` | function | `spawn(child, input: unknown, options?: SpawnOptions): never` | Unsupported; calling it immediately throws `SAGA_NOT_IMPLEMENTED`. Deserialized spawn effects are also rejected defensively. | -| `schedule` | function | `schedule(message, delay: SagaScheduleDelay): CascadedMessage` | Create a cascaded scheduled message. | -| `sagaComplete` | function | `sagaComplete(result: unknown): CascadedMessage` | Create a terminal saga completion message. | -| `sagaFail` | function | `sagaFail(reason): CascadedMessage` | Create a terminal saga failure message. | -| `sagaCompensate` | function | `sagaCompensate(message, reason: string): CascadedMessage` | Create a cascaded compensation message. | - -#### DSL types (root export) - -| Symbol | Kind | Description | -| --- | --- | --- | -| `SagaBuilder` | interface | Userland fluent saga builder. | -| `SagaBuilderPhase` | type alias | Typestate phase for the userland saga builder. | -| `SagaEvent` | type alias | Event shape inferred by `defineSaga().on(type, handler)`. | -| `SagaHandler` | type alias | Synchronous saga handler that returns cascaded messages. | -| `SagaState` | type alias | Base state shape accepted by saga definitions. | -| `SagaConcurrencyOptions` / `SagaConcurrencyPolicy` | type alias | Concurrency options/policy for a saga definition. | -| `CascadedMessage` / `CascadedMessageKind` / `CascadedMessageTarget` | type alias | Cascaded-message side-effect ledger vocabulary. | -| `QueryDefinition` / `SignalDefinition` | type alias | Query/signal definitions reserved by the public DSL. | -| `SendOptions` / `SpawnOptions` / `SagaScheduleDelay` | type alias | Constructor options; `SpawnOptions` is retained for the unsupported, always-throwing `spawn()` call. | - -#### Core sub-path entrypoints - -| Export | Entrypoint | Purpose | -| --- | --- | --- | -| `@netscript/plugin-sagas-core` | `./mod.ts` | DSL constructors and types (documented above). | -| `@netscript/plugin-sagas-core/builders` | `./src/builders/mod.ts` | Fluent `defineSaga` builder and DSL constructors. | -| `@netscript/plugin-sagas-core/domain` | `./src/domain/mod.ts` | Domain primitives, `SagasError`, defaults, and branded ids. | -| `@netscript/plugin-sagas-core/ports` | `./src/ports/mod.ts` | Runtime port interfaces (`SagaBusPort`, `SagaStorePort`, idempotency). | -| `@netscript/plugin-sagas-core/runtime` | `./src/runtime/mod.ts` | Native runtime engine wiring consumed by the plugin runtime. | -| `@netscript/plugin-sagas-core/adapters` | `./src/adapters/mod.ts` | Bus/store adapters. | -| `@netscript/plugin-sagas-core/transports` | `./src/transports/mod.ts` | Transport implementations. | -| `@netscript/plugin-sagas-core/stores` | `./src/stores/mod.ts` | State store implementations. | -| `@netscript/plugin-sagas-core/middleware` | `./src/middleware/mod.ts` | Saga middleware primitives. | -| `@netscript/plugin-sagas-core/telemetry` | `./src/telemetry/mod.ts` | Saga telemetry instrumentation. | -| `@netscript/plugin-sagas-core/config` | `./src/config/mod.ts` | Saga runtime configuration. | -| `@netscript/plugin-sagas-core/contracts/v1` | `./src/contracts/v1/mod.ts` | Core contract primitives. | -| `@netscript/plugin-sagas-core/streams` | `./src/streams/mod.ts` | Core stream schema primitives. | -| `@netscript/plugin-sagas-core/presets` | `./src/presets/mod.ts` | Runtime presets. | -| `@netscript/plugin-sagas-core/abstracts` | `./src/abstracts/mod.ts` | Abstract base primitives. | -| `@netscript/plugin-sagas-core/testing` | `./src/testing/mod.ts` | Deterministic saga test helpers. | -| `@netscript/plugin-sagas-core/agent` | `./src/agent/mod.ts` | Agent-integration primitives. | -| `@netscript/plugin-sagas-core/integration/workers` | `./src/integration/workers/mod.ts` | Workers integration seam. | -| `@netscript/plugin-sagas-core/integration/publisher` | `./src/integration/publisher/mod.ts` | Publisher integration seam. | - -#### Domain primitives (`@netscript/plugin-sagas-core/domain`) - -| Symbol | Kind | Description | -| --- | --- | --- | -| `SagasError` | class | Structured error thrown by sagas core APIs. | -| `SAGAS_ERROR_CODES` / `SagasErrorCode` | variable / type | Error codes produced by `SagasError`. | -| `DEFAULT_RETRY_POLICY` | variable | Default retry policy used when a saga does not override retry behavior. | -| `DEFAULT_SAGA_DURABILITY_TIER` | variable | Default durability tier for saga definitions. | -| `DEFAULT_RETRY_MAX_ATTEMPTS` | variable | Default maximum retry attempts for cascaded messages. | -| `DEFAULT_IDEMPOTENCY_WINDOW_MS` | variable | Default idempotency deduplication window in milliseconds. | -| `SAGA_ADAPTER_KINDS` / `SagaAdapterKind` | variable / type | Runtime adapter kinds supported by `createSagaRuntime`. | -| `SagaMessageType` | type alias | Extracts the message type discriminator from a saga message. | +The unsupported `spawn(child, input, options?: SpawnOptions): never` contract is worth calling out: +it throws immediately rather than starting a child saga. Its full description and every other core +symbol live on the canonical core page. ## Deterministic Testing diff --git a/docs/site/reference/sdk/index.md b/docs/site/reference/sdk/index.md index d0848e42ce..eabb2bbe0d 100644 --- a/docs/site/reference/sdk/index.md +++ b/docs/site/reference/sdk/index.md @@ -5,8 +5,8 @@ title: "@netscript/sdk" # `@netscript/sdk` -Service discovery, oRPC clients, and cache-backed query factories for NetScript. This page -is generated from the package's public surface with `deno doc` (US-2). For the full index of +Service discovery, oRPC clients, and cache-backed query factories for NetScript. This page is +written against the package's public surface reported by `deno doc`. For the full index of packages and plugins return to the [reference overview](/reference/). The root entrypoint (`@netscript/sdk`) is the high-level composition preset for service-aware diff --git a/docs/site/reference/service/index.md b/docs/site/reference/service/index.md index 87c616f8df..1156c14d13 100644 --- a/docs/site/reference/service/index.md +++ b/docs/site/reference/service/index.md @@ -6,8 +6,8 @@ title: "@netscript/service" # `@netscript/service` Service bootstrap builders, health probes, and Hono/oRPC runtime wiring for NetScript -applications. This page is generated from the package's public surface with `deno doc` -(US-2). For the full index of packages and plugins return to the +applications. This page is written against the package's public surface reported by `deno doc`. +For the full index of packages and plugins return to the [reference overview](/reference/). The package has three layers. **Layer 1** exposes small primitives for health, error, RPC, diff --git a/docs/site/reference/streams/index.md b/docs/site/reference/streams/index.md index 27f5d8cd95..166fc63059 100644 --- a/docs/site/reference/streams/index.md +++ b/docs/site/reference/streams/index.md @@ -8,7 +8,7 @@ templateEngine: [vento, md] Durable Streams development plugin for NetScript: a plugin manifest plus CLI, scaffolding, end-to-end gate, and Aspire integration surfaces for a durable, change-data stream service. This -page is generated from the plugin public surface with `deno doc` (US-2). For the full index of +page is written against the plugin public surface reported by `deno doc`. For the full index of packages and plugins return to the [reference overview](/reference/). The plugin ships five published entrypoints. The root export (`@netscript/plugin-streams`) carries @@ -20,9 +20,10 @@ the framework integrations: - [`@netscript/plugin-streams/e2e`](#sub-path-e2e) — E2E gate definitions. - [`@netscript/plugin-streams/aspire`](#sub-path-aspire) — Aspire AppHost contribution. -The schema, producer, telemetry, testing, and diagnostics primitives that the plugin builds on -live in the internal `@netscript/plugin-streams-core` package, documented in -[Internals](#internals) below. +The schema, producer, telemetry, testing, and diagnostics primitives that the plugin builds on live +in the separately published +[`@netscript/plugin-streams-core`](/reference/plugin-streams-core/) package, which has its own +canonical reference page. ## Plugin manifest @@ -47,7 +48,7 @@ live in the internal `@netscript/plugin-streams-core` package, documented in > A producer's `publish()` returns a rejected promise and a consumer's `subscribe()` throws > synchronously, both with `StreamUnsupportedOperationError`. For real producer work use > `createDurableStream` (or the Service-facing `createServiceStreamProducer`) and `defineStreamSchema` -> from [`@netscript/plugin-streams-core`](#internals). See the +> from [`@netscript/plugin-streams-core`](/reference/plugin-streams-core/). See the > [durable streams capability page](/capabilities/streams/) for the full producer/consumer model. > **Browser consumers read over HTTP/SSE.** There is no in-process `subscribe()`; a browser @@ -127,71 +128,13 @@ The remaining symbols on this entrypoint (`AspireBuilder`, `AspireResource`, `As `DenoServiceSpec`, `DenoBackgroundSpec`, `HealthCheckSpec`, `EnvSource`) are re-exported unchanged from [`@netscript/aspire`](/reference/aspire/); see that reference page for their definitions. -## Internals +## Core package -The following surface belongs to the internal **`@netscript/plugin-streams-core`** package. It is a -supporting package — not part of the public plugin contract — and is documented here per the -single-page internals convention (US-8). It provides the schema, producer, configuration, -telemetry, testing, and diagnostics primitives that `@netscript/plugin-streams` builds on. Its root -export is `@netscript/plugin-streams-core` with two sub-path exports (`/telemetry`, `/testing`). - -### Schema and producers (`@netscript/plugin-streams-core`) - -| Symbol | Kind | Signature | Description | -| --- | --- | --- | --- | -| `defineStreamSchema` | function | `function defineStreamSchema(collections): StateSchema` | Define a type-safe durable stream schema. | -| `createDurableStream` | function | `function createDurableStream(options): DurableStreamProducer` | Create or reuse a durable stream producer for a stream path. | -| `createServiceStreamProducer` | function | `function createServiceStreamProducer(options): DurableStreamProducer` | Blessed Service-facing producer factory. Wraps `createDurableStream` reusing `getStreamsUrl`/`getStreamsAuth`; a missing `streams` reference **throws at construction** instead of blocking or silently dropping writes. Install streams and run `netscript service generate` to reconcile a missing reference. | -| `DurableStreamProducer` | class | `class DurableStreamProducer` | Server-side writer for a named durable stream. | -| `DurableStreamProducerOptions` | interface | `interface DurableStreamProducerOptions` | Options accepted by `createDurableStream` / `DurableStreamProducer`. | -| `ServiceStreamProducerOptions` | interface | `interface ServiceStreamProducerOptions extends DurableStreamProducerOptions` | Options for `createServiceStreamProducer`; it has the same fields as `DurableStreamProducerOptions`. | -| `StreamProducerPort` | interface | `interface StreamProducerPort` | Port implemented by stream producers that publish State Protocol changes. | -| `inspectStreamTopic` | function | `function inspectStreamTopic(input): StreamTopicInspectionReport` | Inspect a stream schema and optional producer metadata. | -| `StreamTopicInspectionInput` | interface | `interface StreamTopicInspectionInput` | Input accepted by `inspectStreamTopic`. | -| `StreamTopicInspectionReport` | interface | `interface StreamTopicInspectionReport` | Diagnostic report returned by `inspectStreamTopic`. | - -#### Configuration helpers - -| Symbol | Kind | Signature | Description | -| --- | --- | --- | --- | -| `getStreamsUrl` | function | `function getStreamsUrl(): string` | Resolve the base URL of the durable streams server. | -| `getStreamsAuth` | function | `function getStreamsAuth(): Record` | Resolve authentication headers for the durable streams server. | -| `buildStreamUrl` | function | `function buildStreamUrl(path, baseUrl): string` | Build the full stream URL for a NetScript stream path. | - -#### Schema and event types - -| Symbol | Kind | Description | -| --- | --- | --- | -| `StateSchema` | type alias | Schema map returned by `defineStreamSchema`. | -| `StreamStateDefinition` | type alias | Input map accepted by `defineStreamSchema`. | -| `CollectionDefinition` | interface | A single collection definition inside a durable stream schema. | -| `CollectionWithHelpers` | type alias | Collection definition after durable-streams helper methods are attached. | -| `CollectionEventHelpers` | interface | Helper methods attached to collections by `@durable-streams/state`. | -| `StateEvent` | type alias | Durable stream event union. | -| `ChangeEvent` | interface | Entity change event emitted by durable stream producers. | -| `ControlEvent` | interface | Control event emitted by durable streams for non-entity lifecycle changes. | -| `Operation` | type alias | State Protocol operation names supported by durable streams. | - -### Telemetry (`@netscript/plugin-streams-core/telemetry`) - -| Symbol | Kind | Signature | Description | -| --- | --- | --- | --- | -| `streamsInstrumentation` | variable | `const streamsInstrumentation: StreamsInstrumentationRegistration` | Telemetry registration for stream publish, consume, and subscribe spans. | -| `StreamsInstrumentationRegistration` | interface | `interface StreamsInstrumentationRegistration` | Minimal instrumentation contract understood by NetScript telemetry hosts. | -| `STREAMS_SPAN_NAMES` | variable | `const STREAMS_SPAN_NAMES` | Span names emitted by stream producers and consumers. | -| `STREAMS_TELEMETRY_ATTRIBUTES` | variable | `const STREAMS_TELEMETRY_ATTRIBUTES` | Attribute keys used by stream telemetry. | -| `StreamsSpanName` | type alias | Span name emitted by stream instrumentation. | -| `StreamsTelemetryAttributeKey` | type alias | Attribute key used by stream telemetry. | -| `StreamsTelemetryAttributes` | type alias | Attribute bag accepted by stream instrumentation hooks. | - -### Testing (`@netscript/plugin-streams-core/testing`) - -| Symbol | Kind | Signature | Description | -| --- | --- | --- | --- | -| `MemoryStreamProducer` | class | `class MemoryStreamProducer` | In-memory stream producer for tests that should not open network sockets. | -| `MemoryStreamEvent` | interface | `interface MemoryStreamEvent` | Event recorded by `MemoryStreamProducer`. | -| `createStreamTopicFixture` | function | `function createStreamTopicFixture(): StreamTopicFixtureSchema` | Create a small stream schema fixture with one `execution` collection. | -| `StreamTopicFixtureSchema` | type alias | Schema shape returned by `createStreamTopicFixture`. | +The separately published +[`@netscript/plugin-streams-core`](/reference/plugin-streams-core/) page is canonical for stream +schemas, producers, configuration, telemetry, testing, and diagnostics. This page stays focused on +the deployable plugin's manifest and integration entrypoints. The testing example below uses core +APIs intentionally; exhaustive core entrypoint and symbol tables live only on its reference page. ## Socket-Free Testing and Telemetry diff --git a/docs/site/reference/telemetry/index.md b/docs/site/reference/telemetry/index.md index 4193193005..667d08596a 100644 --- a/docs/site/reference/telemetry/index.md +++ b/docs/site/reference/telemetry/index.md @@ -6,8 +6,8 @@ title: '@netscript/telemetry' # `@netscript/telemetry` OpenTelemetry tracing primitives, context propagation, instrumentation registries, and NetScript -runtime adapters for jobs, queues, RPC, and SSE. This page is generated from the package's public -surface with `deno doc` (US-2). For the full index of packages and plugins return to the +runtime adapters for jobs, queues, RPC, and SSE. This page is written against the package's public +surface reported by `deno doc`. For the full index of packages and plugins return to the [reference overview](/reference/). The root entrypoint (`@netscript/telemetry`) exposes the stable package diagnostic and @@ -209,8 +209,8 @@ Tracing and error-handling plugins for the NetScript oRPC handler. ## Sub-path exports -The following entrypoints are published alongside the root export. Each is generated from its own -`deno doc` surface. +The following entrypoints are published alongside the root export. Each is documented against its +own `deno doc` surface. | Export | Entrypoint | Purpose | | -------------------------------------- | ---------------------- | ------------------------------------------------------------------- | diff --git a/docs/site/reference/triggers/index.md b/docs/site/reference/triggers/index.md index df25799208..8338f453cd 100644 --- a/docs/site/reference/triggers/index.md +++ b/docs/site/reference/triggers/index.md @@ -6,18 +6,19 @@ title: "@netscript/plugin-triggers" # `@netscript/plugin-triggers` NetScript plugin for trigger ingress, scheduling, file watching, and the trigger runtime APIs. -This page is generated from the package's public surface with `deno doc` (US-2). For the full +This page is written against the package's public surface reported by `deno doc`. For the full index of packages and plugins return to the [reference overview](/reference/). The plugin's root entrypoint (`@netscript/plugin-triggers`) exposes the public **plugin manifest** surface — the manifest value and its metadata constants. Shared manifest inspection is provided by `inspectPlugin` from `@netscript/plugin`. The handler-first authoring DSL (`defineWebhook`, `defineScheduledTrigger`, `defineFileWatch`, `enqueueJob`) and the runtime ports live in the sibling -core package and are documented in [Internals](#internals) below. +[`@netscript/plugin-triggers-core`](/reference/plugin-triggers-core/) package, which has its own +canonical reference page. Additional integration entrypoints are published as [sub-path exports](#sub-path-exports): `./public`, `./plugin`, `./runtime`, `./scaffolding`, `./aspire`, `./cli`, `./services`, -`./streams`, and `./streams/server`. Their reference detail is generated from their own +`./streams`, and `./streams/server`. Their reference detail is documented against their own `deno doc` surface. ## Plugin manifest @@ -91,152 +92,14 @@ The following entrypoints are published alongside the root export. --- -## Internals +## Core package -> **Internals — `@netscript/plugin-triggers-core`.** This section documents the sibling **core** -> package that backs the triggers plugin. It is the implementation surface: the handler-first -> trigger DSL, the trigger runtime (ingress + processor), the runtime ports, configuration -> schemas, and deterministic testing primitives. Application code that authors trigger -> definitions imports the DSL from here; everything below is generated from -> `@netscript/plugin-triggers-core`'s own `deno doc` surface (US-8). - -### Authoring DSL - -| Symbol | Signature | Description | -| --- | --- | --- | -| `defineWebhook` | `function defineWebhook(handler: WebhookHandler, spec: WebhookSpec): WebhookDefinition` | Define a webhook trigger from a handler and static spec. | -| `defineScheduledTrigger` | `function defineScheduledTrigger(handler: ScheduledTriggerHandler, spec: DefineScheduledTriggerSpec): ScheduledTriggerDefinition` | Define a scheduled trigger from a handler and static cron spec. | -| `defineFileWatch` | `function defineFileWatch(handler: FileWatchHandler, spec: FileWatchSpec): FileWatchDefinition` | Define a file-watch trigger from a handler and static spec. | -| `enqueueJob` | `function enqueueJob(job: JobDefinition, options: EnqueueJobOptions): EnqueueJobAction` | Create an action that enqueues a typed worker job from a trigger handler. | - -### Runtime - -| Symbol | Signature | Description | -| --- | --- | --- | -| `createTriggerIngress` | `function createTriggerIngress(options: TriggerIngressOptions): TriggerIngressPort` | Create an ack-then-process webhook ingress boundary. | -| `createTriggerProcessor` | `function createTriggerProcessor(options: TriggerProcessorOptions): TriggerProcessor` | Create a trigger processor runtime from explicit dependencies. | -| `TriggerProcessor` | class | T1 trigger processor with idempotency, retry, concurrency, DLQ, and circuit breaker handling. | - -### Runtime ports - -| Symbol | Kind | Description | -| --- | --- | --- | -| `TriggerIngressPort` | interface | Fast ack-then-process ingress boundary. | -| `TriggerProcessorPort` | interface | Processes unified trigger events through the T1 dispatch pipeline. | -| `TriggerSchedulerPort` | interface | Scheduler boundary for scheduled trigger definitions. | -| `TriggerEventStorePort` | interface | Persistent trigger event store boundary. | -| `TriggerIdempotencyPort` | interface | Event-boundary idempotency store with a TTL window. | -| `TriggerDlqPort` | interface | Dead-letter queue boundary for exhausted trigger events. | -| `WebhookVerifierPort` | interface | Verifies inbound webhook authenticity and extracts provider event ids. | -| `LoggerPort` | interface | Structured logger boundary consumed by trigger runtime code. | -| `TriggerActionDispatcher` | type alias | Dispatches actions emitted by trigger handlers. | -| `TriggerIngressEventIdFactory` | type alias | Generates event ids for accepted ingress events. | -| `TriggerIngressOptions` | type alias | Options accepted by the trigger ingress composition root. | -| `TriggerProcessorOptions` | type alias | Options accepted by the trigger processor runtime. | - -### Trigger definitions and payloads - -| Symbol | Kind | Description | -| --- | --- | --- | -| `TriggerDefinition` | type alias | Trigger definitions known by the Group F public surface. | -| `RuntimeTriggerDefinition` | type alias | Trigger definitions implemented by the Group F runtime. | -| `ProcessableTriggerDefinition` | type alias | Trigger definition accepted by runtime processor ports. | -| `WebhookDefinition` | type alias | Webhook trigger definition discovered by the runtime walker. | -| `ScheduledTriggerDefinition` | type alias | Scheduled trigger definition discovered by the runtime walker. | -| `FileWatchDefinition` | type alias | File-watch trigger definition discovered by the runtime walker. | -| `ManualTriggerDefinition` | type alias | Reserved manual trigger definition for CLI/API fire paths. | -| `QueueTriggerDefinition` | type alias | Reserved queue-source trigger definition. Runtime execution is deferred. | -| `StreamTriggerDefinition` | type alias | Reserved stream-source trigger definition. Runtime execution is deferred. | -| `TriggerDefinitionBase` | type alias | Common immutable fields shared by trigger definitions. | -| `WebhookSpec` | type alias | Webhook definition fields accepted by `defineWebhook`. | -| `ScheduledTriggerSpec` | type alias | Static scheduled trigger spec consumed by scheduler ports and builders. | -| `DefineScheduledTriggerSpec` | type alias | Scheduled trigger definition fields accepted by `defineScheduledTrigger`. | -| `FileWatchSpec` | type alias | File-watch definition fields accepted by `defineFileWatch`. | -| `WebhookHandler` | type alias | Webhook handler signature used by `defineWebhook`. | -| `ScheduledTriggerHandler` | type alias | Scheduled trigger handler signature used by `defineScheduledTrigger`. | -| `FileWatchHandler` | type alias | File-watch handler signature used by `defineFileWatch`. | -| `TriggerHandler` | type alias | Handler invoked by the processor for a trigger event. | -| `TriggerContext` | type alias | Context passed to trigger handlers by the processor. | -| `TriggerEvent` | type alias | Unified event envelope consumed by every trigger processor path. | -| `TriggerPayload` | type alias | Payload union for known Group F trigger kinds. | -| `WebhookTriggerPayload` | type alias | HTTP payload captured by webhook ingress before processing. | -| `ScheduledTriggerPayload` | type alias | Scheduled payload emitted by a scheduler adapter. | -| `FileWatchTriggerPayload` | type alias | Filesystem payload captured by a file-watch adapter. | -| `ManualTriggerPayload` | type alias | Reserved manual-fire payload for CLI and API dispatch. | -| `QueueTriggerPayload` | type alias | Reserved queue-source payload. Runtime execution is deferred. | -| `StreamTriggerPayload` | type alias | Reserved stream-source payload. Runtime execution is deferred. | -| `FileWatchLifecycle` | type alias | File lifecycle event names supported by file-watch triggers. | -| `FileWatchStabilityThreshold` | type alias | Stability threshold for network-filesystem tolerant file-watch triggers. | - -### Actions, policies, and branded ids - -| Symbol | Kind | Description | -| --- | --- | --- | -| `TriggerActionResult` | type alias | Action result emitted by trigger handlers. | -| `EnqueueJobAction` | type alias | Action emitted when a trigger should enqueue a worker job. | -| `EnqueueJobOptions` | type alias | Options for dispatching a worker job from a trigger handler. | -| `DeferAction` | type alias | Action emitted when a trigger yields without holding a worker slot. | -| `JobDefinition` | type alias | Root-surface job definition derived from the thin public schema. | -| `TriggerRetryPolicy` | type alias | Retry policy applied by the trigger processor before DLQ handoff. | -| `TriggerCircuitBreakerSpec` | type alias | Circuit breaker policy for repeated trigger dispatch failures. | -| `TriggerConcurrencySpec` | type alias | Bounded dispatch concurrency for a trigger definition. | -| `TriggerDeduplicationSpec` | type alias | Event-boundary deduplication policy. | -| `TriggerDurabilityTier` | type alias | Trigger durability tier. | -| `CronExpression` | type alias | Cron expression accepted by scheduled trigger definitions. | -| `TriggerKind` | type alias | Open trigger discriminator. | -| `TriggerKnownKind` | type alias | Canonical known trigger kind. | -| `TriggerEventStatus` | type alias | Trigger event lifecycle status. | -| `TriggerId` | type alias | Branded trigger definition identifier. | -| `TriggerEventId` | type alias | Branded trigger event identifier. | -| `WebhookId` | type alias | Branded webhook definition identifier. | -| `JobId` | type alias | Branded worker job identifier. | -| `WebhookVerifierKind` | type alias | Webhook verifier selector declared by a webhook trigger. | -| `RuntimeWebhookDefinition` | type alias | Webhook definition shape accepted by the trigger ingress runtime. | - -### Runtime constants - -| Symbol | Description | -| --- | --- | -| `TRIGGER_KINDS` | Canonical trigger kinds known by Group F. | -| `TRIGGER_EVENT_STATUSES` | Trigger event lifecycle statuses. | -| `TRIGGER_DURABILITY_TIERS` | Durability tiers supported by trigger definitions. | - -### DLQ, event-store, and idempotency support types - -| Symbol | Kind | Description | -| --- | --- | --- | -| `TriggerDlqEntry` | type alias | Dead-letter entry recorded after trigger retry exhaustion. | -| `TriggerDlqListOptions` | type alias | Dead-letter list filters. | -| `TriggerEventListOptions` | type alias | Event store list filters. | -| `TriggerIdempotencyClaim` | type alias | Idempotency claim result. | -| `TriggerIdempotencyKeyInput` | type alias | Idempotency key resolution input. | -| `TriggerIngressRequest` | type alias | Ingress request passed to trigger ingress adapters. | -| `TriggerIngressResponse` | type alias | Fast ack response returned by ingress adapters. | -| `TriggerProcessResult` | type alias | Result returned after processing a trigger event. | -| `TriggerProcessorStopOptions` | type alias | Stop options for processor drain. | -| `TriggerSchedulerStopOptions` | type alias | Scheduler stop options. | -| `ScheduledTriggerHandle` | type alias | Scheduled trigger handle returned by scheduler adapters. | -| `WebhookVerificationRequest` | type alias | Request shape passed to a webhook verifier adapter. | -| `WebhookVerificationResult` | type alias | Result returned by a webhook verifier adapter. | - -### Internals sub-path exports - -The core package publishes the following sub-path entrypoints. Each is generated from its own -`deno doc` surface. - -| Export | Entrypoint | Purpose | -| --- | --- | --- | -| `@netscript/plugin-triggers-core` | `./mod.ts` | Curated root surface (DSL, runtime, ports, types — documented above). | -| `@netscript/plugin-triggers-core/public` | `./src/public/mod.ts` | Public root re-export. | -| `@netscript/plugin-triggers-core/builders` | `./src/builders/mod.ts` | Handler-first definition builders (`defineWebhook`, `defineScheduledTrigger`, `defineFileWatch`, `enqueueJob`) and `TRIGGER_*` constants. | -| `@netscript/plugin-triggers-core/config` | `./src/config/mod.ts` | `netscript.config.ts` trigger schemas and `defineTriggers`. | -| `@netscript/plugin-triggers-core/domain` | `./src/domain/mod.ts` | Domain definitions, payloads, and branded ids. | -| `@netscript/plugin-triggers-core/ports` | `./src/ports/mod.ts` | Runtime port boundaries. | -| `@netscript/plugin-triggers-core/runtime` | `./src/runtime/mod.ts` | Ingress and processor runtime. | -| `@netscript/plugin-triggers-core/adapters` | `./src/adapters/mod.ts` | Concrete port adapters. | -| `@netscript/plugin-triggers-core/telemetry` | `./src/telemetry/mod.ts` | Trigger telemetry instrumentation. | -| `@netscript/plugin-triggers-core/contracts/v1` | `./src/contracts/v1/mod.ts` | Versioned wire contracts. | -| `@netscript/plugin-triggers-core/testing` | `./src/testing/mod.ts` | Deterministic in-memory adapters, stores, and clock for trigger tests. | +The separately published +[`@netscript/plugin-triggers-core`](/reference/plugin-triggers-core/) page is canonical for the +handler-first DSL, ingress and processor runtimes, ports, configuration, and testing exports. This +page stays focused on the deployable plugin's manifest and integration entrypoints. The testing +example below uses core APIs intentionally; exhaustive core entrypoint and symbol tables live only +on its reference page. ## Testing and Verification diff --git a/docs/site/reference/watchers/index.md b/docs/site/reference/watchers/index.md index 9e089345fe..3032c55499 100644 --- a/docs/site/reference/watchers/index.md +++ b/docs/site/reference/watchers/index.md @@ -7,8 +7,8 @@ title: "@netscript/watchers" Reusable file-watching primitives for NetScript: composable strategies, filters, and a pipeline-based `FileWatcher` for detecting file-system changes across local and network -filesystems. This page is generated from the package's public surface with `deno doc` -(US-2). For the full index of packages and plugins return to the +filesystems. This page is written against the package's public surface reported by `deno doc`. +For the full index of packages and plugins return to the [reference overview](/reference/). The package exposes a single root entrypoint (`@netscript/watchers` -> `./mod.ts`). There are diff --git a/docs/site/reference/workers/index.md b/docs/site/reference/workers/index.md index 5faf6fa623..2cef1b5a6c 100644 --- a/docs/site/reference/workers/index.md +++ b/docs/site/reference/workers/index.md @@ -7,13 +7,13 @@ title: "@netscript/plugin-workers" The NetScript background-workers plugin: background jobs, task execution, workflow orchestration, a Workers API service, CLI commands, scaffolding, durable streams, and Aspire -process wiring. This page is generated from the package public surface with `deno doc` -(US-2). For the full index of packages and plugins return to the +process wiring. This page is written against the package public surface reported by `deno doc`. +For the full index of packages and plugins return to the [reference overview](/reference/). The deployable plugin (`@netscript/plugin-workers`) binds the host plugin system to the reusable worker primitives that live in -[`@netscript/plugin-workers-core`](#internals-netscriptplugin-workers-core). The plugin root +[`@netscript/plugin-workers-core`](/reference/plugin-workers-core/). The plugin root entrypoint exposes the plugin manifest and a pure inspection helper; framework integrations are carried by sub-path exports documented below. @@ -269,547 +269,14 @@ The long-running runtime processes: the `Worker` job/task consumer and the cron | `WorkerTaskResult` | type alias | Task execution result surface consumed by the worker process. | | `WorkerPoolOptions` | type alias | Options for the plugin-layer in-process job runner pool. | -## Internals: `@netscript/plugin-workers-core` {#internals-netscriptplugin-workers-core} +## Core package -> **Internals.** The `@netscript/plugin-workers-core` package holds the reusable worker -> definition builders, runtime composition, registries, executors, and testing primitives that -> `@netscript/plugin-workers` binds to the host. It is published separately and may be imported -> directly, but most applications consume it through the plugin above (US-8). The surface below -> is generated from its own `deno doc` exports. - -### `@netscript/plugin-workers-core` - -Root entrypoint: the thin public definition builders, runtime starters, and inspection helpers. - -| Symbol | Kind | Description | -| --- | --- | --- | -| `defineJob` | function | Start a worker job definition chain. | -| `defineTask` | function | Start a worker task definition chain. | -| `defineWorkflow` | function | Start a worker workflow definition chain. | -| `cron` | variable | Cron schedule helpers for worker jobs. | -| `permissions` | variable | Permission presets for worker jobs and tasks. | -| `defineJobHandler` | function | Define a worker job handler. | -| `createWorkersRuntime` | function | Create a fresh workers runtime from explicit dependencies. | -| `createFailureResult` | function | Create a failed job result. | -| `createSuccessResult` | function | Create a successful job result. | -| `startWorkers` | function | Create and start a workers runtime using default composition. | -| `inspectJob` | function | Inspect a job definition without starting a runtime. | -| `inspectTask` | function | Inspect a task definition without starting a runtime. | -| `inspectWorkflow` | function | Inspect a workflow definition without starting a runtime. | -| `JobId` | type alias | Branded worker job identifier. | -| `TaskId` | type alias | Branded worker task identifier. | -| `CronHelpers` | type alias | Cron schedule helper surface for worker jobs. | -| `PermissionPresets` | type alias | Worker permission preset surface for common job execution modes. | -| `JobBuilder` | interface | Root-surface job builder typestate API. | -| `JobDefinition` | type alias | Root-surface job definition derived from the thin public schema. | -| `JobHandlerContext` | type alias | Context passed to root-surface job handlers. | -| `JobResult` | type alias | Result returned by worker job handlers. | -| `TaskBuilder` | interface | Root-surface task builder typestate API. | -| `TaskDefinition` | type alias | Root-surface task definition derived from the thin public schema. | -| `WorkflowBuilder` | interface | Root-surface workflow builder typestate API. | -| `WorkflowDefinition` | type alias | Root-surface workflow definition derived from the thin public schema. | - -### `@netscript/plugin-workers-core/builders` - -Typestate builders for jobs, tasks, and workflows. - -| Symbol | Kind | Description | -| --- | --- | --- | -| `defineJob` | function | Start a worker job definition chain. | -| `JobBuilder` | interface | Typestate builder interface for job definitions. | -| `JobBuilderState` | type alias | Job builder state used to gate `build()`. | -| `RetryOptions` | type alias | Retry configuration options for job definitions. | -| `JobRetentionOptions` | type alias | Execution retention settings for job definitions. | -| `defineTask` | function | Start a worker task definition chain. | -| `TaskBuilder` | interface | Typestate builder interface for task definitions. | -| `TaskBuilderState` | type alias | Task builder state used to gate `build()`. | -| `defineWorkflow` | function | Start a worker workflow definition chain. | -| `WorkflowBuilder` | interface | Typestate builder interface for workflow definitions. | -| `WorkflowBuilderState` | type alias | Workflow builder state used to gate `build()`. | -| `WorkflowJobStepOptions` | type alias | Options for adding a job-backed workflow step. | -| `WorkflowTaskStepOptions` | type alias | Options for adding a task-backed workflow step. | -| `BuilderPermissions` | interface | Deno permission set accepted by job and task builders. | -| `BuilderPermissionValue` | type alias | Permission value accepted by job and task builders. | -| `BuilderTaskType` | type alias | Runtime used to execute a task built by the task builder. | -| `JobDefinition` | interface | Public job definition produced by the job builder. | -| `JobHandler` | type alias | Function that executes a job. | -| `JobHandlerContext` | interface | Context passed to job handlers declared with the builder. | -| `JobId` | type alias | Branded worker job identifier used by builder surfaces. | -| `JobResult` | type alias | Worker job handler result. | -| `TaskDefinition` | interface | Public task definition produced by the task builder. | -| `TaskHandler` | type alias | Function that executes a task. | -| `TaskId` | type alias | Branded worker task identifier used by builder surfaces. | -| `WorkflowDefinition` | interface | Public workflow definition produced by the workflow builder. | -| `WorkflowId` | type alias | Branded worker workflow identifier used by builder surfaces. | -| `WorkflowStep` | type alias | Single workflow step produced by the workflow builder. | -| `CronExpression` | type alias | Cron expression type used by worker schedules. | - -### `@netscript/plugin-workers-core/contracts/v1` - -Versioned worker service contract schemas and types (the source of the plugin contracts export). - -| Symbol | Kind | Description | -| --- | --- | --- | -| `ExecutionFiltersSchema` | variable | Schema for list-executions filters. | -| `ExecutionRecordResponseSchema` | variable | Schema for worker execution record responses. | -| `JobCreateInputSchema` | variable | Schema for creating worker job definitions. | -| `JobDefinitionResponseSchema` | variable | Schema for worker job definition responses. | -| `JobFiltersSchema` | variable | Schema for list-jobs filters. | -| `JobTriggerInputSchema` | variable | Schema for triggering a worker job by id. | -| `JobUpdateInputSchema` | variable | Schema for updating worker job definitions. | -| `JobUpdateWithIdSchema` | variable | Schema for updating a worker job definition by id. | -| `SSEEventSchema` | variable | Schema for server-sent event payloads emitted by the workers service. | -| `TaskDefinitionResponseSchema` | variable | Schema for worker task definition responses. | -| `TaskFiltersSchema` | variable | Schema for list-tasks filters. | -| `workersContract` | variable | Worker service contract definition for client generation. | -| `workersContractV1` | variable | Context-bindable worker service contract definition. | -| `ContractProcedureLike` | type alias | Structural oRPC procedure reference used by worker contracts. | -| `ContractSchema` | interface | Package-owned structural schema surface for worker contracts. | -| `ContractSchemaResult` | type alias | Result returned by contract schema validation. | -| `ExecutionRecordResponse` | type alias | Public response returned for worker execution records. | -| `JobDefinitionResponse` | type alias | Public response returned for worker job definitions. | -| `JobTriggerInput` | type alias | Input accepted by the trigger-job procedure. | -| `JobTriggerOutput` | type alias | Output returned by the trigger-job procedure. | -| `SSEEvent` | type alias | Server-sent event payload emitted by the workers service. | -| `StandardSchemaLike` | type alias | Structural Standard Schema reference used by contract metadata. | -| `TaskDefinitionResponse` | type alias | Public response returned for worker task definitions. | -| `TaskTriggerInput` | type alias | Input accepted by the trigger-task procedure. | -| `TaskTriggerOutput` | type alias | Output returned by the trigger-task procedure. | -| `WorkersContract` | type alias | Explicit public contract shape for worker service clients. | -| `WorkersContractV1` | type alias | Context-binding contract wrapper for the v1 worker contract. | -| `WorkersRouteHandler` | type alias | Structural route handler exposed by the implemented worker router. | -| `WorkersRouter` | type alias | Structural worker router returned after binding a context. | - -### `@netscript/plugin-workers-core/registry` - -KV-backed and in-memory job/task registries. - -| Symbol | Kind | Description | -| --- | --- | --- | -| `KvJobRegistry` | class | KV-backed job registry for runtime composition. | -| `KvTaskRegistry` | class | KV-backed task registry for runtime composition. | -| `MemoryJobRegistry` | class | In-memory job registry for tests and local composition. | -| `Registry` | class | Generic registry base for named worker definitions. | -| `JobFilterOptions` | type alias | Filters accepted when listing worker jobs. | -| `TaskFilterOptions` | type alias | Filters accepted when listing worker tasks. | -| `ExecutionRecord` | type alias | Execution record shape stored by job registries. | -| `JobDefinition` | type alias | Job definition shape stored by registries. | -| `JobSource` | type alias | Job source value accepted by registry filters. | -| `RegisterJobInput` | type alias | Input accepted when registering a job. | -| `RegisterTaskInput` | type alias | Input accepted when registering a task. | -| `RegistryJobStoragePort` | type alias | Storage contract implemented by job registries. | -| `RuntimePermissions` | type alias | Runtime permission bag accepted by registry task and job definitions. | -| `RuntimePermissionValue` | type alias | Runtime permission value accepted by registry task and job definitions. | -| `TaskDefinition` | type alias | Task definition shape stored by registries. | -| `TaskSource` | type alias | Task source value accepted by registry filters. | -| `KvEntry` | type alias | Deno KV-compatible entry shape. | -| `KvListSelector` | type alias | Deno KV-compatible list selector. | -| `RegistryKvStore` | interface | Minimal KV shape consumed by registry adapters. | -| `RegistryOptions` | type alias | Registry adapter options. | - -### `@netscript/plugin-workers-core/state` - -KV-backed worker execution-state store. - -| Symbol | Kind | Description | -| --- | --- | --- | -| `KvExecutionState` | class | KV-backed execution state store with explicit construction. | -| `CompleteExecutionOptions` | type alias | Options for completing a worker execution record. | -| `CreateExecutionOptions` | type alias | Options for creating a worker execution record. | -| `ExecutionConcept` | type alias | Execution concept discriminator. | -| `ExecutionMutationHook` | type alias | Hook invoked after execution state mutations. | -| `ExecutionRecord` | type alias | Worker execution record stored in KV. | -| `ExecutionStatus` | type alias | Execution status discriminator. | -| `ExecutionTriggerType` | type alias | Execution trigger discriminator. | -| `ListExecutionOptions` | type alias | Options for listing worker execution records. | - -### `@netscript/plugin-workers-core/executor` - -Multi-runtime task executor and per-runtime adapters. - -| Symbol | Kind | Description | -| --- | --- | --- | -| `TaskExecutor` | class | Stub-only contract for the workers task orchestrator. | -| `TaskRuntimeAdapter` | class | Stub-only contract for a single task runtime adapter. | -| `CmdRuntimeAdapter` | class | Runtime adapter for Windows cmd tasks. | -| `DaxProcessRunner` | class | Run task subprocesses through Dax with streaming output capture. | -| `DenoRuntimeAdapter` | class | Runtime adapter for Deno task scripts. | -| `DotNetRuntimeAdapter` | class | Runtime adapter for .NET task programs. | -| `ExecutableRuntimeAdapter` | class | Runtime adapter for direct executable tasks. | -| `PowerShellRuntimeAdapter` | class | Runtime adapter for PowerShell task scripts. | -| `PythonRuntimeAdapter` | class | Runtime adapter for Python task scripts. | -| `runProcess` | function | Run a subprocess through Dax with result capture and log callbacks. | -| `RuntimeAdapterBase` | class | Shared adapter delegation for built-in subprocess runtimes. | -| `ShellRuntimeAdapter` | class | Runtime adapter for POSIX or Git Bash shell scripts. | -| `EnvironmentReader` | type alias | Function used by command builders to read process environment. | -| `ProcessRunInput` | type alias | Process runner input shared by built-in runtime adapters. | -| `ProcessRunner` | interface | Subprocess primitive used by runtime adapters. | -| `RuntimeCommandBuildContext` | type alias | Context passed to runtime command builders. | -| `RuntimeCommandSpec` | type alias | Command and arguments prepared for a task runtime adapter. | -| `RuntimeTaskMetadata` | type alias | Runtime-specific task metadata recognized by built-in adapters. | -| `createDefaultRuntimeAdapterMap` | function | Create the default built-in runtime adapter map. | -| `createDefaultTaskExecutor` | function | Create the default executor with all built-in runtime adapters. | -| `MultiRuntimeTaskExecutor` | class | Dispatches task execution to runtime-specific adapters. | -| `ResolvedTaskExecutionOptions` | type alias | Execution options resolved by the task orchestrator before adapter dispatch. | -| `TaskDefinition` | type alias | Task definition shape consumed by executor adapters. | -| `TaskExecutionOptions` | type alias | Options supplied to a task execution. | -| `TaskInstrumentationLike` | type alias | Executor instrumentation hook shape. | -| `TaskInstrumentationSpan` | type alias | Span shape accepted by executor instrumentation hooks. | -| `TaskLogEntry` | type alias | Log entry emitted while a task subprocess is running. | -| `TaskResult` | type alias | Result returned by task execution. | -| `TaskRuntimeAdapterLike` | type alias | Task adapter contract consumed by the multi-runtime executor. | -| `TaskType` | type alias | Worker task runtime identifier supported by built-in adapters. | -| `WorkerTaskPermissionField` | type alias | Permission field accepted by Deno task execution. | -| `WorkerTaskPermissions` | type alias | Permission set accepted by Deno task execution. | -| `MultiRuntimeTaskExecutorOptions` | type alias | Options for the default multi-runtime task executor. | - -### `@netscript/plugin-workers-core/workflow` - -Workflow executor, step runner, and durable state store. - -| Symbol | Kind | Description | -| --- | --- | --- | -| `defineWorkflow` | function | Start a worker workflow definition chain. | -| `WorkflowBuilder` | interface | Typestate builder interface for workflow definitions. | -| `WorkflowBuilderState` | type alias | Workflow builder state used to gate `build()`. | -| `WorkflowJobStepOptions` | type alias | Options for adding a job-backed workflow step. | -| `WorkflowTaskStepOptions` | type alias | Options for adding a task-backed workflow step. | -| `WorkflowExecutor` | class | Executes workflow definitions as explicit durable state machines. | -| `WorkflowExecutorOptions` | type alias | Options for creating a workflow executor. | -| `MemoryWorkflowStateStore` | class | In-memory workflow state store for tests and local runtime composition. | -| `WorkflowClock` | type alias | Clock contract used by workflow runtime code. | -| `WorkflowStateStore` | interface | Store contract for durable workflow state and routed events. | -| `WorkflowStepRunner` | class | Executes individual workflow steps through explicit runtime callbacks. | -| `WorkflowJobStepRunner` | type alias | Function that executes a job-backed workflow step. | -| `WorkflowStepRunnerOptions` | type alias | Options for executing workflow steps. | -| `WorkflowTaskStepRunner` | type alias | Function that executes a task-backed workflow step. | -| `JobId` | type alias | Branded worker job identifier used by builder surfaces. | -| `TaskId` | type alias | Branded worker task identifier used by builder surfaces. | -| `WorkflowDefinition` | interface | Public workflow definition produced by the workflow builder. | -| `WorkflowEvent` | type alias | Event routed to a workflow execution. | -| `WorkflowExecutionOptions` | type alias | Options supplied when starting a workflow execution. | -| `WorkflowExecutionStatus` | type alias | Workflow execution lifecycle status. | -| `WorkflowId` | type alias | Branded worker workflow identifier used by builder surfaces. | -| `WorkflowResults` | type alias | Map of workflow step results by step id. | -| `WorkflowState` | type alias | Durable workflow execution state. | -| `WorkflowStep` | type alias | Single workflow step produced by the workflow builder. | -| `WorkflowStepKind` | type alias | Workflow step kind. | -| `WorkflowStepResult` | type alias | Result produced by a workflow step. | -| `WorkflowStepStatus` | type alias | Workflow step lifecycle status. | - -### `@netscript/plugin-workers-core/streams` - -Server-side durable stream producer and execution-state mirror hooks. - -| Symbol | Kind | Description | -| --- | --- | --- | -| `createStreamMutationHook` | function | Create a mutation hook that mirrors execution state into the durable stream. | -| `createWorkersStreamProducer` | function | Create a workers durable stream producer for execution and job entities. | -| `emitJobToStream` | function | Emit a job entity to the workers durable stream. | -| `toExecutionStreamEntity` | function | Convert an execution record into the durable stream execution entity shape. | -| `ExecutionMutation` | type alias | Execution-state mutation published to the workers durable stream. | -| `ExecutionMutationHook` | type alias | Hook called when execution state changes. | -| `WorkerExecutionRecord` | type alias | Execution record shape mirrored into the workers durable stream. | -| `WorkersStreamProducer` | type alias | Durable stream producer type for the workers stream schema. | -| `WorkersStreamProducerOptions` | type alias | Options for creating a workers durable stream producer. | -| `WorkerExecutionSchema` | variable | Stream entity schema for worker executions. | -| `WorkerJobSchema` | variable | Stream entity schema for worker jobs. | -| `workersStreamSchema` | variable | Stream schema definition for worker executions and jobs. | -| `StreamSchemaDefinition` | type alias | Structural stream schema definition map. | -| `WorkerExecution` | type alias | Worker execution entity stored in the durable stream. | -| `WorkerJob` | type alias | Worker job entity stored in the durable stream. | -| `WorkersStreamDefinition` | type alias | Durable stream definition for worker execution and job entities. | -| `WorkersStreamSchema` | type alias | Package-owned structural workers stream schema surface. | -| `WorkerStreamCollectionDefinition` | interface | Package-owned structural stream collection definition. | -| `WorkerStreamEntitySchema` | interface | Package-owned structural schema surface for worker stream entities. | -| `WorkerStreamStandardSchema` | interface | Standard Schema compatible public schema surface for stream entities. | - -### `@netscript/plugin-workers-core/presets` - -Default composition preset (`startWorkers`) and runtime port contracts. - -| Symbol | Kind | Description | -| --- | --- | --- | -| `startWorkers` | function | Create and start a workers runtime using default composition. | -| `StartWorkersOptions` | type alias | Options for the default workers startup preset. | -| `ExecutionRecord` | type alias | Runtime execution record. | -| `JobContext` | type alias | Context supplied to runtime job handlers. | -| `JobDefinition` | type alias | Runtime job definition. | -| `JobHandler` | type alias | Function that executes a runtime job. | -| `JobMessage` | type alias | Message enqueued to trigger a job execution. | -| `JobResult` | type alias | Result returned by runtime job handlers. | -| `RuntimeJobStoragePort` | type alias | Runtime job storage contract. | -| `RuntimeSchedulerPort` | type alias | Runtime scheduler contract. | -| `RuntimeShutdownManager` | type alias | Runtime shutdown manager contract. | -| `RuntimeShutdownOptions` | type alias | Runtime shutdown configuration. | -| `RuntimeShutdownResource` | type alias | Resource managed during runtime shutdown. | -| `RuntimeTaskExecutor` | type alias | Runtime task executor contract. | -| `RuntimeTaskExecutorOptions` | type alias | Runtime task executor configuration. | -| `RuntimeWorkerPort` | type alias | Runtime worker dispatch contract. | -| `RuntimeWorkflowDefinition` | type alias | Runtime workflow definition accepted by composition. | -| `RuntimeWorkflowExecutor` | type alias | Runtime workflow executor contract. | -| `RuntimeWorkflowOptions` | type alias | Runtime workflow executor options. | -| `StaticJobRegistry` | type alias | Registry of statically imported runtime job handlers. | -| `TaskDefinition` | type alias | Runtime task definition. | -| `TaskExecutionOptions` | type alias | Options supplied when executing a task. | -| `TaskRegistryPort` | type alias | Registry contract for task definitions. | -| `TaskResult` | type alias | Result returned by task execution. | -| `WorkersClock` | type alias | Clock contract used by runtime tests and schedulers. | -| `WorkersRuntime` | type alias | Runtime handle returned by the workers composition root. | -| `WorkersRuntimeOptions` | type alias | Explicit dependencies and overrides for a workers runtime instance. | -| `WorkflowId` | type alias | Runtime workflow identifier. | - -### `@netscript/plugin-workers-core/shutdown` - -Graceful shutdown manager for runtime resources. - -| Symbol | Kind | Description | -| --- | --- | --- | -| `ShutdownManager` | class | Coordinates graceful shutdown for runtime resources. | -| `ShutdownManagerOptions` | type alias | Options for creating or invoking a shutdown manager. | -| `ShutdownReport` | type alias | Result returned after a shutdown attempt. | -| `ShutdownResource` | type alias | Resource registered for graceful shutdown. | -| `ShutdownState` | type alias | Resource lifecycle state managed during shutdown. | - -### `@netscript/plugin-workers-core/schemas` - -Thin public definition schemas for the root quick-start surface. - -| Symbol | Kind | Description | -| --- | --- | --- | -| `PublicStandardSchema` | interface | Standard Schema compatible public schema surface. | -| `PublicDefinitionSchemaShape` | type alias | Structural object-shape map used by public definition schemas. | -| `PublicDefinitionSchema` | interface | Package-owned structural schema surface for public definition schemas. | -| `PublicJobDefinitionOutput` | type alias | Thin public job definition output. | -| `PublicTaskDefinitionOutput` | type alias | Thin public task definition output. | -| `PublicWorkflowDefinitionOutput` | type alias | Thin public workflow definition output. | -| `JobDefinitionPublicBaseSchema` | variable | Public base schema for thin job definitions. | -| `TaskDefinitionPublicBaseSchema` | variable | Public base schema for thin task definitions. | -| `WorkflowDefinitionPublicBaseSchema` | variable | Public base schema for thin workflow definitions. | -| `PublicJobDefinitionSchema` | variable | Thin public job definition schema for root-level quick-start APIs. | -| `PublicTaskDefinitionSchema` | variable | Thin public task definition schema for root-level quick-start APIs. | -| `PublicWorkflowDefinitionSchema` | variable | Thin public workflow definition schema for root-level quick-start APIs. | - -### `@netscript/plugin-workers-core/telemetry` - -Worker telemetry span/attribute names and instrumentation classes. - -| Symbol | Kind | Description | -| --- | --- | --- | -| `WorkerSpanNames` | variable | Worker telemetry span names. | -| `WorkerTelemetryAttributes` | variable | Worker telemetry attribute names. | -| `WorkerTelemetryEvents` | variable | Worker telemetry event names. | -| `WorkerTelemetryStatuses` | variable | Worker execution statuses used in telemetry attributes. | -| `WorkerSpanName` | type alias | Worker telemetry span name. | -| `WorkerTelemetryAttribute` | type alias | Worker telemetry attribute name. | -| `WorkerTelemetryEvent` | type alias | Worker telemetry event name. | -| `WorkerTelemetryStatus` | type alias | Worker telemetry status. | -| `applyWorkerInstrumentations` | function | Applies a set of worker instrumentation instances to a span. | -| `JobExecuteInstrumentation` | class | Adds common job execution attributes and lifecycle events. | -| `JobMainInstrumentation` | class | Adds job-main attributes used inside a job handler span. | -| `QueueDequeueInstrumentation` | class | Adds queue dequeue attributes for consumer spans. | -| `QueueEnqueueInstrumentation` | class | Adds queue enqueue attributes for producer spans. | -| `TaskExecuteInstrumentation` | class | Adds task execution attributes and lifecycle events. | -| `WorkerInstrumentation` | class | Base class for workers telemetry instrumentation. | -| `TaskInstrumentation` | class | Stub-only contract for task-scoped worker telemetry instrumentation. | -| `AbstractWorkerInstrumentation` | class | Stub-only contract for worker telemetry instrumentation. | -| `AbstractWorkerInstrumentationContext` | type alias | Context supplied to worker instrumentation hooks. | -| `AbstractWorkerInstrumentationSpan` | type alias | Span shape accepted by worker instrumentation hooks. | -| `InstrumentationContext` | type alias | Context passed to worker instrumentation instances. | -| `TelemetryAttributes` | type alias | Attribute map accepted by worker telemetry instrumentation. | -| `TelemetryAttributeValue` | type alias | Attribute value accepted by worker telemetry instrumentation. | -| `WorkerTelemetrySpan` | interface | Structural span contract used by workers core without binding to one tracer package. | - -### `@netscript/plugin-workers-core/abstracts` - -Stub-only abstract contracts shared across worker subsystems. - -| Symbol | Kind | Description | -| --- | --- | --- | -| `JobDispatcher` | class | Stub-only contract for job dispatchers. | -| `JobLifecycleAdapter` | class | Stub-only contract for job lifecycle adapters. | -| `JobScheduler` | class | Stub-only contract for job schedulers. | -| `Registry` | class | Stub-only contract for keyed workers registries. | -| `TaskInstrumentation` | class | Stub-only contract for task-scoped worker telemetry instrumentation. | -| `TaskExecutor` | class | Stub-only contract for the workers task orchestrator. | -| `TaskRuntimeAdapter` | class | Stub-only contract for a single task runtime adapter. | -| `WorkerInstrumentation` | class | Stub-only contract for worker telemetry instrumentation. | -| `CliCommand` | class | Stub-only base contract for CLI command implementations. | -| `WorkersCommand` | class | Stub-only contract for workers CLI commands. | -| `WorkersItemScaffolder` | class | Stub-only contract for generated workers items. | -| `DisposeContext` | interface | Job disposal context. | -| `InitContext` | interface | Job initialization context. | -| `DispatchContext` | interface | Runtime dispatch context supplied to scheduled jobs. | -| `ExecutionContext` | interface | Execution context shared by worker runtime dispatchers. | -| `ResolvedTaskExecutionOptions` | type alias | Execution options resolved by the task orchestrator before adapter dispatch. | -| `RuntimeTaskMetadata` | type alias | Runtime-specific task metadata recognized by built-in adapters. | -| `TaskDefinition` | type alias | Task definition shape consumed by executor adapters. | -| `TaskExecutionOptions` | type alias | Options supplied to a task execution. | -| `TaskLogEntry` | type alias | Log entry emitted while a task subprocess is running. | -| `TaskResult` | type alias | Result returned by task execution. | -| `TaskType` | type alias | Worker task runtime identifier supported by built-in adapters. | -| `WorkerTaskPermissionField` | type alias | Permission field accepted by Deno task execution. | -| `WorkerTaskPermissions` | type alias | Permission set accepted by Deno task execution. | -| `JobContext` | type alias | Context supplied to runtime job handlers. | -| `JobDefinition` | type alias | Runtime job definition. | -| `JobHandler` | type alias | Function that executes a runtime job. | -| `JobResult` | type alias | Result returned by runtime job handlers. | -| `WorkerInstrumentationContext` | type alias | Context supplied to worker instrumentation hooks. | -| `WorkerInstrumentationSpan` | type alias | Span shape accepted by worker instrumentation hooks. | -| `WorkersCommandDefinition` | interface | Definition supplied to worker CLI commands. | - -### `@netscript/plugin-workers-core/testing` - -Fixtures and memory-backed runtime for tests. - -| Symbol | Kind | Description | -| --- | --- | --- | -| `createExecutionRecordFixture` | function | Create an execution record with realistic defaults. | -| `createJobFixture` | function | Create a runnable job definition for tests. | -| `createJobResultFixture` | function | Create a successful job result for fixture handlers. | -| `createTestWorkersRuntime` | function | Create a test runtime with memory-backed storage and worker ports. | -| `ExecutionRecordFixtureOptions` | type alias | Partial execution record fields used to override fixture defaults. | -| `JobFixtureOptions` | type alias | Options for creating a test job definition. | -| `TestWorkersRuntime` | type alias | Workers runtime fixture with direct access to memory ports. | -| `TestWorkersRuntimeOptions` | type alias | Options for creating a memory-backed workers runtime fixture. | -| `MemoryJobRegistry` | class | In-memory job registry for tests and local composition. | -| `MemoryJobStorage` | class | In-memory job storage for package consumers and tests. | -| `MemoryWorker` | class | In-memory worker port that records dispatches and executes registered handlers. | -| `MemoryWorkerDispatch` | type alias | Recorded memory-worker dispatch with the job, context, and result. | -| `MemoryWorkerOptions` | type alias | Options for constructing an in-memory worker. | -| `ExecutionRecord` | type alias | Execution record shape stored by job registries. | -| `RegistryJobDefinition` | type alias | Job definition shape stored by registries. | -| `RegistryJobSource` | type alias | Job source value accepted by registry filters. | -| `RegistryRegisterJobInput` | type alias | Input accepted when registering a job. | -| `Registry` | class | Generic registry base for named worker definitions. | -| `RegistryJobStoragePort` | type alias | Storage contract implemented by job registries. | -| `RuntimeExecutionRecord` | type alias | Runtime execution record. | -| `JobContext` | type alias | Context supplied to runtime job handlers. | -| `JobDefinition` | type alias | Runtime job definition. | -| `JobHandler` | type alias | Function that executes a runtime job. | -| `JobMessage` | type alias | Message enqueued to trigger a job execution. | -| `JobResult` | type alias | Result returned by runtime job handlers. | -| `RuntimeJobStoragePort` | type alias | Runtime job storage contract. | -| `RuntimeSchedulerPort` | type alias | Runtime scheduler contract. | -| `RuntimeShutdownManager` | type alias | Runtime shutdown manager contract. | -| `RuntimeShutdownOptions` | type alias | Runtime shutdown configuration. | -| `RuntimeShutdownResource` | type alias | Resource managed during runtime shutdown. | -| `RuntimeTaskExecutor` | type alias | Runtime task executor contract. | -| `RuntimeTaskExecutorOptions` | type alias | Runtime task executor configuration. | -| `RuntimeWorkerPort` | type alias | Runtime worker dispatch contract. | -| `RuntimeWorkflowDefinition` | type alias | Runtime workflow definition accepted by composition. | -| `RuntimeWorkflowExecutor` | type alias | Runtime workflow executor contract. | -| `RuntimeWorkflowOptions` | type alias | Runtime workflow executor options. | -| `StaticJobRegistry` | type alias | Registry of statically imported runtime job handlers. | -| `TaskDefinition` | type alias | Runtime task definition. | -| `TaskExecutionOptions` | type alias | Options supplied when executing a task. | -| `TaskRegistryPort` | type alias | Registry contract for task definitions. | -| `TaskResult` | type alias | Result returned by task execution. | -| `WorkersClock` | type alias | Clock contract used by runtime tests and schedulers. | -| `WorkersRuntime` | type alias | Runtime handle returned by the workers composition root. | -| `WorkersRuntimeOptions` | type alias | Explicit dependencies and overrides for a workers runtime instance. | -| `WorkflowId` | type alias | Runtime workflow identifier. | - -### `@netscript/plugin-workers-core/config` - -Worker config file schemas plus defineWorkers and defineJobs helpers. - -| Symbol | Kind | Description | -| --- | --- | --- | -| `ConfigSchema` | interface | Package-owned structural schema type for worker config validation. | -| `ConfigSchemaResult` | type alias | Result returned by a package-owned schema parse attempt. | -| `JobConfigSchema` | variable | Worker job configuration schema. | -| `RetentionConfigSchema` | variable | Retention settings for worker job executions. | -| `JobConfig` | interface | Worker job configuration. | -| `RetentionConfig` | interface | Retention settings for worker job executions. | -| `WorkerConfigPermissions` | interface | Partial Deno permission set accepted by worker config files. | -| `WorkerConfigPermissionValue` | type alias | Permission value accepted by worker config files. | -| `WorkerJobSource` | type alias | Origin of a worker job definition. | -| `TaskConfigSchema` | variable | Runtime task configuration. | -| `TaskConfig` | interface | Runtime task configuration. | -| `WorkerTaskSource` | type alias | Origin of a worker task definition. | -| `WorkerTaskType` | type alias | Runtime used to execute a task. | -| `defineJobs` | function | Define a per-topic job array. | -| `defineWorkers` | function | Define a split worker config module. | -| `QueueProviderSchema` | variable | Queue provider configuration schema. | -| `ScalingConfigSchema` | variable | Per-topic scaling configuration schema. | -| `TopicRetentionConfigSchema` | variable | Per-topic retention policy schema. | -| `WorkerGroupSchema` | variable | Worker group configuration schema. | -| `WorkersConfigSchema` | variable | Workers plugin configuration schema. | -| `JobConfigInput` | type alias | Authoring form for a worker job before schema defaults are applied. | -| `QueueProvider` | type alias | Queue backend provider selector. | -| `QueueProviderData` | type alias | Queue backend provider selector. | -| `ScalingConfig` | type alias | Per-topic worker scaling configuration. | -| `ScalingConfigData` | interface | Per-topic worker scaling configuration. | -| `TopicRetentionConfig` | type alias | Per-topic worker retention configuration. | -| `TopicRetentionConfigData` | interface | Per-topic retention policy configuration. | -| `WorkerGroup` | type alias | Worker group configuration for a topic. | -| `WorkerGroupData` | interface | Worker group configuration for a topic. | -| `WorkersConfig` | type alias | Workers configuration section. | -| `WorkersConfigData` | interface | Workers configuration section. | -| `WorkersConfigInput` | interface | Authoring form for split worker config files before schema defaults are applied. | - -### `@netscript/plugin-workers-core/runtime` - -Runtime composition root, in-process job runner, and worker messaging types. - -| Symbol | Kind | Description | -| --- | --- | --- | -| `DEFAULT_TOPIC` | variable | Default topic for jobs and tasks without explicit topic assignment. | -| `SSEEventTypes` | variable | SSE event names for real-time worker updates. | -| `createWorkersRuntime` | function | Create a fresh workers runtime from explicit dependencies. | -| `TaskRegistryPort` | type alias | Registry contract for task definitions. | -| `WorkersClock` | type alias | Clock contract used by runtime tests and schedulers. | -| `WorkersRuntime` | type alias | Runtime handle returned by the workers composition root. | -| `WorkersRuntimeOptions` | type alias | Explicit dependencies and overrides for a workers runtime instance. | -| `ExecutionRecord` | type alias | Runtime execution record. | -| `JobContext` | type alias | Context supplied to runtime job handlers. | -| `JobDefinition` | type alias | Runtime job definition. | -| `JobDispatcherOptions` | type alias | Options for resolving runtime job handlers. | -| `JobHandler` | type alias | Function that executes a runtime job. | -| `JobId` | type alias | Runtime job identifier. | -| `JobMessage` | type alias | Message enqueued to trigger a job execution. | -| `JobModuleImporter` | type alias | Dynamic runtime module importer. | -| `JobResolution` | type alias | Result of resolving a runtime job handler. | -| `JobResolutionSource` | type alias | Runtime job handler resolution source. | -| `JobResult` | type alias | Result returned by runtime job handlers. | -| `RegisterJobInput` | type alias | Input for registering a job definition. | -| `RegisterTaskInput` | type alias | Input for registering a task definition. | -| `RuntimeJobKvKeyFactories` | type alias | Public shape for runtime KV key factories. | -| `RuntimeJobStoragePort` | type alias | Runtime job storage contract. | -| `RuntimePermissions` | type alias | Runtime permission bag accepted by task and job execution. | -| `RuntimePermissionValue` | type alias | Runtime permission value accepted by task and job execution. | -| `RuntimeSchedulerPort` | type alias | Runtime scheduler contract. | -| `RuntimeShutdownManager` | type alias | Runtime shutdown manager contract. | -| `RuntimeShutdownOptions` | type alias | Runtime shutdown configuration. | -| `RuntimeShutdownResource` | type alias | Resource managed during runtime shutdown. | -| `RuntimeTaskExecutor` | type alias | Runtime task executor contract. | -| `RuntimeTaskExecutorOptions` | type alias | Runtime task executor configuration. | -| `RuntimeWorkerPort` | type alias | Runtime worker dispatch contract. | -| `RuntimeWorkflowDefinition` | type alias | Runtime workflow definition accepted by composition. | -| `RuntimeWorkflowExecutor` | type alias | Runtime workflow executor contract. | -| `RuntimeWorkflowOptions` | type alias | Runtime workflow executor options. | -| `StaticJobRegistry` | type alias | Registry of statically imported runtime job handlers. | -| `TaskDefinition` | type alias | Runtime task definition. | -| `TaskExecutionOptions` | type alias | Options supplied when executing a task. | -| `TaskId` | type alias | Runtime task identifier. | -| `TaskMessage` | type alias | Message enqueued to trigger a task execution. | -| `TaskResult` | type alias | Result returned by task execution. | -| `WorkflowId` | type alias | Runtime workflow identifier. | -| `JobKvKeys` | variable | KV key factories used by the runtime storage adapters. | -| `InProcessJobDispatcher` | class | Resolve job handlers from a static registry, definition, or explicit import fallback. | -| `InProcessJobRunner` | class | Registry-first job runner for tests, compiled binaries, and local composition. | -| `InProcessJobRunnerOptions` | type alias | Options for creating an in-process job runner. | -| `JOB_STATE_CHANNEL` | variable | Broadcast channel name for job execution state updates. | -| `ExecuteJobMessage` | type alias | Message sent to a runner to execute a job. | -| `JobCompleteMessage` | type alias | Message emitted when a job completes successfully. | -| `JobErrorMessage` | type alias | Message emitted when a job fails. | -| `JobLogMessage` | type alias | Message emitted for job logs. | -| `JobProgressMessage` | type alias | Message emitted to report job progress. | -| `StateUpdateMessage` | type alias | State update emitted by runtimes that expose execution progress. | -| `TerminateMessage` | type alias | Message used to stop a long-lived runner. | -| `WorkerInboundMessage` | type alias | Messages accepted by a job runner. | -| `WorkerOutboundMessage` | type alias | Messages emitted by a job runner. | +The separately published +[`@netscript/plugin-workers-core`](/reference/plugin-workers-core/) page is canonical for worker +definition builders, runtime composition, registries, executors, streams, configuration, and testing +exports. This page stays focused on the deployable plugin's manifest and integration entrypoints. The +workflow example below uses core APIs intentionally; exhaustive core entrypoint and symbol tables +live only on its reference page. ## Resumable Workflows and Idempotent Resume diff --git a/packages/sdk/README.md b/packages/sdk/README.md index 94d141a5e4..8db41590b1 100644 --- a/packages/sdk/README.md +++ b/packages/sdk/README.md @@ -27,10 +27,12 @@ and deployed endpoints without a registry or a config file. shared contract router; input and output types come from the contract, never from you. - **Aspire service discovery** — `./discovery` resolves service URLs and database/KV connections from orchestrator-injected environment variables, lazily at call time. -- **Cache-aware query factories** — `createQueryFactory` generates server-side query helpers backed - by the shared KV cache with stale-while-revalidate semantics. -- **TanStack Query integration** — `createNetScriptQueryClient` and `createServiceQueryUtils` give - browser and island code server-first defaults, invalidation bridging, and KV-backed persistence. +- **Cache-aware query factories** — `createQueryFactories` is the golden path: one call over a + resource-to-config map returns server-side query helpers for every resource, backed by the shared + KV cache with stale-while-revalidate semantics. Each generated action takes its input directly — + `queryOptions(input)`. `createQueryFactory` builds the same helpers for a single resource. +- **TanStack Query integration** — `createNetScriptQueryClient` gives browser and island code + server-first defaults, invalidation bridging, and KV-backed persistence. - **Distributed tracing built in** — every client call is wrapped in an outbound span and carries the W3C `traceparent` header, so client and server spans join one distributed trace. - **Native auto-update configuration** — `./auto-update` validates the app-pinned release endpoint @@ -93,6 +95,22 @@ const ordersQueryUtils = queryUtils.orders; Drop to a focused subpath when an app only needs part of the surface — `./client`, `./query`, and `./query-client` carry the three pieces individually. +### Two query dialects — pick one per data layer + +`queries.*` and `queryUtils.*` are not interchangeable, and their call shapes differ by exactly one +pair of braces. + +| | `queries.*` (`createQueryFactories`) | `queryUtils.*` (`createServiceQueryUtils`) | +| -------------------- | --------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | +| Call shape | `queryOptions(input)` | `queryOptions({ input })` | +| Server KV cache tier | yes — stale-while-revalidate, `prefetch`, `getCachedData`, `invalidate` | **no** | +| Use it for | the golden path: server and framework-neutral code, and islands that should read through the shared cache | a thin oRPC-to-TanStack remap when no server cache tier is wanted | + +Prefer `queries.*`. Reach for `queryUtils.*` only when the narrower surface is what you actually +want, and do not mix the two call shapes within one data layer: they address different key spaces, +which is why `./query-client` ships `toClientKeyPrefix` and `bridgeInvalidation` to cross between +them deliberately. + ### Desktop RPC bindings Inside a Deno Desktop webview, reuse the same contract as the runtime router without declaring a diff --git a/packages/sdk/tests/type-fixtures/sdk-client-contributions-rfc_type.ts b/packages/sdk/tests/type-fixtures/sdk-client-contributions-rfc_type.ts index fb2c9fcb8e..960ce95d18 100644 --- a/packages/sdk/tests/type-fixtures/sdk-client-contributions-rfc_type.ts +++ b/packages/sdk/tests/type-fixtures/sdk-client-contributions-rfc_type.ts @@ -346,7 +346,7 @@ const directOnly = defineRfcContribution<{ opaqueSession: string }>()({ const rejectedDesktopOptions: CreateDesktopServiceClientOptions = { contract: serviceContract, - // @ts-expect-error RFC-A keeps HTTP contributions off the Desktop MessagePort options surface + // @ts-expect-error RFC-A keeps HTTP contributions off the Desktop MessagePort options surface // quality-allow: negative compile fixture proves CreateDesktopServiceClientOptions rejects RFC HTTP contributions on the MessagePort transport contributions: [auth], }; void rejectedDesktopOptions; @@ -362,7 +362,7 @@ const duplicateAuthContext = defineRfcContribution<{ auth?: { readonly apiKey: s prepare: () => undefined, }); -// @ts-expect-error duplicate context ownership is rejected at the tuple boundary +// @ts-expect-error duplicate context ownership is rejected at the tuple boundary // quality-allow: negative compile fixture proves tuple validation rejects two contributions that both claim the auth context key acceptRfcContributions([auth, duplicateAuthContext]); type RfcDefineServiceConfig< @@ -442,7 +442,7 @@ services.clients.accounts.orders.list({ page: 1 }, { }, }); -// @ts-expect-error required auth context makes the request options mandatory +// @ts-expect-error required auth context makes the request options mandatory // quality-allow: negative compile fixture proves a generated client call rejects omission of options when contribution context contains a required key services.clients.accounts.orders.list({ page: 1 }); services.queryUtils.accounts.orders.list.queryOptions({ @@ -462,7 +462,7 @@ declare const contributedQueryUtils: RfcServiceQueryUtils< >; void contributedQueryUtils; -// @ts-expect-error direct-only services are omitted from the generated query-utils map +// @ts-expect-error direct-only services are omitted from the generated query-utils map // quality-allow: negative compile fixture proves mapped query-utils keys exclude a service whose contribution declares direct-only response caching services.queryUtils.desktopOnly; type SyntheticContribution = RfcContribution< @@ -499,5 +499,5 @@ declare const seventeen: readonly [ SyntheticContribution<'17'>, ]; -// @ts-expect-error the RFC-A public inference budget is sixteen contributions per service +// @ts-expect-error the RFC-A public inference budget is sixteen contributions per service // quality-allow: negative compile fixture proves tuple validation rejects a seventeenth contribution while accepting sixteen acceptRfcContributions(seventeen);