@astrosheep/keiyaku 2.9.9 → 2.9.11

package/build/core/projection/projection-status-observation.js

@@ -0,0 +1,365 @@
+import fs from "node:fs";
+import * as path from "node:path";
+import { isErrnoException } from "../../errno.js";
+import { executionEventsPath } from "./projection-core.js";
+import { ProjectionStateError } from "../atomic-publish.js";
+import { foldPublicProjectionActivity } from "./projection-activity.js";
+import { readProjectionIdentity } from "./projection-identity.js";
+import { readPendingTellWindow, readProjectionTellCounts } from "./tell/store.js";
+import { ProjectionGenerationStoreError } from "./generation/store.js";
+import { PROJECTION_ADOPTION_TIMEOUT_MS } from "./generation/projection-generation-launcher.js";
+import { observeProjectionLifeSnapshot } from "./projection-life-observer.js";
+import { selectCurrentGeneration } from "./projection-life-protocol.js";
+import { invalidActivityEventDiagnostic, selectValidStoredAgentEvents } from "../stored-agent-event.js";
+import { projectTerminalFailure } from "./projection-terminal-failure.js";
+import { extractTerminalTimestamp } from "./generation/model.js";
+const MAX_STATUS_FILE_BYTES = 256 * 1024;
+class ProjectionStatusFileError extends Error {
+    diagnostic;
+    constructor(kind, filePath) {
+        const label = path.basename(filePath);
+        const detail = `${label} is not a regular file`;
+        super(detail);
+        this.name = "ProjectionStatusFileError";
+        this.diagnostic = { kind, detail };
+    }
+}
+function oversizedProjectionFileDiagnostic(filePath) {
+    return {
+        kind: "oversized-projection-file",
+        fileName: path.basename(filePath),
+    };
+}
+function recordProjectionStatusFileError(error, diagnostics) {
+    if (!(error instanceof ProjectionStatusFileError))
+        return false;
+    diagnostics.push(error.diagnostic);
+    return true;
+}
+function readBoundedRegularFileTail(filePath) {
+    const before = fs.lstatSync(filePath);
+    if (!before.isFile())
+        throw new ProjectionStatusFileError("non-regular-projection-file", filePath);
+    let fd;
+    try {
+        fd = fs.openSync(filePath, fs.constants.O_RDONLY | fs.constants.O_NONBLOCK | fs.constants.O_NOFOLLOW);
+    }
+    catch (error) {
+        if (isErrnoException(error) && error.code === "ELOOP") {
+            throw new ProjectionStatusFileError("non-regular-projection-file", filePath);
+        }
+        throw error;
+    }
+    try {
+        const opened = fs.fstatSync(fd);
+        if (!opened.isFile())
+            throw new ProjectionStatusFileError("non-regular-projection-file", filePath);
+        const snapshotSize = opened.size;
+        const truncated = snapshotSize > MAX_STATUS_FILE_BYTES;
+        const readLength = Math.min(snapshotSize, MAX_STATUS_FILE_BYTES);
+        const readOffset = Math.max(0, snapshotSize - MAX_STATUS_FILE_BYTES);
+        const buffer = Buffer.allocUnsafe(readLength);
+        let total = 0;
+        while (total < readLength) {
+            const bytesRead = fs.readSync(fd, buffer, total, readLength - total, readOffset + total);
+            if (bytesRead === 0)
+                break;
+            total += bytesRead;
+        }
+        let tail = buffer.subarray(0, total);
+        if (truncated) {
+            const firstLf = tail.indexOf(0x0a);
+            if (firstLf < 0) {
+                return { content: "", truncated: true };
+            }
+            tail = tail.subarray(firstLf + 1);
+        }
+        return { content: tail.toString("utf8"), truncated };
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+function displayedTellCounts(counts) {
+    return {
+        inbox: counts.inbox,
+        inflight: counts.inflight,
+        submitted: counts.submitted,
+        seen: counts.seen,
+        consumed: counts.consumed,
+    };
+}
+function emptyTellCounts() {
+    return { inbox: 0, inflight: 0, submitted: 0, seen: 0, consumed: 0 };
+}
+function readIdentityFacts(projectionDir, diagnostics) {
+    try {
+        const identity = readProjectionIdentity(projectionDir);
+        return {
+            identity,
+            pid: identity.pid,
+            akuma: identity.akuma,
+            provider: identity.provider,
+            binding: identity.binding,
+            mintedAt: identity.mintedAt,
+            workspaceRoot: identity.workspaceRoot,
+        };
+    }
+    catch (error) {
+        if (isErrnoException(error) && error.code === "ENOENT") {
+            diagnostics.push({ kind: "missing-identity", detail: "heart identity missing" });
+            return { identity: null, pid: undefined, akuma: undefined, provider: undefined, binding: undefined, mintedAt: undefined, workspaceRoot: undefined };
+        }
+        if (error instanceof ProjectionGenerationStoreError) {
+            diagnostics.push({ kind: "invalid-identity", detail: error.message });
+            return { identity: null, pid: undefined, akuma: undefined, provider: undefined, binding: undefined, mintedAt: undefined, workspaceRoot: undefined };
+        }
+        if (error instanceof ProjectionStateError) {
+            diagnostics.push({ kind: "invalid-identity", detail: error.message });
+            return { identity: null, pid: undefined, akuma: undefined, provider: undefined, binding: undefined, mintedAt: undefined, workspaceRoot: undefined };
+        }
+        diagnostics.push({ kind: "unreadable-identity", detail: `heart identity unreadable: ${String(error)}` });
+        return { identity: null, pid: undefined, akuma: undefined, provider: undefined, binding: undefined, mintedAt: undefined, workspaceRoot: undefined };
+    }
+}
+function readHeartTellCounts(projectionDir, diagnostics) {
+    try {
+        return displayedTellCounts(readProjectionTellCounts(projectionDir));
+    }
+    catch (error) {
+        if (error instanceof ProjectionGenerationStoreError || error instanceof ProjectionStateError) {
+            diagnostics.push({ kind: "unreadable-tells", detail: error.message });
+            return emptyTellCounts();
+        }
+        diagnostics.push({ kind: "unreadable-tells", detail: `heart tells unreadable: ${String(error)}` });
+        return emptyTellCounts();
+    }
+}
+function readPendingTells(projectionDir, diagnostics) {
+    try {
+        // Kanshi is an operator surface: unconsumed tells are actionable facts, not
+        // a count to hide behind. This is one heart read and does not enumerate a
+        // second projection topology.
+        return readPendingTellWindow(projectionDir, Number.MAX_SAFE_INTEGER).window;
+    }
+    catch (error) {
+        if (error instanceof ProjectionGenerationStoreError || error instanceof ProjectionStateError) {
+            diagnostics.push({ kind: "unreadable-tells", detail: error.message });
+            return [];
+        }
+        diagnostics.push({ kind: "unreadable-tells", detail: `heart tells unreadable: ${String(error)}` });
+        return [];
+    }
+}
+function readStoredEvents(projectionDir, executionId, diagnostics) {
+    let content;
+    let truncated = false;
+    const eventsPath = executionEventsPath(projectionDir, executionId);
+    try {
+        const read = readBoundedRegularFileTail(eventsPath);
+        content = read.content;
+        truncated = read.truncated;
+    }
+    catch (error) {
+        if (isErrnoException(error) && error.code === "ENOENT")
+            return [];
+        if (recordProjectionStatusFileError(error, diagnostics))
+            return [];
+        diagnostics.push({ kind: "unreadable-activity", detail: `activity ledger unreadable: ${String(error)}` });
+        return [];
+    }
+    if (truncated) {
+        diagnostics.push(oversizedProjectionFileDiagnostic(eventsPath));
+    }
+    // Parse only LF-terminated records. An unterminated final line is ignored even
+    // when it happens to parse: it may be a concurrent append fragment.
+    const lines = content.split("\n");
+    const values = [];
+    let malformed = 0;
+    for (const line of lines.slice(0, -1)) {
+        try {
+            values.push(JSON.parse(line));
+        }
+        catch {
+            malformed += 1;
+        }
+    }
+    if (malformed > 0) {
+        diagnostics.push({
+            kind: "invalid-activity-event",
+            detail: `${malformed} persisted activity event${malformed === 1 ? "" : "s"} malformed`,
+        });
+    }
+    return values;
+}
+function latestValidEvent(events) {
+    let latest;
+    for (const event of events) {
+        const atMs = Date.parse(event.at);
+        if (!Number.isFinite(atMs))
+            continue;
+        if (latest === undefined || atMs > latest.atMs)
+            latest = { at: event.at, atMs };
+    }
+    return latest;
+}
+function readActivityFacts(projectionDir, executionId, nowMs, diagnostics, fallbackAt) {
+    const fallbackAtMs = fallbackAt === undefined ? undefined : Date.parse(fallbackAt);
+    const validFallback = fallbackAt !== undefined && Number.isFinite(fallbackAtMs)
+        ? { at: fallbackAt, atMs: fallbackAtMs }
+        : undefined;
+    if (!executionId) {
+        return validFallback
+            ? { activityAt: validFallback.at, activityAtMs: validFallback.atMs, activityAgeMs: Math.max(0, nowMs - validFallback.atMs) }
+            : {};
+    }
+    const stored = readStoredEvents(projectionDir, executionId, diagnostics);
+    const { events, malformed } = selectValidStoredAgentEvents(stored);
+    const invalidActivity = invalidActivityEventDiagnostic(malformed);
+    if (invalidActivity)
+        diagnostics.push(invalidActivity);
+    const latest = latestValidEvent(events) ?? validFallback;
+    return {
+        ...(events.length > 0 ? { activity: foldPublicProjectionActivity(events) } : {}),
+        ...(latest !== undefined
+            ? {
+                activityAt: latest.at,
+                activityAtMs: latest.atMs,
+                activityAgeMs: Math.max(0, nowMs - latest.atMs),
+            }
+            : {}),
+    };
+}
+function terminalTimestamp(current) {
+    return extractTerminalTimestamp(current?.verdict?.facts);
+}
+export function readProjectionSummary(projectionDir, id, alias, nowMs, options) {
+    const diagnostics = [];
+    const snapshot = observeProjectionLifeSnapshot(projectionDir, {
+        nowMs,
+        startupTimeoutMs: PROJECTION_ADOPTION_TIMEOUT_MS,
+    });
+    if (snapshot.compatibility === "incompatible") {
+        return {
+            id,
+            ...(alias ? { alias } : {}),
+            projectionDir,
+            snapshot,
+            identityFacts: null,
+            diagnostics,
+            state: "incompatible",
+        };
+    }
+    const life = snapshot.life;
+    const phase = life.phase;
+    const state = phase === "active" || phase === "quiescent" ? "out" : phase;
+    const identityFacts = options?.requiresIdentity?.(state) === false
+        ? null
+        : readIdentityFacts(projectionDir, diagnostics);
+    return {
+        id,
+        ...(alias ? { alias } : {}),
+        projectionDir,
+        snapshot,
+        identityFacts,
+        diagnostics,
+        state,
+    };
+}
+export function readProjectionRow(summary, nowMs, readDetails) {
+    const { id, alias, projectionDir, snapshot } = summary;
+    const diagnostics = [...summary.diagnostics];
+    if (snapshot.compatibility === "incompatible") {
+        return {
+            id,
+            observedAtMs: nowMs,
+            ...(alias ? { alias } : {}),
+            state: "incompatible",
+            observation: snapshot,
+            tellCounts: emptyTellCounts(),
+            diagnostics,
+        };
+    }
+    const identityFacts = summary.identityFacts;
+    if (identityFacts === null && !readDetails) {
+        return {
+            id,
+            observedAtMs: nowMs,
+            ...(alias ? { alias } : {}),
+            state: summary.state,
+            observation: { compatibility: "current", lifecycle: snapshot.life },
+            tellCounts: emptyTellCounts(),
+            diagnostics,
+        };
+    }
+    if (identityFacts === null || !identityFacts.identity) {
+        const diagnostic = diagnostics.map((entry) => entry.detail).find((detail) => detail !== undefined)
+            ?? "projection identity could not be observed";
+        return {
+            id,
+            observedAtMs: nowMs,
+            ...(alias ? { alias } : {}),
+            state: "unknown",
+            observation: {
+                compatibility: "current",
+                lifecycle: { phase: "unknown", diagnostic },
+            },
+            tellCounts: emptyTellCounts(),
+            diagnostics,
+        };
+    }
+    const life = snapshot.life;
+    const current = snapshot.records ? selectCurrentGeneration(snapshot.records) : null;
+    const adoptedAt = current?.adoption?.facts.adoptedAt;
+    const adoptedAtMs = typeof adoptedAt === "string"
+        ? Date.parse(adoptedAt)
+        : Number.NaN;
+    const tellCounts = readDetails
+        ? readHeartTellCounts(projectionDir, diagnostics)
+        : emptyTellCounts();
+    const pendingTells = readDetails
+        ? readPendingTells(projectionDir, diagnostics)
+        : [];
+    const activityFacts = readDetails
+        ? readActivityFacts(projectionDir, life.executionId, nowMs, diagnostics, typeof adoptedAt === "string" && Number.isFinite(adoptedAtMs) ? adoptedAt : identityFacts.mintedAt)
+        : {};
+    const mintedAtMs = Date.parse(identityFacts.mintedAt ?? "");
+    const terminalAt = terminalTimestamp(current);
+    const durationAnchorMs = current?.verdict
+        ? (terminalAt === undefined ? Number.NaN : Date.parse(terminalAt))
+        : nowMs;
+    const durationMs = Number.isFinite(mintedAtMs) && Number.isFinite(durationAnchorMs)
+        ? Math.max(0, durationAnchorMs - mintedAtMs)
+        : undefined;
+    const displayAgeMs = activityFacts.activityAgeMs
+        ?? (Number.isFinite(mintedAtMs) ? Math.max(0, nowMs - mintedAtMs) : undefined);
+    if (life.phase === "unknown" && life.diagnostic) {
+        diagnostics.push({ kind: "unknown-lifecycle", detail: life.diagnostic });
+    }
+    const phase = life.phase;
+    const state = phase === "active" || phase === "quiescent" ? "out" : phase;
+    const terminalFailure = current?.verdict
+        ? projectTerminalFailure(current.verdict.facts.state, current.verdict.facts)
+        : undefined;
+    return {
+        id,
+        observedAtMs: nowMs,
+        ...(alias ? { alias } : {}),
+        state,
+        observation: { compatibility: "current", lifecycle: life },
+        akuma: identityFacts.akuma,
+        provider: identityFacts.provider,
+        binding: identityFacts.binding,
+        pid: identityFacts.pid,
+        mintedAt: identityFacts.mintedAt,
+        ...(terminalAt ? { terminalAt } : {}),
+        ...(durationMs !== undefined ? { durationMs } : {}),
+        ...(identityFacts.workspaceRoot ? { workspaceRoot: identityFacts.workspaceRoot } : {}),
+        ...activityFacts,
+        ...(displayAgeMs !== undefined ? { activityAgeMs: displayAgeMs } : {}),
+        ...(terminalFailure ? { terminalFailure } : {}),
+        tellCounts,
+        ...(pendingTells.length > 0 ? { pendingTells } : {}),
+        diagnostics,
+    };
+}