@company-semantics/contracts 91.1.0 → 93.0.0

package/src/api/generated.ts

@@ -4936,7 +4936,7 @@ export interface paths {
         put?: never;
         /**
          * Approve the draft candidate set as reviewed, per scope
-         * @description Approves the named scopes (or every scope still open) at the revision the person reviewed. Per scope, the items freeze, a hash binds them to that scope’s share of the spending cap, and a landing job is scheduled on one landing-and-synthesis workflow.
+         * @description Approves the named scopes (or every scope still open) at the revision the person reviewed. Per scope, the items freeze, a hash binds the approval to exactly those files and treatments, and a landing job is scheduled on one landing-and-synthesis workflow. Approval authorizes the revision only; it carries no spend.
          */
         post: operations["approveSourceCandidateSet"];
         delete?: never;
@@ -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 */
@@ -7169,7 +7226,7 @@ export interface components {
                 /** @enum {string} */
                 kind: "produced" | "empty" | "partial" | "stopped" | "failed" | "abandoned" | "unknown";
                 /** @enum {string} */
-                reason: "updates_ready" | "updates_applied" | "stopped_by_user" | "paused_billing" | "synthesis_incomplete" | "approval_mismatch" | "landing_refused" | "standing_order_refused" | "no_connection" | "source_sync_off" | "internal_error" | "abandoned" | "unrecognized_terminal_state";
+                reason: "updates_ready" | "updates_applied" | "stopped_by_user" | "paused_billing" | "run_ceiling_reached" | "pricing_unconfigured" | "synthesis_incomplete" | "approval_mismatch" | "landing_refused" | "standing_order_refused" | "no_connection" | "source_sync_off" | "internal_error" | "abandoned" | "unrecognized_terminal_state";
                 facts: {
                     scopeCount: number;
                     violationCount: number;
@@ -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;
                 };
             } | {
@@ -9829,11 +10225,6 @@ export interface components {
                 } | null;
                 approvedAt: string | null;
             }[];
-            estimate: {
-                lowMicroUsd: string;
-                highMicroUsd: string;
-                capMicroUsd: string;
-            } | null;
             discovery: {
                 foundThisRun: number;
                 retainedDecisions: number;
@@ -9909,7 +10300,7 @@ export interface components {
                 workflowId: string;
                 batchId: string | null;
                 /** @enum {string} */
-                phase: "landing" | "drafting" | "waiting_for_review" | "paused_billing" | "applied" | "applied_partial" | "failed" | "closed";
+                phase: "landing" | "drafting" | "waiting_for_review" | "paused_billing" | "paused_ceiling" | "applied" | "applied_partial" | "failed" | "closed";
                 fileCount: number | null;
                 proposedDocumentCount: number;
                 appliedAt: string | null;
@@ -19984,7 +20375,6 @@ export interface operations {
             content: {
                 "application/json": {
                     revision: number;
-                    spendCapMicroUsd: string;
                     scopeKeys?: string[];
                 };
             };
@@ -19999,7 +20389,7 @@ export interface operations {
                     "application/json": components["schemas"]["SourceSyncApproveResponse"];
                 };
             };
-            /** @description Invalid request, a scope with no files (SOURCE_SYNC_SCOPE_UNKNOWN), or a cap too large to hold exactly (SOURCE_SYNC_SPEND_CAP_INVALID) */
+            /** @description Invalid request (an unknown field such as a spend cap is refused by the schema), or a scope with no files (SOURCE_SYNC_SCOPE_UNKNOWN) */
             400: {
                 headers: {
                     [name: string]: unknown;

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:**

package/src/billing/refusals.ts

@@ -40,6 +40,11 @@
  */
 import { z } from "zod";
 
+import {
+  AffordanceSchema,
+  MAX_OFFERED_AFFORDANCES,
+} from "../affordances/affordance";
+
 import { type AiPauseReason } from "./vocabulary";
 
 /* -------------------------------------------------------------------------- */
@@ -216,5 +221,12 @@ export const BillingRefusalPartSchema = z
     orgId: z.string(),
     /** Whether retrying the same turn could succeed once the cause clears. */
     retryable: z.boolean(),
+    /**
+     * The catalog affordances that resolve the refusal for this viewer (control
+     * ADR affordance-system), e.g. billing.open. Present only when non-empty;
+     * the app renders them as controls beside the code's fact.
+     */
+    // prettier-ignore
+    affordances: z.array(AffordanceSchema).min(1).max(MAX_OFFERED_AFFORDANCES).optional(),
   })
   .strict();

package/src/message-parts/README.md

@@ -17,6 +17,7 @@ Canonical vocabulary for structured assistant message output. Defines the type s
 - `SuggestedRepliesPart` is a surface but NOT a governed one: a chip fires an ordinary user turn (no `executionId`, no `submitEndpoint`), is stateless (clicking never consumes it) and advisory (the composer stays enabled) — so it is outside the at-most-one-governed-surface-per-turn rule
 - `WorkflowProgressPart` is the second non-governed surface: a two-field ANCHOR (`workflowId`, `workflowType`) to a durable background workflow. It presents no decision, carries no result snapshot (minted at t=0; parts are never rewritten) and no `startedAt` (operational state stays off immutable content), and names no domain vocabulary — live state is hydrated from the generic workflow projection read
 - `InputRequestPart` (`data-input-request` on the wire) is the GENERIC, GOVERNED anchor for a reviewed request: `{ requestType, requestId, stepCount, withheldCount }`, with every invariant of the structure-review anchor (anchor only — no cards, no endpoints, no staleness hashes; counts against the at-most-one-governed-surface-per-turn rule; emission is orchestration-driven). `isInputRequestDataPartShape` checks `requestType` as a non-empty string, NOT as a member of `INPUT_REQUEST_TYPES`: an unknown type renders nothing but never invalidates a persisted part
+- `AffordanceOfferPart` (`data-affordance-offer` on the wire) is the fourth non-governed surface: the next steps a pushed chat OFFERS, frozen with it as `OfferedAffordance` instances (control ADR `affordance-system`). Ids and args only — never labels, hrefs or a projected id (`review.open`), at most `MAX_OFFERED_AFFORDANCES`; written once with its message and never re-derived; the app renders each as a real control, re-gated per viewer. Built by `WireSurfaceBuilder.affordanceOffer`; emission is orchestration-driven (the proactive chat writer), never a model choice
 - `StructureReviewPart` (`data-structure-review`) is FROZEN, not retired: it stays in `SurfacePart` and parses forever because persisted transcripts carry it, and org-structure keeps emitting it
 
 <!-- BEGIN GENERATED: readme-public-api — derived from code by `pnpm readme-api`. Do not edit. -->
@@ -24,6 +25,9 @@ Canonical vocabulary for structured assistant message output. Defines the type s
 ## Public API
 
 - `AddPartResult` _(type)_ — Result of adding a part to the builder.
+- `AffordanceOfferData` _(type)_ — Affordance offer data payload: the frozen, ordered offer.
+- `AffordanceOfferDataPart` _(type)_ — Affordance offer data part (wire format, as persisted in `chat_messages.parts`).
+- `AffordanceOfferPart` _(type)_ — Affordance offer message part (semantic type, as rendered).
 - `AssistantMessagePart` _(type)_ — All assistant message part types.
 - `CONFIRMATION_LABELS` — Human-readable confirmation dialog titles for each execution kind.
 - `CandidateSource` _(type)_ — How the frontend sources candidate values for an editable field. - `inline`: the options are shipped with the…
@@ -116,6 +120,7 @@ Canonical vocabulary for structured assistant message output. Defines the type s
 
 **Internal domains:**
 
+- `affordances`
 - `chat`
 - `execution`
 - `input-requests`

package/src/message-parts/affordance-offer.ts

@@ -0,0 +1,44 @@
+/**
+ * Affordance Offer Part Types
+ *
+ * The next steps a message OFFERS, frozen with it (control ADR
+ * affordance-system). A pushed proactive chat carries its composer's
+ * `affordances` here so the app renders them as real controls — re-gated per
+ * viewer at render, live availability read separately, executed only by the
+ * server — instead of as chips that merely send a prompt.
+ *
+ * AFFORDANCE OFFER INVARIANTS:
+ * - OFFERED INSTANCES ONLY. Ids and their args, never labels or hrefs (the app
+ *   owns both), never a projected id (`review.open`), at most
+ *   MAX_OFFERED_AFFORDANCES.
+ * - WRITTEN ONCE, with the message it belongs to; never re-derived.
+ * - SHARE-SAFE. Ids and opaque target ids only.
+ * - NON-GOVERNED. It presents no decision and consumes no surface budget.
+ * - Emission is orchestration-driven (the proactive chat writer), never a model
+ *   choice.
+ *
+ * Purely additive: an app that predates this part normalizes unknown part
+ * types to null and drops it.
+ */
+
+import type { OfferedAffordance } from "../affordances/affordance";
+
+/** Affordance offer data payload: the frozen, ordered offer. */
+export interface AffordanceOfferData {
+  affordances: readonly OfferedAffordance[];
+}
+
+/** Affordance offer message part (semantic type, as rendered). */
+export interface AffordanceOfferPart {
+  type: "affordance-offer";
+  data: AffordanceOfferData;
+}
+
+/**
+ * Affordance offer data part (wire format, as persisted in
+ * `chat_messages.parts`). Uses AI SDK's data-{name} convention.
+ */
+export interface AffordanceOfferDataPart {
+  type: "data-affordance-offer";
+  data: AffordanceOfferData;
+}

package/src/message-parts/index.ts

@@ -97,6 +97,13 @@ export type {
   WorkflowOutcomeDataPart,
 } from "./workflow-outcome";
 
+// Affordance offer types (non-governed, the frozen offer on a pushed chat)
+export type {
+  AffordanceOfferData,
+  AffordanceOfferPart,
+  AffordanceOfferDataPart,
+} from "./affordance-offer";
+
 // Execution result types
 export type {
   ExecutionArtifactStatus,

package/src/message-parts/types.ts

@@ -22,6 +22,7 @@ import type { InputRequestPart } from "./input-request";
 import type { SuggestedRepliesPart } from "./suggested-replies";
 import type { WorkflowProgressPart } from "./workflow-progress";
 import type { WorkflowOutcomePart } from "./workflow-outcome";
+import type { AffordanceOfferPart } from "./affordance-offer";
 
 // =============================================================================
 // Narrative Parts (Streamable)
@@ -130,6 +131,10 @@ export interface TablePart {
  * workflow's execution epoch, carried on its settlement message. It presents no
  * decision; a review disposition is delivered as its own InputRequestPart.
  *
+ * AffordanceOfferPart is the fourth non-governed member: the next steps a pushed
+ * chat offers, frozen with it as affordance instances (control ADR
+ * affordance-system). It presents no decision and consumes no surface budget.
+ *
  * InputRequestPart is GOVERNED, like StructureReviewPart: it anchors a reviewed
  * request that asks the person to decide, so it counts against the
  * at-most-one-governed-surface-per-turn budget. It is the generic anchor;
@@ -148,7 +153,8 @@ export type SurfacePart =
   | InputRequestPart
   | SuggestedRepliesPart
   | WorkflowProgressPart
-  | WorkflowOutcomePart;
+  | WorkflowOutcomePart
+  | AffordanceOfferPart;
 
 /**
  * All assistant message part types.