@company-semantics/contracts 92.0.0 → 93.1.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 = 'aebd06a13983' as const;
+export const SPEC_HASH_FULL = 'aebd06a139833549518e70adbcd3af333598cf06fa6669a838f605231395c8cf' as const;