@segmentstream/ontology 0.0.0-stage → 0.92.1

package/dist/manifest.js

@@ -0,0 +1,757 @@
+import { balancesOf, metricExpression } from "./metric.js";
+import { Effect, Schema, SchemaTransformation } from "effect";
+import { acceptingEarlierManifestNames, withEarlierManifestNames } from "./legacy.js";
+import { humanize, MEMBER_ROLE, FEEDBACK_REPORTER_ROLE } from "./names.js";
+import { PROPERTY_TYPES } from "./property.js";
+import { ON_DELETE } from "./relationship.js";
+import { CHANNEL_PROVIDERS, DEFAULT_SIGN_IN_POLICY, isSignInPolicy, } from "./sign-in.js";
+/**
+ * The manifest format this SDK writes. Readers accept any version and ignore unknown fields. Version
+ * 2 replaced the actions' `allow` with `permission`, and added the roles' `permissions` and the
+ * entities' `permissions`; those fields are optional when decoding, so version 1 manifests still read.
+ * `signIn` came later within version 2 and is optional too, as are the actions' `connections` and the
+ * top-level `connections`, which are written only when an action calls a connection. Version 3 added
+ * warehouse sources and metrics. Version 4 writes snake_case names on the wire. Version 5 lets
+ * relationships target warehouse-backed entities and warehouse-backed properties declare `unique`:
+ * a relationship with a warehouse-backed end carries `on` and omits `optional` and `onDelete`.
+ * Version 6 adds the `countDistinct` metric operator and lets stored entities declare `metrics`,
+ * whose columns name the stored properties' replication view columns. Version 7 adds the avg, min,
+ * max and filtered metric operators and balanceOver on metrics. Version 8 adds the top-level
+ * `metrics`, the metrics of the model, written only when the ontology declares some: each combines
+ * metrics of entities, named `entity.metric`, with its inputs and its alignment. Version 9 adds the
+ * top-level `workflows`, written only when the ontology declares some: each names its role, its
+ * input as JSON Schema, the connections its steps call and its triggers, whose input is in wire form.
+ * Within version 9, a property may have the type `list` with its `items` type: only the built-in
+ * user's managed `roles`, which has no column.
+ * Within version 9, triggers may also be `action` and `webhook` triggers; readers ignore kinds they
+ * do not know.
+ * Version 10 adds the roles' `scopes`, written only when a role scopes some of its permissions: each
+ * names the permission and its `where` in the wire form of a query, with `me` as `{ "$me": [] }`
+ * and a path from it as `{ "$me": ["staff_member", "division"] }`. `permissions` still lists every
+ * permission the role holds, scoped or not. Version 11 adds resolved `feedback` settings and the
+ * reserved built-in `feedback_reporter` role, which is implicit for humans and never assignable.
+ * Within version 11, actions may opt in to SQL deadlock recovery with `retryOnDeadlock`; its absence
+ * disables retries and older readers may ignore it.
+ * Within version 11, the top-level `emails`, written only when the ontology declares some, holds the
+ * workspace's own emails by wire name: plain-text fields with `{{value}}` placeholders, which the
+ * platform renders when it sends a sign-in link. Older readers ignore it.
+ * Version 12 changes no field: it marks an SDK whose actions arm a recovery run for their triggers,
+ * so publication writes no sweep cron for it. For earlier versions publication keeps the
+ * five-minute sweep cron, which their service still needs.
+ * Version 13 adds optional `signIn.browser` declarations for workspace-owned browser sign-in
+ * methods, primary method, automatic redirect behavior, and local callback port.
+ * Within version 13, an entity may carry `writes: "actions"`: it has no generated writes, and its
+ * `permissions` hold only `read`, so readers that derive the generated actions from `permissions`
+ * need no change. Older readers ignore the field.
+ * Within version 13, an action may carry `writes`, the names of the entities its handler writes,
+ * which the runtime enforces; absent means it declares none. Older readers ignore the field.
+ * Version 14 gives metrics their current names: entities' and the model's `metrics`, and `metric`
+ * expression nodes (`{ op: "metric", name }`). Readers accept the earlier names, which the history
+ * above calls metrics too; `legacy.ts` names them and renames every document it decodes.
+ * Within version 14, `signIn` may carry `codeLink`, written only when declared: whether the
+ * platform's sign-in code emails also link to the app's sign-in page with the code filled in.
+ * Older readers ignore it and send the code alone.
+ * Version 15 changes no field this SDK writes. Ontology SDKs 0.86.0 to 0.88.0 introduced it with
+ * `executionCompatibility` and three workflow capabilities for a deploy guard that was withdrawn;
+ * readers ignore them.
+ */
+export const MANIFEST_VERSION = 15;
+/** The first version whose documents use snake_case names on the wire. */
+const WIRE_MANIFEST_VERSION = 4;
+/** The first version whose documents name metrics as this SDK does; earlier ones keep theirs. */
+const METRICS_MANIFEST_VERSION = 14;
+/** The phrase used for a direction the author did not phrase. */
+export const DEFAULT_PHRASE = "has";
+export const SelectOptionManifest = Schema.Struct({
+    value: Schema.String,
+    label: Schema.String,
+    description: Schema.String,
+});
+export const PropertyManifest = Schema.Struct({
+    column: Schema.optionalKey(Schema.String),
+    scope: Schema.optionalKey(Schema.Array(Schema.String)),
+    name: Schema.String,
+    type: Schema.Literals(PROPERTY_TYPES),
+    label: Schema.String,
+    description: Schema.optionalKey(Schema.String),
+    optional: Schema.Boolean,
+    unique: Schema.Boolean,
+    managed: Schema.Boolean,
+    default: Schema.optionalKey(Schema.Json),
+    display: Schema.optionalKey(Schema.String),
+    renamedFrom: Schema.optionalKey(Schema.String),
+    min: Schema.optionalKey(Schema.Number),
+    max: Schema.optionalKey(Schema.Number),
+    maxLength: Schema.optionalKey(Schema.Number),
+    accept: Schema.optionalKey(Schema.Array(Schema.String)),
+    maxBytes: Schema.optionalKey(Schema.Number),
+    options: Schema.optionalKey(Schema.Array(SelectOptionManifest)),
+    /** The item type of a `list`, the built-in user's `roles`, which has no column. */
+    items: Schema.optionalKey(Schema.Literals(PROPERTY_TYPES)),
+});
+/**
+ * A relationship as declared. The inverse is not repeated on the target entity: readers derive it
+ * from `to`, `inverse` and the second `phrase`.
+ */
+export const RelationshipManifest = Schema.Struct({
+    /**
+     * The property pair of a value-matched relationship, one with a warehouse-backed end. Absent
+     * between stored entities, which use a `<name>_id` key instead.
+     */
+    on: Schema.optionalKey(Schema.Struct({ property: Schema.String, targetProperty: Schema.String })),
+    name: Schema.String,
+    to: Schema.String,
+    inverse: Schema.String,
+    cardinality: Schema.Literals(["one", "many"]),
+    /** `rel.one` between stored entities only. */
+    optional: Schema.optionalKey(Schema.Boolean),
+    /**
+     * `rel.one` between stored entities only. Before version 5, warehouse → stored relationships
+     * carried it too, as `restrict`, though nothing enforced it.
+     */
+    onDelete: Schema.optionalKey(Schema.Literals(ON_DELETE)),
+    /** `rel.many` only. */
+    ordered: Schema.optionalKey(Schema.Boolean),
+    /** Forward and inverse phrases; unphrased directions read "has". */
+    phrase: Schema.Tuple([Schema.String, Schema.String]),
+    description: Schema.String,
+});
+/**
+ * Whether a relationship is matched by value: either end is warehouse-backed. A value-matched
+ * relationship always declares `on`; a stored → stored relationship never does. It has no
+ * `<name>_id` column, foreign key, index or traversal route.
+ */
+export function isValueMatched(relationship) {
+    return relationship.on !== undefined;
+}
+export const IndexManifest = Schema.Struct({
+    properties: Schema.Array(Schema.String),
+    unique: Schema.Boolean,
+});
+export const ActionManifest = Schema.Struct({
+    name: Schema.String,
+    description: Schema.String,
+    /**
+     * The permission a principal needs to run the action, for example `lead:changeStatus`. Always
+     * written; absent from version 1 manifests, where it reads as `<entity>:<action name>`.
+     */
+    permission: Schema.optionalKey(Schema.String),
+    /** JSON Schema (draft 2020-12) of the input object. */
+    input: Schema.Record(Schema.String, Schema.Json),
+    /** Opt-in SQL handler replay after a confirmed deadlock rollback; absent means disabled. */
+    retryOnDeadlock: Schema.optionalKey(Schema.Boolean),
+    /**
+     * The entities the handler writes, by name, as the action declares them; the runtime refuses any
+     * other write. Absent means it declares none and may write any entity; `[]` writes nothing.
+     */
+    writes: Schema.optionalKey(Schema.Array(Schema.String)),
+    /**
+     * The keys of the workspace connections the action calls before its transaction. Written only
+     * when there are some; absent reads as none.
+     */
+    connections: Schema.optionalKey(Schema.Array(Schema.String)),
+    /** File writes declared in code; absence grants preparation no staging targets. */
+    files: Schema.optionalKey(Schema.Array(Schema.Struct({ entity: Schema.String, property: Schema.String }))),
+    /**
+     * How the action behaves, as MCP tool annotations tell agents. Written only when the action
+     * declares hints; absent safety labels require agent confirmation for compatibility.
+     */
+    hints: Schema.optionalKey(Schema.Struct({
+        readOnly: Schema.optionalKey(Schema.Boolean),
+        connectionsReadOnly: Schema.optionalKey(Schema.Boolean),
+        destructive: Schema.optionalKey(Schema.Boolean),
+        irreversible: Schema.optionalKey(Schema.Boolean),
+        idempotent: Schema.optionalKey(Schema.Boolean),
+    })),
+});
+/**
+ * The permissions of an entity's reads and generated actions, so that readers need not rebuild the
+ * convention. The built-in user has only `read`; `link` and `unlink` exist with a `rel.many`. The
+ * generated `upsert_by_<property>` requires both `create` and `update`.
+ */
+export const EntityPermissionsManifest = Schema.Struct({
+    read: Schema.String,
+    create: Schema.optionalKey(Schema.String),
+    update: Schema.optionalKey(Schema.String),
+    delete: Schema.optionalKey(Schema.String),
+    link: Schema.optionalKey(Schema.String),
+    unlink: Schema.optionalKey(Schema.String),
+});
+/** A metric of an entity: its metadata and the expression the platform computes. */
+export const MetricManifest = Schema.Struct({
+    name: Schema.String,
+    label: Schema.String,
+    description: Schema.String,
+    unit: Schema.Literals(["number", "currency", "ratio", "percent"]),
+    format: Schema.Literals(["decimal", "currency", "percent"]),
+    expression: Schema.Json,
+    /**
+     * The column of the date or timestamp property a balance metric snapshots over; absent for
+     * additive metrics and in manifests before version 7. `balance_over` on the wire.
+     */
+    balanceOver: Schema.optionalKey(Schema.String),
+});
+/**
+ * A metric of the model, `defineOntology({ metrics })`. Its expression is an entity metric's
+ * arithmetic whose `metric` nodes name `entity.metric`, with references to other model metrics
+ * expanded. Names are wire names throughout.
+ */
+export const ModelMetricManifest = Schema.Struct({
+    name: Schema.String,
+    label: Schema.String,
+    description: Schema.String,
+    unit: Schema.Literals(["number", "currency", "ratio", "percent"]),
+    format: Schema.Literals(["decimal", "currency", "percent"]),
+    expression: Schema.Json,
+    /** The entity metrics the expression reads, `entity.metric`, each once, in reading order. */
+    inputs: Schema.Array(Schema.String),
+    /**
+     * Groups of properties that stand for one another: each names every entity the metric reads,
+     * with a property or `null` for an entity without a counterpart.
+     */
+    align: Schema.Array(Schema.Record(Schema.String, Schema.NullOr(Schema.String))),
+});
+export const EntityManifest = Schema.Struct({
+    source: Schema.optionalKey(Schema.Struct({
+        asset: Schema.String,
+        key: Schema.Array(Schema.String),
+        currency: Schema.optionalKey(Schema.String),
+    })),
+    metrics: Schema.optionalKey(Schema.Array(MetricManifest)),
+    id: Schema.String,
+    name: Schema.String,
+    label: Schema.String,
+    plural: Schema.String,
+    title: Schema.String,
+    description: Schema.String,
+    builtIn: Schema.Boolean,
+    renamedFrom: Schema.optionalKey(Schema.String),
+    guide: Schema.optionalKey(Schema.String),
+    properties: Schema.Array(PropertyManifest),
+    relationships: Schema.Array(RelationshipManifest),
+    indexes: Schema.Array(IndexManifest),
+    actions: Schema.Array(ActionManifest),
+    /** Always written; absent from version 1 manifests. */
+    permissions: Schema.optionalKey(EntityPermissionsManifest),
+    /**
+     * `"actions"` when only the entity's authored actions write its records, so it has no generated
+     * writes and its `permissions` hold only `read`. Absent means the generated writes exist.
+     */
+    writes: Schema.optionalKey(Schema.Literal("actions")),
+});
+/**
+ * A scoped permission of a role: `<entity>:<verb>` and the `where` of the records it covers, in the
+ * wire form of a query on the entity, where `{ "$me": [...] }` stands for the caller or a path from
+ * them. Readers that do not enforce scopes may show the `where` or ignore it.
+ */
+export const ScopeManifest = Schema.Struct({
+    permission: Schema.String,
+    where: Schema.Record(Schema.String, Schema.Json),
+});
+export const RoleManifest = Schema.Struct({
+    name: Schema.String,
+    description: Schema.String,
+    builtIn: Schema.Boolean,
+    /**
+     * What the role may do, wildcards included; for the built-in `member`, what every active app user
+     * may do. Always written; absent from version 1 manifests.
+     */
+    permissions: Schema.optionalKey(Schema.Array(Schema.String)),
+    /**
+     * The permissions the role holds only for the records their `where` matches, since version 10.
+     * Written only when there are some; absent reads as none.
+     */
+    scopes: Schema.optionalKey(Schema.Array(ScopeManifest)),
+});
+/**
+ * A cron trigger of a workflow: the platform writes a Vercel cron for it, whose invocation starts the
+ * workflow with `input`, the wire form of the workflow's input, sent as it is.
+ */
+export const CronTriggerManifest = Schema.Struct({
+    kind: Schema.Literal("cron"),
+    name: Schema.String,
+    description: Schema.String,
+    /** Five fields, UTC. */
+    cron: Schema.String,
+    input: Schema.Json,
+});
+/**
+ * An action trigger of a workflow: the ontology service starts the workflow after an action of
+ * `entity` commits, `action` or, when it is absent, any of them. Wire names; the trigger's
+ * predicate and input mapping are code and never in the manifest.
+ */
+export const ActionTriggerManifest = Schema.Struct({
+    kind: Schema.Literal("action"),
+    name: Schema.String,
+    description: Schema.String,
+    entity: Schema.String,
+    action: Schema.optionalKey(Schema.String),
+});
+/**
+ * A webhook trigger of a workflow: the ontology service starts the workflow for each genuine
+ * delivery to `/api/webhooks/<name>`. With `signature`, deliveries are checked with the provider's
+ * scheme against the named workspace secret; without it, the URL ends in a derived token.
+ * `verification` opts into a registration handshake; `headers` lists the request headers the
+ * delivery carries. Optional settings are written only when declared.
+ */
+export const WebhookTriggerManifest = Schema.Struct({
+    kind: Schema.Literal("webhook"),
+    name: Schema.String,
+    description: Schema.String,
+    signature: Schema.optionalKey(Schema.Struct({ scheme: Schema.String, secret: Schema.String })),
+    verification: Schema.optionalKey(Schema.Struct({ scheme: Schema.String, verifyToken: Schema.String })),
+    headers: Schema.optionalKey(Schema.Array(Schema.String)),
+});
+/** The trigger kinds this reader knows. */
+const KNOWN_TRIGGER_KINDS = ["cron", "action", "webhook"];
+/**
+ * A trigger of a kind this reader does not know, kept as written: a manifest a later SDK built
+ * keeps its hash, and readers that present triggers drop it.
+ */
+export const OtherTriggerManifest = Schema.Record(Schema.String, Schema.Json).check(Schema.makeFilter((value) => (typeof value.kind === "string" && !KNOWN_TRIGGER_KINDS.includes(value.kind)) ||
+    "Expected a trigger of another kind than cron, action or webhook"));
+/**
+ * A trigger of a workflow, by `kind`: `cron`, `action`, `webhook`, or a kind this reader keeps
+ * without knowing.
+ */
+export const WorkflowTriggerManifest = Schema.Union([
+    CronTriggerManifest,
+    ActionTriggerManifest,
+    WebhookTriggerManifest,
+    OtherTriggerManifest,
+]);
+/** Whether a trigger is a cron trigger. */
+export function isCronTrigger(trigger) {
+    return trigger.kind === "cron";
+}
+/** Whether a trigger is an action trigger. */
+export function isActionTrigger(trigger) {
+    return trigger.kind === "action";
+}
+/** Whether a trigger is a webhook trigger. */
+export function isWebhookTrigger(trigger) {
+    return trigger.kind === "webhook";
+}
+/**
+ * A workflow, `defineOntology({ workflows })`: a durable process the ontology service runs as the
+ * workflow's own service user holding `role`. Names are wire names; `input` is the JSON Schema of
+ * the workflow's input and `connections` the keys of the connections its steps call.
+ */
+export const WorkflowManifest = Schema.Struct({
+    name: Schema.String,
+    description: Schema.String,
+    role: Schema.String,
+    input: Schema.Record(Schema.String, Schema.Json),
+    connections: Schema.Array(Schema.String),
+    triggers: Schema.Array(WorkflowTriggerManifest),
+});
+/** A workspace connection the ontology's actions call, by its key in `connections/connections.py`. */
+export const ConnectionManifest = Schema.Struct({
+    key: Schema.String,
+    description: Schema.String,
+    /** Written only when the ontology sends data out through the connection. */
+    delivers: Schema.optionalKey(Schema.Literal(true)),
+});
+/**
+ * Who may become a member by signing in: `invited` or `open` as this SDK writes it. The policy is
+ * read as text, not as a closed set, because nothing is stored by it: a reader that meets a policy it
+ * does not know keeps the manifest and treats the policy as `invited`.
+ */
+export const BrowserSignInManifest = Schema.Struct({
+    methods: Schema.Array(Schema.String),
+    primary: Schema.String,
+    autoRedirect: Schema.Boolean,
+    local: Schema.optionalKey(Schema.Struct({ port: Schema.Int })),
+}).pipe(Schema.encodeKeys({ autoRedirect: "auto_redirect" }));
+export const SignInManifest = Schema.Struct({
+    browser: Schema.optionalKey(BrowserSignInManifest),
+    policy: Schema.String,
+    channels: Schema.optionalKey(Schema.Record(Schema.String, Schema.Unknown)),
+    onNewUser: Schema.optionalKey(Schema.String),
+    codeLink: Schema.optionalKey(Schema.Boolean),
+}).pipe(Schema.encodeKeys({ onNewUser: "on_new_user", codeLink: "code_link" }));
+/** One of the workspace's emails, as `defineOntology({ emails })` declares it; see `EmailTemplate`. */
+export const EmailTemplateManifest = Schema.Struct({
+    subject: Schema.String,
+    eyebrow: Schema.optionalKey(Schema.String),
+    heading: Schema.String,
+    card: Schema.optionalKey(Schema.Struct({ title: Schema.String, detail: Schema.optionalKey(Schema.String) })),
+    note: Schema.optionalKey(Schema.String),
+    paragraphs: Schema.optionalKey(Schema.Array(Schema.String)),
+    action: Schema.String,
+    footer: Schema.optionalKey(Schema.String),
+    replyTo: Schema.optionalKey(Schema.String),
+}).pipe(Schema.encodeKeys({ replyTo: "reply_to" }));
+/**
+ * The ontology catalog: the contract between the SDK, backend-next, the console and the CLI. Decoding
+ * ignores unknown fields and accepts any `version`. The closed sets (property types, cardinalities,
+ * `onDelete`) are validated because the migration planner must map every value to storage.
+ */
+const OntologyManifestModel = Schema.Struct({
+    // @legacy ontology.feedback-unset-manifests
+    /** Resolved feedback settings since version 11; absence preserves historical opt-in behavior. */
+    feedback: Schema.optionalKey(Schema.Struct({
+        enabled: Schema.Boolean,
+        files: Schema.Boolean,
+        builders: Schema.Array(Schema.String),
+        automaticFailureReports: Schema.optionalKey(Schema.Boolean),
+    })),
+    runtimeCapabilities: Schema.optionalKey(Schema.Array(Schema.String)),
+    // @legacy ontology.workflow-cutover-artifacts
+    /** Written by ontology SDKs 0.86.0 to 0.88.0 and never read; decoded so their manifests encode back. */
+    executionCompatibility: Schema.optionalKey(Schema.Struct({ version: Schema.Int, hash: Schema.String })),
+    version: Schema.Int,
+    /** `sha256:` and the hex digest of the canonical JSON of the manifest without `hash`. */
+    hash: Schema.String,
+    entities: Schema.Array(EntityManifest),
+    roles: Schema.Array(RoleManifest),
+    /** Always written; absent from manifests built before sign-in policies, which read as `invited`. */
+    signIn: Schema.optionalKey(SignInManifest),
+    /** The workspace's own emails by wire name. Written only when there are some; absent reads as none. */
+    emails: Schema.optionalKey(Schema.Record(Schema.String, EmailTemplateManifest)),
+    /** The connections the actions call. Written only when there are some; absent reads as none. */
+    connections: Schema.optionalKey(Schema.Array(ConnectionManifest)),
+    chat: Schema.optionalKey(Schema.Struct({
+        telegram: Schema.optionalKey(Schema.Struct({ connection: Schema.String })),
+        attribution: Schema.optionalKey(Schema.Struct({
+            template: Schema.optionalKey(Schema.String),
+            separator: Schema.optionalKey(Schema.String),
+        })),
+    })),
+    /**
+     * The metrics of the model, since version 8. Written only when there are some; absent reads as
+     * none.
+     */
+    metrics: Schema.optionalKey(Schema.Array(ModelMetricManifest)),
+    /**
+     * The workflows, since version 9. Written only when there are some; absent reads as none.
+     */
+    workflows: Schema.optionalKey(Schema.Array(WorkflowManifest)),
+});
+/** A property in the snake_case wire spelling, for records that store definitions. */
+export const PropertyManifestWire = PropertyManifest.pipe(Schema.encodeKeys({
+    renamedFrom: "renamed_from",
+    maxLength: "max_length",
+    maxBytes: "max_bytes",
+}));
+const OnDeleteWire = Schema.Literals(["set_null", "cascade", "restrict"]).pipe(Schema.decodeTo(Schema.Literals(ON_DELETE), SchemaTransformation.transform({
+    decode: (value) => (value === "set_null" ? "setNull" : value),
+    encode: (value) => (value === "setNull" ? "set_null" : value),
+})));
+/** A relationship in the snake_case wire spelling, for records that store definitions. */
+export const RelationshipManifestWire = Schema.Struct({
+    ...RelationshipManifest.fields,
+    on: Schema.optionalKey(Schema.Struct({ property: Schema.String, targetProperty: Schema.String }).pipe(Schema.encodeKeys({ targetProperty: "target_property" }))),
+    onDelete: Schema.optionalKey(OnDeleteWire),
+}).pipe(Schema.encodeKeys({ onDelete: "on_delete" }));
+const MetricManifestWire = MetricManifest.pipe(Schema.encodeKeys({ balanceOver: "balance_over" }));
+const EntityManifestWire = Schema.Struct({
+    ...EntityManifest.fields,
+    metrics: Schema.optionalKey(Schema.Array(MetricManifestWire)),
+    properties: Schema.Array(PropertyManifestWire),
+    relationships: Schema.Array(RelationshipManifestWire),
+}).pipe(Schema.encodeKeys({ builtIn: "built_in", renamedFrom: "renamed_from" }));
+const RoleManifestWire = RoleManifest.pipe(Schema.encodeKeys({ builtIn: "built_in" }));
+/** The JSON contract written since version 4; decoded SDK models remain camelCase. */
+export const OntologyManifestWire = Schema.Struct({
+    ...OntologyManifestModel.fields,
+    entities: Schema.Array(EntityManifestWire),
+    roles: Schema.Array(RoleManifestWire),
+}).pipe(Schema.encodeKeys({ signIn: "sign_in" }));
+// @legacy ontology.metric-earlier-names
+/**
+ * Historical readers accept either metadata spelling and any manifest version, with the names of
+ * metrics before version 14: every decode, of the type side too, reads a document through
+ * `withCurrentManifestNames`.
+ */
+export const OntologyManifest = acceptingEarlierManifestNames(Schema.Union([OntologyManifestWire, OntologyManifestModel]));
+const originalDocuments = new WeakMap();
+/**
+ * Retain the complete document when decoding a persisted or published manifest: encoding the decoded
+ * manifest returns it untouched, earlier names included, so its hash still verifies.
+ */
+export const decodeManifestDocument = (value) => Schema.decodeUnknownEffect(OntologyManifest)(value).pipe(Effect.map((manifest) => {
+    originalDocuments.set(manifest, value);
+    return manifest;
+}));
+/** Encode only ontology-owned metadata. JSON values and JSON Schema keywords remain opaque. */
+export function encodeManifest(manifest) {
+    const original = originalDocuments.get(manifest);
+    if (original !== undefined) {
+        return original;
+    }
+    const encoded = manifest.version < WIRE_MANIFEST_VERSION
+        ? manifest
+        : Schema.encodeSync(OntologyManifestWire)(manifest);
+    // A manifest keeps the names of its version, which its hash was computed over.
+    return manifest.version < METRICS_MANIFEST_VERSION ? withEarlierManifestNames(encoded) : encoded;
+}
+/**
+ * The sign-in policy a manifest declares. A manifest without one, or with a policy this reader does
+ * not know, reads as `invited`: the closed choice, so that a misread never lets strangers in.
+ */
+export function signInPolicyOf(manifest) {
+    const policy = manifest.signIn?.policy;
+    return isSignInPolicy(policy) ? policy : DEFAULT_SIGN_IN_POLICY;
+}
+/** Unsupported providers and missing or unknown channel policies require invitation. */
+export function channelPolicyOf(manifest, provider) {
+    if (!CHANNEL_PROVIDERS.some((supported) => supported === provider)) {
+        return DEFAULT_SIGN_IN_POLICY;
+    }
+    const policy = manifest.signIn?.channels?.[provider];
+    return isSignInPolicy(policy) ? policy : DEFAULT_SIGN_IN_POLICY;
+}
+function serialize(value, indent, depth) {
+    if (Array.isArray(value)) {
+        const items = value.map((item) => serialize(item ?? null, indent, depth + 1));
+        return wrap("[", "]", items, indent, depth);
+    }
+    if (typeof value === "object" && value !== null) {
+        const record = value;
+        const separator = indent === undefined ? ":" : ": ";
+        const entries = Object.keys(record)
+            .filter((key) => record[key] !== undefined)
+            .sort()
+            .map((key) => `${JSON.stringify(key)}${separator}${serialize(record[key], indent, depth + 1)}`);
+        return wrap("{", "}", entries, indent, depth);
+    }
+    return JSON.stringify(value) ?? "null";
+}
+function wrap(open, close, items, indent, depth) {
+    if (items.length === 0) {
+        return `${open}${close}`;
+    }
+    if (indent === undefined) {
+        return `${open}${items.join(",")}${close}`;
+    }
+    const inner = indent.repeat(depth + 1);
+    return `${open}\n${inner}${items.join(`,\n${inner}`)}\n${indent.repeat(depth)}${close}`;
+}
+/**
+ * Node's crypto, loaded when a hash is computed rather than when this module is imported: workflow
+ * files import entity declarations, and the Workflow SDK bundles what they import for a runtime
+ * without Node built-ins.
+ */
+function nodeCrypto() {
+    return process.getBuiltinModule("node:crypto");
+}
+/** JSON with object keys sorted at every level and no whitespace: the input of the manifest hash. */
+export function canonicalJson(value) {
+    return serialize(value, undefined, 0);
+}
+/** The manifest as a file: canonical key order, two-space indentation and a final newline. */
+export function formatManifest(manifest) {
+    return `${serialize(encodeManifest(manifest), "  ", 0)}\n`;
+}
+/** The hash of a manifest, computed over its canonical JSON without the `hash` field. */
+export function manifestHash(manifest) {
+    const body = Object.fromEntries(Object.entries(manifest).filter(([key]) => key !== "hash"));
+    const digest = nodeCrypto()
+        .createHash("sha256")
+        .update(canonicalJson(body), "utf8")
+        .digest("hex");
+    return `sha256:${digest}`;
+}
+function propertyManifest({ name, definition }) {
+    return {
+        name,
+        type: definition.type,
+        ...(definition.column !== undefined ? { column: definition.column } : {}),
+        ...(definition.scope !== undefined ? { scope: definition.scope } : {}),
+        label: definition.label ?? humanize(name),
+        ...(definition.description !== undefined ? { description: definition.description } : {}),
+        optional: definition.optional,
+        unique: definition.unique,
+        managed: definition.managed,
+        ...("default" in definition ? { default: definition.default } : {}),
+        ...(definition.display !== undefined ? { display: definition.display } : {}),
+        ...(definition.renamedFrom !== undefined ? { renamedFrom: definition.renamedFrom } : {}),
+        ...(definition.min !== undefined ? { min: definition.min } : {}),
+        ...(definition.max !== undefined ? { max: definition.max } : {}),
+        ...(definition.maxLength !== undefined ? { maxLength: definition.maxLength } : {}),
+        ...(definition.accept !== undefined ? { accept: definition.accept } : {}),
+        ...(definition.maxBytes !== undefined ? { maxBytes: definition.maxBytes } : {}),
+        ...(definition.items !== undefined ? { items: definition.items } : {}),
+        ...(definition.options !== undefined
+            ? {
+                options: definition.options.map((option) => ({
+                    value: option.value,
+                    label: option.label,
+                    description: option.description ?? "",
+                })),
+            }
+            : {}),
+    };
+}
+/**
+ * `stored` says whether both ends are stored: only then does a `rel.one` have a key column, and so
+ * an optionality and a delete rule.
+ */
+function relationshipManifest(input) {
+    const { resolved, stored } = input;
+    const { name, relationship, target } = resolved;
+    const common = {
+        name,
+        to: target ?? "",
+        inverse: relationship.inverse,
+        phrase: relationship.phrase ?? [DEFAULT_PHRASE, DEFAULT_PHRASE],
+        description: relationship.description,
+    };
+    if (relationship.cardinality === "many") {
+        return { ...common, cardinality: "many", ordered: relationship.ordered };
+    }
+    return {
+        ...common,
+        cardinality: "one",
+        ...(stored
+            ? { optional: relationship.optional, onDelete: relationship.onDelete ?? "restrict" }
+            : {}),
+        ...(relationship.on === undefined
+            ? {}
+            : {
+                on: {
+                    property: Object.keys(relationship.on)[0],
+                    targetProperty: Object.values(relationship.on)[0],
+                },
+            }),
+    };
+}
+/**
+ * The metrics of an entity, of one that passed `check`. A warehouse-backed property's column is its
+ * `column`; a stored property has none, and its column in the replication view is its wire name.
+ * Conditions name columns too, and so does `balanceOver`, which comes from the metric's own
+ * aggregates, top-level or inside arithmetic: `check` lets them name one property at most.
+ */
+export function metricsManifest(resolved) {
+    const columns = new Map(resolved.properties.map((property) => [
+        property.name,
+        property.definition.column ?? property.name,
+    ]));
+    return Object.entries(resolved.entity.definition.metrics ?? {}).map(([name, metric]) => {
+        const [balance] = balancesOf(metric);
+        return {
+            name,
+            label: metric.label ?? humanize(name),
+            description: metric.description ?? "",
+            unit: metric.unit ?? "number",
+            format: metric.format ??
+                (metric.unit === "currency"
+                    ? "currency"
+                    : metric.unit === "percent"
+                        ? "percent"
+                        : "decimal"),
+            expression: metricExpression(metric, columns),
+            ...(balance === undefined ? {} : { balanceOver: columns.get(balance) ?? balance }),
+        };
+    });
+}
+/** `warehouseBacked` names the ontology's warehouse-backed entities, which relationships may target. */
+function entityManifest(input) {
+    const { resolved, warehouseBacked } = input;
+    const { definition } = resolved.entity;
+    const storedOwner = definition.source === undefined;
+    const metrics = metricsManifest(resolved);
+    return {
+        // A warehouse-backed entity always lists its metrics; a stored entity only when it has some.
+        ...(definition.source === undefined ? {} : { source: definition.source, metrics }),
+        ...(definition.source === undefined && metrics.length > 0 ? { metrics } : {}),
+        id: definition.id,
+        name: resolved.name,
+        label: definition.label,
+        plural: definition.plural,
+        title: definition.title,
+        description: definition.description,
+        builtIn: resolved.builtIn,
+        ...(definition.renamedFrom !== undefined ? { renamedFrom: definition.renamedFrom } : {}),
+        ...(definition.guide !== undefined ? { guide: definition.guide } : {}),
+        properties: resolved.properties.map(propertyManifest),
+        relationships: resolved.relationships.map((relationship) => relationshipManifest({
+            resolved: relationship,
+            stored: storedOwner && !warehouseBacked.has(relationship.target ?? ""),
+        })),
+        indexes: resolved.indexes.map((index) => ({
+            properties: [...index.properties],
+            unique: index.unique,
+        })),
+        actions: resolved.actions.map((action) => ({
+            name: action.name,
+            description: action.action.description,
+            permission: action.permission,
+            input: action.input ?? {},
+            ...(action.action.retryOnDeadlock === undefined
+                ? {}
+                : { retryOnDeadlock: action.action.retryOnDeadlock }),
+            ...(action.writes === undefined ? {} : { writes: [...action.writes] }),
+            ...(action.connections.length > 0 ? { connections: [...action.connections] } : {}),
+            ...(action.action.files?.length ? { files: [...action.action.files] } : {}),
+            ...(action.hints !== undefined ? { hints: { ...action.hints } } : {}),
+        })),
+        permissions: { ...resolved.permissions },
+        ...(resolved.writes === "actions" ? { writes: "actions" } : {}),
+    };
+}
+/** Builds the manifest of a resolved ontology that passed `check`. */
+export function buildManifest(input) {
+    const connections = input.connections ?? [];
+    const emails = input.emails ?? {};
+    const metrics = input.metrics ?? [];
+    const workflows = input.workflows ?? [];
+    const warehouseBacked = new Set(input.entities
+        .filter((candidate) => candidate.entity.definition.source !== undefined)
+        .map((candidate) => candidate.name));
+    const body = {
+        ...(input.feedback === undefined ? {} : { feedback: input.feedback }),
+        version: MANIFEST_VERSION,
+        runtimeCapabilities: [
+            "pipeline-workload-tokens-v1",
+            "workspace-app-previews-v1",
+            "workspace-app-preview-workflows-v1",
+            "workspace-app-local-previews-v1",
+        ],
+        entities: input.entities.map((candidate) => entityManifest({ resolved: candidate, warehouseBacked })),
+        roles: input.roles.map((candidate) => ({
+            name: candidate.name,
+            description: candidate.description,
+            builtIn: candidate.name === MEMBER_ROLE || candidate.name === FEEDBACK_REPORTER_ROLE,
+            permissions: [...candidate.permissions],
+            ...((candidate.scopes ?? []).length > 0
+                ? {
+                    scopes: (candidate.scopes ?? []).map((scope) => ({
+                        permission: scope.permission,
+                        where: scope.where,
+                    })),
+                }
+                : {}),
+        })),
+        signIn: {
+            policy: input.signIn.policy,
+            ...(input.signIn.browser === undefined ? {} : { browser: input.signIn.browser }),
+            ...(input.signIn.onNewUser === undefined ? {} : { onNewUser: input.signIn.onNewUser }),
+            ...(input.signIn.codeLink === undefined ? {} : { codeLink: input.signIn.codeLink }),
+            ...(Object.keys(input.signIn.channels ?? {}).length > 0
+                ? { channels: input.signIn.channels }
+                : {}),
+        },
+        ...(Object.keys(emails).length > 0 ? { emails } : {}),
+        ...(input.chat === undefined ? {} : { chat: input.chat }),
+        ...(connections.length > 0
+            ? {
+                connections: connections.map((candidate) => ({
+                    key: candidate.key,
+                    description: candidate.description,
+                    ...(candidate.delivers ? { delivers: true } : {}),
+                })),
+            }
+            : {}),
+        ...(metrics.length > 0 ? { metrics } : {}),
+        ...(workflows.length > 0 ? { workflows } : {}),
+    };
+    return { ...body, hash: manifestHash(encodeManifest({ ...body, hash: "" })) };
+}
+/** The keys of every connection the manifest's actions call, without duplicates. */
+export function actionConnectionKeys(manifest) {
+    return [
+        ...new Set(manifest.entities.flatMap((entity) => entity.actions.flatMap((candidate) => candidate.connections ?? []))),
+    ];
+}