@company-semantics/contracts 92.0.0 → 93.0.0

package/src/affordances/available.ts

@@ -0,0 +1,59 @@
+/**
+ * "What can I do here": the RESULT shape of the context tool (control ADR
+ * affordance-system, amended by PRD-01135).
+ *
+ * The tool reads the offer rules for the current context, drops what the
+ * viewer's policy blocks, and pairs each remaining instance with its live
+ * availability. It NEVER enumerates the catalog: existing is not a reason to
+ * offer (INV-AFFORD-RELEVANT), so an empty context returns an empty list.
+ *
+ * INVARIANTS:
+ * - POLICY-FILTERED. An entry is present only when the viewer's policy allows
+ *   it, so the shape carries no policy field and cannot leak a blocked one.
+ * - AVAILABILITY IS LIVE and non-authoritative; only the server executes.
+ * - BOUNDED and DISTINCT. At most MAX_OFFERED_AFFORDANCES entries, no
+ *   instance twice.
+ */
+import { z } from "zod";
+
+import {
+  AffordanceSchema,
+  MAX_OFFERED_AFFORDANCES,
+  sameAffordances,
+} from "./affordance";
+import { AffordanceAvailabilitySchema } from "./availability";
+
+/** One affordance the viewer may take here, with its live availability. */
+export const AvailableAffordanceSchema = z
+  .object({
+    affordance: AffordanceSchema,
+    availability: AffordanceAvailabilitySchema,
+  })
+  .strict();
+export type AvailableAffordance = z.infer<typeof AvailableAffordanceSchema>;
+
+/** The tool result: the offered, policy-allowed instances for this context. */
+export const AvailableAffordancesSchema = z
+  .object({
+    affordances: z
+      .array(AvailableAffordanceSchema)
+      .max(MAX_OFFERED_AFFORDANCES),
+  })
+  .strict()
+  .superRefine((value, ctx) => {
+    const seen = value.affordances.map((entry) => entry.affordance);
+    seen.forEach((affordance, i) => {
+      if (
+        seen
+          .slice(0, i)
+          .some((earlier) => sameAffordances([earlier], [affordance]))
+      ) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["affordances", i],
+          message: "an available affordance appears at most once",
+        });
+      }
+    });
+  });
+export type AvailableAffordances = z.infer<typeof AvailableAffordancesSchema>;

package/src/affordances/coverage.ts

@@ -0,0 +1,51 @@
+/**
+ * Reverse coverage: every capability a person can act on DECLARES its
+ * affordance, or why it has none (control ADR affordance-system, amended by
+ * PRD-01135).
+ *
+ * The forward direction (an affordance resolves to a real capability) is
+ * proven by each binding repo's architecture test. This is the reverse: a
+ * mounted backend command operation, an app navigate route or an app launch
+ * surface either names the affordance that offers it, or names a reason from a
+ * CLOSED vocabulary — so "nobody decided" is not a representable state.
+ *
+ * INVARIANTS:
+ * - CLOSED. NO_AFFORDANCE_REASONS is append-only and never prose; a reason is
+ *   a classification an architecture test can count, not an excuse.
+ * - EXACTLY ONE. A declaration is `{ affordance }` or `{ noAffordance }`,
+ *   never both (strict members of a union).
+ */
+import { z } from "zod";
+
+import { AffordanceIdSchema, type AffordanceId } from "./ids";
+
+/**
+ * Why a capability offers no affordance. Measured 2026-10-06 against backend
+ * routeRegistry (725 GET, the rest mutating; seams for auth-identity,
+ * internal-admin, test-only, webhooks and factory ingest, chat / comments
+ * inline actions) and the app's routes and launch surfaces.
+ */
+export const NO_AFFORDANCE_REASONS = [
+  /** Reads only (a POST that searches, previews or resolves); nothing to offer. */
+  "readOnly",
+  /** Performed by the control that shows it (send, post a comment, save a form). */
+  "inlineControl",
+  /** Staff-only internal administration. */
+  "internalAdmin",
+  /** Machine to machine: webhooks, ingest, station/factory, test-only. */
+  "systemOnly",
+  /** Part of sign-in, sign-up, invite acceptance or session handling. */
+  "authFlow",
+] as const;
+export type NoAffordanceReason = (typeof NO_AFFORDANCE_REASONS)[number];
+export const NoAffordanceReasonSchema = z.enum(NO_AFFORDANCE_REASONS);
+
+/** One capability's reverse-coverage declaration. */
+export type AffordanceCoverage =
+  | { readonly affordance: AffordanceId }
+  | { readonly noAffordance: NoAffordanceReason };
+
+export const AffordanceCoverageSchema = z.union([
+  z.object({ affordance: AffordanceIdSchema }).strict(),
+  z.object({ noAffordance: NoAffordanceReasonSchema }).strict(),
+]);

package/src/affordances/ids.ts

@@ -38,6 +38,34 @@ export const AFFORDANCE_IDS = [
    * workflow outcome's `review` disposition). See PROJECTED_AFFORDANCE_IDS.
    */
   "review.open",
+  // ---------------------------------------------------------------------------
+  // Burn-down wave (PRD-01137): the next steps the 2026-10-06 census found
+  // carried as prose. Appended, never inserted.
+  // ---------------------------------------------------------------------------
+  /** Open Settings → Integrations. */
+  "integrations.open",
+  /** Connect the HR system (BambooHR), or reconnect it when its sign-in died. */
+  "hris.connect",
+  /** Open the person's own profile (their name). */
+  "account.editProfile",
+  /** Open the org's settings. */
+  "workspace.openOrgSettings",
+  /** Add one file to Source Sync by hand. */
+  "sourceSync.addFile",
+  /** Open one Source Sync update (a proposal) for review, in chat. */
+  "sourceSync.openUpdate",
+  /** Open the org-structure review of one proposal (in chat). */
+  "orgStructure.openReview",
+  /** Open one chat. */
+  "chat.open",
+  /** Open one company.md document. */
+  "companyMd.openDoc",
+  /** Open one company.md document's version history. */
+  "companyMd.openHistory",
+  /** Open one team (org unit). */
+  "team.open",
+  /** Open one execution's detail (the target of an execution confirmation). */
+  "execution.open",
 ] as const;
 
 export type AffordanceId = (typeof AFFORDANCE_IDS)[number];

package/src/affordances/index.ts

@@ -6,8 +6,14 @@ export { AFFORDANCE_IDS, AffordanceIdSchema } from "./ids";
 export type { AffordanceId } from "./ids";
 export {
   AFFORDANCE_ARGS,
+  ChatOpenArgsSchema,
+  CompanyMdDocArgsSchema,
+  ExecutionOpenArgsSchema,
   NO_ARG_AFFORDANCE_IDS,
+  OrgStructureOpenReviewArgsSchema,
   ReviewOpenArgsSchema,
+  SourceSyncOpenUpdateArgsSchema,
+  TeamOpenArgsSchema,
 } from "./args";
 export type { AffordanceArgs } from "./args";
 export {
@@ -37,3 +43,14 @@ export type {
   OfferedAffordance,
   ProjectedAffordanceId,
 } from "./affordance";
+export {
+  AffordanceCoverageSchema,
+  NO_AFFORDANCE_REASONS,
+  NoAffordanceReasonSchema,
+} from "./coverage";
+export type { AffordanceCoverage, NoAffordanceReason } from "./coverage";
+export {
+  AvailableAffordanceSchema,
+  AvailableAffordancesSchema,
+} from "./available";
+export type { AvailableAffordance, AvailableAffordances } from "./available";

package/src/api/README.md

@@ -48,6 +48,7 @@ The file is committed to the repo (not .gitignored) so consumers can import type
 
 **Internal domains:**
 
+- `affordances`
 - `mcp`
 - `resource-response`
 

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 = '9937d3953931' as const;
-export const SPEC_HASH_FULL = '9937d39539319f5173df9f15191c8dc5af40aca8c8cd62a9995f7221436909d2' as const;
+export const SPEC_HASH = '4eb1b17b3340' as const;
+export const SPEC_HASH_FULL = '4eb1b17b3340b7613c5f8189f7fef55164ea1d859c67b31790297ce5709b2db4' as const;

package/src/api/generated.ts

@@ -7161,6 +7161,63 @@ export interface components {
                 } | {
                     /** @constant */
                     id: "hris.resyncDirectory";
+                } | {
+                    /** @constant */
+                    id: "integrations.open";
+                } | {
+                    /** @constant */
+                    id: "hris.connect";
+                } | {
+                    /** @constant */
+                    id: "account.editProfile";
+                } | {
+                    /** @constant */
+                    id: "workspace.openOrgSettings";
+                } | {
+                    /** @constant */
+                    id: "sourceSync.addFile";
+                } | {
+                    /** @constant */
+                    id: "sourceSync.openUpdate";
+                    args: {
+                        proposalId: string;
+                    };
+                } | {
+                    /** @constant */
+                    id: "orgStructure.openReview";
+                    args: {
+                        proposalId: string;
+                    };
+                } | {
+                    /** @constant */
+                    id: "chat.open";
+                    args: {
+                        chatId: string;
+                    };
+                } | {
+                    /** @constant */
+                    id: "companyMd.openDoc";
+                    args: {
+                        docId: string;
+                    };
+                } | {
+                    /** @constant */
+                    id: "companyMd.openHistory";
+                    args: {
+                        docId: string;
+                    };
+                } | {
+                    /** @constant */
+                    id: "team.open";
+                    args: {
+                        unitId: string;
+                    };
+                } | {
+                    /** @constant */
+                    id: "execution.open";
+                    args: {
+                        executionId: string;
+                    };
                 })[];
             } | {
                 /** @constant */
@@ -7202,6 +7259,63 @@ export interface components {
                 } | {
                     /** @constant */
                     id: "hris.resyncDirectory";
+                } | {
+                    /** @constant */
+                    id: "integrations.open";
+                } | {
+                    /** @constant */
+                    id: "hris.connect";
+                } | {
+                    /** @constant */
+                    id: "account.editProfile";
+                } | {
+                    /** @constant */
+                    id: "workspace.openOrgSettings";
+                } | {
+                    /** @constant */
+                    id: "sourceSync.addFile";
+                } | {
+                    /** @constant */
+                    id: "sourceSync.openUpdate";
+                    args: {
+                        proposalId: string;
+                    };
+                } | {
+                    /** @constant */
+                    id: "orgStructure.openReview";
+                    args: {
+                        proposalId: string;
+                    };
+                } | {
+                    /** @constant */
+                    id: "chat.open";
+                    args: {
+                        chatId: string;
+                    };
+                } | {
+                    /** @constant */
+                    id: "companyMd.openDoc";
+                    args: {
+                        docId: string;
+                    };
+                } | {
+                    /** @constant */
+                    id: "companyMd.openHistory";
+                    args: {
+                        docId: string;
+                    };
+                } | {
+                    /** @constant */
+                    id: "team.open";
+                    args: {
+                        unitId: string;
+                    };
+                } | {
+                    /** @constant */
+                    id: "execution.open";
+                    args: {
+                        executionId: string;
+                    };
                 })[];
             } | {
                 /** @constant */
@@ -7245,6 +7359,63 @@ export interface components {
                 } | {
                     /** @constant */
                     id: "hris.resyncDirectory";
+                } | {
+                    /** @constant */
+                    id: "integrations.open";
+                } | {
+                    /** @constant */
+                    id: "hris.connect";
+                } | {
+                    /** @constant */
+                    id: "account.editProfile";
+                } | {
+                    /** @constant */
+                    id: "workspace.openOrgSettings";
+                } | {
+                    /** @constant */
+                    id: "sourceSync.addFile";
+                } | {
+                    /** @constant */
+                    id: "sourceSync.openUpdate";
+                    args: {
+                        proposalId: string;
+                    };
+                } | {
+                    /** @constant */
+                    id: "orgStructure.openReview";
+                    args: {
+                        proposalId: string;
+                    };
+                } | {
+                    /** @constant */
+                    id: "chat.open";
+                    args: {
+                        chatId: string;
+                    };
+                } | {
+                    /** @constant */
+                    id: "companyMd.openDoc";
+                    args: {
+                        docId: string;
+                    };
+                } | {
+                    /** @constant */
+                    id: "companyMd.openHistory";
+                    args: {
+                        docId: string;
+                    };
+                } | {
+                    /** @constant */
+                    id: "team.open";
+                    args: {
+                        unitId: string;
+                    };
+                } | {
+                    /** @constant */
+                    id: "execution.open";
+                    args: {
+                        executionId: string;
+                    };
                 })[];
             } | {
                 /** @constant */
@@ -7288,6 +7459,63 @@ export interface components {
                 } | {
                     /** @constant */
                     id: "hris.resyncDirectory";
+                } | {
+                    /** @constant */
+                    id: "integrations.open";
+                } | {
+                    /** @constant */
+                    id: "hris.connect";
+                } | {
+                    /** @constant */
+                    id: "account.editProfile";
+                } | {
+                    /** @constant */
+                    id: "workspace.openOrgSettings";
+                } | {
+                    /** @constant */
+                    id: "sourceSync.addFile";
+                } | {
+                    /** @constant */
+                    id: "sourceSync.openUpdate";
+                    args: {
+                        proposalId: string;
+                    };
+                } | {
+                    /** @constant */
+                    id: "orgStructure.openReview";
+                    args: {
+                        proposalId: string;
+                    };
+                } | {
+                    /** @constant */
+                    id: "chat.open";
+                    args: {
+                        chatId: string;
+                    };
+                } | {
+                    /** @constant */
+                    id: "companyMd.openDoc";
+                    args: {
+                        docId: string;
+                    };
+                } | {
+                    /** @constant */
+                    id: "companyMd.openHistory";
+                    args: {
+                        docId: string;
+                    };
+                } | {
+                    /** @constant */
+                    id: "team.open";
+                    args: {
+                        unitId: string;
+                    };
+                } | {
+                    /** @constant */
+                    id: "execution.open";
+                    args: {
+                        executionId: string;
+                    };
                 })[];
             }) | null;
             error?: string;
@@ -7316,7 +7544,7 @@ export interface components {
         AffordanceStateResponse: {
             entries: {
                 /** @enum {string} */
-                id: "sourceSync.findFiles" | "integrations.connectGoogleDrive" | "sourceSync.enable" | "billing.open" | "orgStructure.reanalyze" | "hris.resyncDirectory" | "review.open";
+                id: "sourceSync.findFiles" | "integrations.connectGoogleDrive" | "sourceSync.enable" | "billing.open" | "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";
                 /** @enum {string} */
                 policy: "allowed" | "blocked";
                 availability: {
@@ -8415,6 +8643,90 @@ export interface components {
                 contextLabel: string;
                 provider: string | null;
                 href: string;
+                affordance?: {
+                    /** @constant */
+                    id: "sourceSync.findFiles";
+                } | {
+                    /** @constant */
+                    id: "integrations.connectGoogleDrive";
+                } | {
+                    /** @constant */
+                    id: "sourceSync.enable";
+                } | {
+                    /** @constant */
+                    id: "billing.open";
+                } | {
+                    /** @constant */
+                    id: "orgStructure.reanalyze";
+                } | {
+                    /** @constant */
+                    id: "hris.resyncDirectory";
+                } | {
+                    /** @constant */
+                    id: "integrations.open";
+                } | {
+                    /** @constant */
+                    id: "hris.connect";
+                } | {
+                    /** @constant */
+                    id: "account.editProfile";
+                } | {
+                    /** @constant */
+                    id: "workspace.openOrgSettings";
+                } | {
+                    /** @constant */
+                    id: "sourceSync.addFile";
+                } | {
+                    /** @constant */
+                    id: "sourceSync.openUpdate";
+                    args: {
+                        proposalId: string;
+                    };
+                } | {
+                    /** @constant */
+                    id: "orgStructure.openReview";
+                    args: {
+                        proposalId: string;
+                    };
+                } | {
+                    /** @constant */
+                    id: "chat.open";
+                    args: {
+                        chatId: string;
+                    };
+                } | {
+                    /** @constant */
+                    id: "companyMd.openDoc";
+                    args: {
+                        docId: string;
+                    };
+                } | {
+                    /** @constant */
+                    id: "companyMd.openHistory";
+                    args: {
+                        docId: string;
+                    };
+                } | {
+                    /** @constant */
+                    id: "team.open";
+                    args: {
+                        unitId: string;
+                    };
+                } | {
+                    /** @constant */
+                    id: "execution.open";
+                    args: {
+                        executionId: string;
+                    };
+                } | {
+                    /** @constant */
+                    id: "review.open";
+                    args: {
+                        /** @enum {string} */
+                        requestType: "org-structure/review" | "source-sync/candidates" | "source-sync/synthesis";
+                        requestId: string;
+                    };
+                };
                 createdAt: string;
             }[];
         };
@@ -8437,6 +8749,90 @@ export interface components {
                     contextLabel: string;
                     provider: string | null;
                     href: string;
+                    affordance?: {
+                        /** @constant */
+                        id: "sourceSync.findFiles";
+                    } | {
+                        /** @constant */
+                        id: "integrations.connectGoogleDrive";
+                    } | {
+                        /** @constant */
+                        id: "sourceSync.enable";
+                    } | {
+                        /** @constant */
+                        id: "billing.open";
+                    } | {
+                        /** @constant */
+                        id: "orgStructure.reanalyze";
+                    } | {
+                        /** @constant */
+                        id: "hris.resyncDirectory";
+                    } | {
+                        /** @constant */
+                        id: "integrations.open";
+                    } | {
+                        /** @constant */
+                        id: "hris.connect";
+                    } | {
+                        /** @constant */
+                        id: "account.editProfile";
+                    } | {
+                        /** @constant */
+                        id: "workspace.openOrgSettings";
+                    } | {
+                        /** @constant */
+                        id: "sourceSync.addFile";
+                    } | {
+                        /** @constant */
+                        id: "sourceSync.openUpdate";
+                        args: {
+                            proposalId: string;
+                        };
+                    } | {
+                        /** @constant */
+                        id: "orgStructure.openReview";
+                        args: {
+                            proposalId: string;
+                        };
+                    } | {
+                        /** @constant */
+                        id: "chat.open";
+                        args: {
+                            chatId: string;
+                        };
+                    } | {
+                        /** @constant */
+                        id: "companyMd.openDoc";
+                        args: {
+                            docId: string;
+                        };
+                    } | {
+                        /** @constant */
+                        id: "companyMd.openHistory";
+                        args: {
+                            docId: string;
+                        };
+                    } | {
+                        /** @constant */
+                        id: "team.open";
+                        args: {
+                            unitId: string;
+                        };
+                    } | {
+                        /** @constant */
+                        id: "execution.open";
+                        args: {
+                            executionId: string;
+                        };
+                    } | {
+                        /** @constant */
+                        id: "review.open";
+                        args: {
+                            /** @enum {string} */
+                            requestType: "org-structure/review" | "source-sync/candidates" | "source-sync/synthesis";
+                            requestId: string;
+                        };
+                    };
                     createdAt: string;
                 };
             } | {

package/src/api/primitives.ts

@@ -1,5 +1,10 @@
 import { z } from "zod";
 
+import {
+  AffordanceSchema,
+  MAX_OFFERED_AFFORDANCES,
+} from "../affordances/affordance";
+
 /** Generic factory for cursor-paginated responses. */
 export function CursorPageSchema<T extends z.ZodTypeAny>(itemSchema: T) {
   return z.object({
@@ -15,6 +20,14 @@ export const ErrorResponseSchema = z.object({
     code: z.string(),
     message: z.string(),
     retryable: z.boolean(),
+    /**
+     * The catalog affordances that resolve this error, when any do (control ADR
+     * affordance-system) — e.g. billing.open on a billing refusal for a viewer
+     * who may open billing. Present only when non-empty; the message states the
+     * fact and never tells the reader what to do.
+     */
+    // prettier-ignore
+    affordances: z.array(AffordanceSchema).min(1).max(MAX_OFFERED_AFFORDANCES).optional(),
   }),
 });
 

package/src/billing/README.md

@@ -221,6 +221,7 @@ owner is always its owner contradicts ADR-BE-296, and nothing imported them.
 
 **Internal domains:**
 
+- `affordances`
 - `api`
 
 **External packages:**