@tinycloud/sdk-services 3.2.6-beta.4 → 3.3.0-beta.7

package/dist/{scope-CQ5kmHlt.d.cts → scope-B7oeKdLM.d.cts}

@@ -1,4 +1,4 @@
-import { R as Result, F as FetchFunction } from './types-gmdUiorz.cjs';
+import { R as Result, F as FetchFunction } from './types-BjH0ZtGy.cjs';
 import { REPLICA_KV_STORES } from './kv/replication/contractConstants.cjs';
 import { ReplicaConsentAnchor, ReplicaGrantPolicy } from './kv/replication/grantPolicyTypes.cjs';
 
@@ -526,7 +526,7 @@ interface ReplicaAccountGate {
     /** Active account's principal hash; null after sign-out. */
     principalHash: string | null;
     lifecycleEpoch: number;
-    /** ms since epoch of the last deny (browser: preserved across database recreation). */
+    /** ms since epoch of the last committed deny (browser: preserved across database recreation). */
     deniedAt: number | null;
     /** Browser: finite ms, fixed from verified fresh consent at establish; mandatory while active. */
     consentDeadline?: number | null;
@@ -665,8 +665,9 @@ type ReplicaDenyOutcome =
 /**
  * Gate moved, intents recorded, first-install anchors cleared and pending generations advanced
  * in one commit. Browser: owner device deleted in that same IDB transaction. Node: the gate
- * file cannot commit atomically with the device file, so the device is durably deleted by its
- * identity's pending-intent erase before that intent clears (idempotent replay).
+ * file cannot commit atomically with the device file, so an ordinary denial deletes it
+ * through the identity's pending-intent erase before intent clear. Deferred node sign-out
+ * holds that intent and the device file until validated resume (CONTRACT.md §2).
  */
 {
     status: "denied";
@@ -691,6 +692,15 @@ type ReplicaDenyOutcome =
     status: "unguarded";
     code: string;
 };
+/** A deferred sign-out denial: a committed `denied` always carries its resume token. */
+type ProfileReplicaDeferredDenyOutcome = {
+    status: "denied";
+    lifecycleEpoch: number;
+    intents: number;
+    resumeToken: ProfileReplicaDeferredToken;
+} | Exclude<ReplicaDenyOutcome, {
+    status: "denied";
+}>;
 interface ReplicaEraseReport {
     erased: string[];
     failed: Array<{
@@ -699,6 +709,11 @@ interface ReplicaEraseReport {
     }>;
     /** Intents still outstanding after this pass. */
     remaining: number;
+    /**
+     * Node/CLI: a durable deferred denial held this pass, so nothing was erased and
+     * `remaining` (possibly 0) is not completion; check `deferredErase()`.
+     */
+    deferred?: true;
     /** Browser startup discovered elapsed consent and durably crypto-shredded the account/gate keys. */
     consentExpired?: boolean;
 }
@@ -781,6 +796,8 @@ interface ReplicaLifecycleGate {
      * if expired, denies and crypto-shreds keys before any replica access; it also retries a
      * pending `deleteDatabase` marker and erases intents. Failures remain gated and visible via
      * `pendingPurge()` / `purgePending`; a browser closed at expiry catches it on its next load.
+     * Node/CLI recovery leaves durably deferred revoke intents and physical files untouched,
+     * reporting them as remaining until `ProfileReplicaPurge.resumeDeferredErase`.
      */
     recover(o: {
         signal: AbortSignal;
@@ -830,6 +847,12 @@ interface ReplicaLifecycleGate {
      * return null when its gate has no persisted consent deadline.
      */
     consentDeadline(stamp: ReplicaSessionStamp): number | null;
+    /**
+     * Browser-only post-commit consent expiry observer. Fires only after deny/delete
+     * destroys the origin account keys; a subscriber failure cannot undo denial.
+     * Controllers register after binding so events use their opened opaque replica IDs.
+     */
+    subscribeConsentExpired?(listener: (stamp: ReplicaSessionStamp) => void): () => void;
     /**
      * Synchronous main-thread delivery check before replica-served values/list keys/event fields,
      * and before open, installGrant and sync. Browser checks marker, origin deny tombstone,
@@ -853,6 +876,275 @@ interface ReplicaLifecycleGate {
     /** Outstanding intents; non-empty means status `purgePending: true`. */
     pendingPurge(): Promise<ReplicaPurgeIntent[]>;
 }
+/** Node/CLI profile-local fencing token, not a secret capability; the profile lock remains authoritative. */
+interface ProfileReplicaDeferredToken {
+    deniedEpoch: number;
+    principalHash: string;
+}
+/** Profile-relative, JSON-safe identity of a path listed before destructive logout. */
+interface ProfileReplicaUnknownEntry {
+    path: string;
+    kind: "file" | "directory" | "symlink";
+    dev: string;
+    ino: string;
+}
+/** Profile-relative directory identity; dev/ino are decimal strings for durable JSON. */
+interface ProfileReplicaRootIdentity {
+    path: string;
+    dev: string;
+    ino: string;
+}
+/** Exact nonsecret path identity displayed with an inventory confirmation token. */
+interface ProfileReplicaApprovalEntry extends ProfileReplicaRootIdentity {
+    kind: ProfileReplicaUnknownEntry["kind"] | "missing";
+}
+/** Read-only profile-locked inventory, including legacy mirrors and flag-owned roots. */
+interface ProfileReplicaPreflight {
+    knownLegacyReplicas: number;
+    unknownLegacyPaths: string[];
+    unknownPaths: string[];
+    unknownEntries: ProfileReplicaUnknownEntry[];
+    knownRoots: ProfileReplicaRootIdentity[];
+    knownEntries: ProfileReplicaUnknownEntry[];
+    missingDatabases: string[];
+}
+/**
+ * CLI-only durable crash fence. `principalDigest` is a domain-separated
+ * SHA-256 owner binding, not a secret or a substitute for the profile lock;
+ * v2/v3 never fabricate a scoped gate principal hash. A v1 `lifecycleEpoch`
+ * is the pre-denial epoch; `deniedEpoch` is the epoch the v1 denial actually
+ * committed, bound once after that denial and compared for equality from then
+ * on (CONTRACT.md §2). Remote-pending and remote-abandoned are mutually
+ * exclusive durable states.
+ */
+type ProfileReplicaLogoutPending = ({
+    v: 1;
+    incarnation: string;
+    lifecycleEpoch: number;
+    principalHash: string;
+    deniedEpoch?: number;
+} | {
+    v: 2;
+    scope: "orphan_profile";
+    nonce: string;
+} | {
+    v: 3;
+    scope: "inactive_gate";
+    incarnation: string;
+    lifecycleEpoch: number;
+}) & ProfileReplicaRemoteLogoutState & {
+    principalDigest: string;
+    /** Random durable 16-byte challenge salt as 32 lowercase hex characters. */
+    approvalSalt: string;
+    discardLocalChanges?: true;
+    approvedUnknown: ProfileReplicaUnknownEntry[];
+    knownRoots: ProfileReplicaRootIdentity[];
+    knownEntries: ProfileReplicaUnknownEntry[];
+    missingDatabases: string[];
+};
+/** A logout marker is remote-pending, remote-abandoned or neither; never both. */
+type ProfileReplicaRemoteLogoutState = {
+    remotePending: true;
+    remoteAbandoned?: never;
+} | {
+    remoteAbandoned: true;
+    remotePending?: never;
+} | {
+    remotePending?: never;
+    remoteAbandoned?: never;
+};
+/**
+ * Node/CLI-only lifecycle facade for a profile's replica root. The node-sdk exports
+ * `createProfileReplicaPurge({ profileDir, guard })`; `guard` is the caller's
+ * mandatory profile lock and MUST be reentrant within one async call chain: the
+ * CLI calls the facade while already holding its (reentrant) profile lock. This
+ * does not widen the browser `ReplicaLifecycleGate`.
+ *
+ * While a durable deferred denial is active, `recover` and `erasePending`
+ * leave intents and physical files untouched; `pendingPurge` lists the intents.
+ * A complete enumeration may have zero intents, so `remaining: 0` does not
+ * prove completion: `deferredErase()` is the authoritative marker check, and
+ * `LocalReplicaStatus.purgePending` / `ReplicaInspectedStatus.purgePending`
+ * are true while the deferred marker or any intent remains. All guarded reads
+ * and new establishment remain refused. Deferred intents leave that state only
+ * through a validated resume (CONTRACT.md §2); there is no account-switch or
+ * consent-expiry override. The facade never denies or erases a gate,
+ * partition, pending state or device record whose active principal is not
+ * the caller's ("Logout by another account", CONTRACT.md §2).
+ */
+interface ProfileReplicaPurge extends Pick<ReplicaLifecycleGate, "recover" | "erasePending" | "pendingPurge"> {
+    /**
+     * `deferErase: true` is valid only for `reason: "sign_out"`; other reasons throw
+     * TypeError before any mutation. A successful deferred `denied` outcome MUST carry
+     * `resumeToken`; stale or unguarded outcomes do not authorize a retryable revoke.
+     * Step 1 atomically denies, records every opaque partition/pending intent and
+     * pending generation, and persists the deferred marker. Physical files remain
+     * until `resumeDeferredErase`, even across process restart.
+     */
+    deny(input: ReplicaDenyInput & {
+        reason: "sign_out";
+    }, options: {
+        deferErase: true;
+    }): Promise<ProfileReplicaDeferredDenyOutcome>;
+    deny(input: ReplicaDenyInput, options?: {
+        deferErase?: false;
+    }): Promise<ReplicaDenyOutcome>;
+    /** Returns the persisted active token across restart, even with zero intents; null only after the marker clears. */
+    deferredErase(): Promise<ProfileReplicaDeferredToken | null>;
+    /**
+     * Under the profile lock, require the exact denied epoch and principal hash and a
+     * null gate principal; otherwise throw `REPLICA_GATED`/`stamp_stale` without erasure.
+     * Clear the deferred marker durably before idempotent erase. A crash after clearing
+     * is completed by ordinary recovery. Repeating the same token is safe only while
+     * the same denied epoch/hash persists; a successor establishment fences it.
+     */
+    resumeDeferredErase(token: ProfileReplicaDeferredToken, options: {
+        signal: AbortSignal;
+    }): Promise<ReplicaEraseReport>;
+    /**
+     * Read-only profile-locked inventory BEFORE marker, denial or remote call.
+     * Report exact profile-relative unknown paths, kinds and dev/ino plus all
+     * known roots/entries. Unknown/indeterminate data refuses unless explicit
+     * discard consent was supplied; the CLI displays the inventory before acting.
+     * A prior inventory is not a wildcard authorization for later new paths.
+     */
+    preflightLogout(input: {
+        principal: string;
+        discardLocalChanges?: boolean;
+    }): Promise<ProfileReplicaPreflight>;
+    /**
+     * Re-inspect and compare the complete approved inventory under the profile
+     * lock, then atomically fsync a scoped v1, orphan v2 or inactive v3 marker.
+     * `approval` is required: the CLI passes its just-displayed preflight even
+     * when it contains no unknown paths. With `remotePending`, the marker fences
+     * replica reads but forbids credential cleanup or erasure until
+     * `completeRemoteLogout` after all exact-CID revokes. Only approved
+     * path/type/dev/ino identities and the explicit discard bit survive; changed
+     * paths refuse pre-action. V1 active remote logout additionally requires a
+     * committed deferred denial/token before online revoke; v2 orphan and v3
+     * inactive markers instead use their version-specific gate-absence/epoch
+     * fences.
+     *
+     * An existing marker is never rewritten here: the same owner, fence,
+     * `remotePending` state and approved inventory return it unchanged; anything
+     * else refuses without mutation. When the gate's active principal is the
+     * caller's, it always yields a v1 marker, even with no replica roots or
+     * intents; another account's active gate yields null and is never denied.
+     * Null otherwise means there is no active principal and no replica-owned
+     * work, not completed logout.
+     *
+     * A missing flag pending index, unrecognized child, nonempty pending state
+     * or corrupt gate requires explicit discard. The CLI still fsyncs
+     * authSignedOut then unlinks and fsyncs both credentials. CLI-bound reads
+     * and ordinary network restore refuse any marker; an explicit remote-revoke
+     * retry may use the retained key/session while `remotePending` without
+     * delivering replica data.
+     */
+    prepareLogoutPending(input: {
+        principal: string;
+        approval: ProfileReplicaPreflight;
+        discardLocalChanges?: boolean;
+        remotePending?: true;
+    }): Promise<ProfileReplicaLogoutPending | null>;
+    /**
+     * After every authoritative exact-CID revoke succeeds, revalidate the
+     * marker's principal and version-specific fence under the profile lock:
+     * v1 `deniedEpoch`/hash, v2 no replacement gate, or v3 exact inactive
+     * epoch/null principal. Then durably remove `remotePending`. A marker that is
+     * not remote-pending (remote-abandoned or already cleanup-ready) refuses
+     * without mutation. A failed/partial remote sequence never calls this.
+     */
+    completeRemoteLogout(input: {
+        principal: string;
+    }): Promise<ProfileReplicaLogoutPending>;
+    /**
+     * Under the profile lock, report whether this principal's marker is still
+     * remote-pending and its v1 deferred gate, v2 orphan or v3 inactive gate
+     * fence still matches. False only when the marker is absent/completed;
+     * a mismatched principal or stale gate refuses. This permits an explicit
+     * network-only revoke retry, never replica delivery.
+     */
+    remotePendingLogout(input: {
+        principal: string;
+    }): Promise<boolean>;
+    /**
+     * First explicit PLAIN logout attempt after unfinished remote revoke:
+     * compare the original durable approved inventory with the current
+     * path/type/dev/ino set under the profile lock. Any change refuses with
+     * `REPLICA_GATED`/`gate_unavailable`, prints every token-bound
+     * `ProfileReplicaApprovalEntry`, exposes the same complete set as
+     * `error.inventoryApprovalEntries` plus a nonsecret 32-hex-character
+     * `error.inventoryApprovalToken`, and mutates nothing even when `approval`
+     * contains the new paths or `discardLocalChanges` is true. With the
+     * original inventory intact, validate the fresh approval and the marker's
+     * version-specific owner/gate fence (a v1 marker is classified by its gate
+     * and checked exactly one way, CONTRACT.md §2), then atomically replace
+     * `remotePending` with `remoteAbandoned: true`.
+     * This is not an online-success receipt and makes no further node call.
+     */
+    abandonRemoteLogout(input: {
+        principal: string;
+        approval: ProfileReplicaPreflight;
+        discardLocalChanges?: boolean;
+    }): Promise<ProfileReplicaLogoutPending>;
+    /**
+     * Only a separate explicit CLI command with
+     * `--discard-local-changes --approve-inventory <token>` may approve a
+     * changed remote-pending inventory. Under the profile lock, require the
+     * same owner and version-specific gate fence, original-to-current inventory
+     * mismatch, exact fresh preflight and matching displayed 32-hex-character
+     * token. Commit the newly approved identities with `remoteAbandoned: true`,
+     * never a remote receipt. Missing, stale or reused tokens fail without
+     * mutation; there is no same-command fallback from `abandonRemoteLogout`.
+     */
+    approveChangedPlainLogout(input: {
+        principal: string;
+        approval: ProfileReplicaPreflight;
+        discardLocalChanges: true;
+        inventoryApprovalToken: string;
+    }): Promise<ProfileReplicaLogoutPending>;
+    /**
+     * After a completed remote sequence, an inventory mismatch leaves the
+     * marker and signed-out state in place. A fresh explicit listing/ack under
+     * the profile lock replaces only the approved inventory; remote revokes
+     * are not repeated, and a still-pending remote sequence cannot reapprove.
+     */
+    reapproveLogoutPending(input: {
+        principal: string;
+        approval: ProfileReplicaPreflight;
+    }): Promise<ProfileReplicaLogoutPending>;
+    /**
+     * CLI startup/logout recovery under the same profile lock. A `remotePending`
+     * marker returns failure with no credential or file deletion. For a
+     * cleanup-ready active-v1 marker, validate the gate and durably commit
+     * generation-fenced denial with complete partition/pending intents
+     * BEFORE calling `clearCredentials`; denial failure leaves the marker,
+     * both credentials and replica files intact and reports nonzero failure.
+     * An already-deferred v1 validates its exact denial; v3 validates its
+     * inactive epoch and v2 its orphan/no-replacement-gate fence without
+     * inventing scoped intents. Only then does `clearCredentials` atomically
+     * fsync CLI authSignedOut before unlinking and fsyncing both session.json
+     * and key.json. Recheck durable approved identities before each unlink;
+     * mismatch stops with marker, remaining files and nonzero failure.
+     * Post-success credentials remain shredded. The callback erases only its
+     * approved inventory under the profile lock (never recursive legacy
+     * deletion). In-repo CLI code owns the signed-out postcondition; the
+     * facade verifies credential absence before erasure. A missing marker
+     * with corrupt/unreadable gate reports failure and nonzero remaining,
+     * without invoking callbacks or fabricating successful completion.
+     */
+    recoverLogoutPending(options: {
+        signal: AbortSignal;
+        clearCredentials: () => Promise<void>;
+        eraseLegacyReplicas: (options: {
+            discardLocalChanges: boolean;
+            approvedUnknown: readonly ProfileReplicaUnknownEntry[];
+            knownRoots: readonly ProfileReplicaRootIdentity[];
+            knownEntries: readonly ProfileReplicaUnknownEntry[];
+            missingDatabases: readonly string[];
+        }) => Promise<void>;
+    }): Promise<ReplicaEraseReport>;
+}
 /** Worker replies that carry replica-served data are stamped; a reply without a stamp is dropped. */
 interface ReplicaStampedReply {
     stamp: ReplicaSessionStamp;
@@ -1315,10 +1607,13 @@ interface ReplicationAuthority {
     mint(deviceDid: string, prefix: string, signal: AbortSignal, 
     /**
      * `expiryMs` is a DURATION from now (forwarded as `delegateTo(…, { expiry: expiryMs })`), from
-     * `mintRemainingMs`. Absent means Phase 1 behaviour (session-tier default).
+     * `mintRemainingMs`. Absent means Phase 1 behaviour (session-tier default). `renewalOnly`
+     * requires the authority to recheck a session-key parent at mint time; an initial runtime
+     * parent mint leaves it unset.
      */
     options?: {
         expiryMs?: number;
+        renewalOnly?: boolean;
     }): Promise<{
         ucan: string;
         parentCid: string;
@@ -1425,6 +1720,12 @@ interface KVReadThrough {
     }): void;
 }
 interface KVReplicationController extends KVReadThrough {
+    /**
+     * Internal browser gate observer: invoked only after the stamped durable consent-expiry
+     * denial/deletion commits. Records opened opaque grant transitions even if the gate's own
+     * timer wins before this controller's timer; does not issue a second deny.
+     */
+    observeConsentExpired(stamp: ReplicaSessionStamp): void;
     status(): Promise<ReplicaStatusEntry[]>;
     sync(o?: {
         prefix?: string;
@@ -1525,7 +1826,9 @@ interface ReplicaStatusEntry extends Partial<LocalReplicaStatus> {
 type ReplicaState = "idle" | "ready" | "grant_missing" | "runtime_unsupported" | "unavailable" | "revoked"
 /** The lifecycle gate refuses this session (REPLICA_GATED); reads use the network. */
  | "gated" | "closed";
-type ReplicationReason = "hit" | "absent" | "deleted" | "content_missing" | "coverage_incomplete" | "not_covered" | "pending_write" | "grant_missing" | "grant_expired" | "grant_revoked" | "grant_not_yet_valid" | "stale" | "replica_error" | "runtime_unsupported" | "replica_unavailable" | "unsupported_option" | "network_cursor" | "cursor_restart" | "aborted" | "REPLICA_BEHIND_OWN_WRITES" | "REPLICA_UNPROVEN_SINCE_START" | "NETWORK_REQUESTED"
+type ReplicationReason = "hit" | "absent" | "deleted" | "content_missing" | "coverage_incomplete" | "not_covered" | "pending_write" | "grant_missing" | "grant_expired"
+/** A revoked grant, including a stale-read sync refusal; read-through uses network with code GRANT_REVOKED. */
+ | "grant_revoked" | "grant_not_yet_valid" | "stale" | "replica_error" | "runtime_unsupported" | "replica_unavailable" | "unsupported_option" | "network_cursor" | "cursor_restart" | "aborted" | "REPLICA_BEHIND_OWN_WRITES" | "REPLICA_UNPROVEN_SINCE_START" | "NETWORK_REQUESTED"
 /** The lifecycle gate refused (REPLICA_GATED); the read went to the network. */
  | "replica_gated";
 type ReplicationEvent = {
@@ -1656,4 +1959,4 @@ declare function replicationIdentityKey(id: ReplicationIdentity): string;
 /** Whether replicating this space/prefix can copy encrypted secret material to disk. */
 declare function requiresSecretsOptIn(space: string, prefix: string): boolean;
 
-export { type ReplicaQuotaLedger as $, type AuthorityRefusal as A, type ReplicaDevice as B, CLEAR_PENDING_WARNING as C, type ReplicaEraseReport as D, type ReplicaGateAccess as E, type ReplicaGateReason as F, type ReplicaGateScope as G, type ReplicaGateSnapshot as H, type ReplicaGateTx as I, type ReplicaGatedError as J, type KVReplicationDeps as K, type LocalGetResult as L, type ReplicaGatedHandle as M, type ReplicaGatedSpec as N, type ReplicaGatedStorage as O, type PendingWriteStore as P, type ReplicaGrantInfo as Q, type ReplicationIdentity as R, type ReplicaGuardedStore as S, type ReplicaInspectedStatus as T, type ReplicaLifecycleGate as U, type ReplicaPageAdmission as V, type ReplicaPartitionEraser as W, type ReplicaPartitionIndexEntry as X, type ReplicaPeerCommit as Y, type ReplicaPrivateGateHash as Z, type ReplicaPurgeIntent as _, type KVReplicationController as a, type ReplicaQuotaSpec as a0, type ReplicaSessionStamp as a1, type ReplicaStampedReply as a2, type ReplicaState as a3, type ReplicaStatusEntry as a4, type ReplicationAuthority as a5, type ReplicationControl as a6, type ReplicationEvent as a7, type ReplicationOptions as a8, type ReplicationPurgeReport as a9, type KVResponseHeaders as aA, type KVServiceConfig as aB, type KVSignedReadUrlResponse as aC, type ReplicationReason as aa, type ReplicationScheduler as ab, type ResolvedReplicationOptions as ac, type SaltedHash as ad, canonicalReplicationIdentity as ae, replicationIdentityKey as af, requiresSecretsOptIn as ag, DEFAULT_SIGNED_READ_URL_EXPIRY_MS as ah, KVAction as ai, type KVActionType as aj, type KVBatchPutItem as ak, type KVBatchPutOptions as al, type KVBatchPutResponse as am, type KVBatchReadResponse as an, type KVChange as ao, type KVChangesAuthority as ap, type KVChangesOptions as aq, type KVChangesResponse as ar, type KVCreateSignedReadUrlOptions as as, type KVDeleteOptions as at, type KVGetOptions as au, type KVHeadOptions as av, type KVListOptions as aw, type KVListResponse as ax, type KVPutOptions as ay, type KVResponse as az, type KVListPage as b, type KVReadThrough as c, type KVReplicaHandle as d, type KVReplicaSpec as e, type KVReplicaStorage as f, type LocalListResult as g, type LocalReadMeta as h, type LocalReplicaStatus as i, type LocalSyncResult as j, type PendingWriteRecord as k, type PendingWriteState as l, type PinnedKey as m, type PurgeTarget as n, type ReplicaAccountGate as o, type ReplicaAdmitHook as p, type ReplicaAuthorityState as q, type ReplicaBrowserGateAccess as r, type ReplicaBrowserGateSnapshot as s, type ReplicaBrowserGateTx as t, type ReplicaBrowserPageAdmission as u, type ReplicaClock as v, type ReplicaCoverage as w, type ReplicaDeliveryDecision as x, type ReplicaDenyInput as y, type ReplicaDenyOutcome as z };
+export { type ReplicaGuardedStore as $, type AuthorityRefusal as A, type ReplicaBrowserGateAccess as B, CLEAR_PENDING_WARNING as C, type ReplicaBrowserGateSnapshot as D, type ReplicaBrowserGateTx as E, type ReplicaBrowserPageAdmission as F, type ReplicaClock as G, type ReplicaCoverage as H, type ReplicaDeliveryDecision as I, type ReplicaDenyInput as J, type KVReplicationDeps as K, type LocalGetResult as L, type ReplicaDenyOutcome as M, type ReplicaDevice as N, type ReplicaEraseReport as O, type PendingWriteStore as P, type ReplicaGateAccess as Q, type ReplicationIdentity as R, type ReplicaGateReason as S, type ReplicaGateScope as T, type ReplicaGateSnapshot as U, type ReplicaGateTx as V, type ReplicaGatedError as W, type ReplicaGatedHandle as X, type ReplicaGatedSpec as Y, type ReplicaGatedStorage as Z, type ReplicaGrantInfo as _, type KVReplicationController as a, type ReplicaInspectedStatus as a0, type ReplicaLifecycleGate as a1, type ReplicaPageAdmission as a2, type ReplicaPartitionEraser as a3, type ReplicaPartitionIndexEntry as a4, type ReplicaPeerCommit as a5, type ReplicaPrivateGateHash as a6, type ReplicaPurgeIntent as a7, type ReplicaQuotaLedger as a8, type ReplicaQuotaSpec as a9, type KVChangesResponse as aA, type KVCreateSignedReadUrlOptions as aB, type KVDeleteOptions as aC, type KVGetOptions as aD, type KVHeadOptions as aE, type KVListOptions as aF, type KVListResponse as aG, type KVPutOptions as aH, type KVResponse as aI, type KVResponseHeaders as aJ, type KVServiceConfig as aK, type KVSignedReadUrlResponse as aL, type ReplicaSessionStamp as aa, type ReplicaStampedReply as ab, type ReplicaState as ac, type ReplicaStatusEntry as ad, type ReplicationAuthority as ae, type ReplicationControl as af, type ReplicationEvent as ag, type ReplicationOptions as ah, type ReplicationPurgeReport as ai, type ReplicationReason as aj, type ReplicationScheduler as ak, type ResolvedReplicationOptions as al, type SaltedHash as am, canonicalReplicationIdentity as an, replicationIdentityKey as ao, requiresSecretsOptIn as ap, DEFAULT_SIGNED_READ_URL_EXPIRY_MS as aq, KVAction as ar, type KVActionType as as, type KVBatchPutItem as at, type KVBatchPutOptions as au, type KVBatchPutResponse as av, type KVBatchReadResponse as aw, type KVChange as ax, type KVChangesAuthority as ay, type KVChangesOptions as az, type KVListPage as b, type KVReadThrough as c, type KVReplicaHandle as d, type KVReplicaSpec as e, type KVReplicaStorage as f, type LocalListResult as g, type LocalReadMeta as h, type LocalReplicaStatus as i, type LocalSyncResult as j, type PendingWriteRecord as k, type PendingWriteState as l, type PinnedKey as m, type ProfileReplicaApprovalEntry as n, type ProfileReplicaDeferredDenyOutcome as o, type ProfileReplicaDeferredToken as p, type ProfileReplicaLogoutPending as q, type ProfileReplicaPreflight as r, type ProfileReplicaPurge as s, type ProfileReplicaRemoteLogoutState as t, type ProfileReplicaRootIdentity as u, type ProfileReplicaUnknownEntry as v, type PurgeTarget as w, type ReplicaAccountGate as x, type ReplicaAdmitHook as y, type ReplicaAuthorityState as z };

package/dist/sql/index.cjs

@@ -43,6 +43,14 @@ var ErrorCodes = {
   ABORTED: "ABORTED",
   INVALID_INPUT: "INVALID_INPUT",
   PERMISSION_DENIED: "PERMISSION_DENIED",
+  // Node retry signals (tinycloud-node #347). `meta.retryable` says whether a
+  // retry is safe; `meta.retryAfterMs` carries the node's Retry-After.
+  /** HTTP 503 `sql_busy:<stage>` / `unavailable_retryable`: nothing was applied; retry after `meta.retryAfterMs`. */
+  NODE_BUSY: "NODE_BUSY",
+  /** HTTP 503 `request_timeout`: the node's deadline passed before any write began; nothing was applied. */
+  REQUEST_TIMEOUT: "REQUEST_TIMEOUT",
+  /** HTTP 500 `outcome_unknown`: a write may have been applied; read back before retrying a non-idempotent operation. */
+  OUTCOME_UNKNOWN: "OUTCOME_UNKNOWN",
   // KV-specific errors
   KV_NOT_FOUND: "KV_NOT_FOUND",
   KV_WRITE_FAILED: "KV_WRITE_FAILED",
@@ -118,6 +126,42 @@ function serviceError(code, message, service, options) {
   };
 }
 
+// src/responseErrors.ts
+function parseServiceErrorBody(errorText) {
+  try {
+    return JSON.parse(errorText);
+  } catch {
+    return {};
+  }
+}
+function formatServiceResponseError(serviceLabel, operation, status, errorText, parsed) {
+  if (parsed.message) {
+    return compactMessage(parsed.message);
+  }
+  if (looksLikeHtml(errorText)) {
+    if (status === 524 || /524\s*[:-]/i.test(errorText) || /a timeout occurred/i.test(errorText)) {
+      return `${serviceLabel} ${operation} failed: upstream request timed out. Please retry.`;
+    }
+    return `${serviceLabel} ${operation} failed: upstream service returned an HTML error page (${status}).`;
+  }
+  return `${serviceLabel} ${operation} failed: ${status} - ${compactMessage(errorText)}`;
+}
+function responseErrorMeta(status, statusText, errorText) {
+  const meta = { status, statusText };
+  const snippet = compactMessage(errorText);
+  if (snippet) {
+    meta.responseSnippet = snippet.slice(0, 300);
+  }
+  return meta;
+}
+function looksLikeHtml(text) {
+  return /<!doctype html/i.test(text) || /<html[\s>]/i.test(text);
+}
+function compactMessage(message) {
+  const compact = message.replace(/\s+/g, " ").trim();
+  return compact.length > 500 ? `${compact.slice(0, 500)}...` : compact;
+}
+
 // src/errors.ts
 var import_bootstrap = require("@tinycloud/bootstrap");
 function authRequiredError(service) {
@@ -127,6 +171,30 @@ function authRequiredError(service) {
     service
   };
 }
+function nodeRetryError(service, message, response, errorText) {
+  const body = errorText.trim();
+  const [, token, stage] = /^([a-z_]+)(?::\s*([a-z_]+):)?/.exec(body) ?? [];
+  let code;
+  if (response.status === 503 && (token === "sql_busy" || token === "unavailable_retryable")) {
+    code = ErrorCodes.NODE_BUSY;
+  } else if (response.status === 503 && token === "request_timeout") {
+    code = ErrorCodes.REQUEST_TIMEOUT;
+  } else if (response.status === 500 && token === "outcome_unknown") {
+    code = ErrorCodes.OUTCOME_UNKNOWN;
+  } else {
+    return void 0;
+  }
+  const retryable = code !== ErrorCodes.OUTCOME_UNKNOWN;
+  const retryAfter = response.headers.get("retry-after")?.trim();
+  return serviceError(code, message, service, {
+    meta: {
+      ...responseErrorMeta(response.status, response.statusText, errorText),
+      retryable,
+      ...token === "sql_busy" && stage ? { stage } : {},
+      ...retryable && retryAfter && /^\d{1,9}$/.test(retryAfter) ? { retryAfterMs: Number(retryAfter) * 1e3 } : {}
+    }
+  });
+}
 var RequestTimeoutError = class extends Error {
   constructor(timeoutMs) {
     super(`Request timed out after ${timeoutMs}ms.`);
@@ -534,42 +602,6 @@ var BaseService = class {
   }
 };
 
-// src/responseErrors.ts
-function parseServiceErrorBody(errorText) {
-  try {
-    return JSON.parse(errorText);
-  } catch {
-    return {};
-  }
-}
-function formatServiceResponseError(serviceLabel, operation, status, errorText, parsed) {
-  if (parsed.message) {
-    return compactMessage(parsed.message);
-  }
-  if (looksLikeHtml(errorText)) {
-    if (status === 524 || /524\s*[:-]/i.test(errorText) || /a timeout occurred/i.test(errorText)) {
-      return `${serviceLabel} ${operation} failed: upstream request timed out. Please retry.`;
-    }
-    return `${serviceLabel} ${operation} failed: upstream service returned an HTML error page (${status}).`;
-  }
-  return `${serviceLabel} ${operation} failed: ${status} - ${compactMessage(errorText)}`;
-}
-function responseErrorMeta(status, statusText, errorText) {
-  const meta = { status, statusText };
-  const snippet = compactMessage(errorText);
-  if (snippet) {
-    meta.responseSnippet = snippet.slice(0, 300);
-  }
-  return meta;
-}
-function looksLikeHtml(text) {
-  return /<!doctype html/i.test(text) || /<html[\s>]/i.test(text);
-}
-function compactMessage(message) {
-  const compact = message.replace(/\s+/g, " ").trim();
-  return compact.length > 500 ? `${compact.slice(0, 500)}...` : compact;
-}
-
 // src/sql/SQLMigrations.ts
 var SQLMigrations = class {
   constructor(service, dbName) {
@@ -985,6 +1017,8 @@ var SQLService = class extends BaseService {
     if (response.status === 413 && parseStorageRejection(errorText)) {
       return err(storageRejectionError("sql", 413, meta, errorText));
     }
+    const retryError = nodeRetryError("sql", `SQL ${operation} failed: ${response.status} - ${errorText}`, response, errorText);
+    if (retryError) return err(retryError);
     const errorBody = parseServiceErrorBody(errorText);
     const errorCode = this.mapHttpStatusToErrorCode(
       response.status,