ushman-ledger 0.3.0

package/dist/schema/manifest.js

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+import { LedgerPhaseSchema } from "./entry.js";
+export const LedgerArchiveMetadataSchema = z.object({
+    createdAt: z.string().datetime({ offset: true }),
+    integrityHash: z.string().length(64),
+    outPath: z.string().min(1),
+});
+export const LedgerManifestSchema = z
+    .object({
+    archives: z.array(LedgerArchiveMetadataSchema).default([]),
+    createdAt: z.string().datetime({ offset: true }),
+    entryCount: z.number().int().nonnegative().default(0),
+    entryLocations: z
+        .record(z.string(), z.object({
+        phase: LedgerPhaseSchema,
+        sequence: z.number().int().positive(),
+    }))
+        .default({}),
+    idempotencyIndex: z.record(z.string(), z.record(z.string(), z.string())).default({}),
+    lastSequence: z.number().int().nonnegative().default(0),
+    perPhaseCounts: z.record(z.string(), z.number().int().nonnegative()).default({}),
+    perPhaseLatest: z.record(z.string(), z.string()).default({}),
+    schemaVersion: z.literal('ushman-ledger-manifest/v1'),
+    updatedAt: z.string().datetime({ offset: true }),
+    workspaceId: z.string().uuid(),
+})
+    .passthrough();

package/dist/schema/note.d.ts

@@ -0,0 +1,10 @@
+import { z } from 'zod';
+export declare const NoteSubkindSchema: z.ZodEnum<{
+    regression: "regression";
+    automation: "automation";
+    retro: "retro";
+    operator: "operator";
+    "tooling-gap": "tooling-gap";
+}>;
+export type NoteSubkind = z.infer<typeof NoteSubkindSchema>;
+//# sourceMappingURL=note.d.ts.map

package/dist/schema/note.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"note.d.ts","sourceRoot":"","sources":["../../src/schema/note.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,iBAAiB;;;;;;EAA2E,CAAC;AAE1G,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC"}

package/dist/schema/note.js

@@ -0,0 +1,2 @@
+import { z } from 'zod';
+export const NoteSubkindSchema = z.enum(['regression', 'automation', 'retro', 'operator', 'tooling-gap']);

package/dist/storage/filesystem.d.ts

@@ -0,0 +1,35 @@
+import { LEDGER_PHASES, type LedgerPhase } from '../schema/entry.ts';
+import { type LedgerManifest } from '../schema/manifest.ts';
+export { LEDGER_PHASES };
+export declare const LEDGER_ROOT_SEGMENTS: readonly [".lab", "ledger"];
+export declare const LEDGER_STALE_TEMP_MS = 60000;
+type AtomicWriteTestHook = {
+    readonly beforeRename?: () => Promise<void>;
+};
+export type LedgerPaths = {
+    readonly analyticsSummaryFile: string;
+    readonly blobsDir: string;
+    readonly lockFile: (phase: LedgerPhase) => string;
+    readonly manifestLockFile: string;
+    readonly manifestFile: string;
+    readonly pendingCommitsDir: string;
+    readonly pendingArchivesDir: string;
+    readonly phaseDir: (phase: LedgerPhase) => string;
+    readonly readIndexFile: string;
+    readonly renderFile: string;
+    readonly renderTimelineFile: string;
+    readonly root: string;
+    readonly workspaceRoot: string;
+};
+export declare const resolveLedgerPaths: (workspaceRoot: string) => LedgerPaths;
+export declare const ensureLedgerDirectories: (workspaceRoot: string) => Promise<LedgerPaths>;
+export declare const setAtomicWriteTestHook: (filePath: string, hook: AtomicWriteTestHook | null) => void;
+export declare const writeAtomicTextFile: (filePath: string, text: string) => Promise<void>;
+export declare const writeAtomicJsonFile: (filePath: string, value: unknown) => Promise<void>;
+export declare const readManifest: (workspaceRoot: string) => Promise<LedgerManifest>;
+export declare const saveManifest: (workspaceRoot: string, manifest: LedgerManifest) => Promise<void>;
+export declare const cleanupStaleTempFiles: (workspaceRoot: string) => Promise<void>;
+export declare const readPhaseEntryFileNames: (workspaceRoot: string, phase: LedgerPhase) => Promise<string[]>;
+export declare const readPhaseEntryText: (workspaceRoot: string, phase: LedgerPhase, fileName: string) => Promise<string>;
+export declare const writeEntryFile: (workspaceRoot: string, phase: LedgerPhase, fileName: string, value: unknown) => Promise<string>;
+//# sourceMappingURL=filesystem.d.ts.map

package/dist/storage/filesystem.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem.d.ts","sourceRoot":"","sources":["../../src/storage/filesystem.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,aAAa,EAAE,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACrE,OAAO,EAAE,KAAK,cAAc,EAAwB,MAAM,uBAAuB,CAAC;AAElF,OAAO,EAAE,aAAa,EAAE,CAAC;AACzB,eAAO,MAAM,oBAAoB,6BAA8B,CAAC;AAChE,eAAO,MAAM,oBAAoB,QAAS,CAAC;AAC3C,KAAK,mBAAmB,GAAG;IACvB,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/C,CAAC;AAaF,MAAM,MAAM,WAAW,GAAG;IACtB,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,MAAM,CAAC;IAClD,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,MAAM,CAAC;IAClD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAClC,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAAI,eAAe,MAAM,KAAG,WAiB1D,CAAC;AAEF,eAAO,MAAM,uBAAuB,GAAU,eAAe,MAAM,KAAG,OAAO,CAAC,WAAW,CAYxF,CAAC;AAEF,eAAO,MAAM,sBAAsB,GAAI,UAAU,MAAM,EAAE,MAAM,mBAAmB,GAAG,IAAI,SAOxF,CAAC;AAoBF,eAAO,MAAM,mBAAmB,GAAU,UAAU,MAAM,EAAE,MAAM,MAAM,kBAiBvE,CAAC;AAEF,eAAO,MAAM,mBAAmB,GAAU,UAAU,MAAM,EAAE,OAAO,OAAO,kBAEzE,CAAC;AAoCF,eAAO,MAAM,YAAY,GAAU,eAAe,MAAM,KAAG,OAAO,CAAC,cAAc,CAmBhF,CAAC;AAEF,eAAO,MAAM,YAAY,GAAU,eAAe,MAAM,EAAE,UAAU,cAAc,kBASjF,CAAC;AAoFF,eAAO,MAAM,qBAAqB,GAAU,eAAe,MAAM,kBAIhE,CAAC;AAEF,eAAO,MAAM,uBAAuB,GAAU,eAAe,MAAM,EAAE,OAAO,WAAW,KAAG,OAAO,CAAC,MAAM,EAAE,CAOzG,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAAU,eAAe,MAAM,EAAE,OAAO,WAAW,EAAE,UAAU,MAAM,oBAGnG,CAAC;AAEF,eAAO,MAAM,cAAc,GAAU,eAAe,MAAM,EAAE,OAAO,WAAW,EAAE,UAAU,MAAM,EAAE,OAAO,OAAO,oBAK/G,CAAC"}

package/dist/storage/filesystem.js

@@ -0,0 +1,258 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, open, readdir, readFile, rename, rm, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { stableStringify } from "../json.js";
+import { readLabManifestMin } from "../lab-min.js";
+import { LEDGER_PHASES } from "../schema/entry.js";
+import { LedgerManifestSchema } from "../schema/manifest.js";
+export { LEDGER_PHASES };
+export const LEDGER_ROOT_SEGMENTS = ['.lab', 'ledger'];
+export const LEDGER_STALE_TEMP_MS = 60_000;
+const atomicWriteTestHooks = new Map();
+const resolveAtomicWriteKey = (filePath) => path.resolve(filePath);
+const consumeAtomicWriteTestHook = (filePath) => {
+    const key = resolveAtomicWriteKey(filePath);
+    const hook = atomicWriteTestHooks.get(key);
+    atomicWriteTestHooks.delete(key);
+    return hook;
+};
+export const resolveLedgerPaths = (workspaceRoot) => {
+    const root = path.join(workspaceRoot, ...LEDGER_ROOT_SEGMENTS);
+    return {
+        analyticsSummaryFile: path.join(root, 'analytics-summary.json'),
+        blobsDir: path.join(root, 'blobs'),
+        lockFile: (phase) => path.join(root, phase, '.lock'),
+        manifestFile: path.join(root, 'manifest.json'),
+        manifestLockFile: path.join(root, '.manifest.lock'),
+        pendingArchivesDir: path.join(root, 'pending-archives'),
+        pendingCommitsDir: path.join(root, 'pending'),
+        phaseDir: (phase) => path.join(root, phase),
+        readIndexFile: path.join(root, 'read-index.json'),
+        renderFile: path.join(root, 'render.md'),
+        renderTimelineFile: path.join(root, 'render.timeline.html'),
+        root,
+        workspaceRoot,
+    };
+};
+export const ensureLedgerDirectories = async (workspaceRoot) => {
+    const paths = resolveLedgerPaths(workspaceRoot);
+    await mkdir(paths.root, { recursive: true });
+    await mkdir(paths.blobsDir, { recursive: true });
+    await mkdir(paths.pendingCommitsDir, { recursive: true });
+    await mkdir(paths.pendingArchivesDir, { recursive: true });
+    await Promise.all(LEDGER_PHASES.map(async (phase) => {
+        await mkdir(paths.phaseDir(phase), { recursive: true });
+    }));
+    return paths;
+};
+export const setAtomicWriteTestHook = (filePath, hook) => {
+    const key = resolveAtomicWriteKey(filePath);
+    if (!hook) {
+        atomicWriteTestHooks.delete(key);
+        return;
+    }
+    atomicWriteTestHooks.set(key, hook);
+};
+const createManifest = async (workspaceRoot) => {
+    const labManifest = await readLabManifestMin(workspaceRoot);
+    const now = new Date().toISOString();
+    return LedgerManifestSchema.parse({
+        archives: [],
+        createdAt: now,
+        entryCount: 0,
+        entryLocations: {},
+        idempotencyIndex: {},
+        lastSequence: 0,
+        perPhaseCounts: {},
+        perPhaseLatest: {},
+        schemaVersion: 'ushman-ledger-manifest/v1',
+        updatedAt: now,
+        workspaceId: labManifest.workspaceId,
+    });
+};
+export const writeAtomicTextFile = async (filePath, text) => {
+    await mkdir(path.dirname(filePath), { recursive: true });
+    const tempPath = `${filePath}.tmp.${process.pid}.${Date.now()}.${randomUUID()}`;
+    const handle = await open(tempPath, 'w');
+    try {
+        await handle.writeFile(text, 'utf8');
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    await consumeAtomicWriteTestHook(filePath)?.beforeRename?.();
+    try {
+        await rename(tempPath, filePath);
+    }
+    catch (error) {
+        await rm(tempPath, { force: true });
+        throw error;
+    }
+};
+export const writeAtomicJsonFile = async (filePath, value) => {
+    await writeAtomicTextFile(filePath, `${stableStringify(value, true)}\n`);
+};
+const parseManifestText = (filePath, text) => {
+    try {
+        return LedgerManifestSchema.parse(JSON.parse(text));
+    }
+    catch (error) {
+        throw new Error(`Invalid ledger manifest at ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+};
+const writeNewTextFileExclusive = async (filePath, text) => {
+    await mkdir(path.dirname(filePath), { recursive: true });
+    let handle;
+    try {
+        handle = await open(filePath, 'wx');
+    }
+    catch (error) {
+        if (error.code === 'EEXIST') {
+            return false;
+        }
+        throw error;
+    }
+    try {
+        await handle.writeFile(text, 'utf8');
+        await handle.sync();
+        return true;
+    }
+    catch (error) {
+        await rm(filePath, { force: true });
+        throw error;
+    }
+    finally {
+        await handle.close();
+    }
+};
+export const readManifest = async (workspaceRoot) => {
+    const paths = await ensureLedgerDirectories(workspaceRoot);
+    try {
+        const text = await readFile(paths.manifestFile, 'utf8');
+        return parseManifestText(paths.manifestFile, text);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code !== 'ENOENT') {
+            throw error;
+        }
+    }
+    const manifest = await createManifest(workspaceRoot);
+    const created = await writeNewTextFileExclusive(paths.manifestFile, `${stableStringify(manifest, true)}\n`);
+    if (created) {
+        return manifest;
+    }
+    const text = await readFile(paths.manifestFile, 'utf8');
+    return parseManifestText(paths.manifestFile, text);
+};
+export const saveManifest = async (workspaceRoot, manifest) => {
+    const paths = await ensureLedgerDirectories(workspaceRoot);
+    await writeAtomicJsonFile(paths.manifestFile, LedgerManifestSchema.parse({
+        ...manifest,
+        updatedAt: new Date().toISOString(),
+    }));
+};
+const isTempFile = (name) => name.includes('.tmp.');
+const parseTempOwnerPid = (fileName) => {
+    const match = /\.tmp\.(\d+)\./u.exec(fileName);
+    if (!match) {
+        return null;
+    }
+    return Number.parseInt(match[1], 10);
+};
+const isProcessAlive = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === 'EPERM') {
+            return true;
+        }
+        if (code === 'ESRCH') {
+            return false;
+        }
+        throw error;
+    }
+};
+const resolveFinalPathFromTemp = (filePath) => {
+    const fileName = path.basename(filePath);
+    const tempMarkerIndex = fileName.lastIndexOf('.tmp.');
+    if (tempMarkerIndex === -1) {
+        return null;
+    }
+    return path.join(path.dirname(filePath), fileName.slice(0, tempMarkerIndex));
+};
+const cleanupStaleTempFile = async (fullPath) => {
+    let fileStat;
+    try {
+        fileStat = await stat(fullPath);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return;
+        }
+        throw error;
+    }
+    const ownerPid = parseTempOwnerPid(path.basename(fullPath));
+    if (Date.now() - fileStat.mtimeMs < LEDGER_STALE_TEMP_MS) {
+        return;
+    }
+    if (ownerPid !== null && isProcessAlive(ownerPid)) {
+        return;
+    }
+    const finalPath = resolveFinalPathFromTemp(fullPath);
+    if (finalPath) {
+        try {
+            await stat(finalPath);
+            await rm(fullPath, { force: true });
+            return;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT') {
+                throw error;
+            }
+        }
+    }
+    await rm(fullPath, { force: true });
+};
+const listLedgerTempFiles = async (root) => {
+    const entries = await readdir(root, { withFileTypes: true });
+    const tempFiles = [];
+    for (const entry of entries) {
+        const fullPath = path.join(root, entry.name);
+        if (entry.isDirectory()) {
+            tempFiles.push(...(await listLedgerTempFiles(fullPath)));
+            continue;
+        }
+        if (entry.isFile() && isTempFile(entry.name)) {
+            tempFiles.push(fullPath);
+        }
+    }
+    return tempFiles;
+};
+export const cleanupStaleTempFiles = async (workspaceRoot) => {
+    const paths = await ensureLedgerDirectories(workspaceRoot);
+    const tempFiles = await listLedgerTempFiles(paths.root);
+    await Promise.all(tempFiles.map(async (filePath) => cleanupStaleTempFile(filePath)));
+};
+export const readPhaseEntryFileNames = async (workspaceRoot, phase) => {
+    const paths = await ensureLedgerDirectories(workspaceRoot);
+    const entries = await readdir(paths.phaseDir(phase), { withFileTypes: true });
+    return entries
+        .filter((entry) => entry.isFile() && entry.name.endsWith('.json'))
+        .map((entry) => entry.name)
+        .sort((left, right) => left.localeCompare(right));
+};
+export const readPhaseEntryText = async (workspaceRoot, phase, fileName) => {
+    const paths = await ensureLedgerDirectories(workspaceRoot);
+    return readFile(path.join(paths.phaseDir(phase), fileName), 'utf8');
+};
+export const writeEntryFile = async (workspaceRoot, phase, fileName, value) => {
+    const paths = await ensureLedgerDirectories(workspaceRoot);
+    const filePath = path.join(paths.phaseDir(phase), fileName);
+    await writeAtomicJsonFile(filePath, value);
+    return filePath;
+};

package/dist/storage/lock.d.ts

@@ -0,0 +1,18 @@
+type LockOptions = {
+    readonly retryDelayMs: number;
+    readonly staleMs: number;
+    readonly testHooks?: {
+        readonly afterStaleObservation?: (context: {
+            lockPath: string;
+            rawText: string;
+        }) => Promise<void>;
+    };
+    readonly timeoutMs: number;
+};
+export type LockHandle = {
+    readonly assertOwnership: () => Promise<void>;
+    readonly release: () => Promise<void>;
+};
+export declare const acquireLock: (lockPath: string, options?: Partial<LockOptions>) => Promise<LockHandle>;
+export {};
+//# sourceMappingURL=lock.d.ts.map

package/dist/storage/lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.d.ts","sourceRoot":"","sources":["../../src/storage/lock.ts"],"names":[],"mappings":"AAGA,KAAK,WAAW,GAAG;IACf,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE;QACjB,QAAQ,CAAC,qBAAqB,CAAC,EAAE,CAAC,OAAO,EAAE;YAAE,QAAQ,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;KACtG,CAAC;IACF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC9B,CAAC;AAqLF,MAAM,MAAM,UAAU,GAAG;IACrB,QAAQ,CAAC,eAAe,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,QAAQ,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACzC,CAAC;AA+BF,eAAO,MAAM,WAAW,GAAU,UAAU,MAAM,EAAE,UAAS,OAAO,CAAC,WAAW,CAAM,KAAG,OAAO,CAAC,UAAU,CAgD1G,CAAC"}

package/dist/storage/lock.js

@@ -0,0 +1,224 @@
+import { randomUUID } from 'node:crypto';
+import { open, readFile, rename, rm, stat } from 'node:fs/promises';
+const DEFAULT_LOCK_OPTIONS = {
+    // Give writers enough time to detect and reclaim a stale lock before timing out.
+    retryDelayMs: 10,
+    staleMs: 30_000,
+    timeoutMs: 35_000,
+};
+const sleep = async (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const readLockState = async (lockPath) => {
+    try {
+        const rawText = await readFile(lockPath, 'utf8');
+        try {
+            const parsed = JSON.parse(rawText);
+            const startedAt = typeof parsed.startedAt === 'string' ? Date.parse(parsed.startedAt) : Number.NaN;
+            return {
+                rawText,
+                startedAtMs: Number.isNaN(startedAt) ? null : startedAt,
+                token: typeof parsed.token === 'string' && parsed.token.length > 0 ? parsed.token : null,
+            };
+        }
+        catch {
+            return {
+                rawText,
+                startedAtMs: null,
+                token: null,
+            };
+        }
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return null;
+        }
+        throw error;
+    }
+};
+const isFreshLockState = (lockState, staleMs) => {
+    if (lockState.startedAtMs === null) {
+        return false;
+    }
+    return Date.now() - lockState.startedAtMs < staleMs;
+};
+const buildReclaimMarkerPath = (lockPath) => `${lockPath}.reclaim`;
+const buildQuarantinePath = (lockPath, token) => `${lockPath}.stale.${token ?? 'corrupt'}.${process.pid}.${Date.now()}.${randomUUID()}`;
+const writeExclusiveTextFile = async (filePath, text) => {
+    let handle;
+    try {
+        handle = await open(filePath, 'wx');
+    }
+    catch (error) {
+        if (error.code === 'EEXIST') {
+            return false;
+        }
+        throw error;
+    }
+    try {
+        await handle.writeFile(text, 'utf8');
+        await handle.sync();
+        return true;
+    }
+    finally {
+        await handle.close();
+    }
+};
+const reclaimMarkerExists = async (lockPath) => {
+    try {
+        await stat(buildReclaimMarkerPath(lockPath));
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return false;
+        }
+        throw error;
+    }
+};
+const acquireReclaimMarker = async (lockPath) => {
+    const reclaimMarkerPath = buildReclaimMarkerPath(lockPath);
+    const created = await writeExclusiveTextFile(reclaimMarkerPath, `${JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString() }, null, 2)}\n`);
+    if (!created) {
+        return null;
+    }
+    return {
+        release: async () => rm(reclaimMarkerPath, { force: true }),
+    };
+};
+const restoreQuarantinedLock = async (lockPath, quarantinePath) => {
+    try {
+        await rename(quarantinePath, lockPath);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === 'ENOENT') {
+            return;
+        }
+        if (code === 'EEXIST') {
+            await rm(quarantinePath, { force: true });
+            return;
+        }
+        throw error;
+    }
+};
+const reclaimIfObservedStateMatches = async ({ lockPath, observedState, testHooks, }) => {
+    // The reclaim marker prevents a fresh owner from keeping a lock created while
+    // stale reclamation temporarily moves the observed lock path out of the way.
+    const reclaimMarker = await acquireReclaimMarker(lockPath);
+    if (!reclaimMarker) {
+        return false;
+    }
+    try {
+        const currentState = await readLockState(lockPath);
+        if (!currentState || currentState.rawText !== observedState.rawText) {
+            return false;
+        }
+        await testHooks?.afterStaleObservation?.({
+            lockPath,
+            rawText: observedState.rawText,
+        });
+        const quarantinePath = buildQuarantinePath(lockPath, observedState.token);
+        try {
+            await rename(lockPath, quarantinePath);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                return false;
+            }
+            throw error;
+        }
+        try {
+            const quarantinedState = await readLockState(quarantinePath);
+            if (!quarantinedState || quarantinedState.rawText !== observedState.rawText) {
+                await restoreQuarantinedLock(lockPath, quarantinePath);
+                return false;
+            }
+            await rm(quarantinePath, { force: true });
+            return true;
+        }
+        finally {
+            await rm(quarantinePath, { force: true });
+        }
+    }
+    finally {
+        await reclaimMarker.release();
+    }
+};
+const reclaimIfStale = async (lockPath, options) => {
+    const observedState = await readLockState(lockPath);
+    if (!observedState || isFreshLockState(observedState, options.staleMs)) {
+        return false;
+    }
+    return reclaimIfObservedStateMatches({
+        lockPath,
+        observedState,
+        testHooks: options.testHooks,
+    });
+};
+const describeCurrentLockState = async (lockPath) => {
+    const [currentState, reclaiming] = await Promise.all([readLockState(lockPath), reclaimMarkerExists(lockPath)]);
+    if (!currentState) {
+        return reclaiming ? 'lock missing while stale reclamation marker is present' : 'lock file is missing';
+    }
+    const ageMs = currentState.startedAtMs === null ? 'unknown age' : `${Date.now() - currentState.startedAtMs}ms old`;
+    return `${ageMs}, token=${currentState.token ?? 'missing'}, reclaiming=${reclaiming ? 'yes' : 'no'}`;
+};
+const assertOwnership = async (lockPath, token) => {
+    if (await reclaimMarkerExists(lockPath)) {
+        throw new Error(`Lost ledger lock ownership for ${lockPath}: stale reclamation is in progress.`);
+    }
+    const currentState = await readLockState(lockPath);
+    if (currentState?.token !== token) {
+        throw new Error(`Lost ledger lock ownership for ${lockPath}: expected token ${token}, found ${currentState?.token ?? 'missing'}.`);
+    }
+};
+const releaseIfOwned = async (lockPath, token) => {
+    const currentState = await readLockState(lockPath);
+    if (currentState?.token !== token) {
+        return;
+    }
+    await rm(lockPath, { force: true });
+};
+export const acquireLock = async (lockPath, options = {}) => {
+    const mergedOptions = { ...DEFAULT_LOCK_OPTIONS, ...options };
+    const deadline = Date.now() + mergedOptions.timeoutMs;
+    while (Date.now() <= deadline) {
+        if (await reclaimMarkerExists(lockPath)) {
+            await sleep(mergedOptions.retryDelayMs);
+            continue;
+        }
+        const token = randomUUID();
+        let handle;
+        try {
+            handle = await open(lockPath, 'wx');
+            try {
+                await handle.writeFile(`${JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString(), token }, null, 2)}\n`, 'utf8');
+                await handle.sync();
+            }
+            catch (error) {
+                await rm(lockPath, { force: true });
+                throw error;
+            }
+            finally {
+                await handle.close();
+            }
+            if (await reclaimMarkerExists(lockPath)) {
+                await releaseIfOwned(lockPath, token);
+                await sleep(mergedOptions.retryDelayMs);
+                continue;
+            }
+            return {
+                assertOwnership: async () => assertOwnership(lockPath, token),
+                release: async () => releaseIfOwned(lockPath, token),
+            };
+        }
+        catch (error) {
+            const code = error.code;
+            if (code !== 'EEXIST') {
+                throw error;
+            }
+            await reclaimIfStale(lockPath, mergedOptions);
+            await sleep(mergedOptions.retryDelayMs);
+        }
+    }
+    throw new Error(`Timed out waiting for ledger lock after ${mergedOptions.timeoutMs}ms: ${lockPath} (${await describeCurrentLockState(lockPath)}).`);
+};

package/dist/uuid.d.ts

@@ -0,0 +1,7 @@
+export declare const isUuidV7: (value: string) => boolean;
+export declare const generateUuidV7: () => string;
+export declare const createDeterministicUuidV7: ({ seed, timestamp, }: {
+    readonly seed: string;
+    readonly timestamp: number | string;
+}) => string;
+//# sourceMappingURL=uuid.d.ts.map

package/dist/uuid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uuid.d.ts","sourceRoot":"","sources":["../src/uuid.ts"],"names":[],"mappings":"AAmBA,eAAO,MAAM,QAAQ,GAAI,OAAO,MAAM,YAAgC,CAAC;AAEvE,eAAO,MAAM,cAAc,cAAiB,CAAC;AAE7C,eAAO,MAAM,yBAAyB,GAAI,sBAGvC;IACC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;CACvC,WAQA,CAAC"}

package/dist/uuid.js

@@ -0,0 +1,25 @@
+import { uuidv7 } from 'uuidv7';
+import { sha256Hex } from "./json.js";
+const UUID_V7_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u;
+const toTimestampHex = (timestamp) => timestamp.toString(16).padStart(12, '0').slice(-12);
+const normalizeTimestamp = (timestamp) => {
+    if (typeof timestamp === 'number') {
+        if (!Number.isFinite(timestamp) || timestamp < 0) {
+            return 0;
+        }
+        return Math.trunc(timestamp);
+    }
+    const parsed = Date.parse(timestamp);
+    return Number.isNaN(parsed) ? 0 : parsed;
+};
+export const isUuidV7 = (value) => UUID_V7_PATTERN.test(value);
+export const generateUuidV7 = () => uuidv7();
+export const createDeterministicUuidV7 = ({ seed, timestamp, }) => {
+    const hash = sha256Hex(seed);
+    const timestampHex = toTimestampHex(normalizeTimestamp(timestamp));
+    const versionedSegment = `7${hash.slice(0, 3)}`;
+    const variantNibble = ((Number.parseInt(hash[3] ?? '0', 16) & 0x3) | 0x8).toString(16);
+    const variantSegment = `${variantNibble}${hash.slice(4, 7)}`;
+    const tailSegment = hash.slice(7, 19);
+    return `${timestampHex.slice(0, 8)}-${timestampHex.slice(8, 12)}-${versionedSegment}-${variantSegment}-${tailSegment}`;
+};

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+export declare const LEDGER_LIBRARY_VERSION = "1.0.0";
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,sBAAsB,UAAU,CAAC"}

package/dist/version.js

@@ -0,0 +1 @@
+export const LEDGER_LIBRARY_VERSION = '1.0.0';