@company-semantics/contracts 92.0.0 → 93.0.0

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/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";