create-githolon 0.65.1 → 0.66.0

package/package.json

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

@@ -119,6 +119,41 @@ as an aggregate. A `z.enum` field generates a REAL Dart enum
 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 CatalogueListingContract = contract("CatalogueListing", {
+  listingId: t.string(),
+  name: t.string(),
+});
+
+// catalogue.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 CatalogueListing = aggregate("CatalogueListing", {
+  listingId: t.string().merge(Lww),
+  name: t.string().merge(Lww),
+  internalNotes: t.string().merge(Lww),      // not in the contract — behind the boundary
+}).implements(CatalogueListingContract);
+
+// estate.ts — reference the CONTRACT, never the concrete aggregate
+export const EstateAsset = aggregate("EstateAsset", {
+  catalogueWorkspaceName: t.string().merge(Lww),
+  listing: t.foreignRef({ workspace: "catalogueWorkspaceName", target: CatalogueListingContract, domain: "catalogue" }),
+});
+```
+
+The generated client types the reference as `ForeignRef<CatalogueListingContract>`;
+the Dart DTO class lives in a shared `contracts.dart` every domain imports, so `estate`
+never imports `catalogue`'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.
+
 ## Merge drivers ARE the conflict policy
 
 | driver | concurrent writes to the same field… |