@cortexkit/claustrum-client 0.13.0 → 0.14.0

package/README.md

@@ -13,8 +13,8 @@ credential caching, refresh, account scheduling, and retry policy.
   expiry-skew refresh can take seconds. Request paths should peek cached state,
   not call `get` speculatively.
 • `permanent` with `not_found` means the handle is unknown OR revoked — uniform refusal
-  by design (the vault cannot enumerate which). Treat it as gone either way: re-run
-  `ck auth migrate-opencode` to mint a fresh handle; the prior record, if any, is kept.
+  by design (the vault cannot enumerate which). Treat it as gone either way; the
+  prior record, if any, is kept.
 • `auth_required` means the record is latched and needs reauthentication.
 • `statusCredential` on an unknown or revoked handle RESOLVES, it does not throw: it
   returns `ready: false, lastErrorCode: 'not_found'` with `recordVersion`, `credentialId`
@@ -52,6 +52,13 @@ credential caching, refresh, account scheduling, and retry policy.
   before categories existed). Both are `undefined` against a vault too old to send
   them; treat that as unknown, not as zero. A present but malformed value refuses the
   reply like any other malformed field.
+• Since 0.14.0, `reportUsageScoped({ credentialId, reading, enrollmentToken? })`
+  sends fire-and-forget quota readings. `accepted` means queued, never that the
+  usage-processing module insula applied the reading. Coalesce per credential and
+  never await it on a request path.
+  The client leaves reading validation to the vault, which refuses top-level
+  `credentialId` and `vouched` keys and compact JSON readings over 15,360 bytes with
+  `invalid_params`.
 
 The client sends `consumerIdentity: null` for every managed request so inherited
 `SUBC_MODULE_ID` and `SUBC_LAUNCH_NONCE` cannot impersonate a supervising host.

package/dist/enrollment.d.ts

@@ -1,12 +1,7 @@
+import { checkPrivatePath } from './private-path.js';
 export type EnrollmentTokenFile = {
     token: string;
     token_generation: number;
 };
-/**
- * Atomically replace a consumer's enrollment credential.
- *
- * Creation uses owner-only Unix permissions or native Windows ACLs before writing
- * any bytes. @cortexkit/store checks that ancestors cannot be replaced by other
- * users, and on Windows also verifies the completed parent's owner-only ACL.
- */
-export declare function writeEnrollmentTokenFile(path: string, value: EnrollmentTokenFile): Promise<void>;
+export declare function createEnrollmentWriter(checkPath?: typeof checkPrivatePath): (path: string, value: EnrollmentTokenFile) => Promise<void>;
+export declare const writeEnrollmentTokenFile: (path: string, value: EnrollmentTokenFile) => Promise<void>;

package/dist/enrollment.js

@@ -11,53 +11,57 @@ function validateTokenFile(value) {
         throw new Error('enrollment token generation must be a positive safe integer');
     }
 }
-async function refuseWritableAncestor(parent) {
-    const result = await checkPrivatePath(parent);
-    if (!result.ok)
-        throw new Error(notPrivate('enrollment token folder', result));
-}
-/**
- * Atomically replace a consumer's enrollment credential.
- *
- * Creation uses owner-only Unix permissions or native Windows ACLs before writing
- * any bytes. @cortexkit/store checks that ancestors cannot be replaced by other
- * users, and on Windows also verifies the completed parent's owner-only ACL.
- */
-export async function writeEnrollmentTokenFile(path, value) {
-    validateTokenFile(value);
-    path = resolve(path);
-    const parent = dirname(path);
-    // Native Windows creation rejects ancestors that other users can replace. A missing
-    // private parent can be created under a safe but non-private folder; afterwards the
-    // async check also requires the completed parent's protected owner-only ACL.
-    if (process.platform !== 'win32')
+export function createEnrollmentWriter(checkPath = checkPrivatePath) {
+    async function refuseWritableAncestor(parent) {
+        const result = await checkPath(parent);
+        if (!result.ok)
+            throw new Error(notPrivate('enrollment token folder', result));
+    }
+    /**
+     * Atomically replace a consumer's enrollment credential.
+     *
+     * Creation uses owner-only Unix permissions or native Windows ACLs before writing
+     * any bytes. @cortexkit/store checks that ancestors cannot be replaced by other
+     * users, and on Windows also verifies the completed parent's owner-only ACL.
+     */
+    async function writeEnrollmentTokenFile(path, value) {
+        validateTokenFile(value);
+        path = resolve(path);
+        const parent = dirname(path);
+        // Native Windows creation rejects ancestors that other users can replace. A missing
+        // private parent can be created under a safe but non-private folder; afterwards the
+        // async check also requires the completed parent's protected owner-only ACL.
+        if (process.platform !== 'win32')
+            await refuseWritableAncestor(parent);
+        await createPrivateParents(parent);
         await refuseWritableAncestor(parent);
-    await createPrivateParents(parent);
-    await refuseWritableAncestor(parent);
-    const temporary = join(parent, `.${basename(path)}.${process.pid}.${randomBytes(12).toString('hex')}.tmp`);
-    let created = false;
-    try {
-        created = true;
-        try {
-            await createPrivateFile(temporary, `${JSON.stringify(value)}\n`);
-        }
-        catch (error) {
-            if (privateCreationCode(error) === 'EEXIST')
-                created = false;
-            throw error;
-        }
-        const descriptor = await open(temporary, 'r+');
+        const temporary = join(parent, `.${basename(path)}.${process.pid}.${randomBytes(12).toString('hex')}.tmp`);
+        let created = false;
         try {
-            await descriptor.sync();
+            created = true;
+            try {
+                await createPrivateFile(temporary, `${JSON.stringify(value)}\n`);
+            }
+            catch (error) {
+                if (privateCreationCode(error) === 'EEXIST')
+                    created = false;
+                throw error;
+            }
+            const descriptor = await open(temporary, 'r+');
+            try {
+                await descriptor.sync();
+            }
+            finally {
+                await descriptor.close();
+            }
+            await rename(temporary, path);
+            created = false;
         }
         finally {
-            await descriptor.close();
+            if (created)
+                await unlink(temporary).catch(() => undefined);
         }
-        await rename(temporary, path);
-        created = false;
-    }
-    finally {
-        if (created)
-            await unlink(temporary).catch(() => undefined);
     }
+    return writeEnrollmentTokenFile;
 }
+export const writeEnrollmentTokenFile = createEnrollmentWriter();

package/dist/handles.d.ts

@@ -1,3 +1,4 @@
+import { checkPrivatePath } from './private-path.js';
 export declare const HANDLE_FILE_CONTRACT: {
     readonly maxBytes: number;
     readonly mode: 384;
@@ -50,6 +51,7 @@ type HandleFileDescriptor = {
     close(): Promise<void>;
 };
 export type HandleFileIo = {
+    pathOptions?: Parameters<typeof checkPrivatePath>[1];
     stat?: (path: string) => Promise<HandleFileStat>;
     lstat?: (path: string) => Promise<HandleFileStat>;
     readFile?: (path: string, encoding: 'utf8') => Promise<string>;

package/dist/handles.js

@@ -208,10 +208,10 @@ async function readHandleSnapshot(path = defaultHandleFilePath(), io = {}) {
             const value = await io.stat(candidate);
             return { ...value, isDirectory: () => value.isDirectory?.() ?? false };
         });
-        const protection = await checkPrivatePath(process.platform === 'win32' ? path : dirname(path), fixtureStat ? {
+        const protection = await checkPrivatePath(process.platform === 'win32' ? path : dirname(path), io.pathOptions ?? (fixtureStat ? {
             euid: expectedUid,
             fs: { stat: fixtureStat, lstat: fixtureStat },
-        } : undefined);
+        } : undefined));
         if (!protection.ok)
             invalid(notPrivate('handle file folder', protection));
         let source;

package/dist/manifest-lock.d.ts

@@ -1,3 +1,4 @@
+import { checkPrivatePath } from './private-path.js';
 import { type OpenCodeHandleFileV1 } from './handles.js';
 export declare const MANIFEST_LOCK: {
     ttlMs: number;
@@ -14,7 +15,7 @@ export type ManifestLockError = Error & {
 export type ManifestHandleAccount = OpenCodeHandleFileV1['providers'][number]['accounts'][number];
 export type ManifestHandleProvider = OpenCodeHandleFileV1['providers'][number];
 export type ManifestHandleFile = OpenCodeHandleFileV1;
-type TestOptions = {
+type ManifestLockOptions = Readonly<{
     ttlMs?: number;
     renewEveryMs?: number;
     retryMinMs?: number;
@@ -24,9 +25,13 @@ type TestOptions = {
     afterEvictRenameAttempt?: () => Promise<void>;
     afterEvict?: () => void;
     beforeManifestRename?: (path: string) => Promise<void>;
-};
-export declare function __setManifestLockTestOptions(options?: TestOptions): void;
+    checkPath?: typeof checkPrivatePath;
+}>;
 export declare function manifestLockQuarantinePrefix(path: string, basename?: (p: string) => string): string | undefined;
-export declare function withManifestLock<T>(path: string, tenant: string, fn: () => Promise<T> | T): Promise<T>;
-export declare function writeHandleFileLocked(path: string, tenant: string, mutate: (file: ManifestHandleFile) => void | ManifestHandleFile | Promise<void | ManifestHandleFile>): Promise<void>;
+/** Each instance captures its dependencies; callers cannot reconfigure the shared writer. */
+export declare function createManifestLock(options?: ManifestLockOptions): {
+    withManifestLock: <T>(path: string, tenant: string, fn: () => Promise<T> | T) => Promise<T>;
+    writeHandleFileLocked: (path: string, tenant: string, mutate: (file: ManifestHandleFile) => void | ManifestHandleFile | Promise<void | ManifestHandleFile>) => Promise<void>;
+};
+export declare const withManifestLock: <T>(path: string, tenant: string, fn: () => Promise<T> | T) => Promise<T>, writeHandleFileLocked: (path: string, tenant: string, mutate: (file: ManifestHandleFile) => void | ManifestHandleFile | Promise<void | ManifestHandleFile>) => Promise<void>;
 export {};

package/dist/manifest-lock.js

@@ -10,8 +10,6 @@ export const MANIFEST_LOCK = { ttlMs: 30_000, renewEveryMs: 10_000, ownerKeys: [
 // loaded host. The retry deadline and staleness window both read `ttl` today; if they split,
 // this bound must keep their max so reclamation still covers the longer role.
 const MANIFEST_LOCK_QUARANTINE_RECLAIM_MARGIN_MS = 5_000;
-let testOptions;
-export function __setManifestLockTestOptions(options) { testOptions = options; }
 // 16 CSPRNG bytes: a collision needs both the same millisecond and the same nonce. Do not
 // simplify this to a counter, pid+timestamp, or a short token.
 const token = () => randomBytes(16).toString('base64url');
@@ -100,234 +98,236 @@ async function reclaimStaleManifestLockQuarantines(path, ttlMs, claimDeadlineMs)
         await rm(target, { recursive: true, force: true }).catch(() => { });
     }));
 }
-export async function withManifestLock(path, tenant, fn) {
-    return withLockCommit(path, tenant, async () => fn());
-}
-async function withLockCommit(path, tenant, fn) {
-    // Stale-lock eviction renames the lock directory while another process may hold it
-    // open. That is safe under POSIX rename; on Windows CI two evictors both won and a
-    // rename of an open lock failed with EPERM. Until the protocol is proven there,
-    // refuse rather than risk two writers overlapping on the shared handle file.
-    if (process.platform === 'win32')
-        throw unsupportedOnWindows();
-    path = resolve(path);
-    const lock = `${path}.lock`, ownerPath = join(lock, 'owner'), ttl = testOptions?.ttlMs ?? MANIFEST_LOCK.ttlMs, renewEvery = testOptions?.renewEveryMs ?? MANIFEST_LOCK.renewEveryMs, retryMin = testOptions?.retryMinMs ?? 25, retryMax = testOptions?.retryMaxMs ?? 75;
-    const nonce = token(), started = Date.now(), deadline = started + ttl;
-    while (true) {
-        try {
-            await createPrivateDirectory(lock);
-            await writeOwner(lock, { tenant, pid: process.pid, claimed_at_ms: Date.now(), nonce });
-            await testOptions?.afterClaim?.();
-            break;
-        }
-        catch (error) {
-            if (code(error) !== 'EEXIST') {
-                if (code(error) !== 'ENOENT')
-                    await rm(lock, { recursive: true, force: true }).catch(() => { });
-                throw error;
+/** Each instance captures its dependencies; callers cannot reconfigure the shared writer. */
+export function createManifestLock(options = {}) {
+    const settings = Object.freeze({ ...options });
+    const checkPath = settings.checkPath ?? checkPrivatePath;
+    async function withManifestLock(path, tenant, fn) {
+        return withLockCommit(path, tenant, async () => fn());
+    }
+    async function withLockCommit(path, tenant, fn) {
+        // Stale-lock eviction renames the lock directory while another process may hold it
+        // open. That is safe under POSIX rename; on Windows CI two evictors both won and a
+        // rename of an open lock failed with EPERM. Until the protocol is proven there,
+        // refuse rather than risk two writers overlapping on the shared handle file.
+        if (process.platform === 'win32')
+            throw unsupportedOnWindows();
+        path = resolve(path);
+        const lock = `${path}.lock`, ownerPath = join(lock, 'owner'), ttl = settings.ttlMs ?? MANIFEST_LOCK.ttlMs, renewEvery = settings.renewEveryMs ?? MANIFEST_LOCK.renewEveryMs, retryMin = settings.retryMinMs ?? 25, retryMax = settings.retryMaxMs ?? 75;
+        const nonce = token(), started = Date.now(), deadline = started + ttl;
+        while (true) {
+            try {
+                await createPrivateDirectory(lock);
+                await writeOwner(lock, { tenant, pid: process.pid, claimed_at_ms: Date.now(), nonce });
+                await settings.afterClaim?.();
+                break;
             }
-        }
-        let observed, ownerReadError;
-        try {
-            observed = await readOwner(ownerPath);
-        }
-        catch (error) {
-            ownerReadError = error;
-            if (code(error) !== 'ENOENT' && Date.now() >= deadline)
-                throw code(error) === 'owner_invalid' ? error : lockError('lock_busy', 'manifest lock busy');
-        }
-        if (!observed && code(ownerReadError) === 'ENOENT') {
-            const metadata = await lstat(lock).catch(() => undefined);
-            if (metadata?.isDirectory() && Date.now() - metadata.mtimeMs >= ttl) {
-                await testOptions?.beforeEvict?.();
-                const stale = `${lock}.stale-${Math.floor(metadata.mtimeMs)}-${token()}`;
-                try {
-                    await rename(lock, stale);
-                    // A claimant may have published its owner while the eviction was pending.
-                    const moved = await lstat(stale);
-                    const ownerExists = await lstat(join(stale, 'owner')).then(() => true, (error) => code(error) !== 'ENOENT');
-                    if (!ownerExists && moved.mtimeMs === metadata.mtimeMs) {
-                        testOptions?.afterEvict?.();
-                        continue;
-                    }
-                    await rename(stale, lock).catch(() => { });
-                }
-                catch (error) {
-                    if (!['ENOENT', 'EEXIST', 'ENOTEMPTY'].includes(code(error) ?? ''))
-                        throw error;
+            catch (error) {
+                if (code(error) !== 'EEXIST') {
+                    if (code(error) !== 'ENOENT')
+                        await rm(lock, { recursive: true, force: true }).catch(() => { });
+                    throw error;
                 }
             }
-        }
-        if (observed && Date.now() - observed.claimed_at_ms >= ttl) {
-            await testOptions?.beforeEvict?.();
-            // The owner record remains because the quarantine is the ABA guard, not an audit log;
-            // bounded reclamation below is what makes that retention finite.
-            const stale = `${lock}.stale-${observed.claimed_at_ms}-${observed.nonce}`;
-            let renameError;
+            let observed, ownerReadError;
             try {
-                await rename(lock, stale);
+                observed = await readOwner(ownerPath);
             }
             catch (error) {
-                renameError = error;
+                ownerReadError = error;
+                if (code(error) !== 'ENOENT' && Date.now() >= deadline)
+                    throw code(error) === 'owner_invalid' ? error : lockError('lock_busy', 'manifest lock busy');
             }
-            await testOptions?.afterEvictRenameAttempt?.();
-            if (renameError === undefined) {
-                const moved = await readOwner(join(stale, 'owner')).catch(() => undefined);
-                if (moved?.nonce === observed.nonce && moved.claimed_at_ms === observed.claimed_at_ms) {
-                    testOptions?.afterEvict?.();
-                    continue;
+            if (!observed && code(ownerReadError) === 'ENOENT') {
+                const metadata = await lstat(lock).catch(() => undefined);
+                if (metadata?.isDirectory() && Date.now() - metadata.mtimeMs >= ttl) {
+                    await settings.beforeEvict?.();
+                    const stale = `${lock}.stale-${Math.floor(metadata.mtimeMs)}-${token()}`;
+                    try {
+                        await rename(lock, stale);
+                        // A claimant may have published its owner while the eviction was pending.
+                        const moved = await lstat(stale);
+                        const ownerExists = await lstat(join(stale, 'owner')).then(() => true, (error) => code(error) !== 'ENOENT');
+                        if (!ownerExists && moved.mtimeMs === metadata.mtimeMs) {
+                            settings.afterEvict?.();
+                            continue;
+                        }
+                        await rename(stale, lock).catch(() => { });
+                    }
+                    catch (error) {
+                        if (!['ENOENT', 'EEXIST', 'ENOTEMPTY'].includes(code(error) ?? ''))
+                            throw error;
+                    }
                 }
-                await rename(stale, lock).catch(() => { });
             }
-            else if (!['ENOENT', 'EEXIST', 'ENOTEMPTY'].includes(code(renameError) ?? ''))
-                throw renameError;
+            if (observed && Date.now() - observed.claimed_at_ms >= ttl) {
+                await settings.beforeEvict?.();
+                // The owner record remains because the quarantine is the ABA guard, not an audit log;
+                // bounded reclamation below is what makes that retention finite.
+                const stale = `${lock}.stale-${observed.claimed_at_ms}-${observed.nonce}`;
+                let renameError;
+                try {
+                    await rename(lock, stale);
+                }
+                catch (error) {
+                    renameError = error;
+                }
+                await settings.afterEvictRenameAttempt?.();
+                if (renameError === undefined) {
+                    const moved = await readOwner(join(stale, 'owner')).catch(() => undefined);
+                    if (moved?.nonce === observed.nonce && moved.claimed_at_ms === observed.claimed_at_ms) {
+                        settings.afterEvict?.();
+                        continue;
+                    }
+                    await rename(stale, lock).catch(() => { });
+                }
+                else if (!['ENOENT', 'EEXIST', 'ENOTEMPTY'].includes(code(renameError) ?? ''))
+                    throw renameError;
+            }
+            if (Date.now() >= deadline)
+                throw code(ownerReadError) === 'owner_invalid' ? ownerReadError : lockError('lock_busy', 'manifest lock busy');
+            await sleep(Math.min(randomInt(retryMin, retryMax + 1), Math.max(1, deadline - Date.now())));
         }
-        if (Date.now() >= deadline)
-            throw code(ownerReadError) === 'owner_invalid' ? ownerReadError : lockError('lock_busy', 'manifest lock busy');
-        await sleep(Math.min(randomInt(retryMin, retryMax + 1), Math.max(1, deadline - Date.now())));
-    }
-    await reclaimStaleManifestLockQuarantines(path, ttl, deadline - started);
-    let renewal = Promise.resolve(), failed = false, stopped = false;
-    const timer = setInterval(() => { renewal = renewal.then(async () => { if (failed)
-        return; try {
-        const current = await readOwner(ownerPath);
-        if (current.nonce !== nonce || Date.now() - current.claimed_at_ms >= ttl)
-            throw new Error('lease lost');
-        await writeOwner(lock, { ...current, claimed_at_ms: Date.now() });
-    }
-    catch {
-        failed = true;
-    } }); }, renewEvery);
-    timer.unref?.();
-    const commit = async () => { if (!stopped) {
-        stopped = true;
-        clearInterval(timer);
-        await renewal;
-    } ; const current = await readOwner(ownerPath).catch(() => undefined); if (failed || !current || current.nonce !== nonce || Date.now() - current.claimed_at_ms >= ttl)
-        throw lockError('renewal_failed', 'manifest lock renewal failed; write aborted'); };
-    try {
-        const result = await fn(commit);
-        if (failed)
-            throw lockError('renewal_failed', 'manifest lock renewal failed; write aborted');
-        return result;
-    }
-    finally {
-        if (!stopped)
+        await reclaimStaleManifestLockQuarantines(path, ttl, deadline - started);
+        let renewal = Promise.resolve(), failed = false, stopped = false;
+        const timer = setInterval(() => { renewal = renewal.then(async () => { if (failed)
+            return; try {
+            const current = await readOwner(ownerPath);
+            if (current.nonce !== nonce || Date.now() - current.claimed_at_ms >= ttl)
+                throw new Error('lease lost');
+            await writeOwner(lock, { ...current, claimed_at_ms: Date.now() });
+        }
+        catch {
+            failed = true;
+        } }); }, renewEvery);
+        timer.unref?.();
+        const commit = async () => { if (!stopped) {
+            stopped = true;
             clearInterval(timer);
-        await renewal;
-        const current = await readOwner(ownerPath).catch(() => undefined);
-        if (!current || current.nonce !== nonce || Date.now() - current.claimed_at_ms >= ttl)
-            console.warn('manifest lock lease lost, not releasing', { path, tenant });
-        else {
-            const release = `${lock}.release-${nonce}`;
-            try {
-                await rename(lock, release);
-                const moved = await readOwner(join(release, 'owner')).catch(() => undefined);
-                if (!moved || moved.nonce !== nonce || Date.now() - moved.claimed_at_ms >= ttl) {
-                    await rename(release, lock).catch(() => { });
+            await renewal;
+        } ; const current = await readOwner(ownerPath).catch(() => undefined); if (failed || !current || current.nonce !== nonce || Date.now() - current.claimed_at_ms >= ttl)
+            throw lockError('renewal_failed', 'manifest lock renewal failed; write aborted'); };
+        try {
+            const result = await fn(commit);
+            if (failed)
+                throw lockError('renewal_failed', 'manifest lock renewal failed; write aborted');
+            return result;
+        }
+        finally {
+            if (!stopped)
+                clearInterval(timer);
+            await renewal;
+            const current = await readOwner(ownerPath).catch(() => undefined);
+            if (!current || current.nonce !== nonce || Date.now() - current.claimed_at_ms >= ttl)
+                console.warn('manifest lock lease lost, not releasing', { path, tenant });
+            else {
+                const release = `${lock}.release-${nonce}`;
+                try {
+                    await rename(lock, release);
+                    const moved = await readOwner(join(release, 'owner')).catch(() => undefined);
+                    if (!moved || moved.nonce !== nonce || Date.now() - moved.claimed_at_ms >= ttl) {
+                        await rename(release, lock).catch(() => { });
+                        console.warn('manifest lock lease lost, not releasing', { path, tenant });
+                    }
+                    else
+                        await rm(release, { recursive: true, force: true });
+                }
+                catch {
                     console.warn('manifest lock lease lost, not releasing', { path, tenant });
                 }
-                else
-                    await rm(release, { recursive: true, force: true });
-            }
-            catch {
-                console.warn('manifest lock lease lost, not releasing', { path, tenant });
             }
         }
     }
-}
-async function readManifest(path) {
-    let metadata;
-    try {
-        metadata = await lstat(path);
+    async function readManifest(path) {
+        let metadata;
+        try {
+            metadata = await lstat(path);
+        }
+        catch (error) {
+            if (code(error) === 'ENOENT')
+                return { version: 1, providers: [] };
+            throw error;
+        }
+        if (metadata.isSymbolicLink() || !metadata.isFile())
+            throw new Error('handle file must be a regular file');
+        if (process.platform !== 'win32' && (metadata.mode & 0o777) !== HANDLE_FILE_CONTRACT.mode)
+            throw new Error('handle file mode must be exactly 0600');
+        const protection = await checkPath(path);
+        if (!protection.ok)
+            throw new Error(notPrivate('handle file folder', protection));
+        const source = await readFile(path);
+        if (source.byteLength > HANDLE_FILE_CONTRACT.maxBytes)
+            throw new Error('handle file exceeds 256 KiB');
+        return parseHandleFile(JSON.parse(source.toString('utf8')));
     }
-    catch (error) {
-        if (code(error) === 'ENOENT')
-            return { version: 1, providers: [] };
-        throw error;
+    const foreign = (file, tenant) => file.providers.filter((provider) => provider.serve !== tenant).map((provider) => JSON.stringify(provider));
+    async function refuseWritableAncestors(parent) {
+        const protection = await checkPath(parent);
+        if (!protection.ok)
+            throw new Error(notPrivate('handle file folder', protection));
     }
-    if (metadata.isSymbolicLink() || !metadata.isFile())
-        throw new Error('handle file must be a regular file');
-    if (process.platform !== 'win32' && (metadata.mode & 0o777) !== HANDLE_FILE_CONTRACT.mode)
-        throw new Error('handle file mode must be exactly 0600');
-    const protection = await checkPrivatePath(path);
-    if (!protection.ok)
-        throw new Error(notPrivate('handle file folder', protection));
-    const source = await readFile(path);
-    if (source.byteLength > HANDLE_FILE_CONTRACT.maxBytes)
-        throw new Error('handle file exceeds 256 KiB');
-    return parseHandleFile(JSON.parse(source.toString('utf8')));
-}
-const foreign = (file, tenant) => file.providers.filter((provider) => provider.serve !== tenant).map((provider) => JSON.stringify(provider));
-async function refuseWritableAncestors(parent) {
-    const protection = await checkPrivatePath(parent);
-    if (!protection.ok)
-        throw new Error(notPrivate('handle file folder', protection));
-}
-async function prepareParent(path) {
-    const parent = dirname(path);
-    // Check existing ancestors before creating directories under a replaceable tree.
-    if (process.platform !== 'win32')
+    async function prepareParent(path) {
+        const parent = dirname(path);
+        // Check existing ancestors before creating directories under a replaceable tree.
+        if (process.platform !== 'win32')
+            await refuseWritableAncestors(parent);
+        const existing = await stat(parent).catch((error) => { if (code(error) !== 'ENOENT')
+            throw error; return undefined; });
+        if (existing && typeof process.getuid === 'function' && existing.uid !== process.getuid())
+            throw new Error('handle file parent is not owned by the current uid');
+        await createPrivateParents(parent);
+        const metadata = await stat(parent);
+        if (!metadata.isDirectory())
+            throw new Error('handle file parent must be a directory');
+        if (typeof process.getuid === 'function' && metadata.uid !== process.getuid())
+            throw new Error('handle file parent is not owned by the current uid');
         await refuseWritableAncestors(parent);
-    const existing = await stat(parent).catch((error) => { if (code(error) !== 'ENOENT')
-        throw error; return undefined; });
-    if (existing && typeof process.getuid === 'function' && existing.uid !== process.getuid())
-        throw new Error('handle file parent is not owned by the current uid');
-    await createPrivateParents(parent);
-    const metadata = await stat(parent);
-    if (!metadata.isDirectory())
-        throw new Error('handle file parent must be a directory');
-    if (typeof process.getuid === 'function' && metadata.uid !== process.getuid())
-        throw new Error('handle file parent is not owned by the current uid');
-    await refuseWritableAncestors(parent);
-}
-async function writeAtomic(path, file, commit) {
-    const bytes = Buffer.from(JSON.stringify(file));
-    if (bytes.byteLength > HANDLE_FILE_CONTRACT.maxBytes)
-        throw new Error('handle file exceeds 256 KiB');
-    // pathBasename for the same reason the quarantine sweep uses it, but this one fails LOUD
-    // rather than inert: a '/' split over a backslash path yields the whole path, so the temp
-    // name embeds separators and a drive-letter colon, join() nests it under its own directory,
-    // and O_CREAT|O_EXCL throws on a name Windows will not accept -- taking the manifest WRITE
-    // down, not just the reclaim. Covered by the dual-basename test, which a POSIX filesystem
-    // test cannot reach.
-    const temporary = join(dirname(path), `.${pathBasename(path)}.${process.pid}.${token()}.tmp`);
-    let handle;
-    try {
-        await createPrivateFile(temporary, bytes);
-        handle = await open(temporary, 'r+');
-        await handle.sync();
-        await handle.close();
-        handle = undefined;
-        await testOptions?.beforeManifestRename?.(`${path}.lock`);
-        await commit();
-        await rename(temporary, path);
     }
-    finally {
-        await handle?.close().catch(() => { });
-        await unlink(temporary).catch(() => { });
+    async function writeAtomic(path, file, commit) {
+        const bytes = Buffer.from(JSON.stringify(file));
+        if (bytes.byteLength > HANDLE_FILE_CONTRACT.maxBytes)
+            throw new Error('handle file exceeds 256 KiB');
+        // Use the native basename so the temporary name cannot embed path separators.
+        const temporary = join(dirname(path), `.${pathBasename(path)}.${process.pid}.${token()}.tmp`);
+        let handle;
+        try {
+            await createPrivateFile(temporary, bytes);
+            handle = await open(temporary, 'r+');
+            await handle.sync();
+            await handle.close();
+            handle = undefined;
+            await settings.beforeManifestRename?.(`${path}.lock`);
+            await commit();
+            await rename(temporary, path);
+        }
+        finally {
+            await handle?.close().catch(() => { });
+            await unlink(temporary).catch(() => { });
+        }
     }
+    async function writeHandleFileLocked(path, tenant, mutate) {
+        // Refuse before any path check, so a Windows caller gets the platform reason rather
+        // than a private-path refusal from the parent check that runs next.
+        if (process.platform === 'win32')
+            throw unsupportedOnWindows();
+        path = resolve(path);
+        await prepareParent(path);
+        await withLockCommit(path, tenant, async (commit) => {
+            const before = await readManifest(path), working = structuredClone(before), result = await mutate(working), next = parseHandleFile(result ?? working), beforeForeign = foreign(before, tenant);
+            if (JSON.stringify(foreign(next, tenant)) !== JSON.stringify(beforeForeign))
+                throw new Error('manifest mutation changed another tenant block');
+            await writeAtomic(path, next, commit);
+            if (process.platform !== 'win32' && ((await lstat(path)).mode & 0o777) !== HANDLE_FILE_CONTRACT.mode)
+                throw new Error('manifest readback mode is not 0600');
+            if (!(await checkPath(path)).ok)
+                throw new Error('manifest readback mode is not 0600');
+            const readback = await readManifest(path);
+            if (JSON.stringify(readback) !== JSON.stringify(next))
+                throw new Error('manifest readback differs');
+            if (JSON.stringify(foreign(readback, tenant)) !== JSON.stringify(beforeForeign))
+                throw new Error('manifest readback changed another tenant block');
+        });
+    }
+    return { withManifestLock, writeHandleFileLocked };
 }
-export async function writeHandleFileLocked(path, tenant, mutate) {
-    // Refuse before any path check, so a Windows caller gets the platform reason rather
-    // than a private-path refusal from the parent check that runs next.
-    if (process.platform === 'win32')
-        throw unsupportedOnWindows();
-    path = resolve(path);
-    await prepareParent(path);
-    await withLockCommit(path, tenant, async (commit) => {
-        const before = await readManifest(path), working = structuredClone(before), result = await mutate(working), next = parseHandleFile(result ?? working), beforeForeign = foreign(before, tenant);
-        if (JSON.stringify(foreign(next, tenant)) !== JSON.stringify(beforeForeign))
-            throw new Error('manifest mutation changed another tenant block');
-        await writeAtomic(path, next, commit);
-        if (process.platform !== 'win32' && ((await lstat(path)).mode & 0o777) !== HANDLE_FILE_CONTRACT.mode)
-            throw new Error('manifest readback mode is not 0600');
-        if (!(await checkPrivatePath(path)).ok)
-            throw new Error('manifest readback mode is not 0600');
-        const readback = await readManifest(path);
-        if (JSON.stringify(readback) !== JSON.stringify(next))
-            throw new Error('manifest readback differs');
-        if (JSON.stringify(foreign(readback, tenant)) !== JSON.stringify(beforeForeign))
-            throw new Error('manifest readback changed another tenant block');
-    });
-}
+export const { withManifestLock, writeHandleFileLocked } = createManifestLock();

package/dist/private-path.d.ts

@@ -1,6 +1,4 @@
-import { AsyncLocalStorage } from 'node:async_hooks';
 import { type OwnerOnlyPathAsyncOptions, type OwnerOnlyPathResult } from '@cortexkit/store';
-export declare const privatePathContext: AsyncLocalStorage<OwnerOnlyPathAsyncOptions>;
 export declare const checkPrivatePath: (path: string, options?: OwnerOnlyPathAsyncOptions) => Promise<OwnerOnlyPathResult>;
 /**
  * The refusal text for a path the store judged not private. It names the folder and the

package/dist/private-path.js

@@ -1,12 +1,7 @@
-import { AsyncLocalStorage } from 'node:async_hooks';
 import { stat } from 'node:fs/promises';
 import { dirname, resolve } from 'node:path';
 import { checkOwnerOnlyPathAsync, createPrivateDirectory } from '@cortexkit/store';
-// Tests run the ownership check against fixture uids and account files through this
-// context, isolated per concurrent test. It is internal: the package `exports` map
-// exposes only the index, so consumers cannot reach it.
-export const privatePathContext = new AsyncLocalStorage();
-export const checkPrivatePath = (path, options) => checkOwnerOnlyPathAsync(resolve(path), privatePathContext.getStore() ?? options);
+export const checkPrivatePath = (path, options) => checkOwnerOnlyPathAsync(resolve(path), options);
 /**
  * The refusal text for a path the store judged not private. It names the folder and the
  * store's own reason (foreign owner, world-writable, a sticky folder without an

package/dist/wire.d.ts

@@ -138,6 +138,19 @@ export declare class ClaustrumClient {
         recordVersion: number;
         reporterSource: ClaustrumReporterSource;
     }): Promise<void>;
+    /**
+     * Fire-and-forget quota reporting: `accepted` means queued, never that the
+     * usage-processing module insula applied the reading.
+     * Callers should coalesce per credential and never await this on a request path.
+     *
+     * Reading contents are not validated here. The vault rejects top-level `credentialId`
+     * and `vouched` keys and compact JSON readings over 15,360 bytes with `invalid_params`.
+     */
+    reportUsageScoped(input: {
+        credentialId: string;
+        reading: Record<string, unknown>;
+        enrollmentToken?: string;
+    }): Promise<void>;
     /**
      * Propose an enrollment. The consumer mints `requestSecret` itself and sends only its
      * hash; the raw secret NEVER leaves the process, and it is what authorizes the poll.

package/dist/wire.js

@@ -241,6 +241,26 @@ export class ClaustrumClient {
         if (result?.accepted !== true)
             throw asCredentialError(response, 'invalid_response', this.#logger);
     }
+    /**
+     * Fire-and-forget quota reporting: `accepted` means queued, never that the
+     * usage-processing module insula applied the reading.
+     * Callers should coalesce per credential and never await this on a request path.
+     *
+     * Reading contents are not validated here. The vault rejects top-level `credentialId`
+     * and `vouched` keys and compact JSON readings over 15,360 bytes with `invalid_params`.
+     */
+    async reportUsageScoped(input) {
+        const response = await this.#call('usage.report_scoped', {
+            credential_id: input.credentialId,
+            reading: input.reading,
+            enrollment_token: input.enrollmentToken,
+        });
+        if (hasCredentialError(response))
+            throw asCredentialError(response, 'invalid_response', this.#logger);
+        const result = isRecord(response) && isRecord(response.result) ? response.result : undefined;
+        if (result?.accepted !== true)
+            throw asCredentialError(response, 'invalid_response', this.#logger);
+    }
     /**
      * Propose an enrollment. The consumer mints `requestSecret` itself and sends only its
      * hash; the raw secret NEVER leaves the process, and it is what authorizes the poll.

package/package.json

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