@cortexkit/claustrum-client 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -3,5 +3,5 @@ export { storeIdentity, storageFingerprint } from './identity.js';
 export { writeEnrollmentTokenFile, type EnrollmentTokenFile, } from './enrollment.js';
 export { MANIFEST_LOCK, manifestLockQuarantinePrefix, withManifestLock, writeHandleFileLocked, type ManifestHandleAccount, type ManifestHandleFile, type ManifestHandleProvider, type ManifestLockError, type ManifestLockErrorCode, } from './manifest-lock.js';
 export { ClaustrumCredentialError, credentialErrorAction, ERROR_CLASS_WIRE_SET, type ClaustrumCredentialErrorAction, type ClaustrumCredentialErrorClass, } from './errors.js';
-export { ClaustrumClient, type ClaustrumClientOptions, type ClaustrumConnector, type ClaustrumReporterSource, type CredentialStatus, type EnrollmentPollOutcome, type ScopedInventoryRow, type ServedCredential, } from './wire.js';
+export { ClaustrumClient, type ClaustrumClientOptions, type ClaustrumConnector, type ClaustrumReporterSource, type CredentialStatus, type EnrollmentPollOutcome, type ScopedInventory, type ScopedInventoryRow, type ServedCredential, } from './wire.js';
 export { HANDLE_FILE_CONTRACT, HandleFileValidationError, credentialIdMatchesProvider, defaultHandleFilePath, handleFileRevision, identifierIsValid, parseHandleFile, readHandleFile, type HandleAccount, type HandleFileIo, type HandleProvider, type OpenCodeHandleFileV1, } from './handles.js';

package/dist/wire.d.ts

@@ -63,7 +63,7 @@ export declare class ClaustrumClient {
      * `params` is `{}` and must be PRESENT: the vault rejects an absent or null params
      * object, so a caller cannot ask a different question by omitting it.
      */
-    listScoped(enrollmentToken?: string): Promise<readonly ScopedInventoryRow[]>;
+    listScoped(enrollmentToken?: string): Promise<ScopedInventory>;
     /**
      * Fetch by credential id, authorized by a grant rather than a bearer handle.
      *
@@ -121,9 +121,19 @@ export declare class ClaustrumClient {
         requestId: string;
         requestSecret: string;
     }): Promise<EnrollmentPollOutcome>;
-    /** Exchange a live token for its successor. The old token dies when the new one is issued. */
+    /**
+     * Exchange a live token for its successor. The old token dies when the new one is issued.
+     *
+     * `expectedTokenGeneration` IS REQUIRED AND IS A FENCE, not bookkeeping: it must be the
+     * generation this caller currently holds. Two rotations racing — a retry after an
+     * uncertain reply, or two instances of the same consumer — would otherwise each mint a
+     * successor and each invalidate the other's, leaving a consumer holding a token the
+     * vault has already replaced. The vault refuses a rotation whose expectation does not
+     * match, so the loser learns it lost instead of discovering it on a later spend.
+     */
     enrollRotate(input: {
         token: string;
+        expectedTokenGeneration: number;
     }): Promise<{
         token: string;
         tokenGeneration: number;
@@ -133,11 +143,20 @@ export declare class ClaustrumClient {
 /**
  * A row from the caller's own grant-covered inventory.
  *
- * `serves` is the ROUTING AXIS, not the id spelling. `apikey:openrouter` and
- * `antigravity:google` both serve Anthropic models and contain no "anthropic"
- * anywhere in their ids, so a consumer that filters on the id segment silently
- * drops working accounts. Measured on a live vault: 8 Anthropic-capable rows, 3 of
- * them invisible to an id-substring filter.
+ * TWO SELECTION AXES, AND THEY ANSWER DIFFERENT QUESTIONS. Pick by what you are about
+ * to do with the token:
+ *
+ * - `refreshAdapter` — whose PROTOCOL the credential speaks. Use it when the token
+ *   goes to a provider's own endpoints. Anything else is invalid there.
+ * - `serves` — which model VENDORS are reachable through it. Use it when choosing
+ *   where a model can be served from, and the protocol is not yours to care about.
+ *
+ * Never the id spelling, in either case: on a live vault 8 rows serve Anthropic models
+ * and 3 of them contain no "anthropic" anywhere in their id.
+ *
+ * An earlier version of this comment called `serves` "the routing axis" full stop. That
+ * was written before `refreshAdapter` existed and is wrong for the protocol-native case:
+ * it would send a Claude OAuth request to `apikey:openrouter`.
  */
 export interface ScopedInventoryRow {
     readonly id: string;
@@ -167,6 +186,18 @@ export interface ScopedInventoryRow {
     readonly email?: string;
     readonly orgName?: string;
 }
+/**
+ * An inventory reply: the covered rows, plus the cursor that says whether they moved.
+ *
+ * `view` is a DIGEST OVER WHAT THIS CALLER CAN SEE — ids, categories, state, operations —
+ * and deliberately NOT over `record_version`, so a routine token refresh does not move it.
+ * Compare it against the previous call's to decide whether to reconcile at all; it is an
+ * opaque string and nothing but equality is defined on it.
+ */
+export interface ScopedInventory {
+    readonly rows: readonly ScopedInventoryRow[];
+    readonly view: string;
+}
 /** What a poll found. `pending` is not an error: the operator has not decided yet. */
 export type EnrollmentPollOutcome = {
     readonly status: 'pending';

package/dist/wire.js

@@ -220,9 +220,21 @@ export class ClaustrumClient {
         });
         return decodeEnrollmentPoll(response, this.#logger);
     }
-    /** Exchange a live token for its successor. The old token dies when the new one is issued. */
+    /**
+     * Exchange a live token for its successor. The old token dies when the new one is issued.
+     *
+     * `expectedTokenGeneration` IS REQUIRED AND IS A FENCE, not bookkeeping: it must be the
+     * generation this caller currently holds. Two rotations racing — a retry after an
+     * uncertain reply, or two instances of the same consumer — would otherwise each mint a
+     * successor and each invalidate the other's, leaving a consumer holding a token the
+     * vault has already replaced. The vault refuses a rotation whose expectation does not
+     * match, so the loser learns it lost instead of discovering it on a later spend.
+     */
     async enrollRotate(input) {
-        const response = await this.#call('auth.enroll_rotate', { token: input.token });
+        const response = await this.#call('auth.enroll_rotate', {
+            token: input.token,
+            expected_token_generation: input.expectedTokenGeneration,
+        });
         const result = decodeEnrollmentResult(response, this.#logger);
         const token = result.token;
         const generation = result.token_generation;
@@ -313,7 +325,14 @@ function decodeScopedInventory(response, logUnknownClass) {
     const rows = result?.credentials;
     if (!Array.isArray(rows))
         throw asCredentialError(response, 'invalid_response', logUnknownClass);
-    return rows.map((row) => {
+    // THE CURSOR IS NOT OPTIONAL. Dropping it silently, as this decoder did in 0.2.0, leaves
+    // a consumer unable to tell "nothing changed" from "I did not ask", so it reconciles
+    // every poll or not at all.
+    const view = result?.view;
+    if (typeof view !== 'string' || view.length === 0) {
+        throw asCredentialError(response, 'invalid_response', logUnknownClass);
+    }
+    const decoded = rows.map((row) => {
         if (!isRecord(row))
             throw asCredentialError(response, 'invalid_response', logUnknownClass);
         const recordVersion = asRecordVersion(row.record_version);
@@ -370,6 +389,7 @@ function decodeScopedInventory(response, logUnknownClass) {
             orgName: row.org_name,
         };
     });
+    return { rows: decoded, view };
 }
 function decodeEnrollmentResult(response, logUnknownClass) {
     if (hasCredentialError(response))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cortexkit/claustrum-client",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "license": "MIT",
   "repository": {
     "type": "git",