create-githolon 0.101.6 → 0.102.1

package/index.mjs

@@ -17,7 +17,7 @@ var NOMOS_VERSION = (() => {
 var args = process.argv.slice(2);
 if (args.includes("-h") || args.includes("--help")) {
   process.stdout.write(
-    "create-githolon \u2014 scaffold a Nomos business-law package\n\nUsage:\n  npm create githolon <dir>        (or: npx create-githolon <dir>)\n\nScaffolds one aggregate, one business birth, the compile config, and a\none-page explanation into <dir> (default: my-holon-app). The generated\nproof exercises the real local engine.\n\nFlags:\n  --no-git    skip git init\n"
+    "create-githolon \u2014 scaffold a Nomos business-law package\n\nUsage:\n  npm create githolon <dir>        (or: npx create-githolon <dir>)\n\nScaffolds one durable business root, one atomic multi-aggregate intent,\none generated application, and a one-page explanation into <dir>\n(default: my-holon-app). The generated\nproof exercises the real local engine.\n\nFlags:\n  --no-git    skip git init\n"
   );
   process.exit(0);
 }
@@ -40,8 +40,11 @@ if (existsSync(path.join(targetDir, "vscode"))) {
   renameSync(path.join(targetDir, "vscode"), path.join(targetDir, ".vscode"));
 }
 var appHash = `${appName.replace(/[-\s]+/g, "_").replace(/([a-z0-9])([A-Z])/g, "$1_$2").toUpperCase()}_DOMAIN_HASH`;
-var subst = (s) => s.replaceAll("__APP_NAME__", appName).replaceAll("__APP_HASH__", appHash).replaceAll("__NOMOS_VERSION__", NOMOS_VERSION);
-for (const f of ["package.json", "README.md", "nomos.package.mjs", "CLAUDE.md", "domains/todo.ts"]) {
+var appDartName = appName.replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "") || "nomos_app";
+var appClassNameRaw = appName.split(/[^A-Za-z0-9]+/).filter(Boolean).map((part) => part[0].toUpperCase() + part.slice(1)).join("") || "NomosApp";
+var appClassName = /^[A-Za-z_]/.test(appClassNameRaw) ? appClassNameRaw : `App${appClassNameRaw}`;
+var subst = (s) => s.replaceAll("__APP_NAME__", appName).replaceAll("__APP_DART_NAME__", appDartName).replaceAll("__APP_CLASS_NAME__", appClassName).replaceAll("__APP_HASH__", appHash).replaceAll("__NOMOS_VERSION__", NOMOS_VERSION);
+for (const f of ["package.json", "README.md", "nomos.package.mjs", "nomos.application.mjs", "CLAUDE.md", "domains/estate.ts"]) {
   const p = path.join(targetDir, f);
   if (existsSync(p)) writeFileSync(p, subst(readFileSync(p, "utf8")), "utf8");
 }
@@ -64,10 +67,10 @@ Nomos in one page: ${path.join(rel, "README.md")}
 Next:
   cd ${rel}
   npm install
-  npx githolon compile        # law + typed client + generated proof
-  npx githolon proof          # births your model in the real local engine
+  npm run compile             # law + generated business application + proof
+  npm run proof               # drives the business language in the real local engine
 
-The starter exposes one creation idea: app.birth(businessFacts).
+The starter exposes one intent: commissionAsset(businessFacts).
 Identity, authorship, persistence, synchronisation, provenance, and recovery stay underneath it.
 `
 );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-githolon",
-  "version": "0.101.6",
+  "version": "0.102.1",
   "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/CLAUDE.md

@@ -1,13 +1,20 @@
 # __APP_NAME__
 
-This is a Nomos business-law package. Keep application code at the level of aggregates, `birth`, directives, and reads.
+Model the business language. Do not recreate Nomos as application infrastructure.
+
+- Aggregates are continuing business identities, not database rows or immutable snapshots.
+- `birth(...)` gives one root aggregate a durable life.
+- Public application writes are `intent(...)` declarations collected by `language(...)`.
+- Directives are private consequences composed beneath an intent; never expose them as an application CRUD API.
+- One intent may atomically change any number of aggregates.
+- Relationships use `t.ref(Aggregate)` and `idOf(Aggregate)`; generated code carries `NomosRef<Aggregate>`.
+- Pass the generated application through the UI as the sole business state. Do not add repositories, SQLite
+  mirrors, runtime hosts, session providers, custom sync, ID stores, or replacement aggregate versions.
 
 ```bash
-npx githolon check
-npx githolon compile
-npx githolon proof
+npm run compile
+npm run proof
 ```
 
-`check` reports statically provable refusals. `compile` emits the law and typed client. `proof` exercises the generated business path in the real local engine.
-
-Do not introduce application-facing identity, signing, storage, deployment, or recovery ceremonies. They belong beneath the generated `birth(payload)` surface.
+If either command exposes framework implementation machinery, treat that as a Nomos defect rather than
+teaching the application to handle it.

package/template/README.md

@@ -1,59 +1,75 @@
 # __APP_NAME__
 
-Nomos lets you describe a business and leave the compute science to the framework.
+Nomos lets you describe what the business means and leaves the compute science to the framework.
 
-You write three things:
+You write four things:
 
-- aggregates: the business things that exist;
-- birth: the facts required to give one of those things a durable life;
-- directives and reads: what may happen to it and what the application may ask.
+- **aggregates** — business things with one continuing identity;
+- **birth** — the facts required to give a root aggregate its own durable life;
+- **private directives** — the consequences Nomos may apply;
+- **public intents** — the business verbs people and applications actually use.
 
-The starter in [`domains/todo.ts`](domains/todo.ts) gives a todo list its own durable life:
+The starter's public verb is `commissionAsset`. It creates an asset and claims its RFID/QR identity in one
+atomic accepted change:
 
 ```ts
-export const TodoList = aggregate("TodoList", {
-  reference: t.string({ nonempty: true }).fromBirth(),
-  title: t.string({ nonempty: true }).fromBirth(),
-});
-
-export const todoList = birth(TodoList, {
-  key: "reference",
-});
+export const commissionAsset = intent("commissionAsset")
+  .payload(z.object({
+    name: z.string().min(1),
+    rfidQrIdentity: z.string().min(1),
+  }))
+  .directs(createCommissionedAsset, ({ name }) => ({ name }))
+  .directs(claimRfidQrIdentity, ({ rfidQrIdentity }) => ({ value: rfidQrIdentity }))
+  .atomically();
+
+export const estateLanguage = language("estate", [commissionAsset]);
 ```
 
-The generated client exposes the same business idea:
+The generated Flutter application exposes that same language—not its directives:
 
-```ts
-const list = await app.birth({
-  reference: "PERSONAL",
-  title: "Things to do",
-});
+```dart
+final estate = await application.estates.birth(
+  const CreateEstateInput(reference: 'E-001', name: 'Foundry'),
+);
+
+final NomosRef<Asset> asset = await estate.commissionAsset(
+  const CommissionAssetInput(
+    name: 'Main electricity meter',
+    rfidQrIdentity: 'E20034120123456789012345',
+  ),
+);
+
+estate.assets.watchOne(asset).listen(render);
 ```
 
-That is the model. A born aggregate is a holon: its law, facts, and history travel together. It can act locally, survive disconnection, converge with other copies, explain every accepted change, and be reconstructed from its history.
+That is the product surface. `EstateApplication` is the application state. Pass it through the UI; do not
+mirror it in repositories, providers, sessions, caches, SQLite tables, or hand-written sync code.
 
-Nomos owns everything underneath `birth`: durable identity, authorship, law installation, local execution, validation, persistence, synchronisation, provenance, and recovery. Those mechanisms are implementation details, not application design choices.
+`NomosRef<Asset>` is the asset's one identity everywhere. The aggregate is not a database row and an update
+does not create a replacement aggregate: its accepted history changes while its reference stays the same.
+
+Nomos owns everything underneath the intent: identity, authorship, validation, atomicity, persistence,
+synchronisation, conflict retention, provenance, access, schema evolution, recovery, and replay.
 
 The development loop is one path:
 
 ```bash
 npm install
-npx githolon compile
-npx githolon proof
+npm run compile
+npm run proof
 ```
 
-`compile` emits the law, typed client, and a proof generated from this domain. `proof` drives the real engine locally, births the list, discards its resident copy, restores it from durable custody, verifies the full history again, and reads the business root back.
-
-Make it yours by renaming `TodoList` and changing its fields. `.fromBirth()` means the fact is required to
-begin that durable life; its field rule is also the birth validation and generated input type. Nomos derives
-the initial write. Keep the rule: application code supplies business facts; Nomos owns the machinery that
-makes those facts durable and trustworthy.
+`compile` emits the law and generated business application. `proof` drives the same business language in the
+real local engine, discards resident state, restores it from durable custody, verifies its history, and reads
+the business world back.
 
 Useful files:
 
-- [`domains/todo.ts`](domains/todo.ts): the business model;
-- [`nomos.package.mjs`](nomos.package.mjs): the modules compiled into the package;
-- `build/__APP_NAME__.client.ts`: the generated typed client after `compile`;
-- `build/__APP_NAME__.proof.mts`: the generated proof after `compile`.
+- [`domains/estate.ts`](domains/estate.ts): nouns, private consequences, and public language;
+- [`nomos.package.mjs`](nomos.package.mjs): business-law authoring input; it emits a published USD package asset;
+- [`nomos.application.mjs`](nomos.application.mjs): application-composition authoring input; only the emitted `.application.usda` travels;
+- `build/application/__APP_DART_NAME___application/`: the sole Flutter application dependency;
+- `build/__APP_NAME__.proof.mts`: the generated local proof.
 
-If you need to understand distributed systems, cryptography, storage topology, or recovery ceremonies to model the business, that concern has leaked out of Nomos.
+If application code needs to understand workspaces, event sourcing, JWTs, signatures, retries, topology,
+serialization, or merge algorithms, a framework concern has leaked out of Nomos.

package/template/domains/estate.ts

@@ -0,0 +1,64 @@
+/**
+ * __APP_NAME__ — business nouns, one durable life, and one public business verb.
+ *
+ * The directives below describe private consequences. Tenant applications receive only
+ * `commissionAsset`: one intention which changes the business world atomically.
+ */
+import {
+  aggregate,
+  birth,
+  create,
+  directive,
+  intent,
+  language,
+  set,
+  t,
+  z,
+} from "@githolon/dsl";
+
+export const Estate = aggregate("Estate", {
+  reference: t.string({ nonempty: true }).fromBirth(),
+  name: t.string({ nonempty: true }).fromBirth(),
+}).owned();
+
+export const estate = birth(Estate, {
+  key: "reference",
+});
+
+export const Asset = aggregate("Asset", {
+  name: t.string({ nonempty: true }),
+}).owned();
+
+export const RfidQrIdentityClaim = aggregate("RfidQrIdentityClaim", {
+  value: t.string({ nonempty: true }),
+}).public();
+
+/** Private consequence: create the commissioned asset. */
+export const createCommissionedAsset = directive("createCommissionedAsset")
+  .creates(Asset)
+  .payload(z.object({ name: z.string().min(1) }))
+  .plan((facts) => {
+    create(Asset).set("name", facts.name);
+    return [];
+  });
+
+/** Private consequence: reserve the physical identifier in the same accepted change. */
+export const claimRfidQrIdentity = directive("claimRfidQrIdentity")
+  .ensures(RfidQrIdentityClaim)
+  .payload(z.object({ value: z.string().min(1) }))
+  .plan((facts) => [set(RfidQrIdentityClaim, "value", facts.value)]);
+
+/** The application-facing verb: business facts in, one atomic change to the world. */
+export const commissionAsset = intent("commissionAsset")
+  .contract({
+    accepts: z.object({
+      name: z.string().min(1),
+      rfidQrIdentity: z.string().min(1),
+    }),
+  })
+  .directs(createCommissionedAsset, ({ name }) => ({ name }))
+  .directs(claimRfidQrIdentity, ({ rfidQrIdentity }) => ({ value: rfidQrIdentity }))
+  .atomically();
+
+/** This is the complete public language. The two directives above remain implementation. */
+export const estateLanguage = language("estate", [commissionAsset]);

package/template/nomos.application.mjs

@@ -0,0 +1,15 @@
+export default {
+  application: "__APP_NAME__",
+  root: {
+    name: "__APP_CLASS_NAME__",
+    kind: "assembly",
+    children: [{
+      name: "Business",
+      kind: "component",
+      reference: {
+        asset: "./build/__APP_NAME__.asset.usda",
+        prim: "/__APP_CLASS_NAME__Business",
+      },
+    }],
+  },
+};

package/template/nomos.package.mjs

@@ -1,5 +1,15 @@
-// The package is just the business-law modules Nomos should compile.
+// The package is just the business language Nomos should compile.
 export default {
   name: "__APP_NAME__",
-  domains: [{ key: "todo", modules: ["./domains/todo.ts"] }],
+  rootPart: { name: "__APP_CLASS_NAME__Business", kind: "component" },
+  domains: [{ key: "estate", modules: ["./domains/estate.ts"] }],
+  dart: {
+    out: "./build/application",
+    support: "package",
+    packages: {
+      types: "__APP_DART_NAME___business",
+      client: "__APP_DART_NAME___application",
+      test: "__APP_DART_NAME___scenarios",
+    },
+  },
 };

package/template/package.json

@@ -3,18 +3,18 @@
   "version": "0.0.0",
   "private": true,
   "type": "module",
-  "description": "A Nomos business-law package: aggregates, birth, directives, and reads.",
+  "description": "A Nomos business application: public intents over private atomic consequences.",
   "scripts": {
-    "compile": "githolon compile",
+    "compile": "githolon compile ./nomos.package.mjs && githolon compile ./nomos.application.mjs",
     "proof": "githolon proof",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@githolon/dsl": "^__NOMOS_VERSION__",
-    "@githolon/client": "^__NOMOS_VERSION__"
+    "@githolon/dsl": "^__NOMOS_VERSION__"
   },
   "devDependencies": {
     "githolon": "^__NOMOS_VERSION__",
+    "@githolon/testing": "^__NOMOS_VERSION__",
     "@types/node": "^25.9.2",
     "tsx": "^4.19.2",
     "typescript": "^5.6.3"

package/template/tsconfig.json

@@ -11,7 +11,7 @@
   },
   "include": [
     "domains/**/*.ts",
-    "build/*.client.ts",
+    "build/*.client.d.mts",
     "build/*.proof.mts",
     "test/**/*.mts"
   ]

package/template/domains/todo.ts

@@ -1,18 +0,0 @@
-/**
- * __APP_NAME__ — the complete starter model.
- *
- * The app supplies business facts. Nomos gives the aggregate a durable life and owns identity,
- * authorship, local execution, synchronisation, persistence, provenance, and recovery beneath it.
- */
-import { aggregate, birth, t } from "@githolon/dsl";
-
-export const TodoList = aggregate("TodoList", {
-  /** A stable business key the caller already knows. */
-  reference: t.string({ nonempty: true }).fromBirth(),
-  title: t.string({ nonempty: true }).fromBirth(),
-}).owned();
-
-/** The one public creation idea: give a todo list its own durable life. */
-export const todoList = birth(TodoList, {
-  key: "reference",
-});