@odingard/guardian-sdk 0.1.0 → 0.2.0

package/dist-dts/contracts/sources.d.ts

@@ -0,0 +1,191 @@
+import { z } from "zod";
+/**
+ * WO-027: guardian.sources.v1 — authority sources and policy-source
+ * precedence (GUA-AUTHORITY-OS-001 §31–33).
+ *
+ * An authority source is a registered pack of constraints contributed by a
+ * party whose authority intersects with the principal's: a human, family,
+ * resource owner, organization, counterparty, jurisdiction, safety policy,
+ * provider, or device policy. Precedence is deterministic intersection —
+ * the strongest restriction wins per dimension and the result can only
+ * NARROW the principal's authority, never enlarge it (§32). Packs from
+ * mandatory kinds (jurisdiction, safety_policy, or any pack flagged
+ * mandatory) require trusted provenance and versioning: an unprovenanced,
+ * stale, or unsigned pack fails closed and is never applied (§33).
+ */
+export declare const SOURCES_CONTRACT_SCHEMA = "guardian.sources.v1";
+export declare const AuthoritySourceKindSchema: z.ZodEnum<{
+    human: "human";
+    counterparty: "counterparty";
+    family: "family";
+    resource_owner: "resource_owner";
+    organization: "organization";
+    jurisdiction: "jurisdiction";
+    safety_policy: "safety_policy";
+    provider: "provider";
+    device_policy: "device_policy";
+}>;
+export type AuthoritySourceKind = z.infer<typeof AuthoritySourceKindSchema>;
+/** Source kinds whose packs are mandatory-rule packs under §33. */
+export declare const MANDATORY_SOURCE_KINDS: readonly AuthoritySourceKind[];
+export declare const SourceProvenanceSchema: z.ZodObject<{
+    issuer: z.ZodString;
+    version: z.ZodNumber;
+    registeredAtEpochMs: z.ZodNumber;
+}, z.core.$strict>;
+export type SourceProvenance = z.infer<typeof SourceProvenanceSchema>;
+/**
+ * Declarative constraints one source contributes. Every field narrows in
+ * exactly one direction under intersection; absent means unconstrained on
+ * that dimension.
+ */
+export declare const SourceConstraintsSchema: z.ZodObject<{
+    allowedActions: z.ZodOptional<z.ZodArray<z.core.$ZodBranded<z.ZodString, "ActionType", "out">>>;
+    deniedActions: z.ZodOptional<z.ZodArray<z.core.$ZodBranded<z.ZodString, "ActionType", "out">>>;
+    allowedResources: z.ZodOptional<z.ZodArray<z.core.$ZodBranded<z.ZodString, "ResourceRef", "out">>>;
+    allowedInterfaces: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        mcp: "mcp";
+        rest: "rest";
+        internal: "internal";
+    }>>>;
+    maxValueCents: z.ZodOptional<z.ZodNumber>;
+    maxUses: z.ZodOptional<z.ZodNumber>;
+    minRuntimeLevel: z.ZodOptional<z.ZodEnum<{
+        T0_UNKNOWN: "T0_UNKNOWN";
+        T1_IDENTIFIED: "T1_IDENTIFIED";
+        T2_VERIFIED: "T2_VERIFIED";
+        T3_ATTESTED: "T3_ATTESTED";
+        T4_HARDWARE_BACKED: "T4_HARDWARE_BACKED";
+    }>>;
+    minAssuranceLevel: z.ZodOptional<z.ZodEnum<{
+        G2_CREDENTIAL_MEDIATED: "G2_CREDENTIAL_MEDIATED";
+        G1_POLICY_MEDIATED: "G1_POLICY_MEDIATED";
+        G3_RUNTIME_CONTAINED: "G3_RUNTIME_CONTAINED";
+        G0_OBSERVED: "G0_OBSERVED";
+        G4_COUNTERPARTY_INTERLOCKED: "G4_COUNTERPARTY_INTERLOCKED";
+    }>>;
+    requiredApprovals: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export type SourceConstraints = z.infer<typeof SourceConstraintsSchema>;
+export declare const SourceSignatureSchema: z.ZodObject<{
+    algorithm: z.ZodLiteral<"ed25519">;
+    value: z.ZodString;
+}, z.core.$strict>;
+export type SourceSignature = z.infer<typeof SourceSignatureSchema>;
+export declare const AuthoritySourcePackSchema: z.ZodObject<{
+    schema: z.ZodLiteral<"guardian.sources.v1">;
+    sourceId: z.ZodString;
+    tenantId: z.core.$ZodBranded<z.ZodString, "TenantId", "out">;
+    kind: z.ZodEnum<{
+        human: "human";
+        counterparty: "counterparty";
+        family: "family";
+        resource_owner: "resource_owner";
+        organization: "organization";
+        jurisdiction: "jurisdiction";
+        safety_policy: "safety_policy";
+        provider: "provider";
+        device_policy: "device_policy";
+    }>;
+    mandatory: z.ZodOptional<z.ZodBoolean>;
+    provenance: z.ZodObject<{
+        issuer: z.ZodString;
+        version: z.ZodNumber;
+        registeredAtEpochMs: z.ZodNumber;
+    }, z.core.$strict>;
+    constraints: z.ZodObject<{
+        allowedActions: z.ZodOptional<z.ZodArray<z.core.$ZodBranded<z.ZodString, "ActionType", "out">>>;
+        deniedActions: z.ZodOptional<z.ZodArray<z.core.$ZodBranded<z.ZodString, "ActionType", "out">>>;
+        allowedResources: z.ZodOptional<z.ZodArray<z.core.$ZodBranded<z.ZodString, "ResourceRef", "out">>>;
+        allowedInterfaces: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            mcp: "mcp";
+            rest: "rest";
+            internal: "internal";
+        }>>>;
+        maxValueCents: z.ZodOptional<z.ZodNumber>;
+        maxUses: z.ZodOptional<z.ZodNumber>;
+        minRuntimeLevel: z.ZodOptional<z.ZodEnum<{
+            T0_UNKNOWN: "T0_UNKNOWN";
+            T1_IDENTIFIED: "T1_IDENTIFIED";
+            T2_VERIFIED: "T2_VERIFIED";
+            T3_ATTESTED: "T3_ATTESTED";
+            T4_HARDWARE_BACKED: "T4_HARDWARE_BACKED";
+        }>>;
+        minAssuranceLevel: z.ZodOptional<z.ZodEnum<{
+            G2_CREDENTIAL_MEDIATED: "G2_CREDENTIAL_MEDIATED";
+            G1_POLICY_MEDIATED: "G1_POLICY_MEDIATED";
+            G3_RUNTIME_CONTAINED: "G3_RUNTIME_CONTAINED";
+            G0_OBSERVED: "G0_OBSERVED";
+            G4_COUNTERPARTY_INTERLOCKED: "G4_COUNTERPARTY_INTERLOCKED";
+        }>>;
+        requiredApprovals: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+    status: z.ZodEnum<{
+        active: "active";
+        revoked: "revoked";
+    }>;
+    version: z.ZodNumber;
+    signature: z.ZodOptional<z.ZodObject<{
+        algorithm: z.ZodLiteral<"ed25519">;
+        value: z.ZodString;
+    }, z.core.$strict>>;
+    createdAtEpochMs: z.ZodNumber;
+    updatedAtEpochMs: z.ZodNumber;
+}, z.core.$strict>;
+export type AuthoritySourcePack = z.infer<typeof AuthoritySourcePackSchema>;
+/** Deployment trust policy: which issuers may contribute packs and how they sign. */
+export declare const SourceTrustPolicySchema: z.ZodObject<{
+    trustedIssuers: z.ZodArray<z.ZodObject<{
+        issuer: z.ZodString;
+        publicKeyPem: z.ZodOptional<z.ZodString>;
+        minVersion: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type SourceTrustPolicy = z.infer<typeof SourceTrustPolicySchema>;
+export declare function isMandatorySource(pack: AuthoritySourcePack): boolean;
+/** The canonical digest a pack signature covers (everything except the signature). */
+export declare function sourcePackSigningDigest(pack: Pick<AuthoritySourcePack, "schema" | "sourceId" | "tenantId" | "kind" | "mandatory" | "provenance" | "constraints" | "version">): string;
+export declare function verifySourceSignature(pack: AuthoritySourcePack, publicKeyPem: string): boolean;
+export type ProvenanceCheck = {
+    ok: true;
+} | {
+    ok: false;
+    reason: "UNTRUSTED_ISSUER" | "STALE_VERSION" | "UNSIGNED_SOURCE" | "INVALID_SIGNATURE";
+};
+/**
+ * §33 — trusted provenance + versioning. A pack is established only when its
+ * issuer is trusted, its provenance version meets the issuer floor, and its
+ * signature verifies against the issuer's configured key. A mandatory pack
+ * with no verifiable signature (or no issuer key at all) fails closed.
+ */
+export declare function verifySourceProvenance(pack: AuthoritySourcePack, trustPolicy: SourceTrustPolicy): ProvenanceCheck;
+/**
+ * §32 — deterministic intersection: the strongest restriction wins per
+ * dimension. The result can never exceed what any contributing pack allows.
+ */
+export declare function intersectSourceConstraints(packs: readonly Pick<AuthoritySourcePack, "constraints">[]): SourceConstraints;
+export type AppliedAuthoritySources = Readonly<{
+    applied: readonly string[];
+    rejected: readonly Readonly<{
+        sourceId: string;
+        reason: string;
+    }>[];
+    constraints: SourceConstraints;
+}>;
+export type AuthoritySourcesOutcome = {
+    ok: true;
+    sources: AppliedAuthoritySources;
+} | {
+    ok: false;
+    reasonCode: string;
+};
+/**
+ * Establish and apply declared source packs. Tenant-mismatched, revoked,
+ * malformed, or unprovenanced packs are never applied; a mandatory pack that
+ * cannot be established fails the whole evaluation closed.
+ */
+export declare function applyAuthoritySources(input: {
+    packs: readonly AuthoritySourcePack[];
+    trustPolicy: SourceTrustPolicy;
+    tenantId: string;
+}): AuthoritySourcesOutcome;

package/dist-dts/contracts/tools.d.ts

@@ -23,9 +23,10 @@ export declare const TOOL_DESCRIPTION_MAX_LENGTH = 512;
 export declare const ToolNameSchema: z.ZodString;
 export type ToolName = z.infer<typeof ToolNameSchema>;
 /** A catalog entry: a named tool that renders to one allowlisted https call. */
-export declare const ToolDescriptorSchema: z.ZodObject<{
+export declare const ToolHttpDescriptorSchema: z.ZodObject<{
     name: z.ZodString;
     description: z.ZodOptional<z.ZodString>;
+    transport: z.ZodOptional<z.ZodLiteral<"http">>;
     method: z.ZodEnum<{
         GET: "GET";
         HEAD: "HEAD";
@@ -36,14 +37,53 @@ export declare const ToolDescriptorSchema: z.ZodObject<{
     }>;
     url: z.ZodString;
 }, z.core.$strict>;
+export type ToolHttpDescriptor = z.infer<typeof ToolHttpDescriptorSchema>;
+/**
+ * WO-021 — a `record` catalog entry: the tool's implementation lives
+ * in-host inside the tool-server runtime (framework adapters — Vercel AI,
+ * LangChain — register the impl host-side). There is no URL: the invocation
+ * never leaves the host, so no endpoint-allowlist leg exists. The governed
+ * flow is propose → ALLOW → local run → redeem+record → receipt; the impl
+ * runs exactly once, at commit, never before the decision and never again
+ * on a failed execute.
+ */
+export declare const ToolRecordDescriptorSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    transport: z.ZodLiteral<"record">;
+}, z.core.$strict>;
+export type ToolRecordDescriptor = z.infer<typeof ToolRecordDescriptorSchema>;
+export declare const ToolDescriptorSchema: z.ZodUnion<readonly [z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    transport: z.ZodLiteral<"record">;
+}, z.core.$strict>, z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    transport: z.ZodOptional<z.ZodLiteral<"http">>;
+    method: z.ZodEnum<{
+        GET: "GET";
+        HEAD: "HEAD";
+        POST: "POST";
+        PUT: "PUT";
+        PATCH: "PATCH";
+        DELETE: "DELETE";
+    }>;
+    url: z.ZodString;
+}, z.core.$strict>]>;
 export type ToolDescriptor = z.infer<typeof ToolDescriptorSchema>;
 /** The tool-server catalog stored on a provider "tool" connection record. */
 export declare const ToolServerCatalogSchema: z.ZodObject<{
     serverName: z.ZodString;
     serverVersion: z.ZodString;
-    tools: z.ZodArray<z.ZodObject<{
+    tools: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        transport: z.ZodLiteral<"record">;
+    }, z.core.$strict>, z.ZodObject<{
         name: z.ZodString;
         description: z.ZodOptional<z.ZodString>;
+        transport: z.ZodOptional<z.ZodLiteral<"http">>;
         method: z.ZodEnum<{
             GET: "GET";
             HEAD: "HEAD";
@@ -53,7 +93,7 @@ export declare const ToolServerCatalogSchema: z.ZodObject<{
             DELETE: "DELETE";
         }>;
         url: z.ZodString;
-    }, z.core.$strict>>;
+    }, z.core.$strict>]>>;
 }, z.core.$strict>;
 export type ToolServerCatalog = z.infer<typeof ToolServerCatalogSchema>;
 /** Bounded canonical JSON object (cycles, prototypes and depth are rejected). */
@@ -74,9 +114,14 @@ export type ToolInvokeParametersV1 = z.infer<typeof ToolInvokeParametersV1Schema
 export declare const McpInstallParametersV1Schema: z.ZodObject<{
     schema: z.ZodLiteral<"odingard.guardian.mcp.install.v1">;
     connectionId: z.core.$ZodBranded<z.ZodString, "ConnectionId", "out">;
-    tool: z.ZodObject<{
+    tool: z.ZodUnion<readonly [z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        transport: z.ZodLiteral<"record">;
+    }, z.core.$strict>, z.ZodObject<{
         name: z.ZodString;
         description: z.ZodOptional<z.ZodString>;
+        transport: z.ZodOptional<z.ZodLiteral<"http">>;
         method: z.ZodEnum<{
             GET: "GET";
             HEAD: "HEAD";
@@ -86,7 +131,7 @@ export declare const McpInstallParametersV1Schema: z.ZodObject<{
             DELETE: "DELETE";
         }>;
         url: z.ZodString;
-    }, z.core.$strict>;
+    }, z.core.$strict>]>;
 }, z.core.$strict>;
 export type McpInstallParametersV1 = z.infer<typeof McpInstallParametersV1Schema>;
 /** mcp.enable enables a catalog tool for the requesting agent. */

package/dist-dts/contracts/transaction.d.ts

@@ -0,0 +1,360 @@
+import { z } from "zod";
+/**
+ * WO-028: guardian.transaction.v1 — deterministic transaction authority
+ * (GUA-AUTHORITY-OS-001 §34–37, §79, §81).
+ *
+ * A transaction is the recorded lifecycle of one consequential action:
+ * PROPOSE → PREPARE → AUTHORIZE → LOCK → COMMIT → VERIFY → SETTLE, entered
+ * only when the action or its governing intent declares it. Every stage is
+ * a recorded transition bound to the canonical action digest; a skipped or
+ * out-of-order stage fails closed.
+ *
+ * The evaluator in this file is pure and deterministic. It never enlarges
+ * authority: it records what the authority path already decided, and a
+ * compensating action is a NEW governed action through the same
+ * ALLOW/ASK/DENY path — compensation never bypasses ASK. A transaction
+ * whose provider outcome is unconfirmed records UNKNOWN or MISMATCH; an
+ * unconfirmed effect is never reported SETTLED.
+ */
+export declare const TRANSACTION_CONTRACT_SCHEMA = "guardian.transaction.v1";
+export declare const TransactionStageSchema: z.ZodEnum<{
+    PROPOSE: "PROPOSE";
+    PREPARE: "PREPARE";
+    AUTHORIZE: "AUTHORIZE";
+    LOCK: "LOCK";
+    COMMIT: "COMMIT";
+    VERIFY: "VERIFY";
+    SETTLE: "SETTLE";
+}>;
+export type TransactionStage = z.infer<typeof TransactionStageSchema>;
+/** The one canonical stage order (§34). */
+export declare const CANONICAL_TRANSACTION_STAGES: readonly TransactionStage[];
+export declare const TransactionStateSchema: z.ZodEnum<{
+    AUTHORIZED: "AUTHORIZED";
+    PROPOSED: "PROPOSED";
+    PREPARED: "PREPARED";
+    LOCKED: "LOCKED";
+    COMMITTING: "COMMITTING";
+    COMMITTED: "COMMITTED";
+    VERIFIED: "VERIFIED";
+    SETTLED: "SETTLED";
+    DENIED: "DENIED";
+    EXPIRED: "EXPIRED";
+    REVOKED: "REVOKED";
+    UNKNOWN: "UNKNOWN";
+    MISMATCH: "MISMATCH";
+    FAILED: "FAILED";
+    CANCELLED: "CANCELLED";
+    COMPENSATING: "COMPENSATING";
+    COMPENSATED: "COMPENSATED";
+}>;
+export type TransactionState = z.infer<typeof TransactionStateSchema>;
+/** States from which the transaction can never move again. */
+export declare const TERMINAL_TRANSACTION_STATES: readonly TransactionState[];
+export declare function isTerminalTransactionState(state: TransactionState): boolean;
+/**
+ * The declared lifecycle of a transaction: a strictly-increasing
+ * subsequence of the canonical stage order that must contain PROPOSE.
+ * Declared on the action definition and/or the governing intent; the
+ * effective declaration is the union in canonical order — declaration
+ * only ever adds recorded obligations, it cannot remove a stage the
+ * other declaration required.
+ */
+export declare const TransactionDeclarationSchema: z.ZodObject<{
+    schema: z.ZodLiteral<"guardian.transaction.v1">;
+    stages: z.ZodArray<z.ZodEnum<{
+        PROPOSE: "PROPOSE";
+        PREPARE: "PREPARE";
+        AUTHORIZE: "AUTHORIZE";
+        LOCK: "LOCK";
+        COMMIT: "COMMIT";
+        VERIFY: "VERIFY";
+        SETTLE: "SETTLE";
+    }>>;
+    deadlineMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export type TransactionDeclaration = z.infer<typeof TransactionDeclarationSchema>;
+export declare function transactionDeclarationDigest(declaration: TransactionDeclaration): string;
+/**
+ * Union of two declared lifecycles in canonical order (declaration only
+ * ever enlarges the recorded obligation set, never shrinks it). The
+ * tighter deadline wins. Returns undefined when neither declares.
+ */
+export declare function effectiveTransactionDeclaration(declaredA: TransactionDeclaration | undefined, declaredB: TransactionDeclaration | undefined): TransactionDeclaration | undefined;
+/**
+ * Every consequential adapter declares its idempotency posture. The
+ * declaration is data on the adapter record — it is required, never
+ * inferred. A retry always binds to the recorded execution attempt's
+ * idempotency key (the effect key); a retry can never carry a fresh key
+ * that would silently produce a second effect.
+ */
+export declare const AdapterIdempotencyDeclarationSchema: z.ZodObject<{
+    support: z.ZodEnum<{
+        none: "none";
+        keyed: "keyed";
+        "provider-native": "provider-native";
+    }>;
+    duplicateEffect: z.ZodEnum<{
+        "return-existing": "return-existing";
+        reject: "reject";
+        unsafe: "unsafe";
+    }>;
+    retry: z.ZodEnum<{
+        "same-attempt-key": "same-attempt-key";
+        "fresh-authority": "fresh-authority";
+    }>;
+    reconciliation: z.ZodEnum<{
+        none: "none";
+        readback: "readback";
+        callback: "callback";
+        manual: "manual";
+    }>;
+}, z.core.$strict>;
+export type AdapterIdempotencyDeclaration = z.infer<typeof AdapterIdempotencyDeclarationSchema>;
+/**
+ * Bound into the canonical action of a compensating action: which
+ * recorded transaction this action compensates. The action still goes
+ * through the full authority path — this binding only declares the
+ * relationship.
+ */
+export declare const TransactionCompensationBindingSchema: z.ZodObject<{
+    transactionId: z.core.$ZodBranded<z.ZodString, "TransactionId", "out">;
+}, z.core.$strict>;
+export type TransactionCompensationBinding = z.infer<typeof TransactionCompensationBindingSchema>;
+export declare const TransactionStageRecordSchema: z.ZodObject<{
+    stage: z.ZodEnum<{
+        PROPOSE: "PROPOSE";
+        PREPARE: "PREPARE";
+        AUTHORIZE: "AUTHORIZE";
+        LOCK: "LOCK";
+        COMMIT: "COMMIT";
+        VERIFY: "VERIFY";
+        SETTLE: "SETTLE";
+    }>;
+    atEpochMs: z.ZodNumber;
+    binding: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type TransactionStageRecord = z.infer<typeof TransactionStageRecordSchema>;
+/** How a revocation mid-transaction resolves (§81). */
+export declare const TransactionResolutionSchema: z.ZodEnum<{
+    cancel: "cancel";
+    settle: "settle";
+    hold: "hold";
+}>;
+export type TransactionResolution = z.infer<typeof TransactionResolutionSchema>;
+export declare const TransactionRecordSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    schema: z.ZodLiteral<"guardian.transaction.v1">;
+    transactionId: z.core.$ZodBranded<z.ZodString, "TransactionId", "out">;
+    tenantId: z.core.$ZodBranded<z.ZodString, "TenantId", "out">;
+    principalId: z.core.$ZodBranded<z.ZodString, "PrincipalId", "out">;
+    agentId: z.core.$ZodBranded<z.ZodString, "AgentId", "out">;
+    requestId: z.core.$ZodBranded<z.ZodString, "RequestId", "out">;
+    correlationId: z.core.$ZodBranded<z.ZodString, "CorrelationId", "out">;
+    action: z.core.$ZodBranded<z.ZodString, "ActionType", "out">;
+    actionDigest: z.ZodString;
+    declaration: z.ZodObject<{
+        schema: z.ZodLiteral<"guardian.transaction.v1">;
+        stages: z.ZodArray<z.ZodEnum<{
+            PROPOSE: "PROPOSE";
+            PREPARE: "PREPARE";
+            AUTHORIZE: "AUTHORIZE";
+            LOCK: "LOCK";
+            COMMIT: "COMMIT";
+            VERIFY: "VERIFY";
+            SETTLE: "SETTLE";
+        }>>;
+        deadlineMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+    declarationDigest: z.ZodString;
+    recordedStages: z.ZodArray<z.ZodObject<{
+        stage: z.ZodEnum<{
+            PROPOSE: "PROPOSE";
+            PREPARE: "PREPARE";
+            AUTHORIZE: "AUTHORIZE";
+            LOCK: "LOCK";
+            COMMIT: "COMMIT";
+            VERIFY: "VERIFY";
+            SETTLE: "SETTLE";
+        }>;
+        atEpochMs: z.ZodNumber;
+        binding: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
+    state: z.ZodEnum<{
+        AUTHORIZED: "AUTHORIZED";
+        PROPOSED: "PROPOSED";
+        PREPARED: "PREPARED";
+        LOCKED: "LOCKED";
+        COMMITTING: "COMMITTING";
+        COMMITTED: "COMMITTED";
+        VERIFIED: "VERIFIED";
+        SETTLED: "SETTLED";
+        DENIED: "DENIED";
+        EXPIRED: "EXPIRED";
+        REVOKED: "REVOKED";
+        UNKNOWN: "UNKNOWN";
+        MISMATCH: "MISMATCH";
+        FAILED: "FAILED";
+        CANCELLED: "CANCELLED";
+        COMPENSATING: "COMPENSATING";
+        COMPENSATED: "COMPENSATED";
+    }>;
+    resolution: z.ZodNullable<z.ZodEnum<{
+        cancel: "cancel";
+        settle: "settle";
+        hold: "hold";
+    }>>;
+    attemptId: z.ZodNullable<z.core.$ZodBranded<z.ZodString, "AttemptId", "out">>;
+    capabilityId: z.ZodNullable<z.core.$ZodBranded<z.ZodString, "CapabilityId", "out">>;
+    idempotencyKey: z.ZodNullable<z.ZodString>;
+    compensationOf: z.ZodNullable<z.core.$ZodBranded<z.ZodString, "TransactionId", "out">>;
+    compensationBy: z.ZodNullable<z.core.$ZodBranded<z.ZodString, "TransactionId", "out">>;
+    terminalReason: z.ZodNullable<z.ZodString>;
+    expiresAtEpochMs: z.ZodNullable<z.ZodNumber>;
+    version: z.ZodNumber;
+    createdAtEpochMs: z.ZodNumber;
+    updatedAtEpochMs: z.ZodNumber;
+}, z.core.$strict>;
+export type TransactionRecord = z.infer<typeof TransactionRecordSchema>;
+/** Deterministic transaction id: one transaction per request. */
+export declare function transactionIdForRequest(requestId: string): string;
+/**
+ * §36 — whether a transaction's effect may be compensated: a landed (or
+ * possibly-landed) effect only; pre-commit states cancel instead.
+ */
+export declare function isCompensatableTransaction(record: TransactionRecord): boolean;
+export declare const TransactionCommandSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    expectedVersion: z.ZodNumber;
+    kind: z.ZodLiteral<"record-stage">;
+    stage: z.ZodEnum<{
+        PROPOSE: "PROPOSE";
+        PREPARE: "PREPARE";
+        AUTHORIZE: "AUTHORIZE";
+        LOCK: "LOCK";
+        COMMIT: "COMMIT";
+        VERIFY: "VERIFY";
+        SETTLE: "SETTLE";
+    }>;
+    binding: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    expectedVersion: z.ZodNumber;
+    kind: z.ZodLiteral<"deny">;
+    reason: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    expectedVersion: z.ZodNumber;
+    kind: z.ZodLiteral<"cancel">;
+    reason: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    expectedVersion: z.ZodNumber;
+    kind: z.ZodLiteral<"expire">;
+    reason: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    expectedVersion: z.ZodNumber;
+    kind: z.ZodLiteral<"revoke">;
+    reason: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    expectedVersion: z.ZodNumber;
+    kind: z.ZodLiteral<"fail">;
+    reason: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    expectedVersion: z.ZodNumber;
+    kind: z.ZodLiteral<"bind-attempt">;
+    attemptId: z.core.$ZodBranded<z.ZodString, "AttemptId", "out">;
+    capabilityId: z.core.$ZodBranded<z.ZodString, "CapabilityId", "out">;
+    idempotencyKey: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    expectedVersion: z.ZodNumber;
+    kind: z.ZodLiteral<"commit-confirmed">;
+    binding: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    expectedVersion: z.ZodNumber;
+    kind: z.ZodLiteral<"outcome">;
+    outcome: z.ZodEnum<{
+        unknown: "unknown";
+        verified: "verified";
+        mismatch: "mismatch";
+        "commit-rejected": "commit-rejected";
+        aborted: "aborted";
+    }>;
+    binding: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    expectedVersion: z.ZodNumber;
+    kind: z.ZodLiteral<"compensate">;
+    compensationTransactionId: z.core.$ZodBranded<z.ZodString, "TransactionId", "out">;
+}, z.core.$strict>, z.ZodObject<{
+    expectedVersion: z.ZodNumber;
+    kind: z.ZodLiteral<"compensated">;
+}, z.core.$strict>], "kind">;
+export type TransactionCommand = z.infer<typeof TransactionCommandSchema>;
+/** A transaction command without its optimistic-concurrency version. */
+export type TransactionCommandInput = {
+    [K in TransactionCommand["kind"]]: Omit<Extract<TransactionCommand, {
+        kind: K;
+    }>, "expectedVersion">;
+}[TransactionCommand["kind"]];
+export type TransactionTransitionResult = Readonly<{
+    ok: true;
+    record: TransactionRecord;
+}> | Readonly<{
+    ok: false;
+    reasonCode: "MALFORMED_RECORD" | "MALFORMED_COMMAND" | "STALE_VERSION" | "TRANSACTION_EXPIRED" | "SKIPPED_STAGE" | "INVALID_TRANSITION";
+}>;
+/** The next declared stage not yet recorded, or null. */
+export declare function nextDeclaredTransactionStage(record: TransactionRecord): TransactionStage | null;
+/** §81: how a revocation resolves from a given pre-revocation state. */
+export declare function revocationResolutionForState(state: TransactionState): TransactionResolution;
+export declare function transitionTransaction(recordInput: unknown, commandInput: unknown, nowEpochMs: number): TransactionTransitionResult;
+/**
+ * Create a transaction record in PROPOSED with PROPOSE already recorded
+ * and bound to the canonical action digest.
+ */
+export declare function proposeTransaction(input: {
+    tenantId: string;
+    principalId: string;
+    agentId: string;
+    requestId: string;
+    correlationId: string;
+    action: string;
+    actionDigest: string;
+    declaration: TransactionDeclaration;
+    compensationOf?: string;
+    atEpochMs: number;
+}): TransactionRecord;
+/**
+ * The injected port the gateway and execution paths record through.
+ * Implementations persist TransactionRecord rows plus a stage-transition
+ * audit; the pure evaluator above is the only writer of state. Every
+ * method returns null on failure — callers fail closed.
+ */
+export interface TransactionTracker {
+    /**
+     * Idempotent create keyed on the request-derived transaction id:
+     * returns the record (creating it PROPOSED when absent), the existing
+     * record when the same action digest is replayed, and null when a
+     * record for the id exists with a different digest or the store
+     * fails.
+     */
+    propose(input: {
+        tenantId: string;
+        principalId: string;
+        agentId: string;
+        requestId: string;
+        correlationId: string;
+        action: string;
+        actionDigest: string;
+        declaration: TransactionDeclaration;
+        compensationOf?: string;
+        atEpochMs: number;
+    }): Promise<TransactionRecord | null>;
+    /** Apply one command through the evaluator with CAS semantics. */
+    transition(input: {
+        tenantId: string;
+        transactionId: string;
+        command: TransactionCommand;
+        atEpochMs: number;
+    }): Promise<TransactionRecord | null>;
+    get(input: {
+        tenantId: string;
+        transactionId: string;
+    }): Promise<TransactionRecord | null>;
+}

package/dist-dts/contracts-entry.d.ts

@@ -0,0 +1 @@
+export * from "./contracts/index.js";