@latysh-development/monolith 0.0.0-stage → 0.1.0-alpha.1

package/dist/durable/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Durable State — a domain-neutral, crash-safe execution record for long-running
+ * agentic tasks. See docs/adr/ADR-017-durable-execution-state.md.
+ */
+export { DurableTasks, newOwnerId, parseToken } from './runtime.js';
+export type { DurableTasksOptions, Fence, CreateTaskInput, TaskSummary, DeliveryResult, EffectOptions, EffectOutcome, ResumePacket, VerifyReport, RetentionReport, } from './runtime.js';
+export { FsEventStore, AppendOutcomeUnknownError, MAX_SEGMENT_BYTES } from './fs-store.js';
+export type { FsStoreOptions, FsStoreTarget } from './fs-store.js';
+export { MemoryEventStore } from './memory-store.js';
+export { assessTask, diffStates, leaseIsLive } from './assess.js';
+export type { Assessment, AssessOptions, ResumeMode, Reason, ReasonCode, AssumptionChange, ResultToConsume, StateChange } from './assess.js';
+export { planRetention } from './retention.js';
+export type { RetentionPolicy, RetentionDecision, RetentionAction, InterruptedWork } from './retention.js';
+export { foldEvents, foldUntil, applyEvent } from './projection.js';
+export { MAX_EVENT_BYTES } from './log.js';
+export { toJson, canonicalize, fingerprintOf } from './canonical.js';
+export type { Json } from './canonical.js';
+export * from './errors.js';
+export type { EventStore, TaskEvent, EventType, TaskState, TaskStatus, Tombstone, LogRead, Evidence, Criticality, PlanStepState, AwaitState, EffectState, AssumptionState, StoreDiagnostic, AppendOutcome, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/durable/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/durable/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AACpE,YAAY,EACV,mBAAmB,EACnB,KAAK,EACL,eAAe,EACf,WAAW,EACX,cAAc,EACd,aAAa,EACb,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,eAAe,GAChB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,YAAY,EAAE,yBAAyB,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAC3F,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnE,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAClE,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,gBAAgB,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC7I,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,YAAY,EAAE,eAAe,EAAE,iBAAiB,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAC3G,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AACpE,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAC3C,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACrE,YAAY,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAC3C,cAAc,aAAa,CAAC;AAC5B,YAAY,EACV,UAAU,EACV,SAAS,EACT,SAAS,EACT,SAAS,EACT,UAAU,EACV,SAAS,EACT,OAAO,EACP,QAAQ,EACR,WAAW,EACX,aAAa,EACb,UAAU,EACV,WAAW,EACX,eAAe,EACf,eAAe,EACf,aAAa,GACd,MAAM,YAAY,CAAC"}

package/dist/durable/index.js

@@ -0,0 +1,13 @@
+/**
+ * Durable State — a domain-neutral, crash-safe execution record for long-running
+ * agentic tasks. See docs/adr/ADR-017-durable-execution-state.md.
+ */
+export { DurableTasks, newOwnerId, parseToken } from './runtime.js';
+export { FsEventStore, AppendOutcomeUnknownError, MAX_SEGMENT_BYTES } from './fs-store.js';
+export { MemoryEventStore } from './memory-store.js';
+export { assessTask, diffStates, leaseIsLive } from './assess.js';
+export { planRetention } from './retention.js';
+export { foldEvents, foldUntil, applyEvent } from './projection.js';
+export { MAX_EVENT_BYTES } from './log.js';
+export { toJson, canonicalize, fingerprintOf } from './canonical.js';
+export * from './errors.js';

package/dist/durable/log.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Event envelope: stamping, hashing, strict parsing, chain verification.
+ *
+ * Each event commits to its predecessor (`prev`) and to its own content
+ * (`hash`), and the task id is part of the hashed content. A flipped bit, a
+ * deleted or reordered event, or an event copied from another task is
+ * therefore detected on read instead of being folded into the state.
+ */
+import { GENESIS_HASH, type EventDraft, type TaskEvent } from './types.js';
+/** Protective ceiling for one event (payloads are application data). */
+export declare const MAX_EVENT_BYTES: number;
+export declare const ID_PATTERN: RegExp;
+export declare function assertId(label: string, value: unknown): asserts value is string;
+export declare function assertNonEmpty(label: string, value: unknown, max: number): asserts value is string;
+type Hashable = Omit<TaskEvent, 'hash'>;
+export declare function computeHash(e: Hashable): string;
+export declare function stampEvent(taskId: string, seq: number, at: string, prev: string, draft: EventDraft): TaskEvent;
+/** One canonical line; byte-identical wherever it is stored (loose file or segment line). */
+export declare function serializeEvent(e: TaskEvent): string;
+/**
+ * Parses and verifies one serialized event: envelope shape, known format and
+ * type (an unknown one is `LogUnsupportedError`, never skipped), payload shape
+ * and the event's own hash. `expectedTaskId` binds it to the task being read.
+ */
+export declare function parseEvent(raw: string, expectedTaskId: string, hintSeq: number | null): TaskEvent;
+/**
+ * Verifies that `events` continue a chain whose last event had `expectedPrev`
+ * and seq `lastSeq`: contiguous seq, `prev` links, nothing after the first
+ * violation is trusted. Throws `LogCorruptError`.
+ */
+export declare function verifyChain(taskId: string, events: readonly TaskEvent[], lastSeq: number, expectedPrev: string): void;
+export { GENESIS_HASH };
+//# sourceMappingURL=log.d.ts.map

package/dist/durable/log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.d.ts","sourceRoot":"","sources":["../../src/durable/log.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,EAGL,YAAY,EACZ,KAAK,UAAU,EAEf,KAAK,SAAS,EACf,MAAM,YAAY,CAAC;AAEpB,wEAAwE;AACxE,eAAO,MAAM,eAAe,QAAa,CAAC;AAE1C,eAAO,MAAM,UAAU,QAAqC,CAAC;AAE7D,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,KAAK,IAAI,MAAM,CAI/E;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,IAAI,MAAM,CAGlG;AAED,KAAK,QAAQ,GAAG,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;AAExC,wBAAgB,WAAW,CAAC,CAAC,EAAE,QAAQ,GAAG,MAAM,CAE/C;AAED,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,SAAS,CAc9G;AAED,6FAA6F;AAC7F,wBAAgB,cAAc,CAAC,CAAC,EAAE,SAAS,GAAG,MAAM,CAMnD;AAoDD;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAiCjG;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,SAAS,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI,CASrH;AAED,OAAO,EAAE,YAAY,EAAE,CAAC"}

package/dist/durable/log.js

@@ -0,0 +1,157 @@
+/**
+ * Event envelope: stamping, hashing, strict parsing, chain verification.
+ *
+ * Each event commits to its predecessor (`prev`) and to its own content
+ * (`hash`), and the task id is part of the hashed content. A flipped bit, a
+ * deleted or reordered event, or an event copied from another task is
+ * therefore detected on read instead of being folded into the state.
+ */
+import { canonicalize, sha256Hex, toJson } from './canonical.js';
+import { LogCorruptError, LogUnsupportedError, ValidationError } from './errors.js';
+import { EVENT_FORMAT_VERSION, EVENT_TYPES, GENESIS_HASH, } from './types.js';
+/** Protective ceiling for one event (payloads are application data). */
+export const MAX_EVENT_BYTES = 256 * 1024;
+export const ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+export function assertId(label, value) {
+    if (typeof value !== 'string' || !ID_PATTERN.test(value)) {
+        throw new ValidationError(`${label} must match ${ID_PATTERN} (letters, digits, "_" and "-", at most 64).`);
+    }
+}
+export function assertNonEmpty(label, value, max) {
+    if (typeof value !== 'string' || value.trim().length === 0)
+        throw new ValidationError(`${label} must be a non-empty string.`);
+    if (value.length > max)
+        throw new ValidationError(`${label} is longer than ${max} characters.`);
+}
+export function computeHash(e) {
+    return sha256Hex(canonicalize(e));
+}
+export function stampEvent(taskId, seq, at, prev, draft) {
+    const body = {
+        v: EVENT_FORMAT_VERSION,
+        taskId,
+        seq,
+        at,
+        type: draft.type,
+        actor: draft.actor,
+        data: toJson(draft.data, `${draft.type}.data`),
+        prev,
+    };
+    const event = { ...body, hash: computeHash(body) };
+    serializeEvent(event); // enforces MAX_EVENT_BYTES before anything touches storage
+    return event;
+}
+/** One canonical line; byte-identical wherever it is stored (loose file or segment line). */
+export function serializeEvent(e) {
+    const line = canonicalize(e);
+    if (Buffer.byteLength(line, 'utf8') > MAX_EVENT_BYTES) {
+        throw new ValidationError(`event ${e.type} is larger than ${MAX_EVENT_BYTES} bytes; store large payloads outside the log and reference them.`);
+    }
+    return line;
+}
+const isStr = (v) => typeof v === 'string';
+const isStrOrNull = (v) => v === null || typeof v === 'string';
+const isInt = (v) => typeof v === 'number' && Number.isInteger(v) && v >= 0;
+const isBool = (v) => typeof v === 'boolean';
+const isAny = (v) => v !== undefined;
+const isStrArr = (v) => Array.isArray(v) && v.every(isStr);
+const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const isLabels = (v) => isObj(v) && Object.values(v).every(isStr);
+const isEvidence = (v) => Array.isArray(v) && v.every((e) => isObj(e) && isStr(e.ref) && isStrOrNull(e.note));
+const isSteps = (v) => Array.isArray(v) && v.every((s) => isObj(s) && isStr(s.id) && isStr(s.title) && isStrArr(s.dependsOn));
+const isCrit = (v) => v === 'blocking' || v === 'advisory';
+const isIntOrNull = (v) => v === null || isInt(v);
+const SCHEMA = {
+    'task.created': { kind: isStr, goal: isStr, input: isAny, parentTaskId: isStrOrNull, dependsOn: isStrArr, labels: isLabels },
+    'run.claimed': { owner: isStr, epoch: isInt, leaseUntil: isStr, takeover: isBool },
+    'run.heartbeat': { owner: isStr, epoch: isInt, leaseUntil: isStr },
+    'run.released': { owner: isStr, epoch: isInt },
+    'plan.declared': { steps: isSteps, reason: isStrOrNull },
+    'plan.step_done': { stepId: isStr, result: isAny },
+    'plan.step_skipped': { stepId: isStr, reason: isStr },
+    'decision.recorded': { id: isStr, summary: isStr, rationale: isStrOrNull, basedOn: isStrArr },
+    'assumption.recorded': { key: isStr, statement: isStr, criticality: isCrit, fingerprint: isStr, value: isAny, evidence: isEvidence },
+    'assumption.retracted': { key: isStr, reason: isStr },
+    'fact.observed': { key: isStr, fingerprint: isStr, value: isAny, source: isStrOrNull },
+    'effect.intended': { key: isStr, description: isStr, params: isAny, epoch: isIntOrNull },
+    'effect.completed': { key: isStr, result: isAny },
+    'effect.failed': { key: isStr, error: isStr, retryable: isBool },
+    'await.registered': {
+        awaitId: isStr, token: isStr, purpose: isStr, stepId: isStrOrNull, request: isAny, deadlineAt: isStrOrNull, basisSeq: isInt,
+    },
+    'await.resolved': { awaitId: isStr, idempotencyKey: isStr, payload: isAny, source: isStrOrNull, late: isBool },
+    'await.delivery_rejected': { awaitId: isStr, idempotencyKey: isStr, reason: (v) => v === 'already-resolved', payload: isAny },
+    'await.expired': { awaitId: isStr },
+    'task.completed': { result: isAny },
+    'task.failed': { error: isStr, detail: isAny },
+    'task.cancelled': { reason: isStr },
+};
+const OPTIONAL_FIELDS = {
+    'effect.failed': { uncertain: isBool },
+};
+/**
+ * Parses and verifies one serialized event: envelope shape, known format and
+ * type (an unknown one is `LogUnsupportedError`, never skipped), payload shape
+ * and the event's own hash. `expectedTaskId` binds it to the task being read.
+ */
+export function parseEvent(raw, expectedTaskId, hintSeq) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new LogCorruptError(expectedTaskId, hintSeq, 'event is not valid JSON');
+    }
+    if (!isObj(parsed))
+        throw new LogCorruptError(expectedTaskId, hintSeq, 'event is not an object');
+    const seq = parsed.seq;
+    if (!isInt(seq) || seq < 1)
+        throw new LogCorruptError(expectedTaskId, hintSeq, 'event has no valid seq');
+    const s = seq;
+    if (parsed.v !== EVENT_FORMAT_VERSION)
+        throw new LogUnsupportedError(expectedTaskId, s, `event format version`);
+    const type = parsed.type;
+    if (typeof type !== 'string' || !EVENT_TYPES.includes(type)) {
+        throw new LogUnsupportedError(expectedTaskId, s, 'event type');
+    }
+    if (parsed.taskId !== expectedTaskId)
+        throw new LogCorruptError(expectedTaskId, s, 'event belongs to another task');
+    if (!isStr(parsed.at) || !isStrOrNull(parsed.actor) || !isStr(parsed.prev) || !isStr(parsed.hash)) {
+        throw new LogCorruptError(expectedTaskId, s, 'malformed envelope fields');
+    }
+    const data = parsed.data;
+    const schema = SCHEMA[type];
+    if (!isObj(data))
+        throw new LogCorruptError(expectedTaskId, s, 'event data is not an object');
+    for (const [field, check] of Object.entries(schema)) {
+        if (!(field in data) || !check(data[field]))
+            throw new LogCorruptError(expectedTaskId, s, `payload field "${field}" of ${type} is invalid`);
+    }
+    // Fields added after format v1 was fixed: may be absent (older logs), must be well-formed when present.
+    for (const [field, check] of Object.entries(OPTIONAL_FIELDS[type] ?? {})) {
+        if (field in data && !check(data[field]))
+            throw new LogCorruptError(expectedTaskId, s, `payload field "${field}" of ${type} is invalid`);
+    }
+    const { hash, ...rest } = parsed;
+    if (computeHash(rest) !== hash)
+        throw new LogCorruptError(expectedTaskId, s, 'content hash mismatch');
+    return parsed;
+}
+/**
+ * Verifies that `events` continue a chain whose last event had `expectedPrev`
+ * and seq `lastSeq`: contiguous seq, `prev` links, nothing after the first
+ * violation is trusted. Throws `LogCorruptError`.
+ */
+export function verifyChain(taskId, events, lastSeq, expectedPrev) {
+    let seq = lastSeq;
+    let prev = expectedPrev;
+    for (const e of events) {
+        if (e.seq !== seq + 1)
+            throw new LogCorruptError(taskId, e.seq, `sequence gap (expected ${seq + 1})`);
+        if (e.prev !== prev)
+            throw new LogCorruptError(taskId, e.seq, 'prev hash does not match the preceding event');
+        seq = e.seq;
+        prev = e.hash;
+    }
+}
+export { GENESIS_HASH };

package/dist/durable/memory-store.d.ts

@@ -0,0 +1,51 @@
+/**
+ * In-memory `EventStore`. For tests of application logic built on Durable
+ * State and for embedding where durability is not wanted. It implements the
+ * same contract as the filesystem store (the shared conformance suite runs
+ * against both), including the prune decision register (ADR-019) and the
+ * canonical-input rules of compaction (Design A, section 40), but nothing
+ * survives the process. There is no version marker: it belongs to the
+ * filesystem layout.
+ */
+import type { AppendOutcome, CompactionResult, DecisionBy, EventStore, LogRead, PruneOutcome, PruneState, TaskEvent, Tombstone } from './types.js';
+export declare class MemoryEventStore implements EventStore {
+    private readonly tasks;
+    private readonly maxAttempts;
+    constructor();
+    private derive;
+    private refusal;
+    pruneState(taskId: string): Promise<PruneState>;
+    /** F-1: the log is that of a finished task whose head is the one the tombstone names. No `await` between check and write. */
+    private assertPrunable;
+    preparePrune(tombstone: Tombstone): Promise<{
+        attempt: number;
+        created: boolean;
+    }>;
+    decidePrune(taskId: string, attempt: number, outcome: PruneOutcome, tombstone?: Tombstone, by?: DecisionBy): Promise<PruneOutcome>;
+    markPruned(tombstone: Tombstone): Promise<void>;
+    withdrawTombstone(tombstone: Tombstone): Promise<void>;
+    prune(tombstone: Tombstone, opts?: {
+        requireCommit?: boolean;
+    }): Promise<{
+        removedFiles: number;
+    }>;
+    /** G2 (section 24.2): the register is asked AFTER a write became visible; nothing visible is ever taken back. */
+    private settle;
+    readLog(taskId: string, opts?: {
+        afterSeq?: number;
+        rawEvents?: boolean;
+    }): Promise<LogRead>;
+    append(event: TaskEvent): Promise<AppendOutcome>;
+    listTaskIds(): Promise<string[]>;
+    /**
+     * Nothing to pack in memory. The input is still checked against the canonical log exactly as the filesystem store checks
+     * it (CC-1, CC-2): every event must equal the stored one byte for byte, and a slot that has no stored event is refused.
+     */
+    compact(taskId: string, throughSeq: number, events: TaskEvent[]): Promise<CompactionResult>;
+    pinReference(parentId: string, childId: string, at: string): Promise<'pinned' | 'parent-pruned' | 'parent-missing'>;
+    listReferences(parentId: string): Promise<Array<{
+        childId: string;
+        at: string;
+    }>>;
+}
+//# sourceMappingURL=memory-store.d.ts.map

package/dist/durable/memory-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-store.d.ts","sourceRoot":"","sources":["../../src/durable/memory-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAeH,OAAO,KAAK,EACV,aAAa,EACb,gBAAgB,EAChB,UAAU,EACV,UAAU,EACV,OAAO,EACP,YAAY,EACZ,UAAU,EAEV,SAAS,EACT,SAAS,EACV,MAAM,YAAY,CAAC;AAoBpB,qBAAa,gBAAiB,YAAW,UAAU;IACjD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA4B;IAClD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;;IAQrC,OAAO,CAAC,MAAM;IAoBd,OAAO,CAAC,OAAO;IAeT,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAIrD,6HAA6H;IAC7H,OAAO,CAAC,cAAc;IAKhB,YAAY,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;IAclF,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,SAAS,CAAC,EAAE,SAAS,EAAE,EAAE,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,YAAY,CAAC;IAelI,UAAU,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAS/C,iBAAiB,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAWtD,KAAK,CAAC,SAAS,EAAE,SAAS,EAAE,IAAI,GAAE;QAAE,aAAa,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,OAAO,CAAC;QAAE,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC;IAiC5G,iHAAiH;YACnG,MAAM;IAgBd,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAoBhG,MAAM,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC;IA4BhD,WAAW,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAItC;;;OAGG;IACG,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAwB3F,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,eAAe,GAAG,gBAAgB,CAAC;IAanH,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAIxF"}

package/dist/durable/memory-store.js

@@ -0,0 +1,302 @@
+/**
+ * In-memory `EventStore`. For tests of application logic built on Durable
+ * State and for embedding where durability is not wanted. It implements the
+ * same contract as the filesystem store (the shared conformance suite runs
+ * against both), including the prune decision register (ADR-019) and the
+ * canonical-input rules of compaction (Design A, section 40), but nothing
+ * survives the process. There is no version marker: it belongs to the
+ * filesystem layout.
+ */
+import { LogCorruptError, PruneAttemptLimitError, PruneDecisionCorruptError, RetentionRefusedError, StoreIoError, TaskPrunedError, TombstoneCommittedError, } from './errors.js';
+import { tombstoneProblem } from './prune-check.js';
+import { takeMemorySeams } from './seams.js';
+import { serializeEvent } from './log.js';
+import { MAX_PRUNE_ATTEMPTS } from './register.js';
+const MAX_WRITE_RESOLVE = 3;
+export class MemoryEventStore {
+    tasks = new Map();
+    maxAttempts;
+    constructor() {
+        this.maxAttempts = takeMemorySeams().maxPruneAttempts ?? MAX_PRUNE_ATTEMPTS;
+    }
+    // ----- the register ---------------------------------------------------------------------------------------------
+    derive(taskId) {
+        const entry = this.tasks.get(taskId);
+        if (!entry)
+            return { kind: 'missing' };
+        const commitAt = entry.attempts.findIndex((a) => a.decision?.outcome === 'commit');
+        if (commitAt >= 0) {
+            return {
+                kind: 'committed',
+                attempt: commitAt + 1,
+                tombstone: structuredClone(entry.attempts[commitAt].tombstone),
+                residue: entry.events.length + entry.refs.size,
+                durability: 'NOT_GUARANTEED',
+            };
+        }
+        const m = entry.attempts.length;
+        if (m === 0)
+            return { kind: 'live', attempt: 0 };
+        const last = entry.attempts[m - 1];
+        if (last.decision)
+            return { kind: 'live', attempt: m };
+        return { kind: 'preparing', attempt: m, tombstone: structuredClone(last.tombstone) };
+    }
+    refusal(taskId, st) {
+        switch (st.kind) {
+            case 'corrupt':
+                return new PruneDecisionCorruptError(taskId, 'register', st.file ?? null, st.attempt ?? null);
+            case 'legacy':
+                return new PruneDecisionCorruptError(taskId, 'legacy-tombstone-unmigrated');
+            case 'missing':
+                return new PruneDecisionCorruptError(taskId, 'task-dir-missing');
+            case 'unreadable':
+                return new StoreIoError(`the prune state of task "${taskId}" cannot be read now.`);
+            default:
+                return new TaskPrunedError(taskId);
+        }
+    }
+    async pruneState(taskId) {
+        return this.derive(taskId);
+    }
+    /** F-1: the log is that of a finished task whose head is the one the tombstone names. No `await` between check and write. */
+    assertPrunable(entry, tombstone) {
+        const problem = tombstoneProblem(tombstone.taskId, entry.events, tombstone);
+        if (problem !== null)
+            throw new RetentionRefusedError(tombstone.taskId, problem);
+    }
+    async preparePrune(tombstone) {
+        const taskId = tombstone.taskId;
+        const st = this.derive(taskId);
+        if (st.kind === 'missing')
+            throw new LogCorruptError(taskId, null, 'cannot prune an unknown task');
+        if (st.kind === 'preparing')
+            return { attempt: st.attempt, created: false };
+        if (st.kind !== 'live')
+            throw this.refusal(taskId, st);
+        const entry = this.tasks.get(taskId);
+        const n = entry.attempts.length + 1;
+        if (n > this.maxAttempts)
+            throw new PruneAttemptLimitError(taskId, this.maxAttempts);
+        this.assertPrunable(entry, tombstone); // synchronous up to the push: nothing can append in between
+        entry.attempts.push({ tombstone: structuredClone(tombstone), decision: null });
+        return { attempt: n, created: true };
+    }
+    async decidePrune(taskId, attempt, outcome, tombstone, by) {
+        const entry = this.tasks.get(taskId);
+        const a = entry?.attempts[attempt - 1];
+        if (!entry || !a)
+            throw new LogCorruptError(taskId, null, `there is no prepare for prune attempt ${attempt}; a decision needs one`);
+        if (outcome !== 'commit' && outcome !== 'abort')
+            throw new LogCorruptError(taskId, null, 'a prune decision is either "commit" or "abort"');
+        if (outcome === 'commit' && (!tombstone || JSON.stringify(sortKeys(tombstone)) !== JSON.stringify(sortKeys(a.tombstone)))) {
+            throw new LogCorruptError(taskId, null, 'a commit must carry the tombstone of its attempt');
+        }
+        if (!a.decision && outcome === 'commit')
+            this.assertPrunable(entry, a.tombstone);
+        if (!a.decision)
+            a.decision = outcome === 'abort' ? { outcome, ...(by ? { by } : {}) } : { outcome };
+        return a.decision.outcome;
+    }
+    // ----- adapters of the pre-register operations ------------------------------------------------------------------
+    async markPruned(tombstone) {
+        const st = this.derive(tombstone.taskId);
+        if (st.kind === 'preparing' || st.kind === 'committed') {
+            if (st.tombstone.headHash !== tombstone.headHash)
+                throw new LogCorruptError(tombstone.taskId, null, 'a different tombstone already exists');
+            return;
+        }
+        await this.preparePrune(tombstone);
+    }
+    async withdrawTombstone(tombstone) {
+        const taskId = tombstone.taskId;
+        const st = this.derive(taskId);
+        if (st.kind === 'live' || st.kind === 'missing')
+            return;
+        if (st.kind === 'committed')
+            throw new TombstoneCommittedError(taskId, 'the prune is committed; the tombstone cannot be withdrawn');
+        if (st.kind !== 'preparing')
+            throw this.refusal(taskId, st);
+        if (st.tombstone.headHash !== tombstone.headHash)
+            throw new LogCorruptError(taskId, null, 'a different tombstone exists; refusing to withdraw it');
+        const w = await this.decidePrune(taskId, st.attempt, 'abort', undefined, 'creator');
+        if (w === 'commit')
+            throw new TombstoneCommittedError(taskId, 'the prune is committed; the tombstone cannot be withdrawn');
+    }
+    async prune(tombstone, opts = {}) {
+        const taskId = tombstone.taskId;
+        let st = this.derive(taskId);
+        if (st.kind === 'missing')
+            throw new LogCorruptError(taskId, null, 'cannot prune an unknown task');
+        if (st.kind === 'live' || st.kind === 'preparing') {
+            if (opts.requireCommit)
+                throw new RetentionRefusedError(taskId, 'no prune decision has been committed for it');
+            if (st.kind === 'live' && (st.attempt ?? 0) > 0)
+                throw new RetentionRefusedError(taskId, 'its last prune attempt was aborted by a task that needs it');
+            if (st.kind === 'preparing' && st.tombstone.headHash !== tombstone.headHash)
+                throw new LogCorruptError(taskId, null, 'a different tombstone already exists');
+            // `st` was read before `preparePrune` re-derives: only the attempt seen here (or the first) may be committed.
+            const expected = st.kind === 'preparing' ? st.attempt : 1;
+            const opened = await this.preparePrune(tombstone);
+            const attempt = opened.attempt;
+            if (attempt !== expected) {
+                if (opened.created)
+                    await this.decidePrune(taskId, attempt, 'abort', undefined, 'pruner');
+                throw new RetentionRefusedError(taskId, 'its prune attempt was aborted by a task that needs it');
+            }
+            const entry = this.tasks.get(taskId);
+            const tomb = entry.attempts[attempt - 1].tombstone;
+            if (tomb.headHash !== tombstone.headHash)
+                throw new LogCorruptError(taskId, null, 'a different tombstone already exists');
+            const w = await this.decidePrune(taskId, attempt, 'commit', tomb, 'pruner');
+            if (w === 'abort')
+                throw new RetentionRefusedError(taskId, 'the prune attempt was aborted by a task that needs it');
+            st = this.derive(taskId);
+        }
+        if (st.kind !== 'committed')
+            throw this.refusal(taskId, st);
+        if (st.tombstone.headHash !== tombstone.headHash)
+            throw new LogCorruptError(taskId, null, 'a different tombstone already exists');
+        const entry = this.tasks.get(taskId);
+        entry.tombstone = structuredClone(st.tombstone);
+        const removed = entry.events.length;
+        entry.events = [];
+        entry.refs.clear();
+        return { removedFiles: removed };
+    }
+    /** G2 (section 24.2): the register is asked AFTER a write became visible; nothing visible is ever taken back. */
+    async settle(taskId, by) {
+        for (let i = 0; i < MAX_WRITE_RESOLVE; i++) {
+            const st = this.derive(taskId);
+            if (st.kind === 'live')
+                return 'CONFIRMED';
+            if (st.kind === 'committed')
+                return 'PRUNED';
+            if (st.kind === 'preparing') {
+                await this.decidePrune(taskId, st.attempt, 'abort', undefined, by);
+                continue;
+            }
+            return st.kind === 'corrupt' || st.kind === 'legacy' ? st : 'UNKNOWN';
+        }
+        return 'UNKNOWN';
+    }
+    // ----- EventStore -----------------------------------------------------------------------------------------------
+    async readLog(taskId, opts = {}) {
+        const entry = this.tasks.get(taskId);
+        if (!entry)
+            return { exists: false, tombstone: null, events: [], compactedThrough: 0, diagnostics: [] };
+        const st = this.derive(taskId);
+        const hidden = st.kind === 'committed' || (st.kind === 'preparing' && !opts.rawEvents);
+        if (hidden) {
+            const diagnostics = entry.events.length > 0 ? [{ code: 'PRUNE_INCOMPLETE', taskId, name: 'events' }] : [];
+            return { exists: true, tombstone: structuredClone(st.tombstone), prune: st, events: [], compactedThrough: 0, diagnostics };
+        }
+        const after = opts.afterSeq ?? 0;
+        return {
+            exists: true,
+            tombstone: null,
+            ...(st.kind === 'live' ? {} : { prune: st }),
+            events: structuredClone(entry.events.filter((e) => e.seq > after)),
+            compactedThrough: 0,
+            diagnostics: [],
+        };
+    }
+    async append(event) {
+        let entry = this.tasks.get(event.taskId);
+        // AV: a task is created by its first event only; a later event never creates one (Design A, section 31.1).
+        if (!entry && event.seq > 1)
+            throw new PruneDecisionCorruptError(event.taskId, 'task-dir-missing');
+        if (entry) {
+            const st = this.derive(event.taskId);
+            if (st.kind === 'committed')
+                throw new TaskPrunedError(event.taskId);
+            if (event.seq > entry.events.length + 1)
+                throw new LogCorruptError(event.taskId, event.seq, 'predecessor event is missing; refusing to publish past a hole');
+        }
+        if (!entry) {
+            entry = { events: [], attempts: [], tombstone: null, refs: new Map() };
+            this.tasks.set(event.taskId, entry);
+        }
+        let created = false;
+        if (event.seq <= entry.events.length) {
+            // The slot is taken: the same event again is adopted, a different one is a conflict (canonical identity).
+            if (serializeEvent(entry.events[event.seq - 1]) !== serializeEvent(event))
+                return 'conflict';
+        }
+        else {
+            entry.events.push(structuredClone(event));
+            created = true;
+        }
+        const g2 = await this.settle(event.taskId, 'append');
+        if (g2 === 'CONFIRMED')
+            return created ? 'appended' : 'adopted';
+        if (g2 === 'PRUNED')
+            throw new TaskPrunedError(event.taskId);
+        if (g2 === 'UNKNOWN')
+            throw new StoreIoError(`the prune state of task "${event.taskId}" could not be settled after the append.`);
+        throw this.refusal(event.taskId, g2);
+    }
+    async listTaskIds() {
+        return [...this.tasks.keys()].sort();
+    }
+    /**
+     * Nothing to pack in memory. The input is still checked against the canonical log exactly as the filesystem store checks
+     * it (CC-1, CC-2): every event must equal the stored one byte for byte, and a slot that has no stored event is refused.
+     */
+    async compact(taskId, throughSeq, events) {
+        const entry = this.tasks.get(taskId);
+        // The same order as the filesystem store: K0 (pruned), nothing to pack, the shape of the input, the task must exist
+        // (compaction never creates one), then every slot against the canonical event (K2).
+        if (entry && this.derive(taskId).kind === 'committed')
+            throw new TaskPrunedError(taskId);
+        if (events.length === 0)
+            return { segment: null, packedEvents: 0, removedFiles: 0 };
+        const first = events[0];
+        const last = events[events.length - 1];
+        if (last.seq !== throughSeq || last.seq - first.seq + 1 !== events.length || events.some((e, i) => e.seq !== first.seq + i)) {
+            throw new LogCorruptError(taskId, first.seq, 'compaction input is not a contiguous range ending at throughSeq');
+        }
+        if (!entry)
+            throw new PruneDecisionCorruptError(taskId, 'task-dir-missing');
+        for (const e of events) {
+            const stored = entry.events[e.seq - 1];
+            if (!stored)
+                throw new LogCorruptError(taskId, e.seq, 'compaction input slot has no canonical event');
+            if (serializeEvent(stored) !== serializeEvent(e))
+                throw new LogCorruptError(taskId, e.seq, 'compaction input is not the canonical log');
+        }
+        const g2 = await this.settle(taskId, 'compact');
+        if (g2 === 'PRUNED')
+            throw new TaskPrunedError(taskId);
+        if (g2 === 'UNKNOWN')
+            throw new StoreIoError(`the prune state of task "${taskId}" could not be settled after the compaction.`);
+        if (g2 !== 'CONFIRMED')
+            throw this.refusal(taskId, g2);
+        return { segment: null, packedEvents: 0, removedFiles: 0 };
+    }
+    async pinReference(parentId, childId, at) {
+        const entry = this.tasks.get(parentId);
+        if (!entry)
+            return 'parent-missing';
+        const before = this.derive(parentId);
+        if (before.kind === 'committed')
+            return 'parent-pruned';
+        if (!entry.refs.has(childId))
+            entry.refs.set(childId, at);
+        const g2 = await this.settle(parentId, 'pin');
+        if (g2 === 'CONFIRMED')
+            return 'pinned';
+        if (g2 === 'PRUNED')
+            return 'parent-pruned';
+        if (g2 === 'UNKNOWN')
+            throw new StoreIoError(`the prune state of task "${parentId}" could not be settled after the pin.`);
+        throw this.refusal(parentId, g2);
+    }
+    async listReferences(parentId) {
+        const entry = this.tasks.get(parentId);
+        return entry ? [...entry.refs].map(([childId, at]) => ({ childId, at })).sort((a, b) => (a.childId < b.childId ? -1 : 1)) : [];
+    }
+}
+function sortKeys(o) {
+    return Object.fromEntries(Object.entries(o).sort(([a], [b]) => (a < b ? -1 : 1)));
+}

package/dist/durable/projection.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Projection — the pure fold from events to `TaskState`.
+ *
+ * Deterministic and total over valid logs: the same events always give the
+ * same state, with no clock, randomness or I/O. It is also *strict*: an event
+ * that violates the task's own rules (a second claim with the wrong epoch, a
+ * delivery to an unknown await, an event after a terminal one) is a corrupt
+ * log, not something to be skipped. Writers run every new event through
+ * `applyEvent` before publishing it, so a log that was written by this code
+ * always folds.
+ */
+import { GENESIS_HASH, type PlanStepDecl, type TaskEvent, type TaskState } from './types.js';
+/** Idempotency keys are scoped to the await they were delivered to ('awaitId' never contains ':'). */
+export declare function deliveryKey(awaitId: string, idempotencyKey: string): string;
+/**
+ * A string-keyed dictionary that does not inherit from `Object.prototype`.
+ *
+ * Keys of these dictionaries are application data (assumption keys, effect keys, await ids, labels).
+ * On a plain object `d['__proto__'] = x` replaces the prototype instead of storing an entry, and
+ * `d['constructor']` / `d['toString']` read an inherited function for a key that was never written.
+ * A null-prototype object has neither problem; it serializes exactly like a plain one (JSON, canonical
+ * form, `Object.keys/values/entries`), so stored events and the public `Record<string, T>` types are unchanged.
+ */
+export declare function newDict<T>(from?: Readonly<Record<string, T>>): Record<string, T>;
+/** Validates a plan declaration; returns the first problem or `null`. Shared by the runtime (nice errors) and the fold (strictness). */
+export declare function planProblem(steps: readonly PlanStepDecl[]): string | null;
+export declare function applyEvent(prevState: TaskState | null, e: TaskEvent): TaskState;
+/** Folds a verified, contiguous list of events (starting at seq 1, or continuing `from`). */
+export declare function foldEvents(events: readonly TaskEvent[], from?: TaskState | null): TaskState;
+/** The state as it was when the log had `seq` events — "what did the task look like when this was sent". */
+export declare function foldUntil(events: readonly TaskEvent[], seq: number): TaskState;
+/** Deep copy. `structuredClone` alone would turn the null-prototype dictionaries back into plain objects. */
+export declare function cloneState(s: TaskState): TaskState;
+export { GENESIS_HASH };
+//# sourceMappingURL=projection.d.ts.map

package/dist/durable/projection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"projection.d.ts","sourceRoot":"","sources":["../../src/durable/projection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAAE,YAAY,EAAE,KAAK,YAAY,EAAsB,KAAK,SAAS,EAAE,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AAEjH,sGAAsG;AACtG,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,MAAM,CAE3E;AAED;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAOhF;AAMD,wIAAwI;AACxI,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,GAAG,MAAM,GAAG,IAAI,CA4BzE;AAED,wBAAgB,UAAU,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI,EAAE,CAAC,EAAE,SAAS,GAAG,SAAS,CAwN/E;AAED,6FAA6F;AAC7F,wBAAgB,UAAU,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,EAAE,IAAI,GAAE,SAAS,GAAG,IAAW,GAAG,SAAS,CAKjG;AAED,4GAA4G;AAC5G,wBAAgB,SAAS,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,CAE9E;AAED,6GAA6G;AAC7G,wBAAgB,UAAU,CAAC,CAAC,EAAE,SAAS,GAAG,SAAS,CASlD;AAED,OAAO,EAAE,YAAY,EAAE,CAAC"}