@company-semantics/contracts 59.1.0 → 61.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "59.1.0",
+  "version": "61.0.0",
   "private": false,
   "repository": {
     "type": "git",

package/src/api/generated-spec-hash.ts

@@ -1,3 +1,3 @@
 // AUTO-GENERATED — do not edit. Run pnpm generate:spec-hash to regenerate.
-export const SPEC_HASH = 'dd2a725d7ebd' as const;
-export const SPEC_HASH_FULL = 'dd2a725d7ebd694db25efbe0e638077984af41551c1989fb374d9a7b8bc4eb3d' as const;
+export const SPEC_HASH = '4ee1bc3befbf' as const;
+export const SPEC_HASH_FULL = '4ee1bc3befbf8bb865b4bdad38b892c59f198fec45acdcdde93a067a678516b3' as const;

package/src/api/generated.ts

@@ -5065,7 +5065,7 @@ export interface components {
             summary: {
                 executionId: string;
                 /** @enum {string} */
-                kind: "integration.connect" | "integration.disconnect" | "integration.purge" | "profile.update" | "slack.send" | "data.ingest" | "data.scope" | "system.cleanup" | "member.changeManager" | "companyMd.ingest" | "companyMd.commentPass" | "semantic.transform" | "companyMd.importContextDoc";
+                kind: "integration.connect" | "integration.disconnect" | "integration.purge" | "profile.update" | "slack.send" | "data.ingest" | "data.scope" | "system.cleanup" | "member.changeManager" | "companyMd.ingest" | "companyMd.commentPass" | "companyMd.commentAction" | "semantic.transform" | "companyMd.importContextDoc";
                 target: {
                     /** @constant */
                     type: "slack";
@@ -5313,6 +5313,7 @@ export interface components {
             canUploadContext?: boolean;
             canManageAcl?: boolean;
             canComment: boolean;
+            canDecideSuggestion: boolean;
             canChangeVisibility?: boolean;
             inheritsFromId: string | null;
             inheritsFrom: string | null;
@@ -6992,6 +6993,7 @@ export interface components {
             createdAt: string;
             updatedAt: string;
             comments: components["schemas"]["Comment"][];
+            capabilities: components["schemas"]["ThreadCapabilities"];
         };
         /** @description Opaque, versioned comment anchor: document-level, a text anchor with a required quote and optional relative positions, or a zero-width text-insertion point for insert suggestions. */
         CommentAnchor: {
@@ -7046,6 +7048,14 @@ export interface components {
             endOffset: number | null;
             displayName: string;
         };
+        /** @description What the requesting actor may do to one thread, decided server-side. */
+        ThreadCapabilities: {
+            canReply: boolean;
+            canResolve: boolean;
+            canReopen: boolean;
+            canDecideSuggestion: boolean;
+            canWithdraw: boolean;
+        };
         /** @description A comment thread without its comments. */
         CommentThreadSummary: {
             id: string;
@@ -9116,7 +9126,7 @@ export interface operations {
             query?: {
                 cursor?: string;
                 limit?: number;
-                kind?: "integration.connect" | "integration.disconnect" | "integration.purge" | "profile.update" | "slack.send" | "data.ingest" | "data.scope" | "system.cleanup" | "member.changeManager" | "companyMd.ingest" | "companyMd.commentPass" | "semantic.transform" | "companyMd.importContextDoc";
+                kind?: "integration.connect" | "integration.disconnect" | "integration.purge" | "profile.update" | "slack.send" | "data.ingest" | "data.scope" | "system.cleanup" | "member.changeManager" | "companyMd.ingest" | "companyMd.commentPass" | "companyMd.commentAction" | "semantic.transform" | "companyMd.importContextDoc";
                 targetType?: string;
                 periodStart?: string;
                 periodEnd?: string;
@@ -9251,7 +9261,7 @@ export interface operations {
             query?: {
                 limit?: number;
                 offset?: number;
-                kind?: "integration.connect" | "integration.disconnect" | "integration.purge" | "profile.update" | "slack.send" | "data.ingest" | "data.scope" | "system.cleanup" | "member.changeManager" | "companyMd.ingest" | "companyMd.commentPass" | "semantic.transform" | "companyMd.importContextDoc";
+                kind?: "integration.connect" | "integration.disconnect" | "integration.purge" | "profile.update" | "slack.send" | "data.ingest" | "data.scope" | "system.cleanup" | "member.changeManager" | "companyMd.ingest" | "companyMd.commentPass" | "companyMd.commentAction" | "semantic.transform" | "companyMd.importContextDoc";
                 kindPrefix?: string;
             };
             header?: never;

package/src/comments/__tests__/schemas.test.ts

@@ -73,6 +73,17 @@ function makeThread(over: Record<string, unknown> = {}) {
     createdAt: "2026-08-01T12:00:00.000Z",
     updatedAt: "2026-08-01T12:00:00.000Z",
     comments: [makeComment()],
+    // REQUIRED on a thread carried WITH its comments. The summary shape has no
+    // capabilities and no comments — a `CommentThreadSummary` parse of this
+    // fixture simply ignores both, which is why the summary cases below still
+    // pass unchanged.
+    capabilities: {
+      canReply: true,
+      canResolve: true,
+      canReopen: false,
+      canDecideSuggestion: false,
+      canWithdraw: false,
+    },
     ...over,
   };
 }

package/src/comments/schemas.ts

@@ -216,8 +216,58 @@ export type CommentThreadSummary = z.infer<typeof CommentThreadSummarySchema>;
  * order a redacted row used to hold open no longer has anything to hold. The
  * wire SHAPE is unchanged either way; what changed is which rows arrive.
  */
+/**
+ * What the requesting actor may do to ONE thread.
+ *
+ * SERVER-COMPUTED, and that is the point. The app used to reconstruct this
+ * model client-side from doc-level signals plus the viewer's id, which is how
+ * the two surfaces came to disagree — the agent's read reported `canResolve:
+ * false` to actors who had a working Resolve button in the rail. One predicate,
+ * on the server, answering for every surface.
+ *
+ * Each flag ANDs the actor's subject-level band with the thread's own kind and
+ * status, so a flag is `true` only where the verb would actually be admitted.
+ * Two things it deliberately cannot express, both documented rather than
+ * papered over:
+ *   - a LIVE ACCEPTANCE LEASE, which makes both decide verbs 409 while
+ *     `suggestion.status` is still `open`; the claim columns are never
+ *     projected, so `canDecideSuggestion: true` is "band and status permit",
+ *     not "nobody else is mid-accept".
+ *   - anything about OTHER threads; these are per-thread answers.
+ */
+export const ThreadCapabilitiesSchema = z.object({
+  /** Write a reply. Not conditioned on status — a reply reopens a resolved thread. */
+  canReply: z.boolean(),
+  /** Resolve it: an OPEN comment thread only; a suggestion is decided, not resolved. */
+  canResolve: z.boolean(),
+  /** Reopen it: the exact complement of `canResolve`. */
+  canReopen: z.boolean(),
+  /** Accept or reject an OPEN suggestion — the edit band (ADR-BE-536). */
+  canDecideSuggestion: z.boolean(),
+  /**
+   * Withdraw one's OWN open suggestion. IDENTITY, not band: the author needs no
+   * edit capability, so this is true for authors that `canDecideSuggestion`
+   * refuses. Separate for exactly that reason — folded together, the stricter
+   * answer governed and a commenter-band author was told they could not close
+   * their own suggestion.
+   */
+  canWithdraw: z.boolean(),
+});
+export type ThreadCapabilities = z.infer<typeof ThreadCapabilitiesSchema>;
+
 export const CommentThreadSchema = CommentThreadSummarySchema.extend({
   comments: z.array(CommentSchema),
+  /**
+   * REQUIRED. Every route that returns a thread WITH its comments computes it —
+   * the list read and the create; the mutation routes return a
+   * `CommentThreadSummary`, which carries no comments and no capabilities.
+   *
+   * Not optional, deliberately. An optional block means a client keeps a local
+   * derivation for when it is absent, and that second opinion is the precise
+   * thing this field exists to delete: the app and the agent-facing read had
+   * drifted into disagreeing about the same thread.
+   */
+  capabilities: ThreadCapabilitiesSchema,
 });
 export type CommentThread = z.infer<typeof CommentThreadSchema>;
 

package/src/content/schemas.ts

@@ -202,6 +202,29 @@ export const CompanyMdDocResponseSchema = z.object({
    * takes the major bump.
    */
   canComment: z.boolean(),
+  /**
+   * SUGGESTION-DECIDE capability signal: whether the requesting actor holds
+   * `CompanyMd.CanEdit` on this doc as `assertCanDecideSuggestion` evaluates it
+   * — accepting or rejecting someone's suggestion arbitrates what the document
+   * will say, so it rides the edit band (PRD-00934 / ADR-BE-536).
+   *
+   * IT EXISTS BECAUSE `canEdit` IS NOT ONE ANSWER. The app used to derive the
+   * Accept/Reject affordance from `canEdit`, which is the BATCH path
+   * (`canUserEditDocBatch`): it subtracts docs whose projection is stale and
+   * adds owner / account-owner identity safeties. The gate the Accept button
+   * actually hits is `evaluate('CompanyMd.CanEdit')`, which has neither. The two
+   * disagree in both directions — a dead Accept button on a doc whose projection
+   * has not compiled, and a hidden affordance on one whose access shrank but has
+   * not recompiled. Same nominal policy, two implementations; this field is the
+   * one the gate uses, computed the way the gate computes it.
+   *
+   * REQUIRED, like `canComment` above and unlike the three sharing signals: an
+   * absent value would mean "unknown", and a client that invents a default for
+   * an authority question has replaced the server's answer with a guess. The
+   * single-doc read is the only producer of this shape and always computes it.
+   * Signal only; admittance and enforcement are unchanged.
+   */
+  canDecideSuggestion: z.boolean(),
   /**
    * GOVERNANCE capability signal (ADR-BE-435): whether the requesting actor holds
    * `CompanyMd.CanChangeVisibility` (owner OR the `org.manage_content_sharing`

package/src/decisions/types.ts

@@ -71,7 +71,29 @@ export type DecisionEffect =
    * derivation to run again. Carries the reason so the follow-up has something
    * to act on, and so the reviewer is not told "saved" when nothing moved.
    */
-  | { readonly kind: "needs_reinference"; readonly note: string };
+  | { readonly kind: "needs_reinference"; readonly note: string }
+  /**
+   * Mark a person as the head of a DURABLE unit, and optionally set that unit's
+   * owner label. Today the only producer names the org root, so accepting is how
+   * an imported chart's CEO becomes the workspace's root owner.
+   *
+   * DURABLE addressing, not a temp id: post-apply every unit is durable, so a
+   * real id is the general form. A temp id would serve only corrections to
+   * not-yet-created units, which a proposal's own `headPersonId` already covers
+   * with no effect at all.
+   *
+   * THIS EFFECT NEVER MINTS AUTHORITY. It writes a presentation/semantic marker
+   * and a label. Granting unit or account ownership stays with the human-gated
+   * ownership route — a root-unit owner IS an account owner, so an automated
+   * grant would be a privilege-escalation path.
+   */
+  | {
+      readonly kind: "set_unit_head";
+      readonly unitId: string;
+      readonly personId: string;
+      /** Non-null also sets the unit's owner label; null marks the head only. */
+      readonly title: string | null;
+    };
 
 /** The closed set of effect kinds, as runtime data for validators. */
 export const DECISION_EFFECT_KINDS = [
@@ -81,6 +103,7 @@ export const DECISION_EFFECT_KINDS = [
   "unadopt_unit",
   "archive_unit",
   "needs_reinference",
+  "set_unit_head",
 ] as const satisfies ReadonlyArray<DecisionEffect["kind"]>;
 
 /** One answer a human may give, with what it means and what it does. */

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

@@ -243,6 +243,27 @@ describe("EXECUTION_KINDS golden snapshot", () => {
           templateId: "companyMd.commentPass",
         },
       },
+      "companyMd.commentAction": {
+        kind: "companyMd.commentAction",
+        domain: "data",
+        display: {
+          label: "Apply Comment Action",
+          pastTenseLabel: "Comment action applied",
+          icon: "pencil",
+        },
+        governance: {
+          visibility: "user",
+          requiresAdmin: false,
+        },
+        ui: {
+          showInAdmin: false,
+          showInTimeline: true,
+          confirmBeforeRun: true,
+        },
+        explanation: {
+          templateId: "companyMd.commentAction",
+        },
+      },
       "semantic.transform": {
         kind: "semantic.transform",
         domain: "organization",
@@ -300,12 +321,14 @@ describe("ExecutionKind exhaustiveness", () => {
   });
 
   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.
+    // These previously ran — or, for the comment ACTION, previewed a confirmable
+    // intent that then routed nowhere — 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",
+      "companyMd.commentAction",
     ]) {
       expect(isValidExecutionKind(kind)).toBe(true);
       expect(CONFIRMATION_LABELS[kind as ExecutionKind]).toBeTruthy();

package/src/execution/kinds.ts

@@ -55,4 +55,12 @@ export type ExecutionKind =
   | "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";
+  | "companyMd.importContextDoc"
+  /** ONE collaboration write on a company.md thread — resolve, reopen, reply,
+   *  or decide a suggestion. Distinct from `companyMd.commentPass`: the pass is
+   *  a reviewed BUNDLE gated on the whole rail's staleness token, which is the
+   *  wrong gate for a single act — an unrelated new comment elsewhere on the
+   *  document would refuse it. Promoted out of a call-site cast for the same
+   *  reason `semantic.transform` was: a kind that runs but is absent from the
+   *  registry is invisible to every reader of it. */
+  | "companyMd.commentAction";

package/src/execution/registry.ts

@@ -271,6 +271,29 @@ export const EXECUTION_KINDS = {
       templateId: "companyMd.commentPass",
     },
   },
+  "companyMd.commentAction": {
+    kind: "companyMd.commentAction",
+    domain: "data",
+    display: {
+      label: "Apply Comment Action",
+      pastTenseLabel: "Comment action applied",
+      icon: "pencil",
+    },
+    governance: {
+      visibility: "user",
+      requiresAdmin: false,
+    },
+    ui: {
+      showInAdmin: false,
+      showInTimeline: true,
+      // A single collaboration write still changes what the conversation says,
+      // and resolving or deciding is not silently reversible for other readers.
+      confirmBeforeRun: true,
+    },
+    explanation: {
+      templateId: "companyMd.commentAction",
+    },
+  },
   "semantic.transform": {
     kind: "semantic.transform",
     domain: "organization",

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

@@ -123,6 +123,7 @@ describe("CONFIRMATION_LABELS", () => {
       "member.changeManager": "Change Reporting Manager",
       "companyMd.ingest": "Ingest Company Knowledge",
       "companyMd.commentPass": "Apply Comment Pass",
+      "companyMd.commentAction": "Apply Comment Action",
       "semantic.transform": "Apply Reporting Transformation",
       "companyMd.importContextDoc": "Import Context Document",
     });

package/src/message-parts/confirmation.ts

@@ -48,6 +48,7 @@ export const CONFIRMATION_LABELS: Record<ExecutionKind, string> = {
   "member.changeManager": "Change Reporting Manager",
   "companyMd.ingest": "Ingest Company Knowledge",
   "companyMd.commentPass": "Apply Comment Pass",
+  "companyMd.commentAction": "Apply Comment Action",
   "semantic.transform": "Apply Reporting Transformation",
   "companyMd.importContextDoc": "Import Context Document",
 };