@company-semantics/contracts 58.5.1 → 59.0.0

package/src/execution/registry.ts

@@ -76,6 +76,29 @@ export const EXECUTION_KINDS = {
       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,
+      // Irreversible by design: the unwind deletes source-owned facts and
+      // history, so no kind reverses this one (reversibleBy stays unset).
+    },
+    ui: {
+      showInAdmin: true,
+      showInTimeline: true,
+      confirmBeforeRun: true,
+    },
+    explanation: {
+      templateId: "integration.purge",
+    },
+  },
   "profile.update": {
     kind: "profile.update",
     domain: "profile",

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/integrations/README.md

@@ -36,6 +36,8 @@ alongside `Meetings`, `Comms`, and `Docs`.
 - `HrConnectInputSchema` — Input submitted by the app to initiate an HR provider connection.
 - `HrConnectionStatus` _(type)_
 - `HrConnectionStatusSchema` — Health of the most recent HR provider sync.
+- `HrisPurgeImpact` _(type)_
+- `HrisPurgeImpactSchema` — Impact of a break-glass HRIS purge (`integration.purge`), counted per entity.
 
 <!-- END GENERATED: readme-public-api -->
 

package/src/integrations/index.ts

@@ -3,6 +3,14 @@
  *
  * @see ./schemas.ts for the full schema definitions and invariants.
  */
-export { HrConnectionStatusSchema, HrConnectInputSchema } from "./schemas";
+export {
+  HrConnectionStatusSchema,
+  HrConnectInputSchema,
+  HrisPurgeImpactSchema,
+} from "./schemas";
 
-export type { HrConnectionStatus, HrConnectInput } from "./schemas";
+export type {
+  HrConnectionStatus,
+  HrConnectInput,
+  HrisPurgeImpact,
+} from "./schemas";

package/src/integrations/schemas.ts

@@ -146,3 +146,90 @@ export const HrConnectInputSchema = z
     description: "Input to initiate an HR provider connection.",
   });
 export type HrConnectInput = z.infer<typeof HrConnectInputSchema>;
+
+// =============================================================================
+// HRIS purge impact
+// =============================================================================
+
+/**
+ * Impact of a break-glass HRIS purge (`integration.purge`), counted per
+ * entity. One shape serves four readers: the purge-preview response, the
+ * execution result, the `integration.purged` fact details, and the
+ * `connection.purged` audit metadata. Preview and purge are built from the
+ * same predicate builders, so on an unchanged org the previewed counts and
+ * the executed counts are equal by construction.
+ */
+export const HrisPurgeImpactSchema = z
+  .object({
+    peopleUnlinked: z.number().int().min(0).meta({
+      description: "Provider identity links deleted (people unlinked).",
+    }),
+    personsRetained: z
+      .number()
+      .int()
+      .min(0)
+      .meta({
+        description:
+          "Persons left in the graph — always all of them; persons are " +
+          "never deleted by a purge, only unlinked from the provider.",
+      }),
+    unitsArchived: z.number().int().min(0).meta({
+      description: "Source-owned org units soft-archived.",
+    }),
+    unitsRetained: z.number().int().min(0).meta({
+      description:
+        "Provider-imported org units retained because a user claimed them.",
+    }),
+    positionsClosed: z.number().int().min(0).meta({
+      description: "Source-owned positions closed (never deleted).",
+    }),
+    positionsRetained: z.number().int().min(0).meta({
+      description:
+        "Provider-imported positions retained because a user claimed them.",
+    }),
+    occupanciesEnded: z.number().int().min(0).meta({
+      description: "Source-owned occupancies ended (employment history kept).",
+    }),
+    occupanciesRetained: z.number().int().min(0).meta({
+      description:
+        "Provider-imported occupancies retained because a user claimed them.",
+    }),
+    reportingEdgesRemoved: z.number().int().min(0).meta({
+      description: "Source-owned reporting edges deleted.",
+    }),
+    reportingEdgesRetained: z
+      .number()
+      .int()
+      .min(0)
+      .meta({
+        description:
+          "Provider-imported reporting edges retained because a user took " +
+          "ownership of them (user_override or human_confirmed authority).",
+      }),
+    syncRunsDeleted: z.number().int().min(0).meta({
+      description: "Sync-run history rows deleted.",
+    }),
+    conflictsDeleted: z.number().int().min(0).meta({
+      description: "Conflict-ledger rows deleted.",
+    }),
+    acknowledgementsDeleted: z.number().int().min(0).meta({
+      description: "Divergence acknowledgements deleted.",
+    }),
+    sourceUnitMappingsDeleted: z.number().int().min(0).meta({
+      description: "Source-unit mapping rows deleted.",
+    }),
+    authorityRowsDeleted: z
+      .number()
+      .int()
+      .min(0)
+      .meta({
+        description:
+          "source-authority rows deleted — only rows whose authority is the " +
+          "provider itself; human-confirmed and user-override rows are never " +
+          "touched.",
+      }),
+  })
+  .meta({
+    description: "Per-entity impact of a break-glass HRIS purge.",
+  });
+export type HrisPurgeImpact = z.infer<typeof HrisPurgeImpactSchema>;

package/src/message-parts/__tests__/confirmation.test.ts

@@ -114,6 +114,7 @@ describe("CONFIRMATION_LABELS", () => {
     expect(CONFIRMATION_LABELS).toStrictEqual({
       "integration.connect": "Connect Integration",
       "integration.disconnect": "Disconnect Integration",
+      "integration.purge": "Purge Integration Data",
       "profile.update": "Update Profile",
       "slack.send": "Send Slack Message",
       "data.ingest": "Import Channel",

package/src/message-parts/confirmation.ts

@@ -39,6 +39,7 @@ export type ConfirmationRiskLevel =
 export const CONFIRMATION_LABELS: Record<ExecutionKind, string> = {
   "integration.connect": "Connect Integration",
   "integration.disconnect": "Disconnect Integration",
+  "integration.purge": "Purge Integration Data",
   "profile.update": "Update Profile",
   "slack.send": "Send Slack Message",
   "data.ingest": "Import Channel",

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>
+>;