@githolon/dsl 0.1.3 → 0.2.0

package/LICENSE.md

@@ -24,6 +24,15 @@ with it; we keep the rest for now.
 - offer the Nomos runtime, or anything materially similar, as a hosted service;
 - reverse-engineer the holon wasm runtime.
 
+## Data retention
+
+This is a pre-release we are actively evaluating. Workspaces you retire stop
+counting toward your quota but are NOT deleted: **we retain all workspace data
+(ledgers, law, intents) and may examine it to evaluate how the product is
+used.** Don't put anything in a pre-release workspace you wouldn't want the
+builders to read. If you need something truly expunged, ask:
+jack@captainapp.co.uk.
+
 ## The rest
 
 Provided **as is**, with no warranty of any kind; to the maximum extent

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "type": "module",
   "description": "Nomos 2 domain-authoring DSL: aggregates + directives in TS, executed and encoded to the Rust kernel's wire shapes.",
   "license": "SEE LICENSE IN LICENSE.md",

package/src/codegen_ts.ts

@@ -18,7 +18,9 @@
  *   * a PAYLOAD TYPE per directive — derived from the SAME zod schema the sealed
  *     engine validates (recursive zod→TS: enums become literal unions, `.optional()`
  *     becomes `?`, `.int()` stays `number`), so a payload the type system accepts is
- *     a payload the engine accepts;
+ *     a payload the engine accepts; required string fields named `…At` are
+ *     CALLER-STAMPED TIMESTAMPS — optional in the type, auto-filled with ISO now()
+ *     at dispatch (see {@link autoStampFields});
  *   * a READ-MODEL interface per aggregate — derived from the DSL `Field` kinds the
  *     projection decodes by (set→`T[]`, map→`Record<string, V>` via `mapValueKind`,
  *     `t.jsonObject()`→`Record<string, unknown>`, plain `t.json()`→`unknown`), with
@@ -45,10 +47,21 @@ import type { DerivedDecl } from "./derived.js";
 import type { CombinedDecl } from "./combined.js";
 
 const cap = (s: string) => (s.length ? s[0]!.toUpperCase() + s.slice(1) : s);
-const camel = (s: string) => s.replace(/[_-]+(\w)/g, (_m, c: string) => c.toUpperCase());
+const camel = (s: string) => s.replace(/[_\s-]+(\w)/g, (_m, c: string) => c.toUpperCase());
 const lcFirst = (s: string) => (s.length ? s[0]!.toLowerCase() + s.slice(1) : s);
 const upperSnake = (s: string) => s.replace(/[-\s]+/g, "_").replace(/([a-z0-9])([A-Z])/g, "$1_$2").toUpperCase();
 
+// ── NAME NORMALIZATION (no naming convention to learn) ────────────────────────────
+// `nomos.package.mjs` names and domain keys may be ANY string — kebab-case,
+// snake_case, space-separated, PascalCase. Artifact FILENAMES keep the raw name
+// verbatim; generated SYMBOLS normalize it:
+
+/** `tool-library` / `tool_library` / `Tool Library` → `toolLibraryClient` — the factory symbol. */
+export const tsClientFactoryName = (domain: string): string => `${lcFirst(camel(domain))}Client`;
+
+/** `tool-library` / `tool_library` / `Tool Library` → `TOOL_LIBRARY_DOMAIN_HASH` — the hash const. */
+export const tsHashConstName = (packageName: string): string => `${upperSnake(packageName)}_DOMAIN_HASH`;
+
 // ── zod → TS (the same `_def ?? def` convention as codegen_dart's walker) ─────────
 
 type ZodInternalDef = {
@@ -151,6 +164,44 @@ function tsTypeOfZod(zt: z.ZodTypeAny, indent: string): string {
   }
 }
 
+// ── caller-side clock sugar (the `…At` payload convention) ────────────────────────
+
+/**
+ * Top-level REQUIRED string payload fields named `…At` (`signedAt`, `updatedAt`,
+ * `stampedAt`, …) are CALLER-STAMPED TIMESTAMPS by convention: the generated client
+ * fills an omitted one with `new Date().toISOString()` at dispatch. The stamp rides
+ * IN the payload — the plan stays a pure function of `(payload, ports)` and replays
+ * byte-identical on every peer — so the domain dev stops thinking about clocks.
+ * Passing the field explicitly always wins (scheduling-shaped fields like
+ * `expiresAt` should be passed explicitly — "now" is only the DEFAULT).
+ */
+function autoStampFields(schema: z.ZodTypeAny): string[] {
+  if (zodKind(schema) !== "object") return [];
+  const out: string[] = [];
+  for (const [name, f] of Object.entries(zodObjectShape(schema))) {
+    // required-only: `.optional()`/`.default()` wrappers change the zod kind, so they skip.
+    if (name.length > 2 && name.endsWith("At") && zodKind(f as z.ZodTypeAny) === "string") out.push(name);
+  }
+  return out;
+}
+
+/** The payload type text, with auto-stamped fields surfaced as optional (`?`). */
+function tsTypeOfPayload(schema: z.ZodTypeAny, autoStamped: readonly string[]): string {
+  if (zodKind(schema) !== "object" || autoStamped.length === 0) return tsTypeOfZod(schema, "");
+  const stamped = new Set(autoStamped);
+  const fields = Object.entries(zodObjectShape(schema)).map(([name, raw]) => {
+    let f = raw as z.ZodTypeAny;
+    let optional = stamped.has(name);
+    while (zodKind(f) === "optional" || zodKind(f) === "default") {
+      optional = true;
+      f = zodDef(f).innerType!;
+    }
+    const note = stamped.has(name) ? " // auto-stamped with ISO now() at dispatch when omitted" : "";
+    return `  ${name}${optional ? "?" : ""}: ${tsTypeOfZod(f, "  ")};${note}`;
+  });
+  return fields.length ? `{\n${fields.join("\n")}\n}` : "Record<string, never>";
+}
+
 // ── DSL Field → read-model TS type (the projection's decode surface) ──────────────
 
 function tsTypeOfField(field: Field): string {
@@ -214,7 +265,7 @@ export interface TsClientOptions {
 }
 
 export function generateTsClient(modules: readonly DomainModule[], opts: TsClientOptions): string {
-  const hashConst = `${upperSnake(opts.packageName)}_DOMAIN_HASH`;
+  const hashConst = tsHashConstName(opts.packageName);
   const out: string[] = [];
   out.push(
     `// AUTO-GENERATED by nomos-compile — typed TS client for package "${opts.packageName}".`,
@@ -222,9 +273,9 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     `// exposing the @githolon/client surface (the structural NomosHolon below), e.g.`,
     `//`,
     `//   import { connect } from "@githolon/client";`,
-    `//   import { ${lcFirst(camel(modules[0]?.domain ?? "domain"))}Client } from "./build/${opts.packageName}.client.js";`,
+    `//   import { ${tsClientFactoryName(modules[0]?.domain ?? "domain")} } from "./build/${opts.packageName}.client.js";`,
     `//   const holon = await connect({ cloud, workspace, clientId });`,
-    `//   const app = ${lcFirst(camel(modules[0]?.domain ?? "domain"))}Client(holon);`,
+    `//   const app = ${tsClientFactoryName(modules[0]?.domain ?? "domain")}(holon);`,
     ``,
     `/** sha256 of the deployed \`.package.usda\` — the installed law this client dispatches under. */`,
     `export const ${hashConst} = ${JSON.stringify(opts.domainHash)};`,
@@ -250,6 +301,28 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
     ``,
   );
 
+  const anyAutoStamp = modules.some((mod) =>
+    (mod.directives as Directive<unknown>[]).some(
+      (d) =>
+        d &&
+        typeof (d as { payloadSchema?: unknown }).payloadSchema === "object" &&
+        autoStampFields((d as unknown as { payloadSchema: z.ZodTypeAny }).payloadSchema).length > 0,
+    ),
+  );
+  if (anyAutoStamp) {
+    out.push(
+      `/** Caller-side clock sugar: fill omitted \`…At\` timestamp payload fields with ISO now().`,
+      ` *  The stamp rides IN the payload, so plans stay pure and replay byte-identical. */`,
+      `const stampNow = <T extends object>(payload: T, fields: string[]): T => {`,
+      `  const now = new Date().toISOString();`,
+      `  const out = { ...payload } as Record<string, unknown>;`,
+      `  for (const f of fields) if (out[f] === undefined) out[f] = now;`,
+      `  return out as T;`,
+      `};`,
+      ``,
+    );
+  }
+
   // ── read models: one interface per aggregate wire type (deduped), deriveds/combineds merged ──
   const aggByType = new Map<string, AggregateHandle>();
   const extrasByType = new Map<string, string[]>();
@@ -291,14 +364,17 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
       if (usedPayloadNames.has(payloadName)) payloadName = `${cap(camel(domain))}${cap(d.id)}Payload`;
       usedPayloadNames.add(payloadName);
       const schema = (d as unknown as { payloadSchema: z.ZodTypeAny }).payloadSchema;
+      const stamps = autoStampFields(schema);
       out.push(
-        `/** \`${domain}/${d.id}\` payload (mirrors the engine's zod schema). */`,
-        `export type ${payloadName} = ${tsTypeOfZod(schema, "")};`,
+        `/** \`${domain}/${d.id}\` payload (mirrors the engine's zod schema).${stamps.length ? ` Omitted ${stamps.map((s) => `\`${s}\``).join("/")} auto-stamp(s) ISO now() at dispatch.` : ""} */`,
+        `export type ${payloadName} = ${tsTypeOfPayload(schema, stamps)};`,
         ``,
       );
       methods.push(
         `    /** Author \`${domain}/${d.id}\` locally under the installed law; returns the new local head. */`,
-        `    ${d.id}: (payload: ${payloadName}) => holon.dispatch(${JSON.stringify(domain)}, ${JSON.stringify(d.id)}, payload, { domainHash }),`,
+        stamps.length
+          ? `    ${d.id}: (payload: ${payloadName}) => holon.dispatch(${JSON.stringify(domain)}, ${JSON.stringify(d.id)}, stampNow(payload, ${JSON.stringify(stamps)}), { domainHash }),`
+          : `    ${d.id}: (payload: ${payloadName}) => holon.dispatch(${JSON.stringify(domain)}, ${JSON.stringify(d.id)}, payload, { domainHash }),`,
       );
     }
 
@@ -350,7 +426,7 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
 
     out.push(
       `/** Typed client for the \`${domain}\` domain, bound to a connected holon. */`,
-      `export function ${lcFirst(camel(domain))}Client(holon: NomosHolon, domainHash: string = ${hashConst}) {`,
+      `export function ${tsClientFactoryName(domain)}(holon: NomosHolon, domainHash: string = ${hashConst}) {`,
       `  return {`,
       `    domain: ${JSON.stringify(domain)} as const,`,
       `    domainHash,`,

package/src/compile_package_main.ts

@@ -69,7 +69,7 @@ import {
   writeIdentity,
   type Mod,
 } from "./build_package.js";
-import { generateTsClient } from "./codegen_ts.js";
+import { generateTsClient, tsClientFactoryName } from "./codegen_ts.js";
 
 const DSL_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 
@@ -288,7 +288,12 @@ async function main(): Promise<void> {
   if (!cfg || typeof cfg.name !== "string" || !Array.isArray(cfg.domains) || cfg.domains.length === 0) {
     fail(`config must default-export { name, domains: [{ key, modules }, ...] }`);
   }
-  if (!/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(cfg.name)) fail(`package name '${cfg.name}' is not a safe basename`);
+  // ANY readable name works ("tool-library", "tool_library", "Tool Library"):
+  // artifact FILENAMES keep it verbatim; generated SYMBOLS normalize it
+  // (toolLibraryClient, TOOL_LIBRARY_DOMAIN_HASH — see codegen_ts.ts).
+  if (!/^[A-Za-z0-9][A-Za-z0-9 ._-]*$/.test(cfg.name)) {
+    fail(`package name '${cfg.name}' is not a safe basename (letters, digits, spaces, '.', '-', '_')`);
+  }
 
   const outDir = path.resolve(cfgDir, cfg.outDir ?? "build");
   mkdirSync(outDir, { recursive: true });
@@ -477,7 +482,7 @@ async function main(): Promise<void> {
       `  queries: ${d.queries.join(", ") || "—"}   counts: ${d.counts.join(", ") || "—"}`,
     ]),
     `deploy: POST ${cfg.name}.deploy.json to /v1/workspaces/<ws>/domains (or: githolon deploy <ws>)`,
-    `typed client: ${cfg.name}.client.ts — ${cfg.name}Client(holon), law hash baked in`,
+    `typed client: ${cfg.name}.client.ts — ${tsClientFactoryName(domainModules[0]?.domain ?? domainModules[0]?.name ?? cfg.name)}(holon), law hash baked in`,
     ``,
   ].join("\n");
   writeFileSync(path.join(outDir, `${cfg.name}.summary.txt`), summaryTxt, "utf8");
@@ -519,9 +524,10 @@ async function main(): Promise<void> {
   console.log(`  deploy     ${rel(deployPath)}`);
   console.log(``);
   console.log(`deploy (Nomos Cloud):`);
-  console.log(`  curl -X POST -H 'content-type: application/json' \\`);
-  console.log(`    --data-binary @${rel(deployPath)} \\`);
-  console.log(`    https://nomos.captainapp.co.uk/v1/workspaces/<ws>/domains`);
+  console.log(`  githolon ws create <ws> && githolon deploy <ws>   # the secret is saved + sent for you`);
+  console.log(`  # raw lane: curl -X POST -H 'content-type: application/json' -H 'Authorization: Bearer <workspaceSecret>' \\`);
+  console.log(`  #   --data-binary @${rel(deployPath)} https://nomos.captainapp.co.uk/v1/workspaces/<ws>/domains`);
+  console.log(`prove it: npm run e2e   # offline write -> sync -> admission -> cloud query, live`);
 }
 
 await main();

package/src/index.ts

@@ -6,6 +6,9 @@
 // If a file isn't this / hosting this / authoring for this / proving this — it's gone.
 
 /** `@githolon/dsl` — the Nomos 2 domain-authoring DSL. */
+// ONE import for a domain file: `z` (payload schemas) rides along with the DSL, so
+// authors never juggle a separate zod dependency (or risk a second zod instance).
+export { z } from "zod";
 export {
   aggregate,
   instance,