@segmentstream/ontology 0.0.0-stage → 0.92.1

package/dist/query.js

@@ -0,0 +1,615 @@
+import { Schema, SchemaTransformation } from "effect";
+import { expectedOneOf, wireStruct } from "./wire.js";
+import { isValueMatched } from "./manifest.js";
+import { BlobValue } from "./blob.js";
+/**
+ * The query language of `find` and of the HTTP API's list and query endpoints.
+ *
+ * ```json
+ * {
+ *   "where": {
+ *     "status": { "in": ["new", "contacted"] },
+ *     "owner": { "email": { "eq": "ada@example.com" } },
+ *     "tags": { "some": { "name": { "eq": "priority" } } },
+ *     "or": [{ "fitScore": { "gte": 80 } }, { "source": "pilot_request" }]
+ *   },
+ *   "orderBy": [{ "field": "created_at", "direction": "desc" }],
+ *   "include": ["owner"],
+ *   "limit": 50
+ * }
+ * ```
+ *
+ * {@link Query} checks the structure for any entity; {@link entityQuerySchema} builds the precise
+ * schema of one entity from the manifest, with its fields, their operators and its relationships.
+ * The runtime validates every query with the precise schema. `include` also takes the object form
+ * `{ "owner": true }`, which a list of names decodes into.
+ */
+export const DEFAULT_QUERY_LIMIT = 50;
+export const MAX_QUERY_LIMIT = 200;
+/** The most values an `in` filter takes. */
+export const MAX_IN_VALUES = 1000;
+/** Filter operators. A field's type decides which apply; see {@link entityQuerySchema}. */
+export const FILTER_OPERATORS = [
+    "eq",
+    "ne",
+    "in",
+    "isNull",
+    "contains",
+    "startsWith",
+    "gt",
+    "gte",
+    "lt",
+    "lte",
+    "between",
+];
+/** Filter operators of a list field: it holds the value, or any of the values. */
+export const LIST_FILTER_OPERATORS = ["has", "hasAny"];
+/** Combinators of a `where`. They take the place of field names. */
+export const WHERE_COMBINATORS = ["and", "or", "not"];
+/** Quantifiers of a filter on a to-many relationship. */
+export const MANY_QUANTIFIERS = ["some", "none", "every"];
+export const SortDirection = Schema.Literals(["asc", "desc"]);
+export const OrderBy = Schema.Struct({
+    field: Schema.String,
+    direction: Schema.optionalKey(SortDirection),
+});
+const Limit = Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: MAX_QUERY_LIMIT })).annotate({
+    description: `How many records to return, ${DEFAULT_QUERY_LIMIT} by default.`,
+});
+const After = Schema.String.annotate({
+    description: "The nextCursor of the previous page. It is only valid for the same where and orderBy.",
+});
+/** Whether an `include` is the list form, `["owner", "tags"]`. */
+export function isIncludeList(include) {
+    return Array.isArray(include);
+}
+/** The relationship names an `include` lists, in either form. */
+export function includedRelationships(include) {
+    if (include === undefined) {
+        return [];
+    }
+    return isIncludeList(include) ? [...new Set(include)] : Object.keys(include);
+}
+/** `["owner", "tags"]` decoded as `{ owner: true, tags: true }`; duplicate names are harmless. */
+function includeList(names, included) {
+    return Schema.Array(names).pipe(Schema.decodeTo(included, SchemaTransformation.transform({
+        decode: (list) => Object.fromEntries(list.map((name) => [name, true])),
+        encode: (relationships) => Object.keys(relationships),
+    })));
+}
+const AnyIncluded = Schema.Record(Schema.String, Schema.Literal(true));
+const SelectedFields = Schema.Array(Schema.String).check(Schema.isMaxLength(200));
+/** A query on any entity. The runtime checks the fields against the entity. */
+export const Query = Schema.Struct({
+    where: Schema.optionalKey(Schema.Record(Schema.String, Schema.Json)),
+    orderBy: Schema.optionalKey(Schema.Array(OrderBy)),
+    select: Schema.optionalKey(SelectedFields),
+    include: Schema.optionalKey(
+    // The list member decodes into the object; the union's static type cannot say so.
+    Schema.Union([AnyIncluded, includeList(Schema.String, AnyIncluded)])),
+    after: Schema.optionalKey(After),
+    limit: Schema.optionalKey(Limit),
+}).annotate({ identifier: "Query" });
+/** A page of records of any entity. */
+export const QueryResult = Schema.Struct({
+    items: Schema.Array(Schema.Record(Schema.String, Schema.Json)),
+    nextCursor: Schema.NullOr(Schema.String),
+    projected: Schema.optionalKey(Schema.Literal(true)),
+}).annotate({ identifier: "QueryResult" });
+/** A page of records described by `record`. */
+export function queryResultSchema(record) {
+    return Schema.Struct({ items: Schema.Array(record), nextCursor: Schema.NullOr(Schema.String) });
+}
+/** Full pages keep their complete record contract; projections carry an explicit marker. */
+export function projectedQueryResultSchema(record, projection, wire = false) {
+    const full = Schema.Struct({
+        items: Schema.Array(record),
+        nextCursor: Schema.NullOr(Schema.String),
+        projected: Schema.optionalKey(Schema.Never),
+    });
+    const selected = Schema.Struct({
+        items: Schema.Array(projection),
+        nextCursor: Schema.NullOr(Schema.String),
+        projected: Schema.Literal(true),
+    });
+    return Schema.Union(wire
+        ? [
+            full.pipe(Schema.encodeKeys({ nextCursor: "next_cursor" })),
+            selected.pipe(Schema.encodeKeys({ nextCursor: "next_cursor" })),
+        ]
+        : [full, selected]);
+}
+const SYSTEM_FIELDS = [
+    { name: "id", storage: "uuid", nullable: false },
+    { name: "created_at", storage: "timestamp", nullable: false },
+    { name: "updated_at", storage: "timestamp", nullable: false },
+    { name: "created_by", storage: "uuid", nullable: true },
+    { name: "updated_by", storage: "uuid", nullable: true },
+];
+/**
+ * The fields of an entity's records, in record order. A value-matched relationship has no
+ * `<relationship>_id`: its reference is the property named in `on`.
+ */
+export function queryFields(entity) {
+    const properties = entity.properties.map((property) => ({
+        name: property.name,
+        storage: property.type,
+        nullable: entity.source !== undefined || property.optional,
+        ...(property.options !== undefined
+            ? { options: property.options.map((option) => option.value) }
+            : {}),
+    }));
+    const keys = entity.relationships
+        .filter((relationship) => relationship.cardinality === "one" && !isValueMatched(relationship))
+        .map((relationship) => ({
+        name: `${relationship.name}_id`,
+        storage: "uuid",
+        nullable: relationship.optional === true,
+    }));
+    return entity.source !== undefined
+        ? [{ name: "id", storage: "text", nullable: false }, ...properties]
+        : [...SYSTEM_FIELDS, ...properties, ...keys];
+}
+/** The relationships of an entity, declared ones first, then the inverses landing on it. */
+export function queryLinks(manifest, entityName, warehouseRecords = false) {
+    const links = [];
+    for (const owner of manifest.entities) {
+        if (owner.source !== undefined && !warehouseRecords) {
+            continue;
+        }
+        for (const relationship of owner.relationships) {
+            if (!warehouseRecords &&
+                findEntityManifest(manifest, relationship.to)?.source !== undefined) {
+                continue;
+            }
+            const common = {
+                declaredBy: owner.name,
+                relationship: relationship.name,
+                declared: relationship.cardinality,
+            };
+            if (owner.name === entityName) {
+                links.push({
+                    ...common,
+                    name: relationship.name,
+                    target: relationship.to,
+                    cardinality: relationship.cardinality,
+                    inverse: false,
+                });
+            }
+            if (relationship.to === entityName) {
+                links.push({
+                    ...common,
+                    name: relationship.inverse,
+                    target: owner.name,
+                    cardinality: "many",
+                    inverse: true,
+                });
+            }
+        }
+    }
+    return [...links.filter((link) => !link.inverse), ...links.filter((link) => link.inverse)];
+}
+export function findEntityManifest(manifest, entityName) {
+    return manifest.entities.find((candidate) => candidate.name === entityName);
+}
+function requireEntity(manifest, entityName) {
+    const entity = findEntityManifest(manifest, entityName);
+    if (entity === undefined) {
+        throw new Error(`"${entityName}" is not an entity of this ontology.`);
+    }
+    return entity;
+}
+const DATE = /^(\d{4})-(\d{2})-(\d{2})$/;
+const TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/;
+const UUID = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+/** `YYYY-MM-DD` naming a day that exists. */
+export function isCalendarDate(value) {
+    const match = DATE.exec(value);
+    if (match === null) {
+        return false;
+    }
+    const [year, month, day] = [Number(match[1]), Number(match[2]), Number(match[3])];
+    const date = new Date(Date.UTC(year, month - 1, day));
+    return (date.getUTCFullYear() === year && date.getUTCMonth() === month - 1 && date.getUTCDate() === day);
+}
+/** An ISO 8601 instant with a time zone, on a day that exists. PostgreSQL keeps microseconds. */
+export function isInstant(value) {
+    return TIMESTAMP.test(value) && isCalendarDate(value.slice(0, 10)) && !isNaN(Date.parse(value));
+}
+export function isUuid(value) {
+    return UUID.test(value);
+}
+const DateValue = Schema.String.check(Schema.makeFilter((value) => isCalendarDate(value) || "Expected a date as YYYY-MM-DD")).annotate({ format: "date" });
+const TimestampValue = Schema.String.check(Schema.makeFilter((value) => isInstant(value) || "Expected an ISO 8601 timestamp with a time zone")).annotate({ format: "date-time" });
+const UuidValue = Schema.String.check(Schema.makeFilter((value) => isUuid(value) || "Expected a UUID")).annotate({ format: "uuid" });
+/** Any JSON value but `null`, which `isNull` expresses. */
+const JsonValue = Schema.Json.check(Schema.makeFilter((value) => value !== null || "Use isNull to match empty values"));
+const TEXT_STORAGE = ["text", "email", "url"];
+const ORDERED_STORAGE = ["integer", "number", "date", "timestamp"];
+/** The schema of one value of a field, as filters and cursors carry it. */
+export function fieldValueSchema(field) {
+    switch (field.storage) {
+        case "text":
+        case "email":
+        case "url":
+            return Schema.String;
+        case "integer":
+            return Schema.Int;
+        case "number":
+            return Schema.Finite;
+        case "boolean":
+            return Schema.Boolean;
+        case "date":
+            return DateValue;
+        case "timestamp":
+            return TimestampValue;
+        case "select":
+            return Schema.Literals(field.options ?? []);
+        case "json":
+            return JsonValue;
+        case "uuid":
+        case "blob":
+            return UuidValue;
+        case "list":
+            return Schema.String;
+    }
+}
+/** Fields a query can sort on: every field but `json`, `blob` and `list` properties. */
+export function isOrderable(field) {
+    return field.storage !== "json" && field.storage !== "blob" && field.storage !== "list";
+}
+const FILTER_IDENTIFIERS = {
+    text: "TextFilter",
+    email: "TextFilter",
+    url: "TextFilter",
+    integer: "IntegerFilter",
+    number: "NumberFilter",
+    boolean: "BooleanFilter",
+    date: "DateFilter",
+    timestamp: "TimestampFilter",
+    json: "JsonFilter",
+    uuid: "IdFilter",
+    blob: "IdFilter",
+    list: "ListFilter",
+};
+const FILTER_DESCRIPTIONS = {
+    TextFilter: "contains and startsWith ignore case.",
+    DateFilter: "Dates are YYYY-MM-DD; between includes both ends.",
+    TimestampFilter: "Timestamps are ISO 8601 with a time zone; between includes both ends.",
+    JsonFilter: "eq compares JSON values; wrap an object whose keys are operator names in { eq }.",
+};
+/** Filters shared by every field of a type; `select` filters are per property. */
+const sharedFilters = new Map();
+function isOperatorObject(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        Object.keys(value).every((key) => [...FILTER_OPERATORS, "is_null", "starts_with"].includes(key)));
+}
+/** The bare-value form of `eq`. For JSON, an object of operators is a filter, never a value. */
+function shorthandSchema(field, value) {
+    if (field.storage !== "json") {
+        return value;
+    }
+    return JsonValue.check(Schema.makeFilter((candidate) => !isOperatorObject(candidate) || "Expected a filter"));
+}
+/** `has` and `hasAny`, the only conditions on a list: it has no empty value and no order. */
+function listFilterSchema(field, identifier, wire) {
+    const value = fieldValueSchema(field);
+    const operators = {
+        has: Schema.optionalKey(value),
+        hasAny: Schema.optionalKey(Schema.Array(value).check(Schema.isMaxLength(MAX_IN_VALUES))),
+    };
+    const filter = wire
+        ? wireStruct(operators, { hasAny: "has_any" }, "Unknown operator")
+        : closedStruct(operators, "Unknown operator");
+    return filter.annotate({
+        identifier,
+        description: `Conditions on the list, all of which must hold: has matches a list that holds the value, ` +
+            `${wire ? "has_any" : "hasAny"} one that holds any of the values.`,
+    });
+}
+function fieldFilterSchema(field, identifier, wire) {
+    if (field.storage === "list") {
+        return listFilterSchema(field, identifier, wire);
+    }
+    const value = fieldValueSchema(field);
+    const operators = {
+        eq: Schema.optionalKey(value),
+        ne: Schema.optionalKey(value),
+        in: Schema.optionalKey(Schema.Array(value).check(Schema.isMaxLength(MAX_IN_VALUES))),
+        isNull: Schema.optionalKey(Schema.Boolean),
+    };
+    if (TEXT_STORAGE.includes(field.storage)) {
+        operators.contains = Schema.optionalKey(Schema.String);
+        operators.startsWith = Schema.optionalKey(Schema.String);
+    }
+    if (ORDERED_STORAGE.includes(field.storage)) {
+        for (const operator of ["gt", "gte", "lt", "lte"]) {
+            operators[operator] = Schema.optionalKey(value);
+        }
+        operators.between = Schema.optionalKey(Schema.Tuple([value, value]));
+    }
+    const filter = wire
+        ? wireStruct(operators, { isNull: "is_null", startsWith: "starts_with" }, "Unknown operator")
+        : closedStruct(operators, "Unknown operator");
+    const note = wire
+        ? FILTER_DESCRIPTIONS[identifier]?.replaceAll("startsWith", "starts_with")
+        : FILTER_DESCRIPTIONS[identifier];
+    return Schema.Union([filter, shorthandSchema(field, value), Schema.Null]).annotate({
+        identifier,
+        description: "Conditions on the field, all of which must hold. A bare value means eq, null means " +
+            `${wire ? "is_null" : "isNull"}: true, and ne also matches empty values.${note === undefined ? "" : ` ${note}`}`,
+    });
+}
+function filterFor(entity, field, schemas, wire) {
+    if (field.storage === "select") {
+        const identifier = `${pascalCase(entity.name)}${pascalCase(field.name)}Filter`;
+        const key = `filter:${entity.name}:${field.name}`;
+        const existing = schemas.get(key) ?? fieldFilterSchema(field, identifier, wire);
+        schemas.set(key, existing);
+        return existing;
+    }
+    const identifier = FILTER_IDENTIFIERS[field.storage];
+    const existing = sharedFilters.get(`${identifier}:${wire}`) ?? fieldFilterSchema(field, identifier, wire);
+    sharedFilters.set(`${identifier}:${wire}`, existing);
+    return existing;
+}
+const fieldFilterGuards = new WeakMap();
+/**
+ * Whether a value is a filter the field takes, as a query's `where` would accept it: operators by
+ * their query names, each with an operand of the field's type, or a bare value or `null`.
+ */
+export function isFieldFilterOf(field, value) {
+    let guard = fieldFilterGuards.get(field);
+    if (guard === undefined) {
+        guard = Schema.is(fieldFilterSchema(field, "FieldFilter", false));
+        fieldFilterGuards.set(field, guard);
+    }
+    return guard(value);
+}
+/** `pilot_request` → `PilotRequest`, `fitScore` → `FitScore`. */
+function pascalCase(name) {
+    return name
+        .split("_")
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+        .join("");
+}
+/**
+ * The `where` of an entity. With `links`, it includes the entity's relationships, whose targets are
+ * filtered by their own fields only: relationship paths are one level deep.
+ */
+function whereSchema(manifest, entity, links, schemas, wire) {
+    const identifier = `${pascalCase(entity.name)}${links ? "Where" : "FieldsWhere"}`;
+    const key = `where:${entity.name}:${links}`;
+    const existing = schemas.get(key);
+    if (existing !== undefined) {
+        return existing;
+    }
+    // The identifier sits on the suspension, so that JSON Schema emits the body once and refers to it.
+    // The body is built below; the suspension reads it only when the schema is used.
+    const self = Schema.suspend(() => body).annotate({
+        identifier,
+        description: links
+            ? `Conditions on ${entity.plural}, all of which must hold.`
+            : `Conditions on the fields of ${entity.plural}, all of which must hold.`,
+    });
+    const fields = {};
+    schemas.set(key, self);
+    for (const field of queryFields(entity)) {
+        fields[field.name] = Schema.optionalKey(filterFor(entity, field, schemas, wire));
+    }
+    if (links) {
+        for (const link of queryLinks(manifest, entity.name)) {
+            const target = whereSchema(manifest, requireEntity(manifest, link.target), false, schemas, wire);
+            fields[link.name] = Schema.optionalKey(link.cardinality === "one" ? target : manyFilterSchema(link, target));
+        }
+    }
+    fields.and = Schema.optionalKey(Schema.Array(self));
+    fields.or = Schema.optionalKey(Schema.Array(self));
+    fields.not = Schema.optionalKey(self);
+    const body = closedStruct(fields, "Unknown field");
+    return self;
+}
+function manyFilterSchema(link, target) {
+    return closedStruct({
+        some: Schema.optionalKey(target),
+        none: Schema.optionalKey(target),
+        every: Schema.optionalKey(target),
+    }, "Unknown quantifier").annotate({
+        description: `Whether some, none or every one of the related ${link.target} records match.`,
+    });
+}
+const wireQuerySchemas = new WeakMap();
+const querySchemas = new WeakMap();
+// A related entity's field filters are identical wherever that entity is reached.
+// Reuse immutable schema definitions within one manifest and spelling; callers'
+// query values, permissions and authorization decisions never enter this cache.
+const wireWhereSchemas = new WeakMap();
+const whereSchemas = new WeakMap();
+/**
+ * The precise query schemas of one entity: its fields with the operators of their types, its
+ * relationships (declared and inverse), the fields it can sort on and the relationships it can
+ * include. Every struct is closed: an unknown field, operator or key is an issue whatever the parse
+ * options, never a silently ignored filter.
+ */
+export function entityQuerySchemas(manifest, entityName, wire = false, warehouseRecords = false) {
+    const cache = wire ? wireQuerySchemas : querySchemas;
+    const cacheKey = `${entityName}:${warehouseRecords}`;
+    const cached = cache.get(manifest)?.get(cacheKey);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const entity = requireEntity(manifest, entityName);
+    const pascal = pascalCase(entityName);
+    const fields = queryFields(entity).filter(isOrderable);
+    const relationships = queryLinks(manifest, entityName, warehouseRecords).map((link) => link.name);
+    const definitions = wire ? wireWhereSchemas : whereSchemas;
+    let shared = definitions.get(manifest);
+    if (shared === undefined) {
+        shared = new Map();
+        definitions.set(manifest, shared);
+    }
+    const where = whereSchema(manifest, entity, true, shared, wire);
+    const orderBy = Schema.Array(closedStruct({
+        field: Schema.Literals(fields.map((field) => field.name)),
+        direction: Schema.optionalKey(SortDirection),
+    }, "Unknown key")).annotate({ description: "Sort keys in order; the id breaks ties. Ascending by default." });
+    const included = includeSchema(relationships);
+    const select = Schema.Array(Schema.Literals(queryFields(entity).map((field) => field.name)))
+        .check(Schema.isMaxLength(200))
+        .annotate({
+        description: "Base-record fields to return; id is always included. Omit for complete records. Includes are unchanged.",
+    });
+    const queryMembers = {
+        where: Schema.optionalKey(where),
+        orderBy: Schema.optionalKey(orderBy),
+        select: Schema.optionalKey(select),
+        include: Schema.optionalKey(included),
+        after: Schema.optionalKey(After),
+        limit: Schema.optionalKey(Limit),
+    };
+    const query = (wire
+        ? wireStruct(queryMembers, { orderBy: "order_by" })
+        : closedStruct(queryMembers, "Unknown key")).annotate({ identifier: `${pascal}Query`, description: `A query on ${entity.plural}.` });
+    // The structs are assembled from the manifest, so their static types are too wide to name; they
+    // accept exactly the Query shape and decode it unchanged.
+    const schemas = {
+        where,
+        orderBy,
+        select,
+        include: included,
+        limit: Limit,
+        after: After,
+        query,
+    };
+    const byEntity = cache.get(manifest) ?? new Map();
+    byEntity.set(cacheKey, schemas);
+    cache.set(manifest, byEntity);
+    return schemas;
+}
+/**
+ * The relationships a query includes: a list of names, `["owner", "tags"]`, or the object form
+ * `{ owner: true, tags: true }` that the list decodes into. Both reject an unknown relationship and
+ * name the ones there are.
+ */
+function includeSchema(relationships) {
+    const fields = {};
+    for (const name of relationships) {
+        fields[name] = Schema.optionalKey(Schema.Literal(true));
+    }
+    const included = closedStruct(fields, "Unknown relationship");
+    const name = Schema.String.check(Schema.makeFilter((candidate) => relationships.includes(candidate) ||
+        expectedOneOf(`Unknown relationship "${candidate}"`, relationships), { toJsonSchema: () => (relationships.length > 0 ? { enum: relationships } : { not: {} }) }));
+    const example = relationships[0];
+    const forms = example === undefined
+        ? "a list of relationship names; there are none"
+        : `a list of relationship names, as in ["${example}"], or an object, as in {"${example}": true}`;
+    return Schema.Union([included, includeList(name, included)]).annotate({
+        description: `Related records to add to each record: ${forms}.`,
+        message: `Expected ${forms}`,
+    });
+}
+/** The query schema of one entity; see {@link entityQuerySchemas}. */
+export function entityQuerySchema(manifest, entityName, warehouseRecords = false) {
+    return entityQuerySchemas(manifest, entityName, false, warehouseRecords).query;
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * A struct that rejects keys it does not declare, whatever the parse options: decoding ignores
+ * unknown keys by default, which would turn a misspelled filter into no filter. JSON Schema says the
+ * same with a `patternProperties` entry that matches every undeclared key.
+ */
+function closedStruct(fields, unknownKey) {
+    const keys = Object.keys(fields);
+    const declared = keys.map(escapeRegExp).join("|");
+    const undeclared = Schema.String.check(Schema.isPattern(new RegExp(`^(?!(?:${declared})$)`)));
+    return Schema.StructWithRest(Schema.Struct(fields), [
+        Schema.Record(undeclared, Schema.Never.annotate({ message: expectedOneOf(unknownKey, keys) })),
+    ]);
+}
+function recordValueSchema(field) {
+    const value = (() => {
+        switch (field.storage) {
+            case "integer":
+                return Schema.Int;
+            case "number":
+                return Schema.Finite;
+            case "boolean":
+                return Schema.Boolean;
+            case "select":
+                return Schema.Literals(field.options ?? []);
+            case "json":
+                return Schema.Json;
+            case "blob":
+                return BlobValue;
+            case "list":
+                return Schema.Array(Schema.String);
+            default:
+                return Schema.String;
+        }
+    })();
+    return field.nullable ? Schema.NullOr(value) : value;
+}
+/**
+ * The record of an entity as the runtime returns it: system fields, properties (`null` when empty;
+ * dates as `YYYY-MM-DD`, timestamps as ISO 8601 in UTC) and a `<relationship>_id` per `rel.one`. It
+ * checks the shape of stored values, not the refinements of the definition (`maxLength`, `min`,
+ * patterns), so that tightening a refinement never makes existing records unreadable.
+ */
+export function entityRecordSchema(entity) {
+    // Assembled from the manifest, the struct's static type is too wide to name.
+    return Schema.Struct(recordFields(entity)).annotate({
+        identifier: pascalCase(entity.name),
+        description: entity.description,
+    });
+}
+function recordFields(entity) {
+    const fields = {};
+    for (const field of queryFields(entity)) {
+        fields[field.name] = recordValueSchema(field);
+    }
+    return fields;
+}
+/** A page of an entity's records, with the relationships a query may include. */
+export function entityQueryResultSchema(manifest, entityName, wire = false, warehouseRecords = false) {
+    const entity = requireEntity(manifest, entityName);
+    const fields = recordFields(entity);
+    const projected = Object.fromEntries(Object.entries(fields).map(([name, value]) => [
+        name,
+        name === "id" ? value : Schema.optionalKey(value),
+    ]));
+    for (const link of queryLinks(manifest, entityName, warehouseRecords)) {
+        const target = entityRecordSchema(requireEntity(manifest, link.target));
+        fields[link.name] = Schema.optionalKey(link.cardinality === "one" ? Schema.NullOr(target) : Schema.Array(target));
+        projected[link.name] = fields[link.name];
+    }
+    const record = Schema.Struct(fields);
+    return projectedQueryResultSchema(record, Schema.Struct(projected), wire);
+}
+/** A JSON Schema whose root is the schema itself, not a `$ref`, as MCP tool inputs need it. */
+function jsonSchema(schema) {
+    const document = Schema.toJsonSchemaDocument(schema, { onExcessProperty: "error" });
+    const definitions = document.definitions;
+    const reference = document.schema.$ref;
+    const referenced = typeof reference === "string" ? definitions[reference.replace("#/$defs/", "")] : undefined;
+    const root = referenced ?? document.schema;
+    return Object.keys(definitions).length === 0
+        ? root
+        : { ...root, $defs: definitions };
+}
+/** The JSON Schema (draft 2020-12) of an entity's queries, for MCP tools, OpenAPI and the console. */
+export function queryJsonSchema(manifest, entityName, warehouseRecords = false) {
+    return jsonSchema(entityQuerySchemas(manifest, entityName, true, warehouseRecords).query);
+}
+/** The JSON Schema (draft 2020-12) of a page of an entity's records. */
+export function queryResultJsonSchema(manifest, entityName) {
+    // MCP requires an object at the root, including when its record variants form a union.
+    return {
+        type: "object",
+        required: ["items", "next_cursor"],
+        ...jsonSchema(entityQueryResultSchema(manifest, entityName, true)),
+    };
+}