dsh-keys-manager 0.2.2 → 0.2.3

package/lib/index.d.ts

@@ -240,12 +240,15 @@ export declare class KeysManagerService {
      * 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.
+     * Round-8 finding I-000106 assumed activation would join this chain. It does
+     * not: activation runs its compare-and-write inside the mutation queue turn,
+     * and the only writer of `row.oauth.grantRef` is {@link reconcileGrantRecord},
+     * which runs outside that queue. The fence is therefore a generation re-check
+     * on both sides of the write — before it (the row must still name the
+     * generation that was read) and after it (a rotation commit can land inside
+     * the seam's compare-and-write await, which only reads the projection key).
+     * Chain members are the echo reconciler, the key-test borrow and adoption
+     * classification.
      */
     private readonly grantReconciliations;
     /**
@@ -340,6 +343,20 @@ export declare class KeysManagerService {
     private credentialsMounted;
     /** Providers whose bounded-wait warning already fired (warn once). */
     private readonly hydrationWaitWarned;
+    /**
+     * Stream attempts each provider served without an attributed account
+     * (`I-000120`, D8): the ownership read had not landed, or it had failed.
+     * Counted at the one managed serving site (`wrapStream`), never in the
+     * hydration pass — a failed read serves no request, it only makes later
+     * attempts unattributed. Two earlier branches are outside this definition and
+     * stay uncounted: a provider this manager does not manage (no ownership is
+     * ever asked for) and the `mismatch` profile shape, which hands the request
+     * to pi-ai untouched precisely because this manager's own binding cannot
+     * describe what serves it. Cleared only when a later read decides the route's
+     * attribution; process-local, never persisted and never on the warnings
+     * channel.
+     */
+    private readonly unattributedRequests;
     /** Channels whose lost-subscription warning already fired (warn once). */
     private readonly subscriptionLostWarnings;
     /** Disposer for the `authorization/settled` subscription. */
@@ -470,6 +487,14 @@ export declare class KeysManagerService {
      * previous grant's.
      */
     private noteProjectionCommitted;
+    /**
+     * Whether a claim landed after `generation` was captured. A reconciliation
+     * reads its snapshot before its awaited record read and decides after it, so
+     * an activation (or login) that claimed the route in between owns the answer
+     * now: the stale body must not clear the claim, mark the route foreign, or
+     * re-point the binding. The hydration write uses the same guard.
+     */
+    private ownershipSuperseded;
     /**
      * Claim the projection owner for one account row, bumping the provider's
      * ownership generation so an in-flight hydration read of an older state
@@ -959,24 +984,79 @@ export declare class KeysManagerService {
      * 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.
+     * Plan iter-pool-activate-queue, "Spike outcome" — the contract this method
+     * implements. The slow half (read the row's grant, validate it, capture what
+     * the route serves now) runs outside the mutation queue, so a slow credential
+     * store does not delay unrelated mutations. The mutation queue turn owns every
+     * write:
+     *
+     * 1. admission checks in queue order, which produce this method's error
+     *    surface (`Provider "…" is not managed`, `Account "…" not found on …`,
+     *    `Key "…" is not an OAuth account`, `The credential store does not support
+     *    records`) — plus a re-check that the row still names the generation the
+     *    read used;
+     * 2. the projection write as a compare-and-write under the seam's per-key
+     *    lock (credentials/src/index.ts:236-250): it lands only while the live
+     *    record still equals the captured baseline, "both absent" included. A
+     *    rotation, a removal or any foreign writer that replaced the projection
+     *    meanwhile makes the compare fail, so this call refuses with the retryable
+     *    `could not be projected` message and leaves the newer projection
+     *    untouched — there is nothing to delete, because nothing was written;
+     * 3. the owner claim, the row writes and the returned `buildState`.
+     *
+     * There is deliberately no shutdown check after the write: `close()` awaits
+     * this queue before it closes the store, so a turn that started in time always
+     * finishes (measured in the spike that produced this contract). A check there
+     * is what used to leave an orphan projection behind.
+     *
+     * The one write the turn cannot make durable by itself is a rejected state
+     * flush; see {@link compensateActivationFlush} for that compensation.
      */
     activateAccount(provider: string, accountId: string): Promise<StateView>;
+    /**
+     * The slow half of an activation, outside the queue: read the row's grant
+     * generation, validate it, and capture the projection the route serves now.
+     */
+    private prepareActivation;
+    /** Whether the projection still holds the value this activation read. */
+    private matchesActivationBaseline;
+    /**
+     * Write the projection only while the route still serves the baseline. The
+     * seam's `modifyRecord` mutate body runs under the per-key lock, so this is
+     * the one atomic primitive the activation has (I-000090: `deleteRecord` has
+     * no expected-payload form). Returns the payload written, or `undefined` when
+     * the compare failed and nothing was touched.
+     */
+    private compareAndWriteProjection;
+    /**
+     * Undo one activation whose state flush was rejected: the row this turn
+     * cleared in memory, the owner claim it took, and the projection it wrote
+     * (back to the captured baseline).
+     *
+     * The baseline decides the mechanism. A present baseline is restored with the
+     * same compare-and-write the projection used; only an absent baseline has to
+     * remove a record, and only while that record is still this activation's own
+     * payload. A foreign writer's record is never deleted.
+     */
+    private compensateActivationFlush;
+    /** Put the route's owner classification back to a captured snapshot. */
+    private applyActivationClassification;
+    /** Put the projection back to the present baseline, if it is still ours. */
+    private restoreActivationProjection;
+    /**
+     * The delete authority's proof for an activation's own projection, as an
+     * explicit three-valued answer (QC R2): only `matches` may authorize touching
+     * the record. `unknown` is a store failure — a closed seam, an unreadable
+     * record — and proves nothing, so it is never permission.
+     */
+    private activationProjectionProof;
+    /**
+     * Delete one projection an activation just proved it still owns, through the
+     * same guarded shape the demotion path uses (MF2): the intentional-removal
+     * marker is armed before the delete, so the deletion's own echo is read as
+     * ours instead of as an out-of-band removal.
+     */
+    private deleteActivationProjection;
     /**
      * Remote: send one minimal request with the selected key or account row.
      *
@@ -1344,6 +1424,12 @@ export declare class KeysManagerService {
     private mutateSettings;
     /** Prune expired bindings at most once a minute, without a restart. */
     private pruneBindings;
+    /**
+     * Project one provider's unattributed-request count into its row. Additive
+     * and optional (`I-000120`): a row with no count spreads nothing, so an
+     * older snapshot and a healthy store render exactly as before.
+     */
+    private unattributedView;
     /** Build the complete UI state. */
     buildState(): StateView;
     /**