@braidlabs/contract 0.1.1

package/README.md

@@ -0,0 +1,95 @@
+# `@braidlabs/contract`
+
+Data-driven schema migrations: the API that owns a contract **publishes its
+history as a document**, and consumers — including consumers built before the
+newest version existed — fetch it, interpret it, and migrate in either
+direction. No client redeploy required.
+
+```jsonc
+// GET /.well-known/skew/contracts/portfolio-fund
+{
+  "skewContract": "1",
+  "name": "portfolio-fund",
+  "current": 2,
+  "steps": [
+    {
+      "from": 1, "to": 2,
+      "description": "promote scalars to structure; add liquidity fields",
+      "ops": [
+        { "rename": { "from": "currency", "to": "baseCurrency" } },
+        { "wrap": { "path": "nav", "key": "amount", "also": { "asOf": { "$now": true } } } },
+        { "move": { "from": "cashPct", "to": "liquidity.cashPct" } },
+        { "default": { "path": "liquidity.hqlaPct", "value": 0 } }
+      ]
+    }
+  ],
+  "schemas": { "1": { /* JSON Schema */ }, "2": { /* JSON Schema */ } }
+}
+```
+
+Nothing in a document is executable. Ops are interpreted against a closed
+whitelist (`rename`, `move`, `wrap`, `hoist`, `map`, `default`, `drop`,
+`convert`, `const`), and each op knows its inverse — so declaring the up
+migration buys the down migration, with the guessed fields (`derivedPaths`)
+and the discarded ones (`lossyPaths`) computed rather than hand-annotated.
+
+## Why this exists
+
+The `ahead` failure — data written by a newer build than the reader — is the
+one failure a code-shipped migration chain can never fix: the reader was built
+before the knowledge existed. But **an API is always at least as new as the
+newest data it serves.** So the origin that produced the too-new data can also
+serve the document that explains it:
+
+```ts
+import { createContractResolver, wellKnownContractUrl } from '@braidlabs/contract';
+
+const resolver = createContractResolver();
+const url = wellKnownContractUrl(API_BASE, 'portfolio-fund');
+
+// Reads exactly like schema.read(); the difference only appears on `ahead`:
+// fetch the contract, learn the newer steps, read a downgraded projection.
+const result = await resolver.readResolving(FundSchemaV1, body, url);
+if (result.ok && result.downgradedFrom) {
+  // honest, lossy, and labeled: result.lossyPaths names what v1 cannot carry
+}
+```
+
+## Building schemas from a document
+
+```ts
+import { versionedFromContract } from '@braidlabs/contract';
+
+// Drop-in replacement for a hand-maintained versioned().next() chain:
+const FundSchema = versionedFromContract<FundV2>(fundContract);
+
+// A build pinned below current still learns the newer steps — they feed the
+// shared registry, which is what read() consults to downgrade newer data:
+const FundSchemaV1 = versionedFromContract<FundV1>(fundContract, { at: 1 });
+```
+
+Steps a document cannot express (semantic transforms) are declared as
+`"code": "derive-summary"` — the *name* of an implementation the consuming
+bundle ships via `codeSteps`. A consumer without the implementation degrades
+loudly with `gap`, never with a guess. A contract accumulating `code` steps is
+a signal the change wanted a new resource, not a new version.
+
+## Frozen types, generated
+
+`skew-contract gen` (in `@braidlabs/build`) emits one frozen interface per
+documented version plus the document as a typed const, which retires the
+hardest rule in schema versioning — "never edit a past version's interface" —
+by making the document the only source:
+
+```sh
+skew-contract gen --in contracts/portfolio-fund.json \
+                  --out src/generated/portfolio-fund.contract.ts
+```
+
+## Trust model
+
+A contract document is fetched from the same origin whose data you already
+trust, carries no executable code, is cached with ETag revalidation (a stale
+copy still beats none when the origin is unreachable), and can be pinned by
+content fingerprint (`pinnedFingerprints`) when the deployment pipeline knows
+exactly which contract it was built against.

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@braidlabs/contract",
+  "version": "0.1.1",
+  "description": "Data-driven schema migrations: publish a contract document from your API, resolve it at runtime, and migrate in both directions without shipping new client code.",
+  "keywords": [
+    "version-skew",
+    "migration",
+    "schema-versioning",
+    "api-contract",
+    "lens"
+  ],
+  "license": "MIT",
+  "sideEffects": false,
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "peerDependencies": {
+    "@braidlabs/skew": "^0.1.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/braidjs/braid.git",
+    "directory": "libs/contract"
+  },
+  "homepage": "https://github.com/braidjs/braid#readme",
+  "bugs": {
+    "url": "https://github.com/braidjs/braid/issues"
+  },
+  "module": "./src/index.js"
+}

package/src/index.d.ts

@@ -0,0 +1,3 @@
+export * from './lib/document.js';
+export * from './lib/schema-from-contract.js';
+export * from './lib/resolver.js';

package/src/index.js

@@ -0,0 +1,4 @@
+export * from './lib/document.js';
+export * from './lib/schema-from-contract.js';
+export * from './lib/resolver.js';
+//# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../libs/contract/src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,mBAAmB,CAAC"}

package/src/lib/document.d.ts

@@ -0,0 +1,62 @@
+import { LensOp } from '@braidlabs/skew';
+/**
+ * The contract document — a schema's history as *data*.
+ *
+ * A closure-based migration chain can only travel inside the bundle that
+ * compiled it, which is why every consumer of a contract ends up hand-copying
+ * frozen interfaces and hoping they stay in agreement. A contract document is
+ * the same knowledge made portable: published by the API that owns the
+ * contract, fetched (or codegen'd) by consumers, interpreted — never
+ * executed — on arrival.
+ *
+ * The property that makes runtime resolution worth having: **an API is always
+ * at least as new as the newest data it serves.** A client that hits `ahead`
+ * can fetch the contract from the very origin that produced the too-new data,
+ * obtain the steps it was born too early to know, and migrate down. The
+ * `ahead` dead end resolves itself without redeploying the client.
+ *
+ * Each step is either:
+ *
+ * - `ops` — declarative, invertible-by-construction where the ops allow, the
+ *   default for structural evolution; or
+ * - `code` — the name of a migration this document *cannot* express (a
+ *   semantic transform). Consumers that carry an implementation under that
+ *   name run it; consumers that don't degrade loudly with `gap`. A contract
+ *   accumulating `code` steps is a signal the change wanted a new resource,
+ *   not a new version.
+ */
+export interface SkewContractStep {
+    readonly from: number;
+    readonly to: number;
+    readonly description: string;
+    readonly ops?: readonly LensOp[];
+    readonly code?: string;
+}
+export interface SkewContractDocument {
+    /** Format version of the document itself. */
+    readonly skewContract: '1';
+    /** The contract's name — the same string consumers pass to `versioned()`. */
+    readonly name: string;
+    /** The newest version the publisher serves. */
+    readonly current: number;
+    /** Every transition, oldest first, covering v1 → `current` contiguously. */
+    readonly steps: readonly SkewContractStep[];
+    /** Optional JSON Schema per version, keyed by version number as a string. */
+    readonly schemas?: Readonly<Record<string, unknown>>;
+}
+/** The well-known path a Skew-aware origin publishes contracts under. */
+export declare function wellKnownContractPath(name: string): string;
+/** Absolute or origin-relative URL for a contract on a given base. */
+export declare function wellKnownContractUrl(base: string, name: string): string;
+/**
+ * Content fingerprint of a document — order-insensitive for object keys, so
+ * logically identical documents always agree. Used for pinning and as an
+ * ETag.
+ */
+export declare function contractFingerprint(doc: SkewContractDocument): string;
+/**
+ * Validates an untrusted value as a contract document. Throws `TypeError`
+ * with a message naming the first problem — a malformed contract must fail at
+ * the boundary where it arrived, not later inside a migration.
+ */
+export declare function parseContractDocument(raw: unknown): SkewContractDocument;

package/src/lib/document.js

@@ -0,0 +1,76 @@
+import { canonicalJson, fnv1a } from '@braidlabs/skew';
+/** The well-known path a Skew-aware origin publishes contracts under. */
+export function wellKnownContractPath(name) {
+    return `/.well-known/skew/contracts/${encodeURIComponent(name)}`;
+}
+/** Absolute or origin-relative URL for a contract on a given base. */
+export function wellKnownContractUrl(base, name) {
+    return `${base.replace(/\/$/, '')}${wellKnownContractPath(name)}`;
+}
+/**
+ * Content fingerprint of a document — order-insensitive for object keys, so
+ * logically identical documents always agree. Used for pinning and as an
+ * ETag.
+ */
+export function contractFingerprint(doc) {
+    return fnv1a(canonicalJson(doc));
+}
+/**
+ * Validates an untrusted value as a contract document. Throws `TypeError`
+ * with a message naming the first problem — a malformed contract must fail at
+ * the boundary where it arrived, not later inside a migration.
+ */
+export function parseContractDocument(raw) {
+    const fail = (message) => {
+        throw new TypeError(`skew contract: ${message}`);
+    };
+    if (typeof raw !== 'object' || raw === null)
+        fail('document must be an object');
+    const doc = raw;
+    if (doc['skewContract'] !== '1') {
+        fail(`unsupported document format "${String(doc['skewContract'])}" — this reader understands "1"`);
+    }
+    if (typeof doc['name'] !== 'string' || doc['name'].length === 0) {
+        fail('name must be a non-empty string');
+    }
+    const current = doc['current'];
+    if (!Number.isInteger(current) || current < 1) {
+        fail(`current must be a positive integer, got ${String(current)}`);
+    }
+    if (!Array.isArray(doc['steps']))
+        fail('steps must be an array');
+    const steps = doc['steps'];
+    if (steps.length !== current - 1) {
+        fail(`steps must cover v1 → v${String(current)} contiguously: expected ${current - 1} steps, got ${steps.length}`);
+    }
+    steps.forEach((entry, index) => {
+        if (typeof entry !== 'object' || entry === null)
+            fail(`step ${index} must be an object`);
+        const step = entry;
+        const expectedTo = index + 2;
+        if (step['to'] !== expectedTo) {
+            fail(`step ${index} must target v${expectedTo}, got ${String(step['to'])}`);
+        }
+        if (step['from'] !== expectedTo - 1) {
+            fail(`step ${index} must come from v${expectedTo - 1}, got ${String(step['from'])}`);
+        }
+        if (typeof step['description'] !== 'string' || step['description'].length === 0) {
+            fail(`step ${index} needs a description`);
+        }
+        const hasOps = step['ops'] !== undefined;
+        const hasCode = step['code'] !== undefined;
+        if (hasOps === hasCode) {
+            fail(`step ${index} must declare exactly one of "ops" or "code"`);
+        }
+        if (hasOps && !Array.isArray(step['ops']))
+            fail(`step ${index} ops must be an array`);
+        if (hasCode && (typeof step['code'] !== 'string' || step['code'].length === 0)) {
+            fail(`step ${index} code must be a non-empty migration name`);
+        }
+    });
+    if (doc['schemas'] !== undefined && (typeof doc['schemas'] !== 'object' || doc['schemas'] === null)) {
+        fail('schemas, when present, must be an object keyed by version');
+    }
+    return raw;
+}
+//# sourceMappingURL=document.js.map

package/src/lib/document.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"document.js","sourceRoot":"","sources":["../../../../../libs/contract/src/lib/document.ts"],"names":[],"mappings":"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"}

package/src/lib/resolver.d.ts

@@ -0,0 +1,60 @@
+import { ReadOptions, SkewResult, VersionedSchema } from '@braidlabs/skew';
+import { SkewContractDocument } from './document.js';
+import { ContractCodeStep } from './schema-from-contract.js';
+/**
+ * Runtime contract resolution — the async layer over `@braidlabs/skew`'s
+ * synchronous reads.
+ *
+ * Trust model: a contract document is fetched from the same origin whose
+ * *data* you already trust, and nothing in it is executable — ops are
+ * interpreted against a closed whitelist, and `code` steps only name
+ * implementations the consuming bundle itself ships. For belt-and-braces
+ * deployments, `pinnedFingerprints` refuses a document whose content hash
+ * moved.
+ */
+export interface ContractResolverOptions {
+    /** Defaults to the global `fetch`. Injected for tests and odd runtimes. */
+    readonly fetchImpl?: typeof fetch;
+    /** Implementations for named `code` steps, passed through to every load. */
+    readonly codeSteps?: Readonly<Record<string, ContractCodeStep<any, any>>>;
+    /**
+     * Expected content fingerprint per contract URL. A resolved document whose
+     * fingerprint differs is refused — use when the deployment pipeline knows
+     * exactly which contract it was built against.
+     */
+    readonly pinnedFingerprints?: Readonly<Record<string, string>>;
+    /**
+     * List-schema names to derive per contract name. An API publishes the
+     * *item* contract (`portfolio-fund`); a client often reads the collection
+     * through its own list schema (`portfolio-funds`). Declaring
+     * `{ 'portfolio-fund': 'portfolio-funds' }` here makes every resolve also
+     * register the item steps lifted element-wise under the list name.
+     */
+    readonly lists?: Readonly<Record<string, string>>;
+}
+export interface ContractResolver {
+    /**
+     * Fetches, validates, and caches a contract document. Subsequent calls for
+     * the same URL revalidate with `If-None-Match` when the origin sent an
+     * ETag, and fall back to the cached copy when the origin is unreachable —
+     * a stale contract is still a better guide than none.
+     */
+    resolve(url: string): Promise<SkewContractDocument>;
+    /**
+     * Resolves a document and registers every runnable step with the shared
+     * registry — after which any schema of the same contract name, in any
+     * bundle of the page, can read across versions it never shipped.
+     */
+    resolveAndRegister(url: string): Promise<SkewContractDocument>;
+    /**
+     * The `ahead` cure, packaged: read; if the result is `ahead`, resolve the
+     * contract (which the origin serves, and the origin is always at least as
+     * new as the data it produced), then read again with the newly registered
+     * down-steps. Any other outcome — success or failure — passes through
+     * untouched.
+     */
+    readResolving<T>(schema: VersionedSchema<T>, raw: unknown, contractUrl: string, options?: ReadOptions): Promise<SkewResult<T>>;
+    /** Drops the cache — the next resolve refetches unconditionally. */
+    invalidate(url?: string): void;
+}
+export declare function createContractResolver(options?: ContractResolverOptions): ContractResolver;

package/src/lib/resolver.js

@@ -0,0 +1,97 @@
+import { __awaiter } from "tslib";
+import { registerSchema, versionedList, } from '@braidlabs/skew';
+import { contractFingerprint, parseContractDocument, } from './document.js';
+import { versionedFromContract } from './schema-from-contract.js';
+export function createContractResolver(options = {}) {
+    var _a;
+    const cache = new Map();
+    const inFlight = new Map();
+    // Wrapped rather than referenced: a bare `fetch` alias loses its `window`
+    // receiver in browsers and throws "Illegal invocation".
+    const doFetch = (_a = options.fetchImpl) !== null && _a !== void 0 ? _a : ((input, init) => fetch(input, init));
+    function fetchDocument(url) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const cached = cache.get(url);
+            const headers = { accept: 'application/json' };
+            if (cached === null || cached === void 0 ? void 0 : cached.etag)
+                headers['if-none-match'] = cached.etag;
+            let response;
+            try {
+                response = yield doFetch(url, { headers });
+            }
+            catch (cause) {
+                if (cached)
+                    return cached.doc;
+                const unreachable = new Error(`skew contract: could not reach ${url}`);
+                unreachable.cause = cause;
+                throw unreachable;
+            }
+            if (response.status === 304 && cached)
+                return cached.doc;
+            if (!response.ok) {
+                if (cached)
+                    return cached.doc;
+                throw new Error(`skew contract: ${url} answered HTTP ${response.status}`);
+            }
+            const doc = parseContractDocument(yield response.json());
+            const pinned = (_a = options.pinnedFingerprints) === null || _a === void 0 ? void 0 : _a[url];
+            if (pinned !== undefined) {
+                const actual = contractFingerprint(doc);
+                if (actual !== pinned) {
+                    throw new Error(`skew contract: ${url} resolved to fingerprint ${actual}, but this build pins ${pinned} — refusing the document`);
+                }
+            }
+            cache.set(url, { doc, etag: response.headers.get('etag') });
+            return doc;
+        });
+    }
+    function resolve(url) {
+        const pending = inFlight.get(url);
+        if (pending)
+            return pending;
+        const request = fetchDocument(url).finally(() => inFlight.delete(url));
+        inFlight.set(url, request);
+        return request;
+    }
+    return {
+        resolve,
+        resolveAndRegister(url) {
+            return __awaiter(this, void 0, void 0, function* () {
+                var _a;
+                const doc = yield resolve(url);
+                // Building at `current` materializes and registers every runnable step;
+                // the schema itself is only kept long enough to lift it to a list.
+                const schema = versionedFromContract(doc, { codeSteps: options.codeSteps });
+                const listName = (_a = options.lists) === null || _a === void 0 ? void 0 : _a[doc.name];
+                if (listName !== undefined) {
+                    registerSchema(versionedList(schema, listName));
+                }
+                return doc;
+            });
+        },
+        readResolving(schema, raw, contractUrl, readOptions) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const first = schema.read(raw, readOptions);
+                if (first.ok || first.reason !== 'ahead')
+                    return first;
+                try {
+                    yield this.resolveAndRegister(contractUrl);
+                }
+                catch (_a) {
+                    // The refusal stands, with its original, accurate message — the cure
+                    // failed, the diagnosis didn't.
+                    return first;
+                }
+                return schema.read(raw, readOptions);
+            });
+        },
+        invalidate(url) {
+            if (url === undefined)
+                cache.clear();
+            else
+                cache.delete(url);
+        },
+    };
+}
+//# sourceMappingURL=resolver.js.map

package/src/lib/resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver.js","sourceRoot":"","sources":["../../../../../libs/contract/src/lib/resolver.ts"],"names":[],"mappings":"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"}

package/src/lib/schema-from-contract.d.ts

@@ -0,0 +1,45 @@
+import { MigrationContext, VersionedSchema } from '@braidlabs/skew';
+import { SkewContractDocument } from './document.js';
+/**
+ * A named implementation for a contract step declared as `code` — the escape
+ * hatch for semantic migrations the op set cannot express. Shipped inside the
+ * consuming bundle, referenced by name from the document.
+ */
+export interface ContractCodeStep<TFrom = unknown, TTo = unknown> {
+    readonly up: (previous: TFrom, ctx: MigrationContext) => TTo;
+    readonly down?: (next: TTo, ctx: MigrationContext) => TFrom;
+    readonly derives?: readonly string[];
+    readonly downDerives?: readonly string[];
+    readonly lossy?: readonly string[];
+}
+export interface ContractSchemaOptions<TCurrent> {
+    /**
+     * Version this build is pinned to. Defaults to the document's `current`.
+     * A build pinned below `current` still learns the newer steps: they are
+     * contributed to the shared registry (unless `register` is false), which is
+     * what lets `read()` downgrade data from the future.
+     */
+    readonly at?: number;
+    /** Implementations for the document's named `code` steps. */
+    readonly codeSteps?: Readonly<Record<string, ContractCodeStep<any, any>>>;
+    /**
+     * Contribute every runnable step to the shared registry. Defaults to
+     * `true` — adopting a published contract *is* the explicit act of sharing
+     * that plain `versioned()` declarations require `registerSchema` for.
+     */
+    readonly register?: boolean;
+    readonly validate?: (value: unknown) => value is TCurrent;
+    readonly assumeLegacyVersion?: number;
+}
+/**
+ * Builds a {@link VersionedSchema} from a contract document — the drop-in,
+ * data-driven replacement for a hand-maintained `versioned().next()` chain.
+ *
+ * - `ops` steps compile to up *and* (where invertible) down migrations, with
+ *   derived and lossy paths computed rather than hand-annotated.
+ * - `code` steps use the implementation supplied in `codeSteps`; a missing
+ *   implementation leaves a hole that reads as `gap` — loud, not guessed.
+ * - Steps beyond the pinned version feed the shared registry, so this build
+ *   can downgrade newer data it could never have shipped knowledge of.
+ */
+export declare function versionedFromContract<TCurrent>(doc: SkewContractDocument, options?: ContractSchemaOptions<TCurrent>): VersionedSchema<TCurrent>;

package/src/lib/schema-from-contract.js

@@ -0,0 +1,71 @@
+import { compileLens, registerSteps, versionedFromSteps, } from '@braidlabs/skew';
+/**
+ * Builds a {@link VersionedSchema} from a contract document — the drop-in,
+ * data-driven replacement for a hand-maintained `versioned().next()` chain.
+ *
+ * - `ops` steps compile to up *and* (where invertible) down migrations, with
+ *   derived and lossy paths computed rather than hand-annotated.
+ * - `code` steps use the implementation supplied in `codeSteps`; a missing
+ *   implementation leaves a hole that reads as `gap` — loud, not guessed.
+ * - Steps beyond the pinned version feed the shared registry, so this build
+ *   can downgrade newer data it could never have shipped knowledge of.
+ */
+export function versionedFromContract(doc, options = {}) {
+    var _a;
+    const at = (_a = options.at) !== null && _a !== void 0 ? _a : doc.current;
+    if (!Number.isInteger(at) || at < 1 || at > doc.current) {
+        throw new TypeError(`skew contract: cannot pin "${doc.name}" at v${at} — the document covers v1 through v${doc.current}`);
+    }
+    const localSteps = [];
+    const futureSteps = [];
+    for (const contractStep of doc.steps) {
+        const step = materialize(doc.name, contractStep, options.codeSteps);
+        if (contractStep.to <= at) {
+            localSteps[contractStep.to - 2] = step;
+        }
+        else if (step) {
+            futureSteps.push(step);
+        }
+    }
+    // Preserve chain length even when the last local step is a hole.
+    localSteps.length = at - 1;
+    const schema = versionedFromSteps(doc.name, localSteps, {
+        validate: options.validate,
+        assumeLegacyVersion: options.assumeLegacyVersion,
+    });
+    if (options.register !== false) {
+        registerSteps(doc.name, localSteps);
+        registerSteps(doc.name, futureSteps);
+    }
+    return schema;
+}
+/** Compiles one contract step, or returns `undefined` for an unrunnable one. */
+function materialize(name, contractStep, codeSteps) {
+    var _a;
+    if (contractStep.ops) {
+        const lens = compileLens(contractStep.ops);
+        return {
+            to: contractStep.to,
+            description: contractStep.description,
+            up: lens.up,
+            down: (_a = lens.down) !== null && _a !== void 0 ? _a : undefined,
+            derives: lens.derivedUp,
+            downDerives: lens.derivedDown,
+            lossy: lens.lossyDown,
+            ops: contractStep.ops,
+        };
+    }
+    const implementation = contractStep.code ? codeSteps === null || codeSteps === void 0 ? void 0 : codeSteps[contractStep.code] : undefined;
+    if (!implementation)
+        return undefined;
+    return {
+        to: contractStep.to,
+        description: contractStep.description,
+        up: implementation.up,
+        down: implementation.down,
+        derives: implementation.derives,
+        downDerives: implementation.downDerives,
+        lossy: implementation.lossy,
+    };
+}
+//# sourceMappingURL=schema-from-contract.js.map

package/src/lib/schema-from-contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-from-contract.js","sourceRoot":"","sources":["../../../../../libs/contract/src/lib/schema-from-contract.ts"],"names":[],"mappings":"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"}