@company-semantics/contracts 51.1.0 → 51.2.0

package/src/comments/resolve.ts

@@ -0,0 +1,261 @@
+/**
+ * Walking the ladder — the READ half of the contract the anchor writes
+ * (ADR-CONTRACTS-116, ADR-CONTRACTS-127).
+ *
+ * WHY THE INTERPRETATION IS PUBLISHED AND NOT ONLY THE SHAPE. The backend
+ * validates an anchor's shape once, at the route boundary, then stores opaque
+ * jsonb it never interprets. So the client that WROTE the anchor and the client
+ * that later RESOLVES it must agree about what these fields MEAN with no
+ * server-side arbiter between them — and a disagreement produces no error at
+ * all. The write succeeds, the read succeeds, and the highlight lands on the
+ * wrong sentence. Publishing the schema bounded that risk; publishing the
+ * resolver closes it, because a second implementation can now be an IMPORT
+ * rather than a second description.
+ *
+ * EACH RUNG EITHER ANSWERS OR DECLINES, AND A RUNG THAT CANNOT VOUCH FOR ITS
+ * ANSWER MUST DECLINE. The whole design turns on refusing rather than guessing,
+ * because the wrong answer looks exactly like the right one. Under-anchoring is
+ * the deliberate error direction: a comment shown as unanchored is legible and
+ * recoverable, while a comment shown against the wrong sentence reads as a
+ * considered objection to a paragraph its author never saw.
+ *
+ * NO YJS HERE, DELIBERATELY. Everything below is a pure function of strings and
+ * indices. Rung 1 — decoding a `Y.RelativePosition` — needs `yjs`, which the
+ * vocabulary-guard forbids this package from importing, and it is the ONE rung
+ * that needs a live replica anyway. A consumer that holds a `Y.Text` composes
+ * it on top: it tries its own rung 1 and falls through to
+ * {@link resolveAnchorFromText}, which is total and never throws. That is also
+ * what lets a comment resolve on a card with no session, no stream and no CRDT
+ * replica — and what lets the server resolve one at all.
+ *
+ * All arithmetic is in UTF-16 code units (plain JavaScript string coordinates),
+ * like every other offset on the comment path. No Unicode normalization happens
+ * anywhere here: normalising before measuring changes the length and
+ * desynchronises every offset after the first composed character.
+ */
+import { ANCHOR_CONTEXT_CHARS } from "./anchor-constants";
+import type { CommentAnchor } from "./anchor";
+
+/**
+ * Where an anchor landed.
+ *
+ * `document` is not a degraded `resolved` and `orphaned` is not an error — they
+ * are three distinct outcomes, and collapsing any pair of them loses the
+ * distinction the comment rail draws on.
+ *
+ * `rung` stays `1 | 2` even though this module can only ever emit `2`: the
+ * consumer that composes the Yjs rung on top returns `rung: 1` into this same
+ * type, and narrowing it here would force that consumer to declare a second,
+ * divergent result type — which is the two-independent-descriptions problem
+ * this domain exists to prevent.
+ */
+export type AnchorResolution =
+  | { status: "resolved"; start: number; end: number; rung: 1 | 2 }
+  | { status: "document" }
+  | { status: "orphaned" };
+
+/** Whether a needle occurs in a haystack exactly once, and where. */
+export type Occurrence =
+  | { kind: "absent" }
+  | { kind: "unique"; index: number }
+  | { kind: "ambiguous" };
+
+/**
+ * Whether `text` still reads `leftContext` immediately before `point` and
+ * `rightContext` immediately after it.
+ *
+ * The two length guards are the whole reason this is a function rather than two
+ * inline slices: `slice` reads a negative start from the END of the string and
+ * clamps a long end, so a context that CANNOT fit around `point` would be
+ * compared against an unrelated substring instead of failing. NOT FITTING IS A
+ * MISMATCH.
+ *
+ * EXPORTED because the acceptance path re-asks this question as a second,
+ * independent assertion before it writes the body (see `./verify`). A private
+ * copy there would be two descriptions of "are the contexts still there" — and
+ * the copy that forgot a length guard would compare against an unrelated
+ * substring and answer `true`, which is the one wrong answer that mutates the
+ * document.
+ */
+export function contextsMatchAt(
+  text: string,
+  point: number,
+  leftContext: string,
+  rightContext: string,
+): boolean {
+  if (point < 0 || point > text.length) return false;
+  if (point < leftContext.length) return false;
+  if (point + rightContext.length > text.length) return false;
+  return (
+    text.slice(point - leftContext.length, point) === leftContext &&
+    text.slice(point, point + rightContext.length) === rightContext
+  );
+}
+
+/**
+ * Whether `needle` occurs in `haystack` exactly once, and where.
+ *
+ * Overlapping occurrences COUNT — the second search resumes at `first + 1`, not
+ * at `first + needle.length`. A quote that overlaps itself (`"aa"` in `"aaa"`)
+ * is no less ambiguous for the overlap, and the conservative count is the one
+ * that errs toward orphaning.
+ *
+ * An EMPTY needle is `ambiguous`, never `unique`: it matches at every position,
+ * which is a fact about the search and not evidence about the point.
+ */
+export function findSoleOccurrence(
+  haystack: string,
+  needle: string,
+): Occurrence {
+  if (needle.length === 0) return { kind: "ambiguous" };
+  const first = haystack.indexOf(needle);
+  if (first === -1) return { kind: "absent" };
+  if (haystack.indexOf(needle, first + 1) !== -1) return { kind: "ambiguous" };
+  return { kind: "unique", index: first };
+}
+
+const HIGH_SURROGATE_MIN = 0xd800;
+const HIGH_SURROGATE_MAX = 0xdbff;
+const LOW_SURROGATE_MIN = 0xdc00;
+const LOW_SURROGATE_MAX = 0xdfff;
+
+/**
+ * The context preceding `index`, never opening on half a character.
+ *
+ * A fixed-width slice can land between a surrogate pair, and the lone surrogate
+ * that results is ill-formed once the anchor is encoded for the wire. Trimming
+ * costs one code unit of context and changes nothing about matching — the
+ * document contains the same code units either way.
+ *
+ * Slices {@link ANCHOR_CONTEXT_CHARS}, the CAPTURE width, which is deliberately
+ * narrower than what the schema ACCEPTS. This is a constructor helper: nothing
+ * in the ladder below calls it, and it is published here so the construction
+ * half (`./create`) and the resolution half agree about the same string work.
+ */
+export function contextBefore(text: string, index: number): string {
+  let from = Math.max(0, index - ANCHOR_CONTEXT_CHARS);
+  const code = text.charCodeAt(from);
+  if (from > 0 && code >= LOW_SURROGATE_MIN && code <= LOW_SURROGATE_MAX) {
+    from += 1;
+  }
+  return text.slice(from, index);
+}
+
+/** The context following `index`, never closing on half a character. */
+export function contextAfter(text: string, index: number): string {
+  let to = Math.min(text.length, index + ANCHOR_CONTEXT_CHARS);
+  if (to > index && to < text.length) {
+    const code = text.charCodeAt(to - 1);
+    if (code >= HIGH_SURROGATE_MIN && code <= HIGH_SURROGATE_MAX) to -= 1;
+  }
+  return text.slice(index, to);
+}
+
+/**
+ * Rung 2 for the text anchor — the context-qualified search, then the bare
+ * quote. Both refuse ambiguity; neither ever settles for a first match.
+ */
+function resolveByQuote(
+  anchor: Extract<CommentAnchor, { type: "text" }>,
+  text: string,
+): AnchorResolution {
+  const context = anchor.prefix + anchor.quote + anchor.suffix;
+  if (context !== anchor.quote) {
+    const qualified = findSoleOccurrence(text, context);
+    // Two context-qualified matches mean the context FAILED to identify a
+    // candidate. Binding to the first would be the guess this ladder exists to
+    // forbid, and falling back to the bare quote here would only re-ask a
+    // question already known to be ambiguous.
+    if (qualified.kind === "ambiguous") return { status: "orphaned" };
+    if (qualified.kind === "unique") {
+      const start = qualified.index + anchor.prefix.length;
+      return {
+        status: "resolved",
+        start,
+        end: start + anchor.quote.length,
+        rung: 2,
+      };
+    }
+    // Absent: the surrounding sentence was edited but the quote itself may have
+    // survived. Fall through.
+  }
+
+  const bare = findSoleOccurrence(text, anchor.quote);
+  if (bare.kind !== "unique") return { status: "orphaned" };
+  return {
+    status: "resolved",
+    start: bare.index,
+    end: bare.index + anchor.quote.length,
+    rung: 2,
+  };
+}
+
+/**
+ * Rung 2 for the zero-width variant — find the seam the two contexts spell out
+ * when the caret between them is closed up, and resolve ONLY if it is unique.
+ *
+ * A repeated seam is the insertion anchor's version of a repeated quote, and it
+ * gets the same answer: `orphaned`. "Insert at the first `item done`" is the
+ * shortcut this rung exists to forbid — in a list of identical rows it is wrong
+ * two times out of three, and it never looks wrong.
+ */
+function resolveInsertionBySeam(
+  anchor: Extract<CommentAnchor, { type: "text-insertion" }>,
+  text: string,
+): AnchorResolution {
+  const { leftContext, rightContext } = anchor;
+  const seam = leftContext + rightContext;
+
+  if (seam === "") {
+    // Only authorable on an EMPTY document, where 0 is the one point there is.
+    // Once the document has text that anchor says nothing about WHERE among it
+    // the caret belongs — and an empty needle matches everywhere, which is a
+    // fact about the search and not evidence about the point.
+    //
+    // Not redundant with `findSoleOccurrence`'s empty-needle refusal below:
+    // this branch is reached first, and it is the one that makes "the only
+    // point an empty document has" resolvable at all.
+    return text.length === 0
+      ? { status: "resolved", start: 0, end: 0, rung: 2 }
+      : { status: "orphaned" };
+  }
+
+  const seen = findSoleOccurrence(text, seam);
+  if (seen.kind !== "unique") return { status: "orphaned" };
+  const point = seen.index + leftContext.length;
+  return { status: "resolved", start: point, end: point, rung: 2 };
+}
+
+/**
+ * Resolve `anchor` against the current `text`, using nothing but the text.
+ *
+ * TOTAL AND NEVER THROWS: every input produces one of the three outcomes, which
+ * is what lets a consumer use it as the floor of its own ladder without a
+ * try/catch or a null check.
+ *
+ * `text` is the coordinate space the caller will paint into — the live
+ * `Y.Text`'s contents where a session is attached, the materialized document
+ * body where it is not. A consumer that holds a `Y.Text` tries its own
+ * relative-position rung FIRST and calls this when that rung declines; the
+ * geometry both paths produce must be identical, or two people looking at the
+ * same document disagree about where a comment sits.
+ *
+ * The three outcomes, by variant:
+ *   - `document` — the thread hangs off the subject AS A WHOLE. It draws no
+ *     highlight, but it is correctly anchored; reporting it as `orphaned` would
+ *     put it behind the rail's "this text is gone" affordance.
+ *   - `text` — {@link resolveByQuote}: the context-qualified string first, the
+ *     bare quote as the fallback, ambiguity orphaned at BOTH levels.
+ *   - `text-insertion` — {@link resolveInsertionBySeam}: the unique
+ *     `leftContext`+`rightContext` seam, and nothing else. Always zero-width.
+ */
+export function resolveAnchorFromText(
+  anchor: CommentAnchor,
+  text: string,
+): AnchorResolution {
+  if (anchor.type === "document") return { status: "document" };
+  if (anchor.type === "text-insertion") {
+    return resolveInsertionBySeam(anchor, text);
+  }
+  return resolveByQuote(anchor, text);
+}

package/src/comments/verify.ts

@@ -0,0 +1,128 @@
+/**
+ * The two questions asked BEFORE the body is written — is the passage still
+ * what the anchor says it is, and what edit does this op make of that range?
+ * (ADR-CONTRACTS-122, ADR-CONTRACTS-127.)
+ *
+ * WHY THESE ARE PUBLISHED AT ALL. Both are total functions of their arguments —
+ * no `Y.Text`, no clock, no lease, nothing touching a sanctioned-mutation
+ * window. The app's own applier records that as the property that makes them
+ * "the only part of the applier that can be lifted out of it": the depth
+ * counter and the lease have to stay in one module, because an exported pair
+ * that opened and closed that window would be a generic bypass. What is left
+ * once they are removed is exactly this file — and once it is an import rather
+ * than a second description, a NON-BROWSER applier (the server, a comment pass)
+ * becomes possible without a second answer to "did this suggestion still apply".
+ *
+ * THE APPLIER MUST NOT TRUST THE FINDER. {@link anchorStillReads} is a SECOND
+ * assertion, independent of {@link resolveAnchorFromText} by construction: it
+ * reads the anchor's own stored evidence against the live text and takes the
+ * resolution only as a position. That a rung already checked something like it
+ * does not make it redundant — the rung answers "where does this land", this
+ * answers "is what lands there still the thing", and a consumer that composes
+ * its own Yjs rung on top supplies a position this module never saw.
+ *
+ * All arithmetic is in UTF-16 code units, like every other offset on the
+ * comment path, and no Unicode normalization happens here.
+ */
+import type { CommentAnchor } from "./anchor";
+import { contextsMatchAt, type AnchorResolution } from "./resolve";
+import type { Suggestion } from "./suggestion";
+
+/**
+ * A resolution that actually named a range.
+ *
+ * Narrowed from {@link AnchorResolution} rather than restated, so a consumer
+ * composing the Yjs rung on top hands its own `rung: 1` answer straight in.
+ */
+type Resolved = Extract<AnchorResolution, { status: "resolved" }>;
+
+/** One text mutation: delete `deleteLength` at `at`, then insert `insert`. */
+export interface PlannedEdit {
+  readonly at: number;
+  readonly deleteLength: number;
+  readonly insert: string;
+}
+
+/**
+ * Does the resolved place still hold what the anchor says it holds?
+ *
+ * By variant:
+ *   - `text` — the live slice must still be the stored `quote`, exactly. Not a
+ *     prefix of it, not a normalized form of it.
+ *   - `text-insertion` — the resolution must still be ZERO-WIDTH, and both
+ *     contexts must still meet at that point ({@link contextsMatchAt}, imported
+ *     rather than re-derived: a private copy that forgot a length guard would
+ *     compare against an unrelated substring and answer `true`, which is the
+ *     one wrong answer that mutates the document).
+ *   - `document` — `false`. A whole-document anchor makes no claim about a
+ *     range, so it can never vouch for one. Unreachable through the shipped
+ *     ladder, which answers `{ status: "document" }` for that variant and never
+ *     a `resolved` — but a consumer's own rung can hand one in, and the refusal
+ *     is what makes that harmless.
+ */
+export function anchorStillReads(
+  anchor: CommentAnchor,
+  text: string,
+  resolution: Resolved,
+): boolean {
+  if (anchor.type === "text") {
+    return text.slice(resolution.start, resolution.end) === anchor.quote;
+  }
+  if (anchor.type === "text-insertion") {
+    return (
+      resolution.start === resolution.end &&
+      contextsMatchAt(
+        text,
+        resolution.start,
+        anchor.leftContext,
+        anchor.rightContext,
+      )
+    );
+  }
+  return false;
+}
+
+/**
+ * What this op does to that range — or `null` when it would do nothing.
+ *
+ * Derived from the CANONICAL suggestion payload, never from a caller's
+ * restatement of it: that seam is where "accept this suggestion" would quietly
+ * become "apply something like it".
+ *
+ * A NO-OP IS A REFUSAL, NOT A CHEAP SUCCESS. An `insert` carrying no text, or a
+ * `delete` over a collapsed range, would run a transaction that writes a
+ * receipt and changes not one character — the thread would go to `accepted`
+ * over a document that never received the proposal, which is the invariant pair
+ * read backwards. Both shapes mean the payload and the anchor disagree about
+ * what kind of edit this is, and that disagreement is not this module's to
+ * settle.
+ *
+ * `insert` lands at `end`, matching where the redline draws the proposed text,
+ * so the diff the user accepted and the edit they get agree about the seam.
+ *
+ * The switch is exhaustive over {@link Suggestion}'s `op` with NO default arm:
+ * a fourth op must arrive as a type error here rather than be absorbed as a
+ * silent `undefined` return.
+ */
+export function plannedEdit(
+  suggestion: Suggestion,
+  resolution: Resolved,
+): PlannedEdit | null {
+  const insert = suggestion.insertedText ?? "";
+  const span = resolution.end - resolution.start;
+
+  switch (suggestion.op) {
+    case "insert":
+      return insert === ""
+        ? null
+        : { at: resolution.end, deleteLength: 0, insert };
+    case "delete":
+      return span === 0
+        ? null
+        : { at: resolution.start, deleteLength: span, insert: "" };
+    case "replace":
+      return span === 0 || insert === ""
+        ? null
+        : { at: resolution.start, deleteLength: span, insert };
+  }
+}

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>;
 
 // =============================================================================