@company-semantics/contracts 58.5.1 → 59.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "58.5.1",
+  "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/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 = 'b4aa56c17639' as const;
-export const SPEC_HASH_FULL = 'b4aa56c1763945ca5c741250d51eafeff80cd2d48b5e0441918233b5f9a6a16b' as const;
+export const SPEC_HASH = 'dd2a725d7ebd' as const;
+export const SPEC_HASH_FULL = 'dd2a725d7ebd694db25efbe0e638077984af41551c1989fb374d9a7b8bc4eb3d' as const;

package/src/api/generated.ts

@@ -5065,7 +5065,7 @@ export interface components {
             summary: {
                 executionId: string;
                 /** @enum {string} */
-                kind: "integration.connect" | "integration.disconnect" | "profile.update" | "slack.send" | "data.ingest" | "data.scope" | "system.cleanup" | "member.changeManager" | "companyMd.ingest" | "companyMd.commentPass" | "semantic.transform" | "companyMd.importContextDoc";
+                kind: "integration.connect" | "integration.disconnect" | "integration.purge" | "profile.update" | "slack.send" | "data.ingest" | "data.scope" | "system.cleanup" | "member.changeManager" | "companyMd.ingest" | "companyMd.commentPass" | "semantic.transform" | "companyMd.importContextDoc";
                 target: {
                     /** @constant */
                     type: "slack";
@@ -9116,7 +9116,7 @@ export interface operations {
             query?: {
                 cursor?: string;
                 limit?: number;
-                kind?: "integration.connect" | "integration.disconnect" | "profile.update" | "slack.send" | "data.ingest" | "data.scope" | "system.cleanup" | "member.changeManager" | "companyMd.ingest" | "companyMd.commentPass" | "semantic.transform" | "companyMd.importContextDoc";
+                kind?: "integration.connect" | "integration.disconnect" | "integration.purge" | "profile.update" | "slack.send" | "data.ingest" | "data.scope" | "system.cleanup" | "member.changeManager" | "companyMd.ingest" | "companyMd.commentPass" | "semantic.transform" | "companyMd.importContextDoc";
                 targetType?: string;
                 periodStart?: string;
                 periodEnd?: string;
@@ -9251,7 +9251,7 @@ export interface operations {
             query?: {
                 limit?: number;
                 offset?: number;
-                kind?: "integration.connect" | "integration.disconnect" | "profile.update" | "slack.send" | "data.ingest" | "data.scope" | "system.cleanup" | "member.changeManager" | "companyMd.ingest" | "companyMd.commentPass" | "semantic.transform" | "companyMd.importContextDoc";
+                kind?: "integration.connect" | "integration.disconnect" | "integration.purge" | "profile.update" | "slack.send" | "data.ingest" | "data.scope" | "system.cleanup" | "member.changeManager" | "companyMd.ingest" | "companyMd.commentPass" | "semantic.transform" | "companyMd.importContextDoc";
                 kindPrefix?: string;
             };
             header?: never;

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/execution/__tests__/registry.test.ts

@@ -53,6 +53,27 @@ describe("EXECUTION_KINDS golden snapshot", () => {
           templateId: "integration.disconnect",
         },
       },
+      "integration.purge": {
+        kind: "integration.purge",
+        domain: "integration",
+        display: {
+          label: "Purge integration data",
+          pastTenseLabel: "Integration data purged",
+          icon: "unlink",
+        },
+        governance: {
+          visibility: "admin",
+          requiresAdmin: true,
+        },
+        ui: {
+          showInAdmin: true,
+          showInTimeline: true,
+          confirmBeforeRun: true,
+        },
+        explanation: {
+          templateId: "integration.purge",
+        },
+      },
       "profile.update": {
         kind: "profile.update",
         domain: "profile",

package/src/execution/kinds.ts

@@ -36,6 +36,10 @@
 export type ExecutionKind =
   | "integration.connect"
   | "integration.disconnect"
+  /** Break-glass HRIS purge: disconnect plus an irreversible unwind of all
+   *  facts still exclusively source-owned, tombstoning the connection as
+   *  `purged`. Only providers enrolled in RETAIN_ON_DISCONNECT qualify. */
+  | "integration.purge"
   | "profile.update"
   | "slack.send"
   | "data.ingest"