@astrosheep/keiyaku 1.0.0 → 1.0.2

package/build/core/projection/generation.js

@@ -0,0 +1,412 @@
+export class ProjectionGenerationError extends Error {
+    code = "PROJECTION_GENERATION_ERROR";
+    constructor(message, options) {
+        super(message, options);
+        this.name = "ProjectionGenerationError";
+    }
+}
+export const GENERATION_VERDICTS = [
+    "completed",
+    "failed",
+    "launch-failed",
+    "lost-runner",
+    "dismissed",
+];
+const VERDICTS = new Set(GENERATION_VERDICTS);
+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;
+}
+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 ProjectionGenerationError(`${location} contains a non-finite number`);
+        }
+        return;
+    }
+    if (typeof value !== "object") {
+        throw new ProjectionGenerationError(`${location} contains a non-JSON value`);
+    }
+    if (ancestors.has(value)) {
+        throw new ProjectionGenerationError(`${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 ProjectionGenerationError(`${location} must contain only plain JSON objects`);
+        }
+        for (const [key, item] of Object.entries(value)) {
+            assertJsonValue(item, `${location}.${key}`, ancestors);
+        }
+    }
+    finally {
+        ancestors.delete(value);
+    }
+}
+function cloneFacts(value, location) {
+    if (!isPlainObject(value)) {
+        throw new ProjectionGenerationError(`${location} must be a JSON object`);
+    }
+    assertJsonValue(value, location, new Set());
+    return JSON.parse(JSON.stringify(value));
+}
+function assertExecutionId(executionId) {
+    if (typeof executionId !== "string" || executionId.trim() === "") {
+        throw new ProjectionGenerationError("executionId must be a non-blank string");
+    }
+    return executionId;
+}
+function assertNonNegativeSafeInteger(value, location) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new ProjectionGenerationError(`${location} must be a non-negative safe integer`);
+    }
+    return value;
+}
+function assertPositiveSafeInteger(value, location) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new ProjectionGenerationError(`${location} must be a positive safe integer`);
+    }
+    return value;
+}
+function assertIsoTimestamp(value, location) {
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new ProjectionGenerationError(`${location} must be an ISO-8601 timestamp`);
+    }
+    const milliseconds = Date.parse(value);
+    if (!Number.isFinite(milliseconds) || new Date(Date.parse(value)).toISOString() !== value) {
+        throw new ProjectionGenerationError(`${location} must be a canonical ISO-8601 timestamp`);
+    }
+    return value;
+}
+function validateTellFence(value, location) {
+    if (!Array.isArray(value)) {
+        throw new ProjectionGenerationError(`${location} must be an array`);
+    }
+    const seen = new Set();
+    return value.map((tellId, index) => {
+        if (typeof tellId !== "string" || tellId.trim() === "") {
+            throw new ProjectionGenerationError(`${location}[${index}] must be a non-blank string`);
+        }
+        if (seen.has(tellId)) {
+            throw new ProjectionGenerationError(`${location} contains duplicate tell '${tellId}'`);
+        }
+        seen.add(tellId);
+        return tellId;
+    });
+}
+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 ProjectionGenerationError(`${location}.state is reserved for verdict records`);
+    }
+    return facts;
+}
+function validateAdoptionFacts(value, location) {
+    const facts = cloneFacts(value, location);
+    if ("state" in facts) {
+        throw new ProjectionGenerationError(`${location}.state is reserved for verdict records`);
+    }
+    return facts;
+}
+function validateVerdictFacts(value, location) {
+    const facts = cloneFacts(value, location);
+    if (typeof facts.state !== "string" || !VERDICTS.has(facts.state)) {
+        throw new ProjectionGenerationError(`${location}.state is not in the closed verdict vocabulary`);
+    }
+    return facts;
+}
+function parseStoredRow(row) {
+    const seq = typeof row.seq === "bigint" ? Number(row.seq) : row.seq;
+    if (!Number.isSafeInteger(seq) || seq <= 0) {
+        throw new ProjectionGenerationError(`generation row has invalid seq '${String(row.seq)}'`);
+    }
+    if (row.kind !== "launch" && row.kind !== "adoption" && row.kind !== "verdict") {
+        throw new ProjectionGenerationError(`generation row ${seq} has unknown kind '${row.kind}'`);
+    }
+    const executionId = assertExecutionId(row.execution_id);
+    let decoded;
+    try {
+        decoded = JSON.parse(row.payload_json);
+    }
+    catch (error) {
+        throw new ProjectionGenerationError(`generation row ${seq} contains malformed facts JSON`, {
+            cause: error,
+        });
+    }
+    const location = `generation row ${seq} facts`;
+    if (row.kind === "launch") {
+        return {
+            seq,
+            kind: "launch",
+            executionId,
+            facts: validateLaunchFacts(decoded, location),
+        };
+    }
+    if (row.kind === "adoption") {
+        return {
+            seq,
+            kind: "adoption",
+            executionId,
+            facts: validateAdoptionFacts(decoded, location),
+        };
+    }
+    return {
+        seq,
+        kind: "verdict",
+        executionId,
+        facts: validateVerdictFacts(decoded, location),
+    };
+}
+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 ProjectionGenerationError(`generation history is not dense: expected seq ${expectedSeq}, found ${record.seq}`);
+        }
+        if (record.kind === "launch") {
+            if (current && !current.verdict) {
+                throw new ProjectionGenerationError(`generation row ${record.seq} launches before execution '${current.launch.executionId}' is terminal`);
+            }
+            if (launchIds.has(record.executionId)) {
+                throw new ProjectionGenerationError(`generation row ${record.seq} reuses executionId '${record.executionId}'`);
+            }
+            launchIds.add(record.executionId);
+            current = { launch: record };
+            continue;
+        }
+        if (!current) {
+            throw new ProjectionGenerationError(`generation row ${record.seq} appears before any launch`);
+        }
+        if (record.executionId !== current.launch.executionId) {
+            throw new ProjectionGenerationError(`generation row ${record.seq} does not join the current launch`);
+        }
+        if (record.kind === "adoption") {
+            if (current.adoption) {
+                throw new ProjectionGenerationError(`generation row ${record.seq} duplicates adoption`);
+            }
+            if (current.verdict) {
+                throw new ProjectionGenerationError(`generation row ${record.seq} adopts a terminal execution`);
+            }
+            current.adoption = record;
+            continue;
+        }
+        if (current.verdict) {
+            throw new ProjectionGenerationError(`generation row ${record.seq} duplicates verdict`);
+        }
+        current.verdict = record;
+    }
+    return current;
+}
+function readValidatedHistory(database) {
+    const rows = database.prepare(`
+    SELECT seq, kind, execution_id, payload_json
+    FROM generation_records
+    ORDER BY seq
+  `).all();
+    const records = rows.map(parseStoredRow);
+    return { records, current: validateHistory(records) };
+}
+function appendRecord(database, kind, executionId, facts, seq) {
+    const encoded = JSON.stringify(facts);
+    database.prepare(`
+    INSERT INTO generation_records (seq, kind, execution_id, payload_json)
+    VALUES (?, ?, ?, ?)
+  `).run(seq, kind, executionId, encoded);
+    return parseStoredRow({
+        seq,
+        kind,
+        execution_id: executionId,
+        payload_json: encoded,
+    });
+}
+function committed(records) {
+    return { status: "committed", records };
+}
+function rejected(reason, current) {
+    return { status: "rejected", reason, current };
+}
+/** Read every validated generation record in dense seq order. */
+export function readGenerationRecords(heart) {
+    return heart.read((database) => readValidatedHistory(database).records);
+}
+/** Fold the validated history into the current open or terminal generation. */
+export function readCurrentGeneration(heart) {
+    return heart.read((database) => readValidatedHistory(database).current);
+}
+export function launchIfSettled(heart, input) {
+    const executionId = assertExecutionId(input.executionId);
+    const facts = validateLaunchFacts(input.facts, "launch facts");
+    return heart.write((database) => {
+        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(heart, input) {
+    const executionId = assertExecutionId(input.executionId);
+    const facts = validateAdoptionFacts(input.facts, "adoption facts");
+    return heart.write((database) => {
+        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 verdictIfOpen(heart, input) {
+    const executionId = assertExecutionId(input.executionId);
+    if (!VERDICTS.has(input.verdict)) {
+        throw new ProjectionGenerationError(`unknown verdict '${String(input.verdict)}'`);
+    }
+    if (input.facts !== undefined) {
+        const supplied = cloneFacts(input.facts, "verdict facts");
+        if ("state" in supplied) {
+            throw new ProjectionGenerationError("verdict facts.state is reserved");
+        }
+    }
+    const facts = validateVerdictFacts({ ...(input.facts ?? {}), state: input.verdict }, "verdict facts");
+    return heart.write((database) => {
+        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 (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(heart, 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 heart.write((database) => {
+        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);
+        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(heart, 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 ProjectionGenerationError("released runner-lock evidence must not be empty");
+    }
+    const successorFacts = validateLaunchFacts(input.successorFacts, "dead-runner successor launch facts");
+    return heart.write((database) => {
+        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("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(heart, 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 ProjectionGenerationError("handoff completion facts.state is reserved");
+    }
+    const successorFactsBase = validateLaunchFacts(input.successorFacts, "handoff successor launch facts");
+    if (successorFactsBase.tellFence !== undefined) {
+        throw new ProjectionGenerationError("handoff successor launch facts.tellFence must be supplied only through handoff.tellFence");
+    }
+    const tellFence = Object.freeze(validateTellFence([...input.tellFence], "handoff tellFence"));
+    const successorFacts = validateLaunchFacts({ ...successorFactsBase, tellFence: [...tellFence] }, "handoff successor launch facts");
+    return heart.write((database) => {
+        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("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),
+        ]);
+    });
+}