Skip to content

sdk/contracts: record the ThrowableError substitution decision and back the deferred bench-prose debt #1693

Description

@rickylabs

Two low-severity items from the #1692 IMPL-EVAL (PASS-WITH-FINDINGS at bcc9f393d), tracked together
because both are "recorded but unbacked" rather than defects. Neither blocks 0.0.7.

F3 — ThrowableError → Error forecloses a consumer extension point

@netscript/sdk's public error types now default TError = Error rather than oRPC's
ThrowableError, which is defined as:

type ThrowableError = Registry extends { throwableError: infer T } ? T : Error

Registry is an oRPC consumer extension point. A repo-wide search finds no
declare module '@orpc/shared' augmentation, so ThrowableError ≡ Error today and the substitution is
exact. It was chosen so the published signature does not name a type that is private relative to our
entrypoints.

The cost: if a downstream consumer ever augments Registry.throwableError, our defaults will not follow
it. This is acceptable now — the affected signatures are new in 0.0.7, so no published consumer can
depend on the old behaviour — but it is a decision with a future trigger and currently has no pointer.

Wanted: a decision record, and a re-evaluation if Registry augmentation is ever requested. The
likely fix is re-exporting ThrowableError from the SDK entrypoints so the name becomes public rather
than substituted — which was not done here because it is barrel growth across three entrypoints.

Recorded at worklog.md (S5 section) in
.llm/runs/fix-sdk-typed-error-channel--0.0.7-wave1/.

F5 — the "tracked" bench-prose debt is not actually tracked

PLAN-EVAL advisory A4 for #1350 asked that the deferred stale-prose follow-up
(packages/contracts/README.md and benchmark reference text, which were a seventh path and therefore a
rescope) be recorded so it is genuinely tracked.

The run record is currently self-contradictory: drift.md:25 says the prose "remains tracked follow-up
debt", while drift.md:35-36 says "No new file or debt entry was created; the coordinator owns any
later issue." The word "tracked" has nothing behind it.

Wanted: this issue is that backing. The stale prose in packages/contracts/README.md and the
benchmark reference text still describes the pre-#1350 error-handling shape and should be refreshed
alongside any future pass over that surface.


Refs #1350, #1692. Filed by the 0.0.7 fixes topic supervisor per coordinator ruling, consolidating F3
and F5 into one follow-up rather than two.

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:sdkpackages/sdkpriority:p3Low / nice-to-havestatus:triageIncoming; not yet triagedtype:choreTooling, config, or housekeeping

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions