dxcomplete 0.1.0

package/src/runtime/records.ts

@@ -0,0 +1,2303 @@
+import { randomUUID } from "node:crypto";
+import type { ClientSession, Db } from "mongodb";
+import type { ActorContext } from "./actor.js";
+
+export const COLLECTION_NAMES = [
+  "workspaces",
+  "statements",
+  "journal_entries",
+  "environments",
+  "components",
+  "estimates",
+  "benefits",
+  "expectations",
+  "requirements",
+  "tasks",
+  "commitments",
+  "deferrals",
+  "changes",
+  "decisions",
+  "risks"
+] as const;
+
+export const LEGACY_COLLECTION_NAMES = [
+  "engagements",
+  "initiatives",
+  "service_charters",
+  "cost_baselines",
+  "cost_actuals",
+  "benefit_measurements"
+] as const;
+export const DXCOMPLETE_TICKET_COLLECTION_NAME = "dxcomplete_tickets";
+export const LEGACY_INTAKE_COLLECTION_NAME = "intake_items";
+export const LEGACY_PRIVATE_COLLECTION_NAMES = [LEGACY_INTAKE_COLLECTION_NAME] as const;
+export const INDEX_COLLECTION_NAMES = [...COLLECTION_NAMES, DXCOMPLETE_TICKET_COLLECTION_NAME] as const;
+export const LINK_SCAN_COLLECTION_NAMES = [...COLLECTION_NAMES, ...LEGACY_COLLECTION_NAMES] as const;
+export const READABLE_ID_SEQUENCES_COLLECTION = "readable_id_sequences";
+export const READABLE_ID_TYPE_CODES = {
+  statements: "STM",
+  journal_entries: "JRN",
+  environments: "ENV",
+  components: "CMP",
+  expectations: "EXP",
+  requirements: "REQ",
+  tasks: "TSK",
+  commitments: "CMT",
+  deferrals: "DFR",
+  decisions: "DEC",
+  changes: "CHG",
+  risks: "RSK",
+  estimates: "EST",
+  benefits: "BFT"
+} as const;
+export const READABLE_ID_COLLECTION_NAMES = Object.keys(READABLE_ID_TYPE_CODES) as ReadableIdCollectionName[];
+
+export type CollectionName = (typeof COLLECTION_NAMES)[number];
+export type ReadableIdCollectionName = keyof typeof READABLE_ID_TYPE_CODES;
+export type PrivateCollectionName = typeof DXCOMPLETE_TICKET_COLLECTION_NAME;
+export type RuntimeCollectionName =
+  | CollectionName
+  | PrivateCollectionName
+  | (typeof LEGACY_COLLECTION_NAMES)[number]
+  | (typeof LEGACY_PRIVATE_COLLECTION_NAMES)[number];
+
+export type RecordLink = {
+  toType: RuntimeCollectionName;
+  toId: string;
+  relationship: string;
+  createdAt: string;
+  createdBy: string;
+};
+
+export type RecordEdge = RecordLink & {
+  fromType: RuntimeCollectionName;
+  fromId: string;
+};
+
+export type DxcRecord = {
+  _id: string;
+  recordType: RuntimeCollectionName;
+  readableId?: string;
+  workspaceId?: string;
+  title?: string;
+  summary?: string;
+  fields: Record<string, unknown>;
+  links: RecordLink[];
+  archivedAt?: string;
+  archivedBy?: string;
+  archiveReason?: string;
+  createdAt: string;
+  createdBy: string;
+  updatedAt: string;
+  updatedBy: string;
+};
+
+export type ReviewableRecordType = "expectations" | "requirements";
+
+export type ReviewNote = {
+  id: string;
+  body: string;
+  createdAt: string;
+  createdBy: string;
+  important?: true;
+};
+
+export type RecordVersionSnapshot = {
+  title?: string;
+  summary?: string;
+  fields: Record<string, unknown>;
+};
+
+export type RecordVersionHistoryEntry = {
+  id: string;
+  fromVersion: number;
+  toVersion: number;
+  createdAt: string;
+  createdBy: string;
+  changedFields: string[];
+  previousSnapshot: RecordVersionSnapshot;
+  nextSnapshot: RecordVersionSnapshot;
+  revisionNote?: string;
+};
+
+export type ChangeEventType =
+  | "notice_given"
+  | "veto_recorded"
+  | "emergency_declared"
+  | "decision_recorded"
+  | "result_reported"
+  | "recovery_recorded"
+  | "plan_revised"
+  | "note_added";
+
+export type ChangeEvent = {
+  id: string;
+  eventType: ChangeEventType;
+  createdAt: string;
+  createdBy: string;
+} & Record<string, unknown>;
+
+export type DeferralEventType =
+  | "condition_addressed"
+  | "condition_reopened"
+  | "condition_note_added"
+  | "deferral_resolved"
+  | "deferral_abandoned";
+
+export type DeferralCondition = {
+  id: string;
+  statement: string;
+  state: "open" | "addressed";
+  createdAt: string;
+  createdBy: string;
+  updatedAt: string;
+  updatedBy: string;
+};
+
+export type DeferralEvent = {
+  id: string;
+  eventType: DeferralEventType;
+  createdAt: string;
+  createdBy: string;
+} & Record<string, unknown>;
+
+export type DecisionEntryType = "argument" | "decision" | "note";
+
+export type DecisionEntry = {
+  id: string;
+  entryType: DecisionEntryType;
+  body: string;
+  createdAt: string;
+  createdBy: string;
+  decidedBy?: string;
+  rationale?: string;
+};
+
+export type TaskEntryType = "comment" | "status_change" | "note";
+export type TaskStatus = "open" | "in_progress" | "blocked" | "done";
+
+export type TaskEntry = {
+  id: string;
+  entryType: TaskEntryType;
+  body: string;
+  createdAt: string;
+  createdBy: string;
+  status?: TaskStatus;
+};
+
+export type JournalEntryKind = "note" | "summary";
+
+export type AppendJournalNoteInput = {
+  workspaceId: string;
+  body: string;
+  tag?: string;
+};
+
+export type ReadJournalInput = {
+  workspaceId: string;
+  limit?: number;
+  includeArchived?: boolean;
+};
+
+export type ReadJournalResult = {
+  workspaceId: string;
+  readTier: "hot" | "cold";
+  compaction: {
+    activeRawNoteCount: number;
+    threshold: number;
+    recommended: boolean;
+  };
+  entries: DxcRecord[];
+};
+
+export type GetJournalEntryInput = {
+  workspaceId: string;
+  id: string;
+};
+
+export type AppendJournalSummaryInput = {
+  workspaceId: string;
+  body: string;
+  covers: string[];
+  tag?: string;
+};
+
+export type CreateRecordInput = {
+  id?: string;
+  workspaceId?: string;
+  title?: string;
+  summary?: string;
+  fields?: Record<string, unknown>;
+  allowManagedFields?: boolean;
+};
+
+export type UpdateRecordInput = {
+  recordType: CollectionName;
+  id: string;
+  workspaceId?: string;
+  title?: string;
+  summary?: string;
+  fields?: Record<string, unknown>;
+  unsetFields?: string[];
+  allowManagedFields?: boolean;
+  revisionNote?: string;
+};
+
+export type AppendReviewNoteInput = {
+  recordType: ReviewableRecordType;
+  id: string;
+  workspaceId: string;
+  body: string;
+  important?: boolean;
+};
+
+export type AppendChangeEventInput = {
+  workspaceId: string;
+  changeId: string;
+  eventType: ChangeEventType;
+  event: Record<string, unknown>;
+};
+
+export type AppendDeferralEventInput = {
+  workspaceId: string;
+  deferralId: string;
+  eventType: DeferralEventType;
+  event: Record<string, unknown>;
+};
+
+export type AppendDecisionEntryInput = {
+  workspaceId: string;
+  decisionId: string;
+  entryType: DecisionEntryType;
+  body: string;
+  decidedBy?: string;
+  rationale?: string;
+};
+
+export type AppendTaskEntryInput = {
+  workspaceId: string;
+  taskId: string;
+  entryType: TaskEntryType;
+  body: string;
+  status?: TaskStatus;
+};
+
+export type UnlinkRecordsInput = {
+  fromType: CollectionName;
+  fromId: string;
+  toType: CollectionName;
+  toId: string;
+  workspaceId?: string;
+  relationship?: string;
+};
+
+export type ArchiveRecordInput = {
+  recordType: CollectionName;
+  id: string;
+  workspaceId?: string;
+  reason?: string;
+  supersededByType?: CollectionName;
+  supersededById?: string;
+};
+
+export type LinkedRecordsResult = {
+  source: DxcRecord;
+  outbound: Array<{
+    edge: RecordEdge;
+    record: DxcRecord;
+  }>;
+  inbound: Array<{
+    edge: RecordEdge;
+    record: DxcRecord;
+  }>;
+};
+
+export type DxcompleteTicketEntryDirection = "submitter_entry" | "dxcomplete_reply";
+
+export type DxcompleteTicketEntry = {
+  id: string;
+  body: string;
+  createdAt: string;
+  createdBy: string;
+  direction: DxcompleteTicketEntryDirection;
+  addressedToActorId?: string;
+  readAt?: string;
+};
+
+export type CreateDxcompleteTicketInput = {
+  title: string;
+  body: string;
+};
+
+export type AppendDxcompleteTicketInput = {
+  id: string;
+  body: string;
+};
+
+export type AppendDxcompleteTicketReplyInput = {
+  id: string;
+  body: string;
+  addressedToActorId: string;
+};
+
+export type ArchiveDxcompleteTicketInput = {
+  id: string;
+};
+
+export type ReadDxcompleteTicketInput = {
+  id: string;
+};
+
+export type DxcompleteTicketUnreadReplySummary = {
+  id: string;
+  createdAt: string;
+  createdBy: string;
+  direction: "dxcomplete_reply";
+  addressedToActorId?: string;
+};
+
+export type DxcompleteTicketUnreadReplyResult = {
+  ticketId: string;
+  title?: string;
+  updatedAt: string;
+  unreadReplyCount: number;
+  newestReplyAt?: string;
+  replies: DxcompleteTicketUnreadReplySummary[];
+};
+
+export const RUNTIME_ACTOR_ID = "dxcomplete-runtime";
+const REVIEW_NOTE_RECORD_TYPES = ["expectations", "requirements"] as const;
+const VERSIONED_RECORD_TYPES = [
+  "statements",
+  "environments",
+  "components",
+  "expectations",
+  "requirements",
+  "estimates",
+  "benefits"
+] as const;
+const VERSION_HISTORY_FIELD = "versionHistory";
+const CHANGE_MANAGED_FIELDS = [
+  "changePlan",
+  "executionSteps",
+  "rollbackPlan",
+  "riskImpact",
+  "plannedFor",
+  "events"
+] as const;
+const COMMITMENT_MANAGED_FIELDS = ["commitmentStatement", "reservations"] as const;
+const DEFERRAL_MANAGED_FIELDS = ["reason", "status", "conditions", "conditionEvents"] as const;
+const ESTIMATE_MANAGED_FIELDS = ["lineItems", "rollup"] as const;
+const BENEFITS_MANAGED_FIELDS = ["benefitItems", "rollup"] as const;
+const ENVIRONMENT_MANAGED_FIELDS = ["name", "description"] as const;
+const COMPONENT_MANAGED_FIELDS = [
+  "name",
+  "environmentId",
+  "kind",
+  "locator",
+  "identifiers",
+  "secretPointers",
+  "notes"
+] as const;
+const DECISION_LEDGER_MANAGED_FIELDS = [
+  "matter",
+  "entries",
+  "currentDecision",
+  "question",
+  "decision",
+  "decidedBy",
+  "rationale",
+  "argumentsConsidered",
+  "concerns",
+  "status"
+] as const;
+const TASK_LEDGER_MANAGED_FIELDS = [
+  "description",
+  "assignee",
+  "assignor",
+  "entries",
+  "currentStatus",
+  "details",
+  "status"
+] as const;
+const DECISION_INPUT_MANAGED_FIELDS = ["informedBy", "informedByIds", "inputRecords"] as const;
+const JOURNAL_ENTRY_MANAGED_FIELDS = ["kind", "body", "tag", "covers", "coveredBySummaryId"] as const;
+const JOURNAL_COMPACTION_THRESHOLD = 200;
+const VERSIONED_TYPED_FIELDS: Partial<Record<CollectionName, string[]>> = {
+  statements: ["statement", "source"],
+  expectations: ["statement", "successRecognition", "approvalState", "approvedBy", "approvedAt", "source"],
+  requirements: ["statement", "acceptanceCriteria", "priority", "status"],
+  estimates: ["lineItems", "rollup"],
+  benefits: ["benefitItems", "rollup"],
+  environments: ["name", "description"],
+  components: ["name", "environmentId", "kind", "locator", "identifiers", "secretPointers", "notes"]
+};
+
+const RESERVED_RELATIONSHIP_FIELDS: Partial<Record<CollectionName, string[]>> = {
+  changes: ["requirementId"],
+  commitments: ["requirementIds", "expectationIds", "deferralId"],
+  deferrals: ["requirementIds", "expectationIds"],
+  estimates: ["requirementIds", "expectationIds"],
+  benefits: ["requirementIds", "expectationIds"],
+  expectations: ["statementId"],
+  requirements: ["expectationId"],
+  tasks: ["requirementId"]
+};
+
+const REMOVED_INITIATIVE_FIELD_RECORD_TYPES: CollectionName[] = [
+  "changes",
+  "estimates",
+  "benefits",
+  "expectations"
+];
+
+export function assertCollectionName(value: string): CollectionName {
+  if ((COLLECTION_NAMES as readonly string[]).includes(value)) {
+    return value as CollectionName;
+  }
+
+  throw new Error(`Unsupported record type "${value}".`);
+}
+
+export async function createRecord(
+  db: Db,
+  recordType: CollectionName,
+  input: CreateRecordInput,
+  actorId: string
+): Promise<DxcRecord> {
+  assertNoReservedRelationshipFields(recordType, input.fields);
+  if (input.allowManagedFields) {
+    assertNoReviewNotesField(recordType, input.fields);
+  } else {
+    assertNoManagedField(recordType, input.fields);
+  }
+
+  const now = new Date().toISOString();
+  const workspaceId = workspaceIdForCreate(recordType, input.workspaceId);
+
+  if (workspaceId) {
+    await assertWorkspaceExists(db, workspaceId);
+  }
+
+  const record: DxcRecord = {
+    _id: input.id ?? randomUUID(),
+    recordType,
+    ...(workspaceId ? { workspaceId } : {}),
+    title: input.title,
+    summary: input.summary,
+    fields: input.fields ?? {},
+    links: [],
+    createdAt: now,
+    createdBy: actorId,
+    updatedAt: now,
+    updatedBy: actorId
+  };
+
+  if (recordTypeSupportsReadableId(recordType)) {
+    const session = db.client.startSession();
+    try {
+      await session.withTransaction(async () => {
+        record.readableId = await allocateReadableId(db, recordType, workspaceId, actorId, now, session);
+        await db.collection<DxcRecord>(recordType).insertOne(record, { session });
+      });
+    } finally {
+      await session.endSession();
+    }
+    return record;
+  }
+
+  await db.collection<DxcRecord>(recordType).insertOne(record);
+  return record;
+}
+
+export async function listRecords(
+  db: Db,
+  recordType: CollectionName,
+  limit: number,
+  options: { includeArchived?: boolean; workspaceId?: string } = {}
+): Promise<DxcRecord[]> {
+  const filter: Record<string, unknown> = {};
+
+  if (recordTypeRequiresWorkspace(recordType)) {
+    filter.workspaceId = readRequiredWorkspaceId(options.workspaceId, recordType);
+  }
+
+  if (!options.includeArchived) {
+    filter.archivedAt = { $exists: false };
+  }
+
+  return db
+    .collection<DxcRecord>(recordType)
+    .find(filter)
+    .sort({ createdAt: -1 })
+    .limit(limit)
+    .toArray();
+}
+
+export async function getRecord(
+  db: Db,
+  recordType: RuntimeCollectionName,
+  id: string,
+  options: { workspaceId?: string; allowAnyWorkspace?: boolean } = {}
+): Promise<DxcRecord | null> {
+  const filter = recordIdentityFilter(recordType, id);
+
+  if (
+    recordTypeRequiresWorkspace(recordType) &&
+    !options.allowAnyWorkspace &&
+    isCurrentCollection(recordType)
+  ) {
+    filter.workspaceId = readRequiredWorkspaceId(options.workspaceId, recordType);
+  }
+
+  return db.collection<DxcRecord>(recordType).findOne(filter);
+}
+
+export async function listLinkedRecords(
+  db: Db,
+  input: {
+    recordType: CollectionName;
+    id: string;
+    workspaceId?: string;
+    direction?: "outbound" | "inbound" | "both";
+    relationship?: string;
+    includeArchived?: boolean;
+  }
+): Promise<LinkedRecordsResult> {
+  const source = await getRecord(db, input.recordType, input.id, { workspaceId: input.workspaceId });
+
+  if (!source) {
+    throw new Error(`Record not found: ${input.recordType}/${input.id}`);
+  }
+
+  const direction = input.direction ?? "both";
+  const result: LinkedRecordsResult = {
+    source,
+    outbound: [],
+    inbound: []
+  };
+
+  if (direction === "outbound" || direction === "both") {
+    for (const link of source.links.filter((link) => linkMatches(link, input.relationship))) {
+      const target = await getRecord(db, link.toType, link.toId, {
+        workspaceId: source.workspaceId,
+        allowAnyWorkspace: !source.workspaceId
+      });
+
+      if (
+        !target ||
+        (!input.includeArchived && target.archivedAt) ||
+        !recordBelongsToWorkspace(target, source.workspaceId)
+      ) {
+        continue;
+      }
+
+      result.outbound.push({
+        edge: {
+          fromType: source.recordType,
+          fromId: source._id,
+          ...link
+        },
+        record: target
+      });
+    }
+  }
+
+  if (direction === "inbound" || direction === "both") {
+    for (const collectionName of LINK_SCAN_COLLECTION_NAMES) {
+      const filter: Record<string, unknown> = {
+        links: {
+          $elemMatch: {
+            toType: input.recordType,
+            toId: source._id,
+            ...(input.relationship ? { relationship: input.relationship } : {})
+          }
+        }
+      };
+
+      if (source.workspaceId && recordTypeRequiresWorkspace(collectionName)) {
+        filter.workspaceId = source.workspaceId;
+      }
+
+      if (!input.includeArchived) {
+        filter.archivedAt = { $exists: false };
+      }
+
+      const records = await db.collection<DxcRecord>(collectionName).find(filter).toArray();
+
+      for (const record of records) {
+        for (const link of record.links.filter(
+          (link) =>
+            link.toType === input.recordType &&
+            link.toId === source._id &&
+            linkMatches(link, input.relationship)
+        )) {
+          result.inbound.push({
+            edge: {
+              fromType: record.recordType,
+              fromId: record._id,
+              ...link
+            },
+            record
+          });
+        }
+      }
+    }
+  }
+
+  return result;
+}
+
+export async function migrateLegacyIntakeItemsToDxcompleteTickets(db: Db): Promise<{ copied: number; skipped: number }> {
+  const legacyCollection = db.collection<DxcRecord>(LEGACY_INTAKE_COLLECTION_NAME);
+  const ticketCollection = db.collection<DxcRecord>(DXCOMPLETE_TICKET_COLLECTION_NAME);
+  const legacyRecords = await legacyCollection.find({}).toArray();
+  let copied = 0;
+  let skipped = 0;
+
+  for (const legacyRecord of legacyRecords) {
+    const existing = await ticketCollection.findOne({ _id: legacyRecord._id });
+
+    if (existing) {
+      skipped += 1;
+      continue;
+    }
+
+    const migratedRecord: DxcRecord = {
+      ...legacyRecord,
+      recordType: DXCOMPLETE_TICKET_COLLECTION_NAME,
+      fields: {
+        ...legacyRecord.fields,
+        entries: normalizeTicketEntries(legacyRecord.fields.entries)
+      }
+    };
+
+    await ticketCollection.insertOne(migratedRecord);
+    copied += 1;
+  }
+
+  return { copied, skipped };
+}
+
+export async function createDxcompleteTicket(
+  db: Db,
+  input: CreateDxcompleteTicketInput,
+  actor: ActorContext
+): Promise<DxcRecord> {
+  const now = new Date().toISOString();
+  const entry: DxcompleteTicketEntry = {
+    id: randomUUID(),
+    body: input.body,
+    createdAt: now,
+    createdBy: actor.actorId,
+    direction: "submitter_entry"
+  };
+  const record: DxcRecord = {
+    _id: randomUUID(),
+    recordType: DXCOMPLETE_TICKET_COLLECTION_NAME,
+    title: input.title,
+    fields: {
+      ownerActorId: actor.actorId,
+      entries: [entry]
+    },
+    links: [],
+    createdAt: now,
+    createdBy: actor.actorId,
+    updatedAt: now,
+    updatedBy: actor.actorId
+  };
+
+  await db.collection<DxcRecord>(DXCOMPLETE_TICKET_COLLECTION_NAME).insertOne(record);
+  return record;
+}
+
+export async function getDxcompleteTicket(db: Db, id: string, actor: ActorContext): Promise<DxcRecord> {
+  const record = await db.collection<DxcRecord>(DXCOMPLETE_TICKET_COLLECTION_NAME).findOne(ticketOwnerFilter(id, actor));
+
+  if (!record) {
+    throw new Error(`DX Complete Ticket not found: ${id}`);
+  }
+
+  return record;
+}
+
+export async function listDxcompleteTickets(
+  db: Db,
+  actor: ActorContext,
+  limit: number,
+  options: { includeArchived?: boolean } = {}
+): Promise<DxcRecord[]> {
+  const filter: Record<string, unknown> = {
+    "fields.ownerActorId": actor.actorId
+  };
+
+  if (!options.includeArchived) {
+    filter.archivedAt = { $exists: false };
+  }
+
+  return db
+    .collection<DxcRecord>(DXCOMPLETE_TICKET_COLLECTION_NAME)
+    .find(filter)
+    .sort({ updatedAt: -1 })
+    .limit(limit)
+    .toArray();
+}
+
+export async function appendDxcompleteTicket(
+  db: Db,
+  input: AppendDxcompleteTicketInput,
+  actor: ActorContext
+): Promise<DxcRecord> {
+  const collection = db.collection<DxcRecord>(DXCOMPLETE_TICKET_COLLECTION_NAME);
+  const existing = await collection.findOne({
+    ...ticketOwnerFilter(input.id, actor),
+    archivedAt: { $exists: false }
+  });
+
+  if (!existing) {
+    throw new Error(`Active DX Complete Ticket not found: ${input.id}`);
+  }
+
+  const now = new Date().toISOString();
+  const entry: DxcompleteTicketEntry = {
+    id: randomUUID(),
+    body: input.body,
+    createdAt: now,
+    createdBy: actor.actorId,
+    direction: "submitter_entry"
+  };
+
+  await collection.updateOne(
+    ticketOwnerFilter(input.id, actor),
+    {
+      $push: {
+        "fields.entries": entry
+      },
+      $set: {
+        updatedAt: now,
+        updatedBy: actor.actorId
+      }
+    }
+  );
+
+  return getDxcompleteTicket(db, input.id, actor);
+}
+
+export async function appendDxcompleteTicketReply(
+  db: Db,
+  input: AppendDxcompleteTicketReplyInput,
+  actorId: string = RUNTIME_ACTOR_ID
+): Promise<DxcRecord> {
+  const collection = db.collection<DxcRecord>(DXCOMPLETE_TICKET_COLLECTION_NAME);
+  const existing = await collection.findOne({
+    _id: input.id,
+    "fields.ownerActorId": input.addressedToActorId,
+    archivedAt: { $exists: false }
+  });
+
+  if (!existing) {
+    throw new Error(`Active DX Complete Ticket not found for addressed actor: ${input.id}`);
+  }
+
+  const now = new Date().toISOString();
+  const entry: DxcompleteTicketEntry = {
+    id: randomUUID(),
+    body: input.body,
+    createdAt: now,
+    createdBy: actorId,
+    direction: "dxcomplete_reply",
+    addressedToActorId: input.addressedToActorId
+  };
+
+  await collection.updateOne(
+    { _id: input.id },
+    {
+      $push: {
+        "fields.entries": entry
+      },
+      $set: {
+        updatedAt: now,
+        updatedBy: actorId
+      }
+    }
+  );
+
+  const record = await collection.findOne({ _id: input.id });
+
+  if (!record) {
+    throw new Error(`DX Complete Ticket not found after reply append: ${input.id}`);
+  }
+
+  return record;
+}
+
+export async function appendJournalNote(
+  db: Db,
+  input: AppendJournalNoteInput,
+  actorId: string
+): Promise<DxcRecord> {
+  return createRecord(
+    db,
+    "journal_entries",
+    {
+      workspaceId: input.workspaceId,
+      title: input.tag ? `Journal note: ${input.tag}` : "Journal note",
+      summary: input.body,
+      allowManagedFields: true,
+      fields: {
+        kind: "note",
+        body: input.body,
+        ...(input.tag ? { tag: input.tag } : {})
+      }
+    },
+    actorId
+  );
+}
+
+export async function readJournal(db: Db, input: ReadJournalInput): Promise<ReadJournalResult> {
+  const limit = clampJournalReadLimit(input.limit);
+  const filter: Record<string, unknown> = {
+    workspaceId: readRequiredWorkspaceId(input.workspaceId, "journal_entries")
+  };
+
+  if (!input.includeArchived) {
+    filter.archivedAt = { $exists: false };
+    filter["fields.kind"] = { $in: ["note", "summary"] };
+  }
+
+  const [entries, activeRawNoteCount] = await Promise.all([
+    db
+      .collection<DxcRecord>("journal_entries")
+      .find(filter)
+      .sort({ createdAt: 1 })
+      .limit(limit)
+      .toArray(),
+    db.collection<DxcRecord>("journal_entries").countDocuments({
+      workspaceId: input.workspaceId,
+      archivedAt: { $exists: false },
+      "fields.kind": "note"
+    })
+  ]);
+
+  return {
+    workspaceId: input.workspaceId,
+    readTier: input.includeArchived ? "cold" : "hot",
+    compaction: {
+      activeRawNoteCount,
+      threshold: JOURNAL_COMPACTION_THRESHOLD,
+      recommended: activeRawNoteCount >= JOURNAL_COMPACTION_THRESHOLD
+    },
+    entries
+  };
+}
+
+export async function getJournalEntry(db: Db, input: GetJournalEntryInput): Promise<DxcRecord> {
+  const entry = await getRecord(db, "journal_entries", input.id, { workspaceId: input.workspaceId });
+
+  if (!entry) {
+    throw new Error(`Journal entry not found: journal_entries/${input.id}`);
+  }
+
+  return entry;
+}
+
+export async function appendJournalSummary(
+  db: Db,
+  input: AppendJournalSummaryInput,
+  actorId: string
+): Promise<DxcRecord> {
+  const coveredIds = [...new Set(input.covers.map((id) => id.trim()).filter(Boolean))];
+
+  if (coveredIds.length === 0) {
+    throw new Error("append_journal_summary requires at least one covered journal entry id.");
+  }
+
+  const coveredEntries: DxcRecord[] = [];
+  for (const id of coveredIds) {
+    const entry = await getRecord(db, "journal_entries", id, { workspaceId: input.workspaceId });
+
+    if (!entry) {
+      throw new Error(`Covered journal entry not found: journal_entries/${id}`);
+    }
+
+    const kind = readJournalEntryKind(entry);
+    if (!kind) {
+      throw new Error(`Covered record is not a journal note or summary: journal_entries/${id}`);
+    }
+
+    coveredEntries.push(entry);
+  }
+
+  const summary = await createRecord(
+    db,
+    "journal_entries",
+    {
+      workspaceId: input.workspaceId,
+      title: input.tag ? `Journal summary: ${input.tag}` : "Journal summary",
+      summary: input.body,
+      allowManagedFields: true,
+      fields: {
+        kind: "summary",
+        body: input.body,
+        covers: coveredEntries.map((entry) => entry._id),
+        ...(input.tag ? { tag: input.tag } : {})
+      }
+    },
+    actorId
+  );
+
+  const now = new Date().toISOString();
+  await db.collection<DxcRecord>("journal_entries").updateMany(
+    {
+      workspaceId: input.workspaceId,
+      _id: { $in: coveredEntries.map((entry) => entry._id) },
+      archivedAt: { $exists: false }
+    },
+    {
+      $set: {
+        archivedAt: now,
+        archivedBy: actorId,
+        archiveReason: `Covered by journal summary ${summary._id}`,
+        "fields.coveredBySummaryId": summary._id,
+        updatedAt: now,
+        updatedBy: actorId
+      }
+    }
+  );
+
+  return summary;
+}
+
+function clampJournalReadLimit(limit: number | undefined): number {
+  if (!limit) {
+    return 100;
+  }
+
+  return Math.min(Math.max(limit, 1), 500);
+}
+
+function readJournalEntryKind(record: DxcRecord): JournalEntryKind | undefined {
+  if (record.fields.kind === "note" || record.fields.kind === "summary") {
+    return record.fields.kind;
+  }
+
+  return undefined;
+}
+
+export async function appendReviewNote(
+  db: Db,
+  input: AppendReviewNoteInput,
+  actorId: string
+): Promise<DxcRecord> {
+  const collection = db.collection<DxcRecord>(input.recordType);
+  const filter = scopedRecordFilter(input.recordType, input.id, input.workspaceId);
+  const existing = await collection.findOne(filter);
+
+  if (!existing) {
+    throw new Error(`Record not found: ${input.recordType}/${input.id}`);
+  }
+
+  const now = new Date().toISOString();
+  const note: ReviewNote = {
+    id: randomUUID(),
+    body: input.body,
+    createdAt: now,
+    createdBy: actorId,
+    ...(input.important ? { important: true } : {})
+  };
+
+  await collection.updateOne(filter, {
+    $push: {
+      "fields.reviewNotes": note
+    },
+    $set: {
+      updatedAt: now,
+      updatedBy: actorId
+    }
+  });
+
+  const updated = await getRecord(db, input.recordType, input.id, { workspaceId: input.workspaceId });
+  if (!updated) {
+    throw new Error(`Record not found after review note append: ${input.recordType}/${input.id}`);
+  }
+
+  return updated;
+}
+
+export async function appendChangeEvent(
+  db: Db,
+  input: AppendChangeEventInput,
+  actorId: string
+): Promise<DxcRecord> {
+  const collection = db.collection<DxcRecord>("changes");
+  const filter = scopedRecordFilter("changes", input.changeId, input.workspaceId);
+  const existing = await collection.findOne(filter);
+
+  if (!existing) {
+    throw new Error(`Record not found: changes/${input.changeId}`);
+  }
+
+  const now = new Date().toISOString();
+  const event: ChangeEvent = {
+    ...input.event,
+    id: randomUUID(),
+    eventType: input.eventType,
+    createdAt: now,
+    createdBy: actorId
+  };
+
+  await collection.updateOne(filter, {
+    $push: {
+      "fields.events": event
+    },
+    $set: {
+      updatedAt: now,
+      updatedBy: actorId
+    }
+  });
+
+  const updated = await getRecord(db, "changes", input.changeId, { workspaceId: input.workspaceId });
+  if (!updated) {
+    throw new Error(`Record not found after change event append: changes/${input.changeId}`);
+  }
+
+  return updated;
+}
+
+export async function appendDeferralEvent(
+  db: Db,
+  input: AppendDeferralEventInput,
+  actorId: string
+): Promise<DxcRecord> {
+  const collection = db.collection<DxcRecord>("deferrals");
+  const filter = scopedRecordFilter("deferrals", input.deferralId, input.workspaceId);
+  const existing = await collection.findOne(filter);
+
+  if (!existing) {
+    throw new Error(`Record not found: deferrals/${input.deferralId}`);
+  }
+
+  const now = new Date().toISOString();
+  const event: DeferralEvent = {
+    ...input.event,
+    id: randomUUID(),
+    eventType: input.eventType,
+    createdAt: now,
+    createdBy: actorId
+  };
+  const { conditions, status } = applyDeferralEventState(existing, event, actorId, now);
+
+  await collection.updateOne(filter, {
+    $push: {
+      "fields.conditionEvents": event
+    },
+    $set: {
+      "fields.conditions": conditions,
+      "fields.status": status,
+      updatedAt: now,
+      updatedBy: actorId
+    }
+  });
+
+  const updated = await getRecord(db, "deferrals", input.deferralId, { workspaceId: input.workspaceId });
+  if (!updated) {
+    throw new Error(`Record not found after deferral event append: deferrals/${input.deferralId}`);
+  }
+
+  return updated;
+}
+
+export async function appendDecisionEntry(
+  db: Db,
+  input: AppendDecisionEntryInput,
+  actorId: string
+): Promise<DxcRecord> {
+  const collection = db.collection<DxcRecord>("decisions");
+  const filter = scopedRecordFilter("decisions", input.decisionId, input.workspaceId);
+  const existing = await collection.findOne(filter);
+
+  if (!existing) {
+    throw new Error(`Record not found: decisions/${input.decisionId}`);
+  }
+
+  assertDecisionEntryInput(input);
+
+  const now = new Date().toISOString();
+  const entry: DecisionEntry = {
+    id: randomUUID(),
+    entryType: input.entryType,
+    body: input.body,
+    createdAt: now,
+    createdBy: actorId,
+    ...(input.decidedBy ? { decidedBy: input.decidedBy } : {}),
+    ...(input.rationale ? { rationale: input.rationale } : {})
+  };
+  const update: Record<string, unknown> = {
+    $push: {
+      "fields.entries": entry
+    },
+    $set: {
+      updatedAt: now,
+      updatedBy: actorId
+    }
+  };
+
+  if (entry.entryType === "decision") {
+    (update.$set as Record<string, unknown>)["fields.currentDecision"] = decisionEntryToCurrentDecision(entry);
+  }
+
+  await collection.updateOne(filter, update);
+
+  const updated = await getRecord(db, "decisions", input.decisionId, { workspaceId: input.workspaceId });
+  if (!updated) {
+    throw new Error(`Record not found after decision entry append: decisions/${input.decisionId}`);
+  }
+
+  return updated;
+}
+
+export async function appendTaskEntry(
+  db: Db,
+  input: AppendTaskEntryInput,
+  actorId: string
+): Promise<DxcRecord> {
+  const collection = db.collection<DxcRecord>("tasks");
+  const filter = scopedRecordFilter("tasks", input.taskId, input.workspaceId);
+  const existing = await collection.findOne(filter);
+
+  if (!existing) {
+    throw new Error(`Record not found: tasks/${input.taskId}`);
+  }
+
+  assertTaskEntryInput(input);
+
+  const now = new Date().toISOString();
+  const entry: TaskEntry = {
+    id: randomUUID(),
+    entryType: input.entryType,
+    body: input.body,
+    createdAt: now,
+    createdBy: actorId,
+    ...(input.status ? { status: input.status } : {})
+  };
+  const update: Record<string, unknown> = {
+    $push: {
+      "fields.entries": entry
+    },
+    $set: {
+      updatedAt: now,
+      updatedBy: actorId
+    }
+  };
+
+  if (entry.entryType === "status_change") {
+    (update.$set as Record<string, unknown>)["fields.currentStatus"] = taskEntryToCurrentStatus(entry);
+  }
+
+  await collection.updateOne(filter, update);
+
+  const updated = await getRecord(db, "tasks", input.taskId, { workspaceId: input.workspaceId });
+  if (!updated) {
+    throw new Error(`Record not found after task entry append: tasks/${input.taskId}`);
+  }
+
+  return updated;
+}
+
+export function decisionEntryToCurrentDecision(entry: DecisionEntry): Record<string, unknown> {
+  return {
+    entryId: entry.id,
+    body: entry.body,
+    createdAt: entry.createdAt,
+    createdBy: entry.createdBy,
+    ...(entry.decidedBy ? { decidedBy: entry.decidedBy } : {}),
+    ...(entry.rationale ? { rationale: entry.rationale } : {})
+  };
+}
+
+export function taskEntryToCurrentStatus(entry: TaskEntry): Record<string, unknown> {
+  if (entry.entryType !== "status_change" || !entry.status) {
+    throw new Error("Task current status can only derive from a status_change entry.");
+  }
+
+  return {
+    entryId: entry.id,
+    status: entry.status,
+    body: entry.body,
+    createdAt: entry.createdAt,
+    createdBy: entry.createdBy
+  };
+}
+
+function assertDecisionEntryInput(input: AppendDecisionEntryInput): void {
+  if (input.entryType !== "decision" && (input.decidedBy || input.rationale)) {
+    throw new Error("decidedBy and rationale are only valid on decision entries.");
+  }
+}
+
+function assertTaskEntryInput(input: AppendTaskEntryInput): void {
+  if (input.entryType === "status_change" && !input.status) {
+    throw new Error("status_change entries require status.");
+  }
+
+  if (input.entryType !== "status_change" && input.status) {
+    throw new Error("status is only valid on status_change entries.");
+  }
+}
+
+function applyDeferralEventState(
+  existing: DxcRecord,
+  event: DeferralEvent,
+  actorId: string,
+  now: string
+): { conditions: DeferralCondition[]; status: string } {
+  const conditions = normalizeDeferralConditions(existing.fields.conditions);
+  let status = typeof existing.fields.status === "string" ? existing.fields.status : "open";
+
+  switch (event.eventType) {
+    case "condition_addressed":
+      return {
+        conditions: updateDeferralConditionState(conditions, event, "addressed", actorId, now),
+        status
+      };
+    case "condition_reopened":
+      return {
+        conditions: updateDeferralConditionState(conditions, event, "open", actorId, now),
+        status
+      };
+    case "condition_note_added":
+      assertDeferralConditionExists(conditions, event);
+      return { conditions, status };
+    case "deferral_resolved":
+      status = "resolved";
+      return { conditions, status };
+    case "deferral_abandoned":
+      status = "abandoned";
+      return { conditions, status };
+  }
+}
+
+function normalizeDeferralConditions(value: unknown): DeferralCondition[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+
+  return value.filter(isDeferralCondition);
+}
+
+function isDeferralCondition(value: unknown): value is DeferralCondition {
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+
+  const condition = value as DeferralCondition;
+  return (
+    typeof condition.id === "string" &&
+    typeof condition.statement === "string" &&
+    (condition.state === "open" || condition.state === "addressed") &&
+    typeof condition.createdAt === "string" &&
+    typeof condition.createdBy === "string" &&
+    typeof condition.updatedAt === "string" &&
+    typeof condition.updatedBy === "string"
+  );
+}
+
+function updateDeferralConditionState(
+  conditions: DeferralCondition[],
+  event: DeferralEvent,
+  state: "open" | "addressed",
+  actorId: string,
+  now: string
+): DeferralCondition[] {
+  const conditionId = readRequiredDeferralEventString(event, "conditionId");
+  let found = false;
+  const updated = conditions.map((condition) => {
+    if (condition.id !== conditionId) {
+      return condition;
+    }
+
+    found = true;
+    return {
+      ...condition,
+      state,
+      updatedAt: now,
+      updatedBy: actorId
+    };
+  });
+
+  if (!found) {
+    throw new Error(`Deferral condition not found: ${conditionId}`);
+  }
+
+  return updated;
+}
+
+function assertDeferralConditionExists(conditions: DeferralCondition[], event: DeferralEvent): void {
+  const conditionId = readRequiredDeferralEventString(event, "conditionId");
+  if (!conditions.some((condition) => condition.id === conditionId)) {
+    throw new Error(`Deferral condition not found: ${conditionId}`);
+  }
+}
+
+function readRequiredDeferralEventString(event: DeferralEvent, key: string): string {
+  const value = event[key];
+  if (typeof value !== "string" || !value.trim()) {
+    throw new Error(`${event.eventType} requires ${key}.`);
+  }
+  return value;
+}
+
+export async function listUnreadDxcompleteTicketReplies(
+  db: Db,
+  actor: ActorContext,
+  limit: number
+): Promise<DxcompleteTicketUnreadReplyResult[]> {
+  const records = await db
+    .collection<DxcRecord>(DXCOMPLETE_TICKET_COLLECTION_NAME)
+    .find({
+      "fields.ownerActorId": actor.actorId,
+      archivedAt: { $exists: false },
+      "fields.entries": {
+        $elemMatch: {
+          direction: "dxcomplete_reply",
+          addressedToActorId: actor.actorId,
+          readAt: { $exists: false }
+        }
+      }
+    })
+    .sort({ updatedAt: -1 })
+    .limit(limit)
+    .toArray();
+
+  return records.map((record) => {
+    const replies = normalizeTicketEntries(record.fields.entries).filter(
+      (entry) =>
+        entry.direction === "dxcomplete_reply" &&
+        entry.addressedToActorId === actor.actorId &&
+        !entry.readAt
+    );
+    const replySummaries = replies.map((entry) => ({
+      id: entry.id,
+      createdAt: entry.createdAt,
+      createdBy: entry.createdBy,
+      direction: "dxcomplete_reply" as const,
+      ...(entry.addressedToActorId ? { addressedToActorId: entry.addressedToActorId } : {})
+    }));
+    const newestReplyAt = replySummaries.reduce<string | undefined>(
+      (current, entry) => (!current || entry.createdAt > current ? entry.createdAt : current),
+      undefined
+    );
+
+    return {
+      ticketId: record._id,
+      ...(record.title ? { title: record.title } : {}),
+      updatedAt: record.updatedAt,
+      unreadReplyCount: replySummaries.length,
+      ...(newestReplyAt ? { newestReplyAt } : {}),
+      replies: replySummaries
+    };
+  });
+}
+
+export async function readDxcompleteTicket(
+  db: Db,
+  input: ReadDxcompleteTicketInput,
+  actor: ActorContext
+): Promise<DxcRecord> {
+  const collection = db.collection<DxcRecord>(DXCOMPLETE_TICKET_COLLECTION_NAME);
+  const existing = await collection.findOne(ticketOwnerFilter(input.id, actor));
+
+  if (!existing) {
+    throw new Error(`DX Complete Ticket not found: ${input.id}`);
+  }
+
+  const now = new Date().toISOString();
+  const entries = normalizeTicketEntries(existing.fields.entries);
+  let changed = false;
+  const nextEntries = entries.map((entry) => {
+    const shouldMark =
+      entry.direction === "dxcomplete_reply" &&
+      entry.addressedToActorId === actor.actorId &&
+      !entry.readAt;
+
+    if (!shouldMark) {
+      return entry;
+    }
+
+    changed = true;
+    return {
+      ...entry,
+      readAt: now
+    };
+  });
+
+  if (!changed) {
+    return existing;
+  }
+
+  await collection.updateOne(ticketOwnerFilter(input.id, actor), {
+    $set: {
+      "fields.entries": nextEntries,
+      updatedAt: now,
+      updatedBy: actor.actorId
+    }
+  });
+
+  return getDxcompleteTicket(db, input.id, actor);
+}
+
+export async function archiveDxcompleteTicket(
+  db: Db,
+  input: ArchiveDxcompleteTicketInput,
+  actor: ActorContext
+): Promise<DxcRecord> {
+  const collection = db.collection<DxcRecord>(DXCOMPLETE_TICKET_COLLECTION_NAME);
+  const existing = await collection.findOne(ticketOwnerFilter(input.id, actor));
+
+  if (!existing) {
+    throw new Error(`DX Complete Ticket not found: ${input.id}`);
+  }
+
+  if (existing.archivedAt) {
+    return existing;
+  }
+
+  const now = new Date().toISOString();
+  await collection.updateOne(ticketOwnerFilter(input.id, actor), {
+    $set: {
+      archivedAt: now,
+      updatedAt: now,
+      updatedBy: actor.actorId
+    }
+  });
+
+  return getDxcompleteTicket(db, input.id, actor);
+}
+
+export async function updateRecord(db: Db, input: UpdateRecordInput, actorId: string): Promise<DxcRecord> {
+  const collection = db.collection<DxcRecord>(input.recordType);
+  const recordFilter = scopedRecordFilter(input.recordType, input.id, input.workspaceId);
+  const existing = await collection.findOne(recordFilter);
+
+  if (!existing) {
+    throw new Error(`Record not found: ${input.recordType}/${input.id}`);
+  }
+
+  const now = new Date().toISOString();
+  const set: Record<string, unknown> = {
+    updatedAt: now,
+    updatedBy: actorId
+  };
+  const unset: Record<string, ""> = {};
+  const versioned = recordTypeSupportsVersionHistory(input.recordType);
+
+  if (input.title !== undefined) {
+    set.title = input.title;
+  }
+
+  if (input.summary !== undefined) {
+    set.summary = input.summary;
+  }
+
+  for (const [key, value] of Object.entries(input.fields ?? {})) {
+    assertFieldName(key);
+    assertNotReservedRelationshipField(input.recordType, key);
+    if (input.allowManagedFields) {
+      assertNotReviewNotesField(input.recordType, key);
+      assertNotVersionHistoryField(input.recordType, key);
+    } else {
+      assertNotManagedField(input.recordType, key);
+      assertNotVersionedTypedField(input.recordType, key);
+    }
+    set[`fields.${key}`] = value;
+  }
+
+  for (const key of input.unsetFields ?? []) {
+    assertFieldName(key);
+    if (input.allowManagedFields) {
+      assertNotReviewNotesField(input.recordType, key);
+      assertNotVersionHistoryField(input.recordType, key);
+    } else {
+      assertNotManagedField(input.recordType, key);
+      assertNotVersionedTypedField(input.recordType, key);
+    }
+    unset[`fields.${key}`] = "";
+  }
+
+  if (versioned) {
+    const previousSnapshot = createRecordVersionSnapshot(existing);
+    const nextSnapshot = createRecordVersionSnapshot(applyRecordUpdate(existing, input));
+    const changedFields = listSnapshotChanges(previousSnapshot, nextSnapshot);
+    const existingVersionHistory = normalizeVersionHistory(existing.fields.versionHistory);
+
+    if (changedFields.length === 0) {
+      return existing;
+    }
+
+    set["fields.versionHistory"] = [
+      ...existingVersionHistory,
+      createVersionHistoryEntry({
+        existingVersionHistory,
+        previousSnapshot,
+        nextSnapshot,
+        changedFields,
+        actorId,
+        createdAt: now,
+        revisionNote: input.revisionNote
+      })
+    ];
+  }
+
+  const update = Object.keys(unset).length > 0 ? { $set: set, $unset: unset } : { $set: set };
+  await collection.updateOne(recordFilter, update);
+
+  const updated = await collection.findOne(recordFilter);
+  if (!updated) {
+    throw new Error(`Updated record not found: ${input.recordType}/${input.id}`);
+  }
+
+  return updated;
+}
+
+function applyRecordUpdate(record: DxcRecord, input: UpdateRecordInput): DxcRecord {
+  const fields = { ...record.fields };
+
+  for (const [key, value] of Object.entries(input.fields ?? {})) {
+    fields[key] = value;
+  }
+
+  for (const key of input.unsetFields ?? []) {
+    delete fields[key];
+  }
+
+  return {
+    ...record,
+    ...(input.title !== undefined ? { title: input.title } : {}),
+    ...(input.summary !== undefined ? { summary: input.summary } : {}),
+    fields
+  };
+}
+
+function createRecordVersionSnapshot(record: DxcRecord): RecordVersionSnapshot {
+  return {
+    ...(record.title !== undefined ? { title: record.title } : {}),
+    ...(record.summary !== undefined ? { summary: record.summary } : {}),
+    fields: Object.fromEntries(
+      Object.entries(record.fields)
+        .filter(([key]) => key !== VERSION_HISTORY_FIELD && key !== "reviewNotes")
+        .map(([key, value]) => [key, cloneSnapshotValue(value)])
+    )
+  };
+}
+
+function listSnapshotChanges(
+  previousSnapshot: RecordVersionSnapshot,
+  nextSnapshot: RecordVersionSnapshot
+): string[] {
+  const changedFields: string[] = [];
+
+  if (!valuesEqual(previousSnapshot.title, nextSnapshot.title)) {
+    changedFields.push("title");
+  }
+
+  if (!valuesEqual(previousSnapshot.summary, nextSnapshot.summary)) {
+    changedFields.push("summary");
+  }
+
+  const fieldNames = new Set([
+    ...Object.keys(previousSnapshot.fields),
+    ...Object.keys(nextSnapshot.fields)
+  ]);
+
+  for (const fieldName of [...fieldNames].sort()) {
+    if (!valuesEqual(previousSnapshot.fields[fieldName], nextSnapshot.fields[fieldName])) {
+      changedFields.push(`fields.${fieldName}`);
+    }
+  }
+
+  return changedFields;
+}
+
+function normalizeVersionHistory(value: unknown): RecordVersionHistoryEntry[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+
+  return value.filter(isVersionHistoryEntry);
+}
+
+function createVersionHistoryEntry(input: {
+  existingVersionHistory: RecordVersionHistoryEntry[];
+  previousSnapshot: RecordVersionSnapshot;
+  nextSnapshot: RecordVersionSnapshot;
+  changedFields: string[];
+  actorId: string;
+  createdAt: string;
+  revisionNote?: string;
+}): RecordVersionHistoryEntry {
+  const fromVersion = input.existingVersionHistory.reduce(
+    (currentVersion, entry) => Math.max(currentVersion, entry.toVersion),
+    1
+  );
+
+  return {
+    id: randomUUID(),
+    fromVersion,
+    toVersion: fromVersion + 1,
+    createdAt: input.createdAt,
+    createdBy: input.actorId,
+    changedFields: input.changedFields,
+    previousSnapshot: input.previousSnapshot,
+    nextSnapshot: input.nextSnapshot,
+    ...(input.revisionNote ? { revisionNote: input.revisionNote } : {})
+  };
+}
+
+function isVersionHistoryEntry(value: unknown): value is RecordVersionHistoryEntry {
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+
+  const candidate = value as Partial<RecordVersionHistoryEntry>;
+  return (
+    typeof candidate.id === "string" &&
+    typeof candidate.fromVersion === "number" &&
+    typeof candidate.toVersion === "number" &&
+    typeof candidate.createdAt === "string" &&
+    typeof candidate.createdBy === "string" &&
+    Array.isArray(candidate.changedFields) &&
+    typeof candidate.previousSnapshot === "object" &&
+    typeof candidate.nextSnapshot === "object"
+  );
+}
+
+function cloneSnapshotValue(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map((entry) => cloneSnapshotValue(entry));
+  }
+
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value as Record<string, unknown>)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, entry]) => [key, cloneSnapshotValue(entry)])
+    );
+  }
+
+  return value;
+}
+
+function valuesEqual(left: unknown, right: unknown): boolean {
+  return stableStringify(left) === stableStringify(right);
+}
+
+function stableStringify(value: unknown): string {
+  return JSON.stringify(cloneSnapshotValue(value));
+}
+
+export async function archiveRecord(db: Db, input: ArchiveRecordInput, actorId: string): Promise<DxcRecord> {
+  const collection = db.collection<DxcRecord>(input.recordType);
+  const recordFilter = scopedRecordFilter(input.recordType, input.id, input.workspaceId);
+  const existing = await collection.findOne(recordFilter);
+
+  if (!existing) {
+    throw new Error(`Record not found: ${input.recordType}/${input.id}`);
+  }
+
+  if ((input.supersededByType && !input.supersededById) || (!input.supersededByType && input.supersededById)) {
+    throw new Error("supersededByType and supersededById must be provided together.");
+  }
+
+  const supersedingRecord =
+    input.supersededByType && input.supersededById
+      ? await getRecord(db, input.supersededByType, input.supersededById, {
+          workspaceId: existing.workspaceId
+        })
+      : null;
+
+  if (input.supersededByType && input.supersededById && !supersedingRecord) {
+    throw new Error(`Superseding record not found: ${input.supersededByType}/${input.supersededById}`);
+  }
+
+  const now = new Date().toISOString();
+  const links = [...existing.links];
+
+  if (input.supersededByType && input.supersededById) {
+    links.push({
+      toType: input.supersededByType,
+      toId: supersedingRecord?._id ?? input.supersededById,
+      relationship: "superseded_by",
+      createdAt: now,
+      createdBy: actorId
+    });
+  }
+
+  await collection.updateOne(
+    recordFilter,
+    {
+      $set: {
+        links,
+        archivedAt: now,
+        archivedBy: actorId,
+        archiveReason: input.reason ?? "Archived",
+        updatedAt: now,
+        updatedBy: actorId
+      }
+    }
+  );
+
+  const updated = await collection.findOne(recordFilter);
+  if (!updated) {
+    throw new Error(`Archived record not found: ${input.recordType}/${input.id}`);
+  }
+
+  return updated;
+}
+
+export async function linkRecords(
+  db: Db,
+  input: {
+    fromType: CollectionName;
+    fromId: string;
+    toType: CollectionName;
+    toId: string;
+    workspaceId?: string;
+    relationship?: string;
+  },
+  actorId: string
+): Promise<DxcRecord> {
+  const sourceCollection = db.collection<DxcRecord>(input.fromType);
+  const source = await getRecord(db, input.fromType, input.fromId, {
+    workspaceId: input.workspaceId
+  });
+  const target = await getRecord(db, input.toType, input.toId, {
+    workspaceId: input.workspaceId
+  });
+
+  if (!source) {
+    throw new Error(`Source record not found: ${input.fromType}/${input.fromId}`);
+  }
+
+  if (!target) {
+    throw new Error(`Target record not found: ${input.toType}/${input.toId}`);
+  }
+
+  assertLinkWorkspaceBoundary(source, target);
+
+  const now = new Date().toISOString();
+  const link: RecordLink = {
+    toType: input.toType,
+    toId: target._id,
+    relationship: input.relationship ?? "related_to",
+    createdAt: now,
+    createdBy: actorId
+  };
+
+  await sourceCollection.updateOne(
+    scopedRecordFilter(input.fromType, source._id, input.workspaceId),
+    {
+      $push: { links: link },
+      $set: {
+        updatedAt: now,
+        updatedBy: actorId
+      }
+    }
+  );
+
+  const updated = await sourceCollection.findOne(scopedRecordFilter(input.fromType, source._id, input.workspaceId));
+  if (!updated) {
+    throw new Error(`Updated source record not found: ${input.fromType}/${input.fromId}`);
+  }
+
+  return updated;
+}
+
+export async function unlinkRecords(
+  db: Db,
+  input: UnlinkRecordsInput,
+  actorId: string
+): Promise<DxcRecord> {
+  const sourceCollection = db.collection<DxcRecord>(input.fromType);
+  const source = await getRecord(db, input.fromType, input.fromId, {
+    workspaceId: input.workspaceId
+  });
+  const target = await getRecord(db, input.toType, input.toId, {
+    workspaceId: input.workspaceId
+  });
+
+  if (!source) {
+    throw new Error(`Source record not found: ${input.fromType}/${input.fromId}`);
+  }
+
+  if (!target) {
+    throw new Error(`Target record not found: ${input.toType}/${input.toId}`);
+  }
+
+  assertLinkWorkspaceBoundary(source, target);
+
+  const relationship = input.relationship ?? "related_to";
+  const remainingLinks = source.links.filter(
+    (link) =>
+      !(
+        link.toType === input.toType &&
+        link.toId === target._id &&
+        link.relationship === relationship
+      )
+  );
+
+  if (remainingLinks.length === source.links.length) {
+    return source;
+  }
+
+  const now = new Date().toISOString();
+  await sourceCollection.updateOne(
+    scopedRecordFilter(input.fromType, source._id, input.workspaceId),
+    {
+      $set: {
+        links: remainingLinks,
+        updatedAt: now,
+        updatedBy: actorId
+      }
+    }
+  );
+
+  const updated = await sourceCollection.findOne(scopedRecordFilter(input.fromType, source._id, input.workspaceId));
+  if (!updated) {
+    throw new Error(`Updated source record not found: ${input.fromType}/${input.fromId}`);
+  }
+
+  return updated;
+}
+
+function assertFieldName(key: string): void {
+  if (!/^[A-Za-z_][A-Za-z0-9_-]*$/.test(key)) {
+    throw new Error(`Invalid field name "${key}". Field updates only support top-level field names.`);
+  }
+}
+
+function assertNoReservedRelationshipFields(
+  recordType: CollectionName,
+  fields: Record<string, unknown> | undefined
+): void {
+  for (const key of Object.keys(fields ?? {})) {
+    assertNotReservedRelationshipField(recordType, key);
+  }
+}
+
+function assertNoReviewNotesField(recordType: CollectionName, fields: Record<string, unknown> | undefined): void {
+  for (const key of Object.keys(fields ?? {})) {
+    assertNotReviewNotesField(recordType, key);
+  }
+}
+
+function assertNoManagedField(recordType: CollectionName, fields: Record<string, unknown> | undefined): void {
+  for (const key of Object.keys(fields ?? {})) {
+    assertNotManagedField(recordType, key);
+  }
+}
+
+function assertNotReservedRelationshipField(recordType: CollectionName, key: string): void {
+  if (key === "workspaceId" && recordTypeRequiresWorkspace(recordType)) {
+    throw new Error(
+      `fields.${key} is reserved for the workspace boundary on ${recordType}. Use the top-level ${key} argument instead.`
+    );
+  }
+
+  if (key === "initiativeId" && REMOVED_INITIATIVE_FIELD_RECORD_TYPES.includes(recordType)) {
+    throw new Error(
+      `fields.${key} belongs to the removed Initiative layer on ${recordType}. Records are scoped directly to workspace now.`
+    );
+  }
+
+  if ((RESERVED_RELATIONSHIP_FIELDS[recordType] ?? []).includes(key)) {
+    throw new Error(
+      `fields.${key} is reserved for relationships on ${recordType}. Use the typed relationship argument or link_records instead.`
+    );
+  }
+}
+
+function assertNotManagedField(recordType: CollectionName, key: string): void {
+  assertNotReviewNotesField(recordType, key);
+  assertNotVersionHistoryField(recordType, key);
+  assertNotChangeManagedField(recordType, key);
+  assertNotCommitmentManagedField(recordType, key);
+  assertNotDeferralManagedField(recordType, key);
+  assertNotEstimateManagedField(recordType, key);
+  assertNotBenefitsManagedField(recordType, key);
+  assertNotEnvironmentManagedField(recordType, key);
+  assertNotComponentManagedField(recordType, key);
+  assertNotDecisionLedgerManagedField(recordType, key);
+  assertNotTaskLedgerManagedField(recordType, key);
+  assertNotDecisionInputManagedField(recordType, key);
+  assertNotJournalEntryManagedField(recordType, key);
+}
+
+function assertNotVersionedTypedField(recordType: CollectionName, key: string): void {
+  if (!(VERSIONED_TYPED_FIELDS[recordType] ?? []).includes(key)) {
+    return;
+  }
+
+  throw new Error(`fields.${key} is managed on ${recordType}. Use ${versionedUpdateToolName(recordType)} to change it.`);
+}
+
+function assertNotReviewNotesField(recordType: CollectionName, key: string): void {
+  if (key !== "reviewNotes" || !recordTypeSupportsReviewNotes(recordType)) {
+    return;
+  }
+
+  throw new Error(
+    `fields.reviewNotes is append-only on ${recordType}. Use append_review_note instead of setting or unsetting it directly.`
+  );
+}
+
+function assertNotVersionHistoryField(recordType: CollectionName, key: string): void {
+  if (key !== VERSION_HISTORY_FIELD || !recordTypeSupportsVersionHistory(recordType)) {
+    return;
+  }
+
+  throw new Error(
+    `fields.versionHistory is append-only on ${recordType}. Current content changes record version history automatically.`
+  );
+}
+
+function assertNotChangeManagedField(recordType: CollectionName, key: string): void {
+  if (recordType !== "changes" || !(CHANGE_MANAGED_FIELDS as readonly string[]).includes(key)) {
+    return;
+  }
+
+  throw new Error(
+    `fields.${key} is managed on changes. Use create_change for the baseline and append_change_event for event history or plan revisions.`
+  );
+}
+
+function assertNotCommitmentManagedField(recordType: CollectionName, key: string): void {
+  if (recordType !== "commitments" || !(COMMITMENT_MANAGED_FIELDS as readonly string[]).includes(key)) {
+    return;
+  }
+
+  throw new Error(
+    `fields.${key} is managed on commitments. Use create_commitment instead of setting or unsetting it directly.`
+  );
+}
+
+function assertNotDeferralManagedField(recordType: CollectionName, key: string): void {
+  if (recordType !== "deferrals" || !(DEFERRAL_MANAGED_FIELDS as readonly string[]).includes(key)) {
+    return;
+  }
+
+  throw new Error(
+    `fields.${key} is managed on deferrals. Use create_deferral for the baseline and append_deferral_event for condition history or resolution.`
+  );
+}
+
+function assertNotEstimateManagedField(recordType: CollectionName, key: string): void {
+  if (recordType !== "estimates" || !(ESTIMATE_MANAGED_FIELDS as readonly string[]).includes(key)) {
+    return;
+  }
+
+  throw new Error(
+    `fields.${key} is managed on estimates. Use create_estimate or update_estimate instead of setting or unsetting it directly.`
+  );
+}
+
+function assertNotBenefitsManagedField(recordType: CollectionName, key: string): void {
+  if (recordType !== "benefits" || !(BENEFITS_MANAGED_FIELDS as readonly string[]).includes(key)) {
+    return;
+  }
+
+  throw new Error(
+    `fields.${key} is managed on benefits. Use create_benefits or update_benefits instead of setting or unsetting it directly.`
+  );
+}
+
+function assertNotEnvironmentManagedField(recordType: CollectionName, key: string): void {
+  if (recordType !== "environments" || !(ENVIRONMENT_MANAGED_FIELDS as readonly string[]).includes(key)) {
+    return;
+  }
+
+  throw new Error(
+    `fields.${key} is managed on environments. Use create_environment or update_environment instead of setting or unsetting it directly.`
+  );
+}
+
+function assertNotComponentManagedField(recordType: CollectionName, key: string): void {
+  if (recordType !== "components" || !(COMPONENT_MANAGED_FIELDS as readonly string[]).includes(key)) {
+    return;
+  }
+
+  throw new Error(
+    `fields.${key} is managed on components. Use create_component or update_component instead of setting or unsetting it directly.`
+  );
+}
+
+function assertNotDecisionLedgerManagedField(recordType: CollectionName, key: string): void {
+  if (recordType !== "decisions" || !(DECISION_LEDGER_MANAGED_FIELDS as readonly string[]).includes(key)) {
+    return;
+  }
+
+  throw new Error(
+    `fields.${key} is managed on decisions. Use create_decision or append_decision_entry instead of setting or unsetting it directly.`
+  );
+}
+
+function assertNotTaskLedgerManagedField(recordType: CollectionName, key: string): void {
+  if (recordType !== "tasks" || !(TASK_LEDGER_MANAGED_FIELDS as readonly string[]).includes(key)) {
+    return;
+  }
+
+  throw new Error(
+    `fields.${key} is managed on tasks. Use create_task or append_task_entry instead of setting or unsetting it directly.`
+  );
+}
+
+function assertNotDecisionInputManagedField(recordType: CollectionName, key: string): void {
+  if (recordType !== "decisions" || !(DECISION_INPUT_MANAGED_FIELDS as readonly string[]).includes(key)) {
+    return;
+  }
+
+  throw new Error(
+    `fields.${key} is managed on decisions. Use link_decision_input to record decision inputs.`
+  );
+}
+
+function assertNotJournalEntryManagedField(recordType: CollectionName, key: string): void {
+  if (recordType !== "journal_entries" || !(JOURNAL_ENTRY_MANAGED_FIELDS as readonly string[]).includes(key)) {
+    return;
+  }
+
+  throw new Error(
+    `fields.${key} is managed on journal entries. Use append_journal_note or append_journal_summary instead of setting or unsetting it directly.`
+  );
+}
+
+function linkMatches(link: RecordLink, relationship: string | undefined): boolean {
+  return !relationship || link.relationship === relationship;
+}
+
+function recordTypeSupportsReviewNotes(recordType: CollectionName): recordType is ReviewableRecordType {
+  return (REVIEW_NOTE_RECORD_TYPES as readonly string[]).includes(recordType);
+}
+
+function recordTypeSupportsVersionHistory(recordType: CollectionName): boolean {
+  return (VERSIONED_RECORD_TYPES as readonly string[]).includes(recordType);
+}
+
+function versionedUpdateToolName(recordType: CollectionName): string {
+  if (recordType === "environments") {
+    return "update_environment";
+  }
+
+  if (recordType === "components") {
+    return "update_component";
+  }
+
+  if (recordType === "estimates") {
+    return "update_estimate";
+  }
+
+  if (recordType === "benefits") {
+    return "update_benefits";
+  }
+
+  if (recordType === "statements") {
+    return "update_statement";
+  }
+
+  return recordType === "expectations" ? "update_expectation" : "update_requirement";
+}
+
+function isCurrentCollection(recordType: RuntimeCollectionName): recordType is CollectionName {
+  return (COLLECTION_NAMES as readonly string[]).includes(recordType);
+}
+
+function recordTypeRequiresWorkspace(recordType: RuntimeCollectionName): boolean {
+  return recordType !== "workspaces" && recordType !== DXCOMPLETE_TICKET_COLLECTION_NAME;
+}
+
+function readRequiredWorkspaceId(workspaceId: string | undefined, recordType: RuntimeCollectionName): string {
+  const trimmed = workspaceId?.trim();
+
+  if (!trimmed) {
+    throw new Error(`${recordType} records require workspaceId.`);
+  }
+
+  return trimmed;
+}
+
+function workspaceIdForCreate(recordType: CollectionName, workspaceId: string | undefined): string | undefined {
+  if (!recordTypeRequiresWorkspace(recordType)) {
+    if (workspaceId?.trim()) {
+      throw new Error("Workspace records do not accept workspaceId.");
+    }
+    return undefined;
+  }
+
+  return readRequiredWorkspaceId(workspaceId, recordType);
+}
+
+async function allocateReadableId(
+  db: Db,
+  recordType: ReadableIdCollectionName,
+  workspaceId: string | undefined,
+  actorId: string,
+  now: string,
+  session: ClientSession
+): Promise<string> {
+  const scopedWorkspaceId = readRequiredWorkspaceId(workspaceId, recordType);
+  const sequenceId = `${scopedWorkspaceId}:${recordType}`;
+  const sequence = await db.collection<ReadableIdSequenceRecord>(READABLE_ID_SEQUENCES_COLLECTION).findOneAndUpdate(
+    { _id: sequenceId },
+    {
+      $inc: { nextNumber: 1 },
+      $set: {
+        updatedAt: now,
+        updatedBy: actorId
+      },
+      $setOnInsert: {
+        _id: sequenceId,
+        workspaceId: scopedWorkspaceId,
+        recordType,
+        createdAt: now,
+        createdBy: actorId
+      }
+    },
+    {
+      upsert: true,
+      returnDocument: "after",
+      session
+    }
+  );
+
+  if (!sequence || !Number.isInteger(sequence.nextNumber) || sequence.nextNumber < 1) {
+    throw new Error(`Readable ID sequence was not allocated for ${recordType}.`);
+  }
+
+  return `${READABLE_ID_TYPE_CODES[recordType]}-${String(sequence.nextNumber).padStart(4, "0")}`;
+}
+
+type ReadableIdSequenceRecord = {
+  _id: string;
+  workspaceId: string;
+  recordType: ReadableIdCollectionName;
+  nextNumber: number;
+  createdAt: string;
+  createdBy: string;
+  updatedAt: string;
+  updatedBy: string;
+};
+
+function recordTypeSupportsReadableId(recordType: RuntimeCollectionName): recordType is ReadableIdCollectionName {
+  return Object.hasOwn(READABLE_ID_TYPE_CODES, recordType);
+}
+
+function normalizeReadableId(value: string): string {
+  return value.trim().toUpperCase();
+}
+
+function recordIdentityFilter(recordType: RuntimeCollectionName, id: string): Record<string, unknown> {
+  if (!recordTypeSupportsReadableId(recordType)) {
+    return { _id: id };
+  }
+
+  return {
+    $or: [
+      { _id: id },
+      { readableId: normalizeReadableId(id) }
+    ]
+  };
+}
+
+function scopedRecordFilter(
+  recordType: CollectionName,
+  id: string,
+  workspaceId: string | undefined
+): Record<string, unknown> {
+  const filter = recordIdentityFilter(recordType, id);
+
+  if (recordTypeRequiresWorkspace(recordType)) {
+    filter.workspaceId = readRequiredWorkspaceId(workspaceId, recordType);
+  }
+
+  return filter;
+}
+
+async function assertWorkspaceExists(db: Db, workspaceId: string): Promise<DxcRecord> {
+  const workspace = await db.collection<DxcRecord>("workspaces").findOne({
+    _id: workspaceId,
+    archivedAt: { $exists: false }
+  });
+
+  if (!workspace) {
+    throw new Error(`Workspace not found: workspaces/${workspaceId}`);
+  }
+
+  return workspace;
+}
+
+function recordBelongsToWorkspace(record: DxcRecord, workspaceId: string | undefined): boolean {
+  return !workspaceId || record.recordType === "workspaces" || record.workspaceId === workspaceId;
+}
+
+function assertLinkWorkspaceBoundary(source: DxcRecord, target: DxcRecord): void {
+  if (!source.workspaceId || !target.workspaceId) {
+    return;
+  }
+
+  if (source.workspaceId !== target.workspaceId) {
+    throw new Error(
+      `Cannot link records across workspaces: ${source.recordType}/${source._id} is in ${source.workspaceId}, while ${target.recordType}/${target._id} is in ${target.workspaceId}.`
+    );
+  }
+}
+
+function ticketOwnerFilter(id: string, actor: ActorContext): Record<string, unknown> {
+  return {
+    _id: id,
+    "fields.ownerActorId": actor.actorId
+  };
+}
+
+function normalizeTicketEntries(value: unknown): DxcompleteTicketEntry[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+
+  return value.flatMap((entry, index) => normalizeTicketEntry(entry, index));
+}
+
+function normalizeTicketEntry(entry: unknown, index: number): DxcompleteTicketEntry[] {
+  if (!entry || typeof entry !== "object") {
+    return [];
+  }
+
+  const candidate = entry as Record<string, unknown>;
+  const body = typeof candidate.body === "string" ? candidate.body : "";
+
+  if (!body) {
+    return [];
+  }
+
+  const createdAt = typeof candidate.createdAt === "string" ? candidate.createdAt : new Date(0).toISOString();
+  const createdBy = typeof candidate.createdBy === "string" ? candidate.createdBy : RUNTIME_ACTOR_ID;
+  const direction =
+    candidate.direction === "dxcomplete_reply" || candidate.direction === "submitter_entry"
+      ? candidate.direction
+      : "submitter_entry";
+  const normalized: DxcompleteTicketEntry = {
+    id: typeof candidate.id === "string" && candidate.id ? candidate.id : `legacy-entry-${index + 1}`,
+    body,
+    createdAt,
+    createdBy,
+    direction
+  };
+
+  if (typeof candidate.addressedToActorId === "string" && candidate.addressedToActorId) {
+    normalized.addressedToActorId = candidate.addressedToActorId;
+  }
+
+  if (typeof candidate.readAt === "string" && candidate.readAt) {
+    normalized.readAt = candidate.readAt;
+  }
+
+  return [normalized];
+}