@milehimikey/em 1.22.0 → 1.22.2

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

@@ -1,6 +1,6 @@
 ---
 name: event-modeling
-em-version: 1.22.0
+em-version: 1.22.2
 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.2
 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.2
 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.2
 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.2
 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.2
 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.2
 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)
@@ -367,6 +369,11 @@ type Name { field: Type, ... }      # named structured type, reusable from any f
 - **Tags:** `@Persona` only on `ui`; `@Context` only on `event`. Undeclared tags auto-create a
   row. Multi-word tags need no quoting — the tag captures everything after `@` to end of line
   (`ui Ticket Queue @Customer Service` matches `persona Customer Service`).
+- **Optional fields:** a trailing `?` on a field name marks it optional (it may be absent);
+  fields are required by default (MIL-237). `note?: text`, typeless `note?` and quoted
+  `"display name"?: text` all work, and the `?` is never part of the name. `em export` carries
+  `optional: true|false`, `em api generate` emits `name?: T`, the slice-doc table shows
+  Required `no`, and `em diff` / `em api check` report a required<->optional flip.
 - **`from "X"`** on views/automations declares the source(s); names are quoted, comma-separated.
   Matching is case-insensitive and whitespace-normalized. A `from` may never point at an event or
   view that first appears in a LATER slice (forward-only timeline — validation error).
@@ -620,6 +627,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 +982,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 +1025,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-2",
   "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.2: 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;
 /**