dxcomplete 0.1.0

package/src/mcp/server.ts

@@ -0,0 +1,3525 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { createHash, randomUUID } from "node:crypto";
+import * as z from "zod/v4";
+import { DOC_PAGE_IDS, DOC_REFERENCE, getDocReference } from "./docs.js";
+import { createLocalActorContext, type ActorContext } from "../runtime/actor.js";
+import type { WorkspaceRole } from "../runtime/auth.js";
+import type { DxRuntime } from "../runtime/mongo.js";
+import {
+  DXCOMPLETE_PACKAGE_VERSION,
+  MCP_SURFACE_ID,
+  WORKSPACE_COMPATIBILITY_VERSION
+} from "../version.js";
+import {
+  COLLECTION_NAMES,
+  RUNTIME_ACTOR_ID,
+  appendChangeEvent,
+  appendDecisionEntry,
+  appendDeferralEvent,
+  appendJournalNote,
+  appendJournalSummary,
+  appendReviewNote,
+  appendTaskEntry,
+  archiveRecord,
+  appendDxcompleteTicket,
+  archiveDxcompleteTicket,
+  type CollectionName,
+  type DecisionEntry,
+  decisionEntryToCurrentDecision,
+  createDxcompleteTicket,
+  createRecord,
+  getJournalEntry,
+  getRecord,
+  linkRecords,
+  listDxcompleteTickets,
+  listLinkedRecords,
+  listUnreadDxcompleteTicketReplies,
+  listRecords,
+  readJournal,
+  readDxcompleteTicket,
+  type TaskEntry,
+  taskEntryToCurrentStatus,
+  unlinkRecords,
+  updateRecord
+} from "../runtime/records.js";
+
+const collectionSchema = z.enum(COLLECTION_NAMES);
+type WorkspaceScopedCollectionName = Exclude<CollectionName, "workspaces">;
+const workspaceScopedCollectionNames = COLLECTION_NAMES.filter(
+  (name): name is WorkspaceScopedCollectionName => name !== "workspaces"
+) as [WorkspaceScopedCollectionName, ...WorkspaceScopedCollectionName[]];
+const hostedCollectionSchema = z.enum(workspaceScopedCollectionNames);
+const amountSchema = z.number().finite().optional();
+const requiredAmountSchema = z.number().finite().nonnegative();
+const currencySchema = z.string().min(3).max(12).optional();
+const requiredCurrencySchema = z.string().min(3).max(12);
+const workspaceIdSchema = z.string().min(1);
+const workspaceModeSchema = z.enum(["transformation", "greenfield", "limited-disclosure"]);
+const expectationApprovalStateSchema = z.enum(["draft", "approved", "not_approved", "superseded"]);
+const requirementStatusSchema = z.enum(["draft", "ready", "approved", "superseded"]);
+const taskStatusSchema = z.enum(["open", "in_progress", "blocked", "done"]);
+const decisionEntryTypeSchema = z.enum(["argument", "decision", "note"]);
+const taskEntryTypeSchema = z.enum(["comment", "status_change", "note"]);
+const reviewableRecordTypeSchema = z.enum(["expectations", "requirements"]);
+const decisionInputRecordTypes = [
+  "expectations",
+  "requirements",
+  "commitments",
+  "deferrals",
+  "journal_entries",
+  "environments",
+  "components",
+  "estimates",
+  "benefits",
+  "risks",
+  "changes",
+  "decisions"
+] as const;
+const decisionInputRecordTypeSchema = z.enum(decisionInputRecordTypes);
+type DecisionInputRecordType = (typeof decisionInputRecordTypes)[number];
+const changeEventTypeSchema = z.enum([
+  "notice_given",
+  "veto_recorded",
+  "emergency_declared",
+  "decision_recorded",
+  "result_reported",
+  "recovery_recorded",
+  "plan_revised",
+  "note_added"
+]);
+const changeVetoRoleSchema = z.enum(["Owner", "Engineer"]);
+const changeDecisionSchema = z.enum(["proceed", "defer", "cancel"]);
+const changeResultSchema = z.enum(["completed", "failed", "rolled_back"]);
+const deferralEventTypeSchema = z.enum([
+  "condition_addressed",
+  "condition_reopened",
+  "condition_note_added",
+  "deferral_resolved",
+  "deferral_abandoned"
+]);
+const journalTagSchema = z.string().min(1).max(80);
+const recordFieldsSchema = z.record(z.string(), z.unknown()).optional();
+const amountInputSchema = z.union([
+  z.object({
+    kind: z.literal("single"),
+    value: requiredAmountSchema
+  }),
+  z.object({
+    kind: z.literal("range"),
+    min: requiredAmountSchema,
+    expected: requiredAmountSchema,
+    max: requiredAmountSchema
+  })
+]);
+const timingSchema = z.enum(["one_time", "recurring"]);
+const estimateLineItemSchema = z.object({
+  id: z.string().min(1).optional(),
+  label: z.string().min(1),
+  timing: timingSchema,
+  period: z.string().min(1).optional(),
+  currency: requiredCurrencySchema,
+  amount: amountInputSchema
+}).strict();
+type EstimateLineItemInput = z.infer<typeof estimateLineItemSchema>;
+const benefitItemSchema = z.object({
+  id: z.string().min(1).optional(),
+  label: z.string().min(1),
+  timing: timingSchema.optional(),
+  period: z.string().min(1).optional(),
+  currency: requiredCurrencySchema.optional(),
+  amount: amountInputSchema.optional()
+}).strict();
+type BenefitItemInput = z.infer<typeof benefitItemSchema>;
+const componentLocatorSchema = z.record(z.string().min(1), z.unknown()).refine(
+  (value) => Object.keys(value).length > 0,
+  "locator must be a non-empty structured object."
+);
+const componentIdentifiersSchema = z.record(z.string().min(1), z.unknown()).optional();
+const secretPointerSchema = z.object({
+  store: z.string().min(1),
+  key: z.string().min(1),
+  location: z.string().min(1).optional(),
+  url: z.string().min(1).optional(),
+  note: z.string().min(1).optional()
+}).strict();
+type ComponentLocatorInput = z.infer<typeof componentLocatorSchema>;
+type ComponentIdentifiersInput = z.infer<typeof componentIdentifiersSchema>;
+type SecretPointerInput = z.infer<typeof secretPointerSchema>;
+const decisionInitialEntrySchema = z.object({
+  entryType: decisionEntryTypeSchema,
+  body: z.string().min(1),
+  decidedBy: z.string().min(1).optional(),
+  rationale: z.string().min(1).optional()
+}).strict();
+type DecisionInitialEntryInput = z.infer<typeof decisionInitialEntrySchema>;
+const initialDecisionSchema = z.object({
+  body: z.string().min(1),
+  decidedBy: z.string().min(1).optional(),
+  rationale: z.string().min(1).optional()
+}).strict();
+type InitialDecisionInput = z.infer<typeof initialDecisionSchema>;
+const fieldNameSchema = z
+  .string()
+  .regex(/^[A-Za-z_][A-Za-z0-9_-]*$/, "Only top-level field names are supported.");
+const SERVER_STARTED_AT = new Date().toISOString();
+const STATEMENT_TYPED_FIELDS = ["statement", "source"];
+const EXPECTATION_TYPED_FIELDS = [
+  "statement",
+  "successRecognition",
+  "approvalState",
+  "approvedBy",
+  "approvedAt",
+  "source"
+];
+const REQUIREMENT_TYPED_FIELDS = [
+  "statement",
+  "acceptanceCriteria",
+  "priority",
+  "status"
+];
+const CHANGE_TYPED_FIELDS = [
+  "changePlan",
+  "executionSteps",
+  "rollbackPlan",
+  "riskImpact",
+  "plannedFor",
+  "events"
+];
+const COMMITMENT_TYPED_FIELDS = ["commitmentStatement", "reservations"];
+const DEFERRAL_TYPED_FIELDS = ["reason", "status", "conditions", "conditionEvents"];
+const ESTIMATE_TYPED_FIELDS = ["lineItems", "rollup", "versionHistory"];
+const BENEFITS_TYPED_FIELDS = ["benefitItems", "rollup", "versionHistory"];
+const ENVIRONMENT_TYPED_FIELDS = ["name", "description", "versionHistory"];
+const COMPONENT_TYPED_FIELDS = [
+  "name",
+  "environmentId",
+  "kind",
+  "locator",
+  "identifiers",
+  "secretPointers",
+  "notes",
+  "versionHistory"
+];
+const OBSOLETE_EXPECTATION_FIELDS = ["confirmationState", "ratifiedBy", "ratifiedAt"];
+const DECISION_INPUT_FIELDS = ["informedBy", "informedByIds", "inputRecords"];
+const DECISION_TYPED_FIELDS = [
+  "workspaceId",
+  "matter",
+  "entries",
+  "currentDecision",
+  "question",
+  "decision",
+  "decidedBy",
+  "rationale",
+  "argumentsConsidered",
+  "concerns",
+  "status"
+];
+const TASK_TYPED_FIELDS = ["workspaceId", "description", "assignee", "assignor", "entries", "currentStatus", "details", "status"];
+const PROCESS_GUIDE = {
+  name: "DX Complete process guide",
+  status:
+    "Current operating guidance for working inside DX Complete. It is a lean guide for MCP clients; it is not the full reference, not a final model, and not a validation rule.",
+  currentFlow: ["Statement", "Expectation", "Requirement", "Commitment"],
+  phaseGuidance: [
+    "These phases describe a typical first-pass order and each has a target end-state, but they are non-terminal and re-enterable: at any point the most useful next activity may belong to any phase, including returning to an earlier one, and no phase is ever closed or locked behind you."
+  ],
+  crossCuttingRecords: [
+    {
+      record: "Journal",
+      use: "Shared workspace context that does not yet belong in a dedicated record; use dedicated records first and Journal only as the fallback."
+    },
+    {
+      record: "Task",
+      use: "Execution work that can be created whenever a phase needs concrete action; Task is not part of the Statement, Expectation, Requirement, Commitment sequence."
+    },
+    {
+      record: "Decision",
+      use: "A recorded choice that can appear in any phase when a meaningful decision needs to remain legible."
+    }
+  ],
+  recordRoutingGuidance: {
+    principle:
+      "Use the dedicated record first. Journal is the fallback for relevant workspace context only when no dedicated record fits.",
+    sharpTest:
+      "Will anything reference or depend on this? If yes, prefer a dedicated record that can carry the relationship.",
+    routingOrder: [
+      {
+        when: "The information is desired truth, success criteria, or a buildable commitment.",
+        use: "Use Statement, Expectation, or Requirement."
+      },
+      {
+        when: "The information is a choice weighed between alternatives.",
+        use: "Use Decision."
+      },
+      {
+        when: "The information is an action someone needs to do.",
+        use: "Use Task."
+      },
+      {
+        when: "The information is an event or controlled service/process history.",
+        use: "Use Change, Risk, or the matching event/history record."
+      },
+      {
+        when: "The information is operational infrastructure state.",
+        use: "Use Environment and Component records in the Operational Registry; do not use Journal as the long-term home."
+      },
+      {
+        when: "The information is relevant context with no better home.",
+        use: "Use Journal."
+      }
+    ],
+    promotion:
+      "If Journal content becomes load-bearing, promote it to the appropriate dedicated record and link back where useful."
+  },
+  phases: [
+    {
+      id: "orient",
+      name: "Orient",
+      purpose:
+        "Capture the desired outcome in plain terms, restate expectations, and confirm how success will be recognized where possible.",
+      commonRecords: ["Workspace", "Statement", "Expectation", "DX Complete Ticket"],
+      processConcepts: [],
+      handoff:
+        "Expectations describe the desired outcome clearly enough to elicit requirements, or any missing approval is visible as open risk.",
+      operatingGuidance: {
+        clientRole: "Help the user express the desired outcome in their terms, confirm captured wording before recording, and prepare expectations for approval where needed.",
+        conductRules: [
+          "Elicit the person's Statement; do not invent it.",
+          "When the client articulates Statement or Expectation wording on a user's behalf, confirm that wording before recording it.",
+          "Do not store same-person capture-confirmation as record state.",
+          "Stay in plain outcome language.",
+          "Do not move into technical solution design during Orient.",
+          "Treat missing separate authority approval as visible open risk, not as a process block."
+        ],
+        questionsToAsk: [
+          "What problem, need, or outcome should DX Complete help clarify?",
+          "What would make this successful from the user's point of view?",
+          "How will people recognize that the expected outcome has been met?",
+          "Is this wording accurate enough to record and use as the basis for requirements?"
+        ],
+        expectedOutput: [
+          "Statement record in the person's language.",
+          "Restated Expectations with success recognition.",
+          "Owner approval where available, or visible open risk where approval is missing."
+        ],
+        exitCheck:
+          "Move to Elicit when expectations are clear enough to translate into requirements, or when proceeding without separate authority approval is visible as open risk.",
+        checkpointNotes: [
+          "Owner approval reduces wrong-outcome risk.",
+          "Unapproved expectations can move forward only when the risk is explicit."
+        ]
+      }
+    },
+    {
+      id: "elicit",
+      name: "Elicit",
+      purpose: "Translate expectations into requirements, dependencies, assumptions, unknowns, and risk.",
+      commonRecords: ["Statement", "Expectation", "Requirement", "Risk", "Decision", "DX Complete Ticket"],
+      processConcepts: ["Requirement"],
+      handoff: "The requirement set is clear enough to estimate cost, value, risk, and confidence, or the open risk is visible.",
+      operatingGuidance: {
+        clientRole: "Translate approved or visibly unapproved expectations into requirements and related delivery facts.",
+        conductRules: [
+          "Keep each requirement tied to the expectation it is meant to satisfy.",
+          "Separate requirements from implementation tasks.",
+          "Surface dependencies, assumptions, unknowns, and risks before estimating.",
+          "Use review notes for Engineer input on expectations or requirements; do not treat review notes as approval, objection state, or blockers.",
+          "Do not treat uncertain details as settled requirements."
+        ],
+        questionsToAsk: [
+          "What must be true for each expectation to be satisfied?",
+          "What dependencies, constraints, or unknowns could affect the work?",
+          "What assumptions are being made because information is incomplete?",
+          "Which risks should be visible before the Owner weighs the work?"
+        ],
+        expectedOutput: [
+          "A requirement set.",
+          "Review notes where Engineer input should stay visible.",
+          "Known dependencies, assumptions, unknowns, and risks.",
+          "Open questions, visible risks, or follow-ups where clarity is incomplete."
+        ],
+        exitCheck:
+          "Move to Weigh when the requirement set is clear enough to support cost, value, risk, and confidence discussion.",
+        checkpointNotes: [
+          "Requirement clarity reduces estimate risk.",
+          "Open unknowns can move forward when they are recorded as visible risk or follow-up."
+        ]
+      }
+    },
+    {
+      id: "weigh",
+      name: "Weigh",
+      purpose:
+        "Compare expected cost, expected value, risks, and confidence before recording a Commitment or Deferral.",
+      commonRecords: [
+        "Estimate",
+        "Benefits",
+        "Commitment",
+        "Deferral",
+        "Decision",
+        "Risk"
+      ],
+      handoff:
+        "The Owner records a Commitment that can move into Build, or a Deferral that makes unmet conditions visible.",
+      operatingGuidance: {
+        clientRole: "Help the decision authority compare the requirement set against cost, value, risk, and confidence.",
+        conductRules: [
+          "Make current-state cost context visible where relevant, but do not require complete baseline data.",
+          "Generate or review a scope-linked Engineer cost Estimate by default from the elicited requirement set.",
+          "Record Owner-authored Benefits separately from Engineer cost Estimates.",
+          "Consider important review notes, but do not require the Owner to acknowledge or answer them.",
+          "Keep the phase outcome-neutral; do not force a Commitment.",
+          "If budget or benefit basis was considered, link the Estimate, Benefits, or Decision rationale to the Commitment; if not, do not fabricate a waiver.",
+          "Use Commitment when the Owner is moving forward, with any reservations recorded.",
+          "Use Deferral when the Owner is not moving forward yet and wants the unmet conditions made explicit.",
+          "Record uncertainty and confidence rather than hiding it.",
+          "Do not compute a verdict; DX Complete preserves the basis for the Owner's judgment."
+        ],
+        questionsToAsk: [
+          "What is known about current cost, proposed cost, and expected benefit?",
+          "How confident is the cost estimate?",
+          "Which Benefits, Estimate, or Decision rationale, if any, should inform the Commitment?",
+          "What risks or missing information affect whether the Owner can commit?",
+          "Is the Owner committing now, or deferring until named conditions are addressed?",
+          "If committing, what reservations should be kept visible?",
+          "If deferring, what conditions would make a future Commitment possible?"
+        ],
+        expectedOutput: [
+          "Decision basis for the Owner's judgment.",
+          "Scope-linked Engineer cost Estimate where available.",
+          "Owner-authored Benefits where available, including qualitative benefits when they cannot be quantified.",
+          "Important review notes considered as input where they exist.",
+          "Commitment with linked requirements or expectations, or Deferral with explicit conditions.",
+          "Decision with linked inputs where a separate rationale record is useful.",
+          "Visible risks."
+        ],
+        exitCheck:
+          "Move to Build only after a Commitment; otherwise keep the Deferral conditions visible or return to Elicit as recorded.",
+        checkpointNotes: [
+          "Incomplete cost or benefit data does not block the decision.",
+          "Proceeding with low confidence should leave the open risk visible.",
+          "A Deferral is not failure; it is the recorded path to a possible future Commitment."
+        ]
+      }
+    },
+    {
+      id: "build",
+      name: "Build",
+      purpose: "Turn committed requirements into working changes.",
+      commonRecords: ["Commitment", "Requirement", "Task", "Decision", "Risk"],
+      handoff: "The change is ready for release preparation and readiness checks.",
+      operatingGuidance: {
+        clientRole: "Help the team break committed requirements into tasks and track implementation evidence.",
+        conductRules: [
+          "Create tasks from requirements covered by a Commitment.",
+          "Keep implementation detail connected to the requirement it supports.",
+          "Use decisions for meaningful design or tradeoff choices.",
+          "Surface blockers and delivery risk early."
+        ],
+        questionsToAsk: [
+          "Which requirement does this task implement?",
+          "What working change will satisfy the requirement?",
+          "What decision, risk, or blocker affects the build?",
+          "What evidence will show that the task is complete?"
+        ],
+        expectedOutput: [
+          "Tasks linked to requirements.",
+          "Working changes or implementation evidence.",
+          "Recorded decisions and risks where needed."
+        ],
+        exitCheck: "Move to Go Live when the committed change is built and ready for release preparation.",
+        checkpointNotes: [
+          "Task completion does not replace requirement verification.",
+          "Known build risk should remain visible through release preparation."
+        ]
+      }
+    },
+    {
+      id: "go_live",
+      name: "Go Live",
+      purpose: "Prepare the change, confirm readiness, and put it into use.",
+      commonRecords: ["Change", "Task", "Decision", "Risk"],
+      handoff: "The change is completed, deferred, cancelled, rolled back, or left with its event history visible.",
+      operatingGuidance: {
+        clientRole: "Help the Operator record the intended service change, readiness basis, execution path, rollback path, and resulting events.",
+        conductRules: [
+          "Use Change for a discrete alteration to the running service; reserve Operations Plan for a future standing operating model.",
+          "Record the original change plan, execution steps, rollback plan, and risk or impact as the baseline.",
+          "Use append-only Change events for notice, veto, emergency, decision, result, recovery, notes, and plan revisions.",
+          "Check readiness before putting the change into use.",
+          "Make release, rollback, notice, veto, emergency, and communication risks visible.",
+          "Do not treat vetoes or readiness checks as mechanical blockers; DX Complete records accountability and does not perform or enforce the operation.",
+          "Record open readiness risk when a readiness concern remains open."
+        ],
+        questionsToAsk: [
+          "What is changing, why, and when is it planned?",
+          "What steps will carry out the change?",
+          "What rollback or recovery path exists if something goes wrong?",
+          "Who needs to know about the change?",
+          "Has anyone recorded a veto or concern?",
+          "What readiness concerns are still open?"
+        ],
+        expectedOutput: [
+          "Change record with change plan, execution steps, rollback plan, and risk or impact.",
+          "Append-only Change events for notice, veto, emergency, decision, result, recovery, notes, or revisions where they occur.",
+          "Readiness basis.",
+          "Release or service-change decision context.",
+          "Visible open risks and any Owner risk-acceptance decisions."
+        ],
+        exitCheck: "Move to Operate when the change event history shows the change is completed, deferred, cancelled, rolled back, or ready to be monitored.",
+        checkpointNotes: [
+          "Readiness checks reduce launch risk.",
+          "A veto by Owner or Engineer is a serious recorded event, not a mechanical stop.",
+          "Emergency changes require both importance and immediacy to be recorded.",
+          "Open readiness concerns can move forward only when the risk remains visible or is formally accepted by the Owner."
+        ]
+      }
+    },
+    {
+      id: "operate",
+      name: "Operate",
+      purpose: "Run the service, help users, and respond when something goes wrong.",
+      commonRecords: ["Change", "DX Complete Ticket", "Risk", "Decision", "Task"],
+      handoff: "Operational signals are handled or sent into measurement, improvement, or new work.",
+      operatingGuidance: {
+        clientRole: "Help keep the service legible while it is running and route operational signals to the right follow-up.",
+        conductRules: [
+          "Separate immediate user-facing help from deeper improvement work.",
+          "Record incidents, risks, decisions, or tasks when operational signals require shared follow-up.",
+          "Use Change when the follow-up is a discrete alteration to the running service.",
+          "Do not assume the service is finished just because there is no active build.",
+          "Surface recurring signals for later improvement or measurement."
+        ],
+        questionsToAsk: [
+          "Is the service running as intended?",
+          "What user-facing issue, operational issue, or risk needs attention?",
+          "Does this signal need immediate response, a task, a decision, or later improvement?",
+          "What operational follow-up remains open?"
+        ],
+        expectedOutput: [
+          "Handled operational signal or routed follow-up.",
+          "Visible incidents, risks, decisions, or tasks where needed.",
+          "Ongoing operating state."
+        ],
+        exitCheck:
+          "Move to Measure when cost, benefit, reliability, or other operating data is available for comparison or learning.",
+        checkpointNotes: [
+          "Operational work is part of the lifecycle, not an exception.",
+          "Unresolved operating signals should remain visible until handled or accepted."
+        ]
+      }
+    },
+    {
+      id: "measure",
+      name: "Measure",
+      purpose: "Compare expected and actual cost or benefit when data is available.",
+      commonRecords: ["Estimate", "Benefits", "Decision", "Risk"],
+      handoff: "Learning from actuals is available for future estimates and decisions.",
+      operatingGuidance: {
+        clientRole: "Help compare estimates to actuals where data exists and feed learning into future decisions.",
+        conductRules: [
+          "Capture actual cost or benefit observations when available.",
+          "Do not block closure or continued operation because actuals are unavailable.",
+          "Compare measured results to earlier estimates where possible.",
+          "Turn meaningful differences into learning, risk, decision context, or future work."
+        ],
+        questionsToAsk: [
+          "What actual cost or benefit data is available?",
+          "How does it compare with the estimate?",
+          "What should future estimates or decisions learn from this?",
+          "Is new work, risk, or a decision needed because of the measurement?"
+        ],
+        expectedOutput: [
+          "Actual cost or benefit observations where available.",
+          "Comparison to estimates where possible.",
+          "Learning for future estimates and decisions."
+        ],
+        exitCheck:
+          "Keep operating, refine estimates, or start new Orient/Elicit work when measurement reveals a new need.",
+        checkpointNotes: [
+          "Actuals improve future estimates but do not block project closure.",
+          "Missing measurement data should be visible without being treated as failure."
+        ]
+      }
+    }
+  ],
+  processConcepts: [
+    {
+      name: "Statement",
+      status: "runtime_record",
+      currentRuntimeRecordType: "statements",
+      use: "The user's own words before DX Complete interprets or translates them.",
+      handling: "Track as a workspace-scoped record. Expectations can derive from Statement records through the derives_from relationship."
+    },
+    {
+      name: "Expectation",
+      status: "runtime_record",
+      currentRuntimeRecordType: "expectations",
+      use: "The expected result and how success will be recognized, captured in user-facing language.",
+      handling: "Track as a workspace-scoped record that can link to statements, requirements, risks, and decisions. Separate authority approval is tracked as risk-reducing state; same-person capture-confirmation is client conduct."
+    },
+    {
+      name: "Requirement detail",
+      status: "requirement_detail",
+      currentRuntimeRecordType: "requirements",
+      use: "Optional implementation or verification detail kept with the requirement when needed.",
+      handling: "Do not treat Specification as a current first-class runtime record."
+    }
+  ],
+  checkpointGuidance: [
+    "Approval and other checkpoints reduce risk; they do not block progress by themselves.",
+    "A checkpoint can be approved or mitigated, formally accepted as risk by the Owner, or proceeded past with open risk still visible.",
+    "Formal risk acceptance is an Owner-level decision; domain actors may proceed, but proceeding does not close or accept the risk.",
+    "Use Risk and Decision records to capture Owner risk acceptance or proceeding past an open checkpoint until dedicated checkpoint fields or tools are proven necessary.",
+    "Use Decision input links to preserve which records informed important choices.",
+    "Use Change records for run-side service changes where notice, veto, emergency posture, execution, rollback, and result need an ordered audit trail."
+  ],
+  nextStepGuidance: {
+    responsibility:
+      "The MCP client derives the next step from the current records, phase handoffs, operating guidance, open risks, and unanswered questions. DX Complete does not compute or prescribe a single server-side next step.",
+    conductRules: [
+      "Use the current phase, record state, links, open questions, risks, and decisions to reason about what should happen next.",
+      "When the next step is uncertain, name the missing information or checkpoint rather than inventing certainty.",
+      "Treat the next-step answer as guidance for the user, not as a hidden server decision."
+    ]
+  },
+  runtimeRecordTypes: COLLECTION_NAMES,
+  deploymentModel: {
+    default: "one_mcp_endpoint_per_workspace",
+    workspaceBinding:
+      "Hosted MCP endpoints get workspace scope from installed repo config, then proxy to the central DX Complete service. Shared record access is scoped by authenticated actor and authorized workspace context. Workspace scope is not an environment variable.",
+    databaseModel:
+      "Workspace MCP servers do not hold database credentials. The central service owns database access, OAuth exchange, membership checks, readable ID allocation, and MCP tool execution.",
+    authorizationModel:
+      "Workspace servers authenticate to the central service with a workspace service client. The central service verifies the human actor and derives allowed tool access from stored workspace roles."
+  },
+  recordGuidance: [
+    {
+      record: "Workspace",
+      use: "The boundary for one service scope, including its name, summary, and mode when useful."
+    },
+    {
+      record: "Statement",
+      use: "A user's own words before interpretation, kept as the traceable root for expectations and downstream work."
+    },
+    {
+      record: "Journal",
+      use: "Shared, append-only workspace notes for relevant background, preferences, observations, and context that has no dedicated record home. Journal notes are visible to workspace members and compacted through summary entries when the hot context grows."
+    },
+    {
+      record: "DX Complete Ticket",
+      use: "Private, appendable communication between the current actor and DX Complete before anyone decides whether shared follow-up is needed."
+    },
+    {
+      record: "Expectation",
+      use: "A user-facing condition of satisfaction that can be approved by separate authority, left not approved with open risk visible, linked to requirements, reviewed with non-blocking notes, and revised with version history."
+    },
+    {
+      record: "Requirement",
+      use: "A team-owned commitment that translates expectations into something buildable and verifiable, with optional non-blocking review notes and version history."
+    },
+    {
+      record: "Commitment",
+      use: "An Owner point-in-time authority record that commits requirements or expectations into Build, with optional reservations kept visible."
+    },
+    {
+      record: "Deferral",
+      use: "An Owner record for not committing yet, with explicit conditions and append-only condition history that can resolve into a Commitment."
+    },
+    {
+      record: "Task",
+      use: "Execution work with an append-only entry log; current status comes from the latest status_change entry."
+    },
+    {
+      record: "Change",
+      use: "A discrete service change record with baseline plan sections and append-only events for notice, veto, emergency posture, decision, result, recovery, notes, and revisions."
+    },
+    {
+      record: "Environment",
+      use: "A named operating context such as local, staging, or production, with version history for operational-state changes."
+    },
+    {
+      record: "Component",
+      use: "One environment-specific operational component with kind, structured locator, identifiers, secret pointers, notes, and version history."
+    },
+    {
+      record: "Estimate",
+      use: "An Engineer cost input for Weigh, with itemized line items, scope links, cost-only roll-up totals, and version history."
+    },
+    {
+      record: "Benefits",
+      use: "An Owner-authored benefit input for Weigh, with qualitative or quantified benefit items, scope links, quantified roll-up totals where amounts exist, and version history."
+    },
+    {
+      record: "Decision",
+      use: "A revisitable choice record with an append-only entry log; current decision comes from the latest decision entry while earlier arguments and decisions remain visible."
+    }
+  ],
+  clientGuidance: [
+    "Use get_process_guide when you need the current DX Complete phase language.",
+    "Use get_doc for the fuller reference on outcomes, flow, records, roles, and glossary terms.",
+    "Use DX Complete Ticket tools for private questions, reports, requests, corrections, or follow-ups.",
+    "Use Journal tools only after checking whether the information belongs in Statement, Expectation, Requirement, Decision, Task, Change, Risk, Environment, Component, or another dedicated record.",
+    "Use workspace-scoped records for shared process work.",
+    "Use readableId values such as REQ-0001 as human-facing references when a tool accepts an existing record id; UUID remains the primary key and link target.",
+    "Hosted MCP access derives workspace scope from installed repo config and actor scope from OAuth.",
+    "Use update_expectation and update_requirement for current content changes so prior versions are preserved.",
+    "Use append_decision_entry and append_task_entry for Decision and Task history; do not rewrite their current decision or status directly.",
+    "Use link_decision_input when a record informed a Decision; use list_linked_records with relationship informed_by to review the decision inputs.",
+    "Use Benefits for Owner-authored benefit lists; use Estimate for Engineer cost estimates.",
+    "Use link_records and unlink_records for other relationships between records."
+  ]
+};
+
+type ToolSchema = Record<string, z.ZodType>;
+type ToolHandler = (...args: any[]) => unknown;
+type ToolManifestEntry = {
+  name: string;
+  description: string;
+  inputFields: string[];
+  inputSchemaFingerprint: string;
+};
+type ToolManifest = {
+  toolCount: number;
+  tools: ToolManifestEntry[];
+};
+type McpSurface = ToolManifest & {
+  version: string;
+  fingerprint: string;
+  workspaceCompatibility: number;
+};
+export type McpServerOptions = {
+  actor?: ActorContext;
+  recordActorId?: string;
+  hostedWorkspace?: {
+    workspaceId: string;
+    name?: string;
+  };
+  workspaceRoles?: WorkspaceRole[];
+  hostedHttp?: {
+    canonicalMcpPath: string;
+    canonicalMcpUrl: string;
+    protectedResourceMetadataUrl: string;
+    googleCallbackUrl: string;
+  };
+};
+
+export function createMcpServer(runtime: DxRuntime, options: McpServerOptions = {}): McpServer {
+  const server = new McpServer({
+    name: "dxcomplete",
+    version: DXCOMPLETE_PACKAGE_VERSION
+  });
+  const actor = options.actor ?? createLocalActorContext();
+  const recordActorId = options.recordActorId ?? (options.actor ? actor.actorId : RUNTIME_ACTOR_ID);
+  const hostedWorkspace = options.hostedWorkspace;
+  const hostedHttp = options.hostedHttp;
+  const activeCollectionSchema = hostedWorkspace ? hostedCollectionSchema : collectionSchema;
+  const toolManifestEntries: ToolManifestEntry[] = [];
+
+  function registerDxcTool<TInputSchema extends ToolSchema>(
+    name: string,
+    config: {
+      description: string;
+      inputSchema: TInputSchema;
+    },
+    handler: ToolHandler
+  ): void {
+    if (hostedWorkspace && name === "create_workspace") {
+      return;
+    }
+
+    const inputSchema = hostedWorkspace ? omitWorkspaceId(config.inputSchema) : config.inputSchema;
+
+    toolManifestEntries.push({
+      name,
+      description: config.description,
+      inputFields: Object.keys(inputSchema).sort(),
+      inputSchemaFingerprint: getInputSchemaFingerprint(inputSchema)
+    });
+    server.registerTool(
+      name,
+      {
+        ...config,
+        inputSchema
+      },
+      (async (input: Record<string, unknown>) => {
+        const handlerInput = hostedWorkspace
+          ? injectHostedWorkspace(input, config.inputSchema, hostedWorkspace.workspaceId)
+          : input;
+        assertHostedWorkspaceAccess(name, handlerInput, hostedWorkspace?.workspaceId);
+        assertToolRoleAccess(name, options.workspaceRoles, handlerInput);
+        return handler(handlerInput);
+      }) as any
+    );
+  }
+
+  function getToolManifest(): ToolManifest {
+    const tools = [...toolManifestEntries].sort((left, right) => left.name.localeCompare(right.name));
+
+    return {
+      toolCount: tools.length,
+      tools
+    };
+  }
+
+  function getMcpSurface(): McpSurface {
+    const toolManifest = getToolManifest();
+    const fingerprint = createHash("sha256")
+      .update(
+        stableStringify({
+          surfaceId: MCP_SURFACE_ID,
+          workspaceCompatibility: WORKSPACE_COMPATIBILITY_VERSION,
+          tools: toolManifest.tools,
+          processGuide: PROCESS_GUIDE,
+          docReferences: DOC_REFERENCE
+        })
+      )
+      .digest("hex")
+      .slice(0, 16);
+
+    return {
+      version: MCP_SURFACE_ID,
+      fingerprint,
+      workspaceCompatibility: WORKSPACE_COMPATIBILITY_VERSION,
+      ...toolManifest
+    };
+  }
+
+  registerDxcTool(
+    "runtime_status",
+    {
+      description: "Check the DX Complete runtime connection and configured record collections.",
+      inputSchema: {}
+    },
+    async () => {
+      const surface = getMcpSurface();
+
+      return jsonResult({
+        ok: true,
+        databaseName: runtime.config.databaseName,
+        actorId: recordActorId,
+        actor,
+        ...(hostedWorkspace
+          ? {
+              workspace: {
+                workspaceId: hostedWorkspace.workspaceId,
+                ...(hostedWorkspace.name ? { name: hostedWorkspace.name } : {}),
+                source: "central_service_membership",
+                ...(options.workspaceRoles ? { roles: options.workspaceRoles } : {})
+              }
+            }
+          : {}),
+        collections: COLLECTION_NAMES,
+        server: {
+          pid: process.pid,
+          version: DXCOMPLETE_PACKAGE_VERSION,
+          packageVersion: DXCOMPLETE_PACKAGE_VERSION,
+          workspaceCompatibility: surface.workspaceCompatibility,
+          startedAt: SERVER_STARTED_AT,
+          surfaceVersion: surface.version,
+          surfaceFingerprint: surface.fingerprint,
+          surfaceIncludes: ["tools", "toolSchemas", "processGuide", "docReferences"],
+          ...(hostedHttp
+            ? {
+                http: hostedHttp
+              }
+            : {}),
+          toolCount: surface.toolCount,
+          tools: surface.tools.map((tool) => tool.name),
+          toolManifest: surface.tools
+        }
+      });
+    }
+  );
+
+  registerDxcTool(
+    "get_process_guide",
+    {
+      description: "Get the current DX Complete process guide, including phases, common records, and handoff guidance.",
+      inputSchema: {}
+    },
+    async () => {
+      const surface = getMcpSurface();
+
+      return jsonResult({
+        surfaceVersion: surface.version,
+        surfaceFingerprint: surface.fingerprint,
+        workspaceCompatibility: surface.workspaceCompatibility,
+        ...PROCESS_GUIDE
+      });
+    }
+  );
+
+  registerDxcTool(
+    "get_doc",
+    {
+      description:
+        "Get an on-demand DX Complete reference page for MCP clients. Use this for fuller outcomes, flow, records, roles, and glossary content without loading all documentation into the process guide.",
+      inputSchema: {
+        page: z.enum(DOC_PAGE_IDS),
+        term: z.string().min(1).optional()
+      }
+    },
+    async ({ page, term }) => {
+      const surface = getMcpSurface();
+      const doc = getDocReference(page, term);
+
+      return jsonResult({
+        surfaceVersion: surface.version,
+        surfaceFingerprint: surface.fingerprint,
+        workspaceCompatibility: surface.workspaceCompatibility,
+        ...doc
+      });
+    }
+  );
+
+  registerDxcTool(
+    "create_workspace",
+    {
+      description: "Create a workspace, the shared-runtime boundary for one service scope.",
+      inputSchema: {
+        id: workspaceIdSchema.optional(),
+        name: z.string().min(1),
+        summary: z.string().min(1).optional(),
+        mode: workspaceModeSchema.optional(),
+        fields: recordFieldsSchema
+      }
+    },
+    async ({ id, name, summary, mode, fields }) => {
+      const existing = id
+        ? await getRecord(runtime.db, "workspaces", id, { allowAnyWorkspace: true })
+        : null;
+
+      if (existing) {
+        return jsonResult(existing);
+      }
+
+      return jsonResult(
+        await createRecord(
+          runtime.db,
+          "workspaces",
+          {
+            ...(id ? { id } : {}),
+            title: name,
+            summary,
+            fields: {
+              name,
+              ...(mode ? { mode } : {}),
+              ...(fields ?? {})
+            }
+          },
+          recordActorId
+        )
+      );
+    }
+  );
+
+  registerDxcTool(
+    "create_record",
+    {
+      description: "Create a record in one of the DX Complete collections.",
+      inputSchema: {
+        recordType: activeCollectionSchema,
+        workspaceId: workspaceIdSchema.optional(),
+        title: z.string().min(1).optional(),
+        summary: z.string().min(1).optional(),
+        fields: recordFieldsSchema
+      }
+    },
+    async ({ recordType, workspaceId, title, summary, fields }) =>
+      jsonResult(await createRecord(runtime.db, recordType, { workspaceId, title, summary, fields }, recordActorId))
+  );
+
+  registerDxcTool(
+    "get_record",
+    {
+      description: "Get one DX Complete record by type and id.",
+      inputSchema: {
+        recordType: activeCollectionSchema,
+        workspaceId: workspaceIdSchema.optional(),
+        id: z.string().min(1)
+      }
+    },
+    async ({ recordType, workspaceId, id }) => {
+      const record = await getRecord(runtime.db, recordType, id, { workspaceId });
+
+      if (!record) {
+        throw new Error(`Record not found: ${recordType}/${id}`);
+      }
+
+      return jsonResult(record);
+    }
+  );
+
+  registerDxcTool(
+    "create_dxcomplete_ticket",
+    {
+      description:
+        "Create a private DX Complete Ticket for a question, report, request, correction, or follow-up from the current actor. The body is stored as the first entry; summary is optional and is not generated automatically.",
+      inputSchema: {
+        title: z.string().min(1),
+        body: z.string().min(1)
+      }
+    },
+    async (input) => jsonResult(await createDxcompleteTicket(runtime.db, input, actor))
+  );
+
+  registerDxcTool(
+    "append_dxcomplete_ticket",
+    {
+      description:
+        "Append a follow-up entry to one of the current actor's DX Complete Tickets while preserving earlier entries.",
+      inputSchema: {
+        id: z.string().min(1),
+        body: z.string().min(1)
+      }
+    },
+    async (input) => jsonResult(await appendDxcompleteTicket(runtime.db, input, actor))
+  );
+
+  registerDxcTool(
+    "list_dxcomplete_tickets",
+    {
+      description:
+        "List the current actor's own DX Complete Tickets. Archived tickets are hidden unless includeArchived is true.",
+      inputSchema: {
+        limit: z.number().int().min(1).max(100).optional(),
+        includeArchived: z.boolean().optional()
+      }
+    },
+    async ({ limit, includeArchived }) =>
+      jsonResult(await listDxcompleteTickets(runtime.db, actor, limit ?? 20, { includeArchived }))
+  );
+
+  registerDxcTool(
+    "list_unread_dxcomplete_ticket_replies",
+    {
+      description:
+        "List tickets with unread DX Complete replies addressed to the current actor. This returns reply identifiers and timestamps only; use read_dxcomplete_ticket to read the ticket and mark replies read.",
+      inputSchema: {
+        limit: z.number().int().min(1).max(100).optional()
+      }
+    },
+    async ({ limit }) => jsonResult(await listUnreadDxcompleteTicketReplies(runtime.db, actor, limit ?? 20))
+  );
+
+  registerDxcTool(
+    "read_dxcomplete_ticket",
+    {
+      description: "Read one DX Complete Ticket owned by the current actor. Reading the ticket marks its unread DX Complete replies as read.",
+      inputSchema: {
+        id: z.string().min(1)
+      }
+    },
+    async (input) => jsonResult(await readDxcompleteTicket(runtime.db, input, actor))
+  );
+
+  registerDxcTool(
+    "archive_dxcomplete_ticket",
+    {
+      description: "Hide one DX Complete Ticket from the current actor's active ticket list. This is personal cleanup.",
+      inputSchema: {
+        id: z.string().min(1)
+      }
+    },
+    async ({ id }) => jsonResult(await archiveDxcompleteTicket(runtime.db, { id }, actor))
+  );
+
+  registerDxcTool(
+    "append_journal_note",
+    {
+      description:
+        "Append a shared workspace Journal note only after checking that the information has no better dedicated record home. Any workspace member may append; author and timestamp are captured automatically.",
+      inputSchema: {
+        workspaceId: workspaceIdSchema,
+        body: z.string().min(1),
+        tag: journalTagSchema.optional()
+      }
+    },
+    async (input) => jsonResult(await appendJournalNote(runtime.db, input, recordActorId))
+  );
+
+  registerDxcTool(
+    "read_journal",
+    {
+      description:
+        "Read the workspace Journal fallback context. By default this returns the hot tier: active summaries plus active raw notes, not the full archive.",
+      inputSchema: {
+        workspaceId: workspaceIdSchema,
+        limit: z.number().int().min(1).max(500).optional(),
+        includeArchived: z.boolean().optional()
+      }
+    },
+    async (input) => jsonResult(await readJournal(runtime.db, input))
+  );
+
+  registerDxcTool(
+    "get_journal_entry",
+    {
+      description:
+        "Fetch one Journal entry by UUID or readable ID, including fallback context entries that have aged out of the hot Journal read.",
+      inputSchema: {
+        workspaceId: workspaceIdSchema,
+        id: z.string().min(1)
+      }
+    },
+    async (input) => jsonResult(await getJournalEntry(runtime.db, input))
+  );
+
+  registerDxcTool(
+    "append_journal_summary",
+    {
+      description:
+        "Append a Journal summary for fallback context that covers existing Journal entries by UUID or readable ID, then archives the covered entries out of the hot read without deleting them.",
+      inputSchema: {
+        workspaceId: workspaceIdSchema,
+        body: z.string().min(1),
+        covers: z.array(z.string().min(1)).min(1),
+        tag: journalTagSchema.optional()
+      }
+    },
+    async (input) => jsonResult(await appendJournalSummary(runtime.db, input, recordActorId))
+  );
+
+  registerDxcTool(
+    "create_statement",
+    {
+      description: "Create a Statement record that preserves a person's own words before interpretation.",
+      inputSchema: {
+        workspaceId: workspaceIdSchema,
+        title: z.string().min(1),
+        statement: z.string().min(1),
+        source: z.string().min(1).optional(),
+        fields: recordFieldsSchema
+      }
+    },
+    async (input) => jsonResult(await createStatement(runtime, input, recordActorId))
+  );
+
+  registerDxcTool(
+    "update_statement",
+    {
+      description: "Update a Statement record while preserving prior versions.",
+      inputSchema: {
+        workspaceId: workspaceIdSchema,
+        id: z.string().min(1),
+        title: z.string().min(1).optional(),
+        statement: z.string().min(1).optional(),
+        source: z.string().min(1).optional(),
+        fields: recordFieldsSchema,
+        unsetFields: z.array(fieldNameSchema).optional(),
+        revisionNote: z.string().min(1).optional()
+      }
+    },
+    async (input) => jsonResult(await updateStatement(runtime, input, recordActorId))
+  );
+
+  registerDxcTool(
+    "list_environments",
+    {
+      description: "List Operational Registry Environment records for the workspace.",
+      inputSchema: {
+        workspaceId: workspaceIdSchema,
+        limit: z.number().int().min(1).max(100).optional(),
+        includeArchived: z.boolean().optional()
+      }
+    },
+    async ({ workspaceId, limit, includeArchived }) =>
+      jsonResult(await listRecords(runtime.db, "environments", limit ?? 20, { workspaceId, includeArchived }))
+  );
+
+  registerDxcTool(
+    "create_environment",
+    {
+      description: "Create an Operational Registry Environment, such as local, staging, or production.",
+      inputSchema: {
+        workspaceId: workspaceIdSchema,
+        name: z.string().min(1),
+        summary: z.string().min(1).optional(),
+        description: z.string().min(1).optional(),
+        fields: recordFieldsSchema
+      }
+    },
+    async (input) => jsonResult(await createEnvironment(runtime, input, recordActorId))
+  );
+
+  registerDxcTool(
+    "update_environment",
+    {
+      description: "Update an Operational Registry Environment while preserving prior versions.",
+      inputSchema: {
+        workspaceId: workspaceIdSchema,
+        id: z.string().min(1),
+        name: z.string().min(1).optional(),
+        summary: z.string().min(1).optional(),
+        description: z.string().min(1).optional(),
+        fields: recordFieldsSchema,
+        unsetFields: z.array(fieldNameSchema).optional(),
+        revisionNote: z.string().min(1).optional()
+      }
+    },
+    async (input) => jsonResult(await updateEnvironment(runtime, input, recordActorId))
+  );
+
+  registerDxcTool(
+    "list_components",
+    {
+      description: "List Operational Registry Components that belong to one Environment.",
+      inputSchema: {
+        workspaceId: workspaceIdSchema,
+        environmentId: z.string().min(1),
+        limit: z.number().int().min(1).max(100).optional(),
+        includeArchived: z.boolean().optional()
+      }
+    },
+    async (input) => jsonResult(await listComponents(runtime, input))
+  );
+
+  registerDxcTool(
+    "create_component",
+    {
+      description:
+        "Create an Operational Registry Component for one Environment. Secret pointers are pointers only; do not paste credentials or secret values.",
+      inputSchema: {
+        workspaceId: workspaceIdSchema,
+        name: z.string().min(1),
+        environmentId: z.string().min(1),
+        kind: z.string().min(1),
+        locator: componentLocatorSchema,
+        summary: z.string().min(1).optional(),
+        identifiers: componentIdentifiersSchema,
+        secretPointers: z.array(secretPointerSchema).optional(),
+        notes: z.string().min(1).optional(),
+        fields: recordFieldsSchema
+      }
+    },
+    async (input) => jsonResult(await createComponent(runtime, input, recordActorId))
+  );
+
+  registerDxcTool(
+    "update_component",
+    {
+      description:
+        "Update an Operational Registry Component while preserving prior versions. Secret pointers are pointers only; do not paste credentials or secret values.",
+      inputSchema: {
+        workspaceId: workspaceIdSchema,
+        id: z.string().min(1),
+        name: z.string().min(1).optional(),
+        kind: z.string().min(1).optional(),
+        locator: componentLocatorSchema.optional(),
+        summary: z.string().min(1).optional(),
+        identifiers: componentIdentifiersSchema,
+        secretPointers: z.array(secretPointerSchema).optional(),
+        notes: z.string().min(1).optional(),
+        fields: recordFieldsSchema,
+        unsetFields: z.array(fieldNameSchema).optional(),
+        revisionNote: z.string().min(1).optional()
+      }
+    },
+    async (input) => jsonResult(await updateComponent(runtime, input, recordActorId))
+  );
+
+  registerDxcTool(
+    "create_estimate",
+    {
+      description: "Create an itemized Engineer cost estimate for Weigh.",
+      inputSchema: {
+        workspaceId: workspaceIdSchema,
+        title: z.string().min(1),
+        summary: z.string().min(1).optional(),
+        lineItems: z.array(estimateLineItemSchema).min(1),
+        requirementIds: z.array(z.string().min(1)).optional(),
+        expectationIds: z.array(z.string().min(1)).optional(),
+        fields: recordFieldsSchema
+      }
+    },
+    async (input) => jsonResult(await createEstimate(runtime, input, recordActorId))
+  );
+
+  registerDxcTool(
+    "update_estimate",
+    {
+      description: "Update an itemized Engineer cost estimate while preserving prior versions.",
+      inputSchema: {
+        workspaceId: workspaceIdSchema,
+        id: z.string().min(1),
+        title: z.string().min(1).optional(),
+        summary: z.string().min(1).optional(),
+        lineItems: z.array(estimateLineItemSchema).min(1).optional(),
+        fields: recordFieldsSchema,
+        unsetFields: z.array(fieldNameSchema).optional(),
+        revisionNote: z.string().min(1).optional()
+      }
+    },
+    async (input) => jsonResult(await updateEstimate(runtime, input, recordActorId))
+  );
+
+  registerDxcTool(
+    "create_benefits",
+    {
+      description: "Create an Owner-authored Benefits record for Weigh.",
+      inputSchema: {
+        workspaceId: workspaceIdSchema,
+        title: z.string().min(1),
+        summary: z.string().min(1).optional(),
+        benefitItems: z.array(benefitItemSchema).min(1),
+        requirementIds: z.array(z.string().min(1)).optional(),
+        expectationIds: z.array(z.string().min(1)).optional(),
+        fields: recordFieldsSchema
+      }
+    },
+    async (input) => jsonResult(await createBenefits(runtime, input, recordActorId))
+  );
+
+  registerDxcTool(
+    "update_benefits",
+    {
+      description: "Update an Owner-authored Benefits record while preserving prior versions.",
+      inputSchema: {
+        workspaceId: workspaceIdSchema,
+        id: z.string().min(1),
+        title: z.string().min(1).optional(),
+        summary: z.string().min(1).optional(),
+        benefitItems: z.array(benefitItemSchema).min(1).optional(),
+        fields: recordFieldsSchema,
+        unsetFields: z.array(fieldNameSchema).optional(),
+        revisionNote: z.string().min(1).optional()
+      }
+    },
+    async (input) => jsonResult(await updateBenefits(runtime, input, recordActorId))
+  );
+
+  registerDxcTool(
+    "create_expectation",
+    {
+      description: "Create an expectation record.",
+      inputSchema: {
+        workspaceId: workspaceIdSchema,
+        title: z.string().min(1),
+        statement: z.string().min(1),
+        successRecognition: z.string().min(1).optional(),
+        approvalState: expectationApprovalStateSchema.optional(),
+        approvedBy: z.string().min(1).optional(),
+        approvedAt: z.string().min(1).optional(),
+        source: z.string().min(1).optional(),
+        statementId: z.string().min(1).optional(),
+        fields: recordFieldsSchema
+      }
+    },
+    async ({
+      workspaceId,
+      title,
+      statement,
+      successRecognition,
+      approvalState,
+      approvedBy,
+      approvedAt,
+      source,
+      statementId,
+      fields
+    }) =>
+      jsonResult(
+        await createExpectation(
+          runtime,
+          {
+            workspaceId,
+            title,
+            statement,
+            successRecognition,
+            approvalState,
+            approvedBy,
+            approvedAt,
+            source,
+            statementId,
+            fields
+          },
+          recordActorId
+        )
+      )
+  );
+
+  registerDxcTool(
+    "create_requirement",
+    {
+      description: "Create a requirement record.",
+      inputSchema: {
+        workspaceId: workspaceIdSchema,
+        title: z.string().min(1),
+        expectationId: z.string().min(1).optional(),
+        statement: z.string().min(1),
+        acceptanceCriteria: z.array(z.string().min(1)).optional(),
+        priority: z.enum(["low", "medium", "high"]).optional(),
+        status: requirementStatusSchema.optional(),
+        fields: recordFieldsSchema
+      }
+    },
+    async ({ workspaceId, title, expectationId, statement, acceptanceCriteria, priority, status, fields }) =>
+      jsonResult(
+        await createRequirement(
+          runtime,
+          { workspaceId, title, expectationId, statement, acceptanceCriteria, priority, status, fields },
+          recordActorId
+        )
+      )
+  );
+
+  registerDxcTool(
+    "create_task",
+    {
+      description:
+        "Create an execution task ledger. Current status is derived from the latest status_change entry.",
+      inputSchema: {
+        workspaceId: workspaceIdSchema,
+        title: z.string().min(1),
+        description: z.string().min(1),
+        assignee: z.string().min(1).optional(),
+        assignor: z.string().min(1).optional(),
+        requirementId: z.string().min(1).optional(),
+        initialStatus: taskStatusSchema.optional(),
+        fields: recordFieldsSchema
+      }
+    },
+    async (input) => jsonResult(await createTask(runtime, input, recordActorId))
+  );
+
+  registerDxcTool(
+    "append_task_entry",
+    {
+      description:
+        "Append an immutable entry to a Task. Use status_change entries to change the derived current status.",
+      inputSchema: {
+        workspaceId: workspaceIdSchema,
+        taskId: z.string().min(1),
+        entryType: taskEntryTypeSchema,
+        body: z.string().min(1),
+        status: taskStatusSchema.optional()
+      }
+    },
+    async (input) => jsonResult(await appendTaskEntry(runtime.db, input, recordActorId))
+  );
+
+  registerDxcTool(
+    "create_commitment",
+    {
+      description: "Create an Owner commitment record that moves requirements or expectations toward Build.",
+      inputSchema: {
+        workspaceId: workspaceIdSchema,
+        title: z.string().min(1),
+        summary: z.string().min(1).optional(),
+        commitmentStatement: z.string().min(1),
+        requirementIds: z.array(z.string().min(1)).optional(),
+        expectationIds: z.array(z.string().min(1)).optional(),
+        reservationNotes: z.array(z.string().min(1)).optional(),
+        deferralId: z.string().min(1).optional(),
+        fields: recordFieldsSchema
+      }
+    },
+    async (input) => jsonResult(await createCommitment(runtime, input, recordActorId))
+  );
+
+  registerDxcTool(
+    "create_deferral",
+    {
+      description: "Create an Owner deferral record with explicit conditions required for a future Commitment.",
+      inputSchema: {
+        workspaceId: workspaceIdSchema,
+        title: z.string().min(1),
+        summary: z.string().min(1).optional(),
+        reason: z.string().min(1),
+        conditions: z.array(z.string().min(1)).min(1),
+        requirementIds: z.array(z.string().min(1)).optional(),
+        expectationIds: z.array(z.string().min(1)).optional(),
+        fields: recordFieldsSchema
+      }
+    },
+    async (input) => jsonResult(await createDeferral(runtime, input, recordActorId))
+  );
+
+  registerDxcTool(
+    "append_deferral_event",
+    {
+      description:
+        "Append an immutable event to a Deferral record. Use this for condition updates, notes, resolution into Commitment, or abandonment.",
+      inputSchema: {
+        workspaceId: workspaceIdSchema,
+        deferralId: z.string().min(1),
+        eventType: deferralEventTypeSchema,
+        conditionId: z.string().min(1).optional(),
+        note: z.string().min(1).optional(),
+        summary: z.string().min(1).optional(),
+        reason: z.string().min(1).optional(),
+        commitmentId: z.string().min(1).optional()
+      }
+    },
+    async (input) => jsonResult(await appendDeferralEventForTool(runtime, input, recordActorId))
+  );
+
+  registerDxcTool(
+    "create_change",
+    {
+      description:
+        "Create a service change record with baseline plan, execution, rollback, and risk/impact sections.",
+      inputSchema: {
+        workspaceId: workspaceIdSchema,
+        title: z.string().min(1),
+        summary: z.string().min(1).optional(),
+        changePlan: z.string().min(1),
+        executionSteps: z.array(z.string().min(1)).min(1),
+        rollbackPlan: z.string().min(1),
+        riskImpact: z.string().min(1),
+        plannedFor: z.string().min(1).optional(),
+        requirementId: z.string().min(1).optional(),
+        fields: recordFieldsSchema
+      }
+    },
+    async (input) => jsonResult(await createChange(runtime, input, recordActorId))
+  );
+
+  registerDxcTool(
+    "append_change_event",
+    {
+      description:
+        "Append an immutable event to a Change record. Use this for notice, veto, emergency posture, decision, result, recovery, plan revisions, and notes.",
+      inputSchema: {
+        workspaceId: workspaceIdSchema,
+        changeId: z.string().min(1),
+        eventType: changeEventTypeSchema,
+        notice: z.string().min(1).optional(),
+        noticeTo: z.array(z.string().min(1)).optional(),
+        effectiveAt: z.string().min(1).optional(),
+        vetoByRole: changeVetoRoleSchema.optional(),
+        reason: z.string().min(1).optional(),
+        importance: z.string().min(1).optional(),
+        immediacy: z.string().min(1).optional(),
+        decision: changeDecisionSchema.optional(),
+        result: changeResultSchema.optional(),
+        summary: z.string().min(1).optional(),
+        note: z.string().min(1).optional(),
+        revisedChangePlan: z.string().min(1).optional(),
+        revisedExecutionSteps: z.array(z.string().min(1)).optional(),
+        revisedRollbackPlan: z.string().min(1).optional(),
+        revisedRiskImpact: z.string().min(1).optional(),
+        revisedPlannedFor: z.string().min(1).optional()
+      }
+    },
+    async (input) =>
+      jsonResult(
+        await appendChangeEvent(
+          runtime.db,
+          {
+            workspaceId: input.workspaceId,
+            changeId: input.changeId,
+            eventType: input.eventType,
+            event: buildChangeEventContent(input)
+          },
+          recordActorId
+        )
+      )
+  );
+
+  registerDxcTool(
+    "create_decision",
+    {
+      description:
+        "Create a revisitable decision ledger. Current decision is derived from the latest decision entry.",
+      inputSchema: {
+        workspaceId: workspaceIdSchema,
+        title: z.string().min(1),
+        matter: z.string().min(1),
+        initialEntries: z.array(decisionInitialEntrySchema).optional(),
+        initialDecision: initialDecisionSchema.optional(),
+        fields: recordFieldsSchema
+      }
+    },
+    async ({ workspaceId, title, matter, initialEntries, initialDecision, fields }) => {
+      assertNoTypedFields(fields, "create_decision", DECISION_TYPED_FIELDS);
+      assertNoDecisionInputFields(fields);
+
+      return jsonResult(await createDecision(runtime, { workspaceId, title, matter, initialEntries, initialDecision, fields }, recordActorId));
+    }
+  );
+
+  registerDxcTool(
+    "append_decision_entry",
+    {
+      description:
+        "Append an immutable entry to a Decision. Use decision entries to change the derived current decision.",
+      inputSchema: {
+        workspaceId: workspaceIdSchema,
+        decisionId: z.string().min(1),
+        entryType: decisionEntryTypeSchema,
+        body: z.string().min(1),
+        decidedBy: z.string().min(1).optional(),
+        rationale: z.string().min(1).optional()
+      }
+    },
+    async (input) => jsonResult(await appendDecisionEntry(runtime.db, input, recordActorId))
+  );
+
+  registerDxcTool(
+    "create_risk",
+    {
+      description: "Create a risk record.",
+      inputSchema: {
+        workspaceId: workspaceIdSchema,
+        title: z.string().min(1),
+        summary: z.string().min(1).optional(),
+        likelihood: z.enum(["low", "medium", "high"]).optional(),
+        impact: z.enum(["low", "medium", "high"]).optional(),
+        mitigation: z.string().min(1).optional(),
+        fields: recordFieldsSchema
+      }
+    },
+    async ({ workspaceId, title, summary, likelihood, impact, mitigation, fields }) =>
+      jsonResult(
+        await createRecord(
+          runtime.db,
+          "risks",
+          {
+            workspaceId,
+            title,
+            summary,
+            fields: {
+              ...(likelihood ? { likelihood } : {}),
+              ...(impact ? { impact } : {}),
+              ...(mitigation ? { mitigation } : {}),
+              ...(fields ?? {})
+            }
+          },
+          recordActorId
+        )
+      )
+  );
+
+  registerDxcTool(
+    "list_records",
+    {
+      description: "List records from a DX Complete collection.",
+      inputSchema: {
+        recordType: activeCollectionSchema,
+        workspaceId: workspaceIdSchema.optional(),
+        limit: z.number().int().min(1).max(100).optional(),
+        includeArchived: z.boolean().optional()
+      }
+    },
+    async ({ recordType, workspaceId, limit, includeArchived }) =>
+      jsonResult(await listRecords(runtime.db, recordType, limit ?? 20, { workspaceId, includeArchived }))
+  );
+
+  registerDxcTool(
+    "list_linked_records",
+    {
+      description: "List records linked to or from a DX Complete record.",
+      inputSchema: {
+        recordType: activeCollectionSchema,
+        workspaceId: workspaceIdSchema.optional(),
+        id: z.string().min(1),
+        direction: z.enum(["outbound", "inbound", "both"]).optional(),
+        relationship: z.string().min(1).optional(),
+        includeArchived: z.boolean().optional()
+      }
+    },
+    async (input) => jsonResult(await listLinkedRecords(runtime.db, input))
+  );
+
+  registerDxcTool(
+    "link_decision_input",
+    {
+      description: "Link a Decision to one record that informed it using the informed_by relationship.",
+      inputSchema: {
+        workspaceId: workspaceIdSchema,
+        decisionId: z.string().min(1),
+        inputRecordType: decisionInputRecordTypeSchema,
+        inputId: z.string().min(1)
+      }
+    },
+    async (input) => jsonResult(await linkDecisionInput(runtime, input, recordActorId))
+  );
+
+  registerDxcTool(
+    "update_record",
+    {
+      description: "Update a DX Complete record and optionally clear top-level fields.",
+      inputSchema: {
+        recordType: activeCollectionSchema,
+        workspaceId: workspaceIdSchema.optional(),
+        id: z.string().min(1),
+        title: z.string().min(1).optional(),
+        summary: z.string().min(1).optional(),
+        fields: recordFieldsSchema,
+        unsetFields: z.array(fieldNameSchema).optional()
+      }
+    },
+    async (input) => jsonResult(await updateRecord(runtime.db, input, recordActorId))
+  );
+
+  registerDxcTool(
+    "update_expectation",
+    {
+      description: "Update an expectation record with typed expectation fields.",
+      inputSchema: {
+        workspaceId: workspaceIdSchema,
+        id: z.string().min(1),
+        title: z.string().min(1).optional(),
+        statement: z.string().min(1).optional(),
+        successRecognition: z.string().min(1).optional(),
+        approvalState: expectationApprovalStateSchema.optional(),
+        approvedBy: z.string().min(1).optional(),
+        approvedAt: z.string().min(1).optional(),
+        source: z.string().min(1).optional(),
+        revisionNote: z.string().min(1).optional(),
+        fields: recordFieldsSchema,
+        unsetFields: z.array(fieldNameSchema).optional()
+      }
+    },
+    async (input) => jsonResult(await updateExpectation(runtime, input, recordActorId))
+  );
+
+  registerDxcTool(
+    "update_requirement",
+    {
+      description: "Update a requirement record with typed requirement fields.",
+      inputSchema: {
+        workspaceId: workspaceIdSchema,
+        id: z.string().min(1),
+        title: z.string().min(1).optional(),
+        statement: z.string().min(1).optional(),
+        acceptanceCriteria: z.array(z.string().min(1)).optional(),
+        priority: z.enum(["low", "medium", "high"]).optional(),
+        status: requirementStatusSchema.optional(),
+        revisionNote: z.string().min(1).optional(),
+        fields: recordFieldsSchema,
+        unsetFields: z.array(fieldNameSchema).optional()
+      }
+    },
+    async (input) => jsonResult(await updateRequirement(runtime, input, recordActorId))
+  );
+
+  registerDxcTool(
+    "append_review_note",
+    {
+      description:
+        "Append a non-blocking review note to an expectation or requirement. The optional important flag only surfaces the note; it does not create an approval duty or workflow block.",
+      inputSchema: {
+        workspaceId: workspaceIdSchema,
+        recordType: reviewableRecordTypeSchema,
+        id: z.string().min(1),
+        body: z.string().min(1),
+        important: z.boolean().optional()
+      }
+    },
+    async (input) => jsonResult(await appendReviewNote(runtime.db, input, recordActorId))
+  );
+
+  registerDxcTool(
+    "archive_record",
+    {
+      description: "Archive a DX Complete record without deleting it.",
+      inputSchema: {
+        recordType: activeCollectionSchema,
+        workspaceId: workspaceIdSchema.optional(),
+        id: z.string().min(1),
+        reason: z.string().min(1).optional(),
+        supersededByType: activeCollectionSchema.optional(),
+        supersededById: z.string().min(1).optional()
+      }
+    },
+    async (input) => jsonResult(await archiveRecord(runtime.db, input, recordActorId))
+  );
+
+  registerDxcTool(
+    "link_records",
+    {
+      description: "Link one DX Complete record to another.",
+      inputSchema: {
+        workspaceId: workspaceIdSchema,
+        fromType: activeCollectionSchema,
+        fromId: z.string().min(1),
+        toType: activeCollectionSchema,
+        toId: z.string().min(1),
+        relationship: z.string().min(1).optional()
+      }
+    },
+    async (input) => jsonResult(await linkRecords(runtime.db, input, recordActorId))
+  );
+
+  registerDxcTool(
+    "unlink_records",
+    {
+      description: "Remove one relationship link from a DX Complete record to another record.",
+      inputSchema: {
+        workspaceId: workspaceIdSchema,
+        fromType: activeCollectionSchema,
+        fromId: z.string().min(1),
+        toType: activeCollectionSchema,
+        toId: z.string().min(1),
+        relationship: z.string().min(1).optional()
+      }
+    },
+    async (input) => jsonResult(await unlinkRecords(runtime.db, input, recordActorId))
+  );
+
+  return server;
+}
+
+function omitWorkspaceId(schema: ToolSchema): ToolSchema {
+  const result: ToolSchema = {};
+
+  for (const [key, value] of Object.entries(schema)) {
+    if (key !== "workspaceId") {
+      result[key] = value;
+    }
+  }
+
+  return result;
+}
+
+function injectHostedWorkspace(
+  input: Record<string, unknown>,
+  originalSchema: ToolSchema,
+  workspaceId: string
+): Record<string, unknown> {
+  if (!Object.hasOwn(originalSchema, "workspaceId")) {
+    return input;
+  }
+
+  return {
+    ...input,
+    workspaceId
+  };
+}
+
+function assertHostedWorkspaceAccess(
+  toolName: string,
+  input: Record<string, unknown>,
+  workspaceId: string | undefined
+): void {
+  if (!workspaceId) {
+    return;
+  }
+
+  for (const key of ["recordType", "fromType", "toType", "supersededByType"]) {
+    if (input[key] === "workspaces") {
+      throw new Error(
+        `${toolName} cannot operate on workspace records through a hosted workspace MCP endpoint.`
+      );
+    }
+  }
+
+  if (typeof input.workspaceId === "string" && input.workspaceId !== workspaceId) {
+    throw new Error("Hosted MCP workspace scope mismatch.");
+  }
+}
+
+function assertToolRoleAccess(toolName: string, roles: WorkspaceRole[] | undefined, input: Record<string, unknown>): void {
+  if (!roles) {
+    return;
+  }
+
+  if (roles.includes("owner") || memberAllowedTools.has(toolName)) {
+    return;
+  }
+
+  if (roles.includes("engineer") && engineerAllowedTools.has(toolName)) {
+    return;
+  }
+
+  if (roles.includes("operator") && operatorAllowedTools.has(toolName)) {
+    return;
+  }
+
+  if (
+    roles.includes("operator") &&
+    toolName === "archive_record" &&
+    (input.recordType === "environments" || input.recordType === "components")
+  ) {
+    return;
+  }
+
+  throw new Error(`Workspace role access denied for ${toolName}.`);
+}
+
+const memberAllowedTools = new Set([
+  "runtime_status",
+  "get_process_guide",
+  "get_doc",
+  "get_record",
+  "list_records",
+  "list_linked_records",
+  "list_environments",
+  "list_components",
+  "create_dxcomplete_ticket",
+  "append_dxcomplete_ticket",
+  "list_dxcomplete_tickets",
+  "list_unread_dxcomplete_ticket_replies",
+  "read_dxcomplete_ticket",
+  "archive_dxcomplete_ticket",
+  "append_journal_note",
+  "read_journal",
+  "get_journal_entry",
+  "append_journal_summary"
+]);
+
+const engineerAllowedTools = new Set([
+  "create_estimate",
+  "update_estimate",
+  "create_task",
+  "append_task_entry",
+  "append_review_note"
+]);
+
+const operatorAllowedTools = new Set([
+  "create_change",
+  "append_change_event",
+  "create_environment",
+  "update_environment",
+  "create_component",
+  "update_component"
+]);
+
+function jsonResult(value: unknown) {
+  return {
+    content: [
+      {
+        type: "text" as const,
+        text: JSON.stringify(value, null, 2)
+      }
+    ]
+  };
+}
+
+function getInputSchemaFingerprint(inputSchema: ToolSchema): string {
+  return createHash("sha256")
+    .update(stableStringify(z.toJSONSchema(z.object(inputSchema))))
+    .digest("hex")
+    .slice(0, 16);
+}
+
+function stableStringify(value: unknown): string {
+  return JSON.stringify(sortJsonValue(value));
+}
+
+function sortJsonValue(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map(sortJsonValue);
+  }
+
+  if (value && typeof value === "object") {
+    const input = value as Record<string, unknown>;
+    const output: Record<string, unknown> = {};
+
+    for (const key of Object.keys(input).sort()) {
+      output[key] = sortJsonValue(input[key]);
+    }
+
+    return output;
+  }
+
+  return value;
+}
+
+
+async function createStatement(
+  runtime: DxRuntime,
+  input: {
+    workspaceId: string;
+    title: string;
+    statement: string;
+    source?: string;
+    fields?: Record<string, unknown>;
+  },
+  actorId: string
+) {
+  assertNoTypedFields(input.fields, "create_statement", STATEMENT_TYPED_FIELDS);
+
+  return createRecord(
+    runtime.db,
+    "statements",
+    {
+      workspaceId: input.workspaceId,
+      title: input.title,
+      summary: input.statement,
+      fields: {
+        ...(input.fields ?? {}),
+        statement: input.statement,
+        ...(input.source !== undefined ? { source: input.source } : {})
+      }
+    },
+    actorId
+  );
+}
+
+async function updateStatement(
+  runtime: DxRuntime,
+  input: {
+    workspaceId: string;
+    id: string;
+    title?: string;
+    statement?: string;
+    source?: string;
+    fields?: Record<string, unknown>;
+    unsetFields?: string[];
+    revisionNote?: string;
+  },
+  actorId: string
+) {
+  assertNoTypedFields(input.fields, "update_statement", STATEMENT_TYPED_FIELDS);
+
+  return updateRecord(
+    runtime.db,
+    {
+      recordType: "statements",
+      workspaceId: input.workspaceId,
+      id: input.id,
+      title: input.title,
+      summary: input.statement,
+      fields: {
+        ...(input.fields ?? {}),
+        ...(input.statement !== undefined ? { statement: input.statement } : {}),
+        ...(input.source !== undefined ? { source: input.source } : {})
+      },
+      unsetFields: input.unsetFields,
+      allowManagedFields: true,
+      revisionNote: input.revisionNote
+    },
+    actorId
+  );
+}
+
+async function createEnvironment(
+  runtime: DxRuntime,
+  input: {
+    workspaceId: string;
+    name: string;
+    summary?: string;
+    description?: string;
+    fields?: Record<string, unknown>;
+  },
+  actorId: string
+) {
+  assertNoTypedFields(input.fields, "create_environment", ENVIRONMENT_TYPED_FIELDS);
+
+  return createRecord(
+    runtime.db,
+    "environments",
+    {
+      workspaceId: input.workspaceId,
+      title: input.name,
+      summary: input.summary,
+      allowManagedFields: true,
+      fields: {
+        ...(input.fields ?? {}),
+        name: input.name,
+        ...(input.description !== undefined ? { description: input.description } : {})
+      }
+    },
+    actorId
+  );
+}
+
+async function updateEnvironment(
+  runtime: DxRuntime,
+  input: {
+    workspaceId: string;
+    id: string;
+    name?: string;
+    summary?: string;
+    description?: string;
+    fields?: Record<string, unknown>;
+    unsetFields?: string[];
+    revisionNote?: string;
+  },
+  actorId: string
+) {
+  assertNoTypedFields(input.fields, "update_environment", ENVIRONMENT_TYPED_FIELDS);
+  assertNoTypedUnsetFields(input.unsetFields, "update_environment", ENVIRONMENT_TYPED_FIELDS);
+
+  return updateRecord(
+    runtime.db,
+    {
+      recordType: "environments",
+      workspaceId: input.workspaceId,
+      id: input.id,
+      title: input.name,
+      summary: input.summary,
+      fields: {
+        ...(input.fields ?? {}),
+        ...(input.name !== undefined ? { name: input.name } : {}),
+        ...(input.description !== undefined ? { description: input.description } : {})
+      },
+      unsetFields: input.unsetFields,
+      allowManagedFields: true,
+      revisionNote: input.revisionNote
+    },
+    actorId
+  );
+}
+
+async function listComponents(
+  runtime: DxRuntime,
+  input: {
+    workspaceId: string;
+    environmentId: string;
+    limit?: number;
+    includeArchived?: boolean;
+  }
+) {
+  const environment = await getRecord(runtime.db, "environments", input.environmentId, {
+    workspaceId: input.workspaceId
+  });
+  if (!environment) {
+    throw new Error(`Environment not found: environments/${input.environmentId}`);
+  }
+
+  const filter: Record<string, unknown> = {
+    workspaceId: input.workspaceId,
+    "fields.environmentId": environment._id
+  };
+
+  if (!input.includeArchived) {
+    filter.archivedAt = { $exists: false };
+  }
+
+  return runtime.db
+    .collection("components")
+    .find(filter)
+    .sort({ createdAt: 1, _id: 1 })
+    .limit(input.limit ?? 20)
+    .toArray();
+}
+
+async function createComponent(
+  runtime: DxRuntime,
+  input: {
+    workspaceId: string;
+    name: string;
+    environmentId: string;
+    kind: string;
+    locator: ComponentLocatorInput;
+    summary?: string;
+    identifiers?: ComponentIdentifiersInput;
+    secretPointers?: SecretPointerInput[];
+    notes?: string;
+    fields?: Record<string, unknown>;
+  },
+  actorId: string
+) {
+  assertNoReservedFields(input.fields, ["workspaceId", "environmentId"]);
+  assertNoTypedFields(input.fields, "create_component", COMPONENT_TYPED_FIELDS);
+
+  const environment = await getRecord(runtime.db, "environments", input.environmentId, {
+    workspaceId: input.workspaceId
+  });
+  if (!environment) {
+    throw new Error(`Environment not found: environments/${input.environmentId}`);
+  }
+
+  const component = await createRecord(
+    runtime.db,
+    "components",
+    {
+      workspaceId: input.workspaceId,
+      title: input.name,
+      summary: input.summary,
+      allowManagedFields: true,
+      fields: {
+        ...(input.fields ?? {}),
+        name: input.name,
+        environmentId: environment._id,
+        kind: input.kind,
+        locator: input.locator,
+        ...(input.identifiers !== undefined ? { identifiers: input.identifiers } : {}),
+        ...(input.secretPointers !== undefined ? { secretPointers: input.secretPointers } : {}),
+        ...(input.notes !== undefined ? { notes: input.notes } : {})
+      }
+    },
+    actorId
+  );
+
+  return ensureLinkRecords(
+    runtime,
+    {
+      workspaceId: input.workspaceId,
+      fromType: "components",
+      fromId: component._id,
+      toType: "environments",
+      toId: environment._id,
+      relationship: "belongs_to_environment"
+    },
+    actorId
+  );
+}
+
+async function updateComponent(
+  runtime: DxRuntime,
+  input: {
+    workspaceId: string;
+    id: string;
+    name?: string;
+    kind?: string;
+    locator?: ComponentLocatorInput;
+    summary?: string;
+    identifiers?: ComponentIdentifiersInput;
+    secretPointers?: SecretPointerInput[];
+    notes?: string;
+    fields?: Record<string, unknown>;
+    unsetFields?: string[];
+    revisionNote?: string;
+  },
+  actorId: string
+) {
+  assertNoTypedFields(input.fields, "update_component", COMPONENT_TYPED_FIELDS);
+  assertNoTypedUnsetFields(input.unsetFields, "update_component", COMPONENT_TYPED_FIELDS);
+
+  return updateRecord(
+    runtime.db,
+    {
+      recordType: "components",
+      workspaceId: input.workspaceId,
+      id: input.id,
+      title: input.name,
+      summary: input.summary,
+      fields: {
+        ...(input.fields ?? {}),
+        ...(input.name !== undefined ? { name: input.name } : {}),
+        ...(input.kind !== undefined ? { kind: input.kind } : {}),
+        ...(input.locator !== undefined ? { locator: input.locator } : {}),
+        ...(input.identifiers !== undefined ? { identifiers: input.identifiers } : {}),
+        ...(input.secretPointers !== undefined ? { secretPointers: input.secretPointers } : {}),
+        ...(input.notes !== undefined ? { notes: input.notes } : {})
+      },
+      unsetFields: input.unsetFields,
+      allowManagedFields: true,
+      revisionNote: input.revisionNote
+    },
+    actorId
+  );
+}
+
+async function createExpectation(
+  runtime: DxRuntime,
+  input: {
+    workspaceId: string;
+    title: string;
+    statement: string;
+    successRecognition?: string;
+    approvalState?: "draft" | "approved" | "not_approved" | "superseded";
+    approvedBy?: string;
+    approvedAt?: string;
+    source?: string;
+    statementId?: string;
+    fields?: Record<string, unknown>;
+  },
+  actorId: string
+) {
+  assertNoTypedFields(input.fields, "create_expectation", EXPECTATION_TYPED_FIELDS);
+  assertNoObsoleteExpectationFields(input.fields, "create_expectation");
+
+  if (input.statementId) {
+    const statement = await getRecord(runtime.db, "statements", input.statementId, {
+      workspaceId: input.workspaceId
+    });
+    if (!statement) {
+      throw new Error(`Statement not found: statements/${input.statementId}`);
+    }
+  }
+
+  const expectation = await createRecord(
+    runtime.db,
+    "expectations",
+    {
+      workspaceId: input.workspaceId,
+      title: input.title,
+      summary: input.statement,
+      fields: {
+        ...(input.fields ?? {}),
+        statement: input.statement,
+        ...(input.successRecognition !== undefined ? { successRecognition: input.successRecognition } : {}),
+        approvalState: input.approvalState ?? "draft",
+        ...(input.approvedBy !== undefined ? { approvedBy: input.approvedBy } : {}),
+        ...(input.approvedAt !== undefined ? { approvedAt: input.approvedAt } : {}),
+        ...(input.source !== undefined ? { source: input.source } : {})
+      }
+    },
+    actorId
+  );
+
+  if (!input.statementId) {
+    return expectation;
+  }
+
+  return linkRecords(
+    runtime.db,
+    {
+      workspaceId: input.workspaceId,
+      fromType: "expectations",
+      fromId: expectation._id,
+      toType: "statements",
+      toId: input.statementId,
+      relationship: "derives_from"
+    },
+    actorId
+  );
+}
+
+type EstimateLineItem = {
+  id: string;
+  label: string;
+  timing: "one_time" | "recurring";
+  period?: string;
+  currency: string;
+  amount:
+    | {
+        kind: "single";
+        value: number;
+      }
+    | {
+        kind: "range";
+        min: number;
+        expected: number;
+        max: number;
+      };
+};
+
+type BenefitItem = {
+  id: string;
+  label: string;
+  timing?: "one_time" | "recurring";
+  period?: string;
+  currency?: string;
+  amount?: EstimateLineItem["amount"];
+};
+
+type RollupAmount = {
+  min: number;
+  expected: number;
+  max: number;
+};
+
+type QuantifiedRollupItem = {
+  timing: "one_time" | "recurring";
+  period?: string;
+  currency: string;
+  amount: EstimateLineItem["amount"];
+};
+
+async function createEstimate(
+  runtime: DxRuntime,
+  input: {
+    workspaceId: string;
+    title: string;
+    summary?: string;
+    lineItems: EstimateLineItemInput[];
+    requirementIds?: string[];
+    expectationIds?: string[];
+    fields?: Record<string, unknown>;
+  },
+  actorId: string
+) {
+  assertNoReservedFields(input.fields, ["workspaceId", "initiativeId", "requirementIds", "expectationIds"]);
+  assertNoTypedFields(input.fields, "create_estimate", ESTIMATE_TYPED_FIELDS);
+  assertAtLeastOneEstimateTarget(input.requirementIds, input.expectationIds);
+  await assertRecordsExist(runtime, "requirements", input.requirementIds ?? [], input.workspaceId);
+  await assertRecordsExist(runtime, "expectations", input.expectationIds ?? [], input.workspaceId);
+
+  const lineItems = normalizeEstimateLineItems(input.lineItems);
+  let estimate = await createRecord(
+    runtime.db,
+    "estimates",
+    {
+      workspaceId: input.workspaceId,
+      title: input.title,
+      summary: input.summary,
+      allowManagedFields: true,
+      fields: {
+        ...(input.fields ?? {}),
+        lineItems,
+        rollup: computeQuantifiedRollup(lineItems)
+      }
+    },
+    actorId
+  );
+
+  estimate = await linkManyRecords(runtime, estimate, "requirements", input.requirementIds ?? [], "estimates", actorId);
+  estimate = await linkManyRecords(runtime, estimate, "expectations", input.expectationIds ?? [], "estimates", actorId);
+
+  return estimate;
+}
+
+async function updateEstimate(
+  runtime: DxRuntime,
+  input: {
+    workspaceId: string;
+    id: string;
+    title?: string;
+    summary?: string;
+    lineItems?: EstimateLineItemInput[];
+    fields?: Record<string, unknown>;
+    unsetFields?: string[];
+    revisionNote?: string;
+  },
+  actorId: string
+) {
+  assertNoTypedFields(input.fields, "update_estimate", ESTIMATE_TYPED_FIELDS);
+  assertNoTypedUnsetFields(input.unsetFields, "update_estimate", ESTIMATE_TYPED_FIELDS);
+
+  const lineItems = input.lineItems ? normalizeEstimateLineItems(input.lineItems) : undefined;
+
+  return updateRecord(
+    runtime.db,
+    {
+      recordType: "estimates",
+      workspaceId: input.workspaceId,
+      id: input.id,
+      title: input.title,
+      summary: input.summary,
+      fields: {
+        ...(input.fields ?? {}),
+        ...(lineItems ? { lineItems, rollup: computeQuantifiedRollup(lineItems) } : {})
+      },
+      unsetFields: input.unsetFields,
+      allowManagedFields: true,
+      revisionNote: input.revisionNote
+    },
+    actorId
+  );
+}
+
+function normalizeEstimateLineItems(lineItems: EstimateLineItemInput[]): EstimateLineItem[] {
+  const seenIds = new Set<string>();
+  return lineItems.map((item, index) => {
+    const id = item.id ?? randomUUID();
+    if (seenIds.has(id)) {
+      throw new Error(`Estimate line item id must be unique: ${id}.`);
+    }
+    seenIds.add(id);
+
+    if (item.timing === "recurring" && !item.period) {
+      throw new Error(`Estimate line item ${index + 1} is recurring and requires period.`);
+    }
+    if (item.timing === "one_time" && item.period) {
+      throw new Error(`Estimate line item ${index + 1} is one_time and must omit period.`);
+    }
+    if (item.amount.kind === "range" && !(item.amount.min <= item.amount.expected && item.amount.expected <= item.amount.max)) {
+      throw new Error(`Estimate line item ${index + 1} range must satisfy min <= expected <= max.`);
+    }
+
+    return {
+      id,
+      label: item.label,
+      timing: item.timing,
+      ...(item.period ? { period: item.period } : {}),
+      currency: item.currency,
+      amount: item.amount
+    };
+  });
+}
+
+async function createBenefits(
+  runtime: DxRuntime,
+  input: {
+    workspaceId: string;
+    title: string;
+    summary?: string;
+    benefitItems: BenefitItemInput[];
+    requirementIds?: string[];
+    expectationIds?: string[];
+    fields?: Record<string, unknown>;
+  },
+  actorId: string
+) {
+  assertNoReservedFields(input.fields, ["workspaceId", "initiativeId", "requirementIds", "expectationIds"]);
+  assertNoTypedFields(input.fields, "create_benefits", BENEFITS_TYPED_FIELDS);
+  assertAtLeastOneBenefitsTarget(input.requirementIds, input.expectationIds);
+  await assertRecordsExist(runtime, "requirements", input.requirementIds ?? [], input.workspaceId);
+  await assertRecordsExist(runtime, "expectations", input.expectationIds ?? [], input.workspaceId);
+
+  const benefitItems = normalizeBenefitItems(input.benefitItems);
+  let benefits = await createRecord(
+    runtime.db,
+    "benefits",
+    {
+      workspaceId: input.workspaceId,
+      title: input.title,
+      summary: input.summary,
+      allowManagedFields: true,
+      fields: {
+        ...(input.fields ?? {}),
+        benefitItems,
+        rollup: computeQuantifiedRollup(benefitItems.filter(isQuantifiedBenefitItem))
+      }
+    },
+    actorId
+  );
+
+  benefits = await linkManyRecords(runtime, benefits, "requirements", input.requirementIds ?? [], "benefits", actorId);
+  benefits = await linkManyRecords(runtime, benefits, "expectations", input.expectationIds ?? [], "benefits", actorId);
+
+  return benefits;
+}
+
+async function updateBenefits(
+  runtime: DxRuntime,
+  input: {
+    workspaceId: string;
+    id: string;
+    title?: string;
+    summary?: string;
+    benefitItems?: BenefitItemInput[];
+    fields?: Record<string, unknown>;
+    unsetFields?: string[];
+    revisionNote?: string;
+  },
+  actorId: string
+) {
+  assertNoTypedFields(input.fields, "update_benefits", BENEFITS_TYPED_FIELDS);
+  assertNoTypedUnsetFields(input.unsetFields, "update_benefits", BENEFITS_TYPED_FIELDS);
+
+  const benefitItems = input.benefitItems ? normalizeBenefitItems(input.benefitItems) : undefined;
+
+  return updateRecord(
+    runtime.db,
+    {
+      recordType: "benefits",
+      workspaceId: input.workspaceId,
+      id: input.id,
+      title: input.title,
+      summary: input.summary,
+      fields: {
+        ...(input.fields ?? {}),
+        ...(benefitItems ? { benefitItems, rollup: computeQuantifiedRollup(benefitItems.filter(isQuantifiedBenefitItem)) } : {})
+      },
+      unsetFields: input.unsetFields,
+      allowManagedFields: true,
+      revisionNote: input.revisionNote
+    },
+    actorId
+  );
+}
+
+function normalizeBenefitItems(benefitItems: BenefitItemInput[]): BenefitItem[] {
+  const seenIds = new Set<string>();
+  return benefitItems.map((item, index) => {
+    const id = item.id ?? randomUUID();
+    if (seenIds.has(id)) {
+      throw new Error(`Benefit item id must be unique: ${id}.`);
+    }
+    seenIds.add(id);
+
+    if (!item.amount) {
+      if (item.timing || item.period || item.currency) {
+        throw new Error(`Benefit item ${index + 1} is qualitative and must omit timing, period, and currency.`);
+      }
+      return {
+        id,
+        label: item.label
+      };
+    }
+
+    if (!item.timing) {
+      throw new Error(`Benefit item ${index + 1} has amount and requires timing.`);
+    }
+    if (!item.currency) {
+      throw new Error(`Benefit item ${index + 1} has amount and requires currency.`);
+    }
+    if (item.timing === "recurring" && !item.period) {
+      throw new Error(`Benefit item ${index + 1} is recurring and requires period.`);
+    }
+    if (item.timing === "one_time" && item.period) {
+      throw new Error(`Benefit item ${index + 1} is one_time and must omit period.`);
+    }
+    if (item.amount.kind === "range" && !(item.amount.min <= item.amount.expected && item.amount.expected <= item.amount.max)) {
+      throw new Error(`Benefit item ${index + 1} range must satisfy min <= expected <= max.`);
+    }
+
+    return {
+      id,
+      label: item.label,
+      timing: item.timing,
+      ...(item.period ? { period: item.period } : {}),
+      currency: item.currency,
+      amount: item.amount
+    };
+  });
+}
+
+function isQuantifiedBenefitItem(item: BenefitItem): item is BenefitItem & QuantifiedRollupItem {
+  return !!item.amount && !!item.timing && !!item.currency;
+}
+
+function computeQuantifiedRollup(lineItems: QuantifiedRollupItem[]): Record<string, unknown> {
+  const currencies: Record<string, Record<string, unknown>> = {};
+
+  for (const item of lineItems) {
+    const currency = (currencies[item.currency] ??= createEmptyRollupTimingGroup());
+    const amount = normalizeRollupAmount(item.amount);
+
+    if (item.timing === "one_time") {
+      currency.one_time = addRollupAmounts(currency.one_time as RollupAmount | undefined, amount);
+      continue;
+    }
+
+    const recurring = currency.recurring as Record<string, RollupAmount>;
+    recurring[item.period ?? ""] = addRollupAmounts(recurring[item.period ?? ""], amount);
+  }
+
+  return { currencies };
+}
+
+function createEmptyRollupTimingGroup(): Record<string, unknown> {
+  return {
+    one_time: createZeroRollupAmount(),
+    recurring: {}
+  };
+}
+
+function createZeroRollupAmount(): RollupAmount {
+  return { min: 0, expected: 0, max: 0 };
+}
+
+function normalizeRollupAmount(amount: EstimateLineItem["amount"]): RollupAmount {
+  if (amount.kind === "single") {
+    return { min: amount.value, expected: amount.value, max: amount.value };
+  }
+
+  return { min: amount.min, expected: amount.expected, max: amount.max };
+}
+
+function addRollupAmounts(
+  left: RollupAmount | undefined,
+  right: RollupAmount
+): RollupAmount {
+  const base = left ?? createZeroRollupAmount();
+  return {
+    min: base.min + right.min,
+    expected: base.expected + right.expected,
+    max: base.max + right.max
+  };
+}
+
+async function createRequirement(
+  runtime: DxRuntime,
+  input: {
+    workspaceId: string;
+    title: string;
+    expectationId?: string;
+    statement: string;
+    acceptanceCriteria?: string[];
+    priority?: "low" | "medium" | "high";
+    status?: "draft" | "ready" | "approved" | "superseded";
+    fields?: Record<string, unknown>;
+  },
+  actorId: string
+) {
+  assertNoReservedFields(input.fields, ["workspaceId", "expectationId"]);
+  assertNoTypedFields(input.fields, "create_requirement", REQUIREMENT_TYPED_FIELDS);
+
+  if (input.expectationId) {
+    const expectation = await getRecord(runtime.db, "expectations", input.expectationId, {
+      workspaceId: input.workspaceId
+    });
+    if (!expectation) {
+      throw new Error(`Expectation not found: expectations/${input.expectationId}`);
+    }
+  }
+
+  const requirement = await createRecord(
+    runtime.db,
+    "requirements",
+    {
+      workspaceId: input.workspaceId,
+      title: input.title,
+      summary: input.statement,
+      fields: {
+        ...(input.fields ?? {}),
+        statement: input.statement,
+        ...(input.acceptanceCriteria ? { acceptanceCriteria: input.acceptanceCriteria } : {}),
+        ...(input.priority ? { priority: input.priority } : {}),
+        status: input.status ?? "draft"
+      }
+    },
+    actorId
+  );
+
+  if (!input.expectationId) {
+    return requirement;
+  }
+
+  return linkRecords(
+    runtime.db,
+    {
+      workspaceId: input.workspaceId,
+      fromType: "requirements",
+      fromId: requirement._id,
+      toType: "expectations",
+      toId: input.expectationId,
+      relationship: "satisfies"
+    },
+    actorId
+  );
+}
+
+async function createTask(
+  runtime: DxRuntime,
+  input: {
+    workspaceId: string;
+    title: string;
+    description: string;
+    assignee?: string;
+    assignor?: string;
+    requirementId?: string;
+    initialStatus?: "open" | "in_progress" | "blocked" | "done";
+    fields?: Record<string, unknown>;
+  },
+  actorId: string
+) {
+  assertNoReservedFields(input.fields, ["workspaceId", "requirementId"]);
+  assertNoTypedFields(input.fields, "create_task", TASK_TYPED_FIELDS);
+
+  if (input.requirementId) {
+    const requirement = await getRecord(runtime.db, "requirements", input.requirementId, {
+      workspaceId: input.workspaceId
+    });
+    if (!requirement) {
+      throw new Error(`Requirement not found: requirements/${input.requirementId}`);
+    }
+  }
+
+  const now = new Date().toISOString();
+  const initialStatus = input.initialStatus ?? "open";
+  const initialStatusEntry: TaskEntry = {
+    id: randomUUID(),
+    entryType: "status_change",
+    body: `Initial status: ${initialStatus}.`,
+    status: initialStatus,
+    createdAt: now,
+    createdBy: actorId
+  };
+
+  const task = await createRecord(
+    runtime.db,
+    "tasks",
+    {
+      workspaceId: input.workspaceId,
+      title: input.title,
+      summary: input.description,
+      allowManagedFields: true,
+      fields: {
+        ...(input.fields ?? {}),
+        description: input.description,
+        ...(input.assignee !== undefined ? { assignee: input.assignee } : {}),
+        ...(input.assignor !== undefined ? { assignor: input.assignor } : {}),
+        entries: [initialStatusEntry],
+        currentStatus: taskEntryToCurrentStatus(initialStatusEntry)
+      }
+    },
+    actorId
+  );
+
+  if (!input.requirementId) {
+    return task;
+  }
+
+  return linkRecords(
+    runtime.db,
+    {
+      workspaceId: input.workspaceId,
+      fromType: "tasks",
+      fromId: task._id,
+      toType: "requirements",
+      toId: input.requirementId,
+      relationship: "implements"
+    },
+    actorId
+  );
+}
+
+async function createDecision(
+  runtime: DxRuntime,
+  input: {
+    workspaceId: string;
+    title: string;
+    matter: string;
+    initialEntries?: DecisionInitialEntryInput[];
+    initialDecision?: InitialDecisionInput;
+    fields?: Record<string, unknown>;
+  },
+  actorId: string
+) {
+  assertNoTypedFields(input.fields, "create_decision", DECISION_TYPED_FIELDS);
+  assertNoDecisionInputFields(input.fields);
+
+  const now = new Date().toISOString();
+  const entries = buildInitialDecisionEntries(input.initialEntries, input.initialDecision, actorId, now);
+  const latestDecisionEntry = [...entries].reverse().find((entry) => entry.entryType === "decision");
+
+  return createRecord(
+    runtime.db,
+    "decisions",
+    {
+      workspaceId: input.workspaceId,
+      title: input.title,
+      summary: latestDecisionEntry?.body ?? input.matter,
+      allowManagedFields: true,
+      fields: {
+        ...(input.fields ?? {}),
+        matter: input.matter,
+        entries,
+        ...(latestDecisionEntry ? { currentDecision: decisionEntryToCurrentDecision(latestDecisionEntry) } : {})
+      }
+    },
+    actorId
+  );
+}
+
+function buildInitialDecisionEntries(
+  initialEntries: DecisionInitialEntryInput[] | undefined,
+  initialDecision: InitialDecisionInput | undefined,
+  actorId: string,
+  createdAt: string
+): DecisionEntry[] {
+  const entries = (initialEntries ?? []).map((entry) =>
+    buildDecisionEntry(
+      {
+        entryType: entry.entryType,
+        body: entry.body,
+        decidedBy: entry.decidedBy,
+        rationale: entry.rationale
+      },
+      actorId,
+      createdAt
+    )
+  );
+
+  if (initialDecision) {
+    entries.push(
+      buildDecisionEntry(
+        {
+          entryType: "decision",
+          body: initialDecision.body,
+          decidedBy: initialDecision.decidedBy,
+          rationale: initialDecision.rationale
+        },
+        actorId,
+        createdAt
+      )
+    );
+  }
+
+  return entries;
+}
+
+function buildDecisionEntry(
+  input: {
+    entryType: "argument" | "decision" | "note";
+    body: string;
+    decidedBy?: string;
+    rationale?: string;
+  },
+  actorId: string,
+  createdAt: string
+): DecisionEntry {
+  if (input.entryType !== "decision" && (input.decidedBy || input.rationale)) {
+    throw new Error("decidedBy and rationale are only valid on decision entries.");
+  }
+
+  return {
+    id: randomUUID(),
+    entryType: input.entryType,
+    body: input.body,
+    createdAt,
+    createdBy: actorId,
+    ...(input.decidedBy ? { decidedBy: input.decidedBy } : {}),
+    ...(input.rationale ? { rationale: input.rationale } : {})
+  };
+}
+
+async function createCommitment(
+  runtime: DxRuntime,
+  input: {
+    workspaceId: string;
+    title: string;
+    summary?: string;
+    commitmentStatement: string;
+    requirementIds?: string[];
+    expectationIds?: string[];
+    reservationNotes?: string[];
+    deferralId?: string;
+    fields?: Record<string, unknown>;
+  },
+  actorId: string
+) {
+  assertNoReservedFields(input.fields, ["workspaceId", "requirementIds", "expectationIds", "deferralId"]);
+  assertNoTypedFields(input.fields, "create_commitment", COMMITMENT_TYPED_FIELDS);
+  assertAtLeastOneCommitmentTarget(input.requirementIds, input.expectationIds);
+  await assertRecordsExist(runtime, "requirements", input.requirementIds ?? [], input.workspaceId);
+  await assertRecordsExist(runtime, "expectations", input.expectationIds ?? [], input.workspaceId);
+
+  if (input.deferralId) {
+    const deferral = await getRecord(runtime.db, "deferrals", input.deferralId, {
+      workspaceId: input.workspaceId
+    });
+    if (!deferral) {
+      throw new Error(`Deferral not found: deferrals/${input.deferralId}`);
+    }
+  }
+
+  const now = new Date().toISOString();
+  let commitment = await createRecord(
+    runtime.db,
+    "commitments",
+    {
+      workspaceId: input.workspaceId,
+      title: input.title,
+      summary: input.summary ?? input.commitmentStatement,
+      allowManagedFields: true,
+      fields: {
+        ...(input.fields ?? {}),
+        commitmentStatement: input.commitmentStatement,
+        reservations: (input.reservationNotes ?? []).map((note) => ({
+          id: randomUUID(),
+          note,
+          createdAt: now,
+          createdBy: actorId
+        }))
+      }
+    },
+    actorId
+  );
+
+  commitment = await linkManyRecords(runtime, commitment, "requirements", input.requirementIds ?? [], "commits", actorId);
+  commitment = await linkManyRecords(runtime, commitment, "expectations", input.expectationIds ?? [], "commits", actorId);
+
+  if (input.deferralId) {
+    commitment = await ensureLinkRecords(
+      runtime,
+      {
+        workspaceId: input.workspaceId,
+        fromType: "commitments",
+        fromId: commitment._id,
+        toType: "deferrals",
+        toId: input.deferralId,
+        relationship: "resolves_deferral"
+      },
+      actorId
+    );
+  }
+
+  return commitment;
+}
+
+async function createDeferral(
+  runtime: DxRuntime,
+  input: {
+    workspaceId: string;
+    title: string;
+    summary?: string;
+    reason: string;
+    conditions: string[];
+    requirementIds?: string[];
+    expectationIds?: string[];
+    fields?: Record<string, unknown>;
+  },
+  actorId: string
+) {
+  assertNoReservedFields(input.fields, ["workspaceId", "requirementIds", "expectationIds"]);
+  assertNoTypedFields(input.fields, "create_deferral", DEFERRAL_TYPED_FIELDS);
+  await assertRecordsExist(runtime, "requirements", input.requirementIds ?? [], input.workspaceId);
+  await assertRecordsExist(runtime, "expectations", input.expectationIds ?? [], input.workspaceId);
+
+  const now = new Date().toISOString();
+  let deferral = await createRecord(
+    runtime.db,
+    "deferrals",
+    {
+      workspaceId: input.workspaceId,
+      title: input.title,
+      summary: input.summary ?? input.reason,
+      allowManagedFields: true,
+      fields: {
+        ...(input.fields ?? {}),
+        reason: input.reason,
+        status: "open",
+        conditions: input.conditions.map((statement) => ({
+          id: randomUUID(),
+          statement,
+          state: "open",
+          createdAt: now,
+          createdBy: actorId,
+          updatedAt: now,
+          updatedBy: actorId
+        })),
+        conditionEvents: []
+      }
+    },
+    actorId
+  );
+
+  deferral = await linkManyRecords(runtime, deferral, "requirements", input.requirementIds ?? [], "defers", actorId);
+  deferral = await linkManyRecords(runtime, deferral, "expectations", input.expectationIds ?? [], "defers", actorId);
+
+  return deferral;
+}
+
+async function appendDeferralEventForTool(
+  runtime: DxRuntime,
+  input: {
+    workspaceId: string;
+    deferralId: string;
+    eventType: "condition_addressed" | "condition_reopened" | "condition_note_added" | "deferral_resolved" | "deferral_abandoned";
+    conditionId?: string;
+    note?: string;
+    summary?: string;
+    reason?: string;
+    commitmentId?: string;
+  },
+  actorId: string
+) {
+  const event = buildDeferralEventContent(input);
+
+  if (input.eventType === "deferral_resolved") {
+    const commitment = await getRecord(runtime.db, "commitments", event.commitmentId as string, {
+      workspaceId: input.workspaceId
+    });
+    if (!commitment) {
+      throw new Error(`Commitment not found: commitments/${event.commitmentId}`);
+    }
+  }
+
+  const deferral = await appendDeferralEvent(
+    runtime.db,
+    {
+      workspaceId: input.workspaceId,
+      deferralId: input.deferralId,
+      eventType: input.eventType,
+      event
+    },
+    actorId
+  );
+
+  if (input.eventType !== "deferral_resolved") {
+    return deferral;
+  }
+
+  await ensureLinkRecords(
+    runtime,
+    {
+      workspaceId: input.workspaceId,
+      fromType: "commitments",
+      fromId: event.commitmentId as string,
+      toType: "deferrals",
+      toId: deferral._id,
+      relationship: "resolves_deferral"
+    },
+    actorId
+  );
+
+  const updated = await getRecord(runtime.db, "deferrals", input.deferralId, { workspaceId: input.workspaceId });
+  if (!updated) {
+    throw new Error(`Deferral not found after resolution link: deferrals/${input.deferralId}`);
+  }
+
+  return updated;
+}
+
+function buildDeferralEventContent(input: {
+  eventType: "condition_addressed" | "condition_reopened" | "condition_note_added" | "deferral_resolved" | "deferral_abandoned";
+  conditionId?: string;
+  note?: string;
+  summary?: string;
+  reason?: string;
+  commitmentId?: string;
+}): Record<string, unknown> {
+  switch (input.eventType) {
+    case "condition_addressed":
+    case "condition_reopened":
+      return compactObject({
+        conditionId: requireDeferralEventField(input.conditionId, input.eventType, "conditionId"),
+        summary: input.summary
+      });
+    case "condition_note_added":
+      return compactObject({
+        conditionId: requireDeferralEventField(input.conditionId, input.eventType, "conditionId"),
+        note: requireDeferralEventField(input.note, input.eventType, "note")
+      });
+    case "deferral_resolved":
+      return compactObject({
+        commitmentId: requireDeferralEventField(input.commitmentId, input.eventType, "commitmentId"),
+        summary: input.summary
+      });
+    case "deferral_abandoned":
+      return compactObject({
+        reason: requireDeferralEventField(input.reason, input.eventType, "reason"),
+        summary: input.summary
+      });
+  }
+}
+
+function requireDeferralEventField<T>(value: T | undefined, eventType: string, fieldName: string): T {
+  if (value === undefined) {
+    throw new Error(`${eventType} requires ${fieldName}.`);
+  }
+
+  return value;
+}
+
+function assertAtLeastOneCommitmentTarget(requirementIds: string[] | undefined, expectationIds: string[] | undefined): void {
+  if ((requirementIds?.length ?? 0) > 0 || (expectationIds?.length ?? 0) > 0) {
+    return;
+  }
+
+  throw new Error("create_commitment requires at least one requirementId or expectationId.");
+}
+
+function assertAtLeastOneEstimateTarget(requirementIds: string[] | undefined, expectationIds: string[] | undefined): void {
+  if ((requirementIds?.length ?? 0) > 0 || (expectationIds?.length ?? 0) > 0) {
+    return;
+  }
+
+  throw new Error("create_estimate requires at least one requirementId or expectationId.");
+}
+
+function assertAtLeastOneBenefitsTarget(requirementIds: string[] | undefined, expectationIds: string[] | undefined): void {
+  if ((requirementIds?.length ?? 0) > 0 || (expectationIds?.length ?? 0) > 0) {
+    return;
+  }
+
+  throw new Error("create_benefits requires at least one requirementId or expectationId.");
+}
+
+async function assertRecordsExist(
+  runtime: DxRuntime,
+  recordType: "requirements" | "expectations",
+  ids: string[],
+  workspaceId: string
+): Promise<void> {
+  for (const id of new Set(ids)) {
+    const record = await getRecord(runtime.db, recordType, id, { workspaceId });
+    if (!record) {
+      throw new Error(`Record not found: ${recordType}/${id}`);
+    }
+  }
+}
+
+async function linkManyRecords(
+  runtime: DxRuntime,
+  source: Awaited<ReturnType<typeof getRecord>>,
+  toType: "requirements" | "expectations",
+  toIds: string[],
+  relationship: string,
+  actorId: string
+) {
+  if (!source) {
+    throw new Error("Source record not found.");
+  }
+
+  let current = source;
+  for (const toId of new Set(toIds)) {
+    current = await ensureLinkRecords(
+      runtime,
+      {
+        workspaceId: current.workspaceId ?? "",
+        fromType: current.recordType as CollectionName,
+        fromId: current._id,
+        toType,
+        toId,
+        relationship
+      },
+      actorId
+    );
+  }
+
+  return current;
+}
+
+async function ensureLinkRecords(
+  runtime: DxRuntime,
+  input: {
+    workspaceId: string;
+    fromType: CollectionName;
+    fromId: string;
+    toType: CollectionName;
+    toId: string;
+    relationship: string;
+  },
+  actorId: string
+) {
+  const source = await getRecord(runtime.db, input.fromType, input.fromId, {
+    workspaceId: input.workspaceId
+  });
+  if (!source) {
+    throw new Error(`Source record not found: ${input.fromType}/${input.fromId}`);
+  }
+  const target = await getRecord(runtime.db, input.toType, input.toId, {
+    workspaceId: input.workspaceId
+  });
+  if (!target) {
+    throw new Error(`Target record not found: ${input.toType}/${input.toId}`);
+  }
+
+  if (
+    source.links.some(
+      (link) =>
+        link.toType === input.toType &&
+        link.toId === target._id &&
+        link.relationship === input.relationship
+    )
+  ) {
+    return source;
+  }
+
+  return linkRecords(runtime.db, input, actorId);
+}
+
+async function createChange(
+  runtime: DxRuntime,
+  input: {
+    workspaceId: string;
+    title: string;
+    summary?: string;
+    changePlan: string;
+    executionSteps: string[];
+    rollbackPlan: string;
+    riskImpact: string;
+    plannedFor?: string;
+    requirementId?: string;
+    fields?: Record<string, unknown>;
+  },
+  actorId: string
+) {
+  assertNoReservedFields(input.fields, ["workspaceId", "initiativeId", "requirementId"]);
+  assertNoTypedFields(input.fields, "create_change", CHANGE_TYPED_FIELDS);
+
+  if (input.requirementId) {
+    const requirement = await getRecord(runtime.db, "requirements", input.requirementId, {
+      workspaceId: input.workspaceId
+    });
+    if (!requirement) {
+      throw new Error(`Requirement not found: requirements/${input.requirementId}`);
+    }
+  }
+
+  let change = await createRecord(
+    runtime.db,
+    "changes",
+    {
+      workspaceId: input.workspaceId,
+      title: input.title,
+      summary: input.summary ?? input.changePlan,
+      allowManagedFields: true,
+      fields: {
+        ...(input.fields ?? {}),
+        changePlan: input.changePlan,
+        executionSteps: input.executionSteps,
+        rollbackPlan: input.rollbackPlan,
+        riskImpact: input.riskImpact,
+        ...(input.plannedFor !== undefined ? { plannedFor: input.plannedFor } : {})
+      }
+    },
+    actorId
+  );
+
+  if (input.requirementId) {
+    change = await linkRecords(
+      runtime.db,
+      {
+        workspaceId: input.workspaceId,
+        fromType: "changes",
+        fromId: change._id,
+        toType: "requirements",
+        toId: input.requirementId,
+        relationship: "for_requirement"
+      },
+      actorId
+    );
+  }
+
+  return change;
+}
+
+function buildChangeEventContent(input: {
+  eventType:
+    | "notice_given"
+    | "veto_recorded"
+    | "emergency_declared"
+    | "decision_recorded"
+    | "result_reported"
+    | "recovery_recorded"
+    | "plan_revised"
+    | "note_added";
+  notice?: string;
+  noticeTo?: string[];
+  effectiveAt?: string;
+  vetoByRole?: "Owner" | "Engineer";
+  reason?: string;
+  importance?: string;
+  immediacy?: string;
+  decision?: "proceed" | "defer" | "cancel";
+  result?: "completed" | "failed" | "rolled_back";
+  summary?: string;
+  note?: string;
+  revisedChangePlan?: string;
+  revisedExecutionSteps?: string[];
+  revisedRollbackPlan?: string;
+  revisedRiskImpact?: string;
+  revisedPlannedFor?: string;
+}): Record<string, unknown> {
+  switch (input.eventType) {
+    case "notice_given":
+      return compactObject({
+        notice: requireChangeEventField(input.notice, input.eventType, "notice"),
+        noticeTo: input.noticeTo,
+        effectiveAt: input.effectiveAt
+      });
+    case "veto_recorded":
+      return compactObject({
+        vetoByRole: requireChangeEventField(input.vetoByRole, input.eventType, "vetoByRole"),
+        reason: input.reason,
+        summary: input.summary
+      });
+    case "emergency_declared":
+      return compactObject({
+        importance: requireChangeEventField(input.importance, input.eventType, "importance"),
+        immediacy: requireChangeEventField(input.immediacy, input.eventType, "immediacy"),
+        summary: input.summary
+      });
+    case "decision_recorded":
+      return compactObject({
+        decision: requireChangeEventField(input.decision, input.eventType, "decision"),
+        reason: input.reason,
+        summary: input.summary
+      });
+    case "result_reported":
+      return compactObject({
+        result: requireChangeEventField(input.result, input.eventType, "result"),
+        summary: input.summary
+      });
+    case "recovery_recorded":
+      return compactObject({
+        summary: requireChangeEventField(input.summary, input.eventType, "summary")
+      });
+    case "plan_revised": {
+      const event = compactObject({
+        summary: input.summary,
+        revisedChangePlan: input.revisedChangePlan,
+        revisedExecutionSteps: input.revisedExecutionSteps,
+        revisedRollbackPlan: input.revisedRollbackPlan,
+        revisedRiskImpact: input.revisedRiskImpact,
+        revisedPlannedFor: input.revisedPlannedFor
+      });
+      if (Object.keys(event).length === 0) {
+        throw new Error("plan_revised requires summary or at least one revised plan field.");
+      }
+      return event;
+    }
+    case "note_added":
+      return compactObject({
+        note: requireChangeEventField(input.note, input.eventType, "note")
+      });
+  }
+}
+
+function requireChangeEventField<T>(value: T | undefined, eventType: string, fieldName: string): T {
+  if (value === undefined) {
+    throw new Error(`${eventType} requires ${fieldName}.`);
+  }
+
+  return value;
+}
+
+function compactObject(input: Record<string, unknown>): Record<string, unknown> {
+  return Object.fromEntries(Object.entries(input).filter(([, value]) => value !== undefined));
+}
+
+async function updateExpectation(
+  runtime: DxRuntime,
+  input: {
+    workspaceId: string;
+    id: string;
+    title?: string;
+    statement?: string;
+    successRecognition?: string;
+    approvalState?: "draft" | "approved" | "not_approved" | "superseded";
+    approvedBy?: string;
+    approvedAt?: string;
+    source?: string;
+    revisionNote?: string;
+    fields?: Record<string, unknown>;
+    unsetFields?: string[];
+  },
+  actorId: string
+) {
+  assertNoTypedFields(input.fields, "update_expectation", EXPECTATION_TYPED_FIELDS);
+  assertNoObsoleteExpectationFields(input.fields, "update_expectation");
+
+  return updateRecord(
+    runtime.db,
+    {
+      recordType: "expectations",
+      workspaceId: input.workspaceId,
+      id: input.id,
+      title: input.title,
+      summary: input.statement,
+      fields: {
+        ...(input.fields ?? {}),
+        ...(input.statement !== undefined ? { statement: input.statement } : {}),
+        ...(input.successRecognition !== undefined ? { successRecognition: input.successRecognition } : {}),
+        ...(input.approvalState !== undefined ? { approvalState: input.approvalState } : {}),
+        ...(input.approvedBy !== undefined ? { approvedBy: input.approvedBy } : {}),
+        ...(input.approvedAt !== undefined ? { approvedAt: input.approvedAt } : {}),
+        ...(input.source !== undefined ? { source: input.source } : {})
+      },
+      unsetFields: input.unsetFields,
+      allowManagedFields: true,
+      revisionNote: input.revisionNote
+    },
+    actorId
+  );
+}
+
+async function updateRequirement(
+  runtime: DxRuntime,
+  input: {
+    workspaceId: string;
+    id: string;
+    title?: string;
+    statement?: string;
+    acceptanceCriteria?: string[];
+    priority?: "low" | "medium" | "high";
+    status?: "draft" | "ready" | "approved" | "superseded";
+    revisionNote?: string;
+    fields?: Record<string, unknown>;
+    unsetFields?: string[];
+  },
+  actorId: string
+) {
+  assertNoTypedFields(input.fields, "update_requirement", REQUIREMENT_TYPED_FIELDS);
+
+  return updateRecord(
+    runtime.db,
+    {
+      recordType: "requirements",
+      workspaceId: input.workspaceId,
+      id: input.id,
+      title: input.title,
+      summary: input.statement,
+      fields: {
+        ...(input.fields ?? {}),
+        ...(input.statement !== undefined ? { statement: input.statement } : {}),
+        ...(input.acceptanceCriteria !== undefined ? { acceptanceCriteria: input.acceptanceCriteria } : {}),
+        ...(input.priority !== undefined ? { priority: input.priority } : {}),
+        ...(input.status !== undefined ? { status: input.status } : {})
+      },
+      unsetFields: input.unsetFields,
+      allowManagedFields: true,
+      revisionNote: input.revisionNote
+    },
+    actorId
+  );
+}
+
+async function linkDecisionInput(
+  runtime: DxRuntime,
+  input: {
+    workspaceId: string;
+    decisionId: string;
+    inputRecordType: DecisionInputRecordType;
+    inputId: string;
+  },
+  actorId: string
+) {
+  if (input.inputRecordType === "decisions" && input.inputId === input.decisionId) {
+    throw new Error("A Decision cannot be linked to itself as a decision input.");
+  }
+
+  const decision = await getRecord(runtime.db, "decisions", input.decisionId, {
+    workspaceId: input.workspaceId
+  });
+  if (!decision) {
+    throw new Error(`Decision not found: decisions/${input.decisionId}`);
+  }
+
+  const inputRecord = await getRecord(runtime.db, input.inputRecordType, input.inputId, {
+    workspaceId: input.workspaceId
+  });
+  if (!inputRecord) {
+    throw new Error(`Decision input not found: ${input.inputRecordType}/${input.inputId}`);
+  }
+
+  if (
+    decision.links.some(
+      (link) =>
+        link.toType === input.inputRecordType &&
+        link.toId === inputRecord._id &&
+        link.relationship === "informed_by"
+    )
+  ) {
+    return decision;
+  }
+
+  return linkRecords(
+    runtime.db,
+    {
+      workspaceId: input.workspaceId,
+      fromType: "decisions",
+      fromId: decision._id,
+      toType: input.inputRecordType,
+      toId: inputRecord._id,
+      relationship: "informed_by"
+    },
+    actorId
+  );
+}
+
+function assertNoReservedFields(fields: Record<string, unknown> | undefined, reservedFields: string[]): void {
+  for (const reservedField of reservedFields) {
+    if (fields && Object.hasOwn(fields, reservedField)) {
+      throw new Error(
+        `${reservedField} is a relationship input on this tool. Use the top-level ${reservedField} argument instead of fields.${reservedField}.`
+      );
+    }
+  }
+}
+
+function assertNoTypedFields(
+  fields: Record<string, unknown> | undefined,
+  toolName: string,
+  typedFields: string[]
+): void {
+  for (const typedField of typedFields) {
+    if (fields && Object.hasOwn(fields, typedField)) {
+      throw new Error(
+        `${typedField} is a typed input on ${toolName}. Use the top-level ${typedField} argument instead of fields.${typedField}.`
+      );
+    }
+  }
+}
+
+function assertNoTypedUnsetFields(unsetFields: string[] | undefined, toolName: string, typedFields: string[]): void {
+  for (const unsetField of unsetFields ?? []) {
+    if (typedFields.includes(unsetField)) {
+      throw new Error(`${unsetField} is managed on ${toolName}. Use the typed inputs instead of unsetFields.${unsetField}.`);
+    }
+  }
+}
+
+function assertNoDecisionInputFields(fields: Record<string, unknown> | undefined): void {
+  for (const fieldName of DECISION_INPUT_FIELDS) {
+    if (fields && Object.hasOwn(fields, fieldName)) {
+      throw new Error(
+        `${fieldName} is managed on decisions. Use link_decision_input to record decision inputs.`
+      );
+    }
+  }
+}
+
+function assertNoObsoleteExpectationFields(fields: Record<string, unknown> | undefined, toolName: string): void {
+  for (const obsoleteField of OBSOLETE_EXPECTATION_FIELDS) {
+    if (fields && Object.hasOwn(fields, obsoleteField)) {
+      throw new Error(
+        `${obsoleteField} is not part of the current Expectation model on ${toolName}. Use approvalState, approvedBy, or approvedAt where approval tracking is needed.`
+      );
+    }
+  }
+}