@blokjs/shared 2.0.1 → 2.2.0

package/dist/JoinContracts.d.ts

@@ -0,0 +1,593 @@
+import { z } from "zod";
+import { type CapabilityEffect } from "./CapabilityManifest.js";
+import { type EvidenceRequirement } from "./EvidenceContracts.js";
+import { type CapabilityAuthority } from "./PermissionAlgebra.js";
+/** Version of the language-neutral branch-join contract. */
+export declare const JOIN_CONTRACT_VERSION: "1";
+export declare const JOIN_MAX_BRANCHES = 128;
+export declare const JOIN_MAX_OUTPUTS = 128;
+export declare const JOIN_MAX_SCHEMA_DEPTH = 8;
+export declare const JOIN_MAX_CONTRACT_BYTES: number;
+/** Version of the retry/resume idempotency contract. */
+export declare const RETRY_RESUME_IDEMPOTENCY_CONTRACT_VERSION: "1";
+export declare const RETRY_RESUME_MAX_ATTEMPTS = 20;
+export declare const RETRY_RESUME_MAX_RESUMES = 100;
+export declare const RETRY_RESUME_MAX_EVIDENCE = 64;
+declare const jsonSchema: z.ZodUnion<[z.ZodBoolean, z.ZodRecord<z.ZodString, z.ZodUnknown>]>;
+export type JoinJsonSchema = z.infer<typeof jsonSchema>;
+export type JoinBranchStatus = "completed" | "failed" | "cancelled" | "missing";
+export interface JoinBranchObligation {
+    readonly id: string;
+    /** Optional branches may be absent; required branches must complete. */
+    readonly required: boolean;
+    /** Evidence required before this branch can contribute to the join. */
+    readonly evidence?: readonly EvidenceRequirement[];
+}
+export interface JoinOutputDeclaration {
+    readonly id: string;
+    readonly branchId: string;
+    readonly path: readonly (string | number)[];
+    /** JSON Schema for the value exported from the branch. */
+    readonly schema: JoinJsonSchema;
+}
+export interface JoinContract {
+    readonly version: typeof JOIN_CONTRACT_VERSION;
+    readonly id: string;
+    /** `all` requires every required branch; `any` requires one completed branch. */
+    readonly mode: "all" | "any";
+    readonly branches: readonly JoinBranchObligation[];
+    readonly outputs: readonly JoinOutputDeclaration[];
+    /** Optional effective authority carried across the join boundary. */
+    readonly authority?: CapabilityAuthority;
+}
+export interface JoinBranchResult {
+    readonly id: string;
+    readonly status: JoinBranchStatus;
+    readonly output?: unknown;
+    readonly evidence?: readonly unknown[];
+}
+export interface JoinResult {
+    readonly branches: readonly JoinBranchResult[];
+}
+/** Effects use the canonical capability-manifest vocabulary (and therefore the authority algebra). */
+export type RetryResumeEffect = "none" | CapabilityEffect;
+export type RetryResumeIdempotencyMode = "not-required" | "keyed" | "evidence-required";
+export interface RetryResumeIdempotencyContract {
+    readonly version: typeof RETRY_RESUME_IDEMPOTENCY_CONTRACT_VERSION;
+    readonly id: string;
+    readonly stepId: string;
+    readonly effect: RetryResumeEffect;
+    readonly maxAttempts: number;
+    readonly maxResumes: number;
+    readonly idempotency: {
+        readonly mode: RetryResumeIdempotencyMode;
+        /** The key is deliberately a declaration, never the secret/raw value. */
+        readonly keyDeclared?: boolean;
+    };
+    readonly evidence?: readonly EvidenceRequirement[];
+    /** Optional effective authority bound to every retry/resume attempt. */
+    readonly authority?: CapabilityAuthority;
+}
+export type EffectRetryEvidenceOutcome = "committed" | "deduplicated" | "not-committed";
+export interface EffectRetryEvidence {
+    readonly version: typeof RETRY_RESUME_IDEMPOTENCY_CONTRACT_VERSION;
+    readonly id: string;
+    readonly stepId: string;
+    readonly runId: string;
+    readonly attempt: number;
+    readonly effect: CapabilityEffect;
+    /** Digest of the resolved idempotency key; the raw key is never persisted. */
+    readonly idempotencyKeyDigest: string;
+    readonly outcome: EffectRetryEvidenceOutcome;
+    readonly producer: {
+        readonly kind: "capability" | "deterministic-step" | "runner";
+        readonly id: string;
+    };
+    readonly observedAt: string;
+}
+export declare class JoinContractError extends Error {
+    readonly reasonCode: string;
+    readonly code = "JOIN_REJECTED";
+    constructor(reasonCode: string, message: string);
+}
+export declare class RetryResumeContractError extends Error {
+    readonly reasonCode: string;
+    readonly code = "RETRY_RESUME_REJECTED";
+    constructor(reasonCode: string, message: string);
+}
+export declare const JoinBranchObligationSchema: z.ZodObject<{
+    id: z.ZodString;
+    required: z.ZodBoolean;
+    evidence: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        type: z.ZodLiteral<"evidence">;
+        id: z.ZodString;
+        kind: z.ZodString;
+        claim: z.ZodOptional<z.ZodString>;
+        artifactKind: z.ZodOptional<z.ZodString>;
+        producers: z.ZodArray<z.ZodEnum<["capability", "deterministic-step", "runner"]>, "many">;
+        verification: z.ZodLiteral<"verified">;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        kind: string;
+        type: "evidence";
+        verification: "verified";
+        producers: ("capability" | "deterministic-step" | "runner")[];
+        claim?: string | undefined;
+        artifactKind?: string | undefined;
+    }, {
+        id: string;
+        kind: string;
+        type: "evidence";
+        verification: "verified";
+        producers: ("capability" | "deterministic-step" | "runner")[];
+        claim?: string | undefined;
+        artifactKind?: string | undefined;
+    }>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    required: boolean;
+    evidence?: {
+        id: string;
+        kind: string;
+        type: "evidence";
+        verification: "verified";
+        producers: ("capability" | "deterministic-step" | "runner")[];
+        claim?: string | undefined;
+        artifactKind?: string | undefined;
+    }[] | undefined;
+}, {
+    id: string;
+    required: boolean;
+    evidence?: {
+        id: string;
+        kind: string;
+        type: "evidence";
+        verification: "verified";
+        producers: ("capability" | "deterministic-step" | "runner")[];
+        claim?: string | undefined;
+        artifactKind?: string | undefined;
+    }[] | undefined;
+}>;
+export declare const JoinOutputDeclarationSchema: z.ZodObject<{
+    id: z.ZodString;
+    branchId: z.ZodString;
+    path: z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodNumber]>, "many">;
+    schema: z.ZodUnion<[z.ZodBoolean, z.ZodRecord<z.ZodString, z.ZodUnknown>]>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    path: (string | number)[];
+    branchId: string;
+    schema: boolean | Record<string, unknown>;
+}, {
+    id: string;
+    path: (string | number)[];
+    branchId: string;
+    schema: boolean | Record<string, unknown>;
+}>;
+export declare const JoinContractSchema: z.ZodEffects<z.ZodObject<{
+    version: z.ZodLiteral<"1">;
+    id: z.ZodString;
+    mode: z.ZodEnum<["all", "any"]>;
+    branches: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        required: z.ZodBoolean;
+        evidence: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            type: z.ZodLiteral<"evidence">;
+            id: z.ZodString;
+            kind: z.ZodString;
+            claim: z.ZodOptional<z.ZodString>;
+            artifactKind: z.ZodOptional<z.ZodString>;
+            producers: z.ZodArray<z.ZodEnum<["capability", "deterministic-step", "runner"]>, "many">;
+            verification: z.ZodLiteral<"verified">;
+        }, "strip", z.ZodTypeAny, {
+            id: string;
+            kind: string;
+            type: "evidence";
+            verification: "verified";
+            producers: ("capability" | "deterministic-step" | "runner")[];
+            claim?: string | undefined;
+            artifactKind?: string | undefined;
+        }, {
+            id: string;
+            kind: string;
+            type: "evidence";
+            verification: "verified";
+            producers: ("capability" | "deterministic-step" | "runner")[];
+            claim?: string | undefined;
+            artifactKind?: string | undefined;
+        }>, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        required: boolean;
+        evidence?: {
+            id: string;
+            kind: string;
+            type: "evidence";
+            verification: "verified";
+            producers: ("capability" | "deterministic-step" | "runner")[];
+            claim?: string | undefined;
+            artifactKind?: string | undefined;
+        }[] | undefined;
+    }, {
+        id: string;
+        required: boolean;
+        evidence?: {
+            id: string;
+            kind: string;
+            type: "evidence";
+            verification: "verified";
+            producers: ("capability" | "deterministic-step" | "runner")[];
+            claim?: string | undefined;
+            artifactKind?: string | undefined;
+        }[] | undefined;
+    }>, "many">;
+    outputs: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        branchId: z.ZodString;
+        path: z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodNumber]>, "many">;
+        schema: z.ZodUnion<[z.ZodBoolean, z.ZodRecord<z.ZodString, z.ZodUnknown>]>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        path: (string | number)[];
+        branchId: string;
+        schema: boolean | Record<string, unknown>;
+    }, {
+        id: string;
+        path: (string | number)[];
+        branchId: string;
+        schema: boolean | Record<string, unknown>;
+    }>, "many">;
+    authority: z.ZodOptional<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>;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    version: "1";
+    mode: "all" | "any";
+    branches: {
+        id: string;
+        required: boolean;
+        evidence?: {
+            id: string;
+            kind: string;
+            type: "evidence";
+            verification: "verified";
+            producers: ("capability" | "deterministic-step" | "runner")[];
+            claim?: string | undefined;
+            artifactKind?: string | undefined;
+        }[] | undefined;
+    }[];
+    outputs: {
+        id: string;
+        path: (string | number)[];
+        branchId: string;
+        schema: boolean | Record<string, unknown>;
+    }[];
+    authority?: {
+        effects: ("read" | "write" | "network" | "filesystem" | "process" | "secret" | "streaming" | "destructive")[];
+        capabilities: string[];
+        secrets: string[];
+        fragments: Record<string, string | number | boolean>;
+    } | undefined;
+}, {
+    id: string;
+    version: "1";
+    mode: "all" | "any";
+    branches: {
+        id: string;
+        required: boolean;
+        evidence?: {
+            id: string;
+            kind: string;
+            type: "evidence";
+            verification: "verified";
+            producers: ("capability" | "deterministic-step" | "runner")[];
+            claim?: string | undefined;
+            artifactKind?: string | undefined;
+        }[] | undefined;
+    }[];
+    outputs: {
+        id: string;
+        path: (string | number)[];
+        branchId: string;
+        schema: boolean | Record<string, unknown>;
+    }[];
+    authority?: {
+        effects: ("read" | "write" | "network" | "filesystem" | "process" | "secret" | "streaming" | "destructive")[];
+        capabilities: string[];
+        secrets: string[];
+        fragments: Record<string, string | number | boolean>;
+    } | undefined;
+}>, {
+    id: string;
+    version: "1";
+    mode: "all" | "any";
+    branches: {
+        id: string;
+        required: boolean;
+        evidence?: {
+            id: string;
+            kind: string;
+            type: "evidence";
+            verification: "verified";
+            producers: ("capability" | "deterministic-step" | "runner")[];
+            claim?: string | undefined;
+            artifactKind?: string | undefined;
+        }[] | undefined;
+    }[];
+    outputs: {
+        id: string;
+        path: (string | number)[];
+        branchId: string;
+        schema: boolean | Record<string, unknown>;
+    }[];
+    authority?: {
+        effects: ("read" | "write" | "network" | "filesystem" | "process" | "secret" | "streaming" | "destructive")[];
+        capabilities: string[];
+        secrets: string[];
+        fragments: Record<string, string | number | boolean>;
+    } | undefined;
+}, {
+    id: string;
+    version: "1";
+    mode: "all" | "any";
+    branches: {
+        id: string;
+        required: boolean;
+        evidence?: {
+            id: string;
+            kind: string;
+            type: "evidence";
+            verification: "verified";
+            producers: ("capability" | "deterministic-step" | "runner")[];
+            claim?: string | undefined;
+            artifactKind?: string | undefined;
+        }[] | undefined;
+    }[];
+    outputs: {
+        id: string;
+        path: (string | number)[];
+        branchId: string;
+        schema: boolean | Record<string, unknown>;
+    }[];
+    authority?: {
+        effects: ("read" | "write" | "network" | "filesystem" | "process" | "secret" | "streaming" | "destructive")[];
+        capabilities: string[];
+        secrets: string[];
+        fragments: Record<string, string | number | boolean>;
+    } | undefined;
+}>;
+export declare const RetryResumeIdempotencyContractSchema: z.ZodEffects<z.ZodObject<{
+    version: z.ZodLiteral<"1">;
+    id: z.ZodString;
+    stepId: z.ZodString;
+    effect: z.ZodEnum<["none", "read", "write", "network", "filesystem", "process", "secret", "streaming", "destructive"]>;
+    maxAttempts: z.ZodNumber;
+    maxResumes: z.ZodNumber;
+    idempotency: z.ZodObject<{
+        mode: z.ZodEnum<["not-required", "keyed", "evidence-required"]>;
+        keyDeclared: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        mode: "not-required" | "keyed" | "evidence-required";
+        keyDeclared?: boolean | undefined;
+    }, {
+        mode: "not-required" | "keyed" | "evidence-required";
+        keyDeclared?: boolean | undefined;
+    }>;
+    evidence: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        type: z.ZodLiteral<"evidence">;
+        id: z.ZodString;
+        kind: z.ZodString;
+        claim: z.ZodOptional<z.ZodString>;
+        artifactKind: z.ZodOptional<z.ZodString>;
+        producers: z.ZodArray<z.ZodEnum<["capability", "deterministic-step", "runner"]>, "many">;
+        verification: z.ZodLiteral<"verified">;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        kind: string;
+        type: "evidence";
+        verification: "verified";
+        producers: ("capability" | "deterministic-step" | "runner")[];
+        claim?: string | undefined;
+        artifactKind?: string | undefined;
+    }, {
+        id: string;
+        kind: string;
+        type: "evidence";
+        verification: "verified";
+        producers: ("capability" | "deterministic-step" | "runner")[];
+        claim?: string | undefined;
+        artifactKind?: string | undefined;
+    }>, "many">>;
+    authority: z.ZodOptional<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>;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    version: "1";
+    idempotency: {
+        mode: "not-required" | "keyed" | "evidence-required";
+        keyDeclared?: boolean | undefined;
+    };
+    effect: "read" | "write" | "network" | "filesystem" | "process" | "secret" | "streaming" | "destructive" | "none";
+    stepId: string;
+    maxAttempts: number;
+    maxResumes: number;
+    authority?: {
+        effects: ("read" | "write" | "network" | "filesystem" | "process" | "secret" | "streaming" | "destructive")[];
+        capabilities: string[];
+        secrets: string[];
+        fragments: Record<string, string | number | boolean>;
+    } | undefined;
+    evidence?: {
+        id: string;
+        kind: string;
+        type: "evidence";
+        verification: "verified";
+        producers: ("capability" | "deterministic-step" | "runner")[];
+        claim?: string | undefined;
+        artifactKind?: string | undefined;
+    }[] | undefined;
+}, {
+    id: string;
+    version: "1";
+    idempotency: {
+        mode: "not-required" | "keyed" | "evidence-required";
+        keyDeclared?: boolean | undefined;
+    };
+    effect: "read" | "write" | "network" | "filesystem" | "process" | "secret" | "streaming" | "destructive" | "none";
+    stepId: string;
+    maxAttempts: number;
+    maxResumes: number;
+    authority?: {
+        effects: ("read" | "write" | "network" | "filesystem" | "process" | "secret" | "streaming" | "destructive")[];
+        capabilities: string[];
+        secrets: string[];
+        fragments: Record<string, string | number | boolean>;
+    } | undefined;
+    evidence?: {
+        id: string;
+        kind: string;
+        type: "evidence";
+        verification: "verified";
+        producers: ("capability" | "deterministic-step" | "runner")[];
+        claim?: string | undefined;
+        artifactKind?: string | undefined;
+    }[] | undefined;
+}>, {
+    id: string;
+    version: "1";
+    idempotency: {
+        mode: "not-required" | "keyed" | "evidence-required";
+        keyDeclared?: boolean | undefined;
+    };
+    effect: "read" | "write" | "network" | "filesystem" | "process" | "secret" | "streaming" | "destructive" | "none";
+    stepId: string;
+    maxAttempts: number;
+    maxResumes: number;
+    authority?: {
+        effects: ("read" | "write" | "network" | "filesystem" | "process" | "secret" | "streaming" | "destructive")[];
+        capabilities: string[];
+        secrets: string[];
+        fragments: Record<string, string | number | boolean>;
+    } | undefined;
+    evidence?: {
+        id: string;
+        kind: string;
+        type: "evidence";
+        verification: "verified";
+        producers: ("capability" | "deterministic-step" | "runner")[];
+        claim?: string | undefined;
+        artifactKind?: string | undefined;
+    }[] | undefined;
+}, {
+    id: string;
+    version: "1";
+    idempotency: {
+        mode: "not-required" | "keyed" | "evidence-required";
+        keyDeclared?: boolean | undefined;
+    };
+    effect: "read" | "write" | "network" | "filesystem" | "process" | "secret" | "streaming" | "destructive" | "none";
+    stepId: string;
+    maxAttempts: number;
+    maxResumes: number;
+    authority?: {
+        effects: ("read" | "write" | "network" | "filesystem" | "process" | "secret" | "streaming" | "destructive")[];
+        capabilities: string[];
+        secrets: string[];
+        fragments: Record<string, string | number | boolean>;
+    } | undefined;
+    evidence?: {
+        id: string;
+        kind: string;
+        type: "evidence";
+        verification: "verified";
+        producers: ("capability" | "deterministic-step" | "runner")[];
+        claim?: string | undefined;
+        artifactKind?: string | undefined;
+    }[] | undefined;
+}>;
+export declare const EffectRetryEvidenceSchema: z.ZodObject<{
+    version: z.ZodLiteral<"1">;
+    id: z.ZodString;
+    stepId: z.ZodString;
+    runId: z.ZodString;
+    attempt: z.ZodNumber;
+    effect: z.ZodEnum<["read", "write", "network", "filesystem", "process", "secret", "streaming", "destructive"]>;
+    idempotencyKeyDigest: z.ZodString;
+    outcome: z.ZodEnum<["committed", "deduplicated", "not-committed"]>;
+    producer: z.ZodObject<{
+        kind: z.ZodEnum<["capability", "deterministic-step", "runner"]>;
+        id: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        kind: "capability" | "deterministic-step" | "runner";
+    }, {
+        id: string;
+        kind: "capability" | "deterministic-step" | "runner";
+    }>;
+    observedAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    version: "1";
+    attempt: number;
+    runId: string;
+    producer: {
+        id: string;
+        kind: "capability" | "deterministic-step" | "runner";
+    };
+    outcome: "committed" | "deduplicated" | "not-committed";
+    observedAt: string;
+    effect: "read" | "write" | "network" | "filesystem" | "process" | "secret" | "streaming" | "destructive";
+    stepId: string;
+    idempotencyKeyDigest: string;
+}, {
+    id: string;
+    version: "1";
+    attempt: number;
+    runId: string;
+    producer: {
+        id: string;
+        kind: "capability" | "deterministic-step" | "runner";
+    };
+    outcome: "committed" | "deduplicated" | "not-committed";
+    observedAt: string;
+    effect: "read" | "write" | "network" | "filesystem" | "process" | "secret" | "streaming" | "destructive";
+    stepId: string;
+    idempotencyKeyDigest: string;
+}>;
+/** Validate branch completion, evidence, and declared output types at a join boundary. */
+export declare function assertJoinSatisfied(contract: JoinContract, result: JoinResult): void;
+export declare function parseJoinContract(value: unknown): JoinContract;
+export declare function serializeJoinContract(value: unknown): string;
+export declare function parseRetryResumeIdempotencyContract(value: unknown): RetryResumeIdempotencyContract;
+export declare function parseEffectRetryEvidence(value: unknown): EffectRetryEvidence;
+/** Require an evidence record for effectful retry/resume; no effect is retried without proof. */
+export declare function assertEffectRetryEvidence(contract: RetryResumeIdempotencyContract, evidence: readonly unknown[]): void;
+export {};