@schnick371/devsteps-shared 1.1.0-next.3 → 2.0.0-next.1

package/dist/core/coord-read.js.map

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

package/dist/core/coord-store.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * File layer of the coordination store (TASK-957).
+ * - IDs are claimed with a non-recursive `mkdir` above the highest ID on disk; a folder is never
+ *   removed, and a purged record leaves a tombstone, so an ID is never reused.
+ * - A write appends to the journal first and then renames the record into place, guarded by the
+ *   version it replaces (the `StaleItemError` pattern, no lock).
+ * - A read validates every record against the one schema and the journal. An invalid or
+ *   hand-written record is moved to `quarantine/` and reported, never skipped.
+ */
+import { type CoordKind, CoordRecord } from '../schemas/coord.js';
+import { type CoordPaths } from './coord-paths.js';
+/** Handover versions kept besides the current one. */
+export declare const HANDOVER_HISTORY = 5;
+export interface QuarantineReport {
+    id: string;
+    file: string;
+    reason: string;
+}
+export interface LoadedRecords {
+    records: CoordRecord[];
+    quarantined: QuarantineReport[];
+}
+/** Thrown when another writer replaced the record since it was read. */
+export declare class CoordConflictError extends Error {
+    readonly recordId: string;
+    readonly code = "COORD_CONFLICT";
+    constructor(recordId: string);
+}
+/** Claim the next free ID of a kind by creating its folder. */
+export declare function claimId(paths: CoordPaths, kind: CoordKind): string;
+/**
+ * Write a record: journal entry, then an atomic rename. `previousVersion` is the version the
+ * caller read (null for a new record); a different version on disk refuses the write.
+ */
+export declare function persistRecord(paths: CoordPaths, record: CoordRecord, transition: string, previousVersion: number | null): void;
+/** Replace a purged record with its tombstone; the folder stays so the ID is never reused. */
+export declare function tombstoneRecord(paths: CoordPaths, record: CoordRecord, at: string): void;
+/**
+ * Every live record, validated; offenders are named in the result. A read by an agent moves
+ * them to `quarantine/` (`move: true`); the start sweep only reports, so the agent's next read
+ * still sees and reports them in band.
+ */
+export declare function loadRecords(paths: CoordPaths, options?: {
+    move?: boolean;
+}): LoadedRecords;
+/** Earlier versions of a handover, newest first. */
+export declare function readHistory(paths: CoordPaths, id: string): unknown[];
+//# sourceMappingURL=coord-store.d.ts.map

package/dist/core/coord-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coord-store.d.ts","sourceRoot":"","sources":["../../src/core/coord-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAaH,OAAO,EAGL,KAAK,SAAS,EACd,WAAW,EACZ,MAAM,qBAAqB,CAAC;AAQ7B,OAAO,EACL,KAAK,UAAU,EAQhB,MAAM,kBAAkB,CAAC;AAE1B,sDAAsD;AACtD,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAElC,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,WAAW,EAAE,gBAAgB,EAAE,CAAC;CACjC;AAED,wEAAwE;AACxE,qBAAa,kBAAmB,SAAQ,KAAK;IAE/B,QAAQ,CAAC,QAAQ,EAAE,MAAM;IADrC,QAAQ,CAAC,IAAI,oBAAoB;IACjC,YAAqB,QAAQ,EAAE,MAAM,EAGpC;CACF;AAED,+DAA+D;AAC/D,wBAAgB,OAAO,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,GAAG,MAAM,CAalE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,WAAW,EACnB,UAAU,EAAE,MAAM,EAClB,eAAe,EAAE,MAAM,GAAG,IAAI,GAC7B,IAAI,CAkBN;AAED,8FAA8F;AAC9F,wBAAgB,eAAe,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAYxF;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,GAAE;IAAE,IAAI,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,aAAa,CAqB9F;AAED,oDAAoD;AACpD,wBAAgB,WAAW,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,EAAE,CAMpE"}

package/dist/core/coord-store.js

@@ -0,0 +1,188 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * File layer of the coordination store (TASK-957).
+ * - IDs are claimed with a non-recursive `mkdir` above the highest ID on disk; a folder is never
+ *   removed, and a purged record leaves a tombstone, so an ID is never reused.
+ * - A write appends to the journal first and then renames the record into place, guarded by the
+ *   version it replaces (the `StaleItemError` pattern, no lock).
+ * - A read validates every record against the one schema and the journal. An invalid or
+ *   hand-written record is moved to `quarantine/` and reported, never skipped.
+ */
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from 'node:fs';
+import { join } from 'node:path';
+import { COORD_ID_PREFIX, COORD_SCHEMA_VERSION, CoordRecord, } from '../schemas/coord.js';
+import { appendJournal, journalKey, readJournal, sha256, } from './coord-journal.js';
+import { ensureCoordRoot, highestNumber, historyDir, listRecordIds, recordDir, recordFile, tombstoneFile, } from './coord-paths.js';
+/** Handover versions kept besides the current one. */
+export const HANDOVER_HISTORY = 5;
+/** Thrown when another writer replaced the record since it was read. */
+export class CoordConflictError extends Error {
+    recordId;
+    code = 'COORD_CONFLICT';
+    constructor(recordId) {
+        super(`${recordId} changed since it was read — read it again and retry`);
+        this.recordId = recordId;
+        this.name = 'CoordConflictError';
+    }
+}
+/** Claim the next free ID of a kind by creating its folder. */
+export function claimId(paths, kind) {
+    ensureCoordRoot(paths);
+    let next = highestNumber(paths, kind) + 1;
+    for (let attempt = 0; attempt < 100; attempt++, next++) {
+        const id = `${COORD_ID_PREFIX[kind]}-${next}`;
+        try {
+            mkdirSync(recordDir(paths, id), { recursive: false });
+            return id;
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+        }
+    }
+    throw new Error(`Could not claim a ${kind} ID after 100 attempts`);
+}
+/**
+ * Write a record: journal entry, then an atomic rename. `previousVersion` is the version the
+ * caller read (null for a new record); a different version on disk refuses the write.
+ */
+export function persistRecord(paths, record, transition, previousVersion) {
+    const target = recordFile(paths, record.id);
+    const onDisk = readVersion(target);
+    if (onDisk !== previousVersion)
+        throw new CoordConflictError(record.id);
+    if (record.kind === 'handover' && previousVersion !== null)
+        keepHistory(paths, record.id);
+    const content = `${JSON.stringify(CoordRecord.parse(record), null, 2)}\n`;
+    appendJournal(paths.journal, {
+        id: record.id,
+        version: record.version,
+        sha256: sha256(content),
+        kind: record.kind,
+        transition,
+        at: record.updated_at,
+    });
+    const temporary = `${target}.${process.pid}.${Date.now()}.tmp`;
+    writeFileSync(temporary, content, 'utf8');
+    renameSync(temporary, target);
+}
+/** Replace a purged record with its tombstone; the folder stays so the ID is never reused. */
+export function tombstoneRecord(paths, record, at) {
+    appendJournal(paths.journal, {
+        id: record.id,
+        version: record.version + 1,
+        sha256: '',
+        kind: record.kind,
+        transition: 'purge',
+        at,
+    });
+    writeFileSync(tombstoneFile(paths, record.id), `${JSON.stringify({ id: record.id, at })}\n`);
+    rmSync(recordFile(paths, record.id), { force: true });
+    rmSync(historyDir(paths, record.id), { recursive: true, force: true });
+}
+/**
+ * Every live record, validated; offenders are named in the result. A read by an agent moves
+ * them to `quarantine/` (`move: true`); the start sweep only reports, so the agent's next read
+ * still sees and reports them in band.
+ */
+export function loadRecords(paths, options = {}) {
+    const move = options.move ?? true;
+    let journal = readJournal(paths.journal);
+    const records = [];
+    const quarantined = [];
+    for (const id of listRecordIds(paths)) {
+        const file = recordFile(paths, id);
+        if (!existsSync(file))
+            continue; // tombstone, or a folder a parallel create just claimed
+        const content = readFileSync(file, 'utf8');
+        let checked = checkRecord(id, content, journal);
+        if ('reason' in checked && checked.journalMiss) {
+            // A writer journals before it renames: a record newer than this read's journal snapshot
+            // is checked once more against the journal as it is now, before anything is moved.
+            journal = readJournal(paths.journal);
+            checked = checkRecord(id, content, journal);
+        }
+        if ('record' in checked)
+            records.push(checked.record);
+        else if (checked.move && move)
+            quarantined.push(quarantine(paths, id, file, checked.reason));
+        else
+            quarantined.push({ id, file, reason: checked.reason });
+    }
+    return { records, quarantined };
+}
+/** Earlier versions of a handover, newest first. */
+export function readHistory(paths, id) {
+    const dir = historyDir(paths, id);
+    if (!existsSync(dir))
+        return [];
+    return historyFiles(dir)
+        .reverse()
+        .map((name) => JSON.parse(readFileSync(join(dir, name), 'utf8')));
+}
+function checkRecord(id, content, journal) {
+    let value;
+    try {
+        value = JSON.parse(content);
+    }
+    catch {
+        return { reason: 'not valid JSON', move: true };
+    }
+    const declared = value?.schema_version;
+    if (typeof declared === 'number' && declared > COORD_SCHEMA_VERSION) {
+        // A newer server wrote it: report, but leave it for that server.
+        return { reason: `schema_version ${declared} is newer than this server`, move: false };
+    }
+    const parsed = CoordRecord.safeParse(value);
+    if (!parsed.success) {
+        const issue = parsed.error.issues[0];
+        return { reason: `schema: ${issue?.path.join('.') || 'record'} ${issue?.message}`, move: true };
+    }
+    if (parsed.data.id !== id) {
+        return { reason: `id ${parsed.data.id} does not match its folder`, move: true };
+    }
+    if (!journal.versions.get(id)?.has(journalKey(parsed.data.version, sha256(content)))) {
+        return {
+            reason: 'not written by the store (no journal entry for this content)',
+            move: true,
+            journalMiss: true,
+        };
+    }
+    return { record: parsed.data };
+}
+function quarantine(paths, id, file, reason) {
+    mkdirSync(paths.quarantine, { recursive: true });
+    const target = join(paths.quarantine, `${id}.${Date.now()}.json`);
+    renameSync(file, target);
+    return { id, file: target, reason };
+}
+function readVersion(file) {
+    if (!existsSync(file))
+        return null;
+    try {
+        const version = JSON.parse(readFileSync(file, 'utf8')).version;
+        return typeof version === 'number' ? version : null;
+    }
+    catch {
+        return null;
+    }
+}
+function keepHistory(paths, id) {
+    const dir = historyDir(paths, id);
+    mkdirSync(dir, { recursive: true });
+    const current = recordFile(paths, id);
+    copyFileSync(current, join(dir, `v${readVersion(current) ?? 0}.json`));
+    const files = historyFiles(dir);
+    for (const name of files.slice(0, Math.max(0, files.length - HANDOVER_HISTORY))) {
+        rmSync(join(dir, name), { force: true });
+    }
+}
+/** History files in version order, oldest first. */
+function historyFiles(dir) {
+    return readdirSync(dir)
+        .filter((name) => /^v[0-9]+\.json$/.test(name))
+        .sort((left, right) => Number(left.slice(1, -5)) - Number(right.slice(1, -5)));
+}
+//# sourceMappingURL=coord-store.js.map

package/dist/core/coord-store.js.map

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

package/dist/core/coord-summary.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Derived views of the coordination store (TASK-957): the stale flag, the triage hint that
+ * every coord response and `status` carry, and the one-line pull summary for `status`/`context`.
+ * Nothing here writes; staleness is computed, never stored.
+ */
+import type { CoordRecord } from '../schemas/coord.js';
+export declare const STALE_DISPATCH_HOURS = 72;
+export declare const OPEN_REQUEST_HINT_COUNT = 10;
+export declare const OLD_REQUEST_HINT_HOURS = 24;
+export declare const COORD_RETENTION_DAYS = 30;
+export declare function isOpen(record: CoordRecord): boolean;
+export declare function isStale(record: CoordRecord, now: Date): boolean;
+/** "40 min", "26 h", "3 d" — the age a person reads at a glance. */
+export declare function formatAge(since: string, now: Date): string;
+/** The in-band triage hint: from 10 open requests, or one older than 24 h. */
+export declare function coordHints(records: readonly CoordRecord[], now: Date): string[];
+/** One pull line, or null when nothing is open. */
+export declare function coordPullLine(records: readonly CoordRecord[], now: Date): string | null;
+export declare function expiryFrom(now: Date): string;
+//# sourceMappingURL=coord-summary.d.ts.map

package/dist/core/coord-summary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coord-summary.d.ts","sourceRoot":"","sources":["../../src/core/coord-summary.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAGvD,eAAO,MAAM,oBAAoB,KAAK,CAAC;AACvC,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAC1C,eAAO,MAAM,sBAAsB,KAAK,CAAC;AACzC,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAEvC,wBAAgB,MAAM,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAEnD;AAED,wBAAgB,OAAO,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,EAAE,IAAI,GAAG,OAAO,CAM/D;AAED,oEAAoE;AACpE,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,GAAG,MAAM,CAK1D;AAQD,8EAA8E;AAC9E,wBAAgB,UAAU,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,EAAE,GAAG,EAAE,IAAI,GAAG,MAAM,EAAE,CAU/E;AAED,mDAAmD;AACnD,wBAAgB,aAAa,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,EAAE,GAAG,EAAE,IAAI,GAAG,MAAM,GAAG,IAAI,CAmBvF;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,IAAI,GAAG,MAAM,CAE5C"}

package/dist/core/coord-summary.js

@@ -0,0 +1,70 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Derived views of the coordination store (TASK-957): the stale flag, the triage hint that
+ * every coord response and `status` carry, and the one-line pull summary for `status`/`context`.
+ * Nothing here writes; staleness is computed, never stored.
+ */
+const HOUR = 3_600_000;
+export const STALE_DISPATCH_HOURS = 72;
+export const OPEN_REQUEST_HINT_COUNT = 10;
+export const OLD_REQUEST_HINT_HOURS = 24;
+export const COORD_RETENTION_DAYS = 30;
+export function isOpen(record) {
+    return record.status === 'open' || record.status === 'dispatched' || record.status === 'reported';
+}
+export function isStale(record, now) {
+    return (record.kind === 'dispatch' &&
+        isOpen(record) &&
+        now.getTime() - Date.parse(record.updated_at) > STALE_DISPATCH_HOURS * HOUR);
+}
+/** "40 min", "26 h", "3 d" — the age a person reads at a glance. */
+export function formatAge(since, now) {
+    const minutes = Math.max(0, Math.floor((now.getTime() - Date.parse(since)) / 60_000));
+    if (minutes < 60)
+        return `${minutes} min`;
+    if (minutes < 48 * 60)
+        return `${Math.floor(minutes / 60)} h`;
+    return `${Math.floor(minutes / 1_440)} d`;
+}
+function openRequests(records) {
+    return records
+        .filter((record) => record.kind === 'request' && record.status === 'open')
+        .sort((left, right) => left.created_at.localeCompare(right.created_at));
+}
+/** The in-band triage hint: from 10 open requests, or one older than 24 h. */
+export function coordHints(records, now) {
+    const open = openRequests(records);
+    const oldest = open[0];
+    if (!oldest)
+        return [];
+    const oldestHours = (now.getTime() - Date.parse(oldest.created_at)) / HOUR;
+    if (open.length < OPEN_REQUEST_HINT_COUNT && oldestHours <= OLD_REQUEST_HINT_HOURS)
+        return [];
+    return [
+        `coord: ${open.length} open request${open.length === 1 ? '' : 's'}, oldest ` +
+            `${formatAge(oldest.created_at, now)} — coordinator triage due`,
+    ];
+}
+/** One pull line, or null when nothing is open. */
+export function coordPullLine(records, now) {
+    const parts = [];
+    const requests = openRequests(records);
+    const oldest = requests[0];
+    if (oldest) {
+        parts.push(`${requests.length} open request${requests.length === 1 ? '' : 's'} ` +
+            `(oldest ${formatAge(oldest.created_at, now)})`);
+    }
+    const dispatches = records.filter((record) => record.kind === 'dispatch' && isOpen(record));
+    if (dispatches.length > 0) {
+        const stale = dispatches.filter((record) => isStale(record, now)).length;
+        parts.push(`${dispatches.length} open dispatch${dispatches.length === 1 ? '' : 'es'}` +
+            (stale > 0 ? ` (${stale} stale)` : ''));
+    }
+    return parts.length > 0 ? `coord: ${parts.join(', ')}` : null;
+}
+export function expiryFrom(now) {
+    return new Date(now.getTime() + COORD_RETENTION_DAYS * 24 * HOUR).toISOString();
+}
+//# sourceMappingURL=coord-summary.js.map

package/dist/core/coord-summary.js.map

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

package/dist/core/coord-sweep.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Start sweep of the coordination store (TASK-957). It runs when a server starts, under a `wx`
+ * lock so parallel starts do not sweep twice, and never on reads. It closes dispatches whose
+ * item finished and replaces every record past its expiry with a tombstone. A handover and an
+ * open record never expire. A lock older than ten minutes was left by a killed process.
+ */
+import { type QuarantineReport } from './coord-store.js';
+import type { CoordOptions } from './coord-write.js';
+export interface CoordSweepResult {
+    /** False when another process holds the sweep lock. */
+    swept: boolean;
+    purged: string[];
+    closed: string[];
+    quarantined: QuarantineReport[];
+}
+export declare function coordSweep(devstepsDir: string, options?: CoordOptions): CoordSweepResult;
+//# sourceMappingURL=coord-sweep.d.ts.map

package/dist/core/coord-sweep.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coord-sweep.d.ts","sourceRoot":"","sources":["../../src/core/coord-sweep.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,EAAE,KAAK,gBAAgB,EAAmB,MAAM,kBAAkB,CAAC;AAC1E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAIrD,MAAM,WAAW,gBAAgB;IAC/B,uDAAuD;IACvD,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,WAAW,EAAE,gBAAgB,EAAE,CAAC;CACjC;AAED,wBAAgB,UAAU,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,GAAE,YAAiB,GAAG,gBAAgB,CAwB5F"}

package/dist/core/coord-sweep.js

@@ -0,0 +1,60 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Start sweep of the coordination store (TASK-957). It runs when a server starts, under a `wx`
+ * lock so parallel starts do not sweep twice, and never on reads. It closes dispatches whose
+ * item finished and replaces every record past its expiry with a tombstone. A handover and an
+ * open record never expire. A lock older than ten minutes was left by a killed process.
+ */
+import { closeSync, existsSync, openSync, rmSync, statSync } from 'node:fs';
+import { coordPaths } from './coord-paths.js';
+import { loadReconciled } from './coord-read.js';
+import { tombstoneRecord } from './coord-store.js';
+const STALE_LOCK_MS = 10 * 60_000;
+export function coordSweep(devstepsDir, options = {}) {
+    const now = (options.now ?? (() => new Date()))();
+    const paths = coordPaths(devstepsDir);
+    const empty = { purged: [], closed: [], quarantined: [] };
+    if (!existsSync(paths.records))
+        return { swept: true, ...empty };
+    const handle = acquire(paths.sweepLock, now);
+    if (handle === null)
+        return { swept: false, ...empty };
+    try {
+        const { records, quarantined, closed } = loadReconciled(devstepsDir, paths, now, {
+            move: false,
+        });
+        const purged = [];
+        for (const record of records) {
+            if (record.expires_at !== null && Date.parse(record.expires_at) <= now.getTime()) {
+                tombstoneRecord(paths, record, now.toISOString());
+                purged.push(record.id);
+            }
+        }
+        return { swept: true, purged, closed, quarantined };
+    }
+    finally {
+        closeSync(handle);
+        rmSync(paths.sweepLock, { force: true });
+    }
+}
+function acquire(lockPath, now) {
+    try {
+        return openSync(lockPath, 'wx');
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+    }
+    if (now.getTime() - statSync(lockPath).mtimeMs < STALE_LOCK_MS)
+        return null;
+    rmSync(lockPath, { force: true });
+    try {
+        return openSync(lockPath, 'wx');
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=coord-sweep.js.map

package/dist/core/coord-sweep.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coord-sweep.js","sourceRoot":"","sources":["../../src/core/coord-sweep.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC5E,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAyB,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAG1E,MAAM,aAAa,GAAG,EAAE,GAAG,MAAM,CAAC;AAUlC,MAAM,UAAU,UAAU,CAAC,WAAmB,EAAE,OAAO,GAAiB,EAAE;IACxE,MAAM,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;IAClD,MAAM,KAAK,GAAG,UAAU,CAAC,WAAW,CAAC,CAAC;IACtC,MAAM,KAAK,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,WAAW,EAAE,EAAE,EAAE,CAAC;IAC1D,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,OAAO,CAAC;QAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,KAAK,EAAE,CAAC;IAEjE,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;IAC7C,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,KAAK,EAAE,CAAC;IACvD,IAAI,CAAC;QACH,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,cAAc,CAAC,WAAW,EAAE,KAAK,EAAE,GAAG,EAAE;YAC/E,IAAI,EAAE,KAAK;SACZ,CAAC,CAAC;QACH,MAAM,MAAM,GAAa,EAAE,CAAC;QAC5B,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC7B,IAAI,MAAM,CAAC,UAAU,KAAK,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,GAAG,CAAC,OAAO,EAAE,EAAE,CAAC;gBACjF,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,WAAW,EAAE,CAAC,CAAC;gBAClD,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;YACzB,CAAC;QACH,CAAC;QACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;IACtD,CAAC;YAAS,CAAC;QACT,SAAS,CAAC,MAAM,CAAC,CAAC;QAClB,MAAM,CAAC,KAAK,CAAC,SAAS,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAC3C,CAAC;AACH,CAAC;AAED,SAAS,OAAO,CAAC,QAAgB,EAAE,GAAS;IAC1C,IAAI,CAAC;QACH,OAAO,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IAClC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ;YAAE,MAAM,KAAK,CAAC;IACtE,CAAC;IACD,IAAI,GAAG,CAAC,OAAO,EAAE,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC,OAAO,GAAG,aAAa;QAAE,OAAO,IAAI,CAAC;IAC5E,MAAM,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAClC,IAAI,CAAC;QACH,OAAO,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IAClC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/core/coord-target.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Request target kinds (STORY-525): known ID namespaces, independent of record retention.
+ * This classification describes a reference; writers still validate that its target exists.
+ */
+declare const RECORD_TARGET_KINDS: readonly ['handover', 'request', 'dispatch'];
+export type CoordTargetKind = 'item' | (typeof RECORD_TARGET_KINDS)[number];
+/** Unknown legacy prefixes and designations carry no supported target kind. */
+export declare function coordTargetKind(id: string | undefined): CoordTargetKind | undefined;
+export {};
+//# sourceMappingURL=coord-target.d.ts.map

package/dist/core/coord-target.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coord-target.d.ts","sourceRoot":"","sources":["../../src/core/coord-target.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,QAAA,MAAM,mBAAmB,YAAI,UAAU,EAAE,SAAS,EAAE,UAAU,CAAU,CAAC;AACzE,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5E,+EAA+E;AAC/E,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,eAAe,GAAG,SAAS,CAKnF"}

package/dist/core/coord-target.js

@@ -0,0 +1,20 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Request target kinds (STORY-525): known ID namespaces, independent of record retention.
+ * This classification describes a reference; writers still validate that its target exists.
+ */
+import { COORD_ID_PREFIX, COORD_ID_RE } from '../schemas/coord.js';
+import { parseItemId } from '../utils/index.js';
+const RECORD_TARGET_KINDS = ['handover', 'request', 'dispatch'];
+/** Unknown legacy prefixes and designations carry no supported target kind. */
+export function coordTargetKind(id) {
+    if (id === undefined)
+        return undefined;
+    if (parseItemId(id))
+        return 'item';
+    const prefix = id.match(COORD_ID_RE)?.[1];
+    return RECORD_TARGET_KINDS.find((kind) => COORD_ID_PREFIX[kind] === prefix);
+}
+//# sourceMappingURL=coord-target.js.map

package/dist/core/coord-target.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coord-target.js","sourceRoot":"","sources":["../../src/core/coord-target.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACnE,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD,MAAM,mBAAmB,GAAG,CAAC,UAAU,EAAE,SAAS,EAAE,UAAU,CAAU,CAAC;AAGzE,+EAA+E;AAC/E,MAAM,UAAU,eAAe,CAAC,EAAsB;IACpD,IAAI,EAAE,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACvC,IAAI,WAAW,CAAC,EAAE,CAAC;QAAE,OAAO,MAAM,CAAC;IACnC,MAAM,MAAM,GAAG,EAAE,CAAC,KAAK,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAC1C,OAAO,mBAAmB,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,eAAe,CAAC,IAAI,CAAC,KAAK,MAAM,CAAC,CAAC;AAC9E,CAAC"}

package/dist/core/coord-write.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * `coord_write` (TASK-957): one action on one record. The server sets ID, status, times,
+ * version, expiry and writer; the state machines refuse illegal moves, and terminal records
+ * are immutable. A request is never refused for volume; designations and dispatches are capped.
+ */
+import { type CoordRecord } from '../schemas/coord.js';
+import { type QuarantineReport } from './coord-store.js';
+export interface CoordOptions {
+    /** Name of the client that called, recorded as the writer's client. */
+    client?: string;
+    /** Clock; tests inject one. */
+    now?: () => Date;
+}
+export interface CoordWriteResult {
+    record: CoordRecord;
+    transition: string;
+    hints: string[];
+    quarantined: QuarantineReport[];
+}
+interface WriteContext {
+    devstepsDir: string;
+    records: CoordRecord[];
+    writer: {
+        designation: string;
+        client: string;
+        retired?: true;
+    };
+    now: string;
+}
+export declare function coordWrite(devstepsDir: string, raw: Record<string, unknown>, options?: CoordOptions): CoordWriteResult;
+interface Applied {
+    record: Omit<CoordRecord, 'schema_version'>;
+    /** Version replaced, or null for a new record. */
+    previous: number | null;
+    transition: string;
+}
+/** A new version of `current`; a move into a terminal status starts its retention. */
+export declare function nextVersion(context: Pick<WriteContext, 'writer' | 'now'>, current: CoordRecord, changes: Record<string, unknown>, transition: string): Applied;
+export {};
+//# sourceMappingURL=coord-write.d.ts.map

package/dist/core/coord-write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coord-write.d.ts","sourceRoot":"","sources":["../../src/core/coord-write.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAKL,KAAK,WAAW,EACjB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EAAuC,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAK9F,MAAM,WAAW,YAAY;IAC3B,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+BAA+B;IAC/B,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,WAAW,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,WAAW,EAAE,gBAAgB,EAAE,CAAC;CACjC;AAED,UAAU,YAAY;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,MAAM,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,IAAI,CAAA;KAAE,CAAC;IAChE,GAAG,EAAE,MAAM,CAAC;CACb;AAED,wBAAgB,UAAU,CACxB,WAAW,EAAE,MAAM,EACnB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,OAAO,GAAE,YAAiB,GACzB,gBAAgB,CA4BlB;AAED,UAAU,OAAO;IACf,MAAM,EAAE,IAAI,CAAC,WAAW,EAAE,gBAAgB,CAAC,CAAC;IAC5C,kDAAkD;IAClD,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;CACpB;AAiJD,sFAAsF;AACtF,wBAAgB,WAAW,CACzB,OAAO,EAAE,IAAI,CAAC,YAAY,EAAE,QAAQ,GAAG,KAAK,CAAC,EAC7C,OAAO,EAAE,WAAW,EACpB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,UAAU,EAAE,MAAM,GACjB,OAAO,CAeT"}