feat(core): add seam foundations. - #30
Merged
Merged
Conversation
…ror root (SEAM-11/12/14/16/17/19/26/27/30) Ships the Phase 2 seam contracts: the Transport interface with composeSignal/isTimeoutSignal and CancellationError, the operation-input projection (OperationDescriptor, buildRequest, OperationAssemblyError), and an internal-only provisional Serde<T> kept out of the public barrel so Phase 6's type-witness rework stays non-breaking. Retrofits Phase 1 with a shared encodeRfc3986Component (HTTP-29) and DexpaceError as the taxonomy root above DomainModelError, and adds a node-floor-conformance CI job that runs the built artifact on Node 18.17.0. Also retrofits a Deviation Ledger section onto the Phase 2 spec and widens Phase 10's intake to row-level checks, so the dot-segment SEAM-27 rejection and Phase 9's own ledger rows can't be dropped at reconciliation.
Closed
…the coverage gate.
OmarAlJarrah
approved these changes
Aug 10, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Phase 2 — Seam Foundations
Ships the seam contracts later phases build on, per
docs/superpowers/specs/2026-07-23-phase2-seam-foundations-design.md. Interfaces plus three purefunctions — no concrete
TransportorSerdeimplementation lands here.What's new
Transport(seams/transport.ts) — onePromise<Response>contract collapsing SEAM-11/16, withclose(): Promise<void>locked in from day one (adding a required method to a published seam laterwould be breaking). SEAM-12/13/14/15/18/30 ride as TSDoc obligations; their conformance tests belong
to Phase 8, which owns the first real adapter.
composeSignal/isTimeoutSignal/CancellationError— reusable cancellation primitives.isTimeoutSignalkeys onsignal.reason.name, notinstanceof DOMException, becauseinstanceofis realm-bound and would misreport a genuine timeout from a
node:vmcontext or worker (XCUT-2).OperationDescriptor/buildRequest/OperationAssemblyError(seams/operation.ts) —SEAM-26/27 projection with the full base-URL composition ruleset.
Serde<T>— provisional,@internal, and deliberately absent from the public barrel.deserialize(data: unknown): Tis exactly the erased generic SEAM-21 forbids; keeping it out of theapi-extractor surface means Phase 6's type-witness rework is not a breaking change.
Retrofits to Phase 1
encodeRfc3986Componentextracted tohttp/rfc3986.ts, now the single implementation behind bothQueryParams.encode()andbuildRequest's path-segment encoding (HTTP-29).DexpaceErroris the new taxonomy root;DomainModelError extends DexpaceError. A cancelledtransport call is not a domain-model construction failure. Additive — every Phase 1 leaf keeps its
parent and its
instanceof DomainModelErrornarrowing.Toolchain
libgains"DOM"soAbortSignal/DOMExceptionresolve from a declared lib rather thanincidentally from
@types/bun's ambient globals (NFR-10). Becauselib.domalso declares globalRequest/Response/Headers, ano-restricted-globalsrule now catches a file that forgets its ownimport and silently type-checks against the DOM global instead.
New
node-floor-conformanceCI job runs the built artifact on literal Node 18.17.0 — the declaredfloor, and the exact version
AbortSignal.any()landed in. This residual was pulled forward fromPhase 3 (NFR-10/NFR-17).
Verification
All eleven gates green:
typecheck·lint·build·test(190 pass, 100% line coverage) ·api:ci·lint:publish·verify:dual-consumption·verify:seam-1·verify:runtime-floor·verify:node-floor·audit. API report regenerated with zero(undocumented)entries and zeroSerdereferences.