create-githolon 0.32.0 → 0.34.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-githolon",
-  "version": "0.32.0",
+  "version": "0.34.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,63 @@ 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.
 
+## 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 SiteLocation = valueObject("SiteLocation", {
+  address: PostalAddress.optional(),               // VOs nest in VOs
+  point: GeoPoint.optional(),
+});
+
+export const EstateSite = aggregate("EstateSite", {
+  name: t.string().merge(Lww),
+  location: SiteLocation.field().optional(),       // ONE json-object leaf
+  point: GeoPoint.field().optional(),              // give a geometry its OWN field…
+});
+export const sitesByBounds = spatial("sitesByBounds").of(EstateSite).on("point"); // …to index it
+export const recordSite = directive("recordSite").creates(EstateSite)
+  .payload(z.object({ name: z.string(), location: SiteLocation.zod })) // the SAME zod validates
+  .plan((p) => { create(EstateSite).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.
+
 ## Merge drivers ARE the conflict policy
 
 | driver | concurrent writes to the same field… |