@blokjs/shared 2.0.1 → 2.2.0

package/dist/BlokError.d.ts

@@ -204,7 +204,9 @@ export default class BlokError extends GlobalError {
 export declare const WORKFLOW_INPUT_VALIDATION = "WORKFLOW_INPUT_VALIDATION";
 /**
  * True when `err` is the ADR-0015 **input-validation gate's** deterministic
- * failure — a `GlobalError` carrying the {@link WORKFLOW_INPUT_VALIDATION} tag.
+ * failure — a `GlobalError` carrying the {@link WORKFLOW_INPUT_VALIDATION} tag
+ * (in practice a {@link WorkflowInputValidationError}; the tag is what's matched
+ * so an error that crossed a serialization boundary still classifies).
  *
  * Triggers consult this to route the error to DLQ / drop / a 4xx response
  * instead of a poison-message loop (worker burning its retry budget, pub/sub
@@ -217,3 +219,55 @@ export declare const WORKFLOW_INPUT_VALIDATION = "WORKFLOW_INPUT_VALIDATION";
  * never surfaced by the webhook 4xx path.
  */
 export declare function isNonRetryableValidationError(err: unknown): boolean;
+/**
+ * Selective retry — THE matcher for a step's `retry.nonRetryableErrorNames`.
+ * Inspects the error name through wrapped causes: both plain `Error.name` and
+ * `GlobalError.context.name` count, and `cause` chains are walked to a bounded
+ * depth so an enriched or re-thrown error cannot hide a non-retryable
+ * classification.
+ *
+ * `RunnerSteps` calls this to short-circuit STEP retries, then records the
+ * verdict on the propagating error with {@link markNonRetryableStepError}.
+ * Transports read the verdict back with {@link isNonRetryableStepError} rather
+ * than re-deriving it, so JOB-level retry (#679 — BullMQ and every other worker
+ * adapter) agrees with step-level retry by construction instead of via a second
+ * implementation that could drift.
+ */
+export declare function isNonRetryableError(error: unknown, names: string[] | undefined): boolean;
+/** Record a {@link isNonRetryableError} match on `error` (no-op for non-objects). */
+export declare function markNonRetryableStepError(error: unknown): void;
+/**
+ * True when the runner classified this failure — or one it wraps — as declared
+ * non-retryable. Walks `cause` to the same bounded depth as
+ * {@link isNonRetryableError} so an outer wrap cannot hide the verdict.
+ */
+export declare function isNonRetryableStepError(error: unknown): boolean;
+/** One Zod issue, flattened to plain data for the wire. */
+export interface WorkflowInputValidationIssue {
+    path: (string | number)[];
+    message: string;
+    code: string;
+}
+/** What the ADR-0015 gate knows about the rejection. */
+export interface WorkflowInputValidationInfo {
+    /** The workflow whose declared `input` schema rejected the payload. */
+    workflowName: string;
+    /** Every Zod issue, in schema order. */
+    issues: WorkflowInputValidationIssue[];
+}
+/**
+ * ADR 0015 — thrown by the input gate in `TriggerBase.run()` when the invoking
+ * trigger's payload fails the workflow's declared `input` Zod.
+ *
+ * Named + exported so callers can `instanceof` it, matching the vocabulary of
+ * the other gate errors (`ConcurrencyLimitError`, `QueueExpiredError`,
+ * `MapperResolutionError`). It extends `GlobalError` — carrying code 400, the
+ * {@link WORKFLOW_INPUT_VALIDATION} tag on `context.name`, and the structured
+ * `validation_errors` json — so every existing transport translation
+ * (HTTP 400, MCP `isError`, gRPC error status, worker/pubsub/webhook DLQ
+ * routing via {@link isNonRetryableValidationError}) keeps working untouched.
+ */
+export declare class WorkflowInputValidationError extends GlobalError {
+    readonly info: WorkflowInputValidationInfo;
+    constructor(info: WorkflowInputValidationInfo);
+}

package/dist/BlokError.js

@@ -335,7 +335,9 @@ export default class BlokError extends GlobalError {
 export const WORKFLOW_INPUT_VALIDATION = "WORKFLOW_INPUT_VALIDATION";
 /**
  * True when `err` is the ADR-0015 **input-validation gate's** deterministic
- * failure — a `GlobalError` carrying the {@link WORKFLOW_INPUT_VALIDATION} tag.
+ * failure — a `GlobalError` carrying the {@link WORKFLOW_INPUT_VALIDATION} tag
+ * (in practice a {@link WorkflowInputValidationError}; the tag is what's matched
+ * so an error that crossed a serialization boundary still classifies).
  *
  * Triggers consult this to route the error to DLQ / drop / a 4xx response
  * instead of a poison-message loop (worker burning its retry budget, pub/sub
@@ -350,3 +352,99 @@ export const WORKFLOW_INPUT_VALIDATION = "WORKFLOW_INPUT_VALIDATION";
 export function isNonRetryableValidationError(err) {
     return err instanceof GlobalError && err.context.name === WORKFLOW_INPUT_VALIDATION;
 }
+/**
+ * How far a `cause` chain is walked when classifying an error. Bounded so a
+ * self-referential or pathologically deep chain can't spin.
+ */
+const CAUSE_WALK_DEPTH = 8;
+/**
+ * Selective retry — THE matcher for a step's `retry.nonRetryableErrorNames`.
+ * Inspects the error name through wrapped causes: both plain `Error.name` and
+ * `GlobalError.context.name` count, and `cause` chains are walked to a bounded
+ * depth so an enriched or re-thrown error cannot hide a non-retryable
+ * classification.
+ *
+ * `RunnerSteps` calls this to short-circuit STEP retries, then records the
+ * verdict on the propagating error with {@link markNonRetryableStepError}.
+ * Transports read the verdict back with {@link isNonRetryableStepError} rather
+ * than re-deriving it, so JOB-level retry (#679 — BullMQ and every other worker
+ * adapter) agrees with step-level retry by construction instead of via a second
+ * implementation that could drift.
+ */
+export function isNonRetryableError(error, names) {
+    if (!names || names.length === 0)
+        return false;
+    let current = error;
+    for (let depth = 0; depth < CAUSE_WALK_DEPTH && current && typeof current === "object"; depth++) {
+        const candidate = current;
+        if (typeof candidate.name === "string" && names.includes(candidate.name))
+            return true;
+        if (candidate.context &&
+            typeof candidate.context === "object" &&
+            typeof candidate.context.name === "string" &&
+            names.includes(candidate.context.name)) {
+            return true;
+        }
+        current = candidate.cause;
+    }
+    return false;
+}
+/**
+ * Property the runner stamps on a failure {@link isNonRetryableError} matched.
+ * Sticky-TRUE only: its absence means "never classified", never "retryable" —
+ * the runner re-wraps errors several times (step enrichment → GlobalError
+ * unwrap) and an intermediate wrap whose own step declared nothing must not
+ * erase an inner verdict.
+ */
+const NON_RETRYABLE_STEP_ERROR = "_blokNonRetryable";
+/** Record a {@link isNonRetryableError} match on `error` (no-op for non-objects). */
+export function markNonRetryableStepError(error) {
+    if (error && typeof error === "object") {
+        error[NON_RETRYABLE_STEP_ERROR] = true;
+    }
+}
+/**
+ * True when the runner classified this failure — or one it wraps — as declared
+ * non-retryable. Walks `cause` to the same bounded depth as
+ * {@link isNonRetryableError} so an outer wrap cannot hide the verdict.
+ */
+export function isNonRetryableStepError(error) {
+    let current = error;
+    for (let depth = 0; depth < CAUSE_WALK_DEPTH && current && typeof current === "object"; depth++) {
+        if (current[NON_RETRYABLE_STEP_ERROR] === true)
+            return true;
+        current = current.cause;
+    }
+    return false;
+}
+/**
+ * ADR 0015 — thrown by the input gate in `TriggerBase.run()` when the invoking
+ * trigger's payload fails the workflow's declared `input` Zod.
+ *
+ * Named + exported so callers can `instanceof` it, matching the vocabulary of
+ * the other gate errors (`ConcurrencyLimitError`, `QueueExpiredError`,
+ * `MapperResolutionError`). It extends `GlobalError` — carrying code 400, the
+ * {@link WORKFLOW_INPUT_VALIDATION} tag on `context.name`, and the structured
+ * `validation_errors` json — so every existing transport translation
+ * (HTTP 400, MCP `isError`, gRPC error status, worker/pubsub/webhook DLQ
+ * routing via {@link isNonRetryableValidationError}) keeps working untouched.
+ */
+export class WorkflowInputValidationError extends GlobalError {
+    info;
+    constructor(info) {
+        const summary = info.issues.map((i) => `${i.path.join(".") || "(root)"} (${i.message})`).join(", ");
+        super(`Input validation failed for workflow '${info.workflowName}': ${summary}`);
+        // `GlobalError`'s own constructor pins the prototype to GlobalError.prototype,
+        // so a subclass MUST re-pin or `instanceof WorkflowInputValidationError` is false.
+        Object.setPrototypeOf(this, WorkflowInputValidationError.prototype);
+        this.name = "WorkflowInputValidationError";
+        this.info = info;
+        this.setCode(400);
+        this.setName(WORKFLOW_INPUT_VALIDATION);
+        this.setJson({
+            error: "Input validation failed",
+            workflowName: info.workflowName,
+            validation_errors: info.issues,
+        });
+    }
+}

package/dist/CapabilityContracts.d.ts

@@ -0,0 +1,91 @@
+import { z } from "zod";
+import type { PolicyContext, PolicyDecision, PolicyEvaluationResult, PolicyProvider } from "./PolicyContracts.js";
+import type { PrincipalIdentity, RequestedCapabilityScope } from "./PolicyContracts.js";
+/** Version shared by the H3 capability contracts. */
+export declare const AGENT_CAPABILITY_CONTRACT_VERSION: "1";
+export declare const CAPABILITY_MAX_ID_LENGTH = 128;
+export declare const CAPABILITY_MAX_PATH_LENGTH = 4096;
+export declare const CAPABILITY_MAX_LIST_ITEMS = 1024;
+export declare const CAPABILITY_MAX_OUTPUT_CHUNK_BYTES: number;
+export interface CapabilityOwner {
+    readonly principal: PrincipalIdentity;
+    readonly sessionId: string;
+    readonly turnId?: string;
+    readonly taskId: string;
+}
+/**
+ * An opaque reference into the workspace capability (#927). H3 contracts do
+ * not canonicalize paths or access the host filesystem; the filesystem
+ * capability owns that boundary.
+ */
+export interface WorkspacePathRef {
+    readonly workspaceId: string;
+    readonly path: string;
+}
+export interface CapabilityRequestContext {
+    readonly policy: PolicyContext;
+    readonly owner: CapabilityOwner;
+}
+/** Every trusted adapter must authorize before doing host-side work. */
+export interface CapabilityAuthorizationPort {
+    authorize(request: PolicyContext): Promise<PolicyEvaluationResult>;
+    readonly provider?: PolicyProvider;
+}
+export declare class CapabilityContractError extends Error {
+    readonly code = "CAPABILITY_CONTRACT_INVALID";
+    constructor(message: string);
+}
+declare const identifier: z.ZodString;
+declare const path: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>, string, string>;
+declare const timestamp: z.ZodEffects<z.ZodString, string, string>;
+declare const digest: z.ZodEffects<z.ZodString, string, string>;
+export declare const CapabilityOwnerSchema: z.ZodObject<{
+    principal: z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        kind: string;
+    }, {
+        id: string;
+        kind: string;
+    }>;
+    sessionId: z.ZodString;
+    turnId: z.ZodOptional<z.ZodString>;
+    taskId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    sessionId: string;
+    principal: {
+        id: string;
+        kind: string;
+    };
+    taskId: string;
+    turnId?: string | undefined;
+}, {
+    sessionId: string;
+    principal: {
+        id: string;
+        kind: string;
+    };
+    taskId: string;
+    turnId?: string | undefined;
+}>;
+export declare const WorkspacePathRefSchema: z.ZodObject<{
+    workspaceId: z.ZodString;
+    path: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>, string, string>;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    workspaceId: string;
+}, {
+    path: string;
+    workspaceId: string;
+}>;
+export declare function parseCapabilityOwner(value: unknown): CapabilityOwner;
+export declare function parseWorkspacePathRef(value: unknown): WorkspacePathRef;
+export declare function parseCapabilityAuthorization(decision: PolicyDecision, result?: PolicyEvaluationResult): PolicyEvaluationResult;
+export declare function assertAuthorized(result: PolicyEvaluationResult, options?: {
+    allowSandbox?: boolean;
+}): void;
+export declare function assertOwned(owner: CapabilityOwner, expected: CapabilityOwner): void;
+export declare function capabilityScope(effects: RequestedCapabilityScope["effects"], capabilities: readonly string[], secrets?: readonly string[]): RequestedCapabilityScope;
+export { digest, identifier, path, timestamp };

package/dist/CapabilityContracts.js

@@ -0,0 +1,104 @@
+import { z } from "zod";
+/** Version shared by the H3 capability contracts. */
+export const AGENT_CAPABILITY_CONTRACT_VERSION = "1";
+export const CAPABILITY_MAX_ID_LENGTH = 128;
+export const CAPABILITY_MAX_PATH_LENGTH = 4_096;
+export const CAPABILITY_MAX_LIST_ITEMS = 1_024;
+export const CAPABILITY_MAX_OUTPUT_CHUNK_BYTES = 64 * 1024;
+export class CapabilityContractError extends Error {
+    code = "CAPABILITY_CONTRACT_INVALID";
+    constructor(message) {
+        super(message);
+        this.name = "CapabilityContractError";
+    }
+}
+const identifier = z
+    .string()
+    .min(1)
+    .max(CAPABILITY_MAX_ID_LENGTH)
+    .regex(/^[A-Za-z][A-Za-z0-9._:/-]*$/);
+const path = z
+    .string()
+    .min(1)
+    .max(CAPABILITY_MAX_PATH_LENGTH)
+    .refine((value) => !value.includes("\0"), "must not contain NUL")
+    .refine((value) => !value.startsWith("/") && !/^[A-Za-z]:[\\/]/.test(value), "must be workspace-relative")
+    .refine((value) => !value.split(/[\\/]+/).includes(".."), "must not escape the workspace");
+const timestamp = z.string().refine((value) => {
+    if (!Number.isFinite(Date.parse(value)))
+        return false;
+    return new Date(value).toISOString() === value;
+}, "must be a canonical ISO timestamp");
+const sessionId = z.string().min(1).max(CAPABILITY_MAX_ID_LENGTH);
+const digest = z
+    .string()
+    .regex(/^(?:sha256):[0-9a-f]{64}$|^(?:sha512):[0-9a-f]{128}$/i)
+    .transform((value) => value.toLowerCase());
+const ownerSchema = z.object({
+    principal: z.object({ id: identifier, kind: identifier }),
+    // Session IDs are opaque references and the control plane uses UUIDs.
+    sessionId,
+    turnId: identifier.optional(),
+    taskId: identifier,
+});
+const workspacePathSchema = z.object({ workspaceId: identifier, path });
+export const CapabilityOwnerSchema = ownerSchema;
+export const WorkspacePathRefSchema = workspacePathSchema;
+function parse(schema, value, label) {
+    const result = schema.safeParse(value);
+    if (!result.success) {
+        throw new CapabilityContractError(result.error.issues
+            .map((issue) => `${label}${issue.path.length > 0 ? `.${issue.path.join(".")}` : ""} ${issue.message}`)
+            .join("; "));
+    }
+    return result.data;
+}
+function immutable(value) {
+    const snapshot = structuredClone(value);
+    const freeze = (item) => {
+        if (item === null || typeof item !== "object" || Object.isFrozen(item))
+            return;
+        for (const child of Object.values(item))
+            freeze(child);
+        Object.freeze(item);
+    };
+    freeze(snapshot);
+    return snapshot;
+}
+export function parseCapabilityOwner(value) {
+    return immutable(parse(ownerSchema, value, "capability owner"));
+}
+export function parseWorkspacePathRef(value) {
+    return immutable(parse(workspacePathSchema, value, "workspace path"));
+}
+export function parseCapabilityAuthorization(decision, result) {
+    if (!result || result.decision.id !== decision.id) {
+        throw new CapabilityContractError("authorization result does not match the policy decision");
+    }
+    return result;
+}
+export function assertAuthorized(result, options = {}) {
+    if (result.decision.kind === "allow")
+        return;
+    if (options.allowSandbox && result.decision.kind === "require-sandbox" && result.sandbox?.proof)
+        return;
+    throw new CapabilityContractError(`capability execution is not authorized: ${result.decision.kind}`);
+}
+export function assertOwned(owner, expected) {
+    if (owner.principal.id !== expected.principal.id ||
+        owner.principal.kind !== expected.principal.kind ||
+        owner.sessionId !== expected.sessionId ||
+        owner.taskId !== expected.taskId ||
+        (owner.turnId ?? "") !== (expected.turnId ?? "")) {
+        throw new CapabilityContractError("capability handle is owned by a different task context");
+    }
+}
+export function capabilityScope(effects, capabilities, secrets = []) {
+    return {
+        effects: [...new Set(effects)].sort(),
+        capabilities: [...new Set(capabilities)].sort(),
+        secrets: [...new Set(secrets)].sort(),
+        fragments: {},
+    };
+}
+export { digest, identifier, path, timestamp };

package/dist/CapabilityManifest.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Language-neutral operational metadata for nodes and workflows (ADR 0003).
+ *
+ * Schemas describe values; this manifest describes risk. It is deliberately
+ * data-only so every SDK can emit the same JSON through gRPC `ListNodes`.
+ * Unknown object fields are ignored when parsing v1, allowing additive wire
+ * evolution, while an unknown VERSION remains ineligible for agent execution.
+ */
+export declare const CAPABILITY_MANIFEST_VERSION: "1";
+export declare const CAPABILITY_EFFECTS: readonly ["read", "write", "network", "filesystem", "process", "secret", "streaming", "destructive"];
+export declare const CAPABILITY_CLASSIFICATIONS: readonly ["agent-compatible", "trusted-legacy", "denied-to-agents"];
+export declare const CAPABILITY_DETERMINISM: readonly ["deterministic", "time-dependent", "random", "external", "unknown"];
+export declare const CAPABILITY_IDEMPOTENCY: readonly ["idempotent", "conditionally-idempotent", "non-idempotent", "unknown"];
+export declare const CAPABILITY_MATURITY: readonly ["stable", "beta", "experimental", "deprecated"];
+export type CapabilityEffect = (typeof CAPABILITY_EFFECTS)[number];
+export type CapabilityClassification = (typeof CAPABILITY_CLASSIFICATIONS)[number];
+export type CapabilityDeterminism = (typeof CAPABILITY_DETERMINISM)[number];
+export type CapabilityIdempotency = (typeof CAPABILITY_IDEMPOTENCY)[number];
+export type CapabilityMaturity = (typeof CAPABILITY_MATURITY)[number];
+export interface CapabilityResourceBounds {
+    maxDurationMs?: number;
+    maxMemoryBytes?: number;
+    maxInputBytes?: number;
+    maxOutputBytes?: number;
+    maxConcurrency?: number;
+}
+export interface CapabilityManifestV1 {
+    version: typeof CAPABILITY_MANIFEST_VERSION;
+    /** Agent compatibility is explicit; absence never implies safety. */
+    classification: CapabilityClassification;
+    /** Empty means pure: no externally observable operational effect. */
+    effects: CapabilityEffect[];
+    /** Fine-grained capability identifiers, e.g. `network.http` or `fs.workspace.read`. */
+    capabilities: string[];
+    /** Opaque secret reference NAMES only. Never put credentials here. */
+    secrets: string[];
+    determinism: CapabilityDeterminism;
+    idempotency: CapabilityIdempotency;
+    maturity: CapabilityMaturity;
+    resources?: CapabilityResourceBounds;
+    /** Optional applicability constraints. Empty/absent means unrestricted. */
+    runtimes?: string[];
+    triggers?: string[];
+}
+export type CapabilityManifestStatus = "declared" | "missing" | "invalid";
+export interface CapabilityManifestAssessment {
+    status: CapabilityManifestStatus;
+    manifest: CapabilityManifestV1 | null;
+    errors: string[];
+    agentEligible: boolean;
+    reason: "eligible" | "missing-manifest" | "invalid-manifest" | "trusted-legacy" | "denied-to-agents";
+}
+export declare class CapabilityManifestError extends Error {
+    readonly errors: readonly string[];
+    constructor(errors: readonly string[]);
+}
+/** Parse and normalize a v1 manifest. Additive unknown fields are ignored. */
+export declare function parseCapabilityManifest(value: unknown): CapabilityManifestV1;
+/** Stable JSON bytes/order for catalog reflection and cross-runtime fixtures. */
+export declare function serializeCapabilityManifest(value: unknown): string;
+/**
+ * Catalog/policy boundary. Missing and invalid metadata are explicit and
+ * agent-ineligible; ordinary execution remains unchanged until policy opts in.
+ */
+export declare function assessCapabilityManifest(value: unknown): CapabilityManifestAssessment;
+/** Fail-closed helper for the future agent execution policy boundary. */
+export declare function requireAgentEligibleManifest(value: unknown): CapabilityManifestV1;

package/dist/CapabilityManifest.js

@@ -0,0 +1,172 @@
+/**
+ * Language-neutral operational metadata for nodes and workflows (ADR 0003).
+ *
+ * Schemas describe values; this manifest describes risk. It is deliberately
+ * data-only so every SDK can emit the same JSON through gRPC `ListNodes`.
+ * Unknown object fields are ignored when parsing v1, allowing additive wire
+ * evolution, while an unknown VERSION remains ineligible for agent execution.
+ */
+export const CAPABILITY_MANIFEST_VERSION = "1";
+export const CAPABILITY_EFFECTS = [
+    "read",
+    "write",
+    "network",
+    "filesystem",
+    "process",
+    "secret",
+    "streaming",
+    "destructive",
+];
+export const CAPABILITY_CLASSIFICATIONS = ["agent-compatible", "trusted-legacy", "denied-to-agents"];
+export const CAPABILITY_DETERMINISM = ["deterministic", "time-dependent", "random", "external", "unknown"];
+export const CAPABILITY_IDEMPOTENCY = ["idempotent", "conditionally-idempotent", "non-idempotent", "unknown"];
+export const CAPABILITY_MATURITY = ["stable", "beta", "experimental", "deprecated"];
+export class CapabilityManifestError extends Error {
+    errors;
+    constructor(errors) {
+        super(`Invalid capability manifest: ${errors.join("; ")}`);
+        this.name = "CapabilityManifestError";
+        this.errors = [...errors];
+    }
+}
+const IDENTIFIER = /^[A-Za-z][A-Za-z0-9._:/-]{0,127}$/;
+const EFFECT_SET = new Set(CAPABILITY_EFFECTS);
+const CLASSIFICATION_SET = new Set(CAPABILITY_CLASSIFICATIONS);
+const DETERMINISM_SET = new Set(CAPABILITY_DETERMINISM);
+const IDEMPOTENCY_SET = new Set(CAPABILITY_IDEMPOTENCY);
+const MATURITY_SET = new Set(CAPABILITY_MATURITY);
+const RESOURCE_KEYS = ["maxDurationMs", "maxMemoryBytes", "maxInputBytes", "maxOutputBytes", "maxConcurrency"];
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function enumValue(value, path, allowed, errors) {
+    if (typeof value !== "string" || !allowed.has(value)) {
+        errors.push(`${path} must be one of: ${[...allowed].join(", ")}`);
+        return undefined;
+    }
+    return value;
+}
+function stringList(value, path, errors, allowed) {
+    if (!Array.isArray(value)) {
+        errors.push(`${path} must be an array`);
+        return [];
+    }
+    const result = new Set();
+    for (let i = 0; i < value.length; i++) {
+        const item = value[i];
+        if (typeof item !== "string" || (!allowed && !IDENTIFIER.test(item)) || (allowed && !allowed.has(item))) {
+            errors.push(`${path}[${i}] is not a valid ${allowed ? "value" : "identifier"}`);
+            continue;
+        }
+        result.add(item);
+    }
+    return [...result].sort();
+}
+function resourceBounds(value, errors) {
+    if (value === undefined)
+        return undefined;
+    if (!isRecord(value)) {
+        errors.push("resources must be an object");
+        return undefined;
+    }
+    const result = {};
+    for (const key of RESOURCE_KEYS) {
+        const raw = value[key];
+        if (raw === undefined)
+            continue;
+        if (typeof raw !== "number" || !Number.isSafeInteger(raw) || raw <= 0) {
+            errors.push(`resources.${key} must be a positive safe integer`);
+            continue;
+        }
+        result[key] = raw;
+    }
+    return Object.keys(result).length > 0 ? result : undefined;
+}
+/** Parse and normalize a v1 manifest. Additive unknown fields are ignored. */
+export function parseCapabilityManifest(value) {
+    const errors = [];
+    if (!isRecord(value))
+        throw new CapabilityManifestError(["manifest must be an object"]);
+    if (value.version !== CAPABILITY_MANIFEST_VERSION) {
+        errors.push(`version must be ${CAPABILITY_MANIFEST_VERSION}`);
+    }
+    const classification = enumValue(value.classification, "classification", CLASSIFICATION_SET, errors);
+    const determinism = enumValue(value.determinism, "determinism", DETERMINISM_SET, errors);
+    const idempotency = enumValue(value.idempotency, "idempotency", IDEMPOTENCY_SET, errors);
+    const maturity = enumValue(value.maturity, "maturity", MATURITY_SET, errors);
+    const effects = stringList(value.effects, "effects", errors, EFFECT_SET);
+    const capabilities = stringList(value.capabilities, "capabilities", errors);
+    const secrets = stringList(value.secrets, "secrets", errors);
+    const resources = resourceBounds(value.resources, errors);
+    const runtimes = value.runtimes === undefined ? undefined : stringList(value.runtimes, "runtimes", errors);
+    const triggers = value.triggers === undefined ? undefined : stringList(value.triggers, "triggers", errors);
+    if (errors.length > 0 || !classification || !determinism || !idempotency || !maturity) {
+        throw new CapabilityManifestError(errors);
+    }
+    return {
+        version: CAPABILITY_MANIFEST_VERSION,
+        classification,
+        effects,
+        capabilities,
+        secrets,
+        determinism,
+        idempotency,
+        maturity,
+        ...(resources ? { resources } : {}),
+        ...(runtimes ? { runtimes } : {}),
+        ...(triggers ? { triggers } : {}),
+    };
+}
+/** Stable JSON bytes/order for catalog reflection and cross-runtime fixtures. */
+export function serializeCapabilityManifest(value) {
+    return JSON.stringify(parseCapabilityManifest(value));
+}
+/**
+ * Catalog/policy boundary. Missing and invalid metadata are explicit and
+ * agent-ineligible; ordinary execution remains unchanged until policy opts in.
+ */
+export function assessCapabilityManifest(value) {
+    if (value === undefined || value === null || value === "") {
+        return {
+            status: "missing",
+            manifest: null,
+            errors: [],
+            agentEligible: false,
+            reason: "missing-manifest",
+        };
+    }
+    try {
+        const manifest = parseCapabilityManifest(value);
+        const eligible = manifest.classification === "agent-compatible";
+        const reason = eligible
+            ? "eligible"
+            : manifest.classification === "trusted-legacy"
+                ? "trusted-legacy"
+                : "denied-to-agents";
+        return {
+            status: "declared",
+            manifest,
+            errors: [],
+            agentEligible: eligible,
+            reason,
+        };
+    }
+    catch (error) {
+        const errors = error instanceof CapabilityManifestError ? [...error.errors] : [String(error)];
+        return {
+            status: "invalid",
+            manifest: null,
+            errors,
+            agentEligible: false,
+            reason: "invalid-manifest",
+        };
+    }
+}
+/** Fail-closed helper for the future agent execution policy boundary. */
+export function requireAgentEligibleManifest(value) {
+    const assessment = assessCapabilityManifest(value);
+    if (assessment.agentEligible && assessment.manifest)
+        return assessment.manifest;
+    const detail = assessment.errors.length > 0 ? assessment.errors : [assessment.reason];
+    throw new CapabilityManifestError(detail);
+}

package/dist/EnforcementContracts.d.ts

@@ -0,0 +1,61 @@
+/**
+ * H1-02 contracts shared by authoring, the runner, and control-plane adapters.
+ *
+ * These are deliberately data-only. A model can return data that resembles a
+ * trusted record, but the runner decides whether the producing step is allowed
+ * to establish trusted provenance.
+ */
+export declare const ENFORCEMENT_CONTRACT_VERSION: "1";
+export type OutputTrust = "model" | "trusted";
+export interface AgentCompletionContract {
+    readonly required?: boolean;
+    /** Dot-separated output path; defaults to `completed`. */
+    readonly path?: string;
+    /** Expected value at `path`; defaults to `true`. */
+    readonly equals?: unknown;
+}
+export interface AgentStepContract {
+    readonly version: typeof ENFORCEMENT_CONTRACT_VERSION;
+    readonly objective: string;
+    readonly completion: AgentCompletionContract;
+}
+export interface ApprovalContract {
+    readonly version: typeof ENFORCEMENT_CONTRACT_VERSION;
+    readonly reason: string;
+    readonly scope?: string;
+}
+export interface AssertionGateContract {
+    readonly version: typeof ENFORCEMENT_CONTRACT_VERSION;
+    readonly path?: string;
+    readonly equals?: unknown;
+    readonly truthy?: boolean;
+    readonly message?: string;
+}
+export interface EvidenceGateRequirement {
+    readonly artifactId: string;
+    readonly artifactVersion: string;
+    readonly producerStepId: string;
+}
+export interface EvidenceGateContract {
+    readonly version: typeof ENFORCEMENT_CONTRACT_VERSION;
+    readonly requirements: readonly EvidenceGateRequirement[];
+}
+export interface TrustedEvidence {
+    readonly version: typeof ENFORCEMENT_CONTRACT_VERSION;
+    readonly provenance: "trusted";
+    readonly producer: {
+        readonly stepId: string;
+        readonly workflow: string;
+    };
+    readonly artifact: {
+        readonly id: string;
+        readonly version: string;
+    };
+    readonly verified: true;
+    readonly verification?: string;
+}
+export declare class EnforcementViolationError extends Error {
+    readonly reasonCode: string;
+    readonly code = "ENFORCEMENT_REJECTED";
+    constructor(reasonCode: string, message: string);
+}