@segmentstream/ontology 0.0.0-stage → 0.92.1

package/dist/service/schemas.js

@@ -0,0 +1,639 @@
+import { BlobValue } from "../blob.js";
+import { isWarehouseRecordId } from "./warehouse-query.js";
+import { Schema, SchemaTransformation } from "effect";
+import { wireStruct } from "../wire.js";
+import { ScopedMetricQueryReason } from "./errors.js";
+import { BatchErrorDetails } from "../errors.js";
+import { METRIC_QUERY_FILTER_OPERATORS, ENTITY_METRIC_QUERY_FILTER_OPERATORS, filterValuesIssue, MAXIMUM_FILTER_VALUES, } from "../metric-filters.js";
+import { acceptingEarlierMetricQueryNames } from "../legacy.js";
+import { isValueMatched, OntologyManifestWire, ScopeManifest } from "../manifest.js";
+import { entityQuerySchemas, projectedQueryResultSchema, queryLinks, } from "../query.js";
+import { ValidationIssue as RuntimeValidationIssue } from "../runtime/errors.js";
+import { Edit, HistoryEntry as RuntimeHistoryEntry } from "../runtime/history.js";
+export { METRIC_QUERY_FILTER_OPERATORS, METRIC_QUERY_PERIOD_UNITS, METRIC_QUERY_PERIODS, ENTITY_METRIC_QUERY_FILTER_OPERATORS, } from "../metric-filters.js";
+/** `lead` → `Lead`, `pilot_request` → `PilotRequest`: component names in the OpenAPI document. */
+function pascalCase(name) {
+    return name
+        .split("_")
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join("");
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * A struct that rejects keys it does not declare. Decoding ignores unknown keys by default, which
+ * would let a misspelled option pass silently. The JSON Schema says the same through a
+ * `patternProperties` entry that matches every undeclared key.
+ */
+function closedStruct(fields, unknownKey) {
+    const declared = Object.keys(fields).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: unknownKey })),
+    ]);
+}
+const Id = Schema.String.annotate({ format: "uuid" });
+const Timestamp = Schema.String.annotate({ format: "date-time" });
+/** A record id in a path: a UUID. */
+export const IdParam = Schema.String.check(Schema.isUUID()).annotate({
+    description: "The record's id.",
+});
+/** An observation's opaque source-key identity, returned by its find tool. */
+export const WarehouseIdParam = Schema.String.check(Schema.makeFilter(isWarehouseRecordId, {
+    toJsonSchema: () => ({ pattern: "^wr1_[A-Za-z0-9_-]{1,12000}$" }),
+})).annotate({
+    description: "The opaque warehouse record id returned by find.",
+});
+/**
+ * The value schema of a property in records. It keeps the type and documentation but not the checks:
+ * a stored value that predates a tightened check still reads. Filters come from `src/query.ts`, and
+ * action inputs keep the full property schema.
+ */
+function propertyValue(definition) {
+    const documentation = {
+        ...(definition.label !== undefined ? { title: definition.label } : {}),
+        ...(definition.description !== undefined ? { description: definition.description } : {}),
+    };
+    switch (definition.type) {
+        case "text":
+            return Schema.String.annotate(documentation);
+        case "email":
+            return Schema.String.annotate({ ...documentation, format: "email" });
+        case "url":
+            return Schema.String.annotate({ ...documentation, format: "uri" });
+        case "integer":
+            return Schema.Int.annotate(documentation);
+        case "number":
+            return Schema.Finite.annotate(documentation);
+        case "boolean":
+            return Schema.Boolean.annotate(documentation);
+        case "date":
+            return Schema.String.annotate({ ...documentation, format: "date" });
+        case "timestamp":
+            return Schema.String.annotate({ ...documentation, format: "date-time" });
+        case "select": {
+            const options = (definition.options ?? []).map((option) => Schema.Literal(option.value).annotate({
+                title: option.label,
+                ...(option.description !== undefined ? { description: option.description } : {}),
+            }));
+            return Schema.Union(options).annotate(documentation);
+        }
+        case "json":
+            return Schema.Json.annotate(documentation);
+        case "blob":
+            return BlobValue.annotate(documentation);
+        case "list":
+            return Schema.Array(Schema.String).annotate(documentation);
+    }
+}
+function recordFields(entity) {
+    if (entity.entity.definition.source !== undefined) {
+        return {
+            id: Schema.String,
+            ...Object.fromEntries(entity.properties.map(({ name, definition }) => [
+                name,
+                Schema.NullOr(propertyValue(definition)),
+            ])),
+        };
+    }
+    const fields = {
+        id: Id.annotate({ description: "The record's id." }),
+        created_at: Timestamp,
+        updated_at: Timestamp,
+        created_by: Schema.NullOr(Id).annotate({
+            description: "The user who created the record; null when the platform wrote it.",
+        }),
+        updated_by: Schema.NullOr(Id).annotate({
+            description: "The user who last updated the record; null when the platform wrote it.",
+        }),
+    };
+    for (const { name, definition } of entity.properties) {
+        const value = propertyValue(definition);
+        fields[name] = definition.optional ? Schema.NullOr(value) : value;
+    }
+    for (const { name, relationship } of entity.relationships) {
+        // A value-matched relationship's reference is the property its `on` names.
+        if (relationship.cardinality === "one" && !isValueMatched(relationship)) {
+            const key = Id.annotate({ description: relationship.description });
+            fields[`${name}_id`] = relationship.optional ? Schema.NullOr(key) : key;
+        }
+    }
+    return fields;
+}
+function splitList(value) {
+    return value
+        .split(",")
+        .map((part) => part.trim())
+        .filter((part) => part.length > 0);
+}
+/** `created_at:desc,email` as URL parameter, `[{ field, direction }]` once decoded. */
+function orderByParam(orderBy) {
+    // URL parameters are documented by their encoded side, so the description goes on the string.
+    const encoded = Schema.String.annotate({
+        description: "Comma-separated fields, each optionally followed by :asc or :desc, as in created_at:desc,email.",
+    });
+    return encoded.pipe(Schema.decodeTo(orderBy, SchemaTransformation.transform({
+        decode: (value) => splitList(value).map((part) => {
+            const [field = "", direction] = part.split(":");
+            return { field, direction: direction ?? "asc" };
+        }),
+        encode: (orders) => orders.map(({ field, direction }) => `${field}:${direction ?? "asc"}`).join(","),
+    })));
+}
+/** `owner,tags` as URL parameter, `{ owner: true, tags: true }` once decoded. */
+function includeParam(include) {
+    const encoded = Schema.String.annotate({
+        description: "Comma-separated relationships to include in each record, as in owner,tags.",
+    });
+    return encoded.pipe(Schema.decodeTo(include, SchemaTransformation.transform({
+        decode: (value) => Object.fromEntries(splitList(value).map((name) => [name, true])),
+        encode: (relationships) => Object.keys(relationships).join(","),
+    })));
+}
+/** Comma-separated selected base fields, validated against the entity. */
+function selectedFieldsParam(select) {
+    return Schema.String.pipe(Schema.decodeTo(select, SchemaTransformation.transform({
+        decode: splitList,
+        encode: (fields) => fields.join(","),
+    })));
+}
+/** A filter as a JSON-encoded URL parameter. */
+function whereParam(where) {
+    const encoded = Schema.String.annotate({
+        description: 'A JSON-encoded filter, as in {"status":{"eq":"new"}}.',
+        contentMediaType: "application/json",
+    });
+    return encoded.pipe(Schema.decodeTo(where, SchemaTransformation.fromJsonString()));
+}
+/** A record of every entity, built once so that the document reuses them. */
+function recordSchemas(plan) {
+    return new Map(plan.entities.map(({ name, resolved: entity }) => [
+        name,
+        Schema.Struct(recordFields(entity)).annotate({
+            identifier: `${pascalCase(name)}Record`,
+            title: entity.entity.definition.label,
+            description: entity.entity.definition.description,
+        }),
+    ]));
+}
+/**
+ * The record and query schemas of every entity. Queries are `src/query.ts`'s, so the service and
+ * the runtime accept exactly the same language.
+ */
+export function entitySchemas(plan) {
+    const records = recordSchemas(plan);
+    return new Map(plan.entities.map((planned) => [
+        planned.name,
+        schemasOf(plan, planned, (name) => records.get(name) ?? Schema.Never),
+    ]));
+}
+function schemasOf(plan, planned, recordOf) {
+    const { name, resolved } = planned;
+    const { manifest } = plan.ontology;
+    const pascal = pascalCase(name);
+    const record = recordOf(name);
+    const query = entityQuerySchemas(manifest, name, true, true);
+    const links = queryLinks(manifest, name, true);
+    const includedFields = {};
+    for (const link of links) {
+        const target = recordOf(link.target);
+        includedFields[link.name] = Schema.optionalKey(link.cardinality === "one" ? Schema.NullOr(target) : Schema.Array(target));
+    }
+    const result = links.length === 0
+        ? record
+        : Schema.Struct({ ...recordFields(resolved), ...includedFields }).annotate({
+            identifier: `${pascal}Result`,
+            description: `A ${resolved.entity.definition.label.toLowerCase()} with the relationships the query included.`,
+        });
+    const projectedRecord = Schema.Struct({
+        ...Object.fromEntries(Object.entries(recordFields(resolved)).map(([field, value]) => [
+            field,
+            field === "id" ? value : Schema.optionalKey(value),
+        ])),
+        ...includedFields,
+    }).annotate({ identifier: `${pascal}Projection` });
+    return {
+        record,
+        result,
+        query: query.query,
+        queryParams: wireStruct({
+            where: Schema.optionalKey(whereParam(query.where)),
+            orderBy: Schema.optionalKey(orderByParam(query.orderBy)),
+            select: Schema.optionalKey(selectedFieldsParam(query.select)),
+            include: Schema.optionalKey(includeParam(query.include)),
+            after: Schema.optionalKey(query.after),
+            limit: Schema.optionalKey(query.limit),
+        }, { orderBy: "order_by" }, "Unknown parameter"),
+        includeParams: {
+            include: Schema.optionalKey(includeParam(query.include)),
+        },
+        findResult: projectedQueryResultSchema(result, projectedRecord, true).annotate({
+            identifier: `${pascal}PageEncoded`,
+        }),
+    };
+}
+const HistoryLimit = Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 200 })).annotate({
+    description: "The page size, at most 200.",
+});
+/** The query parameters of a record's history. */
+export const HistoryParams = {
+    after: Schema.optionalKey(Schema.String.annotate({ description: "The next_cursor of the previous page." })),
+    limit: Schema.optionalKey(HistoryLimit),
+};
+export const ValidationIssue = RuntimeValidationIssue.annotate({ identifier: "ValidationIssue" });
+export const Validation = Schema.Struct({
+    ok: Schema.Boolean,
+    issues: Schema.Array(ValidationIssue),
+}).annotate({ identifier: "Validation" });
+export const HistoryEntry = RuntimeHistoryEntry.pipe(Schema.encodeKeys({ recordId: "record_id", actionId: "action_id", principalId: "principal_id" })).annotate({
+    identifier: "HistoryEntry",
+    description: "What one action changed on the record: the previous and new value of each property, " +
+        "relationship key or link.",
+});
+export const HistoryPage = Schema.Struct({
+    items: Schema.Array(HistoryEntry),
+    nextCursor: Schema.NullOr(Schema.String),
+})
+    .pipe(Schema.encodeKeys({ nextCursor: "next_cursor" }))
+    .annotate({ identifier: "HistoryPage" });
+const uploadOptions = {
+    idempotencyKey: Schema.optionalKey(Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(128))),
+    createIntent: Schema.optionalKey(Schema.String.check(Schema.isUUID())),
+};
+const ActionOptions = wireStruct({
+    ...uploadOptions,
+    validateOnly: Schema.optionalKey(Schema.Boolean.annotate({
+        description: "Validate the input and report issues without a write.",
+    })),
+}, {
+    validateOnly: "validate_only",
+    idempotencyKey: "idempotency_key",
+    createIntent: "create_intent",
+});
+/** The body of `POST /<entity>/actions/<action>`, as documented. */
+export function actionRequest(input) {
+    return Schema.Struct({ input, options: Schema.optionalKey(ActionOptions) });
+}
+/** The body of `POST /<entity>/actions/<action>`, as decoded: `runAction` validates the input. */
+export const ActionEnvelope = closedStruct({
+    input: Schema.Unknown,
+    options: Schema.optionalKey(wireStruct({ validateOnly: Schema.optionalKey(Schema.Boolean), ...uploadOptions }, {
+        validateOnly: "validate_only",
+        idempotencyKey: "idempotency_key",
+        createIntent: "create_intent",
+    })),
+}, "Unknown key; use input and options");
+export const ActionResponse = Schema.Struct({
+    result: Schema.Unknown.annotate({ description: "What the action returned." }),
+    validation: Validation,
+    edits: Schema.Array(Edit.annotate({ identifier: "Edit" })).annotate({
+        description: "The records the action changed, as their history records each change.",
+    }),
+}).annotate({ identifier: "ActionResponse" });
+export const Catalog = OntologyManifestWire.annotate({ identifier: "Catalog" });
+const GraphEntity = Schema.Struct({
+    name: Schema.String,
+    label: Schema.String,
+    plural: Schema.String,
+    description: Schema.String,
+});
+const GraphRelationship = Schema.Struct({
+    from: Schema.String,
+    name: Schema.String,
+    to: Schema.String,
+    inverse: Schema.String,
+    cardinality: Schema.Literals(["one", "many"]),
+    /** The property pair of a relationship matched by value: one with a warehouse-backed end. */
+    on: Schema.optionalKey(Schema.Struct({ property: Schema.String, targetProperty: Schema.String }).pipe(Schema.encodeKeys({ targetProperty: "target_property" }))),
+    optional: Schema.Boolean,
+    phrase: Schema.Tuple([Schema.String, Schema.String]),
+    forward: Schema.String.annotate({ examples: ["Lead is owned by one User"] }),
+    backward: Schema.String.annotate({ examples: ["User owns many Leads"] }),
+    description: Schema.String,
+});
+export const Graph = Schema.Struct({
+    hash: Schema.String,
+    entities: Schema.Array(GraphEntity),
+    relationships: Schema.Array(GraphRelationship),
+}).annotate({ identifier: "Graph" });
+export const Status = Schema.Struct({
+    deployment: Schema.optionalKey(Schema.Struct({
+        target: Schema.Literals(["production", "preview"]),
+        deploymentId: Schema.optionalKey(Schema.String),
+        expiresAt: Schema.optionalKey(Schema.String),
+        capabilities: Schema.Struct({
+            warehouseRead: Schema.Boolean,
+            pipelineRuns: Schema.Boolean,
+            connections: Schema.Boolean,
+            agents: Schema.Boolean,
+            workflows: Schema.Boolean,
+        }),
+    })),
+    hash: Schema.String.annotate({ description: "The hash of the manifest this service serves." }),
+    appliedHash: Schema.NullOr(Schema.String).annotate({
+        description: "The manifest hash recorded by the last migration of the workspace database.",
+    }),
+    upToDate: Schema.Boolean.annotate({ description: "Whether the two hashes match." }),
+})
+    .pipe(Schema.encodeKeys({ appliedHash: "applied_hash", upToDate: "up_to_date" }))
+    .annotate({ identifier: "Status" });
+/** The longest address `POST /api/ontology/sign-in/check` reads; RFC 5321 allows 254. */
+export const SIGN_IN_CHECK_MAX_EMAIL_LENGTH = 320;
+/** `POST /api/ontology/sign-in/check`: the address a person wants to sign in with. */
+export const SignInCheckRequest = Schema.Struct({
+    email: Schema.String.check(Schema.isMaxLength(SIGN_IN_CHECK_MAX_EMAIL_LENGTH)).annotate({
+        description: "The address the person typed, in any case.",
+    }),
+}).annotate({ identifier: "SignInCheckRequest" });
+/** The bounds of a model-level metric query (docs/ontology-aggregates-spec.md, "Request"). */
+export const METRIC_QUERY_LIMITS = {
+    metrics: 30,
+    dimensions: 20,
+    filters: 50,
+    values: MAXIMUM_FILTER_VALUES,
+    orderBy: 50,
+    rows: 1000,
+};
+/**
+ * The granularities a date or timestamp dimension buckets by; `hour` applies to timestamps only.
+ */
+export const METRIC_QUERY_GRANULARITIES = [
+    "hour",
+    "day",
+    "week",
+    "month",
+    "quarter",
+    "year",
+];
+/** The longest `timezone` a request names. */
+export const MAXIMUM_TIMEZONE_LENGTH = 64;
+const MetricQueryValue = Schema.Union([Schema.String, Schema.Number, Schema.Boolean]);
+/**
+ * A filter of either request. Which values each operator takes is checked with SegmentStream's own
+ * messages (`filterValuesIssue`); whether they suit the dimension's type is SegmentStream's to check.
+ */
+function metricQueryFilter(operators, descriptions) {
+    const filter = closedStruct({
+        dimension: Schema.String.annotate({
+            description: "A property, or a path of to-one relationships ending in one.",
+        }),
+        operator: Schema.Literals(operators),
+        value: Schema.optionalKey(MetricQueryValue).annotate({ description: descriptions.value }),
+        values: Schema.optionalKey(Schema.Array(MetricQueryValue).check(Schema.isMaxLength(METRIC_QUERY_LIMITS.values))).annotate({ description: descriptions.values }),
+    }, "Unknown key; use dimension, operator, value and values");
+    return filter.check(Schema.makeFilter((candidate) => filterValuesIssue(candidate) ?? true));
+}
+const MetricQueryOrder = closedStruct({
+    metric: Schema.optionalKey(Schema.String),
+    dimension: Schema.optionalKey(Schema.String),
+    direction: Schema.Literals(["asc", "desc"]),
+}, "Unknown key; use metric or dimension, and direction");
+/** The fields both metric queries share, with their bounds. */
+const metricQueryFields = {
+    granularity: Schema.optionalKey(Schema.Literals(METRIC_QUERY_GRANULARITIES)),
+    granularityOf: Schema.optionalKey(Schema.String).annotate({
+        description: "The requested date or timestamp dimension that granularity buckets.",
+    }),
+    timezone: Schema.optionalKey(Schema.String.check(Schema.isMaxLength(MAXIMUM_TIMEZONE_LENGTH))).annotate({
+        description: "An IANA timezone, such as Europe/Moscow, or UTC. Buckets of timestamps, date bounds on " +
+            "timestamps and inPeriod's today follow it instead of each entity's timezone; metric " +
+            "conditions never do.",
+    }),
+    orderBy: Schema.optionalKey(Schema.Array(MetricQueryOrder).check(Schema.isMaxLength(METRIC_QUERY_LIMITS.orderBy))),
+    limit: Schema.optionalKey(Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: METRIC_QUERY_LIMITS.rows }))).annotate({ description: "At most 1000 rows; 100 by default." }),
+};
+/**
+ * `POST /api/ontology/query_metrics`, as documented: the current names only. The service checks the
+ * shape and the bounds, resolves the names against its manifest and forwards the body with the
+ * current names; SegmentStream checks everything else.
+ */
+export const MetricQueryBody = closedStruct({
+    metrics: Schema.Array(Schema.String)
+        .check(Schema.isMaxLength(METRIC_QUERY_LIMITS.metrics))
+        .annotate({
+        description: "<entity>.<metric>, or a metric of the model by its name, such as plan_attainment; " +
+            "at least one, at most 30 of both together.",
+    }),
+    dimensions: Schema.optionalKey(Schema.Array(Schema.String).check(Schema.isMaxLength(METRIC_QUERY_LIMITS.dimensions))).annotate({
+        description: "<entity>.<property>, or a route from a metric's entity: " +
+            "<entity>.<relationship>[.<relationship>].<property>.",
+    }),
+    filters: Schema.optionalKey(Schema.Array(metricQueryFilter(METRIC_QUERY_FILTER_OPERATORS, {
+        value: "The value of equals and notEquals; the bound of gt, gte, lt and lte; a non-empty " +
+            "string for contains, startsWith and endsWith; the period of inPeriod, such as " +
+            "last 7 days.",
+        values: "The values of in and notIn, or the two inclusive bounds of between.",
+    })).check(Schema.isMaxLength(METRIC_QUERY_LIMITS.filters))).annotate({ description: "All must hold." }),
+    ...metricQueryFields,
+}, "Unknown key; use metrics, dimensions, filters, granularity, granularityOf, timezone, orderBy " +
+    "and limit").annotate({ identifier: "MetricQuery" });
+/** `POST /api/ontology/query_metrics` as decoded: the documented body, or one with earlier names. */
+export const MetricQuery = acceptingEarlierMetricQueryNames(MetricQueryBody);
+/**
+ * `POST /api/ontology/<entity>/query_metrics`: SegmentStream's per-entity request, as documented. Names
+ * are relative to the entity (`revenue`, `product.brand`), and `dateRange` bounds a partitioned
+ * entity.
+ */
+export const EntityMetricQueryBody = closedStruct({
+    dimensions: Schema.Array(Schema.String)
+        .check(Schema.isMaxLength(METRIC_QUERY_LIMITS.dimensions))
+        .annotate({
+        description: "A property, or a path of to-one relationships: product.brand.",
+    }),
+    metrics: Schema.Array(Schema.String)
+        .check(Schema.isMaxLength(METRIC_QUERY_LIMITS.metrics))
+        .annotate({ description: "The entity's metrics, at least one." }),
+    dateRange: Schema.optionalKey(closedStruct({
+        from: Schema.String.annotate({ format: "date" }),
+        to: Schema.String.annotate({ format: "date" }),
+    }, "Unknown key; use from and to")).annotate({ description: "Inclusive days of the entity's partition property." }),
+    filters: Schema.optionalKey(Schema.Array(metricQueryFilter(ENTITY_METRIC_QUERY_FILTER_OPERATORS, {
+        value: "The value of equals and notEquals; the bound of gt, gte, lt and lte; a non-empty " +
+            "string for contains, startsWith and endsWith.",
+        values: "The values of in and notIn.",
+    })).check(Schema.isMaxLength(METRIC_QUERY_LIMITS.filters))).annotate({ description: "All must hold." }),
+    ...metricQueryFields,
+}, "Unknown key; use dimensions, metrics, dateRange, filters, granularity, granularityOf, " +
+    "timezone, orderBy and limit").annotate({ identifier: "EntityMetricQuery" });
+/** `POST /api/ontology/<entity>/query_metrics` as decoded, earlier names included. */
+export const EntityMetricQuery = acceptingEarlierMetricQueryNames(EntityMetricQueryBody);
+/** SegmentStream's answer to a metric query, which the service forwards unchanged. */
+export const MetricQueryResult = Schema.Struct({
+    fields: Schema.Array(Schema.Struct({
+        name: Schema.String.annotate({
+            description: "A dimension identity, <entity>.<metric>, or the name of a metric of the model.",
+        }),
+        label: Schema.String,
+        type: Schema.String,
+        unit: Schema.optionalKey(Schema.String),
+        format: Schema.optionalKey(Schema.String),
+        scope: Schema.optionalKey(Schema.Array(Schema.String)),
+        implicit: Schema.optionalKey(Schema.Boolean),
+        additive: Schema.optionalKey(Schema.Boolean).annotate({
+            description: "false when the metric's rows do not add up to a total.",
+        }),
+        filters: Schema.optionalKey(Schema.Array(Schema.String)).annotate({
+            description: "The filters the metric applied.",
+        }),
+        balanceOver: Schema.optionalKey(Schema.String).annotate({
+            description: "The date or timestamp dimension a balance metric was grouped by or filtered to one " +
+                "day of.",
+        }),
+        inputs: Schema.optionalKey(Schema.Array(Schema.String)).annotate({
+            description: "The entity metrics a metric of the model reads, <entity>.<metric>, in declaration " +
+                "order; present only on such a metric.",
+        }),
+    })),
+    rows: Schema.Array(Schema.Record(Schema.String, Schema.NullOr(Schema.Union([Schema.String, Schema.Boolean])))),
+    truncated: Schema.Boolean,
+    execution: Schema.Struct({
+        elapsedMs: Schema.Number,
+        bytesProcessed: Schema.optionalKey(Schema.String),
+        bytesBilled: Schema.optionalKey(Schema.String),
+        warnings: Schema.optionalKey(Schema.Array(Schema.String)).annotate({
+            description: "For example, a filter that did not apply to some metric's entity.",
+        }),
+        sources: Schema.optionalKey(Schema.Array(Schema.Struct({ entity: Schema.String, asOf: Schema.String }))).annotate({
+            // @legacy ontology.replication-verification-remnants
+            description: "Historical destination observations from older servers; current servers omit this field.",
+        }),
+        periods: Schema.optionalKey(Schema.Array(Schema.Struct({
+            dimension: Schema.String,
+            value: Schema.String,
+            from: Schema.String.annotate({ format: "date" }),
+            to: Schema.String.annotate({ format: "date" }),
+            timezone: Schema.String,
+        }))).annotate({ description: "The inclusive dates each inPeriod filter used, in request order." }),
+    }),
+    deploymentId: Schema.NullOr(Schema.String),
+    definitionDigest: Schema.String,
+}).annotate({ identifier: "MetricQueryResult" });
+/** Whether the address may sign in, and with a code or a link. */
+export const SignInCheckResult = Schema.Union([
+    Schema.Struct({ allowed: Schema.Literal(false) }),
+    Schema.Struct({
+        allowed: Schema.Literal(true),
+        method: Schema.Literals(["code", "link"]).annotate({
+            description: "code: the member has a Neon Auth account and gets a six-digit code. link: they get a " +
+                "sign-in link, which creates the account.",
+        }),
+    }),
+]).annotate({ identifier: "SignInCheckResult" });
+/** `GET /api/ontology/me`: who the caller is and what they may do, for the app to render. */
+export const Me = Schema.Struct({
+    authentication: Schema.Struct({
+        kind: Schema.Literals(["member", "oauth", "runtime", "service", "workload", "unverified"]),
+        client: Schema.NullOr(Schema.Struct({ id: Schema.String, name: Schema.String })),
+        scope: Schema.NullOr(Schema.String),
+    }),
+    attribution: Schema.NullOr(Schema.String),
+    attribution_separator: Schema.optionalKey(Schema.String),
+    user: Schema.Struct({
+        id: Id.annotate({ description: "The caller's user id: principalId in history." }),
+        name: Schema.String,
+        email: Schema.NullOr(Schema.String).annotate({
+            description: "The member's sign-in address; null for services and members without one.",
+        }),
+        kind: Schema.Literals(["member", "service"]),
+        active: Schema.Boolean,
+    }),
+    roles: Schema.Array(Schema.String).annotate({
+        description: "The roles the caller holds; every member holds member.",
+    }),
+    permissions: Schema.Array(Schema.String).annotate({
+        description: "The permissions those roles grant in this ontology, wildcards included.",
+    }),
+    scopes: Schema.optionalKey(Schema.Array(ScopeManifest).annotate({
+        description: "The permissions held only for the records their where matches, as the manifest's " +
+            'roles[].scopes writes them: { "$me": [...] } is the caller or a path from them. ' +
+            "Absent when none is scoped.",
+    })),
+}).annotate({ identifier: "Me" });
+export const AsParams = {
+    as: Schema.optionalKey(Schema.Literal("me").annotate({
+        description: "me: list only the actions the caller's permissions may run.",
+    })),
+};
+const Count = Schema.Int.check(Schema.isGreaterThanOrEqualTo(0));
+/** The platform limit that refused a file upload or attachment, so a caller can explain it. */
+const LimitErrorWire = Schema.Union([
+    Schema.Struct({
+        kind: Schema.Literal("storage_quota"),
+        used_bytes: Count,
+        requested_bytes: Count,
+        quota_bytes: Count,
+    }),
+    Schema.Struct({
+        kind: Schema.Literal("pending_uploads"),
+        pending: Count,
+        max: Count,
+        uploads: Schema.optionalKey(Schema.Array(Schema.Struct({ id: Schema.String, filename: Schema.String, expires_at: Schema.String }))),
+    }),
+    Schema.Struct({ kind: Schema.Literal("member_attachments"), live: Count, max: Count }),
+]).annotate({ identifier: "LimitError" });
+function errorBody(identifier, status, codes, extra = {}) {
+    return Schema.Struct({
+        error: Schema.Literals(codes),
+        detail: Schema.String,
+        requestId: Schema.String.annotate({ description: "Quote it when reporting a problem." }),
+        ...extra,
+    })
+        .pipe(Schema.encodeKeys({ requestId: "request_id" }))
+        .annotate({ identifier, httpApiStatus: status });
+}
+export const ErrorSchemas = {
+    invalidRequest: errorBody("InvalidRequest", 400, ["invalid_request", "invalid_json"], {
+        suggestions: Schema.optionalKey(Schema.Array(Schema.String)),
+        issues: Schema.optionalKey(Schema.Array(ValidationIssue)),
+    }),
+    unauthorized: errorBody("Unauthorized", 401, ["unauthorized"]),
+    forbidden: errorBody("Forbidden", 403, ["forbidden"], {
+        entity: Schema.optionalKey(Schema.String),
+        permission: Schema.optionalKey(Schema.String),
+        batch: Schema.optionalKey(BatchErrorDetails),
+    }),
+    notInvited: errorBody("NotInvited", 403, ["not_invited"]),
+    notFound: errorBody("NotFound", 404, ["not_found"], {
+        suggestions: Schema.optionalKey(Schema.Array(Schema.String)),
+        entity: Schema.optionalKey(Schema.String),
+        id: Schema.optionalKey(Schema.String),
+        batch: Schema.optionalKey(BatchErrorDetails),
+    }),
+    conflict: errorBody("Conflict", 409, ["conflict"], {
+        entity: Schema.optionalKey(Schema.String),
+        property: Schema.optionalKey(Schema.String),
+        batch: Schema.optionalKey(BatchErrorDetails),
+        retryable: Schema.optionalKey(Schema.Boolean),
+        retry_after: Schema.optionalKey(Schema.Int),
+    }),
+    unsupportedMediaType: errorBody("UnsupportedMediaType", 415, ["unsupported_media_type"]),
+    unprocessable: errorBody("Unprocessable", 422, ["invalid_input", "action_rejected"], {
+        issues: Schema.Array(ValidationIssue),
+        batch: Schema.optionalKey(BatchErrorDetails),
+        limit: Schema.optionalKey(LimitErrorWire),
+    }),
+    rateLimited: errorBody("RateLimited", 429, ["rate_limited"]),
+    internal: errorBody("InternalError", 500, ["internal_error"]),
+    unavailable: errorBody("ServiceUnavailable", 503, ["service_unavailable"]),
+    storageUnavailable: errorBody("StorageUnavailable", 503, ["storage_unavailable", "ontology_updating"], { retryable: Schema.Boolean }),
+    invalidMetricQuery: errorBody("InvalidMetricQuery", 400, ["invalid_aggregate_query"]),
+    readForbidden: errorBody("ReadForbidden", 403, ["forbidden", "scoped_aggregate_unavailable"], {
+        permissions: Schema.optionalKey(Schema.Array(Schema.String)),
+        entity: Schema.optionalKey(Schema.String),
+        // Why a scoped metric query was refused, a code for the workspace to word.
+        reason: Schema.optionalKey(ScopedMetricQueryReason),
+    }),
+    metricQueriesUnavailable: errorBody("MetricQueriesUnavailable", 503, ["aggregate_unavailable"], {
+        retryable: Schema.Boolean,
+    }),
+    warehouseReadUnavailable: errorBody("WarehouseReadUnavailable", 503, ["warehouse_read_unavailable"], {
+        retryable: Schema.Boolean,
+    }),
+    metricQueryUpstreamUnavailable: errorBody("MetricQueryUpstreamUnavailable", 502, ["aggregate_upstream_unavailable"], { retryable: Schema.Boolean }),
+    connectionRequired: errorBody("ConnectionRequired", 409, ["connection_authorization_required", "connections_not_deployed"], { connection: Schema.String }),
+    connectionResponseInvalid: errorBody("ConnectionResponseInvalid", 502, [
+        "connection_response_invalid",
+    ]),
+    connectionUnavailable: errorBody("ConnectionUnavailable", 503, ["connection_unavailable", "connection_refused"], { connection: Schema.String, retryable: Schema.Boolean }),
+};

package/dist/service/service.d.ts

@@ -0,0 +1,21 @@
+import type { Ontology } from "../ontology.js";
+import { type OntologyApi } from "./api.js";
+import { type OntologyServiceConfig } from "./config.js";
+/** The header every response carries: the hash of the manifest the service serves. */
+export declare const ONTOLOGY_HASH_HEADER = "x-ontology-hash";
+/** The header every response carries: the correlation id quoted in error bodies and logs. */
+export declare const REQUEST_ID_HEADER = "x-request-id";
+export interface OntologyService {
+    /** Answers one request; what the workspace deployment's Nitro entry calls. */
+    readonly handler: (request: Request) => Promise<Response>;
+    readonly api: OntologyApi;
+    /** Closes the database pool and the other resources the runtime opened. */
+    readonly dispose: () => Promise<void>;
+}
+/**
+ * The ontology service: the derived HttpApi, the MCP server at `/mcp` and the agent's pairing routes,
+ * wired to the runtime, behind Neon Auth, app-token, API-key and runtime-token authentication.
+ * Every response carries `x-ontology-hash`
+ * and `x-request-id`; failures answer with a JSON error and never a stack or SQL.
+ */
+export declare function createOntologyService(ontology: Ontology, config: OntologyServiceConfig): OntologyService;