@astrosheep/keiyaku 2.8.4 → 2.9.0

package/build/core/projection/generation/model.js

@@ -0,0 +1,201 @@
+import { GENERATION_VERDICT_STATES, } from "../../projection-life-protocol.js";
+export { GENERATION_VERDICT_STATES };
+export const VERDICTS = new Set(GENERATION_VERDICT_STATES);
+export class ProjectionGenerationStoreError extends Error {
+    code = "PROJECTION_GENERATION_STORE_ERROR";
+    constructor(message, options) {
+        super(message, options);
+        this.name = "ProjectionGenerationStoreError";
+    }
+}
+export function isPlainObject(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+export function assertJsonValue(value, location, ancestors) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return;
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new ProjectionGenerationStoreError(`${location} contains a non-finite number`);
+        return;
+    }
+    if (typeof value !== "object") {
+        throw new ProjectionGenerationStoreError(`${location} contains a non-JSON value`);
+    }
+    if (ancestors.has(value))
+        throw new ProjectionGenerationStoreError(`${location} contains a cycle`);
+    ancestors.add(value);
+    try {
+        if (Array.isArray(value)) {
+            value.forEach((item, index) => assertJsonValue(item, `${location}[${index}]`, ancestors));
+            return;
+        }
+        if (!isPlainObject(value))
+            throw new ProjectionGenerationStoreError(`${location} must contain only plain JSON objects`);
+        for (const [key, item] of Object.entries(value)) {
+            assertJsonValue(item, `${location}.${key}`, ancestors);
+        }
+    }
+    finally {
+        ancestors.delete(value);
+    }
+}
+export function cloneFacts(value, location) {
+    if (!isPlainObject(value))
+        throw new ProjectionGenerationStoreError(`${location} must be a JSON object`);
+    assertJsonValue(value, location, new Set());
+    return JSON.parse(JSON.stringify(value));
+}
+export function assertExecutionId(executionId) {
+    if (typeof executionId !== "string" || executionId.trim() === "") {
+        throw new ProjectionGenerationStoreError("executionId must be a non-blank string");
+    }
+    return executionId;
+}
+export function assertNonNegativeSafeInteger(value, location) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new ProjectionGenerationStoreError(`${location} must be a non-negative safe integer`);
+    }
+    return value;
+}
+export function assertPositiveSafeInteger(value, location) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new ProjectionGenerationStoreError(`${location} must be a positive safe integer`);
+    }
+    return value;
+}
+export function assertIsoTimestamp(value, location) {
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new ProjectionGenerationStoreError(`${location} must be an ISO-8601 timestamp`);
+    }
+    const milliseconds = Date.parse(value);
+    if (!Number.isFinite(milliseconds) || new Date(milliseconds).toISOString() !== value) {
+        throw new ProjectionGenerationStoreError(`${location} must be a canonical ISO-8601 timestamp`);
+    }
+    return value;
+}
+export function validateTellFence(value, location) {
+    if (!Array.isArray(value))
+        throw new ProjectionGenerationStoreError(`${location} must be an array`);
+    const seen = new Set();
+    return value.map((tellId, index) => {
+        if (typeof tellId !== "string" || tellId.trim() === "") {
+            throw new ProjectionGenerationStoreError(`${location}[${index}] must be a non-blank string`);
+        }
+        if (seen.has(tellId))
+            throw new ProjectionGenerationStoreError(`${location} contains duplicate tell '${tellId}'`);
+        seen.add(tellId);
+        return tellId;
+    });
+}
+export function validateLaunchFacts(value, location) {
+    const facts = cloneFacts(value, location);
+    facts.createdAt = assertIsoTimestamp(facts.createdAt, `${location}.createdAt`);
+    if (facts.tellFence !== undefined)
+        facts.tellFence = validateTellFence(facts.tellFence, `${location}.tellFence`);
+    if ("state" in facts)
+        throw new ProjectionGenerationStoreError(`${location}.state is reserved for verdict records`);
+    return facts;
+}
+export function validateAdoptionFacts(value, location) {
+    const facts = cloneFacts(value, location);
+    if ("state" in facts)
+        throw new ProjectionGenerationStoreError(`${location}.state is reserved for verdict records`);
+    return facts;
+}
+export function validateKillIntentFacts(value, location) {
+    const facts = cloneFacts(value, location);
+    if (facts.operatorAction !== "kill") {
+        throw new ProjectionGenerationStoreError(`${location}.operatorAction must be exactly 'kill'`);
+    }
+    facts.killedAt = assertIsoTimestamp(facts.killedAt, `${location}.killedAt`);
+    if ("state" in facts)
+        throw new ProjectionGenerationStoreError(`${location}.state is reserved for verdict records`);
+    return facts;
+}
+export function validateVerdictFacts(value, location) {
+    const facts = cloneFacts(value, location);
+    if (typeof facts.state !== "string" || !VERDICTS.has(facts.state)) {
+        throw new ProjectionGenerationStoreError(`${location}.state is not in the closed verdict vocabulary`);
+    }
+    return facts;
+}
+export function parseStoredRow(row) {
+    const seq = typeof row.seq === "bigint" ? Number(row.seq) : row.seq;
+    if (!Number.isSafeInteger(seq) || seq <= 0) {
+        throw new ProjectionGenerationStoreError(`generation row has invalid seq '${String(row.seq)}'`);
+    }
+    if (row.kind !== "launch"
+        && row.kind !== "adoption"
+        && row.kind !== "kill-intent"
+        && row.kind !== "verdict") {
+        throw new ProjectionGenerationStoreError(`generation row ${seq} has unknown kind '${row.kind}'`);
+    }
+    const executionId = assertExecutionId(row.execution_id);
+    let decoded;
+    try {
+        decoded = JSON.parse(row.facts_json);
+    }
+    catch (error) {
+        throw new ProjectionGenerationStoreError(`generation row ${seq} contains malformed facts JSON`, { cause: error });
+    }
+    const location = `generation row ${seq} facts`;
+    const facts = row.kind === "launch"
+        ? validateLaunchFacts(decoded, location)
+        : row.kind === "adoption"
+            ? validateAdoptionFacts(decoded, location)
+            : row.kind === "kill-intent"
+                ? validateKillIntentFacts(decoded, location)
+                : validateVerdictFacts(decoded, location);
+    return { seq, kind: row.kind, executionId, facts };
+}
+export function validateHistory(records) {
+    let current = null;
+    const launchIds = new Set();
+    for (let index = 0; index < records.length; index += 1) {
+        const record = records[index];
+        const expectedSeq = index + 1;
+        if (record.seq !== expectedSeq) {
+            throw new ProjectionGenerationStoreError(`generation history is not dense: expected seq ${expectedSeq}, found ${record.seq}`);
+        }
+        if (record.kind === "launch") {
+            if (current && !current.verdict) {
+                throw new ProjectionGenerationStoreError(`generation row ${record.seq} launches before execution '${current.launch.executionId}' is terminal`);
+            }
+            if (launchIds.has(record.executionId)) {
+                throw new ProjectionGenerationStoreError(`generation row ${record.seq} reuses executionId '${record.executionId}'`);
+            }
+            launchIds.add(record.executionId);
+            current = { launch: record };
+            continue;
+        }
+        if (!current)
+            throw new ProjectionGenerationStoreError(`generation row ${record.seq} appears before any launch`);
+        if (record.executionId !== current.launch.executionId) {
+            throw new ProjectionGenerationStoreError(`generation row ${record.seq} does not join the current launch`);
+        }
+        if (record.kind === "adoption") {
+            if (current.adoption)
+                throw new ProjectionGenerationStoreError(`generation row ${record.seq} duplicates adoption`);
+            if (current.verdict)
+                throw new ProjectionGenerationStoreError(`generation row ${record.seq} adopts a terminal execution`);
+            current.adoption = record;
+            continue;
+        }
+        if (record.kind === "kill-intent") {
+            if (current.killIntent)
+                throw new ProjectionGenerationStoreError(`generation row ${record.seq} duplicates kill-intent`);
+            if (current.verdict)
+                throw new ProjectionGenerationStoreError(`generation row ${record.seq} records kill-intent after verdict`);
+            current.killIntent = record;
+            continue;
+        }
+        if (current.verdict)
+            throw new ProjectionGenerationStoreError(`generation row ${record.seq} duplicates verdict`);
+        current.verdict = record;
+    }
+    return current;
+}

package/build/core/projection/generation/store.js

@@ -0,0 +1,73 @@
+import { PROJECTION_GENERATION_SCHEMA_VERSION, PROJECTION_GENERATION_STORE_FILE, assertDatabaseOpen, closeDatabase, isProjectionGenerationSchemaV1Residue, openMutableDatabase, openReadOnlyDatabase, readValidatedHistory, } from "./database.js";
+import { initializeIdentity as initializeProjectionIdentity, readIdentity as readProjectionIdentity, } from "./identity.js";
+import * as transitions from "./transitions.js";
+export { PROJECTION_GENERATION_SCHEMA_VERSION, PROJECTION_GENERATION_STORE_FILE, isProjectionGenerationSchemaV1Residue, };
+export { GENERATION_VERDICT_STATES, ProjectionGenerationStoreError, } from "./model.js";
+export class ProjectionGenerationStore {
+    databasePath;
+    readOnly;
+    #database;
+    constructor(databasePath, database, readOnly) {
+        this.databasePath = databasePath;
+        this.#database = database;
+        this.readOnly = readOnly;
+    }
+    static open(projectionDirectory) {
+        const { databasePath, database } = openMutableDatabase(projectionDirectory);
+        return new ProjectionGenerationStore(databasePath, database, false);
+    }
+    static openReadOnly(projectionDirectory) {
+        const { databasePath, database } = openReadOnlyDatabase(projectionDirectory);
+        return new ProjectionGenerationStore(databasePath, database, true);
+    }
+    close() {
+        closeDatabase(this.#database);
+    }
+    readRecords() {
+        assertDatabaseOpen(this.#database);
+        return readValidatedHistory(this.#database).records;
+    }
+    readCurrentGeneration() {
+        assertDatabaseOpen(this.#database);
+        return readValidatedHistory(this.#database).current;
+    }
+    initializeIdentity(identity) {
+        initializeProjectionIdentity(this.#database, this.databasePath, this.readOnly, identity);
+    }
+    readIdentity() {
+        return readProjectionIdentity(this.#database, this.databasePath);
+    }
+    launchIfSettled(input) {
+        return transitions.launchIfSettled(this.#database, this.readOnly, input);
+    }
+    adoptionIfCurrent(input) {
+        return transitions.adoptionIfCurrent(this.#database, this.readOnly, input);
+    }
+    requestKillIfOpen(input) {
+        return transitions.requestKillIfOpen(this.#database, this.readOnly, input);
+    }
+    runnerKilledIfRequested(input) {
+        return transitions.runnerKilledIfRequested(this.#database, this.readOnly, input);
+    }
+    settleKillIfRunnerDead(input) {
+        return transitions.settleKillIfRunnerDead(this.#database, this.readOnly, input);
+    }
+    verdictIfOpen(input) {
+        return transitions.verdictIfOpen(this.#database, this.readOnly, input);
+    }
+    supersedeStartupTimeout(input) {
+        return transitions.supersedeStartupTimeout(this.#database, this.readOnly, input);
+    }
+    replaceDeadRunner(input) {
+        return transitions.replaceDeadRunner(this.#database, this.readOnly, input);
+    }
+    handoff(input) {
+        return transitions.handoff(this.#database, this.readOnly, input);
+    }
+}
+export function openProjectionGenerationStore(projectionDirectory) {
+    return ProjectionGenerationStore.open(projectionDirectory);
+}
+export function openProjectionGenerationStoreReadOnly(projectionDirectory) {
+    return ProjectionGenerationStore.openReadOnly(projectionDirectory);
+}

package/build/core/projection/generation/transitions.js

@@ -0,0 +1,258 @@
+import { appendRecord, readValidatedHistory, writeTransition, } from "./database.js";
+import { ProjectionGenerationStoreError, VERDICTS, assertExecutionId, assertIsoTimestamp, assertNonNegativeSafeInteger, assertPositiveSafeInteger, cloneFacts, validateAdoptionFacts, validateKillIntentFacts, validateLaunchFacts, validateTellFence, validateVerdictFacts, } from "./model.js";
+function committed(records) {
+    return { status: "committed", records };
+}
+function rejected(reason, current) {
+    return { status: "rejected", reason, current };
+}
+export function launchIfSettled(database, readOnly, input) {
+    const executionId = assertExecutionId(input.executionId);
+    const facts = validateLaunchFacts(input.facts, "launch facts");
+    return writeTransition(database, readOnly, () => {
+        const history = readValidatedHistory(database);
+        if (history.records.some((record) => record.kind === "launch" && record.executionId === executionId)) {
+            return rejected("execution-id-already-used", history.current);
+        }
+        if (history.current && !history.current.verdict) {
+            return rejected("current-generation-open", history.current);
+        }
+        return committed([appendRecord(database, "launch", executionId, facts, history.records.length + 1)]);
+    });
+}
+export function adoptionIfCurrent(database, readOnly, input) {
+    const executionId = assertExecutionId(input.executionId);
+    const facts = validateAdoptionFacts(input.facts, "adoption facts");
+    return writeTransition(database, readOnly, () => {
+        const history = readValidatedHistory(database);
+        const current = history.current;
+        if (!current)
+            return rejected("no-current-launch", null);
+        if (current.launch.executionId !== executionId)
+            return rejected("not-current", current);
+        if (current.verdict)
+            return rejected("already-terminal", current);
+        if (current.adoption)
+            return rejected("already-adopted", current);
+        return committed([appendRecord(database, "adoption", executionId, facts, history.records.length + 1)]);
+    });
+}
+export function requestKillIfOpen(database, readOnly, input) {
+    const executionId = assertExecutionId(input.executionId);
+    const killedAt = assertIsoTimestamp(input.killedAt, "killedAt");
+    return writeTransition(database, readOnly, () => {
+        const history = readValidatedHistory(database);
+        const current = history.current;
+        if (!current)
+            return rejected("no-current-launch", null);
+        if (current.launch.executionId !== executionId)
+            return rejected("not-current", current);
+        if (current.verdict)
+            return rejected("already-terminal", current);
+        if (current.killIntent)
+            return rejected("kill-requested", current);
+        const facts = validateKillIntentFacts({ operatorAction: "kill", killedAt }, "kill-intent facts");
+        return committed([appendRecord(database, "kill-intent", executionId, facts, history.records.length + 1)]);
+    });
+}
+export function runnerKilledIfRequested(database, readOnly, input) {
+    const executionId = assertExecutionId(input.executionId);
+    const callerFacts = cloneFacts(input.facts ?? {}, "killed verdict facts");
+    if ("state" in callerFacts) {
+        throw new ProjectionGenerationStoreError("killed verdict facts.state is reserved");
+    }
+    if ("killIntentSeq" in callerFacts) {
+        throw new ProjectionGenerationStoreError("killed verdict facts.killIntentSeq is reserved");
+    }
+    if ("killedAt" in callerFacts) {
+        throw new ProjectionGenerationStoreError("killed verdict facts.killedAt is reserved");
+    }
+    return writeTransition(database, readOnly, () => {
+        const history = readValidatedHistory(database);
+        const current = history.current;
+        if (!current)
+            return rejected("no-current-launch", null);
+        if (current.launch.executionId !== executionId)
+            return rejected("not-current", current);
+        if (current.verdict)
+            return rejected("already-terminal", current);
+        if (!current.killIntent)
+            return rejected("kill-not-requested", current);
+        const facts = validateVerdictFacts({
+            ...callerFacts,
+            state: "killed",
+            killIntentSeq: current.killIntent.seq,
+            killedAt: current.killIntent.facts.killedAt,
+        }, "killed verdict facts");
+        return committed([appendRecord(database, "verdict", executionId, facts, history.records.length + 1)]);
+    });
+}
+export function settleKillIfRunnerDead(database, readOnly, input) {
+    const executionId = assertExecutionId(input.executionId);
+    const releasedLockEvidence = cloneFacts(input.releasedLockEvidence, "released runner-lock evidence");
+    if (Object.keys(releasedLockEvidence).length === 0) {
+        throw new ProjectionGenerationStoreError("released runner-lock evidence must not be empty");
+    }
+    const callerFacts = cloneFacts(input.facts ?? {}, "killed verdict facts");
+    if ("state" in callerFacts) {
+        throw new ProjectionGenerationStoreError("killed verdict facts.state is reserved");
+    }
+    if ("killIntentSeq" in callerFacts) {
+        throw new ProjectionGenerationStoreError("killed verdict facts.killIntentSeq is reserved");
+    }
+    if ("killedAt" in callerFacts) {
+        throw new ProjectionGenerationStoreError("killed verdict facts.killedAt is reserved");
+    }
+    return writeTransition(database, readOnly, () => {
+        const history = readValidatedHistory(database);
+        const current = history.current;
+        if (!current)
+            return rejected("no-current-launch", null);
+        if (current.launch.executionId !== executionId)
+            return rejected("not-current", current);
+        if (current.verdict)
+            return rejected("already-terminal", current);
+        if (!current.killIntent)
+            return rejected("kill-not-requested", current);
+        const facts = validateVerdictFacts({
+            ...callerFacts,
+            state: "killed",
+            killIntentSeq: current.killIntent.seq,
+            killedAt: current.killIntent.facts.killedAt,
+            releasedLockEvidence,
+        }, "killed verdict facts");
+        return committed([appendRecord(database, "verdict", executionId, facts, history.records.length + 1)]);
+    });
+}
+export function verdictIfOpen(database, readOnly, input) {
+    const executionId = assertExecutionId(input.executionId);
+    if (!VERDICTS.has(input.verdict))
+        throw new ProjectionGenerationStoreError(`unknown verdict '${String(input.verdict)}'`);
+    if (input.verdict === "killed") {
+        throw new ProjectionGenerationStoreError("verdict 'killed' is reserved to runnerKilledIfRequested and settleKillIfRunnerDead");
+    }
+    const facts = validateVerdictFacts({ ...(input.facts ?? {}), state: input.verdict }, "verdict facts");
+    return writeTransition(database, readOnly, () => {
+        const history = readValidatedHistory(database);
+        const current = history.current;
+        if (!current)
+            return rejected("no-current-launch", null);
+        if (current.launch.executionId !== executionId)
+            return rejected("not-current", current);
+        if (current.verdict)
+            return rejected("already-terminal", current);
+        if (current.killIntent) {
+            const killEscalationFailed = input.verdict === "failed"
+                && input.facts?.operatorAction === "kill";
+            if (!killEscalationFailed)
+                return rejected("kill-requested", current);
+        }
+        if (input.verdict === "launch-failed" && current.adoption) {
+            return rejected("already-adopted", current);
+        }
+        return committed([appendRecord(database, "verdict", executionId, facts, history.records.length + 1)]);
+    });
+}
+export function supersedeStartupTimeout(database, readOnly, input) {
+    const executionId = assertExecutionId(input.executionId);
+    const successorExecutionId = assertExecutionId(input.successorExecutionId);
+    const observedAtMs = assertNonNegativeSafeInteger(input.observedAtMs, "observedAtMs");
+    const startupTimeoutMs = assertPositiveSafeInteger(input.startupTimeoutMs, "startupTimeoutMs");
+    const diagnostic = cloneFacts(input.diagnostic, "startup-timeout diagnostic");
+    const successorFacts = validateLaunchFacts(input.successorFacts, "successor launch facts");
+    return writeTransition(database, readOnly, () => {
+        const history = readValidatedHistory(database);
+        const current = history.current;
+        if (!current)
+            return rejected("no-current-launch", null);
+        if (current.launch.executionId !== executionId)
+            return rejected("not-current", current);
+        if (current.verdict)
+            return rejected("already-terminal", current);
+        if (current.killIntent)
+            return rejected("kill-requested", current);
+        if (current.adoption)
+            return rejected("already-adopted", current);
+        if (history.records.some((record) => record.kind === "launch" && record.executionId === successorExecutionId)) {
+            return rejected("execution-id-already-used", current);
+        }
+        const launchedAtMs = Date.parse(current.launch.facts.createdAt);
+        if (observedAtMs - launchedAtMs < startupTimeoutMs) {
+            return rejected("startup-timeout-not-elapsed", current);
+        }
+        const verdictFacts = validateVerdictFacts({ ...diagnostic, state: "launch-failed" }, "startup-timeout verdict facts");
+        const firstSeq = history.records.length + 1;
+        return committed([
+            appendRecord(database, "verdict", executionId, verdictFacts, firstSeq),
+            appendRecord(database, "launch", successorExecutionId, successorFacts, firstSeq + 1),
+        ]);
+    });
+}
+export function replaceDeadRunner(database, readOnly, input) {
+    const executionId = assertExecutionId(input.executionId);
+    const successorExecutionId = assertExecutionId(input.successorExecutionId);
+    const releasedLockEvidence = cloneFacts(input.releasedLockEvidence, "released runner-lock evidence");
+    if (Object.keys(releasedLockEvidence).length === 0) {
+        throw new ProjectionGenerationStoreError("released runner-lock evidence must not be empty");
+    }
+    const successorFacts = validateLaunchFacts(input.successorFacts, "dead-runner successor launch facts");
+    return writeTransition(database, readOnly, () => {
+        const history = readValidatedHistory(database);
+        const current = history.current;
+        if (!current)
+            return rejected("no-current-launch", null);
+        if (current.launch.executionId !== executionId)
+            return rejected("not-current", current);
+        if (current.verdict)
+            return rejected("already-terminal", current);
+        if (current.killIntent)
+            return rejected("kill-requested", current);
+        if (!current.adoption)
+            return rejected("not-adopted", current);
+        if (history.records.some((record) => record.kind === "launch" && record.executionId === successorExecutionId)) {
+            return rejected("execution-id-already-used", current);
+        }
+        const verdictFacts = validateVerdictFacts({ state: "lost-runner", releasedLockEvidence }, "dead-runner verdict facts");
+        const firstSeq = history.records.length + 1;
+        return committed([
+            appendRecord(database, "verdict", executionId, verdictFacts, firstSeq),
+            appendRecord(database, "launch", successorExecutionId, successorFacts, firstSeq + 1),
+        ]);
+    });
+}
+export function handoff(database, readOnly, input) {
+    const executionId = assertExecutionId(input.executionId);
+    const successorExecutionId = assertExecutionId(input.successorExecutionId);
+    const completionFacts = cloneFacts(input.completionFacts, "handoff completion facts");
+    if ("state" in completionFacts)
+        throw new ProjectionGenerationStoreError("handoff completion facts.state is reserved");
+    const successorFactsBase = validateLaunchFacts(input.successorFacts, "handoff successor launch facts");
+    if (successorFactsBase.tellFence !== undefined) {
+        throw new ProjectionGenerationStoreError("handoff successor launch facts.tellFence must be supplied only through handoff.tellFence");
+    }
+    const tellFence = validateTellFence([...input.tellFence], "handoff tellFence");
+    const successorFacts = validateLaunchFacts({ ...successorFactsBase, tellFence }, "handoff successor launch facts");
+    return writeTransition(database, readOnly, () => {
+        const history = readValidatedHistory(database);
+        const current = history.current;
+        if (!current)
+            return rejected("no-current-launch", null);
+        if (current.launch.executionId !== executionId)
+            return rejected("not-current", current);
+        if (current.verdict)
+            return rejected("already-terminal", current);
+        if (current.killIntent)
+            return rejected("kill-requested", current);
+        if (!current.adoption)
+            return rejected("not-adopted", current);
+        if (history.records.some((record) => record.kind === "launch" && record.executionId === successorExecutionId)) {
+            return rejected("execution-id-already-used", current);
+        }
+        const verdictFacts = validateVerdictFacts({ ...completionFacts, state: "completed" }, "handoff verdict facts");
+        const firstSeq = history.records.length + 1;
+        return committed([
+            appendRecord(database, "verdict", executionId, verdictFacts, firstSeq),
+            appendRecord(database, "launch", successorExecutionId, successorFacts, firstSeq + 1),
+        ]);
+    });
+}