create-githolon 0.94.0 → 0.95.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-githolon",
-  "version": "0.94.0",
+  "version": "0.95.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

@@ -24,6 +24,19 @@ 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

package/template/docs/03-client.md

@@ -127,6 +127,37 @@ 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