@loomwork/compliance 0.0.0-stage → 0.1.0

package/src/exportSubject.ts

@@ -0,0 +1,326 @@
+import type { EventEnvelope, ExecutionState } from "@loomwork/core";
+import {
+  type DestructionProof,
+  type EventStore,
+  erasureWindowView,
+  isPayloadShredded,
+} from "@loomwork/event-runtime";
+import { foldEvents } from "@loomwork/replay-vm";
+import type { SubjectIndex } from "./SubjectIndex";
+import { claimCheckRefsOf } from "./eraseSubject";
+
+// ── T3-R2/R3 — subject access & portability (GDPR Art. 15/20) ──────────────────
+//
+// An access/portability request is a fold: gather the subject's executions (from the
+// SubjectIndex), read each execution's log, fold it to state. Event-sourcing makes the
+// authoritative answer already-present — this just assembles it into a portable shape.
+//
+// Note on erased subjects: if a field was crypto-shredded, reading through a default
+// EncryptingEventStore THROWS (G1). Export a partially-erased subject through a store in
+// tolerant mode (`onShredded: "tolerate"`, K10-R4) — the shredded fields come back as
+// `{ $shredded }` and the export honestly shows what remains rather than failing.
+
+/**
+ * A range of an execution's ORIGINAL log that neither the surviving log nor the compaction archive
+ * holds as events (structurally `LogLifecycle.archiveCoverage`'s `UnarchivedRange`). `"legacy"`:
+ * removed by a compaction that predates the archive; only its folded checkpoint remains
+ * (`legacyCheckpoints`, when the archive preserved it). `"missing"`: an archiving compaction removed
+ * it and no archive segment holds it now (a wiped, swapped or truncated archive).
+ */
+export interface UnarchivedRange {
+  readonly from: number;
+  readonly through: number;
+  readonly why: "legacy" | "missing";
+}
+
+/**
+ * ADR 0140 - one claim-checked tool output a subject's log cites, RESOLVED from the content store: the log
+ * holds only `{ ref, size, digest }`, so an access/portability export that returned the envelope alone
+ * would omit the data. `value` is the decoded JSON; `bytesBase64` a stream-typed (non-JSON) blob;
+ * `missing` a blob the store no longer holds (erased or reclaimed).
+ */
+export interface ClaimCheckedBlob {
+  /** The blob's content address. */
+  address: string;
+  size?: number;
+  digest?: unknown;
+  value?: unknown;
+  bytesBase64?: string;
+  missing?: true;
+  /**
+   * ADR 0143 D5/D8: the log CITES this address, but a sealing store could not prove the subject owns the
+   * blob (another subject's, absent, or corrupt): it is NOT the subject's data, so nothing of it (not even
+   * the cited size) is reported. Never present beside `value`/`bytesBase64`.
+   */
+  foreign?: true;
+}
+
+/** One execution's contribution to a subject export. */
+export interface SubjectExecutionExport {
+  executionId: string;
+  workflowId: string;
+  status: ExecutionState["status"];
+  /** Folded state — the Art. 15 "access" view (the current data held about the subject). */
+  state: ExecutionState;
+  /** Raw event log — the Art. 20 "portability" view (machine-readable). Omitted if not requested. */
+  events?: EventEnvelope[];
+  /**
+   * ADR 0140 - the claim-checked tool outputs this execution's events cite, resolved (see
+   * {@link ClaimCheckedBlob}). Present only when `content` was given and the log cites any.
+   */
+  claimChecked?: ClaimCheckedBlob[];
+  /**
+   * ADR 0138 - checkpoints of a log compacted BEFORE the compaction archive existed (their removed
+   * events survive only as a folded state). Present only when such an execution is exported.
+   */
+  legacyCheckpoints?: unknown[];
+  /**
+   * ADR 0139 - the reserved streams (inbox, topic streams, quarantine copies) of the chain this execution
+   * heads, with the envelopes (ids, timestamps, sender metadata) a trim or delete MOVED to the archive,
+   * and every range nothing can return. Present only when the archive holds such a stream.
+   */
+  reservedStreams?: Array<{
+    streamId: string;
+    events: EventEnvelope[];
+    unarchived: UnarchivedRange[];
+  }>;
+  /**
+   * ADR 0138 - EVERY range of this execution's original log the export could not return as events
+   * (see {@link UnarchivedRange}); `[]` is a complete log. Present whenever an `archive` was given, so
+   * a data subject (or their processor) can see each gap instead of a silently shorter export. The
+   * `events` and `state` of an execution with a non-empty list are INCOMPLETE for those ranges.
+   * Absent only when the execution was read through the crypto-shred erasure window (its log is
+   * unreadable by design) or no archive was configured.
+   */
+  unarchived?: UnarchivedRange[];
+  /**
+   * `true` when this execution was read through the crypto-shred erasure window (the key is
+   * destroyed, the tombstone not yet written): the export is the redacted view and `unarchived` is
+   * absent BECAUSE of that, not because the archive is complete.
+   */
+  erasureWindow?: true;
+}
+
+/** A subject's full data export across every execution concerning them. */
+export interface SubjectExport {
+  subjectId: string;
+  executions: SubjectExecutionExport[];
+}
+
+export interface ExportSubjectOptions {
+  index: SubjectIndex;
+  eventStore: Pick<EventStore, "read">;
+  /**
+   * ADR 0138 - the compaction archive's audit read (`LogLifecycle`). Compaction MOVES events out of the
+   * log into the archive, and an Art. 15/20 export that read only the surviving log would omit the
+   * subject's data and fold a compacted log wrongly. Given this, each execution is read as
+   * `archive ∪ log` (and folded from that). A range only a pre-archive checkpoint remembers is
+   * returned in `legacyCheckpoints`, and every range the archive and log together cannot show is
+   * listed in each execution's `unarchived` (never silently dropped).
+   */
+  archive?: {
+    archiveCoverage(
+      executionId: string
+    ): Promise<{ readonly unarchived: readonly UnarchivedRange[] }>;
+    readWithArchive(
+      executionId: string,
+      opts?: { readonly allowIncomplete?: boolean }
+    ): Promise<EventEnvelope[]>;
+    readLegacyCheckpoints?(executionId: string): Promise<unknown[]>;
+    /**
+     * ADR 0139 - the reserved streams of the chain this execution heads (inbox, topic streams,
+     * quarantine copies) with the envelopes a trim or delete MOVED to the archive, and every range
+     * nothing can return. `LogLifecycle.readReservedArchive`.
+     */
+    readReservedArchive?(executionId: string): Promise<
+      Array<{
+        streamId: string;
+        events: EventEnvelope[];
+        unarchived: readonly UnarchivedRange[];
+      }>
+    >;
+  };
+  /**
+   * ADR 0140 - the content store claim-checked tool outputs were offloaded to. Given, each execution's
+   * export resolves the blobs its events cite (`claimChecked`), so the export is the data, not just refs.
+   */
+  content?: {
+    get(
+      ref: { __loomContent: string },
+      access?: { executionId: string; workflowId: string }
+    ): Promise<Uint8Array | null>;
+    /** A sealing store's ownership proof (ADR 0143 D5): asked before a cited blob is opened. */
+    ownedBy?(
+      ref: { __loomContent: string },
+      access: { executionId: string; workflowId: string }
+    ): Promise<boolean>;
+  };
+  /** Include the raw event log per execution (Art. 20 portability). Default `true`. */
+  includeEvents?: boolean;
+  /** T3-R2.4 — scope the export to a tenant (default: the single partition). */
+  tenant?: string;
+  /**
+   * ADR 0130 D7 (round 5) - proof that the key store destroyed the subject's key
+   * (`(s) => keys.wasDestroyed(s)`). A PROOF function only: returning `true` for a key that was
+   * NOT destroyed in the authoritative store produces a false erasure view, so never stub it (use
+   * the per-call {@link ExportSubjectOptions.force} for the operator's assertion). Without it, a stream whose key is unavailable is
+   * REFUSED (`KeyUnavailableError`) even if the log records an erase intent: a dangling intent
+   * (the key still lives elsewhere) is not an erasure.
+   */
+  destroyed?: DestructionProof;
+  /**
+   * ADR 0130 D7 (round 6) - OPERATOR OVERRIDE, per call (mirrors `ShredOptions.force`): asserts the
+   * key was destroyed in the authoritative key store, for a store that cannot prove it. A wrong
+   * assertion exports a redacted view of a subject whose key lives on.
+   */
+  force?: "key-destroyed-elsewhere";
+}
+
+/**
+ * Assemble a data-subject export (Art. 15 access + Art. 20 portability): every execution the
+ * {@link SubjectIndex} attributes to `subjectId` (within `tenant`), each folded to its current
+ * state and (by default) accompanied by its raw log. Executions are emitted in the index's
+ * deterministic (sorted) order. An unknown subject yields an empty `executions` array — not an
+ * error. Scoping to a tenant is what keeps one tenant's `"alice"` out of another's export.
+ */
+export async function exportSubject(
+  subjectId: string,
+  options: ExportSubjectOptions
+): Promise<SubjectExport> {
+  const includeEvents = options.includeEvents ?? true;
+  const executionIds = options.index.executionsOf(subjectId, options.tenant);
+  const executions: SubjectExecutionExport[] = [];
+  for (const executionId of executionIds) {
+    let events: EventEnvelope[];
+    let unarchived: UnarchivedRange[] | undefined;
+    let erasureWindow = false;
+    try {
+      events =
+        options.archive !== undefined
+          ? await options.archive.readWithArchive(executionId, { allowIncomplete: true })
+          : await options.eventStore.read(executionId);
+      if (options.archive !== undefined) {
+        unarchived = [...(await options.archive.archiveCoverage(executionId)).unarchived];
+      }
+    } catch (err) {
+      // The ShredIncomplete window (key destroyed, tombstone not yet written): the redacted view,
+      // only with the log's durable erase intent. A node that lacks the key is not an erasure.
+      const window = await erasureWindowView(
+        err,
+        options.force === "key-destroyed-elsewhere" ? () => true : options.destroyed
+      );
+      if (window === undefined) throw err;
+      events = [...window];
+      erasureWindow = true;
+      unarchived = undefined;
+    }
+    if (events.length === 0) continue; // deleted (retention) — nothing left to export
+    // Seed the fold with identity — foldEvents takes executionId/workflowId from `initial`,
+    // not the events, so an unseeded fold would carry empty identity fields.
+    const workflowId = events[0]?.workflowId ?? "";
+    const state = foldEvents(events, { executionId, workflowId });
+    const legacy = (await options.archive?.readLegacyCheckpoints?.(executionId)) ?? [];
+    // (not through the erasure window: the log is unreadable by design there)
+    const reserved = erasureWindow
+      ? []
+      : ((await options.archive?.readReservedArchive?.(executionId)) ?? []);
+    const claimChecked =
+      options.content === undefined
+        ? []
+        : await resolveBlobs(options.content, events, { executionId, workflowId });
+    executions.push({
+      executionId,
+      workflowId,
+      status: state.status,
+      state,
+      ...(includeEvents && { events }),
+      ...(claimChecked.length > 0 && { claimChecked }),
+      ...(legacy.length > 0 && { legacyCheckpoints: legacy }),
+      ...(reserved.length > 0 && {
+        reservedStreams: reserved.map((r) => ({ ...r, unarchived: [...r.unarchived] })),
+      }),
+      ...(unarchived !== undefined && { unarchived }),
+      ...(erasureWindow && { erasureWindow: true as const }),
+    });
+  }
+  return { subjectId, executions };
+}
+
+/** Resolve every claim-check envelope the events cite (deduped by address), in first-seen order. */
+async function resolveBlobs(
+  content: NonNullable<ExportSubjectOptions["content"]>,
+  events: readonly EventEnvelope[],
+  // ADR 0143: the execution the blobs belong to, so a store that seals per subject opens them with its key.
+  access: { executionId: string; workflowId: string }
+): Promise<ClaimCheckedBlob[]> {
+  const meta = new Map<string, { size?: number; digest?: unknown; codec?: string }>();
+  for (const e of events) collectEnvelopes(e.payload, meta);
+  const out: ClaimCheckedBlob[] = [];
+  for (const [address, m] of meta) {
+    let bytes: Uint8Array | null;
+    try {
+      // A log may CITE a blob it never put (an input, a resume payload, a child's result): over a sealing
+      // store the subject must PROVE ownership before the blob is opened or reported as theirs.
+      if (
+        typeof content.ownedBy === "function" &&
+        !(await content.ownedBy({ __loomContent: address }, access))
+      ) {
+        out.push({ address, foreign: true });
+        continue;
+      }
+      bytes = await content.get({ __loomContent: address }, access);
+    } catch (err) {
+      // A sealed blob whose subject key was destroyed is ERASED (the redacted view shows it as missing);
+      // a key merely absent from this node, or an unopenable OWNED blob, stays loud: never garbage, never a lie.
+      if (!isPayloadShredded(err)) throw err;
+      bytes = null;
+    }
+    const base = {
+      address,
+      ...(m.size !== undefined && { size: m.size }),
+      ...(m.digest !== undefined && { digest: m.digest }),
+    };
+    if (bytes === null) {
+      out.push({ ...base, missing: true });
+    } else if (m.codec === undefined || m.codec === "json") {
+      out.push({ ...base, value: JSON.parse(new TextDecoder().decode(bytes)) as unknown });
+    } else {
+      out.push({ ...base, bytesBase64: Buffer.from(bytes).toString("base64") });
+    }
+  }
+  return out;
+}
+
+function collectEnvelopes(
+  value: unknown,
+  into: Map<string, { size?: number; digest?: unknown; codec?: string }>
+): void {
+  const addresses = claimCheckRefsOf(value);
+  if (addresses.size === 0) return;
+  const stack: unknown[] = [value];
+  const seen = new WeakSet<object>();
+  while (stack.length > 0) {
+    const cur = stack.pop();
+    if (typeof cur !== "object" || cur === null || seen.has(cur)) continue;
+    seen.add(cur);
+    const env = cur as {
+      __loomClaimCheck?: unknown;
+      ref?: { __loomContent?: unknown };
+      size?: unknown;
+      digest?: unknown;
+      codec?: unknown;
+    };
+    const address = env.__loomClaimCheck === true ? env.ref?.__loomContent : undefined;
+    if (typeof address === "string" && !into.has(address)) {
+      into.set(address, {
+        ...(typeof env.size === "number" && { size: env.size }),
+        ...(env.digest !== undefined && { digest: env.digest }),
+        ...(typeof env.codec === "string" && { codec: env.codec }),
+      });
+    }
+    for (const [k, item] of Object.entries(cur)) {
+      if (typeof address === "string" && k === "ref") continue;
+      stack.push(item);
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,36 @@
+export {
+  DEFAULT_TENANT,
+  SubjectIndex,
+  type SubjectIndexOptions,
+  type SubjectResolver,
+  type TenantResolver,
+} from "./SubjectIndex";
+export {
+  exportSubject,
+  type ExportSubjectOptions,
+  type ClaimCheckedBlob,
+  type SubjectExecutionExport,
+  type SubjectExport,
+  type UnarchivedRange,
+} from "./exportSubject";
+export {
+  ArchivedCopiesRemainError,
+  ContentCopiesRemainError,
+  ControlStreamKeyError,
+  claimCheckRefsOf,
+  trustedClaimCheckRefsOf,
+  SenderRedactionUnsupportedError,
+  defaultSenderMatches,
+  EraseCoordinator,
+  ERASURE_STREAM,
+  type ArchivedCopiesDeleted,
+  type ContentCopiesDeleted,
+  type ErasableContent,
+  type EraseCoordinatorOptions,
+  type ErasableArchive,
+  type SenderMatcher,
+  type SenderRedaction,
+  type EraseSubjectOptions,
+  type EraseSubjectResult,
+  type Shredder,
+} from "./eraseSubject";