project-tiny-context-harness 0.11.0 → 0.12.0

package/dist/lib/maintenance-lock.js

@@ -0,0 +1,203 @@
+// File-maintenance lock extracted from the existing lock implementation.
+// No task execution state or machine completion semantics live here.
+import { randomUUID } from "node:crypto";
+import { link, lstat, open, readFile, unlink } from "node:fs/promises";
+import { canonicalJson } from "./strict-codec.js";
+import { ensureSafeRepositoryDirectory, assertSafeRepositoryFilePath, } from "./repository-path-safety.js";
+export async function withMaintenanceLock(repository, operation, action) {
+    await ensureSafeRepositoryDirectory(repository, "tmp/ty-context", "maintenance_lock_parent");
+    const safe = await assertSafeRepositoryFilePath(repository, "tmp/ty-context/maintenance.lock", "maintenance_lock", { destinationMayBeAbsent: true });
+    const owner = {
+        schema_version: "maintenance-lock-owner-v1",
+        lock_id: randomUUID(),
+        pid: process.pid,
+        operation,
+        created_at: new Date().toISOString(),
+    };
+    const bytes = Buffer.from(canonicalJson(owner));
+    const lock = await acquireMaintenanceLock(safe.absolute, bytes, false);
+    const snapshot = await readMaintenanceLockSnapshot(safe.absolute);
+    assertLockSnapshotOwner(snapshot, bytes);
+    try {
+        return await action();
+    }
+    finally {
+        await lock.close();
+        await releaseMaintenanceLock(safe.absolute, bytes, snapshot.identity);
+    }
+}
+async function acquireMaintenanceLock(lockFile, ownerBytes, forceClear) {
+    try {
+        return await createMaintenanceLock(lockFile, ownerBytes);
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+    }
+    let stale;
+    try {
+        stale = await readMaintenanceLockSnapshot(lockFile);
+    }
+    catch (error) {
+        throw new Error(`maintenance_compare_and_swap_failed:lock_unavailable:owner_unreadable_manual_recovery_required:${message(error)}`);
+    }
+    if (stale.identity.nlink !== 1n)
+        throw new Error("maintenance_compare_and_swap_failed:lock_owner_hardlinked_manual_recovery_required");
+    if (processIsLive(stale.owner.pid))
+        throw new Error(`maintenance_compare_and_swap_failed:lock_unavailable:live_owner:${stale.owner.pid}:${stale.owner.operation}`);
+    const claim = `${lockFile}.reclaim-${stale.owner.lock_id}`;
+    try {
+        await link(lockFile, claim);
+    }
+    catch (error) {
+        if (error.code === "EEXIST")
+            throw new Error(`maintenance_compare_and_swap_failed:lock_reclaim_interrupted_manual_recovery_required:${forceClear ? "force_clear" : "automatic"}:${stale.owner.lock_id}`);
+        throw error;
+    }
+    let acquired = null;
+    try {
+        const [current, claimed] = await Promise.all([
+            readMaintenanceLockSnapshot(lockFile),
+            readMaintenanceLockSnapshot(claim),
+        ]);
+        assertSameLockSnapshot(current, claimed);
+        assertClaimedLockTransition(current, stale);
+        if (processIsLive(stale.owner.pid))
+            throw new Error(`maintenance_compare_and_swap_failed:lock_unavailable:owner_became_live:${stale.owner.pid}`);
+        await unlink(lockFile);
+        try {
+            acquired = await createMaintenanceLock(lockFile, ownerBytes);
+        }
+        catch (error) {
+            if (error.code === "EEXIST")
+                throw new Error("maintenance_compare_and_swap_failed:lock_unavailable:reclaim_lost");
+            throw error;
+        }
+    }
+    catch (error) {
+        await unlink(claim).catch(() => undefined);
+        throw error;
+    }
+    try {
+        await unlink(claim);
+    }
+    catch (error) {
+        await acquired.close().catch(() => undefined);
+        await removeOwnedAcquisition(lockFile, ownerBytes).catch(() => undefined);
+        throw new Error(`maintenance_lock_reclaim_cleanup_failed:${message(error)}`);
+    }
+    return acquired;
+}
+async function createMaintenanceLock(lockFile, ownerBytes) {
+    const handle = await open(lockFile, "wx");
+    try {
+        await handle.writeFile(ownerBytes);
+        await handle.sync();
+        return handle;
+    }
+    catch (error) {
+        await handle.close().catch(() => undefined);
+        await unlink(lockFile).catch(() => undefined);
+        throw error;
+    }
+}
+async function releaseMaintenanceLock(lockFile, ownerBytes, identity) {
+    const current = await readMaintenanceLockSnapshot(lockFile).catch((error) => {
+        throw new Error(`maintenance_lock_release_ownership_lost:${message(error)}`);
+    });
+    if (!current.bytes.equals(ownerBytes) ||
+        !sameLockIdentity(current.identity, identity))
+        throw new Error("maintenance_lock_release_ownership_lost");
+    await unlink(lockFile);
+}
+async function readMaintenanceLockSnapshot(lockFile) {
+    const before = await lstat(lockFile, { bigint: true });
+    if (!before.isFile() || before.isSymbolicLink())
+        throw new Error("maintenance_lock_owner_unsafe");
+    const bytes = await readFile(lockFile);
+    const after = await lstat(lockFile, { bigint: true });
+    if (!sameLockIdentity(before, after))
+        throw new Error("maintenance_lock_owner_changed_during_read");
+    if (after.ino === 0n)
+        throw new Error("maintenance_lock_owner_identity_unavailable");
+    let value;
+    try {
+        value = JSON.parse(bytes.toString("utf8"));
+    }
+    catch (error) {
+        throw new Error(`maintenance_lock_owner_invalid:${message(error)}`);
+    }
+    const owner = validateMaintenanceLockOwner(value);
+    if (!bytes.equals(Buffer.from(canonicalJson(owner), "utf8")))
+        throw new Error("maintenance_lock_owner_noncanonical");
+    return { bytes, identity: after, owner };
+}
+function validateMaintenanceLockOwner(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("maintenance_lock_owner_object_required");
+    const row = value;
+    if (Object.keys(row).sort().join("\0") !==
+        ["created_at", "lock_id", "operation", "pid", "schema_version"]
+            .sort()
+            .join("\0") ||
+        row.schema_version !== "maintenance-lock-owner-v1" ||
+        typeof row.lock_id !== "string" ||
+        !/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u.test(row.lock_id) ||
+        typeof row.pid !== "number" ||
+        !Number.isSafeInteger(row.pid) ||
+        row.pid <= 0 ||
+        !maintenanceOperation(row.operation) ||
+        typeof row.created_at !== "string" ||
+        !Number.isFinite(Date.parse(row.created_at)))
+        throw new Error("maintenance_lock_owner_invalid");
+    return row;
+}
+function maintenanceOperation(value) {
+    return ["sync", "upgrade", "context_mutation", "export"].includes(value);
+}
+function processIsLive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code !== "ESRCH";
+    }
+}
+function assertLockSnapshotOwner(snapshot, ownerBytes) {
+    if (!snapshot.bytes.equals(ownerBytes))
+        throw new Error("maintenance_lock_acquire_ownership_lost");
+}
+function assertSameLockSnapshot(current, expected) {
+    if (!current.bytes.equals(expected.bytes) ||
+        !sameLockIdentity(current.identity, expected.identity))
+        throw new Error("maintenance_compare_and_swap_failed:lock_reclaim_owner_changed");
+}
+function assertClaimedLockTransition(current, expected) {
+    if (!current.bytes.equals(expected.bytes) ||
+        current.identity.dev !== expected.identity.dev ||
+        current.identity.ino !== expected.identity.ino ||
+        current.identity.size !== expected.identity.size ||
+        current.identity.mode !== expected.identity.mode ||
+        current.identity.mtimeNs !== expected.identity.mtimeNs ||
+        current.identity.nlink !== 2n)
+        throw new Error("maintenance_compare_and_swap_failed:lock_reclaim_owner_changed");
+}
+async function removeOwnedAcquisition(lockFile, ownerBytes) {
+    const current = await readMaintenanceLockSnapshot(lockFile);
+    if (!current.bytes.equals(ownerBytes))
+        throw new Error("maintenance_lock_acquire_cleanup_ownership_lost");
+    await unlink(lockFile);
+}
+function sameLockIdentity(left, right) {
+    return (left.dev === right.dev &&
+        left.ino === right.ino &&
+        left.nlink === right.nlink &&
+        left.size === right.size &&
+        left.mode === right.mode &&
+        left.mtimeNs === right.mtimeNs &&
+        left.ctimeNs === right.ctimeNs);
+}
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/lib/maintenance-write.d.ts

@@ -0,0 +1,3 @@
+import type { MutationFileState } from "./context-mutation/mutation-types.js";
+export declare function writeMaintenanceText(repository: string, relative: string, text: string, expected?: MutationFileState): Promise<boolean>;
+export declare function removeMaintenanceFile(repository: string, relative: string, expected: MutationFileState): Promise<void>;

package/dist/lib/maintenance-write.js

@@ -0,0 +1,55 @@
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+import { ensureSafeRepositoryDirectory } from "./repository-path-safety.js";
+import { captureMutationFileState, mutationFileStateFromBytes, absentMutationFileState, } from "./context-mutation/mutation-file-state.js";
+import { stageMutationTemporary, prepareMutationTemporaryForRecovery, applyMutationChangeForward, cleanupMutationTemporary, mutationTemporaryPath, } from "./context-mutation/mutation-cas.js";
+// Reuse the Context writer's path, byte/identity CAS and exclusive publication.
+// Callers own cross-file ordering/recovery and hold the maintenance lock.
+export async function writeMaintenanceText(repository, relative, text, expected) {
+    const before = expected ?? (await captureMutationFileState(repository, relative));
+    const bytes = Buffer.from(text);
+    if (before.bytes_base64 === bytes.toString("base64"))
+        return false;
+    await ensureSafeRepositoryDirectory(repository, path.posix.dirname(relative), "maintenance_write_parent");
+    const mode = before.mode ??
+        (process.platform === "win32" ? 0o666 : 0o666 & ~process.umask());
+    const change = {
+        path: relative,
+        before,
+        after: mutationFileStateFromBytes(bytes, mode),
+        commit_order: 0,
+        temporary_path: mutationTemporaryPath(relative, randomUUID(), 0),
+        temporary_state: null,
+        published_before: null,
+        published_after: null,
+    };
+    change.temporary_state = await stageMutationTemporary(repository, change);
+    try {
+        change.published_after = await applyMutationChangeForward(repository, change);
+    }
+    finally {
+        await cleanupMutationTemporary(repository, change);
+    }
+    return true;
+}
+export async function removeMaintenanceFile(repository, relative, expected) {
+    if (!expected.exists)
+        return;
+    const change = {
+        path: relative,
+        before: expected,
+        after: absentMutationFileState(),
+        commit_order: 0,
+        temporary_path: mutationTemporaryPath(relative, randomUUID(), 0),
+        temporary_state: null,
+        published_before: null,
+        published_after: null,
+    };
+    change.temporary_state = await prepareMutationTemporaryForRecovery(repository, change, "after");
+    try {
+        change.published_after = await applyMutationChangeForward(repository, change);
+    }
+    finally {
+        await cleanupMutationTemporary(repository, change);
+    }
+}

package/dist/lib/migrations.d.ts

@@ -14,26 +14,7 @@ export interface UpgradePlan {
     blocked: UpgradePlanItem[];
 }
 export type ReleaseUpdateMode = "sync-only" | "upgrade-required" | "manual-required";
-export interface Migration {
-    id: string;
-    introducedIn: string;
-    description: string;
-    scope: string;
-    risk: "safe" | "manual";
-    manualMessage: string;
-    detect(projectRoot: string, root: string, migrationId: string): Promise<UpgradePlanItem[]>;
-    apply?(projectRoot: string, root: string, report: MigrationReport): Promise<void>;
-    verify(projectRoot: string, root: string): Promise<void>;
-}
-export interface MigrationReport {
-    changed: string[];
-    skipped: string[];
-    manualRequired: UpgradePlanItem[];
-    blocked: UpgradePlanItem[];
-}
-export declare const migrations: Migration[];
-export declare function createUpgradePlan(projectRoot: string): Promise<UpgradePlan>;
+export declare function createUpgradePlan(repository: string): Promise<UpgradePlan>;
 export declare function hasUpgradePlanWork(plan: UpgradePlan): boolean;
 export declare function updateModeForPlan(plan: UpgradePlan): ReleaseUpdateMode;
 export declare function formatUpgradePlan(plan: UpgradePlan): string[];
-export declare function runMigrations(projectRoot: string, existingPlan?: UpgradePlan): Promise<MigrationReport>;