@cortexkit/common-auth 0.24.0 → 0.26.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -97,8 +97,9 @@ function applyHeaderEditsTo(target, edits) {
97
97
  * whether output has started and when the response ended, attributed to
98
98
  * an attempt by the rules below;
99
99
  * - `retry` asks the host to retry at once when an account was refused
100
- * before any output, so `model.request` runs again and can pick another
101
- * account, and refuses to retry once output has started.
100
+ * before any output and `chooseAccount` names another account for the
101
+ * next attempt, keeps the host's decision when the refused account was the
102
+ * last one that can serve, and refuses to retry once output has started.
102
103
  *
103
104
  * Attribution. A send belongs to the attempt named by the mark
104
105
  * `model.request` left on it, so several attempts of one session and kind
@@ -159,6 +160,42 @@ export async function installOpenCode2Auth(ctx, adapter, options = {}) {
159
160
  catch { }
160
161
  };
161
162
  const describe = (error) => error instanceof Error ? error.message : String(error);
163
+ // Adapter choices may enqueue work by session. Serialize their consumption
164
+ // and release so a new choice cannot overtake cleanup, even after forgetting.
165
+ const choiceWork = new Map();
166
+ const inChoiceOrder = (sessionID, run) => {
167
+ const result = (choiceWork.get(sessionID) ?? Promise.resolve()).then(run);
168
+ const settled = result.then(() => { }, () => { });
169
+ choiceWork.set(sessionID, settled);
170
+ void settled.then(() => {
171
+ if (choiceWork.get(sessionID) === settled)
172
+ choiceWork.delete(sessionID);
173
+ });
174
+ return result;
175
+ };
176
+ const afterChoiceWork = (sessionID, run) => {
177
+ const pending = choiceWork.get(sessionID);
178
+ return pending ? pending.then(() => afterChoiceWork(sessionID, run)) : run();
179
+ };
180
+ const releaseChoice = async (next) => {
181
+ try {
182
+ await adapter.dropChoice?.({ ...next.input, accountId: next.accountId });
183
+ }
184
+ catch (error) {
185
+ warn('opencode2 auth dropChoice threw; the request is unaffected', {
186
+ sessionID: next.input.sessionID,
187
+ error: describe(error),
188
+ });
189
+ }
190
+ };
191
+ const discardPending = (key) => {
192
+ const pending = pendingRetries.get(key);
193
+ pendingRetries.delete(key);
194
+ if (pending?.next) {
195
+ const next = pending.next;
196
+ void inChoiceOrder(pending.sessionID, () => releaseChoice(next));
197
+ }
198
+ };
162
199
  const emit = async (event, payload) => {
163
200
  const set = listeners.get(event);
164
201
  if (!set || set.size === 0)
@@ -204,11 +241,12 @@ export async function installOpenCode2Auth(ctx, adapter, options = {}) {
204
241
  /** The attempts of one session and kind, oldest first. */
205
242
  const attemptsOf = (key) => [...attempts.values()].filter((rec) => rec.key === key);
206
243
  const newestOf = (key) => attemptsOf(key).at(-1);
207
- /** Forgets an attempt, and its key's pending retry once nothing else holds the key. */
244
+ /** Forgets an attempt and any pending retry it owns, or whose key is no longer held. */
208
245
  const drop = (rec) => {
209
246
  attempts.delete(rec.id);
210
- if (!attemptsOf(rec.key).length)
211
- pendingRetries.delete(rec.key);
247
+ if (pendingRetries.get(rec.key)?.attemptId === rec.id ||
248
+ !attemptsOf(rec.key).length)
249
+ discardPending(rec.key);
212
250
  };
213
251
  const remember = (rec) => {
214
252
  attempts.set(rec.id, rec);
@@ -300,18 +338,31 @@ export async function installOpenCode2Auth(ctx, adapter, options = {}) {
300
338
  };
301
339
  const select = async (scope, hook, assertActive, transport) => {
302
340
  const key = keyOf(scope.sessionID, scope.kind);
303
- const retried = pendingRetries.get(key);
304
- pendingRetries.delete(key);
305
- const previousAccountId = retried?.accountId ?? newestOf(key)?.accountId;
306
- supersede(key);
307
- const input = {
308
- ...scope,
309
- ...(previousAccountId === undefined ? {} : { previousAccountId }),
310
- ...(retried?.rerouteFrom === undefined
311
- ? {}
312
- : { rerouteFrom: retried.rerouteFrom }),
313
- };
314
- const accountId = await adapter.chooseAccount(input);
341
+ const { input, accountId } = await afterChoiceWork(scope.sessionID, async () => {
342
+ assertActive();
343
+ const retried = pendingRetries.get(key);
344
+ pendingRetries.delete(key);
345
+ const previousAccountId = retried?.accountId ?? newestOf(key)?.accountId;
346
+ supersede(key);
347
+ const next = retried?.next;
348
+ const matches = next !== undefined &&
349
+ next.input.modelID === scope.modelID &&
350
+ next.input.agent === scope.agent;
351
+ const input = {
352
+ ...scope,
353
+ phase: 'request',
354
+ ...(previousAccountId === undefined ? {} : { previousAccountId }),
355
+ ...(retried?.rerouteFrom ? { rerouteFrom: retried.rerouteFrom } : {}),
356
+ };
357
+ if (next && !matches) {
358
+ await inChoiceOrder(scope.sessionID, () => releaseChoice(next));
359
+ assertActive();
360
+ }
361
+ const accountId = matches
362
+ ? next.accountId
363
+ : await adapter.chooseAccount(input);
364
+ return { input, accountId };
365
+ });
315
366
  assertActive();
316
367
  let headers = {};
317
368
  let data;
@@ -730,62 +781,130 @@ export async function installOpenCode2Auth(ctx, adapter, options = {}) {
730
781
  }
731
782
  const rec = picked;
732
783
  await withSelection(rec.scope, async (assertActive) => {
784
+ const checkRetryActive = assertActive;
733
785
  rec.judged = true;
734
- let decision = hostDecision;
735
- let reason;
736
- let rerouteFrom;
737
786
  const attempt = rec.attempt;
738
- if (rec.accountId === undefined || !attempt) {
739
- decision = { retry: false };
740
- reason = 'no-account';
741
- }
742
- else if (rec.outputStarted) {
743
- // The user has already seen part of this answer; a retry would
744
- // send it again.
745
- decision = { retry: false };
746
- reason = 'output-started';
747
- }
748
- else {
787
+ if (attempt && !rec.outputStarted) {
749
788
  if (!rec.limit) {
750
789
  const signal = adapter.limitFromError?.(draft.error, attempt);
751
790
  if (signal)
752
791
  noteLimit(rec, signal, 'error');
753
792
  }
754
- // The next `chooseAccount` should see whatever the plugin learnt
755
- // from how this attempt ended.
756
- if (rec.ended) {
793
+ // Account selection must observe all feedback from the refused send.
794
+ if (rec.ended)
757
795
  await rec.ended;
758
- assertActive();
759
- }
760
- if (rec.limit) {
796
+ if (rec.limit)
761
797
  await rec.limit.delivered;
762
- assertActive();
763
- rec.rerouted = true;
764
- rerouteFrom = {
765
- accountId: rec.accountId,
766
- limit: rec.limit.signal,
767
- };
768
- // No delay: the next attempt goes to another account, and the
769
- // host would otherwise wait out the refused account's backoff,
770
- // or not retry at all for errors it deems final.
771
- decision = { retry: true, delay: 0 };
772
- reason = 'reroute';
798
+ }
799
+ checkRetryActive();
800
+ const { decision, reason } = await inChoiceOrder(rec.scope.sessionID, async () => {
801
+ checkRetryActive();
802
+ const old = pendingRetries.get(rec.key);
803
+ pendingRetries.delete(rec.key);
804
+ if (old?.next)
805
+ await releaseChoice(old.next);
806
+ checkRetryActive();
807
+ let decision = hostDecision;
808
+ let reason;
809
+ let rerouteFrom;
810
+ let next;
811
+ if (rec.accountId === undefined || !attempt) {
812
+ decision = { retry: false };
813
+ reason = 'no-account';
814
+ }
815
+ else if (rec.outputStarted) {
816
+ // The user has already seen part of this answer; a retry would
817
+ // send it again.
818
+ decision = { retry: false };
819
+ reason = 'output-started';
773
820
  }
774
821
  else {
775
- reason = 'host-decides';
822
+ if (rec.limit) {
823
+ const refused = {
824
+ accountId: rec.accountId,
825
+ limit: rec.limit.signal,
826
+ };
827
+ // Ask the adapter now, with the same input the next attempt
828
+ // would give it, which account serves that attempt. Rerouting
829
+ // is right only when that is another account: otherwise the
830
+ // next attempt would find no account (a `no-account` refusal
831
+ // the host treats as a defect and does not retry) or go back
832
+ // at once to the account that just refused.
833
+ let accountId;
834
+ const input = {
835
+ ...rec.scope,
836
+ phase: 'retry',
837
+ previousAccountId: rec.accountId,
838
+ rerouteFrom: refused,
839
+ };
840
+ try {
841
+ accountId = await adapter.chooseAccount(input);
842
+ }
843
+ catch (error) {
844
+ // Treated as no other account: the host's own decision
845
+ // stands, and the next attempt asks the adapter again.
846
+ warn('opencode2 auth chooseAccount threw while the retry hook looked for another account; the host decides the retry', {
847
+ sessionID: rec.scope.sessionID,
848
+ error: describe(error),
849
+ });
850
+ }
851
+ if (accountId !== undefined)
852
+ next = { accountId, input };
853
+ try {
854
+ checkRetryActive();
855
+ }
856
+ catch (error) {
857
+ // A selection revoked while the adapter was choosing cannot be used.
858
+ if (next)
859
+ await releaseChoice(next);
860
+ throw error;
861
+ }
862
+ if (accountId !== undefined && accountId !== rec.accountId) {
863
+ rec.rerouted = true;
864
+ rerouteFrom = refused;
865
+ // The next attempt takes this choice rather than asking
866
+ // again, so an account limited between here and the host's
867
+ // retry costs one refused send, which this hook judges
868
+ // again, rather than a `no-account` refusal.
869
+ // No delay: the next attempt goes to another account, and the
870
+ // host would otherwise wait out the refused account's backoff,
871
+ // or not retry at all for errors it deems final.
872
+ decision = { retry: true, delay: 0 };
873
+ reason = 'reroute';
874
+ }
875
+ else {
876
+ // The refused account keeps the host's wait and serves the
877
+ // retry. Undefined or a throw commits nothing: choose later.
878
+ reason = 'host-decides-last-account';
879
+ }
880
+ }
881
+ else {
882
+ reason = 'host-decides';
883
+ }
776
884
  }
777
- }
778
- draft.decision = decision;
779
- // The host's retry runs `model.request` again for this attempt's
780
- // session and kind; that next attempt, and no other attempt of the
781
- // session, is told what this one ended with.
782
- if (decision.retry && rec.accountId !== undefined) {
783
- pendingRetries.set(rec.key, {
784
- sessionID: rec.scope.sessionID,
785
- accountId: rec.accountId,
786
- ...(rerouteFrom === undefined ? {} : { rerouteFrom }),
787
- });
788
- }
885
+ draft.decision = decision;
886
+ // The host's retry runs `model.request` again for this attempt's
887
+ // session and kind; that next attempt, and no other attempt of the
888
+ // session, is told what this one ended with.
889
+ if (decision.retry &&
890
+ rec.accountId !== undefined &&
891
+ attempts.has(rec.id)) {
892
+ pendingRetries.set(rec.key, {
893
+ attemptId: rec.id,
894
+ sessionID: rec.scope.sessionID,
895
+ accountId: rec.accountId,
896
+ ...(rerouteFrom === undefined ? {} : { rerouteFrom }),
897
+ ...(next === undefined ? {} : { next }),
898
+ });
899
+ }
900
+ else if (next) {
901
+ // Only the computed decision is final here: an incoming veto may
902
+ // have been overridden by a reroute to another account.
903
+ await releaseChoice(next);
904
+ }
905
+ return { decision, reason };
906
+ });
907
+ checkRetryActive();
789
908
  await emit('retry', {
790
909
  sessionID: draft.sessionID,
791
910
  ...(rec.accountId === undefined
@@ -815,7 +934,7 @@ export async function installOpenCode2Auth(ctx, adapter, options = {}) {
815
934
  }
816
935
  for (const [key, pending] of pendingRetries) {
817
936
  if (pending.sessionID === sessionID)
818
- pendingRetries.delete(key);
937
+ discardPending(key);
819
938
  }
820
939
  };
821
940
  const abort = new AbortController();
@@ -867,10 +986,12 @@ export async function installOpenCode2Auth(ctx, adapter, options = {}) {
867
986
  for (const rec of attempts.values())
868
987
  abandon(rec, 'the installation was disposed');
869
988
  attempts.clear();
870
- pendingRetries.clear();
989
+ for (const key of pendingRetries.keys())
990
+ discardPending(key);
871
991
  ownedSockets.clear();
872
992
  latestTransportOwned.clear();
873
993
  listeners.clear();
994
+ await Promise.all(choiceWork.values());
874
995
  await Promise.all(registrations.map(async (registration) => {
875
996
  try {
876
997
  await registration.dispose();
@@ -53,6 +53,8 @@ export interface EventVerdict<Q> {
53
53
  */
54
54
  export type HeaderEdits = Readonly<Record<string, string | null>>;
55
55
  export interface ChooseAccountInput extends RequestScope {
56
+ /** Informational: the retry hook's advance choice, or a request's own choice. */
57
+ readonly phase: 'retry' | 'request';
56
58
  /**
57
59
  * The account of the attempt this one retries, when the retry hook just
58
60
  * asked the host to retry an attempt of this session and kind; otherwise
@@ -61,8 +63,9 @@ export interface ChooseAccountInput extends RequestScope {
61
63
  readonly previousAccountId?: string;
62
64
  /**
63
65
  * Set when the attempt this one retries was refused for a limit before any
64
- * output and the retry hook asked the host to try again. The adapter
65
- * should not pick `accountId` again unless it has nothing else.
66
+ * output. The adapter should not pick `accountId` again unless it has
67
+ * nothing else; returning it, or `undefined`, tells the retry hook that no
68
+ * other account can serve, so the host's own retry decision stands.
66
69
  */
67
70
  readonly rerouteFrom?: {
68
71
  readonly accountId: string;
@@ -166,11 +169,32 @@ export interface OpenCode2AuthAdapter<Q = unknown, A = unknown> {
166
169
  /** Every hook is scoped to this provider; other providers are untouched. */
167
170
  readonly providerID: string;
168
171
  /**
169
- * Picks the account for one model request. Called again for every retry,
170
- * so a refused account can be skipped. Returning `undefined` stops the
171
- * request with `OpenCode2AuthError` kind `no-account`.
172
+ * Commits an account for one attempt. An undefined answer commits nothing
173
+ * to routing state: no consumed retry entry, no queued choice, and no session
174
+ * pin created, moved or deleted. Idempotent maintenance (credential refresh
175
+ * to check usability and recording quota readings) is allowed. On a request,
176
+ * undefined stops with kind `no-account`.
177
+ *
178
+ * After a limit before any output, the retry hook makes this call itself,
179
+ * with `phase: 'retry'` and `rerouteFrom` set. Every returned account,
180
+ * including the refused one, is kept for the next attempt of that session
181
+ * and kind: it does not choose again. Another account retries at once;
182
+ * the refused account keeps the host's decision and wait. `undefined` or a
183
+ * throw commits nothing: the host decides, and the next attempt chooses
184
+ * with `phase: 'request'`, `previousAccountId` and no `rerouteFrom`.
172
185
  */
173
186
  chooseAccount(input: ChooseAccountInput): Promise<string | undefined> | string | undefined;
187
+ /**
188
+ * Releases a kept retry choice that will not be used: no retry, a changed
189
+ * model or agent, session forgetting/deletion, disposal or record eviction.
190
+ * Called once with the original choose input plus its returned accountId,
191
+ * never for a used choice. Awaited before any later chooseAccount for the
192
+ * same session; errors are logged and swallowed. A model/agent change
193
+ * releases the old choice before choosing afresh.
194
+ */
195
+ dropChoice?(input: ChooseAccountInput & {
196
+ readonly accountId: string;
197
+ }): Promise<void> | void;
174
198
  /**
175
199
  * The credential and per-account headers for an account, applied in
176
200
  * `model.request`, `http.request` and `experimental.ws.handshake`. The last
@@ -337,7 +361,20 @@ export interface InstallOpenCode2AuthOptions {
337
361
  readonly maxRecords?: number;
338
362
  readonly logger?: OpenCode2AuthLogger;
339
363
  }
340
- export type RetryReason = 'reroute' | 'output-started' | 'no-account' | 'host-decides';
364
+ /**
365
+ * Why the retry hook decided as it did:
366
+ *
367
+ * - `reroute`: refused for a limit before any output, and `chooseAccount`
368
+ * named another account for the next attempt, so the host retries at once;
369
+ * - `output-started`: output had reached the user, so no retry;
370
+ * - `no-account`: the attempt had no account, so no retry;
371
+ * - `host-decides-last-account`: refused for a limit before any output, but
372
+ * no other account can serve the next attempt, so the host's own decision
373
+ * (its wait, or its refusal to retry) stands and the next attempt may go
374
+ * to the refused account again;
375
+ * - `host-decides`: no limit was recognised, so the host's decision stands.
376
+ */
377
+ export type RetryReason = 'reroute' | 'output-started' | 'no-account' | 'host-decides-last-account' | 'host-decides';
341
378
  /**
342
379
  * The hook that picked an account. Normally `model.request`; a transport hook
343
380
  * picks only when the host skipped `model.request` for that request, which a
@@ -0,0 +1,11 @@
1
+ import type { QuotaObservation } from './merge.js';
2
+ export interface QuotaPublication {
3
+ observation: QuotaObservation;
4
+ }
5
+ export interface QuotaField<P extends QuotaPublication> {
6
+ at: number;
7
+ order: number;
8
+ publication: P;
9
+ priorReading?: P;
10
+ }
11
+ export declare function quotaFields<P extends QuotaPublication>(publication: P, witness?: string): Map<string, QuotaField<P>>;
@@ -0,0 +1,48 @@
1
+ // Use the same independently dated parts as mergeQuotaObservation. A header
2
+ // reading cannot erase a poll-only window, counter, credits record or budget.
3
+ export function quotaFields(publication, witness = '') {
4
+ const result = new Map();
5
+ const { observation } = publication;
6
+ const add = (key, at, part) => result.set(`${witness}:${key}`, {
7
+ at,
8
+ order: 0,
9
+ publication: { ...publication, observation: part },
10
+ });
11
+ const keyFor = (scope, label) => JSON.stringify([scope ?? 'all', label]);
12
+ const read = new Set();
13
+ for (const reading of observation.readings ?? []) {
14
+ const key = keyFor(reading.scope, reading.label);
15
+ read.add(key);
16
+ add(key, observation.checkedAt, {
17
+ checkedAt: observation.checkedAt,
18
+ readings: [{ ...reading }],
19
+ });
20
+ }
21
+ for (const pair of observation.coverage ?? []) {
22
+ const key = keyFor(pair.scope, pair.label);
23
+ if (!read.has(key))
24
+ add(key, observation.checkedAt, {
25
+ checkedAt: observation.checkedAt,
26
+ coverage: [{ ...pair }],
27
+ });
28
+ }
29
+ if (observation.budget)
30
+ add('budget', observation.checkedAt, {
31
+ checkedAt: observation.checkedAt,
32
+ budget: { ...observation.budget },
33
+ });
34
+ for (const [name, counter] of Object.entries(observation.counters ?? {})) {
35
+ add(`counter:${name}`, counter.checkedAt, {
36
+ checkedAt: observation.checkedAt,
37
+ counters: { [name]: { ...counter } },
38
+ });
39
+ }
40
+ if (observation.credits)
41
+ add('credits', observation.credits.checkedAt, {
42
+ checkedAt: observation.checkedAt,
43
+ credits: { ...observation.credits },
44
+ });
45
+ if (!result.size)
46
+ add('empty', observation.checkedAt, { checkedAt: observation.checkedAt });
47
+ return result;
48
+ }
@@ -1,7 +1,7 @@
1
1
  import { type MenuTerminal } from '../auth-menu/terminal.js';
2
2
  import type { SetupHost, SetupIO, SetupPlugin } from './types.js';
3
3
  /** Fixed text: no version, host or account detail, so it is safe to print anywhere. */
4
- export declare const UNSUPPORTED_VAULT_MESSAGE = "This Claustrum vault does not support connecting plugins yet, so setup cannot connect to it. Run setup without --claustrum to use local accounts.";
4
+ export declare const UNSUPPORTED_VAULT_MESSAGE = "This Claustrum vault is too old to connect plugins. Run ck upgrade to move to Claustrum v0.2.0 or newer (read \"Upgrading from v0.1.3\" in its release notes first), or run setup without --claustrum to use local accounts.";
5
5
  /**
6
6
  * The longest setup waits, in total, for the vault to create the enrollment
7
7
  * request and for an operator to approve it. It matches the wait setup always
@@ -5,7 +5,7 @@ import { ClaustrumEnrollmentManager, connectClaustrumEnrollmentClient, hostEnrol
5
5
  import { ProcessFenceViolationError, ProcessInspectionError, } from './process-fence.js';
6
6
  const ENROLLMENT_INCOMPLETE_MESSAGE = 'Claustrum enrollment did not complete. Inspect and approve with ck, then rerun setup.';
7
7
  /** Fixed text: no version, host or account detail, so it is safe to print anywhere. */
8
- export const UNSUPPORTED_VAULT_MESSAGE = 'This Claustrum vault does not support connecting plugins yet, so setup cannot connect to it. Run setup without --claustrum to use local accounts.';
8
+ export const UNSUPPORTED_VAULT_MESSAGE = 'This Claustrum vault is too old to connect plugins. Run ck upgrade to move to Claustrum v0.2.0 or newer (read "Upgrading from v0.1.3" in its release notes first), or run setup without --claustrum to use local accounts.';
9
9
  /**
10
10
  * The longest setup waits, in total, for the vault to create the enrollment
11
11
  * request and for an operator to approve it. It matches the wait setup always
@@ -1,4 +1,6 @@
1
+ import { type StoreContext } from './mutate.js';
1
2
  import { type StoreRuntime } from './runtime.js';
3
+ import { type PoolRow } from './schema.js';
2
4
  /**
3
5
  * What a pull or refresh captured about its row (named by id alongside) when
4
6
  * it was issued. A result applies only while the row with that id still has
@@ -20,6 +22,9 @@ export interface Attribution {
20
22
  credentialEpoch: number;
21
23
  identity?: string;
22
24
  }
25
+ export declare function assertQuotaEpoch(id: string, attribution: Attribution): void;
26
+ export declare function assertQuotaRow(id: string, attribution: Attribution, row: PoolRow | undefined): asserts row is PoolRow;
27
+ export declare function mergedQuota(ctx: StoreContext, id: string, stored: unknown, observation: unknown): unknown;
23
28
  /**
24
29
  * Merges a quota observation into a row's stored map under the store locks,
25
30
  * after attribution passes. Needs no row lock, so it is permitted from
@@ -1,8 +1,41 @@
1
1
  import { PoolOperationError } from './errors.js';
2
- import { toFailure, withTransaction } from './mutate.js';
2
+ import { toFailure, withTransaction, } from './mutate.js';
3
3
  import { LockStack } from './refresh-lock.js';
4
4
  import { refusal, requireBound, unknownRow, } from './runtime.js';
5
5
  import { isCredentialEpoch } from './schema.js';
6
+ export function assertQuotaEpoch(id, attribution) {
7
+ if (!isCredentialEpoch(attribution?.credentialEpoch))
8
+ throw refusal('pull', id, 'invalid-input', 'the credential epoch the reading was issued for must be a positive safe integer');
9
+ }
10
+ // Shared by preflight and the locked commit: accepting into memory must never
11
+ // hide a refusal the immediate writer would have returned to its caller.
12
+ export function assertQuotaRow(id, attribution, row) {
13
+ if (!row)
14
+ throw unknownRow('pull', id);
15
+ if (row.invalid)
16
+ throw refusal('pull', id, 'invalid-row', `row ${id} is invalid`);
17
+ if (!row.credential)
18
+ throw refusal('pull', id, 'no-credential', `row ${id} holds no credential`);
19
+ requireBound('pull', row);
20
+ if (row.torn ||
21
+ !row.hasEntry ||
22
+ row.credentialEpoch !== attribution.credentialEpoch ||
23
+ row.identity !== attribution.identity)
24
+ throw new PoolOperationError({
25
+ operation: 'pull',
26
+ rowId: id,
27
+ phase: 'pull',
28
+ retryable: true,
29
+ kind: 'attribution',
30
+ message: `quota for ${id} was issued for a credential the row no longer holds`,
31
+ });
32
+ }
33
+ export function mergedQuota(ctx, id, stored, observation) {
34
+ const merged = ctx.codec.merge(stored, observation);
35
+ if (!ctx.codec.validate(merged))
36
+ throw refusal('pull', id, 'invalid-quota', 'the quota codec rejected the merged map');
37
+ return merged;
38
+ }
6
39
  /**
7
40
  * Merges a quota observation into a row's stored map under the store locks,
8
41
  * after attribution passes. Needs no row lock, so it is permitted from
@@ -13,37 +46,18 @@ export async function recordQuota(rt, id, attribution, observation) {
13
46
  const locks = new LockStack(ctx.lockDefaults, ctx.lockEnv);
14
47
  const progress = { writes: 0 };
15
48
  try {
16
- if (!isCredentialEpoch(attribution?.credentialEpoch))
17
- throw refusal('pull', id, 'invalid-input', 'the credential epoch the reading was issued for must be a positive safe integer');
49
+ assertQuotaEpoch(id, attribution);
18
50
  await withTransaction(ctx, locks, progress, { operation: 'pull', rowId: id }, async (tx) => {
19
51
  tx.assertNotStaged(id);
20
52
  const row = tx.row(id);
21
- if (!row)
22
- throw unknownRow('pull', id);
23
- if (row.invalid)
24
- throw refusal('pull', id, 'invalid-row', `row ${id} is invalid`);
25
53
  // A reading belongs to one (epoch, identity, credential). A row
26
54
  // holding no credential, or torn between the writes of a replace,
27
55
  // has no such triple on disk, so no reading is recorded for it.
28
- if (!row.credential)
29
- throw refusal('pull', id, 'no-credential', `row ${id} holds no credential`);
30
- requireBound('pull', row);
56
+ assertQuotaRow(id, attribution, row);
31
57
  const entry = tx.entry(id);
32
- if (row.torn ||
33
- !entry ||
34
- entry.credentialEpoch !== attribution.credentialEpoch ||
35
- row.identity !== attribution.identity)
36
- throw new PoolOperationError({
37
- operation: 'pull',
38
- rowId: id,
39
- phase: 'pull',
40
- retryable: true,
41
- kind: 'attribution',
42
- message: `quota for ${id} was issued for a credential the row no longer holds`,
43
- });
44
- const merged = ctx.codec.merge(entry.quota, observation);
45
- if (!ctx.codec.validate(merged))
46
- throw refusal('pull', id, 'invalid-quota', 'the quota codec rejected the merged map');
58
+ if (!entry)
59
+ throw unknownRow('pull', id);
60
+ const merged = mergedQuota(ctx, id, entry.quota, observation);
47
61
  tx.setEntry(id, { ...entry, quota: merged, needsFirstReading: false });
48
62
  await tx.commitConfig();
49
63
  },
@@ -16,6 +16,19 @@ export interface OpenPoolStoreOptions {
16
16
  configPath: string;
17
17
  statePath: string;
18
18
  quota: QuotaCodec;
19
+ /**
20
+ * Opt in to detached, coalesced quota publication, with any `quota` codec.
21
+ * Each accepted observation is queued whole for its row and binding, and
22
+ * the queue is applied in arrival order through `quota.merge` under the
23
+ * store locks, so the codec's own merge decides which fields a newer or
24
+ * older reading replaces. Accepted readings appear in read/load
25
+ * immediately, merged the same way; the returned promise still rejects
26
+ * current-row refusals before queueing. Await dispose or close at shutdown
27
+ * to drain.
28
+ */
29
+ coalesceQuota?: boolean;
30
+ /** Bounded quota drain on close/dispose, in milliseconds; defaults to 1,000. */
31
+ quotaDrainTimeoutMs?: number;
19
32
  /**
20
33
  * The codec of the provider state kept beside each row's credential (see
21
34
  * `ProviderStateCodec`). Without it no row shows a provider state, and
@@ -189,6 +202,10 @@ export interface PoolStore {
189
202
  }>;
190
203
  refresh(id: string, provider: ProviderRefresh, options?: RefreshOptions): Promise<RefreshOutcome>;
191
204
  recordQuota(id: string, attribution: Attribution, observation: unknown): Promise<void>;
205
+ /** Drain opted-in quota publication; subsequent coalesced readings refuse. Idempotent. */
206
+ close(): Promise<void>;
207
+ /** Same bounded quota drain as close(). Does not wait for provider pull hooks. */
208
+ dispose(): Promise<void>;
192
209
  /** Fires a pull for a row admission refused for want of a reading. */
193
210
  requestReading(id: string): void;
194
211
  /** Resolves once every pull fired so far has settled. */