Wave 5b (sdk): research + proposed plan & design [PLAN-EVAL pending] by rickylabs · Pull Request #29 · rickylabs/netscript

rickylabs · 2026-06-11T10:43:25Z

Sub-wave 5b — `@netscript/sdk` (generator hand-off)

Scope: RESEARCH + PLAN & DESIGN only. No implementation. Plan is PROPOSED, not locked — PLAN-EVAL is a separate session.

Run dir: .llm/tmp/run/feat-package-quality-wave5-apps--5b-sdk/ (research.md, plan.md, worklog.md, drift.md, context-pack.md, commits.md, measure-5b.json).

Measured baseline (raw deno, local)

deno check PASS across all 12 entrypoints
Combined doc-lint: 29 (9 private-type-ref / 2 missing-return / 18 jsdoc) — 7 of the 9 ptr live upstream in plugin-streams-core (unexported package-owned types surfaced via sdk's ./streams facade), not in sdk (drift D-1)
Publish dry-run: 2 slow types (the TanStack any-bridges) + 37 excluded-module from root deno.json exclude (drift D-2, predicted by 5a)
0 tests, 3,117 LOC, 1 over-cap file (discovery 643L), 5 of 12 subpaths zero-consumer, F-11 interfaces/ folder

Architecture mandate (umbrella drift, 2026-06-11 user feedback)

Plan §2 delivers the composability layer map: L0 src/ports/ (ContractLike algebra, CacheStore, ServiceTransport/ClientLinkFactory, QueryClientPort) → L1 primitives (CacheQuery SWR, KV store, discovery, otel) → L2 factories (createServiceClient, query factories/utils, collections) → L3 one-liner defineServices() whose outputs ARE the L2 values (no-cliff escape hatch). RFC 14 transport seam protected via internal link-factory port (D-8) — unified mode NOT implemented.

Plan highlights (19 slices, gates A3 ∪ A4)

src/ restructure, interfaces/ → src/ports/ (./interfaces → ./ports), subpaths 12→10
Streams ptr fixed upstream via additive type exports in plugin-streams-core (cross-package slice, D-4)
QueryClientPort + ServiceQueryUtils<TContract> + QueryCollection<TItem> kill the tanstack leaks/slow types
defineServices() L3 preset (D-9, mandated; descopeable)
discovery split, jsdoc sweep, README/docs/tests-from-zero incl. type fixtures + live round-trip, final slice lifts root exclude

For PLAN-EVAL — review hot-spots

D-6 ServiceQueryUtils<TContract> typing budget (2 slices) — enough?
D-9 defineServices — new surface during quality wave; name bikeshed
D-4 cross-package additive-only slice in a Wave-4 package
D-5 QueryClientPort widen-on-drift vs F-15 waiver
D-3 subpath fold choices (openapi→root; telemetry/collections kept on RFC justification)

Next step: PLAN-EVAL session reviews + locks (or bounces) plan.md.

🤖 Generated with Claude Code

Generator artifacts for sub-wave 5b: measure-first baseline (check PASS, combined doc-lint 29 with 7/9 ptr attributed upstream to plugin-streams-core, dry-run 2 slow types + 37 excluded-module from root exclude), architecture-mandate research (composability layer map, transport seam audit, RFC 14/17), proposed 19-slice plan (A3+A4 gate union; ports rename, QueryClientPort/ServiceQueryUtils typing, defineServices L3 preset, cross-package streams type exports), design checkpoint, drift log (4 entries), context pack for PLAN-EVAL. No implementation. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

rickylabs · 2026-06-11T11:32:06Z

@openhands-agent model=openrouter/qwen/qwen3.7-max output=pr-comment use harness proceed to PLAN-EVAL for this PR.

If surface areas of further/additional improvements/fine tuning/deep dive/... are not too broad proceed with them directly and give verdict afterwards all in one run.

rickylabs · 2026-06-11T11:32:19Z

OpenHands Agent — success

Model: openrouter/qwen/qwen3.7-max
Provider: OPENROUTER
Artifacts: .llm/tmp/run/openhands/pr-29/run-27343770321-1

Summary — PLAN-EVAL for PR #29 (Wave 5b: @netscript/sdk)

Summary

PASS verdict for Wave 5b package-quality plan covering @netscript/sdk. The plan
designs a 4-layer composability architecture (L0 ports → L1 primitives → L2 factories
→ L3 defineServices() preset) with transport seam protection, structural type ports
(QueryClientPort, ServiceQueryUtils<TContract> mapped type, QueryCollection<TItem>),
and a 19-slice implementation path. Plan-gate checklist passes commensurately with the
5a (service) precedent that passed PLAN-EVAL earlier in this wave.

Changes

Created .llm/tmp/run/openhands/pr-29/run-27343770321-1/plan-eval.md — PASS verdict
with 8 checklist items verified, 1 open-decision LOCK (defineServices naming),
6 spot-checks of research findings against tree, and 7 advisory findings.

No code changes. No commits made (evaluator session).

Validation

PLAN-EVAL checklist walk-through

Research present and current — research.md §0-§5, measure-5b.json baseline.
Decisions locked — 14 decisions (D-1..D-14) with rationale.
Open-decision sweep — 7 decisions listed, none force rework. defineServices
naming resolved as defineServices.
Commit slices — 19 slices, ordered, under 30 cap, gate+files implied.
Risk register — 6 risks with L×I and mitigations.
Gate set selected — A3 ∪ A4 from archetype-gate-matrix.
Deferred scope explicit — 5 deferred items listed.
jsr-audit surface scan — baseline errors enumerated, exit target ≥7/10 stated.

Spot-checks against tree

Verified: interfaces/ folder exists (F-11), discovery file size (~642L, over-cap),
ServiceTransport seam unused by client (RPCLink constructed inline), 7/9 private-type-ref
errors point to plugin-streams-core internal files, 12 subpaths in deno.json exports,
0 tests exist.

Responses to review comments

This is a PLAN-EVAL (pre-implementation) pass, not review-thread responses. The trigger
comment asked to "proceed to PLAN-EVAL for this PR."

No review thread comments to respond to.

Remaining risks

Non-blocking advisories (captured in plan-eval.md)

Research D-1 wording ("unexported") is imprecise — types ARE exported from
plugin-streams-core/mod.ts barrel but doc-lint traces file-level private-type chains.
Generator should update wording at next opportunity.
Integration test scope (slice 18) covers round-trip + abort but should also name:
connection failure (bad URL/timeout), retry exhaustion, cancellation propagation.
SWR defaults (30s/300s) duplicated in 3 locations — centralize during D-1/D-11 as
named constants. Generator should flag at impl start.
QueryClientPort width maintenance burden — exhaustive consumer audit at D-5 impl
should record final member list in src/ports/query-client.ts with jsdoc noting which
consumer drives each member.

No implementation before generator receives PASS

The generator session should update plan.md status from "PROPOSED — awaiting PLAN-EVAL"
to "LOCKED — PLAN-EVAL PASS" before committing slice 1.

Run: https://github.com/rickylabs/netscript/actions/runs/27343770321

rickylabs · 2026-06-11T12:07:39Z

Slice 1/19 — D-12 Package task block | Unit: @netscript/sdk | Archetype: A3∪A4

Field	Evidence
Gate(s)	Static slice gate: package-local entrypoint check; scoped metadata format check.
Changed	`packages/sdk/deno.json` now declares local `check`, `test`, `lint`, `fmt`, and `publish:dry-run` tasks while preserving the locked exports/imports/publish map.
Gate results	Raw `Deno.Command`: `deno task check` from `packages/sdk` PASS / exit 0 with known pre-slice-19 root-exclude warning `No matching files found`. Raw `Deno.Command`: `deno fmt --check --no-config --ext json packages/sdk/deno.json` PASS / exit 0.
Drift	none
Commits	impl `ef6a6bd`; docs `9b4064e`

rickylabs · 2026-06-11T12:16:23Z

Slice 2/19 — D-1 Move implementation under `src/` facades | Unit: @netscript/sdk | Archetype: A3∪A4

Field	Evidence
Gate(s)	Static slice gate: package-local entrypoint check; stale moved-path scan.
Changed	Implementation files moved under `packages/sdk/src/` while existing public subpath entries remain as thin facades. `core/` dissolved into `src/cache/` and `src/query/`; `src/interfaces/` is retained for the planned slice-3 ports rename.
Gate results	Raw `Deno.Command`: `deno task check` from `packages/sdk` PASS / exit 0 with known pre-slice-19 root-exclude warning `No matching files found`. Stale-path scan found no references to removed implementation locations (`../core`, old KV adapter path, old query-client/discovery/openapi/telemetry implementation siblings).
Drift	none
Commits	impl `0cbd962`; docs `a353ba2`

rickylabs · 2026-06-11T12:19:57Z

Slice 3/19 — D-2 `interfaces` → `ports` | Unit: @netscript/sdk | Archetype: A3∪A4

Field	Evidence
Gate(s)	Static slice gate: sdk package check; consumer gate: Fresh compile check; rename scan.
Changed	Renamed `packages/sdk/src/interfaces/` to `src/ports/`; renamed public subpath facade `./interfaces` to `./ports`; updated `packages/sdk/deno.json`, root barrel, sdk facades/internal imports, and the Fresh consumer `packages/fresh/builders/define-page/types.ts`.
Gate results	Raw `Deno.Command`: `deno task check` from `packages/sdk` PASS / exit 0 with known pre-slice-19 root-exclude warning. Raw `Deno.Command`: `deno task check` from `packages/fresh` PASS / exit 0 with known root-exclude warning. Rename scan over packages/plugins/services found no remaining `@netscript/sdk/interfaces`, `src/interfaces`, `./interfaces`, or `../interfaces` references.
Drift	none
Commits	impl `998c4d6`; docs `be6a4ec`

rickylabs · 2026-06-11T12:23:44Z

Slice 4/19 — D-3 Fold `./adapters` and `./openapi` | Unit: @netscript/sdk | Archetype: A3∪A4

Field	Evidence
Gate(s)	Static slice gate: sdk package check; removed-subpath scan.
Changed	Removed `./adapters` and `./openapi` exports and facades. `KvCacheStore` is now exported from `@netscript/sdk/cache`; OpenAPI helpers are exported from the root barrel. Updated sdk README/example references and completed B1 research wording correction.
Gate results	Raw `Deno.Command`: `deno task check` from `packages/sdk` PASS / exit 0 with known pre-slice-19 root-exclude warning. SDK-only removed-subpath scan found no remaining `@netscript/sdk/adapters`, `@netscript/sdk/openapi`, `sdk/adapters`, `sdk/openapi`, `./adapters/mod.ts`, or `./openapi/mod.ts` references.
Drift	none
Commits	impl `8759d99`; docs `8a8db64`

rickylabs · 2026-06-11T12:30:26Z

Slice 5/19 — D-4 Stream type export chain | Unit: @netscript/sdk | Archetype: A3∪A4

Field	Evidence
Gate(s)	Cross-package static gate: plugin-streams-core check; plugins/streams consumer check; doc-lint for plugin-streams-core and sdk streams facade.
Changed	Added pure type re-exports for `StateSchema`/`StreamStateDefinition` from plugin-streams-core declaring modules and `StreamProducerPort` from the producer declaring module. Updated `@netscript/sdk/streams` to re-export the plugin core type surface while preserving selected value exports and `createStreamProducer` alias.
Gate results	Raw `Deno.Command`: `deno task check` from `packages/plugin-streams-core` PASS / exit 0. Raw `Deno.Command`: `deno task check` from `plugins/streams` PASS / exit 0. Raw `Deno.Command`: `deno doc --lint packages/plugin-streams-core/mod.ts` PASS / checked 1 file. Raw `Deno.Command`: `deno doc --lint packages/sdk/streams.ts` PASS / checked 1 file.
Drift	none
Commits	impl `549326c`; docs `caeba76`

rickylabs · 2026-06-11T13:11:21Z

Slice 6/19 — D-5 `QueryClientPort` | Unit: @netscript/sdk | Archetype: A3∪A4

Field	Evidence
Gate(s)	Static slice gate: sdk package check; public-surface leak scan.
Changed	Added package-owned structural `QueryClientPort` in `src/ports/query-client.ts`, exported it through root/`./ports`/`./query-client`, changed `createNetScriptQueryClient()` to return the port, and changed collection options to accept the port with an internal TanStack boundary cast.
Gate results	Raw `Deno.Command`: `deno task check` from `packages/sdk` PASS / exit 0 with known pre-slice-19 root-exclude warning. Focused query-client/collections doc-lint probe no longer reports the `QueryClient` private-type-ref; remaining probe findings are known later-slice jsdoc/return issues. Static scan shows upstream `QueryClient` only in internal imports/casts, not public signatures.
Drift	none
Commits	impl `9585851`; docs `aec7674`

rickylabs · 2026-06-11T13:26:29Z

Slice 7/19 — D-6a `ServiceQueryUtils<TContract>` mapped type | Unit: @netscript/sdk | Archetype: A3∪A4

Field	Evidence
Gate(s)	Type inference fixture; upstream return assignability fixture; scoped lint/fmt; focused doc-lint on new port + contract algebra; package check wrapper
Changed	Added `packages/sdk/src/ports/service-query-utils.ts` with package-owned structural `ServiceQueryUtils<TContract>` and named option/result aliases. Exported through `./ports`, `./query-client`, and root. Added compile-only fixtures for sdk contract inference and upstream `createTanstackQueryUtils()` return assignability. Runtime `createServiceQueryUtils()` remains unchanged for slice 8.
Gate results	`deno check --no-config --unstable-kv ./packages/sdk/tests/type-fixtures/service-query-utils-contract_type.ts ./packages/sdk/tests/type-fixtures/service-query-utils-upstream_type.ts` PASS exit 0; `deno lint --no-config ./packages/sdk/src/ports/service-query-utils.ts ./packages/sdk/tests/type-fixtures/service-query-utils-contract_type.ts ./packages/sdk/tests/type-fixtures/service-query-utils-upstream_type.ts` PASS exit 0; `deno fmt --config .llm/tmp/run/feat-package-quality-wave5-apps--5b-sdk/deno-format-sdk.json --check <slice-7 files>` PASS exit 0; `deno doc --lint ./packages/sdk/src/ports/service-client.ts ./packages/sdk/src/ports/service-query-utils.ts` PASS checked 2 files; `deno task check` from `packages/sdk` PASS exit 0 with known pre-slice-19 root-exclude warning.
Drift	none
Commits	impl `82abaa6`; docs `5909aff`

rickylabs · 2026-06-11T13:33:21Z

Slice 8/19 — D-6b typed `createServiceQueryUtils()` | Unit: @netscript/sdk | Archetype: A3∪A4

Field	Evidence
Gate(s)	Factory inference fixture; service-query-utils type fixtures; scoped lint/fmt; focused doc-lint; package check wrapper
Changed	Typed `createServiceQueryUtils()` as `createServiceQueryUtils<TContract>(client: ServiceClient<TContract>, options?): ServiceQueryUtils<TContract>`. Removed the public `any` bridge. Added `ServiceClientContract<TContract>`/`ServiceClientShape<TContract>` so `TContract` infers from a `ServiceClient<TContract>` value. Added `service-query-utils-factory_type.ts` to prove zero-annotation factory inference.
Gate results	`deno check --config .llm/tmp/run/feat-package-quality-wave5-apps--5b-sdk/deno-check-sdk.json --unstable-kv ./packages/sdk/src/query-client/create-service-query-utils.ts ./packages/sdk/tests/type-fixtures/service-query-utils-factory_type.ts ./packages/sdk/tests/type-fixtures/service-query-utils-contract_type.ts ./packages/sdk/tests/type-fixtures/service-query-utils-upstream_type.ts` PASS exit 0; `deno lint --no-config ./packages/sdk/src/query-client/create-service-query-utils.ts ./packages/sdk/src/ports/service-client.ts ./packages/sdk/tests/type-fixtures/service-query-utils-factory_type.ts` PASS exit 0; `deno fmt --config .llm/tmp/run/feat-package-quality-wave5-apps--5b-sdk/deno-format-sdk.json --check <slice-8 files>` PASS exit 0; `deno doc --lint ./packages/sdk/src/ports/service-client.ts ./packages/sdk/src/ports/service-query-utils.ts ./packages/sdk/src/query-client/create-service-query-utils.ts` PASS checked 3 files; `deno task check` from `packages/sdk` PASS exit 0 with known pre-slice-19 root-exclude warning.
Drift	none
Commits	impl `b0eca88`; docs `077e74c`

rickylabs · 2026-06-11T14:10:11Z

Slice 13/19 — D-11 JSDoc sweep + inflight state decision | Unit: @netscript/sdk | Archetype: A3∪A4

Field	Evidence
Gate(s)	D-11 public member docs; B3 centralized SWR defaults; cache in-flight state decision; focused check/lint/fmt/doc-lint; current combined doc-lint read; package check wrapper
Changed	Added member JSDoc for `CacheProvider` and `KvCachePersisterStorage`; added `src/cache/defaults.ts` as the single runtime home for query stale/cache defaults; rewired `CacheQuery`, query factories, composite query, query-client defaults, and KV persister TTL to use those constants. Moved `inflightRequests` from module-global state onto `CacheQuery` instances with an optional constructor-injected map.
Gate results	`deno check --config .llm/tmp/run/feat-package-quality-wave5-apps--5b-sdk/deno-check-sdk.json --unstable-kv packages/sdk/src/cache/defaults.ts packages/sdk/src/cache/cache-query.ts packages/sdk/src/cache/cache-provider.ts packages/sdk/src/query/query-factory.ts packages/sdk/src/query/composite-query.ts packages/sdk/src/query-client/query-client-factory.ts packages/sdk/src/query-client/kv-cache-persister.ts` PASS exit 0; `deno lint --config .llm/tmp/run/feat-package-quality-wave5-apps--5b-sdk/deno-check-sdk.json <slice-13 files>` PASS exit 0; `deno fmt --check --config .llm/tmp/run/feat-package-quality-wave5-apps--5b-sdk/deno-format-sdk.json <slice-13 files>` PASS exit 0; `deno doc --lint --import-map .llm/tmp/run/feat-package-quality-wave5-apps--5b-sdk/deno-doc-import-map.json <slice-13 files + referenced ports>` PASS, checked 15 files; `deno run --allow-read --allow-run .llm/tools/run-deno-doc-lint.ts --root packages/sdk --pretty` exit 0 with combined missingJSDoc 0 / privateTypeRef 0 / other 0 for the current entrypoint set; `deno task check` from `packages/sdk` PASS exit 0 with known pre-slice-19 root-exclude warning.
Drift	none
Commits	impl `4443e5f`; docs `41274d3`

Decision recorded: inflightRequests is instance state, not process-global. Remote verified: 41274d396bea24991ae601b2b2966064547f6f7d.

rickylabs · 2026-06-11T14:15:54Z

Slice 14/19 — module docs | Unit: @netscript/sdk | Archetype: A3∪A4

Field	Evidence
Gate(s)	Root `mod.ts` @module >=30L; per-subpath module docs; all-entrypoint check/lint/fmt/doc-lint; package check wrapper
Changed	Expanded root `packages/sdk/mod.ts` module docs to 35 lines covering the root barrel, `defineServices()`, focused subpaths, server-only cache warning, discovery isolation, and port ownership. Refreshed module docs for `cache`, `client`, `collections`, `discovery`, `ports`, `query`, `query-client`, `streams`, and `telemetry`. No export surface changed.
Gate results	`deno check --config .llm/tmp/run/feat-package-quality-wave5-apps--5b-sdk/deno-check-sdk.json --unstable-kv packages/sdk/mod.ts packages/sdk/cache/mod.ts packages/sdk/client/mod.ts packages/sdk/collections/mod.ts packages/sdk/discovery/mod.ts packages/sdk/ports/mod.ts packages/sdk/query/mod.ts packages/sdk/query-client/mod.ts packages/sdk/telemetry/mod.ts packages/sdk/streams.ts` PASS exit 0 with npm peer warning only; `deno doc --lint --import-map .llm/tmp/run/feat-package-quality-wave5-apps--5b-sdk/deno-doc-import-map.json <all current sdk entrypoints>` PASS, checked 10 files; `deno lint --config .llm/tmp/run/feat-package-quality-wave5-apps--5b-sdk/deno-check-sdk.json <all current sdk entrypoints>` PASS exit 0; `deno fmt --check --config .llm/tmp/run/feat-package-quality-wave5-apps--5b-sdk/deno-format-sdk.json <all current sdk entrypoints + run configs>` PASS exit 0; `deno task check` from `packages/sdk` PASS exit 0 with known pre-slice-19 root-exclude warning.
Drift	none
Commits	impl `4938c64`; docs `ff448a0`

Lock hygiene: only run-local check/doc import maps and run-local lock expanded for root entrypoint dependencies; root deno.lock untouched. Remote verified: ff448a068a1ecf258162c4aa59368ed139006400.

rickylabs · 2026-06-11T14:20:49Z

Slice 15/19 — README + architecture docs | Unit: @netscript/sdk | Archetype: A3∪A4

Field	Evidence
Gate(s)	README 14 sections / >=150L; `docs/architecture.md` layer map + composability contract + transport seam audit; Markdown fmt; current combined doc-lint read; package check wrapper
Changed	Replaced `packages/sdk/README.md` with a 14-section, 329-line package guide covering install, entrypoints, `defineServices()`, direct clients, query factories, query-client, cache, discovery, collections, OpenAPI/telemetry, ports, architecture notes, and validation. Added `packages/sdk/docs/architecture.md` with layer map, composability contract, type inference contract, transport seam audit, discovery split, cache state, public surface boundaries, and contributor path.
Gate results	`deno fmt --check --no-config packages/sdk/README.md packages/sdk/docs/architecture.md` PASS exit 0; `deno run --allow-read --allow-run .llm/tools/run-deno-doc-lint.ts --root packages/sdk --pretty` exit 0 with combined missingJSDoc 0 / privateTypeRef 0 / other 0 for the current entrypoint set; `deno task check` from `packages/sdk` PASS exit 0 with known pre-slice-19 root-exclude warning. Architecture probe confirmed `Layer Map`, `Composability Contract`, `Transport Seam Audit`, `ClientLinkFactory`, `defineServices`, and `CacheQuery` references. Size: README 329 lines / 14 `##` sections; architecture doc 116 lines.
Drift	none
Commits	impl `6e50265`; docs `20d65c2`

Remote verified: 20d65c241c0c7dd52178b190f6ab9e5161fb16ab.

rickylabs · 2026-06-11T14:32:22Z

Slice 16/19 — doctest runner + unit tests | Unit: @netscript/sdk | Archetype: A3∪A4

Field	Evidence
Gate(s)	Static + runtime unit coverage for CacheQuery SWR/preferFreshOnStale/inflight dedupe, query-factory keys, discovery ordering, KV persister, README doctests
Changed	Added `packages/sdk/tests/test-helpers.ts`, cache/query/persister tests, and README TypeScript/JSON doctest runner. Fixed `CacheQuery` in-flight dedupe race by rechecking the instance in-flight map after async cache read before starting a fetch.
Gate results	`deno test --config .llm/tmp/run/feat-package-quality-wave5-apps--5b-sdk/deno-check-sdk.json --allow-read --allow-write --allow-run --allow-env packages/sdk/tests/cache/cache-query_test.ts packages/sdk/tests/query/query-factory_test.ts packages/sdk/tests/query-client/kv-cache-persister_test.ts packages/sdk/tests/discovery/env-ordering_test.ts packages/sdk/tests/readme-doctest_test.ts` PASS exit 0, 10 passed / 0 failed; `deno fmt --check --config .llm/tmp/run/feat-package-quality-wave5-apps--5b-sdk/deno-format-sdk.json <slice-16 files>` PASS exit 0; `deno check --config .llm/tmp/run/feat-package-quality-wave5-apps--5b-sdk/deno-check-sdk.json --unstable-kv <slice-16 files>` PASS exit 0; `deno lint --config .llm/tmp/run/feat-package-quality-wave5-apps--5b-sdk/deno-check-sdk.json <slice-16 files>` PASS exit 0; `deno task check` from `packages/sdk` PASS exit 0 with the known pre-slice-19 root-exclude warning.
Drift	none
Commits	impl `117fd2e`; docs `31dc654`

rickylabs · 2026-06-11T14:37:18Z

Slice 17/19 — type-level assignability fixtures | Unit: @netscript/sdk | Archetype: A3∪A4

Field	Evidence
Gate(s)	Static type-level assignability for D-5/D-6/D-7 plus `ServiceClient` inference
Changed	Added `packages/sdk/tests/type-fixtures/sdk-assignability_type.ts`, proving contract inference from `createServiceClient()` through `ServiceClient<TContract>`, `QueryFactory<TContract>`, `ServiceQueryUtils<TContract>`, `QueryClientPort`, and `QueryCollection<TItem>`. Includes a `@ts-expect-error` guard for invalid service-client input.
Gate results	`deno fmt --check --config .llm/tmp/run/feat-package-quality-wave5-apps--5b-sdk/deno-format-sdk.json <all sdk type fixtures>` PASS exit 0; `deno check --config .llm/tmp/run/feat-package-quality-wave5-apps--5b-sdk/deno-check-sdk.json --unstable-kv <all sdk type fixtures>` PASS exit 0; `deno lint --config .llm/tmp/run/feat-package-quality-wave5-apps--5b-sdk/deno-check-sdk.json <slice-17 fixture + non-inline-import type fixtures>` PASS exit 0; `deno task check` from `packages/sdk` PASS exit 0 with the known pre-slice-19 root-exclude warning.
Drift	none
Commits	impl `c250f7d`; docs `aa6d583`

rickylabs · 2026-06-11T14:46:45Z

Slice 18/19 — live service-client integration | Unit: @netscript/sdk | Archetype: A3∪A4

Field	Evidence
Gate(s)	A3 runtime integration + B2 failure paths
Changed	Added `packages/sdk/tests/integration/service-client-runtime_test.ts` booting real `@netscript/service` with `serve({ port: 0 })`, resolving it through `services__sdk-live__http__0`, and calling `createServiceClient()`. Added `ServiceClientContext.signal` and forwarded it through the internal HTTP link for cancellation propagation. Expanded run-local gate config/lock for service/logger/telemetry/oRPC server deps; root `deno.lock` untouched.
Gate results	`deno test --config .llm/tmp/run/feat-package-quality-wave5-apps--5b-sdk/deno-check-sdk.json --unstable-kv --allow-net --allow-env --allow-read --allow-write --allow-run packages/sdk/tests/integration/service-client-runtime_test.ts` PASS exit 0, 4 passed / 0 failed; covers live discovery round-trip, bad URL connection failure with timeout signal, retry exhaustion with 2 retry callbacks, cancellation propagation through `AbortController`, and clean listener stop. `deno fmt --check --config .llm/tmp/run/feat-package-quality-wave5-apps--5b-sdk/deno-format-sdk.json <slice-18 files + run check config>` PASS exit 0; `deno check --config .llm/tmp/run/feat-package-quality-wave5-apps--5b-sdk/deno-check-sdk.json --unstable-kv <slice-18 files>` PASS exit 0 with known oRPC peer warning; `deno lint --config .llm/tmp/run/feat-package-quality-wave5-apps--5b-sdk/deno-check-sdk.json <slice-18 files>` PASS exit 0; `deno task check` from `packages/sdk` PASS exit 0 with known pre-slice-19 root-exclude warning.
Drift	none
Commits	impl `f430fd0`; docs `b340916`

rickylabs · 2026-06-11T15:07:54Z

Slice 19/19 — D-14 root-exclude lift + full gate sweep | Unit: @netscript/sdk | Archetype: A3∪A4

Field	Evidence
Gate(s)	Root/package static gates, publish dry-run, doc-lint, tests/doctests, consumer gates, JSR audit, measure-after
Changed	Removed `packages/sdk/` from root exclude and root wrapper filters; added SDK test dependency/import-map entry; excluded SDK `tests/` from publish; fixed final doc-lint reachability exports/JSDoc/type-only import; accepted root `deno.lock` churn caused by SDK entering the root graph.
Gate results	`deno task check` from `packages/sdk` PASS; `deno publish --dry-run --allow-dirty` from `packages/sdk` PASS exit 0 with no raw slow-type/excluded-module diagnostics; root `deno task check` PASS; root `deno task lint` PASS; root `deno task fmt:check` PASS; `deno task test` from `packages/sdk` PASS, 14 passed / 0 failed; combined SDK doc-lint PASS 0; independent `deno doc --lint packages/sdk/mod.ts` PASS; consumer checks queue/cli/plugin-streams-core/plugins-streams PASS; Fresh exits 0 with pre-existing root-exclude warning and touched import verified; JSR audit script exit 0; measure-after exit 0.
Drift	none; caveat recorded for Fresh future-wave root-exclude behavior
Commits	impl `f8e8bf8`; docs/evidence `7e48df3`

rickylabs · 2026-06-11T15:08:12Z

Unit COMPLETE — @netscript/sdk | Archetype: A3∪A4

Commit range after PLAN-EVAL lock: 13dca51..7e48df3

Gate	Result
Publish dry-run	PASS: `deno publish --dry-run --allow-dirty` from `packages/sdk`, exit 0, no raw slow-type diagnostics and no excluded-module diagnostics.
Doc lint	PASS: combined all SDK entrypoints 0 findings; independent root barrel `deno doc --lint packages/sdk/mod.ts` PASS.
Static checks	PASS: package `deno task check`; root `deno task check`; root `deno task lint`; root `deno task fmt:check`.
Tests and doctests	PASS: `deno task test` from `packages/sdk`, 14 passed / 0 failed across 6 test files.
A3 runtime	PASS: live `@netscript/service` `serve({ port: 0 })` discovery round-trip, clean stop, bad URL failure, retry exhaustion, and cancellation propagation.
Consumer gates	PASS for queue, cli, plugin-streams-core, plugins/streams. Fresh exits 0 with the pre-existing future-wave root-exclude warning; its touched SDK import is `@netscript/sdk/ports`.
JSR audit	PASS exit 0 from `.llm/tools/fitness/audit-jsr-package.ts --root packages/sdk --text`; one parser warning on the dry-run banner, raw dry-run is clean.
Architecture deliverables	PASS: `packages/sdk/docs/architecture.md` contains layer map, composability contract, transport seam audit, and contributor path.
Public surface docs	PASS: `deno doc packages/sdk/mod.ts` completed successfully and documented the root export surface.

Slice-19 Full Validation Sweep

Metric	Baseline	After	Target
Combined doc-lint	29	0	0
Publish dry-run findings	2 slow-types + 37 excluded-module	0 raw findings	0
Tests	0	6 files / 14 passing tests	>0
Source LOC inventory	3,117	4,377	tracked
Over-cap files	1 at 643L	0	0

rickylabs · 2026-06-11T15:08:26Z

READY FOR IMPL-EVAL

Remote head verified with git ls-remote origin refs/heads/feat/package-quality-wave5-apps-5b-sdk:

7e48df3c59763100b4a97ead3fc89299213134b3

Implementation session complete; no self-evaluation or merge performed.

rickylabs · 2026-06-11T15:08:42Z

@openhands-agent model=openrouter/qwen/qwen3.7-max output=pr-comment use harness proceed to IMPL-EVAL for this PR.

In addition to the standard IMPL-EVAL gate replay: you MUST also run the E2E CLI suite (full netscript init scaffold + generated-app checks), because the CLI templates import the @netscript/sdk surface this PR changed (./interfaces → ./ports rename, subpaths folded 12 → 10, new defineServices() preset).

If E2E or gate failures surface and their fix areas are not too broad, proceed to fix them straight away and give the verdict afterwards, all in one run.

rickylabs · 2026-06-11T15:08:59Z

OpenHands Agent — success

Model: openrouter/qwen/qwen3.7-max
Provider: OPENROUTER
Artifacts: .llm/tmp/run/openhands/pr-29/run-27356774781-1

OpenHands Agent Summary

OpenHands did not start or did not produce a summary.

This is a workflow failure, not a task verdict.

Diagnostics

Bootstrap: success
Agent: success
Model: openrouter/qwen/qwen3.7-max
Provider: OPENROUTER
Output mode: pr-comment
Run: https://github.com/rickylabs/netscript/actions/runs/27356774781

See the uploaded Actions artifact for bootstrap.log and agent.log when present.

Run: https://github.com/rickylabs/netscript/actions/runs/27356774781

rickylabs · 2026-06-11T15:09:15Z

@openhands-agent model=openrouter/qwen/qwen3.7-max output=pr-comment use harness proceed to IMPL-EVAL for this PR.

In addition to the standard IMPL-EVAL gate replay: you MUST also run the E2E CLI suite (full netscript init scaffold + generated-app checks), because the CLI templates import the @netscript/sdk surface this PR renamed (./interfaces → ./ports, subpaths 12 → 10, new defineServices()).

If E2E or gate failures surface and their fix areas are not too broad, proceed to fix them straight away and give the verdict afterwards, all in one run.

rickylabs · 2026-06-11T15:15:49Z

OpenHands Agent — success

Model: openrouter/qwen/qwen3.7-max
Provider: OPENROUTER
Artifacts: .llm/tmp/run/openhands/pr-29/run-27356820996-1

OpenHands Agent Summary

OpenHands did not start or did not produce a summary.

This is a workflow failure, not a task verdict.

Diagnostics

Bootstrap: success
Agent: success
Model: openrouter/qwen/qwen3.7-max
Provider: OPENROUTER
Output mode: pr-comment
Run: https://github.com/rickylabs/netscript/actions/runs/27356820996

See the uploaded Actions artifact for bootstrap.log and agent.log when present.

Run: https://github.com/rickylabs/netscript/actions/runs/27356820996

rickylabs and others added 2 commits June 11, 2026 12:40

docs(5b): record generator commit hash in commits.md

9af6b83

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

rickylabs added 3 commits June 11, 2026 14:02

Lock sdk plan after PLAN-EVAL pass

13dca51

Add sdk package tasks for quality gates

ef6a6bd

Record sdk slice 1 gate evidence

9b4064e

rickylabs added 2 commits June 11, 2026 14:14

Move sdk implementation under src facades

0cbd962

Record sdk slice 2 gate evidence

a353ba2

rickylabs added 2 commits June 11, 2026 14:18

Rename sdk interface surface to ports

998c4d6

Record sdk slice 3 gate evidence

be6a4ec

rickylabs added 2 commits June 11, 2026 14:22

Fold sdk adapters and openapi subpaths

8759d99

Record sdk slice 4 gate evidence

8a8db64

rickylabs added 2 commits June 11, 2026 14:28

Export stream producer types for sdk docs

549326c

Record sdk slice 5 gate evidence

caeba76

rickylabs added 2 commits June 11, 2026 15:09

Add sdk query client structural port

9585851

Record sdk slice 6 gate evidence

aec7674

rickylabs added 2 commits June 11, 2026 15:24

Add sdk service query utils type mirror

82abaa6

Record sdk slice 7 gate evidence

5909aff

rickylabs added 2 commits June 11, 2026 15:31

Type sdk service query utils factory

b0eca88

Record sdk slice 8 gate evidence

077e74c

Expose sdk query collection port

830affb

rickylabs added 2 commits June 11, 2026 16:14

Document sdk module entrypoints

4938c64

Record sdk slice 14 gate evidence

ff448a0

rickylabs added 2 commits June 11, 2026 16:19

Document sdk package architecture

6e50265

Record sdk slice 15 gate evidence

20d65c2

rickylabs added 2 commits June 11, 2026 16:30

Add sdk cache and doctest coverage

117fd2e

Record sdk slice 16 gate evidence

31dc654

rickylabs added 2 commits June 11, 2026 16:35

Prove sdk type assignability chain

c250f7d

Record sdk slice 17 gate evidence

aa6d583

rickylabs added 2 commits June 11, 2026 16:44

Prove sdk live service client runtime

f430fd0

Record sdk slice 18 gate evidence

b340916

rickylabs added 2 commits June 11, 2026 17:03

Lift sdk into root quality gates

f8e8bf8

Record sdk final gate evidence

7e48df3

chore(openhands): apply agent changes

bdd179c

rickylabs marked this pull request as ready for review June 11, 2026 17:12

rickylabs merged commit 8d88d17 into feat/package-quality-wave5-apps Jun 11, 2026

rickylabs mentioned this pull request Jun 11, 2026

fix(openhands): enforce summary contract and truthful run reporting #33

Merged

rickylabs mentioned this pull request Jul 1, 2026

fix(fresh-ui): registry ChartBlock + Toast fail deno lint/check when copied into a Deno app #206

Closed

Conversation

rickylabs commented Jun 11, 2026

Sub-wave 5b — @netscript/sdk (generator hand-off)

Measured baseline (raw deno, local)

Architecture mandate (umbrella drift, 2026-06-11 user feedback)

Plan highlights (19 slices, gates A3 ∪ A4)

For PLAN-EVAL — review hot-spots

Uh oh!

rickylabs commented Jun 11, 2026

Uh oh!

rickylabs commented Jun 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

OpenHands Agent — success

Summary — PLAN-EVAL for PR #29 (Wave 5b: @netscript/sdk)

Summary

Changes

Validation

PLAN-EVAL checklist walk-through

Spot-checks against tree

Responses to review comments

Remaining risks

Non-blocking advisories (captured in plan-eval.md)

No implementation before generator receives PASS

Uh oh!

rickylabs commented Jun 11, 2026

Slice 1/19 — D-12 Package task block | Unit: @netscript/sdk | Archetype: A3∪A4

Uh oh!

rickylabs commented Jun 11, 2026

Slice 2/19 — D-1 Move implementation under src/ facades | Unit: @netscript/sdk | Archetype: A3∪A4

Uh oh!

rickylabs commented Jun 11, 2026

Slice 3/19 — D-2 interfaces → ports | Unit: @netscript/sdk | Archetype: A3∪A4

Uh oh!

rickylabs commented Jun 11, 2026

Slice 4/19 — D-3 Fold ./adapters and ./openapi | Unit: @netscript/sdk | Archetype: A3∪A4

Uh oh!

rickylabs commented Jun 11, 2026

Slice 5/19 — D-4 Stream type export chain | Unit: @netscript/sdk | Archetype: A3∪A4

Uh oh!

rickylabs commented Jun 11, 2026

Slice 6/19 — D-5 QueryClientPort | Unit: @netscript/sdk | Archetype: A3∪A4

Uh oh!

rickylabs commented Jun 11, 2026

Slice 7/19 — D-6a ServiceQueryUtils<TContract> mapped type | Unit: @netscript/sdk | Archetype: A3∪A4

Uh oh!

rickylabs commented Jun 11, 2026

Slice 8/19 — D-6b typed createServiceQueryUtils() | Unit: @netscript/sdk | Archetype: A3∪A4

Uh oh!

rickylabs commented Jun 11, 2026

Slice 13/19 — D-11 JSDoc sweep + inflight state decision | Unit: @netscript/sdk | Archetype: A3∪A4

Uh oh!

rickylabs commented Jun 11, 2026

Slice 14/19 — module docs | Unit: @netscript/sdk | Archetype: A3∪A4

Uh oh!

rickylabs commented Jun 11, 2026

Slice 15/19 — README + architecture docs | Unit: @netscript/sdk | Archetype: A3∪A4

Uh oh!

rickylabs commented Jun 11, 2026

Slice 16/19 — doctest runner + unit tests | Unit: @netscript/sdk | Archetype: A3∪A4

Uh oh!

rickylabs commented Jun 11, 2026

Slice 17/19 — type-level assignability fixtures | Unit: @netscript/sdk | Archetype: A3∪A4

Uh oh!

rickylabs commented Jun 11, 2026

Slice 18/19 — live service-client integration | Unit: @netscript/sdk | Archetype: A3∪A4

Uh oh!

rickylabs commented Jun 11, 2026

Slice 19/19 — D-14 root-exclude lift + full gate sweep | Unit: @netscript/sdk | Archetype: A3∪A4

Uh oh!

rickylabs commented Jun 11, 2026

Unit COMPLETE — @netscript/sdk | Archetype: A3∪A4

Slice-19 Full Validation Sweep

Uh oh!

rickylabs commented Jun 11, 2026

Uh oh!

rickylabs commented Jun 11, 2026

Uh oh!

rickylabs commented Jun 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

OpenHands Agent — success

Sub-wave 5b — `@netscript/sdk` (generator hand-off)

rickylabs commented Jun 11, 2026 •

edited

Loading

Slice 2/19 — D-1 Move implementation under `src/` facades | Unit: @netscript/sdk | Archetype: A3∪A4

Slice 3/19 — D-2 `interfaces` → `ports` | Unit: @netscript/sdk | Archetype: A3∪A4

Slice 4/19 — D-3 Fold `./adapters` and `./openapi` | Unit: @netscript/sdk | Archetype: A3∪A4

Slice 6/19 — D-5 `QueryClientPort` | Unit: @netscript/sdk | Archetype: A3∪A4

Slice 7/19 — D-6a `ServiceQueryUtils<TContract>` mapped type | Unit: @netscript/sdk | Archetype: A3∪A4

Slice 8/19 — D-6b typed `createServiceQueryUtils()` | Unit: @netscript/sdk | Archetype: A3∪A4

rickylabs commented Jun 11, 2026 •

edited

Loading

rickylabs commented Jun 11, 2026 •

edited

Loading