run402 4.24.0 → 4.25.0

package/sdk/dist/node/gitvault-publication.d.ts

@@ -0,0 +1,730 @@
+/**
+ * gitvault — publication (protocol rev 40 §6 + §4.4–4.7 + §5A client side;
+ * task 5.4).
+ *
+ * What lives here:
+ *   - the PURE evaluators: ref transactions (§6.1 — force-with-lease only,
+ *     fast-forward for non-force branch updates, immutable tags, deletes need
+ *     expected-old, pairwise-distinct refs refused BEFORE evaluation, the
+ *     §6.5 cardinality bounds), retention-root evolution (§4.5 — map keyed
+ *     `(ref, oid)`, renewal, expiry ONLY at checkpoints against the pre-signing
+ *     cutoff ticket, strict `effective + 90d < cutoff_at`), the heads-listing
+ *     page contract (§6.3 / D186 — anchor echo, cursor echo, has_more/
+ *     next_cursor coupling, strictly-above-anchor, gapless across pages,
+ *     truthful total), chain linkage (`CHAIN_BROKEN`), and the transition
+ *     fail-closed rule (`UPGRADE_REQUIRED`);
+ *   - {@link GitvaultTransport} — the control-plane + bucket operations the
+ *     vault needs (extends task 5.3's creation transport) — and
+ *     {@link createGitvaultHttpTransport}, the `fetch`-backed implementation
+ *     over the SDK kernel (upload sessions → presigned PUT with
+ *     `If-None-Match: *` → finalize);
+ *   - {@link GitvaultVault} — discover/verify to newest with the RESUMABLE
+ *     verification budget, materialize (decrypt ref_state + retention_roots →
+ *     the materialized pin), push (pack_set or a checkpoint-bearing head when
+ *     the delta exceeds the 64-receipt budget, upload with receipt-compare,
+ *     admission with 409 re-apply-and-retry, head read-back before any pin
+ *     advances), checkpoint build + acceptance self-check, and repair (the
+ *     mandatory fresh checkpoint + the exact repair-root algebra).
+ *
+ * Dual pins (§6.4) live in the keystore repo file: `head_pin` is
+ * `highest_authenticated`, `materialized_pin` is `highest_materialized` — the
+ * ONLY push base. A regression below the authenticated pin is
+ * `GENERATION_REGRESSION`; an authenticated-but-undecryptable head is
+ * `CHAIN_UNUSABLE` (read-only at the materialized pin); an admitted non-null
+ * transition is `UPGRADE_REQUIRED` (read-only past it, no publish).
+ */
+import type { Client } from "../kernel.js";
+import type { GitvaultActivationToken, GitvaultCaptureBinding, GitvaultCaptureReceipt, GitvaultCheckpointBlock, GitvaultCheckpointClaimSet, GitvaultCheckpointManifest, GitvaultDigestLabel, GitvaultHead, GitvaultHeadTarget, GitvaultHeadsListingPage, GitvaultHeadsListingRequest, GitvaultRefState, GitvaultRefTransaction, GitvaultRefUpdate, GitvaultRepairDescriptor, GitvaultRetentionCutoff, GitvaultRetentionCutoffReceipt, GitvaultRetentionRoot, GitvaultRetentionRoots, GitvaultRetentionRootsReceipt, GitvaultVaultGenesis } from "../namespaces/gitvault.types.js";
+import type { GitvaultCreationTransport } from "./gitvault-creation-journal.js";
+import { GitvaultKeystore, type GitvaultRepoFile } from "./gitvault-keystore.js";
+import type { GitvaultPruneIntentRecord } from "./gitvault-prune.js";
+export declare const GITVAULT_MAX_CANONICAL_REFS = 10000;
+export declare const GITVAULT_MAX_REF_UPDATES_PER_TRANSACTION = 1000;
+export declare const GITVAULT_MAX_RETENTION_ROOT_ENTRIES = 50000;
+export declare const GITVAULT_MAX_REPAIR_ADDED_ROOTS = 10000;
+export declare const GITVAULT_MAX_WAL_RECEIPTS_PER_HEAD = 64;
+export declare const GITVAULT_MAX_CHECKPOINT_PACKS = 4096;
+export declare const GITVAULT_MAX_CHECKPOINT_TOTAL_STORED_BYTES = 858993459200n;
+export declare const GITVAULT_MULTI_OBJECT_PACK_TARGET_BYTES = 201326592;
+export declare const GITVAULT_MAX_REF_STATE_OBJECT_BYTES = 33554432;
+export declare const GITVAULT_MAX_HEADS_PER_LISTING_PAGE = 1000;
+export declare const GITVAULT_VERIFICATION_BUDGET_HEADS = 100000;
+export declare const GITVAULT_RETENTION_MIN_DAYS = 90;
+/** Default admission-conflict retries before the push gives up (each retry re-verifies + re-applies to the winner). */
+export declare const GITVAULT_PUSH_CONFLICT_RETRIES = 5;
+export declare function generationToBigInt(generation: string): bigint;
+export declare function bigIntToGeneration(value: bigint): string;
+export declare function nextGeneration(generation: string): string;
+export type GitvaultRefMap = Record<string, string>;
+/** A tip that left the canonical map in this transaction — it enters `retention_roots` in the same generation. */
+export interface GitvaultDroppedTip {
+    ref: string;
+    oid: string;
+    reason: "deleted" | "force_displaced";
+}
+export interface GitvaultRefTransactionEvaluation {
+    refs: GitvaultRefMap;
+    dropped: GitvaultDroppedTip[];
+}
+export interface GitvaultEvaluateRefTransactionOptions {
+    /** Ancestry oracle: true iff `ancestor` is reachable from `descendant`. */
+    isAncestor: (ancestor: string, descendant: string) => Promise<boolean> | boolean;
+    /** `refuse` (default — user pushes): any `refs/run402/*` update is refused; `allow`: the protocol's own deploy-ref move. */
+    protocol_refs?: "refuse" | "allow";
+}
+/** One failing update of a refused transaction (never a silent revert). */
+export interface GitvaultRefUpdateFailure {
+    ref: string;
+    reason: "expected_old_mismatch" | "non_fast_forward" | "tag_immutable" | "delete_requires_expected_old" | "noop";
+    expected_old_oid: string | null;
+    current_oid: string | null;
+}
+/**
+ * Evaluate a §6.1 transaction against the materialized map. Refusals in
+ * order: pairwise-distinct refs (before evaluation), grammar, the update cap,
+ * then per-update semantics collected into ONE `REF_EXPECTED_OLD_MISMATCH`
+ * (every failing update listed), then the resulting-state cardinality.
+ */
+export declare function evaluateRefTransaction(current: GitvaultRefMap, transaction: GitvaultRefTransaction, options: GitvaultEvaluateRefTransactionOptions): Promise<GitvaultRefTransactionEvaluation>;
+/** §6.5 bound: ≤ 10 000 canonical refs and the serialized map ≤ 32 MiB. */
+export declare function assertRefMapCardinality(refs: GitvaultRefMap): void;
+/** The §4.4 deploy-ref move: force-with-lease `refs/run402/deploys/latest` → `oid` (creation when absent). */
+export declare function deployRefTransaction(current: GitvaultRefMap, oid: string): GitvaultRefTransaction;
+/** `effective_admitted_at = max(prepared_at, storage creation time of the winning admission record)` (§4.10). */
+export declare function effectiveAdmittedAt(preparedAt: string, recordStorageCreatedAt: string): string;
+/** A root may be removed iff `effective_admitted_at + 90 days < cutoff_at` (STRICT; §4.5a). */
+export declare function isRootEligibleForRemoval(effectiveAdmittedAtIso: string, cutoffAtIso: string, retentionDays?: number): boolean;
+export interface GitvaultEvolveRootsOptions {
+    /** The generation being built (`g+1`) — stamped as `dropped_at_generation` on new/renewed keys. */
+    generation: string;
+    /** Tips dropped or force-displaced by this generation's transaction. */
+    dropped: Array<{
+        ref: string;
+        oid: string;
+    }>;
+    /**
+     * Present ONLY when this generation carries a checkpoint bound to a cutoff
+     * ticket: expiry is evaluated against `cutoff_at` using the resolver for each
+     * root's drop generation. Removal is PERMISSIVE — a resolver returning
+     * `null` keeps the root.
+     */
+    checkpoint_cutoff?: {
+        cutoff_at: string;
+        effectiveAdmittedAt: (droppedAtGeneration: string) => string | null;
+    };
+}
+export declare function compareRoots(a: GitvaultRetentionRoot, b: GitvaultRetentionRoot): number;
+/** roots(g+1) = roots(g) ∪ dropped (RENEWING an existing `(ref, oid)` key) ∖ {expired, only at a checkpoint with a ticket}. */
+export declare function evolveRetentionRoots(previous: GitvaultRetentionRoot[], options: GitvaultEvolveRootsOptions): GitvaultRetentionRoot[];
+export interface GitvaultListingProgress {
+    /** The anchor (constant across the sequence). */
+    after_generation: string;
+    /** The highest generation delivered so far (== anchor before page 1). */
+    last_generation: string;
+    /** Generations delivered so far (for the truthful-total check). */
+    delivered: number;
+}
+/** Validate a listing request before it is sent (the request schema, D186). */
+export declare function validateHeadsListingRequest(request: GitvaultHeadsListingRequest): void;
+/**
+ * Validate one page against the request and the sequence so far. Returns the
+ * advanced progress. Refusals: anchor not echoed / wrong vault / coupling
+ * violation / retired member → `GITVAULT_LISTING_PAGE_INVALID`; an entry at or
+ * below the anchor → `GENERATION_REGRESSION`; a gap within or across pages →
+ * `CHAIN_BROKEN`; an untruthful final `total` → `CHAIN_BROKEN`.
+ */
+export declare function verifyHeadsListingPage(page: GitvaultHeadsListingPage, request: GitvaultHeadsListingRequest, progress: GitvaultListingProgress, expectedRepoId?: string): GitvaultListingProgress;
+/**
+ * The continuation request for `page`, or `null` when the sequence is complete.
+ * The anchor stays CONSTANT and `next_cursor` is echoed UNCHANGED — the cursor
+ * is stored and echoed, never parsed or edited (a client that re-anchors or
+ * edits a byte earns `INVALID_CURSOR` from the platform, D186).
+ */
+export declare function nextListingRequest(request: GitvaultHeadsListingRequest, page: GitvaultHeadsListingPage): GitvaultHeadsListingRequest | null;
+/**
+ * §6.4: the vault's newest generation may never fall BELOW the authenticated
+ * pin. A listing (or a storage read) that says otherwise is a rollback, not a
+ * quiet vault — `GENERATION_REGRESSION`, no publish.
+ */
+export declare function checkGenerationRegression(listedNewestGeneration: string, pinnedGeneration: string): void;
+/** The parameters a maintenance open requests, and that the C1 record must echo. */
+export interface GitvaultOpenBindingRecord {
+    base_head_sha256: string;
+    prior_checkpoint_claim_set_sha256: string | null;
+    r2_cap_size_bytes: string;
+}
+/** `SHA-256("r402s/v0/open-binding" ‖ lp(client_open_id) ‖ lp(base_head) ‖ lp_opt(prior) ‖ lp(cap))`. */
+export declare function openBindingDigest(clientOpenId: string, record: GitvaultOpenBindingRecord): string;
+/**
+ * Recompute the binding from the record's OWN fields and compare it bytewise
+ * with the signed issuance digest. The error registry has no dedicated code for
+ * the fence inequality (D145), so the client surfaces
+ * `GITVAULT_OPEN_BINDING_MISMATCH`; a same-`client_open_id` retry that carries a
+ * DIFFERENT binding is the registry's `CLIENT_OPEN_ID_CONFLICT`.
+ */
+export declare function checkOpenBinding(clientOpenId: string, record: GitvaultOpenBindingRecord, issuanceOpenBindingSha256: string, options?: {
+    retry?: boolean;
+}): void;
+export interface GitvaultChainLinkInput {
+    head: GitvaultHead;
+    stored_bytes: Uint8Array;
+    /** The listing's hash for this generation. */
+    listed_sha256: string;
+    expected_generation: string;
+    prev_sha256: string;
+    repo_id: string;
+    /** The registered writer public key (V0: the genesis creator key). */
+    writer_public_key: Uint8Array | string;
+    writer_key_id: string;
+}
+/** Verify one link: bytes hash to the listing, strict parse, generation, prev linkage, epoch pin, repo, writer signature. */
+export declare function checkChainLink(input: GitvaultChainLinkInput): void;
+/**
+ * The transition fail-closed rule: a V0 client that encounters an ADMITTED
+ * non-null transition stops advancing — read-only at the materialized pin,
+ * no publish past it, `UPGRADE_REQUIRED`. Unknown kinds are a parse reject.
+ */
+export declare function assertNoTransition(head: GitvaultHead): void;
+/** One object to upload — identity fixed BEFORE the PUT; the receipt is compared against it. */
+export interface GitvaultUploadObject {
+    /**
+     * Storage path relative to the vault root (§3). CLIENT-LOCAL addressing only:
+     * the control plane derives the bucket key from `object_kind` + the ledger
+     * identity and REFUSES a manifest entry carrying an unexpected member, so
+     * this never rides the wire (5.6c).
+     */
+    path: string;
+    object_kind: string;
+    /** `null` for path-addressed kinds (envelopes) — those ride `epoch` + `recipient_fingerprint`. */
+    object_id: string | null;
+    bytes: Uint8Array;
+    /** SHA-256 of `bytes` (ciphertext hash for frames, stored-bytes hash for plaintext kinds). */
+    sha256: string;
+    size_bytes: string;
+    /** `wal_pack` only — §4.1: the ONLY receipt kind carrying `base_generation`. */
+    base_generation?: string;
+}
+export interface GitvaultUploadReceipt {
+    path: string;
+    object_id: string | null;
+    sha256: string;
+    size_bytes: string;
+}
+/**
+ * The control plane addresses stored objects by LEDGER IDENTITY, never by
+ * bucket path: heads and admission records have their own generation-addressed
+ * routes, and every uploadable kind is named by `object_kind` + `object_id`
+ * (or, for envelopes, `epoch` + `recipient_fingerprint`). This resolver maps
+ * the SDK's internal `gitvaultPaths` strings onto that identity so the rest of
+ * the vault can keep addressing objects the way §3 describes them.
+ */
+export type GitvaultWireRef = {
+    kind: "head";
+    generation: string;
+} | {
+    kind: "admission";
+    generation: string;
+} | {
+    kind: "object";
+    read: GitvaultObjectReadRequest;
+};
+/** One entry of a `POST …/object-reads` batch. */
+export interface GitvaultObjectReadRequest {
+    object_kind: string;
+    object_id?: string;
+    epoch?: string;
+    recipient_fingerprint?: string;
+}
+/** `null` for a path with no wire identity (e.g. a locally-held cutoff ticket). */
+export declare function gitvaultWireRefForPath(path: string): GitvaultWireRef | null;
+/** The manifest entry for one upload — closed-key, exactly what the control plane validates. */
+export declare function gitvaultManifestEntry(object: GitvaultUploadObject): GitvaultObjectReadRequest & {
+    sha256: string;
+    size_bytes: string;
+    base_generation?: string;
+};
+/** The stable key both sides agree on, used to pair receipts back to requests. */
+export declare function gitvaultLedgerId(read: GitvaultObjectReadRequest): string;
+export interface GitvaultAdmitHeadRequest {
+    repo_id: string;
+    generation: string;
+    stored_bytes: Uint8Array;
+    stored_bytes_sha256: string;
+}
+export type GitvaultAdmitHeadResult = {
+    outcome: "admitted";
+    admission_record_sha256: string;
+    capture_receipt: GitvaultCaptureReceipt | null;
+} | {
+    outcome: "conflict";
+    winner: {
+        generation: string;
+        stored_bytes_sha256: string;
+    };
+};
+export interface GitvaultRetentionCutoffIssued {
+    ticket: GitvaultRetentionCutoff;
+    receipt: GitvaultRetentionCutoffReceipt;
+}
+/**
+ * Everything the vault needs from the control plane + bucket. Extends the
+ * creation transport so one implementation serves 5.3–5.6. All methods are
+ * idempotent from the state machines' point of view.
+ */
+/** The `resource_binding` an upload session is charged against (§7.2 / §9.3). */
+export type GitvaultResourceBinding = {
+    kind: "ordinary_push";
+} | {
+    kind: "maintenance_cycle";
+    maintenance_lease_id: string;
+} | {
+    kind: "repair_attempt";
+    repair_attempt_id: string;
+};
+/** `POST …/maintenance-leases` — the owner's compact/prune reservation (§7.2). */
+export interface GitvaultMaintenanceLeaseRequest {
+    repo_id: string;
+    base_head_sha256: string;
+    current_checkpoint_hash?: string | null;
+    r1_size_bytes: string;
+    r2_cap_size_bytes: string;
+    p_before_c1_size_bytes?: string;
+    p_before_c2_size_bytes?: string;
+}
+export interface GitvaultMaintenanceLease {
+    maintenance_lease_id: string;
+    repo_id: string;
+    base_head_sha256: string;
+    current_checkpoint_hash: string | null;
+    reservation_size_bytes: string;
+    maintenance_headroom_bytes: string;
+    /** Returned ONCE — the liveness instrument (heartbeat / release). Never logged, never cached. */
+    holder_token: string;
+    expires_at: string | null;
+    hard_deadline_at: string | null;
+}
+export interface GitvaultTransport extends GitvaultCreationTransport {
+    listHeads(request: GitvaultHeadsListingRequest & {
+        repo_id: string;
+    }): Promise<GitvaultHeadsListingPage>;
+    /** Session → create-only presigned PUTs (`If-None-Match: *`) → finalize; receipts in request order. */
+    uploadObjects(request: {
+        repo_id: string;
+        objects: GitvaultUploadObject[];
+        resource_binding?: GitvaultResourceBinding;
+    }): Promise<GitvaultUploadReceipt[]>;
+    admitHead(request: GitvaultAdmitHeadRequest): Promise<GitvaultAdmitHeadResult>;
+    requestRetentionCutoff(request: {
+        repo_id: string;
+        base_head_sha256: string;
+    }): Promise<GitvaultRetentionCutoffIssued>;
+    exchangeActivationToken(request: {
+        repo_id: string;
+        operation_id: string;
+        capture_receipt: GitvaultCaptureReceipt;
+    }): Promise<GitvaultActivationToken>;
+    submitOverrideCompletion(request: {
+        repo_id: string;
+        operation_id: string;
+        capture_receipt: GitvaultCaptureReceipt;
+    }): Promise<{
+        cleared: boolean;
+    }>;
+    /** The vault record — policy, allocation generation, storage + maintenance state (§9.2). */
+    getVaultRecord(request: {
+        repo_id: string;
+    }): Promise<GitvaultVaultRecord>;
+    /** Resolve a project's vault without local state (the cold-restart entry point). */
+    findVaultByProject(request: {
+        project_id: string;
+    }): Promise<GitvaultVaultRecord>;
+    acquireMaintenanceLease(request: GitvaultMaintenanceLeaseRequest): Promise<GitvaultMaintenanceLease>;
+    heartbeatMaintenanceLease(request: {
+        repo_id: string;
+        maintenance_lease_id: string;
+        holder_token: string;
+    }): Promise<{
+        maintenance_lease_id: string;
+        expires_at: string | null;
+    }>;
+    releaseMaintenanceLease(request: {
+        repo_id: string;
+        maintenance_lease_id: string;
+        holder_token: string;
+    }): Promise<{
+        maintenance_lease_id: string;
+        status: string;
+    }>;
+    /**
+     * `POST …/prune-intents` — the intent's EXACT BYTES (§7.3).
+     *
+     * The route is parsed with `express.raw` and the owner signature is verified
+     * over the bytes as sent, so the transport MUST NOT re-serialize: it puts
+     * `intent_bytes` on the wire verbatim under `Content-Type: application/json`.
+     * An implementation that accepts a parsed object here and stringifies it is
+     * signing one thing and sending another.
+     */
+    submitPruneIntent(request: {
+        repo_id: string;
+        intent_bytes: Uint8Array;
+    }): Promise<GitvaultPruneIntentRecord & {
+        stored: boolean;
+    }>;
+    /** `GET …/prune-intents/:id` — the intent's state and, once signed, its completion. */
+    getPruneIntent(request: {
+        repo_id: string;
+        prune_intent_object_id: string;
+    }): Promise<GitvaultPruneIntentRecord | null>;
+}
+/** `GET /gitvault/v1/vaults/:vault_id` — the shape `reads.ts:getVaultRecord` returns. */
+export interface GitvaultVaultRecord {
+    repo_id: string;
+    project_id: string;
+    org_id: string;
+    gitvault_policy: "required" | "grandfathered" | null;
+    gitvault_policy_version: string;
+    gitvault_policy_changed_at: string | null;
+    allocation_generation: string;
+    allocation_sha256: string | null;
+    newest_generation: string | null;
+    genesis_admitted_at: string | null;
+    latest_effective_admitted_at: string | null;
+    admitted_generations: string;
+    gc_epoch: string;
+    repair_version: string;
+    repair_fence_state: string;
+    storage: {
+        source_bytes: string;
+        open_session_reserved_bytes: string;
+        objects: Record<string, string>;
+    };
+    maintenance: {
+        lease: {
+            maintenance_lease_id: string;
+            base_head_sha256: string;
+            reservation_size_bytes: string;
+            expires_at: string | null;
+            hard_deadline_at: string | null;
+        } | null;
+        open_cycle: {
+            maintenance_cycle_id: string;
+            state: string;
+            last_cycle_progress_at: string | null;
+        } | null;
+        pending_repair_attempt_id: string | null;
+    };
+    warnings: {
+        kind: string;
+        message: string;
+    }[];
+    created_at: string | null;
+}
+export interface GitvaultHttpTransportOptions {
+    /** Wire shape: every vault-scoped route is `/gitvault/v1/vaults/:vault_id/...`; `vault_id` is the `repo_id` unless a mapping is supplied (D185). */
+    vaultIdFor?: (repoId: string) => string;
+}
+/**
+ * The `fetch`-backed transport over the SDK kernel. Presigned PUTs carry
+ * `If-None-Match: *` (create-only — the bucket policy demands it) and the
+ * FULL_OBJECT SHA-256 checksum header.
+ */
+export declare function createGitvaultHttpTransport(client: Client, options?: GitvaultHttpTransportOptions): GitvaultTransport;
+export declare const gitvaultPaths: {
+    readonly head: (generation: string) => string;
+    readonly admission: (generation: string) => string;
+    readonly wal: (id: string) => string;
+    readonly refState: (id: string) => string;
+    readonly retentionRoots: (id: string) => string;
+    readonly checkpointManifest: (id: string) => string;
+    readonly checkpointPack: (id: string) => string;
+    readonly claimSet: (id: string) => string;
+    readonly cutoffTicket: (id: string) => string;
+    /** `verifier-receipts/<vr>.json` — plaintext-structured, uploaded before a prune intent may reference it (§7.3). */
+    readonly verifierReceipt: (id: string) => string;
+};
+export interface GitvaultVaultOptions {
+    keystore: GitvaultKeystore;
+    transport: GitvaultTransport;
+    repo_id: string;
+    /** The local git repository (objects for pack building / ancestry); optional for read-only use. */
+    repo_dir?: string;
+    now?: () => Date;
+    /** Verification budget per call (resumable — the verified prefix persists). */
+    verification_budget?: number;
+    conflict_retries?: number;
+    /** The signing service key resolved through the registry — when supplied, control-plane-signed messages (cutoff tickets) are signature-checked. */
+    service_public_key?: Uint8Array | string;
+}
+/** How a checkpoint-bearing head binds a `retention_cutoff` ticket and expires roots (§4.5a / §4.5). */
+export interface GitvaultCutoffOptions {
+    /**
+     * `effective_admitted_at` for a root's drop generation, or `null` when this
+     * client cannot resolve it — a `null` RETAINS the root (expiry is permissive).
+     * `effective_admitted_at = max(prepared_at, the admission record's storage
+     * creation time)`; deriving it from `prepared_at` alone shortens the lane.
+     */
+    effectiveAdmittedAt?: (droppedAtGeneration: string) => string | null;
+}
+export interface GitvaultVerifiedState {
+    generation: string;
+    head_sha256: string;
+    /** `null` at generation zero. */
+    head: GitvaultHead | null;
+    genesis: GitvaultVaultGenesis;
+}
+export interface GitvaultMaterializedState extends GitvaultVerifiedState {
+    ref_state: GitvaultRefState | null;
+    retention_roots: GitvaultRetentionRoots | null;
+    refs: GitvaultRefMap;
+    roots: GitvaultRetentionRoot[];
+    head_target: GitvaultHeadTarget;
+}
+export interface GitvaultPushOptions {
+    transaction: GitvaultRefTransaction;
+    /** New `HEAD` target for the published ref_state; carried forward when omitted. */
+    head_target?: GitvaultHeadTarget;
+    protocol_refs?: "refuse" | "allow";
+    /** Force the checkpoint-bearing form (purpose `ordinary_push`) regardless of delta size. */
+    checkpoint?: boolean;
+    /** Bind a fresh `retention_cutoff` ticket so expired roots may leave the map (checkpoint-bearing heads only). */
+    cutoff?: GitvaultCutoffOptions;
+    /** Built lazily at head-sign time — the deploy lane may still be computing the plan digest. */
+    capture_binding?: GitvaultCaptureBinding | (() => Promise<GitvaultCaptureBinding | null> | GitvaultCaptureBinding | null);
+}
+export interface GitvaultPublishResult {
+    generation: string;
+    head_sha256: string;
+    head: GitvaultHead;
+    admission_record_sha256: string;
+    capture_receipt: GitvaultCaptureReceipt | null;
+    /** `wal` = direct WAL receipts; `checkpoint` = the delta shipped as a checkpoint set. */
+    form: "wal" | "checkpoint";
+    conflicts_retried: number;
+    refs: GitvaultRefMap;
+}
+/**
+ * What {@link GitvaultVault.verifyStoredCheckpoint} observed. Every boolean is
+ * a FINDING, not a promise: a `false` here is what makes a truthful negative
+ * `verifier_receipt` possible.
+ */
+export interface GitvaultStoredCheckpointAttestation {
+    checkpoint_head_sha256: string;
+    checkpoint_generation: string;
+    claim_set_sha256: string;
+    /** `null` in the no-removal checkpoint form — a prune needs one, so that is a refusal upstream. */
+    cutoff_ticket_sha256: string | null;
+    cutoff_at: string | null;
+    covered_tips: string[];
+    /** Covered tips that did NOT resolve from the restored set. Non-empty ⇒ the checkpoint does not verify. */
+    missing_tips: string[];
+    restored_object_set_hmac: string;
+    object_set_matches: boolean;
+    ref_state_matches: boolean;
+    retention_roots_matches: boolean;
+    /** The `rootset` commitment over this generation's roots carrier — the intent core's `retention_state_hmac`. */
+    retention_state_hmac: string;
+}
+export interface GitvaultBuiltCheckpoint {
+    manifest: GitvaultCheckpointManifest;
+    claim_set: GitvaultCheckpointClaimSet;
+    claim_set_receipt: GitvaultCheckpointBlock["claim_set"];
+    objects: GitvaultUploadObject[];
+    /** Plaintext packs in order (for the acceptance self-check). */
+    packs: Uint8Array[];
+    covered_tips: string[];
+}
+/** A transport-agnostic view of git ops the publication needs (the local repository). */
+export declare class GitvaultVault {
+    readonly keystore: GitvaultKeystore;
+    readonly transport: GitvaultTransport;
+    readonly repoId: string;
+    readonly repoDir: string | null;
+    private readonly now;
+    private readonly budget;
+    private readonly retries;
+    private readonly servicePublicKey;
+    private genesisCache;
+    constructor(options: GitvaultVaultOptions);
+    static open(options: GitvaultVaultOptions): GitvaultVault;
+    repoFile(): GitvaultRepoFile;
+    private kRepo;
+    private epoch;
+    private git;
+    /** Fetch + pin-check the genesis (the writer key source). */
+    genesis(): Promise<{
+        genesis: GitvaultVaultGenesis;
+        sha256: string;
+    }>;
+    /**
+     * List from the authenticated pin and verify every link upward. Persists
+     * the verified prefix after each page, so a `VERIFICATION_BUDGET_EXCEEDED`
+     * continues rather than restarts. Returns the newest verified state.
+     */
+    verifyToNewest(): Promise<GitvaultVerifiedState>;
+    private readHead;
+    /** Decrypt one encrypted carrier object by its receipt; any failure is `CHAIN_UNUSABLE`. */
+    private openCarrier;
+    /** Verify to newest, then decrypt + apply its carriers — advancing the materialized pin. */
+    materialize(): Promise<GitvaultMaterializedState>;
+    private seal;
+    /**
+     * The owner signing seed, or `GITVAULT_READ_ONLY`.
+     *
+     * Public so the prune lane signs its intent core, wrapper, and verifier
+     * receipt through the SAME refusal path every other signed object uses — a
+     * second "get the seed" helper is a second place for a read-only principal to
+     * slip through. The vault is already open by the time this is reachable, so
+     * `ensureIdentity` never MINTS here (it would refuse at `repoFile()` first).
+     */
+    signer(): Uint8Array;
+    private writerKeyId;
+    private buildRefState;
+    private buildRetentionRoots;
+    /** Plaintext, independently non-thin packs covering `reachable(tips) ∖ reachable(base)`, split at the multi-object target. */
+    buildPacks(tips: string[], base: string[]): Promise<Uint8Array[]>;
+    /** Sorted unique object ids reachable from `tips` (the `"objectset"` content). */
+    objectSet(tips: string[]): Promise<string[]>;
+    /**
+     * The same `"objectset"` content computed in an ARBITRARY repository.
+     *
+     * The prune lane's restore-and-verify pass runs against a scratch clone-back,
+     * not the working tree, and must recompute the digest there with the same
+     * canonicalization the manifest was built with — hence one implementation,
+     * parameterized by directory, rather than a second rev-list at the call site.
+     */
+    objectSetIn(dir: string, tips: string[]): Promise<string[]>;
+    /**
+     * Decrypt one generation's `retention_roots` carrier by its head receipt.
+     *
+     * `materialize()` opens only the NEWEST carrier; the prune lane must compare
+     * consecutive generations to see which roots LEFT the map, so it needs any
+     * generation's. Same `openCarrier` path, same `CHAIN_UNUSABLE` semantics — a
+     * carrier that cannot be opened is never silently treated as empty.
+     */
+    openRetentionRootsAt(receipt: GitvaultRetentionRootsReceipt): Promise<GitvaultRetentionRoots>;
+    private digest;
+    /**
+     * The §1 keyed commitment under one of the five `K_digest` labels.
+     *
+     * Public because the prune lane needs `gcrootset` (over the GC root set's
+     * sorted receipts) and `rootset` (over the retention-roots carrier) and must
+     * compute them with the SAME key derivation the checkpoint manifest uses —
+     * two derivations for one commitment is how a verifier and a publisher stop
+     * agreeing. Keyed by design (§7.3): a server-comparable plaintext digest
+     * would be a confirmation oracle.
+     */
+    keyedDigest(label: GitvaultDigestLabel, content: unknown): string;
+    /** Strip the single top-level signature — the commitment preimage shape carriers use. */
+    digestPreimage<T extends {
+        signature: string;
+    }>(o: T): Omit<T, "signature">;
+    private withoutSignature;
+    /** Coverage tips (§4.7): canonical refs ∪ unexpired roots ∪ the HEAD target (detached commit; an unborn symref contributes nothing). */
+    static coverageTips(refs: GitvaultRefMap, roots: GitvaultRetentionRoot[], headTarget: GitvaultHeadTarget): string[];
+    /**
+     * Build a checkpoint set (§4.7): manifest + packs + the owner-signed claim
+     * set, with the acceptance self-check (restore into an empty scratch, every
+     * covered tip resolves, full connectivity, all three keyed commitments
+     * recomputed). Coverage above the V0 maximum → `CHECKPOINT_SET_LIMIT_EXCEEDED`.
+     */
+    buildCheckpoint(input: {
+        generation: string;
+        ref_state: GitvaultRefState;
+        retention_roots: GitvaultRetentionRoots;
+    }): Promise<GitvaultBuiltCheckpoint>;
+    /** §4.7 acceptance: restore from the set ALONE into an empty scratch; every covered ref resolves; fsck connectivity; recompute the three commitments. */
+    acceptCheckpoint(built: GitvaultBuiltCheckpoint, refState: GitvaultRefState, roots: GitvaultRetentionRoots): Promise<void>;
+    /**
+     * The §4.7 acceptance run against a checkpoint ALREADY IN STORAGE — the
+     * restore-and-verify pass a `verifier_receipt` attests (§7.3).
+     *
+     * `acceptCheckpoint` above proves a checkpoint the client just BUILT; this
+     * proves one the client is about to make a claim about, from the stored bytes
+     * alone. It reports the observed facts rather than throwing on a mismatch,
+     * because "the checkpoint does not verify" is exactly the finding a receipt
+     * must be able to carry as `false` — turning it into an exception would make
+     * an honest negative attestation impossible to produce.
+     */
+    verifyStoredCheckpoint(head: GitvaultHead, headSha256: string): Promise<GitvaultStoredCheckpointAttestation>;
+    /**
+     * The whole verified chain, newest-first walk returned oldest-first, each
+     * head paired with its checkpoint claim set (`null` when it bears none).
+     *
+     * The prune lane needs EVERY generation, not just the newest: a candidate is
+     * an object some head once named and no surviving head still needs, and that
+     * is only computable over the whole chain. Reuses {@link chainFrom}, so the
+     * bytes are re-read and hash-checked against the verified chain rather than
+     * trusted from a listing.
+     */
+    chainEntries(): Promise<Array<{
+        head: GitvaultHead;
+        head_sha256: string;
+        claim_set: GitvaultCheckpointClaimSet | null;
+    }>>;
+    private uploadAll;
+    /**
+     * Build + upload + sign + admit ONE generation over `base`. Shared by the ref
+     * transaction path (`push`) and the checkpoint-only path (`publishCheckpoint`); the
+     * caller owns the conflict loop because only it knows how to re-derive the
+     * next state from the winner.
+     */
+    private publishGeneration;
+    /** The complete push: verify → materialize → evaluate → pack → upload → head → admit (409: re-apply to the winner, retry) → read back → advance pins. */
+    push(options: GitvaultPushOptions): Promise<GitvaultPublishResult>;
+    /**
+     * Publish an `ordinary_push` checkpoint-bearing head that changes NO ref (the
+     * canonical map and HEAD target are carried forward). With a cutoff the head
+     * binds a fresh `retention_cutoff` ticket and roots past their ≥90-day lane
+     * may leave the map; without one it is the no-removal form (§4.5a) and every
+     * root is carried.
+     *
+     * Root expiry is PERMISSIVE: a root whose `effective_admitted_at` this client
+     * cannot resolve is RETAINED. That is deliberate — `effective_admitted_at =
+     * max(prepared_at, the admission record's storage creation time)`, and a client
+     * reading only object bytes cannot see the second term. Resolving it from
+     * `prepared_at` alone would shorten the lane, which the protocol's own
+     * delayed-PUT vector calls out as the naive implementation.
+     *
+     * This is NOT `run402 gitvault compact`: the §7.2 maintenance CYCLE (purpose
+     * `maintenance_cycle`, C1/C2 roles, stage claim sets, prune intents, `R2_cap`
+     * accounting) is a separate protocol under compact authority, and gets its own
+     * method when it ships.
+     */
+    publishCheckpoint(options?: {
+        cutoff?: GitvaultCutoffOptions | false;
+    }): Promise<GitvaultPublishResult>;
+    /** Request a `retention_cutoff` ticket and check it binds THIS base head (and the service key, when one is pinned). */
+    private issueRetentionCutoff;
+    private signHead;
+    /** Admit a signed head; on success read it back from storage and compare BEFORE any pin advances. */
+    private admit;
+    /**
+     * Publish a repair head over `base_generation` (§4.3): superseded tips that
+     * the repaired state no longer reaches enter the retention-root map with
+     * `dropped_at_generation = the repair generation`; the head carries the
+     * mandatory self-contained checkpoint. Coverage that cannot be built →
+     * `REPAIR_TARGET_UNPRESERVABLE`. A repair never crosses an admitted transition.
+     */
+    repair(input: {
+        base_generation: string;
+        reason: GitvaultRepairDescriptor["reason"];
+    }): Promise<GitvaultPublishResult>;
+    /** Heads `base..newest` (already chain-verified by `verifyToNewest`) re-read + hash-checked from storage. */
+    private chainFrom;
+    /**
+     * Pull the newest checkpoint (if any) and every later WAL pack into
+     * `targetRepoDir` (an initialized repository), then verify every canonical
+     * ref + the HEAD target resolves. Returns the materialized refs.
+     */
+    restoreObjectsInto(targetRepoDir: string): Promise<{
+        refs: GitvaultRefMap;
+        head_target: GitvaultHeadTarget;
+        generation: string;
+    }>;
+}
+/** §4.7 cross-field equality: covers_through agree; the claim set's ordered pack ids/hashes/sizes/total equal the manifest's (shared stored fields only). */
+export declare function checkClaimSetEquality(claimSet: GitvaultCheckpointClaimSet, manifest: GitvaultCheckpointManifest, headCoversThrough: string): void;
+/** Convenience for the deploy lane: the §6.5 capture binding. */
+export declare function captureBinding(captureId: string, applyPlanSha256: string | null, snapshotOidHmac: string): GitvaultCaptureBinding;
+export type { GitvaultRefUpdate };
+//# sourceMappingURL=gitvault-publication.d.ts.map