Skip to content

feat(core): add seam foundations. - #30

Merged
OmarAlJarrah merged 2 commits into
mainfrom
29-phase-2
Aug 10, 2026
Merged

feat(core): add seam foundations.#30
OmarAlJarrah merged 2 commits into
mainfrom
29-phase-2

Conversation

@Wahbeh-Mohammad

Copy link
Copy Markdown
Contributor

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 pure
functions — no concrete Transport or Serde implementation lands here.

What's new

  • Transport (seams/transport.ts) — one Promise<Response> contract collapsing SEAM-11/16, with
    close(): Promise<void> locked in from day one (adding a required method to a published seam later
    would 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.
    isTimeoutSignal keys on signal.reason.name, not instanceof DOMException, because instanceof
    is realm-bound and would misreport a genuine timeout from a node:vm context 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): T is exactly the erased generic SEAM-21 forbids; keeping it out of the
    api-extractor surface means Phase 6's type-witness rework is not a breaking change.

Retrofits to Phase 1

  • encodeRfc3986Component extracted to http/rfc3986.ts, now the single implementation behind both
    QueryParams.encode() and buildRequest's path-segment encoding (HTTP-29).
  • DexpaceError is the new taxonomy root; DomainModelError extends DexpaceError. A cancelled
    transport call is not a domain-model construction failure. Additive — every Phase 1 leaf keeps its
    parent and its instanceof DomainModelError narrowing.

Toolchain

lib gains "DOM" so AbortSignal/DOMException resolve from a declared lib rather than
incidentally from @types/bun's ambient globals (NFR-10). Because lib.dom also declares global
Request/Response/Headers, a no-restricted-globals rule now catches a file that forgets its own
import and silently type-checks against the DOM global instead.

New node-floor-conformance CI job runs the built artifact on literal Node 18.17.0 — the declared
floor, and the exact version AbortSignal.any() landed in. This residual was pulled forward from
Phase 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 zero
Serde references.

…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.
@Wahbeh-Mohammad Wahbeh-Mohammad linked an issue Aug 10, 2026 that may be closed by this pull request
@OmarAlJarrah
OmarAlJarrah merged commit 8e55792 into main Aug 10, 2026
2 checks passed
@OmarAlJarrah
OmarAlJarrah deleted the 29-phase-2 branch August 10, 2026 23:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Phase 2

2 participants