@smart-data-engines/sde 0.1.0-dev.0

package/dist/bulk.js

@@ -0,0 +1,83 @@
+/** Bounded application inserts; deliberately separate from idempotent migration copies. */
+import { compareCodePoints } from './canonical.js';
+import { BulkWriteRefused } from './errors.js';
+import { Timestamp } from './timestamp.js';
+export const MAX_BATCH_ROWS = 1000;
+export const MAX_BATCH_VALUES = 60_000;
+export function bulkWriter(engine) {
+    if (!('insertMany' in engine) || typeof engine.insertMany !== 'function') {
+        throw new BulkWriteRefused('this adapter does not support bulk writes (insertMany)');
+    }
+    return engine;
+}
+export function batchColumns(rows, extraColumns = 0) {
+    if (!Array.isArray(rows))
+        throw new BulkWriteRefused('a batch must be an array of row objects');
+    if (rows.length > MAX_BATCH_ROWS) {
+        throw new BulkWriteRefused(`a batch may contain at most ${MAX_BATCH_ROWS} rows`);
+    }
+    let columns;
+    for (const row of rows) {
+        if (row === null || typeof row !== 'object' || Array.isArray(row) ||
+            (Object.getPrototypeOf(row) !== Object.prototype && Object.getPrototypeOf(row) !== null)) {
+            throw new BulkWriteRefused('each batch row must be a nonempty object with string fields');
+        }
+        const here = Object.keys(row).sort(compareCodePoints);
+        if (here.length === 0 || Reflect.ownKeys(row).length !== here.length) {
+            throw new BulkWriteRefused('each batch row must be a nonempty object with string fields');
+        }
+        if (columns === undefined) {
+            columns = here;
+            if (rows.length * (columns.length + extraColumns) > MAX_BATCH_VALUES) {
+                throw new BulkWriteRefused(`a batch may contain at most ${MAX_BATCH_VALUES} values, including generation`);
+            }
+        }
+        else if (here.length !== columns.length || columns.some((field, i) => field !== here[i])) {
+            throw new BulkWriteRefused('all batch rows must have the same fields');
+        }
+    }
+    return columns ?? [];
+}
+function snapshot(value, active) {
+    if (value === null || ['string', 'boolean', 'number', 'bigint'].includes(typeof value))
+        return value;
+    if (value instanceof Timestamp)
+        return value; // Immutable; structuredClone would erase its type.
+    if (value instanceof Date)
+        return new Date(value.getTime());
+    if (Buffer.isBuffer(value))
+        return Buffer.from(value);
+    if (value instanceof Uint8Array)
+        return new Uint8Array(value);
+    if (typeof value !== 'object' || value === null) {
+        throw new BulkWriteRefused('batch values must use the SDK scalar types or JSON containers');
+    }
+    if (active.has(value))
+        throw new BulkWriteRefused('batch values must not contain cycles');
+    active.add(value);
+    try {
+        if (Array.isArray(value))
+            return Array.from(value, (item) => snapshot(item, active));
+        if (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null) {
+            if (Reflect.ownKeys(value).length !== Object.keys(value).length) {
+                throw new BulkWriteRefused('JSON containers must have enumerable string keys');
+            }
+            return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, snapshot(item, active)]));
+        }
+        throw new BulkWriteRefused('batch values must use the SDK scalar types or JSON containers');
+    }
+    finally {
+        active.delete(value);
+    }
+}
+export function snapshotRows(rows) {
+    try {
+        return rows.map((row) => Object.fromEntries(Object.entries(row).map(([key, value]) => [key, snapshot(value, new Set())])));
+    }
+    catch (error) {
+        if (error instanceof RangeError)
+            throw new BulkWriteRefused('batch values are nested too deeply');
+        throw error;
+    }
+}
+//# sourceMappingURL=bulk.js.map

package/dist/bulk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bulk.js","sourceRoot":"","sources":["../src/bulk.ts"],"names":[],"mappings":"AAAA,2FAA2F;AAC3F,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAA;AAClD,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAE9C,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAE1C,MAAM,CAAC,MAAM,cAAc,GAAG,IAAI,CAAA;AAClC,MAAM,CAAC,MAAM,gBAAgB,GAAG,MAAM,CAAA;AAMtC,MAAM,UAAU,UAAU,CAAC,MAAc;IACvC,IAAI,CAAC,CAAC,YAAY,IAAI,MAAM,CAAC,IAAI,OAAO,MAAM,CAAC,UAAU,KAAK,UAAU,EAAE,CAAC;QACzE,MAAM,IAAI,gBAAgB,CAAC,wDAAwD,CAAC,CAAA;IACtF,CAAC;IACD,OAAO,MAAsB,CAAA;AAC/B,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,IAA8B,EAAE,YAAY,GAAG,CAAC;IAC3E,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;QAAE,MAAM,IAAI,gBAAgB,CAAC,yCAAyC,CAAC,CAAA;IAC/F,IAAI,IAAI,CAAC,MAAM,GAAG,cAAc,EAAE,CAAC;QACjC,MAAM,IAAI,gBAAgB,CAAC,+BAA+B,cAAc,OAAO,CAAC,CAAA;IAClF,CAAC;IACD,IAAI,OAA6B,CAAA;IACjC,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,IAAI,GAAG,KAAK,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC;YAC7D,CAAC,MAAM,CAAC,cAAc,CAAC,GAAG,CAAC,KAAK,MAAM,CAAC,SAAS,IAAI,MAAM,CAAC,cAAc,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC,EAAE,CAAC;YAC7F,MAAM,IAAI,gBAAgB,CAAC,6DAA6D,CAAC,CAAA;QAC3F,CAAC;QACD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAA;QACrD,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM,EAAE,CAAC;YACrE,MAAM,IAAI,gBAAgB,CAAC,6DAA6D,CAAC,CAAA;QAC3F,CAAC;QACD,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,OAAO,GAAG,IAAI,CAAA;YACd,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,OAAO,CAAC,MAAM,GAAG,YAAY,CAAC,GAAG,gBAAgB,EAAE,CAAC;gBACrE,MAAM,IAAI,gBAAgB,CAAC,+BAA+B,gBAAgB,+BAA+B,CAAC,CAAA;YAC5G,CAAC;QACH,CAAC;aAAM,IAAI,IAAI,CAAC,MAAM,KAAK,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YAC3F,MAAM,IAAI,gBAAgB,CAAC,0CAA0C,CAAC,CAAA;QACxE,CAAC;IACH,CAAC;IACD,OAAO,OAAO,IAAI,EAAE,CAAA;AACtB,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc,EAAE,MAAmB;IACnD,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,OAAO,KAAK,CAAC;QAAE,OAAO,KAAK,CAAA;IACpG,IAAI,KAAK,YAAY,SAAS;QAAE,OAAO,KAAK,CAAA,CAAC,mDAAmD;IAChG,IAAI,KAAK,YAAY,IAAI;QAAE,OAAO,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAA;IAC3D,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IACrD,IAAI,KAAK,YAAY,UAAU;QAAE,OAAO,IAAI,UAAU,CAAC,KAAK,CAAC,CAAA;IAC7D,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAChD,MAAM,IAAI,gBAAgB,CAAC,+DAA+D,CAAC,CAAA;IAC7F,CAAC;IACD,IAAI,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC;QAAE,MAAM,IAAI,gBAAgB,CAAC,sCAAsC,CAAC,CAAA;IACzF,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;IACjB,IAAI,CAAC;QACH,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,IAAa,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAA;QAC7F,IAAI,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,KAAK,MAAM,CAAC,SAAS,IAAI,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,KAAK,IAAI,EAAE,CAAC;YAC/F,IAAI,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,EAAE,CAAC;gBAChE,MAAM,IAAI,gBAAgB,CAAC,kDAAkD,CAAC,CAAA;YAChF,CAAC;YACD,OAAO,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAA;QACtG,CAAC;QACD,MAAM,IAAI,gBAAgB,CAAC,+DAA+D,CAAC,CAAA;IAC7F,CAAC;YAAS,CAAC;QACT,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;IACtB,CAAC;AACH,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,IAA8B;IACzD,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,MAAM,CAAC,WAAW,CACzC,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,QAAQ,CAAC,KAAK,EAAE,IAAI,GAAG,EAAE,CAAC,CAAC,CAAC,CAC7E,CAAC,CAAA;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,UAAU;YAAE,MAAM,IAAI,gBAAgB,CAAC,oCAAoC,CAAC,CAAA;QACjG,MAAM,KAAK,CAAA;IACb,CAAC;AACH,CAAC"}

package/dist/canonical.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Canonical encoding: the one place where the cross-language contract lives.
+ *
+ * This is a port of the rules in `docs/format-contract.md`, not a port of the Python file. That
+ * distinction matters: if this were written by translating Python line by line it would inherit
+ * whatever Python happens to do, and the point of a second implementation is to find out where the
+ * document said "what Python does" instead of something language-neutral.
+ *
+ * It found one, immediately, and it is the reason this file does not use `Array.prototype.sort`.
+ *
+ * JavaScript compares strings by UTF-16 code unit. The contract requires code point order. For
+ * everything in the Basic Multilingual Plane those are the same, so the difference is invisible in
+ * any test written with Latin or even CJK identifiers. It stops being invisible above U+FFFF: an
+ * astral character is stored as a surrogate pair starting at 0xD800, so UTF-16 order places every
+ * emoji and every CJK extension character *before* U+E000, while code point order places them after.
+ * A model with one such field name would hash differently in Python and in TypeScript, the control
+ * plane would see two models, and nothing would fail until half a fleet was writing to the wrong
+ * tables.
+ *
+ * So `compareCodePoints` below exists, and `conformance/vectors/model/004-astral-identifier` exists
+ * to make sure nobody ever replaces it with `.sort()`.
+ */
+/** A value cannot be encoded canonically. */
+export declare class CanonicalError extends Error {
+    readonly name = "CanonicalError";
+}
+export type Canonical = null | boolean | number | string | readonly Canonical[] | {
+    readonly [key: string]: Canonical;
+};
+/**
+ * Compare two strings by Unicode code point.
+ *
+ * Not `a < b`, which is UTF-16 code unit order. See the note at the top of this file: the two orders
+ * disagree for anything above U+FFFF, and that disagreement would be a hash mismatch between
+ * languages rather than a visible bug.
+ */
+export declare function compareCodePoints(a: string, b: string): number;
+/** Canonical form as text. Prefer {@link canonicalBytes} for hashing. */
+export declare function canonicalString(value: unknown): string;
+/** Canonical form as UTF-8 bytes. This is what gets hashed and what the vectors compare. */
+export declare function canonicalBytes(value: unknown): Buffer;
+/**
+ * The identifier form used for `model_version` and `shape.id`: lowercase hex, first eight bytes of
+ * SHA-256 over the canonical bytes.
+ */
+export declare function digest16(value: unknown): string;

package/dist/canonical.js

@@ -0,0 +1,150 @@
+/**
+ * Canonical encoding: the one place where the cross-language contract lives.
+ *
+ * This is a port of the rules in `docs/format-contract.md`, not a port of the Python file. That
+ * distinction matters: if this were written by translating Python line by line it would inherit
+ * whatever Python happens to do, and the point of a second implementation is to find out where the
+ * document said "what Python does" instead of something language-neutral.
+ *
+ * It found one, immediately, and it is the reason this file does not use `Array.prototype.sort`.
+ *
+ * JavaScript compares strings by UTF-16 code unit. The contract requires code point order. For
+ * everything in the Basic Multilingual Plane those are the same, so the difference is invisible in
+ * any test written with Latin or even CJK identifiers. It stops being invisible above U+FFFF: an
+ * astral character is stored as a surrogate pair starting at 0xD800, so UTF-16 order places every
+ * emoji and every CJK extension character *before* U+E000, while code point order places them after.
+ * A model with one such field name would hash differently in Python and in TypeScript, the control
+ * plane would see two models, and nothing would fail until half a fleet was writing to the wrong
+ * tables.
+ *
+ * So `compareCodePoints` below exists, and `conformance/vectors/model/004-astral-identifier` exists
+ * to make sure nobody ever replaces it with `.sort()`.
+ */
+import { createHash } from 'node:crypto';
+/** A value cannot be encoded canonically. */
+export class CanonicalError extends Error {
+    name = 'CanonicalError';
+}
+const SHORT_ESCAPES = {
+    0x08: '\\b',
+    0x09: '\\t',
+    0x0a: '\\n',
+    0x0c: '\\f',
+    0x0d: '\\r',
+    0x22: '\\"',
+    0x5c: '\\\\',
+};
+/**
+ * Compare two strings by Unicode code point.
+ *
+ * Not `a < b`, which is UTF-16 code unit order. See the note at the top of this file: the two orders
+ * disagree for anything above U+FFFF, and that disagreement would be a hash mismatch between
+ * languages rather than a visible bug.
+ */
+export function compareCodePoints(a, b) {
+    const left = [...a];
+    const right = [...b];
+    const shorter = Math.min(left.length, right.length);
+    for (let i = 0; i < shorter; i += 1) {
+        const x = left[i].codePointAt(0);
+        const y = right[i].codePointAt(0);
+        if (x !== y)
+            return x < y ? -1 : 1;
+    }
+    return left.length - right.length;
+}
+function escape(text) {
+    const normalised = text.normalize('NFC');
+    let out = '"';
+    for (const char of normalised) {
+        const code = char.codePointAt(0);
+        const short = SHORT_ESCAPES[code];
+        if (short !== undefined) {
+            out += short;
+        }
+        else if (code < 0x20) {
+            out += `\\u${code.toString(16).padStart(4, '0')}`;
+        }
+        else {
+            out += char;
+        }
+    }
+    return `${out}"`;
+}
+function encode(value, path) {
+    if (value === null)
+        return 'null';
+    if (value === true)
+        return 'true';
+    if (value === false)
+        return 'false';
+    if (typeof value === 'string')
+        return escape(value);
+    if (typeof value === 'number') {
+        // The contract forbids floating point values in the encoding, and JavaScript has only one
+        // numeric type - so "is this an integer" has to be asked explicitly rather than assumed from the
+        // declared type. This is a place where a Python port would have nothing to do and TypeScript has
+        // to be careful.
+        if (!Number.isInteger(value)) {
+            throw new CanonicalError(`float at ${path}: floating point is not representable in canonical form, because its ` +
+                'textual form differs between languages. Use an integer, or a decimal string, or the name ' +
+                'of a float type if you meant to describe a type.');
+        }
+        if (!Number.isSafeInteger(value)) {
+            throw new CanonicalError(`integer at ${path} is outside the safe range: ${value}. JavaScript numbers lose precision ` +
+                'above 2^53, so emitting this would produce bytes another language cannot reproduce. ' +
+                'Refused rather than truncated.');
+        }
+        return String(value);
+    }
+    if (typeof value === 'bigint') {
+        return value.toString();
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((item, i) => encode(item, `${path}[${i}]`)).join(',')}]`;
+    }
+    if (typeof value === 'object') {
+        const pairs = [];
+        for (const [key, item] of Object.entries(value)) {
+            if (item === undefined) {
+                // `undefined` is not `null` and has no canonical form. JSON.stringify drops such keys
+                // silently, which would make the bytes depend on whether a field was omitted or set to
+                // undefined - exactly the kind of invisible difference this encoding exists to prevent.
+                throw new CanonicalError(`undefined at ${path}.${key}: use null if you mean a null, or omit the key entirely. ` +
+                    'Dropping it silently would make the bytes depend on how the caller spelled absence.');
+            }
+            pairs.push([key.normalize('NFC'), item]);
+        }
+        pairs.sort((left, right) => compareCodePoints(left[0], right[0]));
+        const seen = new Set();
+        const parts = [];
+        for (const [key, item] of pairs) {
+            if (seen.has(key)) {
+                throw new CanonicalError(`duplicate key ${JSON.stringify(key)} at ${path} after NFC normalisation: two keys that ` +
+                    'differ only in Unicode composition are the same key here');
+            }
+            seen.add(key);
+            parts.push(`${escape(key)}:${encode(item, `${path}.${key}`)}`);
+        }
+        return `{${parts.join(',')}}`;
+    }
+    throw new CanonicalError(`${typeof value} at ${path} has no canonical form. The canonical encoding accepts only null, ` +
+        'boolean, integer, string, array and plain object; anything richer has to be reduced to those ' +
+        'by the caller, so that the reduction is visible and testable.');
+}
+/** Canonical form as text. Prefer {@link canonicalBytes} for hashing. */
+export function canonicalString(value) {
+    return encode(value, '$');
+}
+/** Canonical form as UTF-8 bytes. This is what gets hashed and what the vectors compare. */
+export function canonicalBytes(value) {
+    return Buffer.from(canonicalString(value), 'utf8');
+}
+/**
+ * The identifier form used for `model_version` and `shape.id`: lowercase hex, first eight bytes of
+ * SHA-256 over the canonical bytes.
+ */
+export function digest16(value) {
+    return createHash('sha256').update(canonicalBytes(value)).digest('hex').slice(0, 16);
+}
+//# sourceMappingURL=canonical.js.map

package/dist/canonical.js.map

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

package/dist/capabilities.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Asking an engine adapter whether it will answer a call, which is not the same as its type.
+ *
+ * Two optional capabilities decide whether an engine takes part in something: keeping the
+ * forward-only bookkeeping, and taking part in a migration. Both are asked for by **name of the
+ * members required**, with ordinary property access, and the reason is worth carrying across from
+ * the reference implementation even though this runtime cannot reproduce its defect.
+ *
+ * There, the obvious spelling was `isinstance(engine, Protocol)` - and a `runtime_checkable`
+ * protocol resolves its members with `hasattr` up to Python 3.11 and with `inspect.getattr_static`
+ * from 3.12, the second of which ignores `__getattr__`. An object forwarding to a wrapped adapter
+ * therefore passed on one interpreter and failed on the next: the same client, the same wrapper, a
+ * different answer. The consequence was two wrong diagnoses shipped as helpful messages, both
+ * naming the client's engine for a property of their own wrapper, and one of them refusing a
+ * migration outright.
+ *
+ * TypeScript has no such split - property access is property access, and it goes through the
+ * prototype chain and through a `Proxy` trap alike - so wrapping an adapter works here without
+ * anything special. That is exactly why the reason is written down rather than the mechanism
+ * assumed: the *question* is the durable part. Will this object respond to these calls?
+ */
+/**
+ * Whether every member named here can be reached on this object.
+ *
+ * **Presence, not callability, and that is the reference implementation's decision rather than
+ * mine.** A member that exists and is not callable fails at the call with a message naming it,
+ * which is a better failure than a capability check that quietly answers "no" and sends the reader
+ * to look at their engine. The first version of this file asked `typeof === 'function'`, which is
+ * the idiomatic spelling and disagreed with the reference on exactly that input - an adapter with a
+ * null method would have been "cannot take part" here and "takes part, then crashes with the name
+ * of the method" there. One contract, two behaviours, no compilation error.
+ *
+ * Read through the property rather than with `in`, because `in` consults a `Proxy`'s `has` trap and
+ * a forwarding wrapper usually only implements `get`. That is the same wrapper the reference's
+ * module docstring is about, and the reason this question is asked by name at all.
+ */
+export declare function satisfies(engine: unknown, members: readonly string[]): boolean;
+/**
+ * The members an engine needs for the forward-only map check.
+ *
+ * A list rather than an interface used with a type guard, because an interface is erased before the
+ * code runs and this question is asked at runtime about an object a client constructed. The list and
+ * the interface are kept in agreement by the compiler - see `WATERMARK_STORE_IS_TOTAL` in
+ * `watermark.ts`.
+ */
+export declare const WATERMARK_MEMBERS: readonly ["mapWatermark", "recordMapVersion"];
+/** The members an engine needs to take part in a migration. */
+export declare const MIGRATABLE_MEMBERS: readonly ["keyRange", "nthKey", "copyIn", "count", "get", "backfillMarker", "recordBackfillMarker"];

package/dist/capabilities.js

@@ -0,0 +1,62 @@
+/**
+ * Asking an engine adapter whether it will answer a call, which is not the same as its type.
+ *
+ * Two optional capabilities decide whether an engine takes part in something: keeping the
+ * forward-only bookkeeping, and taking part in a migration. Both are asked for by **name of the
+ * members required**, with ordinary property access, and the reason is worth carrying across from
+ * the reference implementation even though this runtime cannot reproduce its defect.
+ *
+ * There, the obvious spelling was `isinstance(engine, Protocol)` - and a `runtime_checkable`
+ * protocol resolves its members with `hasattr` up to Python 3.11 and with `inspect.getattr_static`
+ * from 3.12, the second of which ignores `__getattr__`. An object forwarding to a wrapped adapter
+ * therefore passed on one interpreter and failed on the next: the same client, the same wrapper, a
+ * different answer. The consequence was two wrong diagnoses shipped as helpful messages, both
+ * naming the client's engine for a property of their own wrapper, and one of them refusing a
+ * migration outright.
+ *
+ * TypeScript has no such split - property access is property access, and it goes through the
+ * prototype chain and through a `Proxy` trap alike - so wrapping an adapter works here without
+ * anything special. That is exactly why the reason is written down rather than the mechanism
+ * assumed: the *question* is the durable part. Will this object respond to these calls?
+ */
+/**
+ * Whether every member named here can be reached on this object.
+ *
+ * **Presence, not callability, and that is the reference implementation's decision rather than
+ * mine.** A member that exists and is not callable fails at the call with a message naming it,
+ * which is a better failure than a capability check that quietly answers "no" and sends the reader
+ * to look at their engine. The first version of this file asked `typeof === 'function'`, which is
+ * the idiomatic spelling and disagreed with the reference on exactly that input - an adapter with a
+ * null method would have been "cannot take part" here and "takes part, then crashes with the name
+ * of the method" there. One contract, two behaviours, no compilation error.
+ *
+ * Read through the property rather than with `in`, because `in` consults a `Proxy`'s `has` trap and
+ * a forwarding wrapper usually only implements `get`. That is the same wrapper the reference's
+ * module docstring is about, and the reason this question is asked by name at all.
+ */
+export function satisfies(engine, members) {
+    if (typeof engine !== 'object' || engine === null)
+        return false;
+    const target = engine;
+    return members.every((name) => target[name] !== undefined);
+}
+/**
+ * The members an engine needs for the forward-only map check.
+ *
+ * A list rather than an interface used with a type guard, because an interface is erased before the
+ * code runs and this question is asked at runtime about an object a client constructed. The list and
+ * the interface are kept in agreement by the compiler - see `WATERMARK_STORE_IS_TOTAL` in
+ * `watermark.ts`.
+ */
+export const WATERMARK_MEMBERS = ['mapWatermark', 'recordMapVersion'];
+/** The members an engine needs to take part in a migration. */
+export const MIGRATABLE_MEMBERS = [
+    'keyRange',
+    'nthKey',
+    'copyIn',
+    'count',
+    'get',
+    'backfillMarker',
+    'recordBackfillMarker',
+];
+//# sourceMappingURL=capabilities.js.map

package/dist/capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,SAAS,CAAC,MAAe,EAAE,OAA0B;IACnE,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,KAAK,CAAA;IAC/D,MAAM,MAAM,GAAG,MAAiC,CAAA;IAChD,OAAO,OAAO,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,SAAS,CAAC,CAAA;AAC5D,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,cAAc,EAAE,kBAAkB,CAAU,CAAA;AAE9E,+DAA+D;AAC/D,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,UAAU;IACV,QAAQ;IACR,QAAQ;IACR,OAAO;IACP,KAAK;IACL,gBAAgB;IAChB,sBAAsB;CACd,CAAA"}

package/dist/cutover.d.ts

@@ -0,0 +1,36 @@
+import type { LogicalModel } from './model.js';
+import { type LoadOptions, type PlacementMap } from './placement.js';
+import { VerificationRequest } from './verification.js';
+/** A move: the maintained copy that takes over is in another engine binding than the source. */
+export declare const CUTOVER_PROTOCOL = 1;
+/** A relayout: the copy that takes over is in the source's own engine binding, under fresh names. */
+export declare const CUTOVER_RELAYOUT_PROTOCOL = 2;
+type Outcome = 'success' | 'abort';
+type PublicKeys = NonNullable<LoadOptions['publicKey']>;
+export declare class CutoverPlan {
+    readonly planId: string;
+    readonly projectId: string;
+    readonly group: string;
+    readonly before: PlacementMap;
+    readonly success: PlacementMap;
+    readonly abort: PlacementMap;
+    readonly verification: VerificationRequest;
+    readonly pauseBudgetMs: number;
+    readonly queryImpactDigest: string;
+    readonly verifiedWith: string | null;
+    constructor(planId: string, projectId: string, group: string, before: PlacementMap, success: PlacementMap, abort: PlacementMap, verification: VerificationRequest, pauseBudgetMs: number, queryImpactDigest: string, verifiedWith: string | null);
+    private loaded;
+    get fingerprint(): string | undefined;
+    get sourceEpoch(): number;
+    get maintenanceEpoch(): number;
+    get activationEpoch(): number;
+    asRecord(): Record<string, unknown>;
+    candidatePayload(outcome: Outcome): Uint8Array;
+    checkCurrent(current: PlacementMap): void;
+}
+export declare function loadCutoverPlan(raw: unknown, options: {
+    model: LogicalModel;
+    projectId: string;
+    publicKey: PublicKeys;
+}): CutoverPlan;
+export {};