dsh-keys-manager 0.0.0 → 0.2.0

package/lib/index.d.ts

@@ -0,0 +1,860 @@
+import type { AccountAttemptView, StateView } from './domain.js';
+import type { CredentialsLike, GenerateOptionsLike, HostContext, KeySelection, RequestErrorAction, AgentRequestPayload, RequestErrorPayload, SettingsLike, StreamChunkLike } from './host-types.js';
+import { KeysManagerStore } from './store.js';
+export declare const name = "keys-manager";
+export declare const inject: string[];
+export declare const provide: string[];
+/** The credential-record scope pi-ai stores its per-provider grants under (llm-pi-ai/src/auth.ts:29). */
+export declare const OAUTH_GRANT_RECORD_SCOPE = "llm-pi-ai";
+/**
+ * Stable failure code for a harvest whose state flush rejected AND whose
+ * credential-side rollback then failed to write.
+ *
+ * The state flush is the durability boundary `run` enforces, and the rollback
+ * that follows it deletes/restores the credential records the rolled-back row
+ * referenced. When those compensating writes fail too, the attempt's reason
+ * starts with `<code>: ` and keeps the original flush error verbatim after it,
+ * so an upstream caller can branch on {@link isFlushRollbackCompensationFailure}
+ * instead of matching prose. A flush failure whose rollback completed keeps its
+ * original error unchanged — this code is the only added spelling.
+ */
+export declare const FLUSH_ROLLBACK_COMPENSATION_FAILED = "FLUSH_ROLLBACK_COMPENSATION_FAILED";
+/** Whether an attempt error carries {@link FLUSH_ROLLBACK_COMPENSATION_FAILED}. */
+export declare function isFlushRollbackCompensationFailure(error: string | undefined): boolean;
+/** Service keybinding consumed by the Typert Gateway. */
+interface TypertRemoteBinding {
+    service: KeysManagerService;
+    serviceKey: string;
+    namespace: string;
+}
+export declare class KeysManagerService {
+    readonly ctx: HostContext;
+    readonly store: KeysManagerStore;
+    private readonly als;
+    private readonly attempts;
+    private readonly stepAttempts;
+    private readonly streamAttempts;
+    private readonly linkedAttempts;
+    private readonly retryBindings;
+    private readonly requestSteps;
+    private attemptSequence;
+    private readonly switches;
+    private warnings;
+    settings: SettingsLike | undefined;
+    private rawCredentials;
+    private readonly credentialOriginals;
+    private readonly credentialWrappers;
+    private brokerOwners;
+    private readonly bindingCache;
+    private lastBindingPruneAt;
+    private readonly selectionQueues;
+    private queue;
+    private closing;
+    /** Interactive sign-in attempts, by attempt id. */
+    private readonly loginAttempts;
+    /** The provider → attempt id index for the single-attempt rule. */
+    private readonly loginsInFlight;
+    private loginSequence;
+    /** The account row whose grant payload currently IS the projection, per provider. */
+    private readonly activeAccounts;
+    /**
+     * Account rows committed to removal (C6-1/I1 removal-aware oracle), marked
+     * by {@link removeOAuthGrant} before its first awaited delete. A multi-row
+     * release deletes every row's credential first and the provider record
+     * last, and it never splices its rows, so while it runs the provider record
+     * and the row object both still look live even though the row's grant is
+     * already gone. Object identity alone therefore cannot tell "still serving"
+     * from "mid-removal"; this mark can. A successful removal leaves it set —
+     * the row it names is either spliced out (removeAccount/deleteKey) or left
+     * flagged `valueMissing` (release) — but a removal whose awaited steps
+     * THROW must clear it: the row is then still live and still managed, and a
+     * stale mark would silently skip its rotation sync until a restart. It
+     * marks the live object, so a row object recreated under the same id is
+     * unaffected.
+     */
+    private readonly retiringAccounts;
+    /**
+     * Per-provider projection generation — the write counter for
+     * {@link activeAccounts} claims (round-3 finding 3) and the attribution
+     * identity of a projected grant (round-6 finding SF1). It is bumped exactly
+     * when a grant becomes the provider's projection (a manager-side
+     * re-projection or the seam's committed grant at the settlement broadcast),
+     * never at a later bookkeeping step. A hydration result whose generation no
+     * longer matches is discarded instead of overwriting a newer projection
+     * with a stale read.
+     */
+    private readonly ownershipGenerations;
+    /**
+     * Per-account-row projection generation in effect when the row's CURRENT
+     * cooldown was earned (round-6 finding SF1). `applyFailureCooldown` stamps
+     * it at failure time, so a harvest can tell the previous grant's window
+     * from one the freshly projected grant earned while the harvest was still
+     * queued. A row with no entry carries a window that predates any observed
+     * attribution (one loaded from disk, for example); the next projection
+     * treats it as the older generation's.
+     */
+    private readonly cooldownGenerations;
+    /**
+     * Per-provider chain of pending grant reconciliations (round-9 finding
+     * P1): two refresh echoes for the same route can arrive before the first
+     * write-back settles, and the bodies run read → write → commit. Arrival
+     * order is preserved so the older observation can never commit after the
+     * newer one and leave the row on a stale generation.
+     *
+     * Round-8 finding I-000106: activation joins the same chain. The only
+     * writer of `row.oauth.grantRef` is {@link reconcileGrantRecord}, which runs
+     * outside the mutation queue, so activation's record read and its projection
+     * write must be mutually exclusive with that writer — otherwise a rotation
+     * landing between them leaves the projection on a generation the row no
+     * longer names.
+     */
+    private readonly grantReconciliations;
+    /**
+     * Providers whose projection deletion this manager initiated, mapped to
+     * the moment it was initiated. The `record-updated` echo of our own
+     * demotion consumes the marker (one-shot) and stays silent while the
+     * marker is inside its TTL window; past the window the marker is expired
+     * and a removal warns as genuinely out-of-band again.
+     */
+    private readonly intentionalProjectionRemovals;
+    /**
+     * In-flight projection demotions by provider (round-5 finding C1): the
+     * oauth failure path cools the account and demotes asynchronously, and the
+     * failover retry must not re-enter the stream while the projection still
+     * resolves — pi-ai prefers the stored grant, so the key pool would never be
+     * reached. The request-error listener awaits this entry before deciding.
+     */
+    private readonly projectionDemotions;
+    /**
+     * MF3 load-time hydration result (round-8 finding I-000108). The
+     * constructor starts the ownership read, but a restarted process can serve
+     * a stream before it settles. Until this provider's read lands,
+     * {@link activeAccounts} may not know the owner, so `wrapStream` would
+     * select and mutate a key (cursor, `lastUsedAt`, sticky binding) even though
+     * pi-ai serves the persisted grant, and an OAuth failure would be classified
+     * as externally authenticated instead of cooling the account.
+     *
+     * The promise never rejects (hydration catches and warns per provider), but
+     * it can stay pending forever. Requests therefore never subscribe to it
+     * (round-10 should-fix SF2: a per-call `then`/`await` would be retained on a
+     * promise that never settles); they wait per provider through
+     * {@link hydratedProviders} and {@link hydrationWaiters} instead.
+     */
+    private projectionHydration;
+    /**
+     * Upper bound on one stream's wait for its provider's hydration read
+     * (round-9 should-fix). The hydration read has no timeout of its own, so
+     * without a bound one stalled `readRecord` would gate every managed stream.
+     * Injectable so tests can exercise the bound quickly.
+     */
+    private hydrationWaitMs;
+    /**
+     * Providers whose hydration read has landed — owner found or not
+     * (round-10 should-fix SF1). Hydration walks the providers serially and
+     * writes each owner as it goes, so one stalled read must not make an
+     * already-read provider look unknown: a provider whose own read landed is
+     * ready immediately, and the bounded wait's "unknown" fallback is confined
+     * to the requested provider's own unresolved read.
+     */
+    private readonly hydratedProviders;
+    /**
+     * One resolver set per provider still being waited on (round-10 should-fix
+     * SF2). A wait registers exactly one entry here and removes it when the wait
+     * ends — on timeout or on the late landing — so a read that never settles
+     * cannot retain anything per request. {@link noteProviderHydrated} is the
+     * only notification channel; the shared hydration promise is never
+     * subscribed to.
+     */
+    private readonly hydrationWaiters;
+    /**
+     * True once the load-time hydration read is over (round-10 SF1). From then
+     * on no provider's read can land, so attribution is known for every provider
+     * — including one adopted after the read, whose OAuth rows did not exist
+     * when the projection was looked for.
+     */
+    private hydrationSettled;
+    /** Providers whose bounded-wait warning already fired (warn once). */
+    private readonly hydrationWaitWarned;
+    /** Channels whose lost-subscription warning already fired (warn once). */
+    private readonly subscriptionLostWarnings;
+    /** Disposer for the `authorization/settled` subscription. */
+    private settledDisposer;
+    /** Disposer for the `credentials/record-updated` subscription. */
+    private recordUpdatedDisposer;
+    readonly typertRemote: TypertRemoteBinding;
+    constructor(ctx: HostContext, store: KeysManagerStore);
+    /**
+     * MF3 load-time hydration: a projection outlives this process — pi-ai
+     * wrote `llm-pi-ai/<provider>` during a previous run and it survived in
+     * the credential store. Match each persisted payload back to an account
+     * row (the exact rule the rotation reconciler applies, via
+     * {@link matchOwningAccount}) so removeAccount / deleteManagedCredentials
+     * demote the projection and `onGrantRecordUpdated` can mark valueMissing
+     * after a restart. An orphan projection — no matching row, e.g. a foreign
+     * or stale grant — is left untouched: the manager never adopts a grant it
+     * does not own, and out-of-band updates keep surfacing the native-
+     * management warning.
+     *
+     * Returns its own completion (round-8 finding I-000108), and the returned
+     * promise is already caught, so a failed hydration degrades to "no owner"
+     * instead of wedging every request. Request attribution does not subscribe
+     * to that promise (round-10 should-fix SF2 — it may stay pending forever);
+     * each request waits on its own provider's landing instead.
+     */
+    private hydrateProjectionOwnership;
+    /**
+     * Record that one provider's hydration read is over — owner or not (SF1) —
+     * and wake the requests waiting on that provider alone (SF2).
+     */
+    private noteProviderHydrated;
+    /** Release every provider's readiness wait when hydration cannot proceed. */
+    private settleHydrationWaits;
+    /**
+     * Wait for one provider's own hydration read to land, at most `ms`, and
+     * report whether it landed.
+     *
+     * Registers exactly one waiter entry for this wait and removes it when the
+     * wait ends either way (round-10 should-fix SF2): nothing is attached to the
+     * shared hydration promise, so a read that never settles cannot retain one
+     * reaction per request. A late landing still wakes the wait through
+     * {@link noteProviderHydrated}, and the generation guard in
+     * {@link hydrateProjectionOwnership} still decides whether its result lands
+     * (I-000108).
+     */
+    private waitForProviderHydration;
+    /**
+     * Live per-provider waiter entries. A documented internal counter for the
+     * round-10 SF2 invariant: a wait that ended must leave no entry behind, so
+     * this never grows with the number of timed-out requests.
+     */
+    private hydrationWaiterCount;
+    /**
+     * Wait (bounded) until projection-ownership hydration can attribute this
+     * request, and report whether it did.
+     *
+     * A provider without OAuth rows can never own a projection, so it never
+     * waits — a stalled read for some other provider must not delay it
+     * (round-9 should-fix: this used to gate every managed provider, API-key-
+     * only ones included).
+     *
+     * Returns false when the bound elapsed first. The caller then treats
+     * attribution as unknown (no owner) and keeps key state untouched: a
+     * projection may still be serving, and selecting/mutating a key here would
+     * repeat the I-000108 corruption. The hydration promise is not cancelled,
+     * so a late result still lands under the generation guard and later
+     * requests are attributed normally.
+     *
+     * Readiness is decided PER PROVIDER (round-10 should-fix SF1). Hydration
+     * writes owners progressively, so racing the one global promise would
+     * discard an owner this provider already confirmed just because another
+     * provider's read stalled. A provider whose own read has landed — with an
+     * owner or with none — is ready without waiting, and the "unknown" fallback
+     * is confined to the requested provider's own unresolved read.
+     */
+    private awaitProjectionOwnership;
+    /**
+     * Record that a newly committed grant became the provider's projection and
+     * return that projection's generation (round-6 finding SF1).
+     *
+     * The bump happens at the moment the projection is observable — pi-ai's
+     * committed grant at the settlement broadcast, or a manager-side
+     * re-projection (activation, rotation reconcile, harvest claim) — so every
+     * failure stamped afterwards belongs to that projection. It must never be
+     * deferred to a later bookkeeping step: the harvest waits behind the
+     * mutation queue and the projection read while the new grant already
+     * serves, and a failure landing there must not be mistaken for the
+     * previous grant's.
+     */
+    private noteProjectionCommitted;
+    /**
+     * Claim the projection owner for one account row, bumping the provider's
+     * ownership generation so an in-flight hydration read of an older state
+     * is discarded instead of overwriting the claim (round-3 finding 3).
+     */
+    private claimProjectionOwner;
+    /**
+     * Log without ever echoing secret material. */
+    warn(message: string): void;
+    /** Rebuild the broker-reference → provider index. */
+    private rebuildBrokerMap;
+    /** Serialize mutations, rejecting submissions that arrive during shutdown. */
+    private run;
+    /**
+     * Periodically drop expired transient state: retry pins after `PIN_TTL_MS`,
+     * the remaining attempt/step records after `ATTEMPT_TTL_MS`.
+     */
+    pruneTransient(now?: number): void;
+    /** Stop accepting mutations, drain the queue, then persist the final snapshot. */
+    close(): Promise<void>;
+    /** Push a user-facing warning that rides the next state response. */
+    private pushWarning;
+    private takeWarnings;
+    /** Current settings service, if the composition mounted one. */
+    private settingsService;
+    /** Current raw credential provider. */
+    private credentialsRaw;
+    /**
+     * The credential store's record half, reached through the raw provider:
+     * the broker wrappers only ever replace the reference methods, so the
+     * record methods of the mounted credential provider are always intact on
+     * the raw instance. `llm-pi-ai` writes its grants through exactly these
+     * methods, so the manager's activation projection must use them too.
+     */
+    private credentialRecords;
+    /**
+     * Resolve the OAuth authorization flow one provider offers.
+     *
+     * The flow key format is pinned by `llm-pi-ai/login.ts:149-171` +
+     * `auth.ts:29,36-38`: `recordKeyFor(providerId)` = `llm-pi-ai/<providerId>`,
+     * with the oauth method offered first (`login.ts:40-47`). A provider with
+     * no such flow (not OAuth-capable, or not installed) resolves to
+     * undefined, which callers must treat as "sign-in unavailable".
+     *
+     * Availability is read from the live seam on every call, never cached:
+     * the authorization service may mount after this plugin, so a route whose
+     * flow is not enumerable yet stays account-unsupported until the flow list
+     * exists (the client re-reads state after that ordering settles).
+     */
+    oauthFlowFor(provider: string): {
+        key: string;
+        method: string;
+    } | undefined;
+    /**
+     * C6-2: can this route's OAuth sign-in actually begin right now? Account
+     * capability is gated on this instead of the catalog's `nativeAuth.oauth`
+     * flag alone, so a route without a registered pi-ai flow never offers an
+     * Add account that would fail. The check is lazy — see {@link oauthFlowFor}.
+     */
+    private oauthFlowAvailable;
+    /**
+     * Warn once per channel: a lost subscription silently disables a whole
+     * feature (harvest never runs; rotations never sync), so the degradation
+     * must be observable instead of indistinguishable from success.
+     */
+    private warnSubscriptionLost;
+    /**
+     * Subscribe to the seam's settled broadcast (authorization/src/index.ts:57,
+     * :337-351). A settled attempt for a key this service is driving harvests
+     * the committed grant; everything else is ignored — another surface's
+     * sign-in is that surface's business, and the grant it leaves behind is
+     * reconciled through `credentials/record-updated` instead.
+     */
+    private watchAuthorizationSettled;
+    /** One settled broadcast: finalize the matching attempt, harvest on success. */
+    private onAuthorizationSettled;
+    /**
+     * Start one interactive OAuth sign-in. Returns immediately with the
+     * attempt view; the attempt walks `pending → (prompt ⇄ pending) →
+     * ready | failed | cancelled`, and every transition is observable through
+     * {@link getAccountAttempt} / {@link listAccountAttempts}.
+     */
+    beginAccountLogin(provider: string, alias?: string, targetAccountId?: string): Promise<AccountAttemptView>;
+    /** Resolve the attempt's parked prompt with the human's answer. */
+    answerAccountPrompt(attemptId: string, value: string): Promise<void>;
+    /** One attempt's serializable view, or undefined when unknown. */
+    getAccountAttempt(attemptId: string): AccountAttemptView | undefined;
+    /** Remote: poll one attempt's serializable state (T3 dialog channel). */
+    accountAttempt(attemptId: string): AccountAttemptView | undefined;
+    /** Every attempt, newest first, for T3 surfaces. */
+    listAccountAttempts(): AccountAttemptView[];
+    /**
+     * Detach the parked prompt. With a reason the flow's awaited promise is
+     * rejected too — a parked prompt dropped un-rejected would leave the
+     * seam's flow (and the provider's single-flight slot) wedged until its
+     * own timeout, so every attempt-ending path passes one.
+     */
+    private dropPrompt;
+    /** Finalize an attempt with a terminal status exactly once. */
+    private finishLoginAttempt;
+    /** Finalize an attempt as failed with the given reason. */
+    private failLoginAttempt;
+    /**
+     * Turn a committed sign-in into pool state: persist the grant pi-ai wrote
+     * to `llm-pi-ai/<provider>` according to the settlement-time capture,
+     * under the plugin-scope account ref, and upsert the `kind: 'oauth'` row.
+     * Any failure fails the attempt loudly — a login whose grant could not be
+     * captured must not look like success.
+     *
+     * `committed` is the F2 provenance promise started by
+     * {@link captureSettledProjection}: the projection payload observed at the
+     * settlement broadcast, never a later live read. The harvest persists
+     * exactly that payload and compensation may only revert exactly that
+     * payload, so a foreign grant cannot become this attempt's authority just
+     * because it landed before the queued mutation ran.
+     *
+     * `projectionGeneration` is the generation {@link noteProjectionCommitted}
+     * recorded at that same broadcast (R6-SF1): it names the projection whose
+     * failures own a cooldown, so the stale-window reset below clears only a
+     * window attributed to an OLDER projection.
+     */
+    private harvestLogin;
+    /**
+     * Capture this attempt's committed projection payload (F2 provenance).
+     *
+     * The seam reports `authorized` only after the flow's commit is observed
+     * and still present, so a read STARTED at that broadcast observes the
+     * record this attempt wrote. The read is deliberately not queued on
+     * `run`: a release parked ahead of the harvest must not delay provenance
+     * long enough for a foreign writer to become this attempt's authority.
+     *
+     * The seam offers no writer identity or record version, so this capture is
+     * the closest provenance the manager can obtain: `undefined` means the
+     * committed payload is unknown, and compensation then refuses to touch the
+     * projection instead of guessing. See I-000090 for the seam capability
+     * (compare-and-delete / versioned records) that would make it exact.
+     */
+    private captureSettledProjection;
+    /**
+     * Undo the in-memory half of a harvest whose state document was never made
+     * durable (a rejected `store.flush()` after the mutation resolved).
+     *
+     * Runs synchronously from the failure handler so no queued mutation,
+     * debounced write, or retry can observe — or persist — the rolled-back row
+     * between the rejected flush and this undo. The credential rollback that
+     * follows ({@link compensateFailedFlush}) deletes the grant the row
+     * referenced, so leaving the upsert in memory would make the next
+     * successful flush point at a deleted record.
+     */
+    private undoHarvestRow;
+    /**
+     * Undo the credential writes of a harvest whose state flush rejected.
+     *
+     * Differs from {@link compensateFailedHarvest} in one respect: the row
+     * upsert already happened, so the plugin-scope record cannot simply be
+     * deleted. A same-ref re-authentication overwrote the record the restored
+     * row references, and a changed-ref re-authentication deleted the
+     * superseded generation before the flush failed — both are reverted here,
+     * each write guarded by the exact payload this login committed so a
+     * foreign writer's record is never clobbered. The `llm-pi-ai` projection is
+     * then demoted exactly like any failed harvest (ownership-checked, never a
+     * foreign grant), so no committed credential outlives the rolled-back row
+     * without a pool owner.
+     *
+     * Resolves with the write failures the rollback hit, if any: a refusal to
+     * touch the surface when provenance is unknown is a deliberate skip, not a
+     * failure, but a rejected compensating write means the credential surface
+     * may still hold records the rolled-back row no longer owns. The caller
+     * tags the attempt with {@link FLUSH_ROLLBACK_COMPENSATION_FAILED} so that
+     * state is distinguishable from a clean rollback (each failure is also
+     * warned about here, message by message).
+     */
+    private compensateFailedFlush;
+    /**
+     * Roll a failed harvest back to a clean credential surface: the
+     * plugin-scope grant copy is deleted when it was written; the
+     * `llm-pi-ai` projection is deleted only while it still carries EXACTLY
+     * this login's settlement-time committed payload, so compensation can
+     * never delete a grant another account owns.
+     *
+     * Provenance unknown (the settlement-time capture found no usable record)
+     * refuses both deletions with a warning: without the committed payload
+     * there is no proof of ownership, and deleting "whatever is live" is the
+     * round-4 defect (I-000083).
+     */
+    private compensateFailedHarvest;
+    /**
+     * Delete the `llm-pi-ai` projection only while it still carries exactly
+     * this login's settlement-time committed payload. Shared by the
+     * failed-harvest compensation and the flush-failure rollback.
+     *
+     * Resolves `ok: false` only when the compare/delete writes themselves
+     * rejected; an ownership mismatch is the guard doing its job (the live
+     * record belongs to someone else) and counts as a clean skip.
+     */
+    private revertHarvestProjection;
+    /** Expire wedged sign-ins and drop long-settled attempt records. */
+    private pruneLoginAttempts;
+    /** Keep the attempt cache bounded: evict the oldest settled entries first. */
+    private capLoginAttempts;
+    /**
+     * Subscribe to the credential seam's post-commit record broadcast
+     * (credentials/src/index.ts:271-277; the event carries the key only, so
+     * the handler re-reads the record for its payload).
+     */
+    private watchGrantRecordUpdated;
+    /**
+     * Reconcile one `llm-pi-ai/<provider>` record change with the pool.
+     *
+     * The manager writes this record only through {@link activateAccount}
+     * (D1); pi-ai rewrites it on every lazy refresh and owns every login. A
+     * change whose payload belongs to the active account is a rotation and
+     * syncs back into the owning row; anything else the manager did not write
+     * is native management of the route and surfaces as a warning instead of
+     * being adopted silently.
+     *
+     * C6-1: reconciliation writes a plugin-scope record for the rotated
+     * generation and then mutates the owning row. removeAccount /
+     * releaseProvider mutate the same row but cannot be serialized against
+     * that write — the credential seam offers only a per-record lock
+     * (`modifyRecord`), never a transaction across the record write and the
+     * pool row. So {@link reconcileGrantRecord} revalidates the row immediately
+     * before AND after the awaited write and compensates by deleting the record
+     * it just wrote. An orphan record must never outlive a removed account.
+     *
+     * Round-9 finding P1: two echoes for the same provider can
+     * arrive before the first reconciliation commits. Their write-backs then
+     * race and an out-of-order completion could move the row back onto an
+     * older generation, stranding the newer record outside manager state. The
+     * bodies are therefore chained per provider: one observation's
+     * read → write → commit window is never interleaved with another's, and
+     * {@link reconcileGrantRecord} additionally re-checks that its generation
+     * is still current before committing.
+     */
+    private onGrantRecordUpdated;
+    /**
+     * Append one body to the provider's per-route grant chain and return it.
+     *
+     * The chain is the single serialization point for every operation that can
+     * repoint `row.oauth.grantRef` or reproject the route: the echo reconciler
+     * (round-9 P1 ordering) and, since round-8 finding I-000106, activation.
+     * The stored tail never rejects, so one failed body cannot stop the chain;
+     * callers that must observe the failure await the returned promise (the
+     * fire-and-forget echo caller attaches its own catch).
+     */
+    private scheduleGrantReconciliation;
+    /**
+     * The body of {@link onGrantRecordUpdated}. Pool state is read live, and
+     * every awaited step around the write is guarded by revalidation: a
+     * removal is allowed to complete while the write is in flight.
+     */
+    private reconcileGrantRecord;
+    /**
+     * C6-1 revalidation: the row captured before an awaited credential write
+     * must still be the provider's live row — same object identity, still an
+     * OAuth account. A remove/release landing in between detaches the row
+     * object; object identity is what tells "this account is still there"
+     * apart from "some same-id row was recreated".
+     *
+     * C6-1/I1: a removal that is still IN PROGRESS is not visible through
+     * identity alone. A multi-row release deletes each row's grant first and
+     * the provider record last, and it never splices its rows, so after row X's
+     * grant is deleted the provider record and row X both still look live while
+     * the release awaits later rows. Syncing a rotation into that window would
+     * commit `grantRef = rotatedRef` on a row nothing will serve, and the
+     * release's final provider deletion leaves that record orphaned. The
+     * removal-aware check is {@link retiringAccounts}, set before the removal's
+     * first awaited delete.
+     *
+     * R7-SF3: `valueMissing` is NOT a removal signal — it only says the row is
+     * currently not serving. A demoted row is still managed, and a projection
+     * that reappears for it must be re-adopted (the caller proves the
+     * projection belongs to this row before claiming it). This guard therefore
+     * keeps the credential-write semantics strict: writing to a demoted row is
+     * pointless until the adoption path has cleared the flag.
+     */
+    private accountRowStillCurrent;
+    /**
+     * R7-SF3 adoption proof: the row is live and still managed, whether or not
+     * it is currently serving. "Retiring" (removal in progress) refuses
+     * everything; "demoted" (`valueMissing`) refuses nothing here — the caller
+     * has already proven that the live projection belongs to this exact row
+     * ({@link matchOwningAccount}) and that no newer projection superseded the
+     * observation (generation guard).
+     */
+    private accountRowIsManaged;
+    /**
+     * Round-5 review (R5-MF1): whether a live account row of `provider` still
+     * names `ref` as its grant. The settled harvest can adopt the generation a
+     * reconciliation just wrote while that reconciliation is still awaiting its
+     * staleness probe — the row's `grantRef` then IS the record the cleanup
+     * would delete, so deleting it destroys the account's own live grant.
+     * A row already marked for removal does not count: its removal deletes the
+     * refs it names, so keeping the record would strand it instead.
+     */
+    private grantRefServed;
+    /**
+     * Delete a rotation record a reconciliation wrote but must not keep, unless
+     * a live row already serves it (R5-MF1). Cleanup is best-effort with a
+     * warning, exactly like the harvest-time superseded-record cleanup.
+     */
+    private discardRotationRecord;
+    /**
+     * Round-9 P1 revalidation: the generation a reconciliation observed is
+     * still the one the route holds, and the ownership claim this body made (if
+     * any) is still the newest. Two independent writes can supersede it while
+     * the plugin-scope write-back is in flight: pi-ai refreshing again (the
+     * projection's refresh digest — the ref's identity — moves on) and an
+     * activation or login claiming the projection (the ownership generation
+     * moves). Committing the older ref in either case would move the row
+     * backwards and strand the newer record outside manager state.
+     *
+     * A failed re-read cannot prove staleness, so it must not block the sync:
+     * the commit then proceeds exactly as it did before this guard existed.
+     */
+    private rotationStillCurrent;
+    /**
+     * Make one account's grant payload the route's stored credential
+     * (D1 activation projection).
+     *
+     * Round-8 finding I-000106 (must-fix): the decide snapshot used to be read
+     * before the seam's lock, and `reconcileGrantRecord` runs OUTSIDE the
+     * mutation queue — so a rotation echo could repoint `row.oauth.grantRef` and
+     * delete the record being projected between the read and the write, leaving
+     * the route on an older generation than the row names. The whole
+     * read → project → claim section therefore runs on the provider's grant
+     * chain ({@link scheduleGrantReconciliation}) — the same chain the
+     * reconciler bodies use. A rotation committed before this body is observed
+     * in `row.oauth.grantRef`; one that arrives while the body runs is queued
+     * behind it and reconciles the generation this body projected. Either way
+     * the projection holds exactly the generation the row names.
+     *
+     * The seam's per-key lock still serializes the read-decide-replace steps of
+     * `modifyRecord` (credentials/src/index.ts:236-250) against other writers.
+     * The account whose payload lands becomes the pool's active account and is
+     * cascade-selectable again.
+     */
+    activateAccount(provider: string, accountId: string): Promise<StateView>;
+    /**
+     * Demote the cascade to the key pool by deleting the projection record:
+     * pi-ai's per-request resolution prefers the stored credential and only
+     * falls through to the broker `apiKeyEnv` when none is stored
+     * (research, resolve.js:26-55).
+     *
+     * Recovery is deliberately manual: the cooled account stays demoted until
+     * the user re-activates it or signs in again. An automatic re-activation
+     * on cooldown expiry would replay the failing grant every request; the
+     * user (who can see whether the account recovered upstream) is the
+     * arbiter. `fallbackToKeys` marks every account row value-missing so the
+     * live arbitration — projection presence plus probe fail-skip over a
+     * kind-agnostic cursor ring — keeps serving only real candidates.
+     *
+     * `accountId` names the row whose failure triggers this demotion (R7-MF).
+     * It is resolved when the queued body runs, so the demotion deletes only a
+     * projection that still belongs to THAT row: activating another account
+     * while the failing request is in flight must not lose the new account's
+     * healthy projection.
+     *
+     * R14-M3: the targetless form (omitted `accountId`) is TEST-ONLY. It
+     * resolves the provider's active account when the queued body runs — the
+     * same execution-time race R7-MF removed from the failure path — so it is
+     * kept only because the tests drive the demotion without a failure event.
+     * Production callers must name the row; the failure path always passes
+     * `key.id`.
+     */
+    fallbackToKeys(provider: string, accountId?: string): Promise<void>;
+    /**
+     * Atomic decide-and-delete of the `llm-pi-ai/<provider>` projection for one
+     * row (round-3 finding 1): the payload compare runs INSIDE the credential
+     * seam's per-key lock — `modifyRecord` hands `mutate` the record as it
+     * stands while the write is exclusive, so a native sign-in that already
+     * replaced the projection is visible here and the delete is skipped. The
+     * seam exposes no delete-inside-modify primitive: a `mutate` may only
+     * return a replacement or `undefined` (leave untouched), and calling
+     * `deleteRecord` inside the mutate would deadlock the provider's own
+     * serialized operation queue (credentials-local `enqueue`). The closest
+     * equivalent — the exact primitives this method uses — are a decide-only
+     * modify (returns `undefined`, no write) and a second pre-delete re-read
+     * against the decided-against snapshot ({@link projectionStillMatches},
+     * F2 step-1 hardening): a native writer landing between the decide and
+     * the delete is therefore visible before the delete runs, and its grant
+     * survives. The residual window is the sub-microtask gap between the
+     * re-read releasing the lock and the delete's own queue entry; a native
+     * writer landing there is still deleted, because closing that gap needs a
+     * compare-and-delete primitive the seam does not expose (store issue
+     * I-000090). `tests/host.test.ts` ("a native grant landing after the final
+     * comparison is still lost") pins that exact outcome so the seam fix has a
+     * test to flip.
+     *
+     * This is the only delete authority: a natively replaced grant — another
+     * account signed in, a native api-key record, an unrecognized payload —
+     * never matches and must survive the demotion of a stale row, and the
+     * async hydration window must not decide ownership (round-2 review,
+     * steps 1–2).
+     */
+    private decideAndDeleteProjection;
+    /**
+     * F2 pre-delete re-read, shared by the demotion and harvest-compensation
+     * decide-then-delete pairs: `true` while the live projection still holds
+     * exactly the decided-against payload. Runs inside `modifyRecord`'s
+     * per-key lock (the same primitive as the decide), so a native writer
+     * that already replaced the record is visible here and the delete is
+     * skipped instead of destroying the foreign grant. The lock is released
+     * before the delete, so a writer landing in that final gap is still lost:
+     * closing it needs the seam's compare-and-delete (store issue I-000090).
+     */
+    private projectionStillMatches;
+    /**
+     * The fallback body; callers own the mutation queue. `target` narrows the
+     * ownership check to one explicit row: removal call sites pass the removed
+     * row object, the failure path passes the failing row's id (R7-MF) — an
+     * id is re-resolved here because the failure's demotion is queued and the
+     * row object may be detached by the time it runs. Without a target the
+     * provider's active account decides.
+     */
+    private fallbackToKeysUnqueued;
+    /**
+     * Drop one OAuth account's plugin-scope grant payload and — only while
+     * this row still owns the live projection — demote the cascade to the key
+     * pool first, so the route falls through to the API-key pool instead of
+     * serving a grant whose owning row is gone. The demotion re-reads
+     * `llm-pi-ai/<provider>` inside this mutation and runs it through the
+     * ownership oracle ({@link matchOwningAccount}); a natively replaced
+     * projection (another account signed in, a native api-key record) is left
+     * untouched. Non-oauth rows are a no-op; every OAuth-removal call site
+     * goes through this helper.
+     */
+    private removeOAuthGrant;
+    /**
+     * Drop one account: its plugin-scope grant payload, its row, and — when
+     * it was the active projection — the projection itself, so the route
+     * falls back to the key pool.
+     */
+    removeAccount(provider: string, accountId: string): Promise<StateView>;
+    /** Install the broker layer on one credential provider instance. */
+    attachCredentials(credentials: CredentialsLike): void;
+    /** Restore the credential provider methods when our fiber unloads. */
+    detachCredentials(credentials: CredentialsLike): void;
+    /** Resolve a credential through the unwrapped provider. */
+    private resolveOriginal;
+    /**
+     * Probe one credential reference while distinguishing absence from a
+     * transient credential-store failure. Selection must never persist a
+     * permanent `valueMissing` marker for an error.
+     */
+    private probeKey;
+    /** Write one key literal through the unwrapped provider. */
+    private setOriginal;
+    /**
+     * Remove one key literal through the unwrapped provider. A rejected unset is
+     * only ignored when the credential is confirmed absent; a transient or
+     * permission failure must keep the metadata so a later retry can finish.
+     */
+    private unsetOriginal;
+    /** All settings descriptors, with an explicit unreadable state. */
+    private describeSettings;
+    /** Find one live settings descriptor by entry id. */
+    private namespace;
+    /** Apply one path-addressed settings write through the live revision. */
+    private mutateSettings;
+    /** Prune expired bindings at most once a minute, without a restart. */
+    private pruneBindings;
+    /** Build the complete UI state. */
+    buildState(): StateView;
+    /** Remote: complete manager state. */
+    getState(): StateView;
+    /** Find one directory entry by route id. */
+    private directoryEntry;
+    /**
+     * Classify the live binding. An unreadable settings snapshot is `unknown`,
+     * not a confirmed mismatch: transient settings failures must not disable
+     * key-pool recovery for a provider that is still managed.
+     */
+    private bindingState;
+    /** Candidate credential refs from which an existing key can be imported. */
+    private importRefs;
+    /** Create and store one key record without adding it to a provider. */
+    private createKeyRecord;
+    /** Find the first existing key value worth importing. */
+    private findImport;
+    /** Remote: take over one existing provider route. */
+    adoptProvider(provider: string): Promise<StateView>;
+    /** Discover models for a new extra provider, falling back to the seed catalog. */
+    private discoverModels;
+    /** Remote: install and adopt one extra built-in provider. */
+    addExtraProvider(extraId: string, alias: string, value: string): Promise<StateView>;
+    /** Add one key; caller already owns the mutation queue. */
+    private addKeyLocked;
+    /** Remote: add one key to a managed provider. */
+    addKey(provider: string, alias: string, value: string): Promise<StateView>;
+    /** Remote: rename or pause/resume one key. */
+    updateKey(provider: string, keyId: string, patch: unknown): Promise<StateView>;
+    /** Remote: delete one key, releasing the provider when it was the last one. */
+    deleteKey(provider: string, keyId: string): Promise<StateView>;
+    /** Read one live profile for release-time cleanup decisions. */
+    private profileAt;
+    /** Restore the exact live profile captured before release mutated it. */
+    private restoreProfileSnapshot;
+    /** Remove every managed credential, recording progress before a retry. */
+    private deleteManagedCredentials;
+    /** Restore the provider profile and drop management; caller owns the queue. */
+    private releaseLocked;
+    /** Remote: stop managing a provider and restore its original key reference. */
+    releaseProvider(provider: string): Promise<StateView>;
+    /** Remote: update manager policy. */
+    setSettings(patch: unknown): Promise<StateView>;
+    /**
+     * Serialize the first selection for a sticky session/provider pair so two
+     * concurrent requests cannot advance the cursor and bind different keys.
+     */
+    selectKey(providerId: string, sessionId: string | undefined, step?: {
+        turn: number;
+        step: number;
+    }): Promise<KeySelection>;
+    /** Pin the key a retry must use, scoped to the failing step. */
+    private pinRetry;
+    /** Record the turn/step the agent loop is about to request for one provider. */
+    noteRequestStep(payload: AgentRequestPayload, providerId: string): void;
+    /** Drop one step's retry pin once its attempt settles. */
+    private clearRetry;
+    /** Selection body; callers reach it through {@link selectKey}. */
+    private doSelectKey;
+    /** Record a terminal failure without deciding policy yet. */
+    private recordFailure;
+    /** Record a successful terminal finish. */
+    private recordSuccess;
+    /**
+     * Codex P2: record a projection-served success on the owning account row —
+     * `lastUsedAt`/`totalUses` move and the failure streak resets, symmetric to
+     * the MF2 failure attribution.
+     */
+    private recordProjectionSuccess;
+    /** Mark one key cooling, preserving escalation across recovery windows. */
+    private markFailure;
+    /**
+     * Queue one projection demotion for a failed account and publish its
+     * promise so the request-error handler can wait for the projection to be
+     * gone (round-5 finding C1). `keyId` is the failing row (R7-MF), so the
+     * queued body deletes only a projection that still belongs to it. R14-M1:
+     * both the cooldown-extension branch and the dedupe branch start the
+     * demotion; it is idempotent when the projection is already gone.
+     */
+    private demoteProjection;
+    /**
+     * Wait for any in-flight projection demotion on `providerId` (round-5
+     * finding C1). Resolves immediately when nothing is pending, and always
+     * resolves — the recorded promise already absorbed its own error.
+     */
+    private settleProjectionDemotion;
+    /**
+     * Whether the key pool can serve a request right now (round-5 finding C1):
+     * a selectable non-account row other than `excludeKeyId`. Account rows are
+     * excluded because their reference is not broker-resolvable — only a
+     * projected grant serves them.
+     */
+    private hasFailoverCandidate;
+    /** Prune stale attempt records. */
+    private pruneAttempts;
+    /** Waterfall listener: bind a key to the request and observe its terminal chunk. */
+    streamListener(options: GenerateOptionsLike, next: () => AsyncIterable<StreamChunkLike>): AsyncIterable<StreamChunkLike>;
+    /**
+     * The account row whose grant payload currently IS the live projection,
+     * verified against the provider's rows (MF2/MF3 read side). A stale map
+     * entry (row removed) resolves to null.
+     */
+    private oauthOwnerFor;
+    /** Wrap one managed stream so credential resolution sees this key. */
+    private wrapStream;
+    /**
+     * Delegate recovery to the next agent/request-error listener. Preserve the
+     * current key only when that listener actually requests a retry; a declined
+     * (undefined) recovery is terminal and must still cool the exhausted key.
+     */
+    private delegateAndMaybeCool;
+    /** Record one failed stream attempt for turn/step attribution. */
+    private recordStreamAttempt;
+    /** Consume the stream record linked to this exact failure object. */
+    private takeLinkedAttempt;
+    /** Claim the next unclaimed stream attempt after a step's last sequence. */
+    private claimStreamAttempt;
+    /**
+     * Find a metadata-selectable alternate whose credential actually resolves.
+     * A key whose credential was removed outside the manager must not cause the
+     * current, working key to be cooled and the session rebound.
+     */
+    private findVerifiedAlternate;
+    /** Waterfall listener: bounded retry, then key switch and cool-down. */
+    requestErrorListener(payload: RequestErrorPayload, next: () => Promise<RequestErrorAction>): Promise<RequestErrorAction>;
+}
+/** Host entry. */
+export declare function apply(ctx: HostContext): void;
+export {};