@company-semantics/contracts 58.6.0 → 59.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "58.6.0",
+  "version": "59.0.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -72,7 +72,11 @@
       "types": "./src/ingestion/index.ts",
       "default": "./src/ingestion/index.ts"
     },
-    "./schemas/guard-result.schema.json": "./schemas/guard-result.schema.json"
+    "./schemas/guard-result.schema.json": "./schemas/guard-result.schema.json",
+    "./decisions": {
+      "types": "./src/decisions/index.ts",
+      "default": "./src/decisions/index.ts"
+    }
   },
   "types": "./src/index.ts",
   "files": [
@@ -127,7 +131,8 @@
     "repo-map:check": "tsx \"$(git rev-parse --path-format=absolute --git-common-dir)/../../company-semantics-ci/scripts/generate-repo-map.ts\" --roots src --name company-semantics-contracts --check",
     "readme-api": "tsx \"$(git rev-parse --path-format=absolute --git-common-dir)/../../company-semantics-ci/scripts/generate-readme-api.ts\" --roots src --write --jsdoc",
     "readme-api:check": "tsx \"$(git rev-parse --path-format=absolute --git-common-dir)/../../company-semantics-ci/scripts/generate-readme-api.ts\" --roots src --check --jsdoc",
-    "validate:amp": "tsx scripts/validate-amp.ts"
+    "validate:amp": "tsx scripts/validate-amp.ts",
+    "file-sizes:pin": "sh scripts/ci/file-sizes-pin.sh"
   },
   "packageManager": "pnpm@10.25.0",
   "engines": {

package/src/decisions/README.md

@@ -0,0 +1,41 @@
+# decisions/
+
+A question the system asks a human, and what answering it does.
+
+## Purpose
+
+The surface-agnostic vocabulary for a decidable question. One derivation
+produces a `DecisionQuestion`; the org-settings review panel renders it as radio
+buttons, the chat surface projects it onto an interactive task, and an MCP tool
+lists it for an agent. None of those owns the shape, so it lives here.
+
+It exists because an option used to be a bare string doing three jobs at once —
+the label a reviewer read, the value on the receipt, and the payload the apply
+consumed. A unit was renamed to the literal sentence
+`Rename the existing unit to 'People' (same unitId, preserving history)` because
+the label WAS the payload. `label` and `effect` are separate channels here so
+that cannot recur.
+
+## Invariants
+
+- **An apply reads `effect`, never `label`.** The label is prose for a human and
+  may say anything that makes the consequence clear.
+- **An option is named by `id`, never by its label.** Labels get reworded; an id
+  is what a receipt, a ledger row, and an agent can all still resolve.
+- `recommendedOptionId` must name one of `options`, and option ids are unique
+  within a question — both enforced by `DecisionQuestionSchema`.
+- Choosing the recommendation is the **identity transform**. A recommendation
+  describes what the surrounding proposal already encodes, so following it
+  rewrites nothing.
+- `DecisionEffect` is a **closed union**. An answer may only do things a reader
+  of `types.ts` can enumerate.
+- **`freeText` is never applied as an effect on its own.** It is recorded beside
+  a chosen option, or resolved into a proposed effect that is shown back before
+  anything runs. Turning free text into an action without showing the action is
+  the one thing this vocabulary must not enable.
+- `id` is **content-derived and durable** across re-derivations. An index into a
+  payload is not an identity.
+
+## Dependencies
+
+`zod` only. This package stays pure vocabulary — no domain logic, no I/O.

package/src/decisions/__tests__/README.md

@@ -0,0 +1,37 @@
+# decisions/\_\_tests\_\_/
+
+## Purpose
+
+Locks the one claim the type system cannot make: that an option's **effect** is
+the payload and its **label** is only prose.
+
+- `schemas.test.ts` — the load-bearing case is
+  `carries the effect separately from the label`, built from the exact question
+  that produced the defect: the option labelled
+  `Rename the existing unit to 'People' (same unitId, preserving history)` must
+  parse to `{ kind: "rename_unit", name: "People" }`. A regression that made the
+  label load-bearing again would still typecheck, because both are strings.
+
+  Also the cross-field rules an extending domain inherits and could otherwise
+  silently drop: a `recommendedOptionId` naming no option (there would be no
+  answer to "what happens if you do nothing", which is the common case), duplicate
+  option ids, and a single-option question — a notification, not a question. Plus
+  the bounds that matter at a boundary: a rename name past `org_units.name`'s 255
+  (the defect's sentence cleared every length check in the system), an unknown
+  effect kind, and `archive_unit` requiring a real uuid because it addresses a
+  DURABLE unit rather than a proposal-scoped temp id.
+
+## Invariants
+
+- These assert VOCABULARY and SHAPE, never behaviour. How an apply consumes an
+  effect belongs in backend's structure suites.
+- Fixtures use the REAL question from the incident rather than a synthetic one,
+  so a reader can see what the regression looked like.
+
+## Public API
+
+None — test-only.
+
+## Dependencies
+
+`vitest` and `../index`.

package/src/decisions/__tests__/schemas.test.ts

@@ -0,0 +1,146 @@
+/**
+ * The decision vocabulary's boundary rules.
+ *
+ * Regression origin: an org unit was renamed to the literal option label
+ * `Rename the existing unit to 'People' (same unitId, preserving history)`
+ * because the label WAS the payload. These lock the separation that replaced it.
+ */
+
+import { describe, expect, it } from "vitest";
+import {
+  DecisionAnswerSchema,
+  DecisionEffectSchema,
+  DecisionQuestionSchema,
+  followsRecommendation,
+  optionById,
+  recommendedOption,
+  type DecisionOption,
+  type DecisionQuestion,
+} from "../index";
+
+const KEEP: DecisionOption = {
+  id: "keep",
+  label:
+    "Keep the name 'Human Resources', matching the department string carried by 18 people.",
+  effect: { kind: "none" },
+};
+
+const RENAME: DecisionOption = {
+  id: "rename",
+  label:
+    "Rename the existing unit to 'People' (same unitId, preserving history)",
+  description: "Keeps its documents, history and permissions.",
+  effect: { kind: "rename_unit", unitTempId: "u_hr", name: "People" },
+};
+
+const RENAME_QUESTION: DecisionQuestion = {
+  id: "unit_name:af3dfd54",
+  header: "Unit name",
+  question:
+    "Should the Human Resources unit be renamed 'People' to match its leader's title?",
+  options: [KEEP, RENAME],
+  recommendedOptionId: "keep",
+  multiSelect: false,
+  freeFormAllowed: true,
+  confidence: 0.75,
+  signals: {
+    Departments: "'Human Resources' is the source label for 18 people.",
+  },
+};
+
+describe("DecisionQuestionSchema", () => {
+  it("accepts a question whose labels are prose and whose effect carries the name", () => {
+    const parsed = DecisionQuestionSchema.parse(RENAME_QUESTION);
+    const rename = parsed.options.find((option) => option.id === "rename");
+    // The whole point: the NAME lives in the effect, not scraped from the label.
+    expect(rename?.effect).toEqual({
+      kind: "rename_unit",
+      unitTempId: "u_hr",
+      name: "People",
+    });
+    expect(rename?.label).toContain("preserving history");
+  });
+
+  it("rejects a recommendation that names no option", () => {
+    const result = DecisionQuestionSchema.safeParse({
+      ...RENAME_QUESTION,
+      recommendedOptionId: "nonexistent",
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects duplicate option ids", () => {
+    const result = DecisionQuestionSchema.safeParse({
+      ...RENAME_QUESTION,
+      options: [KEEP, KEEP],
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects a single-option question - that is a notification, not a question", () => {
+    const result = DecisionQuestionSchema.safeParse({
+      ...RENAME_QUESTION,
+      options: [KEEP],
+    });
+    expect(result.success).toBe(false);
+  });
+});
+
+describe("DecisionEffectSchema", () => {
+  it("rejects a rename whose name is a whole sentence past the column bound", () => {
+    const result = DecisionEffectSchema.safeParse({
+      kind: "rename_unit",
+      unitTempId: "u_hr",
+      name: "x".repeat(256),
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects an unknown effect kind rather than passing it through", () => {
+    const result = DecisionEffectSchema.safeParse({
+      kind: "delete_everything",
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it("requires a real uuid for an archive, which addresses a DURABLE unit", () => {
+    const result = DecisionEffectSchema.safeParse({
+      kind: "archive_unit",
+      unitId: "u_hr",
+    });
+    expect(result.success).toBe(false);
+  });
+});
+
+describe("answer helpers", () => {
+  it("resolves the recommended option and an option by id", () => {
+    expect(recommendedOption(RENAME_QUESTION)?.id).toBe("keep");
+    expect(optionById(RENAME_QUESTION, "rename")?.effect.kind).toBe(
+      "rename_unit",
+    );
+  });
+
+  it("treats the recommendation as the identity case", () => {
+    expect(
+      followsRecommendation(RENAME_QUESTION, {
+        questionId: RENAME_QUESTION.id,
+        chosenOptionIds: ["keep"],
+      }),
+    ).toBe(true);
+    expect(
+      followsRecommendation(RENAME_QUESTION, {
+        questionId: RENAME_QUESTION.id,
+        chosenOptionIds: ["rename"],
+      }),
+    ).toBe(false);
+  });
+
+  it("accepts a free-form answer that chooses nothing", () => {
+    const parsed = DecisionAnswerSchema.parse({
+      questionId: RENAME_QUESTION.id,
+      chosenOptionIds: [],
+      freeText: "actually call it People Ops",
+    });
+    expect(parsed.freeText).toBe("actually call it People Ops");
+  });
+});

package/src/decisions/index.ts

@@ -0,0 +1,32 @@
+/**
+ * Decision vocabulary barrel — a question the system asks a human, and what
+ * answering it does.
+ *
+ * Import from '@company-semantics/contracts/decisions'.
+ *
+ * @see ./types.ts for the design rationale (display and effect are separate
+ *   channels, permanently)
+ */
+
+export type {
+  DecisionEffect,
+  DecisionOption,
+  DecisionQuestion,
+  DecisionAnswer,
+} from "./types";
+
+export {
+  DECISION_EFFECT_KINDS,
+  recommendedOption,
+  optionById,
+  followsRecommendation,
+} from "./types";
+
+export {
+  DecisionEffectSchema,
+  DecisionOptionSchema,
+  DecisionQuestionBaseSchema,
+  DecisionQuestionSchema,
+  refineDecisionQuestion,
+  DecisionAnswerSchema,
+} from "./schemas";

package/src/decisions/schemas.ts

@@ -0,0 +1,107 @@
+/**
+ * Runtime schemas for the decision vocabulary.
+ *
+ * Separate from `./types.ts` because the TYPES are the contract every consumer
+ * reads, while these schemas are what a boundary uses to prove an untrusted
+ * payload matches it. Both directions matter: a proposal's questions arrive from
+ * a model, and an answer arrives from a browser.
+ *
+ * @see ./types.ts for what each field means and why
+ */
+
+import { z } from "zod";
+
+export const DecisionEffectSchema = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("none") }),
+  z.object({
+    kind: z.literal("rename_unit"),
+    unitTempId: z.string().min(1),
+    // Bounded to `org_units.name`'s own limit. The defect this vocabulary exists
+    // to prevent produced a 62-character SENTENCE as a unit name, which every
+    // length bound in the system happily accepted.
+    name: z.string().min(1).max(255),
+  }),
+  z.object({
+    kind: z.literal("place_people"),
+    personIds: z.array(z.string()),
+    unitTempId: z.string().min(1),
+  }),
+  z.object({ kind: z.literal("unadopt_unit"), unitTempId: z.string().min(1) }),
+  z.object({ kind: z.literal("archive_unit"), unitId: z.string().uuid() }),
+  z.object({
+    kind: z.literal("needs_reinference"),
+    note: z.string().min(1).max(500),
+  }),
+]);
+
+export const DecisionOptionSchema = z.object({
+  id: z.string().min(1).max(64),
+  label: z.string().min(1).max(500),
+  description: z.string().max(1000).optional(),
+  effect: DecisionEffectSchema,
+});
+
+/**
+ * The question's own fields, WITHOUT the cross-field checks.
+ *
+ * Exported so a domain can `.extend(...)` it with its own addressing (which
+ * people, which units) and re-apply {@link refineDecisionQuestion}. Zod's
+ * `superRefine` returns a `ZodEffects`, which cannot be extended — so the base
+ * and the refinement have to be separable or every domain would restate the
+ * shape and drift from it.
+ */
+export const DecisionQuestionBaseSchema = z.object({
+  id: z.string().min(1).max(200),
+  header: z.string().min(1).max(60),
+  question: z.string().min(1).max(1000),
+  // Two is the floor: one option is a notification, not a question.
+  options: z.array(DecisionOptionSchema).min(2).max(8),
+  recommendedOptionId: z.string().min(1),
+  multiSelect: z.boolean(),
+  freeFormAllowed: z.boolean(),
+  confidence: z.number().min(0).max(1),
+  signals: z.record(z.string(), z.string()),
+});
+
+/**
+ * The cross-field rules every decision question obeys, wherever it is declared.
+ *
+ * Kept as a standalone refiner so a domain that extends
+ * {@link DecisionQuestionBaseSchema} inherits the rules rather than reimplementing
+ * (and eventually contradicting) them.
+ */
+export function refineDecisionQuestion(
+  question: {
+    options: ReadonlyArray<{ id: string }>;
+    recommendedOptionId: string;
+  },
+  ctx: z.RefinementCtx,
+): void {
+  const ids = question.options.map((option) => option.id);
+  if (new Set(ids).size !== ids.length) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["options"],
+      message: "option ids must be unique within a question",
+    });
+  }
+  // A recommendation naming no option means "what happens if you do nothing"
+  // has no answer — and doing nothing is the common case.
+  if (!ids.includes(question.recommendedOptionId)) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["recommendedOptionId"],
+      message: `recommendedOptionId '${question.recommendedOptionId}' names no option`,
+    });
+  }
+}
+
+export const DecisionQuestionSchema = DecisionQuestionBaseSchema.superRefine(
+  refineDecisionQuestion,
+);
+
+export const DecisionAnswerSchema = z.object({
+  questionId: z.string().min(1).max(200),
+  chosenOptionIds: z.array(z.string().min(1).max(64)).max(8),
+  freeText: z.string().max(2000).optional(),
+});

package/src/decisions/types.ts

@@ -0,0 +1,192 @@
+/**
+ * A question the system asks a human, and what answering it DOES.
+ *
+ * WHY THIS EXISTS. A review question used to be three strings: `question`, a
+ * `recommended` option and a list of `alternatives`. The option string did
+ * triple duty — the radio label a reviewer read, the value recorded on the
+ * receipt, AND the payload the apply consumed. That works only while every
+ * option happens to be bare data. It stopped working the moment options carried
+ * their consequence in prose, which is what a reviewer actually needs to read:
+ * an org unit was renamed to the literal sentence
+ * `Rename the existing unit to 'People' (same unitId, preserving history)`.
+ *
+ * So DISPLAY and EFFECT are separate channels here, permanently.
+ * {@link DecisionOption.label} is prose, rendered verbatim, free to say whatever
+ * makes the consequence clear. {@link DecisionOption.effect} is the machine
+ * meaning, and it is the only thing an apply is allowed to read.
+ *
+ * SHAPE. Modelled on the question surface an agent already presents well: a
+ * question, a short header, two-to-four options that each carry both a label and
+ * what it means, one of them recommended, and — where the domain can honour it —
+ * an "other" arm for an answer nobody enumerated.
+ *
+ * SURFACE-AGNOSTIC ON PURPOSE. The same question is rendered as radio buttons in
+ * org settings, is projected onto the chat interactive-task surface, and is
+ * listed by an MCP tool for an agent. None of those may own the vocabulary, so
+ * it lives here.
+ *
+ * @see ADR-CONTRACTS-147
+ */
+
+/**
+ * What choosing an option DOES.
+ *
+ * A closed union rather than a free-form patch: an effect is produced by a
+ * derivation the human did not write and consumed by an apply that writes
+ * durable structure, so the set of things an answer can do has to be
+ * enumerable by a reader of this file.
+ *
+ * `none` is a first-class member, not a gap. Several genuine questions have no
+ * deterministic rewrite — redrawing a unit boundary needs re-inference, not a
+ * label swap — and saying so explicitly is honest where silently recording the
+ * answer and doing nothing is not.
+ */
+export type DecisionEffect =
+  /** Answering changes nothing. The answer is recorded, and that is the whole effect. */
+  | { readonly kind: "none" }
+  /**
+   * Rename a unit the proposal already contains, addressed by its
+   * proposal-scoped temp id. The name is THIS field — never the option's label.
+   */
+  | {
+      readonly kind: "rename_unit";
+      readonly unitTempId: string;
+      readonly name: string;
+    }
+  /** Move these people's placements to the named proposed unit. */
+  | {
+      readonly kind: "place_people";
+      readonly personIds: readonly string[];
+      readonly unitTempId: string;
+    }
+  /**
+   * Stop reusing a pre-existing durable unit: create the proposed unit instead
+   * and leave the reviewer's own where it is.
+   */
+  | { readonly kind: "unadopt_unit"; readonly unitTempId: string }
+  /** Archive a DURABLE unit, addressed by its real id. Soft delete, reversible. */
+  | { readonly kind: "archive_unit"; readonly unitId: string }
+  /**
+   * The answer is understood but cannot be honoured mechanically — it needs the
+   * derivation to run again. Carries the reason so the follow-up has something
+   * to act on, and so the reviewer is not told "saved" when nothing moved.
+   */
+  | { readonly kind: "needs_reinference"; readonly note: string };
+
+/** The closed set of effect kinds, as runtime data for validators. */
+export const DECISION_EFFECT_KINDS = [
+  "none",
+  "rename_unit",
+  "place_people",
+  "unadopt_unit",
+  "archive_unit",
+  "needs_reinference",
+] as const satisfies ReadonlyArray<DecisionEffect["kind"]>;
+
+/** One answer a human may give, with what it means and what it does. */
+export interface DecisionOption {
+  /**
+   * Stable within its question, and the value an answer names.
+   *
+   * An id rather than the label, because a label is prose: it gets reworded, it
+   * is long, it cannot be typed back by an agent, and matching on it makes the
+   * display copy load-bearing. `keep` / `rename` — short, and meaningful in a
+   * receipt read a year later.
+   */
+  readonly id: string;
+  /** Rendered verbatim to the human. Prose; may carry the consequence. */
+  readonly label: string;
+  /** The implication, shown under the label. */
+  readonly description?: string;
+  /** What choosing this option does. The ONLY channel an apply may read. */
+  readonly effect: DecisionEffect;
+}
+
+/** A question, its options, and everything a human needs to answer it well. */
+export interface DecisionQuestion {
+  /**
+   * Stable identity for this question, DURABLE across re-derivations.
+   *
+   * Content-derived from what the question is about, so answering it once can
+   * outlive the run that asked it. An index into a payload cannot: it is valid
+   * only while that exact payload is.
+   */
+  readonly id: string;
+  /** Short chip, e.g. `Unit name`. Two or three words. */
+  readonly header: string;
+  /** The question, phrased for a human. */
+  readonly question: string;
+  /** The offered answers. At least two, or it is not a question. */
+  readonly options: readonly DecisionOption[];
+  /** Which option applies when the human does not choose. Must name one of `options`. */
+  readonly recommendedOptionId: string;
+  /** Whether more than one option may be chosen at once. */
+  readonly multiSelect: boolean;
+  /**
+   * Whether an answer outside `options` is accepted.
+   *
+   * False does not mean the human is wrong to want one — it means this question
+   * has no way to honour it, so offering the box would be a lie.
+   */
+  readonly freeFormAllowed: boolean;
+  /** How sure the derivation is of its recommendation, 0..1. */
+  readonly confidence: number;
+  /** Each competing signal and a one-line reading of what it says. */
+  readonly signals: Readonly<Record<string, string>>;
+}
+
+/** One answer to one question. */
+export interface DecisionAnswer {
+  readonly questionId: string;
+  /**
+   * The chosen options. Empty only when the answer is purely free-form.
+   *
+   * A list even for a single-select question, so a multi-select answer is the
+   * same shape rather than a second one.
+   */
+  readonly chosenOptionIds: readonly string[];
+  /**
+   * What the human typed — the "other" arm, or a note attached to a chosen
+   * option.
+   *
+   * NEVER applied as an effect on its own. It is either recorded alongside the
+   * chosen option, or resolved into a proposed effect that is shown back before
+   * anything runs. Interpreting free text INTO an action without showing the
+   * action is the one thing this vocabulary must not enable.
+   */
+  readonly freeText?: string;
+}
+
+/** Find the recommended option, or undefined when the question is malformed. */
+export function recommendedOption(
+  question: DecisionQuestion,
+): DecisionOption | undefined {
+  return question.options.find(
+    (option) => option.id === question.recommendedOptionId,
+  );
+}
+
+/** Find an option by id. */
+export function optionById(
+  question: DecisionQuestion,
+  optionId: string,
+): DecisionOption | undefined {
+  return question.options.find((option) => option.id === optionId);
+}
+
+/**
+ * True when the answer is exactly the recommendation.
+ *
+ * The identity case: a recommendation is what the surrounding proposal already
+ * encodes, so following it must be a no-op rather than a rewrite that happens to
+ * land on the same value.
+ */
+export function followsRecommendation(
+  question: DecisionQuestion,
+  answer: DecisionAnswer,
+): boolean {
+  return (
+    answer.chosenOptionIds.length === 1 &&
+    answer.chosenOptionIds[0] === question.recommendedOptionId
+  );
+}

package/src/index.ts

@@ -1376,3 +1376,9 @@ export * from "./ingestion";
 // HrConnectionStatus / HrConnectInput — see ./integrations/schemas.ts.
 // Pairs with the `HR` member of INTEGRATION_CATEGORIES above.
 export * from "./integrations";
+
+// Decision vocabulary (ADR-CONTRACTS-147 / ADR-BE-639)
+// A question the system asks a human, and what answering it DOES. Display and
+// effect are separate channels: an option's `label` is prose for a reader, its
+// `effect` is the only thing an apply may read. See ./decisions/types.ts.
+export * from "./decisions";

package/src/org/README.md

@@ -340,6 +340,7 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `RoleCatalogEntry` _(type)_ — Entry in the RBAC roles catalog (GET /api/rbac/roles).
 - `RoleCatalogEntrySchema`
 - `RoleCatalogResponseSchema`
+- `STRUCTURE_REVIEW_ITEM_KINDS` — A question the engine is asking a human, with the competing signals attached.
 - `ScopeCheckBatchResponse` _(type)_
 - `ScopeCheckBatchResponseSchema`
 - `ScopeCheckResponse` _(type)_
@@ -385,7 +386,7 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `StructureReportingFact` _(type)_
 - `StructureReportingFactSchema` — One reporting edge, at person granularity.
 - `StructureReviewItem` _(type)_
-- `StructureReviewItemSchema` — A question the engine is asking a human, with the competing signals attached.
+- `StructureReviewItemSchema` — A review item IS a {@link DecisionQuestion}, plus the addressing that says what the question is about.
 - `StructureUnitAuthority` _(type)_
 - `StructureUnitAuthoritySchema` — How much license the engine has over an EXISTING unit or placement.
 - `SubmitInteractiveTaskResponse` _(type)_
@@ -474,6 +475,7 @@ Shared type vocabulary for organization ownership, type classification, and tran
 **Internal domains:**
 
 - `api`
+- `decisions`
 - `identity`
 - `permissions`
 

package/src/org/__tests__/structure-inference.test.ts

@@ -218,11 +218,34 @@ describe("PersonStructureOutcomeSchema", () => {
 describe("StructureReviewItemSchema", () => {
   const base = {
     kind: "placement_conflict",
+    id: "placement_conflict:clarissa",
+    header: "Placement",
     personIds: ["clarissa"],
     unitTempIds: ["u1", "u2"],
     question: "Which unit does this Account Executive belong to?",
-    recommended: "u2",
-    alternatives: ["u1"],
+    options: [
+      {
+        id: "u2",
+        label: "Sales — matching the role family the other 11 AEs sit in",
+        effect: {
+          kind: "place_people",
+          personIds: ["clarissa"],
+          unitTempId: "u2",
+        },
+      },
+      {
+        id: "u1",
+        label: "Marketing — matching the manager she reports to",
+        effect: {
+          kind: "place_people",
+          personIds: ["clarissa"],
+          unitTempId: "u1",
+        },
+      },
+    ],
+    recommendedOptionId: "u2",
+    multiSelect: false,
+    freeFormAllowed: false,
     signals: {
       department: "Human Resources",
       manager: "VP of Marketing",
@@ -243,6 +266,51 @@ describe("StructureReviewItemSchema", () => {
       StructureReviewItemSchema.parse({ ...base, kind: "something_else" }),
     ).toThrow();
   });
+
+  it("accepts the three rule-derived kinds the backend attaches after the gate", () => {
+    for (const kind of [
+      "reporting_anomaly",
+      "unit_adoption",
+      "unit_retirement",
+    ]) {
+      expect(() =>
+        StructureReviewItemSchema.parse({ ...base, kind }),
+      ).not.toThrow();
+    }
+  });
+
+  it("inherits the decision rules — a recommendation must name a real option", () => {
+    expect(() =>
+      StructureReviewItemSchema.parse({ ...base, recommendedOptionId: "u9" }),
+    ).toThrow();
+  });
+
+  it("carries the effect separately from the label, so an apply never reads prose", () => {
+    const parsed = StructureReviewItemSchema.parse({
+      ...base,
+      kind: "unit_name",
+      options: [
+        {
+          id: "keep",
+          label: "Keep the name 'Human Resources'.",
+          effect: { kind: "none" },
+        },
+        {
+          id: "rename",
+          label:
+            "Rename the existing unit to 'People' (same unitId, preserving history)",
+          effect: { kind: "rename_unit", unitTempId: "u1", name: "People" },
+        },
+      ],
+      recommendedOptionId: "keep",
+    });
+    const rename = parsed.options.find((option) => option.id === "rename");
+    expect(rename?.effect).toEqual({
+      kind: "rename_unit",
+      unitTempId: "u1",
+      name: "People",
+    });
+  });
 });
 
 describe("StructureProposalSchema", () => {

package/src/org/index.ts

@@ -251,6 +251,7 @@ export {
   ProposedOrgUnitSchema,
   PersonStructureOutcomeSchema,
   StructureReviewItemSchema,
+  STRUCTURE_REVIEW_ITEM_KINDS,
   StructureProposalSchema,
   StructurePersonFactSchema,
   StructureReportingFactSchema,

package/src/org/structure-inference.ts

@@ -69,6 +69,10 @@
 import { z } from "zod";
 
 import { PositionReportingRelationshipTypeSchema } from "./position-reporting";
+import {
+  DecisionQuestionBaseSchema,
+  refineDecisionQuestion,
+} from "../decisions/schemas";
 
 // ---------------------------------------------------------------------------
 // StructureEvidence — typed support for a boundary, a name or a placement
@@ -378,28 +382,44 @@ export type PersonStructureOutcome = z.infer<
  * never asks scores well on placement accuracy while being WORSE for the
  * product than one that reports three signals disagreeing.
  */
-export const StructureReviewItemSchema = z.object({
-  kind: z.enum([
-    "placement_conflict",
-    "unit_boundary",
-    "unit_name",
-    "unit_head",
-  ]),
+export const STRUCTURE_REVIEW_ITEM_KINDS = [
+  "placement_conflict",
+  "unit_boundary",
+  "unit_name",
+  "unit_head",
+  "reporting_anomaly",
+  "unit_adoption",
+  "unit_retirement",
+] as const;
+
+/**
+ * A review item IS a {@link DecisionQuestion}, plus the addressing that says
+ * what the question is about.
+ *
+ * It used to carry `recommended: string` and `alternatives: string[]` instead of
+ * options — three strings where the option text was simultaneously the label a
+ * reviewer read, the value on the receipt, and the payload the apply consumed.
+ * A unit was renamed to the literal sentence
+ * `Rename the existing unit to 'People' (same unitId, preserving history)`
+ * because of it. `options[].effect` is the channel that replaced the third job;
+ * see `../decisions/types.ts`.
+ */
+export const StructureReviewItemSchema = DecisionQuestionBaseSchema.extend({
+  kind: z.enum(STRUCTURE_REVIEW_ITEM_KINDS),
   /** Opaque person ids this question is about. */
   personIds: z.array(z.string()),
   /** Proposal-scoped unit handles this question is about. */
   unitTempIds: z.array(z.string()),
-  /** The question, phrased for a human reviewer. */
-  question: z.string(),
-  /** What the engine would do absent an answer. */
-  recommended: z.string(),
-  /** The other defensible answers. */
-  alternatives: z.array(z.string()),
+  /**
+   * DURABLE `org_units.id`s the question is about — a different address space
+   * from {@link StructureReviewItemSchema.shape.unitTempIds}, which is
+   * proposal-scoped. Needed because reconciliation asks about units that already
+   * exist and which the proposal may not contain at all.
+   */
+  unitIds: z.array(z.string()).optional(),
   /** The competing signals, so a reviewer can see WHY it is ambiguous. */
-  signals: z.record(z.string(), z.string()),
-  confidence: z.number().min(0).max(1),
   evidence: z.array(StructureEvidenceSchema),
-});
+}).superRefine(refineDecisionQuestion);
 export type StructureReviewItem = z.infer<typeof StructureReviewItemSchema>;
 
 // ---------------------------------------------------------------------------

package/src/resource-key-tables.ts

@@ -0,0 +1,191 @@
+/**
+ * fromQueryKey's routing tables, and the drift detector over them.
+ *
+ * Data, not operations: `resource-keys.ts` owns the round trip and reads these.
+ * Split out of that module, which had reached its size envelope — the seam is the
+ * one its own docblock already names (vocabulary in `resource-key-types.ts`,
+ * operations in `resource-keys.ts`, and these tables which are neither).
+ * See ADR-CONTRACTS-145.
+ */
+
+import type { ResourceKey } from "./resource-key-types";
+
+/*
+ * ---------------------------------------------------------------------------
+ * fromQueryKey's routing tables, and the drift detector over them.
+ * ---------------------------------------------------------------------------
+ *
+ * `toQueryKey` has always been safe: its switch is exhaustive and its `never`
+ * guard makes a new union member a compile error. `fromQueryKey` was not. Its
+ * five lookup tables are hand-maintained, and a member missing from all of them
+ * fell through to a RUNTIME `throw` — which `matchesResourceKey` catches and
+ * turns into "matches nothing", and which `useResource` turns into a query that
+ * never fetches. Silent in both directions (ADR-CONTRACTS-119).
+ *
+ * Two mechanisms, and BOTH are needed:
+ *
+ *   `satisfies` on each table catches a WRONG entry — a typo, or a literal
+ *   parked under the wrong scope. It cannot catch an entry that is simply
+ *   absent, because an array is free to be a subset of its element type.
+ *
+ *   `_EveryResourceKeyIsRouted` below catches the ABSENT entry, which is the
+ *   failure that actually shipped. It is the half that closes the hole.
+ */
+
+/**
+ * The identity segments a member carries — every field that is neither the type
+ * tag nor a scope discriminator. `member` → `"memberId"`; `commentThreads` →
+ * `"subjectType" | "subjectId"`; a scope-only key → `never`.
+ */
+type IdentityFieldsOf<T extends ResourceKey["type"]> = Exclude<
+  keyof Extract<ResourceKey, { type: T }>,
+  "type" | "orgId" | "userId" | "scope"
+>;
+
+/**
+ * Type literals whose whole shape is the tag plus one scope discriminator —
+ * i.e. the members that belong in a scope ARRAY rather than an identity MAP.
+ * Distributes over the union (`K` is a naked type parameter).
+ */
+type ScopeOnlyType<K = ResourceKey> = K extends {
+  type: infer T extends ResourceKey["type"];
+}
+  ? [IdentityFieldsOf<T>] extends [never]
+    ? T
+    : never
+  : never;
+
+type OrgScopedType = Extract<
+  ScopeOnlyType,
+  Extract<ResourceKey, { orgId: string }>["type"]
+>;
+type UserScopedType = Extract<
+  ScopeOnlyType,
+  Extract<ResourceKey, { userId: string }>["type"]
+>;
+type SystemScopedType = Extract<
+  ScopeOnlyType,
+  Extract<ResourceKey, { scope: "system" }>["type"]
+>;
+
+/**
+ * Identities with a single extra segment. The `satisfies` checks the FIELD NAME
+ * against that member's own keys, so renaming `memberId` in the union — or
+ * pointing a key at a field it does not have — fails to compile here.
+ */
+export const IDENTITY_FIELDS = {
+  member: "memberId",
+  team: "teamId",
+  department: "departmentId",
+  chat: "chatId",
+  companyMdDoc: "slug",
+  companyMdContextBank: "slug",
+  companyMdAccessRequests: "docId",
+  companyMdDocHistory: "docId",
+  orgUnit: "unitId",
+  orgUnitChildren: "unitId",
+  orgUnitAncestors: "unitId",
+  orgUnitMemberships: "unitId",
+  orgUnitPermissions: "unitId",
+  orgUnitOpenRoles: "unitId",
+  orgUnitMyAuthority: "unitId",
+} as const satisfies { [T in ResourceKey["type"]]?: IdentityFieldsOf<T> };
+
+/**
+ * Identities with a COMPOSITE (multi-segment) identity. Checked before
+ * {@link IDENTITY_FIELDS}, which hard-asserts a two-element `rest` and would
+ * otherwise reject these.
+ *
+ * A map of its own rather than widening `IDENTITY_FIELDS` to `string | string[]`:
+ * the single-segment case is every other key in the union, and making it pay for
+ * this one would put a branch in the hot path for no reader's benefit.
+ */
+export const COMPOSITE_IDENTITY_FIELDS = {
+  commentThreads: ["subjectType", "subjectId"],
+  companyMdDocVersion: ["docId", "versionId"],
+} as const satisfies {
+  [T in ResourceKey["type"]]?: readonly IdentityFieldsOf<T>[];
+};
+
+export const ORG_SCOPED_TYPES = [
+  "members",
+  "departments",
+  "chats",
+  "teams",
+  "integrations",
+  "invites",
+  "orgDirectory",
+  "auditEvents",
+  "timeline",
+  "workspace",
+  "workspaceDomains",
+  "authSettings",
+  "billing",
+  "aiUsage",
+  "deletionEligibility",
+  "transferOwnership",
+  "companyMdDocs",
+  "directGrants",
+  "orgTree",
+  "orgLevelConfig",
+  "peopleOrgChart",
+  "orgUnitOwners",
+  "actionItems",
+  "feed",
+  "orgSystemEvents",
+] as const satisfies readonly OrgScopedType[];
+
+export const USER_SCOPED_TYPES = [
+  "dismissedBanners",
+  "userOrgs",
+  "sessions",
+  "userMd",
+  "viewer",
+] as const satisfies readonly UserScopedType[];
+
+/**
+ * System-scoped types (ADR-CONTRACTS-052) — tenant-less super-admin resources.
+ * Their query key is [type, 'system']; they carry no orgId or userId.
+ * Exported only for `resource-keys.ts`, the parser that reads them; like the other
+ * scope arrays they are not part of the package barrel.
+ */
+export const SYSTEM_SCOPED_TYPES = [
+  "internalAdminAiProviders",
+  "internalAdminPrompts",
+  "internalAdminAiRuntimeDefaults",
+  "factoryFloor",
+  "factorySnapshot",
+  "factoryKpis",
+] as const satisfies readonly SystemScopedType[];
+
+/** Every literal `fromQueryKey` can route, across all five tables. */
+type RoutedType =
+  | keyof typeof IDENTITY_FIELDS
+  | keyof typeof COMPOSITE_IDENTITY_FIELDS
+  | (typeof ORG_SCOPED_TYPES)[number]
+  | (typeof USER_SCOPED_TYPES)[number]
+  | (typeof SYSTEM_SCOPED_TYPES)[number];
+
+type Assert<T extends true> = T;
+
+/**
+ * THE DRIFT DETECTOR. Register a union member and forget its routing table and
+ * this fails to compile — instead of shipping a key that parses nowhere,
+ * matches nothing, and disables the query that reads it.
+ *
+ * The false branch resolves to the UNROUTED LITERALS rather than to `false`, so
+ * the diagnostic names the culprit:
+ *   `Type '"directGrants"' does not satisfy the constraint 'true'`.
+ *
+ * EXPORTED, though nothing consumes it. This package ships `src`, so every
+ * consumer typechecks this file under ITS OWN compiler options — and the
+ * backend sets `noUnusedLocals`, which rejects an unexported type alias that
+ * nothing references. Keeping it private broke `tsc` in a consumer while
+ * passing here, so the export is what makes the assertion portable, not a
+ * widening of the public vocabulary. Do not "tidy" it away.
+ */
+export type RoutingExhaustivenessWitness = Assert<
+  [Exclude<ResourceKey["type"], RoutedType>] extends [never]
+    ? true
+    : Exclude<ResourceKey["type"], RoutedType>
+>;

package/src/resource-keys.ts

@@ -25,184 +25,20 @@ export function resolveScope(context: {
   return { orgId: context.impersonatedOrgId ?? context.orgId };
 }
 
-/*
- * ---------------------------------------------------------------------------
- * fromQueryKey's routing tables, and the drift detector over them.
- * ---------------------------------------------------------------------------
- *
- * `toQueryKey` has always been safe: its switch is exhaustive and its `never`
- * guard makes a new union member a compile error. `fromQueryKey` was not. Its
- * five lookup tables are hand-maintained, and a member missing from all of them
- * fell through to a RUNTIME `throw` — which `matchesResourceKey` catches and
- * turns into "matches nothing", and which `useResource` turns into a query that
- * never fetches. Silent in both directions (ADR-CONTRACTS-119).
- *
- * Two mechanisms, and BOTH are needed:
- *
- *   `satisfies` on each table catches a WRONG entry — a typo, or a literal
- *   parked under the wrong scope. It cannot catch an entry that is simply
- *   absent, because an array is free to be a subset of its element type.
- *
- *   `_EveryResourceKeyIsRouted` below catches the ABSENT entry, which is the
- *   failure that actually shipped. It is the half that closes the hole.
- */
-
-/**
- * The identity segments a member carries — every field that is neither the type
- * tag nor a scope discriminator. `member` → `"memberId"`; `commentThreads` →
- * `"subjectType" | "subjectId"`; a scope-only key → `never`.
- */
-type IdentityFieldsOf<T extends ResourceKey["type"]> = Exclude<
-  keyof Extract<ResourceKey, { type: T }>,
-  "type" | "orgId" | "userId" | "scope"
->;
-
-/**
- * Type literals whose whole shape is the tag plus one scope discriminator —
- * i.e. the members that belong in a scope ARRAY rather than an identity MAP.
- * Distributes over the union (`K` is a naked type parameter).
- */
-type ScopeOnlyType<K = ResourceKey> = K extends {
-  type: infer T extends ResourceKey["type"];
-}
-  ? [IdentityFieldsOf<T>] extends [never]
-    ? T
-    : never
-  : never;
-
-type OrgScopedType = Extract<
-  ScopeOnlyType,
-  Extract<ResourceKey, { orgId: string }>["type"]
->;
-type UserScopedType = Extract<
-  ScopeOnlyType,
-  Extract<ResourceKey, { userId: string }>["type"]
->;
-type SystemScopedType = Extract<
-  ScopeOnlyType,
-  Extract<ResourceKey, { scope: "system" }>["type"]
->;
-
-/**
- * Identities with a single extra segment. The `satisfies` checks the FIELD NAME
- * against that member's own keys, so renaming `memberId` in the union — or
- * pointing a key at a field it does not have — fails to compile here.
- */
-const IDENTITY_FIELDS = {
-  member: "memberId",
-  team: "teamId",
-  department: "departmentId",
-  chat: "chatId",
-  companyMdDoc: "slug",
-  companyMdContextBank: "slug",
-  companyMdAccessRequests: "docId",
-  companyMdDocHistory: "docId",
-  orgUnit: "unitId",
-  orgUnitChildren: "unitId",
-  orgUnitAncestors: "unitId",
-  orgUnitMemberships: "unitId",
-  orgUnitPermissions: "unitId",
-  orgUnitOpenRoles: "unitId",
-  orgUnitMyAuthority: "unitId",
-} as const satisfies { [T in ResourceKey["type"]]?: IdentityFieldsOf<T> };
-
-/**
- * Identities with a COMPOSITE (multi-segment) identity. Checked before
- * {@link IDENTITY_FIELDS}, which hard-asserts a two-element `rest` and would
- * otherwise reject these.
- *
- * A map of its own rather than widening `IDENTITY_FIELDS` to `string | string[]`:
- * the single-segment case is every other key in the union, and making it pay for
- * this one would put a branch in the hot path for no reader's benefit.
- */
-const COMPOSITE_IDENTITY_FIELDS = {
-  commentThreads: ["subjectType", "subjectId"],
-  companyMdDocVersion: ["docId", "versionId"],
-} as const satisfies {
-  [T in ResourceKey["type"]]?: readonly IdentityFieldsOf<T>[];
-};
-
-const ORG_SCOPED_TYPES = [
-  "members",
-  "departments",
-  "chats",
-  "teams",
-  "integrations",
-  "invites",
-  "orgDirectory",
-  "auditEvents",
-  "timeline",
-  "workspace",
-  "workspaceDomains",
-  "authSettings",
-  "billing",
-  "aiUsage",
-  "deletionEligibility",
-  "transferOwnership",
-  "companyMdDocs",
-  "directGrants",
-  "orgTree",
-  "orgLevelConfig",
-  "peopleOrgChart",
-  "orgUnitOwners",
-  "actionItems",
-  "feed",
-  "orgSystemEvents",
-] as const satisfies readonly OrgScopedType[];
-
-const USER_SCOPED_TYPES = [
-  "dismissedBanners",
-  "userOrgs",
-  "sessions",
-  "userMd",
-  "viewer",
-] as const satisfies readonly UserScopedType[];
-
 /**
- * System-scoped types (ADR-CONTRACTS-052) — tenant-less super-admin resources.
- * Their query key is [type, 'system']; they carry no orgId or userId.
- * Intentionally NOT exported — internal to the parser like the other scope arrays.
- */
-const SYSTEM_SCOPED_TYPES = [
-  "internalAdminAiProviders",
-  "internalAdminPrompts",
-  "internalAdminAiRuntimeDefaults",
-  "factoryFloor",
-  "factorySnapshot",
-  "factoryKpis",
-] as const satisfies readonly SystemScopedType[];
-
-/** Every literal `fromQueryKey` can route, across all five tables. */
-type RoutedType =
-  | keyof typeof IDENTITY_FIELDS
-  | keyof typeof COMPOSITE_IDENTITY_FIELDS
-  | (typeof ORG_SCOPED_TYPES)[number]
-  | (typeof USER_SCOPED_TYPES)[number]
-  | (typeof SYSTEM_SCOPED_TYPES)[number];
-
-type Assert<T extends true> = T;
-
-/**
- * THE DRIFT DETECTOR. Register a union member and forget its routing table and
- * this fails to compile — instead of shipping a key that parses nowhere,
- * matches nothing, and disables the query that reads it.
- *
- * The false branch resolves to the UNROUTED LITERALS rather than to `false`, so
- * the diagnostic names the culprit:
- *   `Type '"directGrants"' does not satisfy the constraint 'true'`.
- *
- * EXPORTED, though nothing consumes it. This package ships `src`, so every
- * consumer typechecks this file under ITS OWN compiler options — and the
- * backend sets `noUnusedLocals`, which rejects an unexported type alias that
- * nothing references. Keeping it private broke `tsc` in a consumer while
- * passing here, so the export is what makes the assertion portable, not a
- * widening of the public vocabulary. Do not "tidy" it away.
+ * The routing tables `fromQueryKey` reads, and the drift detector over them,
+ * live in `resource-key-tables.ts`. `RoutingExhaustivenessWitness` is
+ * re-exported so its import path is unchanged — see the note on its definition
+ * for why it is exported at all.
  */
-export type RoutingExhaustivenessWitness = Assert<
-  [Exclude<ResourceKey["type"], RoutedType>] extends [never]
-    ? true
-    : Exclude<ResourceKey["type"], RoutedType>
->;
+export type { RoutingExhaustivenessWitness } from "./resource-key-tables";
+import {
+  IDENTITY_FIELDS,
+  COMPOSITE_IDENTITY_FIELDS,
+  ORG_SCOPED_TYPES,
+  USER_SCOPED_TYPES,
+  SYSTEM_SCOPED_TYPES,
+} from "./resource-key-tables";
 
 /**
  * Canonical ResourceKey → query key conversion.