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

package/dist/timestamp.d.ts

@@ -0,0 +1,20 @@
+/** An immutable UTC instant with the microsecond precision of the SDE timestamp types.
+ *
+ * JavaScript Date loses the last three digits before a migration can compare them. Both engine
+ * adapters therefore return Timestamp, and accept it on writes and in keys. Date remains a valid
+ * input for applications whose values really are millisecond-resolution. See docs/timestamps.md.
+ */
+export declare class Timestamp {
+    readonly epochMicroseconds: bigint;
+    private constructor();
+    static fromEpochMicroseconds(value: bigint): Timestamp;
+    /** ISO date-time or engine text; an absent offset means UTC, never the process timezone. */
+    static from(value: string | Date | Timestamp): Timestamp;
+    toISOString(): string;
+    toString(): string;
+    toJSON(): string;
+    /** Convert only when Date can represent the instant exactly. No implicit rounding. */
+    toDate(): Date;
+    /** Ordering must name the exact quantity rather than coerce it to a lossy number. */
+    valueOf(): never;
+}

package/dist/timestamp.js

@@ -0,0 +1,89 @@
+/** An immutable UTC instant with the microsecond precision of the SDE timestamp types.
+ *
+ * JavaScript Date loses the last three digits before a migration can compare them. Both engine
+ * adapters therefore return Timestamp, and accept it on writes and in keys. Date remains a valid
+ * input for applications whose values really are millisecond-resolution. See docs/timestamps.md.
+ */
+export class Timestamp {
+    epochMicroseconds;
+    constructor(epochMicroseconds) {
+        this.epochMicroseconds = epochMicroseconds;
+        Object.freeze(this);
+    }
+    static fromEpochMicroseconds(value) {
+        if (typeof value !== 'bigint')
+            throw new TypeError('epochMicroseconds must be a bigint');
+        // Years 0001 through 9999, the common finite range of the host representations. Each engine
+        // may impose a narrower range; its write error remains authoritative.
+        if (value < -62135596800000000n || value > 253402300799999999n) {
+            throw new RangeError('Timestamp must be within UTC years 0001 through 9999');
+        }
+        return new Timestamp(value);
+    }
+    /** ISO date-time or engine text; an absent offset means UTC, never the process timezone. */
+    static from(value) {
+        if (value instanceof Timestamp)
+            return value;
+        if (value instanceof Date) {
+            if (!Number.isFinite(value.getTime()))
+                throw new RangeError('invalid Date for Timestamp');
+            return Timestamp.fromEpochMicroseconds(BigInt(value.getTime()) * 1000n);
+        }
+        if (typeof value !== 'string')
+            throw new TypeError('Timestamp requires a string or Date');
+        const parts = /^(\d{4})-(\d{2})-(\d{2})[T ](\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,6}))?(?:[Zz]|([+-])(\d{2})(?::?(\d{2}))?(?::?(\d{2}))?)?$/.exec(value);
+        if (parts === null) {
+            throw new RangeError('Timestamp requires a finite ISO date-time with at most six fractional digits');
+        }
+        const year = Number(parts[1]);
+        const month = Number(parts[2]);
+        const day = Number(parts[3]);
+        const hour = Number(parts[4]);
+        const minute = Number(parts[5]);
+        const second = Number(parts[6]);
+        const date = new Date(0);
+        date.setUTCFullYear(year, month - 1, day);
+        date.setUTCHours(hour, minute, second, 0);
+        if (year < 1 || date.getUTCFullYear() !== year || date.getUTCMonth() !== month - 1 ||
+            date.getUTCDate() !== day || date.getUTCHours() !== hour ||
+            date.getUTCMinutes() !== minute || date.getUTCSeconds() !== second) {
+            throw new RangeError('invalid calendar date or time for Timestamp');
+        }
+        const offsetHour = Number(parts[9] ?? 0);
+        const offsetMinute = Number(parts[10] ?? 0);
+        const offsetSecond = Number(parts[11] ?? 0);
+        if (offsetHour > 23 || offsetMinute > 59 || offsetSecond > 59) {
+            throw new RangeError('invalid UTC offset for Timestamp');
+        }
+        const offset = (offsetHour * 3600 + offsetMinute * 60 + offsetSecond) *
+            (parts[8] === '-' ? -1 : 1);
+        const fraction = BigInt((parts[7] ?? '').padEnd(6, '0'));
+        return Timestamp.fromEpochMicroseconds(BigInt(date.getTime()) * 1000n + fraction - BigInt(offset) * 1000000n);
+    }
+    toISOString() {
+        // Floor, not truncation towards zero: the microsecond immediately before the epoch belongs
+        // to the previous millisecond, with a positive fractional remainder.
+        const remainder = ((this.epochMicroseconds % 1000n) + 1000n) % 1000n;
+        const milliseconds = (this.epochMicroseconds - remainder) / 1000n;
+        const iso = new Date(Number(milliseconds)).toISOString();
+        return `${iso.slice(0, -1)}${remainder.toString().padStart(3, '0')}Z`;
+    }
+    toString() {
+        return this.toISOString();
+    }
+    toJSON() {
+        return this.toISOString();
+    }
+    /** Convert only when Date can represent the instant exactly. No implicit rounding. */
+    toDate() {
+        if (this.epochMicroseconds % 1000n !== 0n) {
+            throw new RangeError('Timestamp has microseconds that Date cannot represent; use epochMicroseconds or toISOString()');
+        }
+        return new Date(Number(this.epochMicroseconds / 1000n));
+    }
+    /** Ordering must name the exact quantity rather than coerce it to a lossy number. */
+    valueOf() {
+        throw new TypeError('compare Timestamp.epochMicroseconds explicitly');
+    }
+}
+//# sourceMappingURL=timestamp.js.map

package/dist/timestamp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timestamp.js","sourceRoot":"","sources":["../src/timestamp.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,OAAO,SAAS;IACS;IAA7B,YAA6B,iBAAyB;QAAzB,sBAAiB,GAAjB,iBAAiB,CAAQ;QACpD,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;IACrB,CAAC;IAED,MAAM,CAAC,qBAAqB,CAAC,KAAa;QACxC,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,MAAM,IAAI,SAAS,CAAC,oCAAoC,CAAC,CAAA;QACxF,4FAA4F;QAC5F,sEAAsE;QACtE,IAAI,KAAK,GAAG,CAAC,kBAAuB,IAAI,KAAK,GAAG,mBAAwB,EAAE,CAAC;YACzE,MAAM,IAAI,UAAU,CAAC,sDAAsD,CAAC,CAAA;QAC9E,CAAC;QACD,OAAO,IAAI,SAAS,CAAC,KAAK,CAAC,CAAA;IAC7B,CAAC;IAED,4FAA4F;IAC5F,MAAM,CAAC,IAAI,CAAC,KAAgC;QAC1C,IAAI,KAAK,YAAY,SAAS;YAAE,OAAO,KAAK,CAAA;QAC5C,IAAI,KAAK,YAAY,IAAI,EAAE,CAAC;YAC1B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;gBAAE,MAAM,IAAI,UAAU,CAAC,4BAA4B,CAAC,CAAA;YACzF,OAAO,SAAS,CAAC,qBAAqB,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,GAAG,KAAK,CAAC,CAAA;QACzE,CAAC;QACD,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,MAAM,IAAI,SAAS,CAAC,qCAAqC,CAAC,CAAA;QACzF,MAAM,KAAK,GAAG,yHAAyH,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QACnJ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YACnB,MAAM,IAAI,UAAU,CAAC,8EAA8E,CAAC,CAAA;QACtG,CAAC;QACD,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;QAC7B,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;QAC9B,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;QAC5B,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;QAC7B,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;QAC/B,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;QAC/B,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,CAAC,CAAC,CAAA;QACxB,IAAI,CAAC,cAAc,CAAC,IAAI,EAAE,KAAK,GAAG,CAAC,EAAE,GAAG,CAAC,CAAA;QACzC,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,CAAA;QACzC,IACE,IAAI,GAAG,CAAC,IAAI,IAAI,CAAC,cAAc,EAAE,KAAK,IAAI,IAAI,IAAI,CAAC,WAAW,EAAE,KAAK,KAAK,GAAG,CAAC;YAC9E,IAAI,CAAC,UAAU,EAAE,KAAK,GAAG,IAAI,IAAI,CAAC,WAAW,EAAE,KAAK,IAAI;YACxD,IAAI,CAAC,aAAa,EAAE,KAAK,MAAM,IAAI,IAAI,CAAC,aAAa,EAAE,KAAK,MAAM,EAClE,CAAC;YACD,MAAM,IAAI,UAAU,CAAC,6CAA6C,CAAC,CAAA;QACrE,CAAC;QACD,MAAM,UAAU,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAA;QACxC,MAAM,YAAY,GAAG,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAA;QAC3C,MAAM,YAAY,GAAG,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAA;QAC3C,IAAI,UAAU,GAAG,EAAE,IAAI,YAAY,GAAG,EAAE,IAAI,YAAY,GAAG,EAAE,EAAE,CAAC;YAC9D,MAAM,IAAI,UAAU,CAAC,kCAAkC,CAAC,CAAA;QAC1D,CAAC;QACD,MAAM,MAAM,GAAG,CAAC,UAAU,GAAG,IAAI,GAAG,YAAY,GAAG,EAAE,GAAG,YAAY,CAAC;YACnE,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;QAC7B,MAAM,QAAQ,GAAG,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAA;QACxD,OAAO,SAAS,CAAC,qBAAqB,CACpC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,GAAG,QAAU,CACxE,CAAA;IACH,CAAC;IAED,WAAW;QACT,2FAA2F;QAC3F,qEAAqE;QACrE,MAAM,SAAS,GAAG,CAAC,CAAC,IAAI,CAAC,iBAAiB,GAAG,KAAK,CAAC,GAAG,KAAK,CAAC,GAAG,KAAK,CAAA;QACpE,MAAM,YAAY,GAAG,CAAC,IAAI,CAAC,iBAAiB,GAAG,SAAS,CAAC,GAAG,KAAK,CAAA;QACjE,MAAM,GAAG,GAAG,IAAI,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,WAAW,EAAE,CAAA;QACxD,OAAO,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,CAAA;IACvE,CAAC;IAED,QAAQ;QACN,OAAO,IAAI,CAAC,WAAW,EAAE,CAAA;IAC3B,CAAC;IAED,MAAM;QACJ,OAAO,IAAI,CAAC,WAAW,EAAE,CAAA;IAC3B,CAAC;IAED,sFAAsF;IACtF,MAAM;QACJ,IAAI,IAAI,CAAC,iBAAiB,GAAG,KAAK,KAAK,EAAE,EAAE,CAAC;YAC1C,MAAM,IAAI,UAAU,CAClB,+FAA+F,CAChG,CAAA;QACH,CAAC;QACD,OAAO,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,iBAAiB,GAAG,KAAK,CAAC,CAAC,CAAA;IACzD,CAAC;IAED,qFAAqF;IACrF,OAAO;QACL,MAAM,IAAI,SAAS,CAAC,gDAAgD,CAAC,CAAA;IACvE,CAAC;CACF"}

package/dist/types.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The neutral type vocabulary, and how a TypeScript declaration reaches it.
+ *
+ * Here is where TypeScript differs from Python in the way that matters, and why it was worth writing
+ * second. Python can read a class's annotations at runtime and derive the model from them. TypeScript
+ * cannot: its types are erased before the code runs. So the model has to be *stated*, as values, and
+ * there is no possibility of inferring it from the shape of a class.
+ *
+ * That is a better test of the contract than a similar language would have been. Anything the format
+ * contract left implicit - anything that was really "what Python's introspection happens to produce"
+ * - has nowhere to hide here, because nothing is introspected.
+ *
+ * The vocabulary itself is fixed and shared:
+ *
+ *     bool  int32  int64  float32  float64  decimal(p,s)
+ *     string  bytes  uuid  date  timestamp  timestamptz  json
+ *
+ * `decimal` is written `decimal(12,2)` - precision, comma, scale, no spaces, both required. A decimal
+ * without precision is not a storable type in any engine we place data in, and letting the engine
+ * choose would make the physical schema depend on something the model never said.
+ */
+export declare const NEUTRAL_TYPES: readonly ["bool", "int32", "int64", "float32", "float64", "string", "bytes", "uuid", "date", "timestamp", "timestamptz", "json"];
+export type NeutralType = (typeof NEUTRAL_TYPES)[number] | `decimal(${number},${number})`;
+/** A field: its neutral type, and whether it may be null. */
+export interface FieldType {
+    readonly type: NeutralType;
+    readonly nullable: boolean;
+}
+/**
+ * The vocabulary as values.
+ *
+ * Note what is absent: any mapping from a TypeScript type. `T.timestamptz` is not "the neutral form
+ * of `Date`" - a `Date` has no zone information to inspect and `number` could be any of five things.
+ * The declaration says which one it is, because only the author knows.
+ */
+export declare const T: {
+    readonly bool: FieldType & {
+        nullable: false;
+    };
+    readonly int32: FieldType & {
+        nullable: false;
+    };
+    readonly int64: FieldType & {
+        nullable: false;
+    };
+    readonly float32: FieldType & {
+        nullable: false;
+    };
+    readonly float64: FieldType & {
+        nullable: false;
+    };
+    readonly string: FieldType & {
+        nullable: false;
+    };
+    readonly bytes: FieldType & {
+        nullable: false;
+    };
+    readonly uuid: FieldType & {
+        nullable: false;
+    };
+    readonly date: FieldType & {
+        nullable: false;
+    };
+    readonly timestamp: FieldType & {
+        nullable: false;
+    };
+    readonly timestamptz: FieldType & {
+        nullable: false;
+    };
+    readonly json: FieldType & {
+        nullable: false;
+    };
+    /** `T.decimal(12, 2)`. Both arguments are required, for the reason in this module's docstring. */
+    readonly decimal: (digits: number, scale: number) => FieldType;
+    /** Make any of the above nullable: `T.nullable(T.string)`. */
+    readonly nullable: (inner: FieldType) => FieldType;
+};
+/** Validate a type name that came from outside - a vector, or a hand-written declaration. */
+export declare function checkType(name: string, where: string): NeutralType;

package/dist/types.js

@@ -0,0 +1,100 @@
+/**
+ * The neutral type vocabulary, and how a TypeScript declaration reaches it.
+ *
+ * Here is where TypeScript differs from Python in the way that matters, and why it was worth writing
+ * second. Python can read a class's annotations at runtime and derive the model from them. TypeScript
+ * cannot: its types are erased before the code runs. So the model has to be *stated*, as values, and
+ * there is no possibility of inferring it from the shape of a class.
+ *
+ * That is a better test of the contract than a similar language would have been. Anything the format
+ * contract left implicit - anything that was really "what Python's introspection happens to produce"
+ * - has nowhere to hide here, because nothing is introspected.
+ *
+ * The vocabulary itself is fixed and shared:
+ *
+ *     bool  int32  int64  float32  float64  decimal(p,s)
+ *     string  bytes  uuid  date  timestamp  timestamptz  json
+ *
+ * `decimal` is written `decimal(12,2)` - precision, comma, scale, no spaces, both required. A decimal
+ * without precision is not a storable type in any engine we place data in, and letting the engine
+ * choose would make the physical schema depend on something the model never said.
+ */
+import { DeclarationError } from './errors.js';
+export const NEUTRAL_TYPES = [
+    'bool',
+    'int32',
+    'int64',
+    'float32',
+    'float64',
+    'string',
+    'bytes',
+    'uuid',
+    'date',
+    'timestamp',
+    'timestamptz',
+    'json',
+];
+function simple(type) {
+    return { type, nullable: false };
+}
+/**
+ * The vocabulary as values.
+ *
+ * Note what is absent: any mapping from a TypeScript type. `T.timestamptz` is not "the neutral form
+ * of `Date`" - a `Date` has no zone information to inspect and `number` could be any of five things.
+ * The declaration says which one it is, because only the author knows.
+ */
+export const T = {
+    bool: simple('bool'),
+    int32: simple('int32'),
+    int64: simple('int64'),
+    float32: simple('float32'),
+    float64: simple('float64'),
+    string: simple('string'),
+    bytes: simple('bytes'),
+    uuid: simple('uuid'),
+    date: simple('date'),
+    timestamp: simple('timestamp'),
+    timestamptz: simple('timestamptz'),
+    json: simple('json'),
+    /** `T.decimal(12, 2)`. Both arguments are required, for the reason in this module's docstring. */
+    decimal(digits, scale) {
+        if (!Number.isInteger(digits) || !Number.isInteger(scale)) {
+            throw new DeclarationError(`decimal(${digits}, ${scale}) needs whole numbers: a fractional precision is not a thing`);
+        }
+        if (digits < 1 || scale < 0 || scale > digits) {
+            throw new DeclarationError(`decimal(${digits}, ${scale}) is not a usable decimal: digits must be at least 1 and scale ` +
+                'must be between 0 and digits');
+        }
+        return { type: `decimal(${digits},${scale})`, nullable: false };
+    },
+    /** Make any of the above nullable: `T.nullable(T.string)`. */
+    nullable(inner) {
+        return { type: inner.type, nullable: true };
+    },
+};
+const DECIMAL = /^decimal\((\d+),(\d+)\)$/;
+/** Validate a type name that came from outside - a vector, or a hand-written declaration. */
+export function checkType(name, where) {
+    if (NEUTRAL_TYPES.includes(name)) {
+        return name;
+    }
+    if (name.startsWith('decimal')) {
+        const match = DECIMAL.exec(name);
+        if (match) {
+            const digits = Number(match[1]);
+            const scale = Number(match[2]);
+            if (digits >= 1 && scale >= 0 && scale <= digits) {
+                return name;
+            }
+        }
+        throw new DeclarationError(`${where}: ${JSON.stringify(name)} is not a well-formed decimal. The written form is ` +
+            'decimal(digits,scale) - precision then scale, no spaces, both required. No spaces because ' +
+            'whitespace inside a type name is exactly the sort of thing two libraries would disagree ' +
+            'about, and both required because a decimal without precision is not a storable type in any ' +
+            'engine we place data in.');
+    }
+    throw new DeclarationError(`${where}: ${JSON.stringify(name)} is not in the neutral type vocabulary ` +
+        `(${[...NEUTRAL_TYPES].sort().join(', ')}, decimal(p,s))`);
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

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

package/dist/verification.d.ts

@@ -0,0 +1,41 @@
+import type { PlacementMap } from './placement.js';
+export declare const REQUEST_PROTOCOL = 1;
+export declare function checkProjectId(value: string | undefined): void;
+interface VerificationFields {
+    readonly requestId: string;
+    readonly projectId: string;
+    readonly modelVersion: string;
+    readonly mapVersion: number;
+    readonly mapFingerprint: string;
+    readonly group: string;
+    readonly sourceEngine: string;
+    readonly sourceId: string;
+    readonly targets: readonly (readonly [string, string])[];
+    readonly requestedAt: string;
+    readonly requiresSignature: boolean;
+}
+export declare class VerificationRequest implements VerificationFields {
+    readonly requestId: string;
+    readonly projectId: string;
+    readonly modelVersion: string;
+    readonly mapVersion: number;
+    readonly mapFingerprint: string;
+    readonly group: string;
+    readonly sourceEngine: string;
+    readonly sourceId: string;
+    readonly targets: readonly (readonly [string, string])[];
+    readonly requestedAt: string;
+    readonly requiresSignature: boolean;
+    constructor(fields: VerificationFields);
+    asRecord(): Record<string, unknown>;
+    static fromRecord(value: unknown): VerificationRequest;
+    checkSession(placement: PlacementMap, projectId: string | undefined, group: string): void;
+    checkTime(at: string): void;
+}
+export declare function verificationRequest(placement: PlacementMap, options: {
+    readonly group: string;
+    readonly projectId: string;
+    readonly requestId: string;
+    readonly requestedAt: string;
+}): VerificationRequest;
+export {};

package/dist/verification.js

@@ -0,0 +1,169 @@
+/** A comparison bound to one request, locally configured project and exact placement map. */
+import { canonicalString, compareCodePoints } from './canonical.js';
+import { MigrationRefused } from './errors.js';
+import { fingerprintOf, placementOf } from './placement.js';
+import { Timestamp } from './timestamp.js';
+export const REQUEST_PROTOCOL = 1;
+function hex(value, width, field) {
+    if (typeof value !== 'string' || !new RegExp(`^[0-9a-f]{${width}}$`).test(value)) {
+        throw new MigrationRefused(`verification ${field} must be ${width} lowercase hexadecimal digits`);
+    }
+}
+export function checkProjectId(value) {
+    if (value !== undefined)
+        hex(value, 32, 'project_id');
+}
+function name(value) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new MigrationRefused('verification names must be nonempty strings');
+    }
+}
+function awareTime(value) {
+    if (typeof value !== 'string' || !/^\d{4}-\d{2}-\d{2}T(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d{1,6})?(?:Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)$/.test(value)) {
+        throw new MigrationRefused('verification time must be an ISO timestamp with an offset');
+    }
+    try {
+        return Timestamp.from(value).epochMicroseconds;
+    }
+    catch {
+        throw new MigrationRefused('verification time must be an ISO timestamp with an offset');
+    }
+}
+function exact(value, fields, label) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value) ||
+        Object.keys(value).sort().join('|') !== [...fields].sort().join('|')) {
+        throw new MigrationRefused(`verification ${label} has missing or unknown fields`);
+    }
+}
+export class VerificationRequest {
+    requestId;
+    projectId;
+    modelVersion;
+    mapVersion;
+    mapFingerprint;
+    group;
+    sourceEngine;
+    sourceId;
+    targets;
+    requestedAt;
+    requiresSignature;
+    constructor(fields) {
+        hex(fields.requestId, 32, 'request_id');
+        hex(fields.projectId, 32, 'project_id');
+        hex(fields.modelVersion, 16, 'model_version');
+        hex(fields.mapFingerprint, 64, 'map_fingerprint');
+        if (!Number.isSafeInteger(fields.mapVersion) || fields.mapVersion < 1) {
+            throw new MigrationRefused('verification map_version must be a positive integer');
+        }
+        if (typeof fields.requiresSignature !== 'boolean') {
+            throw new MigrationRefused('verification requires_signature must be a boolean');
+        }
+        for (const value of [fields.group, fields.sourceEngine, fields.sourceId])
+            name(value);
+        if (!Array.isArray(fields.targets) || fields.targets.length === 0) {
+            throw new MigrationRefused('verification targets must be nonempty engine/id pairs');
+        }
+        for (const target of fields.targets) {
+            if (!Array.isArray(target) || target.length !== 2) {
+                throw new MigrationRefused('verification targets must be nonempty engine/id pairs');
+            }
+            name(target[0]);
+            name(target[1]);
+            if (target[1] === fields.sourceId) {
+                throw new MigrationRefused('verification source cannot also be a target');
+            }
+        }
+        if (new Set(fields.targets.map((target) => target[1])).size !== fields.targets.length) {
+            throw new MigrationRefused('verification target ids must be unique');
+        }
+        const sorted = [...fields.targets].sort(compareTargets);
+        if (canonicalString(sorted) !== canonicalString(fields.targets)) {
+            throw new MigrationRefused('verification targets must be sorted by engine and id');
+        }
+        awareTime(fields.requestedAt);
+        this.requestId = fields.requestId;
+        this.projectId = fields.projectId;
+        this.modelVersion = fields.modelVersion;
+        this.mapVersion = fields.mapVersion;
+        this.mapFingerprint = fields.mapFingerprint;
+        this.group = fields.group;
+        this.sourceEngine = fields.sourceEngine;
+        this.sourceId = fields.sourceId;
+        this.targets = Object.freeze(fields.targets.map(([engine, id]) => Object.freeze([engine, id])));
+        this.requestedAt = fields.requestedAt;
+        this.requiresSignature = fields.requiresSignature;
+        Object.freeze(this);
+    }
+    asRecord() {
+        return {
+            protocol: REQUEST_PROTOCOL,
+            request_id: this.requestId, project_id: this.projectId,
+            model_version: this.modelVersion, map_version: this.mapVersion,
+            map_fingerprint: this.mapFingerprint, group: this.group,
+            source: { engine: this.sourceEngine, id: this.sourceId },
+            targets: this.targets.map(([engine, id]) => ({ engine, id })),
+            requested_at: this.requestedAt, requires_signature: this.requiresSignature,
+        };
+    }
+    static fromRecord(value) {
+        exact(value, ['protocol', 'request_id', 'project_id', 'model_version', 'map_version',
+            'map_fingerprint', 'group', 'source', 'targets', 'requested_at', 'requires_signature'], 'request');
+        if (value['protocol'] !== REQUEST_PROTOCOL) {
+            throw new MigrationRefused('unsupported verification request protocol');
+        }
+        const source = value['source'];
+        exact(source, ['engine', 'id'], 'source');
+        if (!Array.isArray(value['targets'])) {
+            throw new MigrationRefused('verification targets must contain exactly engine and id');
+        }
+        const targets = value['targets'].map((target) => {
+            exact(target, ['engine', 'id'], 'target');
+            return [target['engine'], target['id']];
+        });
+        return new VerificationRequest({
+            requestId: value['request_id'], projectId: value['project_id'],
+            modelVersion: value['model_version'], mapVersion: value['map_version'],
+            mapFingerprint: value['map_fingerprint'], group: value['group'],
+            sourceEngine: source['engine'], sourceId: source['id'], targets,
+            requestedAt: value['requested_at'], requiresSignature: value['requires_signature'],
+        });
+    }
+    checkSession(placement, projectId, group) {
+        if (projectId !== this.projectId) {
+            throw new MigrationRefused('verification request names another project, or this session has no project_id. ' +
+                "Configure the project id from the client's enrollment, not from the request.");
+        }
+        if (group !== this.group)
+            throw new MigrationRefused('verification request names another group');
+        const expected = verificationRequest(placement, {
+            group, projectId, requestId: this.requestId, requestedAt: this.requestedAt,
+        });
+        if (canonicalString(this.asRecord()) !== canonicalString(expected.asRecord())) {
+            throw new MigrationRefused("verification request does not match this session's model, map, source or targets; " +
+                'no comparison was started');
+        }
+    }
+    checkTime(at) {
+        if (awareTime(at) < awareTime(this.requestedAt)) {
+            throw new MigrationRefused("verification predates its request; check the verifier's clock and run the " +
+                'comparison for the current request');
+        }
+    }
+}
+function compareTargets(left, right) {
+    return compareCodePoints(left[0], right[0]) || compareCodePoints(left[1], right[1]);
+}
+export function verificationRequest(placement, options) {
+    const fingerprint = fingerprintOf(placement);
+    if (fingerprint === undefined) {
+        throw new MigrationRefused('verification needs a loaded, canonically encodable placement map');
+    }
+    const spot = placementOf(placement, options.group);
+    return new VerificationRequest({
+        ...options, modelVersion: placement.modelVersion, mapVersion: placement.mapVersion,
+        mapFingerprint: fingerprint, sourceEngine: spot.source.engine, sourceId: spot.source.id,
+        targets: spot.alsoWrite.map((target) => [target.engine, target.id]).sort(compareTargets),
+        requiresSignature: placement.signed,
+    });
+}
+//# sourceMappingURL=verification.js.map

package/dist/verification.js.map

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

package/dist/watermark.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Refusing a placement map that goes backwards, and the durable state that makes it possible.
+ *
+ * A signed map for version 3 verifies correctly forever - that is what a signature is. So replacing
+ * the client's map file with an older signed one loads cleanly, routes writes to the previous
+ * placement, and **nothing protests**. Today that costs a client a stale schema. Once the migration
+ * state travels in the map, it costs them writes: a library reverted from dual-write to
+ * single-write in the middle of a migration drops exactly the rows the migration exists not to
+ * drop.
+ *
+ * Refusing it needs one thing a library has never had: **memory**. Everything else here is a pure
+ * function of a document, a model and a key, which is why it can be verified by reading it. This
+ * module is the exception, and each of the three obvious places to keep that memory is worse than
+ * the one chosen:
+ *
+ * - **in the process** protects until the first restart, and a restart is when a swapped file is
+ *   read. A protection that lapses exactly when it is needed;
+ * - **in a file** needs a configured path, and in a container that path is usually ephemeral - so it
+ *   degrades to the first option while continuing to look like the third. The worst property
+ *   available: a guarantee present in the code and absent in production;
+ * - **with us** would mean the library asking our service whether it may start, which is the one
+ *   thing this product promises it will never need to do. Our outage would become the client's.
+ *
+ * So it lives **in the client's own engines**, in a table this library owns. Four properties, and
+ * the first two are what make it safe rather than merely present.
+ *
+ * **Append-only, and the watermark is `max(map_version)`.** No update, no key enforcement, no
+ * row-level contention - and therefore identical semantics in PostgreSQL and in ClickHouse, which is
+ * the engine that has no unique constraint to offer. A stale row can never lower the bar.
+ *
+ * **Every participating engine is written, and the watermark is the maximum over all of them.**
+ * Losing an engine cannot lose the protection, and one engine lagging cannot weaken it.
+ *
+ * **An engine that cannot store it does not participate, and that is reported rather than hidden.**
+ * A protection whose state cannot be read is a protection taken on trust.
+ *
+ * **Only signed maps are checked.** An unsigned map is the client's own document: hand-writing one
+ * and pointing a library at it is the no-account mode, and their business what they replace it with.
+ * In pure no-account mode this module does nothing at all - no table, no query, no cost.
+ *
+ * The escape hatch is deliberately not a parameter. A legitimate rollback - we issued a bad map -
+ * means clearing the bookkeeping, and the refusal says how. A parameter called `allowRollback` would
+ * be set once during an incident and left set.
+ */
+import { WATERMARK_MEMBERS } from './capabilities.js';
+import type { PlacementMap } from './placement.js';
+export type Protection = 'enforced' | 'unavailable' | 'not_applicable';
+/**
+ * What an engine adapter offers to take part.
+ *
+ * Separate from the engine interface, and optional. Requiring these of every adapter would break
+ * every one anybody has written - including the fakes in somebody else's test suite - for a
+ * capability one of our own engines cannot provide anyway. So participation is discovered rather
+ * than required, and non-participation is a reportable state instead of a crash.
+ */
+export interface WatermarkStore {
+    mapWatermark(): Promise<number | null>;
+    recordMapVersion(version: number, options: {
+        readonly modelVersion: string;
+    }): Promise<void>;
+}
+/**
+ * A compile-time ratchet between the interface and the list the runtime check uses.
+ *
+ * Add a method to `WatermarkStore` and forget `WATERMARK_MEMBERS`, and this stops being assignable.
+ * The runtime list cannot be derived from the interface - types are erased - so the compiler holds
+ * the other direction instead.
+ */
+export declare const WATERMARK_STORE_IS_TOTAL: (typeof WATERMARK_MEMBERS)[number] extends keyof WatermarkStore ? keyof WatermarkStore extends (typeof WATERMARK_MEMBERS)[number] ? true : never : never;
+/**
+ * What the check did, in a form a client can assert on.
+ *
+ * Exposed rather than kept private on purpose. A protection whose state cannot be read is a
+ * protection taken on trust, and this product's whole argument is that its guarantees are checkable
+ * by reading the code and now by reading this.
+ */
+export interface WatermarkCheck {
+    readonly protection: Protection;
+    readonly mapVersion: number;
+    readonly highestSeen: number | null;
+    readonly participating: readonly string[];
+    readonly unable: readonly string[];
+    readonly why: string;
+}
+export declare function watermarkRecord(check: WatermarkCheck): Record<string, unknown>;
+/**
+ * Refuse a signed map older than the newest one these engines have seen.
+ *
+ * Throws {@link MapRolledBack}. Equal is allowed - restarting a process against the same map is the
+ * ordinary case - and only strictly lower is refused.
+ *
+ * Asynchronous because reading a watermark is a query, and split in two inside: this gathers the
+ * numbers and {@link decide} makes the decision from them. The decision is therefore a pure
+ * function of a document and a set of integers, which is what lets the `migration/` vectors check
+ * it, and what lets a reader confirm by reading that nothing here depends on the order the engines
+ * answered in.
+ *
+ * **Nothing is read for an unsigned map.** The no-account mode promises no table, no query and no
+ * cost, and this function gathered every watermark and *then* asked whether the map was signed
+ * until `migration/001` existed - the right answer, with the promise broken, which is the one shape
+ * of defect a record of the decision cannot show.
+ */
+export declare function enforceForwardOnly(placement: PlacementMap, engines: Readonly<Record<string, unknown>>): Promise<WatermarkCheck>;