@run402/sdk 4.61.1 → 4.62.1

package/dist/node/gitvault-publication.js

@@ -1101,6 +1101,11 @@ export function createGitvaultHttpTransport(client, options = {}) {
         },
         getVaultRecord: ({ repo_id }) => client.request(base(repo_id), { context: "reading the gitvault record" }),
         getState: ({ repo_id, since }) => getVaultStateOut(repo_id, since),
+        openCompactionGrant: ({ repo_id }) => client.request(`${base(repo_id)}/compaction-grant`, { method: "POST", context: "opening the gitvault compaction headroom grant" }),
+        closeCompactionGrant: async ({ repo_id }) => {
+            const r = await client.request(`${base(repo_id)}/compaction-grant`, { method: "DELETE", context: "closing the gitvault compaction headroom grant" });
+            return { closed: r.closed === true };
+        },
         findVaultByProject: ({ project_id }) => client.request(`/gitvault/v1/vaults?project_id=${encodeURIComponent(project_id)}`, { context: "resolving the project's gitvault" }),
         findVaultByRepo: ({ org_slug, repo_name }) => client.request(`/gitvault/v1/vaults?repo=${encodeURIComponent(`${org_slug}/${repo_name}`)}`, { context: "resolving the gitvault by repo address" }),
         listOrgEncryptionKeys: ({ org_id }) => client.request(`/orgs/v1/${encodeURIComponent(org_id)}/encryption-keys`, { context: "reading the org encryption-key directory" }),
@@ -1165,8 +1170,33 @@ export function createGitvaultHttpTransport(client, options = {}) {
                 parsed = null;
             }
             if (!r.ok) {
+                // kychee-com/run402#578 fix 1: the gateway's error envelope is FLAT
+                // (docs/style.md §Errors — `buildErrorEnvelope` in the gateway) —
+                // `code`, `message`, `details`, `trace_id`, and `next_actions` all
+                // ride at the TOP level, never nested under an `error` object (that
+                // key is a human-readable STRING alias for `message`, kept only for
+                // legacy consumers). Reading `envelope.error.code` here — as if the
+                // envelope were `{error: {code, message, details}}` — always missed,
+                // so EVERY refusal (receipt-id reuse, the retention floor,
+                // GC_EPOCH_STALE, …) collapsed to the same opaque
+                // `GITVAULT_PRUNE_SUBMIT_FAILED {details: null}`. Read the real
+                // shape so the gateway's own refusal rides through verbatim; this
+                // wrapper only adds the HTTP status, never replaces content.
                 const envelope = parsed;
-                fail(envelope?.error?.code ?? "GITVAULT_PRUNE_SUBMIT_FAILED", envelope?.error?.message ?? `prune intent submission failed (HTTP ${r.status})`, "submitting the gitvault prune intent", { status: r.status, details: envelope?.error?.details ?? null });
+                // Spread the gateway's own `details` verbatim (its keys survive
+                // untouched — `ineligible`, `expires_at`, whatever the refusal
+                // carries) and add `http_status`/`trace_id` alongside as this
+                // wrapper's own context, never replacing what the gateway sent.
+                const gatewayDetails = envelope?.details;
+                const details = gatewayDetails && typeof gatewayDetails === "object" && !Array.isArray(gatewayDetails)
+                    ? { ...gatewayDetails }
+                    : gatewayDetails !== undefined
+                        ? { gateway_details: gatewayDetails }
+                        : {};
+                details.http_status = r.status;
+                if (envelope?.trace_id)
+                    details.trace_id = envelope.trace_id;
+                fail(envelope?.code ?? "GITVAULT_PRUNE_SUBMIT_FAILED", envelope?.message ?? (typeof envelope?.error === "string" ? envelope.error : undefined) ?? `prune intent submission failed (HTTP ${r.status})`, "submitting the gitvault prune intent", details, Array.isArray(envelope?.next_actions) ? envelope.next_actions : undefined);
             }
             const body = (parsed ?? {});
             return { ...body, stored: body.stored === true };
@@ -1318,6 +1348,35 @@ async function writeGitvaultRestoreMarker(targetRepoDir, generation, headSha256)
     await hardenedGit(targetRepoDir, ["config", "--local", GITVAULT_RESTORE_MARKER_GENERATION_KEY, generation]);
     await hardenedGit(targetRepoDir, ["config", "--local", GITVAULT_RESTORE_MARKER_SHA256_KEY, headSha256]);
 }
+// ─── auto-gc cadence threshold (gitvault-checkpoint-cadence design D1) ───────
+//
+// `auto_gc_generations` rides the SAME local-git-config mechanism as the
+// restore marker above — a per-CHECKOUT knob, exactly like git's own
+// `gc.auto` (`git config gc.auto`), not a server-side vault policy. Read
+// fresh every push (a cheap local read, never network); `0` disables;
+// absent reads as the default.
+const GITVAULT_AUTO_GC_GENERATIONS_KEY = "r402.autoGcGenerations";
+/** Default `auto_gc_generations` — see the change proposal's rationale (≈2-3s over the fresh-checkpoint floor at this backlog, a busy repo compacts roughly once per few dozen pushes). */
+export const GITVAULT_AUTO_GC_GENERATIONS_DEFAULT = 32;
+/**
+ * Read this checkout's auto-gc threshold, or the default when unset or
+ * unparseable. Never throws — a corrupt local config value degrades to the
+ * default rather than blocking a push's own auto-gc check.
+ */
+export async function readGitvaultAutoGcThreshold(targetRepoDir) {
+    const raw = await readLocalGitConfigValue(targetRepoDir, GITVAULT_AUTO_GC_GENERATIONS_KEY);
+    if (raw === null)
+        return GITVAULT_AUTO_GC_GENERATIONS_DEFAULT;
+    const trimmed = raw.trim();
+    if (!/^\d+$/.test(trimmed))
+        return GITVAULT_AUTO_GC_GENERATIONS_DEFAULT;
+    const n = Number.parseInt(trimmed, 10);
+    return Number.isSafeInteger(n) && n >= 0 ? n : GITVAULT_AUTO_GC_GENERATIONS_DEFAULT;
+}
+/** Set this checkout's auto-gc threshold. `0` disables auto-gc entirely. */
+export async function writeGitvaultAutoGcThreshold(targetRepoDir, generations) {
+    await hardenedGit(targetRepoDir, ["config", "--local", GITVAULT_AUTO_GC_GENERATIONS_KEY, String(generations)]);
+}
 /** A transport-agnostic view of git ops the publication needs (the local repository). */
 export class GitvaultVault {
     keystore;
@@ -3578,13 +3637,28 @@ export class GitvaultVault {
      * verification and retained-refs reconciliation run UNCHANGED on both
      * paths; the marker only advances after they both succeed.
      */
-    async restoreObjectsInto(targetRepoDir) {
+    async restoreObjectsInto(targetRepoDir, reuse) {
         // gitvault-delta-fetch: the marker is read BEFORE materialize so the
         // state read can carry THIS git dir's applied position as `since` —
         // see tryStateFastPath's own comment on why the pin is the wrong
         // position for a standing clone.
+        //
+        // gitvault-session-state-reuse: `reuse` lets a caller that ALREADY
+        // materialized state for this same target directory — using the SAME
+        // marker `since` this method would itself read — hand that response
+        // in directly, skipping this method's own state read entirely (the
+        // remote-helper session's `list` phase is the caller: see `runFetch`
+        // in `cli/lib/remote-helper-session.mjs`). The marker below is read
+        // regardless (a cheap local `git config` read, never a network call)
+        // and compared against `reuse.marker`: only an EXACT match (both
+        // `null`, or both present with equal `generation`/`head_sha256`) is
+        // trusted — any mismatch (a different push admitted in this same
+        // session, a stale handoff) falls through to this method's own
+        // `materialize()` exactly as if `reuse` had never been passed. A wrong
+        // reuse therefore costs one extra read, never a wrong result.
         const marker = await readGitvaultRestoreMarker(targetRepoDir);
-        const newest = await this.materialize({ ...(marker ? { deltaSince: marker.generation } : {}) });
+        const markerMatches = (a, b) => a === null ? b === null : b !== null && a.generation === b.generation && a.head_sha256 === b.head_sha256;
+        const newest = reuse && markerMatches(reuse.marker, marker) ? reuse.state : await this.materialize({ ...(marker ? { deltaSince: marker.generation } : {}) });
         if (!newest.head) {
             const retained_refs = await reconcileRetainedTipRefs(targetRepoDir, { refs: {}, roots: [], head_target: newest.head_target });
             return { refs: {}, head_target: newest.head_target, generation: newest.generation, retained_refs };
@@ -3844,6 +3918,15 @@ export class GitvaultVault {
         await writeGitvaultRestoreMarker(targetRepoDir, newest.generation, newest.head_sha256);
         return { refs: newest.refs, head_target: newest.head_target, generation: newest.generation, retained_refs };
     }
+    // ── compaction headroom grant (gitvault-checkpoint-cadence design D3) ──
+    /** Thin passthrough to the transport — see {@link GitvaultTransport.openCompactionGrant}. */
+    async openCompactionGrant() {
+        return this.transport.openCompactionGrant({ repo_id: this.repoId });
+    }
+    /** Thin passthrough to the transport — see {@link GitvaultTransport.closeCompactionGrant}. Always safe best-effort; never throws by construction of the route (idempotent). */
+    async closeCompactionGrant() {
+        return this.transport.closeCompactionGrant({ repo_id: this.repoId });
+    }
 }
 /** §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 function checkClaimSetEquality(claimSet, manifest, headCoversThrough) {