@loomwork/event-runtime 0.0.0-stage → 0.1.0

package/src/index.ts

@@ -0,0 +1,151 @@
+export { TenantScopedEventStore } from "./TenantScopedEventStore";
+export { CoalescingEventStore } from "./CoalescingEventStore";
+export type { InboxStreams } from "./types";
+export type { CoalescingEventStoreOptions } from "./CoalescingEventStore";
+export type { DestructionProof } from "./keyUnavailable";
+export {
+  KEY_UNAVAILABLE_CODE,
+  KeyUnavailableError,
+  erasureWindowView,
+  isErasureWindow,
+  isKeyUnavailable,
+  recordsErasureIntent,
+} from "./keyUnavailable";
+export {
+  PAYLOAD_SHREDDED_BRAND,
+  brandPayloadShredded,
+  isPayloadShredded,
+} from "./payloadShredded";
+export { ShardSealingMismatchError, ShardedEventStore } from "./ShardedEventStore";
+export type { MigrationResult, ShardedEventStoreOptions } from "./ShardedEventStore";
+export { ShardPlan, DEFAULT_BUCKETS } from "./ShardPlan";
+export type { ShardPlacement, ShardPlanJSON } from "./ShardPlan";
+export { SubscriberRegistry, bucketOf } from "./SubscriberRegistry";
+export { ProfilingEventStore } from "./ProfilingEventStore";
+export type { WriteProfile } from "./ProfilingEventStore";
+export { InMemoryAsyncEventStore } from "./InMemoryAsyncEventStore";
+export { compareExecutionIds } from "./executionIdOrder";
+export type { InMemoryAsyncEventStoreOptions } from "./InMemoryAsyncEventStore";
+export type {
+  AcquireFenceIfResult,
+  AppendIfUnchangedResult,
+  TipObservation,
+  EventStore,
+  EventStoreOptions,
+  ExecutionEnumerable,
+  ExecutionPage,
+  OptionalEventStoreMethod,
+  SealMarker,
+  SealingCapability,
+  AtRestEventReader,
+} from "./types";
+export {
+  decoratedInnerOf,
+  forwardStoreMarkers,
+  installOptional,
+  refusalsOf,
+} from "./installOptional";
+export type { DecoratorPlan } from "./installOptional";
+export {
+  OPTIONAL_EVENT_STORE_METHODS,
+  headOf,
+  readRangeOf,
+  appendBatchOf,
+  INBOX_STREAM_PREFIX,
+  INBOX_TOPIC_SEQ_BASE,
+  INBOX_REGISTRY_SUFFIX,
+  INBOX_LAYOUT_STREAM,
+  QUARANTINE_STREAM_PREFIX,
+  quarantineStreamId,
+  chainIdOfFirst,
+  hasInboxStreamShape,
+  inboxChainOf,
+  RESERVED_LATE_PREFIX,
+  archiveChainOf,
+  reservedLateKey,
+  reservedLateOrigin,
+  inboxRegistryStreamId,
+  inboxStreamsOfChain,
+  inboxStreamsOfChainDeep,
+  inboxTopicHash,
+  inboxTopicStreamId,
+  isReservedStream,
+  iterateExecutionIds,
+  RESERVED_STREAM_PREFIX,
+  EVENT_STORE_SPI_VERSION,
+} from "./types";
+export { StaleFenceError, fenceOf } from "./fencing";
+export { creationMarker } from "./creationMarker";
+export {
+  EVENT_KIND_CLASS,
+  isAnsweringKind,
+  isQuiescent,
+  type EventKindClass,
+} from "./eventKindClass";
+export {
+  InMemoryLeaseStore,
+  LEASE_STORE_SPI_VERSION,
+  assertNoBatchSteal,
+  assertSteal,
+  assertTtl,
+  type AcquireOptions,
+  type InMemoryLeaseStoreOptions,
+  type Lease,
+  type LeaseStore,
+  type StealProof,
+} from "./leases";
+export { DuplicateEnvelopeIdError, DuplicateSequenceError } from "./writeConflicts";
+export { lowerBoundBySequence, sliceBySequence } from "./sequenceRange";
+export { InMemoryBranchRegistry } from "./InMemoryBranchRegistry";
+export type { InMemoryBranchRegistryOptions } from "./InMemoryBranchRegistry";
+export { InMemoryTimerStore } from "./timers";
+export type { TimerRecord, TimerStore } from "./timers";
+export type {
+  BranchRef,
+  BranchRegistry,
+  LineageRecord,
+  ListRefsOptions,
+  PromoteOptions,
+} from "./BranchRegistry";
+export {
+  BRANCH_REGISTRY_SPI_VERSION,
+  BranchPromotionConflictError,
+  assertListRefsLimit,
+} from "./BranchRegistry";
+export {
+  ARCHIVE_STORE_SPI_VERSION,
+  ArchiveConflictError,
+  ArchiveDigestError,
+  ArchiveIncarnationError,
+  ArchiveUnserializableError,
+  ARCHIVE_LEGACY_CHECKPOINT_EVENT,
+  OPTIONAL_ARCHIVE_STORE_METHODS,
+  assertReplaceable,
+  classifyAppend,
+  headerOf,
+} from "./archiveSpi";
+export type {
+  ArchiveExecutionPage,
+  ArchiveSegment,
+  ArchiveSegmentHeader,
+  ArchiveSegmentKind,
+  ArchiveStore,
+} from "./archiveSpi";
+export {
+  SENDER_ERASED,
+  archivedReservedStreams,
+  assertReservedSegmentDigest,
+  assertSegmentDigest,
+  buildReservedSegment,
+  buildSegment,
+  isSenderErased,
+  maskSender,
+  pageIds,
+  reservedSegmentDigest,
+  sameReservedEnvelope,
+  segmentDigest,
+  senderDigestOf,
+  senderErasedMarker,
+} from "./archive";
+export { TenantScopedArchiveStore } from "./TenantScopedArchiveStore";
+export { InMemoryArchiveStore } from "./InMemoryArchiveStore";

package/src/installOptional.ts

@@ -0,0 +1,136 @@
+/**
+ * How a store decorator handles one OPTIONAL SPI method of the store it wraps (ADR 0074
+ * Amendment, L1):
+ *
+ * - `"forward"` — call the inner store's method verbatim (bound to the inner store);
+ * - a function — the decorator's own implementation (it transforms ids, payloads, …);
+ * - `{ refuse: reason }` — deliberately NOT offered, with the reason recorded. The method is
+ *   left uninstalled, so callers see exactly what they see for a store without it.
+ *
+ * What the compiler enforces: every key in `M` is REQUIRED (`-?` strips the `?` a mapped type
+ * over `S` would otherwise inherit from the optional SPI methods). So a decorator whose plan is
+ * `satisfies DecoratorPlan<EventStore, OptionalEventStoreMethod>` fails to compile if it omits
+ * any optional method — including one added to the SPI later, since `OptionalEventStoreMethod`
+ * is derived from the interface. Pinned by `decoratorPlan.typecheck.ts`, which `pnpm typecheck`
+ * checks. What it cannot enforce: that a decorator uses a plan at all — that is the decorator
+ * conformance kit's job, and the `packages/spec` fitness test makes every decorator run it.
+ */
+export type DecoratorPlan<S, M extends keyof S> = {
+  readonly [K in M]-?: "forward" | NonNullable<S[K]> | { readonly refuse: string };
+};
+
+// Refusals, keyed by the decorated object. A WeakMap so a discarded store takes its entry
+// with it; read back by the decorator conformance kit through `refusalsOf`.
+const refusals = new WeakMap<object, ReadonlyMap<string, string>>();
+
+/**
+ * The encryption-boundary marker a store exposes structurally (`EncryptingEventStore.keys`,
+ * `EncryptingSnapshotStore.keys`). `loom doctor` and `LogLifecycle`'s compaction/archive
+ * guard read it by shape, so a decorator stacked ABOVE an encrypting store must carry it up —
+ * otherwise `Coalescing(Encrypting(pg))` looks like a plain store and compaction would write
+ * the decrypted fold to a plaintext snapshot store (ADR 0022 Amendment).
+ */
+const ENCRYPTION_MARKER = "keys";
+/** `EncryptingSnapshotStore.sealsWholeState` (ADR 0130 D8), carried up the same way. */
+const WHOLE_STATE_MARKER = "sealsWholeState";
+
+/**
+ * Install each optional method of `plan` on `target`, **iff the inner store has it** — so a
+ * capability probe (`if (store.copyPrefix)`) answers exactly as it would against `inner`,
+ * and a decorator never advertises a capability its backend lacks. O(|M|) once, at
+ * construction; zero cost per call (a forward is a bound method, not a trampoline).
+ *
+ * A function entry is bound to `bindTo` when given (a decorator whose implementation uses
+ * `this`), else installed as-is. `{ refuse }` entries are recorded for {@link refusalsOf}.
+ *
+ * Also carries the inner store's structural encryption marker (`keys`) onto `target` when
+ * `target` does not define its own — see {@link ENCRYPTION_MARKER}.
+ */
+export function installOptional<S extends object, M extends keyof S>(
+  target: S,
+  inner: S,
+  plan: DecoratorPlan<S, M>,
+  bindTo?: object
+): void {
+  const writable = target as Record<PropertyKey, unknown>;
+  const source = inner as Record<PropertyKey, unknown>;
+  let refused: Map<string, string> | undefined;
+  for (const method of Object.keys(plan) as M[]) {
+    const entry = plan[method] as unknown;
+    if (typeof entry === "object" && entry !== null) {
+      refused ??= new Map();
+      refused.set(String(method), (entry as { refuse: string }).refuse);
+      continue;
+    }
+    const innerMethod = source[method as PropertyKey];
+    if (typeof innerMethod !== "function") continue; // the backend lacks it: so do we
+    if (entry === "forward") {
+      writable[method as PropertyKey] = (innerMethod as (...a: unknown[]) => unknown).bind(inner);
+    } else if (typeof entry === "function") {
+      writable[method as PropertyKey] =
+        bindTo === undefined ? entry : (entry as (...a: unknown[]) => unknown).bind(bindTo);
+    }
+  }
+  if (refused !== undefined) refusals.set(target, refused);
+  forwardStoreMarkers(target, inner);
+}
+
+/** `TenantScopedEventStore.tenantScope` (and the archive/snapshot twins), carried up the same way (ADR 0138 H3). */
+const TENANT_MARKER = "tenantScope";
+
+/**
+ * ADR 0141 - the snapshot codec a store WRITES (`"none" | "zstd"`), carried up through every snapshot
+ * decorator so the composition root (`defineConfig`) reads what the outermost store really does and can
+ * refuse a mismatch, instead of the opt-in being silently dropped by a wrapper.
+ */
+const CODEC_MARKER = "snapshotCodec";
+
+// Who a decorator wraps, keyed by the decorator: lets a guard walk a stack whose layers hide their
+// inner store (a closure-built decorator exposes no `inner`). A WeakMap, so it never keeps a store alive.
+const wrapped = new WeakMap<object, object>();
+
+/** The store `target` was built over (recorded by {@link forwardStoreMarkers}), or `undefined`. */
+export function decoratedInnerOf(target: object): object | undefined {
+  return wrapped.get(target);
+}
+
+/**
+ * Carry the STRUCTURAL markers other layers read by shape from `inner` up to the decorator `target`
+ * (unless `target` defines its own): the encryption marker `keys`, `sealsWholeState` (ADR 0130 D8) and
+ * the tenant marker `tenantScope` (ADR 0138 H3), the snapshot codec marker `snapshotCodec` (ADR 0141), and record `target` as wrapping `inner`. EVERY store
+ * decorator (event, snapshot, archive) must call this - {@link installOptional} does - or a guard that
+ * reads a marker on the outermost store sees a plain, unscoped one. The decorator conformance kit
+ * asserts it for each decorator in the repo.
+ */
+export function forwardStoreMarkers(target: object, inner: object): void {
+  const writable = target as Record<PropertyKey, unknown>;
+  const source = inner as Record<PropertyKey, unknown>;
+  wrapped.set(target, inner);
+  const marker = source[ENCRYPTION_MARKER];
+  if (typeof marker === "object" && marker !== null && writable[ENCRYPTION_MARKER] === undefined) {
+    writable[ENCRYPTION_MARKER] = marker;
+  }
+  // ADR 0130 D8 - a snapshot store that seals its WHOLE state says so structurally; a decorator
+  // above it must not hide that (the doctor / kernel would read a sealed store as plaintext).
+  if (source[WHOLE_STATE_MARKER] === true && writable[WHOLE_STATE_MARKER] === undefined) {
+    writable[WHOLE_STATE_MARKER] = true;
+  }
+  // ADR 0138 H3 - a decorator above a tenant-scoped store is still scoped to that tenant.
+  const tenant = source[TENANT_MARKER];
+  if (typeof tenant === "string" && writable[TENANT_MARKER] === undefined) {
+    writable[TENANT_MARKER] = tenant;
+  }
+  // ADR 0141 - a decorator above a codec-writing snapshot store still writes that codec.
+  const codec = source[CODEC_MARKER];
+  if ((codec === "none" || codec === "zstd") && writable[CODEC_MARKER] === undefined) {
+    writable[CODEC_MARKER] = codec;
+  }
+}
+
+/**
+ * The optional methods a decorator deliberately refused through {@link installOptional},
+ * with their reasons. Empty for a store that refused nothing (or did not use the helper).
+ */
+export function refusalsOf(store: object): ReadonlyMap<string, string> {
+  return refusals.get(store) ?? new Map();
+}

package/src/keyUnavailable.ts

@@ -0,0 +1,98 @@
+import type { EventEnvelope } from "@loomwork/core";
+
+/** The stable `code` of {@link KeyUnavailableError}. */
+export const KEY_UNAVAILABLE_CODE = "KEY_UNAVAILABLE" as const;
+
+/**
+ * ADR 0130 residuals D7 - a sealing store holds ciphertext for a subject whose key THIS node's key
+ * store does not have, and the log carries NO `PAYLOAD_SHREDDED` tombstone for it: the node is
+ * misconfigured (a different or empty key store), not erased. It is deliberately not
+ * `PayloadShreddedError`, which stays exclusively the erasure outcome. Lives beside the store error
+ * contract so the kernel can recognise it without depending on the crypto plugin.
+ *
+ * Carries the subject id and stream id, never ciphertext or key material. The kernel translates it
+ * to a denial-shaped `SealedStreamUnreadableError` (operator-only detail `key-unavailable`).
+ */
+export class KeyUnavailableError extends Error {
+  readonly code = KEY_UNAVAILABLE_CODE;
+  constructor(
+    readonly subjectId: string,
+    readonly streamId?: string,
+    /** The stream's workflow id (a plaintext column), so the kernel can word its refusal. */
+    readonly workflowId?: string,
+    /**
+     * The stream with each sealed field replaced by a placeholder (its status and tip are
+     * plaintext). Lets the erasure lifecycle (`EraseCoordinator`, `exportSubject`) judge a stream
+     * in the ShredIncomplete window (key destroyed, tombstone not yet written). Never ciphertext.
+     */
+    readonly redacted?: readonly EventEnvelope[]
+  ) {
+    super(
+      `the encryption key for subject "${subjectId}"${streamId ? ` (stream "${streamId}")` : ""} is not available to this node and the log records no erasure (no PAYLOAD_SHREDDED): this node's key store lacks the key. It is not a crypto-shred.`
+    );
+    this.name = "KeyUnavailableError";
+    Object.setPrototypeOf(this, KeyUnavailableError.prototype);
+  }
+}
+
+/** True for a {@link KeyUnavailableError}, by its stable `code` (survives duplicate package copies). */
+export function isKeyUnavailable(e: unknown): e is KeyUnavailableError {
+  return (e as { code?: unknown } | null)?.code === KEY_UNAVAILABLE_CODE;
+}
+
+/**
+ * ADR 0130 residuals D7 (round 4) - does this stream carry the DURABLE ERASE INTENT of `subjectId`?
+ * `shredSubject` appends an `ERASURE_PENDING` (an existing, ignorable, pure-audit kernel kind) naming
+ * the key's subject to each affected execution's log BEFORE it destroys the key. It is the only
+ * evidence that distinguishes the ShredIncomplete window (key destroyed, tombstone not yet written:
+ * intent present) from a node that simply never had the key (no intent). `subjectId` omitted accepts
+ * any intent.
+ */
+export function recordsErasureIntent(
+  events: readonly Pick<EventEnvelope, "eventType" | "payload">[],
+  subjectId?: string
+): boolean {
+  return events.some(
+    (e) =>
+      e.eventType === "ERASURE_PENDING" &&
+      (subjectId === undefined ||
+        (e.payload as { subjectId?: unknown } | null)?.subjectId === subjectId)
+  );
+}
+
+/**
+ * ADR 0130 D7 (round 5) - proof that the KEY STORE destroyed `subjectId`'s key (`KeyStore.wasDestroyed`,
+ * or the operator's explicit assertion `() => true`). The log proves intent, never destruction.
+ */
+export type DestructionProof = (subjectId: string) => boolean | Promise<boolean>;
+
+/**
+ * The retry window, decided: a {@link KeyUnavailableError} carrying a redacted view is the genuine
+ * ShredIncomplete window ONLY when that view records this subject's erase intent AND `destroyed`
+ * proves the key store destroyed the key (a dangling intent whose key still lives elsewhere is not
+ * the window). No proof, or a false one, fails closed. Returns the redacted view in that case,
+ * `undefined` otherwise (the caller rethrows).
+ */
+export async function erasureWindowView(
+  err: unknown,
+  destroyed?: DestructionProof
+): Promise<readonly EventEnvelope[] | undefined> {
+  if (!isKeyUnavailable(err) || !err.redacted) return undefined;
+  return (await isErasureWindow(err, err.redacted, destroyed)) ? err.redacted : undefined;
+}
+
+/**
+ * The ONE gate of the retry window: `err` is a {@link KeyUnavailableError} AND `events` (the
+ * stream's log, redacted or raw) records this subject's erase intent AND `destroyed` proves the key
+ * store destroyed the key. Every read in the window (event log, sealed checkpoint) uses it, so
+ * they cannot drift. No proof, or a false one, fails closed.
+ */
+export async function isErasureWindow(
+  err: unknown,
+  events: readonly Pick<EventEnvelope, "eventType" | "payload">[],
+  destroyed?: DestructionProof
+): Promise<boolean> {
+  if (!isKeyUnavailable(err)) return false;
+  if (!recordsErasureIntent(events, err.subjectId)) return false;
+  return destroyed !== undefined && (await destroyed(err.subjectId)) === true;
+}