run402 4.68.3 → 4.69.0

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

@@ -277,9 +277,15 @@ export declare function checkChainLink(input: GitvaultChainLinkInput): void;
  * rotation is ACTIVATED") — `checkChainLink`'s own D194 epoch-continuity
  * check already validates its structural admissibility, and
  * {@link parseRotateEpochPayload} / the caller's own envelope-open step
- * (`GitvaultVault.verifyToNewest`) handle it fully. The other three kinds
- * (`add_envelope`, `add_writer_key`, `transfer_binding`) remain genuinely
- * unactivated and stay fail-closed exactly as before.
+ * (`GitvaultVault.verifyToNewest`) handle it fully. `add_writer_key` is
+ * EXEMPT as of rev 47 (gitvault-multi-writer) the same way — {@link
+ * parseAddWriterKeyPayload} + `validateAddWriterKeyPayload`
+ * (`gitvault-writer-state.js`) handle it fully, INSIDE `verifyToNewest`'s
+ * own loop, BEFORE this function ever runs on that head (so a transition
+ * that fails writer validation never reaches here at all — this function
+ * only ever sees ones that already passed). The other two kinds
+ * (`add_envelope`, `transfer_binding`) remain genuinely unactivated and stay
+ * fail-closed exactly as before.
  */
 export declare function assertNoTransition(head: GitvaultHead): void;
 /** One object to upload — identity fixed BEFORE the PUT; the receipt is compared against it. */
@@ -439,8 +445,7 @@ export interface GitvaultCompactionGrant {
      * client-declared. NOTE the byte fields arrive as STRINGS on the wire (the
      * gateway serializes Postgres BIGINTs as strings, verified live) — consumers
      * MUST `Number(...)` before arithmetic; `Number.isFinite` on the raw value
-     * is false and silently discards the grant (the bug the live acceptance
-     * run caught on 2026-08-31).
+     * is false and silently discards the grant.
      */
     granted_bytes: number | string;
     expires_at: string;
@@ -799,8 +804,8 @@ export interface GitvaultTransport extends GitvaultCreationTransport {
  *
  * The gateway route (`GET /orgs/v1/:org_id/encryption-keys`, `routes/org.ts`
  * in run402-private) returns `public_key` on every row — the raw key
- * material is what makes the directory usable for wrapping at all
- * (deployed 2026-08-26). The field stays OPTIONAL in this wire type the
+ * material is what makes the directory usable for wrapping at all.
+ * The field stays OPTIONAL in this wire type the
  * same way `desired[]` does on {@link GitvaultEnvelopeRecipientsResponse}:
  * a response is network data, and an older/rolling-deploy gateway that
  * omits the field must degrade to a per-entry `skipped` report
@@ -815,6 +820,16 @@ export interface GitvaultOrgEncryptionKeyEntry {
     created_at: string;
     /** Raw base64url X25519 public key. Present on every current-gateway row; tolerated as absent (per-entry `missing_public_key` skip) for wire robustness only. */
     public_key?: string;
+    /**
+     * gitvault-multi-writer (rev 47) D9 — the SAME row's vault-WRITER signing
+     * half (`routes/org.ts` in run402-private, deployed alongside `public_key`
+     * D9). Raw base64url Ed25519 public key; `null` when this principal has
+     * never published a signing half (a pre-rev47 or encryption-only
+     * enrollment), absent entirely on an older gateway that predates D9.
+     */
+    signing_pubkey?: string | null;
+    signing_fingerprint?: string | null;
+    signing_possession_verified_at?: string | null;
     [key: string]: unknown;
 }
 /** `GET /orgs/v1/:org_id/encryption-keys` — {@link GitvaultTransport.listOrgEncryptionKeys}'s result. */
@@ -905,11 +920,79 @@ export interface GitvaultVaultRecord {
         } | null;
         pending_repair_attempt_id: string | null;
     };
+    /**
+     * gitvault-multi-writer (rev 47) task 3.7 — the writer chain state's read
+     * surface, mirrored client-side from the gateway's `VaultRecord` (see
+     * `services/gitvault/reads.ts` in run402-private for the authoritative doc
+     * comment). `writer_set` is the on-chain-recognized set exactly as the
+     * chain itself would verify (regardless of any gateway-only block — that's
+     * `ineligible_members`). `pending_writers` is the reverse direction:
+     * active org members at role developer+ with a published,
+     * possession-verified signing key who are NOT yet in `writer_set.writers`
+     * — candidates for the "writer"-door `add_writer_key` (task 5.7's
+     * `reconcile()`). `ineligible_members` is a chain-recognized active writer
+     * the gateway has flagged for removal, still active on-chain pending the
+     * next `rotate_epoch{writer_set_update}`.
+     */
+    writer_set?: {
+        version: string;
+        sha256: string | null;
+        writers: GitvaultVaultWriterSetEntry[];
+    };
+    pending_writers?: GitvaultVaultPendingWriter[];
+    ineligible_members?: GitvaultVaultIneligibleMember[];
+    /** `gitvault_vaults.read_only_terminal_at IS NOT NULL` — the D228 forced sole-writer-removal terminal state: no further writer-authenticated push is admissible. Absent (never `undefined`-checked as `true`) on an older gateway — treat as `false`. */
+    read_only_terminal?: boolean;
+    /**
+     * gitvault-multi-writer (rev 47) D6/D227, task 5.9 — decimal-string
+     * uint64 counter, bumped by the gateway every time a membership/role/key
+     * change gateway-blocks one or more writer keys. A client building a
+     * `writer_set_update` freezes THIS value into `rotation_attempt_
+     * descriptor.writer_revocation_version` at its own admission fence —
+     * there is no writer-side "declare" round-trip (unlike the encryption
+     * side's `declareRecipientKeyRevoked`), so this read is the only source.
+     * Absent on an older gateway that predates this field.
+     */
+    writer_revocation_version?: string;
     warnings: {
         kind: string;
         message: string;
     }[];
     created_at: string | null;
+    /**
+     * The control plane's SIGNED allocation record for the vault (present on
+     * gateways that wrap it into the vault read; `null`/absent otherwise).
+     * gitvault-agent-envelopes D4: a cold open compares genesis's creator
+     * fingerprints against these — platform-attested consistency, never
+     * independent authentication (the platform serves both sides).
+     */
+    allocation?: {
+        creator_signing_fingerprint: string;
+        creator_encryption_fingerprint: string;
+        status?: string;
+        service_key_id?: string;
+        [key: string]: unknown;
+    } | null;
+}
+/** One chain-recognized active writer on {@link GitvaultVaultRecord.writer_set} — the on-chain shape only; `gateway_blocked_at` (gateway-only) rides {@link GitvaultVaultIneligibleMember} instead. */
+export interface GitvaultVaultWriterSetEntry {
+    writer_key_id: string;
+    principal_id: string;
+    authorization_kind: "writer" | "handoff";
+    admitted_generation: string;
+    admitted_head_sha256: string;
+}
+/** An org member eligible to become a writer (active membership at role developer+, a published possession-verified signing key) who is NOT yet in {@link GitvaultVaultRecord.writer_set}'s `writers` — a candidate for the "writer"-door `add_writer_key` ({@link GitvaultVault.reconcileWriterAdmissions}). */
+export interface GitvaultVaultPendingWriter {
+    principal_id: string;
+    writer_key_id: string;
+}
+/** A chain-recognized active writer the gateway has flagged for removal — still active on-chain, pending the next `rotate_epoch{writer_set_update}`. */
+export interface GitvaultVaultIneligibleMember {
+    principal_id: string;
+    writer_key_id: string;
+    gateway_blocked_at: string | null;
+    reason: "membership_revoked" | "role_below_developer" | "encryption_key_revoked" | "gateway_blocked_pending_removal";
 }
 /**
  * {@link GitvaultTransport.getState}'s result — the SAME bytes the per-object
@@ -1080,6 +1163,26 @@ export declare const GITVAULT_AUTO_GC_GENERATIONS_DEFAULT = 32;
 export declare function readGitvaultAutoGcThreshold(targetRepoDir: string): Promise<number>;
 /** Set this checkout's auto-gc threshold. `0` disables auto-gc entirely. */
 export declare function writeGitvaultAutoGcThreshold(targetRepoDir: string, generations: number): Promise<void>;
+/**
+ * {@link GitvaultVault.ensureRepoState}'s report when a cold keystore was
+ * restored from its own envelope (gitvault-agent-envelopes D4). `trust` is
+ * `receipt` only when a creator-held recovery receipt pinned genesis;
+ * `platform_attested` means the control plane's signed allocation matched —
+ * consistency the platform itself vouches for, so `independently_verified`
+ * is `false` there and this label must never be read as end-to-end
+ * authentication. `continuity` is `pinned` when this keystore had already
+ * seen this genesis (a later open), `first_seen` on the first.
+ */
+export interface GitvaultColdOpenResult {
+    repo_id: string;
+    org_id: string;
+    provenance: "restored_from_envelope";
+    trust: "receipt" | "platform_attested" | "unauthenticated_salvage";
+    continuity: "first_seen" | "pinned";
+    independently_verified: boolean;
+    epoch: string;
+    recipient_fingerprint: string;
+}
 export interface GitvaultVaultOptions {
     keystore: GitvaultKeystore;
     transport: GitvaultTransport;
@@ -1092,6 +1195,15 @@ export interface GitvaultVaultOptions {
     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;
+    /**
+     * Consult round 2 §5: an ordinary open REFUSES a cold restore whose genesis
+     * the control plane cannot attest (no signed allocation on the vault
+     * record) — a data-path that cannot forge the allocation could otherwise
+     * simply omit it and hand the client a fabricated vault. Only the explicit
+     * recovery flow sets this, and the result still says
+     * `unauthenticated_salvage`.
+     */
+    allow_unauthenticated_salvage?: boolean;
 }
 /** How a checkpoint-bearing head binds a `retention_cutoff` ticket and expires roots (§4.5a / §4.5). */
 export interface GitvaultCutoffOptions {
@@ -1110,6 +1222,19 @@ export interface GitvaultEncounteredRotation {
     /** == `payload.new_epoch` == the head's own `epoch`. */
     epoch: string;
     payload: GitvaultRotateEpochPayload;
+    /**
+     * gitvault-multi-writer rev 47 — the writer who actually signed THIS
+     * rotation head (already resolved + signature-verified by the forward
+     * chain walk at the point this was collected — never the vault's fixed
+     * genesis creator in a multi-writer vault). Optional: the BACKWARD
+     * catch-up walk in `verifyToNewest` (decrypt-lag recovery) does not yet
+     * resolve this for a rotation it discovers walking `prev_sha256`
+     * backward from `lastHead` — a documented, narrower remaining gap
+     * distinct from the forward walk's own full fix; `openEpochRotationForRecipient`
+     * falls back to the vault's genesis-creator key when absent, byte-identical
+     * to this field's pre-rev-47 non-existence.
+     */
+    signing_pubkey?: string;
 }
 /** Named detail for a reader's own `GITVAULT_EPOCH_NOT_OPENABLE` / decrypt stop point (Part C: `repos fsck`'s honest `chain_verified_to` vs `decryptable_to` split). */
 export interface GitvaultEpochDecryptFailure {
@@ -1185,6 +1310,51 @@ export interface GitvaultReconcileEnvelopeRecipientsResult {
     /** Directory entries this call could not (or, for `pinned_key_mismatch`, would not) wrap. */
     skipped: GitvaultReconcileEnvelopeRecipientsSkipped[];
 }
+/** One `pending_writers[]` entry {@link GitvaultVault.reconcileWriterAdmissions} admitted via a fresh `add_writer_key{"writer"}` head. */
+export interface GitvaultReconcileWriterAdmissionsAdmitted {
+    principal_id: string;
+    writer_key_id: string;
+    generation: string;
+}
+/** Why {@link GitvaultVault.reconcileWriterAdmissions} did NOT admit a `pending_writers[]` entry it otherwise would have. */
+export type GitvaultReconcileWriterAdmissionsSkipReason = "missing_signing_pubkey" | "invalid_signing_pubkey";
+export interface GitvaultReconcileWriterAdmissionsSkipped {
+    principal_id: string;
+    writer_key_id: string;
+    reason: GitvaultReconcileWriterAdmissionsSkipReason;
+}
+/**
+ * {@link GitvaultVault.reconcileWriterAdmissions}'s full per-candidate
+ * breakdown (task 5.7). Structurally parallel to
+ * {@link GitvaultReconcileEnvelopeRecipientsResult} (same repo/wrapped-or-
+ * admitted/already-covered/skipped shape), but this reconcile submits a REAL
+ * chain head per admission (one `add_writer_key{"writer"}` transition per
+ * candidate — the protocol allows only one added writer per head) rather
+ * than an out-of-band object upload, so it is never fully parallel: each
+ * admission materializes fresh against the PRIOR admission's own updated
+ * writer set.
+ */
+export interface GitvaultReconcileWriterAdmissionsResult {
+    repo_id: string;
+    org_id: string;
+    /**
+     * `false` exactly when THIS session's own key is not (or is no longer) an
+     * active writer — the "writer" door's authorization is the carrying
+     * head's own signer, so an ineligible session cannot admit anyone, and
+     * this call returns immediately with every other field empty. Distinct
+     * from a genuinely empty `pending_writers[]` (still `eligible: true`,
+     * there was simply nothing to do) — otherwise both cases produce the
+     * SAME all-empty shape and a caller could not tell "nothing needed
+     * doing" from "I have no authority to do anything here."
+     */
+    eligible: boolean;
+    /** `pending_writers[]` entries this call admitted this call, each via its own head. */
+    admitted: GitvaultReconcileWriterAdmissionsAdmitted[];
+    /** `writer_key_id`s already active before (or, for a raced admission, as of) this call — no action taken. */
+    already_covered: string[];
+    /** `pending_writers[]` entries this call could not admit. */
+    skipped: GitvaultReconcileWriterAdmissionsSkipped[];
+}
 export interface GitvaultPushOptions {
     transaction: GitvaultRefTransaction;
     /** New `HEAD` target for the published ref_state; carried forward when omitted. */
@@ -1294,9 +1464,22 @@ export interface GitvaultRotationResult {
         stored_bytes_sha256: string;
         principal_ids: string[];
     } | null;
+    /**
+     * gitvault-multi-writer (task 5.9, D6/D227) — writer keys this SAME head
+     * removed via a folded `writer_set_update`, each with the reason it was
+     * removed for. Empty (never omitted) when nothing needed removing — the
+     * common case, matching `excluded_keyless_principal_ids`' own
+     * always-present-possibly-empty shape rather than `pin_manifest_published`'s
+     * `| null`.
+     */
+    writers_removed: {
+        writer_key_id: string;
+        principal_id: string;
+        reason: "member_removed" | "writer_key_revoked" | "epoch_secret_exposed";
+    }[];
 }
 /**
- * What {@link GitvaultVault.planPush} reports (kychee-com/run402#565) — a REAL
+ * What {@link GitvaultVault.planPush} reports — a REAL
  * local computation, not an estimate: every number here comes from actually
  * building the packs (or checkpoint set) and actually sealing/encrypting
  * them, exactly as a real `push` would. `would_admit_generation` is what this
@@ -1360,6 +1543,7 @@ export interface GitvaultBuiltCheckpoint {
 }
 /** A transport-agnostic view of git ops the publication needs (the local repository). */
 export declare class GitvaultVault {
+    #private;
     readonly keystore: GitvaultKeystore;
     readonly transport: GitvaultTransport;
     readonly repoId: string;
@@ -1405,6 +1589,7 @@ export declare class GitvaultVault {
     private stateRestorePlan;
     private readonly retries;
     private readonly servicePublicKey;
+    private readonly allowUnauthenticatedSalvage;
     private genesisCache;
     /**
      * gitvault-byo-primary-bucket task 3.2 — this vault's resolved BYO write
@@ -1419,6 +1604,40 @@ export declare class GitvaultVault {
     constructor(options: GitvaultVaultOptions);
     static open(options: GitvaultVaultOptions): GitvaultVault;
     repoFile(): GitvaultRepoFile;
+    /**
+     * gitvault-agent-envelopes D4 — the COLD OPEN. A keystore that holds an
+     * identity but no repo file for this vault (a member joining from a fresh
+     * machine, or a creator whose repo file was lost) restores `K_repo` from
+     * its OWN `key_envelope` instead of dying `GITVAULT_REPO_STATE_MISSING`:
+     *
+     *   1. genesis (the writer-key source) is fetched and signature-verified;
+     *   2. its creator fingerprints are compared against the control plane's
+     *      SIGNED allocation record — `platform_attested`, never `receipt`
+     *      (the platform serves both sides of that comparison; a substituted
+     *      genesis needs a substituted allocation, which the org's owners can
+     *      see — TOFU + audit, human-envelopes D4's tier);
+     *   3. the envelope-recipients read says whether THIS fingerprint is
+     *      covered — if not, `GITVAULT_ENVELOPE_PENDING` names the key-holders
+     *      who can fulfil and the exact next actions (never a terminal error:
+     *      the desired state already records this member; any key-holder's
+     *      next gitvault operation wraps);
+     *   4. the base envelope is fetched, opened, and the repo file written
+     *      `restored_from_envelope` with the genesis hash PINNED (a later open
+     *      seeing a different genesis for this repo_id refuses
+     *      `VAULT_CREATION_CONFLICT`).
+     *
+     * Rotation epochs are NOT opened here — `verifyToNewest` walks them and
+     * opens each rotation-scoped envelope this identity is included in, exactly
+     * as it does for every other reader (`openEpochRotationForRecipient`).
+     *
+     * Returns `null` when the repo file already existed (nothing restored).
+     */
+    ensureRepoState(): Promise<GitvaultColdOpenResult | null>;
+    /** {@link open}, but a missing repo file triggers {@link ensureRepoState} first. */
+    static openOrRestore(options: GitvaultVaultOptions): Promise<{
+        vault: GitvaultVault;
+        restored: GitvaultColdOpenResult | null;
+    }>;
     private kRepo;
     private epoch;
     /**
@@ -1660,10 +1879,9 @@ export declare class GitvaultVault {
      * **This is task 1.1's residual WORKAROUND, not the design D5 ideal.** D5
      * describes a recipient-set change as an epoch rotation — "history epochs
      * stay wrapped as they were; a new member reads from their first covered
-     * epoch forward" — which needs a protocol revision (task 1, BLOCKED as of
-     * 2026-08-26: V0 pins `epoch` to the single constant
-     * `GITVAULT_GENESIS_EPOCH` on every head, so there is no "forward" to
-     * speak of yet). What this method actually does, legally, without any
+     * epoch forward" — which needs a protocol revision: V0 pins `epoch` to
+     * the single constant `GITVAULT_GENESIS_EPOCH` on every head, so there
+     * is no "forward" to speak of. What this method actually does, legally, without any
      * protocol change: `key_envelope` objects are never head-referenced (not
      * even genesis's own envelope is), so uploading an ADDITIONAL one at
      * `envelopes/<current epoch>/<recipient fingerprint>` for a missing
@@ -1686,7 +1904,7 @@ export declare class GitvaultVault {
      * this SDK does not make unattended.
      *
      * **The gateway directory route carries `public_key` on every row**
-     * (`GET /orgs/v1/:org_id/encryption-keys`, deployed 2026-08-26 — see the
+     * (`GET /orgs/v1/:org_id/encryption-keys` — see the
      * doc comment on {@link GitvaultOrgEncryptionKeyEntry}), so against a
      * current gateway entries actually wrap. A directory entry that arrives
      * WITHOUT the field (an older/rolling-deploy gateway) is still tolerated
@@ -1719,6 +1937,35 @@ export declare class GitvaultVault {
      */
     signer(): Uint8Array;
     private writerKeyId;
+    /**
+     * gitvault-multi-writer (task 5.8) — the push pre-check: before signing an
+     * ORDINARY head (any operation that expects this session to already be an
+     * active writer), refuse EARLY and LOCALLY when this session's own key is
+     * not (or is no longer) an active writer, rather than let real
+     * crypto/upload work run only to be refused by the gateway with a less
+     * specific message once the head finally reaches it. Reads the FRESHLY-
+     * pinned `writer_set_pin`; every call site below calls this immediately
+     * after its own `materialize()`/`verifyToNewest()` (same generation the
+     * caller is about to build against), so this performs no verification of
+     * its own — it only reads what the caller already froze.
+     *
+     * `removedMidRace` (design D8/D10) distinguishes the two shapes this
+     * refusal takes: `false` (the default) is the ORDINARY pre-check — this
+     * session was never (or is not currently) an admitted writer, thrown as
+     * `GITVAULT_WRITER_NOT_ADMITTED`. `true` is the CAS-LOSER path
+     * specifically: a retry, after re-materializing from the winner, that
+     * discovers THIS session's own key was removed by whatever won the race —
+     * "stop if removed" in D8's loser-rule sequence (fetch winner → verify →
+     * apply writer transition → stop if removed → rebase → rebuild → bounded
+     * backoff) — thrown as the more specific, client-local
+     * `GITVAULT_WRITER_REMOVED` (D10) instead: a real prior attempt just lost
+     * to a removal, not a caller who was never eligible.
+     *
+     * Deliberately NOT called for a "handoff"-door `add_writer_key` head
+     * ({@link submitWriterActivationHead}): there the signer is BY DESIGN not
+     * yet a writer — becoming one is what that exact head does.
+     */
+    private assertCallerIsWriter;
     /** The owner's full signing keypair, or `GITVAULT_READ_ONLY` — same refusal path as {@link signer}, which returns only the seed; {@link sealKeyEnvelope} needs both halves. */
     private signingKeypair;
     private buildRefState;
@@ -1833,7 +2080,7 @@ export declare class GitvaultVault {
      */
     push(options: GitvaultPushOptions): Promise<GitvaultPublishResult>;
     /**
-     * A REAL preview of what {@link push} would publish (kychee-com/run402#565)
+     * A REAL preview of what {@link push} would publish
      * — runs the SAME local pipeline `push` runs (materialize → evaluate →
      * evolve retention roots → build refState/retentionRoots → build packs or a
      * checkpoint set → seal/encrypt) and stops BEFORE the two network
@@ -1925,9 +2172,9 @@ export declare class GitvaultVault {
      * `POST …/object-reads` rejected every `recipient_pin_manifest` read
      * (its null-`idScalar` validation was hardcoded to `key_envelope`'s
      * `{epoch, recipient_fingerprint}` shape, never generalized when D197
-     * shipped the second path-addressed kind), so the network fallback below
-     * always 400'd. That gateway bug is fixed (deployed and live-verified
-     * 2026-08-28): the network path works for any keystore, including
+     * shipped the second path-addressed kind), which 400'd the network
+     * fallback below. That gateway bug is fixed: the network path works for
+     * any keystore, including
      * §4.11's fresh-client "SEEDS its local pin file from it" onboarding.
      * The cache stays purely as the round-trip saver described above.
      */
@@ -2012,10 +2259,10 @@ export declare class GitvaultVault {
      * `publishPinManifestUpdate` is an ORDINARY admission (`transition:
      * null`) and is therefore itself refused `EPOCH_ROTATION_REQUIRED` while
      * this vault has an urgent/migration condition outstanding — the exact
-     * state a `rotateEpoch` call is being made to clear. Reproduced live in
-     * production 2026-08-27 (a vault's first `epoch_secret_exposed` rekey:
-     * `/confirm` minted a receipt server-side, but the ordinary push that
-     * would publish it never admitted). Pass the pending receipted updates
+     * state a `rotateEpoch` call is being made to clear. On an
+     * `epoch_secret_exposed` rekey `/confirm` mints a receipt server-side,
+     * but the ordinary push that would publish it never admits. Pass the
+     * pending receipted updates
      * here instead — they ride the SAME head as this rotation's `transition`,
      * which IS `EPOCH_ROTATION_REQUIRED`'s own escape valve, so the publish
      * is no longer blocked. **This does NOT include these principals in
@@ -2050,6 +2297,19 @@ export declare class GitvaultVault {
             ek_fingerprint: string;
             receipt: GitvaultRecipientConfirmationReceipt;
         }[];
+        /**
+         * gitvault-multi-writer (task 5.9, D7/D228) — an outstanding
+         * gateway-blocked writer set (`ineligible_members`, checked fresh on
+         * every call — see the `writer_set_update` fold-in below) is ALWAYS
+         * folded into this rotation automatically; this flag is the EXPLICIT
+         * owner + step-up acknowledgment D7 requires ONLY when that fold-in
+         * would empty the vault's writer set entirely (the sole surviving
+         * writer was itself gateway-blocked) — the declared read-only terminal.
+         * Every OTHER case that would empty the writer set is refused
+         * `EPOCH_ROTATION_WOULD_LEAVE_VAULT_UNCOVERED` regardless of this flag;
+         * it widens nothing beyond that one specific, named exception.
+         */
+        force_empty_writer_set?: boolean;
     }): Promise<GitvaultRotationResult>;
     /**
      * The ONE fully self-contained rotation entry point: declares
@@ -2060,6 +2320,104 @@ export declare class GitvaultVault {
     rotateEpochForKeyRevocation(principalId: string, options?: {
         client_idempotency_key?: string;
     }): Promise<GitvaultRotationResult>;
+    /**
+     * Submit a REF-NEUTRAL `add_writer_key{authorization.kind:"handoff"}`
+     * activation head — no ref/checkpoint/repair changes ride it (protocol
+     * §4.17's own "ref-neutral head shape... for the activation head" rule),
+     * built by `publishGeneration` the SAME way every ordinary no-op push
+     * would be (`refs`/`head_target` carried forward from `base` UNCHANGED),
+     * just with `transition` set. Retries `HEAD_CAS_CONFLICT` like every
+     * other publish path here. The caller (`resume()`) has already built and
+     * locally sanity-checked the grant + acceptance; this method only reads
+     * the FRESHLY-verified `writer_set_pin` (set by the `materialize()` this
+     * same call performs, mirroring `push()`'s own base-then-retry shape) to
+     * compute `base_writer_set`/`next_writer_set`, signs the head under
+     * `this.signer()` (the ADDED key itself — protocol §4.17's "head signed
+     * by the added key" — since `signer()` reads straight from THIS
+     * keystore's identity, and `resume()` mints/loads that identity before
+     * ever reaching this call), and advances the local `writer_set_pin` on
+     * success so a subsequent read reflects the new writer without a second
+     * chain walk.
+     *
+     * Crash-resumable (task 5.6): the chain burns `handoff_id` single-use, so
+     * a naive resubmission after a crash between a prior attempt's successful
+     * admission and this checkout learning about it would be refused
+     * VALIDATION_FAILED. Returns `{outcome:"already_admitted", generation}`
+     * instead of submitting anything whenever the freshly-verified writer set
+     * ALREADY contains `input.addedWriterKeyId` — the caller treats both
+     * outcomes as success (the writer IS active either way) and proceeds.
+     */
+    submitWriterActivationHead(input: {
+        addedWriterKeyId: string;
+        addedSigningPubkeyB64u: string;
+        addedPrincipalId: string;
+        handoffId: string;
+        grant: Record<string, unknown>;
+        acceptance: Record<string, unknown>;
+    }): Promise<{
+        outcome: "activated";
+        result: GitvaultPublishResult;
+    } | {
+        outcome: "already_admitted";
+        generation: string;
+    }>;
+    /**
+     * gitvault-multi-writer (task 5.7) — the "writer"-door twin of {@link
+     * submitWriterActivationHead}: an ALREADY-ACTIVE writer (this vault
+     * session's own key) admits `input`, an eligible org member with a
+     * published signing key but no writer standing yet, via a fresh
+     * `add_writer_key{"writer"}` head. No grant/acceptance — the carrying
+     * head's own signer being an active writer at the predecessor generation
+     * IS the authorization (`validateAddWriterKeyPayload`'s `"writer"`
+     * branch), re-verified admission-side by `checkTransitionAdmissible`.
+     * Task 5.8 adds the SAME local pre-check every other head-signing path
+     * gets: if THIS session's own key is not (or is no longer) an active
+     * writer, refuse EARLY and LOCALLY (`GITVAULT_WRITER_NOT_ADMITTED` /
+     * `GITVAULT_WRITER_REMOVED`) rather than let the head reach the gateway
+     * only to be refused there — redundant with `reconcileWriterAdmissions`'s
+     * own upfront gate for that caller, but this method is public and a
+     * direct caller should get the same fast, specific refusal.
+     */
+    admitPendingWriter(input: {
+        addedWriterKeyId: string;
+        addedSigningPubkeyB64u: string;
+        addedPrincipalId: string;
+    }): Promise<{
+        outcome: "activated";
+        result: GitvaultPublishResult;
+    } | {
+        outcome: "already_admitted";
+        generation: string;
+    }>;
+    /**
+     * gitvault-multi-writer (task 5.7) — the vault's OWN writer-admission
+     * reconcile: reads `pending_writers[]` off the vault record (eligible org
+     * members with no writer standing yet), resolves each candidate's
+     * published signing key off the org's encryption-key directory (the SAME
+     * `/orgs/v1/:org_id/encryption-keys` row {@link
+     * reconcileEnvelopeRecipients} reads, widened D9 to also carry the
+     * signing half), and admits each via {@link admitPendingWriter} — one
+     * `add_writer_key{"writer"}` head per candidate, sequentially: each
+     * admission materializes fresh against the PRIOR one's own updated writer
+     * set, so there is no batched/parallel form.
+     *
+     * Requires THIS session's own key to already be an active writer (the
+     * chain's own authorization rule for the "writer" door) — checked ONCE,
+     * upfront, off the locally-pinned `writer_set_pin` (no network call),
+     * rather than discovered N times over from N identical gateway refusals:
+     * a session that reached this call already pushed successfully as an
+     * active writer in every wired call site (push/snapshot/deploy) OR is a
+     * member that simply is not one yet (session-start/read) — the SAME
+     * "not yet admitted" case {@link Gitvault.push}'s own pre-push check
+     * (task 5.8) names, not a new refusal shape. Returns `{eligible: false}`
+     * with every other field empty (never throws) for that case: every OTHER
+     * `pending_writers[]` entry would fail identically, so there is nothing
+     * this call can usefully do, and "I am not a writer" is not this vault's
+     * fault — but it is distinguishable from "there was nothing pending"
+     * (`eligible: true`, still all empty), which matters to a caller trying
+     * to explain an all-empty result to a human.
+     */
+    reconcileWriterAdmissions(): Promise<GitvaultReconcileWriterAdmissionsResult>;
     /**
      * Publish a repair head over `base_generation` (§4.3): superseded tips that
      * the repaired state no longer reaches enter the retention-root map with