@company-semantics/contracts 58.0.0 → 58.2.0

package/src/org/structure-inference.ts

@@ -0,0 +1,521 @@
+/**
+ * Org-structure inference vocabulary — the snapshot in, the proposal out.
+ *
+ * HRIS gives us a department STRING and a reporting graph. Neither one IS the
+ * org-unit tree. This module is the frozen vocabulary for the engine that
+ * reconciles them: a {@link StructureInferenceSnapshotSchema} of the persisted
+ * canonical graph goes in, and a {@link StructureProposalSchema} — a proposed
+ * DESIRED STATE, never a list of database commands — comes out.
+ *
+ * The four terms of the surrounding model are distinct and must stay distinct
+ * here, in the tables and in UI copy:
+ *
+ *  - SOURCE FACT — what the HRIS said ({@link CanonicalFactsSchema}).
+ *  - INFERENCE PROPOSAL — what the reasoning system thinks it means (this file).
+ *  - ACCEPTED ORGANIZATIONAL FACT — what the product considers the org to be.
+ *  - DRIFT FINDING — evidence that a later sync no longer agrees.
+ *
+ * Four decisions are load-bearing and are encoded in the types, not in prose:
+ *
+ *  1. Evidence is TYPED ({@link StructureEvidenceSchema}). A validator cannot
+ *     enforce "this unit is not supported by reporting topology alone" against
+ *     the free-text string "several employees have similar roles"; it can
+ *     enforce it against a discriminated union plus
+ *     {@link TOPOLOGY_ONLY_EVIDENCE_KINDS}.
+ *  2. A proposed unit carries `targetUnitId`. Present means "preserve that
+ *     durable identity"; null means "create". Without it the very first run
+ *     that renames `Human Resources` to `People` creates a SECOND unit beside
+ *     the first and orphans a doc-owning one.
+ *  3. Every person in the snapshot gets EXACTLY ONE outcome — placed,
+ *     needs_review or excluded. "Zero or one placement" would accept a proposal
+ *     that silently forgets three people, which is the same silent-omission
+ *     failure class this whole effort exists because of.
+ *  4. People and units are referenced ONLY by the opaque ids the snapshot
+ *     supplied. Names are display-only and never identifiers — two records with
+ *     no characters in common can be the same person (a legal name and a
+ *     preferred name), so no fuzzy name match can be trusted.
+ *
+ * WHY THIS IS NOT `structure-facts.ts` PROVENANCE. Every other org fact carries
+ * a {@link FactProvenanceSchema} envelope (tier / source / confidence / locked /
+ * supersedesFactId). A proposal deliberately carries none: it is a CANDIDATE,
+ * not a recorded fact, and it has not entered the truth hierarchy at all.
+ * Provenance attaches when a human accepts it.
+ *
+ * WHY {@link StructureUnitAuthoritySchema} IS NOT {@link FactSourceTierSchema}.
+ * The tier axis (`user` > `sync` > `import` > `inferred`) answers "which writer
+ * wins when two facts collide". The authority axis here answers a different
+ * question the model must be told the answer to: "may you reorganize this unit?"
+ * `human_confirmed` is an ANCHOR the model must leave alone and disagree with
+ * out loud; `hris_source` is imported evidence it may reorganize. Collapsing the
+ * two axes would make `inferred` mean both "loses a write race" and "safe to
+ * rearrange", which are not the same claim.
+ *
+ * PROVENANCE IS THREE AXES, NOT ONE LADDER. When a proposal is ACCEPTED it
+ * records {@link StructureProvenanceSchema}: `proposalOrigin` (how it came to be
+ * proposed), `acceptedBy` (who signed off) and `authority` (what it may now
+ * overwrite). Only the third drives precedence, via
+ * {@link mayOverrideAuthority}. Clicking Apply on an AI proposal makes it
+ * `human_confirmed` without making its origin `manual` — collapsing those is
+ * what makes an AI guess indistinguishable from a human decision today.
+ *
+ * NOT TO BE CONFUSED WITH `reasoning-review.ts`. That module
+ * (`OrgStructureReviewInference`, `OrgStructureReviewQueue`, ADR-CONT-095 /
+ * ADR-BE-345) is the OLDER reasoning-lens review queue, backed by
+ * `org_structure_inferences`, which can express only two mutations: re-parent an
+ * existing unit and rename a seat title. This vocabulary is a SEPARATE seam
+ * backed by `org_structure_proposals`, and it describes a whole desired state.
+ * Neither replaces the other in this release.
+ */
+import { z } from "zod";
+
+import { PositionReportingRelationshipTypeSchema } from "./position-reporting";
+
+// ---------------------------------------------------------------------------
+// StructureEvidence — typed support for a boundary, a name or a placement
+// ---------------------------------------------------------------------------
+
+/**
+ * TYPED evidence. Prose evidence cannot be validated; a discriminated union can.
+ * The validator reads these `kind`s directly to enforce "a proposed unit must
+ * have at least one boundary signal that is not reporting topology" and "a name
+ * may not carry specificity absent from its `nameBasis`".
+ */
+export const StructureEvidenceSchema = z.discriminatedUnion("kind", [
+  /** The source stated a department outright for these people. */
+  z.object({
+    kind: z.literal("explicit_department"),
+    personIds: z.array(z.string()),
+    value: z.string(),
+  }),
+  /** The source stated a division outright for these people. */
+  z.object({
+    kind: z.literal("explicit_division"),
+    personIds: z.array(z.string()),
+    value: z.string(),
+  }),
+  /** A title cluster. Role families cut ACROSS reporting lines on purpose. */
+  z.object({
+    kind: z.literal("role_family"),
+    family: z.string(),
+    personIds: z.array(z.string()),
+    count: z.number().int(),
+  }),
+  /** A C-level / VP seat that anchors a function. */
+  z.object({
+    kind: z.literal("functional_leader"),
+    personId: z.string(),
+    function: z.string(),
+  }),
+  /** Manager topology. Alone this is NEVER enough — see the const below. */
+  z.object({
+    kind: z.literal("reporting_cluster"),
+    managerPersonId: z.string(),
+    personIds: z.array(z.string()),
+  }),
+  /**
+   * A manager whose reports span many functions — an administrative supervisor
+   * rather than a unit boundary. Recorded so a proposal can explain why it did
+   * NOT draw a unit around that seat.
+   */
+  z.object({
+    kind: z.literal("administrative_pivot"),
+    personId: z.string(),
+    departmentEntropy: z.number(),
+  }),
+  /** A concept from a controlled ontology rather than from this org's data. */
+  z.object({
+    kind: z.literal("controlled_ontology"),
+    concept: z.string(),
+  }),
+]);
+export type StructureEvidence = z.infer<typeof StructureEvidenceSchema>;
+
+/**
+ * Evidence kinds that alone are NOT sufficient to justify a unit boundary.
+ *
+ * On the reference org, 17 of 19 cross-department placements route through two
+ * `Sr. HR Administrator` seats whose reports span seven departments each.
+ * Deriving units from reporting topology puts the entire company inside one
+ * unit — so a unit whose only support is `reporting_cluster` is rejected.
+ */
+export const TOPOLOGY_ONLY_EVIDENCE_KINDS = [
+  "reporting_cluster",
+] as const satisfies ReadonlyArray<StructureEvidence["kind"]>;
+
+// ---------------------------------------------------------------------------
+// StructureUnitAuthority — may the model reorganize this existing unit?
+// ---------------------------------------------------------------------------
+
+/**
+ * How much license the engine has over an EXISTING unit or placement. See the
+ * file header for why this is a separate axis from {@link FactSourceTierSchema}.
+ *
+ * This is the authority axis of {@link StructureProvenanceSchema} read from the
+ * proposal side; {@link StructureAuthoritySchema} is the SAME schema object read
+ * from the apply side. One ladder, and exactly one meaning per rung:
+ *
+ *  - `human_confirmed` — a PERSON signed off, whether by editing structure
+ *    directly or by accepting an AI proposal. An anchor: never renamed,
+ *    reparented or replaced by inference; a disagreement is surfaced for review
+ *    instead.
+ *  - `ai_inferred` — accepted with nobody in the loop, i.e. `acceptedBy` is
+ *    `system_policy` (calibrated auto-accept); may be revisited. An AI proposal
+ *    a human clicked Apply on is NOT this — it is `human_confirmed`, and the
+ *    fact that an AI proposed it survives in `proposalOrigin`, not here. Writing
+ *    a human-accepted fact as `ai_inferred` would make it reorganizable and
+ *    overwritable by the next AI guess, which is the defect this vocabulary
+ *    exists to close.
+ *  - `hris_source` — imported source evidence the feed accepted for itself; may
+ *    be reorganized when stronger functional evidence supports it.
+ */
+export const StructureUnitAuthoritySchema = z.enum([
+  "human_confirmed",
+  "ai_inferred",
+  "hris_source",
+]);
+export type StructureUnitAuthority = z.infer<
+  typeof StructureUnitAuthoritySchema
+>;
+
+// ---------------------------------------------------------------------------
+// StructureProvenance — three orthogonal axes: origin, acceptor, authority
+// ---------------------------------------------------------------------------
+
+/**
+ * How a structural fact came to be PROPOSED. Orthogonal to who accepted it and
+ * to how much authority it now carries.
+ *
+ * Accepting an AI proposal must not rewrite its origin as `manual`. The moment
+ * it does, an AI guess and a human decision become indistinguishable in the
+ * record — which is exactly the defect being fixed: today both land as
+ * `source_authority.system_of_record = 'user_override'`, nothing downstream can
+ * tell them apart, and nothing ever deletes such a row, so the guess is
+ * permanent AND wears the costume of intent. Nothing is recorded as
+ * `user_override` again.
+ */
+export const StructureProposalOriginSchema = z.enum([
+  "ai_inference",
+  "hris_source",
+  "manual",
+]);
+export type StructureProposalOrigin = z.infer<
+  typeof StructureProposalOriginSchema
+>;
+
+/**
+ * WHO accepted the fact. A discriminated union rather than a nullable `userId`,
+ * because "nobody" and "a policy decided" are different claims, and only the
+ * second one is an answer when someone asks who signed off. A null would let
+ * an unattributed write and an automated one share a representation.
+ */
+export const StructureAcceptedBySchema = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("user"), userId: z.string().uuid() }),
+  z.object({ kind: z.literal("system_policy") }),
+]);
+export type StructureAcceptedBy = z.infer<typeof StructureAcceptedBySchema>;
+
+/**
+ * The authority axis — the ONLY axis precedence runs on:
+ * `human_confirmed` > `ai_inferred` > `hris_source`.
+ *
+ * Deliberately the same vocabulary as {@link StructureUnitAuthoritySchema}, and
+ * deliberately the same schema object rather than a second identically-valued
+ * enum beside it. "May the model reorganize this unit?" and "may this write
+ * overwrite that fact?" are two readings of ONE ladder; two copies of it would
+ * drift, and a proposal-time answer that disagreed with the apply-time answer is
+ * precisely the class of bug this vocabulary exists to make impossible.
+ */
+export const StructureAuthoritySchema = StructureUnitAuthoritySchema;
+export type StructureAuthority = StructureUnitAuthority;
+
+/**
+ * Highest wins. Private on purpose: callers ask {@link mayOverrideAuthority}
+ * instead of comparing numbers, so the ordering has exactly one definition and
+ * adding a member to the enum is a compile error here rather than a silent tie.
+ */
+const AUTHORITY_RANK: Record<StructureAuthority, number> = {
+  human_confirmed: 3,
+  ai_inferred: 2,
+  hris_source: 1,
+};
+
+/**
+ * True when `incoming` may overwrite a fact currently held at `existing`.
+ *
+ * Equal authority overwrites: a later HRIS sync must be able to correct an
+ * earlier one, and a second human decision must be able to revise the first.
+ * A strict `>` would freeze the first write of every field forever.
+ */
+export function mayOverrideAuthority(
+  incoming: StructureAuthority,
+  existing: StructureAuthority,
+): boolean {
+  return AUTHORITY_RANK[incoming] >= AUTHORITY_RANK[existing];
+}
+
+/**
+ * The three axes together, as one accepted structural fact records them.
+ *
+ *  - v1 — AI proposes, an admin clicks Apply:
+ *    `ai_inference` / `user` / `human_confirmed`.
+ *  - Later — calibrated auto-accept:
+ *    `ai_inference` / `system_policy` / `ai_inferred`.
+ *  - An admin edits structure directly:
+ *    `manual` / `user` / `human_confirmed`.
+ *  - The feed said so:
+ *    `hris_source` / `system_policy` / `hris_source`.
+ *
+ * Read the `authority` column alone and you have precedence. Read a row across
+ * and acceptance has not erased how the fact originated — which is the whole
+ * reason these are three fields and not one.
+ */
+export const StructureProvenanceSchema = z.object({
+  proposalOrigin: StructureProposalOriginSchema,
+  acceptedBy: StructureAcceptedBySchema,
+  authority: StructureAuthoritySchema,
+});
+export type StructureProvenance = z.infer<typeof StructureProvenanceSchema>;
+
+// ---------------------------------------------------------------------------
+// ProposedOrgUnit — one node of the proposed desired state
+// ---------------------------------------------------------------------------
+
+/**
+ * A unit the proposal wants the org to have. `tempId` is proposal-scoped
+ * plumbing; `targetUnitId` is the only durable identity in this record.
+ */
+export const ProposedOrgUnitSchema = z.object({
+  /** Proposal-scoped handle. NOT the durable identity. */
+  tempId: z.string().min(1),
+  /**
+   * Present => this proposal IS an existing durable unit; preserve its id, its
+   * Company.md doc, its history and its permissions. Null => create a new
+   * durable unit on acceptance.
+   *
+   * Without this, renaming `Human Resources` to `People` creates a second unit
+   * and orphans the first. A unit's durable identity is never derived from its
+   * name and never from its leader — when a team lead leaves it is still the
+   * same team.
+   */
+  targetUnitId: z.string().uuid().nullable(),
+  /** Certainty in [0,1] that `targetUnitId` really is this unit. */
+  identityConfidence: z.number().min(0).max(1),
+  /** Typed support for the identity claim above. */
+  identityEvidence: z.array(StructureEvidenceSchema),
+  /** Human-facing unit name. Display only; never an identifier. */
+  name: z.string().min(1),
+  /** Typed support for the NAME specifically — the anti-invention check. */
+  nameBasis: z.array(StructureEvidenceSchema),
+  /** `tempId` of the parent unit; `null` for the proposed root. */
+  parentTempId: z.string().nullable(),
+  /** Free-text level label (e.g. `Department`, `Team`); advisory only. */
+  suggestedTypeLabel: z.string(),
+  /** Opaque person id of the unit's head; `null` when unknown. */
+  headPersonId: z.string().nullable(),
+  /** Certainty in [0,1] that the NAME is right. */
+  nameConfidence: z.number().min(0).max(1),
+  /** Certainty in [0,1] that the BOUNDARY is right. */
+  structureConfidence: z.number().min(0).max(1),
+  /** A leader-derived placeholder label the user is expected to rename. */
+  provisional: z.boolean(),
+  /** Typed support for the BOUNDARY — what the topology-only rule reads. */
+  evidence: z.array(StructureEvidenceSchema),
+});
+export type ProposedOrgUnit = z.infer<typeof ProposedOrgUnitSchema>;
+
+// ---------------------------------------------------------------------------
+// PersonStructureOutcome — exactly one per person in the snapshot
+// ---------------------------------------------------------------------------
+
+/**
+ * EXACTLY ONE outcome per person in the snapshot.
+ *
+ * "Zero or one placement" would accept a proposal that simply forgets three
+ * people — the same silent-omission failure that dropped people out of the
+ * reporting tree while the sync reported a clean run. A person the engine
+ * cannot place returns `needs_review` with a reason; never a guess, and never
+ * an absence.
+ */
+export const PersonStructureOutcomeSchema = z.discriminatedUnion("kind", [
+  z.object({
+    kind: z.literal("placed"),
+    personId: z.string(),
+    /** `tempId` of the unit this person is placed in. */
+    unitTempId: z.string(),
+    confidence: z.number().min(0).max(1),
+    evidence: z.array(StructureEvidenceSchema),
+    /** Signals that disagreed with this placement, stated not suppressed. */
+    conflicts: z.array(z.string()),
+  }),
+  z.object({
+    kind: z.literal("needs_review"),
+    personId: z.string(),
+    reason: z.enum([
+      "insufficient_evidence",
+      "conflicting_evidence",
+      "ambiguous_boundary",
+    ]),
+  }),
+  z.object({
+    kind: z.literal("excluded"),
+    personId: z.string(),
+    reason: z.enum(["service_account", "not_workforce", "inactive"]),
+  }),
+]);
+export type PersonStructureOutcome = z.infer<
+  typeof PersonStructureOutcomeSchema
+>;
+
+// ---------------------------------------------------------------------------
+// StructureReviewItem — a decision boundary, not merely a low number
+// ---------------------------------------------------------------------------
+
+/**
+ * A question the engine is asking a human, with the competing signals attached.
+ *
+ * A low confidence number is not a review item. A review item is a genuine
+ * decision boundary: an engine that confidently places an ambiguous person and
+ * 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",
+  ]),
+  /** 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()),
+  /** 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),
+});
+export type StructureReviewItem = z.infer<typeof StructureReviewItemSchema>;
+
+// ---------------------------------------------------------------------------
+// StructureProposal — the proposed desired state
+// ---------------------------------------------------------------------------
+
+/**
+ * A proposed desired state for one org. Not database commands, not an applied
+ * change: acceptance is a separate, human step.
+ */
+export const StructureProposalSchema = z.object({
+  orgId: z.string().uuid(),
+  /** Lineage only. Staleness is decided by `inputHash`, not by this. */
+  sourceSnapshotId: z.string(),
+  /** The org-graph revision this proposal reasoned about. */
+  structureRevision: z.string(),
+  /** Hash of the NORMALIZED inference inputs — the staleness key. */
+  inputHash: z.string(),
+  /** Registry version of the prompt that produced this proposal. */
+  promptVersion: z.string(),
+  orgUnits: z.array(ProposedOrgUnitSchema),
+  personOutcomes: z.array(PersonStructureOutcomeSchema),
+  /** Things the engine noticed but could not express as a review item. */
+  structureWarnings: z.array(z.string()),
+  reviewItems: z.array(StructureReviewItemSchema),
+});
+export type StructureProposal = z.infer<typeof StructureProposalSchema>;
+
+// ---------------------------------------------------------------------------
+// StructureInferenceSnapshot — the inference INPUT, taken from the graph
+// ---------------------------------------------------------------------------
+
+/**
+ * A person as the inference engine sees them. `personId` is the opaque internal
+ * id and the ONLY handle a proposal may return; `sourcePersonId` is retained
+ * for diagnostics and is stripped before the snapshot reaches the model, because
+ * keeping provider identity out of the reasoning layer is the point.
+ */
+export const StructurePersonFactSchema = z.object({
+  /** Opaque internal id. The only handle a proposal may reference. */
+  personId: z.string().min(1),
+  /** Diagnostics only — stripped from the model-facing snapshot. */
+  sourcePersonId: z.string().min(1).nullable().optional(),
+  /** Display only. Never an identifier, never fuzzy-matched. */
+  displayName: z.string(),
+  title: z.string().nullable(),
+  department: z.string().nullable(),
+  division: z.string().nullable(),
+  location: z.string().nullable(),
+  managerPersonId: z.string().nullable(),
+  directReportPersonIds: z.array(z.string()),
+});
+export type StructurePersonFact = z.infer<typeof StructurePersonFactSchema>;
+
+/**
+ * One reporting edge, at person granularity. Reporting is a SEPARATE axis: a
+ * proposal must never rewrite one, and the validator proves it did not by
+ * comparing against these.
+ */
+export const StructureReportingFactSchema = z.object({
+  reportPersonId: z.string().min(1),
+  managerPersonId: z.string().min(1),
+  relationshipType: PositionReportingRelationshipTypeSchema,
+});
+export type StructureReportingFact = z.infer<
+  typeof StructureReportingFactSchema
+>;
+
+/** An org unit that already exists, with the license the engine has over it. */
+export const ExistingUnitFactSchema = z.object({
+  unitId: z.string().uuid(),
+  name: z.string(),
+  parentUnitId: z.string().uuid().nullable(),
+  depth: z.number().int(),
+  /**
+   * Anchor vs reorganizable. This is the `authority` axis of the accepted
+   * fact's {@link StructureProvenanceSchema}, copied through unchanged — a unit
+   * a human accepted is `human_confirmed` here even when an AI proposed it.
+   */
+  authority: StructureUnitAuthoritySchema,
+});
+export type ExistingUnitFact = z.infer<typeof ExistingUnitFactSchema>;
+
+/** Where a person already sits, and on whose authority they sit there. */
+export const ExistingPlacementFactSchema = z.object({
+  personId: z.string().min(1),
+  unitId: z.string().uuid(),
+  /** The accepted fact's `authority` axis — see {@link ExistingUnitFactSchema}. */
+  authority: StructureUnitAuthoritySchema,
+});
+export type ExistingPlacementFact = z.infer<typeof ExistingPlacementFactSchema>;
+
+/**
+ * The inference INPUT: a point-in-time view of the PERSISTED canonical graph.
+ *
+ * Never a {@link CanonicalFactsSchema} batch. Internal ids are already resolved
+ * here, duplicates already reconciled, provenance already attached — and a delta
+ * batch is a partial workforce, on which inference is meaningless.
+ *
+ * Derived heuristic signals (role families, functional leaders, administrative
+ * pivot candidates, department outliers) are deliberately NOT part of this
+ * contract. They are an engine-local enrichment layered on top by the extractor;
+ * they are tuning knobs that will change without a coordinated release, so they
+ * fail the promotion rule that governs this package. What is frozen here is the
+ * FACTS the engine reasons over and the ids a proposal may reference.
+ */
+export const StructureInferenceSnapshotSchema = z.object({
+  orgId: z.string().uuid(),
+  /** Lineage only. Staleness is decided by the hash of these inputs. */
+  sourceSnapshotId: z.string(),
+  structureRevision: z.string(),
+  persons: z.array(StructurePersonFactSchema),
+  reporting: z.array(StructureReportingFactSchema),
+  existingUnits: z.array(ExistingUnitFactSchema),
+  existingPlacements: z.array(ExistingPlacementFactSchema),
+});
+export type StructureInferenceSnapshot = z.infer<
+  typeof StructureInferenceSnapshotSchema
+>;

package/src/proactive/README.md

@@ -0,0 +1,125 @@
+# proactive/
+
+## Purpose
+
+The vocabulary of **proactive delivery** — how the system speaks first. It
+encodes the doctrine in the control ADR with slug
+`proactive-delivery-occurrence-audience-projection` (ADR-CTRL-408) as a
+compile-checked vocabulary: a **presentation class** is a TOTAL FUNCTION from
+class to surfaces, and an **event kind** carries only the IDS each surface
+needs. See ADR-CONTRACTS-142.
+
+This vocabulary COMPOSES the three notification vocabularies beside it — it
+adds no member to `NotificationKind` or `ActionItemKind`, and it derives none of
+the three from another.
+
+## Invariants
+
+- **`CLASS_SURFACES` is total in both directions.** Checked by
+  `as const satisfies Record<ProactivePresentationClass, ClassSurfacePlan>`: a
+  class with no entry fails to compile, and an entry for a non-class fails too.
+- **Exactly one badge carrier per class.** `ClassSurfacePlan` is a UNION, not a
+  flat interface, so a badge naming a surface the class does not have is a
+  compile error.
+- **Every class writes a durable inbox row.** `inbox` is literal `true` in every
+  union member. What varies is whether the row is born read.
+- **The born-read rule is stated once.** `bornRead(surfaces, surface)` is the
+  only place "born read whenever a louder surface owns the badge" lives. A
+  backend that re-derives it per call site is how the two halves drift.
+- **Loudness, not severity.** `error|warning|info` exists in this package scoped
+  to org-transformation findings and is not overloaded here.
+- **Kinds carry ids, never surface booleans.** A kind names its `class` and the
+  identifiers each surface needs; the surfaces themselves are derived from the
+  class table. Restating them would leave the compiler having to prove two
+  declarations agree.
+- **`PROACTIVE_EVENT_KINDS` is total in both directions.** Same
+  `as const satisfies Record<ProactiveEventKind, ProactiveEventDefinition>`
+  idiom: a kind with no plan fails to compile, and a plan for a non-kind fails.
+- **The plan union types the ids a class lacks as `never`.** An `announcement`
+  MUST name a `bannerType` and a `chatTemplate`; `explained` and `briefing`
+  cannot name a banner; a `notice` can name neither. Every member requires an
+  `inboxKind`. The one consistency the compiler cannot express — a plan's ids
+  agreeing with `CLASS_SURFACES[plan.class]` — is pinned by the vocabulary
+  test.
+- **Email and action items are orthogonal axes.** `emailKind` is off-platform
+  delivery governed by notify/'s policy; `actionItemKind` is a work-state
+  projection, not a loudness tier. No kind sets `emailKind` in this wave.
+- **The kind string and the inbox kind string are distinct.**
+  `org.became_shared` names its row `proactive.org_became_shared` and
+  `brief.morning` names its row `proactive.brief_morning`; identical names
+  across two unions is how one quietly becomes derived from the other.
+- **A `briefing` needs no new machinery.** `brief.morning` is the proof: its
+  class already types `bannerType` as `never`, so it cannot name a banner, and
+  the plan/surface test covers it for free. ONE occurrence per org per
+  org-local day, with N recipients — personalisation lives in the per-recipient
+  `MorningBriefFacts`, never in occurrence identity, or the system would have
+  one event row per person per day and two shapes of occurrence to reason
+  about.
+- **`ORG_SYSTEM_EVENT_TYPES` mirrors the backend pgEnum value for value.**
+  `org.became_shared` names the EXISTING `first_member_joined` banner rather
+  than minting a third value — it fires at exactly the personal-to-shared flip.
+- **The occurrence vocabulary is closed.** `ProactiveEventId` is branded so a
+  raw string cannot stand in for an occurrence; `ProactiveRecipientReason` is a
+  closed enum because the recipients table is the frozen audit record of who
+  was addressed and why; `ProactiveProjection` is deliberately broader than the
+  three surfaces because an occurrence has zero or more PROJECTIONS.
+- **Pushed-chat copy lives here, not in the backend.** The precedent notify/'s
+  README states for outbound notifications — copy belongs to contracts'
+  `compose` — applied to the third surface. The backend hands a composer facts
+  and writes what comes back; it never owns a sentence.
+- **The composer is pure and content-only.** `(facts)` in, message out; no
+  clock, no env, no I/O; no markup, no channel names, no hrefs the app owns.
+  Members are arrow properties, never method shorthand, because the vocabulary
+  guard reads a method signature as behaviour.
+- **`PROACTIVE_CHAT_COMPOSERS` is total in both directions.** Same
+  `as const satisfies Record<ProactiveChatTemplate, ProactiveChatComposer>`
+  idiom: a template with no composer fails to compile. `ProactiveChatComposer`
+  is a DISTRIBUTIVE type so the bare name is a union of per-template composers
+  — an arrow `compose` is checked contravariantly, and a composer taking one
+  template's facts is not assignable to one taking the union of all facts.
+- **The pushed message is FROZEN AT WRITE TIME (INV-PROACTIVE-CONTENT).** It
+  is written once into `chat_messages.content` and never re-renders, so a
+  composer may only interpolate facts the recipient was entitled to at compose
+  time. The deliberate opposite of the durable-inbox rule, and both are
+  correct: a transcript that changed under the reader would be a lie about the
+  conversation.
+
+## Public API
+
+| Export                           | Description                                                                   |
+| -------------------------------- | ----------------------------------------------------------------------------- |
+| `PROACTIVE_PRESENTATION_CLASSES` | The closed class vocabulary (announcement, explained, briefing, notice)       |
+| `ProactivePresentationClass`     | Union derived from the array                                                  |
+| `BadgeCarrier`                   | `banner` \| `chat` \| `inbox` — exactly one per class                         |
+| `ClassSurfacePlan`               | Union of the surface sets a badge carrier presupposes                         |
+| `CLASS_SURFACES`                 | The total class → surfaces table                                              |
+| `bornRead`                       | Whether a class's `chat` or `inbox` row is born read                          |
+| `ORG_SYSTEM_EVENT_TYPES`         | Mirror of the backend `org_system_event_type` pgEnum — the banner ids         |
+| `OrgSystemEventType`             | Union derived from the array                                                  |
+| `PROACTIVE_CHAT_TEMPLATES`       | Which prose composes a kind's pushed chat (`orgBecameShared`, `morningBrief`) |
+| `ProactiveChatTemplate`          | Union derived from the array                                                  |
+| `PROACTIVE_EVENT_KIND_IDS`       | The closed kind vocabulary (`org.became_shared`, `brief.morning`)             |
+| `ProactiveEventKind`             | Union derived from the array                                                  |
+| `ProactiveEventId`               | Branded id of ONE occurrence — a raw string cannot be passed as one           |
+| `PROACTIVE_RECIPIENT_REASONS`    | Closed enum of WHY a recipient was addressed (the frozen audit record)        |
+| `ProactiveRecipientReason`       | Union derived from the array                                                  |
+| `PROACTIVE_PROJECTIONS`          | What was materialized for one recipient — broader than the three surfaces     |
+| `ProactiveProjection`            | Union derived from the array                                                  |
+| `ProactiveEventDefinition`       | A kind's plan: discriminated union on `class`, ids the class lacks as `never` |
+| `PROACTIVE_EVENT_KINDS`          | The total kind → plan registry                                                |
+| `ProactiveChatFacts`             | The facts each template composes from, keyed by template                      |
+| `OrgBecameSharedFacts`           | Facts for the personal-to-shared flip: `orgName`, `joinerDisplayName`         |
+| `MorningBriefFacts`              | Per-recipient facts for the morning brief — where personalisation lives       |
+| `ProactiveChatMessage`           | What a composer returns: `title`, `text`, and 0..4 `replies` chips            |
+| `ProactiveChatComposer`          | The composer port — `template` plus an arrow-property `compose(facts)`        |
+| `PROACTIVE_CHAT_MAX_REPLIES`     | At most this many chips (4); more is a menu, not a chip row                   |
+| `PROACTIVE_CHAT_COMPOSERS`       | The total template → composer registry (see `templates/README.md`)            |
+
+## Dependencies
+
+Type-only imports of `UserNotificationKind` (`../user-notifications`),
+`NotificationKind` (`../notifications`) and `ActionItemKind`
+(`../action-items`) — the three vocabularies this one composes — and of
+`SuggestedReply` (`../message-parts`), the chip shape a composer's `replies`
+reuse rather than redeclare. No `zod`, no runtime imports; pure vocabulary
+data and pure helpers.