create-githolon 0.71.0 → 0.72.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-githolon",
-  "version": "0.71.0",
+  "version": "0.72.0",
   "type": "module",
   "description": "Scaffold a Nomos domain package: the starter domain + compile config + live e2e. `npm create githolon my-app`.",
   "license": "SEE LICENSE IN LICENSE.md",

package/template/docs/02-authoring.md

@@ -154,6 +154,89 @@ never imports `catalogue`'s implementation. If two domains ever import each othe
 concrete types, the compiler fails with a cycle diagnostic pointing you here. Contracts
 are pure typing metadata — they never change an aggregate's law hash.
 
+## Naming: the four generated tiers (and how to rename them)
+
+One aggregate spawns several generated identities. Know the four tiers so you can name
+each deliberately (the names below are the DEFAULTS, derived from your ids):
+
+| tier | what it is | generated name |
+|---|---|---|
+| **Command payloads** | the typed input to a directive (`toPayloadJson()`) | `<Cap(directiveId)>Payload` — e.g. `CreateSitePayload` |
+| **Aggregate state** | the concrete decoded aggregate class | `<Cap(aggId)>` — e.g. `EstateSite` |
+| **Read models / projections** | the typed projection row (incl. derived/combined fields) | `<stem(aggId)>ReadModel` — e.g. `EstateSiteReadModel` |
+| **Value objects** | a named structured value (`valueObject`/`geo.*`) | the VO's own declared name, unprefixed |
+
+The wire identity (aggregate id, stable ids, projection type tag) is separate from ALL of
+these — names are labels, identity is minted. Renaming below never touches the law.
+
+### `.dartName()` — declare the product name (Dart codegen only)
+
+An aggregate id is often long for uniqueness (`EstateSite`); the Dart product name you want
+is short (`Site`). `.dartName("Site")` makes `Site` the PRIMARY generated Dart identity —
+not a post-hoc alias:
+
+```ts
+export const EstateSite = aggregate("EstateSite", {
+  owner: t.string().merge(Lww),
+  name: t.string().merge(Lww),
+}).public().dartName("Site");
+```
+
+Now EVERY Dart site renames consistently: the state class `Site`, the read model
+`SiteReadModel`, the typed id `SiteId`, the by-id accessors `readSiteById`/`watchSiteById`,
+`listSites`, and any `ForeignRef<Site>`. The WIRE id stays `EstateSite` (unchanged law,
+unchanged stable ids — the minted-id tag is still `EstateSite_<uuid>`). It is validated
+at author time (must be a Dart type identifier `^[A-Z][A-Za-z0-9_]*$`; a collision with
+another aggregate's name fails the compile). **TS codegen is deliberately unaffected** —
+the generated `.client.ts` stays id-derived (`EstateSiteData`), so there is no
+cross-language identity confusion; `.dartName()` is a Dart-only presentation choice.
+
+### Namespaces, not prefixes (multi-domain packages)
+
+Each domain compiles to its OWN generated `.dart` library (`estate.dart`, `catalogue.dart`).
+That IS Dart's namespace mechanism: two domains can BOTH declare a `Site` and stay
+unambiguous — `import 'package:x/src/generated/estate.dart' as estate;` then `estate.Site`.
+The compiler never smashes a domain word into your class name. The top-level package barrel
+flat-re-exports every domain's classes by default (`dart.packages.barrelExports: 'all'`);
+for a multi-domain package where you'd rather force prefixed imports (so two `Site`s never
+silently share one flat scope), set `barrelExports: 'explicit'` — the barrel then exports
+only the shared core and you import each domain with an `as` prefix. A single-domain package
+is unaffected either way.
+
+### The migration compat package
+
+Renaming a name callers already import is a breaking change. `dart.packages.compat` gives
+you a soft landing: a standalone, clearly-labeled package of pure `typedef`s over the real
+types, deletable once callers have migrated. Map the OLD name each caller used to the new
+generated name via `dart.names`, and route it to the compat package:
+
+```js
+// nomos.package.mjs
+dart: {
+  support: "package",
+  packages: {
+    types:  "co2_estate_types",
+    client: "co2_estate_client",
+    test:   "co2_estate_test",
+    compat: "co2_estate_compat_names",   // ← the migration-only shim
+  },
+  // EstateSite.dartName("Site") → the read model is now `SiteReadModel`. Callers that
+  // imported the old `SiteRootAggregate` name keep compiling via the compat typedef.
+  names: { SiteReadModel: "SiteRootAggregate" },
+}
+```
+
+The `co2_estate_compat_names` package then contains exactly:
+
+```dart
+// MIGRATION-ONLY — delete this package once callers have moved to the real names in
+// `co2_estate_types`. …
+import 'package:co2_estate_types/co2_estate_types.dart';
+typedef SiteRootAggregate = SiteReadModel;
+```
+
+When `compat` is UNSET, the typedefs land in the types barrel exactly as before.
+
 ## Merge drivers ARE the conflict policy
 
 | driver | concurrent writes to the same field… |

package/template/docs/03-client.md

@@ -38,16 +38,54 @@ and the semantics live in the doc comments.
 Everything about Nomos is multi-workspace: a real app holds a dozen+ live
 local workspaces (the user's home, each estate, each catalogue). Don't build
 on a single-connection assumption — hold one PLANE and many handles on it.
+The four-layer split (the blessed shape):
+
+- **Engine** (`NomosEngine`, the bridge root / `openRealm`) — ONLY the
+  runtime: mount/connect, the session registry, sync, custody, `follow(ref)`.
+  Never the surface for domain writes.
+- **Session** — exactly one workspace, stateful + inspectable.
+- **Generated client** — exactly one session + one domain interface + one
+  actor context. No workspace/domain/directive strings at call sites, ever.
+- **Stateless values** — payloads, VOs, `NomosRef`s, read rows, outcomes.
 
 - **TS/JS**: `openRealm` mounts N workspaces in ONE engine; give each
   generated client its own handle:
   `const realm = await openRealm({ cloud }); const estate = estateClient(await realm.workspace("estate-…"));`
   (`connect()` remains the one-workspace sugar over the same machinery.)
-- **Flutter/Dart**: one `NomosBridge` per app, one `NomosSession` per
-  workspace: `EstateClient(bridge.session('estate-…'))`. A session IS a
-  `NomosBridge` (generated clients take it unchanged) with every op pinned to
-  its workspace. Calling a bare multi-session bridge without a session refuses
-  LOUDLY (`multiple sessions connected — pass session`) rather than guessing.
+- **Flutter/Dart** — session-bound clients, preflighted at construction:
+
+  ```dart
+  final engine = NomosBridge(transport);          // the device's local plane
+  await engine.ready;
+  final home = await engine.open(cloud: cloud, workspace: homeWs);
+  final homeClient = await HomeClient.bind(home); // ASYNC preflight (see below)
+
+  final platform = await engine.open(cloud: cloud, workspace: platformWs);
+  final platformClient = await Co2PlatformClient.bind(platform);
+
+  // A `.births()` directive takes NO parent — the parent IS the session workspace:
+  final birth = await platformClient.birthEstateWorkspace(payload: order);
+  // NomosRef is THE cross-workspace primitive — follow it, bind the next client:
+  final estate = await engine.follow(birth.bornRefs.single);
+  final estateClient = await EstateClient.bind(estate);
+  ```
+
+  `XClient.bind(session)` verifies the session's workspace is reachable, holds
+  the client's domain, and serves a structurally compatible interface (#72
+  shape-compat) — an incompatible session throws a typed
+  `DomainClientSessionMismatch` (session, expected/active domain keys +
+  hashes, the classified cause, a fix hint) AT CONSTRUCTION, not two clicks
+  into the app. The synchronous `XClient(session)` constructor remains for
+  codepaths that can't await; it runs the SAME preflight lazily on the first
+  dispatch. `session.assertCompatible(XClient.interface)` is the same check as
+  a bare assertion (handy in tests). A dispatch that names a domain the
+  workspace doesn't run surfaces as a typed `DomainNotInstalledForSession`
+  naming what the workspace ACTUALLY runs and the likely causes — never the
+  bare kernel string.
+
+  The engine-level generic writes (`bridge.offerDirective(...)`,
+  `bridge.createWorkspace(parent: ...)`) are `@Deprecated` — CLI/admin tooling
+  lanes only. App code dispatches through a bound client.
 
 A workspace opened with no `cloud` is LOCAL-ONLY (never converges upstream);
 cloud sync is a per-workspace posture, and one plane freely mixes both.

package/template/docs/08-births.md

@@ -62,6 +62,21 @@ export const birthEstateChild = directive("birthEstateChild")
   .requires("creator");                       // the birth authority (see below)
 ```
 
+## From the app (Dart) — parentless, session-bound
+
+The generated Dart client emits a typed method per `.births()` directive, bound to the SESSION whose
+workspace IS the parent — no loose parent string, and the born child comes back as a followable ref:
+
+```dart
+final parentClient = await MyPlatformClient.bind(parentSession);
+final birth = await parentClient.birthEstateChild(payload: order);   // parent = the session workspace
+final child = await engine.follow(birth.bornRefs.single);            // mount the born child
+final childClient = await EstateClient.bind(child);                  // typed client on the child
+```
+
+(The old `parent:` parameter survives one minor version as a deprecated legacy-gateway shim; its verdict
+rides `outcome.gatewayVerdict`.)
+
 ## Authority — who may birth
 
 `.requires("creator")` gates the birth on a relation tuple. Grant the home owner `#creator` on their own