@astrosheep/keiyaku 2.9.8 → 2.9.10

package/build/core/projection/projection-history.js

@@ -0,0 +1,474 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { isErrnoException } from "../../errno.js";
+import { FlowError } from "../../flow-error.js";
+import { readContractHistoryConsequences, unavailableContractHistoryConsequences, } from "../repository-ledger/history-read.js";
+import { indexResponseArtifacts, isResponseArtifactId, locateResponseArtifact, } from "../transcripts.js";
+import { parseStructuredQuery, STRUCTURED_QUERY_COMPLETION, STRUCTURED_QUERY_GRAMMAR } from "../structured-query.js";
+import { selectValidStoredAgentEvents } from "../stored-agent-event.js";
+import { extractTerminalTimestamp } from "./generation/model.js";
+import { readProjectionAlias } from "./projection-alias.js";
+import { foldPublicProjectionActivity } from "./projection-activity.js";
+import { isProjectionId, projectionDir, projectionRoot, readGenerationEventsWithRetention, readProjectionEvents } from "./projection-core.js";
+import { projectionCoordinateRoot } from "./projection-coordinate.js";
+import { readProjectionIdentity } from "./projection-identity.js";
+import { observeProjectionLifeSnapshot } from "./projection-life-observer.js";
+import { selectCurrentGeneration } from "./projection-life-protocol.js";
+import { PROJECTION_ADOPTION_TIMEOUT_MS } from "./generation/projection-generation-launcher.js";
+export const PROJECTION_HISTORY_FILTER_FIELDS = ["contract", "akuma", "role", "outcome", "created", "updated"];
+export const PROJECTION_HISTORY_FILTER_GRAMMAR = STRUCTURED_QUERY_GRAMMAR;
+export const PROJECTION_HISTORY_FILTER_COMPLETION = STRUCTURED_QUERY_COMPLETION;
+const HISTORY_FIELDS = new Set(PROJECTION_HISTORY_FILTER_FIELDS);
+const HISTORY_ROLES = new Set(["call", "revive", "unknown"]);
+const HISTORY_OUTCOMES = new Set(["minting", "startup-timeout", "unknown", "out", "lost", "done", "killed", "dismissed", "failed", "dead", "incompatible"]);
+const RELATIVE_TIME = /^now-([1-9][0-9]*)([smhdw])$/;
+const UNIT_MS = { s: 1_000, m: 60_000, h: 3_600_000, d: 86_400_000, w: 604_800_000 };
+function invalidHistoryFilter(detail, recovered = []) {
+    const suffix = recovered.length > 0
+        ? `; parsed terms: ${recovered.map((term) => `${term.field}${term.operator}${term.values.join(",")}`).join("|")}`
+        : "";
+    throw new FlowError("INVALID_TARGET", `invalid history filter: ${detail}${suffix}`);
+}
+function parseTimestamp(value, nowMs, recovered) {
+    const relative = RELATIVE_TIME.exec(value);
+    if (relative)
+        return nowMs - Number(relative[1]) * UNIT_MS[relative[2]];
+    const parsed = Date.parse(value);
+    if (!Number.isFinite(parsed) || new Date(parsed).toISOString() !== value) {
+        invalidHistoryFilter(`timestamp '${value}' must be canonical ISO-8601 or now-<duration>`, recovered);
+    }
+    return parsed;
+}
+export function parseProjectionHistoryFilter(expression) {
+    return parseStructuredQuery({
+        expression,
+        fields: HISTORY_FIELDS,
+        invalid: invalidHistoryFilter,
+        validate: (field, operator, values, recovered) => {
+            const ordered = field === "created" || field === "updated";
+            const text = field === "contract" || field === "akuma" || field === "role" || field === "outcome";
+            if ((ordered && operator !== "=" && operator !== "!=" && operator !== "<" && operator !== "<=" && operator !== ">" && operator !== ">=")
+                || (text && operator !== "=" && operator !== "!=" && operator !== "~")) {
+                invalidHistoryFilter(`field '${field}' does not support operator '${operator}'`, recovered);
+            }
+            if (field === "role" && values.some((value) => !HISTORY_ROLES.has(value))) {
+                invalidHistoryFilter(`unknown role '${values.find((value) => !HISTORY_ROLES.has(value))}'`, recovered);
+            }
+            if (field === "outcome" && values.some((value) => !HISTORY_OUTCOMES.has(value))) {
+                invalidHistoryFilter(`unknown outcome '${values.find((value) => !HISTORY_OUTCOMES.has(value))}'`, recovered);
+            }
+            if (ordered)
+                values.forEach((value) => parseTimestamp(value, 0, recovered));
+        },
+    });
+}
+export function parseProjectionHistorySort(value) {
+    if (value === undefined)
+        return undefined;
+    const keys = value.split(",");
+    if (keys.some((key) => !["created", "updated", "outcome", "akuma"].includes(key))) {
+        throw new FlowError("INVALID_TARGET", `invalid history sort key '${keys.find((key) => !["created", "updated", "outcome", "akuma"].includes(key))}'; expected created, updated, outcome, or akuma`);
+    }
+    if (new Set(keys).size !== keys.length)
+        throw new FlowError("INVALID_TARGET", "history sort keys must not repeat");
+    return keys;
+}
+function compare(left, right, operator) {
+    if (operator === "=")
+        return left === right;
+    if (operator === "!=")
+        return left !== right;
+    if (operator === "<")
+        return left < right;
+    if (operator === "<=")
+        return left <= right;
+    if (operator === ">")
+        return left > right;
+    if (operator === ">=")
+        return left >= right;
+    return false;
+}
+function matches(run, filter, nowMs) {
+    return filter.values.some((value) => {
+        const text = filter.field === "contract" ? run.contractId ?? "none"
+            : filter.field === "akuma" ? run.akuma ?? "none"
+                : filter.field === "role" ? run.role
+                    : filter.field === "outcome" ? run.outcome
+                        : undefined;
+        if (text !== undefined)
+            return filter.operator === "~" ? text.toLowerCase().includes(value.toLowerCase()) : compare(text, value, filter.operator);
+        const stamp = filter.field === "created" ? run.mintedAt : run.activityAt ?? run.terminalAt ?? run.mintedAt;
+        return stamp === null ? filter.operator === "!=" : compare(Date.parse(stamp), parseTimestamp(value, nowMs, [filter]), filter.operator);
+    });
+}
+function listDirectories(directory) {
+    try {
+        if (!fs.lstatSync(directory).isDirectory())
+            return null;
+        return fs.readdirSync(directory).filter((name) => !name.startsWith(".")).sort();
+    }
+    catch (error) {
+        if (isErrnoException(error) && error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+function outcomeFromLife(phase) {
+    return phase === "active" || phase === "quiescent" ? "out" : phase;
+}
+function roleFromRecords(records) {
+    const inputs = records?.find((record) => record.kind === "launch")?.facts.inputs;
+    return inputs && typeof inputs === "object" && !Array.isArray(inputs) && typeof inputs.sourceArtifactId === "string"
+        ? "revive"
+        : records?.some((record) => record.kind === "launch") ? "call" : "unknown";
+}
+async function artifactFromVerdict(cwd, artifactId, executionId, index) {
+    if (artifactId === undefined)
+        return null;
+    if (typeof artifactId !== "string" || !isResponseArtifactId(artifactId)) {
+        return { id: null, path: null, retention: "incompatible", executionId };
+    }
+    const indexed = index?.lookup(artifactId);
+    if (indexed) {
+        return indexed.state === "available"
+            ? { id: artifactId, path: indexed.artifact.absolutePath, retention: "available", executionId }
+            : { id: artifactId, path: null, retention: indexed.state, executionId };
+    }
+    if (index?.coverage === "complete")
+        return { id: artifactId, path: null, retention: "missing", executionId };
+    if (index)
+        return { id: artifactId, path: null, retention: "unavailable", executionId };
+    try {
+        const artifact = await locateResponseArtifact({
+            cwd,
+            artifactId,
+            attempt: { repo: { kind: "user" }, workdir: path.resolve(cwd), expected: "artifact", supplied: artifactId, candidates: [], inference: ["projection history artifact observation"] },
+        });
+        return { id: artifactId, path: artifact.absolutePath, retention: "available", executionId };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { id: artifactId, path: null, retention: /invalid|incompatible|malformed/i.test(message) ? "incompatible" : "missing", executionId };
+    }
+}
+function generationExecutionIds(records) {
+    return records?.filter((record) => record.kind === "launch").map((record) => record.executionId) ?? [];
+}
+function namespaceGenerationEvents(events, executionId, startOrder) {
+    return events.map((event, index) => {
+        const identity = "id" in event && typeof event.id === "string"
+            ? { id: `${executionId}:${event.id}` }
+            : {};
+        return { ...event, ...identity, seq: startOrder + index, historyTurnKey: `${executionId}:${event.turn}`, historyExecutionId: executionId };
+    });
+}
+function readHistoryEvents(directory, records) {
+    const executionIds = generationExecutionIds(records);
+    if (executionIds.length === 0) {
+        const selected = selectValidStoredAgentEvents(readProjectionEvents(directory));
+        return {
+            events: selected.events.map((event, index) => ({ ...event, seq: index })),
+            malformed: selected.malformed,
+            retention: selected.malformed > 0 ? "incompatible" : undefined,
+        };
+    }
+    const events = [];
+    let malformed = 0;
+    let unavailable = false;
+    for (const executionId of executionIds) {
+        const ledger = readGenerationEventsWithRetention(directory, executionId);
+        unavailable ||= ledger.retention === "unavailable";
+        const selected = selectValidStoredAgentEvents(ledger.events);
+        malformed += selected.malformed;
+        events.push(...namespaceGenerationEvents(selected.events, executionId, events.length));
+    }
+    return {
+        events,
+        malformed,
+        retention: malformed > 0 ? "incompatible" : unavailable ? "unavailable" : undefined,
+    };
+}
+function telemetryFromActivity(activity) {
+    if (!activity)
+        return null;
+    let inputTokens = 0;
+    let outputTokens = 0;
+    let cachedInputTokens = 0;
+    let costUsd = 0;
+    let hasUsage = false;
+    let hasCachedInputTokens = false;
+    let hasCostUsd = false;
+    for (const turn of activity.ledgerTurns) {
+        if (turn.inputTokens !== undefined) {
+            inputTokens += turn.inputTokens;
+            hasUsage = true;
+        }
+        if (turn.outputTokens !== undefined) {
+            outputTokens += turn.outputTokens;
+            hasUsage = true;
+        }
+        if (turn.cachedInputTokens !== undefined) {
+            cachedInputTokens += turn.cachedInputTokens;
+            hasCachedInputTokens = true;
+        }
+        if (turn.costUsd !== undefined) {
+            costUsd += turn.costUsd;
+            hasCostUsd = true;
+        }
+    }
+    return hasUsage || hasCachedInputTokens || hasCostUsd
+        ? { inputTokens, outputTokens, ...(hasCachedInputTokens ? { cachedInputTokens } : {}), ...(hasCostUsd ? { costUsd } : {}) }
+        : null;
+}
+async function artifactsFromGenerations(cwd, records, artifactIndex) {
+    const artifacts = [];
+    for (const record of records ?? []) {
+        if (record.kind !== "verdict" || record.facts.artifactId === undefined)
+            continue;
+        const artifact = await artifactFromVerdict(cwd, record.facts.artifactId, record.executionId, artifactIndex);
+        if (artifact)
+            artifacts.push(artifact);
+    }
+    return artifacts;
+}
+async function readRun(artifactRoot, directory, id, alias, artifactIndex, addressedArtifactId) {
+    const diagnostics = [];
+    const snapshot = observeProjectionLifeSnapshot(directory, {
+        nowMs: Date.now(),
+        startupTimeoutMs: PROJECTION_ADOPTION_TIMEOUT_MS,
+    });
+    if (snapshot.compatibility === "incompatible") {
+        return { id, ...(alias ? { alias } : {}), akuma: null, provider: null, pid: null, role: "unknown", contractId: null, outcome: "incompatible", mintedAt: null, terminalAt: null, generation: null, activityAt: null, artifact: null, artifacts: [], activityRetention: "incompatible", activityCount: 0, activityRange: null, telemetry: null, consequences: null, diagnostics: [snapshot.diagnostic], activity: null };
+    }
+    let identity;
+    try {
+        identity = readProjectionIdentity(directory);
+    }
+    catch (error) {
+        diagnostics.push(`identity unavailable: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const current = snapshot.records ? selectCurrentGeneration(snapshot.records) : undefined;
+    let activity = null;
+    let activityRetention = "complete";
+    try {
+        const historyEvents = readHistoryEvents(directory, snapshot.records);
+        if (historyEvents.malformed > 0)
+            diagnostics.push(`${historyEvents.malformed} malformed activity event${historyEvents.malformed === 1 ? "" : "s"} omitted`);
+        activity = historyEvents.events.length > 0
+            ? foldPublicProjectionActivity(historyEvents.events, historyEvents.retention === "incompatible" ? "incompatible" : historyEvents.retention === "unavailable" ? "unavailable" : undefined)
+            : null;
+        activityRetention = activity?.retention.state ?? historyEvents.retention ?? "complete";
+    }
+    catch (error) {
+        activityRetention = "unavailable";
+        diagnostics.push(`activity unavailable: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const terminalAt = extractTerminalTimestamp(current?.verdict?.facts) ?? null;
+    const activityAt = activity?.retainedTimeline.at(-1)?.at ?? null;
+    const artifacts = await artifactsFromGenerations(artifactRoot, snapshot.records, artifactIndex);
+    const artifact = addressedArtifactId === undefined
+        ? current ? artifacts.find((candidate) => candidate.executionId === current.launch.executionId) ?? null : null
+        : artifacts.find((candidate) => candidate.id === addressedArtifactId) ?? null;
+    return {
+        id,
+        ...(alias ? { alias } : {}),
+        akuma: identity?.akuma ?? null,
+        provider: identity?.provider ?? null,
+        pid: identity?.pid ?? null,
+        role: roleFromRecords(snapshot.records),
+        contractId: identity?.binding.kind === "commission" ? identity.binding.commissionId : null,
+        outcome: outcomeFromLife(snapshot.life.phase),
+        mintedAt: identity?.mintedAt ?? null,
+        terminalAt,
+        generation: current && typeof current.launch.facts.createdAt === "string"
+            ? {
+                executionId: current.launch.executionId,
+                createdAt: current.launch.facts.createdAt,
+                adoptedAt: typeof current.adoption?.facts.adoptedAt === "string" ? current.adoption.facts.adoptedAt : null,
+            }
+            : null,
+        activityAt,
+        artifact,
+        artifacts,
+        activityRetention,
+        activityCount: activity?.retention.retainedCount ?? 0,
+        activityRange: activity?.retention.range ?? null,
+        telemetry: telemetryFromActivity(activity),
+        consequences: null,
+        diagnostics,
+        activity,
+    };
+}
+async function consequencesForContracts(cwd, contractIds) {
+    return readContractHistoryConsequences(cwd, contractIds);
+}
+function withLifecycleConsequences(run, consequences) {
+    return run.contractId === null ? run : { ...run, consequences: consequences.get(run.contractId) ?? unavailableContractHistoryConsequences("repository-unavailable") };
+}
+async function aliasesFor(cwd, root) {
+    const result = new Map();
+    const aliasRoot = path.join(path.dirname(path.dirname(root)), ".keiyaku", "projection-alias");
+    for (const alias of listDirectories(aliasRoot) ?? []) {
+        try {
+            const id = await readProjectionAlias(cwd, alias);
+            if (id)
+                result.set(id, alias);
+        }
+        catch { /* malformed alias has no trustworthy history coordinate */ }
+    }
+    return result;
+}
+export async function readProjectionHistory(cwd, options = {}) {
+    const root = await projectionRoot(cwd);
+    const akumas = listDirectories(root);
+    if (!akumas)
+        return [];
+    const aliases = await aliasesFor(cwd, root);
+    const artifactRoot = await projectionCoordinateRoot(cwd);
+    const artifactIndex = await indexResponseArtifacts({
+        cwd: artifactRoot,
+        ...(options.readArtifactDirectory ? { readDirectory: options.readArtifactDirectory } : {}),
+    });
+    const discovered = [];
+    for (const akuma of akumas) {
+        for (const hex of listDirectories(path.join(root, akuma)) ?? []) {
+            const id = `${akuma}/${hex}`;
+            if (!isProjectionId(id))
+                continue;
+            discovered.push(await readRun(artifactRoot, path.join(root, akuma, hex), id, aliases.get(id), artifactIndex));
+        }
+    }
+    const consequences = await consequencesForContracts(cwd, discovered.flatMap((run) => run.contractId === null ? [] : [run.contractId]));
+    return discovered.map(({ activity: _activity, ...run }) => withLifecycleConsequences(run, consequences));
+}
+export async function readExactProjectionHistory(cwd, id) {
+    if (!isProjectionId(id))
+        return null;
+    const directory = await projectionDir(cwd, id);
+    const root = await projectionRoot(cwd);
+    if (!listDirectories(directory))
+        return null;
+    const artifactRoot = await projectionCoordinateRoot(cwd);
+    const artifactIndex = await indexResponseArtifacts({ cwd: artifactRoot });
+    const run = await readRun(artifactRoot, directory, id, (await aliasesFor(cwd, root)).get(id), artifactIndex);
+    return withLifecycleConsequences(run, await consequencesForContracts(cwd, run.contractId === null ? [] : [run.contractId]));
+}
+function directoryForId(root, id) {
+    const [akuma, hex] = id.split("/");
+    return path.join(root, akuma, hex);
+}
+function projectionHistoryDirectories(root, preferredAkuma) {
+    const directories = (listDirectories(root) ?? []).flatMap((akuma) => (listDirectories(path.join(root, akuma)) ?? []).map((hex) => path.join(root, akuma, hex)));
+    if (preferredAkuma === undefined)
+        return directories;
+    return directories.sort((left, right) => {
+        const leftPreferred = path.basename(path.dirname(left)) === preferredAkuma;
+        const rightPreferred = path.basename(path.dirname(right)) === preferredAkuma;
+        return leftPreferred === rightPreferred ? left.localeCompare(right) : leftPreferred ? -1 : 1;
+    });
+}
+/**
+ * One query-local relationship index reads every published heart through its
+ * public snapshot. Response metadata may prioritize a likely Akuma, but it
+ * never excludes another heart from ambiguity or uniqueness truth.
+ */
+async function retainedArtifactRelationships(root, artifactId, preferredAkuma) {
+    const directories = projectionHistoryDirectories(root, preferredAkuma);
+    const matches = [];
+    const batchSize = 32;
+    for (let start = 0; start < directories.length; start += batchSize) {
+        const batch = directories.slice(start, start + batchSize);
+        const rows = await Promise.all(batch.map(async (directory) => {
+            const id = `${path.basename(path.dirname(directory))}/${path.basename(directory)}`;
+            if (!isProjectionId(id))
+                return [];
+            const snapshot = observeProjectionLifeSnapshot(directory, {
+                nowMs: Date.now(),
+                startupTimeoutMs: PROJECTION_ADOPTION_TIMEOUT_MS,
+            });
+            if (snapshot.compatibility === "incompatible" || !snapshot.records)
+                return [];
+            return snapshot.records
+                .filter((record) => record.kind === "verdict" && record.facts.artifactId === artifactId)
+                .map((record) => ({ id, executionId: record.executionId }));
+        }));
+        matches.push(...rows.flat());
+    }
+    return matches;
+}
+async function resolveProjectionHistoryAddressAtRoot(cwd, root, address, artifactAkuma) {
+    if (isProjectionId(address))
+        return listDirectories(directoryForId(root, address)) ? { id: address } : null;
+    if (isResponseArtifactId(address)) {
+        const matches = await retainedArtifactRelationships(root, address, artifactAkuma);
+        if (matches.length > 1) {
+            throw new FlowError("INVALID_TARGET", `response artifact '${address}' has ambiguous retained projection relationships: ${matches.map((match) => `${match.id}@${match.executionId}`).join(", ")}`);
+        }
+        return matches[0] ? { id: matches[0].id, addressedArtifactId: address } : null;
+    }
+    const id = await readProjectionAlias(cwd, address);
+    if (!id)
+        return null;
+    if (!listDirectories(directoryForId(root, id))) {
+        throw new FlowError("PROJECTION_HISTORY_NOT_FOUND", `projection alias ${address} points to missing retained projection ${id}`);
+    }
+    return { id };
+}
+/** Resolve and inspect one coordinate with one root/alias read and one query-local artifact index. */
+export async function readProjectionHistoryAddress(cwd, address, options = {}) {
+    const root = await projectionRoot(cwd);
+    const artifactRoot = await projectionCoordinateRoot(cwd);
+    const artifactIndex = isResponseArtifactId(address)
+        ? await indexResponseArtifacts({
+            cwd: artifactRoot,
+            ...(options.readArtifactDirectory ? { readDirectory: options.readArtifactDirectory } : {}),
+        })
+        : undefined;
+    const indexedArtifact = artifactIndex?.lookup(address);
+    const artifactAkuma = indexedArtifact?.state === "available"
+        ? indexedArtifact.artifact.subagentName ?? indexedArtifact.artifact.launchSnapshot?.akuma.name
+        : undefined;
+    const resolved = await resolveProjectionHistoryAddressAtRoot(cwd, root, address, artifactAkuma);
+    if (!resolved)
+        return null;
+    const directory = directoryForId(root, resolved.id);
+    if (!listDirectories(directory))
+        return null;
+    const resolvedArtifactIndex = artifactIndex ?? await indexResponseArtifacts({
+        cwd: artifactRoot,
+        ...(options.readArtifactDirectory ? { readDirectory: options.readArtifactDirectory } : {}),
+    });
+    const run = await readRun(artifactRoot, directory, resolved.id, (await aliasesFor(cwd, root)).get(resolved.id), resolvedArtifactIndex, resolved.addressedArtifactId);
+    return withLifecycleConsequences(run, await consequencesForContracts(cwd, run.contractId === null ? [] : [run.contractId]));
+}
+export async function resolveProjectionHistoryAddress(cwd, address) {
+    const root = await projectionRoot(cwd);
+    return (await resolveProjectionHistoryAddressAtRoot(cwd, root, address))?.id ?? null;
+}
+export function selectProjectionHistory(runs, options = {}) {
+    const filters = (options.filters ?? []).map(parseProjectionHistoryFilter);
+    const keys = parseProjectionHistorySort(options.sort);
+    const nowMs = options.nowMs ?? Date.now();
+    const stamp = (run, key) => key === "created" ? run.mintedAt ?? "" : run.activityAt ?? run.terminalAt ?? run.mintedAt ?? "";
+    return [...runs]
+        .filter((run) => filters.every((expression) => expression.some((filter) => matches(run, filter, nowMs))))
+        .sort((left, right) => {
+        const compareKey = (key) => {
+            const a = key === "akuma" ? left.akuma ?? "" : key === "outcome" ? left.outcome : stamp(left, key);
+            const b = key === "akuma" ? right.akuma ?? "" : key === "outcome" ? right.outcome : stamp(right, key);
+            return a < b ? -1 : a > b ? 1 : 0;
+        };
+        if (keys)
+            for (const key of keys) {
+                const result = compareKey(key);
+                if (result)
+                    return result;
+            }
+        else {
+            const recent = stamp(right, "updated").localeCompare(stamp(left, "updated"));
+            if (recent)
+                return recent;
+        }
+        return left.id.localeCompare(right.id);
+    });
+}

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

@@ -323,6 +323,18 @@ export function observeProjectionRunnerLock(projectionDirectory, platform = proc
         };
     }
     const lockPath = projectionRunnerLockPath(projectionDirectory);
+    try {
+        if (!fs.lstatSync(lockPath).isFile()) {
+            return {
+                state: "unknown",
+                reason: "open-failed",
+                detail: "projection runner lock database is not a regular file",
+            };
+        }
+    }
+    catch (error) {
+        return { state: "unknown", reason: "open-failed", detail: errorDetail(error) };
+    }
     let database;
     try {
         database = new DatabaseSync(lockPath);