@company-semantics/contracts 89.2.0 → 91.0.0

package/src/affordances/ids.ts

@@ -0,0 +1,45 @@
+/**
+ * The affordance vocabulary: every next step the product may OFFER a person
+ * or the agent (control ADR affordance-system).
+ *
+ * An affordance names an action the product can actually perform. Existing
+ * here is never a reason to offer it: an affordance is offered only by a
+ * domain-owned, deterministic offer rule that relates a domain state to it
+ * (INV-AFFORD-RELEVANT). Neither a model nor a renderer invents, infers or
+ * searches for one.
+ *
+ * INVARIANTS:
+ * - `{domain}.{action}` names, camelCase after the dot. A member is persisted
+ *   inside immutable workflow outcomes and chat parts, so the set is CLOSED and
+ *   append-only: removing one orphans every record that carries it.
+ * - GROUNDED. Every member has a binding kind (`AFFORDANCE_BINDING_KIND_OF` in
+ *   ./affordance) and the repo that owns the binding proves it exists with an
+ *   architecture test: a mounted backend route for `command`, an app `Route`
+ *   for `navigate`, an app launch surface for `surface` (INV-AFFORD-GROUNDED).
+ */
+import { z } from "zod";
+
+export const AFFORDANCE_IDS = [
+  /** Start a new search of the connected drive (Source Sync discovery). */
+  "sourceSync.findFiles",
+  /** Connect Google Drive, or reconnect it when its sign-in stopped working. */
+  "integrations.connectGoogleDrive",
+  /** Turn Source Sync on for the org. */
+  "sourceSync.enable",
+  /** Open the org's billing page. */
+  "billing.open",
+  /** Run the org-structure analysis again. */
+  "orgStructure.reanalyze",
+  /** Sync the HR directory again. */
+  "hris.resyncDirectory",
+  /**
+   * Open a review (an input request) in chat. PROJECTED, never persisted in an
+   * offer: it is derived from authoritative state already stored elsewhere (a
+   * workflow outcome's `review` disposition). See PROJECTED_AFFORDANCE_IDS.
+   */
+  "review.open",
+] as const;
+
+export type AffordanceId = (typeof AFFORDANCE_IDS)[number];
+
+export const AffordanceIdSchema = z.enum(AFFORDANCE_IDS);

package/src/affordances/index.ts

@@ -0,0 +1,39 @@
+/**
+ * Affordance vocabulary barrel (control ADR affordance-system).
+ * Import from '@company-semantics/contracts' (root).
+ */
+export { AFFORDANCE_IDS, AffordanceIdSchema } from "./ids";
+export type { AffordanceId } from "./ids";
+export {
+  AFFORDANCE_ARGS,
+  NO_ARG_AFFORDANCE_IDS,
+  ReviewOpenArgsSchema,
+} from "./args";
+export type { AffordanceArgs } from "./args";
+export {
+  AFFORDANCE_AVAILABILITY_IDS,
+  AFFORDANCE_BINDING_KINDS,
+  AFFORDANCE_UNAVAILABLE_REASONS,
+  AffordanceAvailabilityIdSchema,
+  AffordanceAvailabilitySchema,
+} from "./availability";
+export type {
+  AffordanceAvailability,
+  AffordanceAvailabilityId,
+  AffordanceBindingKind,
+  AffordanceUnavailableReason,
+} from "./availability";
+export {
+  AFFORDANCE_AVAILABILITY_OF,
+  AFFORDANCE_BINDING_KIND_OF,
+  AffordanceSchema,
+  MAX_OFFERED_AFFORDANCES,
+  OfferedAffordanceSchema,
+  PROJECTED_AFFORDANCE_IDS,
+  sameAffordances,
+} from "./affordance";
+export type {
+  Affordance,
+  OfferedAffordance,
+  ProjectedAffordanceId,
+} from "./affordance";

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 = '7144c9a832d5' as const;
-export const SPEC_HASH_FULL = '7144c9a832d55cf9179e5825c6c8fa486bf7130c0d1022d1b721f175dcf99f6d' as const;
+export const SPEC_HASH = 'b2a6eec5dea4' as const;
+export const SPEC_HASH_FULL = 'b2a6eec5dea4f72290740a1cf16608a826ece2e3654ba64d2bc5e3794d571809' as const;

package/src/api/generated.ts

@@ -4271,6 +4271,23 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/internal-admin/quality/decisions/{id}/diagnosis": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** A decision's diagnosis: stable vs flaky failures, failure kinds by bucket, suspected component and findings */
+        get: operations["getQualityDecisionDiagnosis"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/comments": {
         parameters: {
             query?: never;
@@ -8122,7 +8139,7 @@ export interface components {
                 notification: {
                     id: string;
                     /** @enum {string} */
-                    kind: "companyMd.access_requested" | "companyMd.access_request_approved" | "companyMd.access_request_denied" | "comment.mention" | "comment.reply" | "chat.mention" | "proactive.org_became_shared" | "proactive.brief_morning" | "proactive.billing_balance_below_half" | "proactive.billing_balance_below_threshold" | "proactive.billing_auto_recharge_succeeded" | "proactive.billing_top_up_credited" | "proactive.billing_monthly_budget_80" | "proactive.billing_monthly_budget_100" | "proactive.billing_user_monthly_limit_reached" | "proactive.billing_byo_key_invalid" | "proactive.billing_provider_price_changed" | "proactive.billing_payment_recovered" | "proactive.billing_balance_exhausted" | "proactive.billing_auto_recharge_failed" | "proactive.billing_payment_past_due" | "proactive.billing_suspended" | "proactive.billing_subscription_canceled" | "proactive.source_sync_docs_updated" | "proactive.source_sync_review_ready" | "proactive.org_structure_review_ready";
+                    kind: "companyMd.access_requested" | "companyMd.access_request_approved" | "companyMd.access_request_denied" | "comment.mention" | "comment.reply" | "chat.mention" | "proactive.org_became_shared" | "proactive.brief_morning" | "proactive.billing_balance_below_half" | "proactive.billing_balance_below_threshold" | "proactive.billing_auto_recharge_succeeded" | "proactive.billing_top_up_credited" | "proactive.billing_monthly_budget_80" | "proactive.billing_monthly_budget_100" | "proactive.billing_user_monthly_limit_reached" | "proactive.billing_byo_key_invalid" | "proactive.billing_provider_price_changed" | "proactive.billing_payment_recovered" | "proactive.billing_balance_exhausted" | "proactive.billing_auto_recharge_failed" | "proactive.billing_payment_past_due" | "proactive.billing_suspended" | "proactive.billing_subscription_canceled" | "proactive.source_sync_docs_updated" | "proactive.source_sync_review_ready" | "proactive.org_structure_review_ready" | "proactive.workflow_needs_attention" | "proactive.workflow_finished";
                     target: {
                         /** @enum {string} */
                         type: "company_md" | "org_unit" | "org" | "execution";
@@ -9328,8 +9345,10 @@ export interface components {
                 /** @enum {string} */
                 classificationState: "unclassified" | "classified";
                 sourceClass: ("board_deck" | "board_minutes" | "investor_update" | "financial_brief" | "budget_forecast" | "okr_plan" | "annual_plan" | "all_hands" | "unit_strategy" | "roadmap" | "qbr" | "other" | "decoy") | null;
-                documentType: ("board_deck" | "board_minutes" | "strategy_memo" | "planning_doc" | "okr_doc" | "roadmap" | "operating_review" | "all_hands_deck" | "offsite_notes" | "investor_update" | "pitch_deck" | "product_spec" | "research_analysis" | "general_meeting_notes" | "financial_plan" | "financial_actuals" | "equity_admin_record" | "corporate_formation_record" | "corporate_governance_record" | "government_filing" | "equity_agreement" | "commercial_agreement" | "employment_agreement" | "transaction_record" | "personal_document" | "social_event_material" | "coursework" | "empty_template" | "image_or_screenshot" | "unknown") | null;
+                documentType: ("board_deck" | "board_minutes" | "strategy_memo" | "planning_doc" | "okr_doc" | "roadmap" | "operating_review" | "all_hands_deck" | "offsite_notes" | "investor_update" | "pitch_deck" | "product_spec" | "research_analysis" | "general_meeting_notes" | "financial_plan" | "financial_actuals" | "equity_admin_record" | "corporate_formation_record" | "corporate_governance_record" | "government_filing" | "equity_agreement" | "commercial_agreement" | "employment_agreement" | "transaction_record" | "personal_document" | "social_event_material" | "coursework" | "empty_template" | "image_or_screenshot" | "team_charter" | "process_playbook" | "policy_handbook" | "onboarding_guide" | "values_culture" | "positioning_messaging" | "decision_log" | "postmortem" | "metrics_definition" | "operating_cadence" | "unknown") | null;
                 documentTypeConfidence: number | null;
+                operatingKnowledgeFamily: ("direction" | "operating_model" | "practices" | "identity_market" | "decisions_learning") | null;
+                canonicalPath: string | null;
                 periodLabel: string | null;
                 seriesRole: ("current" | "history") | null;
                 relevance: number;
@@ -9375,6 +9394,59 @@ export interface components {
                     t1: ("exploit" | "explore") | null;
                     t2: ("exploit" | "explore") | null;
                 };
+                attentionEvidence: ({
+                    /** @constant */
+                    kind: "tree_prior";
+                    score: number;
+                    folderId: string;
+                    source: {
+                        producer: string;
+                        version: string;
+                    };
+                } | {
+                    /** @constant */
+                    kind: "path_terms";
+                    values: string[];
+                    source: {
+                        producer: string;
+                        version: string;
+                    };
+                } | {
+                    /** @constant */
+                    kind: "content_match";
+                    values: string[];
+                    strength: number;
+                    probeId: string;
+                    source: {
+                        producer: string;
+                        version: string;
+                    };
+                } | {
+                    /** @constant */
+                    kind: "breadth";
+                    /** @enum {string} */
+                    value: "restricted_few" | "group" | "domain" | "anyone" | "unknown";
+                    source: {
+                        producer: string;
+                        version: string;
+                    };
+                } | {
+                    /** @constant */
+                    kind: "recency";
+                    score: number;
+                    source: {
+                        producer: string;
+                        version: string;
+                    };
+                } | {
+                    /** @constant */
+                    kind: "mime_prior";
+                    score: number;
+                    source: {
+                        producer: string;
+                        version: string;
+                    };
+                })[] | null;
                 included: boolean;
                 treatmentUnresolved: boolean;
                 matchReason: string;
@@ -9465,6 +9537,33 @@ export interface components {
                 coveragePercent: number;
                 /** @enum {string} */
                 scanOutcome: "complete" | "budget_exhausted" | "file_ceiling" | "stopped";
+                enumerationCompleteness: ("complete" | "local_budget_truncated" | "provider_incomplete" | "both") | null;
+                rootCoverage: {
+                    /** @enum {string} */
+                    rootKind: "user" | "shared_drive" | "domain";
+                    rootId: string | null;
+                    /** @enum {string} */
+                    status: "complete" | "local_budget_truncated" | "provider_incomplete" | "both";
+                    enumeratedCount: number;
+                    observedOldestModifiedTime: string | null;
+                    observedNewestModifiedTime: string | null;
+                    skippedRanges: {
+                        /** Format: date-time */
+                        from: string;
+                        /** Format: date-time */
+                        to: string;
+                    }[];
+                }[] | null;
+                stageCounters: {
+                    filesEnumerated: number;
+                    filesMetadataEligible: number;
+                    filesT0Scored: number;
+                    filesT1Attended: number;
+                    filesPeeked: number;
+                    filesClassified: number;
+                    filesShown: number;
+                    filesRetained: number;
+                } | null;
             } | null;
         };
         SourceSyncApproveResponse: {
@@ -17982,6 +18081,47 @@ export interface operations {
             };
         };
     };
+    getQualityDecisionDiagnosis: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The decision, whether its diagnosis is stored, pending or not applicable, and the report once stored */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Validation error */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Not an internal admin, or missing internal.manage_quality */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description No such decision */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
     listCommentThreads: {
         parameters: {
             query: {

package/src/generated/openapi-routes.ts

@@ -110,6 +110,7 @@ export const openApiRoutes = {
   '/api/internal-admin/quality/candidates/{id}/accept': ['POST'],
   '/api/internal-admin/quality/candidates/{id}/reject': ['POST'],
   '/api/internal-admin/quality/changes/manual': ['POST'],
+  '/api/internal-admin/quality/decisions/{id}/diagnosis': ['GET'],
   '/api/internal-admin/quality/escalations': ['GET'],
   '/api/internal-admin/quality/escalations/{id}/resolve': ['POST'],
   '/api/internal-admin/quality/graders': ['GET'],

package/src/proactive/README.md

@@ -134,6 +134,23 @@ the three from another.
   broken, so it gets an unread inbox row (`proactive.org_structure_review_ready`)
   and no chat or banner. It is triggered by the committed insert of a
   `validated` proposal, and its occurrence key is the proposal id.
+- **The two workflow settlement kinds are one `explained` and one `notice`**
+  (control ADR-CTRL-540 phase 2; control ADR `affordance-system`). Both are
+  triggered by a ROUTED workflow settlement — the committed `deferred → routed`
+  transition of a settlement nobody was watching, routed per reason through
+  `../workflows/deferred-route` — and both key on
+  `workflow-settled:{workflowId}:{executionEpoch}`. `workflow.needs_attention`
+  is `explained`: the `workflowNeedsAttention` chat is FACT-FREE (no counts —
+  the outcome's facts are stripped), carries the settled outcome as
+  `ProactiveChatMessage.outcome` so its grounded affordances render as real
+  controls, and has NO chips (a chip only sends a chat prompt, which is not
+  grounded). Its composer frames and never narrates: `text` is the backend's
+  settlement narration verbatim, and its per-type title states no digit and
+  no next step. The inbox row is born read. `workflow.finished` is a `notice`:
+  an unread inbox row and nothing else, because telling it needs counts that
+  must re-render under the reader's authority. Their rows are
+  `proactive.workflow_needs_attention` and `proactive.workflow_finished`.
+  Neither sets `emailKind` or `actionItemKind`.
 - **The occurrence vocabulary is closed.** `ProactiveEventId` is branded so a
   raw string cannot stand in for an occurrence; `ProactiveRecipientReason` is a
   closed enum because the recipients table is the frozen audit record of who
@@ -172,9 +189,9 @@ the three from another.
 | `bornRead`                         | Whether a class's `chat` or `inbox` row is born read                          |
 | `ORG_SYSTEM_EVENT_TYPES`           | Mirror of the backend `org_system_event_type` pgEnum — the banner ids         |
 | `OrgSystemEventType`               | Union derived from the array                                                  |
-| `PROACTIVE_CHAT_TEMPLATES`         | Which prose composes a kind's pushed chat (8: 2 + 5 `billing*` + 1 `source*`) |
+| `PROACTIVE_CHAT_TEMPLATES`         | Which prose composes a kind's pushed chat (9, incl. `workflowNeedsAttention`) |
 | `ProactiveChatTemplate`            | Union derived from the array                                                  |
-| `PROACTIVE_EVENT_KIND_IDS`         | Closed kinds (3 org/brief/chat + 15 `billing.*` + 2 `sourceSync.*`)           |
+| `PROACTIVE_EVENT_KIND_IDS`         | Closed kinds (org/brief/chat, `billing.*`, `sourceSync.*`, `workflow.*` …)    |
 | `ProactiveEventKind`               | Union derived from the array                                                  |
 | `ProactiveEventId`                 | Branded id of ONE occurrence — a raw string cannot be passed as one           |
 | `PROACTIVE_RECIPIENT_REASONS`      | Closed enum of WHY a recipient was addressed (the frozen audit record)        |
@@ -192,7 +209,9 @@ the three from another.
 | `BillingSuspendedFacts`            | `orgName` — the prose needs nothing else, and may state nothing else          |
 | `BillingSubscriptionCanceledFacts` | `orgName`                                                                     |
 | `SourceSyncReviewReadyFacts`       | `orgName` + `checkpoint`; no count, no document name, no source name          |
-| `ProactiveChatMessage`             | What a composer returns: `title`, `text`, and 0..4 `replies` chips            |
+| `ExplainedWorkflowOutcomeData`     | The settlement data part with an explained, fact-free outcome                 |
+| `WorkflowNeedsAttentionFacts`      | `narration` (backend settlement copy) + the fact-free `outcome` data part     |
+| `ProactiveChatMessage`             | `title`, `text`, 0..4 `replies` chips, and an optional settled `outcome`      |
 | `ProactiveChatComposer`            | The composer port — `template` plus an arrow-property `compose(facts)`        |
 | `PROACTIVE_CHAT_MAX_REPLIES`       | At most this many chips (4); more is a menu, not a chip row                   |
 | `PROACTIVE_CHAT_COMPOSERS`         | The total template → composer registry (see `templates/README.md`)            |
@@ -203,5 +222,8 @@ Type-only imports of `UserNotificationKind` (`../user-notifications`),
 `NotificationKind` (`../notifications`) and `ActionItemKind`
 (`../action-items`) — the three vocabularies this one composes — and of
 `SuggestedReply` (`../message-parts`), the chip shape a composer's `replies`
-reuse rather than redeclare. No `zod`, no runtime imports; pure vocabulary
+reuse rather than redeclare. Type-only imports of `WorkflowOutcomeData`
+(`../message-parts`), `ExplainedWorkflowOutcome` (`../workflows`) and
+`WorkflowType` for the workflow settlement chat; the dependency runs
+proactive → workflows, never the reverse. No `zod`, no runtime imports; pure vocabulary
 data and pure helpers.

package/src/proactive/__tests__/README.md

@@ -51,6 +51,16 @@ cannot.
   must not be told to update one), past-due separates the seat subscription from
   the AI balance, and suspension and cancellation each say outright that nothing
   was deleted.
+- `workflow-attention.test.ts` — the two workflow settlement kinds (control
+  ADR-CTRL-540 phase 2): `workflow.needs_attention` is explained (a chat and a
+  born-read inbox row, never a banner) and `workflow.finished` is a notice (an
+  unread inbox row only); the `workflowNeedsAttention` chat carries the
+  fact-free outcome (schema-valid, `facts: null`) and no chips, frames the
+  backend narration verbatim, has a title per workflow type with no digit and
+  no next-step wording; and both inbox rows supersede per workflow type.
+- `workflow-attention-fixtures.ts` — explained, fact-free outcomes for those
+  tests and the registry-wide fixtures. A COMPILED module, so each fixture is
+  typechecked against `ExplainedWorkflowOutcome`.
 
 ## Invariants
 

package/src/proactive/__tests__/chat-templates.test.ts

@@ -6,6 +6,10 @@ import type { OrgSharedTransitionTrigger } from "../../org/shared-transition";
 import { PROACTIVE_CHAT_TEMPLATES } from "../surfaces";
 import type { ProactiveChatTemplate } from "../surfaces";
 import { PROACTIVE_CHAT_COMPOSERS } from "../templates/index";
+import {
+  DRIVE_AUTH_NARRATION,
+  DRIVE_AUTH_OUTCOME,
+} from "./workflow-attention-fixtures";
 
 /**
  * One representative facts fixture per template. Total over
@@ -32,6 +36,10 @@ const FACTS: { readonly [T in ProactiveChatTemplate]: ProactiveChatFacts[T] } =
     billingSuspended: { orgName: "Acme" },
     billingSubscriptionCanceled: { orgName: "Acme" },
     sourceSyncReviewReady: { orgName: "Acme", checkpoint: "candidates" },
+    workflowNeedsAttention: {
+      narration: DRIVE_AUTH_NARRATION,
+      outcome: { workflowId: "wf-1", outcome: DRIVE_AUTH_OUTCOME },
+    },
   };
 
 /**

package/src/proactive/__tests__/vocabulary.test.ts

@@ -37,6 +37,10 @@ import {
   PLAN_FIXTURES_THE_COMPILER_REJECTS,
   REGISTRY_FIXTURES_THE_COMPILER_REJECTS,
 } from "./compile-fixtures";
+import {
+  DRIVE_AUTH_NARRATION,
+  DRIVE_AUTH_OUTCOME,
+} from "./workflow-attention-fixtures";
 
 /**
  * The registry, read as the union it satisfies rather than as its literal
@@ -103,6 +107,10 @@ const FRESH_FACTS: {
     orgName: "Acme",
     checkpoint: "synthesis" as const,
   }),
+  workflowNeedsAttention: () => ({
+    narration: DRIVE_AUTH_NARRATION,
+    outcome: { workflowId: "wf-1", outcome: DRIVE_AUTH_OUTCOME },
+  }),
 };
 
 /**
@@ -259,6 +267,9 @@ describe("the kind registry", () => {
       "sourceSync.review_ready": "proactive",
       // The org structure row is rendered by `src/proactive/` as well.
       "orgStructure.review_ready": "proactive",
+      // Both workflow settlement rows are rendered by `src/proactive/`.
+      "workflow.needs_attention": "proactive",
+      "workflow.finished": "proactive",
     };
 
     expect(Object.keys(EXPECTED_INBOX_DOMAIN).sort()).toEqual(

package/src/proactive/__tests__/workflow-attention-fixtures.ts

@@ -0,0 +1,49 @@
+/**
+ * Explained, fact-free workflow outcomes for the `workflowNeedsAttention`
+ * template's tests. A COMPILED module (not `*.test.ts`), so every fixture is
+ * checked against `ExplainedWorkflowOutcome` — a reason that is not explained,
+ * or facts left in, fails the typecheck rather than passing silently.
+ *
+ * The narrations are fixture strings standing in for the backend's settlement
+ * copy; contracts never owns that wording.
+ */
+import type { ExplainedWorkflowOutcomeData } from "../facts";
+import type { ExplainedWorkflowOutcome } from "../../workflows/deferred-route";
+
+export const DRIVE_AUTH_NARRATION =
+  "The search of the connected drive stopped because Google Drive no longer accepts the connection's sign-in.";
+
+export const DRIVE_AUTH_OUTCOME: ExplainedWorkflowOutcome = {
+  workflowType: "source-sync/discover",
+  executionEpoch: 0,
+  kind: "failed",
+  reason: "drive_auth",
+  facts: null,
+  disposition: { kind: "narrate" },
+  affordances: [{ id: "integrations.connectGoogleDrive" }],
+};
+
+export const PAUSED_BILLING_OUTCOME: ExplainedWorkflowOutcome = {
+  workflowType: "source-sync/synthesize",
+  executionEpoch: 1,
+  kind: "failed",
+  reason: "paused_billing",
+  facts: null,
+  disposition: { kind: "narrate" },
+  affordances: [{ id: "billing.open" }],
+};
+
+export const MODEL_FAILED_OUTCOME: ExplainedWorkflowOutcome = {
+  workflowType: "org-structure/reanalyze",
+  executionEpoch: 2,
+  kind: "failed",
+  reason: "model_failed",
+  facts: null,
+  disposition: { kind: "narrate" },
+  affordances: [{ id: "orgStructure.reanalyze" }],
+};
+
+/** The settlement data part for an outcome, as the backend would hand it over. */
+export const outcomeDataOf = (
+  outcome: ExplainedWorkflowOutcome,
+): ExplainedWorkflowOutcomeData => ({ workflowId: "wf-1", outcome });

package/src/proactive/__tests__/workflow-attention.test.ts

@@ -0,0 +1,146 @@
+/**
+ * The two workflow settlement proactive kinds (control ADR-CTRL-540 phase 2;
+ * control ADR affordance-system): `workflow.needs_attention` is explained and
+ * its chat only FRAMES the backend's narration, `workflow.finished` is a notice.
+ */
+import { describe, it, expect } from "vitest";
+import { CLASS_SURFACES, bornRead } from "../classes";
+import type { ProactiveChatMessage } from "../composer";
+import type { WorkflowNeedsAttentionFacts } from "../facts";
+import { PROACTIVE_EVENT_KINDS } from "../registry";
+import { PROACTIVE_CHAT_COMPOSERS } from "../templates/index";
+import { notificationKeysOf } from "../../user-notifications/condition-keys";
+import { NOTIFICATION_LIFECYCLE } from "../../user-notifications/lifecycle-registry";
+import { WorkflowOutcomeSchema } from "../../workflows/outcome";
+import { ANALYSIS_WORKFLOW_TYPES } from "../../workflows/types";
+import type { ExplainedWorkflowOutcome } from "../../workflows/deferred-route";
+import {
+  DRIVE_AUTH_NARRATION,
+  DRIVE_AUTH_OUTCOME,
+  MODEL_FAILED_OUTCOME,
+  PAUSED_BILLING_OUTCOME,
+  outcomeDataOf,
+} from "./workflow-attention-fixtures";
+
+// Mirrors the backend settlement-copy ban (backend tests/chat/workflow-outcome-copy.test.ts).
+const CALL_TO_ACTION =
+  /\byou can\b|\btry\b|\bagain\b|\bsettings\b|\breconnect\b|\badd funds\b|\bclick\b|\bgo to\b|\bopen\b/i;
+
+const compose = (facts: WorkflowNeedsAttentionFacts): ProactiveChatMessage =>
+  PROACTIVE_CHAT_COMPOSERS.workflowNeedsAttention.compose(facts);
+
+const DRIVE_AUTH_FACTS: WorkflowNeedsAttentionFacts = {
+  narration: DRIVE_AUTH_NARRATION,
+  outcome: outcomeDataOf(DRIVE_AUTH_OUTCOME),
+};
+
+/** The drive-auth outcome re-typed as each workflow type, for title coverage. */
+const outcomeAs = (
+  workflowType: (typeof ANALYSIS_WORKFLOW_TYPES)[number],
+): ExplainedWorkflowOutcome =>
+  ({ ...DRIVE_AUTH_OUTCOME, workflowType }) as ExplainedWorkflowOutcome;
+
+describe("workflow settlement proactive kinds", () => {
+  it("workflow.needs_attention is explained: a chat and a born-read inbox row, never a banner", () => {
+    const plan = PROACTIVE_EVENT_KINDS["workflow.needs_attention"];
+    expect(plan).toEqual({
+      class: "explained",
+      chatTemplate: "workflowNeedsAttention",
+      inboxKind: "proactive.workflow_needs_attention",
+    });
+    const surfaces = CLASS_SURFACES[plan.class];
+    expect(surfaces.banner).toBe(false);
+    expect(surfaces.chat).toBe(true);
+    expect(bornRead(surfaces, "inbox")).toBe(true);
+  });
+
+  it("workflow.finished is a notice: an unread inbox row, no banner and no chat", () => {
+    const plan = PROACTIVE_EVENT_KINDS["workflow.finished"];
+    expect(plan).toEqual({
+      class: "notice",
+      inboxKind: "proactive.workflow_finished",
+    });
+    const surfaces = CLASS_SURFACES[plan.class];
+    expect(surfaces.banner).toBe(false);
+    expect(surfaces.chat).toBe(false);
+    expect(bornRead(surfaces, "inbox")).toBe(false);
+  });
+
+  it("the attention chat carries the fact-free outcome and no chips", () => {
+    const msg = compose(DRIVE_AUTH_FACTS);
+    expect(msg.replies).toEqual([]);
+    expect(msg.outcome).toEqual({
+      workflowId: "wf-1",
+      outcome: DRIVE_AUTH_OUTCOME,
+    });
+    expect(msg.outcome?.outcome.facts).toBeNull();
+    expect(WorkflowOutcomeSchema.safeParse(msg.outcome?.outcome).success).toBe(
+      true,
+    );
+  });
+
+  it("the attention chat frames the backend narration verbatim", () => {
+    for (const outcome of [
+      DRIVE_AUTH_OUTCOME,
+      PAUSED_BILLING_OUTCOME,
+      MODEL_FAILED_OUTCOME,
+    ]) {
+      const narration = `Narration for ${outcome.workflowType} ${outcome.reason}.`;
+      const msg = compose({ narration, outcome: outcomeDataOf(outcome) });
+      expect(msg.text, outcome.workflowType).toBe(narration);
+    }
+  });
+
+  it("the attention chat has a title for every workflow type", () => {
+    for (const workflowType of ANALYSIS_WORKFLOW_TYPES) {
+      const msg = compose({
+        narration: DRIVE_AUTH_NARRATION,
+        outcome: outcomeDataOf(outcomeAs(workflowType)),
+      });
+      expect(typeof msg.title, workflowType).toBe("string");
+      expect(msg.title.trim().length, workflowType).toBeGreaterThan(0);
+    }
+  });
+
+  it("the attention chat title states no digit and offers no next step", () => {
+    for (const workflowType of ANALYSIS_WORKFLOW_TYPES) {
+      const { title } = compose({
+        narration: DRIVE_AUTH_NARRATION,
+        outcome: outcomeDataOf(outcomeAs(workflowType)),
+      });
+      expect(title, workflowType).not.toMatch(/\d/);
+      expect(title, workflowType).not.toMatch(CALL_TO_ACTION);
+    }
+  });
+
+  it("both workflow inbox rows supersede per workflow type", () => {
+    for (const kind of [
+      "proactive.workflow_needs_attention",
+      "proactive.workflow_finished",
+    ] as const) {
+      const lifecycle = NOTIFICATION_LIFECYCLE[kind];
+      expect(lifecycle.condition, kind).toEqual({
+        scope: "fields",
+        fields: ["workflowType"],
+      });
+      expect(lifecycle.supersedes, kind).toBe(true);
+      expect(lifecycle.resolution, kind).toBe("never");
+
+      const first = notificationKeysOf(kind, {
+        workflowType: "source-sync/discover",
+        workflowId: "wf-1",
+      });
+      const second = notificationKeysOf(kind, {
+        workflowType: "source-sync/discover",
+        workflowId: "wf-2",
+      });
+      const other = notificationKeysOf(kind, {
+        workflowType: "org-structure/reanalyze",
+        workflowId: "wf-3",
+      });
+      expect(first.supersessionKey, kind).not.toBeNull();
+      expect(second.supersessionKey, kind).toBe(first.supersessionKey);
+      expect(other.supersessionKey, kind).not.toBe(first.supersessionKey);
+    }
+  });
+});

package/src/proactive/composer.ts

@@ -35,6 +35,7 @@
  */
 
 import type { SuggestedReply } from "../message-parts/suggested-replies";
+import type { WorkflowOutcomeData } from "../message-parts/workflow-outcome";
 import type { ProactiveChatFacts } from "./facts";
 import type { ProactiveChatTemplate } from "./surfaces";
 
@@ -65,6 +66,13 @@ export interface ProactiveChatMessage {
   readonly text: string;
   /** 0..`PROACTIVE_CHAT_MAX_REPLIES` chips. */
   readonly replies: readonly SuggestedReply[];
+  /**
+   * The settled workflow a template reports, when it reports one. The chat
+   * writer persists it as a `data-workflow-outcome` part beside the prose, so
+   * the same renderer shows its affordances. Present only for a template whose
+   * facts carry an outcome; always fact-free here.
+   */
+  readonly outcome?: WorkflowOutcomeData;
 }
 
 // =============================================================================