@company-semantics/contracts 51.0.0 → 51.2.0

package/src/execution/__tests__/registry.test.ts

@@ -4,6 +4,8 @@ import {
   getExecutionKindDefinition,
   isValidExecutionKind,
 } from "../registry.js";
+import type { ExecutionKind } from "../kinds.js";
+import { CONFIRMATION_LABELS } from "../../message-parts/confirmation.js";
 
 describe("EXECUTION_KINDS golden snapshot", () => {
   it("exact values are frozen", () => {
@@ -199,10 +201,97 @@ describe("EXECUTION_KINDS golden snapshot", () => {
           templateId: "companyMd.ingest",
         },
       },
+      "companyMd.commentPass": {
+        kind: "companyMd.commentPass",
+        domain: "data",
+        display: {
+          label: "Apply Comment Pass",
+          pastTenseLabel: "Comment pass applied",
+          icon: "pencil",
+        },
+        governance: {
+          visibility: "user",
+          requiresAdmin: false,
+        },
+        ui: {
+          showInAdmin: false,
+          showInTimeline: true,
+          confirmBeforeRun: true,
+        },
+        explanation: {
+          templateId: "companyMd.commentPass",
+        },
+      },
+      "semantic.transform": {
+        kind: "semantic.transform",
+        domain: "organization",
+        display: {
+          label: "Apply Reporting Transformation",
+          pastTenseLabel: "Reporting transformation applied",
+          icon: "pencil",
+        },
+        governance: {
+          visibility: "user",
+          requiresAdmin: false,
+        },
+        ui: {
+          showInAdmin: false,
+          showInTimeline: true,
+          confirmBeforeRun: false,
+        },
+        explanation: {
+          templateId: "semantic.transform",
+        },
+      },
+      "companyMd.importContextDoc": {
+        kind: "companyMd.importContextDoc",
+        domain: "data",
+        display: {
+          label: "Import Context Document",
+          pastTenseLabel: "Context document imported",
+          icon: "pencil",
+        },
+        governance: {
+          visibility: "user",
+          requiresAdmin: false,
+        },
+        ui: {
+          showInAdmin: false,
+          showInTimeline: true,
+          confirmBeforeRun: false,
+        },
+        explanation: {
+          templateId: "companyMd.importContextDoc",
+        },
+      },
     });
   });
 });
 
+describe("ExecutionKind exhaustiveness", () => {
+  // `satisfies Record<ExecutionKind, ...>` catches a MISSING key at compile
+  // time, but only a runtime set comparison catches an EXTRA one that no union
+  // member claims — a Record with a surplus key still satisfies the type.
+  it("the registry and the confirmation labels cover exactly the same kinds", () => {
+    expect(Object.keys(EXECUTION_KINDS).sort()).toStrictEqual(
+      Object.keys(CONFIRMATION_LABELS).sort(),
+    );
+  });
+
+  it("every kind the backend dispatches is a union member, not a call-site cast", () => {
+    // These three previously ran while cast to ExecutionKind at their call
+    // sites, which left the registry incomplete over what actually executes.
+    for (const kind of [
+      "companyMd.commentPass",
+      "semantic.transform",
+      "companyMd.importContextDoc",
+    ]) {
+      expect(isValidExecutionKind(kind)).toBe(true);
+      expect(CONFIRMATION_LABELS[kind as ExecutionKind]).toBeTruthy();
+    }
+  });
+});
+
 describe("registry structural invariants", () => {
   it("every registry key matches its definition.kind field", () => {
     for (const [key, def] of Object.entries(EXECUTION_KINDS)) {

package/src/execution/kinds.ts

@@ -18,9 +18,20 @@
  * - domain: integration, policy, data, system
  * - verb: action being performed (connect, disconnect, etc.)
  *
+ * This union is the authority over what may run: every kind that a backend
+ * executor dispatches MUST be a member here. A kind cast in at its call site
+ * is invisible to every reader of the registry — ExecutionSummaryService drops
+ * such executions from timelines, and the query enums cannot filter for them.
+ *
  * New kinds MUST be added to:
  * 1. This union type
  * 2. EXECUTION_KINDS registry in registry.ts
+ * 3. CONFIRMATION_LABELS in message-parts/confirmation.ts
+ *
+ * Both (2) and (3) are exhaustive Records over this union, so omitting either
+ * is a typecheck failure rather than a checklist item.
+ *
+ * @see decisions/ADR-CONTRACTS-128-execution-kind-union-is-exhaustive.md
  */
 export type ExecutionKind =
   | "integration.connect"
@@ -31,4 +42,13 @@ export type ExecutionKind =
   | "data.scope"
   | "system.cleanup"
   | "member.changeManager"
-  | "companyMd.ingest";
+  | "companyMd.ingest"
+  /** A reviewed comment pass over one company.md doc: validated range edits plus
+   *  thread dispositions, applied in one transaction after one confirmation. */
+  | "companyMd.commentPass"
+  /** Already RUNS today, previously cast at the call site. Applies a frozen
+   *  bundle of fact mutations to the org chart's reporting edges. */
+  | "semantic.transform"
+  /** Already RUNS today, previously cast at the call site. Creates a context
+   *  doc from submitted text and links it under a destination doc. */
+  | "companyMd.importContextDoc";

package/src/execution/registry.ts

@@ -225,6 +225,79 @@ export const EXECUTION_KINDS = {
       templateId: "companyMd.ingest",
     },
   },
+  "companyMd.commentPass": {
+    kind: "companyMd.commentPass",
+    domain: "data",
+    display: {
+      label: "Apply Comment Pass",
+      pastTenseLabel: "Comment pass applied",
+      icon: "pencil",
+    },
+    governance: {
+      visibility: "user",
+      requiresAdmin: false,
+    },
+    ui: {
+      showInAdmin: false,
+      showInTimeline: true,
+      // The pass mutates the document body; the reviewer confirms once and the
+      // whole bundle of range edits and dispositions lands in one transaction.
+      confirmBeforeRun: true,
+    },
+    explanation: {
+      templateId: "companyMd.commentPass",
+    },
+  },
+  "semantic.transform": {
+    kind: "semantic.transform",
+    domain: "organization",
+    display: {
+      label: "Apply Reporting Transformation",
+      pastTenseLabel: "Reporting transformation applied",
+      icon: "pencil",
+    },
+    governance: {
+      // Authority is decided in-operation by the reporting write seam, not by
+      // this flag — the same shape member.changeManager already has.
+      visibility: "user",
+      requiresAdmin: false,
+      // The frozen bundle is applied atomically; reversal is not a single-edge
+      // restore, so no kind reverses this one.
+    },
+    ui: {
+      showInAdmin: false,
+      showInTimeline: true,
+      // The confirmed preview IS the deliberate action — no second confirmation.
+      confirmBeforeRun: false,
+    },
+    explanation: {
+      templateId: "semantic.transform",
+    },
+  },
+  "companyMd.importContextDoc": {
+    kind: "companyMd.importContextDoc",
+    domain: "data",
+    display: {
+      label: "Import Context Document",
+      pastTenseLabel: "Context document imported",
+      icon: "pencil",
+    },
+    governance: {
+      visibility: "user",
+      requiresAdmin: false,
+      // Reversal is an executor undo window over the created doc, not a
+      // separately governed ExecutionKind, so reversibleBy stays unset.
+    },
+    ui: {
+      showInAdmin: false,
+      showInTimeline: true,
+      // The filled interactive-task form IS the deliberate action.
+      confirmBeforeRun: false,
+    },
+    explanation: {
+      templateId: "companyMd.importContextDoc",
+    },
+  },
 } as const satisfies Record<ExecutionKind, ExecutionKindDefinition>;
 
 // =============================================================================

package/src/generated/openapi-routes.ts

@@ -26,6 +26,7 @@ export const openApiRoutes = {
   '/api/comments/threads/{threadId}/accept-complete': ['POST'],
   '/api/comments/threads/{threadId}/accept-intent': ['POST'],
   '/api/comments/threads/{threadId}/accept-release': ['POST'],
+  '/api/comments/threads/{threadId}/anchor-trace': ['POST'],
   '/api/comments/threads/{threadId}/comments': ['POST'],
   '/api/comments/threads/{threadId}/reject': ['POST'],
   '/api/comments/threads/{threadId}/reopen': ['POST'],

package/src/index.ts

@@ -329,16 +329,89 @@ export type {
 // contracts drift on it has NO server-side tripwire and mis-places comments
 // silently. Response vocabulary only — request bodies stay backend-side.
 // See src/comments/README.md.
+//
+// The anchor SIZE BOUNDS are published alongside the shape, because the client
+// that composes an anchor and the schema that accepts it are the two halves of
+// that same driftable agreement: a constructor capturing more context than the
+// boundary accepts loses a comment after it was written. Note ANCHOR_CONTEXT_CHARS
+// (capture) and ANCHOR_AFFIX_MAX_CHARS (accept) differ ON PURPOSE.
 // @see ADR-CONTRACTS-116, ADR-CONT-029
 export {
+  ANCHOR_AFFIX_MAX_CHARS,
+  ANCHOR_CONTEXT_CHARS,
   COMMENT_ANCHOR_TYPES,
   COMMENT_SUBJECT_TYPES,
   COMMENT_THREAD_KINDS,
   COMMENT_THREAD_STATUSES,
+  QUOTE_MAX_CHARS,
+  RELATIVE_POSITION_MAX_CHARS,
   SUGGESTION_OPS,
   SUGGESTION_STATUSES,
 } from "./comments/index";
 
+// The anchor's INTERPRETATION, published beside its shape (ADR-CONTRACTS-127).
+// The schema said what an anchor looks like; these say what it MEANS. Both
+// halves have to be published for the same reason: the writing client and the
+// resolving client agree with no server-side arbiter between them, so a second
+// description of "where does this anchor land" mis-places comments with nothing
+// anywhere throwing. `resolveAnchorFromText` is total, pure and text-only — the
+// Yjs relative-position rung stays in consumers, which compose it on top.
+export {
+  contextAfter,
+  contextBefore,
+  contextsMatchAt,
+  findSoleOccurrence,
+  resolveAnchorFromText,
+} from "./comments/index";
+
+export type { AnchorResolution, Occurrence } from "./comments/index";
+
+// The two questions asked BEFORE the body is written (ADR-CONTRACTS-127).
+// `anchorStillReads` is a SECOND assertion, independent of the ladder — the
+// applier must not trust the finder — and `plannedEdit` derives the mutation
+// from the canonical payload rather than a caller's restatement of it. Both are
+// total functions of their arguments, which is exactly what makes them liftable
+// out of a browser applier: no Y.Text, no clock, no lease.
+export { anchorStillReads, plannedEdit } from "./comments/index";
+
+export type { PlannedEdit } from "./comments/index";
+
+// The CONSTRUCTION half of the same contract (ADR-CONTRACTS-127). Publishing
+// anchor → text while leaving text → anchor browser-only would be half an
+// extraction: the side that COMPOSES an anchor decides how much context to
+// capture and what counts as a quote, and a second description of that is the
+// same silent-drift hazard the resolver was published to end. Both constructors
+// validate through `CommentAnchorSchema` before returning and refuse — `null` —
+// rather than truncate, because an anchor the route boundary rejects is a
+// comment lost after it was composed. The relative-position pair is NOT
+// produced here; a consumer holding a `Y.Text` merges it onto the result.
+export {
+  createTextAnchorFromRange,
+  createTextInsertionAnchorAt,
+} from "./comments/index";
+
+export type { TextRange } from "./comments/index";
+
+// The application receipt — the durable proof that an accepted suggestion's
+// edit ALREADY LANDED IN THE BODY (ADR-CONTRACTS-127). It travels in the same
+// CRDT transaction as the edit, so either both survived or neither did, which
+// is what closes the window between the write and the acknowledgement. The MAP
+// KEY is the load-bearing part: a receipt written under any other name lands in
+// a map nobody reads while the reader watches a map nobody writes, and nothing
+// anywhere throws — the same no-arbiter hazard as the anchor, now that a second
+// implementation is about to write receipts too. Published with a PARSER,
+// because these values arrive from a peer through a CRDT that has no schema of
+// its own: a row that is not three well-typed fields is dropped, never
+// surfaced. The receipt lives BESIDE the body and must never reach the markdown
+// source, an export, or the content hash.
+export {
+  SUGGESTION_RECEIPTS_MAP,
+  SuggestionReceiptSchema,
+  readSuggestionReceipt,
+} from "./comments/index";
+
+export type { SuggestionReceipt } from "./comments/index";
+
 export {
   CommentAnchorSchema,
   CommentAnchorTypeSchema,

package/src/message-parts/__tests__/confirmation.test.ts

@@ -121,6 +121,9 @@ describe("CONFIRMATION_LABELS", () => {
       "system.cleanup": "Cleanup Connections",
       "member.changeManager": "Change Reporting Manager",
       "companyMd.ingest": "Ingest Company Knowledge",
+      "companyMd.commentPass": "Apply Comment Pass",
+      "semantic.transform": "Apply Reporting Transformation",
+      "companyMd.importContextDoc": "Import Context Document",
     });
   });
 });

package/src/message-parts/confirmation.ts

@@ -46,6 +46,9 @@ export const CONFIRMATION_LABELS: Record<ExecutionKind, string> = {
   "system.cleanup": "Cleanup Connections",
   "member.changeManager": "Change Reporting Manager",
   "companyMd.ingest": "Ingest Company Knowledge",
+  "companyMd.commentPass": "Apply Comment Pass",
+  "semantic.transform": "Apply Reporting Transformation",
+  "companyMd.importContextDoc": "Import Context Document",
 };
 
 /**