@company-semantics/contracts 39.3.0 → 39.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "39.3.0",
+  "version": "39.4.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -147,14 +147,14 @@
     "overrides": {
       "brace-expansion@<5.0.8": ">=5.0.8",
       "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",
       "postcss@<8.5.18": ">=8.5.18",
-      "markdown-it@<14.2.0": ">=14.2.0",
-      "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"
+      "markdown-it@<14.2.0": ">=14.2.0"
     }
   },
   "lint-staged": {
@@ -162,5 +162,5 @@
     "*.md": "markdownlint-cli2",
     "package.json": "node -e \"JSON.parse(require('fs').readFileSync('package.json'))\""
   },
-  "securityRequirementsVersion": "e88ddf247895bafc36dc5d878bb1045dc522a2375683fe08e1b59a10f99e8766"
+  "securityRequirementsVersion": "888e8f888ed3bee8311fd39dee4b24b4f23a6638f1df183e3e6b4e0455704ae2"
 }

package/src/action-items/README.md

@@ -0,0 +1,73 @@
+# action-items/
+
+## Purpose
+
+The vocabulary for **things awaiting a particular user's decision** — the
+published shape of `GET /api/me/action-items`, which is the one read that
+answers "what needs me?" across every domain at once.
+
+Before this, every pending-thing read in the system was scoped to one entity
+(`/docs/{id}/access-requests`) or one org (`/api/workspace/invites`). Nothing
+was keyed by _actor = me, across resources_, so a pending access request on a
+document was invisible from the tree, the sidebar, and the app shell — the only
+real notice was an email.
+
+An action item is **derived standing state, never a stored row**. A provider in
+`backend/src/action-items/providers/` answers "what does user U owe action on in
+org O?" from its domain's own pending rows, under its domain's own authority
+gate. Nothing is written, so nothing has to be cleared: when the first owner
+approves a request, the source row leaves `pending` and the item is simply
+absent from the next read. There is no clearing code to forget to write.
+
+- `kinds.ts` — `ACTION_ITEM_KINDS` and the `ActionItemKind` union derived from
+  it. Also the argument for why this is a different vocabulary from
+  `NotificationKind`, and the list of things deliberately excluded.
+- `schemas.ts` — `ActionItem`, `ActionItemTarget`, `ActionItemListResponse`.
+  Zod-canonical.
+
+## Invariants
+
+- **A kind names STANDING STATE, not an event.** `NotificationKind` names
+  things that get SENT (`companyMd.access_requested` — an email left the
+  building); an `ActionItemKind` names a decision that is outstanding right now
+  (`companyMd.access_request_pending`). They are not in bijection: `auth.otp`
+  can never be an action item, `execution.confirmation_pending` has no
+  notification, and one item can be owed by many users where the first to act
+  closes it for all. Collapsing the unions makes one of those meanings lie.
+- **Copy is not shared with `notifications/`.** An email is prose carrying a
+  brand and a year; an action-item row is a title, a detail line and the name of
+  the thing. Bending the send-shaped render pipeline to also emit list rows
+  would couple derived state to a delivery mechanism. This is a decision, not an
+  oversight — see ADR-CONT-104 before "fixing" it.
+- **`href` must RESOLVE the item, not merely show it.** An item you can only
+  look at is a notification. This is what keeps the layer honest about being
+  actionable-only.
+- **`id` is `${kind}:${sourceRowId}`** — a function of the source row, stable
+  across reads. It is not an id of its own, because there is no row of its own.
+- **`unitPath` is a roll-up ANCHOR, not a materialised ancestor path.** It is
+  the ltree `path` of the anchor org unit, read live from the same column
+  `OrgUnitSchema.path` carries. Clients count a subtree by prefix match
+  (`p === path || p.startsWith(`${path}.`)`). Because this and the org tree read
+  the same live column, they cannot disagree, and moving a unit needs no
+  backfill. Storing an ancestor list here would reintroduce exactly that
+  backfill. `null` means org-wide: it rolls up to the root and nowhere below.
+- **Authority is the provider's, never this layer's.** These are shapes; nothing
+  here filters. A provider that returns an item the viewer may not act on is a
+  provider bug, and its test is the one that must catch it.
+- Types and pure vocabulary only — no classes, no side effects, no imports
+  beyond `zod` (vocabulary-guard enforced).
+
+## Public API
+
+| Export                                              | Description                                                  |
+| --------------------------------------------------- | ------------------------------------------------------------ |
+| `ActionItemKind` / `ACTION_ITEM_KINDS`              | The closed vocabulary of outstanding-decision kinds          |
+| `ActionItem` / `ActionItemSchema`                   | One outstanding decision                                     |
+| `ActionItemTarget` / `ActionItemTargetSchema`       | What the item is about — the entity a surface badges against |
+| `ActionItemTargetType` / `ACTION_ITEM_TARGET_TYPES` | `company_md` \| `org_unit` \| `org` \| `execution`           |
+| `ActionItemListResponse` / `…Schema`                | The `GET /api/me/action-items` response                      |
+
+## Dependencies
+
+`zod`, and `./kinds` from `./schemas`. Nothing else — this domain depends on
+nothing outside itself, including `notifications/`.

package/src/action-items/__tests__/README.md

@@ -0,0 +1,39 @@
+# action-items/\_\_tests\_\_/
+
+## Purpose
+
+Locks the claims `../README.md` and ADR-CONT-104 make that the compiler cannot.
+
+- `vocabulary.test.ts` — the three things a type signature does not say:
+  1. **`ActionItemKind` and `NotificationKind` share no member.** This is the
+     load-bearing test of the whole domain. The two unions look mergeable and
+     are not: one names events that get SENT, the other names standing state.
+     If someone "unifies" them, this is what stops it.
+  2. **The response carries no field named `version`.** The app's
+     `invalidateResource` probes cached payloads for that name structurally and
+     SKIPS the invalidation when the cached value is at least as new. A field of
+     that name here would silently wedge every badge in the product, with no
+     error anywhere. Nothing else in the stack would catch it.
+  3. **A null `unitPath` parses.** An execution has no owning org unit, so it
+     must be able to say so rather than carry a fabricated anchor.
+
+## Invariants
+
+- These tests assert VOCABULARY, never behaviour — there is no behaviour here to
+  assert. A test that needs a provider, a fetch, or a database belongs in
+  backend's `src/action-items/__tests__/`, not here.
+- The disjointness test reads `NOTIFICATION_DEFINITIONS` rather than restating
+  the notification kinds. A hand-copied list would drift and start passing
+  vacuously.
+- `makeItem()` returns a well-formed item and every negative case mutates ONE
+  field of it. A negative test that hand-builds a broken object can pass for the
+  wrong reason.
+
+## Public API
+
+None — test-only.
+
+## Dependencies
+
+`vitest`, the sibling modules under test, `../../notifications` (for the real
+kind list), and `../../resource-keys` (for the key round-trip).

package/src/action-items/__tests__/vocabulary.test.ts

@@ -0,0 +1,133 @@
+/**
+ * The action-item vocabulary's invariants, as tests rather than prose
+ * (ADR-CONT-104).
+ *
+ * These lock the two claims the README makes that a compiler cannot: that this
+ * is a SEPARATE vocabulary from NotificationKind, and that an action item is
+ * addressable both as a cache key and as a roll-up anchor.
+ */
+import { describe, it, expect } from "vitest";
+import { ACTION_ITEM_KINDS, type ActionItemKind } from "../kinds.js";
+import {
+  ACTION_ITEM_TARGET_TYPES,
+  ActionItemListResponseSchema,
+  ActionItemSchema,
+} from "../schemas.js";
+import { NOTIFICATION_DEFINITIONS } from "../../notifications/index.js";
+import {
+  toQueryKey,
+  fromQueryKey,
+  type ResourceKey,
+} from "../../resource-keys.js";
+
+const ORG_ID = "11111111-1111-4111-8111-111111111111";
+
+function makeItem(over: Partial<Record<string, unknown>> = {}) {
+  return {
+    id: "companyMd.access_request_pending:req-1",
+    kind: "companyMd.access_request_pending" satisfies ActionItemKind,
+    target: { type: "company_md", id: "doc-1" },
+    unitPath: "acme.sales",
+    title: "Maya Chen wants access",
+    detail: "Reviewing the cross-team roadmap",
+    contextLabel: "Sales.md",
+    href: "/@acme/md/doc-1?share=1&request=req-1",
+    createdAt: "2026-07-27T00:00:00.000Z",
+    ...over,
+  };
+}
+
+describe("ActionItemKind is a separate vocabulary from NotificationKind", () => {
+  // The core claim of ADR-CONT-104. If someone "unifies" the two unions,
+  // this is the test that should stop them: the overlap must stay empty, because
+  // the two name different things (a sent event vs. standing state).
+  it("shares no member with NotificationKind", () => {
+    const notificationKinds = new Set(Object.keys(NOTIFICATION_DEFINITIONS));
+    const overlap = ACTION_ITEM_KINDS.filter((k) => notificationKinds.has(k));
+    expect(overlap).toEqual([]);
+  });
+
+  it("names standing state — every kind reads as a pending condition", () => {
+    for (const kind of ACTION_ITEM_KINDS) {
+      expect(kind).toMatch(/_pending$/);
+    }
+  });
+
+  it("uses the shared {domain}.{type} convention", () => {
+    for (const kind of ACTION_ITEM_KINDS) {
+      expect(kind).toMatch(/^[a-zA-Z]+\.[a-z_]+$/);
+    }
+  });
+});
+
+describe("ActionItemSchema", () => {
+  it("accepts a well-formed item", () => {
+    expect(ActionItemSchema.parse(makeItem())).toMatchObject({
+      kind: "companyMd.access_request_pending",
+    });
+  });
+
+  it("accepts a null unitPath — an org-wide item with no tree anchor", () => {
+    // Proves the shape admits targets that live outside the org tree at all
+    // (an execution has no owning unit). Those roll up to the root and nowhere
+    // below it; a required unitPath would have forced a fake anchor.
+    const parsed = ActionItemSchema.parse(
+      makeItem({
+        kind: "execution.confirmation_pending",
+        target: { type: "execution", id: "exec-1" },
+        unitPath: null,
+      }),
+    );
+    expect(parsed.unitPath).toBeNull();
+  });
+
+  it("rejects a kind outside the vocabulary", () => {
+    expect(() =>
+      ActionItemSchema.parse(makeItem({ kind: "org.invite" })),
+    ).toThrow();
+  });
+
+  it("rejects a target type outside the vocabulary", () => {
+    expect(() =>
+      ActionItemSchema.parse(makeItem({ target: { type: "chat", id: "c-1" } })),
+    ).toThrow();
+  });
+
+  it("requires an href — an item you cannot resolve is not an action item", () => {
+    const { href: _dropped, ...withoutHref } = makeItem();
+    expect(() => ActionItemSchema.parse(withoutHref)).toThrow();
+  });
+
+  it("carries no field named `version`", () => {
+    // invalidateResource() probes a cached payload for `version` structurally
+    // and SKIPS the invalidation when the cached value is at least as new. A
+    // field of that name in this response would silently wedge every badge.
+    expect(Object.keys(ActionItemSchema.shape)).not.toContain("version");
+    expect(Object.keys(ActionItemListResponseSchema.shape)).not.toContain(
+      "version",
+    );
+  });
+});
+
+describe("the actionItems resource key", () => {
+  const key: ResourceKey = { type: "actionItems", orgId: ORG_ID };
+
+  it("is org-scoped, so switching org cannot serve the previous org's bucket", () => {
+    expect(toQueryKey(key)).toEqual(["actionItems", ORG_ID]);
+  });
+
+  it("roundtrips through fromQueryKey", () => {
+    expect(fromQueryKey(toQueryKey(key))).toEqual(key);
+  });
+});
+
+describe("target types", () => {
+  it("covers every surface a badge can hang on", () => {
+    expect([...ACTION_ITEM_TARGET_TYPES].sort()).toEqual([
+      "company_md",
+      "execution",
+      "org",
+      "org_unit",
+    ]);
+  });
+});

package/src/action-items/index.ts

@@ -0,0 +1,33 @@
+/**
+ * action-items/ — the vocabulary for things awaiting a user's decision.
+ *
+ * See ./README.md for the domain, and ADR-CONT-104 for why this is not
+ * `NotificationKind`.
+ */
+
+// =============================================================================
+// Kinds — what sorts of decision can be outstanding
+// =============================================================================
+
+export { ACTION_ITEM_KINDS } from "./kinds";
+export type { ActionItemKind } from "./kinds";
+
+// =============================================================================
+// Shapes — the published GET /api/me/action-items contract
+// =============================================================================
+
+export {
+  ACTION_ITEM_TARGET_TYPES,
+  ActionItemKindSchema,
+  ActionItemListResponseSchema,
+  ActionItemSchema,
+  ActionItemTargetSchema,
+  ActionItemTargetTypeSchema,
+} from "./schemas";
+
+export type {
+  ActionItem,
+  ActionItemListResponse,
+  ActionItemTarget,
+  ActionItemTargetType,
+} from "./schemas";

package/src/action-items/kinds.ts

@@ -0,0 +1,82 @@
+/**
+ * What kinds of action item exist (ADR-CONT-104).
+ *
+ * An action item is a thing AWAITING A PARTICULAR USER'S DECISION. It is
+ * derived standing state, never a stored row: a provider answers "what does
+ * user U owe action on in org O?" from its domain's own pending rows, so an
+ * item resolved by someone else is simply absent from the next read.
+ *
+ * WHY THIS IS NOT `NotificationKind`:
+ *
+ * `NotificationKind` names EVENTS THAT GET SENT — `companyMd.access_requested`
+ * is the moment an email leaves the building. An action item names STANDING
+ * STATE — `companyMd.access_request_pending` is the fact that a decision is
+ * outstanding right now. The two are not in bijection and never will be:
+ *
+ * - `auth.otp` is a notification and can never be an action item.
+ * - `execution.confirmation_pending` is an action item with no notification.
+ * - One notification kind can open an item that many DIFFERENT users owe, and
+ *   the first of them to act closes it for all of them. A sent notification has
+ *   no such lifecycle — it is delivered once, to one address, and is then over.
+ *
+ * Collapsing the two unions would make one of those two meanings lie. Keep them
+ * separate; if a future kind needs both, it gets a member in each.
+ *
+ * Copy is likewise NOT shared with `NotificationDefinition.compose`. An email is
+ * prose carrying a brand and a year; an action-item row is a title, a detail
+ * line and the name of the thing. Bending the send-shaped render pipeline to
+ * also emit list rows would couple derived state to a delivery mechanism.
+ *
+ * INVARIANTS:
+ * - `{domain}.{type}` dot notation, matching `NotificationKind`'s convention.
+ *   The `_pending` suffix is load-bearing: it is what makes the "standing state,
+ *   not event" reading obvious at the call site.
+ * - These strings go on the wire and are used as the stable prefix of an item's
+ *   id. Renaming one is a breaking change, not a tidy-up.
+ * - A kind earns membership by having a PROVIDER that can derive it and an
+ *   `href` that RESOLVES it. A kind whose item cannot be acted on is not an
+ *   action item — that is the informational feed, which this layer does not
+ *   model (yet).
+ */
+
+// =============================================================================
+// ActionItemKind Union
+// =============================================================================
+
+/**
+ * ActionItemKind identifies what sort of decision is outstanding.
+ *
+ * New kinds MUST be added to:
+ * 1. This union
+ * 2. A provider in `backend/src/action-items/providers/`, which applies that
+ *    domain's OWN authority gate
+ *
+ * `execution.confirmation_pending` earns its place by fixing a real hole rather
+ * than by symmetry: a chat execution in `pending_confirmation` is reachable
+ * ONLY from the chat stream it was proposed in, so closing the tab strands it
+ * until it expires. Its confirm/reject routes already exist
+ * (`POST /api/executions/{id}/confirm|reject`); what was missing was any way to
+ * find it. That is exactly what this layer is for.
+ *
+ * The candidates that did NOT earn a place, recorded so they are not
+ * re-litigated — every one fails a membership test above:
+ *
+ * - **A pending INVITE awaits the invitee**, who is not yet in the org. No
+ *   viewer owes it a decision. The `+ N invite` counts in the people surfaces
+ *   are VOLUME badges and stay where they are.
+ * - **An ownership TRANSFER is the recipient's decision** — but accepting is
+ *   token-bearing (`token + session + email match + fresh login`) and only the
+ *   token's hash is stored, so an in-app row could not resolve it. "Go check
+ *   your email" is a dead affordance.
+ * - **`execution_approvals`** (the approval-policy chain) has no `org_id` of
+ *   its own, names a ROLE rather than a user as approver, and has zero HTTP
+ *   surface. Distinct from `execution.confirmation_pending` above.
+ * - **`orgReasoning.inference_review`** is semantically a clean fit and its
+ *   decision route exists — with no caller and no review UI to link to.
+ */
+export const ACTION_ITEM_KINDS = [
+  "companyMd.access_request_pending",
+  "execution.confirmation_pending",
+] as const;
+
+export type ActionItemKind = (typeof ACTION_ITEM_KINDS)[number];

package/src/action-items/schemas.ts

@@ -0,0 +1,87 @@
+/**
+ * Action-item DTOs (ADR-CONT-104).
+ *
+ * The published shape of `GET /api/me/action-items` — everything awaiting the
+ * viewer's decision across every domain, in one read.
+ *
+ * Zod-canonical: schema is the source of truth, the type is inferred.
+ */
+import { z } from "zod";
+import { ACTION_ITEM_KINDS } from "./kinds";
+
+/**
+ * What an item is ABOUT — the entity a surface badges against.
+ *
+ * A small union of its own rather than the app-local `SHAREABLE_ENTITY_TYPES`
+ * (which contracts does not publish) or `ResourceKey` (a cache vocabulary whose
+ * company.md variant carries the doc id under a field named `slug`). Promoting
+ * either is its own change; this stays sized to what badges exist.
+ */
+export const ACTION_ITEM_TARGET_TYPES = [
+  "company_md",
+  "org_unit",
+  "org",
+  // Not an ACL entity — an execution is addressed by id and has no owning unit,
+  // so its items anchor at `unitPath: null` and roll up only to the root. That
+  // asymmetry is deliberate and is what proves the roll-up handles targets with
+  // no place in the org tree.
+  "execution",
+] as const;
+export const ActionItemTargetTypeSchema = z.enum(ACTION_ITEM_TARGET_TYPES);
+export type ActionItemTargetType = z.infer<typeof ActionItemTargetTypeSchema>;
+
+export const ActionItemTargetSchema = z.object({
+  type: ActionItemTargetTypeSchema,
+  /** The entity's stable id. Docs are id-addressed (ADR-BE-315), never slug. */
+  id: z.string(),
+});
+export type ActionItemTarget = z.infer<typeof ActionItemTargetSchema>;
+
+/** Zod mirror of the vocabulary. `./kinds` owns the list; this never restates it. */
+export const ActionItemKindSchema = z.enum(ACTION_ITEM_KINDS);
+
+/**
+ * One outstanding decision.
+ *
+ * Derived, never stored — see `./kinds`. Two consequences worth stating at the
+ * shape rather than in prose elsewhere:
+ *
+ * - `id` is `${kind}:${sourceRowId}`, stable across reads because it is a
+ *   function of the source row. It is NOT a row id of its own; there is no row.
+ * - `unitPath` is the ltree `path` of the item's anchor org unit, read live from
+ *   the same column `OrgUnitSchema.path` carries. It is a ROLL-UP ANCHOR, not a
+ *   materialised ancestor list: the client counts a subtree by prefix-matching
+ *   (`p === path || p.startsWith(`${path}.`)`), and because both this and the
+ *   org tree are read from the same live column, they cannot disagree. Moving a
+ *   unit needs no backfill. `null` means org-wide — it rolls up to the root and
+ *   nowhere below it.
+ */
+export const ActionItemSchema = z.object({
+  /** `${kind}:${sourceRowId}` — a function of the source row, not a row id. */
+  id: z.string(),
+  kind: ActionItemKindSchema,
+  target: ActionItemTargetSchema,
+  /** ltree anchor for subtree roll-up; `null` = org-wide. */
+  unitPath: z.string().nullable(),
+  /** One line naming the decision, e.g. "Maya Chen wants access". */
+  title: z.string(),
+  /** Optional second line — the requester's message, a reason, a deadline. */
+  detail: z.string().nullable(),
+  /** The thing it is about, as the user names it, e.g. "Sales.md". */
+  contextLabel: z.string(),
+  /**
+   * Where to go to RESOLVE it. An action item whose href only *shows* the thing
+   * is a notification, not an action item — see `./kinds`.
+   */
+  href: z.string(),
+  createdAt: z.string(),
+});
+export type ActionItem = z.infer<typeof ActionItemSchema>;
+
+/** `GET /api/me/action-items` — everything awaiting this viewer, newest first. */
+export const ActionItemListResponseSchema = z.object({
+  items: z.array(ActionItemSchema),
+});
+export type ActionItemListResponse = z.infer<
+  typeof ActionItemListResponseSchema
+>;

package/src/index.ts

@@ -240,6 +240,32 @@ export {
   isValidNotificationKind,
 } from "./notifications/index";
 
+// Action-item domain types — things awaiting a user's DECISION, derived from
+// each domain's own pending rows rather than stored. Deliberately a separate
+// vocabulary from NotificationKind above: that one names events that get SENT,
+// this one names standing state. See src/action-items/README.md.
+// @see ADR-CONT-104
+export {
+  ACTION_ITEM_KINDS,
+  ACTION_ITEM_TARGET_TYPES,
+} from "./action-items/index";
+
+export {
+  ActionItemKindSchema,
+  ActionItemListResponseSchema,
+  ActionItemSchema,
+  ActionItemTargetSchema,
+  ActionItemTargetTypeSchema,
+} from "./action-items/index";
+
+export type {
+  ActionItem,
+  ActionItemKind,
+  ActionItemListResponse,
+  ActionItemTarget,
+  ActionItemTargetType,
+} from "./action-items/index";
+
 // Chat domain types
 // @see PRD-00142 for share chat design rationale
 export type {

package/src/resource-keys.ts

@@ -55,6 +55,13 @@ export type ResourceKey =
   // dashboard reads over Global-infra factory tables; tenant-less, scope 'system'.
   | { type: "factoryFloor"; scope: "system" }
   | { type: "factorySnapshot"; scope: "system" }
+  // Everything awaiting the viewer's decision, across every domain
+  // (ADR-CONT-104). ORG-scoped, not user-scoped, even though the content is
+  // per-viewer: the bucket differs per org, so a user-keyed entry would serve
+  // one org's items after switching to another. Same shape as `chats` and
+  // `timeline`, which are likewise viewer-filtered but org-partitioned — and it
+  // inherits `resolveScope`'s impersonation handling for free.
+  | { type: "actionItems"; orgId: string }
   // User-scoped
   | { type: "dismissedBanners"; userId: string }
   | { type: "userOrgs"; userId: string }
@@ -98,6 +105,7 @@ const ORG_SCOPED_TYPES = [
   "orgLevelConfig",
   "peopleOrgChart",
   "orgUnitOwners",
+  "actionItems",
 ] as const;
 
 const USER_SCOPED_TYPES = [
@@ -181,6 +189,7 @@ export function toQueryKey(key: ResourceKey): readonly string[] {
     case "orgLevelConfig":
     case "peopleOrgChart":
     case "orgUnitOwners":
+    case "actionItems":
       return [key.type, key.orgId] as const;
 
     // System-scoped (ADR-CONTRACTS-052) — tenant-less super-admin resources