create-githolon 0.98.3 → 0.100.0

package/template/docs/02-authoring.md

@@ -1,437 +0,0 @@
-# Authoring law
-
-You write exactly TWO things: aggregates and directives. Never apply/fold/
-merge code — the kernel owns folding; your directive PLANS ops and the sealed
-engine replays them deterministically on every peer. Declared reads (query,
-count, derived, sum) are auto-discovered from your module's exports by shape.
-`domains/todo.ts` demonstrates the core patterns below; reshape it.
-
-## Aggregates: typed fields, each tagged a merge driver
-
-```ts
-export const Book = aggregate("Book", {
-  title: t.string().merge(Lww),
-  tags:  t.set(t.string()).merge(AddWins),
-  notes: t.map(t.string()).merge(MapOf(Lww)),
-});
-```
-
-Field kinds: `t.string()` · `t.int()` · `t.bool()` (a true/false flag —
-count/filter key on it; NOT a 2-value `t.enum`) · `t.enum([...] as const)` (typos squeal
-at compile time) · `t.set(t.string())` · `t.map(inner)` · `t.json()` /
-`t.jsonObject()` (JSON-string leaf; `jsonObject` asserts an object and reads
-back structured) · `t.ref(Agg)` (an id-valued reference) ·
-`t.hasMany(Child).via("parent")` (the virtual read side of a child's ref —
-nothing stored on the parent). Add `.optional()` where absence is legal.
-
-**Cross-workspace links are TYPED — never a bare string.** A reference into ANOTHER
-workspace (its own app-specific ledger — a Task pointing at a Space, a Project at a
-catalogue) is `t.foreignRef({ workspace: "<sibling field holding the foreign workspace
-id>", target: SpaceOwner })`. It stores the foreign aggregate id, types the edge as
-`ForeignRef<SpaceOwnerData>`, and the generated client emits `.resolve(nomos)` /
-`.watch(nomos)` to open the other holon on demand. Cross-domain imports are first-class
-(`import { SpaceOwner } from "./space.ts"`). It is a typed LOCATOR, not a gate-enforced
-foreign key (separate ledgers = no cross-workspace referential integrity at the gate);
-law that must depend on the foreign FACT opts into attested evidence via `trustSource`
-+ `.readsFrom(...)`. Worked four-layer example (home → Space + Project with a typed
-cross-ref): `bench/scale/fixtures/four-layer-nested-topology`. **Do NOT store a foreign
-workspace name in a plain `t.string()` — that throws away the type and the resolver.**
-
-## Relationships: reference aggregates, don't hand-roll composite ids
-
-When one aggregate points at another — a listing's primary image, its many
-images, a membership row — reach for a REFERENCE, not a `primary:<listingId>` /
-`media:<listingId>:<attId>` string convention. A `t.ref` stores the target's id
-(the same bytes a string would), but it tells the compiler, the generated
-client, and the next reader *what that id means* — so queries can traverse it,
-the client types it as a link, and the ER graph renders it.
-
-```ts
-export const Attachment = aggregate("Attachment", { url: t.string().merge(Lww) });
-
-export const Listing = aggregate("Listing", {
-  title: t.string().merge(Lww),
-  primaryImage: t.ref(Attachment),                     // 1:1 — "exactly one" is one field (re-set to change)
-  media: t.hasMany(() => ListingMedia).via("listing"), // 1:N — the virtual read side of the child's ref
-});
-
-// M:N WITH EDGE DATA — a real join aggregate whose FKs are refs (typed + traversable), carrying role/order.
-export const ListingMedia = aggregate("ListingMedia", {
-  listing: t.ref(Listing),
-  attachment: t.ref(Attachment),
-  role: t.enum(["gallery", "datasheet", "manual"] as const).merge(Lww),
-  order: t.int().merge(Lww),
-});
-```
-
-Pick the shape by cardinality: **1:1** is a `t.ref` field ("one" is structural,
-no invariant needed); **1:N** is `t.hasMany(...).via("backref")` on the parent
-(virtual — the child's `t.ref` back-edge is the only thing stored, and
-`parent.add("children", child)` writes ONE event on the child); **M:N** is a
-join aggregate with `t.ref` foreign keys (a real row when the edge carries data
-like role/order). Traverse in a query by keying on the ref: `query("mediaByListing").key("listing").returns(ListingMedia)`.
-
-A bidirectional pair (`Listing.hasMany(ListingMedia)` ⇄ `ListingMedia.ref(Listing)`)
-is a declaration-order cycle — pass a THUNK on either side (`t.hasMany(() =>
-ListingMedia)` / `t.ref(() => Listing)`) and it resolves lazily; the emitted law
-is byte-identical to the eager form. Worked example: `examples/relations`.
-
-## Value objects: named, composable structured values
-
-When a field is a STRUCTURE (an address, a location, a money amount), don't
-hand-roll `t.jsonObject()` plus a private zod — declare a NAMED value object
-once and reuse it everywhere:
-
-```ts
-import { valueObject, geo, z } from "@githolon/dsl";
-
-const PostalAddress = valueObject("PostalAddress", {
-  streetAddress: z.string(), city: z.string(), countryCode: z.string(),
-});
-const GeoPoint = geo.point("GeoPoint");            // RFC 7946 Point
-const TaskLocation = valueObject("TaskLocation", {
-  address: PostalAddress.optional(),               // VOs nest in VOs
-  point: GeoPoint.optional(),
-});
-
-export const ProjectTask = aggregate("ProjectTask", {
-  name: t.string().merge(Lww),
-  location: TaskLocation.field().optional(),       // ONE json-object leaf
-  point: GeoPoint.field().optional(),              // give a geometry its OWN field…
-});
-export const tasksByBounds = spatial("tasksByBounds").of(ProjectTask).on("point"); // …to index it
-export const recordTask = directive("recordTask").creates(ProjectTask)
-  .payload(z.object({ name: z.string(), location: TaskLocation.zod })) // the SAME zod validates
-  .plan((p) => { create(ProjectTask).set("name", p.name).set("location", p.location); return []; });
-```
-
-ONE definition yields the zod (payload validation — a malformed VO is the
-normal typed refusal), the TS type + a named interface in the generated
-`.client.ts`, a typed Dart class (`fromProjected`/`toJson`), and a canonical
-descriptor in the package IR (`nomosValueObjects`) so tooling can see the
-structure. A domain using no VOs is byte-identical to before they existed.
-
-**The merge rule (know it):** a VO field is ONE `Lww`-class value leaf,
-replaced WHOLESALE on write — there is NO per-subfield merge. Two offline
-writers touching different subfields of the same VO converge to one writer's
-whole value. When subfields must merge independently, model them as aggregate
-fields or a `t.map(...)` — that is what aggregates and maps are for.
-`.optional()`/`.encrypted()` compose under the usual field rules.
-
-**Spatial pairing:** `geo.point()` is the blessed spatial-indexable shape.
-The R*Tree indexes a TOP-LEVEL geometry field — so give the geometry its own
-field (`point: GeoPoint.field()`) and declare `spatial(...).on("point")`. A
-geometry nested inside another VO (`location.point`) is data, not an
-indexable path (a spatial over a non-geo VO field refuses at compile).
-`geo.lineString()` / `geo.polygon()` exist as typed VOs too.
-
-VO fields come from a deliberately small set: `z.string()` · `z.number()` ·
-`z.boolean()` · `z.enum([...])` · `z.array(<of these>)` · a nested value
-object · `.optional()` on any. Anything richer refuses at compile — model it
-as an aggregate. A `z.enum` field generates a REAL Dart enum
-(`<VoName><Field>Enum`, `.wire` = the exact wire string) with a TOLERANT
-decode: a wire value this client's law snapshot doesn't know decodes to the
-`unknownWire` sentinel — law can add enum values without crashing old clients.
-
-## Contracts: public DTOs for cross-domain references
-
-When one domain references another's aggregate, reference a **contract** — a named
-public shape (a DTO) — not the concrete aggregate. This keeps domains from importing
-each other's private types (which tangles the package graph). A contract is fields,
-no behavior:
-
-```ts
-// contracts.ts — the shared public shapes
-export const SpaceLabelContract = contract("SpaceLabel", {
-  labelId: t.string(),
-  name: t.string(),
-});
-
-// space.ts — the concrete owner declares it satisfies the shape (compile-checked;
-// a missing/mismatched field fails the build naming it). Private fields stay private.
-export const SpaceLabel = aggregate("SpaceLabel", {
-  labelId: t.string().merge(Lww),
-  name: t.string().merge(Lww),
-  internalNotes: t.string().merge(Lww),      // not in the contract — behind the boundary
-}).implements(SpaceLabelContract);
-
-// project.ts — reference the CONTRACT, never the concrete aggregate
-export const ProjectTask = aggregate("ProjectTask", {
-  spaceWorkspaceName: t.string().merge(Lww),
-  label: t.foreignRef({ workspace: "spaceWorkspaceName", target: SpaceLabelContract, domain: "space" }),
-});
-```
-
-The generated client types the reference as `ForeignRef<SpaceLabelContract>`;
-the Dart DTO class lives in a shared `contracts.dart` every domain imports, so `project`
-never imports `space`'s implementation. If two domains ever import each other's
-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. `RecordTaskPayload` |
-| **Aggregate state** | the concrete decoded aggregate class | `<Cap(aggId)>` — e.g. `ProjectTask` |
-| **Read models / projections** | the typed projection row (incl. derived/combined fields) | `<stem(aggId)>ReadModel` — e.g. `ProjectTaskReadModel` |
-| **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 (`ProjectTask`); the Dart product name you want
-is short (`Task`). `.dartName("Task")` makes `Task` the PRIMARY generated Dart identity —
-not a post-hoc alias:
-
-```ts
-export const ProjectTask = aggregate("ProjectTask", {
-  owner: t.string().merge(Lww),
-  name: t.string().merge(Lww),
-}).public().dartName("Task");
-```
-
-Now EVERY Dart site renames consistently: the state class `Task`, the read model
-`TaskReadModel`, the typed id `TaskId`, the by-id accessors `readTaskById`/`watchTaskById`,
-`listTasks`, and any `ForeignRef<Task>`. The WIRE id stays `ProjectTask` (unchanged law,
-unchanged stable ids — the minted-id tag is still `ProjectTask_<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 (`ProjectTaskData`), 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 (`project.dart`, `space.dart`).
-That IS Dart's namespace mechanism: two domains can BOTH declare a `Comment` and stay
-unambiguous — `import 'package:x/src/generated/project.dart' as project;` then `project.Comment`.
-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 `Comment`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:  "task_tracker_types",
-    client: "task_tracker_client",
-    test:   "task_tracker_test",
-    compat: "task_tracker_compat_names",   // ← the migration-only shim
-  },
-  // ProjectTask.dartName("Task") → the read model is now `TaskReadModel`. Callers that
-  // imported the old `TaskRootAggregate` name keep compiling via the compat typedef.
-  names: { TaskReadModel: "TaskRootAggregate" },
-}
-```
-
-The `task_tracker_compat_names` package then contains exactly:
-
-```dart
-// MIGRATION-ONLY — delete this package once callers have moved to the real names in
-// `task_tracker_types`. …
-import 'package:task_tracker_types/task_tracker_types.dart';
-typedef TaskRootAggregate = TaskReadModel;
-```
-
-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… |
-|---|---|
-| `Lww` | last write wins (by the intent's HLC timestamp) |
-| `AddWins` | sets union — concurrent adds ALL survive |
-| `MapOf(Lww)` | per-key LWW — concurrent writers to different keys commute |
-| `Conflict` | refuse to merge (fail-closed; the default if you tag nothing) |
-
-You choose the policy per field, at authoring time. Nobody writes merge code
-at 2am during an incident — the kernel applies the declared driver, the same
-way on every peer.
-
-## Directives: a zod payload → a pure plan
-
-```ts
-export const addBook = directive("addBook").creates(Book)
-  .payload(z.object({ title: z.string(), addedAt: z.string() }))
-  .plan((p) => { create(Book).set("title", p.title); return []; });
-```
-
-Plan ops: `set` (scalars/refs) · `addToSet` (the ONLY additive write to an
-AddWins set — `set()` on a set field would overwrite the union and is REFUSED
-at the type level and at runtime) · `setEntry` (one map key) · `strike`
-(retract). `.creates(Agg)` mints the id — payloads never carry one;
-`.mutates(Agg)` takes the instance id in the payload; `.ensures(Agg)` upserts
-at a DETERMINISTIC id (next section).
-
-## Upserts: `.ensures` — create-or-amend at a deterministic id
-
-When the CALLER owns the identity (a reading keyed `probe:day`, a config row
-keyed by name), mark the directive `.ensures(Agg)` and address the instance
-with an id DERIVED FROM THE PAYLOAD — never minted, never guessed:
-
-```ts
-export const recordReading = directive("recordReading").ensures(Reading)
-  .payload(z.object({ probe: z.string(), day: z.string(), value: z.number().int() }))
-  .plan((p) => {
-    const r = instance(Reading, `reading:${p.probe}:${p.day}`);
-    return [set(r, "probe", p.probe), set(r, "day", p.day), set(r, "value", p.value)];
-  });
-```
-
-The first dispatch creates the row; a re-dispatch folds onto it IN PLACE under
-the field merge drivers (Lww: a re-submission of the same value is a no-op, a
-corrected value replaces it). That makes the write IDEMPOTENT — any host can
-re-submit without double-counting. Collectors, crons, and retry loops live on
-this.
-
-## "Singletons" — minted record + natural-key query, NEVER a fixed row id
-
-A common instinct is to model a one-of-a-kind record (a platform, a config, a
-tenant) with a FIXED aggregate id — `create(Platform)` then address it forever
-at `"the-platform"`. **The gate refuses this.** Every `create()` mints a
-kernel id (`<TypeTag>_<uuidv7>`) and `check_create_ids` rejects a hand-written
-id typed (`NotMinted`). Identity is minted; names are data.
-
-So a singleton is **a minted record carrying its natural key as a FIELD, plus an
-indexed query to find it by that key:**
-
-```ts
-export const Platform = aggregate("Platform", {
-  platformId: t.string().merge(Lww),   // the natural key — a FIELD, not the row id
-  namespace: t.string().merge(Lww),
-  // … the rest of the platform's state
-});
-
-export const registerPlatform = directive("registerPlatform").creates(Platform)
-  .payload(z.object({ platformId: z.string().min(1), namespace: z.string().min(1) }))
-  .plan((p) => { create(Platform).set("platformId", p.platformId).set("namespace", p.namespace); return []; });
-//  ^ NO id in the payload — Nomos MINTS it. The typed client mints-when-omitted.
-
-export const platformByPlatformId = query("platformByPlatformId").key("platformId").returns(Platform);
-//  ^ "the singleton" is read by its natural key, O(1) — never by a guessed row id.
-```
-
-The same pattern is how you model `namespaceId`, `providerId`, a config record
-keyed by `name` — each a minted row + a `…By<NaturalKey>` query. If you truly
-want create-or-amend semantics at a caller-owned key (and the natural key IS the
-identity), use `.ensures` above instead — that lane DELIBERATELY addresses a
-derived id and is the ONLY way a non-minted id is lawful.
-
-### Multi-aggregate ensures: `withMarker`
-
-A directive's marker covers its OWN target aggregate only. When the same plan
-also upserts a SECOND aggregate (a sample updating its monthly meter in the
-same intent), tag that aggregate's write explicitly with
-`withMarker(op, "ensures")` — untagged fan-out rides as a mutate of a row
-that may not exist yet:
-
-```ts
-export const recordSample = directive("recordSample").ensures(Sample)
-  .payload(/* … */)
-  .plan((p) => {
-    const s = instance(Sample, sampleId(p));   // the directive's .ensures target
-    const m = instance(Meter, meterId(p));     // the sibling upsert
-    return [
-      set(s, "value", p.value),
-      withMarker(set(m, "month", monthOf(p)), "ensures"), // ONE tagged op marks the whole aggregate's event
-      set(m, "monthToDate", p.monthToDate),
-    ];
-  });
-```
-
-One tagged op per sibling aggregate is enough (conflicting markers for the
-same aggregate refuse at encode, fail-closed). This is exactly how Nomos
-Cloud's own usage tenant folds a reading AND its budget meter in ONE intent —
-so the budget invariant judges both together: a reading that would leave the
-meter over an unacked threshold refuses, and the sample refuses WITH it.
-
-## Roles — sugar over relations (the kernel is the authority)
-
-A `role(...)` is the highest-level authz surface: it LOWERS onto the ONE ReBAC
-spine (relation tuples + the kernel gate). It is pure sugar — there is NO
-role-array membership check anywhere; every capability is a relation tuple the
-kernel judges.
-
-```ts
-import { role, aggregate, t, Lww, requires, directive, create } from "@githolon/dsl";
-
-export const editor = role("editor");                 // .edit / .view refs available immediately
-
-export const Note = aggregate("Note",
-  { author: t.string().merge(Lww), body: t.string().merge(Lww) },
-  { visibility: requires(editor.view) });             // Note is private behind the role's VIEW cap
-
-// EMIT the role's grant/revoke/seed directives + relation schema (auto-discovered by shape):
-export const noteRoles = editor.canEdit(Note).canView(Note).grantableBy("admin").emit();
-
-// Wire the role's EDIT ref onto a mutating directive — only an editor may write:
-export const editNote = directive("editNote")
-  .creates(Note)
-  .payload(z.object({ author: z.string().min(1), body: z.string().min(1) }))
-  .plan((p) => { create(Note).set("author", p.author).set("body", p.body); return []; })
-  .requires(editor.edit);
-```
-
-What `editor…emit()` gives you:
-
-- **Relation schema with TEETH** — the `editorEdit` write relation is authored
-  into the law, so `.requires(editor.edit)` never fails open (the fail-open
-  footgun is closed); `editorView` is a read-visibility cap (wire it as an
-  aggregate `requires(editor.view)`).
-- **Grant / revoke / seed directives** — `grantEditor` / `revokeEditor` seat or
-  remove the role's relation tuple, gated `.requires("admin")` (the kernel judges
-  the granter). `seedEditor` seats the `admin` grant-authority on a founding
-  principal at genesis/birth (ungated seed lane).
-- **Typed policy refs** — `editor.edit` / `editor.view` (never strings) for
-  `.requires(...)` and aggregate visibility.
-- **`canEdit<Agg>` / `canView<Agg>` codegen** (TS + Dart) — UI-hint helpers that
-  mirror the kernel's check over the folded tuples. **INFORMATIONAL only — the one
-  wasm gate is the authority and refuses regardless of what the helper returns.**
-  Use them to grey out a button, never to decide access.
-
-Roles are workspace-scoped (the read-visibility gate is workspace-scoped in the
-kernel). Per-record grants stay available via the lower-level
-`.requires(rel, { objectFrom })` axis. `grantableBy` defaults to `admin`.
-
-## Determinism or death
-
-A plan is a PURE function of its payload. No `Date.now()`, no
-`Math.random()`, no I/O — the sandbox traps them. Timestamps ride IN the
-payload as ISO strings, stamped by the caller. Why so strict: every peer
-re-runs your plan and byte-compares the result; one nondeterministic call and
-admission fails everywhere, forever.
-
-## Declared reads — name them, never scan
-
-- `query("booksByShelf").key("shelf").returns(Book)` — an indexed probe.
-- `count("booksPerShelf").of(Book).by("shelf")` — a maintained O(1) tally.
-- `sum("stockValue", "price").of(Book).by("shelf")` — count's numeric sibling:
-  a maintained running total of an int field; `.where(p => …)` filters, `.by`
-  groups. Never a `SUM(*)` scan.
-- `derived("isLong").of(Book).returns(z.boolean()).as((b) => …)` — a PURE
-  engine-projected read field. Lives only in the read model, never in the
-  ledger, so it is always re-derivable.
-
-Export each at top level; `githolon compile` auto-discovers them by shape and
-routes them into the read manifest so they work at the edge AND in clients.
-After a compile, read `build/<pkg>.summary.txt` — it lists every aggregate,
-directive, query, count, and sum you actually built; if a declared read is
-missing there, it is missing everywhere.
-
-Next: [03-client.md](./03-client.md) — driving it from an app.

package/template/docs/03-client.md

@@ -1,166 +0,0 @@
-# The client
-
-`test/e2e.mts` IS the tutorial — every claim below runs live in it. This page
-is the map.
-
-## connect()
-
-```ts
-import { connect } from "@githolon/client";
-import { todoClient } from "../build/<app>.client.ts";
-
-const holon = await connect({ cloud, workspace, clientId });
-const app = todoClient(holon);
-```
-
-`connect` pulls the wasm, the workspace manifests, and the ledger, then runs
-the byte-identical holon LOCALLY. `clientId` names your session branch
-(`session/<clientId>`) — one per writer. Everything after connect works
-offline; the e2e proves it by trapping `fetch` while it authors and queries.
-
-## The generated client contract
-
-`githolon compile` emits `build/<pkg>.client.ts`: a typed method per directive
-(payload types from the SAME zod the engine validates), a read-model interface
-per aggregate (every field optional — partial folds are normal), typed
-accessors per declared query/count/sum, by-id read and watch helpers, and the
-deployed law's content hash baked in. Zero imports — it binds structurally to
-`connect()`'s holon. If the cloud's law hash differs from the client's, you
-compiled different bytes; recompile rather than wonder.
-
-The raw surface stays underneath: `holon.dispatch(...)`, `holon.query(id,
-params)`, `holon.queryById(id)`, `holon.count(id, group)`, `holon.sum(id,
-group)`. Hover anything in your editor — `@githolon/client` ships full types
-and the semantics live in the doc comments.
-
-## Many workspaces at once (the normal shape)
-
-Everything about Nomos is multi-workspace: a real app holds a dozen+ live
-local workspaces (the user's home, each space, each project). 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 project = projectClient(await realm.workspace("project-…"));`
-  (`connect()` remains the one-workspace sugar over the same machinery.)
-- **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 PlatformClient.bind(platform);
-
-  // A `.births()` directive takes NO parent — the parent IS the session workspace:
-  final birth = await platformClient.birthProjectWorkspace(payload: order);
-  // NomosRef is THE cross-workspace primitive — follow it, bind the next client:
-  final project = await engine.follow(birth.bornRefs.single);
-  final projectClient = await ProjectClient.bind(project);
-  ```
-
-  `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.
-
-## sync()
-
-```ts
-const s = await holon.sync({ admit: true });
-```
-
-One call: push unpushed intents to your session branch, ask the edge to judge
-now, pull canonical main, rebase-replay anything still unacked (intent-id
-deduped — nothing ever double-folds). `s.admission` is `null` when there was
-nothing to push — normal, not an error. Without `{admit: true}` a push still
-lands within ~2s: the edge self-schedules admission. `holon.pull()` converges
-in place on demand; no reconnects, ever.
-
-## watch
-
-`app.watch<Agg>ById(id, (rows) => …)` is a LOCAL reactive read — it fires on
-local folds and on pulls. Render from watches; treat sync as background
-reconciliation, not as the read path.
-
-## Dead letters — refused work is never lost
-
-A DOMAIN rejection (the law couldn't admit it — e.g. its domain isn't deployed
-yet) parks the FULL intent on both sides: `holon.deadLetters()` locally
-(durable — it rides `holon.export()`/restore) and the workspace DLQ in the
-cloud. Ship a law fix through the deploy lane, then `holon.retryDeadLetter(id)`
-— the user's work lands on main. `discardDeadLetter(id)` is the app's explicit
-choice; nothing is silently dropped. Obvious attacks (session-lane law
-intents) are dropped, never queued.
-
-## Two writers, no coordination
-
-The canonical concurrency demo (e2e step 9): two `connect()`s with DIFFERENT
-clientIds tag the same entry offline, blind to each other. Both sync; the
-AddWins union keeps every add. No locks, no "last writer wins the whole
-record", no merge code — the field's declared driver did it
-(see [02-authoring.md](./02-authoring.md)).
-
-## Typed-client patterns (the three gotchas)
-
-Building with the generated typed client (`XClient.bind(session)` — no string
-directive ids), three things trip people up once and never again:
-
-- **Success = `outcome.ok`.** A directive method returns a `NomosOfferOutcome`;
-  `outcome.ok` is true when it committed (a refusal *throws* / surfaces its typed
-  law error, it doesn't return a false outcome). For a `.creates` you also get the
-  minted id back with no query round-trip; for a `.births` you get `outcome.born`.
-- **Timestamps are caller-stamped — pass them.** Payload fields like `createdAt` /
-  `bornAt` are `required` BY DESIGN, not an oversight: a plan is a pure function of
-  its payload and reads no clock (determinism — every peer replays the same bytes).
-  Stamp `DateTime.now().toUtc().toIso8601String()` at the call site. This is the
-  timestamp doctrine, not friction to remove.
-- **Apps hold MANY workspaces open at once — that is the model, not an edge case.**
-  `bridge.session(ws)` returns a live session from the REALM (one engine, N mounted
-  workspaces, LRU park/remount above a budget). A Space AND a Project AND the home
-  are all open concurrently; there is no singleton "current workspace" (that surface
-  would be the bug). See [10-flutter-layering.md](./10-flutter-layering.md).
-- **A cross-workspace `ForeignRef` has TWO read paths — don't confuse them.**
-  `task.space` (a `ForeignRef<SpaceOwnerData>`) is a typed LOCATOR.
-  - **App/presentation read:** `await task.space.resolve(nomos)` / `.watch(nomos)`
-    reads the target THROUGH the open realm — instant when that Space is already a
-    live session (it usually is), a mount otherwise. This is live UI data, not law.
-  - **Law read (a plan's DECISION depends on the foreign fact):** never a live
-    resolve — declare `trustSource` + `.readsFrom(...)` so the fact is CAPTURED onto
-    the intent and re-verified on every replay (the captured-ports / attested-read
-    doctrine, deterministic). `foreignRef` also generates `.attest(nomos)` for that
-    evidence. Separate ledgers mean readability is policy, not a gate-checked FK —
-    see [09-attested-reads.md](./09-attested-reads.md).
-
-## Persistence
-
-`holon.export()` → bytes; `connect({ restoreFrom: bytes })` restores. Pending
-un-synced writes survive an app reload and still sync.
-
-Next: [04-cloud.md](./04-cloud.md) — workspaces, identity, quotas.