@company-semantics/contracts 44.4.0 → 45.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "44.4.0",
+  "version": "45.0.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -130,7 +130,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/node": "^26.1.2",
+    "@types/node": "^22.20.1",
     "amphtml-validator": "^1.0.38",
     "culori": "^4.0.2",
     "husky": "^9.1.7",
@@ -150,7 +150,6 @@
       "minimatch@<10.2.3": ">=10.2.3",
       "js-yaml@>=4.0.0 <4.3.0": ">=4.3.0 <5.0.0",
       "js-yaml@>=5.0.0 <5.2.2": ">=5.2.2 <6.0.0",
-      "rollup@<4.59.0": ">=4.59.0",
       "picomatch@<4.0.4": ">=4.0.4",
       "esbuild@<0.28.1": ">=0.28.1",
       "linkify-it@<5.0.2": ">=5.0.2",

package/src/__tests__/resource-keys.test.ts

@@ -98,6 +98,37 @@ describe("resource-keys: system-scoped internalAdmin* types", () => {
   });
 });
 
+describe("resource-keys: userMd (user-scoped singleton)", () => {
+  const USER_ID = "55555555-5555-4555-8555-555555555555";
+  const key: ResourceKey = { type: "userMd", userId: USER_ID };
+
+  it("toQueryKey produces [type, userId] with no doc identity", () => {
+    const qk = toQueryKey(key);
+    expect(qk).toEqual(["userMd", USER_ID]);
+    // A per-user singleton: the user IS the identity, so there is no third
+    // segment even though the payload is a work item (ADR-BE-487).
+    expect(qk).toHaveLength(2);
+  });
+
+  it("roundtrips through fromQueryKey", () => {
+    const parsed = fromQueryKey(toQueryKey(key));
+    expect(parsed).toEqual(key);
+    expect("orgId" in parsed).toBe(false);
+  });
+
+  it("matchesResourceKey is user-scoped: rejects another user's doc", () => {
+    const otherUser = "66666666-6666-4666-8666-666666666666";
+    expect(matchesResourceKey(toQueryKey(key), key)).toBe(true);
+    expect(matchesResourceKey(["userMd", otherUser], key)).toBe(false);
+  });
+
+  it("does not collide with the other user-scoped keys", () => {
+    const viewerKey: ResourceKey = { type: "viewer", userId: USER_ID };
+    expect(matchesResourceKey(toQueryKey(viewerKey), key)).toBe(false);
+    expect(matchesResourceKey(toQueryKey(key), viewerKey)).toBe(false);
+  });
+});
+
 describe("resource-keys: companyMdAccessRequests (per-doc identity)", () => {
   const DOC_ID = "22222222-2222-4222-8222-222222222222";
   const key: ResourceKey = {

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 = '9bcb0e0bc2cc' as const;
-export const SPEC_HASH_FULL = '9bcb0e0bc2cce27742a97dd5f7ef4cadcff268e8700f40554258301cee4e183e' as const;
+export const SPEC_HASH = 'b10dd357bc4f' as const;
+export const SPEC_HASH_FULL = 'b10dd357bc4fd990f9d6646954b3b1aa38f9dce4dd64ecfe8f5f83eb8f51a568' as const;

package/src/api/generated.ts

@@ -4736,8 +4736,8 @@ export interface components {
             extractionStatus: "pending" | "extracting" | "complete" | "failed";
             errorClass?: string | null;
             errorReason?: string | null;
-            createdAt: string;
-            updatedAt: string;
+            createdAt?: string;
+            updatedAt?: string;
         };
         UpdateCompanyMdTitleRequest: {
             title: string;

package/src/content/schemas.ts

@@ -199,8 +199,16 @@ export const CompanyMdDocResponseSchema = z.object({
    */
   errorClass: z.string().nullable().optional(),
   errorReason: z.string().nullable().optional(),
-  createdAt: z.string(),
-  updatedAt: z.string(),
+  /**
+   * Withheld from non-readers — see `CompanyMdDocRelations` for why, and keep the
+   * two in lockstep. Present on every reader path; absent on the
+   * `locked_requestable` / `redacted_admin` stubs, where a moving timestamp is
+   * the last remaining side channel on a doc whose body, collaborators and
+   * structure are already withheld. Absence means "you were not told", not
+   * "never modified".
+   */
+  createdAt: z.string().optional(),
+  updatedAt: z.string().optional(),
 });
 
 // ---------------------------------------------------------------------------

package/src/org/company-md.ts

@@ -275,8 +275,25 @@ export interface CompanyMdDocRelations {
   readonly inheritsFrom: string | null;
   readonly sources: readonly CompanyMdSource[];
   readonly dependencies: readonly CompanyMdDependency[];
-  readonly createdAt: string;
-  readonly updatedAt: string;
+  /**
+   * WITHHELD FROM NON-READERS, and optional for exactly that reason.
+   *
+   * A non-reader's doc read is a stub: `content` is `''`, and `sources` /
+   * `dependencies` / `members` are empty. These two timestamps were the one
+   * thing left on it that still reported activity INSIDE the document — that
+   * someone wrote to it, and roughly when. On a doc whose body, collaborators
+   * and structure are all withheld, a moving `updatedAt` is a side channel: poll
+   * it and you learn how busy a document you cannot open is.
+   *
+   * So they are absent on the `locked_requestable` / `redacted_admin` branches
+   * and present on every reader path. Optional rather than nullable because
+   * "withheld" is the absence of an answer, not an answer of `null` — and
+   * because an older consumer reading the new API sees a missing field, which is
+   * the shape it already tolerates for every other stub-withheld value here.
+   * Treat absence as "you were not told", never as "never modified".
+   */
+  readonly createdAt?: string;
+  readonly updatedAt?: string;
 }
 
 export type CompanyMdDoc = CompanyMdDocCore &

package/src/resource-keys.ts

@@ -84,6 +84,12 @@ export type ResourceKey =
   | { type: "dismissedBanners"; userId: string }
   | { type: "userOrgs"; userId: string }
   | { type: "sessions"; userId: string }
+  // The viewer's personal doc (`/api/me/md`) — a per-user singleton, so it is
+  // keyed by userId alone with no doc identity segment. Its PAYLOAD is a work
+  // item, lazily materialized on first read (ADR-BE-487), but the resource is
+  // "this user's personal doc", not "work item <id>": a future generic
+  // `workItem` key would be a different resource with a different identity.
+  | { type: "userMd"; userId: string }
   | { type: "viewer"; userId: string };
 
 /**
@@ -131,6 +137,7 @@ const USER_SCOPED_TYPES = [
   "dismissedBanners",
   "userOrgs",
   "sessions",
+  "userMd",
   "viewer",
 ] as const;
 
@@ -186,6 +193,7 @@ export function toQueryKey(key: ResourceKey): readonly string[] {
     case "dismissedBanners":
     case "userOrgs":
     case "sessions":
+    case "userMd":
     case "viewer":
       return [key.type, key.userId] as const;