create-githolon 0.62.0 → 0.63.0

package/package.json

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

@@ -23,6 +23,45 @@ 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.
 
+## 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