@hasna/infinity 0.1.0

package/dist/types/brokers/git/promotion.d.ts

@@ -0,0 +1,418 @@
+import { type Int64 } from "../../core/int64";
+import { type AuthenticatedFenceContext, type BrokerFence, type BrokerFenceInput } from "../../contracts/fence";
+import type { IdempotentExecutor } from "../checkpoint/idempotency";
+import { type ProviderStepExecutor } from "../persistence/contracts";
+import { type CheckpointSealReceipt, type FenceAuthorityPort } from "../checkpoint/service";
+import { type PassingVerificationReceipt, type VerificationReceiptCryptographyPort, type VerificationReceiptFinalTrustAuthorityPort } from "../checkpoint/verifier";
+import type { VersionedReadbackReceipt } from "../checkpoint/store";
+export interface DecisionIdempotencyTuple {
+    authenticatedPrincipal: string;
+    delegationChainSha256: string;
+    sourceNamespace: string;
+    projectId: string;
+    repositoryId: string;
+    resourceId: string;
+    routeAuthorityReferenceSha256: string;
+    command: "approval_decide";
+    key: string;
+    requestSha256: string;
+}
+export interface PromotionApprovalReceipt {
+    schemaVersion: "infinity.promotion-approval-consumption/v1";
+    grantType: "human_webauthn_promotion";
+    issuer: string;
+    audience: "git-promotion-broker";
+    jti: string;
+    issuedAt: string;
+    notBefore: string;
+    approvalId: string;
+    approvalRevision: number;
+    decisionVerb: "approve" | "deny";
+    decisionOperationId: string;
+    decisionIdempotency: DecisionIdempotencyTuple;
+    approvedProposalSha256: string;
+    decisionReceiptSha256: string;
+    consumptionTransactionId: string;
+    consumedAt: string;
+    approverPrincipal: string;
+    expiresAt: string;
+    webauthnChallengeSha256: string;
+    webauthnRpId: string;
+    webauthnOrigin: string;
+    signingKeyId: string;
+    signatureAlgorithm: "ecdsa-p256-sha256";
+    signedEnvelopeSha256: string;
+    signatureBase64: string;
+    signatureSha256: string;
+}
+export interface GitPromotionIntentInput {
+    fence: BrokerFenceInput;
+    checkpoint: CheckpointSealReceipt;
+    verification: PassingVerificationReceipt;
+    approval: PromotionApprovalReceipt;
+    installationId: string;
+    appPrincipal: string;
+    repositoryId: string;
+    targetRef: string;
+    branchRef: string;
+    prTitleDigest: string;
+    prBodyDigest: string;
+    automationPolicySha256: string;
+    scannerPolicySha256: string;
+}
+export type GitPromotionProposalInput = Omit<GitPromotionIntentInput, "approval">;
+export interface GitPromotionIntent extends Omit<Readonly<GitPromotionIntentInput>, "fence" | "approval"> {
+    readonly fence: BrokerFence;
+    readonly approval: Readonly<PromotionApprovalReceipt & {
+        decisionIdempotency: Readonly<DecisionIdempotencyTuple>;
+    }>;
+}
+export interface GitRefReadReceipt {
+    readonly repositoryId: string;
+    readonly ref: string;
+    readonly oid: string | null;
+    readonly providerRequestId: string;
+}
+export interface GitCandidateObjectSource {
+    readonly checkpointId: string;
+    readonly checkpointSealSha256: string;
+    readonly verificationReceiptSha256: string;
+    readonly objectFormat: "sha1" | "sha256";
+    readonly expectedBaseOid: string;
+    readonly candidateOid: string;
+    readonly bundleSha256: string;
+    readonly bundleObject: VersionedReadbackReceipt;
+}
+export type PromotionStepAction = "read_target_precondition" | "anchor_branch" | "cas_candidate" | "read_ref_postconditions" | "create_draft_pr" | "read_draft_pr_postcondition";
+export interface PromotionFenceAuthorityPort extends FenceAuthorityPort {
+    authorizePromotionStep(input: {
+        action: PromotionStepAction;
+        fence: BrokerFence;
+        nextResourceLifecycleGeneration: Int64;
+        proposalSha256: string;
+        approvalConsumptionReceiptSha256: string;
+    }): Promise<{
+        fence: BrokerFence;
+        databaseTime: Date;
+    }>;
+}
+export interface PromotionApprovalAuthorityPort {
+    verifyConsumed(input: {
+        approval: PromotionApprovalReceipt;
+        proposalSha256: string;
+        fence: BrokerFence;
+    }): Promise<PromotionApprovalConsumptionVerification>;
+}
+export interface PromotionApprovalConsumptionVerification {
+    fence: BrokerFence;
+    proposalSha256: string;
+    consumptionReceiptSha256: string;
+    approvalId: string;
+    approvalRevision: number;
+    decisionReceiptSha256: string;
+    consumptionTransactionId: string;
+    consumedAt: string;
+}
+export interface FreshPromotionSecretScanReceipt {
+    readonly schemaVersion: "infinity.promotion-secret-scan/v1";
+    readonly verdict: "pass";
+    readonly fence: BrokerFence;
+    readonly checkpointSealSha256: string;
+    readonly verificationReceiptSha256: string;
+    readonly candidateOid: string;
+    readonly scannerPolicySha256: string;
+    readonly proposalSha256: string;
+    readonly approvalConsumptionReceiptSha256: string;
+    readonly stagedDiffScanned: true;
+    readonly allIntroducedBlobsScanned: true;
+    readonly findingCount: 0;
+    readonly completedAt: string;
+    readonly receiptSha256: string;
+}
+export interface PromotionSecretScannerPort {
+    scan(input: {
+        fence: BrokerFence;
+        checkpoint: CheckpointSealReceipt;
+        verification: PassingVerificationReceipt;
+        proposalSha256: string;
+        approvalConsumptionReceiptSha256: string;
+    }): Promise<FreshPromotionSecretScanReceipt>;
+}
+export type GitBranchCreateReceipt = Readonly<{
+    status: "created";
+    oid: string;
+    providerRequestId: string;
+    reconciliationProviderRequestId: string | null;
+    resourceGenerationBefore: Int64;
+    resourceGenerationAfter: Int64;
+}> | Readonly<{
+    status: "conflict";
+    existingOid: string;
+    providerRequestId: string;
+    reconciliationProviderRequestId: string | null;
+    resourceGenerationBefore: Int64;
+    resourceGenerationAfter: Int64;
+}> | Readonly<{
+    status: "ambiguous";
+    providerRequestId: string;
+    reconciliationProviderRequestId: string;
+    resourceGenerationBefore: Int64;
+    possibleResourceGenerationAfter: Int64;
+}>;
+export type GitBranchCasReceipt = Readonly<{
+    status: "updated";
+    previousOid: string;
+    oid: string;
+    providerRequestId: string;
+    reconciliationProviderRequestId: string | null;
+    resourceGenerationBefore: Int64;
+    resourceGenerationAfter: Int64;
+}> | Readonly<{
+    status: "conflict";
+    existingOid: string | null;
+    providerRequestId: string;
+    reconciliationProviderRequestId: string | null;
+    resourceGenerationBefore: Int64;
+    resourceGenerationAfter: Int64;
+}> | Readonly<{
+    status: "ambiguous";
+    providerRequestId: string;
+    reconciliationProviderRequestId: string;
+    resourceGenerationBefore: Int64;
+    possibleResourceGenerationAfter: Int64;
+}>;
+export interface GitPullRequestRecord {
+    readonly providerPullRequestId: string;
+    readonly number: number;
+    readonly repositoryId: string;
+    readonly installationId: string;
+    readonly baseRef: string;
+    readonly baseOid: string;
+    readonly headRef: string;
+    readonly headOid: string;
+    readonly marker: string;
+    readonly titleDigest: string;
+    readonly bodyDigest: string;
+    readonly state: "open";
+    readonly draft: true;
+    readonly authorPrincipal: string;
+    readonly providerRequestId: string;
+}
+export type GitPullRequestCreateReceipt = Readonly<{
+    status: "created";
+    pullRequest: GitPullRequestRecord;
+    reconciliationProviderRequestId: string | null;
+    resourceGenerationBefore: Int64;
+    resourceGenerationAfter: Int64;
+}> | Readonly<{
+    status: "ambiguous";
+    providerRequestId: string;
+    reconciliationProviderRequestId: string;
+    resourceGenerationBefore: Int64;
+    possibleResourceGenerationAfter: Int64;
+}>;
+export interface GitPullRequestReadReceipt {
+    readonly pullRequest: GitPullRequestRecord | null;
+    readonly providerRequestId: string;
+}
+export interface ExpectedBaseGitPort {
+    /**
+     * Implementations must revalidate the full fence and authorization deadline
+     * at the last asynchronous boundary before every external provider request,
+     * including ambiguity reconciliation requests.
+     */
+    withOperation<T>(input: {
+        fence: BrokerFence;
+        authorizationExpiresAt: string;
+    }, effect: () => Promise<T>): Promise<T>;
+    readRef(input: {
+        repositoryId: string;
+        ref: string;
+        fence: BrokerFence;
+    }): Promise<GitRefReadReceipt>;
+    compareAndCreateBranch(input: {
+        repositoryId: string;
+        ref: string;
+        oid: string;
+        operationId: string;
+        operationDigest: string;
+        resourceGenerationBefore: Int64;
+        resourceGenerationAfter: Int64;
+        fence: BrokerFence;
+    }): Promise<GitBranchCreateReceipt>;
+    compareAndSwapBranch(input: {
+        repositoryId: string;
+        ref: string;
+        expectedOid: string;
+        candidateOid: string;
+        candidateSource: GitCandidateObjectSource;
+        operationId: string;
+        operationDigest: string;
+        resourceGenerationBefore: Int64;
+        resourceGenerationAfter: Int64;
+        fence: BrokerFence;
+    }): Promise<GitBranchCasReceipt>;
+    createDraftPullRequest(input: {
+        repositoryId: string;
+        installationId: string;
+        appPrincipal: string;
+        baseRef: string;
+        baseOid: string;
+        headRef: string;
+        headOid: string;
+        marker: string;
+        titleDigest: string;
+        bodyDigest: string;
+        operationId: string;
+        operationDigest: string;
+        resourceGenerationBefore: Int64;
+        resourceGenerationAfter: Int64;
+        fence: BrokerFence;
+    }): Promise<GitPullRequestCreateReceipt>;
+    readPullRequest(input: {
+        repositoryId: string;
+        providerPullRequestId: string;
+        fence: BrokerFence;
+    }): Promise<GitPullRequestReadReceipt>;
+}
+export type GitPromotionStatus = "complete" | "base_drifted" | "branch_conflict" | "unknown_requires_review";
+export interface GitPromotionReceiptCore {
+    readonly schemaVersion: "infinity.git-promotion-receipt/v1";
+    readonly status: GitPromotionStatus;
+    readonly fence: BrokerFence;
+    readonly operationDigest: string;
+    readonly proposalSha256: string;
+    readonly approvalConsumptionReceiptSha256: string;
+    readonly checkpointSealSha256: string;
+    readonly verificationReceiptSha256: string;
+    readonly approvalDecisionReceiptSha256: string;
+    readonly freshSecretScanReceiptSha256: string;
+    readonly installationId: string;
+    readonly appPrincipal: string;
+    readonly repositoryId: string;
+    readonly targetRef: string;
+    readonly branchRef: string;
+    readonly expectedBaseOid: string;
+    readonly candidateOid: string;
+    readonly candidateTreeOid: string;
+    readonly resourceGenerationBefore: Int64;
+    readonly resourceGenerationAfter: Int64 | null;
+    readonly possibleResourceGenerationAfter: Int64;
+    readonly targetOidBefore: string | null;
+    readonly targetOidAfter: string | null;
+    readonly branchOid: string | null;
+    readonly pullRequest: GitPullRequestRecord | null;
+    readonly providerRequestIds: readonly string[];
+    readonly recordedAt: string;
+}
+export interface GitPromotionResultAuthorityCommit {
+    readonly schemaVersion: "infinity.git-promotion-authority-commit/v1";
+    readonly operationId: string;
+    readonly operationDigest: string;
+    readonly resultCoreSha256: string;
+    readonly proposalSha256: string;
+    readonly approvalConsumptionReceiptSha256: string;
+    readonly effectJournalFrontierSha256: string;
+    readonly authorityWitnessReceiptSha256: string;
+    readonly cancellationWitnessReceiptSha256: string;
+    readonly authorityTransactionId: string;
+    readonly authorityEventId: string;
+    readonly committedAt: string;
+    readonly signingKeyId: string;
+    readonly signatureSha256: string;
+    readonly receiptSha256: string;
+}
+export interface GitPromotionReceipt extends GitPromotionReceiptCore {
+    readonly authorityCommit: GitPromotionResultAuthorityCommit;
+}
+export interface PromotionResultAuthorityPort {
+    /**
+     * Rechecks independent authority/cancellation witnesses, then durably commits
+     * and verifies the signed external effect-journal frontier for this result.
+     */
+    commitAndVerifyPromotionResult(input: {
+        core: GitPromotionReceiptCore;
+        coreDigest: string;
+        proposalSha256: string;
+        approvalConsumptionReceiptSha256: string;
+    }): Promise<GitPromotionResultAuthorityCommit>;
+    verifyPromotionResult(input: {
+        core: GitPromotionReceiptCore;
+        coreDigest: string;
+        authorityCommit: GitPromotionResultAuthorityCommit;
+    }): Promise<GitPromotionResultAuthorityCommit>;
+}
+export declare function promotionProposalDigest(input: GitPromotionProposalInput): string;
+export type PromotionApprovalChallengeInput = Pick<PromotionApprovalReceipt, "schemaVersion" | "grantType" | "issuer" | "audience" | "jti" | "issuedAt" | "notBefore" | "approvalId" | "approvalRevision" | "decisionVerb" | "decisionOperationId" | "decisionIdempotency" | "approvedProposalSha256" | "approverPrincipal" | "expiresAt" | "webauthnRpId" | "webauthnOrigin">;
+export declare function promotionApprovalWebauthnChallengeDigest(input: PromotionApprovalChallengeInput): string;
+export type PromotionApprovalSignedEnvelope = Omit<PromotionApprovalReceipt, "signedEnvelopeSha256" | "signatureBase64" | "signatureSha256">;
+export declare function promotionApprovalSignedEnvelopeDigest(input: PromotionApprovalSignedEnvelope): string;
+export declare function promotionApprovalConsumptionReceiptDigest(input: PromotionApprovalReceipt): string;
+export declare function promotionOperationDigest(input: GitPromotionIntentInput): string;
+export declare function createGitPromotionIntent(input: GitPromotionIntentInput, currentFence: BrokerFence, authenticated: AuthenticatedFenceContext): GitPromotionIntent;
+export declare class GitPromotionBroker {
+    private readonly dependencies;
+    constructor(dependencies: {
+        authority: PromotionFenceAuthorityPort;
+        git: ExpectedBaseGitPort;
+        secretScanner: PromotionSecretScannerPort;
+        approvalAuthority: PromotionApprovalAuthorityPort;
+        resultAuthority: PromotionResultAuthorityPort;
+        verificationReceiptCryptography: VerificationReceiptCryptographyPort;
+        verificationReceiptFinalTrustAuthority: VerificationReceiptFinalTrustAuthorityPort;
+        ledger: IdempotentExecutor<GitPromotionReceipt>;
+        providerSteps: ProviderStepExecutor;
+    });
+    promote(intentInput: GitPromotionIntentInput, authenticated: AuthenticatedFenceContext): Promise<GitPromotionReceipt>;
+    private executePromotion;
+    private providerStep;
+    private authorizeStep;
+}
+export declare function parseGitPromotionReceipt(value: unknown): GitPromotionReceipt;
+export declare function derivePromotionBranchRef(fence: BrokerFenceInput | BrokerFence): string;
+export interface InMemoryExpectedBaseGitPortOptions {
+    repositoryId?: string;
+    targetRef?: string;
+    targetOid?: string;
+    driftTargetAfterCasTo?: string;
+    ambiguousPullRequest?: boolean;
+    preexistingBranchOid?: string;
+}
+export declare class InMemoryExpectedBaseGitPort implements ExpectedBaseGitPort {
+    private readonly options;
+    readRefCalls: number;
+    createBranchCalls: number;
+    casBranchCalls: number;
+    createPullRequestCalls: number;
+    readPullRequestCalls: number;
+    readonly observedFenceGenerations: Int64[];
+    readonly observedAuthorizationExpiries: string[];
+    private requestSequence;
+    private pullRequestSequence;
+    private readonly refs;
+    private readonly pullRequests;
+    private resourceGeneration;
+    private readonly repositoryId;
+    private readonly targetRef;
+    constructor(options?: InMemoryExpectedBaseGitPortOptions);
+    withOperation<T>(input: Parameters<ExpectedBaseGitPort["withOperation"]>[0], effect: () => Promise<T>): Promise<T>;
+    readRef(input: {
+        repositoryId: string;
+        ref: string;
+        fence: BrokerFence;
+    }): Promise<GitRefReadReceipt>;
+    compareAndCreateBranch(input: Parameters<ExpectedBaseGitPort["compareAndCreateBranch"]>[0]): Promise<GitBranchCreateReceipt>;
+    compareAndSwapBranch(input: Parameters<ExpectedBaseGitPort["compareAndSwapBranch"]>[0]): Promise<GitBranchCasReceipt>;
+    createDraftPullRequest(input: Parameters<ExpectedBaseGitPort["createDraftPullRequest"]>[0]): Promise<GitPullRequestCreateReceipt>;
+    readPullRequest(input: {
+        repositoryId: string;
+        providerPullRequestId: string;
+        fence: BrokerFence;
+    }): Promise<GitPullRequestReadReceipt>;
+    private initializeGeneration;
+    private advanceGeneration;
+    private assertRepository;
+    private assertOperation;
+    private observeFence;
+    private nextRequestId;
+}

package/dist/types/brokers/persistence/contracts.d.ts

@@ -0,0 +1,77 @@
+import type { BrokerFence } from "../../contracts/fence";
+import type { Int64 } from "../../core/int64";
+export declare class ProviderNoEffectError extends Error {
+    constructor(message?: string, options?: {
+        cause?: unknown;
+    });
+}
+export interface CanonicalCodec<T> {
+    encode(value: T): string;
+    decode(canonical: string): T;
+}
+export declare function canonicalCodec<T>(validate: (value: unknown) => T): CanonicalCodec<T>;
+export interface ProviderStepExecutionInput {
+    operationId: string;
+    operationDigest: string;
+    stepKey: string;
+    action: string;
+    fence: BrokerFence;
+    request: unknown;
+    resourceGenerationBefore: Int64;
+    resourceGenerationAfter: Int64;
+    providerClientTokenFingerprint?: string;
+    /**
+     * Optional independent authorization deadline. Implementations must treat it
+     * as an upper bound on provider dispatch, never as an extension of the fence.
+     */
+    dispatchExpiresAt?: string;
+    executionLeaseMs?: number;
+}
+export interface ProviderEffectJournalAnchorInput {
+    operationId: string;
+    operationDigest: string;
+    stepKey: string;
+    stepDigest: string;
+    action: string;
+    fence: BrokerFence;
+    requestSha256: string;
+    resourceGenerationBefore: Int64;
+    resourceGenerationAfter: Int64;
+    providerClientTokenFingerprint: string | null;
+    dispatchExpiresAt: string;
+}
+export interface VerifiedProviderEffectJournalAnchor {
+    schemaVersion: "infinity.provider-effect-journal-anchor/v1";
+    anchorId: string;
+    authorityEventId: string;
+    operationId: string;
+    operationDigest: string;
+    stepKey: string;
+    stepDigest: string;
+    action: string;
+    fenceSha256: string;
+    requestSha256: string;
+    resourceGenerationBefore: Int64;
+    resourceGenerationAfter: Int64;
+    providerClientTokenFingerprint: string | null;
+    dispatchExpiresAt: string;
+    anchorCoreSha256: string;
+    authorityWitnessReceiptSha256: string;
+    cancellationWitnessReceiptSha256: string;
+    committedAt: string;
+    signingKeyId: string;
+    signatureSha256: string;
+    receiptSha256: string;
+}
+/**
+ * Authority boundary for the external inbox/outbox journal. Implementations must
+ * re-read the independent current authority-epoch and cancellation witnesses,
+ * then durably commit and cryptographically verify the exact anchor before
+ * returning. Witness unavailability or cancellation must fail closed.
+ */
+export interface ProviderEffectJournalAuthorityPort {
+    commitAndVerifyDispatchAnchor(input: ProviderEffectJournalAnchorInput): Promise<VerifiedProviderEffectJournalAnchor>;
+}
+export interface ProviderStepExecutor {
+    execute<T>(input: ProviderStepExecutionInput, effect: () => Promise<T>, codec: CanonicalCodec<T>, providerRequestId: (result: T) => string | null, classifyResult?: (result: T) => "succeeded" | "unknown_requires_review"): Promise<T>;
+}

package/dist/types/brokers/persistence/memory.d.ts

@@ -0,0 +1,5 @@
+import type { CanonicalCodec, ProviderStepExecutionInput, ProviderStepExecutor } from "./contracts";
+export declare class InMemoryProviderStepLedger implements ProviderStepExecutor {
+    private readonly steps;
+    execute<T>(input: ProviderStepExecutionInput, effect: () => Promise<T>, codec: CanonicalCodec<T>, providerRequestId: (result: T) => string | null, classifyResult?: (result: T) => "succeeded" | "unknown_requires_review"): Promise<T>;
+}

package/dist/types/brokers/persistence/migration.d.ts

@@ -0,0 +1,6 @@
+export declare const CHECKPOINT_BROKER_MIGRATION_ID = "20260710_checkpoint_broker_v1";
+export declare const CHECKPOINT_BROKER_MIGRATION_V1: string;
+export declare const CHECKPOINT_TRUST_MIGRATION_ID = "20260711_checkpoint_trust_v2";
+export declare const CHECKPOINT_TRUST_MIGRATION_V2: string;
+export declare const CHECKPOINT_BROKER_MIGRATION_V2_ID = "20260711_verifier_cleanup_v2";
+export declare const CHECKPOINT_BROKER_MIGRATION_V2: string;

package/dist/types/brokers/persistence/postgres.d.ts

@@ -0,0 +1,74 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { SQL, type TransactionSQL } from "bun";
+import { type BrokerFence } from "../../contracts/fence";
+import type { IdempotentExecutionContext, IdempotentExecutor } from "../checkpoint/idempotency";
+import type { CanonicalCodec, ProviderEffectJournalAnchorInput, ProviderEffectJournalAuthorityPort, ProviderStepExecutionInput, ProviderStepExecutor } from "./contracts";
+export type SqlParameter = string | number | bigint | boolean | Date | null;
+export interface SqlExecutor {
+    query<Row extends Record<string, unknown>>(statement: string, parameters?: readonly SqlParameter[]): Promise<readonly Row[]>;
+    transaction<T>(effect: (transaction: SqlExecutor) => Promise<T>): Promise<T>;
+}
+interface SqlSerializationState {
+    tail: Promise<void>;
+    readonly transactionOwner: AsyncLocalStorage<{
+        active: boolean;
+    }>;
+    readonly reentrantScope: AsyncLocalStorage<{
+        active: boolean;
+    }>;
+}
+export declare class BunPostgresExecutor implements SqlExecutor {
+    private readonly sql;
+    private readonly inTransaction;
+    private readonly serialization;
+    constructor(sql: SQL | TransactionSQL, inTransaction?: boolean, serialization?: SqlSerializationState);
+    query<Row extends Record<string, unknown>>(statement: string, parameters?: readonly SqlParameter[]): Promise<readonly Row[]>;
+    transaction<T>(effect: (transaction: SqlExecutor) => Promise<T>): Promise<T>;
+    runConcurrentWithinSerializedTransaction<T>(effect: () => Promise<T>): Promise<T>;
+    private serialize;
+}
+export declare function runConcurrentWithinSerializedSqlTransaction<T>(executor: SqlExecutor, effect: () => Promise<T>): Promise<T>;
+export declare function applyCheckpointBrokerMigration(executor: SqlExecutor): Promise<"applied" | "already_applied">;
+export { canonicalCodec } from "./contracts";
+export type { CanonicalCodec, ProviderEffectJournalAnchorInput, ProviderEffectJournalAuthorityPort, ProviderStepExecutionInput, ProviderStepExecutor, VerifiedProviderEffectJournalAnchor, } from "./contracts";
+export { ProviderNoEffectError } from "./contracts";
+export interface PostgresLedgerOptions {
+    executionLeaseMs?: number;
+    pollIntervalMs?: number;
+    maxPolls?: number;
+}
+export declare class PostgresOperationLedger<T> implements IdempotentExecutor<T> {
+    private readonly executor;
+    private readonly codec;
+    private readonly executionLeaseMs;
+    private readonly pollIntervalMs;
+    private readonly maxPolls;
+    constructor(executor: SqlExecutor, codec: CanonicalCodec<T>, options?: PostgresLedgerOptions);
+    execute(operationIdInput: string, operationDigestInput: string, effect: () => Promise<T>, context?: IdempotentExecutionContext, classifyResult?: (result: T) => "committed" | "unknown_requires_review"): Promise<T>;
+    resolve(operationIdInput: string, operationDigestInput: string, fenceInput: BrokerFence): Promise<T | null>;
+    adoptReconciledResult(operationIdInput: string, operationDigestInput: string, fenceInput: BrokerFence, result: T, reconciliationEvidenceSha256Input: string): Promise<T>;
+    private join;
+    private load;
+    private resolveRow;
+}
+export type ProviderStepResolution<T> = Readonly<{
+    state: "missing";
+} | {
+    state: "prepared" | "dispatched" | "failed_no_effect";
+} | {
+    state: "unknown_requires_review";
+    result?: T;
+} | {
+    state: "succeeded";
+    result: T;
+}>;
+export declare class PostgresProviderStepLedger implements ProviderStepExecutor {
+    private readonly executor;
+    private readonly effectJournal;
+    private readonly options;
+    constructor(executor: SqlExecutor, effectJournal: ProviderEffectJournalAuthorityPort, options?: PostgresLedgerOptions);
+    execute<T>(input: ProviderStepExecutionInput, effect: () => Promise<T>, codec: CanonicalCodec<T>, providerRequestId: (result: T) => string | null, classifyResult?: (result: T) => "succeeded" | "unknown_requires_review"): Promise<T>;
+    resolve<T>(input: ProviderStepExecutionInput, codec: CanonicalCodec<T>): Promise<ProviderStepResolution<T>>;
+    adoptReconciledResult<T>(input: ProviderStepExecutionInput, result: T, codec: CanonicalCodec<T>, providerRequestId: (result: T) => string | null, reconciliationProviderRequestIdInput: string, reconciliationEvidenceSha256Input: string): Promise<T>;
+}
+export declare function providerEffectJournalAnchorCoreDigest(input: ProviderEffectJournalAnchorInput): string;

package/dist/types/cli/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export declare const LOCAL_OPERATOR_ENDPOINT: "http://127.0.0.1:18787";

package/dist/types/cli/operation-journal.d.ts

@@ -0,0 +1,47 @@
+import type { Clock } from "../core/clock";
+import type { IdFactory } from "../core/ids";
+import type { OperatorEnvelope } from "../client/operator-client";
+import { type PublicMutationResultExpectation } from "../contracts/operations";
+export interface CliOperationIntent {
+    command: string;
+    idempotencyKey: string;
+    scope: Readonly<Record<string, unknown>>;
+    request: Readonly<Record<string, unknown>>;
+    authorityRequestHash: string;
+    resultExpectation: Readonly<PublicMutationResultExpectation>;
+}
+export interface PreparedCliOperation {
+    operationId: string;
+    command: string;
+    idempotencyKey: string;
+    scopeDigest: string;
+    requestDigest: string;
+    authorityRequestHash: string;
+    resultExpectation: Readonly<PublicMutationResultExpectation>;
+    replayed: boolean;
+}
+export interface CliOperationJournal {
+    prepare(intent: CliOperationIntent): Promise<PreparedCliOperation>;
+    recordResponse(operationId: string, envelope: OperatorEnvelope): Promise<void>;
+    read(operationId: string): PreparedCliOperation & {
+        state: "prepared" | "responded";
+        responseDigest: string | null;
+    };
+}
+export declare function defaultCliOperationJournalPath(): string;
+export declare class DurableCliOperationJournal implements CliOperationJournal {
+    private readonly path;
+    private readonly ids;
+    private readonly clock;
+    private database;
+    constructor(path: string, ids: IdFactory, clock: Clock);
+    prepare(value: CliOperationIntent): Promise<PreparedCliOperation>;
+    recordResponse(operationIdInput: string, envelope: OperatorEnvelope): Promise<void>;
+    read(operationIdInput: string): PreparedCliOperation & {
+        state: "prepared" | "responded";
+        responseDigest: string | null;
+    };
+    close(): void;
+    private open;
+}
+export declare function successfulMutationConsequenceDigest(command: string, operationId: string, value: unknown, expectation: PublicMutationResultExpectation): string;

package/dist/types/cli/run.d.ts

@@ -0,0 +1,15 @@
+import { type OperatorClient, type OperatorEnvelope } from "../client/operator-client";
+import { type CliOperationJournal } from "./operation-journal";
+export interface CliRuntime {
+    client: OperatorClient;
+    readInput(selector: string): Promise<string>;
+    writeStdout(value: string): void;
+    writeStderr(value: string): void;
+    operationJournal: CliOperationJournal;
+    now(): Date;
+}
+export declare function runCli(argv: string[], runtime: CliRuntime): Promise<number>;
+export declare class CliUsageError extends Error {
+    constructor(message: string);
+}
+export declare function localFailure(error: unknown, now: Date): OperatorEnvelope;