@tangleai/store 0.20.0

package/src/mas-jobs.js

@@ -0,0 +1,194 @@
+/**
+ * MAS durable segments over the suite queue — composition, not a queue.
+ *
+ * Enqueue is the suite's own idempotent caller-supplied-id enqueue with
+ * the derived segment id `<masRunId>:<segment>` and the versioned kind
+ * `mas:<executableRevision>`; re-enqueueing one segment is the suite's
+ * no-op, and an unknown versioned kind is simply never claimed by a
+ * worker that does not register it. The worker is
+ * `store.jobs.createWorker`; the checkpoint store every region hands
+ * `compileDag` is a thin NAMESPACE adaptation over the suite's
+ * `context.checkpoints` — load filters by
+ * `<region>/<branch>/<iteration>/`, save prefixes the lowered node id
+ * and delegates (keeping the suite's lease guard and JSON validation),
+ * a region result is a prefixed delegated save, and only a terminal
+ * outcome for the whole runnable segment calls the suite store's
+ * `complete`, which atomically records the segment result, marks the
+ * job done and prunes that segment's checkpoint rows. It grows no map,
+ * table or serialization of its own.
+ *
+ * Before any checkpoint loads, the handler reads the MAS run and
+ * refuses `TMAS2002` unless the job id, payload, workflow version,
+ * registry snapshot and executable revision all agree — Jaren DAG
+ * resume under different document bytes is undefined, so a mismatch
+ * never reaches a checkpoint.
+ */
+import { masIssue, masJobKindOf, segmentJobIdOf, } from '@tangleai/mas';
+/** Idempotent per segment: the suite keeps one row per caller-supplied id. */
+export async function enqueueMasSegment(db, plan) {
+    const jobs = db.jobs;
+    if (jobs === undefined)
+        throw new TypeError('enqueueMasSegment: the store was opened without { jobs }');
+    const payload = {
+        runId: plan.runId,
+        segment: plan.segment,
+        workflowVersionId: plan.workflowVersionId,
+        registryRevision: plan.registryRevision,
+        executableRevision: plan.executableRevision,
+        resume: plan.resume ?? null,
+    };
+    return jobs.enqueue(masJobKindOf(plan.executableRevision), payload, { id: segmentJobIdOf(plan.runId, plan.segment) });
+}
+/**
+ * The namespace adaptation: one region incarnation's view of the
+ * segment's suite checkpoint rows. Region-level `complete` records a
+ * prefixed result via delegated save and deliberately does NOT mark the
+ * job done.
+ */
+export function namespacedRegionCheckpoints(suite, segmentJobId, namespace) {
+    const prefix = `${namespace}/`;
+    return {
+        async load(runId) {
+            if (runId !== segmentJobId) {
+                throw new Error(`the region checkpoint store is bound to segment '${segmentJobId}', not '${runId}'`);
+            }
+            const stored = await Promise.resolve(suite.load(segmentJobId));
+            if (stored === null)
+                return null;
+            const values = {};
+            for (const [key, value] of Object.entries(stored.values)) {
+                if (key.startsWith(prefix))
+                    values[key.slice(prefix.length)] = value;
+            }
+            return Object.keys(values).length === 0 ? null : { values };
+        },
+        save(runId, nodeId, value) {
+            if (runId !== segmentJobId) {
+                throw new Error(`the region checkpoint store is bound to segment '${segmentJobId}', not '${runId}'`);
+            }
+            return suite.save(segmentJobId, `${prefix}${nodeId}`, value);
+        },
+        complete(runId, result) {
+            if (runId !== segmentJobId) {
+                throw new Error(`the region checkpoint store is bound to segment '${segmentJobId}', not '${runId}'`);
+            }
+            return suite.save(segmentJobId, `${prefix}__region`, result);
+        },
+    };
+}
+/** A refusal the queue records as the job's failure value. */
+export class MasSegmentRefusal extends Error {
+    issue;
+    constructor(issue) {
+        super(`${issue.code} ${issue.path} — ${issue.detail}`);
+        this.issue = issue;
+    }
+}
+/**
+ * The semantic resume reconciler over the published queue — not another
+ * queue. `respondInteraction` accepts exactly one typed response and
+ * moves the run to `resume_pending` with a reserved zero-padded segment
+ * id; the enqueue of that derived id happens OUTSIDE the semantic
+ * transaction (the suite queue cannot be assumed to join it), so this
+ * scan makes the seam idempotent: it enqueues every reserved segment
+ * (the suite's caller-supplied-id no-op absorbs a crash after enqueue)
+ * and CAS-advances `resume_pending -> queued`. The second identical
+ * reconciliation changes zero rows and reports zero; every enqueue,
+ * skip and conflict is a counted value.
+ */
+export async function ensurePendingMasSegments(db, masStore) {
+    const counts = { examined: 0, enqueued: 0, queued: 0, skipped: 0 };
+    const runs = await masStore.listResumePendingRuns();
+    for (const run of runs) {
+        counts.examined += 1;
+        const trace = await masStore.readTrace(run.id);
+        const responded = trace?.interactions.find((interaction) => interaction.status === 'responded' && interaction.resumeSegment !== null);
+        if (responded === undefined || responded.resumeSegment === null) {
+            counts.skipped += 1;
+            continue;
+        }
+        await enqueueMasSegment(db, {
+            runId: run.id,
+            segment: responded.resumeSegment,
+            workflowVersionId: run.workflowVersionId,
+            registryRevision: run.registryRevision,
+            executableRevision: run.executableRevision,
+            resume: { interaction: responded.id, responseKey: responded.responseKey },
+        });
+        counts.enqueued += 1;
+        const advanced = await masStore.transitionRun(run.id, { kind: 'queue-segment' });
+        if (advanced.ok)
+            counts.queued += 1;
+        else
+            counts.skipped += 1;
+    }
+    return counts;
+}
+/**
+ * The versioned segment handlers a worker registers — exported so the
+ * crash matrix can drive one claim at a time deterministically through
+ * `store.jobs.claim` with an injected clock, without a polling loop.
+ */
+export function createMasSegmentHandlers(masStore, options) {
+    if (options.executableRevisions.length === 0)
+        throw new TypeError('createMasSegmentHandlers: at least one executable revision is required');
+    const owner = options.owner ?? 'mas-worker';
+    const handlers = {};
+    for (const executableRevision of options.executableRevisions) {
+        handlers[masJobKindOf(executableRevision)] = async (rawPayload, context) => {
+            const payload = rawPayload;
+            const segmentJobId = segmentJobIdOf(payload.runId, payload.segment);
+            if (context.job.id !== segmentJobId) {
+                throw new MasSegmentRefusal(masIssue('TMAS2002', '/id', `the job id '${context.job.id}' does not derive from its payload ('${segmentJobId}')`));
+            }
+            const run = await masStore.getRun(payload.runId);
+            if (run === undefined) {
+                throw new MasSegmentRefusal(masIssue('TMAS2002', '/runId', `run '${payload.runId}' does not exist`));
+            }
+            if (run.workflowVersionId !== payload.workflowVersionId
+                || run.registryRevision !== payload.registryRevision
+                || run.executableRevision !== payload.executableRevision
+                || run.executableRevision !== executableRevision) {
+                throw new MasSegmentRefusal(masIssue('TMAS2002', '/executableRevision', 'the run identities do not agree with the queued segment; resuming under different document bytes is undefined and refused before any checkpoint loads'));
+            }
+            const suite = context.checkpoints;
+            // A committed terminal outcome whose job completion was lost: close
+            // the segment without executing a region.
+            if (run.segment === payload.segment
+                && (run.status === 'completed' || run.status === 'failed' || run.status === 'waiting_for_input' || run.status === 'resume_pending')) {
+                await Promise.resolve(suite.complete(segmentJobId, { status: run.status }));
+                return { status: run.status, reclaimed: true };
+            }
+            const claimed = await masStore.claimRunSegment(payload.runId, owner);
+            if (!claimed.ok)
+                throw new MasSegmentRefusal(claimed.issue);
+            let completed = false;
+            await options.execute({
+                run: claimed.value,
+                payload,
+                segmentJobId,
+                claimSeq: claimed.value.claim.seq,
+                signal: context.signal,
+                checkpointsFor: (namespace) => namespacedRegionCheckpoints(suite, segmentJobId, namespace),
+                completeSegment: async (result) => {
+                    await Promise.resolve(suite.complete(segmentJobId, result));
+                    completed = true;
+                },
+            });
+            if (!completed) {
+                throw new MasSegmentRefusal(masIssue('TMAS2003', '/segment', 'the segment executor returned without a terminal outcome; a runnable segment ends completed, failed or durably waiting'));
+            }
+            return null;
+        };
+    }
+    return handlers;
+}
+export function createMasSegmentWorker(db, masStore, options) {
+    const jobs = db.jobs;
+    if (jobs === undefined)
+        throw new TypeError('createMasSegmentWorker: the store was opened without { jobs }');
+    const owner = options.owner ?? 'mas-worker';
+    const handlers = createMasSegmentHandlers(masStore, { executableRevisions: options.executableRevisions, execute: options.execute, owner });
+    const { executableRevisions: _revisions, execute: _execute, ...workerOptions } = options;
+    return jobs.createWorker({ ...workerOptions, handlers, owner });
+}

package/src/mas-store.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The MAS store adapter — one transaction per semantic commit.
+ *
+ * Implements `@tangleai/mas`'s `MasStore` over the Jaren database:
+ * immutable content-addressed puts (a same-byte put changes nothing, a
+ * mutated value under a stale address refuses `TMAS2001`), workflow and
+ * template activation as compare-and-swap head rows, run records with a
+ * worker claim epoch (`TMAS2005` for a zombie's stale commit), and node
+ * completion as ONE transaction writing the terminal attempt, outbound
+ * messages, next state revision, budget snapshot and artifact rows —
+ * all or nothing, exactly D6. Every record validates against the
+ * generated runtime contracts before it is written; persistence never
+ * invents a shape. Semantic idempotency: `beginNodeAttempt` returns the
+ * stored completion for a key it has already committed and refuses an
+ * uncertain attempt rather than repeating external work.
+ */
+import { type MasStore } from '@tangleai/mas';
+import type { TangleDb } from './db.ts';
+export interface MasStoreOptions {
+    /** Injected clock; deterministic ticks under conformance. */
+    now?: () => string;
+    /**
+     * Test-only probe invoked between the writes of one completion
+     * transaction; a throwing probe proves rollback leaves nothing.
+     */
+    applyProbe?: (step: string) => void;
+}
+export declare function createMasStore(db: TangleDb, options?: MasStoreOptions): MasStore;