@company-semantics/contracts 91.1.0 → 93.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "91.1.0",
+  "version": "93.0.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -142,27 +142,27 @@
     "node": "22.x"
   },
   "dependencies": {
-    "@slack/types": "^3.1.0",
+    "@slack/types": "^3.2.0",
     "zod": "^4.6.5"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@types/node": "^22.20.4",
+    "@types/node": "^22.20.5",
     "amphtml-validator": "^1.0.38",
     "culori": "^4.0.2",
-    "dependency-cruiser": "18.4.0",
-    "eslint": "^10.11.0",
+    "dependency-cruiser": "18.5.0",
+    "eslint": "^10.12.0",
     "husky": "^9.1.7",
-    "knip": "6.38.0",
+    "knip": "6.39.0",
     "lint-staged": "^17.6.0",
     "markdownlint-cli2": "^0.23.3",
     "openapi-typescript": "^7.13.0",
     "prettier": "^3.9.9",
     "tsx": "^4.23.15",
     "typescript": "^5.8.3",
-    "typescript-eslint": "^8.70.1",
-    "vite": "^8.3.1",
-    "vitest": "^5.0.2",
+    "typescript-eslint": "^8.71.0",
+    "vite": "^8.3.2",
+    "vitest": "^5.0.3",
     "yaml": "^2.9.1"
   },
   "pnpm": {
@@ -179,6 +179,7 @@
       "esbuild@<0.28.1": ">=0.28.1",
       "linkify-it@<5.0.2": ">=5.0.2",
       "postcss@<8.5.23": ">=8.5.23",
+      "source-map-js@<1.2.2": ">=1.2.2",
       "markdown-it@<14.2.0": ">=14.2.0",
       "@humanfs/node@<0.16.8": ">=0.16.8 <0.17.0"
     }
@@ -188,5 +189,5 @@
     "*.md": "markdownlint-cli2",
     "package.json": "node -e \"JSON.parse(require('fs').readFileSync('package.json'))\""
   },
-  "securityRequirementsVersion": "8700b9fe36f8c948f12970ec54128e4f1955986dd9b634114f7501fdb1884267"
+  "securityRequirementsVersion": "4b88755e9a43a82b2f5eb55b953581526f1982de362da77bc579888d1f6a1bb0"
 }

package/src/action-items/README.md

@@ -42,6 +42,13 @@ absent from the next read. There is no clearing code to forget to write.
 - **`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.
+- **`affordance` is optional; `href` is the fallback.** When a catalog
+  affordance resolves the item (control ADR `affordance-system`), the provider
+  sets it and a surface that can render a real control renders that —
+  re-gated per viewer, executed by the server. When it is absent, the surface
+  links to `href`. Any instance is allowed, including the projected
+  `review.open`: an item is derived on read and never stored, so nothing is
+  stored twice.
 - **`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 materialized ancestor path.** It is
@@ -54,8 +61,9 @@ absent from the next read. There is no clearing code to forget to write.
 - **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).
+- Types and pure vocabulary only — no classes, no side effects, no runtime
+  imports beyond `zod` and sibling contracts modules (vocabulary-guard
+  enforced).
 
 ## Kinds
 
@@ -80,5 +88,5 @@ absent from the next read. There is no clearing code to forget to write.
 
 ## Dependencies
 
-`zod`, and `./kinds` from `./schemas`. Nothing else — this domain depends on
-nothing outside itself, including `notifications/`.
+`zod`, `./kinds` from `./schemas`, and `../affordances/affordance` for the
+optional `affordance`. Nothing else — in particular not `notifications/`.

package/src/action-items/schemas.ts

@@ -7,6 +7,7 @@
  * Zod-canonical: schema is the source of truth, the type is inferred.
  */
 import { z } from "zod";
+import { AffordanceSchema } from "../affordances/affordance";
 import { ACTION_ITEM_KINDS } from "./kinds";
 
 /**
@@ -91,6 +92,15 @@ export const ActionItemSchema = z.object({
    * an action item — see `./kinds`.
    */
   href: z.string(),
+  /**
+   * The catalog affordance that resolves it, when one does (control ADR
+   * affordance-system). A surface that can render a real control renders this
+   * — re-gated per viewer, executed by the server — and falls back to `href`
+   * when it is absent. Any instance, including a projected one (`review.open`):
+   * an action item is derived on read and never stored, so nothing is stored
+   * twice.
+   */
+  affordance: AffordanceSchema.optional(),
   createdAt: z.string(),
 });
 export type ActionItem = z.infer<typeof ActionItemSchema>;

package/src/affordances/README.md

@@ -43,12 +43,59 @@ only the binding KIND.
   whether an action executes.
 - **`MAX_OFFERED_AFFORDANCES` is a sanity bound**, never a presentation cap.
   How many a surface shows is that surface's decision.
+- **The burn-down wave is appended, never inserted** (PRD-01137). Twelve ids
+  follow `review.open`: `integrations.open`, `hris.connect`,
+  `account.editProfile`, `workspace.openOrgSettings`, `sourceSync.addFile`,
+  `sourceSync.openUpdate`, `orgStructure.openReview`, `chat.open`,
+  `companyMd.openDoc`, `companyMd.openHistory`, `team.open`, `execution.open`
+  (arguments and binding kinds in [the burn-down wave](#the-burn-down-wave)
+  below). An action on one thing names it by its id, never by a URL — the
+  binding owns the route. None reads a live availability condition yet; adding
+  one is an append.
+- **Reverse coverage is exactly one of two things.** Every capability a person
+  can act on declares `{ affordance }` or `{ noAffordance }` with a reason from
+  the closed `NO_AFFORDANCE_REASONS` (`readOnly`, `inlineControl`,
+  `internalAdmin`, `systemOnly`, `authFlow`), so "nobody decided" is not
+  representable.
+- **"What can I do here" is a result shape, not a catalog listing.**
+  `AvailableAffordancesSchema` holds the policy-allowed instances the context's
+  offer rules produced, each with its live availability — bounded by
+  `MAX_OFFERED_AFFORDANCES`, no instance twice, and no policy field, so a
+  blocked one cannot leak. Nothing here enumerates the catalog.
+
+## The burn-down wave
+
+The twelve ids appended after `review.open` (PRD-01137), in catalog order.
+Arguments come from `AFFORDANCE_ARGS` / `NO_ARG_AFFORDANCE_IDS` (`args.ts`); an
+id with no arguments has no `args` key. The binding kind comes from
+`AFFORDANCE_BINDING_KIND_OF` (`affordance.ts`); none of the twelve is a
+`command`. All twelve read no live availability condition (`null` in
+`AFFORDANCE_AVAILABILITY_OF`).
+
+| Id                          | Args (schema)                                         | Binding kind |
+| --------------------------- | ----------------------------------------------------- | ------------ |
+| `integrations.open`         | none                                                  | `navigate`   |
+| `hris.connect`              | none                                                  | `surface`    |
+| `account.editProfile`       | none                                                  | `navigate`   |
+| `workspace.openOrgSettings` | none                                                  | `navigate`   |
+| `sourceSync.addFile`        | none                                                  | `surface`    |
+| `sourceSync.openUpdate`     | `{ proposalId }` (`SourceSyncOpenUpdateArgsSchema`)   | `surface`    |
+| `orgStructure.openReview`   | `{ proposalId }` (`OrgStructureOpenReviewArgsSchema`) | `surface`    |
+| `chat.open`                 | `{ chatId }` (`ChatOpenArgsSchema`)                   | `navigate`   |
+| `companyMd.openDoc`         | `{ docId }` (`CompanyMdDocArgsSchema`)                | `navigate`   |
+| `companyMd.openHistory`     | `{ docId }` (`CompanyMdDocArgsSchema`)                | `navigate`   |
+| `team.open`                 | `{ unitId }` (`TeamOpenArgsSchema`)                   | `navigate`   |
+| `execution.open`            | `{ executionId }` (`ExecutionOpenArgsSchema`)         | `navigate`   |
+
+Every argument is a non-empty string and every args object is strict.
 
 ## Public API
 
 - `AFFORDANCE_IDS`, `AffordanceId`, `AffordanceIdSchema` (`ids.ts`).
 - `AFFORDANCE_ARGS`, `NO_ARG_AFFORDANCE_IDS`, `ReviewOpenArgsSchema`,
-  `AffordanceArgs` (`args.ts`).
+  `SourceSyncOpenUpdateArgsSchema`, `OrgStructureOpenReviewArgsSchema`,
+  `ChatOpenArgsSchema`, `CompanyMdDocArgsSchema`, `TeamOpenArgsSchema`,
+  `ExecutionOpenArgsSchema`, `AffordanceArgs` (`args.ts`).
 - `AFFORDANCE_BINDING_KINDS`, `AFFORDANCE_AVAILABILITY_IDS`,
   `AffordanceAvailabilityIdSchema`, `AFFORDANCE_UNAVAILABLE_REASONS`,
   `AffordanceAvailabilitySchema` and their types (`availability.ts`).
@@ -56,6 +103,10 @@ only the binding KIND.
   `AffordanceSchema`, `OfferedAffordanceSchema`, `PROJECTED_AFFORDANCE_IDS`,
   `AFFORDANCE_BINDING_KIND_OF`, `AFFORDANCE_AVAILABILITY_OF`,
   `MAX_OFFERED_AFFORDANCES`, `sameAffordances` (`affordance.ts`).
+- `NO_AFFORDANCE_REASONS`, `NoAffordanceReason`, `NoAffordanceReasonSchema`,
+  `AffordanceCoverage`, `AffordanceCoverageSchema` (`coverage.ts`).
+- `AvailableAffordance`, `AvailableAffordanceSchema`, `AvailableAffordances`,
+  `AvailableAffordancesSchema` (`available.ts`).
 
 Published from the package root through `src/root-exports/delivery.ts`.
 

package/src/affordances/__tests__/README.md

@@ -13,6 +13,14 @@ Locks the affordance vocabulary and the shape of an affordance instance.
   canonical args, every schema converts to JSON Schema the way the backend's
   OpenAPI generation converts it, and every name is reachable from the package
   root as the same binding.
+- `catalog-wave.test.ts` — pins the twelve burn-down ids (PRD-01137) appended
+  after the original seven, their binding kinds and null availability; proves a
+  targeted id requires exactly its one non-empty id arg, the no-affordance
+  reasons are closed, a coverage declaration is an affordance or a reason and
+  never both, an available-affordances result is bounded, distinct and carries
+  no policy field, the error envelope and billing refusal part carry
+  affordances only when non-empty, and every new name is reachable from the
+  package root.
 
 ## Invariants
 
@@ -27,4 +35,5 @@ None — test-only.
 
 ## Dependencies
 
-`vitest`, `zod`, `../index`, `../../workflows/outcome` and the package root.
+`vitest`, `zod`, `../index`, `../../workflows/outcome`, `../../api/primitives`,
+`../../billing/refusals` and the package root.

package/src/affordances/__tests__/affordances.test.ts

@@ -32,7 +32,7 @@ const schemaMatchesType: Equals<
 > = true;
 
 describe("affordance vocabulary", () => {
-  it("names the seven affordances, in order", () => {
+  it("names the nineteen affordances, in order", () => {
     expect(AFFORDANCE_IDS).toEqual([
       "sourceSync.findFiles",
       "integrations.connectGoogleDrive",
@@ -41,6 +41,18 @@ describe("affordance vocabulary", () => {
       "orgStructure.reanalyze",
       "hris.resyncDirectory",
       "review.open",
+      "integrations.open",
+      "hris.connect",
+      "account.editProfile",
+      "workspace.openOrgSettings",
+      "sourceSync.addFile",
+      "sourceSync.openUpdate",
+      "orgStructure.openReview",
+      "chat.open",
+      "companyMd.openDoc",
+      "companyMd.openHistory",
+      "team.open",
+      "execution.open",
     ]);
     expect(schemaMatchesType).toBe(true);
   });

package/src/affordances/__tests__/catalog-wave.test.ts

@@ -0,0 +1,237 @@
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+
+import * as root from "../../index";
+import * as barrel from "../index";
+import {
+  AFFORDANCE_AVAILABILITY_OF,
+  AFFORDANCE_BINDING_KIND_OF,
+  AFFORDANCE_IDS,
+  AffordanceCoverageSchema,
+  AffordanceSchema,
+  AvailableAffordancesSchema,
+  NO_AFFORDANCE_REASONS,
+  OfferedAffordanceSchema,
+} from "../index";
+import { ErrorResponseSchema } from "../../api/primitives";
+import {
+  BILLING_REFUSAL_CODES,
+  BillingRefusalPartSchema,
+} from "../../billing/refusals";
+
+// The burn-down wave (PRD-01137): exactly these ids, appended, with these kinds.
+const WAVE = {
+  "integrations.open": "navigate",
+  "hris.connect": "surface",
+  "account.editProfile": "navigate",
+  "workspace.openOrgSettings": "navigate",
+  "sourceSync.addFile": "surface",
+  "sourceSync.openUpdate": "surface",
+  "orgStructure.openReview": "surface",
+  "chat.open": "navigate",
+  "companyMd.openDoc": "navigate",
+  "companyMd.openHistory": "navigate",
+  "team.open": "navigate",
+  "execution.open": "navigate",
+} as const;
+
+const TARGET_ARG = {
+  "sourceSync.openUpdate": "proposalId",
+  "orgStructure.openReview": "proposalId",
+  "chat.open": "chatId",
+  "companyMd.openDoc": "docId",
+  "companyMd.openHistory": "docId",
+  "team.open": "unitId",
+  "execution.open": "executionId",
+} as const;
+
+describe("affordance catalog wave", () => {
+  it("appends the twelve burn-down ids after the original seven, in order", () => {
+    expect(AFFORDANCE_IDS.slice(7)).toEqual(Object.keys(WAVE));
+    expect(AFFORDANCE_IDS).toHaveLength(19);
+  });
+
+  it("every new id has the locked binding kind", () => {
+    for (const [id, kind] of Object.entries(WAVE)) {
+      expect(AFFORDANCE_BINDING_KIND_OF[id as keyof typeof WAVE], id).toBe(
+        kind,
+      );
+    }
+  });
+
+  it("the burn-down ids read no live availability", () => {
+    for (const id of Object.keys(WAVE)) {
+      expect(
+        AFFORDANCE_AVAILABILITY_OF[id as keyof typeof WAVE],
+        id,
+      ).toBeNull();
+    }
+  });
+
+  it("an id that targets one thing requires its id arg and refuses any other key", () => {
+    for (const [id, key] of Object.entries(TARGET_ARG)) {
+      expect(
+        OfferedAffordanceSchema.safeParse({ id, args: { [key]: "x1" } })
+          .success,
+        id,
+      ).toBe(true);
+      expect(OfferedAffordanceSchema.safeParse({ id }).success, id).toBe(false);
+      expect(
+        OfferedAffordanceSchema.safeParse({ id, args: { [key]: "" } }).success,
+        id,
+      ).toBe(false);
+      expect(
+        OfferedAffordanceSchema.safeParse({
+          id,
+          args: { [key]: "x1", url: "/x" },
+        }).success,
+        id,
+      ).toBe(false);
+    }
+    for (const id of [
+      "integrations.open",
+      "hris.connect",
+      "account.editProfile",
+      "workspace.openOrgSettings",
+      "sourceSync.addFile",
+    ]) {
+      expect(OfferedAffordanceSchema.safeParse({ id }).success, id).toBe(true);
+      expect(
+        OfferedAffordanceSchema.safeParse({ id, args: {} }).success,
+        id,
+      ).toBe(false);
+    }
+  });
+
+  it("the new instance schemas convert to JSON Schema", () => {
+    expect(() =>
+      z.toJSONSchema(AffordanceSchema, { io: "input" }),
+    ).not.toThrow();
+    expect(() =>
+      z.toJSONSchema(AvailableAffordancesSchema, { io: "input" }),
+    ).not.toThrow();
+    expect(() =>
+      z.toJSONSchema(AffordanceCoverageSchema, { io: "input" }),
+    ).not.toThrow();
+  });
+
+  it("the no-affordance reasons are closed, in order", () => {
+    expect(NO_AFFORDANCE_REASONS).toEqual([
+      "readOnly",
+      "inlineControl",
+      "internalAdmin",
+      "systemOnly",
+      "authFlow",
+    ]);
+  });
+
+  it("a coverage declaration names an affordance or a closed reason, never both", () => {
+    expect(
+      AffordanceCoverageSchema.safeParse({ affordance: "billing.open" })
+        .success,
+    ).toBe(true);
+    expect(
+      AffordanceCoverageSchema.safeParse({ noAffordance: "authFlow" }).success,
+    ).toBe(true);
+    expect(
+      AffordanceCoverageSchema.safeParse({
+        affordance: "billing.open",
+        noAffordance: "authFlow",
+      }).success,
+    ).toBe(false);
+    expect(
+      AffordanceCoverageSchema.safeParse({ noAffordance: "because" }).success,
+    ).toBe(false);
+    expect(AffordanceCoverageSchema.safeParse({}).success).toBe(false);
+  });
+
+  it("an available-affordances result is bounded, distinct and policy-filtered", () => {
+    const entry = {
+      affordance: { id: "billing.open" },
+      availability: { state: "available" },
+    };
+    expect(
+      AvailableAffordancesSchema.safeParse({ affordances: [] }).success,
+    ).toBe(true);
+    expect(
+      AvailableAffordancesSchema.safeParse({ affordances: [entry] }).success,
+    ).toBe(true);
+    expect(
+      AvailableAffordancesSchema.safeParse({ affordances: [entry, entry] })
+        .success,
+    ).toBe(false);
+    expect(
+      AvailableAffordancesSchema.safeParse({
+        affordances: [{ ...entry, policy: "allowed" }],
+      }).success,
+    ).toBe(false);
+    const many = Array.from({ length: 17 }, (_, i) => ({
+      affordance: { id: "chat.open", args: { chatId: `c${i}` } },
+      availability: { state: "available" },
+    }));
+    expect(
+      AvailableAffordancesSchema.safeParse({ affordances: many }).success,
+    ).toBe(false);
+  });
+
+  it("the error envelope and the billing refusal part offer affordances only when there are some", () => {
+    const err = (extra: Record<string, unknown>) => ({
+      error: {
+        code: "FORBIDDEN",
+        message: "Billing is paused.",
+        retryable: false,
+        ...extra,
+      },
+    });
+    expect(ErrorResponseSchema.safeParse(err({})).success).toBe(true);
+    expect(
+      ErrorResponseSchema.safeParse(
+        err({ affordances: [{ id: "billing.open" }] }),
+      ).success,
+    ).toBe(true);
+    expect(
+      ErrorResponseSchema.safeParse(err({ affordances: [] })).success,
+    ).toBe(false);
+    expect(
+      ErrorResponseSchema.safeParse(
+        err({ affordances: [{ id: "billing.nope" }] }),
+      ).success,
+    ).toBe(false);
+    const part = {
+      code: BILLING_REFUSAL_CODES[0],
+      orgId: "org-1",
+      retryable: false,
+    };
+    expect(BillingRefusalPartSchema.safeParse(part).success).toBe(true);
+    expect(
+      BillingRefusalPartSchema.safeParse({
+        ...part,
+        affordances: [{ id: "billing.open" }],
+      }).success,
+    ).toBe(true);
+    expect(
+      BillingRefusalPartSchema.safeParse({ ...part, affordances: [] }).success,
+    ).toBe(false);
+  });
+
+  it("every new name is reachable from the package root as the same binding", () => {
+    for (const name of [
+      "AffordanceCoverageSchema",
+      "AvailableAffordanceSchema",
+      "AvailableAffordancesSchema",
+      "ChatOpenArgsSchema",
+      "CompanyMdDocArgsSchema",
+      "ExecutionOpenArgsSchema",
+      "NO_AFFORDANCE_REASONS",
+      "NoAffordanceReasonSchema",
+      "OrgStructureOpenReviewArgsSchema",
+      "SourceSyncOpenUpdateArgsSchema",
+      "TeamOpenArgsSchema",
+    ] as const) {
+      expect((root as Record<string, unknown>)[name], name).toBeDefined();
+      expect((root as Record<string, unknown>)[name], name).toBe(
+        (barrel as Record<string, unknown>)[name],
+      );
+    }
+  });
+});

package/src/affordances/affordance.ts

@@ -14,7 +14,16 @@
  */
 import { z } from "zod";
 
-import { ReviewOpenArgsSchema, type AffordanceArgs } from "./args";
+import {
+  ChatOpenArgsSchema,
+  CompanyMdDocArgsSchema,
+  ExecutionOpenArgsSchema,
+  OrgStructureOpenReviewArgsSchema,
+  ReviewOpenArgsSchema,
+  SourceSyncOpenUpdateArgsSchema,
+  TeamOpenArgsSchema,
+  type AffordanceArgs,
+} from "./args";
 import type {
   AffordanceAvailabilityId,
   AffordanceBindingKind,
@@ -44,6 +53,11 @@ export type OfferedAffordance = Exclude<
 const noArgs = <K extends AffordanceId>(id: K) =>
   z.object({ id: z.literal(id) }).strict();
 
+const withArgs = <K extends AffordanceId, A extends z.ZodTypeAny>(
+  id: K,
+  args: A,
+) => z.object({ id: z.literal(id), args }).strict();
+
 const OFFERED_MEMBERS = [
   noArgs("sourceSync.findFiles"),
   noArgs("integrations.connectGoogleDrive"),
@@ -51,14 +65,24 @@ const OFFERED_MEMBERS = [
   noArgs("billing.open"),
   noArgs("orgStructure.reanalyze"),
   noArgs("hris.resyncDirectory"),
+  noArgs("integrations.open"),
+  noArgs("hris.connect"),
+  noArgs("account.editProfile"),
+  noArgs("workspace.openOrgSettings"),
+  noArgs("sourceSync.addFile"),
+  withArgs("sourceSync.openUpdate", SourceSyncOpenUpdateArgsSchema),
+  withArgs("orgStructure.openReview", OrgStructureOpenReviewArgsSchema),
+  withArgs("chat.open", ChatOpenArgsSchema),
+  withArgs("companyMd.openDoc", CompanyMdDocArgsSchema),
+  withArgs("companyMd.openHistory", CompanyMdDocArgsSchema),
+  withArgs("team.open", TeamOpenArgsSchema),
+  withArgs("execution.open", ExecutionOpenArgsSchema),
 ] as const;
 
 /** Every affordance instance, validated per id. */
 export const AffordanceSchema = z.discriminatedUnion("id", [
   ...OFFERED_MEMBERS,
-  z
-    .object({ id: z.literal("review.open"), args: ReviewOpenArgsSchema })
-    .strict(),
+  withArgs("review.open", ReviewOpenArgsSchema),
 ]);
 
 /** What may be persisted inside an offer: every member except a projection. */
@@ -76,6 +100,18 @@ export const AFFORDANCE_BINDING_KIND_OF = {
   "orgStructure.reanalyze": "command",
   "hris.resyncDirectory": "command",
   "review.open": "surface",
+  "integrations.open": "navigate",
+  "hris.connect": "surface",
+  "account.editProfile": "navigate",
+  "workspace.openOrgSettings": "navigate",
+  "sourceSync.addFile": "surface",
+  "sourceSync.openUpdate": "surface",
+  "orgStructure.openReview": "surface",
+  "chat.open": "navigate",
+  "companyMd.openDoc": "navigate",
+  "companyMd.openHistory": "navigate",
+  "team.open": "navigate",
+  "execution.open": "navigate",
 } as const satisfies Record<AffordanceId, AffordanceBindingKind>;
 
 /** The live condition each affordance's availability is read from, if any. */
@@ -88,6 +124,22 @@ export const AFFORDANCE_AVAILABILITY_OF = {
   "orgStructure.reanalyze": null,
   "hris.resyncDirectory": "hris.connected",
   "review.open": null,
+  // The burn-down wave reads no live condition: a navigate target is always
+  // reachable (its page renders its own state), and the two surfaces open a
+  // dialog that shows whether the HR system is connected / which files are
+  // already synced. A later availability id is an append, never a change.
+  "integrations.open": null,
+  "hris.connect": null,
+  "account.editProfile": null,
+  "workspace.openOrgSettings": null,
+  "sourceSync.addFile": null,
+  "sourceSync.openUpdate": null,
+  "orgStructure.openReview": null,
+  "chat.open": null,
+  "companyMd.openDoc": null,
+  "companyMd.openHistory": null,
+  "team.open": null,
+  "execution.open": null,
 } as const satisfies Record<AffordanceId, AffordanceAvailabilityId | null>;
 
 /**

package/src/affordances/args.ts

@@ -2,7 +2,8 @@
  * The arguments each affordance carries. An affordance INSTANCE is
  * `{ id, args }`, never a bare id, so an affordance that one day needs a
  * target (a document, an import, a finding) is a new member here, not a new
- * persisted shape. Every v1 org-scoped action takes no arguments.
+ * persisted shape. An org-scoped action takes no arguments; an action on one
+ * thing names it by its id, never by a URL (the binding owns the route).
  */
 import { z } from "zod";
 
@@ -17,6 +18,36 @@ export const ReviewOpenArgsSchema = z
   })
   .strict();
 
+/** `sourceSync.openUpdate`: which Source Sync update (proposal). */
+export const SourceSyncOpenUpdateArgsSchema = z
+  .object({ proposalId: z.string().min(1) })
+  .strict();
+
+/** `orgStructure.openReview`: which org-structure proposal's chat review. */
+export const OrgStructureOpenReviewArgsSchema = z
+  .object({ proposalId: z.string().min(1) })
+  .strict();
+
+/** `chat.open`: which chat. */
+export const ChatOpenArgsSchema = z
+  .object({ chatId: z.string().min(1) })
+  .strict();
+
+/** `companyMd.openDoc` / `companyMd.openHistory`: which document. */
+export const CompanyMdDocArgsSchema = z
+  .object({ docId: z.string().min(1) })
+  .strict();
+
+/** `team.open`: which team (org unit). */
+export const TeamOpenArgsSchema = z
+  .object({ unitId: z.string().min(1) })
+  .strict();
+
+/** `execution.open`: which execution. */
+export const ExecutionOpenArgsSchema = z
+  .object({ executionId: z.string().min(1) })
+  .strict();
+
 /**
  * Argument schemas, ONLY for ids that take arguments. An id that takes none is
  * listed in NO_ARG_AFFORDANCE_IDS and its instance OMITS `args` entirely: there
@@ -27,6 +58,13 @@ export const ReviewOpenArgsSchema = z
  */
 export const AFFORDANCE_ARGS = {
   "review.open": ReviewOpenArgsSchema,
+  "sourceSync.openUpdate": SourceSyncOpenUpdateArgsSchema,
+  "orgStructure.openReview": OrgStructureOpenReviewArgsSchema,
+  "chat.open": ChatOpenArgsSchema,
+  "companyMd.openDoc": CompanyMdDocArgsSchema,
+  "companyMd.openHistory": CompanyMdDocArgsSchema,
+  "team.open": TeamOpenArgsSchema,
+  "execution.open": ExecutionOpenArgsSchema,
 } as const;
 
 /** The ids whose instances carry no `args` key. */
@@ -37,6 +75,11 @@ export const NO_ARG_AFFORDANCE_IDS = [
   "billing.open",
   "orgStructure.reanalyze",
   "hris.resyncDirectory",
+  "integrations.open",
+  "hris.connect",
+  "account.editProfile",
+  "workspace.openOrgSettings",
+  "sourceSync.addFile",
 ] as const satisfies readonly AffordanceId[];
 
 type ArgsId = keyof typeof AFFORDANCE_ARGS;