@odingard/guardian-sdk 0.0.0-stage → 0.2.0

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";

package/dist-dts/embedded.d.ts

@@ -0,0 +1,58 @@
+/**
+ * WO-019 — embedded approval primitives for partner apps (extends the WO-015
+ * SDK). A partner embeds Guardian authority by driving the human's approval
+ * surface through this client; the calls hit `/v1/embedded/approvals`, which
+ * runs the identical approval-service methods as the first-party route, so
+ * the decision semantics, receipts and evidence are identical.
+ *
+ * The partner supplies the human's own Guardian session token — the partner
+ * never handles agent credentials and cannot widen what the human may see or
+ * decide.
+ */
+export type EmbeddedApprovalConfig = Readonly<{
+    /** e.g. https://guardian-api-staging.odingard.com */
+    baseUrl: string;
+    /** The human's Guardian session token presented through the partner app. */
+    sessionToken: string;
+    fetch?: typeof fetch;
+}>;
+export type EmbeddedApprovalSummary = Readonly<{
+    approvalId: string;
+    state: string;
+    version: number;
+    headline: string;
+    expiresAtEpochMs: number;
+}>;
+export type EmbeddedApprovalView = Readonly<{
+    display: unknown;
+    challenge: unknown | null;
+}>;
+export type EmbeddedDecisionResult = Readonly<{
+    receipt: unknown;
+    changed: boolean;
+}>;
+export type EmbeddedResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    reasonCode: string;
+};
+export declare function isHumanSessionToken(token: unknown): token is string;
+export declare function createEmbeddedApprovalClient(config: EmbeddedApprovalConfig): {
+    listApprovals(): Promise<EmbeddedResult<{
+        approvals: readonly EmbeddedApprovalSummary[];
+    }>>;
+    viewApproval(approvalId: string): Promise<EmbeddedResult<EmbeddedApprovalView>>;
+    decideApproval(approvalId: string, input: {
+        expectedVersion: number;
+        decision: "approve" | "deny";
+        presentationDigest: string;
+        /** WO-019 step-up factor: tap (default), passkey, biometric, second-device. */
+        factor?: "tap" | "passkey" | "biometric" | "second-device";
+    }): Promise<EmbeddedResult<EmbeddedDecisionResult>>;
+    revokeApproval(approvalId: string, input: {
+        expectedVersion: number;
+    }): Promise<EmbeddedResult<EmbeddedDecisionResult>>;
+};
+export type EmbeddedApprovalClient = ReturnType<typeof createEmbeddedApprovalClient>;

package/dist-dts/evidence/evidence.d.ts

@@ -0,0 +1,25 @@
+import { type EvidenceEvent, type EvidenceChainContext, type EvidenceRecord, type EvidenceRecordCore } from "../contracts/index.js";
+export type AppendEvidenceFailure = "MALFORMED_CHAIN" | "MALFORMED_DRAFT" | "CHAIN_INVALID" | "DUPLICATE_EVIDENCE_ID" | "APPEND_CONTEXT_MISMATCH" | "NON_MONOTONIC_EVENT_TIME" | "CHAIN_LIMIT_EXCEEDED";
+export type AppendEvidenceResult = {
+    ok: true;
+    record: EvidenceRecord;
+    chain: EvidenceRecord[];
+} | {
+    ok: false;
+    reasonCode: AppendEvidenceFailure;
+};
+export type EvidenceVerificationFailure = "MALFORMED_CHAIN" | "INVALID_GENESIS" | "DUPLICATE_EVIDENCE_ID" | "DUPLICATE_SEQUENCE" | "SEQUENCE_GAP" | "RECORD_REORDERED" | "CONTEXT_MISMATCH" | "ACTION_DIGEST_MISMATCH" | "INVALID_EVENT_ORDER" | "PAYLOAD_DIGEST_MISMATCH" | "BROKEN_LINK" | "NON_MONOTONIC_EVENT_TIME" | "RECORD_HASH_MISMATCH";
+export type EvidenceVerificationResult = {
+    valid: true;
+    count: number;
+    lastRecordHash: string | null;
+    context: EvidenceChainContext | null;
+} | {
+    valid: false;
+    reasonCode: EvidenceVerificationFailure;
+    recordIndex: number | null;
+};
+export declare function hashEvidencePayload(event: EvidenceEvent): string;
+export declare function hashEvidenceRecordCore(core: EvidenceRecordCore): string;
+export declare function verifyEvidenceChain(chainInput: unknown, expectedContextInput?: unknown): EvidenceVerificationResult;
+export declare function appendEvidenceRecord(chainInput: unknown, draftInput: unknown): AppendEvidenceResult;

package/dist-dts/evidence/receipt.d.ts

@@ -0,0 +1,61 @@
+import { type ApprovalRecord, type CanonicalAction, type CapabilityClaims, type EvidenceRecord, type ExecutionRecord, type PortableAuthorityReceipt, type PortableReceiptBody, type ReceiptVerificationJwk } from "../contracts/index.js";
+export type ReceiptSigner = Readonly<{
+    keyId: string;
+    verificationJwk: ReceiptVerificationJwk;
+    sign(body: PortableReceiptBody): PortableAuthorityReceipt;
+}>;
+/** Deterministic receipt key id: rkey_<first-16-hex of sha256(x)>. */
+export declare function receiptKeyIdFromX(x: string): string;
+/**
+ * Builds a receipt signer from an Ed25519 signing JWK (`{x, d}` as stored in
+ * the `receipt-signing-jwk` secret). Throws on malformed key material.
+ */
+export declare function createReceiptSignerFromJwk(input: unknown): ReceiptSigner;
+/** Generates an ephemeral signer — development and tests only. */
+export declare function createEphemeralReceiptSigner(): ReceiptSigner;
+export type BuildPortableReceiptInput = Readonly<{
+    receiptId: string;
+    issuedAtEpochMs: number;
+    /** The complete evidence chain for the request, in sequence order. */
+    chain: readonly EvidenceRecord[];
+    /**
+     * The canonical action the kernel evaluated (from the private
+     * materialized-action store). The chain binds it via its material digest.
+     */
+    action?: CanonicalAction | null;
+    /** Latest stored approval record, when the request required one. */
+    approval?: ApprovalRecord | null;
+    /** The issued capability's claims (never the token). */
+    capabilityClaims?: CapabilityClaims | null;
+    capabilityState?: "issued" | "used" | "expired" | "revoked" | null;
+    /** Latest execution ledger record, when execution was attempted. */
+    execution?: ExecutionRecord | null;
+}>;
+export type BuildPortableReceiptResult = {
+    ok: true;
+    body: PortableReceiptBody;
+} | {
+    ok: false;
+    reasonCode: "CHAIN_INVALID" | "ACTION_UNAVAILABLE" | "DECISION_MISSING" | "APPROVAL_INCONSISTENT" | "CAPABILITY_INCONSISTENT" | "EXECUTION_INCONSISTENT";
+};
+export declare function buildPortableReceipt(input: BuildPortableReceiptInput): BuildPortableReceiptResult;
+/** Recomputes the capability claims digest (same domain as the broker). */
+export declare function capabilityClaimsDigest(claims: CapabilityClaims): string;
+export type PortableReceiptVerificationFailure = "MALFORMED_RECEIPT" | "UNKNOWN_KEY" | "SIGNATURE_INVALID" | "EVIDENCE_CHAIN_INVALID" | "SUBJECT_MISMATCH" | "ACTION_MISMATCH" | "DECISION_MISMATCH" | "APPROVAL_MISMATCH" | "CAPABILITY_MISMATCH" | "EXECUTION_MISMATCH" | "EFFECT_MISMATCH" | "EVIDENCE_HEAD_MISMATCH";
+export type PortableReceiptVerificationResult = {
+    valid: true;
+    subject: PortableReceiptBody["subject"];
+    decision: PortableReceiptBody["decision"]["decision"];
+    effect: PortableReceiptBody["effect"]["kind"];
+} | {
+    valid: false;
+    reasonCode: PortableReceiptVerificationFailure;
+};
+/**
+ * Self-contained portable receipt verification. The caller supplies only the
+ * receipt and the published verification key set — no Guardian credential,
+ * database, or service is required. Every embedded object is re-digested and
+ * cross-checked against the embedded evidence chain, and the Ed25519 proof is
+ * verified over the canonical receipt body.
+ */
+export declare function verifyPortableAuthorityReceipt(receiptInput: unknown, keysInput: unknown): PortableReceiptVerificationResult;

package/dist-dts/index.d.ts

@@ -0,0 +1,5 @@
+export { createGuardianClient, type GuardianClient, type GuardianClientConfig, type GuardianGovernedInvocation, type GuardianInvocation, type GuardianRequestResult, type GuardianToolInvocation, type GuardianMcpInvocation, } from "./client.js";
+export { createEmbeddedApprovalClient, isHumanSessionToken, type EmbeddedApprovalClient, type EmbeddedApprovalConfig, type EmbeddedApprovalSummary, type EmbeddedApprovalView, type EmbeddedDecisionResult, type EmbeddedResult, } from "./embedded.js";
+export { classifyRequestResult, type GuardianDecision } from "./lifecycle.js";
+export { fetchReceiptVerificationKeys, verifyReceiptOffline, verifyReceiptOnline, type ReceiptKeySetResult, type ReceiptVerification, } from "./receipts.js";
+export { findAgentSystem, guardianCatalog, verticalsForAction, type GuardianCatalogAgentSystem, type GuardianCatalogVertical, type GuardianPublicCatalog, } from "./catalog.js";

package/dist-dts/lifecycle.d.ts

@@ -0,0 +1,25 @@
+import type { GuardianRequestResult } from "./client.js";
+/**
+ * WO-042 — the single, fail-closed reading of a Guardian request result.
+ *
+ *   ALLOW — a capability token was issued; `execute` redeems it.
+ *   ASK   — held for a human; keep `requestId`, then `claim(requestId)`
+ *           after the human decides. The gateway reports a held ASK as
+ *           `{ ok: false, reasonCode: "APPROVAL_REQUIRED", requestId }`.
+ *   DENY  — everything else, including ambiguity (ALLOW without a token),
+ *           an unknown shape, or Guardian being unreachable.
+ */
+export type GuardianDecision = {
+    decision: "ALLOW";
+    requestId: string;
+    capabilityToken: string;
+} | {
+    decision: "ASK";
+    requestId: string;
+    reasonCode: string;
+} | {
+    decision: "DENY";
+    reasonCode: string;
+    requestId?: string;
+};
+export declare function classifyRequestResult(result: GuardianRequestResult): GuardianDecision;

package/dist-dts/proposal.d.ts

@@ -0,0 +1,41 @@
+import { z } from "zod";
+export declare const AgentActionProposalSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    requestId: z.core.$ZodBranded<z.ZodString, "RequestId", "out">;
+    correlationId: z.core.$ZodBranded<z.ZodString, "CorrelationId", "out">;
+    action: z.core.$ZodBranded<z.ZodString, "ActionType", "out">;
+    resource: z.core.$ZodBranded<z.ZodString, "ResourceRef", "out">;
+    valueCents: z.ZodOptional<z.ZodNumber>;
+    merchantId: z.ZodOptional<z.ZodString>;
+    merchantCategory: z.ZodOptional<z.ZodString>;
+    recurring: z.ZodOptional<z.ZodBoolean>;
+    taskId: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "TaskId", "out">>;
+    intentId: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "IntentId", "out">>;
+    planId: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "PlanId", "out">>;
+    parentActionId: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "RequestId", "out">>;
+    sourceEffectId: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "AttemptId", "out">>;
+    compensatesTransactionId: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "TransactionId", "out">>;
+    physicalFacts: z.ZodOptional<z.ZodObject<{
+        zone: z.ZodOptional<z.ZodString>;
+        speed: z.ZodOptional<z.ZodNumber>;
+        force: z.ZodOptional<z.ZodNumber>;
+        payload: z.ZodOptional<z.ZodNumber>;
+        atEpochMs: z.ZodOptional<z.ZodNumber>;
+        humanDistance: z.ZodOptional<z.ZodNumber>;
+        environment: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        supervised: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    uses: z.ZodLiteral<1>;
+    materialParameters: z.ZodPipe<z.ZodUnknown, z.ZodTransform<Readonly<Record<string, import("./contracts/canonical-json.js").CanonicalJsonValue>>, unknown>>;
+    purpose: z.ZodString;
+    initiatingContext: z.ZodEnum<{
+        agent: "agent";
+        user: "user";
+        scheduled: "scheduled";
+        "external-event": "external-event";
+    }>;
+    requestedAdapterId: z.core.$ZodBranded<z.ZodString, "AdapterId", "out">;
+    requestedTtlMs: z.ZodNumber;
+    runtime: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type AgentActionProposal = z.infer<typeof AgentActionProposalSchema>;

package/dist-dts/receipts.d.ts

@@ -0,0 +1,37 @@
+import { verifyPortableAuthorityReceipt } from "./evidence/receipt.js";
+/**
+ * WO-042 — portable receipt verification for developers and auditors.
+ *
+ * Offline verification needs only the receipt and Guardian's published
+ * Ed25519 verification keys: no agent credential, account, plan or Guardian
+ * service is involved once the keys are in hand. It checks the
+ * `guardian-canonical-json.v1` signature over the receipt body and
+ * re-derives every embedded record against the receipt's evidence chain.
+ * Verification is never billable (GUA-REVENUE-001).
+ */
+export type ReceiptVerification = ReturnType<typeof verifyPortableAuthorityReceipt>;
+export type ReceiptKeySetResult = {
+    ok: true;
+    keys: unknown;
+} | {
+    ok: false;
+    reasonCode: string;
+};
+type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+/** Fetch the published verification key set (public; no credential). */
+export declare function fetchReceiptVerificationKeys(baseUrl: string, options?: {
+    fetch?: FetchLike;
+}): Promise<ReceiptKeySetResult>;
+/** Verify a receipt locally against a key set. Pure; no network. */
+export declare function verifyReceiptOffline(receipt: unknown, keys: unknown): ReceiptVerification;
+/** Ask a Guardian deployment to verify a receipt (public endpoint). */
+export declare function verifyReceiptOnline(baseUrl: string, receipt: unknown, options?: {
+    fetch?: FetchLike;
+}): Promise<{
+    ok: true;
+    result: Record<string, unknown>;
+} | {
+    ok: false;
+    reasonCode: string;
+}>;
+export {};