@atomic-chat/core 0.5.1

package/dist/lock/instance-lock.d.ts

@@ -0,0 +1,93 @@
+/**
+ * One core owner per data folder (PLAN.md §3.4, §3.6).
+ *
+ * `<data>/atomic-core/instance.lock` is created exclusively (`open` with `wx`); its record carries
+ * the owner's PID *and* start identity, so a client can tell a live owner from a recycled PID. The
+ * record is written twice: `starting` when the lock is taken and `ready` once the control listener
+ * is bound, so a client never dials a port that is not listening yet.
+ *
+ * Recovering a stale lock is itself serialised through a second exclusive file, otherwise two
+ * clients that start together both decide the lock is stale and both become owner. A lock whose
+ * owner is alive — or whose liveness cannot be disproven — is never taken over.
+ */
+import { AtomicCoreError } from '../contracts/index.js';
+import type { DataLayout } from '../config/index.js';
+import type { IdentityDeps, IdentityVerdict } from './process-identity.js';
+export interface LockRecord {
+    instance_id: string;
+    owner_scope?: 'app' | 'cli' | undefined;
+    pid: number;
+    process_start_id: string | null;
+    owner_started_at?: string | null;
+    protocol: number;
+    version: string;
+    /** Canonical data folder: the lock's scope, so two paths to the same folder collide as they should. */
+    data_folder: string;
+    control_host: string;
+    control_port: number;
+    state: 'starting' | 'ready';
+    acquired_at: string;
+}
+export type LockState = {
+    kind: 'free';
+} | {
+    kind: 'owned';
+    record: LockRecord;
+    verdict: Extract<IdentityVerdict, 'match' | 'unknown'>;
+} | {
+    kind: 'stale';
+    record: LockRecord;
+    verdict: Extract<IdentityVerdict, 'dead' | 'mismatch'>;
+} | {
+    kind: 'corrupt';
+};
+/** How long a torn or unreadable lock is re-read before it counts as corrupt. */
+export declare const CORRUPT_LOCK_GRACE_MS = 500;
+/** A takeover mutex older than this belonged to a process that died mid-recovery. */
+export declare const TAKEOVER_MUTEX_TTL_MS = 30000;
+export declare const TAKEOVER_ATTEMPTS = 20;
+export declare const TAKEOVER_RETRY_MS = 50;
+export interface LockDeps extends IdentityDeps {
+    ownerScope?: 'app' | 'cli';
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+    /** Own start identity; injected in tests. */
+    selfStartId?: () => Promise<string | undefined>;
+}
+/** Resolve symlinks so `/tmp/x` and `/private/tmp/x` are one scope; unresolvable paths stay as given. */
+export declare function canonicalDataFolder(root: string): Promise<string>;
+/**
+ * Read the record. A record being written at this instant parses as garbage, so an unreadable file
+ * is re-read for `CORRUPT_LOCK_GRACE_MS` before the caller is told it is corrupt.
+ */
+export declare function readLockRecord(path: string, deps?: LockDeps): Promise<LockRecord | undefined | 'corrupt'>;
+export declare function parseLockRecord(text: string): LockRecord | undefined;
+export declare function inspectLock(layout: DataLayout, deps?: LockDeps): Promise<LockState>;
+export declare class InstanceLock {
+    private readonly handle;
+    private readonly path;
+    private current;
+    private readonly deps;
+    private constructor();
+    get record(): LockRecord;
+    get instanceId(): string;
+    /**
+     * Become the owner, or fail with `CORE_ALREADY_RUNNING` describing who holds it. A stale lock is
+     * recovered under a mutex so concurrent starters produce exactly one owner.
+     */
+    static acquire(layout: DataLayout, deps?: LockDeps): Promise<InstanceLock>;
+    /** Announce the bound control listener. Until this lands, clients see `state: "starting"`. */
+    publish(controlHost: string, controlPort: number): Promise<void>;
+    /** Release only what is still ours: a lock taken over by someone else is left alone. */
+    release(): Promise<void>;
+}
+export declare function alreadyRunning(record: LockRecord, verdict: 'match' | 'unknown'): AtomicCoreError;
+export interface WaitForOwnerOptions extends LockDeps {
+    timeoutMs?: number;
+    pollMs?: number;
+}
+/**
+ * Wait until an owner publishes its control endpoint. Used by a client that just launched a core:
+ * it must not dial before the listener is bound, and must give up when the launched process dies.
+ */
+export declare function waitForPublishedOwner(layout: DataLayout, options?: WaitForOwnerOptions): Promise<LockRecord>;

package/dist/lock/instance-lock.js

@@ -0,0 +1,244 @@
+/**
+ * One core owner per data folder (PLAN.md §3.4, §3.6).
+ *
+ * `<data>/atomic-core/instance.lock` is created exclusively (`open` with `wx`); its record carries
+ * the owner's PID *and* start identity, so a client can tell a live owner from a recycled PID. The
+ * record is written twice: `starting` when the lock is taken and `ready` once the control listener
+ * is bound, so a client never dials a port that is not listening yet.
+ *
+ * Recovering a stale lock is itself serialised through a second exclusive file, otherwise two
+ * clients that start together both decide the lock is stale and both become owner. A lock whose
+ * owner is alive — or whose liveness cannot be disproven — is never taken over.
+ */
+import { randomUUID } from 'node:crypto';
+import { mkdir, open, readFile, rm, stat } from 'node:fs/promises';
+import { realpath } from 'node:fs/promises';
+import { AtomicCoreError, CONTROL_PROTOCOL_VERSION } from '../contracts/index.js';
+import { CORE_VERSION } from '../version.js';
+import { identityPermitsTakeover, processStartEpoch, processStartId, verifyProcessIdentity, } from './process-identity.js';
+/** How long a torn or unreadable lock is re-read before it counts as corrupt. */
+export const CORRUPT_LOCK_GRACE_MS = 500;
+/** A takeover mutex older than this belonged to a process that died mid-recovery. */
+export const TAKEOVER_MUTEX_TTL_MS = 30_000;
+export const TAKEOVER_ATTEMPTS = 20;
+export const TAKEOVER_RETRY_MS = 50;
+const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const isEnoent = (e) => e.code === 'ENOENT';
+const isEexist = (e) => e.code === 'EEXIST';
+/** Resolve symlinks so `/tmp/x` and `/private/tmp/x` are one scope; unresolvable paths stay as given. */
+export async function canonicalDataFolder(root) {
+    return realpath(root).catch(() => root);
+}
+/**
+ * Read the record. A record being written at this instant parses as garbage, so an unreadable file
+ * is re-read for `CORRUPT_LOCK_GRACE_MS` before the caller is told it is corrupt.
+ */
+export async function readLockRecord(path, deps = {}) {
+    const sleep = deps.sleep ?? defaultSleep;
+    const now = deps.now ?? Date.now;
+    const deadline = now() + CORRUPT_LOCK_GRACE_MS;
+    for (;;) {
+        let text;
+        try {
+            text = await readFile(path, 'utf8');
+        }
+        catch (e) {
+            if (isEnoent(e))
+                return undefined;
+            throw new AtomicCoreError('IO_ERROR', `Cannot read the instance lock at ${path}`, e.message);
+        }
+        const parsed = parseLockRecord(text);
+        if (parsed)
+            return parsed;
+        if (now() >= deadline)
+            return 'corrupt';
+        await sleep(25);
+    }
+}
+export function parseLockRecord(text) {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+    if (!raw || typeof raw !== 'object')
+        return undefined;
+    const r = raw;
+    if (typeof r['instance_id'] !== 'string' || typeof r['pid'] !== 'number')
+        return undefined;
+    return {
+        instance_id: r['instance_id'],
+        owner_scope: r['owner_scope'] === 'app' || r['owner_scope'] === 'cli' ? r['owner_scope'] : undefined,
+        pid: r['pid'],
+        process_start_id: typeof r['process_start_id'] === 'string' ? r['process_start_id'] : null,
+        owner_started_at: typeof r['owner_started_at'] === 'string' ? r['owner_started_at'] : null,
+        protocol: typeof r['protocol'] === 'number' ? r['protocol'] : 0,
+        version: typeof r['version'] === 'string' ? r['version'] : '',
+        data_folder: typeof r['data_folder'] === 'string' ? r['data_folder'] : '',
+        control_host: typeof r['control_host'] === 'string' ? r['control_host'] : '',
+        control_port: typeof r['control_port'] === 'number' ? r['control_port'] : 0,
+        state: r['state'] === 'ready' ? 'ready' : 'starting',
+        acquired_at: typeof r['acquired_at'] === 'string' ? r['acquired_at'] : '',
+    };
+}
+export async function inspectLock(layout, deps = {}) {
+    const record = await readLockRecord(layout.core.instanceLock, deps);
+    if (record === undefined)
+        return { kind: 'free' };
+    if (record === 'corrupt')
+        return { kind: 'corrupt' };
+    const verdict = await verifyProcessIdentity(record.pid, record.process_start_id, deps);
+    return identityPermitsTakeover(verdict)
+        ? { kind: 'stale', record, verdict: verdict }
+        : { kind: 'owned', record, verdict: verdict };
+}
+export class InstanceLock {
+    handle;
+    path;
+    current;
+    deps;
+    constructor(handle, path, current, deps) {
+        this.handle = handle;
+        this.path = path;
+        this.current = current;
+        this.deps = deps;
+    }
+    get record() {
+        return { ...this.current };
+    }
+    get instanceId() {
+        return this.current.instance_id;
+    }
+    /**
+     * Become the owner, or fail with `CORE_ALREADY_RUNNING` describing who holds it. A stale lock is
+     * recovered under a mutex so concurrent starters produce exactly one owner.
+     */
+    static async acquire(layout, deps = {}) {
+        const sleep = deps.sleep ?? defaultSleep;
+        const path = layout.core.instanceLock;
+        await mkdir(layout.core.dir, { recursive: true });
+        const dataFolder = await canonicalDataFolder(layout.root);
+        // Two probes of the same process; on Windows each is a PowerShell start, so they run together.
+        const [selfId, ownerStartedAt] = await Promise.all([
+            deps.selfStartId ? deps.selfStartId() : processStartId(process.pid, deps),
+            processStartEpoch(process.pid, deps),
+        ]);
+        for (let attempt = 0; attempt < TAKEOVER_ATTEMPTS; attempt++) {
+            const handle = await open(path, 'wx').catch((e) => {
+                if (isEexist(e))
+                    return undefined;
+                throw new AtomicCoreError('IO_ERROR', `Cannot create the instance lock at ${path}`, e.message);
+            });
+            if (handle) {
+                const record = {
+                    instance_id: randomUUID(),
+                    owner_scope: deps.ownerScope ?? 'cli',
+                    pid: process.pid,
+                    process_start_id: selfId ?? null,
+                    owner_started_at: ownerStartedAt ?? null,
+                    protocol: CONTROL_PROTOCOL_VERSION,
+                    version: CORE_VERSION,
+                    data_folder: dataFolder,
+                    control_host: '',
+                    control_port: 0,
+                    state: 'starting',
+                    acquired_at: new Date().toISOString(),
+                };
+                await writeRecord(handle, record).catch(async (e) => {
+                    await handle.close().catch(() => { });
+                    await rm(path, { force: true }).catch(() => { });
+                    throw e;
+                });
+                return new InstanceLock(handle, path, record, deps);
+            }
+            const state = await inspectLock(layout, deps);
+            if (state.kind === 'owned')
+                throw alreadyRunning(state.record, state.verdict);
+            if (state.kind === 'free')
+                continue; // the holder released between our attempts
+            // stale or corrupt: recover, but only one starter at a time
+            const recovered = await tryRecoverStale(layout, deps);
+            if (!recovered)
+                await sleep(TAKEOVER_RETRY_MS);
+        }
+        throw new AtomicCoreError('CORE_START_FAILED', 'Could not acquire the core instance lock.', `${path} kept changing hands across ${TAKEOVER_ATTEMPTS} attempts`);
+    }
+    /** Announce the bound control listener. Until this lands, clients see `state: "starting"`. */
+    async publish(controlHost, controlPort) {
+        this.current = { ...this.current, control_host: controlHost, control_port: controlPort, state: 'ready' };
+        await writeRecord(this.handle, this.current);
+    }
+    /** Release only what is still ours: a lock taken over by someone else is left alone. */
+    async release() {
+        await this.handle.close().catch(() => { });
+        const onDisk = await readLockRecord(this.path, this.deps).catch(() => undefined);
+        if (onDisk && onDisk !== 'corrupt' && onDisk.instance_id !== this.current.instance_id)
+            return;
+        await rm(this.path, { force: true }).catch(() => { });
+    }
+}
+async function writeRecord(handle, record) {
+    const bytes = Buffer.from(`${JSON.stringify(record, null, 2)}\n`);
+    await handle.truncate(0);
+    await handle.write(bytes, 0, bytes.length, 0);
+    await handle.sync().catch(() => { });
+}
+export function alreadyRunning(record, verdict) {
+    const where = record.control_port ? `${record.control_host}:${record.control_port}` : 'not yet published';
+    const proof = verdict === 'match' ? 'confirmed' : 'could not be disproven';
+    return new AtomicCoreError('CORE_ALREADY_RUNNING', 'Another Atomic Chat core already owns this data folder.', `pid ${record.pid} (${proof}), instance ${record.instance_id}, control ${where}`);
+}
+/** Returns true when this caller performed the recovery; false when someone else is doing it. */
+async function tryRecoverStale(layout, deps) {
+    const now = deps.now ?? Date.now;
+    const mutexPath = `${layout.core.instanceLock}.takeover`;
+    const mutex = await open(mutexPath, 'wx').catch(async (e) => {
+        if (!isEexist(e))
+            throw new AtomicCoreError('IO_ERROR', `Cannot create ${mutexPath}`, e.message);
+        const age = await stat(mutexPath).then((s) => now() - s.mtimeMs, () => 0);
+        if (age > TAKEOVER_MUTEX_TTL_MS)
+            await rm(mutexPath, { force: true }).catch(() => { });
+        return undefined;
+    });
+    if (!mutex)
+        return false;
+    try {
+        await mutex.write(Buffer.from(`${process.pid}\n`));
+        // Re-check under the mutex: the previous reader's verdict may be out of date.
+        const state = await inspectLock(layout, deps);
+        if (state.kind === 'owned')
+            throw alreadyRunning(state.record, state.verdict);
+        if (state.kind === 'stale' || state.kind === 'corrupt') {
+            await rm(layout.core.instanceLock, { force: true });
+        }
+        return true;
+    }
+    finally {
+        await mutex.close().catch(() => { });
+        await rm(mutexPath, { force: true }).catch(() => { });
+    }
+}
+/**
+ * Wait until an owner publishes its control endpoint. Used by a client that just launched a core:
+ * it must not dial before the listener is bound, and must give up when the launched process dies.
+ */
+export async function waitForPublishedOwner(layout, options = {}) {
+    const now = options.now ?? Date.now;
+    const sleep = options.sleep ?? defaultSleep;
+    const deadline = now() + (options.timeoutMs ?? 15_000);
+    for (;;) {
+        const state = await inspectLock(layout, options);
+        if (state.kind === 'owned' && state.record.state === 'ready')
+            return state.record;
+        if (now() >= deadline) {
+            const detail = state.kind === 'owned'
+                ? `owner pid ${state.record.pid} did not publish a control port in time`
+                : `no live owner appeared (${state.kind})`;
+            throw new AtomicCoreError('CORE_START_FAILED', 'The Atomic Chat core did not become ready.', detail);
+        }
+        await sleep(options.pollMs ?? 25);
+    }
+}
+//# sourceMappingURL=instance-lock.js.map

package/dist/lock/instance-lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance-lock.js","sourceRoot":"","sources":["../../src/lock/instance-lock.ts"],"names":[],"mappings":"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"}

package/dist/lock/legacy-guard.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Reads what the desktop app's legacy runtime is holding, so the core does not load a model the app
+ * already has (PLAN.md §3.4, "Coexistence with legacy").
+ *
+ * Until the app becomes a core client, both runtimes can be live on one data folder. Two copies of
+ * one model double the VRAM and race for the GPU, and neither side can ask the other over IPC — so
+ * the app's llama.cpp plugin mirrors its session table to
+ * `<data>/atomic-core/legacy-runtime.json` and the core refuses before it mutates anything.
+ *
+ * Advisory by design: a file whose PID is gone is ignored (a crashed app holds nothing), an
+ * unreadable or malformed file means "nothing known", and the check never blocks on IO for long.
+ */
+import type { DataLayout } from '../config/index.js';
+export declare const LEGACY_RUNTIME_FILE = "legacy-runtime.json";
+export interface LegacySession {
+    model_id: string;
+    port: number;
+    pid: number;
+    is_embedding: boolean;
+}
+export interface LegacyRuntimeState {
+    /** The desktop app's PID. */
+    pid: number;
+    owner_start_id?: string;
+    updated_at: number;
+    provider: string;
+    sessions: LegacySession[];
+}
+export interface LegacyGuardDeps {
+    alive?: (pid: number) => boolean;
+    startId?: (pid: number) => Promise<string | undefined>;
+    read?: (path: string) => Promise<string | undefined>;
+}
+export declare function parseLegacyRuntimeState(text: string): LegacyRuntimeState | undefined;
+/**
+ * What the app holds right now, or `undefined` when it holds nothing we can prove: no file, a file
+ * we cannot parse, or one written by a process that is gone.
+ */
+export declare function readLegacyRuntime(layout: DataLayout, deps?: LegacyGuardDeps): Promise<LegacyRuntimeState | undefined>;
+/** The live legacy session for a model, if the app has it loaded. */
+export declare function legacySessionFor(state: LegacyRuntimeState | undefined, modelId: string): LegacySession | undefined;
+/**
+ * Refuse a load the desktop app already owns. Called before anything is spawned, so the user gets a
+ * sentence they can act on instead of a second copy of the model competing for the GPU.
+ */
+export declare function assertNotLoadedByLegacy(layout: DataLayout, modelId: string, deps?: LegacyGuardDeps): Promise<void>;

package/dist/lock/legacy-guard.js

@@ -0,0 +1,87 @@
+/**
+ * Reads what the desktop app's legacy runtime is holding, so the core does not load a model the app
+ * already has (PLAN.md §3.4, "Coexistence with legacy").
+ *
+ * Until the app becomes a core client, both runtimes can be live on one data folder. Two copies of
+ * one model double the VRAM and race for the GPU, and neither side can ask the other over IPC — so
+ * the app's llama.cpp plugin mirrors its session table to
+ * `<data>/atomic-core/legacy-runtime.json` and the core refuses before it mutates anything.
+ *
+ * Advisory by design: a file whose PID is gone is ignored (a crashed app holds nothing), an
+ * unreadable or malformed file means "nothing known", and the check never blocks on IO for long.
+ */
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { AtomicCoreError } from '../contracts/index.js';
+import { isProcessAlive, processStartEpoch } from './process-identity.js';
+export const LEGACY_RUNTIME_FILE = 'legacy-runtime.json';
+export function parseLegacyRuntimeState(text) {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+    if (!raw || typeof raw !== 'object')
+        return undefined;
+    const r = raw;
+    if (typeof r['pid'] !== 'number')
+        return undefined;
+    const sessions = Array.isArray(r['sessions']) ? r['sessions'] : [];
+    return {
+        pid: r['pid'],
+        ...(typeof r['owner_start_id'] === 'string' ? { owner_start_id: r['owner_start_id'] } : {}),
+        updated_at: typeof r['updated_at'] === 'number' ? r['updated_at'] : 0,
+        provider: typeof r['provider'] === 'string' ? r['provider'] : 'llamacpp-upstream',
+        sessions: sessions.filter(isLegacySession),
+    };
+}
+function isLegacySession(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const s = value;
+    return typeof s['model_id'] === 'string' && typeof s['pid'] === 'number';
+}
+/**
+ * What the app holds right now, or `undefined` when it holds nothing we can prove: no file, a file
+ * we cannot parse, or one written by a process that is gone.
+ */
+export async function readLegacyRuntime(layout, deps = {}) {
+    const read = deps.read ??
+        ((path) => readFile(path, 'utf8').then((t) => t, () => undefined));
+    const text = await read(join(layout.core.dir, LEGACY_RUNTIME_FILE));
+    if (text === undefined)
+        return undefined;
+    const state = parseLegacyRuntimeState(text);
+    if (!state)
+        return undefined;
+    const alive = deps.alive ?? isProcessAlive;
+    // A crashed app leaves a stale table behind; its backends are the reaper's problem, not a reason
+    // to refuse the user a model.
+    if (!alive(state.pid))
+        return undefined;
+    if (state.owner_start_id) {
+        const actual = await (deps.startId ?? processStartEpoch)(state.pid);
+        // Fail closed when the identity cannot be established; only a proven mismatch makes this stale.
+        if (actual && actual !== state.owner_start_id)
+            return undefined;
+    }
+    return state;
+}
+/** The live legacy session for a model, if the app has it loaded. */
+export function legacySessionFor(state, modelId) {
+    return state?.sessions.find((s) => s.model_id === modelId);
+}
+/**
+ * Refuse a load the desktop app already owns. Called before anything is spawned, so the user gets a
+ * sentence they can act on instead of a second copy of the model competing for the GPU.
+ */
+export async function assertNotLoadedByLegacy(layout, modelId, deps = {}) {
+    const state = await readLegacyRuntime(layout, deps);
+    const session = legacySessionFor(state, modelId);
+    if (!session)
+        return;
+    throw new AtomicCoreError('CORE_ALREADY_RUNNING', `The Atomic Chat app already has "${modelId}" loaded.`, `unload it in the app, or use it at http://127.0.0.1:${session.port} (app pid ${state.pid})`);
+}
+//# sourceMappingURL=legacy-guard.js.map

package/dist/lock/legacy-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"legacy-guard.js","sourceRoot":"","sources":["../../src/lock/legacy-guard.ts"],"names":[],"mappings":"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"}

package/dist/lock/model-claim.d.ts

@@ -0,0 +1,20 @@
+import type { DataLayout } from '../config/index.js';
+export interface ModelClaim {
+    claim_id: string;
+    provider: string;
+    model_id: string;
+    owner_kind: 'core' | 'app';
+    owner_pid: number;
+    owner_started_at: string | null;
+    owner_instance_id: string;
+    state: 'loading' | 'ready';
+    updated_at: string;
+}
+export interface ModelClaimHandle {
+    claim: ModelClaim;
+    path: string;
+    update(state: ModelClaim['state']): Promise<void>;
+    release(): Promise<void>;
+}
+export declare function modelClaimKey(provider: string, modelId: string): string;
+export declare function acquireModelClaim(layout: DataLayout, provider: string, modelId: string, ownerInstanceId: string): Promise<ModelClaimHandle>;

package/dist/lock/model-claim.js

@@ -0,0 +1,84 @@
+/** Atomic cross-process ownership claim for a model shared by the app and the core. */
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { AtomicCoreError } from '../contracts/index.js';
+import { isProcessAlive, processStartEpoch } from './process-identity.js';
+export function modelClaimKey(provider, modelId) {
+    return createHash('sha256').update(provider).update('\0').update(modelId).digest('hex');
+}
+export async function acquireModelClaim(layout, provider, modelId, ownerInstanceId) {
+    await mkdir(layout.core.modelClaims, { recursive: true });
+    const path = join(layout.core.modelClaims, modelClaimKey(provider, modelId));
+    const claim = {
+        claim_id: randomUUID(),
+        provider,
+        model_id: modelId,
+        owner_kind: 'core',
+        owner_pid: process.pid,
+        owner_started_at: (await processStartEpoch(process.pid)) ?? null,
+        owner_instance_id: ownerInstanceId,
+        state: 'loading',
+        updated_at: new Date().toISOString(),
+    };
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            await mkdir(path);
+            await writeClaim(path, claim);
+            return handle(path, claim);
+        }
+        catch (e) {
+            if (e.code !== 'EEXIST')
+                throw e;
+            const existing = await readClaim(path);
+            if (existing?.owner_kind === 'core' && existing.owner_instance_id === ownerInstanceId)
+                return handle(path, existing);
+            if (!existing || !(await claimOwnerIsStale(existing))) {
+                throw new AtomicCoreError('CORE_ALREADY_RUNNING', `Another runtime already owns "${modelId}".`, existing ? `${existing.owner_kind} pid ${existing.owner_pid} (${existing.state})` : path);
+            }
+            const stale = `${path}.stale-${randomUUID()}`;
+            await rename(path, stale).catch(() => undefined);
+            await rm(stale, { recursive: true, force: true }).catch(() => undefined);
+        }
+    }
+    throw new AtomicCoreError('CORE_ALREADY_RUNNING', `Could not claim "${modelId}".`);
+}
+async function claimOwnerIsStale(claim) {
+    if (!isProcessAlive(claim.owner_pid))
+        return true;
+    if (!claim.owner_started_at)
+        return false;
+    const actual = await processStartEpoch(claim.owner_pid);
+    return actual !== undefined && actual !== claim.owner_started_at;
+}
+async function readClaim(path) {
+    try {
+        return JSON.parse(await readFile(join(path, 'claim.json'), 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+async function writeClaim(path, claim) {
+    const target = join(path, 'claim.json');
+    const temp = join(path, `claim.${claim.claim_id}.${randomUUID()}.tmp`);
+    await writeFile(temp, `${JSON.stringify(claim, null, 2)}\n`);
+    await rename(temp, target);
+}
+function handle(path, claim) {
+    return {
+        claim,
+        path,
+        async update(state) {
+            claim.state = state;
+            claim.updated_at = new Date().toISOString();
+            await writeClaim(path, claim);
+        },
+        async release() {
+            const current = await readClaim(path);
+            if (current?.claim_id === claim.claim_id)
+                await rm(path, { recursive: true, force: true });
+        },
+    };
+}
+//# sourceMappingURL=model-claim.js.map

package/dist/lock/model-claim.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-claim.js","sourceRoot":"","sources":["../../src/lock/model-claim.ts"],"names":[],"mappings":"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"}