run402 4.63.1 → 4.65.0

package/sdk/dist/namespaces/gitvault.js

@@ -29,7 +29,7 @@
  * never persisted into an agent-surface result store, and never logged.
  */
 import { LocalError, isRun402Error } from "../errors.js";
-import { GITVAULT_DURABILITY_STATEMENT, GITVAULT_MIRROR_KEYSTORE_STILL_REQUIRED_STATEMENT, GITVAULT_MIRROR_VALIDITY_NOT_FRESHNESS_STATEMENT, GITVAULT_TERMINAL_LOSS_DOCTOR_TEXT, GITVAULT_TERMINAL_LOSS_STATEMENT, } from "./gitvault.crypto.js";
+import { GITVAULT_BYO_UNMIRRORED_REMEDY_STATEMENT, GITVAULT_DEGRADED_READ_STATEMENT, GITVAULT_DURABILITY_STATEMENT, GITVAULT_MIRROR_KEYSTORE_STILL_REQUIRED_STATEMENT, GITVAULT_MIRROR_VALIDITY_NOT_FRESHNESS_STATEMENT, GITVAULT_TERMINAL_LOSS_DOCTOR_TEXT, GITVAULT_TERMINAL_LOSS_STATEMENT, GITVAULT_UNMIRRORED_FINDING_STATEMENT, } from "./gitvault.crypto.js";
 /** A keystore path, or `null` when there is no id to derive it from (or it is malformed). */
 function safePath(derive, repoId) {
     if (!repoId)
@@ -53,6 +53,17 @@ async function nodeOnly(load, verb) {
 function mib(bytes) {
     return `${(bytes / (1024 * 1024)).toFixed(1)} MiB`;
 }
+/**
+ * gitvault-byo-primary-bucket task 3.3 — the number of `{key, object_kind}`
+ * entries `GITVAULT_BYO_OBJECT_MISSING`'s `details.missing` lists before
+ * truncating (`details.missing_count` always carries the true total, and
+ * `details.missing_truncated` says whether the list above was cut). A
+ * chain-referenced object list can be arbitrarily large; an error envelope
+ * is not the place to reproduce it whole. Matches the platform's existing
+ * `sample_keys`-class cap (asset-sync's plan response, `PLATFORM_INCIDENT_
+ * FANOUT_CAP`) rather than inventing a new number.
+ */
+export const GITVAULT_BYO_OBJECT_MISSING_LIST_CAP = 50;
 /**
  * D210 (rev 44) — the decision function behind `fsck`'s best-effort
  * proof-of-open submission, factored out of {@link Gitvault}'s private
@@ -117,6 +128,81 @@ export async function computeOpenProofOutcome(input) {
         };
     }
 }
+/**
+ * gitvault-byo-primary-bucket task 3.3 (design D6) — the decision function
+ * behind `fsck`'s BYO presence check, factored out of {@link Gitvault}'s
+ * private `#checkByoPresence` the same way {@link computeOpenProofOutcome}
+ * is factored out of `#submitFsckOpenProof`, so it is directly unit-testable
+ * with an injected (fake) `hasLocalConfig`/`verifyPresence`, independent of
+ * a real keystore or HTTP client. `#checkByoPresence` supplies the REAL
+ * dependencies (`readByoConfig` against the real keystore,
+ * `verifyByoObjectsPresent` against the real client) — this function
+ * contains no filesystem/HTTP code of its own.
+ *
+ * Runs AUTOMATICALLY for a `storage_profile: "byo"` vault — never behind a
+ * new flag, so a returning agent's ordinary `fsck` catches a
+ * silently-emptied bucket without having to know to ask for it. Returns
+ * `undefined` for a managed vault (`vault?.storage_profile !== "byo"` is
+ * the FIRST check, before `hasLocalConfig`/`verifyPresence` are ever
+ * called) — a managed vault pays zero extra network/filesystem work and
+ * this task changes nothing about it (design D6/D9).
+ *
+ * NO local credentials configured (`hasLocalConfig()` returns `false`) is
+ * reported, never thrown — a BYO vault this machine cannot reach is an
+ * honest "not checked", not a failure that should break `fsck` for a
+ * credential-less returning agent (see {@link GitvaultFsckByoPresence}'s
+ * own doc comment). A confirmed absence is the opposite: it THROWS
+ * `GITVAULT_BYO_OBJECT_MISSING` — the same severity class as {@link
+ * Gitvault.mirrorVerify}'s own `GITVAULT_MIRROR_NOT_CONFIGURED` throw when
+ * `--mirror` is requested against an unconfigured vault — this is exactly
+ * the honesty D6 names: "we can tell the customer what SHOULD exist and
+ * does not", stated as a real refusal rather than a silently-embedded
+ * finding. The listed entries are capped at
+ * {@link GITVAULT_BYO_OBJECT_MISSING_LIST_CAP} (a chain-referenced object
+ * list can be arbitrarily large and this is an error envelope, not a
+ * report); `missing_count` always carries the true total regardless of how
+ * many are listed.
+ *
+ * `verifyPresence()` is a pure read (HEAD checks only, via
+ * `verifyByoObjectsPresent`) — this function persists nothing itself, so
+ * it behaves identically whether `fsck` was called with `write: true` or
+ * `write: false`.
+ */
+export async function computeByoPresenceOutcome(input) {
+    if (input.vault?.storage_profile !== "byo")
+        return undefined;
+    const destination = input.vault.byo_destination ?? null;
+    if (!input.hasLocalConfig()) {
+        return {
+            verified: false,
+            destination,
+            checked_count: 0,
+            not_checked_reason: "no local BYO destination credentials are configured for this vault on this machine — presence could not be verified; configure the same destination (`run402 repos create --byo <destination>` again, or the equivalent local BYO config) to enable it",
+        };
+    }
+    const report = await input.verifyPresence();
+    if (report.missing.length > 0) {
+        const missing = report.missing.slice(0, GITVAULT_BYO_OBJECT_MISSING_LIST_CAP);
+        throw new LocalError(`the BYO destination for ${input.repoId} (${report.destination}) is missing ${report.missing.length} object(s) run402's own signed chain says should exist`, "running gitvault fsck", {
+            code: "GITVAULT_BYO_OBJECT_MISSING",
+            details: {
+                repo_id: input.repoId,
+                destination: report.destination,
+                checked_count: report.checked,
+                missing_count: report.missing.length,
+                missing,
+                missing_truncated: report.missing.length > missing.length,
+            },
+            next_actions: [
+                {
+                    action: "restore the listed object(s) to the destination bucket from your own backup, or run `run402 repos mirror <destination>` to add a second customer-held copy",
+                    why: "run402 holds no payload copy for a BYO vault — it can only tell you what SHOULD exist from the signed chain, never restore it",
+                },
+            ],
+        });
+    }
+    return { verified: true, destination: report.destination, checked_count: report.checked, not_checked_reason: null };
+}
 /**
  * {@link Gitvault.deploy}'s post-push glue: attach the best-effort
  * mirror/reconcile hooks to a deploy result, gated on whether this deploy
@@ -377,7 +463,14 @@ export class Gitvault {
         const [{ GitvaultVault, createGitvaultHttpTransport }, { GitvaultKeystore }] = await Promise.all([this.#publication(), this.#keystore()]);
         const repoId = await this.#resolveRepoId(options);
         const keystore = new GitvaultKeystore(options.keystore_root !== undefined ? { rootDir: options.keystore_root } : {});
-        const transport = createGitvaultHttpTransport(this.#client);
+        // gitvault-object-host-predial (design D1, task 1.2): this is the ONE
+        // transport whose object reads back the returned handle's vault, so
+        // wiring the origin-observation hook here (and nowhere else `open()`
+        // is reached from — `openOrCreate`'s own allocation-only transport
+        // never serves object reads) covers every read path.
+        const transport = createGitvaultHttpTransport(this.#client, {
+            onObjectStoreOriginObserved: (rid, origins) => keystore.recordObjectStoreOrigins(rid, origins),
+        });
         const vault = new GitvaultVault({
             keystore,
             transport,
@@ -526,14 +619,28 @@ export class Gitvault {
      */
     async init(options) {
         const [{ createGitvaultHttpTransport }, { GitvaultKeystore }, { createGitvault }] = await Promise.all([this.#publication(), this.#keystore(), this.#creation()]);
+        const { parseMirrorDestinationUrl, formatMirrorDestination } = await this.#mirrorConfig();
         const keystore = new GitvaultKeystore(options.keystore_root !== undefined ? { rootDir: options.keystore_root } : {});
+        const transport = createGitvaultHttpTransport(this.#client);
+        let byoWriteTarget;
+        let byoDestinationAddress;
+        if (options.byo) {
+            const destination = parseMirrorDestinationUrl(options.byo.destination_url, { region: options.byo.region, endpoint: options.byo.endpoint });
+            byoWriteTarget = { destination, ...(options.byo.credential ? { credential: options.byo.credential } : {}) };
+            byoDestinationAddress = formatMirrorDestination(destination);
+            // gitvault-byo-primary-bucket task 3.1 (design D6) — probe BEFORE any
+            // allocation request; a failed probe throws and nothing is created.
+            const { probeGitvaultByoDestination } = await this.#byoProbe();
+            await probeGitvaultByoDestination(destination, options.byo.credential);
+        }
         const created = await createGitvault({
             keystore,
-            transport: createGitvaultHttpTransport(this.#client),
+            transport,
             org_id: options.org_id,
             project_id: options.project_id,
             ...(options.client_creation_id !== undefined ? { client_creation_id: options.client_creation_id } : {}),
             ...(options.service_public_key !== undefined ? { service_public_key: options.service_public_key } : {}),
+            ...(byoWriteTarget ? { storage_profile: "byo", byo_destination: byoDestinationAddress, byo_write_target: byoWriteTarget } : {}),
         });
         let remote = null;
         if (options.scaffold_git !== false && options.repo_dir) {
@@ -545,6 +652,31 @@ export class Gitvault {
                 ...(options.remote_url !== undefined ? { remote_url: options.remote_url } : {}),
             });
         }
+        // gitvault-byo-primary-bucket task 3.1/3.5 — read back the AUTHORITATIVE
+        // storage_profile from the vault record rather than trusting what THIS
+        // call requested: an idempotent replay against a pre-existing vault
+        // (a different client_creation_id, a different machine) can legitimately
+        // resolve to a vault whose real profile disagrees with what was just
+        // asked for (`allocateVault`'s own doc comment: "a replay reads the
+        // EXISTING row's profile, never re-derives it"). Only when the SERVER
+        // confirms "byo" is the local write-credential config actually saved —
+        // never speculatively, and never when it disagrees.
+        let storageProfile = "managed";
+        let byoDestination = null;
+        if (byoWriteTarget) {
+            const record = await transport.getVaultRecord({ repo_id: created.repo_id });
+            storageProfile = record.storage_profile ?? "managed";
+            byoDestination = record.byo_destination ?? null;
+            if (storageProfile === "byo") {
+                const { saveByoConfig } = await this.#byoConfig();
+                saveByoConfig(keystore, { repo_id: created.repo_id, destination: byoWriteTarget.destination, ...(byoWriteTarget.credential ? { credential: byoWriteTarget.credential } : {}) });
+            }
+            // storageProfile !== "byo" here means this project's vault already
+            // existed as a MANAGED vault under a different creation attempt —
+            // nothing is saved locally, and the result below reports the TRUE
+            // profile so the caller can tell the user honestly rather than
+            // silently writing a bogus BYO config for a managed vault.
+        }
         return {
             repo_id: created.repo_id,
             project_id: options.project_id,
@@ -553,6 +685,8 @@ export class Gitvault {
             remote,
             deduplicated: created.how === "reconciled",
             terminal_loss_statement: GITVAULT_TERMINAL_LOSS_STATEMENT,
+            storage_profile: storageProfile,
+            byo_destination: byoDestination,
         };
     }
     /**
@@ -966,12 +1100,16 @@ export class Gitvault {
         // above (already returned/committed) — a mirror failure is a named
         // pending finding reported BESIDE the vault result, on its own field.
         const mirrorPush = await this.#tryMirrorPush(handle.repo_id, handle.keystore);
+        // gitvault-byo-primary-bucket task 3.3 — the SAME non-blocking contract,
+        // fired right beside the mirror hook (skipped_no_mirror with no network
+        // call for any managed vault or any machine with no local BYO config).
+        const byoChainCopy = await this.#tryByoChainCopyPush(handle.repo_id, handle.keystore);
         // Deploy-time reconcile hook: fires on every successful push,
         // best-effort — a reconcile failure (including a read-only principal
         // with no signing key) is reported BESIDE the vault result, never a
         // `push()` throw, same non-blocking contract as the mirror hook above.
         const reconcileRecipients = await this.#tryReconcileEnvelopeRecipients(handle.vault);
-        return { ...result, snapshot, gitvault_commit: snapshot.oid, gitvault_commit_line: line, mirror_push: mirrorPush, reconcile_recipients: reconcileRecipients };
+        return { ...result, snapshot, gitvault_commit: snapshot.oid, gitvault_commit_line: line, mirror_push: mirrorPush, byo_chain_copy: byoChainCopy, reconcile_recipients: reconcileRecipients };
     }
     /** Best-effort dual-push: catches EVERYTHING, including the lazy module import itself, so a mirror problem can never surface as a `push()` throw. */
     /**
@@ -1020,6 +1158,23 @@ export class Gitvault {
             return { attempted: false, outcome: "skipped_no_mirror", error: e instanceof Error ? e.message : String(e) };
         }
     }
+    /**
+     * gitvault-byo-primary-bucket task 3.3 — the chain's every-push dual-write
+     * into a BYO vault's own destination, mirroring {@link #tryMirrorPush}'s
+     * exact contract byte-for-byte (best-effort, catches EVERYTHING, never
+     * throws, never alters the vault outcome already committed above — a
+     * chain-copy failure is a named pending finding reported BESIDE the vault
+     * result on its own field, never a `push()`/`deploy()` throw).
+     */
+    async #tryByoChainCopyPush(repoId, keystore) {
+        try {
+            const { byoChainCopyPushForGeneration } = await this.#mirror();
+            return await byoChainCopyPushForGeneration(this.#client, repoId, { keystore });
+        }
+        catch (e) {
+            return { attempted: false, outcome: "skipped_no_mirror", error: e instanceof Error ? e.message : String(e) };
+        }
+    }
     /** Best-effort envelope-recipient reconcile: catches EVERYTHING so a reconcile problem can never surface as a `push()` throw (mirrors {@link #tryMirrorPush}'s contract exactly). */
     async #tryReconcileEnvelopeRecipients(vault) {
         try {
@@ -1657,6 +1812,14 @@ export class Gitvault {
      * to 7, `GITVAULT_EPOCH_NOT_OPENABLE` at epoch 2/rotation …") is exactly
      * what this split makes representable. `refs`/`head_target`/
      * `pin_after.highest_materialized` all reflect `decryptable_to_generation`.
+     *
+     * **gitvault-byo-primary-bucket task 3.3 (design D6).** For a
+     * `storage_profile: "byo"` vault, `fsck` ALSO adjudicates the customer's
+     * own bucket against run402's signed chain — see {@link
+     * #checkByoPresence} for the full contract (automatic, never a flag;
+     * fails soft with no local credentials; throws
+     * `GITVAULT_BYO_OBJECT_MISSING` on a confirmed absence). A managed vault
+     * is byte-identical to before this task.
      */
     async fsck(options = {}) {
         const before = await this.status(options);
@@ -1701,6 +1864,14 @@ export class Gitvault {
             chain_verified_to_generation: state.generation,
             decryptable_to_generation: decryptableToGeneration,
         });
+        // gitvault-byo-primary-bucket task 3.3 (design D6) — LAST, deliberately:
+        // everything above (chain verify + its pin persist, retained-refs
+        // reconcile, open-proof submission) is real, valid work regardless of
+        // what the customer's own bucket holds — the signed chain is run402-
+        // authoritative either way (design D9) — so a missing-object refusal
+        // below must never cost any of it. See `#checkByoPresence`'s own doc
+        // comment for the throw/no-throw split.
+        const byoPresence = await this.#checkByoPresence(before.vault, repoId, handle.keystore);
         return {
             repo_id: repoId,
             write,
@@ -1717,6 +1888,7 @@ export class Gitvault {
             mirror,
             retained_refs: retainedRefs,
             open_proof: openProof,
+            ...(byoPresence !== undefined ? { byo_presence: byoPresence } : {}),
         };
     }
     /**
@@ -1749,6 +1921,28 @@ export class Gitvault {
             }),
         });
     }
+    /**
+     * gitvault-byo-primary-bucket task 3.3 (design D6) — `repos fsck`'s
+     * wiring of the shipped read-half primitive
+     * {@link import("../node/gitvault-mirror.js").verifyByoObjectsPresent}.
+     * Thin wrapper over {@link computeByoPresenceOutcome} (the testable
+     * decision function, factored out the same way {@link
+     * computeOpenProofOutcome} is factored out of `#submitFsckOpenProof`)
+     * supplying THIS instance's real `hasLocalConfig`/`verifyPresence`
+     * dependencies (`readByoConfig` against the real keystore,
+     * `verifyByoObjectsPresent` against the real HTTP client). See that
+     * function's own doc comment for the full gating/throw contract.
+     */
+    async #checkByoPresence(vault, repoId, keystore) {
+        const { readByoConfig } = await this.#byoConfig();
+        const { verifyByoObjectsPresent } = await this.#mirror();
+        return computeByoPresenceOutcome({
+            repoId,
+            vault,
+            hasLocalConfig: () => readByoConfig(keystore, repoId) !== null,
+            verifyPresence: () => verifyByoObjectsPresent(this.#client, repoId, { keystore }),
+        });
+    }
     /**
      * Wrap this vault's current epoch key to every org member who has
      * published an encryption key but has no `key_envelope` on this vault yet
@@ -2001,7 +2195,15 @@ export class Gitvault {
         // failure in a log line that assumed ordering. Extracted to a standalone
         // function so the outcome-gating is unit-testable with fake thunks,
         // without standing up a live vault — see gitvault-deploy-hooks.test.ts.
-        return attachGitvaultDeployHooks(result, () => this.#tryMirrorPush(handle.repo_id, handle.keystore), () => this.#tryReconcileEnvelopeRecipients(handle.vault));
+        const hooked = await attachGitvaultDeployHooks(result, () => this.#tryMirrorPush(handle.repo_id, handle.keystore), () => this.#tryReconcileEnvelopeRecipients(handle.vault));
+        // gitvault-byo-primary-bucket task 3.3 — composed AFTER, not inside,
+        // `attachGitvaultDeployHooks` (kept untouched so its own unit-tested
+        // outcome-gating contract stays byte-for-byte): the SAME "did this
+        // deploy actually land a generation" gate `mirror_push`'s presence
+        // already encodes, so no new outcome-inspection logic here.
+        if (hooked.mirror_push === undefined)
+            return hooked;
+        return { ...hooked, byo_chain_copy: await this.#tryByoChainCopyPush(handle.repo_id, handle.keystore) };
     }
     /**
      * Drain every unvaulted-override journal on this machine: push the exact
@@ -2023,6 +2225,35 @@ export class Gitvault {
         const out = await handle.vault.restoreObjectsInto(options.target_dir);
         return { refs: out.refs, generation: out.generation, retained_refs: out.retained_refs };
     }
+    // ── degraded read (gitvault-byo-primary-bucket, design D4, task 3.4 — mirror half) ──
+    /**
+     * Wrap an ALREADY-RESOLVED vault read with degraded-read fallback: run
+     * `options.attemptLive` (the caller's own live call — its
+     * `vault.materialize()` for a `list`-shaped read, or
+     * `vault.restoreObjectsInto(dir)` for a `fetch`-shaped one), and on a
+     * network-class failure (never on an authorization refusal or any other
+     * 4xx — see `isNetworkClassGitvaultReadError`), fall back to the vault's
+     * configured mirror via the SAME `r402s-recover` engine `recover()` uses.
+     *
+     * Deliberately takes an already-open `vault`/`keystore`/`repo_id` rather
+     * than resolving them itself: named-address resolution (slug-form vs.
+     * id-form), stale-pin recovery, and cross-command vault-instance reuse
+     * within one `git-remote-run402` session are CLI-layer concerns that
+     * already live in `cli/lib/remote-helper-session.mjs` — this method owns
+     * only the trigger discipline and the fallback engine, never vault
+     * resolution, so it composes with that existing flow instead of
+     * duplicating it.
+     *
+     * `out_dir` is REQUIRED for the fallback to ever run — pass the resolved,
+     * git-proven repository directory (`resolveGitInvocationRepo`'s own
+     * `repo_dir`, never a guess from `cwd`). `null` (no resolvable repository,
+     * e.g. a bare `git ls-remote` outside any checkout) disables the fallback
+     * entirely: the original gateway error surfaces exactly as it always did.
+     */
+    async withDegradedRead(options) {
+        const { tryGitvaultDegradedRead } = await this.#degradedRead();
+        return tryGitvaultDegradedRead(options);
+    }
     // ── mirror (gitvault-mirror-and-recover, design D1/D2/D7) ─────────────────
     /**
      * Configure (or replace) the customer-owned mirror destination for one
@@ -2060,8 +2291,19 @@ export class Gitvault {
         const keystore = new GitvaultKeystore(options.keystore_root !== undefined ? { rootDir: options.keystore_root } : {});
         const config = readMirrorConfig(keystore, repoId);
         const base = { repo_id: repoId, validity_not_freshness: GITVAULT_MIRROR_VALIDITY_NOT_FRESHNESS_STATEMENT, keystore_still_required: GITVAULT_MIRROR_KEYSTORE_STILL_REQUIRED_STATEMENT };
+        const lastSuccessAt = config?.last_success_at ?? null;
         if (!config) {
-            return { ...base, configured: false, destination: null, credential_kind: null, mirrored_generation: null, newest_generation: null, is_current: null, closing_command: null };
+            // gitvault-mirror-default: the unconfigured branch stays gateway-blind
+            // by construction — it returns before ANY network call, finding included.
+            // `options.is_byo` is a caller-supplied hint (gitvault-byo-primary-bucket
+            // task 3.5) — NEVER derived here, which is what keeps this branch
+            // network-call-free; `repos view` already has `storage_profile` from
+            // its own `status()` read and passes it in.
+            return {
+                ...base, configured: false, destination: null, credential_kind: null, mirrored_generation: null, newest_generation: null, is_current: null, closing_command: null,
+                last_success_at: lastSuccessAt,
+                finding: gitvaultUnmirroredFinding({ configured: false, last_success_at: lastSuccessAt, mirrored_generation: null, is_byo: options.is_byo }),
+            };
         }
         let mirroredGeneration = null;
         try {
@@ -2084,6 +2326,8 @@ export class Gitvault {
             ...base, configured: true, destination: formatMirrorDestination(config.destination), credential_kind: config.credential?.kind ?? null,
             mirrored_generation: mirroredGeneration, newest_generation: newestGeneration, is_current: isCurrent,
             closing_command: isCurrent === false ? "run402 repos mirror --backfill" : null,
+            last_success_at: lastSuccessAt,
+            finding: gitvaultUnmirroredFinding({ configured: true, last_success_at: lastSuccessAt, mirrored_generation: mirroredGeneration, is_byo: options.is_byo }),
         };
     }
     /** List the vault's stored objects, diff against the mirror, fetch + hash-verify + write what's missing, in admission order. Resumable and idempotent. */
@@ -2202,6 +2446,15 @@ export class Gitvault {
     #recovery() {
         return nodeOnly(() => import("../node/gitvault-recover.js"), "recover");
     }
+    #degradedRead() {
+        return nodeOnly(() => import("../node/gitvault-degraded-read.js"), "list");
+    }
+    #byoConfig() {
+        return nodeOnly(() => import("../node/gitvault-byo-config.js"), "init");
+    }
+    #byoProbe() {
+        return nodeOnly(() => import("../node/gitvault-byo-probe.js"), "init");
+    }
 }
 // ─── D7 — progressive terminal-loss warning (repo-first-onramp task 2.7) ────
 //
@@ -2331,6 +2584,37 @@ export function gitvaultKeystoreBackupReminderMessage(trip, coveringRecipients)
     return (`this vault has accrued real value at risk (${reasons.join(", ")}), but it is covered by ${coveringRecipients} recipients today — not the single-principal case. ` +
         `${GITVAULT_DURABILITY_STATEMENT} Back up this machine's keystore anyway: losing it does not lose the vault, but it does lose YOUR access to it.`);
 }
+/**
+ * gitvault-mirror-default — the pure `vault_unmirrored` computation, in ONE
+ * place so doctor and `repos view` echo the same finding instead of each
+ * deriving their own (the loss-warning pattern above). Present when no mirror
+ * is configured, OR when one is configured but has no success evidence yet —
+ * either the local `last_success_at` stamp (survives a transiently unreachable
+ * mirror) or a chain-verified `mirrored_generation` read from the mirror
+ * itself (covers mirrors synced before the stamp existed). Informational,
+ * never blocking; every input is client-local or read from the CUSTOMER'S
+ * mirror — nothing here touches the gateway.
+ */
+export function gitvaultUnmirroredFinding(state) {
+    if (state.configured && (state.last_success_at !== null || state.mirrored_generation !== null))
+        return null;
+    return {
+        kind: "vault_unmirrored",
+        message: state.is_byo ? GITVAULT_BYO_UNMIRRORED_REMEDY_STATEMENT : GITVAULT_UNMIRRORED_FINDING_STATEMENT,
+        setup_command: state.configured ? "run402 repos mirror --backfill" : "run402 repos mirror <destination>",
+    };
+}
+/**
+ * gitvault-byo-primary-bucket (design D4) — the ONE stderr line a degraded
+ * chain/payload read prints: the fallback's own destination (never a
+ * credential) plus the canonical, mechanism-only statement. `list`/`fetch`
+ * degrading in the SAME `git-remote-run402` session each print their own
+ * line (one per degraded READ, not one per session) — see
+ * `Gitvault.withDegradedRead`'s own doc comment.
+ */
+export function gitvaultDegradedReadNote(source) {
+    return `degraded read from ${source.destination}: ${GITVAULT_DEGRADED_READ_STATEMENT}`;
+}
 /** `run402::<org_id>/<project_id>` — what `git-remote-run402` resolves. */
 export function gitvaultRemoteUrl(orgId, projectId) {
     return `run402::${orgId}/${projectId}`;