@company-semantics/contracts 45.0.0 → 45.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "45.0.0",
+  "version": "45.2.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -116,6 +116,7 @@
     "generate:current": "tsx ../company-semantics-ci/scripts/generate-current.ts",
     "adr:new": "tsx ../company-semantics-control/scripts/adr/adr-new-cli.ts",
     "repo-map": "tsx ../company-semantics-ci/scripts/generate-repo-map.ts --roots src --name company-semantics-contracts --write",
+    "sync:workflow-pins": "tsx ../company-semantics-ci/scripts/sync-workflow-pins.ts --write",
     "repo-map:check": "tsx ../company-semantics-ci/scripts/generate-repo-map.ts --roots src --name company-semantics-contracts --check",
     "readme-api": "tsx ../company-semantics-ci/scripts/generate-readme-api.ts --roots src --write --jsdoc",
     "readme-api:check": "tsx ../company-semantics-ci/scripts/generate-readme-api.ts --roots src --check --jsdoc",
@@ -134,7 +135,7 @@
     "amphtml-validator": "^1.0.38",
     "culori": "^4.0.2",
     "husky": "^9.1.7",
-    "lint-staged": "^17.2.0",
+    "lint-staged": "^17.3.0",
     "markdownlint-cli2": "^0.23.2",
     "openapi-typescript": "^7.13.0",
     "prettier": "^3.9.6",
@@ -146,9 +147,9 @@
   },
   "pnpm": {
     "overrides": {
-      "brace-expansion@<5.0.8": ">=5.0.8",
+      "brace-expansion@<5.0.9": ">=5.0.9",
       "minimatch@<10.2.3": ">=10.2.3",
-      "js-yaml@>=4.0.0 <4.3.0": ">=4.3.0 <5.0.0",
+      "js-yaml@>=4.0.0 <4.3.1": ">=4.3.1 <5.0.0",
       "js-yaml@>=5.0.0 <5.2.2": ">=5.2.2 <6.0.0",
       "picomatch@<4.0.4": ">=4.0.4",
       "esbuild@<0.28.1": ">=0.28.1",
@@ -162,5 +163,5 @@
     "*.md": "markdownlint-cli2",
     "package.json": "node -e \"JSON.parse(require('fs').readFileSync('package.json'))\""
   },
-  "securityRequirementsVersion": "9ffb1b974fa033f13a73539f8338cad319b62bb95695aa4ac7b5215a50493513"
+  "securityRequirementsVersion": "795d779110bb8dee6374229e227dc7b7e813197c34a35bbe2066113e0939a988"
 }

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 = 'b10dd357bc4f' as const;
-export const SPEC_HASH_FULL = 'b10dd357bc4fd990f9d6646954b3b1aa38f9dce4dd64ecfe8f5f83eb8f51a568' as const;
+export const SPEC_HASH = '7f497f657ee3' as const;
+export const SPEC_HASH_FULL = '7f497f657ee3f1a81b096b02094743f5e0fa6a3d03c0bb92cdb0034762ca3ee7' as const;

package/src/api/generated.ts

@@ -3394,6 +3394,109 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/comments": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** List a subject's comment threads */
+        get: operations["listCommentThreads"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/comments/threads": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Open a comment thread on a subject */
+        post: operations["createCommentThread"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/comments/threads/{threadId}/comments": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Reply into a comment thread */
+        post: operations["replyToCommentThread"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/comments/{commentId}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post?: never;
+        /** Soft-delete a comment (author or subject owner) */
+        delete: operations["deleteComment"];
+        options?: never;
+        head?: never;
+        /** Edit a comment's body (author-only) */
+        patch: operations["editComment"];
+        trace?: never;
+    };
+    "/api/comments/threads/{threadId}/resolve": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Resolve a comment thread */
+        post: operations["resolveCommentThread"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/comments/threads/{threadId}/reopen": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Reopen a resolved comment thread */
+        post: operations["reopenCommentThread"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
 }
 export type webhooks = Record<string, never>;
 export interface components {
@@ -4036,6 +4139,10 @@ export interface components {
             unitMembershipsTruncated: boolean;
             inviteStatus: ("active" | "pending" | "expired") | null;
             effectiveScopes: string[];
+            scopeProvenance?: {
+                scope: string;
+                bands: string[];
+            }[];
             recentActions: {
                 id: string;
                 timestamp: string;
@@ -6156,6 +6263,41 @@ export interface components {
                 userAgent: string;
             } | null;
         };
+        /** @description Every thread on the subject the caller may see. */
+        CommentThreadListResponse: {
+            threads: components["schemas"]["CommentThread"][];
+        };
+        /** @description The created thread with its opening comment. */
+        CommentThreadResponse: {
+            thread: components["schemas"]["CommentThread"];
+        };
+        CreateCommentThreadRequest: {
+            /** @enum {string} */
+            subjectType: "company_md" | "strategy_doc" | "work_item" | "meeting_recording";
+            /** Format: uuid */
+            subjectId: string;
+            anchor: components["schemas"]["CommentAnchor"];
+            body: string;
+        };
+        /** @description The written reply, and whether it auto-reopened a resolved thread. */
+        CommentReplyResponse: {
+            comment: components["schemas"]["Comment"];
+            reopened: boolean;
+        };
+        CommentReplyRequest: {
+            body: string;
+        };
+        /** @description The comment after the mutation (redacted projection after delete). */
+        CommentResponse: {
+            comment: components["schemas"]["Comment"];
+        };
+        EditCommentRequest: {
+            body: string;
+        };
+        /** @description The thread after a resolve/reopen transition. */
+        CommentThreadSummaryResponse: {
+            thread: components["schemas"]["CommentThreadSummary"];
+        };
         /** @description Server-enforced collaboration size limits, published so clients can pre-check. */
         CollabSyncLimits: {
             maxUpdateBytes: number;
@@ -6174,6 +6316,69 @@ export interface components {
             /** @enum {string} */
             matchedVia: "fts" | "vector";
         };
+        /** @description A comment thread with all its comments oldest-first; soft-deleted comments appear redacted, never filtered out. */
+        CommentThread: {
+            id: string;
+            /** @enum {string} */
+            subjectType: "company_md" | "strategy_doc" | "work_item" | "meeting_recording";
+            subjectId: string;
+            /** @enum {string} */
+            anchorType: "document" | "text";
+            anchor: components["schemas"]["CommentAnchor"];
+            /** @enum {string} */
+            status: "open" | "resolved";
+            createdByUserId: string | null;
+            resolvedByUserId: string | null;
+            resolvedAt: string | null;
+            createdAt: string;
+            updatedAt: string;
+            comments: components["schemas"]["Comment"][];
+        };
+        /** @description Opaque, versioned comment anchor: document-level, or a text anchor with a required quote and optional relative positions. */
+        CommentAnchor: {
+            /** @constant */
+            type: "document";
+            /** @constant */
+            v: 1;
+        } | {
+            /** @constant */
+            type: "text";
+            /** @constant */
+            v: 1;
+            relStart?: string;
+            relEnd?: string;
+            quote: string;
+            prefix: string;
+            suffix: string;
+        };
+        /** @description One comment; body is null iff soft-deleted (redacted projection with empty mentions). */
+        Comment: {
+            id: string;
+            threadId: string;
+            authorUserId: string | null;
+            body: string | null;
+            editedAt: string | null;
+            deletedAt: string | null;
+            createdAt: string;
+            mentions: string[];
+        };
+        /** @description A comment thread without its comments. */
+        CommentThreadSummary: {
+            id: string;
+            /** @enum {string} */
+            subjectType: "company_md" | "strategy_doc" | "work_item" | "meeting_recording";
+            subjectId: string;
+            /** @enum {string} */
+            anchorType: "document" | "text";
+            anchor: components["schemas"]["CommentAnchor"];
+            /** @enum {string} */
+            status: "open" | "resolved";
+            createdByUserId: string | null;
+            resolvedByUserId: string | null;
+            resolvedAt: string | null;
+            createdAt: string;
+            updatedAt: string;
+        };
     };
     responses: never;
     parameters: never;
@@ -11905,4 +12110,247 @@ export interface operations {
             };
         };
     };
+    listCommentThreads: {
+        parameters: {
+            query: {
+                subjectType: "company_md" | "strategy_doc" | "work_item" | "meeting_recording";
+                subjectId: string;
+                status?: "open" | "resolved";
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Every thread on the subject with its comments oldest-first */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["CommentThreadListResponse"];
+                };
+            };
+            /** @description Invalid query parameters */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Subject not found, or the caller may not read it */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    createCommentThread: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["CreateCommentThreadRequest"];
+            };
+        };
+        responses: {
+            /** @description Thread created with its opening comment (one transaction) */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["CommentThreadResponse"];
+                };
+            };
+            /** @description Invalid body (including every anchor-corpus reject case) */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Subject not found, or the caller may not comment on it */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    replyToCommentThread: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                threadId: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["CommentReplyRequest"];
+            };
+        };
+        responses: {
+            /** @description Reply written; reopened=true when it auto-reopened a resolved thread */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["CommentReplyResponse"];
+                };
+            };
+            /** @description Invalid body */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Thread not found, or the caller may not comment on its subject */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    deleteComment: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                commentId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Comment soft-deleted; response carries the redacted projection */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["CommentResponse"];
+                };
+            };
+            /** @description Comment not found, already deleted, or the caller may not delete it */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    editComment: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                commentId: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["EditCommentRequest"];
+            };
+        };
+        responses: {
+            /** @description Comment updated with edited_at stamped */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["CommentResponse"];
+                };
+            };
+            /** @description Invalid body */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Comment not found, deleted, or the caller is not its author */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    resolveCommentThread: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                threadId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Thread resolved with resolved_at + resolved_by stamped */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["CommentThreadSummaryResponse"];
+                };
+            };
+            /** @description Thread not found, or the caller may not comment on its subject */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    reopenCommentThread: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                threadId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Thread reopened with the resolution stamp cleared */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["CommentThreadSummaryResponse"];
+                };
+            };
+            /** @description Thread not found, or the caller may not comment on its subject */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
 }

package/src/generated/openapi-routes.ts

@@ -21,6 +21,12 @@ export const openApiRoutes = {
   '/api/chats/{id}/messages': ['POST'],
   '/api/chats/{id}/messages/{messageId}': ['DELETE'],
   '/api/chats/{id}/pin': ['DELETE', 'POST'],
+  '/api/comments': ['GET'],
+  '/api/comments/threads': ['POST'],
+  '/api/comments/threads/{threadId}/comments': ['POST'],
+  '/api/comments/threads/{threadId}/reopen': ['POST'],
+  '/api/comments/threads/{threadId}/resolve': ['POST'],
+  '/api/comments/{commentId}': ['DELETE', 'PATCH'],
   '/api/company-md/access-requests/{id}/approve': ['POST'],
   '/api/company-md/access-requests/{id}/deny': ['POST'],
   '/api/company-md/context-bank': ['POST'],

package/src/guards/evolution-config.ts

@@ -11,8 +11,6 @@
  * ./config.ts so the package public surface is unchanged.
  *
  * Design principle: Configuration is data, not code.
- *
- * @architecture-role universal
  */
 
 // =============================================================================

package/src/guards/soc2-config.ts

@@ -10,8 +10,6 @@
  * ./config.ts so the package public surface is unchanged.
  *
  * Design principle: Configuration is data, not code.
- *
- * @architecture-role universal
  */
 
 import type { Soc2ControlArea } from "./types";

package/src/org/__tests__/company-md-collab.test.ts

@@ -142,6 +142,62 @@ describe("CompanyMdCollabSseEventSchema — raw backend frames", () => {
     ).not.toThrow();
   });
 
+  /**
+   * `canEdit` is permission and `status` is occupancy — the pair below is the
+   * case that motivated the field (ADR-CONTRACTS-114). A read-only participant
+   * and an edit-capable one who is merely reading BOTH report `viewing`, so a
+   * consumer that split the roster on `status` would get the wrong answer for
+   * one of them. These three assertions lock that the schema keeps the two
+   * axes independent, including the absent case a rollout produces.
+   */
+  it("carries canEdit independently of status", () => {
+    const base = {
+      type: "collab-presence" as const,
+      v: 1 as const,
+      userId: USER_ID,
+      clientKey: CLIENT_KEY,
+    };
+
+    // Edit-capable, but reading. Occupancy says viewing; permission says yes.
+    const reader = CompanyMdCollabSseEventSchema.parse({
+      ...base,
+      status: "viewing",
+      canEdit: true,
+    });
+    expect(reader).toMatchObject({ status: "viewing", canEdit: true });
+
+    // Read-only, and on the editor tab. Occupancy is the same; permission is not.
+    const viewer = CompanyMdCollabSseEventSchema.parse({
+      ...base,
+      status: "viewing",
+      canEdit: false,
+    });
+    expect(viewer).toMatchObject({ status: "viewing", canEdit: false });
+
+    // An older server omits the field. It must parse, and it must not
+    // materialize as `true` — absent means no edit rights, so a consumer
+    // reading `canEdit === true` fails closed on its own.
+    const legacy = CompanyMdCollabSseEventSchema.parse({
+      ...base,
+      status: "editing",
+    });
+    expect(legacy).toMatchObject({ status: "editing" });
+    expect((legacy as { canEdit?: boolean }).canEdit).toBeUndefined();
+  });
+
+  it("rejects a non-boolean canEdit", () => {
+    expect(() =>
+      CompanyMdCollabSseEventSchema.parse({
+        type: "collab-presence",
+        v: 1,
+        userId: USER_ID,
+        clientKey: CLIENT_KEY,
+        status: "editing",
+        canEdit: "yes",
+      }),
+    ).toThrow();
+  });
+
   it("parses a collab-reset frame for each reason the backend sends", () => {
     for (const reason of ["epoch-mismatch", "compacted", "cursor-ahead"]) {
       expect(() =>

package/src/org/company-md-collab.ts

@@ -235,7 +235,9 @@ export type CompanyMdCollabUpdateEvent = z.infer<
  * `userId` is trustworthy: the server stamps it from the posting session and
  * never takes it from a client body. That is why no client-supplied identity
  * type is published — receiving clients resolve name/avatar/colour from
- * `userId` themselves.
+ * `userId` themselves. `canEdit` is stamped from the same session for the same
+ * reason: it is an authority answer, and an authority answer a client could
+ * assert about itself is not one.
  */
 export const CompanyMdCollabPresenceEventSchema = z.object({
   type: z.literal("collab-presence"),
@@ -247,6 +249,23 @@ export const CompanyMdCollabPresenceEventSchema = z.object({
   clientKey: z.string().uuid(),
   /** What that editor instance is doing. */
   status: z.enum(["editing", "viewing"]),
+  /**
+   * Whether this participant may WRITE the document — server-stamped from the
+   * same `CompanyMd.CanEdit` binding the sync handshake reports as `editable`,
+   * never taken from a client body.
+   *
+   * Distinct from `status`, which is occupancy: `status` says what one editor
+   * instance is doing right now, this says what the person is ALLOWED to do.
+   * The roster admits viewers on purpose (CanView, not CanEdit), so a reader
+   * cannot tell the two apart without this — and a client must never re-derive
+   * it from an ACL, which would stand up a second access authority in the
+   * browser.
+   *
+   * Optional so an older server stays representable on the wire. ABSENT MEANS
+   * NO EDIT RIGHTS: a consumer reads the missing field as `false` rather than
+   * guessing, which keeps the surface default-deny through a rollout.
+   */
+  canEdit: z.boolean().optional(),
   /** Selection anchor — an encoded Y.RelativePosition blob. */
   anchor: z.string().optional(),
   /** Selection head — an encoded Y.RelativePosition blob. */

package/src/org/schemas.ts

@@ -129,8 +129,31 @@ const MemberRecentActionSchema = z.object({
   summary: z.string(),
 });
 
+/**
+ * Which bundle or role contributed a resolved scope (ADR-CTRL-360).
+ *
+ * `member_default` / `admin` / `account_owner` are the static actor-class
+ * bundles AUTH-011C re-homed the deleted role scope lists onto (ADR-BE-184);
+ * `role:<name>` is a surviving RBAC role assignment. Open string rather than an
+ * enum because `rbac_roles` is data, not a closed vocabulary.
+ *
+ * A scope carries EVERY band that granted it — composition is a union, not a
+ * ladder, so an owner who also holds admin authority legitimately shows both.
+ * Display/audit only; `effectiveScopes` remains the authorization surface.
+ */
+const ScopeProvenanceEntrySchema = z.object({
+  scope: z.string(),
+  bands: z.array(z.string()).min(1),
+});
+
 export const WorkspaceMemberDetailSchema = WorkspaceMemberSchema.extend({
   effectiveScopes: z.array(z.string()),
+  /**
+   * Per-scope provenance for {@link WorkspaceMemberDetailSchema.shape.effectiveScopes}.
+   * Optional: absence means the server did not compute it (legacy callsite, or a
+   * non-user actor), never that the scopes were granted by nothing.
+   */
+  scopeProvenance: z.array(ScopeProvenanceEntrySchema).optional(),
   recentActions: z.array(MemberRecentActionSchema),
 });