@company-semantics/contracts 51.1.0 → 51.2.0

package/src/comments/anchor-constants.ts

@@ -0,0 +1,61 @@
+/**
+ * The anchor size bounds, published once.
+ *
+ * CAPTURE AND ACCEPT ARE DIFFERENT NUMBERS AND MUST STAY THAT WAY. A
+ * constructor captures ANCHOR_CONTEXT_CHARS of surrounding text; the schema
+ * ACCEPTS up to ANCHOR_AFFIX_MAX_CHARS, because an anchor written by an older
+ * client (or a future one with a wider capture) must still parse. Collapsing
+ * them would silently reject valid stored anchors.
+ *
+ * These are the SAME numbers `CommentAnchorSchema` reads — that schema carries
+ * no inline size literal, so a bound can no longer be changed in one of the two
+ * places. They are published rather than kept file-local because the writing
+ * client and the resolving client are independent implementations with no
+ * server-side arbiter between them (ADR-CONTRACTS-116): a constructor that
+ * captures more than the schema accepts composes an anchor the route boundary
+ * then refuses, losing a comment after it was written.
+ *
+ * Measured in UTF-16 code units (plain JavaScript `String#length`), like every
+ * other offset on the comment path. No Unicode normalization happens anywhere
+ * here, so a two-unit emoji costs two.
+ */
+
+/**
+ * How much surrounding text a CONSTRUCTOR captures either side of a range —
+ * `prefix`/`suffix` on a text anchor, `leftContext`/`rightContext` on a
+ * text-insertion point.
+ *
+ * Deliberately SMALLER than {@link ANCHOR_AFFIX_MAX_CHARS}, and the gap is the
+ * point: this is a write-side choice that may change, while the accept bound is
+ * a promise made to every anchor already in storage.
+ */
+export const ANCHOR_CONTEXT_CHARS = 32;
+
+/**
+ * The largest affix `CommentAnchorSchema` will ACCEPT — `prefix`, `suffix`,
+ * `leftContext` and `rightContext` alike.
+ *
+ * Not redundant with {@link ANCHOR_CONTEXT_CHARS}: narrowing this to the
+ * capture width would refuse anchors written by a client that captured more,
+ * and those anchors are already durable jsonb the server never re-validates.
+ */
+export const ANCHOR_AFFIX_MAX_CHARS = 64;
+
+/**
+ * The largest `quote` a text anchor may carry.
+ *
+ * The quote is the durable fallback the passage is re-found by, so it is bounded
+ * generously — but bounded, because an anchor must never become a second copy of
+ * the document in a column nothing on the server reads.
+ */
+export const QUOTE_MAX_CHARS = 2000;
+
+/**
+ * Cap on ONE encoded `Y.RelativePosition` payload, in base64 chars — `relStart`,
+ * `relEnd` and `relPos` alike.
+ *
+ * The backend never decodes these; the bound and the base64 charset are the only
+ * things anyone checks, which is why both have to be checked at the boundary or
+ * a client can write a position no other client can decode.
+ */
+export const RELATIVE_POSITION_MAX_CHARS = 512;

package/src/comments/anchor.ts

@@ -19,7 +19,9 @@
  * Zod-canonical: the schema is the source of truth, the type is inferred.
  *
  * MIRRORED, NOT INVENTED. Every bound below is the backend route boundary's
- * (`src/api/http/routes/comments/comments.schemas.ts`), and the accept/reject
+ * (`src/api/http/routes/comments/comments.schemas.ts`) — they are named in
+ * `./anchor-constants` and read from there, so this file carries no size
+ * literal a constructor could drift away from. The accept/reject
  * corpus at `./__tests__/fixtures/comment-anchors.json` is copied byte-for-byte
  * from that suite's fixtures. Editing that copy HERE fails the anchor suite —
  * its digest is pinned beside it. A change made at the BOUNDARY is not caught
@@ -29,6 +31,12 @@
  */
 import { z } from "zod";
 
+import {
+  ANCHOR_AFFIX_MAX_CHARS,
+  QUOTE_MAX_CHARS,
+  RELATIVE_POSITION_MAX_CHARS,
+} from "./anchor-constants";
+
 /**
  * A base64 `Y.RelativePosition` payload, encoded by the client.
  *
@@ -40,7 +48,7 @@ import { z } from "zod";
 const RelativePositionSchema = z
   .string()
   .min(1)
-  .max(512)
+  .max(RELATIVE_POSITION_MAX_CHARS)
   .regex(/^[A-Za-z0-9+/]+={0,2}$/, "must be base64");
 
 /**
@@ -90,9 +98,9 @@ const TextAnchorSchema = z.strictObject({
   v: z.literal(1),
   relStart: RelativePositionSchema.optional(),
   relEnd: RelativePositionSchema.optional(),
-  quote: z.string().min(1).max(2000),
-  prefix: z.string().max(64),
-  suffix: z.string().max(64),
+  quote: z.string().min(1).max(QUOTE_MAX_CHARS),
+  prefix: z.string().max(ANCHOR_AFFIX_MAX_CHARS),
+  suffix: z.string().max(ANCHOR_AFFIX_MAX_CHARS),
 });
 
 /**
@@ -110,10 +118,11 @@ const TextAnchorSchema = z.strictObject({
  *
  * `leftContext`/`rightContext` are the durable fallback — the text
  * immediately before and after the point. They are required-but-may-be-empty
- * (max 64 UTF-16 code units each, like `prefix`/`suffix`): either may be
- * empty or short at a document edge, and an empty string means "there is
- * nothing on that side", which must stay distinguishable from "this client
- * forgot to send it". No Unicode normalization happens anywhere on this path.
+ * (max {@link ANCHOR_AFFIX_MAX_CHARS} UTF-16 code units each, like
+ * `prefix`/`suffix`): either may be empty or short at a document edge, and an
+ * empty string means "there is nothing on that side", which must stay
+ * distinguishable from "this client forgot to send it". No Unicode
+ * normalization happens anywhere on this path.
  *
  * RESOLUTION SEMANTICS (implemented client-side in the app; the backend is a
  * passthrough that interprets nothing):
@@ -144,8 +153,8 @@ const TextInsertionAnchorSchema = z.strictObject({
   type: z.literal("text-insertion"),
   v: z.literal(1),
   relPos: RelativePositionSchema.optional(),
-  leftContext: z.string().max(64),
-  rightContext: z.string().max(64),
+  leftContext: z.string().max(ANCHOR_AFFIX_MAX_CHARS),
+  rightContext: z.string().max(ANCHOR_AFFIX_MAX_CHARS),
 });
 
 /**

package/src/comments/create.ts

@@ -0,0 +1,128 @@
+/**
+ * Composing the anchor — the WRITE half of the contract `./resolve` reads
+ * (ADR-CONTRACTS-116, ADR-CONTRACTS-127).
+ *
+ * WHY BOTH DIRECTIONS ARE PUBLISHED, NOT JUST ONE. Publishing anchor → text
+ * while leaving text → anchor browser-only would be half an extraction: the
+ * side that COMPOSES an anchor is the side that 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. A constructor
+ * that captured more context than {@link CommentAnchorSchema} accepts composes
+ * an anchor the route boundary then refuses — a comment lost after it was
+ * written — and one that captured a DIFFERENT amount composes an anchor that
+ * parses and then resolves somewhere else.
+ *
+ * REFUSE RATHER THAN GUESS, in the same direction as the ladder. Range → anchor
+ * is a write capability and inherits the ladder's discipline exactly: every
+ * degenerate input returns `null` rather than a plausible anchor. Truncating an
+ * over-long quote is the sharpest case — the resulting anchor is well-formed,
+ * parses, resolves, and highlights a range the caller never selected. `null`
+ * means "compose no comment", which the caller can report; a truncated quote
+ * means "compose a comment about something else", which nobody can.
+ *
+ * VALIDATED BEFORE IT IS RETURNED. Both constructors run the object they built
+ * through the PUBLISHED schema rather than asserting the shape, so the only
+ * anchors this module can emit are anchors the route boundary will accept. The
+ * bounds come from `./anchor-constants` for the same reason: a literal here
+ * would be a fifth copy of a number whose whole point is having one.
+ *
+ * NO YJS HERE, DELIBERATELY — the same seam `./resolve` holds. `relStart`,
+ * `relEnd` and `relPos` are NOT produced: encoding a `Y.RelativePosition` needs
+ * `yjs`, which the vocabulary-guard forbids this package from importing, and it
+ * needs a live replica besides. A consumer that holds a `Y.Text` merges the
+ * encoded pair onto the anchor returned here; the anchor is useful without it,
+ * because the quote and the contexts are the durable fallback anyway.
+ *
+ * All arithmetic is in UTF-16 code units (plain JavaScript string coordinates),
+ * like every other offset on the comment path, and no Unicode normalization
+ * happens anywhere here.
+ *
+ * SPELLING DEVIATION FROM THE AUTHORITATIVE REFERENCE (PRD-00941, must_log).
+ * Nothing semantic. The reference writes
+ * `export function createTextAnchorFromRange(range: TextRange): CommentAnchor | null {`
+ * on one line, which is 82 columns against this repo's `printWidth: 80`, so
+ * `pnpm format:check` reflows the signature onto three lines. Same precedent as
+ * the notes in `./anchor.ts`: a different spelling of the same function, and
+ * nothing about what is accepted or refused changed.
+ */
+import { CommentAnchorSchema, type CommentAnchor } from "./anchor";
+import { QUOTE_MAX_CHARS } from "./anchor-constants";
+import { contextAfter, contextBefore } from "./resolve";
+
+/**
+ * A selected range, in the coordinate space of the text it was selected in.
+ *
+ * `text` travels WITH the offsets rather than being passed separately, because
+ * a start/end pair means nothing without the string it indexes — and a caller
+ * holding the pair from one revision and the string from another is the bug
+ * this shape makes hard to write.
+ */
+export interface TextRange {
+  readonly text: string;
+  readonly start: number;
+  readonly end: number;
+}
+
+/**
+ * range → anchor, headlessly. The mirror of `resolveAnchorFromText`, and a
+ * WRITE capability, so it refuses rather than guesses on every degenerate
+ * input.
+ *
+ * Returns `null` for: a non-integer offset, an out-of-order or EMPTY range
+ * (`end <= start` — the zero-width case has its own constructor below, and
+ * silently promoting one here would produce a text anchor whose quote is the
+ * empty string), a range reaching past the end of `text`, or a quote longer
+ * than {@link QUOTE_MAX_CHARS}.
+ *
+ * The relative-position pair is NOT produced here: it needs `yjs`, which this
+ * package may not import. A consumer holding a `Y.Text` merges it onto the
+ * result.
+ */
+export function createTextAnchorFromRange(
+  range: TextRange,
+): CommentAnchor | null {
+  const { text, start, end } = range;
+  if (!Number.isInteger(start) || !Number.isInteger(end)) return null;
+  if (start < 0 || end <= start || end > text.length) return null;
+
+  const quote = text.slice(start, end);
+  // Refusing beats truncating: a truncated quote anchors a range nobody chose.
+  if (quote.length === 0 || quote.length > QUOTE_MAX_CHARS) return null;
+
+  const parsed = CommentAnchorSchema.safeParse({
+    type: "text",
+    v: 1,
+    quote,
+    prefix: contextBefore(text, start),
+    suffix: contextAfter(text, end),
+  });
+  return parsed.success ? parsed.data : null;
+}
+
+/**
+ * The zero-width variant: a point BETWEEN two characters.
+ *
+ * Refuses two empty contexts on a non-empty document — that anchor identifies
+ * nothing, and `resolveInsertionBySeam` would (correctly) orphan it, so
+ * composing it at all would only defer the loss until after the suggestion was
+ * written. On an EMPTY document both contexts are empty and that is the one
+ * point there is, so it is allowed.
+ */
+export function createTextInsertionAnchorAt(
+  text: string,
+  point: number,
+): CommentAnchor | null {
+  if (!Number.isInteger(point) || point < 0 || point > text.length) return null;
+  const leftContext = contextBefore(text, point);
+  const rightContext = contextAfter(text, point);
+  // Two empty contexts identify nothing on a non-empty document.
+  if (leftContext === "" && rightContext === "" && text.length > 0) return null;
+
+  const parsed = CommentAnchorSchema.safeParse({
+    type: "text-insertion",
+    v: 1,
+    leftContext,
+    rightContext,
+  });
+  return parsed.success ? parsed.data : null;
+}

package/src/comments/index.ts

@@ -8,6 +8,13 @@
  * bodies, per ADR-CONT-029).
  */
 
+export {
+  ANCHOR_AFFIX_MAX_CHARS,
+  ANCHOR_CONTEXT_CHARS,
+  QUOTE_MAX_CHARS,
+  RELATIVE_POSITION_MAX_CHARS,
+} from "./anchor-constants";
+
 export {
   COMMENT_ANCHOR_TYPES,
   CommentAnchorTypeSchema,
@@ -16,6 +23,16 @@ export {
 
 export type { CommentAnchor, CommentAnchorType } from "./anchor";
 
+export {
+  contextAfter,
+  contextBefore,
+  contextsMatchAt,
+  findSoleOccurrence,
+  resolveAnchorFromText,
+} from "./resolve";
+
+export type { AnchorResolution, Occurrence } from "./resolve";
+
 export {
   COMMENT_SUBJECT_TYPES,
   COMMENT_THREAD_STATUSES,
@@ -55,3 +72,22 @@ export type {
   SuggestionOp,
   SuggestionStatus,
 } from "./suggestion";
+
+export { anchorStillReads, plannedEdit } from "./verify";
+
+export type { PlannedEdit } from "./verify";
+
+export {
+  createTextAnchorFromRange,
+  createTextInsertionAnchorAt,
+} from "./create";
+
+export type { TextRange } from "./create";
+
+export {
+  SUGGESTION_RECEIPTS_MAP,
+  SuggestionReceiptSchema,
+  readSuggestionReceipt,
+} from "./receipt";
+
+export type { SuggestionReceipt } from "./receipt";

package/src/comments/receipt.ts

@@ -0,0 +1,146 @@
+/**
+ * The application receipt — the durable proof that an accepted suggestion's
+ * edit ALREADY LANDED IN THE BODY (ADR-CONTRACTS-116, ADR-CONTRACTS-122,
+ * ADR-CONTRACTS-127).
+ *
+ * WHY THERE IS A RECEIPT AT ALL. Acceptance is apply-then-record: the edit is
+ * written into the CRDT first and the server is told afterwards, which is what
+ * makes `accepted` mean `applied` — and which opens exactly one window, between
+ * the transaction and the acknowledgement, in which the document has already
+ * changed and the thread still says `open`. A closed tab, a POST that never came
+ * back and a lost network all land in that window. The receipt closes it: it
+ * travels in the SAME transaction as the edit, so either both survived or
+ * neither did, and every client that syncs the body syncs the proof beside it.
+ * `./verify`'s no-op refusal is the other half of this same argument — a
+ * "mutation" that changes not one character would still write a receipt, and the
+ * thread would read `accepted` over a document that never received the proposal.
+ *
+ * THE KEY IS THE CONTRACT, exactly as `COMPANY_MD_COLLAB_TEXT_KEY` is for the
+ * body text (`../org/company-md-collab`). A receipt written under any other name
+ * lands in a map nobody reads while the reader observes a map nobody writes: the
+ * accept control stays live over an edit that already happened, a second apply
+ * is offered for an edit already in the body, and NOTHING ANYWHERE THROWS. One
+ * implementation can get away with spelling the name inline. Two cannot — that
+ * is the same two-independent-implementations-with-no-arbiter hazard the anchor
+ * schema is published for (ADR-CONTRACTS-116), and the receipt now has a second
+ * writer coming, so the name is spelled once, here.
+ *
+ * IT LIVES BESIDE THE BODY, NEVER INSIDE IT. This is a ROOT map on the same
+ * document as the text, not a span within the text: a receipt must never appear
+ * in the markdown source, in an export, or in the content hash. A materializer
+ * that reads the text root and nothing else is what keeps that true, and nothing
+ * here may tempt a writer into the body.
+ *
+ * ABSENCE IS NOT PROOF. A reader holding no replica holds no receipts, so an
+ * empty map means "no receipt is KNOWN HERE" and never "no receipt exists".
+ * Every consumer must therefore act on PRESENCE only; a consumer that concluded
+ * anything from silence would turn a reader that merely has no session into one
+ * that does the wrong thing rather than nothing.
+ *
+ * NO YJS HERE, DELIBERATELY — the same seam `./resolve` and `./create` hold.
+ * This module names the key and states one row's shape. Getting the map,
+ * iterating it and observing it are the consumer's, because `yjs` is an import
+ * the vocabulary-guard forbids this package from making.
+ *
+ * A LEAF, like `./suggestion`: this module imports nothing but `zod`. It has no
+ * reason to reach for the anchor or the resolution ladder, and staying a leaf
+ * means anything in this directory can import it later without a cycle.
+ *
+ * SPELLING DEVIATION FROM THE AUTHORITATIVE REFERENCE (PRD-00941, must_log).
+ * Nothing semantic, on three counts. (1) The reference writes
+ * `z.object({...}).strict()`; what ships is `z.strictObject`, zod v4's idiom for
+ * exactly that and this directory's existing spelling (see `./anchor`'s
+ * PRD-00922 note). (2) The reference single-quotes its strings; `.prettierrc`
+ * sets `singleQuote: false`, so `pnpm format:check` rewrites them. (3) The
+ * reference writes `readSuggestionReceipt`'s signature on one line, which is 81
+ * columns against `printWidth: 80`, so Prettier reflows it onto three. A
+ * different spelling of the same schema and the same function; nothing about
+ * what is accepted or refused changed.
+ */
+import { z } from "zod";
+
+/**
+ * The root map key every application receipt is written under, keyed within
+ * that map by thread id.
+ *
+ * THIS IS THE NAME OF THE MAP, NOT A MAP. It is a single string, and the reason
+ * it is a published constant rather than an inline literal is that a typo is
+ * silent on BOTH ends — the writer's receipt lands somewhere nobody reads, and
+ * the reader watches somewhere nobody writes.
+ */
+export const SUGGESTION_RECEIPTS_MAP = "suggestionReceipts";
+
+/**
+ * What one applied suggestion left behind.
+ *
+ * STRICT, AND WITHOUT A `v` HATCH — unlike `CommentAnchorSchema` and
+ * `SuggestionSchema`, and that difference is deliberate rather than an
+ * oversight. Those two are negotiated payloads whose shapes must be able to grow
+ * while old readers keep parsing, so they version. This row is not negotiated:
+ * it is three fields that already exist, written by the shipped applier exactly
+ * as spelled here, and this module PROMOTES that convention rather than
+ * redesigning it. Adding a required `v` now would make the published parser
+ * reject every receipt currently in existence — the failure this module was
+ * written to prevent, committed by the module itself.
+ *
+ * So the three fields are closed, and a fourth fact does not arrive by widening
+ * this row. It arrives as a new key, or as a versioned successor schema that
+ * readers adopt before any writer emits it. The drop direction is why that is
+ * safe: an unrecognised row parses to `null`, which every consumer must already
+ * handle correctly, because absence is not proof and a reader with no replica
+ * sees exactly the same thing. Accepting the extras instead would surface a row
+ * this package half-understands to a decision surface, where one reader acts on
+ * the unknown field and another does not.
+ */
+export const SuggestionReceiptSchema = z.strictObject({
+  /**
+   * The claim token whose holder applied the edit, and the dedupe key for the
+   * apply itself.
+   *
+   * `min(1)` and nothing more. The backend's request boundary constrains this
+   * token to a 64-char hex string, and that constraint is already published
+   * through the generated API surface; restating it here would make a THIRD
+   * description of one token that no parity guard compares — the same call
+   * `./schemas` makes in leaving `userId` a bare `z.string()`. What this schema
+   * has to reject is a row that is not a token at all.
+   */
+  claimToken: z.string().min(1),
+  /**
+   * Wall clock at the moment the edit landed. DISPLAY ONLY — never an ordering
+   * key, never an expiry input. The lease is the monotonic one.
+   *
+   * A bare `z.number()`, which in zod v4 already refuses `NaN` and the
+   * infinities. That matters more here than for a JSON response: a CRDT map
+   * replicates raw JavaScript values, so a peer can put a literal `NaN` in this
+   * field and it will arrive as one.
+   */
+  appliedAt: z.number(),
+  /**
+   * Who applied it. A bare non-empty string rather than `.uuid()`, mirroring
+   * `./schemas`' `userId` for the same reason: the shapes in this package
+   * mirror the backend's looseness rather than tightening past it.
+   */
+  byUserId: z.string().min(1),
+});
+
+export type SuggestionReceipt = z.infer<typeof SuggestionReceiptSchema>;
+
+/**
+ * A receipt is parsed, not trusted.
+ *
+ * These values arrive over the wire from a peer and the CRDT replicates
+ * whatever was put there, with no schema of its own and no boundary in between.
+ * A row that is not three well-typed fields is therefore DROPPED rather than
+ * surfaced: a malformed receipt reaching a decision surface would withdraw a
+ * live suggestion's controls with no way back, or post a garbage claim token on
+ * every render. Returning the row's recognisable fields as a partial receipt
+ * would be the same mistake wearing a type.
+ *
+ * Total: any input, no throw, `null` for everything that is not a receipt.
+ */
+export function readSuggestionReceipt(
+  value: unknown,
+): SuggestionReceipt | null {
+  const parsed = SuggestionReceiptSchema.safeParse(value);
+  return parsed.success ? parsed.data : null;
+}