@decionis/agent-safe-pipeline 0.4.0 → 0.5.0

package/dist/profile/ApiProfile.js

@@ -0,0 +1,755 @@
+import { z } from "zod";
+import { TargetPreconditionSchema } from "../intent/TargetPrecondition.js";
+/**
+ * `agent-safe.profile.api/1`: a platform API described as data, so that every
+ * component that turns one of its calls into an intent turns it into the same
+ * one. A profile maps method + path (and, where an API overloads a path, an
+ * exact query value) to an action type, and names the facts a decision reads
+ * by JSON pointer into the call. The gateway reads it to govern an agent's
+ * call; a native executor's `prepare` reads it to describe the call it is
+ * about to make. One mapping, no code coupling between them.
+ *
+ * An operation may also say where the subject sits (the customer a call is
+ * for): in the call, and, for a read, in each item of its answer. A component
+ * that pins a session to one subject checks a read against it, and states the
+ * subject to the authority for a write. A read is an operation only for that:
+ * it is checked, never decided.
+ *
+ * A write may also name the read that states its target's version (an ETag,
+ * a row version), and where that read's answer states it: a component that
+ * binds the target's state reads it once before the authority is asked, and
+ * the version rides into the intent as its precondition.
+ */
+export const API_PROFILE_CONTRACT = "agent-safe.profile.api/1";
+export const API_PROFILE_SCHEMA_ID = "https://github.com/decionis/agent-safe-pipeline/blob/master/spec/profiles/api/v1/schema.json";
+/** The methods a profile governs: each operation of one is decided by the authority. */
+export const API_PROFILE_METHODS = ["POST", "PUT", "PATCH", "DELETE"];
+/** The one read method an operation may name: checked for its subject, never decided. */
+export const API_PROFILE_READ_METHOD = "GET";
+/**
+ * Fact names a profile may not use. The first group is what the gateway
+ * already states in an intent's context; the second is what the Decionis
+ * authority states itself, or reads from the request rather than the context,
+ * so a fact of that name would be shadowed or refused there.
+ */
+export const RESERVED_FACT_NAMES = [
+    "request_sha256",
+    "request_hmac_sha256",
+    "body_sha256",
+    "body_bytes",
+    "content_type",
+    "body_embedded",
+    "ingress",
+    "claimed_principal",
+    "api_profile",
+    "agent_safe",
+    "action_context",
+    "amount",
+    "risk_score",
+    "channel",
+    "objective_profile",
+    "mode",
+    "decision_band",
+    "transaction_type",
+    "workflow_key",
+    "vertical_pack",
+    "policy_version",
+    "org_id",
+    "decision_type",
+    "decision_domain",
+    "signals",
+    "signal_provenance",
+    "history",
+    "override",
+    "evidence",
+    "attachments",
+    "attachment_count",
+    "policy",
+    "context",
+    "intake",
+    "runtime_attribution",
+    "session",
+];
+/** The most elements one `*` pointer collects; more is not a fact, it is a payload. */
+export const MAX_FACT_ELEMENTS = 100;
+/** The longest string a fact carries; a longer value is not stated. */
+export const MAX_FACT_STRING = 1000;
+/** The longest subject: an identifier, never a payload. */
+export const MAX_SUBJECT_LENGTH = 200;
+const PLACEHOLDER = /\{([A-Z]\w{0,63})\}/gi;
+const TEMPLATE = /^(\/[^/?#%\\\s]+)+$/;
+const POINTER = /^\/(path|query|body)(\/.*)?$/;
+const RESPONSE_POINTER = /^\/body(\/.*)?$/;
+/** Into a read's answer: its JSON body, or one response header by its lower-case name. */
+const STATE_POINTER = /^\/(body(\/.*)?|headers\/[a-z0-9][a-z0-9-]{0,63})$/;
+const name = z.string().regex(/^[a-z][a-z0-9_]{0,63}$/);
+const projectionText = z.string().trim().min(1).max(120);
+export const ApiPolicyProjectionSchema = z.strictObject({
+    decision_type: projectionText,
+    transaction_type: projectionText.nullable(),
+    workflow_key: projectionText.nullable(),
+    channel: projectionText.nullable(),
+});
+/** A query parameter's name as a subject rule names it: `$filter` as well as `sku`. */
+const queryName = z.string().regex(/^\$?[a-z][\w.-]{0,63}$/i);
+/**
+ * Where an operation's subject sits, and what else a call or an answer may
+ * carry around it:
+ *
+ * - `request`, a pointer into the call like a fact's, with no `*`;
+ * - `response`, a pointer into a successful answer's JSON body, where one `*`
+ *   reaches every item of a list;
+ * - `query`, for a read, the one query parameter that must state the subject,
+ *   exactly as `template` writes it with `{subject}` in place of the
+ *   session's subject (`customerNumber eq '{subject}'`);
+ * - `parameters`, for a read, every other query parameter it may carry;
+ * - `envelope`, beside a `response` pointer through `*`, the keys the object
+ *   holding the list may carry besides the list.
+ */
+export const ApiSubjectSchema = z.strictObject({
+    request: z.string().max(300).regex(POINTER).optional(),
+    response: z.string().max(300).regex(RESPONSE_POINTER).optional(),
+    query: z
+        .strictObject({
+        name: queryName,
+        template: z.string().min(1).max(300),
+    })
+        .optional(),
+    parameters: z.array(queryName).max(32).optional(),
+    envelope: z.array(z.string().min(1).max(100)).max(32).optional(),
+});
+const operationId = z
+    .string()
+    .regex(/^[a-z][A-Za-z0-9]*(\.[a-z][A-Za-z0-9]*)*$/)
+    .max(120);
+/**
+ * Where a write's target states its version: `read`, a read in the same
+ * profile whose path placeholders the write's path also has, so the read can
+ * be made from the write's own call; `version`, a pointer into the read's
+ * answer, `{ body, headers }`, with no `*`; and `state`, where the same answer
+ * states the target's state, when a transition rule reads one.
+ */
+export const ApiPreconditionSchema = z.strictObject({
+    read: operationId,
+    version: z.string().max(300).regex(STATE_POINTER),
+    state: z.string().max(300).regex(STATE_POINTER).optional(),
+});
+export const ApiOperationSchema = z.strictObject({
+    /** The operation's name in the profile, unique, dotted lower camel case. */
+    id: operationId,
+    method: z.enum([...API_PROFILE_METHODS, API_PROFILE_READ_METHOD]),
+    /** A path template: literal text and `{name}` placeholders, each within one segment. */
+    path: z.string().max(500).regex(TEMPLATE),
+    /** Exact query values the call must carry to be this operation (an API that overloads a path). */
+    query: z.record(z.string().regex(/^[a-z][\w.-]{0,63}$/), z.string().max(200)).optional(),
+    /** The intent's action type. */
+    action: z
+        .string()
+        .max(120)
+        .regex(/^[a-z][a-z0-9._:-]*$/),
+    summary: z.string().trim().min(1).max(300),
+    /** Fact name → RFC 6901 pointer into `{ path, query, body }`; one `*` segment collects an array. */
+    facts: z.record(name, z.string().max(300).regex(POINTER)),
+    /** The policy path the authority decides the call under, when the profile states one. */
+    policy_projection: ApiPolicyProjectionSchema.nullable(),
+    /** Where the call's subject sits; required of a read, optional for a write. */
+    subject: ApiSubjectSchema.optional(),
+    /** For a write, the read that states its target's version. */
+    precondition: ApiPreconditionSchema.optional(),
+});
+export const ApiProfileDefinitionSchema = z.strictObject({
+    profile: z.literal(API_PROFILE_CONTRACT),
+    /** `<platform>/<api>/<version>`, the profile's directory under `profiles/`. */
+    id: z
+        .string()
+        .regex(/^[a-z][a-z0-9]*\/[a-z][a-z0-9]*\/v\d+(\.\d+)?$/)
+        .max(120),
+    platform: z
+        .string()
+        .regex(/^[a-z][a-z0-9-]*$/)
+        .max(80),
+    title: z.string().trim().min(1).max(200),
+    /** Path templates an operation's path may follow; `""` is the bare path. Tried in order. */
+    prefixes: z
+        .array(z.union([z.literal(""), z.string().max(300).regex(TEMPLATE)]))
+        .min(1)
+        .max(8),
+    operations: z.array(ApiOperationSchema).min(1).max(200),
+});
+/** Where a template states the subject. */
+const SUBJECT_PLACEHOLDER = "{subject}";
+export class ApiProfileError extends Error {
+    code;
+    detail;
+    constructor(code, detail) {
+        super(code);
+        this.code = code;
+        this.detail = detail;
+        this.name = "ApiProfileError";
+    }
+}
+/**
+ * One profile, validated and compiled. Matching is deterministic and total:
+ * the first operation, in profile order, whose method, path and query match
+ * is the call's operation; a call no operation matches is not described by
+ * the profile and the caller decides what that means.
+ */
+export class ApiProfile {
+    definition;
+    compiled;
+    constructor(definition) {
+        this.definition = definition;
+        const ids = new Set();
+        const signatures = new Set();
+        this.compiled = definition.operations.map((operation) => {
+            if (ids.has(operation.id))
+                throw new ApiProfileError("API_PROFILE_INVALID", `duplicate operation ${operation.id}`);
+            ids.add(operation.id);
+            const signature = `${operation.method} ${operation.path.replace(PLACEHOLDER, "{}")} ${JSON.stringify(Object.entries(operation.query ?? {}).sort(([a], [b]) => a.localeCompare(b)))}`;
+            if (signatures.has(signature))
+                throw new ApiProfileError("API_PROFILE_INVALID", `operation ${operation.id} repeats another operation's method, path and query`);
+            signatures.add(signature);
+            for (const fact of Object.keys(operation.facts)) {
+                if (RESERVED_FACT_NAMES.includes(fact))
+                    throw new ApiProfileError("API_PROFILE_INVALID", `operation ${operation.id} names the reserved fact ${fact}`);
+            }
+            for (const pointer of Object.values(operation.facts))
+                ApiProfile.pointerSegments(pointer, operation.id);
+            ApiProfile.subjectRules(operation);
+            ApiProfile.preconditionRules(operation, definition.operations);
+            const matchers = [];
+            const placeholders = [];
+            for (const prefix of definition.prefixes) {
+                const { pattern, names } = ApiProfile.compile(`${prefix}${operation.path}`, operation.id);
+                matchers.push(pattern);
+                placeholders.push(names);
+            }
+            return {
+                definition: operation,
+                matchers,
+                loose: matchers.map((matcher) => new RegExp(matcher.source, "i")),
+                beneath: matchers.map((matcher) => new RegExp(`${matcher.source.slice(0, -1)}/`, "i")),
+                placeholders,
+            };
+        });
+    }
+    /** Validates a definition (closed schema, unique operations, pointers, reserved names) and compiles it. */
+    static parse(value) {
+        const parsed = ApiProfileDefinitionSchema.safeParse(value);
+        if (!parsed.success)
+            throw new ApiProfileError("API_PROFILE_INVALID", parsed.error.issues
+                .slice(0, 3)
+                .map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`)
+                .join("; "));
+        return new ApiProfile(parsed.data);
+    }
+    get id() {
+        return this.definition.id;
+    }
+    get platform() {
+        return this.definition.platform;
+    }
+    /**
+     * Every action type the profile's writes can produce, for a registry to be
+     * sealed over. A read's action names it in reports; it is never an intent.
+     */
+    actions() {
+        return [
+            ...new Set(this.definition.operations
+                .filter((operation) => !ApiProfile.isRead(operation))
+                .map((operation) => operation.action)),
+        ];
+    }
+    /** Whether an operation is a read: checked for its subject, never decided. */
+    static isRead(operation) {
+        return operation.method === API_PROFILE_READ_METHOD;
+    }
+    /**
+     * A call against the session's subject, before it is sent: `MATCH`, or why
+     * not. A read that names the query parameters it may carry carries no
+     * other (`QUERY_PARAMETER_REFUSED`); a read that names its subject query
+     * states the session's subject there and nothing else, so a list can be
+     * asked only for the session's own records; and the subject at the
+     * operation's request pointer is the session's.
+     */
+    checkRequest(match, query, subject) {
+        const definition = this.operation(match.operation);
+        const declared = definition?.subject;
+        if (declared?.parameters !== undefined) {
+            const allowed = new Set([
+                ...declared.parameters,
+                ...(declared.query === undefined ? [] : [declared.query.name]),
+                ...Object.keys(definition?.query ?? {}),
+            ]);
+            if (Object.keys(query).some((name) => !allowed.has(name)))
+                return "QUERY_PARAMETER_REFUSED";
+        }
+        if (declared?.query !== undefined) {
+            const stated = ApiProfile.checkQuery(declared.query.template, query[declared.query.name], subject);
+            if (stated !== "MATCH")
+                return stated;
+        }
+        if (match.subject === undefined)
+            return "MATCH";
+        if (match.subject === null)
+            return "SUBJECT_ABSENT";
+        return match.subject === subject ? "MATCH" : "SUBJECT_MISMATCH";
+    }
+    /**
+     * A subject query parameter against its template: absent is
+     * `SUBJECT_ABSENT`; given twice, or anything but the template with one
+     * literal in place of `{subject}`, is `QUERY_PARAMETER_REFUSED`, which is
+     * what a second predicate beside the subject's is; a literal naming
+     * another subject is `SUBJECT_MISMATCH`. A `'` inside the literal is
+     * written doubled, as an OData string literal writes it; a single one ends
+     * the literal, so it refuses the call.
+     */
+    static checkQuery(template, value, subject) {
+        if (value === undefined)
+            return "SUBJECT_ABSENT";
+        if (typeof value !== "string")
+            return "QUERY_PARAMETER_REFUSED";
+        const at = template.indexOf(SUBJECT_PLACEHOLDER);
+        const prefix = template.slice(0, at);
+        const suffix = template.slice(at + SUBJECT_PLACEHOLDER.length);
+        if (value.length < prefix.length + suffix.length ||
+            !value.startsWith(prefix) ||
+            !value.endsWith(suffix)) {
+            return "QUERY_PARAMETER_REFUSED";
+        }
+        const literal = value.slice(prefix.length, value.length - suffix.length);
+        let named = "";
+        for (let index = 0; index < literal.length; index += 1) {
+            const character = literal[index];
+            if (character === "'") {
+                if (literal[index + 1] !== "'")
+                    return "QUERY_PARAMETER_REFUSED";
+                index += 1;
+            }
+            named += character;
+        }
+        return named === subject ? "MATCH" : "SUBJECT_MISMATCH";
+    }
+    /**
+     * A successful answer, to a read or a write, against the session's
+     * subject, before any of it is relayed: every item the operation's response
+     * pointer reaches must name the subject. One item naming another is
+     * `RESPONSE_SUBJECT_MISMATCH`, one naming none `RESPONSE_SUBJECT_ABSENT`,
+     * and an answer the pointer cannot be walked into (not JSON, or no list
+     * where the `*` stands) `RESPONSE_UNREADABLE`. Beside a list, the object
+     * that holds it may carry only the keys the operation's `envelope` names,
+     * so a count or a summary about other subjects is `RESPONSE_KEY_REFUSED`.
+     * Nothing is filtered: a partial answer would look complete. An empty list
+     * names no one and matches. Null when the operation names no response
+     * subject, so there is nothing to check.
+     */
+    checkResponse(operationId, body, subject) {
+        const pointer = this.operation(operationId)?.subject?.response;
+        if (pointer === undefined)
+            return null;
+        if (body === undefined)
+            return "RESPONSE_UNREADABLE";
+        const tokens = ApiProfile.pointerSegments(pointer, operationId);
+        const root = { body };
+        const wildcard = tokens.indexOf("*");
+        const items = wildcard === -1
+            ? [ApiProfile.walk(root, tokens)]
+            : ApiProfile.walkList(root, tokens.slice(0, wildcard), tokens.slice(wildcard + 1));
+        if (items === null)
+            return "RESPONSE_UNREADABLE";
+        if (wildcard > 1) {
+            const holder = ApiProfile.walk(root, tokens.slice(0, wildcard - 1));
+            const list = tokens[wildcard - 1];
+            const envelope = this.operation(operationId)?.subject?.envelope ?? [];
+            if (holder !== null &&
+                typeof holder === "object" &&
+                !Array.isArray(holder) &&
+                Object.keys(holder).some((key) => key !== list && !envelope.includes(key))) {
+                return "RESPONSE_KEY_REFUSED";
+            }
+        }
+        let absent = false;
+        for (const item of items) {
+            const named = ApiProfile.subjectOf(item);
+            if (named === null)
+                absent = true;
+            else if (named !== subject)
+                return "RESPONSE_SUBJECT_MISMATCH";
+        }
+        return absent ? "RESPONSE_SUBJECT_ABSENT" : "MATCH";
+    }
+    operation(id) {
+        return this.definition.operations.find((operation) => operation.id === id) ?? null;
+    }
+    /**
+     * The operation a method, path and query select, before any body is read:
+     * what the gateway needs to decide whether to govern a call.
+     */
+    operationFor(method, path, query = {}) {
+        return this.select(method, path, query)?.operation.definition ?? null;
+    }
+    /**
+     * Whether a call reads like one of this method's operations without
+     * matching it exactly: its path in another letter case, or with a literal
+     * percent-encoded. An upstream that folds case or decodes before it routes
+     * would serve it as that operation, so a component that checks reads
+     * refuses it rather than let it through unchecked. A path that does not
+     * decode resembles everything.
+     */
+    resembles(method, path) {
+        let decoded;
+        try {
+            decoded = decodeURIComponent(path);
+        }
+        catch {
+            return true;
+        }
+        const upper = method.toUpperCase();
+        return this.compiled.some((operation) => operation.definition.method === upper &&
+            operation.loose.some((matcher) => matcher.test(path) || matcher.test(decoded)));
+    }
+    /**
+     * Whether a call's path goes on below one of this method's operations
+     * without being an operation itself, in any letter case: a count
+     * (`/customers/$count`), a navigation or a media stream beneath a record.
+     * What it answers is not what the operation's subject rule checks, so a
+     * component that checks reads refuses it.
+     */
+    beneath(method, path) {
+        let decoded;
+        try {
+            decoded = decodeURIComponent(path);
+        }
+        catch {
+            return true;
+        }
+        const upper = method.toUpperCase();
+        return this.compiled.some((operation) => operation.definition.method === upper &&
+            operation.beneath.some((matcher) => matcher.test(path) || matcher.test(decoded)));
+    }
+    /** The operation, action type, facts and policy projection of one call; null when no operation matches. */
+    match(request) {
+        const selected = this.select(request.method, request.path, request.query ?? {});
+        if (selected === null)
+            return null;
+        const { operation, parameters } = selected;
+        const root = {
+            path: parameters,
+            query: ApiProfile.queryRoot(request.query ?? {}),
+            ...(request.body === undefined ? {} : { body: request.body }),
+        };
+        const facts = {};
+        for (const [fact, pointer] of Object.entries(operation.definition.facts)) {
+            const value = ApiProfile.read(root, ApiProfile.pointerSegments(pointer, operation.definition.id));
+            if (value !== undefined)
+                facts[fact] = value;
+        }
+        const subjectPointer = operation.definition.subject?.request;
+        return {
+            profile: this.definition.id,
+            operation: operation.definition.id,
+            action: operation.definition.action,
+            facts,
+            policyProjection: operation.definition.policy_projection,
+            ...(subjectPointer === undefined
+                ? {}
+                : {
+                    subject: ApiProfile.subjectOf(ApiProfile.walk(root, ApiProfile.pointerSegments(subjectPointer, operation.definition.id))),
+                }),
+        };
+    }
+    /**
+     * The read a write's precondition names, as the call to make: `GET`, the
+     * read's path under the prefix the write matched, each placeholder filled
+     * with the write's own text for it, exactly as the write's call wrote it.
+     * Null when the call matches no write, or its operation names no
+     * precondition. The component makes the read; the profile makes no call.
+     */
+    stateRead(request) {
+        const selected = this.select(request.method, request.path, request.query ?? {});
+        const precondition = selected?.operation.definition.precondition;
+        if (selected === null || precondition === undefined)
+            return null;
+        const read = this.operation(precondition.read);
+        const template = `${this.definition.prefixes[selected.prefix]}${read.path}`;
+        return {
+            method: API_PROFILE_READ_METHOD,
+            path: template.replace(PLACEHOLDER, (_, name) => selected.raw[name]),
+            ...(read.query === undefined ? {} : { query: { ...read.query } }),
+        };
+    }
+    /**
+     * The precondition a write's read answered: the version at the operation's
+     * pointer, a string or a finite number as a string, within the
+     * precondition's bounds; the state beside it when the operation names
+     * where; which read said so, as `<profile>#<read>`; and when. Null when the
+     * operation names no precondition, or the answer states no usable version:
+     * a component that binds the target's state refuses then, rather than bind
+     * none. A state the answer does not state is left out.
+     */
+    precondition(operationId, answer, readAt) {
+        const declared = this.operation(operationId)?.precondition;
+        if (declared === undefined)
+            return null;
+        const root = {
+            headers: { ...answer.headers },
+            ...(answer.body === undefined ? {} : { body: answer.body }),
+        };
+        const at = (pointer) => {
+            if (pointer === undefined)
+                return undefined;
+            const value = ApiProfile.walk(root, ApiProfile.pointerSegments(pointer, operationId));
+            if (typeof value === "string")
+                return value;
+            return typeof value === "number" && Number.isFinite(value) ? String(value) : undefined;
+        };
+        const state = at(declared.state);
+        const parsed = TargetPreconditionSchema.safeParse({
+            version: at(declared.version),
+            ...(state === undefined ? {} : { state }),
+            source: `${this.definition.id}#${declared.read}`,
+            read_at: readAt.toISOString(),
+        });
+        return parsed.success ? parsed.data : null;
+    }
+    select(method, path, query) {
+        const upper = method.toUpperCase();
+        if (!path.startsWith("/") || /[?#]/.test(path))
+            return null;
+        for (const operation of this.compiled) {
+            if (operation.definition.method !== upper)
+                continue;
+            if (!ApiProfile.queryMatches(operation.definition.query ?? {}, query))
+                continue;
+            for (let index = 0; index < operation.matchers.length; index += 1) {
+                const found = operation.matchers[index].exec(path);
+                if (found === null)
+                    continue;
+                const parameters = {};
+                const raw = {};
+                let decodable = true;
+                operation.placeholders[index].forEach((placeholder, position) => {
+                    const text = found[position + 1] ?? "";
+                    const decoded = ApiProfile.decode(text);
+                    raw[placeholder] = text;
+                    if (decoded === null)
+                        decodable = false;
+                    else
+                        parameters[placeholder] = decoded;
+                });
+                if (decodable)
+                    return { operation, parameters, prefix: index, raw };
+            }
+        }
+        return null;
+    }
+    /** A template as an anchored expression: placeholders take one segment's text, never a `/`. */
+    static compile(template, operation) {
+        const names = [];
+        let source = "";
+        let last = 0;
+        for (const found of template.matchAll(PLACEHOLDER)) {
+            const placeholder = found[1];
+            if (names.includes(placeholder))
+                throw new ApiProfileError("API_PROFILE_INVALID", `operation ${operation} repeats the placeholder ${placeholder}`);
+            names.push(placeholder);
+            source += ApiProfile.escape(template.slice(last, found.index)) + "([^/()]+)";
+            last = (found.index ?? 0) + found[0].length;
+        }
+        source += ApiProfile.escape(template.slice(last));
+        if (/[{}]/.test(template.replace(PLACEHOLDER, "")))
+            throw new ApiProfileError("API_PROFILE_INVALID", `operation ${operation} has a malformed placeholder`);
+        return { pattern: new RegExp(`^${source}$`), names };
+    }
+    static escape(text) {
+        return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    }
+    /** A placeholder's value: percent-decoded, OData quotes removed; null when it does not decode. */
+    static decode(raw) {
+        let value;
+        try {
+            value = decodeURIComponent(raw);
+        }
+        catch {
+            return null;
+        }
+        if (value.length >= 2 && value.startsWith("'") && value.endsWith("'"))
+            value = value.slice(1, -1);
+        if (value === "" || value === "." || value === ".." || value.includes("/"))
+            return null;
+        return value;
+    }
+    static queryMatches(expected, query) {
+        return Object.entries(expected).every(([key, value]) => {
+            const actual = query[key];
+            return typeof actual === "string" ? actual === value : false;
+        });
+    }
+    static queryRoot(query) {
+        const root = {};
+        for (const [key, value] of Object.entries(query)) {
+            if (key === "__proto__" || key === "constructor" || key === "prototype")
+                continue;
+            root[key] = typeof value === "string" ? value : [...value];
+        }
+        return root;
+    }
+    /**
+     * What a definition must also be about subjects: a subject names where it
+     * sits, in the call, its query or its answer; a read names one and states
+     * no fact or policy path, since it is never decided; only a read names a
+     * subject query or the parameters it may carry; a request subject is one
+     * value, so its pointer has no `*`; a subject query's template states the
+     * subject once; an envelope stands beside a list.
+     */
+    static subjectRules(operation) {
+        const subject = operation.subject;
+        const refuse = (detail) => {
+            throw new ApiProfileError("API_PROFILE_INVALID", `operation ${operation.id} ${detail}`);
+        };
+        if (subject !== undefined &&
+            subject.request === undefined &&
+            subject.response === undefined &&
+            subject.query === undefined)
+            refuse("names an empty subject");
+        if (ApiProfile.isRead(operation)) {
+            if (subject === undefined)
+                refuse("is a read that names no subject");
+            if (Object.keys(operation.facts).length > 0 || operation.policy_projection !== null)
+                refuse("is a read: it states no fact and no policy projection");
+        }
+        else if (subject?.query !== undefined || subject?.parameters !== undefined) {
+            refuse("is a write: only a read names its query parameters");
+        }
+        if (subject?.request !== undefined) {
+            if (ApiProfile.pointerSegments(subject.request, operation.id).includes("*"))
+                refuse("names a request subject through *");
+        }
+        const response = subject?.response === undefined
+            ? null
+            : ApiProfile.pointerSegments(subject.response, operation.id);
+        const template = subject?.query?.template;
+        if (template !== undefined && template.split(SUBJECT_PLACEHOLDER).length !== 2)
+            refuse("has a subject query template that does not state {subject} once");
+        if (subject?.envelope !== undefined && !(response ?? []).includes("*"))
+            refuse("names an envelope without a list to stand beside");
+    }
+    /**
+     * What a precondition must be: a write's, naming a read in the same
+     * profile, whose path placeholders the write's path all has, so the read
+     * is made from the write's own call; and pointers through no `*`, since a
+     * version is one value.
+     */
+    static preconditionRules(operation, operations) {
+        const precondition = operation.precondition;
+        if (precondition === undefined)
+            return;
+        const refuse = (detail) => {
+            throw new ApiProfileError("API_PROFILE_INVALID", `operation ${operation.id} ${detail}`);
+        };
+        if (ApiProfile.isRead(operation))
+            refuse("is a read: only a write names a precondition");
+        const read = operations.find((candidate) => candidate.id === precondition.read);
+        if (read === undefined || !ApiProfile.isRead(read))
+            refuse(`names a precondition read ${precondition.read} that is not a read in the profile`);
+        const placeholders = (path) => [...path.matchAll(PLACEHOLDER)].map((found) => found[1]);
+        const own = placeholders(operation.path);
+        if (placeholders(read.path).some((name) => !own.includes(name)))
+            refuse(`names a precondition read whose path has a placeholder the write's has not`);
+        for (const pointer of [precondition.version, precondition.state]) {
+            if (pointer !== undefined && ApiProfile.pointerSegments(pointer, operation.id).includes("*"))
+                refuse("names a precondition pointer through *");
+        }
+    }
+    /** A subject as stated: a string or a finite number, as a string, within the bound; else null. */
+    static subjectOf(value) {
+        const text = typeof value === "string"
+            ? value
+            : typeof value === "number" && Number.isFinite(value)
+                ? String(value)
+                : null;
+        return text === null || text.length === 0 || text.length > MAX_SUBJECT_LENGTH ? null : text;
+    }
+    /** Each element's value through a `*`; null when there is no list where the `*` stands. */
+    static walkList(root, before, after) {
+        const list = ApiProfile.walk(root, before);
+        if (!Array.isArray(list))
+            return null;
+        return list.map((element) => ApiProfile.walk(element, after));
+    }
+    /** RFC 6901 reference tokens, unescaped; one `*` token at most. */
+    static pointerSegments(pointer, operation) {
+        const tokens = pointer
+            .slice(1)
+            .split("/")
+            .map((token) => token.replaceAll("~1", "/").replaceAll("~0", "~"));
+        if (tokens.filter((token) => token === "*").length > 1 || /~[^01]|~$/.test(pointer))
+            throw new ApiProfileError("API_PROFILE_INVALID", `operation ${operation} has an invalid fact pointer ${pointer}`);
+        return tokens;
+    }
+    /**
+     * The value at a pointer, when it is statable: a string (at most 1000
+     * characters), a finite number or a boolean; or, through one `*`, an array
+     * of up to 100 of them, every element statable. Anything else is absent.
+     */
+    static read(root, tokens) {
+        const wildcard = tokens.indexOf("*");
+        if (wildcard === -1)
+            return ApiProfile.statable(ApiProfile.walk(root, tokens));
+        const list = ApiProfile.walk(root, tokens.slice(0, wildcard));
+        if (!Array.isArray(list) || list.length === 0 || list.length > MAX_FACT_ELEMENTS)
+            return undefined;
+        const values = [];
+        for (const element of list) {
+            const value = ApiProfile.statable(ApiProfile.walk(element, tokens.slice(wildcard + 1)));
+            if (value === undefined)
+                return undefined;
+            values.push(value);
+        }
+        return values;
+    }
+    static walk(value, tokens) {
+        let current = value;
+        for (const token of tokens) {
+            if (Array.isArray(current)) {
+                if (!/^(?:0|[1-9]\d{0,5})$/.test(token))
+                    return undefined;
+                current = current[Number(token)];
+            }
+            else if (current !== null && typeof current === "object") {
+                current = Object.hasOwn(current, token) ? current[token] : undefined;
+            }
+            else {
+                return undefined;
+            }
+            if (current === undefined)
+                return undefined;
+        }
+        return current;
+    }
+    static statable(value) {
+        if (typeof value === "string")
+            return value.length <= MAX_FACT_STRING ? value : undefined;
+        if (typeof value === "number")
+            return Number.isFinite(value) ? value : undefined;
+        if (typeof value === "boolean")
+            return value;
+        return undefined;
+    }
+}
+/** The published JSON Schema of a profile definition, generated from the validator above. */
+export function apiProfileJsonSchema() {
+    const generated = z.toJSONSchema(ApiProfileDefinitionSchema, {
+        target: "draft-2020-12",
+        io: "input",
+    });
+    const schema = { ...generated };
+    delete schema["$schema"];
+    return {
+        $schema: "https://json-schema.org/draft/2020-12/schema",
+        $id: API_PROFILE_SCHEMA_ID,
+        title: API_PROFILE_CONTRACT,
+        ...schema,
+    };
+}
+//# sourceMappingURL=ApiProfile.js.map