@braidlabs/skew 0.1.1

package/src/lib/http.d.ts

@@ -0,0 +1,70 @@
+import { VersionedEnvelope } from './versioned.js';
+/**
+ * HTTP-native version carriage.
+ *
+ * The `{ v, payload }` body envelope is right for storage, where there is
+ * nothing but the bytes. HTTP already has places to carry a version — the
+ * URL (`/v2/funds`), a header, the media type
+ * (`application/vnd.acme.fund.v2+json`) — and requiring servers to reshape
+ * every response body just to adopt Skew is an adoption tax with no payoff.
+ *
+ * These helpers extract the version from wherever the response carries it and
+ * hand back a normal envelope, so the rest of the pipeline (`schema.read`)
+ * never knows the difference:
+ *
+ * ```ts
+ * const res = await fetch(`${API_BASE}/v1/funds`);
+ * const body = await res.json();
+ * const result = FundListSchema.read(envelopeFromResponse(res, body));
+ * ```
+ */
+/** The subset of `Response` these helpers need — also satisfied by mocks. */
+export interface ResponseLike {
+    readonly url?: string;
+    readonly headers?: {
+        get(name: string): string | null;
+    };
+}
+export interface VersionCarriage {
+    /**
+     * Header carrying the version. The value may be a bare integer (`2`), a
+     * `v=` parameter (`portfolio-fund; v=2`), or a Skew contract link
+     * (`</.well-known/skew/contracts/portfolio-fund>; v=2`).
+     */
+    readonly header?: string;
+    /** Pattern run against `content-type`; first capture group is the version. */
+    readonly mediaType?: RegExp;
+    /** Pattern run against the response URL; first capture group is the version. */
+    readonly urlPattern?: RegExp;
+}
+/** The response header a Skew-aware server uses to name its contract. */
+export declare const SKEW_CONTRACT_HEADER = "skew-contract";
+export interface SkewContractRef {
+    /** Contract document URL, when the header carried one. */
+    readonly url?: string;
+    /** Contract name, when the header carried a bare name instead of a URL. */
+    readonly name?: string;
+    readonly v?: number;
+}
+/**
+ * Parses a `Skew-Contract` header value.
+ *
+ * Accepted forms: `2` · `portfolio-fund; v=2` ·
+ * `</.well-known/skew/contracts/portfolio-fund>; v=2`
+ */
+export declare function parseSkewContractHeader(value: string): SkewContractRef;
+/** Formats the header the parser above accepts. */
+export declare function formatSkewContractHeader(ref: SkewContractRef): string;
+/**
+ * Extracts the contract version a response carries, or `null` when it
+ * carries none. Checks, in order: the header, the media type, the URL.
+ */
+export declare function versionFromResponse(res: ResponseLike, carriage?: VersionCarriage): number | null;
+/**
+ * Normalizes a response + parsed body into something `schema.read` accepts.
+ *
+ * - Body already enveloped → returned as-is (the writer's statement wins).
+ * - Version found in the response → the body wrapped at that version.
+ * - Neither → the bare body, unchanged, which `read` treats as legacy data.
+ */
+export declare function envelopeFromResponse(res: ResponseLike, body: unknown, carriage?: VersionCarriage): VersionedEnvelope | unknown;

package/src/lib/http.js

@@ -0,0 +1,76 @@
+/** The response header a Skew-aware server uses to name its contract. */
+export const SKEW_CONTRACT_HEADER = 'skew-contract';
+const DEFAULT_CARRIAGE = {
+    header: SKEW_CONTRACT_HEADER,
+    mediaType: /vnd\.[^+;]*\.v(\d+)\+json/i,
+    urlPattern: /\/v(\d+)(?:\/|\?|$)/,
+};
+/**
+ * Parses a `Skew-Contract` header value.
+ *
+ * Accepted forms: `2` · `portfolio-fund; v=2` ·
+ * `</.well-known/skew/contracts/portfolio-fund>; v=2`
+ */
+export function parseSkewContractHeader(value) {
+    var _a, _b, _c;
+    const trimmed = value.trim();
+    const ref = {};
+    const linked = trimmed.match(/^<([^>]+)>/);
+    const bare = (_b = (_a = trimmed.split(';')[0]) === null || _a === void 0 ? void 0 : _a.trim()) !== null && _b !== void 0 ? _b : '';
+    if (linked === null || linked === void 0 ? void 0 : linked[1]) {
+        ref.url = linked[1];
+    }
+    else if (bare && !/^\d+$/.test(bare)) {
+        ref.name = bare;
+    }
+    const explicit = trimmed.match(/(?:^|;)\s*v\s*=\s*(\d+)/);
+    const implicit = /^\d+$/.test(bare) ? bare : undefined;
+    const version = (_c = explicit === null || explicit === void 0 ? void 0 : explicit[1]) !== null && _c !== void 0 ? _c : implicit;
+    if (version !== undefined)
+        ref.v = Number(version);
+    return ref;
+}
+/** Formats the header the parser above accepts. */
+export function formatSkewContractHeader(ref) {
+    var _a;
+    const subject = ref.url !== undefined ? `<${ref.url}>` : ((_a = ref.name) !== null && _a !== void 0 ? _a : '');
+    const version = ref.v !== undefined ? `v=${ref.v}` : '';
+    return [subject, version].filter((part) => part.length > 0).join('; ');
+}
+/**
+ * Extracts the contract version a response carries, or `null` when it
+ * carries none. Checks, in order: the header, the media type, the URL.
+ */
+export function versionFromResponse(res, carriage = {}) {
+    var _a, _b, _c, _d, _e, _f;
+    const headerName = (_a = carriage.header) !== null && _a !== void 0 ? _a : DEFAULT_CARRIAGE.header;
+    const headerValue = (_b = res.headers) === null || _b === void 0 ? void 0 : _b.get(headerName);
+    if (headerValue) {
+        const parsed = parseSkewContractHeader(headerValue);
+        if (parsed.v !== undefined)
+            return parsed.v;
+    }
+    const contentType = (_c = res.headers) === null || _c === void 0 ? void 0 : _c.get('content-type');
+    const mediaMatch = contentType === null || contentType === void 0 ? void 0 : contentType.match((_d = carriage.mediaType) !== null && _d !== void 0 ? _d : DEFAULT_CARRIAGE.mediaType);
+    if (mediaMatch === null || mediaMatch === void 0 ? void 0 : mediaMatch[1])
+        return Number(mediaMatch[1]);
+    const urlMatch = (_e = res.url) === null || _e === void 0 ? void 0 : _e.match((_f = carriage.urlPattern) !== null && _f !== void 0 ? _f : DEFAULT_CARRIAGE.urlPattern);
+    if (urlMatch === null || urlMatch === void 0 ? void 0 : urlMatch[1])
+        return Number(urlMatch[1]);
+    return null;
+}
+/**
+ * Normalizes a response + parsed body into something `schema.read` accepts.
+ *
+ * - Body already enveloped → returned as-is (the writer's statement wins).
+ * - Version found in the response → the body wrapped at that version.
+ * - Neither → the bare body, unchanged, which `read` treats as legacy data.
+ */
+export function envelopeFromResponse(res, body, carriage = {}) {
+    if (typeof body === 'object' && body !== null && typeof body.v === 'number' && 'payload' in body) {
+        return body;
+    }
+    const version = versionFromResponse(res, carriage);
+    return version === null ? body : { v: version, payload: body };
+}
+//# sourceMappingURL=http.js.map

package/src/lib/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../../../../libs/skew/src/lib/http.ts"],"names":[],"mappings":"AAyCA,yEAAyE;AACzE,MAAM,CAAC,MAAM,oBAAoB,GAAG,eAAe,CAAC;AAEpD,MAAM,gBAAgB,GAA8B;IAClD,MAAM,EAAE,oBAAoB;IAC5B,SAAS,EAAE,4BAA4B;IACvC,UAAU,EAAE,qBAAqB;CAClC,CAAC;AAUF;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,KAAa;;IACnD,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,MAAM,GAAG,GAAgD,EAAE,CAAC;IAE5D,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;IAC3C,MAAM,IAAI,GAAG,MAAA,MAAA,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,0CAAE,IAAI,EAAE,mCAAI,EAAE,CAAC;IACjD,IAAI,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAG,CAAC,CAAC,EAAE,CAAC;QAChB,GAAG,CAAC,GAAG,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;IACtB,CAAC;SAAM,IAAI,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACvC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC;IAClB,CAAC;IAED,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,yBAAyB,CAAC,CAAC;IAC1D,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;IACvD,MAAM,OAAO,GAAG,MAAA,QAAQ,aAAR,QAAQ,uBAAR,QAAQ,CAAG,CAAC,CAAC,mCAAI,QAAQ,CAAC;IAC1C,IAAI,OAAO,KAAK,SAAS;QAAE,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;IAEnD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,mDAAmD;AACnD,MAAM,UAAU,wBAAwB,CAAC,GAAoB;;IAC3D,MAAM,OAAO,GAAG,GAAG,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,MAAA,GAAG,CAAC,IAAI,mCAAI,EAAE,CAAC,CAAC;IAC1E,MAAM,OAAO,GAAG,GAAG,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACxD,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACzE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAiB,EAAE,WAA4B,EAAE;;IACnF,MAAM,UAAU,GAAG,MAAA,QAAQ,CAAC,MAAM,mCAAI,gBAAgB,CAAC,MAAM,CAAC;IAC9D,MAAM,WAAW,GAAG,MAAA,GAAG,CAAC,OAAO,0CAAE,GAAG,CAAC,UAAU,CAAC,CAAC;IACjD,IAAI,WAAW,EAAE,CAAC;QAChB,MAAM,MAAM,GAAG,uBAAuB,CAAC,WAAW,CAAC,CAAC;QACpD,IAAI,MAAM,CAAC,CAAC,KAAK,SAAS;YAAE,OAAO,MAAM,CAAC,CAAC,CAAC;IAC9C,CAAC;IAED,MAAM,WAAW,GAAG,MAAA,GAAG,CAAC,OAAO,0CAAE,GAAG,CAAC,cAAc,CAAC,CAAC;IACrD,MAAM,UAAU,GAAG,WAAW,aAAX,WAAW,uBAAX,WAAW,CAAE,KAAK,CAAC,MAAA,QAAQ,CAAC,SAAS,mCAAI,gBAAgB,CAAC,SAAS,CAAC,CAAC;IACxF,IAAI,UAAU,aAAV,UAAU,uBAAV,UAAU,CAAG,CAAC,CAAC;QAAE,OAAO,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;IAElD,MAAM,QAAQ,GAAG,MAAA,GAAG,CAAC,GAAG,0CAAE,KAAK,CAAC,MAAA,QAAQ,CAAC,UAAU,mCAAI,gBAAgB,CAAC,UAAU,CAAC,CAAC;IACpF,IAAI,QAAQ,aAAR,QAAQ,uBAAR,QAAQ,CAAG,CAAC,CAAC;QAAE,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;IAE9C,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAClC,GAAiB,EACjB,IAAa,EACb,WAA4B,EAAE;IAE9B,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,IAAI,OAAQ,IAAwB,CAAC,CAAC,KAAK,QAAQ,IAAI,SAAS,IAAI,IAAI,EAAE,CAAC;QACtH,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,OAAO,GAAG,mBAAmB,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;IACnD,OAAO,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AACjE,CAAC"}

package/src/lib/identity.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Build identity and skew negotiation.
+ *
+ * The premise: a deployed artifact needs a stable name so two independently
+ * deployed parties can discover that they disagree. Everything else here —
+ * stale chunks, contract mismatches, hydration failures — is a consequence of
+ * that one missing primitive.
+ */
+/** Identity of the running client build, stamped at build time. */
+export interface BuildIdentity {
+    readonly buildId: string;
+    /** ISO timestamp. Optional, but without it two builds cannot be *ordered*. */
+    readonly builtAt?: string;
+}
+/**
+ * The artifact an origin serves so clients can discover the current build.
+ * Serve it with `Cache-Control: no-store`.
+ */
+export interface SkewManifest {
+    readonly buildId: string;
+    readonly builtAt?: string;
+    /**
+     * Optional logical-module → output-chunk map. Present, it lets a client
+     * distinguish "this route moved" from "this route was deleted"; absent,
+     * classification falls back to build identity alone.
+     */
+    readonly modules?: Readonly<Record<string, {
+        readonly file: string;
+        readonly hash?: string;
+    }>>;
+}
+/**
+ * Outcome of comparing the running client against the origin.
+ *
+ * `staleOrigin` is the case naïve implementations miss, and the reason a plain
+ * reload-on-error can brick a tab: if the origin is handing out an *older*
+ * build than the one already running (a cached entry document, a lagging
+ * region), reloading fetches the same stale bundle and fails again, forever.
+ */
+export type SkewStatus = {
+    readonly kind: 'current';
+    readonly buildId: string;
+} | {
+    /** A newer deployment exists. Reloading is safe and will resolve it. */
+    readonly kind: 'staleClient';
+    readonly local: string;
+    readonly remote: string;
+    readonly remoteBuiltAt?: string;
+} | {
+    /** Origin is behind us — reloading would loop. Do not reload. */
+    readonly kind: 'staleOrigin';
+    readonly local: string;
+    readonly remote: string;
+} | {
+    /** Builds differ but cannot be ordered (no timestamps to compare). */
+    readonly kind: 'differs';
+    readonly local: string;
+    readonly remote: string;
+} | {
+    /** The origin could not be reached: offline, blocked, or timed out. */
+    readonly kind: 'unreachable';
+    readonly error: unknown;
+};
+export interface VersionProbeOptions {
+    /** Identity of this build. */
+    readonly identity: BuildIdentity;
+    /** URL of the manifest. Should be served `no-store`. */
+    readonly manifestUrl: string;
+    /** Injected for testing and for non-browser runtimes. */
+    readonly fetch?: typeof globalThis.fetch;
+    /** Abort the probe after this long. Default 5000ms. */
+    readonly timeoutMs?: number;
+    /**
+     * Minimum gap between network probes; repeat calls inside the window reuse
+     * the last answer. Default 10_000ms. Prevents a burst of chunk failures from
+     * turning into a burst of manifest requests.
+     */
+    readonly minIntervalMs?: number;
+}
+export interface VersionProbe {
+    /** Compares this build against the origin, subject to the interval cache. */
+    check(): Promise<SkewStatus>;
+    /** Last status observed, without touching the network. */
+    last(): SkewStatus | null;
+    /**
+     * The manifest behind the last successful probe.
+     *
+     * Exposed because classification often needs the payload, not just the
+     * verdict — `moduleWasRemoved()` is the motivating case, where "the route was
+     * deleted" and "the chunk moved" demand different recovery.
+     */
+    lastManifest(): SkewManifest | null;
+    /** Discards the cached answer so the next `check()` hits the network. */
+    invalidate(): void;
+}
+/**
+ * Creates a probe that answers "is this client still current?".
+ *
+ * ```ts
+ * const probe = createVersionProbe({
+ *   identity: { buildId: BUILD_ID, builtAt: BUILT_AT },
+ *   manifestUrl: '/skew-manifest.json',
+ * });
+ *
+ * const status = await probe.check();
+ * if (status.kind === 'staleClient') offerReload();
+ * if (status.kind === 'staleOrigin') doNotReload();  // would loop
+ * ```
+ */
+export declare function createVersionProbe(options: VersionProbeOptions): VersionProbe;
+/**
+ * Pure comparison of a client identity against a manifest.
+ *
+ * Ordering requires timestamps on both sides. Without them the only honest
+ * answer is `differs` — which callers should treat conservatively, because
+ * they cannot rule out the reload-loop case.
+ */
+export declare function compareBuilds(identity: BuildIdentity, manifest: SkewManifest): SkewStatus;
+/** True when a module is absent from the manifest, i.e. deleted in the new build. */
+export declare function moduleWasRemoved(manifest: SkewManifest, moduleId: string): boolean;

package/src/lib/identity.js

@@ -0,0 +1,126 @@
+/**
+ * Build identity and skew negotiation.
+ *
+ * The premise: a deployed artifact needs a stable name so two independently
+ * deployed parties can discover that they disagree. Everything else here —
+ * stale chunks, contract mismatches, hydration failures — is a consequence of
+ * that one missing primitive.
+ */
+import { __awaiter } from "tslib";
+/**
+ * Creates a probe that answers "is this client still current?".
+ *
+ * ```ts
+ * const probe = createVersionProbe({
+ *   identity: { buildId: BUILD_ID, builtAt: BUILT_AT },
+ *   manifestUrl: '/skew-manifest.json',
+ * });
+ *
+ * const status = await probe.check();
+ * if (status.kind === 'staleClient') offerReload();
+ * if (status.kind === 'staleOrigin') doNotReload();  // would loop
+ * ```
+ */
+export function createVersionProbe(options) {
+    var _a;
+    const { identity, manifestUrl, fetch: fetchImpl = (_a = globalThis.fetch) === null || _a === void 0 ? void 0 : _a.bind(globalThis), timeoutMs = 5000, minIntervalMs = 10000, } = options;
+    let cached = null;
+    let cachedManifest = null;
+    let cachedAt = 0;
+    let inFlight = null;
+    function probe() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!fetchImpl) {
+                return { kind: 'unreachable', error: new Error('no fetch implementation available') };
+            }
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), timeoutMs);
+            try {
+                const response = yield fetchImpl(manifestUrl, {
+                    cache: 'no-store',
+                    signal: controller.signal,
+                });
+                if (!response.ok) {
+                    return { kind: 'unreachable', error: new Error(`manifest responded ${response.status}`) };
+                }
+                const manifest = (yield response.json());
+                cachedManifest = manifest;
+                return compareBuilds(identity, manifest);
+            }
+            catch (error) {
+                return { kind: 'unreachable', error };
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        });
+    }
+    return {
+        check() {
+            return __awaiter(this, void 0, void 0, function* () {
+                const now = Date.now();
+                if (cached && now - cachedAt < minIntervalMs)
+                    return cached;
+                // Collapse concurrent callers onto one request — a page that fails to
+                // load three chunks at once should still make a single probe.
+                if (inFlight)
+                    return inFlight;
+                inFlight = probe().then((status) => {
+                    cached = status;
+                    cachedAt = Date.now();
+                    inFlight = null;
+                    return status;
+                });
+                return inFlight;
+            });
+        },
+        last: () => cached,
+        lastManifest: () => cachedManifest,
+        invalidate: () => {
+            cached = null;
+            cachedManifest = null;
+            cachedAt = 0;
+        },
+    };
+}
+/**
+ * Pure comparison of a client identity against a manifest.
+ *
+ * Ordering requires timestamps on both sides. Without them the only honest
+ * answer is `differs` — which callers should treat conservatively, because
+ * they cannot rule out the reload-loop case.
+ */
+export function compareBuilds(identity, manifest) {
+    if (identity.buildId === manifest.buildId) {
+        return { kind: 'current', buildId: manifest.buildId };
+    }
+    const localTime = parseTime(identity.builtAt);
+    const remoteTime = parseTime(manifest.builtAt);
+    if (localTime !== null && remoteTime !== null) {
+        if (remoteTime > localTime) {
+            return manifest.builtAt === undefined
+                ? { kind: 'staleClient', local: identity.buildId, remote: manifest.buildId }
+                : {
+                    kind: 'staleClient',
+                    local: identity.buildId,
+                    remote: manifest.buildId,
+                    remoteBuiltAt: manifest.builtAt,
+                };
+        }
+        if (remoteTime < localTime) {
+            return { kind: 'staleOrigin', local: identity.buildId, remote: manifest.buildId };
+        }
+    }
+    return { kind: 'differs', local: identity.buildId, remote: manifest.buildId };
+}
+function parseTime(iso) {
+    if (!iso)
+        return null;
+    const ms = Date.parse(iso);
+    return Number.isNaN(ms) ? null : ms;
+}
+/** True when a module is absent from the manifest, i.e. deleted in the new build. */
+export function moduleWasRemoved(manifest, moduleId) {
+    return manifest.modules !== undefined && manifest.modules[moduleId] === undefined;
+}
+//# sourceMappingURL=identity.js.map

package/src/lib/identity.js.map

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

package/src/lib/lens.d.ts

@@ -0,0 +1,133 @@
+import type { MigrationContext } from './context.js';
+/**
+ * Declarative migration ops — the data-driven alternative to closure
+ * migrations.
+ *
+ * A closure can express any migration but can only travel inside the bundle
+ * that compiled it. An ops list is data: it can be published by an API,
+ * fetched by a build that has never seen the newer shape, audited by a human,
+ * and — because every op is structural — **mechanically inverted**, so
+ * declaring the up-migration buys the down-migration for free.
+ *
+ * The op set is deliberately closed and non-Turing-complete. Nothing fetched
+ * over the network is ever executed as code; it is interpreted, op by op,
+ * against a whitelist. Semantic transforms ("split this name into first and
+ * last") do not belong here — they stay as named code steps, and a reader
+ * that lacks the named function degrades loudly rather than guessing.
+ *
+ * Directionality: ops describe the **up** migration (older shape → newer
+ * shape). The inverse of each op, where one exists, is derived:
+ *
+ * | op        | up (old → new)                          | down (new → old)                     |
+ * | --------- | --------------------------------------- | ------------------------------------ |
+ * | `rename`  | move value `from` → `to`                | move value `to` → `from`             |
+ * | `move`    | alias of `rename`                       | reversed                             |
+ * | `wrap`    | scalar → `{ [key]: scalar, ...also }`   | object → its `[key]`; `also` dropped |
+ * | `hoist`   | object → its `[key]` member             | `[key]` re-wrapped (siblings lost)   |
+ * | `map`     | sub-ops over each array element         | inverted sub-ops, reversed           |
+ * | `default` | set `path` when absent                  | delete `path` (lossy)                |
+ * | `drop`    | delete `path`                           | set `restore` if given, else none    |
+ * | `convert` | coerce / map the value at `path`        | opposite coercion / inverted map     |
+ * | `const`   | set `path` unconditionally              | delete `path` (lossy)                |
+ */
+/**
+ * A value computed while applying an op:
+ * - `{ $now: true }` — `ctx.now().toISOString()`. Derived by definition.
+ * - `{ $from: 'path' }` — copied from another field. A leading `/` resolves
+ *   against the document root (useful inside `map`, where the scope is the
+ *   array element); otherwise against the current scope. Real data, not a
+ *   guess.
+ * - `{ $value: x }` — the literal `x`, for literals that would otherwise be
+ *   mistaken for one of the specs above. Derived by definition.
+ * - anything else — itself, as a literal. Derived by definition.
+ */
+export type LensValueSpec = {
+    readonly $now: true;
+} | {
+    readonly $from: string;
+} | {
+    readonly $value: unknown;
+} | unknown;
+export type LensOp = {
+    readonly rename: {
+        readonly from: string;
+        readonly to: string;
+    };
+} | {
+    readonly move: {
+        readonly from: string;
+        readonly to: string;
+    };
+} | {
+    readonly wrap: {
+        readonly path: string;
+        readonly key: string;
+        readonly also?: Readonly<Record<string, LensValueSpec>>;
+    };
+} | {
+    readonly hoist: {
+        readonly path: string;
+        readonly key: string;
+    };
+} | {
+    readonly map: {
+        readonly path: string;
+        readonly ops: readonly LensOp[];
+    };
+} | {
+    readonly default: {
+        readonly path: string;
+        readonly value: unknown;
+        /** Defaults to `true` — a filled-in default is a guess by definition. */
+        readonly derived?: boolean;
+    };
+} | {
+    readonly drop: {
+        readonly path: string;
+        /**
+         * Value the down-migration reinstates for the field the newer shape
+         * removed. Without it the step cannot travel downward at all.
+         */
+        readonly restore?: unknown;
+    };
+} | {
+    readonly convert: {
+        readonly path: string;
+        readonly to: 'string' | 'number';
+        /**
+         * Explicit value mapping (keys are `String(oldValue)`). Invertible
+         * only when bijective. Without `via`, `'string'` and `'number'` are
+         * treated as inverses of each other.
+         */
+        readonly via?: Readonly<Record<string, unknown>>;
+    };
+} | {
+    readonly const: {
+        readonly path: string;
+        readonly value: unknown;
+        /** Defaults to `false` — use `true` when the constant is a placeholder. */
+        readonly derived?: boolean;
+    };
+};
+export interface CompiledLens {
+    /** Applies the ops in order. Clones the input; never mutates it. */
+    readonly up: (data: unknown, ctx: MigrationContext) => unknown;
+    /**
+     * Applies the inverted ops in reverse order, or `null` when any op is not
+     * invertible (see {@link CompiledLens.invertible}).
+     */
+    readonly down: ((data: unknown, ctx: MigrationContext) => unknown) | null;
+    readonly invertible: boolean;
+    /** Paths the up direction fills with guesses (statically known). */
+    readonly derivedUp: readonly string[];
+    /** Paths the down direction fills with guesses (`drop.restore`). */
+    readonly derivedDown: readonly string[];
+    /** Paths the down direction discards — the cost of the projection. */
+    readonly lossyDown: readonly string[];
+}
+/**
+ * Compiles an ops list into executable up and (when possible) down
+ * migrations. Throws `TypeError` on a malformed ops list — a bad contract is
+ * a programming error and should fail at declaration, not at read time.
+ */
+export declare function compileLens(ops: readonly LensOp[]): CompiledLens;