Epic: Typed SDK client contributions — credentials, transport policy, metadata, and cache-safe extensions

[rickylabs]

Important

0.0.7 normative scope amendment — 2026-08-13. RFC 0001 was merged by PR #1390 and is the
ratified source of truth. Its public protocol is the versioned SdkClientContribution contract,
contribution-owned context projection, disjoint header ownership, and explicit response-cache
declaration in rfcs/0001-sdk-client-contributions.md. The older envelope, callback-array,
public-link, NetScriptProcedureMeta.policy, #928/#934 milestone, and custom-link-unblocking
statements below are historical proposal text and are non-normative where they conflict with the
merged RFC. Stage 0 is accepted; #1466 owns procedure metadata; #1349–#1353 are amended below.

Summary

@netscript/sdk owns a transport nobody can extend. CreateServiceClientOptions is a closed
nine-field record with no headers, fetch, interceptors, plugins, link, or context type
parameter, and ServiceClientContext is a closed interface rather than a type parameter — so the
shipped auth plugin cannot ride the typed client, no plugin can contribute to client construction,
and procedure policy metadata does not exist. Every mechanism needed is already present in the
pinned oRPC 1.14.6, so this is an un-hiding problem, not a missing-primitive problem. This RFC
ratifies one versioned SdkClientContribution contract that carries client construction, request
context, headers/credentials, transport middleware, $meta policy metadata, response/error types,
and query defaults/invalidation through a single typed chain, before #928 defines a second
contribution dialect and before #934 invents its own policy shape.

Evidence

• RFC text: rfcs/RFC-A-sdk-client-composition.md (this run).
• Corpus: research/repo-audit/services-sdk.md §2, §3.1–§3.6, gap register S4/S5/S11/S12/S13;
  research/repo-audit/auth.md §0, §2, §3.1, gaps G1/G2/G9/G10;
  research/external/orpc.md §1, §4 (G1–G4, G6, G7, G11), §5, §6.
• Source at baseline fac9e339042c (re-verified for this draft):
  • packages/sdk/src/ports/service-client.ts:203-222 — the closed nine-field options record;
    port and timeout documented "Reserved …".
  • packages/sdk/src/ports/service-client.ts:129-155 — ServiceClientContext is a concrete
    interface, not a type parameter.
  • packages/sdk/src/client/service-client.ts:41-49 — port/timeout are never destructured.
  • packages/sdk/src/client/http-client-link.ts:82-126 — method, headers, and plugins are
    literals inside the link.
  • packages/sdk/src/client/mod.ts:15-36 — createHttpClientLink is not exported;
    packages/sdk/src/ports/mod.ts:7 advertises "the transport seam" while
    packages/sdk/src/ports/client-link-factory.ts:18-25 is unexported.
  • packages/service/src/primitives/handlers.ts:41-58 vs
    packages/service/src/builder/service-rpc.ts:57 — RPCHandlerConfig.plugins exists and is never
    populated by the builder path.
  • packages/plugin/src/config/domain/plugin-contributions.ts:12-39 — twelve contribution groups,
    none client-side; :16 is a closed literal union naming a first-party plugin.
  • grep -rnE '\$meta<|\.meta\(' packages plugins → no oRPC metadata usage.
• Board: [frontend-contrib S6] @netscript/plugin-frontend-core contracts/v1 #928 (contribution contracts v1, 0.0.7), [frontend-contrib S12] Generated deny-by-default procedure gateway #934 (deny-by-default gateway, 0.0.7), [sdk-client S8] fix(plugin-core): let third-party plugin factories participate in discovery #1093
  (discovery hardcodes official factories, 0.0.6), [enterprise-auth S13] Define organization-aware identity and authorization policy contracts #884 (org-aware policy contracts, 0.0.12),
  feat(sdk): in-process link-mode adapter for single-process service mounting #451 (in-process link mode, Backlog / Triage).

Current surface

createServiceClient(options) → createORPCClient(createHttpClientLink(...))
(packages/sdk/src/client/service-client.ts:41-66). The link is constructed once with literal
headers, literal plugins, hard-coded fetch, and method: inferRPCMethodFromContractRouter(contract). The only per-call seam that works is the retry/dedupe
knob set typed into ServiceClientContext (http-client-link.ts:27, regression-tested at
packages/sdk/tests/integration/service-client-runtime_test.ts:113,153). defineServices() forwards
the same nine fields and inherits the gap wholesale
(packages/sdk/src/presets/define-services.ts:106-116). There is no plugin-facing client axis
anywhere.

Target contract

A ratified RFC-A that fixes, at minimum:

• a versioned SdkClientContribution envelope (literal contractVersion, namespaced name,
  environment, requires, typed context marker, headerKeys + headers, the four oRPC
  interceptor/plugin arrays, fetch, errors, query);
• a composition algebra where the client's per-call context is the intersection of the chain's
  declared contexts and with is optional — a host app with no plugins compiles unchanged;
• a failure taxonomy in which absence, version mismatch, and conflict fail at compile time or
  construction time, never as a missing header or a silently dropped plugin;
• NetScriptProcedureMeta.policy as the single policy-metadata shape, threaded through
  baseContract via oc.$meta<…>();
• server/client environment boundaries that are enforced, not documented;
• the rule that contributions never observe the HTTP method, so oRPC v2's POST-only default lands in
  one owned function.

Ratification means: the owner accepts or amends the shape, the tracking issue receives its
milestone, and #1349…#1353 may proceed. This issue closes only when all implementation children are
merged.

Acceptance

• RFC 0001 is merged in the house shape and is the normative contract for 0.0.7.
• Contribution descriptors are limited to context projection, disjoint header authorship, and
  response-cache declarations. Transport retains retry, dedupe, tracing, link, fetch, and final
  trace-header ownership.
• Adapter ports stay private under packages/sdk/src/internal/client-contributions/; no link
  factory or adapter port becomes a public export, and feat(sdk): in-process link-mode adapter for single-process service mounting #451 remains independent.
• Q1 is resolved: 0.0.7 ships bearer-header contribution only. Cookie/session transport and
  credential mode/topology remain out of scope.
• Q2 is resolved: PluginContributions gains an optional generic sdkClients module-reference
  group with explicit generated selection; no closed official-plugin union is introduced.
• The first implementation ceiling is exactly 16 contributions. No environment-reading bearer
  convenience ships in the first slice; application code supplies credentials.
• Contribution composition wraps the outer logical call and is not memoized. Incoming
  request-header handling requires explicit selection and changes no default behavior.
• [sdk-client S1] fix(sdk): preserve contract errors through safe() and isDefinedError #1350 owns procedure metadata preservation. [sdk-client S4] refactor(sdk): centralize HTTP method and GET-cache policy #1351 upgrades the complete oRPC v1 family to
  stable v1.15.0 and keeps port/timeout accepted but deprecated.
• Public names follow RFC 0001 unless a compile/public-surface gate requires a mechanical rename.
  oRPC v2 questions are safely deferred to a separate v2 RFC and are not 0.0.7 gates.
• [sdk-client S3] feat(sdk): expose the typed oRPC client-contribution seam #1349–[sdk-client S6] feat(sdk): express trace propagation as a general contribution #1353 have in-place Acceptance sections aligned to these decisions and reference this
  tracking issue.
• Coordinator checkpoint: close this tracking issue manually, without a child PR closing keyword,
  only after [sdk-client S3] feat(sdk): expose the typed oRPC client-contribution seam #1349–[sdk-client S6] feat(sdk): express trace propagation as a general contribution #1353 and [sdk-client S2] feat(sdk): define NetScriptProcedureMeta without erasing contract errors #1466/[sdk-client S7] feat(sdk): ship locale as the non-auth contribution proof #1467/[sdk-client S8] fix(plugin-core): let third-party plugin factories participate in discovery #1093 are merged and their acceptance is verified.

Boundaries

• Do not duplicate [frontend-contrib S6] @netscript/plugin-frontend-core contracts/v1 #928 ([frontend-contrib S6] plugin-frontend-core contracts/v1) — it owns
  the frontend contribution contract; this RFC only asks that the two envelopes share a version
  field, a conflict key, and a failure taxonomy.
• Do not duplicate [frontend-contrib S12] Generated deny-by-default procedure gateway #934 (generated deny-by-default procedure gateway) — it owns the gateway;
  this RFC owns only the metadata type it will read.
• Do not duplicate [sdk-client S8] fix(plugin-core): let third-party plugin factories participate in discovery #1093 (plugin discovery hardcodes official factory functions) — it owns
  discovery; this RFC owns the contribution shape.
• Do not duplicate [enterprise-auth S13] Define organization-aware identity and authorization policy contracts #884 (organization-aware identity and authorization policy contracts) —
  tenancy typing on Principal/AuthSession stays there; this RFC only keeps the client context
  extensible enough that a tenant field can arrive later.
• Do not duplicate [enterprise-auth S14] Build an auth conformance, mocking, and scaffold test kit #885 (auth conformance/mocking/scaffold test kit) or [enterprise-auth S1] Make auth capability discovery backend-truthful #872
  (auth capability discovery).
• Do not duplicate feat(sdk): in-process link-mode adapter for single-process service mounting #451 (in-process link-mode adapter) — [sdk-client S3] feat(sdk): expose the typed oRPC client-contribution seam #1349's public link seam unblocks
  it; it stays its own issue.
• Do not duplicate Type soundness ratification: eliminate unsound and arbitrary types across the public surface and the docs #1278 (type soundness ratification) — the safe/isDefinedError repair
  is filed as [sdk-client S1] fix(sdk): preserve contract errors through safe() and isDefinedError #1350 against a specific executed check, not as a soundness sweep.
• Not in scope: implementation. This is a tracking issue; no code lands under it directly.

Docs/consumer proof

Ratification is proved by documents, not by code: the RFC text, the owner's written disposition, the
cross-links recorded on #928 and #934, and answers to Q1/Q2 on this issue. Adoption proof belongs to
the children — #1352 and #1353 must each show a working consumer, and #1350 must show
docs/site/services-sdk/sdk.md:199 compiling.

Provenance

Seed run plan-fable5-remediation-roadmap--seed, PR #1347, 2026-08-08. Drafted from the Stage-B
corpus (research/repo-audit/services-sdk.md, research/repo-audit/auth.md,
research/external/orpc.md) and Stage-C synthesis §4 (pack T1) and §5. All source claims re-verified
against worktree baseline fac9e339042c. No GitHub mutation was performed.

---

Filed from planning seed PR #1347 · source Draft-ID T1-01 · live issue #1348.

[rickylabs]

RFC-A has passed Claude Fable 5 cycle-2 review and the final Qwen 3.8 Max adversarial review with PASS_ACCEPT. Formal FCP with disposition accept is open on PR #1390 through 2026-08-15 22:00 Europe/Zurich. The maintainer dispositions, numbering order (0001), stable-v1 sequencing, and separate metadata-child decision are recorded in the FCP comment.

This tracking issue remains open after RFC merge and continues to own implementation coordination.