@mistriwork/engine 0.0.0-stage → 1.0.0-rc.9

package/dist/adapters/http/openapi.js

@@ -0,0 +1,487 @@
+/**
+ * An OpenAPI document read as a catalog of browsable resources.
+ *
+ * A resource is a collection an API lists (`GET /contacts`) together with the
+ * item it reads by key (`GET /contacts/{id}`), when both answer the same kind
+ * of row. For each one this says the columns a row carries and what the API
+ * can do with a list — filter, search, sort, page — as data, so tablewalk
+ * asks the API only what it can answer and refuses the rest by name.
+ *
+ * Pure: a parsed JSON document in, a catalog out. The spec is pinned locally
+ * and read at startup, as a database's catalog is read on connect, so there
+ * is no network here, no remote `$ref` and no YAML. Nothing outside the
+ * supported subset is guessed at: its operation is skipped with the reason,
+ * which `--check-openapi` prints. Paging is the one inference, and every
+ * inferred setting is listed under `guesses` for the author to confirm.
+ */
+/** The whole document is outside what tablewalk reads; the message names the fix. */
+export class OpenApiError extends Error {
+    code = 'openapi_unsupported';
+    constructor(message) {
+        super(message);
+        this.name = 'OpenApiError';
+    }
+}
+const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/* One operation outside the subset: skipped with this reason, never the whole document's failure. */
+class Skip extends Error {
+}
+/* Bounds on what one document may ask of the reader, so a pathological spec
+   costs a refusal rather than a hung startup. */
+const LIMITS = { paths: 2000, properties: 500, refDepth: 32, allOfDepth: 8 };
+/* Parameter names that mean paging, search or sort rather than a column.
+   A name the author uses differently is corrected in the description the
+   import drafts; the reader only proposes. */
+const SEARCH = ['q', 'search', 'query'];
+const SORT = ['sort', 'sort_by', 'sortBy', 'order', 'order_by', 'orderBy'];
+const PAGING = {
+    offset: ['offset', 'skip'],
+    limit: ['limit', 'per_page', 'page_size', 'pageSize', 'size'],
+    page: ['page', 'page_number', 'pageNumber'],
+    cursor: ['cursor', 'after', 'page_token', 'pageToken', 'starting_after', 'next_token'],
+    next: ['next_cursor', 'nextCursor', 'next_page_token', 'nextPageToken', 'next', 'cursor'],
+};
+const NAME = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+const pointer = (name) => name.replace(/~/g, '~0').replace(/\//g, '~1');
+const typesOf = (schema) => Array.isArray(schema.type)
+    ? schema.type.filter((type) => typeof type === 'string')
+    : typeof schema.type === 'string'
+        ? [schema.type]
+        : [];
+/** Follows local `$ref`s within this one document; a remote one is a Skip, never a fetch. */
+function resolver(document) {
+    return function resolve(value) {
+        let current = value;
+        for (let depth = 0; isObject(current) && typeof current.$ref === 'string'; depth++) {
+            if (depth >= LIMITS.refDepth)
+                throw new Skip(`a $ref chain is longer than ${LIMITS.refDepth} links`);
+            const ref = current.$ref;
+            if (!ref.startsWith('#/'))
+                throw new Skip(`the remote $ref ${JSON.stringify(ref)} is not read: only one file is read`);
+            let target = document;
+            for (const raw of ref.slice(2).split('/')) {
+                const key = raw.replace(/~1/g, '/').replace(/~0/g, '~');
+                target = isObject(target) && Object.hasOwn(target, key) ? target[key] : undefined;
+            }
+            if (target === undefined)
+                throw new Skip(`the $ref ${JSON.stringify(ref)} names nothing in the document`);
+            current = target;
+        }
+        return current;
+    };
+}
+/* A row's properties, with `allOf` parts merged in order. A row that is one
+   of several shapes has no single set of columns, so it is skipped rather
+   than flattened into something no response actually is. */
+function rowShape(resolve, raw, depth = 0) {
+    if (depth > LIMITS.allOfDepth)
+        throw new Skip(`allOf nests deeper than ${LIMITS.allOfDepth} levels`);
+    const schema = resolve(raw);
+    if (!isObject(schema))
+        throw new Skip('the row schema is not an object');
+    if (schema.oneOf !== undefined || schema.anyOf !== undefined || schema.discriminator !== undefined) {
+        throw new Skip('a row that is one of several shapes (oneOf, anyOf, discriminator) is not read yet');
+    }
+    const shape = { properties: new Map(), required: new Set() };
+    const add = (name, property) => {
+        const before = shape.properties.get(name);
+        if (before !== undefined && JSON.stringify(before) !== JSON.stringify(property)) {
+            throw new Skip(`the property "${name}" is declared twice with different schemas`);
+        }
+        shape.properties.set(name, property);
+    };
+    const parts = Array.isArray(schema.allOf) ? schema.allOf : [];
+    for (const part of parts) {
+        const inner = rowShape(resolve, part, depth + 1);
+        for (const [name, property] of inner.properties)
+            add(name, property);
+        for (const name of inner.required)
+            shape.required.add(name);
+    }
+    if (isObject(schema.properties))
+        for (const [name, property] of Object.entries(schema.properties))
+            add(name, property);
+    if (Array.isArray(schema.required))
+        for (const name of schema.required)
+            if (typeof name === 'string')
+                shape.required.add(name);
+    if (!parts.length && !isObject(schema.properties) && !typesOf(schema).includes('object'))
+        throw new Skip('the row schema is not an object');
+    if (shape.properties.size > LIMITS.properties)
+        throw new Skip(`a row has ${shape.properties.size} properties; at most ${LIMITS.properties} are read`);
+    return shape;
+}
+function column(resolve, name, raw, required) {
+    const resolved = resolve(raw);
+    let property = isObject(resolved) ? resolved : {};
+    // Only an exact scalar-or-null union has one column type. Other unions
+    // remain documents; annotations outside the union must not erase a constraint.
+    if (Array.isArray(property.anyOf) &&
+        property.anyOf.length === 2 &&
+        Object.keys(property).every((key) => ['anyOf', 'description', 'title', 'readOnly'].includes(key))) {
+        const arms = property.anyOf.map(resolve);
+        const nullIndex = arms.findIndex((arm) => isObject(arm) && arm.type === 'null' && Object.keys(arm).length === 1);
+        const scalar = arms[1 - nullIndex];
+        if (nullIndex !== -1 &&
+            isObject(scalar) &&
+            typeof scalar.type === 'string' &&
+            ['string', 'integer', 'number', 'boolean'].includes(scalar.type) &&
+            !['anyOf', 'oneOf', 'allOf', 'properties', 'items'].some((key) => Object.hasOwn(scalar, key))) {
+            const { anyOf: _union, ...annotations } = property;
+            property = { ...scalar, ...annotations, nullable: true };
+        }
+    }
+    const types = typesOf(property), base = types.filter((type) => type !== 'null');
+    const allowed = Array.isArray(property.enum) && property.enum.length && property.enum.every((value) => typeof value === 'string')
+        ? property.enum
+        : undefined;
+    let type;
+    /* A nested object, an array or a value of several shapes is one document:
+       shown whole, never filtered, never edited as a field. */
+    if (property.oneOf !== undefined ||
+        property.anyOf !== undefined ||
+        property.allOf !== undefined ||
+        isObject(property.properties) ||
+        base.length > 1 ||
+        base.includes('object') ||
+        base.includes('array'))
+        type = 'json';
+    else if (base[0] === 'string' || (!base.length && allowed)) {
+        type =
+            property.format === 'date' ? 'date' : property.format === 'date-time' ? 'datetime' : property.format === 'uuid' ? 'uuid' : 'string';
+    }
+    else if (base[0] === 'integer')
+        type = property.format === 'int64' ? 'bigint' : 'integer';
+    else if (base[0] === 'number')
+        type = 'number';
+    else if (base[0] === 'boolean')
+        type = 'boolean';
+    else
+        type = 'json';
+    const comment = typeof property.description === 'string' && property.description ? property.description : undefined;
+    return {
+        name,
+        type,
+        nullable: !required || types.includes('null') || property.nullable === true,
+        readOnly: property.readOnly === true || type === 'json',
+        ...(allowed ? { allowed } : {}),
+        ...(comment ? { comment } : {}),
+    };
+}
+/* Path-level parameters apply to every operation under the path; an
+   operation's own parameter of the same name and place replaces one. */
+function parameters(resolve, pathItem, operation) {
+    const byKey = new Map();
+    for (const list of [pathItem.parameters, operation.parameters]) {
+        if (!Array.isArray(list))
+            continue;
+        for (const raw of list) {
+            const parameter = resolve(raw);
+            if (!isObject(parameter) || typeof parameter.name !== 'string' || typeof parameter.in !== 'string')
+                continue;
+            const schema = resolve(parameter.schema);
+            byKey.set(`${parameter.in}:${parameter.name}`, {
+                name: parameter.name,
+                in: parameter.in,
+                schema: isObject(schema) ? schema : {},
+                csv: parameter.style === 'form' && parameter.explode === false,
+                fields: parameter['x-mistri-fields'],
+            });
+        }
+    }
+    return [...byKey.values()];
+}
+/** The JSON schema of an operation's first success response, if it has one. */
+function successSchema(resolve, operation) {
+    const responses = isObject(operation.responses) ? operation.responses : {};
+    const code = Object.keys(responses)
+        .filter((status) => /^2\d\d$/.test(status))
+        .sort()[0] ?? (Object.hasOwn(responses, '2XX') ? '2XX' : undefined);
+    if (code === undefined)
+        return undefined;
+    const response = resolve(responses[code]);
+    if (!isObject(response) || !isObject(response.content))
+        return undefined;
+    const media = Object.keys(response.content).find((type) => type === 'application/json' || /^application\/[\w.+-]*\+json$/.test(type));
+    const content = media === undefined ? undefined : response.content[media];
+    return isObject(content) ? content.schema : undefined;
+}
+/* Where a list response keeps its rows: the response itself, or the one
+   array in an object. Two arrays leave no honest answer, so that is a Skip. */
+function listRows(resolve, raw) {
+    const schema = resolve(raw);
+    if (!isObject(schema))
+        throw new Skip("the list's success response has no JSON schema");
+    if (typesOf(schema).includes('array'))
+        return { rows: '', items: schema.items };
+    const properties = isObject(schema.properties) ? schema.properties : {};
+    const arrays = Object.entries(properties).filter(([, value]) => {
+        const property = resolve(value);
+        return isObject(property) && typesOf(property).includes('array');
+    });
+    if (arrays.length !== 1) {
+        throw new Skip(arrays.length
+            ? `the list response holds ${arrays.length} arrays (${arrays.map(([name]) => name).join(', ')}), so which one is the rows is not clear`
+            : 'the list response is neither an array nor an object holding one array of rows');
+    }
+    const [name, value] = arrays[0];
+    return { rows: `/${pointer(name)}`, items: resolve(value).items, body: schema };
+}
+/* A sparse list may omit properties that its full item requires, but must
+   describe exactly the same property types. Imported nullability remains
+   conservative because column() reads the list's required set. */
+function sameRow(resolve, a, b) {
+    if (isObject(a) && isObject(b) && typeof a.$ref === 'string' && a.$ref === b.$ref)
+        return true;
+    const list = resolve(a), item = resolve(b);
+    if (JSON.stringify(list) === JSON.stringify(item))
+        return true;
+    const closed = (raw) => {
+        if (!isObject(raw) || raw.type !== 'object' || raw.additionalProperties !== false || !isObject(raw.properties))
+            return;
+        const metadata = ['x-mistri-primary-key', 'x-mistri-default-fields', 'x-mistri-projection-validation'];
+        if (Object.keys(raw).some((key) => !['type', 'properties', 'required', 'additionalProperties', ...metadata].includes(key)))
+            return;
+        const names = Object.keys(raw.properties);
+        const members = (value) => Array.isArray(value) &&
+            value.every((name) => typeof name === 'string' && names.includes(name)) &&
+            new Set(value).size === value.length;
+        if (!members(raw.required))
+            return;
+        const required = raw.required;
+        if (metadata.some((key) => Object.hasOwn(raw, key))) {
+            const key = raw['x-mistri-primary-key'], fields = raw['x-mistri-default-fields'];
+            if (!members(key) ||
+                !key.length ||
+                !members(fields) ||
+                fields.length !== names.length ||
+                key.length !== required.length ||
+                key.some((name) => !required.includes(name)) ||
+                raw['x-mistri-projection-validation'] !== 'request-codec-requires-exact-selected-fields-plus-complete-key')
+                return;
+        }
+        return { properties: raw.properties, required };
+    };
+    const left = closed(list), right = closed(item);
+    return Boolean(left &&
+        right &&
+        JSON.stringify(left.properties) === JSON.stringify(right.properties) &&
+        left.required.every((name) => right.required.includes(name)));
+}
+function readResource(resolve, path, pathItem, itemPath, itemItem) {
+    const segment = path.slice(path.lastIndexOf('/') + 1);
+    if (!NAME.test(segment))
+        throw new Skip(`"${segment}" is not a usable resource name`);
+    const list = pathItem.get, item = itemItem.get;
+    const listSchema = successSchema(resolve, list), itemSchema = successSchema(resolve, item);
+    if (listSchema === undefined)
+        throw new Skip("the list's success response has no JSON schema");
+    if (itemSchema === undefined)
+        throw new Skip(`GET ${itemPath} has no JSON success response`);
+    const { rows, items, body } = listRows(resolve, listSchema);
+    if (!sameRow(resolve, items, itemSchema))
+        throw new Skip(`GET ${path} and GET ${itemPath} answer different row shapes`);
+    const shape = rowShape(resolve, items);
+    const key = itemPath.slice(path.length + 2, -1);
+    const keyParameter = parameters(resolve, itemItem, item).find((parameter) => parameter.in === 'path' && parameter.name === key);
+    if (keyParameter && (typesOf(keyParameter.schema).includes('object') || isObject(keyParameter.schema.properties))) {
+        throw new Skip(`the item's path parameter {${key}} is a composite object key, which is not supported`);
+    }
+    if (!shape.properties.has(key))
+        throw new Skip(`the item's path parameter {${key}} names no property of the row`);
+    const columns = [...shape.properties]
+        .map(([name, property]) => column(resolve, name, property, shape.required.has(name)))
+        .map((each) => (each.name === key ? { ...each, nullable: false } : each));
+    if (columns.find((each) => each.name === key)?.type === 'json')
+        throw new Skip(`the key "${key}" is a document, not a value`);
+    const query = parameters(resolve, pathItem, list).filter((parameter) => parameter.in === 'query');
+    const byName = new Map(query.map((parameter) => [parameter.name, parameter]));
+    const first = (names) => names.find((name) => byName.has(name));
+    const used = new Set();
+    const [offset, limit, page, cursor] = [first(PAGING.offset), first(PAGING.limit), first(PAGING.page), first(PAGING.cursor)];
+    const next = body && isObject(body.properties) ? PAGING.next.find((name) => Object.hasOwn(body.properties, name)) : undefined;
+    let paging = { kind: 'none' };
+    let guess = 'paging: none found — the list is read as one page';
+    if (cursor && next) {
+        paging = { kind: 'cursor', param: cursor, next: `/${pointer(next)}`, ...(limit ? { limit } : {}) };
+        guess = `paging: cursor — sends "${cursor}", reads the next one at /${pointer(next)}${limit ? `, page size "${limit}"` : ''}`;
+        used.add(cursor);
+        if (limit)
+            used.add(limit);
+    }
+    else if (offset && limit) {
+        paging = { kind: 'offset', offset, limit };
+        guess = `paging: offset — "${offset}" and "${limit}"`;
+        used.add(offset);
+        used.add(limit);
+    }
+    else if (page && limit) {
+        paging = { kind: 'page', page, size: limit };
+        guess = `paging: page — "${page}" and "${limit}"`;
+        used.add(page);
+        used.add(limit);
+    }
+    const search = SEARCH.find((name) => {
+        const schema = byName.get(name)?.schema;
+        return schema !== undefined && (!typesOf(schema).length || typesOf(schema).includes('string'));
+    });
+    if (search)
+        used.add(search);
+    let sort;
+    for (const name of SORT) {
+        const schema = byName.get(name)?.schema;
+        if (!schema)
+            continue;
+        const values = [schema.enum, isObject(schema.items) ? schema.items.enum : undefined].find((list) => Array.isArray(list) && list.length && list.every((value) => typeof value === 'string'));
+        // Without its documented values a sort parameter's syntax is unknown, so it is not offered.
+        if (values) {
+            sort = { param: name, values };
+            used.add(name);
+            break;
+        }
+        const fields = byName.get(name)?.fields;
+        if (Array.isArray(fields) &&
+            fields.length &&
+            fields.every((field) => typeof field === 'string' && /^[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*$/.test(field)) &&
+            new Set(fields).size === fields.length) {
+            const field = `(?:${fields.map((field) => field.replaceAll('.', '\\.')).join('|')})`;
+            if (schema.type === 'string' && schema.pattern === `^-?${field}(?:,-?${field})*$(?![\\s\\S])`) {
+                sort = { param: name, values: fields.flatMap((field) => [field, `-${field}`]) };
+                used.add(name);
+                break;
+            }
+        }
+    }
+    const filters = {};
+    for (const parameter of query) {
+        if (used.has(parameter.name))
+            continue;
+        const target = columns.find((each) => each.name === parameter.name);
+        if (!target || target.type === 'json')
+            continue;
+        const array = typesOf(parameter.schema).includes('array') ||
+            (parameter.csv &&
+                Array.isArray(parameter.schema.anyOf) &&
+                parameter.schema.anyOf.length === 2 &&
+                parameter.schema.anyOf.some((arm) => isObject(arm) && arm.type === 'array') &&
+                parameter.schema.anyOf.some((arm) => isObject(arm) && arm.type === 'string'));
+        filters[target.name] = {
+            param: parameter.name,
+            ops: array ? ['=', 'in'] : ['='],
+            ...(array && parameter.csv ? { serialization: 'csv' } : {}),
+        };
+    }
+    const comment = typeof list.summary === 'string' && list.summary ? list.summary : undefined;
+    return {
+        name: segment,
+        list: path,
+        item: itemPath,
+        key,
+        rows,
+        columns,
+        filters,
+        ...(search ? { search } : {}),
+        ...(sort ? { sort } : {}),
+        paging,
+        guesses: [guess],
+        ...(comment ? { comment } : {}),
+    };
+}
+/* Two keys can hold the same value only when they are the same kind of value. */
+const KEY_KIND = { string: 'text', uuid: 'text', integer: 'number', bigint: 'number' };
+/* A spec has no foreign keys to read. What it has is names: a `carrier_id`
+   beside a `carriers` resource keyed by the same kind of value is guessed to
+   point at it, and said so under `guesses`, as the paging is — a draft to
+   confirm, because a name is a signal and not a promise. */
+function guessReferences(resources) {
+    for (const resource of resources) {
+        for (const column of resource.columns) {
+            const stem = /^(.+)_id$/.exec(column.name)?.[1];
+            if (!stem || column.name === resource.key)
+                continue;
+            const names = [stem, `${stem}s`, `${stem}es`, stem.replace(/y$/, 'ies')];
+            const target = resources.find((each) => names.includes(each.name));
+            const key = target?.columns.find((each) => each.name === target.key);
+            if (!target || !key || !KEY_KIND[key.type] || KEY_KIND[key.type] !== KEY_KIND[column.type])
+                continue;
+            column.references = target.name;
+            resource.guesses.push(`references: ${column.name} → ${target.name}, by its name`);
+        }
+    }
+}
+/**
+ * Reads a parsed OpenAPI 3.0 or 3.1 document. Throws `OpenApiError` only for
+ * a document tablewalk cannot read at all; everything else becomes either a
+ * resource or a skipped operation with its reason.
+ */
+export function readOpenApi(document) {
+    if (!isObject(document))
+        throw new OpenApiError('An OpenAPI document is a JSON object.');
+    if (typeof document.swagger === 'string') {
+        throw new OpenApiError(`This is a Swagger ${document.swagger} document. Only OpenAPI 3.0 and 3.1 are read; convert it first (swagger2openapi, or your framework's exporter).`);
+    }
+    if (typeof document.openapi !== 'string' || !/^3\.[01]\.\d+$/.test(document.openapi)) {
+        throw new OpenApiError(`Only OpenAPI 3.0 and 3.1 are read; this document says ${JSON.stringify(document.openapi ?? null)}.`);
+    }
+    if (!isObject(document.paths))
+        throw new OpenApiError('The document has no "paths" object.');
+    const paths = document.paths;
+    const keys = Object.keys(paths).sort();
+    if (keys.length > LIMITS.paths)
+        throw new OpenApiError(`The document has ${keys.length} paths; at most  are read.`);
+    const resolve = resolver(document);
+    const withGet = (path) => {
+        try {
+            const pathItem = resolve(paths[path]);
+            return isObject(pathItem) && isObject(pathItem.get) ? pathItem : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const resources = [];
+    const skipped = [];
+    const claimed = new Set();
+    const names = new Set();
+    for (const path of keys) {
+        if (path.includes('{'))
+            continue;
+        const pathItem = withGet(path);
+        if (!pathItem)
+            continue;
+        try {
+            const itemPath = keys.find((candidate) => candidate.startsWith(`${path}/{`) && /^\{[^{}/]+\}$/.test(candidate.slice(path.length + 1)) && withGet(candidate));
+            if (!itemPath)
+                throw new Skip(`no item operation (GET ${path}/{id}) reads one row by its key`);
+            claimed.add(itemPath);
+            const resource = readResource(resolve, path, pathItem, itemPath, withGet(itemPath));
+            if (names.has(resource.name))
+                throw new Skip(`another collection is already called "${resource.name}"`);
+            names.add(resource.name);
+            resources.push(resource);
+        }
+        catch (error) {
+            if (!(error instanceof Skip))
+                throw error;
+            skipped.push({ operation: `GET ${path}`, reason: error.message });
+        }
+    }
+    for (const path of keys) {
+        if (!path.includes('{') || claimed.has(path) || !withGet(path))
+            continue;
+        const reason = /\{[^}]+\}\//.test(path)
+            ? 'nested collections (a list under an item) are not read yet'
+            : (path.match(/\{[^}]+\}/g) ?? []).length > 1
+                ? 'an item addressed by more than one path parameter is not read yet'
+                : `no list operation (GET ${path.slice(0, path.lastIndexOf('/'))}) lists these rows`;
+        skipped.push({ operation: `GET ${path}`, reason });
+    }
+    guessReferences(resources);
+    const info = isObject(document.info) ? document.info : {};
+    return {
+        title: typeof info.title === 'string' && info.title ? info.title : 'API',
+        version: typeof info.version === 'string' ? info.version : '',
+        resources: resources.sort((a, b) => a.name.localeCompare(b.name)),
+        skipped: skipped.sort((a, b) => a.operation.localeCompare(b.operation)),
+    };
+}

package/dist/adapters/layoutRefusal.d.ts

@@ -0,0 +1,24 @@
+/**
+ * What a store says when the layout it holds is not the one this build expects.
+ *
+ * Every store attests its layout at open, and an attestation compares a whole
+ * catalog, so on its own it can only say "missing or not the layout this
+ * version expects". The version row is read apart, after the comparison has
+ * failed, to say which way the difference runs: a newer build wrote it
+ * (upgrade to open it) or an older one did (`mistri migrate stores up`,
+ * which `migrate stores status` already reports in the same words). Nothing
+ * is altered either way. A store with no readable version row, or at the
+ * expected version, keeps the store's own generic message.
+ */
+import type { DatabaseSync } from 'node:sqlite';
+import type { PgQuery } from './postgresPool.js';
+/** The message for a store found at `found` when `expected` was wanted; undefined when the version does not explain the refusal. */
+export declare function layoutRefusal(store: string, found: unknown, expected: number): string | undefined;
+/** The one version a meta table's rows hold, or null when there is not exactly one. */
+export declare function versionOfRows(rows: readonly {
+    version?: unknown;
+}[]): number | null;
+/** Best effort, after a refusal: the version a SQLite meta table (in `main`) holds. */
+export declare function sqliteLayoutVersion(db: DatabaseSync, metaTable: string): number | null;
+/** Best effort, after a refusal: the version a PostgreSQL meta table holds (`qualified` is the quoted table name). */
+export declare function postgresLayoutVersion(client: PgQuery, qualified: string): Promise<number | null>;

package/dist/adapters/layoutRefusal.js

@@ -0,0 +1,35 @@
+/** The message for a store found at `found` when `expected` was wanted; undefined when the version does not explain the refusal. */
+export function layoutRefusal(store, found, expected) {
+    const version = typeof found === 'number' || typeof found === 'bigint' || typeof found === 'string' ? Number(found) : NaN;
+    if (!Number.isInteger(version) || version === expected)
+        return undefined;
+    if (version > expected)
+        return (`${store} is at layout version ${version}, newer than the version ${expected} this build expects. ` +
+            'A newer build wrote it: upgrade to open it. It is refused, not altered.');
+    return (`${store} is at layout version ${version}, older than the version ${expected} this build expects. ` +
+        'Stop the server and run `mistri migrate stores up` to bring it forward (`mistri migrate stores status` ' +
+        `says whether a step exists from version ${version}). It is refused, not altered.`);
+}
+/** The one version a meta table's rows hold, or null when there is not exactly one. */
+export function versionOfRows(rows) {
+    const version = rows.length === 1 ? Number(rows[0].version) : NaN;
+    return Number.isInteger(version) ? version : null;
+}
+/** Best effort, after a refusal: the version a SQLite meta table (in `main`) holds. */
+export function sqliteLayoutVersion(db, metaTable) {
+    try {
+        return versionOfRows(db.prepare(`SELECT version FROM main."${metaTable}"`).all());
+    }
+    catch {
+        return null;
+    }
+}
+/** Best effort, after a refusal: the version a PostgreSQL meta table holds (`qualified` is the quoted table name). */
+export async function postgresLayoutVersion(client, qualified) {
+    try {
+        return versionOfRows((await client.query(`SELECT version FROM ${qualified}`)).rows);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/adapters/net/networkPolicy.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Where a socket this process opens on the operator's behalf may go.
+ *
+ * Every outbound connection a config file can point somewhere — an API
+ * (egress.ts), a cache, a search service — resolves its host through
+ * `checkedLookup`, so the address checked is the address connected: a name
+ * that resolves somewhere else a moment later (DNS rebinding) changes
+ * nothing. One set of ranges, one rule, whichever protocol rides on top.
+ *
+ * Private networks are reachable by default, because internal services are
+ * the common case and these connections only ever come from the operator's
+ * config, never from a browser. Link-local addresses, where cloud metadata
+ * services answer, are not, unless the connection says so: they hand out
+ * credentials to whoever asks.
+ */
+import { type LookupAddress } from 'node:dns';
+type LookupCallback = (error: NodeJS.ErrnoException | null, addresses: LookupAddress[]) => void;
+/** `node:dns` lookup with `{ all: true }`, injectable so a test can resolve a name to any address it likes. */
+export type Resolver = (hostname: string, options: {
+    all: true;
+}, callback: LookupCallback) => void;
+export interface NetworkPolicy {
+    /** Loopback and private ranges (RFC 1918, CGNAT, ULA). Reachable unless a connection opts out. */
+    allowPrivate: boolean;
+    /** Link-local ranges, where cloud metadata services answer. Unreachable unless a connection opts in. */
+    allowLinkLocal: boolean;
+    resolver?: Resolver;
+}
+/**
+ * A host written as an address is never looked up, so it is checked before
+ * any socket opens: the address it names when that address is refused,
+ * undefined when it is a name or a reachable address.
+ */
+export declare function refusedLiteral(hostname: string, policy: NetworkPolicy): string | undefined;
+/**
+ * The lookup a socket uses: resolve, keep only reachable addresses, and hand
+ * those back, so the address checked is the address connected. Node asks for
+ * one address or for all (happy eyeballs); both are answered. `refuse` makes
+ * the caller's own error for a name that resolves only to refused addresses.
+ */
+export declare function checkedLookup(policy: NetworkPolicy, refuse: (host: string, addresses: string[]) => Error): (hostname: string, options: {
+    all?: boolean;
+}, callback: (...args: unknown[]) => void) => void;
+export {};