@braidlabs/skew 0.1.1

package/README.md

@@ -0,0 +1,247 @@
+# @braidlabs/skew
+
+Framework-agnostic primitives for surviving version skew.
+
+No dependencies. No framework. Works in browsers, Node, workers, and Deno.
+
+---
+
+## The problem
+
+Four failures that look unrelated are the same failure:
+
+| Boundary | What crosses it | Symptom |
+|---|---|---|
+| Client ↔ origin | a lazy chunk request | `ChunkLoadError` after a deploy |
+| Client ↔ API | a queued mutation, flushed later | 400s, or silent data corruption |
+| Host ↔ fragment | props and events | mismatched contracts at runtime |
+| **Past self ↔ present self** | a persisted draft or cache | `undefined` deep in a renderer |
+
+In every case, two independently-versioned parties met at a boundary and had no way to discover that they disagreed.
+
+This package is that missing primitive: **stamp what crosses a boundary with the version it was authored under, detect disagreement, then migrate forward or fail loudly.**
+
+The fourth row is the one most teams miss. A draft written by build 41 and resumed by build 57 is the same problem as a client on 41 calling a server on 57 — the counterparty is just your own past deployment.
+
+---
+
+## Install
+
+```sh
+npm install @braidlabs/skew
+```
+
+---
+
+## Versioned schemas
+
+Declare a type's current version, its history, and the functions that move data between them in one place.
+
+```ts
+import { versioned } from '@braidlabs/skew';
+
+// Snapshot shapes — frozen copies, never your live application types.
+interface V1 { id: string; themeQuote?: { text: string } }
+interface V2 { id: string; scriptureOfWeek?: { text: string } }
+type V3 = V2 & { orderOfWorship: { setting: string; hymns: string[] } };
+
+export const WeeklyContent = versioned<V1>('weekly-content')
+  .next<V2>('rename themeQuote to scriptureOfWeek', (p) => ({
+    id: p.id,
+    scriptureOfWeek: p.themeQuote,
+  }))
+  .next<V3>('introduce orderOfWorship', (p) => ({
+    ...p,
+    orderOfWorship: { setting: '', hymns: [] },
+  }));
+```
+
+Reading migrates forward automatically:
+
+```ts
+const result = WeeklyContent.read(rawFromFirestore);
+
+if (result.ok) {
+  render(result.value);              // always the current shape
+  if (result.migratedFrom !== null) {
+    console.info(`upgraded from v${result.migratedFrom}`);
+  }
+}
+```
+
+Each `next()` is typed against the previous version, so a migration that does not actually produce the next shape is a compile error. There is no terminal `build()` call — the chain *is* the schema.
+
+### The one rule
+
+**A migration must never import your current application types or services.** Close each step over its own snapshot type (`V1`, `V2`, …). The moment a migration references a live interface, it silently changes meaning the next time that interface is edited, and your old migrations start lying about what they produce.
+
+---
+
+## Results, not exceptions
+
+`read()` returns a discriminated result, because the failure modes need *different* remedies:
+
+```ts
+const result = WeeklyContent.read(raw);
+
+if (!result.ok) {
+  switch (result.reason) {
+    case 'ahead':   return refetchFromServer();  // written by a NEWER build
+    case 'gap':     return reportBug(result);    // missing migration step
+    case 'invalid': return discardAndRefetch();
+    case 'threw':   return reportBug(result);    // a migration failed
+    case 'retired': return discardAndRefetch();  // below the declared floor — policy, not a bug
+  }
+}
+```
+
+### Why `ahead` matters
+
+Data written by a newer build than the one reading it **cannot be migrated downward** — the information genuinely is not there. This is not hypothetical: a colleague saves from the new deploy while your tab is stale, or a user's phone updates before their laptop.
+
+Collapsing this into `null` means every caller guesses, and the guess is almost always "discard it" — which destroys perfectly good data that merely came from the future.
+
+---
+
+## Versioned storage
+
+The failure this prevents is the quiet one:
+
+```ts
+// Before: an assertion, not a check.
+return JSON.parse(raw) as WeeklyContent;
+```
+
+The moment the model changes, every cached record on every user's machine has the old shape while being *typed* as the new one. You get `undefined` deep inside a renderer instead of a clean failure at the boundary.
+
+```ts
+import { createVersionedStore, webStorageDriver } from '@braidlabs/skew';
+
+const drafts = createVersionedStore(WeeklyContent, {
+  driver: webStorageDriver('local'),
+  buildId: BUILD_ID,
+  onReadFailure: (key, failure) => telemetry.warn('stale draft', { key, ...failure }),
+  rewriteOnRead: true,   // read-repair: persist migrated records at the current version
+});
+
+await drafts.set('2026-12-06', content);
+const result = await drafts.get('2026-12-06');   // migrated on the way out
+
+// Sync read for signal/hook initialisers — no flash of empty state.
+const immediate = drafts.peek('2026-12-06');     // null on async drivers
+```
+
+Drivers: `memoryDriver()`, `webStorageDriver('local' | 'session')`, or implement `StorageDriver` for IndexedDB or anything else. Web Storage degrades to memory automatically under Safari private mode, disabled cookies, and SSR, and swallows quota errors on write — a failing cache should never break a save the user asked for.
+
+### Adopting on existing data
+
+You do not need a backfill. Data with no envelope is treated as **v1**, so declare your *current* shape as the base and records upgrade themselves as users touch them.
+
+```ts
+export const Parish = versioned<CurrentShape>('parish');   // v1, adopts everything
+```
+
+### Retiring old versions (cleanup)
+
+Chains are **append-only at the top and trim-only at the bottom**. A step
+`n → n+1` is deletable only when no data enveloped at ≤ n can still reach a
+reader — so cleanup is a sequence, not an edit:
+
+1. **Instrument**: watch `result.migratedFrom` in telemetry. You can only
+   delete steps you can prove are idle.
+2. **Shrink the tail**: enable `rewriteOnRead` on stores (below), so each old
+   record pays its migration once, is re-persisted at the current version,
+   and drops out of the telemetry.
+3. **Trim**: re-declare the schema with the oldest surviving shape as its
+   base and delete the retired steps. Never renumber — v4 stays v4.
+
+```ts
+// before: versioned<V1>('draft').next<V2>(…).next<V3>(…).next<V4>(…)
+export const Draft = versioned<V3>('draft', { base: 3 }).next<V4>(…);
+```
+
+Reads below the floor fail with `reason: 'retired'` (plus `floor`) — a
+*policy* outcome whose remedy is discard/refetch/reset — never `gap`, which
+still means "a step is missing and that's a bug". If another bundle on the
+page or a resolved contract still supplies the retired steps via the shared
+registry, the read simply succeeds. Bare (un-enveloped) data is still assumed
+to be v1, so after a trim it surfaces as `retired`; set
+`assumeLegacyVersion: base` only if bare data is known to carry the base
+shape. `write({ as })` below the floor throws.
+
+Retire conservatively for data you cannot refetch (drafts, queued outboxes —
+drain queues first and give users a "too old to open" path), aggressively for
+refetchable caches. Steps are cheap; delete with evidence, not tidiness.
+
+---
+
+## Build identity and skew detection
+
+```ts
+import { createVersionProbe } from '@braidlabs/skew';
+
+const probe = createVersionProbe({
+  identity: { buildId: BUILD_ID, builtAt: BUILT_AT },
+  manifestUrl: '/skew-manifest.json',   // serve with Cache-Control: no-store
+});
+
+const status = await probe.check();
+```
+
+| Status | Meaning | Correct response |
+|---|---|---|
+| `current` | in sync | — |
+| `staleClient` | a newer deploy exists | offer a reload |
+| `staleOrigin` | **origin is older than us** | **do not reload — it will loop** |
+| `differs` | cannot be ordered (no timestamps) | treat conservatively |
+| `unreachable` | offline or blocked | do not reload; you would land on an error page |
+
+`staleOrigin` is the case naïve implementations miss. If a CDN is serving a cached entry document or a region is lagging, reloading fetches the same stale bundle and fails again — forever. Detecting it requires comparing build *timestamps*, which is why `builtAt` is worth stamping.
+
+The probe collapses concurrent callers onto a single request and caches for `minIntervalMs` (default 10s), so a page that fails three chunks at once still makes one network call.
+
+### The manifest
+
+Emit it at build time and serve it uncached:
+
+```json
+{
+  "buildId": "a1b2c3d",
+  "builtAt": "2026-08-07T10:14:00Z",
+  "modules": { "admin.routes": { "file": "chunk-XYZ789.js" } }
+}
+```
+
+`modules` is optional. With it, `moduleWasRemoved(manifest, id)` distinguishes "this route moved" from "this route was deleted" — which is the difference between reloading and redirecting to a fallback.
+
+---
+
+## API
+
+| Export | Purpose |
+|---|---|
+| `versioned<T>(name, options?)` | Begin a schema declaration (`base` retires older versions) |
+| `VersionedSchema.next<TNext>(desc?, fn)` | Add a version |
+| `emitSkewTrace` / `SKEW_DEVTOOLS_HOOK` | Devtools trace hook — reads/writes emit events when a hook is installed |
+| `.read(raw)` / `.write(value, buildId?)` | Migrate in / envelope out |
+| `isEnvelope(v)` / `peekVersion(v)` | Inspect without migrating |
+| `createVersionedStore(schema, opts)` | Persistence with migration |
+| `memoryDriver()` / `webStorageDriver()` | Built-in drivers |
+| `createVersionProbe(opts)` | Build comparison against an origin |
+| `compareBuilds(identity, manifest)` | Pure classification |
+| `moduleWasRemoved(manifest, id)` | Route-deleted detection |
+| `isOk` / `isErr` / `valueOr` / `mapResult` | Result helpers |
+
+---
+
+## Related packages
+
+`@braidlabs/skew` is consumed by, but never requires, the framework bindings:
+
+- `@braidlabs/angular-router` — chunk-load recovery for the Angular router
+- `@braidlabs/angular-data` — versioned cache and durable mutation outbox
+- `@braidlabs/angular-workflow` — durable multi-step flows
+- `@braidlabs/react-*` — the same, for React
+- `@braidlabs/node` / `@braidlabs/nest` — server-side negotiation and manifest serving
+
+Each is independently installable. None requires the others.

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@braidlabs/skew",
+  "version": "0.1.1",
+  "description": "Framework-agnostic primitives for surviving version skew: versioned envelopes, migration chains, build identity and negotiation.",
+  "keywords": [
+    "version-skew",
+    "migration",
+    "schema-versioning",
+    "deployment",
+    "offline"
+  ],
+  "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"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/braidjs/braid.git",
+    "directory": "libs/skew"
+  },
+  "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,12 @@
+export * from './lib/result.js';
+export * from './lib/context.js';
+export * from './lib/versioned.js';
+export * from './lib/lens.js';
+export * from './lib/list.js';
+export * from './lib/registry.js';
+export * from './lib/fingerprint.js';
+export * from './lib/http.js';
+export * from './lib/identity.js';
+export * from './lib/storage.js';
+export * from './lib/devtools.js';
+export * from './lib/disabled.js';

package/src/index.js

@@ -0,0 +1,14 @@
+export * from './lib/result.js';
+export * from './lib/context.js';
+export * from './lib/versioned.js';
+export * from './lib/lens.js';
+export * from './lib/list.js';
+export * from './lib/registry.js';
+export * from './lib/fingerprint.js';
+export * from './lib/http.js';
+export * from './lib/identity.js';
+export * from './lib/storage.js';
+export * from './lib/devtools.js';
+// Not public API. Undocumented on purpose — read the module comment first.
+export * from './lib/disabled.js';
+//# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../libs/skew/src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAElC,2EAA2E;AAC3E,cAAc,mBAAmB,CAAC"}

package/src/lib/context.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The context handed to every migration function.
+ *
+ * Migrations must be deterministic: the same input must produce the same
+ * output, or replays, tests, memoization, and fingerprinting all quietly
+ * break. Anything a migration needs from the outside world therefore arrives
+ * through this context — never through `new Date()` or `Math.random()` inside
+ * the migration body — so a test (or a replay) can pin it.
+ */
+export interface MigrationContext {
+    /**
+     * The clock. A migration that needs "now" (an `asOf` stamp, a derived
+     * timestamp) must take it from here so two runs over the same input can be
+     * made to agree.
+     */
+    now(): Date;
+    /**
+     * A stable seed for anything that must be unique-but-reproducible — a
+     * derived idempotency key, a placeholder reference. Callers that retry a
+     * migration (an outbox, a replay) pass the same seed each attempt so the
+     * derived value stays identical across attempts.
+     */
+    readonly seed?: string;
+}
+/** The context used when a caller supplies none: the real clock, no seed. */
+export declare const defaultMigrationContext: MigrationContext;

package/src/lib/context.js

@@ -0,0 +1,5 @@
+/** The context used when a caller supplies none: the real clock, no seed. */
+export const defaultMigrationContext = {
+    now: () => new Date(),
+};
+//# sourceMappingURL=context.js.map

package/src/lib/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../../../../libs/skew/src/lib/context.ts"],"names":[],"mappings":"AAyBA,6EAA6E;AAC7E,MAAM,CAAC,MAAM,uBAAuB,GAAqB;IACvD,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE;CACtB,CAAC"}

package/src/lib/devtools.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The devtools trace hook.
+ *
+ * Follows the React-devtools pattern: a tool that wants to observe skew
+ * activity installs a global hook *before* the app boots, and the library
+ * emits one event per `read()` / `write()` into it. When no hook is
+ * installed (production, tests, every app that never opens the tools) the
+ * cost is one property lookup per call and nothing is retained.
+ *
+ * Events deliberately carry versions, reasons, and paths — never payloads.
+ * Payload capture is a tool-side, opt-in concern (drafts contain user data);
+ * the library's default must be safe to leave enabled everywhere.
+ */
+/** One observed schema operation. */
+export interface SkewTraceEvent {
+    readonly kind: 'read' | 'write';
+    /** Schema / contract name. */
+    readonly schema: string;
+    /**
+     * Version the data claimed (envelope `v`, or the assumed version for bare
+     * data). For writes: the version of the value being written (the chain's
+     * current version).
+     */
+    readonly from: number;
+    /**
+     * The reader's current version (reads), or the target version being
+     * written at (writes — differs from `from` on a `write({ as })`).
+     */
+    readonly to: number;
+    /** Read outcome. Always `true` for writes — a failed write throws. */
+    readonly ok: boolean;
+    /** Failure reason, when `ok` is false. */
+    readonly reason?: string;
+    readonly migratedFrom?: number | null;
+    readonly downgradedFrom?: number | null;
+    readonly derivedPaths?: readonly string[];
+    readonly lossyPaths?: readonly string[];
+    /** Epoch milliseconds. */
+    readonly ts: number;
+}
+/** What a devtools implementation installs at `globalThis.__SKEW_DEVTOOLS_HOOK__`. */
+export interface SkewDevtoolsHook {
+    emit(event: SkewTraceEvent): void;
+}
+/** The global property devtools implementations install themselves under. */
+export declare const SKEW_DEVTOOLS_HOOK = "__SKEW_DEVTOOLS_HOOK__";
+/**
+ * Emits a trace event into the installed hook, if any. A throwing hook is
+ * swallowed — observability must never break the app it observes.
+ */
+export declare function emitSkewTrace(event: SkewTraceEvent): void;

package/src/lib/devtools.js

@@ -0,0 +1,31 @@
+/**
+ * The devtools trace hook.
+ *
+ * Follows the React-devtools pattern: a tool that wants to observe skew
+ * activity installs a global hook *before* the app boots, and the library
+ * emits one event per `read()` / `write()` into it. When no hook is
+ * installed (production, tests, every app that never opens the tools) the
+ * cost is one property lookup per call and nothing is retained.
+ *
+ * Events deliberately carry versions, reasons, and paths — never payloads.
+ * Payload capture is a tool-side, opt-in concern (drafts contain user data);
+ * the library's default must be safe to leave enabled everywhere.
+ */
+/** The global property devtools implementations install themselves under. */
+export const SKEW_DEVTOOLS_HOOK = '__SKEW_DEVTOOLS_HOOK__';
+/**
+ * Emits a trace event into the installed hook, if any. A throwing hook is
+ * swallowed — observability must never break the app it observes.
+ */
+export function emitSkewTrace(event) {
+    const hook = globalThis[SKEW_DEVTOOLS_HOOK];
+    if (!hook || typeof hook.emit !== 'function')
+        return;
+    try {
+        hook.emit(event);
+    }
+    catch (_a) {
+        // The hook is diagnostic machinery; its failures are its own.
+    }
+}
+//# sourceMappingURL=devtools.js.map

package/src/lib/devtools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"devtools.js","sourceRoot":"","sources":["../../../../../libs/skew/src/lib/devtools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAmCH,6EAA6E;AAC7E,MAAM,CAAC,MAAM,kBAAkB,GAAG,wBAAwB,CAAC;AAE3D;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,KAAqB;IACjD,MAAM,IAAI,GAAI,UAAsC,CAAC,kBAAkB,CAE1D,CAAC;IACd,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,UAAU;QAAE,OAAO;IACrD,IAAI,CAAC;QACH,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACnB,CAAC;IAAC,WAAM,CAAC;QACP,8DAA8D;IAChE,CAAC;AACH,CAAC"}

package/src/lib/disabled.d.ts

@@ -0,0 +1,48 @@
+/**
+ * ⚠️ NOT PUBLIC API. Undocumented on purpose. Do not use in an application.
+ *
+ * A process-wide switch that makes every `@braidlabs` package behave as though it
+ * were not installed:
+ *
+ *   - stores write bare payloads and read them back with no envelope check,
+ *     which is `JSON.parse(raw) as T` — an assertion, not a check
+ *   - `versioned().read()` returns whatever it was handed, unmigrated
+ *   - `lazy()` stops retrying
+ *   - recovery stops classifying and takes no action
+ *
+ * ## Why this exists
+ *
+ * The demos need to show the failure modes these packages prevent, and the only
+ * trustworthy way to show a failure is to actually produce one. A screenshot of
+ * a hand-written "before" snippet proves nothing; running the same scenario
+ * with the protections removed proves it exactly.
+ *
+ * ## Why it is not documented
+ *
+ * There is no legitimate production use. Every reason to reach for it — "just
+ * while I debug this", "only in staging" — ends with a flag nobody remembers
+ * set on a deployment nobody re-checks, and the failures it re-enables are
+ * silent ones: a draft read at the wrong shape, a mutation replayed against a
+ * contract that moved. Those surface as `undefined` in a renderer weeks later,
+ * far from the switch that caused them.
+ *
+ * So it ships, because the demos are more valuable than the purity of the
+ * export list, but it stays out of the README, out of the package docs, and out
+ * of every example. If you found this by reading the source: that was the deal.
+ * Turning it on logs a warning for the same reason.
+ *
+ * ## Why it is global mutable state
+ *
+ * `@braidlabs/skew` has no framework and no dependencies, so there is no injector to
+ * read from. A module-level flag is the only mechanism available to it. The
+ * Angular packages wrap this in `provideSkewDisabled()` so an application at
+ * least *looks* like it is configuring something, but the state is here.
+ *
+ * One consequence worth knowing: under Module Federation this is per *bundle
+ * instance*, so it only behaves as one switch when `@braidlabs/skew` is genuinely
+ * shared as a singleton. Two copies of core means two flags.
+ */
+/** @internal Not public API — see the module comment. */
+export declare function setSkewDisabled(next: boolean): void;
+/** @internal Not public API — see the module comment. */
+export declare function isSkewDisabled(): boolean;

package/src/lib/disabled.js

@@ -0,0 +1,59 @@
+/**
+ * ⚠️ NOT PUBLIC API. Undocumented on purpose. Do not use in an application.
+ *
+ * A process-wide switch that makes every `@braidlabs` package behave as though it
+ * were not installed:
+ *
+ *   - stores write bare payloads and read them back with no envelope check,
+ *     which is `JSON.parse(raw) as T` — an assertion, not a check
+ *   - `versioned().read()` returns whatever it was handed, unmigrated
+ *   - `lazy()` stops retrying
+ *   - recovery stops classifying and takes no action
+ *
+ * ## Why this exists
+ *
+ * The demos need to show the failure modes these packages prevent, and the only
+ * trustworthy way to show a failure is to actually produce one. A screenshot of
+ * a hand-written "before" snippet proves nothing; running the same scenario
+ * with the protections removed proves it exactly.
+ *
+ * ## Why it is not documented
+ *
+ * There is no legitimate production use. Every reason to reach for it — "just
+ * while I debug this", "only in staging" — ends with a flag nobody remembers
+ * set on a deployment nobody re-checks, and the failures it re-enables are
+ * silent ones: a draft read at the wrong shape, a mutation replayed against a
+ * contract that moved. Those surface as `undefined` in a renderer weeks later,
+ * far from the switch that caused them.
+ *
+ * So it ships, because the demos are more valuable than the purity of the
+ * export list, but it stays out of the README, out of the package docs, and out
+ * of every example. If you found this by reading the source: that was the deal.
+ * Turning it on logs a warning for the same reason.
+ *
+ * ## Why it is global mutable state
+ *
+ * `@braidlabs/skew` has no framework and no dependencies, so there is no injector to
+ * read from. A module-level flag is the only mechanism available to it. The
+ * Angular packages wrap this in `provideSkewDisabled()` so an application at
+ * least *looks* like it is configuring something, but the state is here.
+ *
+ * One consequence worth knowing: under Module Federation this is per *bundle
+ * instance*, so it only behaves as one switch when `@braidlabs/skew` is genuinely
+ * shared as a singleton. Two copies of core means two flags.
+ */
+let disabled = false;
+/** @internal Not public API — see the module comment. */
+export function setSkewDisabled(next) {
+    if (next && !disabled) {
+        console.warn('[skew] PROTECTIONS DISABLED. Envelopes, migrations, retries and ' +
+            'recovery are all inert. This is a demo/debugging switch and is not ' +
+            'supported in production.');
+    }
+    disabled = next;
+}
+/** @internal Not public API — see the module comment. */
+export function isSkewDisabled() {
+    return disabled;
+}
+//# sourceMappingURL=disabled.js.map

package/src/lib/disabled.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"disabled.js","sourceRoot":"","sources":["../../../../../libs/skew/src/lib/disabled.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,IAAI,QAAQ,GAAG,KAAK,CAAC;AAErB,yDAAyD;AACzD,MAAM,UAAU,eAAe,CAAC,IAAa;IAC3C,IAAI,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;QACtB,OAAO,CAAC,IAAI,CACV,kEAAkE;YAChE,qEAAqE;YACrE,0BAA0B,CAC7B,CAAC;IACJ,CAAC;IACD,QAAQ,GAAG,IAAI,CAAC;AAClB,CAAC;AAED,yDAAyD;AACzD,MAAM,UAAU,cAAc;IAC5B,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/src/lib/fingerprint.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Content fingerprints for schemas and their steps.
+ *
+ * Two independently built bundles can declare a chain under the same contract
+ * name. When their declarations *agree*, that duplication is harmless; when
+ * they disagree — same name, same version numbers, different meaning — the
+ * result is the silent kind of corruption nothing else in the system can see.
+ * A fingerprint makes "do these two declarations agree?" a cheap, answerable
+ * question.
+ *
+ * What goes into a step's fingerprint is deliberate:
+ *
+ * - For an ops step, the canonical JSON of the ops — the ops *are* the
+ *   migration, so structural equality is real equality.
+ * - For a code step, the target version and the (required) description — and
+ *   **not** `Function.prototype.toString()`. Two builds minify the same source
+ *   differently, so function text equality would report false conflicts
+ *   between builds that genuinely agree. The description is the human-owned
+ *   identity of a code step; that is one of the reasons it is required.
+ */
+import type { MigrationStep } from './versioned.js';
+/** FNV-1a, 32-bit, hex output. Small, stable, dependency-free. */
+export declare function fnv1a(text: string): string;
+/**
+ * JSON with object keys sorted at every level, so logically identical
+ * documents always serialize identically.
+ */
+export declare function canonicalJson(value: unknown): string;
+/** Fingerprint of a single migration step. */
+export declare function stepFingerprint(step: MigrationStep): string;
+/** Fingerprint of a whole chain: name, current version, and every step. */
+export declare function chainFingerprint(name: string, version: number, steps: readonly (MigrationStep | undefined)[]): string;

package/src/lib/fingerprint.js

@@ -0,0 +1,62 @@
+/**
+ * Content fingerprints for schemas and their steps.
+ *
+ * Two independently built bundles can declare a chain under the same contract
+ * name. When their declarations *agree*, that duplication is harmless; when
+ * they disagree — same name, same version numbers, different meaning — the
+ * result is the silent kind of corruption nothing else in the system can see.
+ * A fingerprint makes "do these two declarations agree?" a cheap, answerable
+ * question.
+ *
+ * What goes into a step's fingerprint is deliberate:
+ *
+ * - For an ops step, the canonical JSON of the ops — the ops *are* the
+ *   migration, so structural equality is real equality.
+ * - For a code step, the target version and the (required) description — and
+ *   **not** `Function.prototype.toString()`. Two builds minify the same source
+ *   differently, so function text equality would report false conflicts
+ *   between builds that genuinely agree. The description is the human-owned
+ *   identity of a code step; that is one of the reasons it is required.
+ */
+/** FNV-1a, 32-bit, hex output. Small, stable, dependency-free. */
+export function fnv1a(text) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < text.length; i++) {
+        hash ^= text.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return (hash >>> 0).toString(16).padStart(8, '0');
+}
+/**
+ * JSON with object keys sorted at every level, so logically identical
+ * documents always serialize identically.
+ */
+export function canonicalJson(value) {
+    return JSON.stringify(sortKeys(value));
+}
+function sortKeys(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeys);
+    if (typeof value === 'object' && value !== null) {
+        const source = value;
+        const sorted = {};
+        for (const key of Object.keys(source).sort()) {
+            sorted[key] = sortKeys(source[key]);
+        }
+        return sorted;
+    }
+    return value;
+}
+/** Fingerprint of a single migration step. */
+export function stepFingerprint(step) {
+    const body = step.ops ? canonicalJson(step.ops) : 'code';
+    return fnv1a(`${step.to}:${step.description}:${body}`);
+}
+/** Fingerprint of a whole chain: name, current version, and every step. */
+export function chainFingerprint(name, version, steps) {
+    // A hole (a known-of but not-runnable step) fingerprints as such — two
+    // builds missing the same implementation still agree about the chain.
+    const parts = steps.map((s) => (s ? stepFingerprint(s) : 'hole')).join('.');
+    return fnv1a(`${name}@${version}:${parts}`);
+}
+//# sourceMappingURL=fingerprint.js.map

package/src/lib/fingerprint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fingerprint.js","sourceRoot":"","sources":["../../../../../libs/skew/src/lib/fingerprint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,kEAAkE;AAClE,MAAM,UAAU,KAAK,CAAC,IAAY;IAChC,IAAI,IAAI,GAAG,UAAU,CAAC;IACtB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,IAAI,IAAI,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;QAC3B,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;IACrC,CAAC;IACD,OAAO,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;AACpD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,OAAO,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;AACzC,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc;IAC9B,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACrD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAChD,MAAM,MAAM,GAAG,KAAgC,CAAC;QAChD,MAAM,MAAM,GAA4B,EAAE,CAAC;QAC3C,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;YAC7C,MAAM,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;QACtC,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,8CAA8C;AAC9C,MAAM,UAAU,eAAe,CAAC,IAAmB;IACjD,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IACzD,OAAO,KAAK,CAAC,GAAG,IAAI,CAAC,EAAE,IAAI,IAAI,CAAC,WAAW,IAAI,IAAI,EAAE,CAAC,CAAC;AACzD,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,gBAAgB,CAC9B,IAAY,EACZ,OAAe,EACf,KAA6C;IAE7C,uEAAuE;IACvE,sEAAsE;IACtE,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC5E,OAAO,KAAK,CAAC,GAAG,IAAI,IAAI,OAAO,IAAI,KAAK,EAAE,CAAC,CAAC;AAC9C,CAAC"}