@company-semantics/contracts 90.0.0 → 91.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "90.0.0",
+  "version": "91.1.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -127,7 +127,7 @@
     "generate:openapi-routes": "tsx scripts/generate-openapi-routes.ts",
     "generate:openapi-routes:check": "tsx scripts/generate-openapi-routes.ts --check",
     "generate:api-types:check": "openapi-typescript openapi/backend.yaml -o /tmp/cs-api-types-check.ts && diff -q src/api/generated.ts /tmp/cs-api-types-check.ts",
-    "generate:current": "tsx \"$(git rev-parse --path-format=absolute --git-common-dir)/../../company-semantics-ci/scripts/generate-current.ts\"",
+    "generate:current": "tsx \"$(git rev-parse --path-format=absolute --git-common-dir)/../../company-semantics-ci/scripts/generate-current.ts\" --write",
     "adr:new": "tsx \"$(git rev-parse --path-format=absolute --git-common-dir)/../../company-semantics-control/scripts/adr/adr-new-cli.ts\"",
     "repo-map": "tsx \"$(git rev-parse --path-format=absolute --git-common-dir)/../../company-semantics-ci/scripts/generate-repo-map.ts\" --roots src --name company-semantics-contracts --write",
     "sync:workflow-pins": "tsx \"$(git rev-parse --path-format=absolute --git-common-dir)/../../company-semantics-ci/scripts/sync-workflow-pins.ts\" --write",

package/src/affordances/README.md

@@ -0,0 +1,65 @@
+# affordances/
+
+The closed vocabulary of next steps the product may offer a person or the
+agent (control ADR `affordance-system`).
+
+## Purpose
+
+An affordance names an action the product can actually perform: find files
+again, connect Google Drive, turn Source Sync on, open billing, re-run the
+org-structure analysis, resync the HR directory, open a review. This directory
+holds that vocabulary — the ids, the arguments each id carries, the kind of
+capability each one is bound to and the live condition its availability is
+read from — so every producer, validator and renderer agrees on it.
+
+Contracts carries no copy, label, route, operationId or policy key for an
+affordance. Bindings are proven in the repo that owns them; contracts carries
+only the binding KIND.
+
+## Invariants
+
+- **Offered only by a rule, never because it exists** (INV-AFFORD-RELEVANT).
+  An affordance is offered only by a domain-owned, deterministic offer rule
+  that relates a domain state to it (for workflows, the per-reason tables in
+  `src/workflows/`). Being in this vocabulary, or being permitted, never offers
+  it. Neither a model nor a renderer invents, infers or searches for one.
+- **Instances, not bare ids.** An affordance is `{ id, args? }`. An id that
+  takes arguments (`review.open`) requires them; an id that takes none has NO
+  `args` key at all (strict), so persisted JSON round-trips unchanged. There is
+  no undefined-valued schema anywhere here: Zod 4's JSON-schema conversion
+  refuses one, and the backend's OpenAPI generation converts every route
+  schema that carries an outcome.
+- **Closed and append-only.** Ids are persisted inside immutable workflow
+  outcomes and chat parts; removing one orphans every record that carries it.
+- **Grounded** (INV-AFFORD-GROUNDED). Every id declares a binding kind
+  (`command`, `navigate`, `surface`) and the owning repo proves the binding
+  exists with an architecture test.
+- **`review.open` is a projection.** It is derived from authoritative state
+  already persisted elsewhere (a workflow outcome's `review` disposition) and
+  is never persisted inside an offer — `OfferedAffordanceSchema` refuses it.
+- **Availability is live and non-authoritative** (INV-AFFORD-FOUR-STATES).
+  `available | already_satisfied | unavailable` (with a closed reason) is read
+  at render time; it never mutates a frozen offer, and only the server decides
+  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.
+
+## Public API
+
+- `AFFORDANCE_IDS`, `AffordanceId`, `AffordanceIdSchema` (`ids.ts`).
+- `AFFORDANCE_ARGS`, `NO_ARG_AFFORDANCE_IDS`, `ReviewOpenArgsSchema`,
+  `AffordanceArgs` (`args.ts`).
+- `AFFORDANCE_BINDING_KINDS`, `AFFORDANCE_AVAILABILITY_IDS`,
+  `AffordanceAvailabilityIdSchema`, `AFFORDANCE_UNAVAILABLE_REASONS`,
+  `AffordanceAvailabilitySchema` and their types (`availability.ts`).
+- `Affordance`, `OfferedAffordance`, `ProjectedAffordanceId`,
+  `AffordanceSchema`, `OfferedAffordanceSchema`, `PROJECTED_AFFORDANCE_IDS`,
+  `AFFORDANCE_BINDING_KIND_OF`, `AFFORDANCE_AVAILABILITY_OF`,
+  `MAX_OFFERED_AFFORDANCES`, `sameAffordances` (`affordance.ts`).
+
+Published from the package root through `src/root-exports/delivery.ts`.
+
+## Dependencies
+
+`zod` and `../input-requests/types` (the request types `review.open` addresses).
+Otherwise pure vocabulary data and one pure comparison helper.

package/src/affordances/__tests__/README.md

@@ -0,0 +1,30 @@
+# affordances/\_\_tests\_\_/
+
+## Purpose
+
+Locks the affordance vocabulary and the shape of an affordance instance.
+
+- `affordances.test.ts` — pins the exact membership and order of the ids,
+  availability ids, unavailable reasons and binding kinds; proves an id with no
+  args parses with no `args` key and refuses one, `review.open` requires a
+  registered request type and a non-empty id, a projected id is never an
+  offered one, every id declares a binding kind and an availability id (or
+  null), unavailable carries a closed reason, offers compare by id, order and
+  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.
+
+## Invariants
+
+- These assert VOCABULARY and SHAPE, never behavior. Which affordance a domain
+  offers belongs to that domain's offer rules and their tests.
+- Membership pins are intentionally exact: a removed id orphans every persisted
+  record that carries it.
+
+## Public API
+
+None — test-only.
+
+## Dependencies
+
+`vitest`, `zod`, `../index`, `../../workflows/outcome` and the package root.

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

@@ -0,0 +1,251 @@
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+
+import { WorkflowOutcomeSchema } from "../../workflows/outcome";
+import * as root from "../../index";
+import * as barrel from "../index";
+import {
+  AFFORDANCE_AVAILABILITY_IDS,
+  AFFORDANCE_AVAILABILITY_OF,
+  AFFORDANCE_BINDING_KINDS,
+  AFFORDANCE_BINDING_KIND_OF,
+  AFFORDANCE_IDS,
+  AFFORDANCE_ARGS,
+  AFFORDANCE_UNAVAILABLE_REASONS,
+  AffordanceAvailabilitySchema,
+  AffordanceSchema,
+  NO_ARG_AFFORDANCE_IDS,
+  OfferedAffordanceSchema,
+  PROJECTED_AFFORDANCE_IDS,
+  sameAffordances,
+  type Affordance,
+} from "../index";
+
+// Compile-time: the schema's output is exactly the Affordance type.
+type Equals<A, B> =
+  (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2
+    ? true
+    : false;
+const schemaMatchesType: Equals<
+  Readonly<z.infer<typeof AffordanceSchema>>,
+  Affordance
+> = true;
+
+describe("affordance vocabulary", () => {
+  it("names the seven affordances, in order", () => {
+    expect(AFFORDANCE_IDS).toEqual([
+      "sourceSync.findFiles",
+      "integrations.connectGoogleDrive",
+      "sourceSync.enable",
+      "billing.open",
+      "orgStructure.reanalyze",
+      "hris.resyncDirectory",
+      "review.open",
+    ]);
+    expect(schemaMatchesType).toBe(true);
+  });
+
+  it("names the four availability ids and the four unavailable reasons, in order", () => {
+    expect(AFFORDANCE_AVAILABILITY_IDS).toEqual([
+      "sourceSync.discoveryIdle",
+      "integrations.googleDriveDisconnected",
+      "sourceSync.disabled",
+      "hris.connected",
+    ]);
+    expect(AFFORDANCE_UNAVAILABLE_REASONS).toEqual([
+      "conflicting_operation",
+      "missing_dependency",
+      "resource_gone",
+      "temporarily_disabled",
+    ]);
+    expect(AFFORDANCE_BINDING_KINDS).toEqual([
+      "command",
+      "navigate",
+      "surface",
+    ]);
+  });
+
+  it("an affordance without args parses with no args key", () => {
+    expect(AffordanceSchema.safeParse({ id: "billing.open" }).success).toBe(
+      true,
+    );
+    expect(
+      AffordanceSchema.safeParse({ id: "billing.open", args: {} }).success,
+    ).toBe(false);
+  });
+
+  it("the affordance schema converts to JSON Schema", () => {
+    // The backend's scripts/generate-openapi.ts converts route schemas with
+    // z.toJSONSchema(schema, { io: "input" }); Zod 4 throws on an
+    // undefined-valued schema. Mirror that call on everything a route carries.
+    for (const schema of [
+      AffordanceSchema,
+      OfferedAffordanceSchema,
+      AffordanceAvailabilitySchema,
+      WorkflowOutcomeSchema,
+    ]) {
+      expect(() => z.toJSONSchema(schema, { io: "input" })).not.toThrow();
+    }
+  });
+
+  it("every id either takes args or is listed as taking none, never both", () => {
+    const withArgs = Object.keys(AFFORDANCE_ARGS);
+    expect([...withArgs, ...NO_ARG_AFFORDANCE_IDS].sort()).toEqual(
+      [...AFFORDANCE_IDS].sort(),
+    );
+    for (const id of NO_ARG_AFFORDANCE_IDS) expect(withArgs).not.toContain(id);
+  });
+
+  it("refuses an args key on an affordance that takes none", () => {
+    expect(
+      AffordanceSchema.safeParse({ id: "sourceSync.findFiles", args: null })
+        .success,
+    ).toBe(false);
+  });
+
+  it("review.open requires a registered request type and an id", () => {
+    const ok = {
+      id: "review.open",
+      args: { requestType: "source-sync/candidates", requestId: "set-1" },
+    };
+    expect(AffordanceSchema.safeParse(ok).success).toBe(true);
+    expect(AffordanceSchema.safeParse({ id: "review.open" }).success).toBe(
+      false,
+    );
+    expect(
+      AffordanceSchema.safeParse({
+        id: "review.open",
+        args: { requestType: "candidates", requestId: "set-1" },
+      }).success,
+    ).toBe(false);
+    expect(
+      AffordanceSchema.safeParse({
+        id: "review.open",
+        args: { requestType: "source-sync/candidates", requestId: "" },
+      }).success,
+    ).toBe(false);
+  });
+
+  it("refuses an unknown affordance id", () => {
+    expect(AffordanceSchema.safeParse({ id: "billing.addFunds" }).success).toBe(
+      false,
+    );
+  });
+
+  it("a projected affordance is never an offered one", () => {
+    for (const id of PROJECTED_AFFORDANCE_IDS) {
+      expect(
+        OfferedAffordanceSchema.safeParse({
+          id,
+          args: { requestType: "org-structure/review", requestId: "p-1" },
+        }).success,
+      ).toBe(false);
+    }
+  });
+
+  it("every affordance declares a binding kind and an availability id or null", () => {
+    expect(Object.keys(AFFORDANCE_BINDING_KIND_OF).sort()).toEqual(
+      [...AFFORDANCE_IDS].sort(),
+    );
+    expect(Object.keys(AFFORDANCE_AVAILABILITY_OF).sort()).toEqual(
+      [...AFFORDANCE_IDS].sort(),
+    );
+    for (const id of AFFORDANCE_IDS) {
+      expect(AFFORDANCE_BINDING_KINDS).toContain(
+        AFFORDANCE_BINDING_KIND_OF[id],
+      );
+      const availability = AFFORDANCE_AVAILABILITY_OF[id];
+      if (availability !== null) {
+        expect(AFFORDANCE_AVAILABILITY_IDS).toContain(availability);
+      }
+    }
+  });
+
+  it("unavailable carries a closed reason; available and already_satisfied carry none", () => {
+    expect(
+      AffordanceAvailabilitySchema.safeParse({ state: "available" }).success,
+    ).toBe(true);
+    expect(
+      AffordanceAvailabilitySchema.safeParse({ state: "already_satisfied" })
+        .success,
+    ).toBe(true);
+    expect(
+      AffordanceAvailabilitySchema.safeParse({
+        state: "unavailable",
+        reason: "conflicting_operation",
+      }).success,
+    ).toBe(true);
+    expect(
+      AffordanceAvailabilitySchema.safeParse({ state: "unavailable" }).success,
+    ).toBe(false);
+    expect(
+      AffordanceAvailabilitySchema.safeParse({
+        state: "unavailable",
+        reason: "Drive is busy",
+      }).success,
+    ).toBe(false);
+    expect(
+      AffordanceAvailabilitySchema.safeParse({
+        state: "available",
+        reason: "conflicting_operation",
+      }).success,
+    ).toBe(false);
+  });
+
+  it("compares offers by id, order and canonical args", () => {
+    const a: Affordance[] = [
+      { id: "billing.open" },
+      { id: "sourceSync.enable" },
+    ];
+    expect(
+      sameAffordances(a, [{ id: "billing.open" }, { id: "sourceSync.enable" }]),
+    ).toBe(true);
+    expect(
+      sameAffordances(a, [{ id: "sourceSync.enable" }, { id: "billing.open" }]),
+    ).toBe(false);
+    expect(sameAffordances(a, [{ id: "billing.open" }])).toBe(false);
+    expect(
+      sameAffordances(
+        [
+          {
+            id: "review.open",
+            args: { requestType: "org-structure/review", requestId: "p" },
+          },
+        ],
+        [
+          {
+            id: "review.open",
+            args: { requestId: "p", requestType: "org-structure/review" },
+          },
+        ],
+      ),
+    ).toBe(true);
+  });
+
+  it("every affordance name is reachable from the package root as the same binding", () => {
+    for (const name of [
+      "AFFORDANCE_IDS",
+      "AFFORDANCE_ARGS",
+      "AFFORDANCE_AVAILABILITY_IDS",
+      "AFFORDANCE_AVAILABILITY_OF",
+      "AFFORDANCE_BINDING_KINDS",
+      "AFFORDANCE_BINDING_KIND_OF",
+      "AFFORDANCE_UNAVAILABLE_REASONS",
+      "AffordanceIdSchema",
+      "AffordanceSchema",
+      "AffordanceAvailabilityIdSchema",
+      "AffordanceAvailabilitySchema",
+      "MAX_OFFERED_AFFORDANCES",
+      "NO_ARG_AFFORDANCE_IDS",
+      "OfferedAffordanceSchema",
+      "PROJECTED_AFFORDANCE_IDS",
+      "ReviewOpenArgsSchema",
+      "sameAffordances",
+    ] 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

@@ -0,0 +1,124 @@
+/**
+ * An affordance INSTANCE (`{ id, args? }`) and the catalog facts every
+ * consumer must agree on: its binding kind and the live condition its
+ * availability is read from (control ADR affordance-system).
+ *
+ * INVARIANTS:
+ * - An instance carries `args` exactly when its id takes them; an id that takes
+ *   none has NO `args` key (strict), so persisted JSON round-trips unchanged.
+ * - A PROJECTED id (`review.open`) is derived from other authoritative persisted
+ *   state and is never persisted inside an offer (`OfferedAffordanceSchema`
+ *   refuses it): one fact, one stored place.
+ * - `MAX_OFFERED_AFFORDANCES` is a SANITY bound against a pathological
+ *   producer. How many a surface shows is that surface's presentation cap.
+ */
+import { z } from "zod";
+
+import { ReviewOpenArgsSchema, type AffordanceArgs } from "./args";
+import type {
+  AffordanceAvailabilityId,
+  AffordanceBindingKind,
+} from "./availability";
+import type { AffordanceId } from "./ids";
+
+/** Sanity bound on one offer. Never a presentation cap. */
+export const MAX_OFFERED_AFFORDANCES = 16;
+
+/** One affordance instance: an id and, when the id takes them, its args. */
+export type Affordance = {
+  [K in AffordanceId]: AffordanceArgs[K] extends undefined
+    ? { readonly id: K }
+    : { readonly id: K; readonly args: AffordanceArgs[K] };
+}[AffordanceId];
+
+/** Ids derived from other persisted state, never stored in an offer. */
+export const PROJECTED_AFFORDANCE_IDS = ["review.open"] as const;
+export type ProjectedAffordanceId = (typeof PROJECTED_AFFORDANCE_IDS)[number];
+
+/** An affordance a domain offer rule may produce and persist. */
+export type OfferedAffordance = Exclude<
+  Affordance,
+  { readonly id: ProjectedAffordanceId }
+>;
+
+const noArgs = <K extends AffordanceId>(id: K) =>
+  z.object({ id: z.literal(id) }).strict();
+
+const OFFERED_MEMBERS = [
+  noArgs("sourceSync.findFiles"),
+  noArgs("integrations.connectGoogleDrive"),
+  noArgs("sourceSync.enable"),
+  noArgs("billing.open"),
+  noArgs("orgStructure.reanalyze"),
+  noArgs("hris.resyncDirectory"),
+] 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(),
+]);
+
+/** What may be persisted inside an offer: every member except a projection. */
+export const OfferedAffordanceSchema = z.discriminatedUnion(
+  "id",
+  OFFERED_MEMBERS,
+);
+
+/** Which kind of capability each affordance is bound to. */
+export const AFFORDANCE_BINDING_KIND_OF = {
+  "sourceSync.findFiles": "command",
+  "integrations.connectGoogleDrive": "command",
+  "sourceSync.enable": "command",
+  "billing.open": "navigate",
+  "orgStructure.reanalyze": "command",
+  "hris.resyncDirectory": "command",
+  "review.open": "surface",
+} as const satisfies Record<AffordanceId, AffordanceBindingKind>;
+
+/** The live condition each affordance's availability is read from, if any. */
+export const AFFORDANCE_AVAILABILITY_OF = {
+  "sourceSync.findFiles": "sourceSync.discoveryIdle",
+  "integrations.connectGoogleDrive": "integrations.googleDriveDisconnected",
+  "sourceSync.enable": "sourceSync.disabled",
+  "billing.open": null,
+  // The route joins an active run instead of refusing, so nothing to read.
+  "orgStructure.reanalyze": null,
+  "hris.resyncDirectory": "hris.connected",
+  "review.open": null,
+} as const satisfies Record<AffordanceId, AffordanceAvailabilityId | null>;
+
+/**
+ * Whether two offers are the same: same length, same ids in the same order,
+ * and canonically equal args (keys sorted). Order is part of an offer — the
+ * producing rule owns it.
+ */
+export function sameAffordances(
+  a: readonly Affordance[],
+  b: readonly Affordance[],
+): boolean {
+  if (a.length !== b.length) return false;
+  return a.every((left, i) => {
+    const right = b[i];
+    return (
+      right !== undefined &&
+      left.id === right.id &&
+      canonical(argsOf(left)) === canonical(argsOf(right))
+    );
+  });
+}
+
+function argsOf(affordance: Affordance): unknown {
+  return "args" in affordance ? affordance.args : undefined;
+}
+
+function canonical(value: unknown): string {
+  if (value === undefined) return "";
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  const entries = Object.entries(value as Record<string, unknown>).sort(
+    ([x], [y]) => (x < y ? -1 : x > y ? 1 : 0),
+  );
+  return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonical(v)}`).join(",")}}`;
+}

package/src/affordances/args.ts

@@ -0,0 +1,59 @@
+/**
+ * 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.
+ */
+import { z } from "zod";
+
+import { INPUT_REQUEST_TYPES } from "../input-requests/types";
+import type { AffordanceId } from "./ids";
+
+/** `review.open`: which review, by its input-request type and id. */
+export const ReviewOpenArgsSchema = z
+  .object({
+    requestType: z.enum(INPUT_REQUEST_TYPES),
+    requestId: 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
+ * is deliberately no way to write an undefined-valued args schema here, because
+ * Zod 4's JSON-schema conversion refuses one ("Undefined cannot be represented
+ * in JSON Schema") and the backend's OpenAPI generation converts every route
+ * schema that carries an outcome.
+ */
+export const AFFORDANCE_ARGS = {
+  "review.open": ReviewOpenArgsSchema,
+} as const;
+
+/** The ids whose instances carry no `args` key. */
+export const NO_ARG_AFFORDANCE_IDS = [
+  "sourceSync.findFiles",
+  "integrations.connectGoogleDrive",
+  "sourceSync.enable",
+  "billing.open",
+  "orgStructure.reanalyze",
+  "hris.resyncDirectory",
+] as const satisfies readonly AffordanceId[];
+
+type ArgsId = keyof typeof AFFORDANCE_ARGS;
+type NoArgId = (typeof NO_ARG_AFFORDANCE_IDS)[number];
+
+// Type-level totality: every id is EITHER in AFFORDANCE_ARGS or in
+// NO_ARG_AFFORDANCE_IDS, never both, never neither.
+type Missing = Exclude<AffordanceId, ArgsId | NoArgId>;
+type Both = Extract<ArgsId, NoArgId>;
+const argsCoverEveryIdOnce: [Missing, Both] extends [never, never]
+  ? true
+  : never = true;
+void argsCoverEveryIdOnce;
+
+/** The arguments of each affordance; `undefined` for one that takes none. */
+export type AffordanceArgs = {
+  readonly [K in AffordanceId]: K extends ArgsId
+    ? z.infer<(typeof AFFORDANCE_ARGS)[K]>
+    : undefined;
+};

package/src/affordances/availability.ts

@@ -0,0 +1,78 @@
+/**
+ * How an offered affordance relates to the world right now, and how it is
+ * bound to the thing that performs it.
+ *
+ * Availability is LIVE and NON-AUTHORITATIVE (INV-AFFORD-FOUR-STATES): it never
+ * mutates a frozen offer, and only the server decides whether an action
+ * executes. It exists so an old offer can read "already connected" instead of
+ * a stale button, and so a disabled control says why in a closed reason rather
+ * than prose.
+ */
+import { z } from "zod";
+
+/** What an affordance is bound to. The owning repo proves each binding exists. */
+export const AFFORDANCE_BINDING_KINDS = [
+  /** A mounted backend route (by operationId). */
+  "command",
+  /** An app route (`Route["type"]`). */
+  "navigate",
+  /** An app launch surface (a `LaunchAnchor` kind). */
+  "surface",
+] as const;
+export type AffordanceBindingKind = (typeof AFFORDANCE_BINDING_KINDS)[number];
+
+/** The live conditions an affordance's availability is read from. */
+export const AFFORDANCE_AVAILABILITY_IDS = [
+  /**
+   * Whether a new drive search could start now: `unavailable`
+   * (`conflicting_operation`) while one runs, `unavailable`
+   * (`missing_dependency`) when Drive is not connected or Source Sync is off.
+   */
+  "sourceSync.discoveryIdle",
+  /**
+   * Whether Google Drive still needs connecting: `already_satisfied` when it is
+   * connected and its sign-in works.
+   */
+  "integrations.googleDriveDisconnected",
+  /** Whether Source Sync is still off: `already_satisfied` when it is on. */
+  "sourceSync.disabled",
+  /**
+   * Whether the HR directory can be synced: `unavailable`
+   * (`missing_dependency`) when no HR directory is connected, `unavailable`
+   * (`conflicting_operation`) while a sync runs.
+   */
+  "hris.connected",
+] as const;
+export type AffordanceAvailabilityId =
+  (typeof AFFORDANCE_AVAILABILITY_IDS)[number];
+export const AffordanceAvailabilityIdSchema = z.enum(
+  AFFORDANCE_AVAILABILITY_IDS,
+);
+
+/** Why an offered affordance cannot be taken right now. Closed: never prose. */
+export const AFFORDANCE_UNAVAILABLE_REASONS = [
+  /** Another operation that conflicts with this one is running. */
+  "conflicting_operation",
+  /** Something this action depends on is missing (a connection, a setting). */
+  "missing_dependency",
+  /** The thing the action addresses no longer exists. */
+  "resource_gone",
+  /** The action is switched off for now. */
+  "temporarily_disabled",
+] as const;
+export type AffordanceUnavailableReason =
+  (typeof AFFORDANCE_UNAVAILABLE_REASONS)[number];
+
+export const AffordanceAvailabilitySchema = z.discriminatedUnion("state", [
+  z.object({ state: z.literal("available") }).strict(),
+  z.object({ state: z.literal("already_satisfied") }).strict(),
+  z
+    .object({
+      state: z.literal("unavailable"),
+      reason: z.enum(AFFORDANCE_UNAVAILABLE_REASONS),
+    })
+    .strict(),
+]);
+export type AffordanceAvailability = z.infer<
+  typeof AffordanceAvailabilitySchema
+>;

package/src/affordances/ids.ts

@@ -0,0 +1,45 @@
+/**
+ * The affordance vocabulary: every next step the product may OFFER a person
+ * or the agent (control ADR affordance-system).
+ *
+ * An affordance names an action the product can actually perform. Existing
+ * here is never a reason to offer it: an affordance is offered only by a
+ * domain-owned, deterministic offer rule that relates a domain state to it
+ * (INV-AFFORD-RELEVANT). Neither a model nor a renderer invents, infers or
+ * searches for one.
+ *
+ * INVARIANTS:
+ * - `{domain}.{action}` names, camelCase after the dot. A member is persisted
+ *   inside immutable workflow outcomes and chat parts, so the set is CLOSED and
+ *   append-only: removing one orphans every record that carries it.
+ * - GROUNDED. Every member has a binding kind (`AFFORDANCE_BINDING_KIND_OF` in
+ *   ./affordance) and the repo that owns the binding proves it exists with an
+ *   architecture test: a mounted backend route for `command`, an app `Route`
+ *   for `navigate`, an app launch surface for `surface` (INV-AFFORD-GROUNDED).
+ */
+import { z } from "zod";
+
+export const AFFORDANCE_IDS = [
+  /** Start a new search of the connected drive (Source Sync discovery). */
+  "sourceSync.findFiles",
+  /** Connect Google Drive, or reconnect it when its sign-in stopped working. */
+  "integrations.connectGoogleDrive",
+  /** Turn Source Sync on for the org. */
+  "sourceSync.enable",
+  /** Open the org's billing page. */
+  "billing.open",
+  /** Run the org-structure analysis again. */
+  "orgStructure.reanalyze",
+  /** Sync the HR directory again. */
+  "hris.resyncDirectory",
+  /**
+   * Open a review (an input request) in chat. PROJECTED, never persisted in an
+   * offer: it is derived from authoritative state already stored elsewhere (a
+   * workflow outcome's `review` disposition). See PROJECTED_AFFORDANCE_IDS.
+   */
+  "review.open",
+] as const;
+
+export type AffordanceId = (typeof AFFORDANCE_IDS)[number];
+
+export const AffordanceIdSchema = z.enum(AFFORDANCE_IDS);