@cortexkit/claustrum-client 0.14.0 → 0.16.0

package/README.md

@@ -23,6 +23,9 @@ credential caching, refresh, account scheduling, and retry policy.
   as a version older than every real one.
 • Unknown server error classes are bounded to `transient`; callers must retry them
   rather than treating a forward-compatible class as permanent.
+• Account pools use the refresh adapter from `list_scoped` plus opaque `accountId`.
+  Use `recordVersion` to invalidate cached material, never as part of a pool key:
+  a token refresh must not split one account into a new pool.
 • **Changed in 0.13.0:** a transport `Error` frame whose answer no retry or reconnect
   can change is reported as `permanent` with action `gone`, and the client no longer
   reconnects for it: `unknown_method`, `invalid_params`, `invalid_request`,
@@ -61,7 +64,11 @@ credential caching, refresh, account scheduling, and retry policy.
   `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.
+launch identity cannot impersonate a supervising host. Nonce possession, not process
+ancestry, is the authority boundary: environment variables and an inheritable nonce
+descriptor can reach helpers unless scrubbed or closed. Helpers using other clients
+must explicitly omit route identity (for subc-client, `consumerIdentity: null`) when
+they should be anonymous; process ancestry alone does not enforce isolation.
 
 **Changed in 0.11.0:** the client depends on `@cortexkit/subc-client` ^0.22.0 (was
 ^0.16.0). A host that also uses subc-client must move to the 0.22 line, so both share one
@@ -69,6 +76,26 @@ copy. One behaviour reaches callers: while the vault is restarting or refusing r
 opens as retryable, a call now keeps retrying for up to 90 s (paced, with jitter) instead
 of 30 s. Give every vault call on a latency-sensitive path its own timeout.
 
+**Changed in 0.16.0:** the dependency is now `@cortexkit/subc-client` ^0.24.0.
+The SDK negotiates FIFO request/watch windows and retries only daemon-origin
+`route_busy` refusals within the request deadline. Claustrum adds no busy retry;
+older daemons keep the SDK's previous behavior.
+
+## Reading credential material
+
+The wire payload is opaque bytes. `getCredential(handle, minTtlMs?)` and
+`getScoped({ credentialId, enrollmentToken?, minTtlMs? })` keep their text results
+(`ServedCredential.material: string`) and require valid UTF-8. They refuse a
+non-UTF-8 payload with `invalid_response`; this does not mean the stored credential
+is corrupt.
+
+Use `getCredentialBytes(handle, minTtlMs?)` or
+`getScopedBytes({ credentialId, enrollmentToken?, minTtlMs? })` for binary cookies
+or any material that may not be UTF-8. Both return `ServedCredentialBytes`, with
+`material: Uint8Array` preserving every payload byte and the same metadata, grant
+checks, and TTL semantics as their text counterparts. Neither byte method performs
+text decoding.
+
 ## Watching for changes
 
 Since 0.12.0, `client.watchScoped(onNotice, { enrollmentToken? })` holds an
@@ -139,20 +166,37 @@ for (;;) {
 }
 ```
 
-## OpenCode handle-file exports
+## Enrollment
+
+Use `newEnrollmentSecret()` to prepare an enrollment proposal. It generates 32
+random bytes as exactly 64 lowercase hex characters, plus `requestSecretHash`:
+the lowercase hex SHA-256 of the **32 decoded bytes**, not of the UTF-8 hex text.
+`enrollmentSecretHash(requestSecret)` recomputes the hash of a persisted secret
+and refuses anything other than exactly 64 lowercase hex characters.
+
+```ts
+import { ClaustrumClient, newEnrollmentSecret } from '@cortexkit/claustrum-client'
+
+const client = await ClaustrumClient.connect()
+const { requestSecret, requestSecretHash } = newEnrollmentSecret()
+// Persist the secret privately before proposing so a crash can recover the poll.
+await persistRequestSecret(requestSecret)
+const { requestId } = await client.enrollPropose({ name: 'consumer', requestSecretHash })
+await persistRequestId(requestId)
+// After operator approval, poll with the original secret, not its hash.
+const outcome = await client.enrollPoll({ requestId, requestSecret })
+```
 
-`defaultHandleFilePath`, `readHandleFile`, `handleFileRevision`, and `parseHandleFile`
-are exported for tenant plugins consuming the OpenCode handle manifest. The shared
-`HANDLE_FILE_CONTRACT` is pinned to `maxBytes: 262144`, `mode: 0o600`,
-`labelRe: /^[a-z0-9][a-z0-9._-]{0,63}$/`, and `handleRe: /^ckh_[A-Za-z0-9_-]{43}$/`.
+The persistence functions above are caller-provided. Re-proposing the same name
+with the same persisted secret/hash recovers the request id after a lost reply.
+Only `pending` means poll again; an approved outcome returns the token once, so
+persist it with `writeEnrollmentTokenFile` before using it. Never log the request
+secret or token.
 
-### Private files and Windows support
+## Private files and Windows support
 
-Enrollment tokens support Windows as well as Unix. Reading a handle manifest works on
-Windows; writing one does not: the manifest lock's stale-lock eviction renames a lock
-another process may hold open, which Windows refuses, so `withManifestLock` and
-`writeHandleFileLocked` reject on Windows with code `unsupported_platform` rather than
-risk two writers overlapping. The client uses `@cortexkit/store` 0.2.1 or newer: exclusive private creation
+Enrollment tokens support Windows as well as Unix. The client uses
+`@cortexkit/store` 0.2.3 or newer: exclusive private creation
 protects files before any secret bytes are written, and atomic replacement keeps
 that protection. Unix files use mode 0600 and new directories use 0700. On Windows,
 the store's `@cortexkit/private-files` native module creates owner-only ACLs and the
@@ -174,7 +218,7 @@ preserved: an owned, non-sticky group-writable directory (including a 0775
 
 ## Testing a consumer of this client
 
-Three things on a developer box silently satisfy what a consumer's test is trying to
+Two things on a developer box silently satisfy what a consumer's test is trying to
 prove. Each was found by a consumer shipping green and failing elsewhere.
 
 • **A connection file at the default path is a host fact, not a fixture.** If the vault
@@ -182,9 +226,6 @@ prove. Each was found by a consumer shipping green and failing elsewhere.
   up, so a suite can pass on the daemon's real socket and fail anywhere without one.
   Force it absent (`CLAUSTRUM_SUBC_CONNECTION=/nonexistent/x.json`, and clear
   `XDG_RUNTIME_DIR`) and prove the suite still passes.
-• **Tests default into the operator's live config.** A suite that resolves
-  `~/.config/opencode` without an override writes lock files and manifests beside real
-  credentials — passing locally, and mutating state no CI runner has.
 • **A bare `bun` run is not an oracle for module resolution.** The Bun CLI auto-installs
   a public dependency it cannot resolve; a compiled binary does not. All readings below
   are bun 1.3.14, same module, no `node_modules` — a toolchain behaviour with no version
@@ -215,5 +256,5 @@ prove. Each was found by a consumer shipping green and failing elsewhere.
   result: a freshly linked unsigned binary is SIGKILLed, and `rc=137` with empty stderr
   reads as a resolution failure while being a signature one.
 
-The shape is the same in all three: the producing machine supplies the thing under test.
+The shape is the same in both: the producing machine supplies the thing under test.
 A passing check on it is evidence only when the ambient supply is removed first.

package/dist/enrollment.d.ts

@@ -3,5 +3,12 @@ export type EnrollmentTokenFile = {
     token: string;
     token_generation: number;
 };
+/** Hash the 32 decoded bytes, not the UTF-8 text of the hex request secret. */
+export declare function enrollmentSecretHash(requestSecret: string): string;
+/** Mint an enrollment request secret and the hash to send with the proposal. */
+export declare function newEnrollmentSecret(): {
+    requestSecret: string;
+    requestSecretHash: string;
+};
 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

@@ -1,9 +1,21 @@
 import { createPrivateFile } from '@cortexkit/store';
 import { checkPrivatePath, createPrivateParents, notPrivate, privateCreationCode } from './private-path.js';
-import { randomBytes } from 'node:crypto';
+import { createHash, randomBytes } from 'node:crypto';
 import { open, rename, unlink } from 'node:fs/promises';
 import { basename, dirname, join, resolve } from 'node:path';
 const TOKEN_RE = /^[0-9a-f]{64}$/;
+/** Hash the 32 decoded bytes, not the UTF-8 text of the hex request secret. */
+export function enrollmentSecretHash(requestSecret) {
+    if (typeof requestSecret !== 'string' || requestSecret.length !== 64 || !TOKEN_RE.test(requestSecret)) {
+        throw new Error('enrollment request secret must be exactly 64 lowercase hex characters');
+    }
+    return createHash('sha256').update(Buffer.from(requestSecret, 'hex')).digest('hex');
+}
+/** Mint an enrollment request secret and the hash to send with the proposal. */
+export function newEnrollmentSecret() {
+    const requestSecret = randomBytes(32).toString('hex');
+    return { requestSecret, requestSecretHash: enrollmentSecretHash(requestSecret) };
+}
 function validateTokenFile(value) {
     if (!TOKEN_RE.test(value.token))
         throw new Error('enrollment token must be exactly 64 lowercase hex characters');

package/dist/index.d.ts

@@ -1,8 +1,6 @@
 export { detectClaustrumConnection, getDefaultClaustrumConnectionPath, resolveClaustrumConnectionPath, type ClaustrumDetection, type ClaustrumEndpoint, } from './detect.js';
 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 { enrollmentSecretHash, newEnrollmentSecret, writeEnrollmentTokenFile, type EnrollmentTokenFile, } from './enrollment.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 ScopedGrantTuple, type ScopedInventory, type ScopedInventoryRow, type ServedCredential, } from './wire.js';
+export { ClaustrumClient, type ClaustrumClientOptions, type ClaustrumConnector, type ClaustrumReporterSource, type CredentialStatus, type EnrollmentPollOutcome, type ScopedGrantTuple, type ScopedInventory, type ScopedInventoryRow, type ServedCredential, type ServedCredentialBytes, } from './wire.js';
 export { ScopedWatchError, type ScopedWatch, type ScopedWatchNotice, type ScopedWatchOptions, type ScopedWatchOutcome, } from './watch.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/index.js

@@ -1,8 +1,6 @@
 export { detectClaustrumConnection, getDefaultClaustrumConnectionPath, resolveClaustrumConnectionPath, } from './detect.js';
 export { storeIdentity, storageFingerprint } from './identity.js';
-export { writeEnrollmentTokenFile, } from './enrollment.js';
-export { MANIFEST_LOCK, manifestLockQuarantinePrefix, withManifestLock, writeHandleFileLocked, } from './manifest-lock.js';
+export { enrollmentSecretHash, newEnrollmentSecret, writeEnrollmentTokenFile, } from './enrollment.js';
 export { ClaustrumCredentialError, credentialErrorAction, ERROR_CLASS_WIRE_SET, } from './errors.js';
 export { ClaustrumClient, } from './wire.js';
 export { ScopedWatchError, } from './watch.js';
-export { HANDLE_FILE_CONTRACT, HandleFileValidationError, credentialIdMatchesProvider, defaultHandleFilePath, handleFileRevision, identifierIsValid, parseHandleFile, readHandleFile, } from './handles.js';

package/dist/wire.d.ts

@@ -26,19 +26,22 @@ export type ClaustrumClientOptions = {
  * an outage caused that way is visible only to the consumer that caused it.
  */
 export type ServedCredential = {
+    /** UTF-8 text; use `ServedCredentialBytes` for opaque, potentially non-UTF-8 material. */
     material: string;
     recordVersion: number;
     expiresAtMs: number | null;
     /**
      * Operator-chosen record label for verifying a caller-held binding. It is not a routing key:
-     * account-scoped routing joins `accountId` with `recordVersion`.
+     * Account-scoped routing joins `accountId` with `refreshAdapter` from the inventory,
+     * never `recordVersion`, which only invalidates cached material.
      */
     credentialId?: string;
     /** Non-secret Code Assist project identity, present only for antigravity credentials. */
     projectId?: string;
     /**
-     * Provider account identity the served token executes under. Account-scoped routing joins this
-     * value with `recordVersion`; it is neither the operator's credential label nor the bearer handle.
+     * Provider account identity the served token executes under. Account pools join this value with
+     * the inventory's `refreshAdapter`, not the material's `recordVersion`, so refreshes do not split
+     * one account into new pools. It is neither the operator's credential label nor the bearer handle.
      *
      * BEST-EFFORT, NEVER GUARANTEED, including for JWT providers. The vault parses the claim live
      * from the served access token and falls back to stored login-time identity; both legs can be
@@ -52,6 +55,10 @@ export type ServedCredential = {
     /** Non-secret organization or workspace display metadata captured at login. */
     orgName?: string;
 };
+/** The same credential metadata with opaque payload bytes, without text conversion. */
+export type ServedCredentialBytes = Omit<ServedCredential, 'material'> & {
+    material: Uint8Array;
+};
 /**
  * Non-secret health for one handle, read without minting anything.
  *
@@ -93,7 +100,10 @@ export declare class ClaustrumClient {
     #private;
     private constructor();
     static connect(options?: ClaustrumClientOptions): Promise<ClaustrumClient>;
+    /** Fetch UTF-8 text; use `getCredentialBytes` if the payload may contain arbitrary bytes. */
     getCredential(handle: string, minTtlMs?: number): Promise<ServedCredential>;
+    /** Fetch opaque payload bytes by bearer handle without UTF-8 decoding. */
+    getCredentialBytes(handle: string, minTtlMs?: number): Promise<ServedCredentialBytes>;
     statusCredential(handle: string): Promise<CredentialStatus>;
     reportAuthFailure(input: {
         handle: string;
@@ -111,7 +121,8 @@ export declare class ClaustrumClient {
     /** One watch on a dedicated route. Reopen/reconnect policy belongs to the caller. */
     watchScoped(onNotice: (notice: ScopedWatchNotice) => void, options?: ScopedWatchOptions): ScopedWatch;
     /**
-     * Fetch by credential id, authorized by a grant rather than a bearer handle.
+     * Fetch UTF-8 text by credential id, authorized by a grant rather than a bearer handle.
+     * Use `getScopedBytes` if the payload may contain arbitrary bytes.
      *
      * `minTtlMs` is a DEMAND, not a hint: if a real upstream exchange still cannot satisfy
      * it, the vault refuses with `ttl_unsatisfiable` (class `context_overflow`) rather than
@@ -123,6 +134,12 @@ export declare class ClaustrumClient {
         enrollmentToken?: string;
         minTtlMs?: number;
     }): Promise<ServedCredential>;
+    /** Fetch opaque bytes by credential id, with the same grant and TTL rules as `getScoped`. */
+    getScopedBytes(input: {
+        credentialId: string;
+        enrollmentToken?: string;
+        minTtlMs?: number;
+    }): Promise<ServedCredentialBytes>;
     /**
      * Report a served credential dead, addressed by id rather than by handle.
      *

package/dist/wire.js

@@ -52,6 +52,17 @@ function isOptionalString(value) {
  * widen the published surface.
  */
 export function decodeCredential(response, logUnknownClass) {
+    const credential = decodeCredentialBytes(response, logUnknownClass);
+    let material;
+    try {
+        material = new TextDecoder('utf-8', { fatal: true }).decode(credential.material);
+    }
+    catch {
+        throw asCredentialError(response, 'invalid_response', logUnknownClass);
+    }
+    return { ...credential, material };
+}
+function decodeCredentialBytes(response, logUnknownClass) {
     if (hasCredentialError(response))
         throw asCredentialError(response, 'invalid_response', logUnknownClass);
     const result = isRecord(response) && isRecord(response.result) ? response.result : undefined;
@@ -86,15 +97,8 @@ export function decodeCredential(response, logUnknownClass) {
         !isOptionalString(orgName)) {
         throw asCredentialError(response, 'invalid_response', logUnknownClass);
     }
-    let material;
-    try {
-        material = new TextDecoder('utf-8', { fatal: true }).decode(Uint8Array.from(payload));
-    }
-    catch {
-        throw asCredentialError(response, 'invalid_response', logUnknownClass);
-    }
     return {
-        material,
+        material: Uint8Array.from(payload),
         recordVersion,
         expiresAtMs,
         credentialId,
@@ -160,6 +164,7 @@ export class ClaustrumClient {
         });
         return new ClaustrumClient(client, connector, connectionFile, options.handshakeTimeoutMs, identity, options.logger ?? ((errorClass) => console.warn(errorClass)));
     }
+    /** Fetch UTF-8 text; use `getCredentialBytes` if the payload may contain arbitrary bytes. */
     async getCredential(handle, minTtlMs) {
         const response = await this.#call('credential.get', {
             handle,
@@ -168,6 +173,15 @@ export class ClaustrumClient {
         });
         return decodeCredential(response, this.#logger);
     }
+    /** Fetch opaque payload bytes by bearer handle without UTF-8 decoding. */
+    async getCredentialBytes(handle, minTtlMs) {
+        const response = await this.#call('credential.get', {
+            handle,
+            min_ttl_ms: minTtlMs,
+            force_refresh: false,
+        });
+        return decodeCredentialBytes(response, this.#logger);
+    }
     async statusCredential(handle) {
         const response = await this.#call('credential.status', { handle });
         return decodeStatus(response, this.#logger);
@@ -204,7 +218,8 @@ export class ClaustrumClient {
         });
     }
     /**
-     * Fetch by credential id, authorized by a grant rather than a bearer handle.
+     * Fetch UTF-8 text by credential id, authorized by a grant rather than a bearer handle.
+     * Use `getScopedBytes` if the payload may contain arbitrary bytes.
      *
      * `minTtlMs` is a DEMAND, not a hint: if a real upstream exchange still cannot satisfy
      * it, the vault refuses with `ttl_unsatisfiable` (class `context_overflow`) rather than
@@ -219,6 +234,15 @@ export class ClaustrumClient {
         });
         return decodeCredential(response, this.#logger);
     }
+    /** Fetch opaque bytes by credential id, with the same grant and TTL rules as `getScoped`. */
+    async getScopedBytes(input) {
+        const response = await this.#call('credential.get_scoped', {
+            credential_id: input.credentialId,
+            enrollment_token: input.enrollmentToken,
+            min_ttl_ms: input.minTtlMs,
+        });
+        return decodeCredentialBytes(response, this.#logger);
+    }
     /**
      * Report a served credential dead, addressed by id rather than by handle.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cortexkit/claustrum-client",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -27,7 +27,7 @@
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@cortexkit/store": "^0.2.1",
-    "@cortexkit/subc-client": "^0.22.0"
+    "@cortexkit/store": "^0.2.3",
+    "@cortexkit/subc-client": "^0.24.0"
   }
 }

package/dist/handles.d.ts

@@ -1,64 +0,0 @@
-import { checkPrivatePath } from './private-path.js';
-export declare const HANDLE_FILE_CONTRACT: {
-    readonly maxBytes: number;
-    readonly mode: 384;
-    readonly labelRe: RegExp;
-    readonly handleRe: RegExp;
-};
-export declare class HandleFileValidationError extends Error {
-    name: string;
-}
-export type HandleAccount = {
-    label: string;
-    handle: string;
-    credential_id: string;
-    superseded?: string[];
-    minTtlMs?: number;
-};
-export type HandleProvider = {
-    provider: string;
-    shape: 'api' | 'oauth';
-    serve: string;
-    accounts: HandleAccount[];
-};
-export type OpenCodeHandleFileV1 = {
-    version: 1;
-    providers: HandleProvider[];
-};
-export declare function identifierIsValid(value: unknown): value is string;
-export declare function credentialIdMatchesProvider(value: unknown, provider: string): value is string;
-export declare function parseHandleFile(value: unknown): OpenCodeHandleFileV1;
-type HandleFileStat = {
-    isFile(): boolean;
-    isDirectory?(): boolean;
-    isSymbolicLink?(): boolean;
-    mode: number;
-    size?: number;
-    gid?: number;
-    uid?: number;
-    mtimeMs?: number;
-};
-type HandleFileDescriptor = {
-    read?(buffer: Uint8Array, offset: number, length: number, position: number): Promise<{
-        bytesRead: number;
-    }> | {
-        bytesRead: number;
-    };
-    stat(): Promise<HandleFileStat>;
-    readFile(options: {
-        encoding: 'utf8';
-    }): Promise<string>;
-    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>;
-    open?: (path: string) => Promise<HandleFileDescriptor>;
-    currentUid?: () => number | undefined;
-};
-export declare function defaultHandleFilePath(env?: NodeJS.ProcessEnv): string;
-export declare function readHandleFile(path?: string, io?: HandleFileIo): Promise<OpenCodeHandleFileV1>;
-export declare function handleFileRevision(path?: string, io?: HandleFileIo): Promise<string>;
-export {};

package/dist/handles.js

@@ -1,255 +0,0 @@
-import { createHash } from 'node:crypto';
-import { constants } from 'node:fs';
-import { lstat as nodeLstat, open as nodeOpen, readFile, stat as nodeStat } from 'node:fs/promises';
-import { userInfo } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
-import { checkPrivatePath, notPrivate } from './private-path.js';
-export const HANDLE_FILE_CONTRACT = {
-    maxBytes: 256 * 1024,
-    mode: 0o600,
-    // Shape only: identifier validity also rejects FORBIDDEN_IDENTIFIERS; use
-    // identifierIsValid for validation so callers do not accept parser-rejected labels.
-    labelRe: /^[a-z0-9][a-z0-9._-]{0,63}$/,
-    handleRe: /^ckh_[A-Za-z0-9_-]{43}$/,
-};
-const FORBIDDEN_IDENTIFIERS = new Set(['__proto__', 'constructor', 'prototype']);
-export class HandleFileValidationError extends Error {
-    name = 'HandleFileValidationError';
-}
-function isAccount(value) {
-    if (!value || typeof value !== 'object')
-        return false;
-    const account = value;
-    return typeof account.label === 'string' && typeof account.handle === 'string' &&
-        typeof account.credential_id === 'string' &&
-        (account.superseded === undefined ||
-            (Array.isArray(account.superseded) && account.superseded.every((handle) => typeof handle === 'string')));
-}
-function handleIsValid(handle) {
-    return typeof handle === 'string' && HANDLE_FILE_CONTRACT.handleRe.test(handle);
-}
-export function identifierIsValid(value) {
-    return typeof value === 'string' && HANDLE_FILE_CONTRACT.labelRe.test(value) && !FORBIDDEN_IDENTIFIERS.has(value);
-}
-export function credentialIdMatchesProvider(value, provider) {
-    if (typeof value !== 'string')
-        return false;
-    const segments = value.split(':');
-    return value.length > 0 && segments[1] === provider && segments.every((segment) => segment.length > 0);
-}
-function invalid(message) {
-    throw new HandleFileValidationError(message);
-}
-export function parseHandleFile(value) {
-    if (!value || typeof value !== 'object')
-        invalid('handle file must be an object');
-    const file = value;
-    if (file.version !== 1 || !Array.isArray(file.providers)) {
-        invalid('handle file must have version 1 and providers');
-    }
-    const providerIds = new Set();
-    const providers = file.providers.map((provider, index) => {
-        if (!provider || typeof provider !== 'object')
-            invalid(`provider ${index} must be an object`);
-        const item = provider;
-        if (!identifierIsValid(item.provider))
-            invalid(`provider ${index} has invalid provider`);
-        if (providerIds.has(item.provider))
-            invalid(`provider ${index} duplicates provider ${item.provider}`);
-        providerIds.add(item.provider);
-        if (item.shape !== 'api' && item.shape !== 'oauth')
-            invalid(`provider ${index} has invalid shape`);
-        if (typeof item.serve !== 'string' || !item.serve)
-            invalid(`provider ${index} requires serve`);
-        if (!Array.isArray(item.accounts) || item.accounts.length === 0 || !item.accounts.every(isAccount)) {
-            invalid(`provider ${index} has invalid accounts`);
-        }
-        const labels = new Set();
-        for (const account of item.accounts) {
-            if (!identifierIsValid(account.label))
-                invalid(`provider ${index} has an invalid account label`);
-            if (labels.has(account.label))
-                invalid(`provider ${index} duplicates account label ${account.label}`);
-            labels.add(account.label);
-            if (!handleIsValid(account.handle))
-                invalid(`provider ${index} account ${account.label} has invalid handle`);
-            if (account.minTtlMs !== undefined && !(Number.isSafeInteger(account.minTtlMs) && account.minTtlMs >= 0)) {
-                invalid(`provider ${index} account ${account.label} has invalid minTtlMs`);
-            }
-            // Segment 2 of the credential id must BE the provider block it sits in. Without
-            // this the check was non-empty-string only, so an `oauth:openai` binding parsed
-            // cleanly inside an `anthropic` block -- a cross-provider smuggle that every
-            // tenant reading this manifest would have honoured. Two peer tenants found the
-            // same hole in their own parsers independently.
-            //
-            // SCOPED TO SEGMENT 2 ONLY, deliberately. Segment 1 (the kind) is an OPEN SET --
-            // `oauth:`, `chatgpt:`, `antigravity:`, `apikey:` are all live in this vault today
-            // -- so a kind allowlist would refuse real ids. Segment 3+ (the label) is
-            // operator-chosen and may be absent: main is the 2-segment `oauth:anthropic`,
-            // fallbacks are 3-segment. Constraining either would reject the deployment this
-            // contract describes.
-            //
-            // NO SEGMENT MAY BE EMPTY. Segment 2 alone is what fences the provider, but a
-            // position-1 check ignores the rest of the string, and that left two ids passing
-            // that name credentials which cannot exist: `:anthropic:x` (empty kind) and
-            // `oauth:anthropic:` (empty label) both satisfy "segment 2 is the provider"
-            // literally. Neither is a smuggle; both defer a GUARANTEED resolve-time failure
-            // past the door, and under custody a resolve-time failure on a tombstoned account
-            // is a dark route rather than a refused row.
-            //
-            // It also removes an asymmetry nobody designed and everyone would read as a bug:
-            // `oauth::anthropic` rejected while `:anthropic:x` passed, purely because the
-            // check indexed position 1 and ignored positions 0 and 2. Agreed with the peer
-            // tenant and mirrored on their side, so this is chosen rather than defaulted --
-            // the previous behaviour was two independent defaults that happened to differ.
-            //
-            // The emptiness guard is ALSO explicit rather than a consequence: `''.split(':')`
-            // yields `['']`, whose `[1]` is `undefined` and cannot equal a provider string,
-            // so an empty id would reject anyway -- but that is a coincidence doing
-            // load-bearing work, and the check this replaced (`!account.credential_id`) was
-            // the emptiness guard. NO TEST DISTINGUISHES THAT ONE (empty rejects with or
-            // without it, verified by removal), so it is kept for a future reader who loosens
-            // the comparison, not for an arm it could never redden. The non-empty-SEGMENT
-            // rule in credentialIdMatchesProvider is different: it reddens, and is pinned.
-            if (!credentialIdMatchesProvider(account.credential_id, item.provider)) {
-                invalid(`provider ${index} account ${account.label} has invalid credential id`);
-            }
-            if (account.superseded?.some((handle) => !handleIsValid(handle))) {
-                invalid(`provider ${index} account ${account.label} has invalid superseded handle`);
-            }
-        }
-        return {
-            provider: item.provider,
-            shape: item.shape,
-            serve: item.serve,
-            accounts: item.accounts.map((account) => ({
-                ...account,
-                ...(account.superseded === undefined ? {} : { superseded: account.superseded }),
-            })),
-        };
-    });
-    return { version: 1, providers };
-}
-export function defaultHandleFilePath(env = process.env) {
-    if (env.CLAUSTRUM_OPENCODE_HANDLES)
-        return env.CLAUSTRUM_OPENCODE_HANDLES;
-    const configHome = env.XDG_CONFIG_HOME || (env.HOME ? join(env.HOME, '.config') : '.config');
-    return join(configHome, 'cortexkit', 'opencode-handles.json');
-}
-function currentUid() {
-    return process.platform === 'win32' ? undefined : process.getuid?.() ?? userInfo().uid;
-}
-async function readBounded(descriptor, cap) {
-    if (!descriptor.read)
-        throw new Error('readBounded requires a descriptor exposing read()');
-    const buffer = Buffer.alloc(cap + 1);
-    let total = 0;
-    while (total < cap + 1) {
-        const chunk = await descriptor.read(buffer, total, buffer.length - total, total);
-        if (chunk.bytesRead === 0)
-            break;
-        total += chunk.bytesRead;
-    }
-    return { buffer, bytes: total > cap ? -1 : total };
-}
-async function readHandleSnapshot(path = defaultHandleFilePath(), io = {}) {
-    path = resolve(path);
-    const stat = io.stat ?? nodeStat;
-    const lstat = io.lstat ?? nodeLstat;
-    const read = io.readFile ?? readFile;
-    const openFd = io.open ?? ((candidate) => nodeOpen(candidate, constants.O_RDONLY | constants.O_NOFOLLOW));
-    let descriptor;
-    try {
-        let metadata;
-        try {
-            if (io.lstat || io.readFile) {
-                metadata = await lstat(path);
-            }
-            else {
-                descriptor = await openFd(path);
-                metadata = await descriptor.stat();
-            }
-        }
-        catch (error) {
-            if (error.code === 'ENOENT')
-                return { file: { version: 1, providers: [] } };
-            if (error.code === 'ELOOP')
-                invalid('handle file must not be a symlink');
-            invalid(`cannot stat handle file: ${error instanceof Error ? error.message : String(error)}`);
-        }
-        if (metadata.isSymbolicLink?.())
-            invalid('handle file must not be a symlink');
-        if (!metadata.isFile())
-            invalid('handle file must be a regular file');
-        if ((metadata.size ?? 0) > HANDLE_FILE_CONTRACT.maxBytes)
-            invalid('handle file exceeds 256 KiB');
-        if (process.platform !== 'win32' && (metadata.mode & 0o777) !== HANDLE_FILE_CONTRACT.mode)
-            invalid('handle file mode must be exactly 0600');
-        const uid = io.currentUid ?? currentUid;
-        const expectedUid = uid();
-        if (expectedUid !== undefined && metadata.uid !== undefined && metadata.uid !== expectedUid) {
-            invalid('handle file is not owned by the current uid');
-        }
-        let parent;
-        try {
-            parent = await stat(dirname(path));
-        }
-        catch (error) {
-            invalid(`cannot stat handle file parent: ${error instanceof Error ? error.message : String(error)}`);
-        }
-        if (!parent.isDirectory?.())
-            invalid('handle file parent must be a directory');
-        if (expectedUid !== undefined && parent.uid !== undefined && parent.uid !== expectedUid) {
-            invalid('handle file parent is not owned by the current uid');
-        }
-        // HandleFileIo's injected stat supplies ancestor metadata as well as the immediate
-        // parent. Pass that metadata to @cortexkit/store's Unix path check.
-        const fixtureStat = io.stat && (async (candidate) => {
-            const value = await io.stat(candidate);
-            return { ...value, isDirectory: () => value.isDirectory?.() ?? false };
-        });
-        const protection = await checkPrivatePath(process.platform === 'win32' ? path : dirname(path), io.pathOptions ?? (fixtureStat ? {
-            euid: expectedUid,
-            fs: { stat: fixtureStat, lstat: fixtureStat },
-        } : undefined));
-        if (!protection.ok)
-            invalid(notPrivate('handle file folder', protection));
-        let source;
-        try {
-            if (descriptor) {
-                const { buffer, bytes } = await readBounded(descriptor, HANDLE_FILE_CONTRACT.maxBytes);
-                if (bytes === -1)
-                    invalid('handle file exceeds 256 KiB');
-                source = buffer.subarray(0, bytes).toString('utf8');
-            }
-            else {
-                source = await read(path, 'utf8');
-            }
-        }
-        catch (error) {
-            if (error instanceof HandleFileValidationError)
-                throw error;
-            invalid(`cannot read handle file: ${error instanceof Error ? error.message : String(error)}`);
-        }
-        let value;
-        try {
-            value = JSON.parse(source);
-        }
-        catch {
-            invalid('handle file contains invalid JSON');
-        }
-        return { file: parseHandleFile(value), source, mtimeMs: metadata.mtimeMs };
-    }
-    finally {
-        await descriptor?.close();
-    }
-}
-export async function readHandleFile(path = defaultHandleFilePath(), io = {}) {
-    return (await readHandleSnapshot(path, io)).file;
-}
-export async function handleFileRevision(path = defaultHandleFilePath(), io = {}) {
-    const snapshot = await readHandleSnapshot(path, io);
-    if (snapshot.source === undefined)
-        invalid('cannot revise absent handle file');
-    return `${snapshot.mtimeMs ?? 0}:${createHash('sha256').update(snapshot.source).digest('hex')}`;
-}

package/dist/manifest-lock.d.ts

@@ -1,37 +0,0 @@
-import { checkPrivatePath } from './private-path.js';
-import { type OpenCodeHandleFileV1 } from './handles.js';
-export declare const MANIFEST_LOCK: {
-    ttlMs: number;
-    renewEveryMs: number;
-    ownerKeys: readonly ['tenant', 'pid', 'claimed_at_ms', 'nonce'];
-    staleTargetRe: RegExp;
-    errorCodes: readonly ['lock_busy', 'owner_invalid', 'renewal_failed', 'unsupported_platform'];
-};
-/** Thrown by the lock. Branch on `code`; the message is diagnostic and may be reworded. */
-export type ManifestLockErrorCode = (typeof MANIFEST_LOCK.errorCodes)[number];
-export type ManifestLockError = Error & {
-    code: ManifestLockErrorCode;
-};
-export type ManifestHandleAccount = OpenCodeHandleFileV1['providers'][number]['accounts'][number];
-export type ManifestHandleProvider = OpenCodeHandleFileV1['providers'][number];
-export type ManifestHandleFile = OpenCodeHandleFileV1;
-type ManifestLockOptions = Readonly<{
-    ttlMs?: number;
-    renewEveryMs?: number;
-    retryMinMs?: number;
-    retryMaxMs?: number;
-    afterClaim?: () => Promise<void> | void;
-    beforeEvict?: () => Promise<void>;
-    afterEvictRenameAttempt?: () => Promise<void>;
-    afterEvict?: () => void;
-    beforeManifestRename?: (path: string) => Promise<void>;
-    checkPath?: typeof checkPrivatePath;
-}>;
-export declare function manifestLockQuarantinePrefix(path: string, basename?: (p: string) => string): string | undefined;
-/** 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

@@ -1,333 +0,0 @@
-import { createPrivateDirectory, createPrivateFile } from '@cortexkit/store';
-import { checkPrivatePath, createPrivateParents, notPrivate, privateCreationCode } from './private-path.js';
-import { lstat, open, readFile, readdir, rename, rm, stat, unlink } from 'node:fs/promises';
-import { randomBytes, randomInt } from 'node:crypto';
-import { basename as pathBasename, dirname, join, resolve } from 'node:path';
-import { HANDLE_FILE_CONTRACT, parseHandleFile } from './handles.js';
-export const MANIFEST_LOCK = { ttlMs: 30_000, renewEveryMs: 10_000, ownerKeys: ['tenant', 'pid', 'claimed_at_ms', 'nonce'], staleTargetRe: /^\.lock\.stale-\d+-(?!\.{1,2}$)(?!.*[. ]$)[^/\\\x00-\x1f:*?"<>|]{1,128}$/, errorCodes: ['lock_busy', 'owner_invalid', 'renewal_failed', 'unsupported_platform'] };
-// The claim deadline bounds when the last stale-lock rename is issued, not when it lands:
-// a rename issued at deadline-1ms can complete afterwards, by tens to hundreds of ms on a
-// 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;
-// 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');
-const code = privateCreationCode;
-const sleep = async (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-// A tenant classifying a failure must not string-match our prose: a copy-edit would
-// silently reclassify a retryable busy-lock as an unknown error, with nothing failing
-// loudly. The code is the contract; the message is free to change.
-const lockError = (code, message) => Object.assign(new Error(message), { code });
-const unsupportedOnWindows = () => lockError('unsupported_platform', 'handle-file manifest locking is not supported on Windows');
-function parseOwner(source) {
-    let value;
-    try {
-        value = JSON.parse(source);
-    }
-    catch {
-        throw lockError('owner_invalid', 'manifest lock owner invalid');
-    }
-    if (!value || typeof value !== 'object')
-        throw lockError('owner_invalid', 'manifest lock owner invalid');
-    const owner = value;
-    // Widen the nonce alphabet only after every tenant has this path-safe reader; an older
-    // allowlist reader can otherwise wedge forever on the first owner using the new alphabet.
-    const staleTarget = `.lock.stale-${owner.claimed_at_ms}-${owner.nonce}`;
-    if (MANIFEST_LOCK.ownerKeys.some((key) => !Object.hasOwn(owner, key)) || typeof owner.claimed_at_ms !== 'number' || !Number.isInteger(owner.claimed_at_ms) || owner.claimed_at_ms < 0 || typeof owner.nonce !== 'string' || !MANIFEST_LOCK.staleTargetRe.test(staleTarget))
-        throw lockError('owner_invalid', 'manifest lock owner invalid');
-    return owner;
-}
-const readOwner = async (path) => parseOwner(await readFile(path, 'utf8'));
-async function writeOwner(lock, owner) {
-    const target = join(lock, 'owner');
-    const temporary = join(lock, `owner.${process.pid}.${token()}.tmp`);
-    let file;
-    try {
-        await createPrivateFile(temporary, `${JSON.stringify(owner)}\n`);
-        file = await open(temporary, 'r+');
-        await file.sync();
-        await file.close();
-        file = undefined;
-        await rename(temporary, target);
-    }
-    finally {
-        await file?.close().catch(() => { });
-        await unlink(temporary).catch(() => { });
-    }
-}
-// Split out from the sweep so the platform claim is testable from a POSIX runner: this takes
-// the basename FUNCTION, so a test can drive it with path.win32.basename without pretending
-// a Linux host is Windows. A filesystem test cannot do that -- on Linux a '/' split and
-// basename agree, so the defect below survives every filesystem test written against it.
-//
-// pathBasename, not a split on '/': on Windows the manifest path is backslash-separated, so a
-// '/' split yields the whole path, nothing matches the prefix, and the sweep becomes a silent
-// no-op on the one platform the quarantine bound is hardest to observe. Fails closed -- it
-// cannot reap the wrong directory -- but the feature is inert, which is worse than loud.
-export function manifestLockQuarantinePrefix(path, basename = pathBasename) {
-    const name = basename(path);
-    return name ? name : undefined;
-}
-async function reclaimStaleManifestLockQuarantines(path, ttlMs, claimDeadlineMs) {
-    const reclaimAgeMs = Math.max(ttlMs, claimDeadlineMs) + MANIFEST_LOCK_QUARANTINE_RECLAIM_MARGIN_MS;
-    let names;
-    try {
-        names = await readdir(dirname(path));
-    }
-    catch {
-        return;
-    }
-    const basename = manifestLockQuarantinePrefix(path);
-    if (!basename)
-        return;
-    await Promise.all(names.map(async (name) => {
-        const staleTarget = name.startsWith(basename) ? name.slice(basename.length) : undefined;
-        if (!staleTarget || !MANIFEST_LOCK.staleTargetRe.test(staleTarget))
-            return;
-        const target = join(dirname(path), name);
-        let metadata;
-        try {
-            metadata = await lstat(target);
-        }
-        catch {
-            return;
-        }
-        if (!metadata.isDirectory() || Date.now() - metadata.mtimeMs < reclaimAgeMs)
-            return;
-        await rm(target, { recursive: true, force: true }).catch(() => { });
-    }));
-}
-/** 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;
-            }
-            catch (error) {
-                if (code(error) !== 'EEXIST') {
-                    if (code(error) !== 'ENOENT')
-                        await rm(lock, { recursive: true, force: true }).catch(() => { });
-                    throw error;
-                }
-            }
-            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 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;
-                    }
-                }
-            }
-            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())));
-        }
-        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)
-                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 });
-                }
-            }
-        }
-    }
-    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')));
-    }
-    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));
-    }
-    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);
-    }
-    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 const { withManifestLock, writeHandleFileLocked } = createManifestLock();