@caupulican/pi-adaptative 0.81.40 → 0.81.42

package/dist/core/orchestration/event-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"event-store.d.ts","sourceRoot":"","sources":["../../../src/core/orchestration/event-store.ts"],"names":[],"mappings":"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","sourcesContent":["import { createHash, randomUUID } from \"node:crypto\";\nimport { existsSync, readdirSync, readFileSync, statSync, unlinkSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport { stateFile } from \"../agent-paths.ts\";\nimport type { JsonObject } from \"../autonomy/contracts.ts\";\nimport { withFileLockSync, writeFileAtomicSync } from \"../util/atomic-file.ts\";\nimport {\n\ttype AppendOrchestrationEventInput,\n\tisOrchestrationEvent,\n\tORCHESTRATION_SCHEMA_VERSION,\n\ttype OrchestrationEvent,\n} from \"./contracts.ts\";\n\nconst EVENT_FILE_PATTERN = /^(\\d{16})\\.json$/;\nconst SNAPSHOT_FILE_PATTERN = /^(\\d{16})\\.json$/;\nconst DEFAULT_MAX_TAIL_EVENTS = 256;\nconst DEFAULT_MAX_TAIL_BYTES = 4 * 1024 * 1024;\nconst DEFAULT_MAX_IDEMPOTENCY_EVENTS = 512;\n\ninterface EventCursor {\n\tversion: 1;\n\tlastOrdinal: number;\n\ttailBytes?: number;\n}\n\ninterface SynchronizedIndexes {\n\tlastOrdinal: number;\n\ttailBytes: number;\n}\n\ninterface IdempotencyMarker {\n\tversion: 1;\n\tkey: string;\n\tordinal: number;\n}\n\ninterface ProjectionSnapshotContent {\n\tversion: 1;\n\tschemaVersion: typeof ORCHESTRATION_SCHEMA_VERSION;\n\tthroughOrdinal: number;\n\tcreatedAt: string;\n\tprojection: JsonObject;\n\tidempotencyEvents: OrchestrationEvent[];\n}\n\ninterface ProjectionSnapshot extends ProjectionSnapshotContent {\n\tdigest: string;\n}\n\ninterface SnapshotBaseline {\n\tversion: 1;\n\tthroughOrdinal: number;\n\tdigest: string;\n\tsnapshotFile: string;\n}\n\ninterface SnapshotFileSignature {\n\tsize: number;\n\tmtimeMs: number;\n\tctimeMs: number;\n}\n\ninterface VerifiedSnapshotBaseline {\n\tbaseline: SnapshotBaseline;\n\tsignature: SnapshotFileSignature;\n}\n\nexport interface OrchestrationEventStoreOptions {\n\tagentDir: string;\n\tsessionId: string;\n\tnow?: () => string;\n\tcreateEventId?: () => string;\n\tmaxTailEvents?: number;\n\tmaxTailBytes?: number;\n\tmaxIdempotencyEvents?: number;\n}\n\nexport class OrchestrationEventStoreError extends Error {\n\tconstructor(message: string) {\n\t\tsuper(message);\n\t\tthis.name = \"OrchestrationEventStoreError\";\n\t}\n}\n\nexport class OrchestrationConcurrencyError extends OrchestrationEventStoreError {\n\tconstructor(expected: number, actual: number) {\n\t\tsuper(`Orchestration event cursor changed: expected ${expected}, actual ${actual}.`);\n\t\tthis.name = \"OrchestrationConcurrencyError\";\n\t}\n}\n\nexport class OrchestrationSnapshotRequiredError extends OrchestrationEventStoreError {\n\treadonly throughOrdinal: number;\n\n\tconstructor(throughOrdinal: number) {\n\t\tsuper(`Orchestration projection snapshot through ordinal ${throughOrdinal} is required.`);\n\t\tthis.name = \"OrchestrationSnapshotRequiredError\";\n\t\tthis.throughOrdinal = throughOrdinal;\n\t}\n}\n\nfunction safeSessionDirectoryName(sessionId: string): string {\n\tconst readable = encodeURIComponent(sessionId).replaceAll(\"%\", \"_\").slice(0, 80) || \"session\";\n\tconst digest = createHash(\"sha256\").update(sessionId).digest(\"hex\").slice(0, 16);\n\treturn `${readable}-${digest}`;\n}\n\nfunction parseCursor(filePath: string): EventCursor | undefined {\n\tif (!existsSync(filePath)) return undefined;\n\ttry {\n\t\tconst parsed: unknown = JSON.parse(readFileSync(filePath, \"utf-8\"));\n\t\tif (!parsed || typeof parsed !== \"object\" || Array.isArray(parsed)) return undefined;\n\t\tconst record = parsed as Record<string, unknown>;\n\t\tif (record.version !== 1 || !Number.isSafeInteger(record.lastOrdinal) || Number(record.lastOrdinal) < 0) {\n\t\t\treturn undefined;\n\t\t}\n\t\tif (record.tailBytes !== undefined && (!Number.isSafeInteger(record.tailBytes) || Number(record.tailBytes) < 0)) {\n\t\t\treturn undefined;\n\t\t}\n\t\treturn {\n\t\t\tversion: 1,\n\t\t\tlastOrdinal: Number(record.lastOrdinal),\n\t\t\t...(record.tailBytes !== undefined ? { tailBytes: Number(record.tailBytes) } : {}),\n\t\t};\n\t} catch {\n\t\treturn undefined;\n\t}\n}\n\nfunction serialize(value: unknown): string {\n\treturn `${JSON.stringify(value, null, \"\\t\")}\\n`;\n}\n\nfunction eventFileName(ordinal: number): string {\n\treturn `${String(ordinal).padStart(16, \"0\")}.json`;\n}\n\nfunction snapshotDigest(content: ProjectionSnapshotContent): string {\n\treturn createHash(\"sha256\").update(JSON.stringify(content)).digest(\"hex\");\n}\n\nfunction positiveSafeInteger(value: number | undefined, fallback: number, label: string): number {\n\tconst resolved = value ?? fallback;\n\tif (!Number.isSafeInteger(resolved) || resolved < 1) {\n\t\tthrow new OrchestrationEventStoreError(`${label} must be a positive safe integer.`);\n\t}\n\treturn resolved;\n}\n\n/**\n * Append-only event tail with a replaceable full-state projection snapshot. Atomic rename prevents\n * torn records. Snapshot publication is two-phase (payload, then small baseline pointer), after which\n * covered event/idempotency files are pruned. A crash at any point leaves either the old replay prefix\n * or the new verified snapshot authoritative; ordinals never reset.\n */\nexport class OrchestrationEventStore {\n\treadonly rootDir: string;\n\treadonly eventsDir: string;\n\treadonly idempotencyDir: string;\n\treadonly cursorPath: string;\n\treadonly snapshotsDir: string;\n\treadonly baselinePath: string;\n\tprivate readonly now: () => string;\n\tprivate readonly createEventId: () => string;\n\tprivate readonly maxTailEvents: number;\n\tprivate readonly maxTailBytes: number;\n\tprivate readonly maxIdempotencyEvents: number;\n\tprivate readonly listeners = new Set<(event: OrchestrationEvent) => void>();\n\tprivate verifiedSnapshotBaseline: VerifiedSnapshotBaseline | undefined;\n\n\tconstructor(options: OrchestrationEventStoreOptions) {\n\t\tthis.rootDir = stateFile(options.agentDir, \"orchestration\", safeSessionDirectoryName(options.sessionId));\n\t\tthis.eventsDir = join(this.rootDir, \"events\");\n\t\tthis.idempotencyDir = join(this.rootDir, \"idempotency\");\n\t\tthis.cursorPath = join(this.rootDir, \"cursor.json\");\n\t\tthis.snapshotsDir = join(this.rootDir, \"snapshots\");\n\t\tthis.baselinePath = join(this.rootDir, \"projection-baseline.json\");\n\t\tthis.now = options.now ?? (() => new Date().toISOString());\n\t\tthis.createEventId = options.createEventId ?? randomUUID;\n\t\tthis.maxTailEvents = positiveSafeInteger(options.maxTailEvents, DEFAULT_MAX_TAIL_EVENTS, \"maxTailEvents\");\n\t\tthis.maxTailBytes = positiveSafeInteger(options.maxTailBytes, DEFAULT_MAX_TAIL_BYTES, \"maxTailBytes\");\n\t\tthis.maxIdempotencyEvents = positiveSafeInteger(\n\t\t\toptions.maxIdempotencyEvents,\n\t\t\tDEFAULT_MAX_IDEMPOTENCY_EVENTS,\n\t\t\t\"maxIdempotencyEvents\",\n\t\t);\n\t}\n\n\tappend(input: AppendOrchestrationEventInput, options: { expectedLastOrdinal?: number } = {}): OrchestrationEvent {\n\t\tconst committed = withFileLockSync(this.cursorPath, (): { event: OrchestrationEvent; appended: boolean } => {\n\t\t\tconst cursor = this.synchronizeIndexesUnlocked();\n\t\t\tconst actual = cursor.lastOrdinal;\n\t\t\tif (input.idempotencyKey) {\n\t\t\t\tconst existing = this.readIdempotentEventUnlocked(input.idempotencyKey);\n\t\t\t\tif (existing) return { event: existing, appended: false };\n\t\t\t}\n\t\t\tif (options.expectedLastOrdinal !== undefined) {\n\t\t\t\tif (actual !== options.expectedLastOrdinal) {\n\t\t\t\t\tthrow new OrchestrationConcurrencyError(options.expectedLastOrdinal, actual);\n\t\t\t\t}\n\t\t\t}\n\n\t\t\tconst ordinal = actual + 1;\n\t\t\tconst next: OrchestrationEvent = {\n\t\t\t\tschemaVersion: ORCHESTRATION_SCHEMA_VERSION,\n\t\t\t\tordinal,\n\t\t\t\teventId: this.createEventId(),\n\t\t\t\ttype: input.type,\n\t\t\t\taggregateId: input.aggregateId,\n\t\t\t\tactor: input.actor,\n\t\t\t\toccurredAt: this.now(),\n\t\t\t\t...(input.correlationId ? { correlationId: input.correlationId } : {}),\n\t\t\t\t...(input.causationId ? { causationId: input.causationId } : {}),\n\t\t\t\t...(input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {}),\n\t\t\t\tpayload: structuredClone(input.payload),\n\t\t\t};\n\t\t\tconst serializedEvent = serialize(next);\n\t\t\twriteFileAtomicSync(join(this.eventsDir, eventFileName(ordinal)), serializedEvent);\n\t\t\tif (input.idempotencyKey) this.writeIdempotencyMarkerUnlocked(input.idempotencyKey, ordinal);\n\t\t\twriteFileAtomicSync(\n\t\t\t\tthis.cursorPath,\n\t\t\t\tserialize({\n\t\t\t\t\tversion: 1,\n\t\t\t\t\tlastOrdinal: ordinal,\n\t\t\t\t\ttailBytes: cursor.tailBytes + Buffer.byteLength(serializedEvent),\n\t\t\t\t} satisfies EventCursor),\n\t\t\t);\n\t\t\treturn { event: next, appended: true };\n\t\t});\n\n\t\tif (committed.appended) {\n\t\t\tfor (const listener of this.listeners) listener(structuredClone(committed.event));\n\t\t}\n\t\treturn structuredClone(committed.event);\n\t}\n\n\treadAll(): OrchestrationEvent[] {\n\t\treturn this.readAllUnlocked();\n\t}\n\n\treadAfter(ordinal: number): OrchestrationEvent[] {\n\t\tconst baseline = this.readBaselineUnlocked();\n\t\tif (baseline && ordinal < baseline.throughOrdinal) {\n\t\t\tthrow new OrchestrationSnapshotRequiredError(baseline.throughOrdinal);\n\t\t}\n\t\tconst events: OrchestrationEvent[] = [];\n\t\tconst names = this.eventFileNamesUnlocked();\n\t\tthis.assertReadableTailUnlocked(names, baseline?.throughOrdinal ?? 0);\n\t\tlet previousOrdinal = ordinal;\n\t\tfor (const name of names) {\n\t\t\tconst match = EVENT_FILE_PATTERN.exec(name);\n\t\t\tif (!match) continue;\n\t\t\tconst fileOrdinal = Number(match[1]);\n\t\t\tif (fileOrdinal <= ordinal) continue;\n\t\t\tconst event = this.readEventFileUnlocked(name);\n\t\t\tif (event.ordinal !== fileOrdinal || event.ordinal <= previousOrdinal) {\n\t\t\t\tthrow new OrchestrationEventStoreError(`Non-monotonic orchestration event ordinal in ${name}`);\n\t\t\t}\n\t\t\tpreviousOrdinal = event.ordinal;\n\t\t\tevents.push(structuredClone(event));\n\t\t}\n\t\treturn events;\n\t}\n\n\treadProjectionSnapshot(): { throughOrdinal: number; projection: JsonObject } | undefined {\n\t\tconst snapshot = this.readProjectionSnapshotUnlocked();\n\t\treturn snapshot\n\t\t\t? { throughOrdinal: snapshot.throughOrdinal, projection: structuredClone(snapshot.projection) }\n\t\t\t: undefined;\n\t}\n\n\t/** Replace a large replay prefix with one verified current-state snapshot and a bounded tail. */\n\tcompactIfNeeded(throughOrdinal: number, projection: () => JsonObject): boolean {\n\t\tconst baselineBeforeLock = this.readBaselineUnlocked()?.throughOrdinal ?? 0;\n\t\tconst cursorBeforeLock = parseCursor(this.cursorPath);\n\t\tif (\n\t\t\tcursorBeforeLock?.lastOrdinal === throughOrdinal &&\n\t\t\tcursorBeforeLock.tailBytes !== undefined &&\n\t\t\tthroughOrdinal - baselineBeforeLock < this.maxTailEvents &&\n\t\t\tcursorBeforeLock.tailBytes < this.maxTailBytes\n\t\t) {\n\t\t\treturn false;\n\t\t}\n\t\treturn withFileLockSync(this.cursorPath, () => {\n\t\t\tconst cursor = this.synchronizeIndexesUnlocked();\n\t\t\tif (cursor.lastOrdinal !== throughOrdinal) return false;\n\t\t\tconst baselineOrdinal = this.readBaselineUnlocked()?.throughOrdinal ?? 0;\n\t\t\tconst tailNames = this.eventFileNamesUnlocked().filter(\n\t\t\t\t(name) => Number(EVENT_FILE_PATTERN.exec(name)?.[1] ?? 0) > baselineOrdinal,\n\t\t\t);\n\t\t\tif (tailNames.length < this.maxTailEvents && cursor.tailBytes < this.maxTailBytes) return false;\n\n\t\t\tconst retainedByKey = new Map<string, OrchestrationEvent>();\n\t\t\tfor (const event of this.readProjectionSnapshotUnlocked()?.idempotencyEvents ?? []) {\n\t\t\t\tif (event.idempotencyKey) retainedByKey.set(event.idempotencyKey, event);\n\t\t\t}\n\t\t\tfor (const name of tailNames) {\n\t\t\t\tconst event = this.readEventFileUnlocked(name);\n\t\t\t\tif (event.ordinal <= throughOrdinal && event.idempotencyKey) {\n\t\t\t\t\tretainedByKey.set(event.idempotencyKey, event);\n\t\t\t\t}\n\t\t\t}\n\t\t\tconst idempotencyEvents = [...retainedByKey.values()]\n\t\t\t\t.sort((left, right) => left.ordinal - right.ordinal)\n\t\t\t\t.slice(-this.maxIdempotencyEvents)\n\t\t\t\t.map((event) => structuredClone(event));\n\t\t\tconst content: ProjectionSnapshotContent = {\n\t\t\t\tversion: 1,\n\t\t\t\tschemaVersion: ORCHESTRATION_SCHEMA_VERSION,\n\t\t\t\tthroughOrdinal,\n\t\t\t\tcreatedAt: this.now(),\n\t\t\t\tprojection: structuredClone(projection()),\n\t\t\t\tidempotencyEvents,\n\t\t\t};\n\t\t\tconst digest = snapshotDigest(content);\n\t\t\tconst snapshotFile = eventFileName(throughOrdinal);\n\t\t\twriteFileAtomicSync(\n\t\t\t\tjoin(this.snapshotsDir, snapshotFile),\n\t\t\t\tserialize({ ...content, digest } satisfies ProjectionSnapshot),\n\t\t\t);\n\t\t\twriteFileAtomicSync(\n\t\t\t\tthis.baselinePath,\n\t\t\t\tserialize({ version: 1, throughOrdinal, digest, snapshotFile } satisfies SnapshotBaseline),\n\t\t\t);\n\n\t\t\tfor (const name of this.idempotencyFileNamesUnlocked()) {\n\t\t\t\tthis.unlinkManagedFile(join(this.idempotencyDir, name));\n\t\t\t}\n\t\t\tfor (const name of this.eventFileNamesUnlocked()) {\n\t\t\t\tconst ordinal = Number(EVENT_FILE_PATTERN.exec(name)?.[1] ?? 0);\n\t\t\t\tif (ordinal <= throughOrdinal) this.unlinkManagedFile(join(this.eventsDir, name));\n\t\t\t}\n\t\t\tfor (const name of this.snapshotFileNamesUnlocked()) {\n\t\t\t\tif (name !== snapshotFile) this.unlinkManagedFile(join(this.snapshotsDir, name));\n\t\t\t}\n\t\t\twriteFileAtomicSync(\n\t\t\t\tthis.cursorPath,\n\t\t\t\tserialize({ version: 1, lastOrdinal: throughOrdinal, tailBytes: 0 } satisfies EventCursor),\n\t\t\t);\n\t\t\treturn true;\n\t\t});\n\t}\n\n\tsubscribe(listener: (event: OrchestrationEvent) => void): () => void {\n\t\tthis.listeners.add(listener);\n\t\treturn () => this.listeners.delete(listener);\n\t}\n\n\tprivate readAllUnlocked(): OrchestrationEvent[] {\n\t\tconst names = this.eventFileNamesUnlocked();\n\t\tconst events: OrchestrationEvent[] = [];\n\t\tconst baselineOrdinal = this.readProjectionSnapshotUnlocked()?.throughOrdinal ?? 0;\n\t\tthis.assertReadableTailUnlocked(names, baselineOrdinal);\n\t\tlet previousOrdinal = baselineOrdinal;\n\t\tfor (const name of names) {\n\t\t\tconst match = EVENT_FILE_PATTERN.exec(name);\n\t\t\tif (!match) continue;\n\t\t\tconst fileOrdinal = Number(match[1]);\n\t\t\tif (fileOrdinal <= baselineOrdinal) continue;\n\t\t\tconst parsed = this.readEventFileUnlocked(name);\n\t\t\tif (parsed.ordinal !== fileOrdinal || parsed.ordinal <= previousOrdinal) {\n\t\t\t\tthrow new OrchestrationEventStoreError(`Non-monotonic orchestration event ordinal in ${name}`);\n\t\t\t}\n\t\t\tpreviousOrdinal = parsed.ordinal;\n\t\t\tevents.push(structuredClone(parsed));\n\t\t}\n\t\treturn events;\n\t}\n\n\tprivate eventFileNamesUnlocked(): string[] {\n\t\ttry {\n\t\t\treturn readdirSync(this.eventsDir)\n\t\t\t\t.filter((candidate) => EVENT_FILE_PATTERN.test(candidate))\n\t\t\t\t.sort();\n\t\t} catch (error) {\n\t\t\tif ((error as NodeJS.ErrnoException).code === \"ENOENT\") return [];\n\t\t\tthrow error;\n\t\t}\n\t}\n\n\tprivate idempotencyFileNamesUnlocked(): string[] {\n\t\ttry {\n\t\t\treturn readdirSync(this.idempotencyDir).filter((candidate) => candidate.endsWith(\".json\"));\n\t\t} catch {\n\t\t\treturn [];\n\t\t}\n\t}\n\n\tprivate snapshotFileNamesUnlocked(): string[] {\n\t\ttry {\n\t\t\treturn readdirSync(this.snapshotsDir)\n\t\t\t\t.filter((candidate) => SNAPSHOT_FILE_PATTERN.test(candidate))\n\t\t\t\t.sort();\n\t\t} catch {\n\t\t\treturn [];\n\t\t}\n\t}\n\n\t/** Event files are a contiguous append-only tail after the published snapshot. */\n\tprivate assertContiguousTailOrdinalsUnlocked(names: readonly string[], baselineOrdinal: number): void {\n\t\tlet expectedOrdinal = baselineOrdinal + 1;\n\t\tfor (const name of names) {\n\t\t\tconst ordinal = Number(EVENT_FILE_PATTERN.exec(name)?.[1] ?? 0);\n\t\t\t// A crash after publishing the baseline but before pruning is safe: the snapshot covers these files.\n\t\t\tif (ordinal <= baselineOrdinal) continue;\n\t\t\tif (ordinal !== expectedOrdinal) {\n\t\t\t\tthrow new OrchestrationEventStoreError(\n\t\t\t\t\t`Missing orchestration event ordinal ${expectedOrdinal} before ${name}.`,\n\t\t\t\t);\n\t\t\t}\n\t\t\texpectedOrdinal++;\n\t\t}\n\t}\n\n\t/** A valid cursor may lag a newly published snapshot, but it must never lead its committed tail. */\n\tprivate assertReadableTailUnlocked(names: readonly string[], baselineOrdinal: number): void {\n\t\tthis.assertContiguousTailOrdinalsUnlocked(names, baselineOrdinal);\n\t\tconst highestEventOrdinal = names.length > 0 ? Number(EVENT_FILE_PATTERN.exec(names.at(-1)!)?.[1] ?? 0) : 0;\n\t\tconst highestCommittedOrdinal = Math.max(baselineOrdinal, highestEventOrdinal);\n\t\tconst cursor = parseCursor(this.cursorPath);\n\t\tif (cursor && cursor.lastOrdinal > highestCommittedOrdinal) {\n\t\t\tthrow new OrchestrationEventStoreError(\n\t\t\t\t`Orchestration cursor ${cursor.lastOrdinal} is ahead of the last committed event ${highestCommittedOrdinal}.`,\n\t\t\t);\n\t\t}\n\t}\n\n\tprivate readBaselineUnlocked(): SnapshotBaseline | undefined {\n\t\tif (!existsSync(this.baselinePath)) return undefined;\n\t\tlet parsed: unknown;\n\t\ttry {\n\t\t\tparsed = JSON.parse(readFileSync(this.baselinePath, \"utf-8\"));\n\t\t} catch (error) {\n\t\t\tthrow new OrchestrationEventStoreError(\n\t\t\t\t`Failed to parse orchestration snapshot baseline: ${error instanceof Error ? error.message : String(error)}`,\n\t\t\t);\n\t\t}\n\t\tif (!parsed || typeof parsed !== \"object\" || Array.isArray(parsed)) {\n\t\t\tthrow new OrchestrationEventStoreError(\"Invalid orchestration snapshot baseline.\");\n\t\t}\n\t\tconst baseline = parsed as Record<string, unknown>;\n\t\tif (\n\t\t\tbaseline.version !== 1 ||\n\t\t\t!Number.isSafeInteger(baseline.throughOrdinal) ||\n\t\t\tNumber(baseline.throughOrdinal) < 1 ||\n\t\t\ttypeof baseline.digest !== \"string\" ||\n\t\t\tbaseline.digest.length === 0 ||\n\t\t\ttypeof baseline.snapshotFile !== \"string\" ||\n\t\t\t!SNAPSHOT_FILE_PATTERN.test(baseline.snapshotFile) ||\n\t\t\tNumber(SNAPSHOT_FILE_PATTERN.exec(baseline.snapshotFile)?.[1] ?? 0) !== Number(baseline.throughOrdinal)\n\t\t) {\n\t\t\tthrow new OrchestrationEventStoreError(\"Invalid orchestration snapshot baseline.\");\n\t\t}\n\t\treturn {\n\t\t\tversion: 1,\n\t\t\tthroughOrdinal: Number(baseline.throughOrdinal),\n\t\t\tdigest: baseline.digest,\n\t\t\tsnapshotFile: baseline.snapshotFile,\n\t\t};\n\t}\n\n\tprivate readProjectionSnapshotUnlocked(): ProjectionSnapshot | undefined {\n\t\tconst baseline = this.readBaselineUnlocked();\n\t\tif (!baseline) return undefined;\n\t\tlet parsed: unknown;\n\t\ttry {\n\t\t\tparsed = JSON.parse(readFileSync(join(this.snapshotsDir, baseline.snapshotFile), \"utf-8\"));\n\t\t} catch (error) {\n\t\t\tthrow new OrchestrationEventStoreError(\n\t\t\t\t`Failed to parse orchestration projection snapshot: ${error instanceof Error ? error.message : String(error)}`,\n\t\t\t);\n\t\t}\n\t\tif (!parsed || typeof parsed !== \"object\" || Array.isArray(parsed)) {\n\t\t\tthrow new OrchestrationEventStoreError(\"Invalid orchestration projection snapshot.\");\n\t\t}\n\t\tconst snapshot = parsed as Record<string, unknown>;\n\t\tif (\n\t\t\tsnapshot.version !== 1 ||\n\t\t\tsnapshot.schemaVersion !== ORCHESTRATION_SCHEMA_VERSION ||\n\t\t\tsnapshot.throughOrdinal !== baseline.throughOrdinal ||\n\t\t\ttypeof snapshot.createdAt !== \"string\" ||\n\t\t\t!snapshot.projection ||\n\t\t\ttypeof snapshot.projection !== \"object\" ||\n\t\t\tArray.isArray(snapshot.projection) ||\n\t\t\t!Array.isArray(snapshot.idempotencyEvents) ||\n\t\t\t!snapshot.idempotencyEvents.every(isOrchestrationEvent) ||\n\t\t\t!snapshot.idempotencyEvents.every(\n\t\t\t\t(event) => event.ordinal <= baseline.throughOrdinal && event.idempotencyKey !== undefined,\n\t\t\t) ||\n\t\t\tnew Set(snapshot.idempotencyEvents.map((event) => event.idempotencyKey)).size !==\n\t\t\t\tsnapshot.idempotencyEvents.length ||\n\t\t\ttypeof snapshot.digest !== \"string\" ||\n\t\t\tsnapshot.digest !== baseline.digest\n\t\t) {\n\t\t\tthrow new OrchestrationEventStoreError(\"Invalid orchestration projection snapshot.\");\n\t\t}\n\t\tconst content: ProjectionSnapshotContent = {\n\t\t\tversion: 1,\n\t\t\tschemaVersion: ORCHESTRATION_SCHEMA_VERSION,\n\t\t\tthroughOrdinal: baseline.throughOrdinal,\n\t\t\tcreatedAt: snapshot.createdAt,\n\t\t\tprojection: structuredClone(snapshot.projection) as JsonObject,\n\t\t\tidempotencyEvents: snapshot.idempotencyEvents.map((event) => structuredClone(event)),\n\t\t};\n\t\tif (snapshotDigest(content) !== baseline.digest) {\n\t\t\tthrow new OrchestrationEventStoreError(\"Orchestration projection snapshot digest mismatch.\");\n\t\t}\n\t\treturn { ...content, digest: baseline.digest };\n\t}\n\n\t/**\n\t * Appends need a verified snapshot baseline but must not deserialize its projection on every event.\n\t * The baseline pointer remains small and is reread each time; an immutable snapshot is reparsed only\n\t * when its pointer or filesystem identity changes.\n\t */\n\tprivate readVerifiedSnapshotBaselineUnlocked(): SnapshotBaseline | undefined {\n\t\tconst baseline = this.readBaselineUnlocked();\n\t\tif (!baseline) {\n\t\t\tthis.verifiedSnapshotBaseline = undefined;\n\t\t\treturn undefined;\n\t\t}\n\t\tconst signature = this.snapshotFileSignatureUnlocked(baseline);\n\t\tconst cached = this.verifiedSnapshotBaseline;\n\t\tif (\n\t\t\tcached &&\n\t\t\tcached.baseline.throughOrdinal === baseline.throughOrdinal &&\n\t\t\tcached.baseline.digest === baseline.digest &&\n\t\t\tcached.baseline.snapshotFile === baseline.snapshotFile &&\n\t\t\tcached.signature.size === signature.size &&\n\t\t\tcached.signature.mtimeMs === signature.mtimeMs &&\n\t\t\tcached.signature.ctimeMs === signature.ctimeMs\n\t\t) {\n\t\t\treturn baseline;\n\t\t}\n\t\tthis.readProjectionSnapshotUnlocked();\n\t\tconst verifiedSignature = this.snapshotFileSignatureUnlocked(baseline);\n\t\tif (\n\t\t\tverifiedSignature.size !== signature.size ||\n\t\t\tverifiedSignature.mtimeMs !== signature.mtimeMs ||\n\t\t\tverifiedSignature.ctimeMs !== signature.ctimeMs\n\t\t) {\n\t\t\tthrow new OrchestrationEventStoreError(\"Orchestration projection snapshot changed while being verified.\");\n\t\t}\n\t\tthis.verifiedSnapshotBaseline = { baseline, signature };\n\t\treturn baseline;\n\t}\n\n\tprivate snapshotFileSignatureUnlocked(baseline: SnapshotBaseline): SnapshotFileSignature {\n\t\ttry {\n\t\t\tconst stats = statSync(join(this.snapshotsDir, baseline.snapshotFile));\n\t\t\tif (!stats.isFile())\n\t\t\t\tthrow new OrchestrationEventStoreError(\"Orchestration projection snapshot is not a file.\");\n\t\t\treturn { size: stats.size, mtimeMs: stats.mtimeMs, ctimeMs: stats.ctimeMs };\n\t\t} catch (error) {\n\t\t\tif (error instanceof OrchestrationEventStoreError) throw error;\n\t\t\tthrow new OrchestrationEventStoreError(\n\t\t\t\t`Failed to parse orchestration projection snapshot: ${error instanceof Error ? error.message : String(error)}`,\n\t\t\t);\n\t\t}\n\t}\n\n\tprivate unlinkManagedFile(filePath: string): void {\n\t\ttry {\n\t\t\tunlinkSync(filePath);\n\t\t} catch (error) {\n\t\t\tif ((error as NodeJS.ErrnoException).code !== \"ENOENT\") throw error;\n\t\t}\n\t}\n\n\tprivate readEventFileUnlocked(name: string): OrchestrationEvent {\n\t\tlet parsed: unknown;\n\t\ttry {\n\t\t\tparsed = JSON.parse(readFileSync(join(this.eventsDir, name), \"utf-8\"));\n\t\t} catch (error) {\n\t\t\tthrow new OrchestrationEventStoreError(\n\t\t\t\t`Failed to parse orchestration event ${name}: ${error instanceof Error ? error.message : String(error)}`,\n\t\t\t);\n\t\t}\n\t\tif (!isOrchestrationEvent(parsed)) {\n\t\t\tthrow new OrchestrationEventStoreError(`Invalid orchestration event record: ${name}`);\n\t\t}\n\t\treturn parsed;\n\t}\n\n\tprivate idempotencyPath(key: string): string {\n\t\treturn join(this.idempotencyDir, `${createHash(\"sha256\").update(key).digest(\"hex\")}.json`);\n\t}\n\n\tprivate writeIdempotencyMarkerUnlocked(key: string, ordinal: number): void {\n\t\twriteFileAtomicSync(\n\t\t\tthis.idempotencyPath(key),\n\t\t\tserialize({ version: 1, key, ordinal } satisfies IdempotencyMarker),\n\t\t);\n\t}\n\n\tprivate readIdempotentEventUnlocked(key: string): OrchestrationEvent | undefined {\n\t\tconst markerPath = this.idempotencyPath(key);\n\t\tif (!existsSync(markerPath)) {\n\t\t\treturn this.readProjectionSnapshotUnlocked()?.idempotencyEvents.find((event) => event.idempotencyKey === key);\n\t\t}\n\t\tlet parsed: unknown;\n\t\ttry {\n\t\t\tparsed = JSON.parse(readFileSync(markerPath, \"utf-8\"));\n\t\t} catch (error) {\n\t\t\tthrow new OrchestrationEventStoreError(\n\t\t\t\t`Failed to parse orchestration idempotency marker: ${error instanceof Error ? error.message : String(error)}`,\n\t\t\t);\n\t\t}\n\t\tif (!parsed || typeof parsed !== \"object\" || Array.isArray(parsed)) {\n\t\t\tthrow new OrchestrationEventStoreError(\"Invalid orchestration idempotency marker.\");\n\t\t}\n\t\tconst marker = parsed as Record<string, unknown>;\n\t\tif (\n\t\t\tmarker.version !== 1 ||\n\t\t\tmarker.key !== key ||\n\t\t\t!Number.isSafeInteger(marker.ordinal) ||\n\t\t\tNumber(marker.ordinal) < 1\n\t\t) {\n\t\t\tthrow new OrchestrationEventStoreError(\"Invalid orchestration idempotency marker.\");\n\t\t}\n\t\tconst ordinal = Number(marker.ordinal);\n\t\tif (!existsSync(join(this.eventsDir, eventFileName(ordinal)))) {\n\t\t\tconst retained = this.readProjectionSnapshotUnlocked()?.idempotencyEvents.find(\n\t\t\t\t(event) => event.idempotencyKey === key && event.ordinal === ordinal,\n\t\t\t);\n\t\t\tif (retained) return retained;\n\t\t}\n\t\tconst event = this.readEventFileUnlocked(eventFileName(ordinal));\n\t\tif (event.ordinal !== ordinal || event.idempotencyKey !== key) {\n\t\t\tthrow new OrchestrationEventStoreError(\"Orchestration idempotency marker does not match its event.\");\n\t\t}\n\t\treturn event;\n\t}\n\n\t/**\n\t * Reconcile only the crash tail when an event rename committed before its marker/cursor. Normal\n\t * appends read directory metadata plus one marker, never the accumulated event payload prefix.\n\t */\n\tprivate synchronizeIndexesUnlocked(): SynchronizedIndexes {\n\t\tconst names = this.eventFileNamesUnlocked();\n\t\tconst baselineOrdinal = this.readVerifiedSnapshotBaselineUnlocked()?.throughOrdinal ?? 0;\n\t\tthis.assertReadableTailUnlocked(names, baselineOrdinal);\n\t\tconst highestEventOrdinal = names.length > 0 ? Number(EVENT_FILE_PATTERN.exec(names.at(-1)!)?.[1] ?? 0) : 0;\n\t\tconst highest = Math.max(baselineOrdinal, highestEventOrdinal);\n\t\tconst cursor = parseCursor(this.cursorPath);\n\t\tif (\n\t\t\tcursor?.lastOrdinal === highest &&\n\t\t\tcursor.tailBytes !== undefined &&\n\t\t\t(highest > baselineOrdinal || cursor.tailBytes === 0)\n\t\t) {\n\t\t\treturn { lastOrdinal: highest, tailBytes: cursor.tailBytes };\n\t\t}\n\t\tif (cursor && cursor.lastOrdinal > highest) {\n\t\t\tthrow new OrchestrationEventStoreError(\n\t\t\t\t`Orchestration cursor ${cursor.lastOrdinal} is ahead of the last committed event ${highest}.`,\n\t\t\t);\n\t\t}\n\t\tconst rebuildFrom = Math.max(\n\t\t\tbaselineOrdinal + 1,\n\t\t\tcursor && cursor.lastOrdinal >= baselineOrdinal && cursor.lastOrdinal <= highest\n\t\t\t\t? cursor.lastOrdinal + 1\n\t\t\t\t: baselineOrdinal + 1,\n\t\t);\n\t\tfor (const name of names) {\n\t\t\tconst ordinal = Number(EVENT_FILE_PATTERN.exec(name)?.[1] ?? 0);\n\t\t\tif (ordinal < rebuildFrom || ordinal <= baselineOrdinal) continue;\n\t\t\tconst event = this.readEventFileUnlocked(name);\n\t\t\tif (event.ordinal !== ordinal) {\n\t\t\t\tthrow new OrchestrationEventStoreError(`Event ordinal does not match file name: ${name}`);\n\t\t\t}\n\t\t\tif (event.idempotencyKey) this.writeIdempotencyMarkerUnlocked(event.idempotencyKey, ordinal);\n\t\t}\n\t\tconst tailBytes = names.reduce((total, name) => {\n\t\t\tconst ordinal = Number(EVENT_FILE_PATTERN.exec(name)?.[1] ?? 0);\n\t\t\tif (ordinal <= baselineOrdinal) return total;\n\t\t\ttry {\n\t\t\t\treturn total + statSync(join(this.eventsDir, name)).size;\n\t\t\t} catch {\n\t\t\t\treturn total;\n\t\t\t}\n\t\t}, 0);\n\t\twriteFileAtomicSync(\n\t\t\tthis.cursorPath,\n\t\t\tserialize({ version: 1, lastOrdinal: highest, tailBytes } satisfies EventCursor),\n\t\t);\n\t\treturn { lastOrdinal: highest, tailBytes };\n\t}\n}\n"]}
+{"version":3,"file":"event-store.d.ts","sourceRoot":"","sources":["../../../src/core/orchestration/event-store.ts"],"names":[],"mappings":"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","sourcesContent":["import { createHash, randomUUID } from \"node:crypto\";\nimport { existsSync, statSync, unlinkSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport { orchestrationEventStoreDir } from \"../agent-paths.ts\";\nimport type { JsonObject } from \"../autonomy/contracts.ts\";\nimport { withFileLockSync, writeFileAtomicSync } from \"../util/atomic-file.ts\";\nimport { readBoundedDirectoryNamesSync, readBoundedTextFileSync } from \"../util/bounded-file.ts\";\nimport {\n\ttype AppendOrchestrationEventInput,\n\tisOrchestrationEvent,\n\tORCHESTRATION_SCHEMA_VERSION,\n\ttype OrchestrationEvent,\n} from \"./contracts.ts\";\n\nconst EVENT_FILE_PATTERN = /^(\\d{16})\\.json$/;\nconst SNAPSHOT_FILE_PATTERN = /^(\\d{16})\\.json$/;\nconst DEFAULT_MAX_TAIL_EVENTS = 256;\nconst DEFAULT_MAX_TAIL_BYTES = 4 * 1024 * 1024;\nconst DEFAULT_MAX_IDEMPOTENCY_EVENTS = 512;\nconst MAX_CONFIGURED_TAIL_EVENTS = 1_024;\nconst MAX_CONFIGURED_TAIL_BYTES = 16 * 1024 * 1024;\nconst MAX_CONFIGURED_IDEMPOTENCY_EVENTS = 1_024;\nconst MAX_EVENT_DIRECTORY_ENTRIES = 2_048;\nconst MAX_IDEMPOTENCY_DIRECTORY_ENTRIES = 2_048;\nconst MAX_SNAPSHOT_DIRECTORY_ENTRIES = 8;\nconst MAX_CURSOR_BYTES = 64 * 1024;\nconst MAX_BASELINE_BYTES = 64 * 1024;\nconst MAX_IDEMPOTENCY_MARKER_BYTES = 64 * 1024;\n/** Full current task state plus retained idempotency evidence; intentionally above the 16MiB tail cap. */\nconst MAX_PROJECTION_SNAPSHOT_BYTES = 32 * 1024 * 1024;\n\ninterface EventCursor {\n\tversion: 1;\n\tlastOrdinal: number;\n\ttailBytes?: number;\n}\n\ninterface SynchronizedIndexes {\n\tlastOrdinal: number;\n\ttailBytes: number;\n}\n\ninterface IdempotencyMarker {\n\tversion: 1;\n\tkey: string;\n\tordinal: number;\n}\n\ninterface ProjectionSnapshotContent {\n\tversion: 1;\n\tschemaVersion: typeof ORCHESTRATION_SCHEMA_VERSION;\n\tthroughOrdinal: number;\n\tcreatedAt: string;\n\tprojection: JsonObject;\n\tidempotencyEvents: OrchestrationEvent[];\n}\n\ninterface ProjectionSnapshot extends ProjectionSnapshotContent {\n\tdigest: string;\n}\n\ninterface SnapshotBaseline {\n\tversion: 1;\n\tthroughOrdinal: number;\n\tdigest: string;\n\tsnapshotFile: string;\n}\n\ninterface SnapshotFileSignature {\n\tsize: number;\n\tmtimeMs: number;\n\tctimeMs: number;\n}\n\ninterface VerifiedSnapshotBaseline {\n\tbaseline: SnapshotBaseline;\n\tsignature: SnapshotFileSignature;\n}\n\nexport interface OrchestrationEventStoreOptions {\n\tagentDir: string;\n\tsessionId: string;\n\tnow?: () => string;\n\tcreateEventId?: () => string;\n\tmaxTailEvents?: number;\n\tmaxTailBytes?: number;\n\tmaxIdempotencyEvents?: number;\n}\n\nexport class OrchestrationEventStoreError extends Error {\n\tconstructor(message: string) {\n\t\tsuper(message);\n\t\tthis.name = \"OrchestrationEventStoreError\";\n\t}\n}\n\nexport class OrchestrationConcurrencyError extends OrchestrationEventStoreError {\n\tconstructor(expected: number, actual: number) {\n\t\tsuper(`Orchestration event cursor changed: expected ${expected}, actual ${actual}.`);\n\t\tthis.name = \"OrchestrationConcurrencyError\";\n\t}\n}\n\nexport class OrchestrationSnapshotRequiredError extends OrchestrationEventStoreError {\n\treadonly throughOrdinal: number;\n\n\tconstructor(throughOrdinal: number) {\n\t\tsuper(`Orchestration projection snapshot through ordinal ${throughOrdinal} is required.`);\n\t\tthis.name = \"OrchestrationSnapshotRequiredError\";\n\t\tthis.throughOrdinal = throughOrdinal;\n\t}\n}\n\nfunction parseCursor(filePath: string): EventCursor | undefined {\n\tif (!existsSync(filePath)) return undefined;\n\tlet content: string;\n\ttry {\n\t\tcontent = readBoundedTextFileSync(filePath, MAX_CURSOR_BYTES, \"Orchestration cursor\");\n\t} catch (error) {\n\t\tthrow new OrchestrationEventStoreError(\n\t\t\t`Failed to read orchestration cursor: ${error instanceof Error ? error.message : String(error)}`,\n\t\t);\n\t}\n\ttry {\n\t\tconst parsed: unknown = JSON.parse(content);\n\t\tif (!parsed || typeof parsed !== \"object\" || Array.isArray(parsed)) return undefined;\n\t\tconst record = parsed as Record<string, unknown>;\n\t\tif (record.version !== 1 || !Number.isSafeInteger(record.lastOrdinal) || Number(record.lastOrdinal) < 0) {\n\t\t\treturn undefined;\n\t\t}\n\t\tif (record.tailBytes !== undefined && (!Number.isSafeInteger(record.tailBytes) || Number(record.tailBytes) < 0)) {\n\t\t\treturn undefined;\n\t\t}\n\t\treturn {\n\t\t\tversion: 1,\n\t\t\tlastOrdinal: Number(record.lastOrdinal),\n\t\t\t...(record.tailBytes !== undefined ? { tailBytes: Number(record.tailBytes) } : {}),\n\t\t};\n\t} catch {\n\t\treturn undefined;\n\t}\n}\n\nfunction serialize(value: unknown): string {\n\treturn `${JSON.stringify(value, null, \"\\t\")}\\n`;\n}\n\nfunction serializeBounded(\n\tvalue: unknown,\n\tmaxBytes: number,\n\tlabel: string,\n\toversizedMessage = `${label} exceeds its byte limit.`,\n): string {\n\tconst serialized = serialize(value);\n\tif (Buffer.byteLength(serialized, \"utf-8\") > maxBytes) {\n\t\tthrow new OrchestrationEventStoreError(oversizedMessage);\n\t}\n\treturn serialized;\n}\n\nfunction eventFileName(ordinal: number): string {\n\treturn `${String(ordinal).padStart(16, \"0\")}.json`;\n}\n\nfunction snapshotDigest(content: ProjectionSnapshotContent): string {\n\treturn createHash(\"sha256\").update(JSON.stringify(content)).digest(\"hex\");\n}\n\nfunction positiveSafeInteger(value: number | undefined, fallback: number, maximum: number, label: string): number {\n\tconst resolved = value ?? fallback;\n\tif (!Number.isSafeInteger(resolved) || resolved < 1) {\n\t\tthrow new OrchestrationEventStoreError(`${label} must be a positive safe integer.`);\n\t}\n\tif (resolved > maximum) throw new OrchestrationEventStoreError(`${label} must not exceed ${maximum}.`);\n\treturn resolved;\n}\n\n/**\n * Append-only event tail with a replaceable full-state projection snapshot. Atomic rename prevents\n * torn records. Snapshot publication is two-phase (payload, then small baseline pointer), after which\n * covered event/idempotency files are pruned. A crash at any point leaves either the old replay prefix\n * or the new verified snapshot authoritative; ordinals never reset.\n */\nexport class OrchestrationEventStore {\n\treadonly rootDir: string;\n\treadonly eventsDir: string;\n\treadonly idempotencyDir: string;\n\treadonly cursorPath: string;\n\treadonly snapshotsDir: string;\n\treadonly baselinePath: string;\n\tprivate readonly now: () => string;\n\tprivate readonly createEventId: () => string;\n\tprivate readonly maxTailEvents: number;\n\tprivate readonly maxTailBytes: number;\n\tprivate readonly maxIdempotencyEvents: number;\n\tprivate readonly listeners = new Set<(event: OrchestrationEvent) => void>();\n\tprivate verifiedSnapshotBaseline: VerifiedSnapshotBaseline | undefined;\n\n\tconstructor(options: OrchestrationEventStoreOptions) {\n\t\tthis.rootDir = orchestrationEventStoreDir(options.agentDir, options.sessionId);\n\t\tthis.eventsDir = join(this.rootDir, \"events\");\n\t\tthis.idempotencyDir = join(this.rootDir, \"idempotency\");\n\t\tthis.cursorPath = join(this.rootDir, \"cursor.json\");\n\t\tthis.snapshotsDir = join(this.rootDir, \"snapshots\");\n\t\tthis.baselinePath = join(this.rootDir, \"projection-baseline.json\");\n\t\tthis.now = options.now ?? (() => new Date().toISOString());\n\t\tthis.createEventId = options.createEventId ?? randomUUID;\n\t\tthis.maxTailEvents = positiveSafeInteger(\n\t\t\toptions.maxTailEvents,\n\t\t\tDEFAULT_MAX_TAIL_EVENTS,\n\t\t\tMAX_CONFIGURED_TAIL_EVENTS,\n\t\t\t\"maxTailEvents\",\n\t\t);\n\t\tthis.maxTailBytes = positiveSafeInteger(\n\t\t\toptions.maxTailBytes,\n\t\t\tDEFAULT_MAX_TAIL_BYTES,\n\t\t\tMAX_CONFIGURED_TAIL_BYTES,\n\t\t\t\"maxTailBytes\",\n\t\t);\n\t\tthis.maxIdempotencyEvents = positiveSafeInteger(\n\t\t\toptions.maxIdempotencyEvents,\n\t\t\tDEFAULT_MAX_IDEMPOTENCY_EVENTS,\n\t\t\tMAX_CONFIGURED_IDEMPOTENCY_EVENTS,\n\t\t\t\"maxIdempotencyEvents\",\n\t\t);\n\t}\n\n\tappend(input: AppendOrchestrationEventInput, options: { expectedLastOrdinal?: number } = {}): OrchestrationEvent {\n\t\tconst committed = withFileLockSync(this.cursorPath, (): { event: OrchestrationEvent; appended: boolean } => {\n\t\t\tconst cursor = this.synchronizeIndexesUnlocked();\n\t\t\tconst actual = cursor.lastOrdinal;\n\t\t\tif (input.idempotencyKey) {\n\t\t\t\tconst existing = this.readIdempotentEventUnlocked(input.idempotencyKey);\n\t\t\t\tif (existing) return { event: existing, appended: false };\n\t\t\t}\n\t\t\tif (options.expectedLastOrdinal !== undefined) {\n\t\t\t\tif (actual !== options.expectedLastOrdinal) {\n\t\t\t\t\tthrow new OrchestrationConcurrencyError(options.expectedLastOrdinal, actual);\n\t\t\t\t}\n\t\t\t}\n\n\t\t\tconst ordinal = actual + 1;\n\t\t\tconst next: OrchestrationEvent = {\n\t\t\t\tschemaVersion: ORCHESTRATION_SCHEMA_VERSION,\n\t\t\t\tordinal,\n\t\t\t\teventId: this.createEventId(),\n\t\t\t\ttype: input.type,\n\t\t\t\taggregateId: input.aggregateId,\n\t\t\t\tactor: input.actor,\n\t\t\t\toccurredAt: this.now(),\n\t\t\t\t...(input.correlationId ? { correlationId: input.correlationId } : {}),\n\t\t\t\t...(input.causationId ? { causationId: input.causationId } : {}),\n\t\t\t\t...(input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {}),\n\t\t\t\tpayload: structuredClone(input.payload),\n\t\t\t};\n\t\t\tconst serializedEvent = serializeBounded(\n\t\t\t\tnext,\n\t\t\t\tthis.maxTailBytes,\n\t\t\t\t\"Orchestration event\",\n\t\t\t\t\"Orchestration event exceeds its configured tail byte limit.\",\n\t\t\t);\n\t\t\tconst serializedMarker = input.idempotencyKey\n\t\t\t\t? this.serializeIdempotencyMarker(input.idempotencyKey, ordinal)\n\t\t\t\t: undefined;\n\t\t\tconst serializedCursor = serializeBounded(\n\t\t\t\t{\n\t\t\t\t\tversion: 1,\n\t\t\t\t\tlastOrdinal: ordinal,\n\t\t\t\t\ttailBytes: cursor.tailBytes + Buffer.byteLength(serializedEvent),\n\t\t\t\t} satisfies EventCursor,\n\t\t\t\tMAX_CURSOR_BYTES,\n\t\t\t\t\"Orchestration cursor\",\n\t\t\t);\n\t\t\twriteFileAtomicSync(join(this.eventsDir, eventFileName(ordinal)), serializedEvent);\n\t\t\tif (input.idempotencyKey && serializedMarker) {\n\t\t\t\tthis.writeIdempotencyMarkerUnlocked(input.idempotencyKey, serializedMarker);\n\t\t\t}\n\t\t\twriteFileAtomicSync(this.cursorPath, serializedCursor);\n\t\t\treturn { event: next, appended: true };\n\t\t});\n\n\t\tif (committed.appended) {\n\t\t\tfor (const listener of this.listeners) listener(structuredClone(committed.event));\n\t\t}\n\t\treturn structuredClone(committed.event);\n\t}\n\n\treadAll(): OrchestrationEvent[] {\n\t\treturn this.readAllUnlocked();\n\t}\n\n\treadAfter(ordinal: number): OrchestrationEvent[] {\n\t\tconst baseline = this.readBaselineUnlocked();\n\t\tif (baseline && ordinal < baseline.throughOrdinal) {\n\t\t\tthrow new OrchestrationSnapshotRequiredError(baseline.throughOrdinal);\n\t\t}\n\t\tconst events: OrchestrationEvent[] = [];\n\t\tconst names = this.eventFileNamesUnlocked();\n\t\tthis.assertReadableTailUnlocked(names, baseline?.throughOrdinal ?? 0);\n\t\tlet previousOrdinal = ordinal;\n\t\tfor (const name of names) {\n\t\t\tconst match = EVENT_FILE_PATTERN.exec(name);\n\t\t\tif (!match) continue;\n\t\t\tconst fileOrdinal = Number(match[1]);\n\t\t\tif (fileOrdinal <= ordinal) continue;\n\t\t\tconst event = this.readEventFileUnlocked(name);\n\t\t\tif (event.ordinal !== fileOrdinal || event.ordinal <= previousOrdinal) {\n\t\t\t\tthrow new OrchestrationEventStoreError(`Non-monotonic orchestration event ordinal in ${name}`);\n\t\t\t}\n\t\t\tpreviousOrdinal = event.ordinal;\n\t\t\tevents.push(structuredClone(event));\n\t\t}\n\t\treturn events;\n\t}\n\n\treadProjectionSnapshot(): { throughOrdinal: number; projection: JsonObject } | undefined {\n\t\tconst snapshot = this.readProjectionSnapshotUnlocked();\n\t\treturn snapshot\n\t\t\t? { throughOrdinal: snapshot.throughOrdinal, projection: structuredClone(snapshot.projection) }\n\t\t\t: undefined;\n\t}\n\n\t/** Replace a large replay prefix with one verified current-state snapshot and a bounded tail. */\n\tcompactIfNeeded(throughOrdinal: number, projection: () => JsonObject): boolean {\n\t\tconst baselineBeforeLock = this.readBaselineUnlocked()?.throughOrdinal ?? 0;\n\t\tconst cursorBeforeLock = parseCursor(this.cursorPath);\n\t\tif (\n\t\t\tcursorBeforeLock?.lastOrdinal === throughOrdinal &&\n\t\t\tcursorBeforeLock.tailBytes !== undefined &&\n\t\t\tthroughOrdinal - baselineBeforeLock < this.maxTailEvents &&\n\t\t\tcursorBeforeLock.tailBytes < this.maxTailBytes\n\t\t) {\n\t\t\treturn false;\n\t\t}\n\t\treturn withFileLockSync(this.cursorPath, () => {\n\t\t\tconst cursor = this.synchronizeIndexesUnlocked();\n\t\t\tif (cursor.lastOrdinal !== throughOrdinal) return false;\n\t\t\tconst baselineOrdinal = this.readBaselineUnlocked()?.throughOrdinal ?? 0;\n\t\t\tconst tailNames = this.eventFileNamesUnlocked().filter(\n\t\t\t\t(name) => Number(EVENT_FILE_PATTERN.exec(name)?.[1] ?? 0) > baselineOrdinal,\n\t\t\t);\n\t\t\tif (tailNames.length < this.maxTailEvents && cursor.tailBytes < this.maxTailBytes) return false;\n\n\t\t\tconst retainedByKey = new Map<string, OrchestrationEvent>();\n\t\t\tfor (const event of this.readProjectionSnapshotUnlocked()?.idempotencyEvents ?? []) {\n\t\t\t\tif (event.idempotencyKey) retainedByKey.set(event.idempotencyKey, event);\n\t\t\t}\n\t\t\tfor (const name of tailNames) {\n\t\t\t\tconst event = this.readEventFileUnlocked(name);\n\t\t\t\tif (event.ordinal <= throughOrdinal && event.idempotencyKey) {\n\t\t\t\t\tretainedByKey.set(event.idempotencyKey, event);\n\t\t\t\t}\n\t\t\t}\n\t\t\tconst idempotencyEvents = [...retainedByKey.values()]\n\t\t\t\t.sort((left, right) => left.ordinal - right.ordinal)\n\t\t\t\t.slice(-this.maxIdempotencyEvents)\n\t\t\t\t.map((event) => structuredClone(event));\n\t\t\tconst content: ProjectionSnapshotContent = {\n\t\t\t\tversion: 1,\n\t\t\t\tschemaVersion: ORCHESTRATION_SCHEMA_VERSION,\n\t\t\t\tthroughOrdinal,\n\t\t\t\tcreatedAt: this.now(),\n\t\t\t\tprojection: structuredClone(projection()),\n\t\t\t\tidempotencyEvents,\n\t\t\t};\n\t\t\tconst digest = snapshotDigest(content);\n\t\t\tconst snapshotFile = eventFileName(throughOrdinal);\n\t\t\tconst serializedSnapshot = serializeBounded(\n\t\t\t\t{ ...content, digest } satisfies ProjectionSnapshot,\n\t\t\t\tMAX_PROJECTION_SNAPSHOT_BYTES,\n\t\t\t\t\"Orchestration projection snapshot\",\n\t\t\t);\n\t\t\tconst serializedBaseline = serializeBounded(\n\t\t\t\t{ version: 1, throughOrdinal, digest, snapshotFile } satisfies SnapshotBaseline,\n\t\t\t\tMAX_BASELINE_BYTES,\n\t\t\t\t\"Orchestration snapshot baseline\",\n\t\t\t);\n\t\t\tconst serializedCursor = serializeBounded(\n\t\t\t\t{ version: 1, lastOrdinal: throughOrdinal, tailBytes: 0 } satisfies EventCursor,\n\t\t\t\tMAX_CURSOR_BYTES,\n\t\t\t\t\"Orchestration cursor\",\n\t\t\t);\n\t\t\twriteFileAtomicSync(join(this.snapshotsDir, snapshotFile), serializedSnapshot);\n\t\t\twriteFileAtomicSync(this.baselinePath, serializedBaseline);\n\n\t\t\tfor (const name of this.idempotencyFileNamesUnlocked()) {\n\t\t\t\tthis.unlinkManagedFile(join(this.idempotencyDir, name));\n\t\t\t}\n\t\t\tfor (const name of this.eventFileNamesUnlocked()) {\n\t\t\t\tconst ordinal = Number(EVENT_FILE_PATTERN.exec(name)?.[1] ?? 0);\n\t\t\t\tif (ordinal <= throughOrdinal) this.unlinkManagedFile(join(this.eventsDir, name));\n\t\t\t}\n\t\t\tfor (const name of this.snapshotFileNamesUnlocked()) {\n\t\t\t\tif (name !== snapshotFile) this.unlinkManagedFile(join(this.snapshotsDir, name));\n\t\t\t}\n\t\t\twriteFileAtomicSync(this.cursorPath, serializedCursor);\n\t\t\treturn true;\n\t\t});\n\t}\n\n\tsubscribe(listener: (event: OrchestrationEvent) => void): () => void {\n\t\tthis.listeners.add(listener);\n\t\treturn () => this.listeners.delete(listener);\n\t}\n\n\tprivate readAllUnlocked(): OrchestrationEvent[] {\n\t\tconst names = this.eventFileNamesUnlocked();\n\t\tconst events: OrchestrationEvent[] = [];\n\t\tconst baselineOrdinal = this.readProjectionSnapshotUnlocked()?.throughOrdinal ?? 0;\n\t\tthis.assertReadableTailUnlocked(names, baselineOrdinal);\n\t\tlet previousOrdinal = baselineOrdinal;\n\t\tfor (const name of names) {\n\t\t\tconst match = EVENT_FILE_PATTERN.exec(name);\n\t\t\tif (!match) continue;\n\t\t\tconst fileOrdinal = Number(match[1]);\n\t\t\tif (fileOrdinal <= baselineOrdinal) continue;\n\t\t\tconst parsed = this.readEventFileUnlocked(name);\n\t\t\tif (parsed.ordinal !== fileOrdinal || parsed.ordinal <= previousOrdinal) {\n\t\t\t\tthrow new OrchestrationEventStoreError(`Non-monotonic orchestration event ordinal in ${name}`);\n\t\t\t}\n\t\t\tpreviousOrdinal = parsed.ordinal;\n\t\t\tevents.push(structuredClone(parsed));\n\t\t}\n\t\treturn events;\n\t}\n\n\tprivate eventFileNamesUnlocked(): string[] {\n\t\ttry {\n\t\t\treturn readBoundedDirectoryNamesSync(\n\t\t\t\tthis.eventsDir,\n\t\t\t\tMAX_EVENT_DIRECTORY_ENTRIES,\n\t\t\t\t\"Orchestration events directory\",\n\t\t\t)\n\t\t\t\t.filter((candidate) => EVENT_FILE_PATTERN.test(candidate))\n\t\t\t\t.sort();\n\t\t} catch (error) {\n\t\t\tif ((error as NodeJS.ErrnoException).code === \"ENOENT\") return [];\n\t\t\tthrow error;\n\t\t}\n\t}\n\n\tprivate idempotencyFileNamesUnlocked(): string[] {\n\t\ttry {\n\t\t\treturn readBoundedDirectoryNamesSync(\n\t\t\t\tthis.idempotencyDir,\n\t\t\t\tMAX_IDEMPOTENCY_DIRECTORY_ENTRIES,\n\t\t\t\t\"Orchestration idempotency directory\",\n\t\t\t).filter((candidate) => candidate.endsWith(\".json\"));\n\t\t} catch (error) {\n\t\t\tif ((error as NodeJS.ErrnoException).code === \"ENOENT\") return [];\n\t\t\tthrow error;\n\t\t}\n\t}\n\n\tprivate snapshotFileNamesUnlocked(): string[] {\n\t\ttry {\n\t\t\treturn readBoundedDirectoryNamesSync(\n\t\t\t\tthis.snapshotsDir,\n\t\t\t\tMAX_SNAPSHOT_DIRECTORY_ENTRIES,\n\t\t\t\t\"Orchestration snapshots directory\",\n\t\t\t)\n\t\t\t\t.filter((candidate) => SNAPSHOT_FILE_PATTERN.test(candidate))\n\t\t\t\t.sort();\n\t\t} catch (error) {\n\t\t\tif ((error as NodeJS.ErrnoException).code === \"ENOENT\") return [];\n\t\t\tthrow error;\n\t\t}\n\t}\n\n\t/** Event files are a contiguous append-only tail after the published snapshot. */\n\tprivate assertContiguousTailOrdinalsUnlocked(names: readonly string[], baselineOrdinal: number): void {\n\t\tlet expectedOrdinal = baselineOrdinal + 1;\n\t\tfor (const name of names) {\n\t\t\tconst ordinal = Number(EVENT_FILE_PATTERN.exec(name)?.[1] ?? 0);\n\t\t\t// A crash after publishing the baseline but before pruning is safe: the snapshot covers these files.\n\t\t\tif (ordinal <= baselineOrdinal) continue;\n\t\t\tif (ordinal !== expectedOrdinal) {\n\t\t\t\tthrow new OrchestrationEventStoreError(\n\t\t\t\t\t`Missing orchestration event ordinal ${expectedOrdinal} before ${name}.`,\n\t\t\t\t);\n\t\t\t}\n\t\t\texpectedOrdinal++;\n\t\t}\n\t}\n\n\t/** A valid cursor may lag a newly published snapshot, but it must never lead its committed tail. */\n\tprivate assertReadableTailUnlocked(names: readonly string[], baselineOrdinal: number): void {\n\t\tthis.assertContiguousTailOrdinalsUnlocked(names, baselineOrdinal);\n\t\tconst highestEventOrdinal = names.length > 0 ? Number(EVENT_FILE_PATTERN.exec(names.at(-1)!)?.[1] ?? 0) : 0;\n\t\tconst highestCommittedOrdinal = Math.max(baselineOrdinal, highestEventOrdinal);\n\t\tconst cursor = parseCursor(this.cursorPath);\n\t\tif (cursor && cursor.lastOrdinal > highestCommittedOrdinal) {\n\t\t\tthrow new OrchestrationEventStoreError(\n\t\t\t\t`Orchestration cursor ${cursor.lastOrdinal} is ahead of the last committed event ${highestCommittedOrdinal}.`,\n\t\t\t);\n\t\t}\n\t}\n\n\tprivate readBaselineUnlocked(): SnapshotBaseline | undefined {\n\t\tif (!existsSync(this.baselinePath)) return undefined;\n\t\tlet parsed: unknown;\n\t\ttry {\n\t\t\tparsed = JSON.parse(\n\t\t\t\treadBoundedTextFileSync(this.baselinePath, MAX_BASELINE_BYTES, \"Orchestration snapshot baseline\"),\n\t\t\t);\n\t\t} catch (error) {\n\t\t\tthrow new OrchestrationEventStoreError(\n\t\t\t\t`Failed to parse orchestration snapshot baseline: ${error instanceof Error ? error.message : String(error)}`,\n\t\t\t);\n\t\t}\n\t\tif (!parsed || typeof parsed !== \"object\" || Array.isArray(parsed)) {\n\t\t\tthrow new OrchestrationEventStoreError(\"Invalid orchestration snapshot baseline.\");\n\t\t}\n\t\tconst baseline = parsed as Record<string, unknown>;\n\t\tif (\n\t\t\tbaseline.version !== 1 ||\n\t\t\t!Number.isSafeInteger(baseline.throughOrdinal) ||\n\t\t\tNumber(baseline.throughOrdinal) < 1 ||\n\t\t\ttypeof baseline.digest !== \"string\" ||\n\t\t\tbaseline.digest.length === 0 ||\n\t\t\ttypeof baseline.snapshotFile !== \"string\" ||\n\t\t\t!SNAPSHOT_FILE_PATTERN.test(baseline.snapshotFile) ||\n\t\t\tNumber(SNAPSHOT_FILE_PATTERN.exec(baseline.snapshotFile)?.[1] ?? 0) !== Number(baseline.throughOrdinal)\n\t\t) {\n\t\t\tthrow new OrchestrationEventStoreError(\"Invalid orchestration snapshot baseline.\");\n\t\t}\n\t\treturn {\n\t\t\tversion: 1,\n\t\t\tthroughOrdinal: Number(baseline.throughOrdinal),\n\t\t\tdigest: baseline.digest,\n\t\t\tsnapshotFile: baseline.snapshotFile,\n\t\t};\n\t}\n\n\tprivate readProjectionSnapshotUnlocked(): ProjectionSnapshot | undefined {\n\t\tconst baseline = this.readBaselineUnlocked();\n\t\tif (!baseline) return undefined;\n\t\tlet parsed: unknown;\n\t\ttry {\n\t\t\tparsed = JSON.parse(\n\t\t\t\treadBoundedTextFileSync(\n\t\t\t\t\tjoin(this.snapshotsDir, baseline.snapshotFile),\n\t\t\t\t\tMAX_PROJECTION_SNAPSHOT_BYTES,\n\t\t\t\t\t\"Orchestration projection snapshot\",\n\t\t\t\t),\n\t\t\t);\n\t\t} catch (error) {\n\t\t\tthrow new OrchestrationEventStoreError(\n\t\t\t\t`Failed to parse orchestration projection snapshot: ${error instanceof Error ? error.message : String(error)}`,\n\t\t\t);\n\t\t}\n\t\tif (!parsed || typeof parsed !== \"object\" || Array.isArray(parsed)) {\n\t\t\tthrow new OrchestrationEventStoreError(\"Invalid orchestration projection snapshot.\");\n\t\t}\n\t\tconst snapshot = parsed as Record<string, unknown>;\n\t\tif (\n\t\t\tsnapshot.version !== 1 ||\n\t\t\tsnapshot.schemaVersion !== ORCHESTRATION_SCHEMA_VERSION ||\n\t\t\tsnapshot.throughOrdinal !== baseline.throughOrdinal ||\n\t\t\ttypeof snapshot.createdAt !== \"string\" ||\n\t\t\t!snapshot.projection ||\n\t\t\ttypeof snapshot.projection !== \"object\" ||\n\t\t\tArray.isArray(snapshot.projection) ||\n\t\t\t!Array.isArray(snapshot.idempotencyEvents) ||\n\t\t\tsnapshot.idempotencyEvents.length > this.maxIdempotencyEvents ||\n\t\t\t!snapshot.idempotencyEvents.every(isOrchestrationEvent) ||\n\t\t\t!snapshot.idempotencyEvents.every(\n\t\t\t\t(event) => event.ordinal <= baseline.throughOrdinal && event.idempotencyKey !== undefined,\n\t\t\t) ||\n\t\t\tnew Set(snapshot.idempotencyEvents.map((event) => event.idempotencyKey)).size !==\n\t\t\t\tsnapshot.idempotencyEvents.length ||\n\t\t\ttypeof snapshot.digest !== \"string\" ||\n\t\t\tsnapshot.digest !== baseline.digest\n\t\t) {\n\t\t\tthrow new OrchestrationEventStoreError(\"Invalid orchestration projection snapshot.\");\n\t\t}\n\t\tconst content: ProjectionSnapshotContent = {\n\t\t\tversion: 1,\n\t\t\tschemaVersion: ORCHESTRATION_SCHEMA_VERSION,\n\t\t\tthroughOrdinal: baseline.throughOrdinal,\n\t\t\tcreatedAt: snapshot.createdAt,\n\t\t\tprojection: structuredClone(snapshot.projection) as JsonObject,\n\t\t\tidempotencyEvents: snapshot.idempotencyEvents.map((event) => structuredClone(event)),\n\t\t};\n\t\tif (snapshotDigest(content) !== baseline.digest) {\n\t\t\tthrow new OrchestrationEventStoreError(\"Orchestration projection snapshot digest mismatch.\");\n\t\t}\n\t\treturn { ...content, digest: baseline.digest };\n\t}\n\n\t/**\n\t * Appends need a verified snapshot baseline but must not deserialize its projection on every event.\n\t * The baseline pointer remains small and is reread each time; an immutable snapshot is reparsed only\n\t * when its pointer or filesystem identity changes.\n\t */\n\tprivate readVerifiedSnapshotBaselineUnlocked(): SnapshotBaseline | undefined {\n\t\tconst baseline = this.readBaselineUnlocked();\n\t\tif (!baseline) {\n\t\t\tthis.verifiedSnapshotBaseline = undefined;\n\t\t\treturn undefined;\n\t\t}\n\t\tconst signature = this.snapshotFileSignatureUnlocked(baseline);\n\t\tconst cached = this.verifiedSnapshotBaseline;\n\t\tif (\n\t\t\tcached &&\n\t\t\tcached.baseline.throughOrdinal === baseline.throughOrdinal &&\n\t\t\tcached.baseline.digest === baseline.digest &&\n\t\t\tcached.baseline.snapshotFile === baseline.snapshotFile &&\n\t\t\tcached.signature.size === signature.size &&\n\t\t\tcached.signature.mtimeMs === signature.mtimeMs &&\n\t\t\tcached.signature.ctimeMs === signature.ctimeMs\n\t\t) {\n\t\t\treturn baseline;\n\t\t}\n\t\tthis.readProjectionSnapshotUnlocked();\n\t\tconst verifiedSignature = this.snapshotFileSignatureUnlocked(baseline);\n\t\tif (\n\t\t\tverifiedSignature.size !== signature.size ||\n\t\t\tverifiedSignature.mtimeMs !== signature.mtimeMs ||\n\t\t\tverifiedSignature.ctimeMs !== signature.ctimeMs\n\t\t) {\n\t\t\tthrow new OrchestrationEventStoreError(\"Orchestration projection snapshot changed while being verified.\");\n\t\t}\n\t\tthis.verifiedSnapshotBaseline = { baseline, signature };\n\t\treturn baseline;\n\t}\n\n\tprivate snapshotFileSignatureUnlocked(baseline: SnapshotBaseline): SnapshotFileSignature {\n\t\ttry {\n\t\t\tconst stats = statSync(join(this.snapshotsDir, baseline.snapshotFile));\n\t\t\tif (!stats.isFile())\n\t\t\t\tthrow new OrchestrationEventStoreError(\"Orchestration projection snapshot is not a file.\");\n\t\t\treturn { size: stats.size, mtimeMs: stats.mtimeMs, ctimeMs: stats.ctimeMs };\n\t\t} catch (error) {\n\t\t\tif (error instanceof OrchestrationEventStoreError) throw error;\n\t\t\tthrow new OrchestrationEventStoreError(\n\t\t\t\t`Failed to parse orchestration projection snapshot: ${error instanceof Error ? error.message : String(error)}`,\n\t\t\t);\n\t\t}\n\t}\n\n\tprivate unlinkManagedFile(filePath: string): void {\n\t\ttry {\n\t\t\tunlinkSync(filePath);\n\t\t} catch (error) {\n\t\t\tif ((error as NodeJS.ErrnoException).code !== \"ENOENT\") throw error;\n\t\t}\n\t}\n\n\tprivate readEventFileUnlocked(name: string): OrchestrationEvent {\n\t\tlet parsed: unknown;\n\t\ttry {\n\t\t\tparsed = JSON.parse(\n\t\t\t\treadBoundedTextFileSync(join(this.eventsDir, name), this.maxTailBytes, `Orchestration event ${name}`),\n\t\t\t);\n\t\t} catch (error) {\n\t\t\tthrow new OrchestrationEventStoreError(\n\t\t\t\t`Failed to parse orchestration event ${name}: ${error instanceof Error ? error.message : String(error)}`,\n\t\t\t);\n\t\t}\n\t\tif (!isOrchestrationEvent(parsed)) {\n\t\t\tthrow new OrchestrationEventStoreError(`Invalid orchestration event record: ${name}`);\n\t\t}\n\t\treturn parsed;\n\t}\n\n\tprivate idempotencyPath(key: string): string {\n\t\treturn join(this.idempotencyDir, `${createHash(\"sha256\").update(key).digest(\"hex\")}.json`);\n\t}\n\n\tprivate serializeIdempotencyMarker(key: string, ordinal: number): string {\n\t\treturn serializeBounded(\n\t\t\t{ version: 1, key, ordinal } satisfies IdempotencyMarker,\n\t\t\tMAX_IDEMPOTENCY_MARKER_BYTES,\n\t\t\t\"Orchestration idempotency marker\",\n\t\t);\n\t}\n\n\tprivate writeIdempotencyMarkerUnlocked(key: string, serializedMarker: string): void {\n\t\twriteFileAtomicSync(this.idempotencyPath(key), serializedMarker);\n\t}\n\n\tprivate readIdempotentEventUnlocked(key: string): OrchestrationEvent | undefined {\n\t\tconst markerPath = this.idempotencyPath(key);\n\t\tif (!existsSync(markerPath)) {\n\t\t\treturn this.readProjectionSnapshotUnlocked()?.idempotencyEvents.find((event) => event.idempotencyKey === key);\n\t\t}\n\t\tlet parsed: unknown;\n\t\ttry {\n\t\t\tparsed = JSON.parse(\n\t\t\t\treadBoundedTextFileSync(markerPath, MAX_IDEMPOTENCY_MARKER_BYTES, \"Orchestration idempotency marker\"),\n\t\t\t);\n\t\t} catch (error) {\n\t\t\tthrow new OrchestrationEventStoreError(\n\t\t\t\t`Failed to parse orchestration idempotency marker: ${error instanceof Error ? error.message : String(error)}`,\n\t\t\t);\n\t\t}\n\t\tif (!parsed || typeof parsed !== \"object\" || Array.isArray(parsed)) {\n\t\t\tthrow new OrchestrationEventStoreError(\"Invalid orchestration idempotency marker.\");\n\t\t}\n\t\tconst marker = parsed as Record<string, unknown>;\n\t\tif (\n\t\t\tmarker.version !== 1 ||\n\t\t\tmarker.key !== key ||\n\t\t\t!Number.isSafeInteger(marker.ordinal) ||\n\t\t\tNumber(marker.ordinal) < 1\n\t\t) {\n\t\t\tthrow new OrchestrationEventStoreError(\"Invalid orchestration idempotency marker.\");\n\t\t}\n\t\tconst ordinal = Number(marker.ordinal);\n\t\tif (!existsSync(join(this.eventsDir, eventFileName(ordinal)))) {\n\t\t\tconst retained = this.readProjectionSnapshotUnlocked()?.idempotencyEvents.find(\n\t\t\t\t(event) => event.idempotencyKey === key && event.ordinal === ordinal,\n\t\t\t);\n\t\t\tif (retained) return retained;\n\t\t}\n\t\tconst event = this.readEventFileUnlocked(eventFileName(ordinal));\n\t\tif (event.ordinal !== ordinal || event.idempotencyKey !== key) {\n\t\t\tthrow new OrchestrationEventStoreError(\"Orchestration idempotency marker does not match its event.\");\n\t\t}\n\t\treturn event;\n\t}\n\n\t/**\n\t * Reconcile only the crash tail when an event rename committed before its marker/cursor. Normal\n\t * appends read directory metadata plus one marker, never the accumulated event payload prefix.\n\t */\n\tprivate synchronizeIndexesUnlocked(): SynchronizedIndexes {\n\t\tconst names = this.eventFileNamesUnlocked();\n\t\tconst baselineOrdinal = this.readVerifiedSnapshotBaselineUnlocked()?.throughOrdinal ?? 0;\n\t\tthis.assertReadableTailUnlocked(names, baselineOrdinal);\n\t\tconst highestEventOrdinal = names.length > 0 ? Number(EVENT_FILE_PATTERN.exec(names.at(-1)!)?.[1] ?? 0) : 0;\n\t\tconst highest = Math.max(baselineOrdinal, highestEventOrdinal);\n\t\tconst cursor = parseCursor(this.cursorPath);\n\t\tif (\n\t\t\tcursor?.lastOrdinal === highest &&\n\t\t\tcursor.tailBytes !== undefined &&\n\t\t\t(highest > baselineOrdinal || cursor.tailBytes === 0)\n\t\t) {\n\t\t\treturn { lastOrdinal: highest, tailBytes: cursor.tailBytes };\n\t\t}\n\t\tif (cursor && cursor.lastOrdinal > highest) {\n\t\t\tthrow new OrchestrationEventStoreError(\n\t\t\t\t`Orchestration cursor ${cursor.lastOrdinal} is ahead of the last committed event ${highest}.`,\n\t\t\t);\n\t\t}\n\t\tconst rebuildFrom = Math.max(\n\t\t\tbaselineOrdinal + 1,\n\t\t\tcursor && cursor.lastOrdinal >= baselineOrdinal && cursor.lastOrdinal <= highest\n\t\t\t\t? cursor.lastOrdinal + 1\n\t\t\t\t: baselineOrdinal + 1,\n\t\t);\n\t\tfor (const name of names) {\n\t\t\tconst ordinal = Number(EVENT_FILE_PATTERN.exec(name)?.[1] ?? 0);\n\t\t\tif (ordinal < rebuildFrom || ordinal <= baselineOrdinal) continue;\n\t\t\tconst event = this.readEventFileUnlocked(name);\n\t\t\tif (event.ordinal !== ordinal) {\n\t\t\t\tthrow new OrchestrationEventStoreError(`Event ordinal does not match file name: ${name}`);\n\t\t\t}\n\t\t\tif (event.idempotencyKey) {\n\t\t\t\tthis.writeIdempotencyMarkerUnlocked(\n\t\t\t\t\tevent.idempotencyKey,\n\t\t\t\t\tthis.serializeIdempotencyMarker(event.idempotencyKey, ordinal),\n\t\t\t\t);\n\t\t\t}\n\t\t}\n\t\tconst tailBytes = names.reduce((total, name) => {\n\t\t\tconst ordinal = Number(EVENT_FILE_PATTERN.exec(name)?.[1] ?? 0);\n\t\t\tif (ordinal <= baselineOrdinal) return total;\n\t\t\ttry {\n\t\t\t\treturn total + statSync(join(this.eventsDir, name)).size;\n\t\t\t} catch {\n\t\t\t\treturn total;\n\t\t\t}\n\t\t}, 0);\n\t\twriteFileAtomicSync(\n\t\t\tthis.cursorPath,\n\t\t\tserializeBounded(\n\t\t\t\t{ version: 1, lastOrdinal: highest, tailBytes } satisfies EventCursor,\n\t\t\t\tMAX_CURSOR_BYTES,\n\t\t\t\t\"Orchestration cursor\",\n\t\t\t),\n\t\t);\n\t\treturn { lastOrdinal: highest, tailBytes };\n\t}\n}\n"]}

package/dist/core/orchestration/event-store.js

@@ -1,14 +1,26 @@
 import { createHash, randomUUID } from "node:crypto";
-import { existsSync, readdirSync, readFileSync, statSync, unlinkSync } from "node:fs";
+import { existsSync, statSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
-import { stateFile } from "../agent-paths.js";
+import { orchestrationEventStoreDir } from "../agent-paths.js";
 import { withFileLockSync, writeFileAtomicSync } from "../util/atomic-file.js";
+import { readBoundedDirectoryNamesSync, readBoundedTextFileSync } from "../util/bounded-file.js";
 import { isOrchestrationEvent, ORCHESTRATION_SCHEMA_VERSION, } from "./contracts.js";
 const EVENT_FILE_PATTERN = /^(\d{16})\.json$/;
 const SNAPSHOT_FILE_PATTERN = /^(\d{16})\.json$/;
 const DEFAULT_MAX_TAIL_EVENTS = 256;
 const DEFAULT_MAX_TAIL_BYTES = 4 * 1024 * 1024;
 const DEFAULT_MAX_IDEMPOTENCY_EVENTS = 512;
+const MAX_CONFIGURED_TAIL_EVENTS = 1_024;
+const MAX_CONFIGURED_TAIL_BYTES = 16 * 1024 * 1024;
+const MAX_CONFIGURED_IDEMPOTENCY_EVENTS = 1_024;
+const MAX_EVENT_DIRECTORY_ENTRIES = 2_048;
+const MAX_IDEMPOTENCY_DIRECTORY_ENTRIES = 2_048;
+const MAX_SNAPSHOT_DIRECTORY_ENTRIES = 8;
+const MAX_CURSOR_BYTES = 64 * 1024;
+const MAX_BASELINE_BYTES = 64 * 1024;
+const MAX_IDEMPOTENCY_MARKER_BYTES = 64 * 1024;
+/** Full current task state plus retained idempotency evidence; intentionally above the 16MiB tail cap. */
+const MAX_PROJECTION_SNAPSHOT_BYTES = 32 * 1024 * 1024;
 export class OrchestrationEventStoreError extends Error {
     constructor(message) {
         super(message);
@@ -29,16 +41,18 @@ export class OrchestrationSnapshotRequiredError extends OrchestrationEventStoreE
         this.throughOrdinal = throughOrdinal;
     }
 }
-function safeSessionDirectoryName(sessionId) {
-    const readable = encodeURIComponent(sessionId).replaceAll("%", "_").slice(0, 80) || "session";
-    const digest = createHash("sha256").update(sessionId).digest("hex").slice(0, 16);
-    return `${readable}-${digest}`;
-}
 function parseCursor(filePath) {
     if (!existsSync(filePath))
         return undefined;
+    let content;
     try {
-        const parsed = JSON.parse(readFileSync(filePath, "utf-8"));
+        content = readBoundedTextFileSync(filePath, MAX_CURSOR_BYTES, "Orchestration cursor");
+    }
+    catch (error) {
+        throw new OrchestrationEventStoreError(`Failed to read orchestration cursor: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    try {
+        const parsed = JSON.parse(content);
         if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
             return undefined;
         const record = parsed;
@@ -61,17 +75,26 @@ function parseCursor(filePath) {
 function serialize(value) {
     return `${JSON.stringify(value, null, "\t")}\n`;
 }
+function serializeBounded(value, maxBytes, label, oversizedMessage = `${label} exceeds its byte limit.`) {
+    const serialized = serialize(value);
+    if (Buffer.byteLength(serialized, "utf-8") > maxBytes) {
+        throw new OrchestrationEventStoreError(oversizedMessage);
+    }
+    return serialized;
+}
 function eventFileName(ordinal) {
     return `${String(ordinal).padStart(16, "0")}.json`;
 }
 function snapshotDigest(content) {
     return createHash("sha256").update(JSON.stringify(content)).digest("hex");
 }
-function positiveSafeInteger(value, fallback, label) {
+function positiveSafeInteger(value, fallback, maximum, label) {
     const resolved = value ?? fallback;
     if (!Number.isSafeInteger(resolved) || resolved < 1) {
         throw new OrchestrationEventStoreError(`${label} must be a positive safe integer.`);
     }
+    if (resolved > maximum)
+        throw new OrchestrationEventStoreError(`${label} must not exceed ${maximum}.`);
     return resolved;
 }
 /**
@@ -95,7 +118,7 @@ export class OrchestrationEventStore {
     listeners = new Set();
     verifiedSnapshotBaseline;
     constructor(options) {
-        this.rootDir = stateFile(options.agentDir, "orchestration", safeSessionDirectoryName(options.sessionId));
+        this.rootDir = orchestrationEventStoreDir(options.agentDir, options.sessionId);
         this.eventsDir = join(this.rootDir, "events");
         this.idempotencyDir = join(this.rootDir, "idempotency");
         this.cursorPath = join(this.rootDir, "cursor.json");
@@ -103,9 +126,9 @@ export class OrchestrationEventStore {
         this.baselinePath = join(this.rootDir, "projection-baseline.json");
         this.now = options.now ?? (() => new Date().toISOString());
         this.createEventId = options.createEventId ?? randomUUID;
-        this.maxTailEvents = positiveSafeInteger(options.maxTailEvents, DEFAULT_MAX_TAIL_EVENTS, "maxTailEvents");
-        this.maxTailBytes = positiveSafeInteger(options.maxTailBytes, DEFAULT_MAX_TAIL_BYTES, "maxTailBytes");
-        this.maxIdempotencyEvents = positiveSafeInteger(options.maxIdempotencyEvents, DEFAULT_MAX_IDEMPOTENCY_EVENTS, "maxIdempotencyEvents");
+        this.maxTailEvents = positiveSafeInteger(options.maxTailEvents, DEFAULT_MAX_TAIL_EVENTS, MAX_CONFIGURED_TAIL_EVENTS, "maxTailEvents");
+        this.maxTailBytes = positiveSafeInteger(options.maxTailBytes, DEFAULT_MAX_TAIL_BYTES, MAX_CONFIGURED_TAIL_BYTES, "maxTailBytes");
+        this.maxIdempotencyEvents = positiveSafeInteger(options.maxIdempotencyEvents, DEFAULT_MAX_IDEMPOTENCY_EVENTS, MAX_CONFIGURED_IDEMPOTENCY_EVENTS, "maxIdempotencyEvents");
     }
     append(input, options = {}) {
         const committed = withFileLockSync(this.cursorPath, () => {
@@ -135,15 +158,20 @@ export class OrchestrationEventStore {
                 ...(input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {}),
                 payload: structuredClone(input.payload),
             };
-            const serializedEvent = serialize(next);
-            writeFileAtomicSync(join(this.eventsDir, eventFileName(ordinal)), serializedEvent);
-            if (input.idempotencyKey)
-                this.writeIdempotencyMarkerUnlocked(input.idempotencyKey, ordinal);
-            writeFileAtomicSync(this.cursorPath, serialize({
+            const serializedEvent = serializeBounded(next, this.maxTailBytes, "Orchestration event", "Orchestration event exceeds its configured tail byte limit.");
+            const serializedMarker = input.idempotencyKey
+                ? this.serializeIdempotencyMarker(input.idempotencyKey, ordinal)
+                : undefined;
+            const serializedCursor = serializeBounded({
                 version: 1,
                 lastOrdinal: ordinal,
                 tailBytes: cursor.tailBytes + Buffer.byteLength(serializedEvent),
-            }));
+            }, MAX_CURSOR_BYTES, "Orchestration cursor");
+            writeFileAtomicSync(join(this.eventsDir, eventFileName(ordinal)), serializedEvent);
+            if (input.idempotencyKey && serializedMarker) {
+                this.writeIdempotencyMarkerUnlocked(input.idempotencyKey, serializedMarker);
+            }
+            writeFileAtomicSync(this.cursorPath, serializedCursor);
             return { event: next, appended: true };
         });
         if (committed.appended) {
@@ -229,8 +257,11 @@ export class OrchestrationEventStore {
             };
             const digest = snapshotDigest(content);
             const snapshotFile = eventFileName(throughOrdinal);
-            writeFileAtomicSync(join(this.snapshotsDir, snapshotFile), serialize({ ...content, digest }));
-            writeFileAtomicSync(this.baselinePath, serialize({ version: 1, throughOrdinal, digest, snapshotFile }));
+            const serializedSnapshot = serializeBounded({ ...content, digest }, MAX_PROJECTION_SNAPSHOT_BYTES, "Orchestration projection snapshot");
+            const serializedBaseline = serializeBounded({ version: 1, throughOrdinal, digest, snapshotFile }, MAX_BASELINE_BYTES, "Orchestration snapshot baseline");
+            const serializedCursor = serializeBounded({ version: 1, lastOrdinal: throughOrdinal, tailBytes: 0 }, MAX_CURSOR_BYTES, "Orchestration cursor");
+            writeFileAtomicSync(join(this.snapshotsDir, snapshotFile), serializedSnapshot);
+            writeFileAtomicSync(this.baselinePath, serializedBaseline);
             for (const name of this.idempotencyFileNamesUnlocked()) {
                 this.unlinkManagedFile(join(this.idempotencyDir, name));
             }
@@ -243,7 +274,7 @@ export class OrchestrationEventStore {
                 if (name !== snapshotFile)
                     this.unlinkManagedFile(join(this.snapshotsDir, name));
             }
-            writeFileAtomicSync(this.cursorPath, serialize({ version: 1, lastOrdinal: throughOrdinal, tailBytes: 0 }));
+            writeFileAtomicSync(this.cursorPath, serializedCursor);
             return true;
         });
     }
@@ -275,7 +306,7 @@ export class OrchestrationEventStore {
     }
     eventFileNamesUnlocked() {
         try {
-            return readdirSync(this.eventsDir)
+            return readBoundedDirectoryNamesSync(this.eventsDir, MAX_EVENT_DIRECTORY_ENTRIES, "Orchestration events directory")
                 .filter((candidate) => EVENT_FILE_PATTERN.test(candidate))
                 .sort();
         }
@@ -287,20 +318,24 @@ export class OrchestrationEventStore {
     }
     idempotencyFileNamesUnlocked() {
         try {
-            return readdirSync(this.idempotencyDir).filter((candidate) => candidate.endsWith(".json"));
+            return readBoundedDirectoryNamesSync(this.idempotencyDir, MAX_IDEMPOTENCY_DIRECTORY_ENTRIES, "Orchestration idempotency directory").filter((candidate) => candidate.endsWith(".json"));
         }
-        catch {
-            return [];
+        catch (error) {
+            if (error.code === "ENOENT")
+                return [];
+            throw error;
         }
     }
     snapshotFileNamesUnlocked() {
         try {
-            return readdirSync(this.snapshotsDir)
+            return readBoundedDirectoryNamesSync(this.snapshotsDir, MAX_SNAPSHOT_DIRECTORY_ENTRIES, "Orchestration snapshots directory")
                 .filter((candidate) => SNAPSHOT_FILE_PATTERN.test(candidate))
                 .sort();
         }
-        catch {
-            return [];
+        catch (error) {
+            if (error.code === "ENOENT")
+                return [];
+            throw error;
         }
     }
     /** Event files are a contiguous append-only tail after the published snapshot. */
@@ -332,7 +367,7 @@ export class OrchestrationEventStore {
             return undefined;
         let parsed;
         try {
-            parsed = JSON.parse(readFileSync(this.baselinePath, "utf-8"));
+            parsed = JSON.parse(readBoundedTextFileSync(this.baselinePath, MAX_BASELINE_BYTES, "Orchestration snapshot baseline"));
         }
         catch (error) {
             throw new OrchestrationEventStoreError(`Failed to parse orchestration snapshot baseline: ${error instanceof Error ? error.message : String(error)}`);
@@ -364,7 +399,7 @@ export class OrchestrationEventStore {
             return undefined;
         let parsed;
         try {
-            parsed = JSON.parse(readFileSync(join(this.snapshotsDir, baseline.snapshotFile), "utf-8"));
+            parsed = JSON.parse(readBoundedTextFileSync(join(this.snapshotsDir, baseline.snapshotFile), MAX_PROJECTION_SNAPSHOT_BYTES, "Orchestration projection snapshot"));
         }
         catch (error) {
             throw new OrchestrationEventStoreError(`Failed to parse orchestration projection snapshot: ${error instanceof Error ? error.message : String(error)}`);
@@ -381,6 +416,7 @@ export class OrchestrationEventStore {
             typeof snapshot.projection !== "object" ||
             Array.isArray(snapshot.projection) ||
             !Array.isArray(snapshot.idempotencyEvents) ||
+            snapshot.idempotencyEvents.length > this.maxIdempotencyEvents ||
             !snapshot.idempotencyEvents.every(isOrchestrationEvent) ||
             !snapshot.idempotencyEvents.every((event) => event.ordinal <= baseline.throughOrdinal && event.idempotencyKey !== undefined) ||
             new Set(snapshot.idempotencyEvents.map((event) => event.idempotencyKey)).size !==
@@ -459,7 +495,7 @@ export class OrchestrationEventStore {
     readEventFileUnlocked(name) {
         let parsed;
         try {
-            parsed = JSON.parse(readFileSync(join(this.eventsDir, name), "utf-8"));
+            parsed = JSON.parse(readBoundedTextFileSync(join(this.eventsDir, name), this.maxTailBytes, `Orchestration event ${name}`));
         }
         catch (error) {
             throw new OrchestrationEventStoreError(`Failed to parse orchestration event ${name}: ${error instanceof Error ? error.message : String(error)}`);
@@ -472,8 +508,11 @@ export class OrchestrationEventStore {
     idempotencyPath(key) {
         return join(this.idempotencyDir, `${createHash("sha256").update(key).digest("hex")}.json`);
     }
-    writeIdempotencyMarkerUnlocked(key, ordinal) {
-        writeFileAtomicSync(this.idempotencyPath(key), serialize({ version: 1, key, ordinal }));
+    serializeIdempotencyMarker(key, ordinal) {
+        return serializeBounded({ version: 1, key, ordinal }, MAX_IDEMPOTENCY_MARKER_BYTES, "Orchestration idempotency marker");
+    }
+    writeIdempotencyMarkerUnlocked(key, serializedMarker) {
+        writeFileAtomicSync(this.idempotencyPath(key), serializedMarker);
     }
     readIdempotentEventUnlocked(key) {
         const markerPath = this.idempotencyPath(key);
@@ -482,7 +521,7 @@ export class OrchestrationEventStore {
         }
         let parsed;
         try {
-            parsed = JSON.parse(readFileSync(markerPath, "utf-8"));
+            parsed = JSON.parse(readBoundedTextFileSync(markerPath, MAX_IDEMPOTENCY_MARKER_BYTES, "Orchestration idempotency marker"));
         }
         catch (error) {
             throw new OrchestrationEventStoreError(`Failed to parse orchestration idempotency marker: ${error instanceof Error ? error.message : String(error)}`);
@@ -539,8 +578,9 @@ export class OrchestrationEventStore {
             if (event.ordinal !== ordinal) {
                 throw new OrchestrationEventStoreError(`Event ordinal does not match file name: ${name}`);
             }
-            if (event.idempotencyKey)
-                this.writeIdempotencyMarkerUnlocked(event.idempotencyKey, ordinal);
+            if (event.idempotencyKey) {
+                this.writeIdempotencyMarkerUnlocked(event.idempotencyKey, this.serializeIdempotencyMarker(event.idempotencyKey, ordinal));
+            }
         }
         const tailBytes = names.reduce((total, name) => {
             const ordinal = Number(EVENT_FILE_PATTERN.exec(name)?.[1] ?? 0);
@@ -553,7 +593,7 @@ export class OrchestrationEventStore {
                 return total;
             }
         }, 0);
-        writeFileAtomicSync(this.cursorPath, serialize({ version: 1, lastOrdinal: highest, tailBytes }));
+        writeFileAtomicSync(this.cursorPath, serializeBounded({ version: 1, lastOrdinal: highest, tailBytes }, MAX_CURSOR_BYTES, "Orchestration cursor"));
         return { lastOrdinal: highest, tailBytes };
     }
 }