@githolon/dsl 0.66.0 → 0.68.0

package/src/compile_package_main.ts

@@ -56,6 +56,8 @@ import type { AggregateHandle } from "./aggregate.js";
 import {
   generateDartDomain,
   generateDartContracts,
+  generateDartActivityRegistry,
+  collectActivityDescriptors,
   type DartImport,
   type DartRefImport,
   type DomainModule,
@@ -428,6 +430,8 @@ const DART_SUPPORT_CORE_SRC = [
   // The foreign-ref locator runtime (ForeignRef<T>/NomosForeignReader/…, t.foreignRef) — a generated read
   // model with a `t.foreignRef` field references `ForeignRef<Target>` through the barrel, so it must vendor.
   "foreign_ref.dart",
+  "activity.dart",
+  "nomos_ref.dart",
 ] as const;
 // The RUNTIME support files, vendored from `nomos_client` (dsl/dart/lib/src): the async WebView
 // bridge the generated `<name>.client.dart` drives, and the provider surface. Their
@@ -450,6 +454,10 @@ const FRAMEWORK_FILE = "nomos_framework";
 /** The shared basename of the domain-contracts DTO file emitted once per package (domain_contracts.md). */
 const CONTRACTS_FILE = "contracts";
 
+/** The shared basename of the ACTIVITY REGISTRY file emitted once per package (activity_descriptors.md).
+ *  Absent when no directive declares `.activity(...)` — an activity-free package emits no `activity_registry.dart`. */
+const ACTIVITY_FILE = "activity_registry";
+
 /** Collect every domain contract across the package's modules, deduped by id (later-wins). Sorted by id.
  *  Empty when no domain declares a contract (contract-free packages emit no `contracts.dart`). */
 function collectPackageContracts(modules: readonly DomainModule[]): ContractHandle[] {
@@ -731,6 +739,14 @@ function emitDart(
   if (packageContracts.length > 0) {
     writeGenerated(CONTRACTS_FILE, generateDartContracts(packageContracts));
   }
+  // 2a-ter. the shared ACTIVITY REGISTRY (`activity_registry.dart`) — the pure `renderActivity`, ONCE. Emitted
+  //         iff a directive opts in via `.activity(...)` (activity-free packages stay byte-identical). Pure
+  //         (nomos_types), so the client folds typed activity rows from the intent log with no runtime import.
+  const packageActivity = collectActivityDescriptors(modules);
+  const activityImportUri = packageActivity.length > 0 ? `${ACTIVITY_FILE}.dart` : undefined;
+  if (packageActivity.length > 0) {
+    writeGenerated(ACTIVITY_FILE, generateDartActivityRegistry(packageActivity));
+  }
   // CROSS-DOMAIN `t.foreignRef` (auto import). A foreignRef field typed `ForeignRef<CatalogueListing>` +
   // `CatalogueListing.fromJson` needs the TARGET aggregate's Dart class — which lives in the target DOMAIN's
   // generated file. Within ONE package the compiler knows which domain owns each aggregate, so we auto-emit
@@ -794,6 +810,7 @@ function emitDart(
       ...(compat !== undefined ? { compat } : {}),
       supportImport,
       ...(domainFrameworkImport !== undefined ? { frameworkImportUri: domainFrameworkImport } : {}),
+      ...(packageActivity.length > 0 ? { emitActivity: true, ...(activityImportUri !== undefined ? { activityImportUri } : {}) } : {}),
     });
     const cp = path.join(genDir, `${mod.name}.client.dart`);
     writeFileSync(cp, clientSrc, "utf8");
@@ -820,6 +837,7 @@ function emitDart(
       : `export 'package:nomos_client/nomos_client.dart';`,
     ...(hasFrameworkSymbols ? [`export '${genRel}/${FRAMEWORK_FILE}.dart';`] : []),
     ...(contractsImportUri !== undefined ? [`export '${genRel}/${CONTRACTS_FILE}.dart';`] : []),
+    ...(activityImportUri !== undefined ? [`export '${genRel}/${ACTIVITY_FILE}.dart';`] : []),
     ...modules.flatMap((m) => [
       `export '${genRel}/${m.name}.dart';`,
       `export '${genRel}/${m.name}.client.dart';`,
@@ -844,8 +862,10 @@ function emitDart(
 /** The pure-core support import generated TYPES files carry in layered-packages mode. */
 const DART_TYPES_IMPORT = `import 'package:nomos_types/nomos_types.dart';`;
 /** Version constraints the scaffolded pubspecs pin — move together with the Dart packages' releases. */
-const NOMOS_TYPES_DEP = "^0.1.0";
-const NOMOS_CLIENT_DEP = "^0.38.0";
+// FLOOR = the release carrying every symbol generated code may reference (0.1.3: NomosRef).
+const NOMOS_TYPES_DEP = "^0.1.3";
+// FLOOR = the release carrying the bridge methods generated clients call (0.45.0: offerOutcome/NomosCreated.ref).
+const NOMOS_CLIENT_DEP = "^0.45.0";
 
 const isPubPackageName = (s: string): boolean => /^[a-z][a-z0-9_]*$/.test(s);
 
@@ -960,7 +980,7 @@ function emitDartPackages(
   // field as the target aggregate's class, which lives in the target domain's file). A sibling types file is
   // still PURE (no runtime/bridge surface — the purity gate exists to keep nomos_client out, not to isolate
   // domain files from each other; Dart allows type-import cycles for mutual refs).
-  const siblingTypeFiles = new Set<string>([...modules.map((m) => `${m.name}.dart`), `${FRAMEWORK_FILE}.dart`, `${CONTRACTS_FILE}.dart`]);
+  const siblingTypeFiles = new Set<string>([...modules.map((m) => `${m.name}.dart`), `${FRAMEWORK_FILE}.dart`, `${CONTRACTS_FILE}.dart`, `${ACTIVITY_FILE}.dart`]);
   const writeTypes = (fileBase: string, src: string): void => {
     if (!src.includes(DART_PACKAGE_IMPORT)) {
       fail(`generated Dart for '${fileBase}' does not carry the expected support import — codegen_dart header drifted`);
@@ -994,6 +1014,10 @@ function emitDartPackages(
   const packageContracts = collectPackageContracts(modules);
   const contractsImportUri = packageContracts.length > 0 ? `${CONTRACTS_FILE}.dart` : undefined;
   if (packageContracts.length > 0) writeTypes(CONTRACTS_FILE, generateDartContracts(packageContracts));
+  // ACTIVITY REGISTRY (layered): the pure `renderActivity` in the TYPES package (nomos_types only). The
+  // client resolves it through the types-package barrel (which re-exports every types file). Opt-in only.
+  const packageActivity = collectActivityDescriptors(modules);
+  if (packageActivity.length > 0) writeTypes(ACTIVITY_FILE, generateDartActivityRegistry(packageActivity));
   // CROSS-DOMAIN foreignRef (layered): map aggregate id → its domain's type file, so a foreignRef field's
   // target class resolves via a sibling import (the purity gate now permits sibling type files).
   const aggIdToTypeFile = new Map<string, string>();
@@ -1085,6 +1109,7 @@ function emitDartPackages(
       ...(compat !== undefined ? { compat } : {}),
       supportImport: "package",
       typesImportUri,
+      ...(packageActivity.length > 0 ? { emitActivity: true } : {}),
     });
     const cp = path.join(clientGen, `${mod.name}.client.dart`);
     writeFileSync(cp, clientSrc, "utf8");

package/src/directive.ts

@@ -23,6 +23,7 @@ import type { Ports } from "./ctx.js";
 import type { CertifiedReadDecl } from "./certified_read.js";
 import type { RelationDecl } from "./relation.js";
 import type { QueryDecl } from "./query.js";
+import { normalizeActivity, type ActivityInput, type ActivityDescriptor } from "./activity.js";
 import { BIRTH_METER_QUERIES } from "./birth_meter.js";
 import {
   isFromPayloadRef,
@@ -115,6 +116,15 @@ export interface Directive<P = unknown> {
    * byte-identical in the canonical manifest to before `description` existed).
    */
   readonly description?: string;
+  /**
+   * OPT-IN user-facing ACTIVITY metadata (`architecture/activity_descriptors.md`) — the kind/title/message
+   * template, refs, params, category/icon/severity a client uses to render a typed activity row from this
+   * directive's intents (no string-enricher). Set by `.activity({...})`; NON-LAW, additive (same class as
+   * `description` — a directive that never declares activity is byte-identical). Normalized + validated at
+   * author time. `undefined` ⇒ this directive contributes no activity row. (The setter is `.activity({...})`;
+   * this stored field is `activityDescriptor` to avoid a method/field name clash on `RequirableDirective`.)
+   */
+  readonly activityDescriptor?: ActivityDescriptor;
   /**
    * NATIVE ZANZIBAR write-authz (P4): the RELATION the captured author must HOLD to author this
    * directive, and the OBJECT it is checked on. The ONE gate runs `engine.check(schema, object,
@@ -414,6 +424,14 @@ export interface RequirableDirective<P> extends Directive<P> {
    * calls this declares no prose (codegen falls back to a default derived from the id).
    */
   doc(description: string): RequirableDirective<P>;
+  /**
+   * Declare OPT-IN user-facing ACTIVITY metadata (`architecture/activity_descriptors.md`) — a stable `kind`,
+   * a `{actor}`+params message template, navigation `refs`, display `params` (payload field paths), and
+   * category/icon/severity. Codegen emits a typed activity descriptor + `renderActivity` so a client folds
+   * typed activity rows from the intent log (no string-enricher). Validated at author time (unknown template
+   * var / missing payload field refuse). Non-law, additive; a directive that never calls it is byte-identical.
+   */
+  activity(input: ActivityInput): RequirableDirective<P>;
   /**
    * Declare the directive's CertifiedReads (survival Constraint 5; `certified_read.md`
    * §"Tenant authoring") — the profiled, named write-path reads its `decide()` consults, the
@@ -810,6 +828,16 @@ function makeRequirable<P>(base: Directive<P>): RequirableDirective<P> {
     doc(description: string): RequirableDirective<P> {
       return makeRequirable({ ...base, description });
     },
+    activity(input: ActivityInput): RequirableDirective<P> {
+      // Normalize + validate against this directive's payload (unknown template var / missing payload field
+      // refuse here). "@created" refs are checked against the aggregates this directive CREATES (the primary
+      // .creates target + any .alsoCreates). Non-law, additive — stored like `description`.
+      const createdIds = [
+        ...(base.marker === "creates" ? [base.aggregateId] : []),
+        ...(base.secondaryOutputs ?? []).filter((o) => o.marker === "creates").map((o) => o.aggregateId),
+      ];
+      return makeRequirable({ ...base, activityDescriptor: normalizeActivity(base.id, input, base.payloadSchema, createdIds) });
+    },
     readsCertified(reads: Record<string, CertifiedReadDecl>): RequirableDirective<P> {
       // Accumulate onto any prior declared CertifiedReads (a repeated local name's later decl
       // wins) — additive, non-destructive. The local binding NAME (the key) is what `decide`

package/src/index.ts

@@ -136,6 +136,7 @@ export {
 // surface). The dev never sees a "prim" — that is the GitHolon's internal OpenUSD IR.
 export { create, existing, ensure, type AggregateRef } from "./authoring.js";
 export { contract, isContractHandle, satisfiesContract, type ContractHandle, type ContractField, type ContractSatisfaction } from "./contract.js";
+export { normalizeActivity, renderActivityTemplate, activityKey, type ActivityInput, type ActivityDescriptor, type ActivityRefInput, type ActivitySeverity } from "./activity.js";
 // THE CAPTURED READ — a plan reads O(1) DSL queries via `read(query, args)`; the result is committed as
 // the intent's read footprint (deterministic replay + stale-premise detection). The dev calls typed DSL
 // queries; the library routes them here. The host capability is `nomos.read` (twin of `nomos.rng`).