@milehimikey/em 1.22.0 → 1.22.1

package/.claude/skills/event-modeling/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: event-modeling
-em-version: 1.22.0
+em-version: 1.22.1
 description: >-
   Use when the user runs `/event-modeling` (with or without a phase name), or wants to resume an
   event-modeling session without specifying which part of the process applies. Reads the model's

package/.claude/skills/event-modeling-conform/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: event-modeling-conform
-em-version: 1.22.0
+em-version: 1.22.1
 description: >-
   Use when checking a ratified event model (and its slice docs) for drift against the codebase
   that implements it — advisory only, never a gate, never an unprompted edit — or when walking

package/.claude/skills/event-modeling-design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: event-modeling-design
-em-version: 1.22.0
+em-version: 1.22.1
 description: >-
   Use when structuring a draft event model into swimlanes and the four patterns (State Change,
   State View, Automation, Translation), evaluating a model's structural completeness, or writing
@@ -234,7 +234,10 @@ For each slice:
 1. Hold a Socratic deep-dive to fill every section of `../event-modeling-shared/templates/slice.md`:
    intent, trigger/actor,
    command fields (types & rules), event(s) + payload (mark immutable facts) — field names and
-   types go into the `.em`, the doc's tables are generated from it — invariants
+   types go into the `.em`, the doc's tables are generated from it (on a `public` element, a
+   field's type must be the fixed scalar table, a declared `type`, a declared identity `scalar`,
+   or a declared `enum` — see `em-dsl.md`'s Strict public types/Identity scalars/Enums
+   sections) — invariants
    (give each a stable ID — see **Invariants live in the model** below), Given/When/Then scenarios (happy path + rule boundaries + edge cases),
    alternate/error flows (retries, idempotency, compensations), non-functional requirements
    (security/authz, PII/compliance, performance/SLA), read models affected, open questions. Park

package/.claude/skills/event-modeling-discover/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: event-modeling-discover
-em-version: 1.22.0
+em-version: 1.22.1
 description: >-
   Use when starting a brand-new event model from scratch — greenfield discovery: brainstorming
   past-tense events, storyboarding the happy path, finding the commands and read models — or when

package/.claude/skills/event-modeling-engagement/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: event-modeling-engagement
-em-version: 1.22.0
+em-version: 1.22.1
 description: >-
   Use when leading an engagement: building a named set of ratified event-modeling slices
   (`em engagement`) into one independent PR per slice, each against main, by dispatching the

package/.claude/skills/event-modeling-implement/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: event-modeling-implement
-em-version: 1.22.0
+em-version: 1.22.1
 description: >-
   Use when building a single ratified event-modeling slice (status: ready-to-implement) into
   merged, tested code — the one phase where the agent builds rather than facilitates. Gates on

package/.claude/skills/event-modeling-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: event-modeling-review
-em-version: 1.22.0
+em-version: 1.22.1
 description: >-
   Use when starting em's live browser viewer (`em watch --serve`) so a team can watch a model
   update in real time, or facilitating a SCHEDULED stakeholder walkthrough that steps through

package/.claude/skills/event-modeling-shared/reference/em-dsl.md

@@ -352,6 +352,8 @@ slice "Name" [source "url"] {    # one vertical time step (a column); source is
 arrow From Element -> To Element    # explicit cross-slice edge (overrides inferred flow)
 
 type Name { field: Type, ... }      # named structured type, reusable from any field (see Named types)
+scalar Name: base                   # identity alias over a public scalar table entry (see Named types)
+enum Name { member, ... }           # closed named value set, reusable from any field (see Named types)
 ```
 
 ### Element kinds (8 keywords, nothing else)
@@ -620,6 +622,31 @@ how tree/recursive data (categories, org charts, comment threads, BOMs) gets exp
 fields and ordinary element fields alike) — `{ name, ref, array }` when resolved, `null`
 otherwise. `em diff` tracks types added/removed and field changes on surviving types.
 
+**Identity scalars** (GH #477): `scalar Name: base` declares an identity alias over one public
+scalar table entry (`base`, case-insensitive) — so a `public` field can carry a domain name on
+the wire (`orderId: OrderId`) instead of degrading to the bare table type (`uuid`) to satisfy
+[Strict public types](#strict-public-types). Reference it bare or `Name[]`, same as a declared
+`type`; on a `public` element it satisfies the strict table directly, on an internal element it
+resolves opportunistically. `em validate` errors on an unknown `base`, a redeclared name, or a
+name colliding with a declared `type` (either direction). `em api generate` declares a used
+scalar once, after the table scalars, extending the formatted table scalar
+(`scalar OrderId extends Uuid;`) or the core type (`scalar Sku extends string;`) — a model with
+no `scalar` emits unchanged. `em export` adds `model.scalars[]` and an additive `scalarRef` field
+key, mutually exclusive with `typeRef`.
+
+**Enums** (GH #478): `enum Name { member, … }` declares a closed, named value set — members are
+bare identifiers or quoted strings, in declaration order. Reference it bare or `Name[]`, same
+as a declared `type`/`scalar`; on a `public` element it satisfies the strict table directly, on
+an internal element it resolves opportunistically. `em validate` errors on an empty enum, a
+case-insensitive duplicate member, a redeclared name, or a name colliding with a declared
+`type`/`scalar` (either direction). `em api generate` declares a used enum once, members in
+declaration order (`enum OrderStatus { placed, shipped }`), after the scalar declarations and
+before type blocks — a member that isn't a bare TypeSpec identifier emits as a quoted string
+literal; a model with no `enum` emits unchanged. `em export` adds `model.enums[]` and an
+additive `enumRef` field key, mutually exclusive with both `typeRef` and `scalarRef`. `em api
+check --base` judges a surviving enum's member changes by role: removed/renamed is breaking on
+an output, added is breaking on an input, additive on a pure output.
+
 ### Swimlane band order (top → bottom)
 Header row → **Automation** (only if used) → **persona** rows (in declared order) → **API**
 (commands + views share this lane) → **context** rows (in declared order).
@@ -950,11 +977,17 @@ not the prose above has caught up yet. `--slice-ready <key>`-only codes are excl
 | `doc-names-unfed-event` | warning | Doc names an event its view does not read | Add the event to the view's `from` in the model (if the edge is real), or fix the doc's Source column / scenario. |
 | `doc-omits-fed-event` | warning | Doc omits an event its view reads | Mention the event in the view's Source column (run `em slice sync`), or drop it from the view's `from`. |
 | `duplicate-element-ref` | warning | Duplicate element ref | Rename the element so its export ref is unique. |
+| `duplicate-enum-ref` | warning | Duplicate enum ref | Rename the enum so its export ref is unique. |
 | `duplicate-model-key` | warning | Duplicate model key | Give each model a unique `model "Name"` so its key (and every cross-model ref) is stable. |
 | `duplicate-name` | warning | Duplicate name | Rename one of the duplicates. |
+| `duplicate-scalar-ref` | warning | Duplicate scalar ref | Rename the scalar so its export ref is unique. |
 | `duplicate-slice-name` | warning | Duplicate slice name | Rename the slice so its export key is unique. |
 | `duplicate-type-name` | warning | Duplicate type name | Rename one of the duplicate `type` declarations. |
 | `duplicate-type-ref` | warning | Duplicate type ref | Rename the type so its export ref is unique. |
+| `enum-duplicate-member` | error | Enum duplicate member | Remove or rename the duplicate member — members are compared case-insensitively. |
+| `enum-duplicate-name` | error | Enum duplicate name | Declare the enum once; rename or remove the duplicate `enum` block. |
+| `enum-empty` | error | Empty enum | Give the enum at least one member, or remove the declaration. |
+| `enum-name-collision` | error | Enum/type/scalar name collision | Rename the `enum` or the colliding `type`/`scalar` so the names no longer collide — a name can't mean both at once. |
 | `fields-completeness/event-field-no-source` | warning | Event field not from a command | Add the field to a command that records the event (in any slice), mark it assigned if the handler sets it, or remove it from the event. |
 | `fields-completeness/view-field-no-source` | warning | View field with no source | Add the field to a source event, or remove it from the view. |
 | `frontmatter-coherence-implemented-without-link` | warning | Implemented without a link | Add `implementedIn` once the slice ships. |
@@ -987,6 +1020,9 @@ not the prose above has caught up yet. `--slice-ready <key>`-only codes are excl
 | `reaction-from-future-view` | error | Backward timeline (reaction reads a future view) | Declare the view in or before the reaction's slice. |
 | `reaction-from-unresolved` | error | Unknown read-model source | Project the event into a view first, or fix the `from` reference. |
 | `retry-slice-of` | warning | Slice only retries another command | Re-fire the same reaction via `view … again from` the retry-scheduled event; a different actor's override is its own slice with its own command (docs/patterns.md#automation). |
+| `scalar-duplicate-name` | error | Scalar duplicate name | Declare the scalar once; rename or remove the duplicate `scalar` line. |
+| `scalar-type-name-collision` | error | Scalar/type name collision | Rename the `scalar` or the `type` so the two names no longer collide — a name can't mean both at once. |
+| `scalar-unknown-base` | error | Scalar unknown base | Point `base` at one of the public scalar table's names (string, text, int, long, decimal, boolean, uuid, date, datetime, duration, bytes), case-insensitive. |
 | `scenario-then-not-outcome` | warning | Scenario's Then names no event or rejection | Make the Then bullets name the event(s) the command records, or the rejection/error it returns. |
 | `scenario-when-not-command` | warning | Scenario's When does not name the slice's command | Make the When bullet name the slice's command (for a reaction slice: the command, the reaction element, or a view of the slice) — each scenario exercises exactly one command. For a Translation, naming the translation element satisfies it. |
 | `seam-consumer-not-reaction` | error | Seam consumer is not a reaction | Point `to` at a translation/automation element (or a slice containing exactly one). |

package/.claude-plugin/marketplace.json

@@ -1,9 +1,9 @@
 {
-  "name": "em-1-22-0",
+  "name": "em-1-22-1",
   "owner": {
     "name": "Mike Key"
   },
-  "description": "em v1.22.0: the Event Modeling skill bundle and MCP server as a Claude Code plugin.",
+  "description": "em v1.22.1: the Event Modeling skill bundle and MCP server as a Claude Code plugin.",
   "plugins": [
     {
       "name": "em",

package/dist/cli/api.d.ts

@@ -1,7 +1,7 @@
 import { NormalizedModel } from "../model/model.js";
 import { Diagnostic } from "../model/validate.js";
 import { compile } from "../pipeline.js";
-import { ElementExport, FieldExport, TypeExport } from "../emit/json.js";
+import { ElementExport, EnumExport, FieldExport, TypeExport } from "../emit/json.js";
 import { RefsResult } from "../model/refs.js";
 import { GitRunner } from "./diff-inputs.js";
 /** `<modelDir>/contracts/<modelKey>.tsp` (R6), built from the model path as given. */
@@ -30,7 +30,7 @@ export interface ApiCheckChange {
 }
 type Role = "input" | "output";
 interface SurfaceEntry {
-    /** command | event | view | type */
+    /** command | event | view | type | enum */
     kind: string;
     name: string;
     /** Normalized identity key: kind + normalizeName(name). */
@@ -38,11 +38,13 @@ interface SurfaceEntry {
     fields: FieldExport[];
     renamedFrom: string[];
     roles: Set<Role>;
-    /** Model-declared invariants (MIL-265), declaration order; `[]` for a type. */
+    /** Model-declared invariants (MIL-265), declaration order; `[]` for a type/enum. */
     invariants: {
         id: string;
         rule: string | null;
     }[];
+    /** GH #478: an enum's own members, in declaration order — `[]` for every non-enum kind. */
+    members: string[];
 }
 interface Surface {
     entries: SurfaceEntry[];
@@ -51,14 +53,29 @@ interface Surface {
     allElements: Set<string>;
 }
 /** Build the public surface of one compiled model: public commands (input), events and views
- *  (output), and every declared type reachable from them (carrying the roles that reach it). */
+ *  (output), and every declared type/enum reachable from them (carrying the roles that reach
+ *  it — GH #478 extends the existing type-reach walk to also track an `enumRef` field,
+ *  directly or through a reachable type's own fields, the same way `reachableEnumRefs`
+ *  (emit/api.ts) tracks it for `em api generate`). `enums` defaults to `[]` so every existing
+ *  caller (and the one test helper that built a `Surface` before enums existed) keeps compiling
+ *  without a required third argument at a call site that never has one. */
 export declare function surfaceOf(slices: {
     elements: ElementExport[];
-}[], types: TypeExport[]): Surface;
-/** A field's type as the contract sees it: a declared type's name or the raw string,
- *  normalized, with its array arity. */
-export declare function typeLabel(f: Pick<FieldExport, "type" | "typeRef">): string;
-export declare function typeIdentity(f: Pick<FieldExport, "type" | "typeRef">): string;
+}[], types: TypeExport[], enums?: EnumExport[]): Surface;
+/** A field's type as the contract sees it: a declared type's, identity scalar's or enum's
+ *  name, or the raw string, normalized, with its array arity. */
+export declare function typeLabel(f: Pick<FieldExport, "type" | "typeRef" | "scalarRef" | "enumRef">): string;
+/**
+ * GH #477: a `scalarRef` folds its `base` into the identity string too, not just `ref`/`array` —
+ * so a surviving scalar DECLARATION's base changing (`OrderId: uuid` -> `OrderId: string`)
+ * registers as a type change on every field that uses it, even though the scalar's own ref and
+ * the field's array arity are unchanged. This reuses `diffFields`' existing per-field
+ * `compare()` rather than adding a second comparison path — see its `scalarRef`-aware branch
+ * below for the breaking-change message this produces. GH #478: `enumRef` needs no equivalent
+ * fold — an enum's MEMBER changes are diffed on the enum's own `SurfaceEntry` (`diffEnumMembers`
+ * below), not per using field, so `ref`/`array` alone identify a field's enum reference here.
+ */
+export declare function typeIdentity(f: Pick<FieldExport, "type" | "typeRef" | "scalarRef" | "enumRef">): string;
 /** Diff two public surfaces. `base === null` means the model did not exist at the base
  *  revision: every HEAD element is an additive addition. */
 export declare function diffSurfaces(base: Surface | null, head: Surface): ApiCheckChange[];
@@ -96,13 +113,21 @@ export type ApiCheckOutcome = {
 export declare function runApiCheck(file: string, base: string | undefined, runGit?: GitRunner): ApiCheckOutcome;
 /** The text report: one status line, then one `additive:`/`breaking:` line per change. */
 export declare function formatApiCheckText(r: ApiCheckReport): string[];
-/** A public field's resolved type (R7's fixed table or a declared type), the same shape
- *  `resolvePublicType` (model/model.ts) computes — scalar carries the matched table entry's
- *  key and the TypeSpec core scalar `em api generate` emits for it; declared carries the
- *  reachable type's own name (see `ApiSurfaceType` below for its full field shape). */
+/** A public field's resolved type (R7's fixed table, a declared identity scalar, a declared
+ *  enum, or a declared type), the same shape `resolvePublicType` (model/model.ts) computes —
+ *  `scalar` carries the matched table entry's key and the TypeSpec core scalar `em api
+ *  generate` emits for it; `declared` carries the reachable type's own name (see
+ *  `ApiSurfaceType` below for its full field shape); `scalar-alias` (GH #477, schema 1.1)
+ *  carries the declared identity scalar's own name in `tsType` (what actually appears in the
+ *  generated contract, same convention `declared` already uses) and the table key it extends
+ *  in `base` — `scalar`/`declared` leave `base` `null`; `enum` (GH #478, schema 1.2) carries
+ *  the declared enum's own name in `tsType`, same convention — find its members under the
+ *  report's own `enums` list. */
 export interface ApiSurfaceFieldType {
-    kind: "scalar" | "declared";
+    kind: "scalar" | "declared" | "scalar-alias" | "enum";
     scalar: string | null;
+    /** The `PUBLIC_SCALAR_TYPES` key a `scalar-alias` extends; `null` for every other kind. */
+    base: string | null;
     tsType: string;
     array: boolean;
 }
@@ -133,6 +158,20 @@ export interface ApiSurfaceType {
     slug: string;
     fields: ApiSurfaceField[];
 }
+/** One declared `scalar Name: base` identity alias reachable from a public command/event/view's
+ *  fields (GH #477, schema 1.1) — `base` is the `PUBLIC_SCALAR_TYPES` key it extends. */
+export interface ApiSurfaceScalar {
+    name: string;
+    slug: string;
+    base: string;
+}
+/** One declared `enum Name { member, … }` reachable from a public command/event/view's fields
+ *  (GH #478, schema 1.2) — `members` in declaration order, raw (unquoted). */
+export interface ApiSurfaceEnum {
+    name: string;
+    slug: string;
+    members: string[];
+}
 export interface ApiSurfaceReport {
     file: string;
     modelKey: string;
@@ -140,6 +179,8 @@ export interface ApiSurfaceReport {
     events: ApiSurfaceElement[];
     views: ApiSurfaceElement[];
     types: ApiSurfaceType[];
+    scalars: ApiSurfaceScalar[];
+    enums: ApiSurfaceEnum[];
 }
 export type ApiSurfaceOutcome = {
     ok: true;
@@ -154,9 +195,11 @@ export type ApiSurfaceOutcome = {
  * Build the `em api surface` report for an already-validated (error-free) model: the `public`
  * commands/events/views (`publicSurfaceOf`, same as `em api generate`/`em api check`) plus every
  * declared type reachable from their fields (`reachableTypeRefs`, same walk `em api generate`'s
- * contract body uses), each field's type resolved through `resolvePublicType` — the one notion
- * of the public surface every em surface shares, so a companion tool never re-derives it from
- * `em export --json` and risks drifting from it.
+ * contract body uses), every declared identity scalar reachable the same way
+ * (`reachableScalarRefs`, GH #477), and every declared enum reachable the same way
+ * (`reachableEnumRefs`, GH #478), each field's type resolved through `resolvePublicType` — the
+ * one notion of the public surface every em surface shares, so a companion tool never re-derives
+ * it from `em export --json` and risks drifting from it.
  */
 export declare function buildApiSurfaceReport(model: NormalizedModel, refs: RefsResult, diagnostics: Diagnostic[], source: string, file: string): ApiSurfaceReport;
 /**

package/dist/cli/api.js

@@ -14,7 +14,7 @@ import { hasErrors } from "../model/validate.js";
 import { compile, compileModelFile } from "../pipeline.js";
 import { ModelLoadError } from "../model/loadModel.js";
 import { ParseError } from "../parser/parser.js";
-import { buildApiContract, publicSurfaceOf, reachableTypeRefs } from "../emit/api.js";
+import { buildApiContract, publicSurfaceOf, reachableEnumRefs, reachableScalarRefs, reachableTypeRefs } from "../emit/api.js";
 import { buildExportDoc } from "../emit/json.js";
 import { kebabSlug } from "../util/slug.js";
 import { realGit, resolveRevision } from "./diff-inputs.js";
@@ -36,14 +36,25 @@ export function generateContract(file, source, compiled, outPath) {
 }
 const keyOf = (kind, name) => `${kind}:${normalizeName(name)}`;
 /** Build the public surface of one compiled model: public commands (input), events and views
- *  (output), and every declared type reachable from them (carrying the roles that reach it). */
-export function surfaceOf(slices, types) {
+ *  (output), and every declared type/enum reachable from them (carrying the roles that reach
+ *  it — GH #478 extends the existing type-reach walk to also track an `enumRef` field,
+ *  directly or through a reachable type's own fields, the same way `reachableEnumRefs`
+ *  (emit/api.ts) tracks it for `em api generate`). `enums` defaults to `[]` so every existing
+ *  caller (and the one test helper that built a `Surface` before enums existed) keeps compiling
+ *  without a required third argument at a call site that never has one. */
+export function surfaceOf(slices, types, enums = []) {
     const s = publicSurfaceOf(slices);
     const entries = [];
     const typesByRef = new Map(types.map((t) => [t.ref, t]));
     const typeRoles = new Map();
+    const enumRoles = new Map();
     const reach = (fields, role) => {
         for (const f of fields ?? []) {
+            if (f.enumRef) {
+                const roles = enumRoles.get(f.enumRef.ref) ?? new Set();
+                roles.add(role);
+                enumRoles.set(f.enumRef.ref, roles);
+            }
             if (!f.typeRef)
                 continue;
             const roles = typeRoles.get(f.typeRef.ref) ?? new Set();
@@ -63,6 +74,7 @@ export function surfaceOf(slices, types) {
             renamedFrom: el.renamedFrom ?? [],
             roles: new Set([role]),
             invariants: el.invariants ?? [],
+            members: [],
         });
         reach(el.fields, role);
     };
@@ -76,7 +88,13 @@ export function surfaceOf(slices, types) {
         const roles = typeRoles.get(t.ref);
         if (!roles)
             continue;
-        entries.push({ kind: "type", name: t.name, key: keyOf("type", t.name), fields: t.fields, renamedFrom: [], roles, invariants: [] });
+        entries.push({ kind: "type", name: t.name, key: keyOf("type", t.name), fields: t.fields, renamedFrom: [], roles, invariants: [], members: [] });
+    }
+    for (const e of enums) {
+        const roles = enumRoles.get(e.ref);
+        if (!roles)
+            continue;
+        entries.push({ kind: "enum", name: e.name, key: keyOf("enum", e.name), fields: [], renamedFrom: [], roles, invariants: [], members: e.members });
     }
     const allElements = new Set();
     for (const slice of slices)
@@ -84,18 +102,38 @@ export function surfaceOf(slices, types) {
             allElements.add(keyOf(el.kind, el.name));
     for (const t of types)
         allElements.add(keyOf("type", t.name));
+    for (const e of enums)
+        allElements.add(keyOf("enum", e.name));
     return { entries, allElements };
 }
-/** A field's type as the contract sees it: a declared type's name or the raw string,
- *  normalized, with its array arity. */
+/** A field's type as the contract sees it: a declared type's, identity scalar's or enum's
+ *  name, or the raw string, normalized, with its array arity. */
 export function typeLabel(f) {
     if (f.typeRef)
         return `${f.typeRef.name}${f.typeRef.array ? "[]" : ""}`;
+    if (f.scalarRef)
+        return `${f.scalarRef.name}${f.scalarRef.array ? "[]" : ""}`;
+    if (f.enumRef)
+        return `${f.enumRef.name}${f.enumRef.array ? "[]" : ""}`;
     return f.type ?? "(none)";
 }
+/**
+ * GH #477: a `scalarRef` folds its `base` into the identity string too, not just `ref`/`array` —
+ * so a surviving scalar DECLARATION's base changing (`OrderId: uuid` -> `OrderId: string`)
+ * registers as a type change on every field that uses it, even though the scalar's own ref and
+ * the field's array arity are unchanged. This reuses `diffFields`' existing per-field
+ * `compare()` rather than adding a second comparison path — see its `scalarRef`-aware branch
+ * below for the breaking-change message this produces. GH #478: `enumRef` needs no equivalent
+ * fold — an enum's MEMBER changes are diffed on the enum's own `SurfaceEntry` (`diffEnumMembers`
+ * below), not per using field, so `ref`/`array` alone identify a field's enum reference here.
+ */
 export function typeIdentity(f) {
     if (f.typeRef)
         return `ref:${f.typeRef.ref}:${f.typeRef.array}`;
+    if (f.scalarRef)
+        return `ref:${f.scalarRef.ref}:${f.scalarRef.array}:${f.scalarRef.base}`;
+    if (f.enumRef)
+        return `enum-ref:${f.enumRef.ref}:${f.enumRef.array}`;
     return `raw:${(f.type ?? "").replace(/\s+/g, "").toLowerCase()}`;
 }
 function diffFields(base, head, element, out) {
@@ -120,7 +158,25 @@ function diffFields(base, head, element, out) {
     }
     const compare = (b, h) => {
         if (typeIdentity(b) !== typeIdentity(h)) {
-            out.push({ kind: "breaking", element, field: h.name, what: `type changed ${typeLabel(b)} → ${typeLabel(h)}` });
+            // GH #477: same scalar declaration, same array arity, different `base` — the field's own
+            // reference didn't change, but what it resolves to on the wire did (every consumer
+            // deserializing this field as the old base now gets the new one). Phrased distinctly from
+            // an ordinary type change so the report doesn't read as "OrderId -> OrderId" (no visible
+            // difference) when the real story is the scalar's declaration.
+            if (b.scalarRef && h.scalarRef &&
+                b.scalarRef.ref === h.scalarRef.ref &&
+                b.scalarRef.array === h.scalarRef.array &&
+                b.scalarRef.base !== h.scalarRef.base) {
+                out.push({
+                    kind: "breaking",
+                    element,
+                    field: h.name,
+                    what: `scalar "${h.scalarRef.name}" base changed ${b.scalarRef.base} → ${h.scalarRef.base}`,
+                });
+            }
+            else {
+                out.push({ kind: "breaking", element, field: h.name, what: `type changed ${typeLabel(b)} → ${typeLabel(h)}` });
+            }
         }
         if (b.optional !== h.optional) {
             if (h.optional) {
@@ -160,6 +216,37 @@ function diffFields(base, head, element, out) {
         out.push({ kind, element, field: h.name, what: `added (${required ? "required" : "optional"})` });
     }
 }
+/**
+ * GH #478: an enum's own member set, base vs HEAD, diffed by role (the same `isInput`/
+ * `isOutput` union `diffFields` computes above) — the issue's pinned severity matrix:
+ *   - member REMOVED (or, since there's no rename clause, the removal half of what reads as a
+ *     rename) is breaking wherever the enum reaches an OUTPUT (an existing receiver may still
+ *     expect that known value) — not conditioned on input reach at all.
+ *   - member ADDED is breaking wherever the enum reaches an INPUT (existing senders are
+ *     unaffected; a strict receiver built against the old member set rejects the new value) —
+ *     additive on a PURE output (`isInput` false): a receiver tolerates an unknown value.
+ * A rename is never detected as such (same "no rename detection" posture `em diff` already
+ * takes for a `type`/element rename, model/diff.ts) — it reads as remove+add, each half scored
+ * independently by the rules above. Base order first (removals), then HEAD-only (additions),
+ * same convention `diffFields` uses.
+ */
+function diffEnumMembers(base, head, element, out) {
+    const roles = new Set([...base.roles, ...head.roles]);
+    const isInput = roles.has("input");
+    const isOutput = roles.has("output");
+    const baseKeys = new Set(base.members.map(normalizeName));
+    const headKeys = new Set(head.members.map(normalizeName));
+    for (const b of base.members) {
+        if (headKeys.has(normalizeName(b)))
+            continue;
+        out.push({ kind: isOutput ? "breaking" : "additive", element, field: null, what: `member "${b}" removed` });
+    }
+    for (const h of head.members) {
+        if (baseKeys.has(normalizeName(h)))
+            continue;
+        out.push({ kind: isInput ? "breaking" : "additive", element, field: null, what: `member "${h}" added` });
+    }
+}
 /** MIL-265: a public element's invariants, base vs HEAD, matched by ID. Added or rule text
  *  changed = breaking (the contract got tighter); removed = additive (looser). HEAD order for
  *  additions/changes, then base order for removals. */
@@ -195,7 +282,10 @@ export function diffSurfaces(base, head) {
         const same = baseByKey.get(h.key);
         if (same) {
             matchedBase.add(same.key);
-            diffFields(same, h, element, out);
+            if (h.kind === "enum")
+                diffEnumMembers(same, h, element, out);
+            else
+                diffFields(same, h, element, out);
             diffInvariants(same, h, element, out);
             continue;
         }
@@ -205,11 +295,14 @@ export function diffSurfaces(base, head) {
         if (renamedFrom) {
             matchedBase.add(renamedFrom.key);
             out.push({ kind: "breaking", element, field: null, what: `renamed from "${renamedFrom.name}"` });
-            diffFields(renamedFrom, h, element, out);
+            if (h.kind === "enum")
+                diffEnumMembers(renamedFrom, h, element, out);
+            else
+                diffFields(renamedFrom, h, element, out);
             diffInvariants(renamedFrom, h, element, out);
             continue;
         }
-        if (h.kind !== "type" && base.allElements.has(h.key)) {
+        if (h.kind !== "type" && h.kind !== "enum" && base.allElements.has(h.key)) {
             out.push({ kind: "additive", element, field: null, what: "marked public" });
         }
         else {
@@ -220,7 +313,7 @@ export function diffSurfaces(base, head) {
         if (matchedBase.has(b.key))
             continue;
         const element = elementId(b);
-        if (b.kind !== "type" && head.allElements.has(b.key)) {
+        if (b.kind !== "type" && b.kind !== "enum" && head.allElements.has(b.key)) {
             out.push({ kind: "breaking", element, field: null, what: "`public` dropped" });
         }
         else {
@@ -274,7 +367,7 @@ export function runApiCheck(file, base, runGit = realGit) {
             return { ok: false, message: `em api check: unknown revision "${base}" (needed for --base)`, diagnostics: head.diagnostics };
         }
         const headDoc = buildExportDoc(head.model, head.refs, head.diagnostics, head.source, file).doc;
-        const headSurface = surfaceOf(headDoc.model.slices, headDoc.model.types);
+        const headSurface = surfaceOf(headDoc.model.slices, headDoc.model.types, headDoc.model.enums);
         const atBase = resolveRevision(file, base, runGit);
         let baseSurface = null;
         if (atBase.ok) {
@@ -301,7 +394,7 @@ export function runApiCheck(file, base, runGit = realGit) {
             // Base-side validate errors (e.g. a pre-1.14 free-text public type) do not block the
             // structural diff — the diff reads shapes, not strictness.
             const baseDoc = buildExportDoc(baseCompiled.model, baseCompiled.refs, baseCompiled.diagnostics, atBase.content, file).doc;
-            baseSurface = surfaceOf(baseDoc.model.slices, baseDoc.model.types);
+            baseSurface = surfaceOf(baseDoc.model.slices, baseDoc.model.types, baseDoc.model.enums);
         }
         else if (!/is not tracked by git/.test(atBase.message)) {
             return { ok: false, message: atBase.message.replace(/^em diff:/, "em api check:"), diagnostics: head.diagnostics };
@@ -334,35 +427,41 @@ export function formatApiCheckText(r) {
     return lines;
 }
 /** Resolve one field's public type exactly as `em api generate`'s own `fieldType()` does
- *  (emit/api.ts) — declared types win (same precedence `resolvePublicType` already gives), else
- *  the fixed scalar table. A model with errors never reaches here (both CLI callers refuse
- *  first), so an unresolved type is a programming error, not a user-facing case — same posture
- *  as `buildApiContract`'s own throw. */
-function surfaceFieldType(f, typesByName, owner) {
-    const r = resolvePublicType(f.type ?? undefined, typesByName);
+ *  (emit/api.ts) — declared types win (same precedence `resolvePublicType` already gives), then
+ *  a declared identity scalar (GH #477), then a declared enum (GH #478), else the fixed scalar
+ *  table. A model with errors never reaches here (both CLI callers refuse first), so an
+ *  unresolved type is a programming error, not a user-facing case — same posture as
+ *  `buildApiContract`'s own throw. */
+function surfaceFieldType(f, typesByName, scalarsByName, enumsByName, owner) {
+    const r = resolvePublicType(f.type ?? undefined, typesByName, scalarsByName, enumsByName);
     if (!r) {
         throw new Error(`em api surface: ${owner} field "${f.name}" has no public type — em validate's ` +
             "public-field-type-unresolved should have refused this model");
     }
-    return r.kind === "scalar"
-        ? { kind: "scalar", scalar: r.scalar, tsType: r.tsType, array: r.array }
-        : { kind: "declared", scalar: null, tsType: r.typeDecl.name, array: r.array };
+    if (r.kind === "scalar")
+        return { kind: "scalar", scalar: r.scalar, base: null, tsType: r.tsType, array: r.array };
+    if (r.kind === "identity") {
+        return { kind: "scalar-alias", scalar: null, base: r.base, tsType: r.scalarDecl.name, array: r.array };
+    }
+    if (r.kind === "enum")
+        return { kind: "enum", scalar: null, base: null, tsType: r.enumDecl.name, array: r.array };
+    return { kind: "declared", scalar: null, base: null, tsType: r.typeDecl.name, array: r.array };
 }
-function surfaceField(f, typesByName, owner) {
+function surfaceField(f, typesByName, scalarsByName, enumsByName, owner) {
     return {
         name: f.name,
-        type: surfaceFieldType(f, typesByName, owner),
+        type: surfaceFieldType(f, typesByName, scalarsByName, enumsByName, owner),
         optional: f.optional,
         tag: f.tag,
         assigned: f.assigned,
         renamedFrom: f.renamedFrom,
     };
 }
-function surfaceElement(el, typesByName) {
+function surfaceElement(el, typesByName, scalarsByName, enumsByName) {
     return {
         name: el.name,
         slug: kebabSlug(el.name),
-        fields: (el.fields ?? []).map((f) => surfaceField(f, typesByName, `${el.kind} "${el.name}"`)),
+        fields: (el.fields ?? []).map((f) => surfaceField(f, typesByName, scalarsByName, enumsByName, `${el.kind} "${el.name}"`)),
         invariants: el.invariants ?? null,
     };
 }
@@ -370,28 +469,38 @@ function surfaceElement(el, typesByName) {
  * Build the `em api surface` report for an already-validated (error-free) model: the `public`
  * commands/events/views (`publicSurfaceOf`, same as `em api generate`/`em api check`) plus every
  * declared type reachable from their fields (`reachableTypeRefs`, same walk `em api generate`'s
- * contract body uses), each field's type resolved through `resolvePublicType` — the one notion
- * of the public surface every em surface shares, so a companion tool never re-derives it from
- * `em export --json` and risks drifting from it.
+ * contract body uses), every declared identity scalar reachable the same way
+ * (`reachableScalarRefs`, GH #477), and every declared enum reachable the same way
+ * (`reachableEnumRefs`, GH #478), each field's type resolved through `resolvePublicType` — the
+ * one notion of the public surface every em surface shares, so a companion tool never re-derives
+ * it from `em export --json` and risks drifting from it.
  */
 export function buildApiSurfaceReport(model, refs, diagnostics, source, file) {
     const { doc } = buildExportDoc(model, refs, diagnostics, source, file);
     const surface = publicSurfaceOf(doc.model.slices);
     const typesByRef = new Map(doc.model.types.map((t) => [t.ref, t]));
     const reachable = reachableTypeRefs([...surface.commands, ...surface.events, ...surface.views], typesByRef);
+    const reachableScalars = reachableScalarRefs([...surface.commands, ...surface.events, ...surface.views], typesByRef);
+    const reachableEnums = reachableEnumRefs([...surface.commands, ...surface.events, ...surface.views], typesByRef);
     return {
         file,
         modelKey: doc.model.key,
-        commands: surface.commands.map((el) => surfaceElement(el, model.typesByName)),
-        events: surface.events.map((el) => surfaceElement(el, model.typesByName)),
-        views: surface.views.map((el) => surfaceElement(el, model.typesByName)),
+        commands: surface.commands.map((el) => surfaceElement(el, model.typesByName, model.scalarsByName, model.enumsByName)),
+        events: surface.events.map((el) => surfaceElement(el, model.typesByName, model.scalarsByName, model.enumsByName)),
+        views: surface.views.map((el) => surfaceElement(el, model.typesByName, model.scalarsByName, model.enumsByName)),
         types: doc.model.types
             .filter((t) => reachable.has(t.ref))
             .map((t) => ({
             name: t.name,
             slug: kebabSlug(t.name),
-            fields: t.fields.map((f) => surfaceField(f, model.typesByName, `type "${t.name}"`)),
+            fields: t.fields.map((f) => surfaceField(f, model.typesByName, model.scalarsByName, model.enumsByName, `type "${t.name}"`)),
         })),
+        scalars: doc.model.scalars
+            .filter((s) => reachableScalars.has(s.ref))
+            .map((s) => ({ name: s.name, slug: kebabSlug(s.name), base: s.base })),
+        enums: doc.model.enums
+            .filter((e) => reachableEnums.has(e.ref))
+            .map((e) => ({ name: e.name, slug: kebabSlug(e.name), members: e.members })),
     };
 }
 /**
@@ -441,7 +550,18 @@ export function formatApiSurfaceText(r) {
     section("events", r.events);
     section("views", r.views);
     section("types", r.types);
-    if (r.commands.length === 0 && r.events.length === 0 && r.views.length === 0 && r.types.length === 0) {
+    if (r.scalars.length > 0) {
+        lines.push("scalars:");
+        for (const s of r.scalars)
+            lines.push(`  ${s.slug} extends ${s.base}`);
+    }
+    if (r.enums.length > 0) {
+        lines.push("enums:");
+        for (const e of r.enums)
+            lines.push(`  ${e.slug} { ${e.members.join(", ")} }`);
+    }
+    if (r.commands.length === 0 && r.events.length === 0 && r.views.length === 0 &&
+        r.types.length === 0 && r.scalars.length === 0 && r.enums.length === 0) {
         lines.push("(no public surface)");
     }
     return lines;