@astrosheep/keiyaku 1.0.1 → 1.0.2

package/build/core/projection-identity.js

@@ -0,0 +1,11 @@
+import { openProjectionGenerationStoreReadOnly, } from "./projection-generation-store.js";
+/** Read the immutable projection identity from the heart database. */
+export function readProjectionIdentity(projectionDirectory) {
+    const heart = openProjectionGenerationStoreReadOnly(projectionDirectory);
+    try {
+        return heart.readIdentity();
+    }
+    finally {
+        heart.close();
+    }
+}

package/build/core/projection-life-observer.js

@@ -0,0 +1,87 @@
+import { openProjectionGenerationStoreReadOnly, } from "./projection-generation-store.js";
+import { deriveProjectionLife, selectCurrentGeneration, } from "./projection-life-protocol.js";
+import { observeProjectionRunnerLock } from "./projection-runner-lock.js";
+function errorDetail(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Observe the current generation without creating, repairing, or mutating
+ * projection storage. Generation history is the ordering authority; the
+ * runner lock is consulted only for an adopted, non-terminal generation.
+ */
+export function observeProjectionLifeSnapshot(projectionDirectory, options) {
+    const readRecords = () => {
+        const store = openProjectionGenerationStoreReadOnly(projectionDirectory);
+        try {
+            return store.readRecords();
+        }
+        finally {
+            store.close();
+        }
+    };
+    for (let attempt = 0; attempt < 4; attempt += 1) {
+        let records;
+        try {
+            records = readRecords();
+        }
+        catch (error) {
+            return {
+                life: {
+                    phase: "unknown",
+                    diagnostic: `generation history could not be observed: ${errorDetail(error)}`,
+                },
+            };
+        }
+        const current = selectCurrentGeneration(records);
+        if (!current || current.verdict || !current.adoption) {
+            return {
+                life: deriveProjectionLife({
+                    records,
+                    nowMs: options.nowMs,
+                    startupTimeoutMs: options.startupTimeoutMs,
+                }),
+                records,
+            };
+        }
+        const lock = observeProjectionRunnerLock(projectionDirectory, options.platform);
+        let after;
+        try {
+            after = readRecords();
+        }
+        catch (error) {
+            return {
+                life: {
+                    phase: "unknown",
+                    executionId: current.launch.executionId,
+                    diagnostic: `generation history could not be re-observed: ${errorDetail(error)}`,
+                },
+            };
+        }
+        const beforeTail = records.at(-1)?.seq;
+        const afterTail = after.at(-1)?.seq;
+        if (records.length !== after.length || beforeTail !== afterTail)
+            continue;
+        return {
+            life: deriveProjectionLife({
+                records,
+                runnerLock: lock.state === "held"
+                    ? "held"
+                    : lock.state === "released"
+                        ? "released"
+                        : "unknown",
+                nowMs: options.nowMs,
+                startupTimeoutMs: options.startupTimeoutMs,
+            }),
+            records,
+        };
+    }
+    return {
+        life: {
+            phase: "unknown",
+            diagnostic: "generation history changed during runner-lock observation",
+        },
+    };
+}
+export function observeProjectionLife(projectionDirectory, options) {
+    return observeProjectionLifeSnapshot(projectionDirectory, options).life;
+}

package/build/core/projection-life-protocol.js

@@ -0,0 +1,95 @@
+export const GENERATION_VERDICT_STATES = [
+    "completed",
+    "failed",
+    "launch-failed",
+    "lost-runner",
+    "dismissed",
+];
+function asLaunch(record) {
+    return record.kind === "launch"
+        ? record
+        : undefined;
+}
+function asAdoption(record) {
+    return record.kind === "adoption"
+        ? record
+        : undefined;
+}
+function asVerdict(record) {
+    return record.kind === "verdict"
+        ? record
+        : undefined;
+}
+/**
+ * Select the current generation using ledger sequence only. The store validates
+ * dense sequence and transition legality before records reach this fold.
+ */
+export function selectCurrentGeneration(records) {
+    let launch;
+    for (const record of records) {
+        const candidate = asLaunch(record);
+        if (candidate)
+            launch = candidate;
+    }
+    if (!launch)
+        return null;
+    let adoption;
+    let verdict;
+    for (const record of records) {
+        if (record.seq <= launch.seq || record.executionId !== launch.executionId)
+            continue;
+        adoption ??= asAdoption(record);
+        verdict ??= asVerdict(record);
+    }
+    return {
+        launch,
+        ...(adoption ? { adoption } : {}),
+        ...(verdict ? { verdict } : {}),
+    };
+}
+function verdictState(record) {
+    const state = record?.facts.state;
+    return typeof state === "string"
+        && GENERATION_VERDICT_STATES.includes(state)
+        ? state
+        : undefined;
+}
+function phaseForVerdict(state) {
+    switch (state) {
+        case "completed": return "done";
+        case "dismissed": return "dismissed";
+        case "lost-runner": return "lost";
+        case "failed":
+        case "launch-failed":
+            return "failed";
+    }
+}
+export function deriveProjectionLife(input) {
+    const chain = selectCurrentGeneration(input.records);
+    if (!chain)
+        return { phase: "quiescent" };
+    const executionId = chain.launch.executionId;
+    if (chain.verdict) {
+        const state = verdictState(chain.verdict);
+        return state
+            ? { phase: phaseForVerdict(state), executionId, verdict: state }
+            : { phase: "unknown", executionId, diagnostic: "current generation has an invalid verdict" };
+    }
+    if (!chain.adoption) {
+        const createdAt = chain.launch.facts.createdAt;
+        const launchedAtMs = typeof createdAt === "string" ? Date.parse(createdAt) : Number.NaN;
+        if (!Number.isFinite(launchedAtMs)) {
+            return { phase: "unknown", executionId, diagnostic: "current launch has an invalid createdAt fact" };
+        }
+        return input.nowMs - launchedAtMs >= input.startupTimeoutMs
+            ? { phase: "startup-timeout", executionId }
+            : { phase: "minting", executionId };
+    }
+    switch (input.runnerLock) {
+        case "held": return { phase: "active", executionId };
+        case "released": return { phase: "lost", executionId };
+        case "unknown":
+        case undefined:
+            return { phase: "unknown", executionId, diagnostic: "runner lock could not be determined" };
+    }
+}

package/build/core/projection-mint.js

@@ -1,8 +1,11 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { isErrnoException } from "../errno.js";
-import { atomicPublishFile, ProjectionStateError, randomHex8 } from "./atomic-publish.js";
-import { encodeProjectionJson, isoFromNowMs, PROJECTION_LAYER_DIRS, PROJECTION_ROOT_SEGMENTS, projectionDir, projectionRoot, } from "./projection-core.js";
+import { ProjectionStateError, randomHex8 } from "./atomic-publish.js";
+import { isoFromNowMs, PROJECTION_ROOT_SEGMENTS, projectionDir, projectionRoot, } from "./projection-core.js";
+import { parseExecutionAuthoritySelection, parseExecutionPact, parseExecutionPactFields, } from "./execution-pact.js";
+import { openProjectionGenerationStore } from "./projection-generation-store.js";
+import { initializeProjectionRunnerLockDatabase } from "./projection-runner-lock.js";
 export class ProjectionMintCollisionError extends Error {
     code = "PROJECTION_MINT_COLLISION";
     constructor(message, options) {
@@ -22,11 +25,10 @@ function assertMintSlug(slug) {
     return normalized;
 }
 /**
- * Mint a projection directory.
- * Order (closed): mkdirSync(id) → pact.json + heartbeat + five layer dirs → ready last via atomicPublishFile.
- * Readers ignore directories without `ready`.
+ * Validate mint inputs that can fail, then reserve one private staging directory.
+ * Dot-prefixed staging is never a published projection address.
  */
-export function mintProjection(input) {
+function reserveProjectionDirectory(input) {
     const slug = assertMintSlug(input.slug);
     if (!Number.isInteger(input.pid) || input.pid < 0) {
         throw new ProjectionStateError("projection pid must be a non-negative integer");
@@ -47,8 +49,11 @@ export function mintProjection(input) {
         }
         const id = `${slug}-${hex}`;
         const dir = projectionDir(input.cwd, id);
+        const stagingDir = path.join(root, `.mint-${id}`);
+        if (fs.existsSync(dir))
+            continue;
         try {
-            fs.mkdirSync(dir);
+            fs.mkdirSync(stagingDir);
         }
         catch (error) {
             if (isErrnoException(error) && error.code === "EEXIST") {
@@ -56,24 +61,91 @@ export function mintProjection(input) {
             }
             throw error;
         }
-        const pact = {
-            version: 1,
-            pid: input.pid,
-            akuma: input.akuma,
-            provider: input.provider,
-            mintedAt: isoFromNowMs(input.nowMs),
-            ...(input.effectivePolicy ? { effectivePolicy: input.effectivePolicy } : {}),
-        };
-        fs.writeFileSync(path.join(dir, "pact.json"), encodeProjectionJson(pact), "utf8");
-        fs.writeFileSync(path.join(dir, "heartbeat"), Buffer.alloc(0));
-        for (const layer of PROJECTION_LAYER_DIRS) {
-            fs.mkdirSync(path.join(dir, layer));
-        }
-        const ready = atomicPublishFile(path.join(dir, "ready"), Buffer.alloc(0));
-        if (ready === "taken") {
-            throw new ProjectionStateError(`ready marker already present while minting ${id}`);
+        if (fs.existsSync(dir)) {
+            fs.rmdirSync(stagingDir);
+            continue;
         }
-        return { id, dir, pact };
+        return { id, dir, stagingDir };
     }
     throw new ProjectionMintCollisionError(`exhausted ${maxAttempts} projection id attempts under ${PROJECTION_ROOT_SEGMENTS.join("/")} (PROJECTION_MINT_COLLISION)`);
 }
+/** Build the pact fields shared by both authority variants. */
+function buildMintPactFields(input) {
+    return {
+        version: 1,
+        pid: input.pid,
+        akuma: input.akuma,
+        provider: input.provider,
+        binding: input.binding,
+        mintedAt: isoFromNowMs(input.nowMs),
+        workspaceRoot: input.workspaceRoot ?? path.resolve(input.cwd),
+        ...(input.effectivePolicy ? { effectivePolicy: input.effectivePolicy } : {}),
+    };
+}
+/**
+ * Build both hard projection organs in private staging, close every database
+ * handle, then publish the complete projection with one directory rename.
+ */
+function publishReservedProjection(pact, reserved) {
+    let published = false;
+    try {
+        const heart = openProjectionGenerationStore(reserved.stagingDir);
+        try {
+            heart.initializeIdentity(pact);
+        }
+        finally {
+            heart.close();
+        }
+        initializeProjectionRunnerLockDatabase(reserved.stagingDir);
+        fs.renameSync(reserved.stagingDir, reserved.dir);
+        published = true;
+        return { id: reserved.id, dir: reserved.dir, pact };
+    }
+    finally {
+        if (!published) {
+            fs.rmSync(reserved.stagingDir, { recursive: true, force: true });
+        }
+    }
+}
+/**
+ * Mint a user-authority projection directory.
+ * Order (closed): validate → reserve staging → heart + leash → atomic rename.
+ */
+export function mintProjection(input) {
+    const authority = parseExecutionAuthoritySelection(input.authority, "projection identity", "user");
+    const fields = parseExecutionPactFields(buildMintPactFields(input));
+    const pact = parseExecutionPact({
+        version: fields.version,
+        pid: fields.pid,
+        akuma: fields.akuma,
+        provider: fields.provider,
+        authority,
+        binding: fields.binding,
+        mintedAt: fields.mintedAt,
+        workspaceRoot: fields.workspaceRoot,
+        ...(fields.effectivePolicy !== undefined ? { effectivePolicy: fields.effectivePolicy } : {}),
+    });
+    const reserved = reserveProjectionDirectory(input);
+    return publishReservedProjection(pact, reserved);
+}
+/**
+ * Mint a repository-authority projection.
+ * Order: validate complete identity → reserve staging → heart + leash → atomic rename.
+ */
+export async function mintRepositoryProjection(input) {
+    parseExecutionAuthoritySelection(input.authority, "projection identity", "repository");
+    const fields = parseExecutionPactFields(buildMintPactFields(input));
+    const reserved = reserveProjectionDirectory(input);
+    const pact = parseExecutionPact({
+        version: fields.version,
+        pid: fields.pid,
+        akuma: fields.akuma,
+        provider: fields.provider,
+        authority: { kind: "repository" },
+        binding: fields.binding,
+        mintedAt: fields.mintedAt,
+        workspaceRoot: fields.workspaceRoot,
+        ...(fields.effectivePolicy !== undefined ? { effectivePolicy: fields.effectivePolicy } : {}),
+    });
+    return publishReservedProjection(pact, reserved);
+}

package/build/core/projection-runner-lock.js

@@ -0,0 +1,230 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { DatabaseSync } from "node:sqlite";
+export const PROJECTION_RUNNER_LOCK_DATABASE = "leash";
+const SQLITE_BUSY = 5;
+const SUPPORTED_PLATFORMS = new Set(["darwin", "linux"]);
+export class ProjectionRunnerLockUnavailableError extends Error {
+    code = "PROJECTION_RUNNER_LOCK_UNAVAILABLE";
+    constructor(message, options) {
+        super(message, options);
+        this.name = "ProjectionRunnerLockUnavailableError";
+    }
+}
+export class ProjectionRunnerLockUnsupportedError extends Error {
+    code = "PROJECTION_RUNNER_LOCK_UNSUPPORTED";
+    constructor(platform) {
+        super(`projection runner locks are unsupported on platform '${platform}'`);
+        this.name = "ProjectionRunnerLockUnsupportedError";
+    }
+}
+export function projectionRunnerLockPath(projectionDirectory) {
+    return path.join(projectionDirectory, PROJECTION_RUNNER_LOCK_DATABASE);
+}
+export function isProjectionRunnerLockPlatformSupported(platform = process.platform) {
+    return SUPPORTED_PLATFORMS.has(platform);
+}
+function errorDetail(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function isSqliteBusy(error) {
+    return typeof error === "object"
+        && error !== null
+        && "errcode" in error
+        && error.errcode === SQLITE_BUSY;
+}
+function readJournalMode(database) {
+    const row = database.prepare("PRAGMA journal_mode").get();
+    return typeof row?.journal_mode === "string" ? row.journal_mode.toLowerCase() : undefined;
+}
+function assertCurrentLockSchema(database) {
+    database.prepare("SELECT id FROM lock_anchor LIMIT 1").get();
+}
+function closeAfterFailedAcquire(database, error) {
+    try {
+        database.close();
+    }
+    catch {
+        // The acquisition error remains the causal failure. Closing a connection
+        // that never became authoritative cannot turn it into a held lock.
+    }
+    if (isSqliteBusy(error)) {
+        throw new ProjectionRunnerLockUnavailableError("projection runner lock is already held", { cause: error });
+    }
+    throw new ProjectionRunnerLockUnavailableError(`projection runner lock acquisition failed: ${errorDetail(error)}`, { cause: error });
+}
+/**
+ * Mint-time initialization for the fixed lock database. This creates storage,
+ * forces rollback-journal mode, verifies the anchor schema, and closes without
+ * retaining any process-life authority.
+ */
+export function initializeProjectionRunnerLockDatabase(projectionDirectory, platform = process.platform) {
+    if (!isProjectionRunnerLockPlatformSupported(platform)) {
+        throw new ProjectionRunnerLockUnsupportedError(platform);
+    }
+    const lockPath = projectionRunnerLockPath(projectionDirectory);
+    let database;
+    try {
+        database = new DatabaseSync(lockPath);
+    }
+    catch (error) {
+        throw new ProjectionRunnerLockUnavailableError(`projection runner lock database could not be initialized: ${errorDetail(error)}`, { cause: error });
+    }
+    let initializationError;
+    try {
+        database.exec("PRAGMA busy_timeout=0");
+        database.exec("PRAGMA journal_mode=DELETE");
+        database.exec("CREATE TABLE IF NOT EXISTS lock_anchor (id INTEGER PRIMARY KEY CHECK (id = 1))");
+        if (readJournalMode(database) !== "delete") {
+            throw new ProjectionRunnerLockUnavailableError("projection runner lock database does not use rollback-journal mode");
+        }
+        assertCurrentLockSchema(database);
+    }
+    catch (error) {
+        initializationError = error;
+    }
+    try {
+        database.close();
+    }
+    catch (error) {
+        initializationError ??= error;
+    }
+    if (initializationError !== undefined) {
+        throw new ProjectionRunnerLockUnavailableError(`projection runner lock database initialization failed: ${errorDetail(initializationError)}`, { cause: initializationError });
+    }
+    return lockPath;
+}
+/**
+ * Open the already initialized projection-local lock database and hold one
+ * rollback-mode EXCLUSIVE transaction until close() or process death. SQLite
+ * requires a writable connection for this write-grade lock; the preceding
+ * regular-file check prevents ordinary missing storage from being created.
+ * Database bytes and timestamps are deliberately absent from the returned authority.
+ */
+export function acquireProjectionRunnerLock(projectionDirectory, platform = process.platform) {
+    if (!isProjectionRunnerLockPlatformSupported(platform)) {
+        throw new ProjectionRunnerLockUnsupportedError(platform);
+    }
+    const lockPath = projectionRunnerLockPath(projectionDirectory);
+    try {
+        if (!fs.lstatSync(lockPath).isFile()) {
+            throw new ProjectionRunnerLockUnavailableError("projection runner lock database is not a regular file");
+        }
+    }
+    catch (error) {
+        if (error instanceof ProjectionRunnerLockUnavailableError)
+            throw error;
+        throw new ProjectionRunnerLockUnavailableError(`projection runner lock database is not initialized: ${errorDetail(error)}`, { cause: error });
+    }
+    let database;
+    try {
+        database = new DatabaseSync(lockPath);
+    }
+    catch (error) {
+        throw new ProjectionRunnerLockUnavailableError(`projection runner lock database could not be opened: ${errorDetail(error)}`, { cause: error });
+    }
+    try {
+        database.exec("PRAGMA busy_timeout=0");
+        database.exec("BEGIN EXCLUSIVE");
+        if (readJournalMode(database) !== "delete") {
+            throw new ProjectionRunnerLockUnavailableError("projection runner lock database does not use rollback-journal mode");
+        }
+        assertCurrentLockSchema(database);
+    }
+    catch (error) {
+        try {
+            database.exec("ROLLBACK");
+        }
+        catch {
+            // A failure before BEGIN has no transaction; a failure after BEGIN is
+            // still released by closeAfterFailedAcquire if rollback cannot run.
+        }
+        return closeAfterFailedAcquire(database, error);
+    }
+    let closed = false;
+    return {
+        path: lockPath,
+        close() {
+            if (closed)
+                return;
+            closed = true;
+            let rollbackError;
+            try {
+                database.exec("ROLLBACK");
+            }
+            catch (error) {
+                rollbackError = error;
+            }
+            try {
+                database.close();
+            }
+            catch (error) {
+                rollbackError ??= error;
+            }
+            if (rollbackError !== undefined) {
+                throw new ProjectionRunnerLockUnavailableError(`projection runner lock release failed: ${errorDetail(rollbackError)}`, { cause: rollbackError });
+            }
+        },
+    };
+}
+/**
+ * Probe without creating the lock database. BEGIN DEFERRED itself acquires no
+ * file lock, so the sqlite_schema SELECT is mandatory: SQLITE_BUSY there is
+ * positive evidence of the runner's EXCLUSIVE transaction. Successful reads
+ * hold a compatible SHARED transaction only long enough to verify DELETE
+ * journal mode, then roll back. Every other failure remains unknown.
+ */
+export function observeProjectionRunnerLock(projectionDirectory, platform = process.platform) {
+    if (!isProjectionRunnerLockPlatformSupported(platform)) {
+        return {
+            state: "unknown",
+            reason: "unsupported-platform",
+            detail: `projection runner locks are unsupported on platform '${platform}'`,
+        };
+    }
+    const lockPath = projectionRunnerLockPath(projectionDirectory);
+    let database;
+    try {
+        database = new DatabaseSync(lockPath, { readOnly: true });
+    }
+    catch (error) {
+        return { state: "unknown", reason: "open-failed", detail: errorDetail(error) };
+    }
+    let transactionOpen = false;
+    try {
+        database.exec("PRAGMA busy_timeout=0");
+        database.exec("BEGIN DEFERRED");
+        transactionOpen = true;
+        assertCurrentLockSchema(database);
+        const journalMode = readJournalMode(database);
+        if (journalMode !== "delete") {
+            return {
+                state: "unknown",
+                reason: "unsupported-journal-mode",
+                detail: `projection runner lock database uses journal mode '${journalMode ?? "unknown"}'`,
+            };
+        }
+        return { state: "released" };
+    }
+    catch (error) {
+        if (isSqliteBusy(error))
+            return { state: "held" };
+        return { state: "unknown", reason: "probe-failed", detail: errorDetail(error) };
+    }
+    finally {
+        if (transactionOpen) {
+            try {
+                database.exec("ROLLBACK");
+            }
+            catch {
+                // Closing below still drops this observer's own ephemeral SHARED lock.
+            }
+        }
+        try {
+            database.close();
+        }
+        catch {
+            // Observer cleanup failures cannot be converted into death evidence.
+        }
+    }
+}