@blokjs/shared 2.1.0 → 2.2.1

package/dist/JoinContracts.js

@@ -0,0 +1,329 @@
+import { z } from "zod";
+import { CAPABILITY_EFFECTS } from "./CapabilityManifest.js";
+import { EVIDENCE_MAX_REQUIREMENTS, EvidenceRequirementSchema, parseEvidenceRecord, } from "./EvidenceContracts.js";
+import { CapabilityAuthoritySchema } from "./PermissionAlgebra.js";
+/** Version of the language-neutral branch-join contract. */
+export const JOIN_CONTRACT_VERSION = "1";
+export const JOIN_MAX_BRANCHES = 128;
+export const JOIN_MAX_OUTPUTS = 128;
+export const JOIN_MAX_SCHEMA_DEPTH = 8;
+export const JOIN_MAX_CONTRACT_BYTES = 64 * 1024;
+/** Version of the retry/resume idempotency contract. */
+export const RETRY_RESUME_IDEMPOTENCY_CONTRACT_VERSION = "1";
+export const RETRY_RESUME_MAX_ATTEMPTS = 20;
+export const RETRY_RESUME_MAX_RESUMES = 100;
+export const RETRY_RESUME_MAX_EVIDENCE = 64;
+const IDENTIFIER = /^[A-Za-z][A-Za-z0-9._:/-]{0,127}$/;
+const DIGEST = /^(sha256):[0-9a-f]{64}$|^(sha512):[0-9a-f]{128}$/i;
+const identifier = z.string().min(1).max(128).regex(IDENTIFIER, "must be a bounded identifier");
+const pathSegment = z.union([identifier, z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER)]);
+const jsonSchema = z.union([z.boolean(), z.record(z.unknown())]);
+export class JoinContractError extends Error {
+    reasonCode;
+    code = "JOIN_REJECTED";
+    constructor(reasonCode, message) {
+        super(`Join rejected (${reasonCode}): ${message}`);
+        this.reasonCode = reasonCode;
+        this.name = "JoinContractError";
+    }
+}
+export class RetryResumeContractError extends Error {
+    reasonCode;
+    code = "RETRY_RESUME_REJECTED";
+    constructor(reasonCode, message) {
+        super(`Retry/resume rejected (${reasonCode}): ${message}`);
+        this.reasonCode = reasonCode;
+        this.name = "RetryResumeContractError";
+    }
+}
+const joinBranchSchema = z.object({
+    id: identifier,
+    required: z.boolean(),
+    evidence: z.array(EvidenceRequirementSchema).max(EVIDENCE_MAX_REQUIREMENTS).optional(),
+});
+const joinOutputSchema = z.object({
+    id: identifier,
+    branchId: identifier,
+    path: z.array(pathSegment).max(64),
+    schema: jsonSchema,
+});
+export const JoinBranchObligationSchema = joinBranchSchema;
+export const JoinOutputDeclarationSchema = joinOutputSchema;
+export const JoinContractSchema = z
+    .object({
+    version: z.literal(JOIN_CONTRACT_VERSION),
+    id: identifier,
+    mode: z.enum(["all", "any"]),
+    branches: z.array(joinBranchSchema).min(1).max(JOIN_MAX_BRANCHES),
+    outputs: z.array(joinOutputSchema).max(JOIN_MAX_OUTPUTS),
+    authority: CapabilityAuthoritySchema.optional(),
+})
+    .superRefine((value, context) => {
+    const branchIds = new Set();
+    for (const [index, branch] of value.branches.entries()) {
+        if (branchIds.has(branch.id)) {
+            context.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["branches", index, "id"],
+                message: "branch ids must be unique",
+            });
+        }
+        branchIds.add(branch.id);
+    }
+    const outputIds = new Set();
+    for (const [index, output] of value.outputs.entries()) {
+        if (outputIds.has(output.id)) {
+            context.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["outputs", index, "id"],
+                message: "output ids must be unique",
+            });
+        }
+        outputIds.add(output.id);
+        if (!branchIds.has(output.branchId)) {
+            context.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["outputs", index, "branchId"],
+                message: `output references unknown branch "${output.branchId}"`,
+            });
+        }
+    }
+});
+const retryIdempotencySchema = z.object({
+    mode: z.enum(["not-required", "keyed", "evidence-required"]),
+    keyDeclared: z.boolean().optional(),
+});
+export const RetryResumeIdempotencyContractSchema = z
+    .object({
+    version: z.literal(RETRY_RESUME_IDEMPOTENCY_CONTRACT_VERSION),
+    id: identifier,
+    stepId: identifier,
+    effect: z.enum(["none", ...CAPABILITY_EFFECTS]),
+    maxAttempts: z.number().int().positive().max(RETRY_RESUME_MAX_ATTEMPTS),
+    maxResumes: z.number().int().nonnegative().max(RETRY_RESUME_MAX_RESUMES),
+    idempotency: retryIdempotencySchema,
+    evidence: z.array(EvidenceRequirementSchema).max(RETRY_RESUME_MAX_EVIDENCE).optional(),
+    authority: CapabilityAuthoritySchema.optional(),
+})
+    .superRefine((value, context) => {
+    const effectful = value.effect !== "none";
+    const retriesOrResume = value.maxAttempts > 1 || value.maxResumes > 0;
+    if (effectful && retriesOrResume && value.idempotency.mode === "not-required") {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["idempotency", "mode"],
+            message: "effectful retry/resume requires keyed idempotency or evidence",
+        });
+    }
+    if (value.idempotency.mode === "keyed" && value.idempotency.keyDeclared !== true) {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["idempotency", "keyDeclared"],
+            message: "keyed idempotency requires keyDeclared: true",
+        });
+    }
+    if (value.idempotency.mode === "evidence-required" && (!value.evidence || value.evidence.length === 0)) {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["evidence"],
+            message: "evidence-required idempotency must declare evidence obligations",
+        });
+    }
+});
+export const EffectRetryEvidenceSchema = z.object({
+    version: z.literal(RETRY_RESUME_IDEMPOTENCY_CONTRACT_VERSION),
+    id: identifier,
+    stepId: identifier,
+    runId: identifier,
+    attempt: z.number().int().positive().max(RETRY_RESUME_MAX_ATTEMPTS),
+    effect: z.enum(CAPABILITY_EFFECTS),
+    idempotencyKeyDigest: z.string().max(140).regex(DIGEST, "must be a complete sha256: or sha512: digest"),
+    outcome: z.enum(["committed", "deduplicated", "not-committed"]),
+    producer: z.object({ kind: z.enum(["capability", "deterministic-step", "runner"]), id: identifier }),
+    observedAt: z.string().min(1).max(64),
+});
+function parse(schema, value, label) {
+    const result = schema.safeParse(value);
+    if (!result.success)
+        throw new JoinContractError("INVALID_CONTRACT", `${label}: ${result.error.message}`);
+    return result.data;
+}
+function boundedJson(value, label) {
+    let serialized;
+    try {
+        serialized = JSON.stringify(value);
+    }
+    catch {
+        throw new JoinContractError("INVALID_RESULT", `${label} must be JSON-serializable`);
+    }
+    if (new TextEncoder().encode(serialized).byteLength > JOIN_MAX_CONTRACT_BYTES) {
+        throw new JoinContractError("RESULT_TOO_LARGE", `${label} exceeds ${JOIN_MAX_CONTRACT_BYTES} bytes`);
+    }
+    return value;
+}
+function atPath(value, path) {
+    let current = value;
+    for (const segment of path) {
+        if (current === null || typeof current !== "object" || !(segment in current))
+            return undefined;
+        current = current[segment];
+    }
+    return current;
+}
+function schemaMatches(value, schema, depth = 0) {
+    if (depth > JOIN_MAX_SCHEMA_DEPTH)
+        return false;
+    if (typeof schema === "boolean")
+        return schema;
+    const type = schema.type;
+    if (typeof type === "string") {
+        const actual = value === null ? "null" : Array.isArray(value) ? "array" : typeof value;
+        if (type === "integer") {
+            if (typeof value !== "number" || !Number.isInteger(value))
+                return false;
+        }
+        else if (actual !== type)
+            return false;
+    }
+    if (Array.isArray(schema.enum) && !schema.enum.some((candidate) => Object.is(candidate, value)))
+        return false;
+    if ("const" in schema && !Object.is(schema.const, value))
+        return false;
+    if (schema.required &&
+        typeof schema.required === "object" &&
+        Array.isArray(schema.required) &&
+        typeof value === "object" &&
+        value !== null) {
+        for (const key of schema.required) {
+            if (typeof key === "string" && !(key in value))
+                return false;
+        }
+    }
+    if (schema.properties &&
+        typeof schema.properties === "object" &&
+        !Array.isArray(schema.properties) &&
+        typeof value === "object" &&
+        value !== null) {
+        for (const [key, childSchema] of Object.entries(schema.properties)) {
+            if (key in value && (typeof childSchema === "boolean" || (childSchema && typeof childSchema === "object"))) {
+                if (!schemaMatches(value[key], childSchema, depth + 1))
+                    return false;
+            }
+        }
+    }
+    if (schema.items &&
+        Array.isArray(value) &&
+        (typeof schema.items === "boolean" || (schema.items && typeof schema.items === "object"))) {
+        if (!value.every((item) => schemaMatches(item, schema.items, depth + 1)))
+            return false;
+    }
+    return true;
+}
+function evidenceMatches(record, requirement) {
+    return (record.verification.status === "verified" &&
+        record.kind === requirement.kind &&
+        (requirement.claim === undefined || record.claim === requirement.claim) &&
+        (requirement.artifactKind === undefined || record.artifact.artifact.kind === requirement.artifactKind) &&
+        requirement.producers.includes(record.provenance.producer.kind));
+}
+/** Validate branch completion, evidence, and declared output types at a join boundary. */
+export function assertJoinSatisfied(contract, result) {
+    const parsed = parse(JoinContractSchema, contract, "join contract");
+    boundedJson(result, "join result");
+    const results = new Map(result.branches.map((branch) => [branch.id, branch]));
+    const declaredBranchIds = new Set(parsed.branches.map((branch) => branch.id));
+    for (const branch of result.branches) {
+        if (!declaredBranchIds.has(branch.id)) {
+            throw new JoinContractError("UNKNOWN_BRANCH", `join result contains undeclared branch "${branch.id}"`);
+        }
+    }
+    for (const branch of parsed.branches) {
+        const current = results.get(branch.id);
+        if (!current || current.status === "missing") {
+            if (branch.required)
+                throw new JoinContractError("REQUIRED_BRANCH_MISSING", `required branch "${branch.id}" did not complete`);
+            continue;
+        }
+        if (current.status !== "completed") {
+            if (branch.required)
+                throw new JoinContractError("REQUIRED_BRANCH_INCOMPLETE", `required branch "${branch.id}" is ${current.status}`);
+            continue;
+        }
+        for (const requirement of branch.evidence ?? []) {
+            const evidence = (current.evidence ?? [])
+                .map((item) => {
+                try {
+                    return parseEvidenceRecord(item);
+                }
+                catch {
+                    return null;
+                }
+            })
+                .filter((item) => item !== null);
+            if (!evidence.some((item) => evidenceMatches(item, requirement))) {
+                throw new JoinContractError("EVIDENCE_MISSING", `branch "${branch.id}" is missing evidence requirement "${requirement.id}"`);
+            }
+        }
+    }
+    if (parsed.mode === "any" && !parsed.branches.some((branch) => results.get(branch.id)?.status === "completed")) {
+        throw new JoinContractError("NO_BRANCH_COMPLETED", "an any-mode join requires at least one completed branch");
+    }
+    for (const output of parsed.outputs) {
+        const branch = results.get(output.branchId);
+        if (!branch || branch.status !== "completed") {
+            if (parsed.branches.find((item) => item.id === output.branchId)?.required) {
+                throw new JoinContractError("OUTPUT_BRANCH_MISSING", `output "${output.id}" has no completed branch source`);
+            }
+            continue;
+        }
+        const value = atPath(branch.output, output.path);
+        if (value === undefined)
+            throw new JoinContractError("OUTPUT_MISSING", `declared output "${output.id}" is missing`);
+        if (!schemaMatches(value, output.schema))
+            throw new JoinContractError("OUTPUT_TYPE_INVALID", `declared output "${output.id}" does not match its schema`);
+    }
+}
+export function parseJoinContract(value) {
+    return parse(JoinContractSchema, value, "join contract");
+}
+export function serializeJoinContract(value) {
+    return JSON.stringify(parseJoinContract(value));
+}
+export function parseRetryResumeIdempotencyContract(value) {
+    const result = RetryResumeIdempotencyContractSchema.safeParse(value);
+    if (!result.success)
+        throw new RetryResumeContractError("INVALID_CONTRACT", result.error.message);
+    return result.data;
+}
+export function parseEffectRetryEvidence(value) {
+    const result = EffectRetryEvidenceSchema.safeParse(value);
+    if (!result.success)
+        throw new RetryResumeContractError("INVALID_EVIDENCE", result.error.message);
+    return result.data;
+}
+/** Require an evidence record for effectful retry/resume; no effect is retried without proof. */
+export function assertEffectRetryEvidence(contract, evidence) {
+    const parsed = parseRetryResumeIdempotencyContract(contract);
+    if (parsed.effect === "none" || (parsed.maxAttempts === 1 && parsed.maxResumes === 0))
+        return;
+    if (parsed.idempotency.mode === "not-required") {
+        throw new RetryResumeContractError("IDEMPOTENCY_REQUIRED", `effectful step "${parsed.stepId}" cannot retry or resume without idempotency`);
+    }
+    if (parsed.idempotency.mode !== "evidence-required")
+        return;
+    const valid = evidence
+        .map((item) => {
+        try {
+            return parseEffectRetryEvidence(item);
+        }
+        catch {
+            return null;
+        }
+    })
+        .filter((item) => item !== null);
+    for (const requirement of parsed.evidence ?? []) {
+        const found = valid.some((item) => item.stepId === parsed.stepId && item.producer.kind === "runner" && item.id === requirement.id);
+        if (!found)
+            throw new RetryResumeContractError("EVIDENCE_MISSING", `missing retry evidence "${requirement.id}" for step "${parsed.stepId}"`);
+    }
+}

package/dist/NodeBase.d.ts

@@ -13,6 +13,24 @@ export default abstract class NodeBase {
     active: boolean;
     stop: boolean;
     originalConfig: ParamsDictionary;
+    /** Trusted manifest copied from the node descriptor; absent means unsafe to agents. */
+    capabilityManifest?: import("./CapabilityManifest.js").CapabilityManifestV1;
+    /** Raw descriptor value retained so invalid runtime metadata fails closed. */
+    capabilityManifestRaw?: unknown;
+    /** H1-02: model work must satisfy an explicit completion contract. */
+    agentStep?: import("./EnforcementContracts.js").AgentStepContract;
+    /** H1-02: policy-backed durable approval handoff metadata. */
+    approval?: import("./EnforcementContracts.js").ApprovalContract;
+    /** H1-02: runner-owned deterministic assertion gate. */
+    assertionGate?: import("./EnforcementContracts.js").AssertionGateContract;
+    /** H1-02: runner-owned trusted evidence gate. */
+    evidenceGate?: import("./EnforcementContracts.js").EvidenceGateContract;
+    /** Trust is a property of the node implementation, never model prose. */
+    outputTrust: import("./EnforcementContracts.js").OutputTrust;
+    /** H1-04 evidence-aware obligations and typed outputs at a join boundary. */
+    join?: import("./JoinContracts.js").JoinContract;
+    /** H1-04 bounded effect retry/resume idempotency declaration. */
+    retryResume?: import("./JoinContracts.js").RetryResumeIdempotencyContract;
     /**
      * Alternative state key for this step's output. When set, the runner
      * stores result.data at `ctx.state[as]` instead of `ctx.state[name]`.
@@ -94,6 +112,8 @@ export default abstract class NodeBase {
      * in v0.3.x — the schema includes a deferred-feature error message.
      */
     wait?: boolean;
+    prepare(ctx: Context): Promise<void>;
+    protected validatePrepared(_ctx: Context): Promise<void>;
     process(ctx: Context, step?: Step): Promise<ResponseContext>;
     processFlow(ctx: Context): Promise<ResponseContext>;
     abstract run(ctx: Context): Promise<ResponseContext>;

package/dist/NodeBase.js

@@ -1,7 +1,28 @@
-import _ from "lodash";
 import GlobalError from "./GlobalError.js";
-import mapper from "./utils/Mapper.js";
+import mapper, { cloneResolvable } from "./utils/Mapper.js";
 import { MapperResolutionError } from "./utils/MapperResolutionError.js";
+const preparedContexts = new WeakMap();
+/**
+ * Resolve one step's config slice for this execution and publish the resolved
+ * COPY at `config[name]`, leaving the source slice unresolved. Returns the
+ * pristine source (the step's `originalConfig`).
+ *
+ * The mapper mutates in place, so before #874 every caller that might run a
+ * step more than once against one config — a forEach iteration, a loop body —
+ * had to hand it a deep clone of the WHOLE workflow config first, which is
+ * O(config) per iteration and O(config × steps) per run. Copying only the
+ * slice being resolved, and only the parts the mapper can reach, gives the
+ * same isolation for the cost of the one thing that changes.
+ *
+ * Safe because `RunnerSteps.runSteps` already gives every (nested, parallel)
+ * pipeline its own top-level config object: replacing a key is private to the
+ * pipeline that does it, while the slice VALUES stay shared and unresolved.
+ */
+function resolveSlice(config, name, map, ctx) {
+    const original = config[name];
+    config[name] = map(cloneResolvable(original), ctx);
+    return original;
+}
 export default class NodeBase {
     flow = false;
     name = "";
@@ -9,6 +30,24 @@ export default class NodeBase {
     active = true;
     stop = false;
     originalConfig = {};
+    /** Trusted manifest copied from the node descriptor; absent means unsafe to agents. */
+    capabilityManifest;
+    /** Raw descriptor value retained so invalid runtime metadata fails closed. */
+    capabilityManifestRaw;
+    /** H1-02: model work must satisfy an explicit completion contract. */
+    agentStep;
+    /** H1-02: policy-backed durable approval handoff metadata. */
+    approval;
+    /** H1-02: runner-owned deterministic assertion gate. */
+    assertionGate;
+    /** H1-02: runner-owned trusted evidence gate. */
+    evidenceGate;
+    /** Trust is a property of the node implementation, never model prose. */
+    outputTrust = "model";
+    /** H1-04 evidence-aware obligations and typed outputs at a join boundary. */
+    join;
+    /** H1-04 bounded effect retry/resume idempotency declaration. */
+    retryResume;
     // =========================================================================
     // V2 persistence knobs — populated by Configuration.getSteps from the
     // step definition. Read by PersistenceHelper.applyStepOutput.
@@ -98,15 +137,27 @@ export default class NodeBase {
      * in v0.3.x — the schema includes a deferred-feature error message.
      */
     wait;
+    async prepare(ctx) {
+        const config = ctx.config;
+        this.originalConfig = resolveSlice(config, this.name, this.blueprintMapper, ctx);
+        await this.validatePrepared(ctx);
+        let prepared = preparedContexts.get(ctx);
+        if (!prepared) {
+            prepared = new Set();
+            preparedContexts.set(ctx, prepared);
+        }
+        prepared.add(this);
+    }
+    async validatePrepared(_ctx) { }
     async process(ctx, step) {
         let response = {
             success: true,
             data: null,
             error: null,
         };
-        const config = ctx.config;
-        this.originalConfig = _.cloneDeep(config[this.name]);
-        this.blueprintMapper(config[this.name], ctx);
+        const prepared = preparedContexts.get(ctx)?.has(this) === true;
+        if (!prepared)
+            await this.prepare(ctx);
         response = await this.run(ctx);
         if (response.error)
             throw response.error;
@@ -121,7 +172,7 @@ export default class NodeBase {
         };
         try {
             const config = ctx.config;
-            this.blueprintMapper(config[this.name], ctx);
+            resolveSlice(config, this.name, this.blueprintMapper, ctx);
             response = await this.run(ctx);
         }
         catch (error) {

package/dist/PermissionAlgebra.d.ts

@@ -0,0 +1,51 @@
+import { z } from "zod";
+import { type CapabilityEffect } from "./CapabilityManifest.js";
+/** The scalar values accepted in a capability authority's constraint fragments. */
+export declare const CapabilityFragmentValueSchema: z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+/**
+ * A normalized authority envelope. An empty list means that the envelope does
+ * not grant that category; an omitted policy envelope means that policy did
+ * not add a further restriction.
+ */
+export interface CapabilityAuthority {
+    readonly effects: readonly CapabilityEffect[];
+    readonly capabilities: readonly string[];
+    readonly secrets: readonly string[];
+    readonly fragments: Readonly<Record<string, string | number | boolean>>;
+}
+export declare const CapabilityAuthoritySchema: z.ZodObject<{
+    effects: z.ZodArray<z.ZodEnum<["read", "write", "network", "filesystem", "process", "secret", "streaming", "destructive"]>, "many">;
+    capabilities: z.ZodArray<z.ZodString, "many">;
+    secrets: z.ZodArray<z.ZodString, "many">;
+    fragments: z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+}, "strict", z.ZodTypeAny, {
+    effects: ("read" | "write" | "network" | "filesystem" | "process" | "secret" | "streaming" | "destructive")[];
+    capabilities: string[];
+    secrets: string[];
+    fragments: Record<string, string | number | boolean>;
+}, {
+    effects: ("read" | "write" | "network" | "filesystem" | "process" | "secret" | "streaming" | "destructive")[];
+    capabilities: string[];
+    secrets: string[];
+    fragments: Record<string, string | number | boolean>;
+}>;
+export declare class CapabilityAuthorityError extends Error {
+    readonly code = "CAPABILITY_AUTHORITY_INVALID";
+    readonly errors: readonly string[];
+    constructor(errors: readonly string[]);
+}
+/** Parse, validate, canonicalize, and freeze an authority envelope. */
+export declare function parseCapabilityAuthority(value: unknown): CapabilityAuthority;
+/**
+ * Compute the monotonic permission intersection. The operation is
+ * commutative, associative, and returns a canonical frozen value, making it
+ * safe to persist in requests and traces.
+ */
+export declare function intersectCapabilityAuthorities(...authorities: readonly CapabilityAuthority[]): CapabilityAuthority;
+/** Return whether a child authority is no broader than its parent. */
+export declare function isCapabilityAuthoritySubset(child: CapabilityAuthority, parent: CapabilityAuthority): boolean;
+/**
+ * Validate child delegation before dispatch. Errors use stable category and
+ * sorted-value ordering so callers and conformance tests can inspect them.
+ */
+export declare function assertCapabilityAuthoritySubset(child: CapabilityAuthority, parent: CapabilityAuthority, path?: string): void;

package/dist/PermissionAlgebra.js

@@ -0,0 +1,125 @@
+import { z } from "zod";
+import { CAPABILITY_EFFECTS } from "./CapabilityManifest.js";
+/** The scalar values accepted in a capability authority's constraint fragments. */
+export const CapabilityFragmentValueSchema = z.union([z.string(), z.number().finite(), z.boolean()]);
+const capabilityIdentifier = z
+    .string()
+    .regex(/^[A-Za-z][A-Za-z0-9._:/-]{0,127}$/, "must be a valid capability or secret reference name");
+export const CapabilityAuthoritySchema = z
+    .object({
+    effects: z.array(z.enum(CAPABILITY_EFFECTS)),
+    capabilities: z.array(capabilityIdentifier),
+    secrets: z.array(capabilityIdentifier),
+    fragments: z.record(CapabilityFragmentValueSchema),
+})
+    .strict();
+export class CapabilityAuthorityError extends Error {
+    code = "CAPABILITY_AUTHORITY_INVALID";
+    errors;
+    constructor(errors) {
+        super(`Invalid capability authority: ${errors.join("; ")}`);
+        this.name = "CapabilityAuthorityError";
+        this.errors = [...errors];
+    }
+}
+function sortedUnique(values) {
+    return [...new Set(values)].sort();
+}
+function stableFragments(fragments) {
+    const result = {};
+    for (const key of Object.keys(fragments).sort())
+        result[key] = fragments[key];
+    return Object.freeze(result);
+}
+function normalize(value) {
+    return Object.freeze({
+        effects: Object.freeze(sortedUnique(value.effects)),
+        capabilities: Object.freeze(sortedUnique(value.capabilities)),
+        secrets: Object.freeze(sortedUnique(value.secrets)),
+        fragments: stableFragments(value.fragments),
+    });
+}
+function formatIssue(path, message) {
+    return `${path.length > 0 ? `authority.${path.join(".")}` : "authority"} ${message}`;
+}
+/** Parse, validate, canonicalize, and freeze an authority envelope. */
+export function parseCapabilityAuthority(value) {
+    const parsed = CapabilityAuthoritySchema.safeParse(value);
+    if (!parsed.success) {
+        const errors = parsed.error.issues
+            .map((issue) => formatIssue(issue.path, issue.message))
+            .sort((left, right) => left.localeCompare(right));
+        throw new CapabilityAuthorityError(errors);
+    }
+    return normalize(parsed.data);
+}
+function commonValues(left, right) {
+    const rightSet = new Set(right);
+    return [...new Set(left)].filter((value) => rightSet.has(value)).sort();
+}
+/**
+ * Compute the monotonic permission intersection. The operation is
+ * commutative, associative, and returns a canonical frozen value, making it
+ * safe to persist in requests and traces.
+ */
+export function intersectCapabilityAuthorities(...authorities) {
+    if (authorities.length === 0) {
+        return parseCapabilityAuthority({ effects: [], capabilities: [], secrets: [], fragments: {} });
+    }
+    let result = parseCapabilityAuthority(authorities[0]);
+    for (const authority of authorities.slice(1)) {
+        const next = parseCapabilityAuthority(authority);
+        const fragments = {};
+        for (const key of Object.keys(result.fragments).sort()) {
+            if (Object.prototype.hasOwnProperty.call(next.fragments, key) &&
+                Object.is(result.fragments[key], next.fragments[key])) {
+                fragments[key] = result.fragments[key];
+            }
+        }
+        result = Object.freeze({
+            effects: Object.freeze(commonValues(result.effects, next.effects)),
+            capabilities: Object.freeze(commonValues(result.capabilities, next.capabilities)),
+            secrets: Object.freeze(commonValues(result.secrets, next.secrets)),
+            fragments: stableFragments(fragments),
+        });
+    }
+    return result;
+}
+function isSubset(child, parent) {
+    const parentSet = new Set(parent);
+    return child.every((value) => parentSet.has(value));
+}
+/** Return whether a child authority is no broader than its parent. */
+export function isCapabilityAuthoritySubset(child, parent) {
+    if (!isSubset(child.effects, parent.effects))
+        return false;
+    if (!isSubset(child.capabilities, parent.capabilities))
+        return false;
+    if (!isSubset(child.secrets, parent.secrets))
+        return false;
+    return Object.entries(child.fragments).every(([key, value]) => Object.is(parent.fragments[key], value));
+}
+/**
+ * Validate child delegation before dispatch. Errors use stable category and
+ * sorted-value ordering so callers and conformance tests can inspect them.
+ */
+export function assertCapabilityAuthoritySubset(child, parent, path = "child authority") {
+    const errors = [];
+    const check = (category, childValues, parentValues) => {
+        const parentSet = new Set(parentValues);
+        const widened = childValues.filter((value) => !parentSet.has(value)).sort();
+        if (widened.length > 0)
+            errors.push(`${path}.${category} contains unauthorized value(s): ${widened.join(", ")}`);
+    };
+    check("effects", child.effects, parent.effects);
+    check("capabilities", child.capabilities, parent.capabilities);
+    check("secrets", child.secrets, parent.secrets);
+    const missingFragments = Object.entries(child.fragments)
+        .filter(([key, value]) => !Object.is(parent.fragments[key], value))
+        .sort(([left], [right]) => left.localeCompare(right));
+    for (const [key, value] of missingFragments) {
+        errors.push(`${path}.fragments.${key} is not permitted: ${JSON.stringify(value)}`);
+    }
+    if (errors.length > 0)
+        throw new CapabilityAuthorityError(errors.sort((left, right) => left.localeCompare(right)));
+}