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

package/dist/placement.js

@@ -0,0 +1,651 @@
+/**
+ * The placement map: where every group lives, and where every operation goes.
+ *
+ * The only instruction this library takes from outside, and therefore the one input that refuses
+ * rather than degrades. A bad signature, a mismatched model version, an unknown contract version:
+ * all of them stop the library from starting, because the map decides where data is written.
+ *
+ * An unsigned map is valid - that is the no-account mode, and it is a supported way to use this
+ * library rather than a gap. What is refused is a map carrying a signature, and therefore claiming to
+ * come from us, when there is no key to check the claim against.
+ */
+import { createHash, createPublicKey, verify as verifySignature } from 'node:crypto';
+import { CanonicalError, canonicalBytes, compareCodePoints } from './canonical.js';
+import { MapError } from './errors.js';
+import { DRAIN_TABLE, EPOCH_COLUMN } from './generation.js';
+import { colocationGroups } from './groups.js';
+import { CONTRACT, entityOf } from './model.js';
+import { PHYSICAL_DESIGN_SINCE, checkAgainstModel, parseIndexes, parseKeyOrder, parsePartitionBy, } from './physical.js';
+import { enumerateShapes, shapeId } from './shapes.js';
+export const MAP_CONTRACT = 5;
+/**
+ * The placement map's format version, which is not the IR's - see `CONTRACT`.
+ *
+ * Five since 23 September 2026, for the physical design vocabulary (`physical.ts`): the order of a
+ * key, a time partition, and index methods. An earlier library would ignore `"method": "brin"` and
+ * build a B-tree from the same document, which is a loosening and therefore a bump. A contract-5
+ * library reads contracts 1 to 4 with their meaning unchanged, and refuses the new keys in them.
+ *
+ * Two because the map gained `also_write`, which a contract-1 library would ignore while a
+ * contract-2 one honours it: the same document, two different sets of engines written to, and the
+ * difference decided by which version happens to be installed. A loosening bumps the number.
+ */
+export const ALSO_WRITE_SINCE = 2;
+/**
+ * The contract that introduced `also_write`.
+ *
+ * A document declaring an earlier contract and carrying the key is refused. That is a *tightening*
+ * - no bump - and it exists because of who makes the mistake: a producer that grew the key and
+ * forgot to raise the number, which is what happened on the control-plane side of the very change
+ * that added it.
+ */
+export const MAP_CONTRACT_FLOOR = 1;
+/**
+ * The oldest map format this library still reads.
+ *
+ * Backwards compatible, forwards strict, and the asymmetry is knowledge rather than kindness: every
+ * contract-1 document is a valid contract-2 one with a key absent, which reads as "no dual write"
+ * and is a complete meaning. What came after this library cannot be known, so a higher number is
+ * refused rather than interpreted.
+ */
+export const WATERMARK_TABLE = 'sde_map_state';
+/**
+ * The table the Python library keeps its map bookkeeping in: the highest map version applied
+ * against an engine, which is what stops an older signed map being loaded over a newer one.
+ *
+ * This runtime has no engine adapters, so it never writes that table - and it refuses a layout
+ * naming it anyway. The rule is a *parsing* rule, and a parsing rule that holds in one language
+ * and not the other is exactly the divergence the conformance suite exists to catch: one map, two
+ * libraries, accepted here and refused there. Nothing in this file could have discovered that on
+ * its own.
+ */
+export const BACKFILL_TABLE = 'sde_backfill_state';
+/**
+ * The table the Python library keeps its backfill progress in: how many rows of each entity a
+ * migration has copied into an engine, which is what lets an interrupted backfill resume.
+ *
+ * The second reserved name, and the reason the refusal below is written over a table of them
+ * rather than over one string.
+ */
+export const RESERVED_TABLES = [
+    [
+        WATERMARK_TABLE,
+        'the highest map version applied against an engine, which is what stops an older map from ' +
+            'being loaded over a newer one',
+    ],
+    [
+        BACKFILL_TABLE,
+        'how many rows of each entity a migration has copied into an engine, which is what lets an ' +
+            'interrupted backfill resume instead of starting over',
+    ],
+];
+/**
+ * Table names the library owns, and what each one holds - kept in the same order as the Python
+ * mapping so that a document colliding with two of them is refused for the same one in both.
+ */
+const AUTO = Symbol('auto-layout');
+function asRecord(value, where) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new MapError(`${where}: expected an object`);
+    }
+    return value;
+}
+function readLayout(raw, where, contract) {
+    const body = asRecord(raw, `${where}: layout`);
+    if (body['auto'] === true) {
+        if (Object.keys(body).length !== 1) {
+            throw new MapError(`${where}: a layout is either auto or explicit, not both. Two sources of truth for a schema ` +
+                'is how a column ends up existing in one place and not the other.');
+        }
+        return AUTO;
+    }
+    const tables = body['tables'];
+    if (typeof tables !== 'object' || tables === null || Object.keys(tables).length === 0) {
+        throw new MapError(`${where}: layout needs a non-empty 'tables' mapping entity to table name, or {"auto": true} ` +
+            'to have one derived from the model');
+    }
+    for (const [name, holds] of RESERVED_TABLES) {
+        const reserved = Object.entries(tables)
+            .filter(([, table]) => table === name)
+            .map(([entity]) => entity)
+            .sort();
+        if (reserved.length > 0) {
+            throw new MapError(`${where}: ${JSON.stringify(reserved)} would be stored in a table called ` +
+                `'${name}', which this library keeps its own bookkeeping in - ${holds}. A client table ` +
+                'under that name would be read as bookkeeping and written to as bookkeeping. Rename ' +
+                'the table; the name is yours to choose everywhere else.');
+        }
+    }
+    const columns = (body['columns'] ?? {});
+    let keyOrder = {};
+    let partitionBy = {};
+    if (contract < PHYSICAL_DESIGN_SINCE) {
+        // Before contract 5 `partition_by` had no meaning, and the refusal is the whole point: the key
+        // was parsed, emitted by the control plane when non-empty, and no renderer ever applied it. A
+        // contract-4 document may not start meaning something by it now (`errors/037`).
+        if (Object.keys((body['partition_by'] ?? {})).length > 0) {
+            throw new MapError(`${where}: this layout declares partition_by in a document declaring map contract ` +
+                `${contract}, where no library renders it - the table would be created unpartitioned ` +
+                `and nothing would say so. Partitioning is map contract ${PHYSICAL_DESIGN_SINCE}; ` +
+                'remove the key or raise the contract.');
+        }
+        if ('key_order' in body) {
+            throw new MapError(`${where}: key_order is map contract ${PHYSICAL_DESIGN_SINCE} and this document declares ` +
+                `${contract}. A library of that contract would ignore it and order the key as declared, ` +
+                'so one document would build two different tables.');
+        }
+    }
+    else {
+        const named = tables;
+        // Absent is "no design"; `null` is a key with a value that is not a design, refused as the
+        // reference refuses it. `?? {}` would read the two as one - the `or` against `??` divergence
+        // this suite has caught before, one key over.
+        keyOrder = parseKeyOrder(body['key_order'] === undefined ? {} : body['key_order'], where, named);
+        partitionBy = parsePartitionBy(body['partition_by'] === undefined ? {} : body['partition_by'], where, named);
+    }
+    return {
+        tables: tables,
+        columns,
+        indexes: parseIndexes(body['indexes'], where, tables, columns, contract),
+        partitionBy,
+        keyOrder,
+    };
+}
+/**
+ * The derived copies writes are additionally sent to. Four refusals, each with its failure.
+ *
+ * Validated when the map loads rather than at the first write, for the reason the routing table
+ * was: a map is handed over once and obeyed for months, so a defect in it should be found when it
+ * arrives and not by the request that happens to touch it. During a migration that request is a
+ * write, and the failure is a write that goes to one engine when the map says two.
+ */
+function readAlsoWrite(raw, where, contract, source, derived) {
+    if (raw === undefined || raw === null)
+        return [];
+    if (contract < ALSO_WRITE_SINCE) {
+        throw new MapError(`${where}: this map declares format contract ${contract} and uses 'also_write', which ` +
+            `contract ${ALSO_WRITE_SINCE} introduced. Refused rather than honoured, and the reason is ` +
+            'who makes this mistake: a producer that grew the key and forgot to raise the number. ' +
+            'Honouring it would mean a contract-1 library ignoring the fan-out while a contract-2 one ' +
+            'performs it - the same document, two sets of engines written to - which is the whole ' +
+            'failure the version exists to prevent.');
+    }
+    if (!Array.isArray(raw) || raw.length === 0) {
+        throw new MapError(`${where}: 'also_write' is a non-empty list of materialisation ids, or absent. Absent means ` +
+            'writes go to the source alone; an empty list would be a claim that fan-out was ' +
+            'considered and none chosen, which is a stronger thing to say and not what the planner ' +
+            'means when it omits the key.');
+    }
+    const byId = new Map(derived.map((m) => [m.id, m]));
+    const out = [];
+    const seen = new Set();
+    for (const entry of raw) {
+        if (typeof entry !== 'string') {
+            throw new MapError(`${where}: 'also_write' holds materialisation ids, not ${JSON.stringify(entry)}`);
+        }
+        if (entry === source.id) {
+            throw new MapError(`${where}: 'also_write' names the source '${entry}'. The source is where writes already ` +
+                'land - listing it would either write the row twice or read as though the source were ' +
+                'somehow optional, and both are worse than the refusal.');
+        }
+        if (seen.has(entry)) {
+            throw new MapError(`${where}: 'also_write' names '${entry}' twice. Two identical fan-out targets is either a ` +
+                'duplicated row or a document nobody meant to write.');
+        }
+        const found = byId.get(entry);
+        if (found === undefined) {
+            throw new MapError(`${where}: 'also_write' names '${entry}', which is not a derived materialisation of this ` +
+                `group. It has ${JSON.stringify([...byId.keys()].sort())}. A fan-out target that does ` +
+                'not exist is a write with nowhere to go, and during a migration that is a row the copy ' +
+                'never receives.');
+        }
+        seen.add(entry);
+        out.push(found);
+    }
+    return out;
+}
+function readMaterialization(raw, where, isSource, contract) {
+    const body = asRecord(raw, where);
+    for (const required of ['id', 'engine', 'layout']) {
+        if (!(required in body))
+            throw new MapError(`${where}: materialisation is missing '${required}'`);
+    }
+    const lag = body['lag_budget_ms'];
+    if (isSource && lag !== undefined && lag !== null) {
+        throw new MapError(`${where}: the source materialisation cannot have a lag budget. The source is where writes ` +
+            'land, so it is by definition not behind anything.');
+    }
+    if (!isSource && (lag === undefined || lag === null)) {
+        throw new MapError(`${where}: a derived materialisation needs lag_budget_ms. Without it nobody - not the client, ` +
+            'not the monitoring - can tell whether it is healthy or hours behind.');
+    }
+    return {
+        mat: {
+            id: String(body['id']),
+            engine: String(body['engine']),
+            lagBudgetMs: isSource ? null : Number(lag),
+        },
+        layout: readLayout(body['layout'], where, contract),
+    };
+}
+/**
+ * Derive the obvious schema for a group.
+ *
+ * Tier 0 does not create schema, so this only has to produce the same *names* the Python
+ * implementation does - which is what a routing decision depends on. Column types are a Tier 2
+ * concern and are deliberately left empty rather than guessed at half-right.
+ */
+function defaultLayout(model, members) {
+    const tables = {};
+    for (const member of members) {
+        entityOf(model, member);
+        tables[member] = member
+            .normalize('NFC')
+            .replace(/(?<=[a-z0-9])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])/g, '_')
+            .toLowerCase();
+    }
+    return { tables, columns: {}, indexes: [], partitionBy: {}, keyOrder: {} };
+}
+/**
+ * Normalise what the caller supplied into named keys, refusing what cannot be a key.
+ *
+ * A key of the wrong length is refused here rather than left to fail verification: it is the
+ * client's configuration, and a rotation that silently did not take effect - because the new key
+ * was pasted a byte short - is the failure this whole mechanism exists to avoid.
+ */
+function keySet(publicKey) {
+    let pairs;
+    if (publicKey instanceof Uint8Array) {
+        pairs = [['', publicKey]];
+    }
+    else {
+        pairs = Object.entries(publicKey).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+        if (pairs.length === 0) {
+            throw new MapError('an empty set of public keys was supplied. That is not the no-account mode - a map with ' +
+                'no signature is - it is a configuration that can verify nothing. Pass the keys, or ' +
+                'load an unsigned map.');
+        }
+    }
+    for (const [name, value] of pairs) {
+        if (value.length !== 32) {
+            throw new MapError(`the public key ${JSON.stringify(name || '(unnamed)')} is ${value.length} bytes and an ` +
+                'Ed25519 public key is 32. Refused here rather than at verification: a key pasted a ' +
+                'byte short would look like a map that does not verify, and the two have completely ' +
+                'different fixes.');
+        }
+    }
+    return pairs;
+}
+/**
+ * Verify, and report **which** of the caller's keys did it.
+ *
+ * **Every key is tried, and `key_id` only decides the order.** The signature block is excluded
+ * from the signed payload in its entirety, so `key_id` is not covered by the signature and anybody
+ * can edit it. Treating it as authoritative would be trusting an attacker's annotation; making it
+ * authenticated would change what the payload is, which recomputes every signature ever issued and
+ * is a contract bump in every language at once. As an ordering it costs nothing to be wrong about.
+ *
+ * The cost of accepting a set is real: **an old key verifies for as long as the client keeps it.**
+ * This library has no clock, so it cannot expire one - and that same absence is what makes "you
+ * stop paying and nothing breaks" true. Revocation is the client removing a key from their own
+ * configuration, which is why the id that verified is reported.
+ */
+/** Internal shared verifier for signed instruction envelopes; not a package entry point. */
+export function verifyMapSignature(raw, publicKey) {
+    const signature = asRecord(raw['signature'], 'signature');
+    if (signature['alg'] !== 'ed25519') {
+        throw new MapError('only ed25519 signatures are understood');
+    }
+    const value = Buffer.from(String(signature['value']), 'base64');
+    const { signature: _omit, ...rest } = raw;
+    const payload = canonicalBytes(rest);
+    const claimed = typeof signature['key_id'] === 'string' ? signature['key_id'] : null;
+    const keys = keySet(publicKey);
+    const ordered = claimed === null
+        ? keys
+        : [...keys.filter(([name]) => name === claimed), ...keys.filter(([name]) => name !== claimed)];
+    for (const [name, raw32] of ordered) {
+        // Node wants a KeyObject; a raw 32-byte Ed25519 key becomes one via a minimal DER wrapper. The
+        // alternative is asking callers for PEM, which is a worse interface for a key that is 32 bytes.
+        const der = Buffer.concat([
+            Buffer.from('302a300506032b6570032100', 'hex'),
+            Buffer.from(raw32),
+        ]);
+        const key = createPublicKey({ key: der, format: 'der', type: 'spki' });
+        if (verifySignature(null, payload, key, value)) {
+            return name === '' ? null : name;
+        }
+    }
+    const tried = ordered.map(([name]) => name || '(unnamed)');
+    throw new MapError(`the map's signature does not verify against any of the ${ordered.length} key(s) supplied ` +
+        `(${JSON.stringify(tried)}); the map says it was signed with ${JSON.stringify(claimed)}. ` +
+        'This is refused rather than warned about: the map decides where your data is written. If a ' +
+        'rotation is in progress, the key named above is the one to add - and while both are ' +
+        'configured, maps signed with either are accepted.');
+}
+/**
+ * Every routing entry must name a materialisation that exists, in the shape's own group.
+ *
+ * This lived in `materializationById` - that is, at the first read that routed through the broken
+ * entry. Deferring it there turns a mistake in a document we hand over into an error inside the
+ * client's request path at a moment nobody can predict: only the shapes routing through that entry
+ * fail, so a run that never issues those operations is green and the map looks applied.
+ *
+ * Two levels, because the model is optional. Without one: the target must be an id declared
+ * somewhere in this map. With one: it must be declared in the group the shape belongs to - the
+ * check that matters, since ids are unique only *within* a group.
+ */
+function checkRoutingTargets(routing, groups, model) {
+    const declared = Object.create(null);
+    const everywhere = new Set();
+    for (const [name, placement] of Object.entries(groups)) {
+        const ids = new Set([placement.source, ...placement.derived].map((m) => m.id));
+        declared[name] = ids;
+        for (const id of ids)
+            everywhere.add(id);
+    }
+    const entries = Object.entries(routing).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    for (const [shapeIdent, target] of entries) {
+        if (typeof target !== 'string') {
+            throw new MapError(`the routing entry for shape '${shapeIdent}' is not a materialisation id. Routing maps a ` +
+                'shape id to one id, and anything else is a table nobody can look up.');
+        }
+        if (!everywhere.has(target)) {
+            throw new MapError(`the routing table sends shape '${shapeIdent}' to materialisation '${target}', and no ` +
+                'group in this map declares one with that id. The map is internally inconsistent: ' +
+                `declared ids are ${JSON.stringify([...everywhere].sort())}.`);
+        }
+    }
+    if (!model)
+        return;
+    const shapes = new Map(enumerateShapes(model).map((shape) => [shapeId(shape), shape]));
+    for (const [shapeIdent, target] of entries) {
+        const shape = shapes.get(shapeIdent);
+        if (!shape) {
+            throw new MapError(`the routing table has an entry for shape '${shapeIdent}', and this model does not produce ` +
+                'that shape. The model version matched, so the two sides enumerated shapes differently - ' +
+                "which is the divergence that puts one library's write in a table another library never " +
+                'looks at.');
+        }
+        if (!declared[shape.group]?.has(target)) {
+            throw new MapError(`the routing table sends shape '${shapeIdent}' - which belongs to group '${shape.group}' - ` +
+                `to materialisation '${target}', which that group does not declare. ` +
+                'Materialisation ids are unique only within a group, so this would read ' +
+                `${shape.entity} out of a copy that does not hold it.`);
+        }
+    }
+}
+/**
+ * The physical design rules that need the model: key permutations and partitions on the key.
+ *
+ * Materialisations in document order within the group, entities in name order within a layout -
+ * the ordering the reference gives it, so one document refuses the same way in both languages.
+ */
+function checkPhysical(placement, model) {
+    for (const material of [placement.source, ...placement.derived]) {
+        const layout = material.layout;
+        const where = `group '${placement.group}': '${material.id}'`;
+        const keyOrder = layout.keyOrder ?? {};
+        const entities = [...new Set([...Object.keys(keyOrder), ...Object.keys(layout.partitionBy)])].sort(compareCodePoints);
+        for (const entity of entities) {
+            const spec = model.entities.find((candidate) => candidate.name === entity);
+            if (spec === undefined) {
+                throw new MapError(`${where}: the physical design names '${entity}', which this model does not declare, so ` +
+                    'there is no key to order or partition by.');
+            }
+            const fieldTypes = Object.create(null);
+            for (const field of spec.fields)
+                fieldTypes[field.name] = field.type;
+            checkAgainstModel(where, entity, spec.key, fieldTypes, Object.hasOwn(keyOrder, entity) ? keyOrder[entity] : undefined, Object.hasOwn(layout.partitionBy, entity) ? layout.partitionBy[entity] : undefined);
+        }
+    }
+}
+function requireCanonicalText(value) {
+    if (typeof value === 'string') {
+        // With /u, a valid surrogate pair is one astral code point; only unpaired halves match.
+        if (value !== value.normalize('NFC') || /[\uD800-\uDFFF]/u.test(value)) {
+            throw new MapError('placement map payload strings and member names must be Unicode scalar text in NFC');
+        }
+    }
+    else if (Array.isArray(value)) {
+        for (const child of value)
+            requireCanonicalText(child);
+    }
+    else if (value !== null && typeof value === 'object') {
+        for (const [key, child] of Object.entries(value)) {
+            requireCanonicalText(key);
+            requireCanonicalText(child);
+        }
+    }
+}
+export function loadMap(raw, options = {}) {
+    const body = asRecord(structuredClone(raw), 'a placement map');
+    const contract = body['contract'];
+    if (typeof contract !== 'number' || !Number.isInteger(contract)) {
+        throw new MapError(`this map declares format contract ${JSON.stringify(contract)}, which is not a version ` +
+            `number. This library reads ${MAP_CONTRACT_FLOOR} to ${MAP_CONTRACT}.`);
+    }
+    if (contract < MAP_CONTRACT_FLOOR) {
+        throw new MapError(`this map declares format contract ${contract} and the oldest this library still reads is ` +
+            `${MAP_CONTRACT_FLOOR}.`);
+    }
+    if (contract > MAP_CONTRACT) {
+        throw new MapError(`this map declares format contract ${contract} and this library implements ` +
+            `${MAP_CONTRACT}. Refusing rather than guessing: a version this library does not know may ` +
+            'say something with a key it has never heard of, and the difference between two contract ' +
+            'versions is exactly the kind of thing that would otherwise be interpreted as a missing ' +
+            'field meaning zero. Upgrade the library.');
+    }
+    // Reject instead of rewriting physical names after verifying a normalized signature.
+    // key_id is outside the payload and remains only a hint about which trusted key to try first.
+    requireCanonicalText(Object.fromEntries(Object.entries(body).filter(([key]) => key !== 'signature')));
+    const projectId = contract >= 4 ? body['project_id'] : undefined;
+    if (contract >= 4 && (typeof projectId !== 'string' || !/^[0-9a-f]{32}$/.test(projectId))) {
+        throw new MapError('contract 4 requires a 32-digit lowercase hexadecimal project_id');
+    }
+    if (contract < 4 && 'project_id' in body)
+        throw new MapError('project_id requires placement map contract 4');
+    const modelVersion = body['model_version'];
+    if (typeof modelVersion !== 'string' || modelVersion.length === 0) {
+        throw new MapError('the map does not say which model version it is for');
+    }
+    if (options.model && options.model.version !== modelVersion) {
+        throw new MapError(`this map is for model version ${modelVersion} and your declared model is ` +
+            `${options.model.version}. Something changed in your entities; ask for a new map rather than ` +
+            'running against this one, because the difference cannot be guessed.');
+    }
+    const mapVersion = body['map_version'];
+    if (typeof mapVersion !== 'number' || !Number.isInteger(mapVersion) || mapVersion < 1) {
+        throw new MapError(`this map declares map_version ${JSON.stringify(mapVersion)}, which is not a version ` +
+            "number. It used to be read as Number(body['map_version'] ?? 0), so a document without " +
+            'one loaded as version 0 - and this is the number that decides whether an older map is ' +
+            "being replayed over a newer one against the client's own engines.");
+    }
+    let verifiedWith = null;
+    const signaturePresent = body['signature'] !== undefined && body['signature'] !== null;
+    if (options.requireSignature === true && !signaturePresent) {
+        throw new MapError('a signature was required and this map has none');
+    }
+    if (signaturePresent) {
+        if (!options.publicKey) {
+            throw new MapError('this map is signed, which is a claim that it came from us, and no public key was provided ' +
+                'to check that claim. Either pass the key, or use an unsigned map - an unsigned map is a ' +
+                'supported mode, an unverifiable claim is not.');
+        }
+        verifiedWith = verifyMapSignature(body, options.publicKey);
+    }
+    const groupsRaw = body['groups'];
+    if (typeof groupsRaw !== 'object' || groupsRaw === null) {
+        throw new MapError('the map places no groups');
+    }
+    const modelGroups = options.model ? colocationGroups(options.model) : [];
+    const membersOf = new Map(modelGroups.map((g) => [g.name, g.members]));
+    const groups = {};
+    // By name, not in the document's order. A map with two defects has to refuse the same way in
+    // every language (format-contract §8a): `errors/019` carries a reserved table name in one group
+    // and an auto-plus-explicit layout in another, and it pinned the first only because that group is
+    // written earlier in the file and both of our runtimes iterate an object in insertion order. A
+    // third implementation in Go, whose maps iterate in a randomised order, failed that vector in 5
+    // of 20 runs. `checkRoutingTargets` has sorted since it was written; this loop had not.
+    const groupNames = Object.keys(groupsRaw).sort(compareCodePoints);
+    for (const name of groupNames) {
+        const value = groupsRaw[name];
+        const where = `group '${name}'`;
+        const placement = asRecord(value, where);
+        if (!('source' in placement)) {
+            throw new MapError(`${where}: needs a 'source' materialisation`);
+        }
+        const resolve = (layout, what) => {
+            if (layout !== AUTO)
+                return layout;
+            const members = membersOf.get(name);
+            if (!members) {
+                throw new MapError(`${where}.${what}: a layout asked to be derived with {"auto": true}, but no model was ` +
+                    'supplied to derive it from. Pass model to loadMap().');
+            }
+            return defaultLayout(options.model, members);
+        };
+        const writeEpoch = contract >= 4 ? placement['write_epoch'] : undefined;
+        if (contract >= 4 && (typeof writeEpoch !== 'number' || !Number.isSafeInteger(writeEpoch) || writeEpoch < 1)) {
+            throw new MapError(`${where}: contract 4 requires a positive safe write_epoch`);
+        }
+        if (contract < 4 && 'write_epoch' in placement) {
+            throw new MapError(`${where}: write_epoch requires placement map contract 4`);
+        }
+        const sourceRead = readMaterialization(placement['source'], `${where}.source`, true, contract);
+        const source = {
+            ...sourceRead.mat,
+            layout: resolve(sourceRead.layout, 'source'),
+        };
+        const derivedRaw = (placement['derived'] ?? []);
+        const derived = derivedRaw.map((entry, i) => {
+            const read = readMaterialization(entry, `${where}.derived[${i}]`, false, contract);
+            return { ...read.mat, layout: resolve(read.layout, `derived[${i}]`) };
+        });
+        const ids = [source, ...derived].map((m) => m.id);
+        if (new Set(ids).size !== ids.length) {
+            throw new MapError(`${where}: two materialisations share an id`);
+        }
+        // A derived copy in the same engine, naming the same tables, is the source with a second name in
+        // the map: its lag would always read as zero and a read routed to it would silently be a read of
+        // the source. Found by a Python test; refused here for the same reason.
+        const sourceTables = new Set(Object.values(source.layout.tables));
+        for (const candidate of derived) {
+            if (candidate.engine !== source.engine)
+                continue;
+            const shared = Object.values(candidate.layout.tables)
+                .filter((t) => sourceTables.has(t))
+                .sort();
+            if (shared.length > 0) {
+                throw new MapError(`${where}: materialisation '${candidate.id}' is in the same engine as the source and ` +
+                    `reuses its tables ${JSON.stringify(shared)}. That is not a copy of the group, it is ` +
+                    'the original with a second name in the map.');
+            }
+        }
+        groups[name] = {
+            ...(writeEpoch === undefined ? {} : { writeEpoch: writeEpoch }),
+            group: name,
+            source,
+            derived,
+            alsoWrite: readAlsoWrite(placement['also_write'], where, contract, source, derived),
+        };
+    }
+    if (options.model) {
+        const declaredNames = modelGroups.map((g) => g.name);
+        const missing = declaredNames.filter((name) => !(name in groups)).sort();
+        if (missing.length > 0) {
+            throw new MapError(`the map does not place these groups: ${JSON.stringify(missing)}. Every group in the model ` +
+                'needs a home before anything can run.');
+        }
+        // And the other direction. Checking one of the two reads as complete: Python fell through to a
+        // dict lookup and produced a bare KeyError, this one accepted the map in silence. Two
+        // languages, one missing check, two different wrong answers.
+        const unknown = Object.keys(groups)
+            .filter((name) => !declaredNames.includes(name))
+            .sort();
+        if (unknown.length > 0) {
+            throw new MapError(`the map places groups this model does not have: ${JSON.stringify(unknown)}. The model ` +
+                'version matched, so this is not a stale map: the two sides derived colocation groups ' +
+                'differently, and a group nobody declared has no entities to hold.');
+        }
+    }
+    const routingRaw = body['routing'] ?? {};
+    if (typeof routingRaw !== 'object' || routingRaw === null) {
+        throw new MapError("'routing' must be a mapping from shape id to materialisation id");
+    }
+    if (options.model) {
+        for (const name of Object.keys(groups).sort(compareCodePoints)) {
+            checkPhysical(groups[name], options.model);
+        }
+    }
+    checkRoutingTargets(routingRaw, groups, options.model);
+    if (contract >= 4) {
+        for (const spot of Object.values(groups)) {
+            for (const materialization of [spot.source, ...spot.derived]) {
+                if (Object.values(materialization.layout.columns).some((fields) => EPOCH_COLUMN in fields)) {
+                    throw new MapError('the write-epoch column is reserved for the SDK');
+                }
+                if (Object.values(materialization.layout.tables).includes(DRAIN_TABLE)) {
+                    throw new MapError('the write-fence drain log is reserved for the SDK');
+                }
+            }
+        }
+    }
+    let fingerprint;
+    try {
+        const payload = { ...body };
+        delete payload['signature'];
+        fingerprint = createHash('sha256').update(canonicalBytes(payload)).digest('hex');
+    }
+    catch (error) {
+        if (!(error instanceof CanonicalError))
+            throw error;
+        if (contract >= 4)
+            throw new MapError('contract 4 requires a canonically encodable placement map');
+    }
+    const result = {
+        // The document's number, not this library's. Reporting CONTRACT here said "this map declares
+        // contract 2" of a document declaring 1, and the Python field has always carried the
+        // document's.
+        contract,
+        modelVersion,
+        mapVersion,
+        ...(projectId === undefined ? {} : { projectId: projectId }),
+        groups,
+        routing: routingRaw,
+        signed: signaturePresent,
+        fingerprint,
+        verifiedWith,
+    };
+    freeze(result);
+    loadedFingerprints.set(result, fingerprint);
+    return result;
+}
+const loadedFingerprints = new WeakMap();
+export function fingerprintOf(map) {
+    return loadedFingerprints.get(map);
+}
+function freeze(value) {
+    if (typeof value !== 'object' || value === null)
+        return;
+    for (const member of Object.values(value))
+        freeze(member);
+    Object.freeze(value);
+}
+export function placementOf(map, group) {
+    const found = map.groups[group];
+    if (!found) {
+        throw new MapError(`no placement for group '${group}'. Every group in the model needs one: a group with nowhere ` +
+            'to live is not a slow path, it is an unanswerable operation.');
+    }
+    return found;
+}
+export function materializationById(placement, id) {
+    const found = [placement.source, ...placement.derived].find((m) => m.id === id);
+    if (!found) {
+        throw new MapError(`group '${placement.group}' has no materialisation '${id}', but the routing table points at ` +
+            'it. The map is internally inconsistent.');
+    }
+    return found;
+}
+//# sourceMappingURL=placement.js.map