@company-semantics/contracts 92.0.0 → 93.1.0

package/src/proactive/templates/billing-payment-past-due.ts

@@ -53,5 +53,6 @@ export const billingPaymentPastDueComposer: ProactiveChatComposer<"billingPaymen
             "What happens to my workspace if this payment stays unresolved?",
         },
       ],
+      affordances: [{ id: "billing.open" }],
     }),
   };

package/src/proactive/templates/billing-subscription-canceled.ts

@@ -47,11 +47,7 @@ export const billingSubscriptionCanceledComposer: ProactiveChatComposer<"billing
           prompt:
             "What happens to the AI funds already in my wallet after cancellation?",
         },
-        {
-          id: "resubscribe",
-          label: "How do I resubscribe?",
-          prompt: "How do I start the seat subscription again?",
-        },
       ],
+      affordances: [{ id: "billing.open" }],
     }),
   };

package/src/proactive/templates/billing-suspended.ts

@@ -49,5 +49,6 @@ export const billingSuspendedComposer: ProactiveChatComposer<"billingSuspended">
             "Is any of my workspace data at risk while this is suspended?",
         },
       ],
+      affordances: [{ id: "billing.open" }],
     }),
   };

package/src/proactive/templates/morning-brief.ts

@@ -73,5 +73,6 @@ export const morningBriefComposer: ProactiveChatComposer<"morningBrief"> = {
         prompt: "What needs a decision from me today?",
       },
     ],
+    affordances: [],
   }),
 };

package/src/proactive/templates/org-became-shared.ts

@@ -74,9 +74,9 @@ export const orgBecameSharedComposer: ProactiveChatComposer<"orgBecameShared"> =
       text:
         `${openingFor(facts)}\n\n` +
         `This is a relocation, not an addition: Integrations, Invite team ` +
-        `members, AI usage, Spending controls and Billing have moved out of My ` +
-        `settings and into Org settings. Nothing was removed — the five sections now ` +
-        `belong to the workspace rather than to you.`,
+        `members, AI usage, Spending controls and Billing have moved from your ` +
+        `own area to the workspace's. Nothing was removed — the five sections ` +
+        `now belong to the workspace rather than to you.`,
       replies: [
         {
           id: "plain-english",
@@ -96,5 +96,6 @@ export const orgBecameSharedComposer: ProactiveChatComposer<"orgBecameShared"> =
           prompt: "Who can see what in my workspace now that it is shared?",
         },
       ],
+      affordances: [{ id: "workspace.openOrgSettings" }],
     }),
   };

package/src/proactive/templates/source-sync-review-ready.ts

@@ -36,17 +36,11 @@ export const sourceSyncReviewReadyComposer: ProactiveChatComposer<"sourceSyncRev
             `strategy documents and have proposed changes for you to ` +
             `review.\n\n` +
             `Nothing has been changed. Each document is updated only when ` +
-            `you say so, as an ordinary version you can restore, and ` +
+            `you say so, as an ordinary version that can be restored, and ` +
             `anything a person has edited is left alone unless you choose ` +
             `otherwise.`) +
-        `\n\nOpen the review when you have a few minutes. If you leave it, ` +
-        `nothing happens.`,
+        `\n\nThe review waits for you. If you leave it, nothing happens.`,
       replies: [
-        {
-          id: "open-review",
-          label: "Open the review",
-          prompt: "Open the source review.",
-        },
         {
           id: "what-was-found",
           label: "What did you find?",
@@ -60,5 +54,6 @@ export const sourceSyncReviewReadyComposer: ProactiveChatComposer<"sourceSyncRev
             "If I attach a source to a document, who will be able to see it?",
         },
       ],
+      affordances: [],
     }),
   };

package/src/proactive/templates/workflow-needs-attention.ts

@@ -30,6 +30,7 @@ export const workflowNeedsAttentionComposer: ProactiveChatComposer<"workflowNeed
       title: TITLE_OF_WORKFLOW_TYPE[facts.outcome.outcome.workflowType],
       text: facts.narration,
       replies: [],
+      affordances: [],
       outcome: facts.outcome,
     }),
   };

package/src/rate-limit/README.md

@@ -35,6 +35,29 @@ interface RateLimitResult {
 }
 ```
 
+### RateLimitedErrorResponseSchema
+
+The 429 body every rate-limited response carries — exactly what backend's
+shared limiter sends, plus the reset fact:
+
+```typescript
+{
+  error: "RATE_LIMIT_EXCEEDED"; // RATE_LIMITED_ERROR_CODE
+  scope?: "email" | "ip" | "global";
+  message: string;
+  retryAfterSeconds: number | null; // whole seconds until the window resets
+}
+```
+
+The object is strict and `retryAfterSeconds` is REQUIRED: it mirrors the
+`Retry-After` header, or is null when the limiter cannot say.
+
+**Facts only.** `retryAfterSeconds` is a fact, so the message states it
+("Too many requests. Available in 30s.") and never tells the reader to retry.
+A retry control, if a surface has one, is that surface's own control label
+(control ADR affordance-system). Distinct from `ShedResponse` in
+`src/pressure.ts`, which is the load-shed body only.
+
 ## Semantic Convention
 
 This domain uses `allowed: boolean` where `true` means the request is permitted.
@@ -54,9 +77,12 @@ This is the canonical semantic across all Company Semantics repos.
 
 ## Public API
 
+- `RATE_LIMITED_ERROR_CODE`
 - `RateLimitConfig` _(type)_
 - `RateLimitResult` _(type)_
 - `RateLimitTier`
+- `RateLimitedErrorResponse` _(type)_
+- `RateLimitedErrorResponseSchema`
 
 <!-- END GENERATED: readme-public-api -->
 
@@ -70,6 +96,6 @@ _None._
 
 **External packages:**
 
-_None._
+- `zod`
 
 <!-- END GENERATED: readme-dependencies -->

package/src/rate-limit/__tests__/README.md

@@ -0,0 +1,23 @@
+# rate-limit/\_\_tests\_\_/
+
+## Purpose
+
+Locks the shape of the rate-limited error envelope.
+
+- `rate-limited-error.test.ts` — proves a rate-limited body carries
+  `retryAfterSeconds` as whole non-negative seconds or null and is refused
+  without it, refuses any code other than `RATE_LIMIT_EXCEEDED`, and that the
+  schema and code are reachable from the package root as the same binding.
+
+## Invariants
+
+- These assert VOCABULARY and SHAPE, never limiter behavior. Window sizes and
+  which routes are limited belong to backend.
+
+## Public API
+
+None — test-only.
+
+## Dependencies
+
+`vitest`, `../index` and the package root.

package/src/rate-limit/__tests__/rate-limited-error.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from "vitest";
+
+import * as root from "../../index";
+import {
+  RATE_LIMITED_ERROR_CODE,
+  RateLimitedErrorResponseSchema,
+} from "../index";
+
+const body = (fields: Record<string, unknown>) => ({
+  error: "RATE_LIMIT_EXCEEDED",
+  message: "Too many requests.",
+  ...fields,
+});
+
+describe("the rate-limited error envelope", () => {
+  it("a rate-limited body states when the window resets, or null", () => {
+    expect(
+      RateLimitedErrorResponseSchema.safeParse(body({ retryAfterSeconds: 30 }))
+        .success,
+    ).toBe(true);
+    expect(
+      RateLimitedErrorResponseSchema.safeParse(
+        body({ retryAfterSeconds: null }),
+      ).success,
+    ).toBe(true);
+  });
+
+  it("refuses a rate-limited body without retryAfterSeconds", () => {
+    expect(RateLimitedErrorResponseSchema.safeParse(body({})).success).toBe(
+      false,
+    );
+    expect(
+      RateLimitedErrorResponseSchema.safeParse(body({ retryAfterSeconds: -1 }))
+        .success,
+    ).toBe(false);
+  });
+
+  it("refuses any other code", () => {
+    expect(
+      RateLimitedErrorResponseSchema.safeParse(
+        body({ error: "FORBIDDEN", retryAfterSeconds: 3 }),
+      ).success,
+    ).toBe(false);
+    expect(RATE_LIMITED_ERROR_CODE).toBe("RATE_LIMIT_EXCEEDED");
+  });
+
+  it("is reachable from the package root", () => {
+    expect(root.RateLimitedErrorResponseSchema).toBe(
+      RateLimitedErrorResponseSchema,
+    );
+    expect(root.RATE_LIMITED_ERROR_CODE).toBe(RATE_LIMITED_ERROR_CODE);
+  });
+});

package/src/rate-limit/index.ts

@@ -1,3 +1,5 @@
+import { z } from "zod";
+
 /**
  * Rate limiting vocabulary types.
  * @see PRD-00012 for foundational implementation
@@ -21,3 +23,34 @@ export interface RateLimitResult {
   remaining: number;
   resetAt: number;
 }
+
+// =============================================================================
+// The rate-limited error envelope (owner ruling 2026-10-06: retry prose is
+// FACTS ONLY; control ADR affordance-system)
+// =============================================================================
+
+/** The error code every rate-limited response carries. */
+export const RATE_LIMITED_ERROR_CODE = "RATE_LIMIT_EXCEEDED" as const;
+
+/**
+ * A 429 body, exactly as backend's shared limiter sends it
+ * (`{ error: 'RATE_LIMIT_EXCEEDED', scope?, message }`), plus the one fact a
+ * client needs to say when the window resets.
+ *
+ * `retryAfterSeconds` mirrors the `Retry-After` header: whole seconds until the
+ * window resets, or null when the limiter cannot say. It is a FACT, so the
+ * message states it ("Too many requests. Available in 30s.") and never
+ * tells the reader to retry; a retry control, if a surface has one, is that
+ * surface's own control label.
+ */
+export const RateLimitedErrorResponseSchema = z
+  .object({
+    error: z.literal(RATE_LIMITED_ERROR_CODE),
+    scope: z.enum(["email", "ip", "global"]).optional(),
+    message: z.string(),
+    retryAfterSeconds: z.number().int().nonnegative().nullable(),
+  })
+  .strict();
+export type RateLimitedErrorResponse = z.infer<
+  typeof RateLimitedErrorResponseSchema
+>;

package/src/resource-key-tables.ts

@@ -161,6 +161,7 @@ export const SYSTEM_SCOPED_TYPES = [
   "factoryFloor",
   "factorySnapshot",
   "factoryKpis",
+  "factoryLineage",
 ] as const satisfies readonly SystemScopedType[];
 
 /** Every literal `fromQueryKey` can route, across all five tables. */

package/src/resource-key-types.ts

@@ -157,6 +157,9 @@ export type ResourceKey =
   // `useResource` disables a query whose `toQueryKey` throws, the panel it backs
   // never fetched at all. An unregistered key is not a stale read, it is no read.
   | { type: "factoryKpis"; scope: "system" }
+  // Change lineage over the release ledger (ADR-CONTRACTS-222, backend
+  // ADR-BE-926): each release with its commits, PRDs, workers, run and health.
+  | { type: "factoryLineage"; 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

package/src/resource-keys.ts

@@ -137,6 +137,7 @@ export function toQueryKey(key: ResourceKey): readonly string[] {
     case "factoryFloor":
     case "factorySnapshot":
     case "factoryKpis":
+    case "factoryLineage":
       return [key.type, key.scope] as const;
 
     default: {

package/src/root-exports/agent-runtime.ts

@@ -97,6 +97,10 @@ export type {
   WorkflowOutcomeData,
   WorkflowOutcomePart,
   WorkflowOutcomeDataPart,
+  // Affordance offer types (non-governed, the frozen offer on a pushed chat, control ADR affordance-system)
+  AffordanceOfferData,
+  AffordanceOfferPart,
+  AffordanceOfferDataPart,
   // Execution result types (Phase 5)
   ExecutionArtifactStatus,
   ExecutionResultSummary,
@@ -213,5 +217,13 @@ export type {
 
 // Rate limit domain types
 // @see PRD-00013 for contracts integration
-export type { RateLimitConfig, RateLimitResult } from "../rate-limit/index";
-export { RateLimitTier } from "../rate-limit/index";
+export type {
+  RateLimitConfig,
+  RateLimitResult,
+  RateLimitedErrorResponse,
+} from "../rate-limit/index";
+export {
+  RATE_LIMITED_ERROR_CODE,
+  RateLimitTier,
+  RateLimitedErrorResponseSchema,
+} from "../rate-limit/index";

package/src/root-exports/delivery.ts

@@ -299,13 +299,24 @@ export {
   AFFORDANCE_UNAVAILABLE_REASONS,
   AffordanceAvailabilityIdSchema,
   AffordanceAvailabilitySchema,
+  AffordanceCoverageSchema,
   AffordanceIdSchema,
   AffordanceSchema,
+  AvailableAffordanceSchema,
+  AvailableAffordancesSchema,
+  ChatOpenArgsSchema,
+  CompanyMdDocArgsSchema,
+  ExecutionOpenArgsSchema,
   MAX_OFFERED_AFFORDANCES,
+  NO_AFFORDANCE_REASONS,
   NO_ARG_AFFORDANCE_IDS,
+  NoAffordanceReasonSchema,
   OfferedAffordanceSchema,
+  OrgStructureOpenReviewArgsSchema,
   PROJECTED_AFFORDANCE_IDS,
   ReviewOpenArgsSchema,
+  SourceSyncOpenUpdateArgsSchema,
+  TeamOpenArgsSchema,
   sameAffordances,
 } from "../affordances/index";
 
@@ -315,8 +326,12 @@ export type {
   AffordanceAvailability,
   AffordanceAvailabilityId,
   AffordanceBindingKind,
+  AffordanceCoverage,
   AffordanceId,
   AffordanceUnavailableReason,
+  AvailableAffordance,
+  AvailableAffordances,
+  NoAffordanceReason,
   OfferedAffordance,
   ProjectedAffordanceId,
 } from "../affordances/index";