@ultimat3/jobs 29.3.2 → 30.0.0

package/src/subject-export-pass.ts

@@ -0,0 +1,228 @@
+// One `subjectExport()` pass: every table the subject reaches and every target, one object per
+// page (`<prefix>/<table>/part-NNNNN.<ext>`), then `<prefix>/index.json` naming each table, its
+// count and its treatment. Sealed columns never leave; a page is a step, so a killed run resumes.
+
+import { assert } from '@ultimat3/core';
+import { sealedFields } from '@ultimat3/entity';
+import { JobAbortedError } from './errors';
+import { DEFAULT_EXPORT_MAX_PART_BYTES } from './export';
+import { ExportPartTooLargeError } from './export-errors';
+import type { ExportFormat, ExportRecord, ExportValue } from './export-format';
+import { encodeExportPage } from './export-format';
+import type { ExportSink } from './export-sink';
+import { exportPartKey } from './export-sink';
+import type { StepApi } from './steps-api';
+import type { SubjectTargetEntry, SubjectTreatment } from './subject';
+import { isRetainedTarget, targetOf } from './subject';
+import type { SubjectReader, SubjectRow } from './subject-select';
+import { rowIdentity } from './subject-select';
+
+/** One line of the index: what the subject's data in one table is, and what the erase does to it. */
+export interface SubjectIndexEntry {
+  readonly name: string;
+  readonly kind: 'table' | 'target';
+  readonly treatment: 'delete' | 'anonymize' | 'retain' | 'erase';
+  /** The declared `retain` reason, printed so the person reads why a row is kept. */
+  readonly reason?: string;
+  readonly rows: number;
+  readonly parts: number;
+}
+
+export interface SubjectExportReport {
+  readonly name: string;
+  readonly prefix: string;
+  readonly indexKey: string;
+  readonly tables: readonly SubjectIndexEntry[];
+}
+
+export interface SubjectExportRun {
+  readonly name: string;
+  readonly runId: string;
+  readonly prefix: string;
+  readonly format: ExportFormat;
+  readonly sink: ExportSink;
+  readonly nowMs: () => number;
+}
+
+const hex = (bytes: Uint8Array): string =>
+  Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('');
+
+/** One stored value as a cell: an instant as ISO (UTC, zone in the string), structure as JSON. */
+export function subjectCell(value: unknown): ExportValue {
+  if (value === null || value === undefined) return null;
+  if (typeof value === 'string' || typeof value === 'boolean') return value;
+  if (typeof value === 'number') return Number.isFinite(value) ? value : String(value);
+  if (typeof value === 'bigint') return value.toString();
+  if (value instanceof Date) return Number.isNaN(value.getTime()) ? null : value.toISOString();
+  if (value instanceof Uint8Array) return hex(value);
+  return JSON.stringify(value, (_key, inner: unknown) =>
+    typeof inner === 'bigint' ? inner.toString() : inner,
+  );
+}
+
+const treatmentName = (treatment: SubjectTreatment): SubjectIndexEntry['treatment'] =>
+  treatment === 'delete' ? 'delete' : 'anonymize' in treatment ? 'anonymize' : 'retain';
+
+interface Part {
+  readonly rows: number;
+  readonly bytes: number;
+}
+
+async function writePart(
+  step: StepApi,
+  run: SubjectExportRun,
+  table: string,
+  index: number,
+  columns: readonly string[],
+  records: readonly ExportRecord[],
+): Promise<Part> {
+  const stepName = `export:${table}:${index}`;
+  return step.run(stepName, async (signal): Promise<Part> => {
+    const body = encodeExportPage({
+      subject: run.name,
+      format: run.format,
+      columns,
+      records,
+      header: index === 0,
+    });
+    if (body.byteLength > DEFAULT_EXPORT_MAX_PART_BYTES) {
+      throw new ExportPartTooLargeError({
+        export: run.name,
+        part: index,
+        bytes: body.byteLength,
+        maxBytes: DEFAULT_EXPORT_MAX_PART_BYTES,
+      });
+    }
+    if (signal.aborted) throw new JobAbortedError({ job: run.name, step: stepName });
+    await run.sink.put(exportPartKey(`${run.prefix}/${table}`, index, run.format), body);
+    return { rows: records.length, bytes: body.byteLength };
+  });
+}
+
+async function exportTable(
+  step: StepApi,
+  run: SubjectExportRun,
+  reader: SubjectReader,
+  entity: string,
+) {
+  const core = reader.core(entity);
+  const sealed = new Set(sealedFields(core).map((field) => field.property));
+  const columns = core
+    .$describe()
+    .columns.map((c) => c.property)
+    .filter((p) => !sealed.has(p));
+  const seen = new Set<string>();
+  let rows = 0;
+  let parts = 0;
+  for await (const page of reader.pages(entity)) {
+    // Deduplicated before the step, so a replay rebuilds exactly the page it checkpointed.
+    const fresh = page.filter((row: SubjectRow) => {
+      const id = rowIdentity(core, row);
+      if (seen.has(id)) return false;
+      seen.add(id);
+      return true;
+    });
+    if (fresh.length === 0) continue;
+    const records = fresh.map((row) =>
+      Object.fromEntries(columns.map((c) => [c, subjectCell(row[c])])),
+    );
+    rows += (await writePart(step, run, entity, parts, columns, records)).rows;
+    parts += 1;
+  }
+  return { rows, parts };
+}
+
+async function exportTarget(
+  step: StepApi,
+  run: SubjectExportRun,
+  reader: SubjectReader,
+  entry: SubjectTargetEntry,
+) {
+  const target = targetOf(entry);
+  let cursor: string | null = null;
+  let rows = 0;
+  let parts = 0;
+  for (let n = 0; ; n += 1) {
+    const at = cursor;
+    const page: { rows: number; cursor: string | null } = await step.run(
+      `export:target:${target.name}:${n}`,
+      async (signal) => {
+        const read = await target.exportPage(
+          { key: reader.key, row: (await reader.rootRow()) ?? {} },
+          at,
+          reader.size,
+        );
+        if (read.rows.length === 0) return { rows: 0, cursor: null };
+        if (signal.aborted) throw new JobAbortedError({ job: run.name, step: target.name });
+        const body = encodeExportPage({
+          subject: run.name,
+          format: run.format,
+          columns: target.columns,
+          records: read.rows,
+          header: n === 0,
+        });
+        await run.sink.put(exportPartKey(`${run.prefix}/${target.name}`, n, run.format), body);
+        return { rows: read.rows.length, cursor: read.cursor };
+      },
+    );
+    rows += page.rows;
+    if (page.rows > 0) parts += 1;
+    cursor = page.cursor;
+    if (cursor === null) return { rows, parts };
+  }
+}
+
+export async function subjectExportPass(
+  step: StepApi,
+  run: SubjectExportRun,
+  reader: SubjectReader,
+  targets: readonly SubjectTargetEntry[],
+): Promise<SubjectExportReport> {
+  assert(
+    run.prefix.length > 0 && !run.prefix.startsWith('/') && !run.prefix.includes('..'),
+    `subject export "${run.name}" prefix() answered "${run.prefix}", which is not a key prefix`,
+    `prefix: (input) => \`exports/\${input.orgId}/\${input.requestId}\`   # on subjectExport("${run.name}"): relative, no leading slash, no ".."`,
+  );
+  const tables: SubjectIndexEntry[] = [];
+  // The subject first: the index reads as the person, then what hangs off them.
+  for (const planned of [...reader.plan.steps].reverse()) {
+    const { rows, parts } = await exportTable(step, run, reader, planned.entity);
+    const treatment = planned.treatment;
+    tables.push({
+      name: planned.entity,
+      kind: 'table',
+      treatment: treatmentName(treatment),
+      ...(typeof treatment === 'object' && 'retain' in treatment
+        ? { reason: treatment.retain }
+        : {}),
+      rows,
+      parts,
+    });
+  }
+  for (const entry of targets) {
+    const { rows, parts } = await exportTarget(step, run, reader, entry);
+    tables.push({
+      name: targetOf(entry).name,
+      kind: 'target',
+      treatment: isRetainedTarget(entry) ? 'retain' : 'erase',
+      ...(isRetainedTarget(entry) ? { reason: entry.retain } : {}),
+      rows,
+      parts,
+    });
+  }
+  const indexKey = `${run.prefix}/index.json`;
+  await step.run('export:index', async (): Promise<null> => {
+    const index = {
+      export: run.name,
+      runId: run.runId,
+      subject: reader.plan.subject,
+      format: run.format,
+      tables,
+      // `toISOString()` is UTC and carries its zone: an instant, not a date anybody formats.
+      completedAt: new Date(run.nowMs()).toISOString(),
+    };
+    await run.sink.put(indexKey, new TextEncoder().encode(JSON.stringify(index)));
+    return null;
+  });
+  return { name: run.name, prefix: run.prefix, indexKey, tables };
+}

package/src/subject-jobs.ts

@@ -0,0 +1,121 @@
+// `subjectExport()` and `subjectErase()`: one person's data exported or erased, each a FACTORY over
+// `job()`, never a ninth primitive. Both plan the subject when a run starts and refuse an untreated
+// table before a row is touched. Who may call them is the app's action: no route, no MCP tool.
+
+import type { Clock } from '@ultimat3/core';
+import { systemClock } from '@ultimat3/core';
+import { registeredEntities } from '@ultimat3/entity';
+import type { StandardSchemaV1 } from '@ultimat3/schema';
+import type { DurationInput } from './clock';
+import { nowMs } from './clock';
+import type { ExportFormat } from './export-format';
+import type { ExportSink } from './export-sink';
+import type { JobHandle } from './job';
+import { job } from './job';
+import type { RetryPolicy } from './retry';
+import { DEFAULT_RETRY } from './retry';
+import type { StepApi } from './steps-api';
+import type { Subject } from './subject';
+import type { SubjectEraseReport } from './subject-erase-pass';
+import { subjectErasePass } from './subject-erase-pass';
+import type { SubjectExportReport } from './subject-export-pass';
+import { subjectExportPass } from './subject-export-pass';
+import type { SubjectPlan } from './subject-plan';
+import { planSubject } from './subject-plan';
+import type { SubjectReader } from './subject-select';
+import { subjectReader } from './subject-select';
+import type { JobTenant } from './tenant';
+
+export interface SubjectJobDefinition<I> {
+  /** REQUIRED: a durable key, as on `exportRows()`. */
+  readonly name: string;
+  readonly input: StandardSchemaV1<unknown, I>;
+  readonly subject: Subject<I>;
+  /** A job per tenant: `(input) => input.orgId`. Crossing tenants is the app's own loop. */
+  readonly tenant: JobTenant<I>;
+  readonly queue?: string;
+  readonly retry?: RetryPolicy;
+  readonly timeout?: DurationInput;
+}
+
+export interface SubjectExportDefinition<I> extends SubjectJobDefinition<I> {
+  /** Where the parts land — a thunk, read per write, as `exportRows()` takes it. */
+  readonly sink: () => ExportSink;
+  /** The artifact's key prefix: `<prefix>/<table>/part-00000.<ext>`, `<prefix>/index.json`. */
+  prefix(input: I): string;
+  readonly format: ExportFormat;
+  readonly clock?: Clock;
+}
+
+/** The subject planned against every registered entity, its first refusal thrown. */
+export function plannedSubject<I>(subject: Subject<I>): SubjectPlan {
+  const { plan, problems } = planSubject({
+    subject: subject.entity,
+    tables: subject.init.tables,
+    columns: subject.init.columns,
+    entries: registeredEntities(),
+  });
+  const [first] = problems;
+  if (first !== undefined) throw first;
+  return plan;
+}
+
+const readerFor = <I>(subject: Subject<I>, input: I): SubjectReader =>
+  subjectReader(subject, plannedSubject(subject), subject.init.key(input));
+
+const common = <I>(definition: SubjectJobDefinition<I>) => ({
+  name: definition.name,
+  input: definition.input,
+  tenant: definition.tenant,
+  retry: definition.retry ?? DEFAULT_RETRY,
+  ...(definition.queue === undefined ? {} : { queue: definition.queue }),
+  ...(definition.timeout === undefined ? {} : { timeout: definition.timeout }),
+});
+
+export function subjectErase<I>(definition: SubjectJobDefinition<I>): JobHandle<I> {
+  const { subject } = definition;
+  return job<I>({
+    ...common(definition),
+    // One live erase per person: a second request while one runs is the same run.
+    idempotencyKey: (input) => `${definition.name}:${subject.init.key(input)}`,
+    run: ({ step, input }): Promise<SubjectEraseReport> =>
+      subjectErasePass(step, readerFor(subject, input), subject.init.targets ?? []),
+  });
+}
+
+export function subjectExport<I>(definition: SubjectExportDefinition<I>): JobHandle<I> {
+  const { subject } = definition;
+  const clock = definition.clock ?? systemClock;
+  return job<I>({
+    ...common(definition),
+    // One live pass per artifact, derived as `exportRows()` derives it.
+    idempotencyKey: (input) => `${definition.name}:${definition.prefix(input)}`,
+    run: ({ step, input, runId }): Promise<SubjectExportReport> =>
+      subjectExportPass(
+        step,
+        {
+          name: definition.name,
+          runId,
+          prefix: definition.prefix(input),
+          format: definition.format,
+          sink: { put: (key, body) => definition.sink().put(key, body) },
+          nowMs: () => nowMs(clock),
+        },
+        readerFor(subject, input),
+        subject.init.targets ?? [],
+      ),
+  });
+}
+
+/**
+ * The erase's table passes alone, for one key, under the CALLER's context and step runner — what
+ * `subjectProof` (`@ultimat3/testing`) drives on generated rows. Targets are skipped: they hold no
+ * entity rows the proof could search, and the job is still what an app enqueues.
+ */
+export function subjectEraseTables<I>(
+  subject: Subject<I>,
+  key: string,
+  step: StepApi,
+): Promise<SubjectEraseReport> {
+  return subjectErasePass(step, subjectReader(subject, plannedSubject(subject), key), []);
+}

package/src/subject-plan.ts

@@ -0,0 +1,287 @@
+// The subject's plan, pure: which tables reach the subject (a foreign-key walk from it, continued
+// only through tables the erase deletes), how each one's rows are found, the order that deletes
+// children before parents, and every refusal of the declaration. Registry entries in, plan out.
+
+import type { UltimateError } from '@ultimat3/core';
+import type { ColumnDescription, EntityDescription, RegistryEntry } from '@ultimat3/entity';
+import type { SubjectTreatment } from './subject';
+import {
+  SubjectCycleError,
+  SubjectTableUndeclaredError,
+  SubjectTreatmentInvalidError,
+} from './subject-errors';
+
+/** How one table's rows of the subject are found: `<table>.<property>` equal to `<parent>.<key>`. */
+export interface SubjectVia {
+  readonly property: string;
+  readonly parent: string;
+  readonly parentKey: string;
+}
+
+export interface SubjectStep {
+  readonly entity: string;
+  readonly treatment: SubjectTreatment;
+  /** Empty for the subject itself, which is found by its key. */
+  readonly via: readonly SubjectVia[];
+}
+
+/** A key closing a loop: set to null on the rows naming a parent the erase deletes, before any. */
+export interface SubjectUnlink extends SubjectVia {
+  readonly entity: string;
+}
+
+export interface SubjectPlan {
+  readonly subject: string;
+  /** The subject's single primary-key property. */
+  readonly key: string;
+  readonly unlink: readonly SubjectUnlink[];
+  /** Children first, the subject last: the order an erase runs in. */
+  readonly steps: readonly SubjectStep[];
+}
+
+export interface SubjectPlanInput {
+  readonly subject: string;
+  readonly tables: Readonly<Record<string, SubjectTreatment>>;
+  readonly columns?: Readonly<Record<string, string>> | undefined;
+  readonly entries: readonly RegistryEntry[];
+}
+
+interface Edge extends SubjectVia {
+  readonly from: string;
+  readonly nullable: boolean;
+  readonly onDelete: string | null;
+}
+
+const own = <T>(record: Readonly<Record<string, T>> | undefined, key: string): T | undefined =>
+  record !== undefined && Object.hasOwn(record, key) ? record[key] : undefined;
+
+const isDelete = (treatment: SubjectTreatment | undefined): boolean => treatment === 'delete';
+
+const nulls = (treatment: SubjectTreatment | undefined, property: string): boolean =>
+  typeof treatment === 'object' &&
+  'anonymize' in treatment &&
+  Object.hasOwn(treatment.anonymize, property) &&
+  treatment.anonymize[property] === null;
+
+/** The column a property names, or undefined. */
+const columnOf = (d: EntityDescription, property: string): ColumnDescription | undefined =>
+  d.columns.find((column) => column.property === property);
+
+/** Every key INTO each entity — declared references, then the hand-listed `columns:`. */
+function inboundEdges(input: SubjectPlanInput, byName: ReadonlyMap<string, RegistryEntry>) {
+  const inbound = new Map<string, Edge[]>();
+  const push = (to: string, edge: Edge): void => {
+    inbound.set(to, [...(inbound.get(to) ?? []), edge]);
+  };
+  for (const entry of byName.values()) {
+    for (const ref of entry.references()) {
+      push(ref.targetEntity, {
+        from: entry.name,
+        property: ref.property,
+        parent: ref.targetEntity,
+        parentKey: ref.targetProperty,
+        nullable: ref.nullable,
+        onDelete: ref.onDelete,
+      });
+    }
+  }
+  const root = byName.get(input.subject)?.describe();
+  const rootKey = root?.columns.find((column) => column.primaryKey)?.property ?? 'id';
+  for (const [entity, property] of Object.entries(input.columns ?? {})) {
+    const column = byName
+      .get(entity)
+      ?.describe()
+      .columns.find((c) => c.property === property);
+    push(input.subject, {
+      from: entity,
+      property,
+      parent: input.subject,
+      parentKey: rootKey,
+      nullable: column?.notNull === false,
+      onDelete: null,
+    });
+  }
+  for (const edges of inbound.values()) {
+    edges.sort((a, b) => `${a.from}.${a.property}`.localeCompare(`${b.from}.${b.property}`));
+  }
+  return inbound;
+}
+
+/** What is wrong with one declared treatment on its own, before any reach is considered. */
+function treatmentProblems(
+  subject: string,
+  table: string,
+  treatment: SubjectTreatment,
+  entry: RegistryEntry | undefined,
+): readonly UltimateError[] {
+  const invalid = (field: string, reason: string) =>
+    new SubjectTreatmentInvalidError({ subject, table, field, reason });
+  if (entry === undefined) return [invalid(table, 'names no registered entity')];
+  const d = entry.describe();
+  if (treatment === 'delete') {
+    if (d.appendOnly === true) {
+      return [invalid("'delete'", 'is refused: the entity is append-only')];
+    }
+    if (d.softDelete) {
+      return [invalid("'delete'", 'only stamps deleted_at: a soft delete keeps every value')];
+    }
+    return [];
+  }
+  if (typeof treatment !== 'object' || treatment === null) {
+    return [invalid('the treatment', "is none of 'delete', { anonymize } or { retain }")];
+  }
+  if ('retain' in treatment) {
+    const reason = treatment.retain;
+    return typeof reason === 'string' && reason.trim().length > 0
+      ? []
+      : [invalid('retain', 'is blank: the reason is printed in every export and is required')];
+  }
+  if (!('anonymize' in treatment)) {
+    return [invalid('the treatment', "is none of 'delete', { anonymize } or { retain }")];
+  }
+  if (d.appendOnly === true) return [invalid('anonymize', 'is refused: the entity is append-only')];
+  const named = Object.entries(treatment.anonymize);
+  if (named.length === 0) return [invalid('anonymize', 'names no column')];
+  return named.flatMap(([property, value]) => {
+    const column = columnOf(d, property);
+    if (column === undefined) return [invalid(`anonymize.${property}`, 'is not a column')];
+    if (column.primaryKey) return [invalid(`anonymize.${property}`, 'is the primary key')];
+    if (value === null && column.notNull) {
+      return [invalid(`anonymize.${property}`, 'is null and the column is not nullable')];
+    }
+    return [];
+  });
+}
+
+/** A kept row under a parent the erase deletes: it would block the delete, or be cascaded away. */
+function keptUnderDeleted(
+  subject: string,
+  edge: Edge,
+  treatment: SubjectTreatment,
+): UltimateError | undefined {
+  if (isDelete(treatment) || nulls(treatment, edge.property)) return undefined;
+  if (edge.nullable && (edge.onDelete === 'set null' || edge.onDelete === 'set default')) {
+    return undefined;
+  }
+  return new SubjectTreatmentInvalidError({
+    subject,
+    table: edge.from,
+    field: edge.property,
+    instead: "'delete'",
+    reason:
+      edge.onDelete === 'cascade'
+        ? `keeps rows the delete of ${edge.parent} cascades away — use 'delete', or anonymize ${edge.property}: null on a nullable key`
+        : `keeps rows that block the delete of ${edge.parent} — use 'delete', or anonymize ${edge.property}: null on a nullable key`,
+  });
+}
+
+export function planSubject(input: SubjectPlanInput): {
+  readonly plan: SubjectPlan;
+  readonly problems: readonly UltimateError[];
+} {
+  const byName = new Map(
+    input.entries
+      .filter((entry) => entry.describe().view === undefined)
+      .map((entry) => [entry.name, entry]),
+  );
+  const subject = input.subject;
+  const problems: UltimateError[] = [];
+  const root = byName.get(subject)?.describe();
+  const keys = root?.columns.filter((column) => column.primaryKey) ?? [];
+  const key = keys[0]?.property ?? 'id';
+  if (root === undefined || keys.length !== 1) {
+    problems.push(
+      new SubjectTreatmentInvalidError({
+        subject,
+        table: subject,
+        field: 'the subject',
+        reason:
+          root === undefined
+            ? 'names no registered entity'
+            : 'has a composite primary key: a subject is found by one key',
+      }),
+    );
+  }
+  for (const [table, treatment] of Object.entries(input.tables)) {
+    problems.push(...treatmentProblems(subject, table, treatment, byName.get(table)));
+  }
+  const inbound = inboundEdges(input, byName);
+  const treatmentOf = (entity: string) => own(input.tables, entity);
+  const propagates = (entity: string) => entity === subject || isDelete(treatmentOf(entity));
+
+  const state = new Map<string, 'open' | 'done'>();
+  const via = new Map<string, SubjectVia[]>();
+  const order: string[] = [];
+  const unlink: SubjectUnlink[] = [];
+  const undeclared = new Set<string>();
+  if (treatmentOf(subject) === undefined && root !== undefined) {
+    problems.push(new SubjectTableUndeclaredError({ subject, table: subject, path: [subject] }));
+    undeclared.add(subject);
+  }
+
+  const walk = (entity: string, path: readonly string[]): void => {
+    state.set(entity, 'open');
+    const deleted = isDelete(treatmentOf(entity));
+    for (const edge of inbound.get(entity) ?? []) {
+      const here = [...path, `${edge.from}.${edge.property}`];
+      const treatment = treatmentOf(edge.from);
+      if (treatment === undefined) {
+        if (!undeclared.has(edge.from)) {
+          undeclared.add(edge.from);
+          problems.push(new SubjectTableUndeclaredError({ subject, table: edge.from, path: here }));
+        }
+        continue;
+      }
+      if (state.get(edge.from) === 'open') {
+        // A back edge closes a loop: it finds no rows, and a deleted parent needs it cleared first.
+        if (!deleted) continue;
+        if (edge.nullable) unlink.push({ entity: edge.from, ...edgeVia(edge) });
+        else problems.push(new SubjectCycleError({ subject, table: edge.from, ...cycleOf(edge) }));
+        continue;
+      }
+      if (deleted) {
+        const kept = keptUnderDeleted(subject, edge, treatment);
+        if (kept !== undefined) problems.push(kept);
+      }
+      via.set(edge.from, [...(via.get(edge.from) ?? []), edgeVia(edge)]);
+      if (state.has(edge.from)) continue;
+      if (propagates(edge.from)) walk(edge.from, here);
+      else {
+        state.set(edge.from, 'done');
+        order.push(edge.from);
+      }
+    }
+    state.set(entity, 'done');
+    order.push(entity);
+  };
+  if (root !== undefined) walk(subject, [subject]);
+
+  for (const table of Object.keys(input.tables)) {
+    if (byName.has(table) && !state.has(table)) {
+      problems.push(
+        new SubjectTreatmentInvalidError({
+          subject,
+          table,
+          field: table,
+          reason: `is declared and nothing reaches it from ${subject} — remove it, or list its key column in columns:`,
+        }),
+      );
+    }
+  }
+  const steps = order
+    .filter((entity) => treatmentOf(entity) !== undefined)
+    .map((entity) => ({
+      entity,
+      treatment: treatmentOf(entity) as SubjectTreatment,
+      via: via.get(entity) ?? [],
+    }));
+  return { plan: { subject, key, unlink, steps }, problems };
+}
+
+const edgeVia = (edge: Edge): SubjectVia => ({
+  property: edge.property,
+  parent: edge.parent,
+  parentKey: edge.parentKey,
+});
+
+const cycleOf = (edge: Edge) => ({ column: edge.property, parent: edge.parent });