@astrosheep/keiyaku 1.0.0 → 1.0.2

package/build/core/projection-tells.js

@@ -0,0 +1,401 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { ProjectionStateError, randomHex8 } from "./atomic-publish.js";
+import { PROJECTION_GENERATION_STORE_FILE, } from "./projection-generation-store.js";
+import { configureHeartBusyTimeout } from "./projection/heart.js";
+export const PROJECTION_TELL_STATES = [
+    "inbox",
+    "inflight",
+    "submitted",
+    "consumed",
+    "delivered",
+];
+const PENDING_TELL_LIMIT = 10_000;
+function databasePath(projectionDirectory) {
+    return path.join(projectionDirectory, PROJECTION_GENERATION_STORE_FILE);
+}
+function openDatabase(projectionDirectory, readOnly) {
+    const target = databasePath(projectionDirectory);
+    if (!fs.lstatSync(target).isFile()) {
+        throw new ProjectionStateError("projection heart must be a regular file");
+    }
+    const database = new DatabaseSync(target, {
+        readOnly,
+        enableForeignKeyConstraints: true,
+        enableDoubleQuotedStringLiterals: false,
+        allowExtension: false,
+    });
+    configureHeartBusyTimeout(database);
+    if (!readOnly) {
+        database.exec("PRAGMA foreign_keys = ON");
+        database.exec("PRAGMA trusted_schema = OFF");
+    }
+    return database;
+}
+function rollbackQuietly(database) {
+    try {
+        database.exec("ROLLBACK");
+    }
+    catch {
+        // Preserve the transition failure.
+    }
+}
+function withRead(projectionDirectory, read) {
+    const database = openDatabase(projectionDirectory, true);
+    try {
+        return read(database);
+    }
+    finally {
+        database.close();
+    }
+}
+function withWrite(projectionDirectory, write) {
+    const database = openDatabase(projectionDirectory, false);
+    try {
+        database.exec("BEGIN IMMEDIATE");
+        try {
+            const result = write(database);
+            database.exec("COMMIT");
+            return result;
+        }
+        catch (error) {
+            rollbackQuietly(database);
+            throw error;
+        }
+    }
+    finally {
+        database.close();
+    }
+}
+function requireExecutionId(value) {
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new ProjectionStateError("submitted tell executionId must be a non-empty string");
+    }
+    return value;
+}
+function parseFence(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new ProjectionStateError("tell fence is required");
+    }
+    const record = value;
+    if (record.kind === "turn" && typeof record.turnId === "string" && record.turnId.length > 0) {
+        return { kind: "turn", turnId: record.turnId };
+    }
+    if (record.kind === "ordinal"
+        && typeof record.ordinal === "number"
+        && Number.isSafeInteger(record.ordinal)
+        && record.ordinal >= 0) {
+        return { kind: "ordinal", ordinal: record.ordinal };
+    }
+    throw new ProjectionStateError("tell fence must be turn(string) or ordinal(non-negative integer)");
+}
+function decodeJson(value, location) {
+    try {
+        return JSON.parse(value);
+    }
+    catch (error) {
+        throw new ProjectionStateError(`${location} contains malformed JSON`, { cause: error });
+    }
+}
+function parseReplay(value) {
+    if (value === null)
+        return [];
+    const decoded = decodeJson(value, "tell replay history");
+    if (!Array.isArray(decoded))
+        throw new ProjectionStateError("tell replay history must be an array");
+    return decoded.map((item) => {
+        if (!item || typeof item !== "object" || Array.isArray(item)) {
+            throw new ProjectionStateError("tell replay history entry must be an object");
+        }
+        const entry = item;
+        return {
+            executionId: requireExecutionId(entry.executionId),
+            fence: parseFence(entry.fence),
+        };
+    });
+}
+function originalFromRow(row) {
+    return {
+        version: 1,
+        text: row.text,
+        createdAt: row.created_at,
+        ...(row.effort ? { effort: row.effort } : {}),
+    };
+}
+function submittedFromRow(row) {
+    if (row.state !== "submitted" && row.state !== "consumed" && row.state !== "delivered") {
+        throw new ProjectionStateError(`tell '${row.tell_id}' is not submitted`);
+    }
+    if (row.execution_id === null || row.fence_json === null) {
+        throw new ProjectionStateError(`tell '${row.tell_id}' is missing submission facts`);
+    }
+    const replayedFrom = parseReplay(row.replayed_from_json);
+    return {
+        ...originalFromRow(row),
+        executionId: requireExecutionId(row.execution_id),
+        fence: parseFence(decodeJson(row.fence_json, "tell fence")),
+        ...(replayedFrom.length > 0 ? { replayedFrom } : {}),
+    };
+}
+function selectTell(database, tellId) {
+    return database.prepare(`
+    SELECT
+      tell_id,
+      text,
+      created_at,
+      effort,
+      state,
+      execution_id,
+      fence_json,
+      replayed_from_json,
+      delivered_at
+    FROM projection_tells
+    WHERE tell_id = ?
+  `).get(tellId);
+}
+function assertTellIdRandomHex(randomHex) {
+    if (!/^[0-9a-f]{8}$/.test(randomHex)) {
+        throw new ProjectionStateError(`tell id random segment must be 8 lowercase hex chars, got ${randomHex}`);
+    }
+    return randomHex;
+}
+export function listTellIds(projectionDirectory, state) {
+    return withRead(projectionDirectory, (database) => database.prepare(`
+      SELECT tell_id
+      FROM projection_tells
+      WHERE state = ?
+      ORDER BY tell_id
+    `).all(state).map((row) => row.tell_id));
+}
+export function readTellOriginal(projectionDirectory, state, tellId) {
+    return withRead(projectionDirectory, (database) => {
+        const row = selectTell(database, tellId);
+        if (!row || row.state !== state) {
+            throw new ProjectionStateError(`tell '${tellId}' is not in ${state}`);
+        }
+        return originalFromRow(row);
+    });
+}
+export function readTellSubmitted(projectionDirectory, tellId) {
+    return withRead(projectionDirectory, (database) => {
+        const row = selectTell(database, tellId);
+        if (!row)
+            throw new ProjectionStateError(`tell '${tellId}' does not exist`);
+        return submittedFromRow(row);
+    });
+}
+export function writeInboxTell(projectionDirectory, text, nowMs, options) {
+    if (!Number.isSafeInteger(nowMs) || nowMs < 0) {
+        throw new ProjectionStateError("nowMs must be a safe non-negative integer");
+    }
+    const tellId = `${nowMs}-${assertTellIdRandomHex((options?.randomHex ?? randomHex8)())}`;
+    return withWrite(projectionDirectory, (database) => {
+        const pending = database.prepare(`
+      SELECT COUNT(*) AS count
+      FROM projection_tells
+      WHERE state IN ('inbox', 'inflight', 'submitted', 'delivered')
+    `).get();
+        if (Number(pending.count) >= PENDING_TELL_LIMIT) {
+            throw new ProjectionStateError(`projection has reached the ${PENDING_TELL_LIMIT} pending tell limit`);
+        }
+        try {
+            database.prepare(`
+        INSERT INTO projection_tells (
+          tell_id, text, created_at, effort, state
+        ) VALUES (?, ?, ?, ?, 'inbox')
+      `).run(tellId, text, new Date(nowMs).toISOString(), options?.effort ?? null);
+        }
+        catch (error) {
+            throw new ProjectionStateError(`tell id already exists: ${tellId}`, { cause: error });
+        }
+        return tellId;
+    });
+}
+export function claimTellToInflight(projectionDirectory, tellId) {
+    return withWrite(projectionDirectory, (database) => {
+        const result = database.prepare(`
+      UPDATE projection_tells
+      SET state = 'inflight'
+      WHERE tell_id = ? AND state = 'inbox'
+    `).run(tellId);
+        return Number(result.changes) === 1;
+    });
+}
+export function claimAllInbox(projectionDirectory) {
+    return withWrite(projectionDirectory, (database) => {
+        const rows = database.prepare(`
+      SELECT tell_id
+      FROM projection_tells
+      WHERE state = 'inbox'
+      ORDER BY tell_id
+    `).all();
+        for (const row of rows) {
+            database.prepare(`
+        UPDATE projection_tells
+        SET state = 'inflight'
+        WHERE tell_id = ? AND state = 'inbox'
+      `).run(row.tell_id);
+        }
+        return rows.map((row) => row.tell_id);
+    });
+}
+export function claimFencedTells(projectionDirectory, fence, executionId) {
+    const owner = requireExecutionId(executionId);
+    return withWrite(projectionDirectory, (database) => {
+        const claimed = [];
+        const seen = new Set();
+        for (const tellId of fence) {
+            if (seen.has(tellId))
+                throw new ProjectionStateError(`duplicate tell in generation fence: ${tellId}`);
+            seen.add(tellId);
+            const row = selectTell(database, tellId);
+            if (!row)
+                throw new ProjectionStateError(`generation tell fence member is missing: ${tellId}`);
+            if (row.state === "inbox") {
+                database.prepare(`
+          UPDATE projection_tells
+          SET state = 'inflight'
+          WHERE tell_id = ? AND state = 'inbox'
+        `).run(tellId);
+                claimed.push(tellId);
+                continue;
+            }
+            if (row.state === "inflight") {
+                claimed.push(tellId);
+                continue;
+            }
+            if (row.state === "consumed" && row.execution_id === owner)
+                continue;
+            throw new ProjectionStateError(`generation tell fence member is not claimable: ${tellId}`);
+        }
+        return claimed;
+    });
+}
+export function markTellSubmitted(projectionDirectory, tellId, fields) {
+    const executionId = requireExecutionId(fields.executionId);
+    const fence = parseFence(fields.fence);
+    const replayedFrom = (fields.replayedFrom ?? []).map((entry) => ({
+        executionId: requireExecutionId(entry.executionId),
+        fence: parseFence(entry.fence),
+    }));
+    withWrite(projectionDirectory, (database) => {
+        const row = selectTell(database, tellId);
+        if (!row)
+            throw new ProjectionStateError(`tell '${tellId}' does not exist`);
+        if (row.state === "submitted")
+            return;
+        if (row.state !== "inflight") {
+            throw new ProjectionStateError(`tell '${tellId}' is not inflight`);
+        }
+        database.prepare(`
+      UPDATE projection_tells
+      SET
+        state = 'submitted',
+        execution_id = ?,
+        fence_json = ?,
+        replayed_from_json = ?
+      WHERE tell_id = ? AND state = 'inflight'
+    `).run(executionId, JSON.stringify(fence), replayedFrom.length > 0 ? JSON.stringify(replayedFrom) : null, tellId);
+    });
+}
+export function markTellConsumed(projectionDirectory, tellId) {
+    withWrite(projectionDirectory, (database) => {
+        const result = database.prepare(`
+      UPDATE projection_tells
+      SET state = 'consumed', delivered_at = NULL
+      WHERE tell_id = ? AND state IN ('submitted', 'delivered')
+    `).run(tellId);
+        if (Number(result.changes) !== 1) {
+            throw new ProjectionStateError(`tell '${tellId}' is not submitted or delivered`);
+        }
+    });
+}
+export function readProjectionTellCounts(projectionDirectory) {
+    return withRead(projectionDirectory, (database) => {
+        const counts = {
+            inbox: 0,
+            inflight: 0,
+            submitted: 0,
+            consumed: 0,
+            delivered: 0,
+        };
+        const rows = database.prepare(`
+      SELECT state, COUNT(*) AS count
+      FROM projection_tells
+      GROUP BY state
+    `).all();
+        for (const row of rows)
+            counts[row.state] = Number(row.count);
+        return counts;
+    });
+}
+export function snapshotPendingTells(projectionDirectory) {
+    return withRead(projectionDirectory, (database) => {
+        const rows = database.prepare(`
+      SELECT tell_id, effort
+      FROM projection_tells
+      WHERE state IN ('inbox', 'inflight', 'submitted', 'delivered')
+      ORDER BY tell_id
+    `).all();
+        const effort = rows.reduce((selected, row) => row.effort ?? selected, undefined);
+        return {
+            tellIds: rows.map((row) => row.tell_id),
+            ...(effort ? { effort } : {}),
+        };
+    });
+}
+export function demoteSubmittedTellsForReplay(projectionDirectory, executionId) {
+    const currentExecutionId = requireExecutionId(executionId);
+    return withWrite(projectionDirectory, (database) => {
+        const rows = database.prepare(`
+      SELECT
+        tell_id,
+        text,
+        created_at,
+        effort,
+        state,
+        execution_id,
+        fence_json,
+        replayed_from_json,
+        delivered_at
+      FROM projection_tells
+      WHERE state IN ('submitted', 'delivered')
+      ORDER BY tell_id
+    `).all();
+        for (const row of rows) {
+            const submitted = submittedFromRow(row);
+            if (submitted.executionId === currentExecutionId) {
+                throw new ProjectionStateError(`submitted tell belongs to current execution: ${row.tell_id}`);
+            }
+            const replayedFrom = [
+                ...(submitted.replayedFrom ?? []),
+                { executionId: submitted.executionId, fence: submitted.fence },
+            ];
+            database.prepare(`
+        UPDATE projection_tells
+        SET
+          state = 'inflight',
+          execution_id = NULL,
+          fence_json = NULL,
+          replayed_from_json = ?,
+          delivered_at = NULL
+        WHERE tell_id = ? AND state IN ('submitted', 'delivered')
+      `).run(JSON.stringify(replayedFrom), row.tell_id);
+        }
+        return rows.map((row) => row.tell_id);
+    });
+}
+/** The only tell-consumption predicate. */
+export function isTellCausallyConsumed(submitted, checkpoint) {
+    if (submitted.kind !== checkpoint.kind) {
+        throw new ProjectionStateError(`tell fence kind mismatch: ${submitted.kind} vs ${checkpoint.kind}`);
+    }
+    if (submitted.kind === "ordinal" && checkpoint.kind === "ordinal") {
+        return checkpoint.ordinal > submitted.ordinal;
+    }
+    if (submitted.kind === "turn" && checkpoint.kind === "turn") {
+        return checkpoint.turnId === submitted.turnId;
+    }
+    throw new ProjectionStateError("unreachable tell fence comparison");
+}

package/build/core/projection-wait.js

@@ -0,0 +1,155 @@
+import { foldAgentActivity } from "./projection-activity.js";
+import { readGenerationEvents, } from "./projection-core.js";
+import { readProjectionIdentity } from "./projection-identity.js";
+import { PROJECTION_ADOPTION_TIMEOUT_MS } from "./projection-generation-launcher.js";
+import { observeProjectionLifeSnapshot } from "./projection-life-observer.js";
+import { selectCurrentGeneration } from "./projection-life-protocol.js";
+import { readProjectionTellCounts } from "./projection-tells.js";
+import { invalidActivityEventDiagnostic, selectValidStoredAgentEvents, } from "./stored-agent-event.js";
+const WAIT_POLL_MS = 100;
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function waitingTellCount(projectionDirectory) {
+    const counts = readProjectionTellCounts(projectionDirectory);
+    return counts.inbox + counts.inflight + counts.submitted + counts.delivered;
+}
+function latestValidEventAgeMs(events, nowMs) {
+    let latest;
+    for (const event of events) {
+        const atMs = Date.parse(event.at);
+        if (!Number.isFinite(atMs))
+            continue;
+        if (latest === undefined || atMs > latest)
+            latest = atMs;
+    }
+    return latest === undefined ? undefined : Math.max(0, nowMs - latest);
+}
+function adoptionAgeMs(current, nowMs) {
+    const adoptedAt = current?.adoption?.facts.adoptedAt;
+    if (typeof adoptedAt !== "string")
+        return undefined;
+    const adoptedAtMs = Date.parse(adoptedAt);
+    return Number.isFinite(adoptedAtMs)
+        ? Math.max(0, nowMs - adoptedAtMs)
+        : undefined;
+}
+function relativeEventLedgerFile(executionId) {
+    return `${executionId}.events.jsonl`;
+}
+function timestampFact(current, nowMs) {
+    const facts = current.verdict?.facts;
+    for (const key of ["completedAt", "failedAt", "dismissedAt"]) {
+        const value = facts?.[key];
+        if (typeof value === "string" && Number.isFinite(Date.parse(value)))
+            return value;
+    }
+    return new Date(nowMs).toISOString();
+}
+function verdictFromCurrent(current, nowMs) {
+    if (!current.verdict)
+        return undefined;
+    const state = current.verdict.facts.state;
+    if (typeof state !== "string")
+        return undefined;
+    const detail = current.verdict.facts.detail;
+    return {
+        state: state,
+        at: timestampFact(current, nowMs),
+        ...(typeof detail === "string" && detail.trim() ? { detail } : {}),
+    };
+}
+function outcomeText(current) {
+    const finalMessage = current.verdict?.facts.finalMessage;
+    if (typeof finalMessage === "string" && finalMessage.trim())
+        return finalMessage;
+    const detail = current.verdict?.facts.detail;
+    return typeof detail === "string" && detail.trim() ? detail : undefined;
+}
+function buildSnapshot(input) {
+    const { projectionDirectory, pact, phase, current, events, malformedEvents, nowMs } = input;
+    const anchorAt = current?.verdict ? timestampFact(current, nowMs) : new Date(nowMs).toISOString();
+    const anchorMs = Date.parse(anchorAt);
+    const mintedAtMs = Date.parse(pact.mintedAt);
+    const activityAgeMs = latestValidEventAgeMs(events, nowMs)
+        ?? adoptionAgeMs(current, nowMs);
+    const invalidActivity = invalidActivityEventDiagnostic(malformedEvents);
+    const responsePath = current?.verdict?.facts.responsePath;
+    const artifactId = current?.verdict?.facts.artifactId;
+    return {
+        phase,
+        observedAtMs: Number.isFinite(anchorMs) ? anchorMs : nowMs,
+        durationMs: Number.isFinite(mintedAtMs) && Number.isFinite(anchorMs)
+            ? Math.max(0, anchorMs - mintedAtMs)
+            : 0,
+        ...(activityAgeMs !== undefined ? { activityAgeMs } : {}),
+        tellsWaiting: waitingTellCount(projectionDirectory),
+        activity: foldAgentActivity(events),
+        ...(invalidActivity ? { eventDiagnostics: [invalidActivity] } : {}),
+        workspaceRoot: pact.workspaceRoot,
+        ...(current ? {
+            executionId: current.launch.executionId,
+            eventLedgerFile: relativeEventLedgerFile(current.launch.executionId),
+        } : {}),
+        ...(typeof responsePath === "string" && responsePath.trim() ? { responsePath } : {}),
+        ...(typeof artifactId === "string" && artifactId.trim() ? { artifactId } : {}),
+    };
+}
+export async function waitForProjection(input) {
+    const now = input.now ?? Date.now;
+    let pact;
+    try {
+        pact = readProjectionIdentity(input.projectionDirectory);
+    }
+    catch (error) {
+        return {
+            state: "unknown",
+            diagnostic: `projection identity could not be observed: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    const deadline = input.timeoutMs === undefined ? undefined : now() + input.timeoutMs;
+    for (;;) {
+        input.signal?.throwIfAborted();
+        const observedAtMs = now();
+        const observation = observeProjectionLifeSnapshot(input.projectionDirectory, {
+            nowMs: observedAtMs,
+            startupTimeoutMs: PROJECTION_ADOPTION_TIMEOUT_MS,
+        });
+        const current = observation.records
+            ? selectCurrentGeneration(observation.records)
+            : null;
+        const life = observation.life;
+        const verdict = current ? verdictFromCurrent(current, observedAtMs) : undefined;
+        const terminal = verdict !== undefined;
+        if (terminal || (deadline !== undefined && observedAtMs >= deadline)) {
+            const stored = current
+                ? readGenerationEvents(input.projectionDirectory, current.launch.executionId)
+                : [];
+            const { events, malformed } = selectValidStoredAgentEvents(stored);
+            const snapshot = buildSnapshot({
+                projectionDirectory: input.projectionDirectory,
+                pact,
+                phase: life.phase,
+                current,
+                events,
+                malformedEvents: malformed,
+                nowMs: observedAtMs,
+            });
+            if (terminal && current) {
+                const text = outcomeText(current);
+                return {
+                    state: "terminal",
+                    pact,
+                    verdict,
+                    snapshot,
+                    ...(text ? { outcomeText: text } : {}),
+                };
+            }
+            return { state: "timeout", pact, snapshot };
+        }
+        const waitMs = deadline === undefined
+            ? WAIT_POLL_MS
+            : Math.max(0, Math.min(WAIT_POLL_MS, deadline - observedAtMs));
+        await sleep(waitMs);
+    }
+}