@company-semantics/contracts 89.2.0 → 91.0.0

package/src/source-sync/candidate-item.ts

@@ -18,6 +18,7 @@ import { IsoDateTime } from "../api/primitives";
 import {
   AUDIENCE_FITS,
   DOCUMENT_TYPES,
+  OPERATING_KNOWLEDGE_FAMILIES,
   SHARING_BREADTHS,
   SOURCE_CLASSES,
   SOURCE_SENSITIVITY_CLASSES,
@@ -34,6 +35,7 @@ import {
   SOURCE_RELEVANCE_TIERS,
   TARGET_AUDIENCES,
 } from "./relevance";
+import { AttentionEvidenceSchema } from "./attention-evidence";
 
 /** ONE source proposed for ONE target document. */
 export const SourceSyncCandidateItemSchema = z
@@ -75,6 +77,22 @@ export const SourceSyncCandidateItemSchema = z
     documentType: z.enum(DOCUMENT_TYPES).nullable(),
     /** Confidence of the resolved type, 0..1. NULL exactly when documentType is null or `unknown`. */
     documentTypeConfidence: z.number().min(0).max(1).nullable(),
+    /**
+     * WHAT KIND of operating knowledge the line is — a NAME the backend RESOLVES from the
+     * resolved document type through its versioned policy table (control ADR
+     * index-first-operating-knowledge-discovery), exactly as it resolves sourceClass. The
+     * backend's internal relevance-policy families never travel. NULL when the type is
+     * null or unknown, or names no operating knowledge (a legal agreement, a transaction,
+     * personal material), and on every line of a run that predates index-first discovery.
+     */
+    operatingKnowledgeFamily: z.enum(OPERATING_KNOWLEDGE_FAMILIES).nullable(),
+    /**
+     * WHERE the source lives in the provider ("Product/Planning/2026") — the Tier-1
+     * canonical path the backend resolves from its location graph once the file reached
+     * T1 attention (Tier-0 never retains a name or a path). NULL for a file that never
+     * reached attention, on a withheld line, and on a run that predates index-first discovery.
+     */
+    canonicalPath: z.string().min(1).max(1024).nullable(),
     periodLabel: z.string().max(64).nullable(),
     seriesRole: z.enum(["current", "history"]).nullable(),
     /** The FUSED relevance score (control ADR source-discovery-relevance-funnel), 0..1. */
@@ -106,6 +124,13 @@ export const SourceSyncCandidateItemSchema = z
     targetAudience: z.enum(TARGET_AUDIENCES).nullable(),
     /** Which lane earned each model tier's attention (INV-SOURCESYNC-EXPLORATION-RESERVED). */
     attention: CandidateAttentionSchema,
+    /**
+     * WHY the line received T1 attention: each signal with its producer and version
+     * (INV-SOURCESYNC-ATTENTION-EVIDENCE-HAS-PROVENANCE). NULL for a file that never
+     * reached attention, on a withheld line (terms and folder ids identify a source), and
+     * on every line of a run that predates index-first discovery.
+     */
+    attentionEvidence: AttentionEvidenceSchema.nullable(),
     /**
      * Whether this line is in the set that approval would land — the SERVER's
      * answer, never derived from `use`. A decoy, a series' history or a line a

package/src/source-sync/enumeration.ts

@@ -0,0 +1,152 @@
+/**
+ * Index-first discovery's ENUMERATION vocabulary (control ADR
+ * index-first-operating-knowledge-discovery; INV-SOURCESYNC-PARTIAL-ENUMERATION-IS-UNKNOWN).
+ *
+ * A discovery run first enumerates every source reachable through the connection,
+ * root by root (the person's own corpus, each shared drive, the domain corpus).
+ * How completely it did so is a closed answer that separates OUR ceiling from the
+ * PROVIDER's incompleteness, so a partial enumeration can never read as an index of
+ * the corpus: only `complete` lets a surface say "full index". Anything else means
+ * absence is UNKNOWN, never negative evidence.
+ *
+ * Stage counters name what each count did: enumerated / metadata-eligible / T0-scored
+ * are metadata only; attended / peeked / classified involve a model; shown / retained
+ * are outcomes. `filesEnumerated = 100000` with `local_budget_truncated` never reads as
+ * "indexed every file".
+ */
+import { z } from "zod";
+import { IsoDateTime } from "../api/primitives";
+
+/** How completely a run (or one root) was enumerated. */
+export const ENUMERATION_COMPLETENESS = [
+  "complete",
+  "local_budget_truncated",
+  "provider_incomplete",
+  "both",
+] as const;
+export type EnumerationCompleteness = (typeof ENUMERATION_COMPLETENESS)[number];
+
+/** Which corpus a root is: the connected person's, one shared drive, or the domain. */
+export const ENUMERATION_ROOT_KINDS = [
+  "user",
+  "shared_drive",
+  "domain",
+] as const;
+export type EnumerationRootKind = (typeof ENUMERATION_ROOT_KINDS)[number];
+
+/**
+ * PURE: one completeness for many roots. Our ceiling anywhere and the provider's
+ * incompleteness anywhere combine to `both`; only every root complete is `complete`.
+ */
+export function combineEnumerationCompleteness(
+  statuses: readonly EnumerationCompleteness[],
+): EnumerationCompleteness {
+  const local = statuses.some(
+    (s) => s === "local_budget_truncated" || s === "both",
+  );
+  const provider = statuses.some(
+    (s) => s === "provider_incomplete" || s === "both",
+  );
+  if (local && provider) return "both";
+  if (local) return "local_budget_truncated";
+  if (provider) return "provider_incomplete";
+  return "complete";
+}
+
+const MS = (iso: string): number => Date.parse(iso);
+
+/** A modified-time range the sampler did not enumerate. */
+export const EnumerationSkippedRangeSchema = z
+  .object({ from: IsoDateTime, to: IsoDateTime })
+  .refine((r) => MS(r.from) <= MS(r.to), {
+    message: "a skipped range ends no earlier than it starts",
+  });
+
+/** How far one root's enumeration got. Counts, times and provider ids only — never a name. */
+export const RootCoverageSchema = z
+  .object({
+    rootKind: z.enum(ENUMERATION_ROOT_KINDS),
+    /** The shared drive's provider id; null for the user and domain corpora. */
+    rootId: z.string().min(1).max(128).nullable(),
+    status: z.enum(ENUMERATION_COMPLETENESS),
+    enumeratedCount: z.number().int().min(0),
+    /** Null exactly when nothing was enumerated under the root. */
+    observedOldestModifiedTime: IsoDateTime.nullable(),
+    observedNewestModifiedTime: IsoDateTime.nullable(),
+    skippedRanges: z.array(EnumerationSkippedRangeSchema).max(16),
+  })
+  .superRefine((root, ctx) => {
+    if ((root.rootId !== null) !== (root.rootKind === "shared_drive")) {
+      ctx.addIssue({
+        code: "custom",
+        message: "a root id names exactly a shared drive",
+      });
+    }
+    if (root.status === "complete" && root.skippedRanges.length > 0) {
+      ctx.addIssue({
+        code: "custom",
+        message: "a complete root skips nothing",
+      });
+    }
+    const empty = root.enumeratedCount === 0;
+    const timesAbsent =
+      root.observedOldestModifiedTime === null &&
+      root.observedNewestModifiedTime === null;
+    const timesPresent =
+      root.observedOldestModifiedTime !== null &&
+      root.observedNewestModifiedTime !== null;
+    if (empty ? !timesAbsent : !timesPresent) {
+      ctx.addIssue({
+        code: "custom",
+        message:
+          "observed modified times are present exactly when the root enumerated a file",
+      });
+    }
+    if (
+      timesPresent &&
+      MS(root.observedOldestModifiedTime as string) >
+        MS(root.observedNewestModifiedTime as string)
+    ) {
+      ctx.addIssue({
+        code: "custom",
+        message: "the oldest observed time is not after the newest",
+      });
+    }
+  });
+export type RootCoverage = z.infer<typeof RootCoverageSchema>;
+
+/**
+ * A run's stage counters. Each narrows the one before it:
+ * enumerated >= metadata-eligible >= T0-scored >= T1-attended >= peeked;
+ * T0-scored >= classified; T0-scored >= retained >= shown.
+ */
+export const DiscoveryStageCountersSchema = z
+  .object({
+    filesEnumerated: z.number().int().min(0),
+    filesMetadataEligible: z.number().int().min(0),
+    filesT0Scored: z.number().int().min(0),
+    filesT1Attended: z.number().int().min(0),
+    filesPeeked: z.number().int().min(0),
+    filesClassified: z.number().int().min(0),
+    filesShown: z.number().int().min(0),
+    filesRetained: z.number().int().min(0),
+  })
+  .superRefine((c, ctx) => {
+    const narrows =
+      c.filesMetadataEligible <= c.filesEnumerated &&
+      c.filesT0Scored <= c.filesMetadataEligible &&
+      c.filesT1Attended <= c.filesT0Scored &&
+      c.filesPeeked <= c.filesT1Attended &&
+      c.filesClassified <= c.filesT0Scored &&
+      c.filesRetained <= c.filesT0Scored &&
+      c.filesShown <= c.filesRetained;
+    if (!narrows) {
+      ctx.addIssue({
+        code: "custom",
+        message: "stage counters narrow from enumerated to shown",
+      });
+    }
+  });
+export type DiscoveryStageCounters = z.infer<
+  typeof DiscoveryStageCountersSchema
+>;

package/src/source-sync/index.ts

@@ -3,7 +3,9 @@
  *
  * Re-exports the closed Source Sync vocabularies (the sets the backend persists
  * and mirrors as database CHECK constraints, and the app handles exhaustively)
- * including the discovery relevance vocabulary, the discovery and candidate-set response schemas, the candidate-edit and
+ * including the discovery relevance vocabulary, the index-first enumeration
+ * vocabulary (completeness, root coverage, stage counters), the attention
+ * evidence schemas, the discovery and candidate-set response schemas, the candidate-edit and
  * per-scope approval request and response schemas, the per-document change
  * plan and apply schemas, the source-resolution rule schemas, the staleness
  * finding and standing-order schemas, and the Drive-reach status and upgrade
@@ -31,6 +33,7 @@ export type {
   SourceSyncScopeApproverKind,
   DocumentType,
   KnownDocumentType,
+  OperatingKnowledgeFamily,
 } from "./vocabulary";
 
 export {
@@ -45,6 +48,7 @@ export {
   SOURCE_SYNC_SCOPE_APPROVAL_STATES,
   SOURCE_SYNC_SCOPE_APPROVER_KINDS,
   DOCUMENT_TYPES,
+  OPERATING_KNOWLEDGE_FAMILIES,
 } from "./vocabulary";
 
 export type {
@@ -86,6 +90,36 @@ export {
   refineCandidateRelevance,
 } from "./relevance";
 
+export type {
+  EnumerationCompleteness,
+  EnumerationRootKind,
+  RootCoverage,
+  DiscoveryStageCounters,
+} from "./enumeration";
+
+export {
+  ENUMERATION_COMPLETENESS,
+  ENUMERATION_ROOT_KINDS,
+  combineEnumerationCompleteness,
+  EnumerationSkippedRangeSchema,
+  RootCoverageSchema,
+  DiscoveryStageCountersSchema,
+} from "./enumeration";
+
+export type {
+  AttentionSignalKind,
+  AttentionSignalSource,
+  AttentionSignal,
+  AttentionEvidence,
+} from "./attention-evidence";
+
+export {
+  ATTENTION_SIGNAL_KINDS,
+  AttentionSignalSourceSchema,
+  AttentionSignalSchema,
+  AttentionEvidenceSchema,
+} from "./attention-evidence";
+
 export type {
   SourceSyncCandidateItem,
   SourceSyncCandidateItemPatch,

package/src/source-sync/relevance.ts

@@ -7,6 +7,12 @@
  */
 
 import { z } from "zod";
+import {
+  combineEnumerationCompleteness,
+  DiscoveryStageCountersSchema,
+  ENUMERATION_COMPLETENESS,
+  RootCoverageSchema,
+} from "./enumeration";
 
 /** The funnel's verdict. `dropped` is persisted (drop ledger / re-scored observation) and never reaches the wire item. */
 export const SOURCE_RELEVANCE_TIERS = ["dropped", "hidden", "shown"] as const;
@@ -165,17 +171,50 @@ export type CandidateAttention = z.infer<typeof CandidateAttentionSchema>;
 
 /**
  * The last completed discovery run's counts, so no surface shows one ambiguous total.
- * The set response carries it NULL before any run has completed.
+ * The set response carries it NULL before any run has completed. The three enumeration
+ * fields are all present or all absent: NULL on all three = the run predates index-first
+ * discovery (control ADR index-first-operating-knowledge-discovery).
  */
-export const CandidateDiscoverySummarySchema = z.object({
-  foundThisRun: z.number().int().min(0),
-  retainedDecisions: z.number().int().min(0),
-  notRediscovered: z.number().int().min(0),
-  pendingClassification: z.number().int().min(0),
-  filesDropped: z.number().int().min(0),
-  coveragePercent: z.number().int().min(0).max(100),
-  scanOutcome: z.enum(SCAN_OUTCOMES),
-});
+export const CandidateDiscoverySummarySchema = z
+  .object({
+    foundThisRun: z.number().int().min(0),
+    retainedDecisions: z.number().int().min(0),
+    notRediscovered: z.number().int().min(0),
+    pendingClassification: z.number().int().min(0),
+    filesDropped: z.number().int().min(0),
+    coveragePercent: z.number().int().min(0).max(100),
+    scanOutcome: z.enum(SCAN_OUTCOMES),
+    /** How completely the run enumerated; only `complete` may be called a full index. */
+    enumerationCompleteness: z.enum(ENUMERATION_COMPLETENESS).nullable(),
+    /** One entry per enumerated root. */
+    rootCoverage: z.array(RootCoverageSchema).min(1).max(64).nullable(),
+    /** What each stage did, by count (filesEnumerated is metadata only — never "indexed"). */
+    stageCounters: DiscoveryStageCountersSchema.nullable(),
+  })
+  .superRefine((s, ctx) => {
+    const present = [
+      s.enumerationCompleteness,
+      s.rootCoverage,
+      s.stageCounters,
+    ].filter((v) => v !== null).length;
+    if (present !== 0 && present !== 3) {
+      ctx.addIssue({
+        code: "custom",
+        message: "enumeration fields are all present or all absent",
+      });
+    }
+    if (
+      s.rootCoverage !== null &&
+      s.enumerationCompleteness !== null &&
+      combineEnumerationCompleteness(s.rootCoverage.map((r) => r.status)) !==
+        s.enumerationCompleteness
+    ) {
+      ctx.addIssue({
+        code: "custom",
+        message: "enumeration completeness is the combination of its roots",
+      });
+    }
+  });
 export type CandidateDiscoverySummary = z.infer<
   typeof CandidateDiscoverySummarySchema
 >;
@@ -191,6 +230,11 @@ type CandidateRelevanceFacts = {
   selectionSource: SelectionSource | null;
   documentType: string | null;
   documentTypeConfidence: number | null;
+  withheld: boolean;
+  attention: { t1: AttentionLane | null; t2: AttentionLane | null };
+  operatingKnowledgeFamily: string | null;
+  canonicalPath: string | null;
+  attentionEvidence: readonly unknown[] | null;
 };
 
 /**
@@ -198,7 +242,10 @@ type CandidateRelevanceFacts = {
  * a hidden line is never included; classification decides whether a recommendation and a
  * class exist; `selectionSource` is present exactly when a treatment is committed. A
  * document type exists only on a classified line, and carries a confidence exactly when
- * it is a known type (control ADR source-discovery-observation-vs-policy).
+ * it is a known type (control ADR source-discovery-observation-vs-policy). An
+ * operating-knowledge family needs a known type; attention evidence and a canonical path
+ * exist only on a line T1 attended and never on a withheld one (control ADR
+ * index-first-operating-knowledge-discovery).
  */
 export function refineCandidateRelevance(
   item: CandidateRelevanceFacts,
@@ -248,4 +295,31 @@ export function refineCandidateRelevance(
         "a known document type carries a confidence; unknown and absent carry none",
     });
   }
+  if (item.operatingKnowledgeFamily !== null && !knownType) {
+    ctx.addIssue({
+      code: "custom",
+      message: "an operating-knowledge family needs a known document type",
+    });
+  }
+  if (
+    item.withheld &&
+    (item.attentionEvidence !== null || item.canonicalPath !== null)
+  ) {
+    ctx.addIssue({
+      code: "custom",
+      message: "a withheld line carries no attention evidence and no path",
+    });
+  }
+  if (item.attentionEvidence !== null && item.attention.t1 === null) {
+    ctx.addIssue({
+      code: "custom",
+      message: "attention evidence exists only on a line T1 attended",
+    });
+  }
+  if (item.canonicalPath !== null && item.attention.t1 === null) {
+    ctx.addIssue({
+      code: "custom",
+      message: "a canonical path exists only on a line T1 attended",
+    });
+  }
 }

package/src/source-sync/vocabulary.ts

@@ -113,7 +113,9 @@ export type SourceSyncScopeApproverKind =
 
 /**
  * What a source IS — a STRUCTURAL name the model observes, never a relevance verdict
- * (control ADR source-discovery-observation-vs-policy). Product policy in the backend maps a
+ * (control ADR source-discovery-observation-vs-policy). The set names operating
+ * knowledge — charters, playbooks, policies, decision logs, postmortems and the like —
+ * beside strategy (control ADR index-first-operating-knowledge-discovery). Product policy in the backend maps a
  * resolved type to a family, a source class, a sensitivity and a relevance policy; none of
  * that travels on the wire. A medium is not a meaning: `image_or_screenshot` is graded on
  * content. `unknown` is a real answer (the model could not tell, or two reads disagreed).
@@ -151,7 +153,41 @@ export const DOCUMENT_TYPES = [
   "coursework",
   "empty_template",
   "image_or_screenshot",
+  // Operating knowledge (control ADR index-first-operating-knowledge-discovery):
+  "team_charter",
+  "process_playbook",
+  "policy_handbook",
+  "onboarding_guide",
+  "values_culture",
+  "positioning_messaging",
+  "decision_log",
+  "postmortem",
+  "metrics_definition",
+  "operating_cadence",
   "unknown",
 ] as const;
 export type DocumentType = (typeof DOCUMENT_TYPES)[number];
 export type KnownDocumentType = Exclude<DocumentType, "unknown">;
+
+/**
+ * WHAT KIND of operating knowledge a source is: what the company is trying to do
+ * (direction), how it is organized to do it (operating_model), how it runs
+ * (practices), who it is and for whom (identity_market), and what it decided and
+ * learned (decisions_learning). Control ADR index-first-operating-knowledge-discovery.
+ *
+ * A NAME the product derives from the resolved document type — the backend's
+ * versioned policy table owns the type -> family mapping, exactly as it owns
+ * sourceClass. It is NOT the backend's relevance-policy family (strategy,
+ * reference, corporate_record, …), which never travels on the wire. Board and
+ * financial material are ordinary members of `direction`; no family is required
+ * to exist for a discovery to be valid.
+ */
+export const OPERATING_KNOWLEDGE_FAMILIES = [
+  "direction",
+  "operating_model",
+  "practices",
+  "identity_market",
+  "decisions_learning",
+] as const;
+export type OperatingKnowledgeFamily =
+  (typeof OPERATING_KNOWLEDGE_FAMILIES)[number];

package/src/user-notifications/README.md

@@ -78,6 +78,14 @@ that renders them alongside action items at the top of `/me/work`.
 - **`proactive.org_structure_review_ready` is the org structure notice's row.**
   It arrives UNREAD, because a `notice` has no other surface to hold the badge.
   The renderer links it to the place the review is opened.
+- **`proactive.workflow_needs_attention` and `proactive.workflow_finished` are
+  the workflow settlement rows** (control ADR-CTRL-540 phase 2), the durable
+  twins of `workflow.needs_attention` (explained, so born READ) and
+  `workflow.finished` (a notice, so UNREAD). A row holds identifiers only — the
+  workflow id and type; a finished run's counts render at read time under the
+  reader's authority. Both supersede per workflow type (condition field
+  `workflowType`, renewing): one active row per workflow type per reader, and a
+  newer settlement is news again.
 - **This is a mention row, not a chat-unread model.** Being named is a discrete
   fact you come back to; "this chat has new messages" is not modeled here or
   anywhere, and the proactive `unread` flag on a chat summary stays a one-time

package/src/user-notifications/kinds.ts

@@ -229,6 +229,19 @@ export const USER_NOTIFICATION_KINDS = [
    * where the review is opened.
    */
   "proactive.org_structure_review_ready",
+
+  // ===========================================================================
+  // Workflow settlements (control ADR-CTRL-540 phase 2)
+  // ===========================================================================
+  //
+  // The durable twins of `workflow.needs_attention` / `workflow.finished`,
+  // rendered by `src/proactive/` in the backend, DISTINCT from the kind strings.
+  // A row holds identifiers only (the workflow id and type); a `notice` row's
+  // counts render at read time under the reader's authority.
+  /** A failure a person can act on. Explained: the chat holds the badge, born read. */
+  "proactive.workflow_needs_attention",
+  /** A finished run nobody watched. A notice: this row IS the attention, unread. */
+  "proactive.workflow_finished",
 ] as const;
 
 export type UserNotificationKind = (typeof USER_NOTIFICATION_KINDS)[number];

package/src/user-notifications/lifecycle-registry.ts

@@ -32,6 +32,14 @@ const STANDING = {
   resolution: RESOLVED_FOR_ALL,
   retention: "standard",
 } as const;
+/** One active row per workflow type per reader; a newer settlement renews it. */
+const PER_WORKFLOW_TYPE = {
+  condition: { scope: "fields", fields: ["workflowType"] },
+  supersedes: true,
+  attentionOnSupersede: "renew",
+  resolution: "never",
+  retention: "standard",
+} as const;
 
 /**
  * Every kind's lifecycle. Annotated (not `satisfies`) so a missing kind and an
@@ -120,4 +128,6 @@ export const NOTIFICATION_LIFECYCLE: Readonly<Record<UserNotificationKind, Notif
     resolution: RESOLVED_FOR_ALL,
     retention: "standard",
   },
+  "proactive.workflow_needs_attention": PER_WORKFLOW_TYPE,
+  "proactive.workflow_finished": PER_WORKFLOW_TYPE,
 };

package/src/workflows/README.md

@@ -40,6 +40,30 @@ so every producer, validator and renderer agrees on it.
   adding its outcome member; the union must cover every registered type.
 - **`unknown` is a safety valve, not a status.** It names an unrecognized
   terminal transition, never a workflow whose state could not be read.
+- **The offer is a function of reason** (control ADR affordance-system). Every
+  outcome carries a REQUIRED `affordances` list — the ordered next steps the
+  ending offers — fixed by its reason's per-type `*_AFFORDANCES_OF_REASON`
+  table and frozen with the outcome. The tables are total (an empty list is an
+  explicit decision) and the schema refuses any other list, a missing key and
+  more than `MAX_OFFERED_AFFORDANCES`. Producers read the offer through
+  `affordancesOfReason` only.
+- **`review.open` is projected, never stored.** It is derived from a `review`
+  disposition; an offer that contains it is refused. `affordancesOfOutcome` is
+  the single projection every consumer renders from: the frozen offer, then
+  `review.open` when the disposition is `review`.
+- **A deferred settlement's route is a function of reason** (control
+  ADR-CTRL-540 phase 2). An ending with no launching conversation takes its
+  reason's entry in the total per-type `*_DEFERRED_ROUTE_OF_REASON` table:
+  `explained` only for a `failed` or `abandoned` ending that offers at least one
+  affordance (told fact-free via `toExplainedOutcome`), `notice` for anything
+  whose telling needs counts, `covered` when a domain proactive kind normally
+  announces it (always with a `fallback: "notice"` and an audience, because
+  the backend verifies the covering occurrence at route time), and `silent`
+  exactly for `stopped_by_user`. A `produced`, `empty` or `partial` ending is
+  never explained.
+- **Workflows never imports proactive.** The covering kinds are literal
+  strings pinned against `PROACTIVE_EVENT_KIND_IDS` by a test; the dependency
+  runs proactive → workflows only.
 
 ## Public API
 
@@ -47,8 +71,20 @@ so every producer, validator and renderer agrees on it.
 - `WorkflowOutcomeSchema` / `WorkflowOutcome` and the per-type member schemas,
   reason tables, fact schemas and `WorkflowOutcomeDispositionSchema`
   (`outcome.ts`).
+- `DISCOVER_AFFORDANCES_OF_REASON`, `SYNTHESIZE_AFFORDANCES_OF_REASON`,
+  `ORG_STRUCTURE_AFFORDANCES_OF_REASON` (`outcome.ts`).
+- `WORKFLOW_AFFORDANCES_OF_REASON`, `affordancesOfReason`,
+  `affordancesOfOutcome` (`affordances-of-outcome.ts`).
+- `SETTLEMENT_AUDIENCE_POLICIES`, `SETTLEMENT_COVERING_KINDS`,
+  `SETTLEMENT_SILENT_REASONS`, `DEFERRED_ROUTES`, `DeferredRouteSchema` /
+  `DeferredRoute`, the `*_DEFERRED_ROUTE_OF_REASON` tables,
+  `WORKFLOW_DEFERRED_ROUTE_OF_REASON`, `ExplainedWorkflowOutcome` and its
+  `Explained*Reason` types, `deferredRouteOf`, `toExplainedOutcome`
+  (`deferred-route.ts`).
 
 ## Dependencies
 
-`zod` (outcome schemas) and `../input-requests/types` (the review
-disposition's request type). Otherwise pure vocabulary data and one guard.
+`zod` (outcome schemas), `../input-requests/types` (the review disposition's
+request type) and `../affordances/affordance` (the offered-affordance schema,
+its sanity bound and `sameAffordances`). Otherwise pure vocabulary data, one
+guard and pure helpers.

package/src/workflows/__tests__/README.md

@@ -17,7 +17,24 @@ wire value against it.
   (compile-time), each reason table's kinds are valid, the schema accepts a
   well-formed member and refuses a kind that does not match its reason, a
   review disposition on a non-produced outcome, a reason from another type,
-  and extra keys (the facts stay closed).
+  and extra keys (the facts stay closed). Every reason has an explicit offer
+  of offerable affordances, and the schema refuses an offer that differs from
+  its reason's table, a missing `affordances` key, `review.open` inside a
+  frozen offer and more than `MAX_OFFERED_AFFORDANCES` entries.
+
+- `affordances-of-outcome.test.ts` — `affordancesOfOutcome` projects
+  `review.open` after the frozen offer for a `review` disposition and nothing
+  extra for `narrate`; `affordancesOfReason` returns each workflow type's
+  table entry (both org-structure types share one table); every projected
+  list is a valid `Affordance` list.
+
+- `deferred-route.test.ts` — every reason of every workflow type has a valid
+  deferred route; `explained` only for a `failed`/`abandoned` ending with a
+  non-empty offer; `produced`/`empty`/`partial` never explained; `silent` ⇔
+  `stopped_by_user`; every covering kind is a real proactive kind and every
+  covered route falls back to a notice with an audience; `toExplainedOutcome`
+  strips facts and stays schema-valid; and no `src/workflows/*.ts` file
+  imports from proactive.
 
 ## Invariants
 
@@ -33,4 +50,6 @@ None — test-only.
 
 ## Dependencies
 
-`vitest` and `../types`.
+`vitest`, `node:fs`, `../types`, `../outcome`, `../affordances-of-outcome`,
+`../deferred-route`, `../../affordances/affordance` and
+`../../proactive/kinds` (test-only: pins the covering kinds).