@githolon/dsl 0.66.0 → 0.68.0

package/src/activity.ts

@@ -0,0 +1,197 @@
+// NOMOS — DIRECTIVE ACTIVITY DESCRIPTORS (architecture/activity_descriptors.md). A directive OPT-IN declares
+// its own user-facing activity metadata, so a client can fold typed activity rows straight from the intent
+// log — no string-enricher guessing meaning beside the truth. The kernel/ledger stays the audit truth; this
+// is a pure CLIENT-SIDE human projection, declared where the event semantics live.
+//
+//   directive("createSite").creates(EstateSite).payload(SitePayload)
+//     .activity({
+//       kind: "site.created",                       // STABLE event id (seeds the i18n keys)
+//       title: "Created site",
+//       message: "{actor} created {siteName}",       // {actor} + declared params
+//       category: "estate", icon: "add_location", severity: "info",
+//       refs: { site: { type: EstateSite, from: "siteId" } },   // navigation target (type + payload path)
+//       params: { siteName: "name" },                // display value ← payload field path
+//     })
+//
+// NON-LAW, additive metadata (same class as `.doc()`): a directive that never calls `.activity()` is
+// byte-identical in the canonical manifest.
+import { z } from "zod";
+import type { AggregateHandle } from "./aggregate.js";
+import { isContractHandle, type ContractHandle } from "./contract.js";
+
+/** How prominent an activity row is — a declared default the app may style/threshold on. */
+export type ActivitySeverity = "info" | "success" | "warning" | "critical";
+
+/** A declared navigation target: the referenced aggregate/contract TYPE + the payload field path holding its
+ *  id. Replaces the enricher's blind id-probing — the reference is declared, not guessed. */
+export interface ActivityRefInput {
+  /** The target type — an aggregate handle or a `contract(...)` (reuse contracts for the nav target). */
+  readonly type: AggregateHandle | ContractHandle;
+  /** The payload field path holding the target's id (dotted for nested, e.g. `"location.siteId"`), OR the
+   *  sentinel `"@created"` — the id the LAW MINTED for this intent's created aggregate of `type` (read from
+   *  the sealed Create events at render time; the fix for "a .creates payload carries no id"). */
+  readonly from: string;
+}
+
+/** The `.activity({...})` input (declarative — field PATHS, never functions, so it generates to Dart too). */
+export interface ActivityInput {
+  /** STABLE event id (e.g. `"site.created"`) — the wire kind + the seed for the i18n keys. */
+  readonly kind: string;
+  /** Default (English) title; falls back to `kind` if omitted. */
+  readonly title?: string;
+  /** Message template — `{actor}` + any declared `params` name in braces (e.g. `"{actor} created {siteName}"`). */
+  readonly message: string;
+  /** Optional grouping category (e.g. `"estate"`). */
+  readonly category?: string;
+  /** Optional default icon token (app-interpreted). */
+  readonly icon?: string;
+  /** Row prominence (default `"info"`). */
+  readonly severity?: ActivitySeverity;
+  /** Navigation targets: name → { target type, payload path to its id }. */
+  readonly refs?: Record<string, ActivityRefInput>;
+  /** Display values: template-param name → payload field path (dotted ok). */
+  readonly params?: Record<string, string>;
+}
+
+/** The NORMALIZED, serializable descriptor stored on the directive + emitted to codegen/IR. */
+export interface ActivityDescriptor {
+  readonly kind: string;
+  readonly title: string;
+  readonly message: string;
+  readonly category?: string;
+  readonly icon?: string;
+  readonly severity: ActivitySeverity;
+  /** Refs sorted by name; `type` is the target's wire id (a string). */
+  readonly refs: readonly { readonly name: string; readonly type: string; readonly from: string }[];
+  /** Params sorted by name. */
+  readonly params: readonly { readonly name: string; readonly from: string }[];
+  /** Stable i18n keys derived from `kind` (`activity.<kind>.title` / `.message`). */
+  readonly titleKey: string;
+  readonly messageKey: string;
+}
+
+const SEVERITIES: ReadonlySet<string> = new Set(["info", "success", "warning", "critical"]);
+
+/** The i18n key for a `kind` + slot — stable, derived (never hand-authored). */
+export function activityKey(kind: string, slot: "title" | "message"): string {
+  return `activity.${kind}.${slot}`;
+}
+
+/** Interpolate `{name}` placeholders in a template from `vars` (a missing var renders as the empty string —
+ *  the compile-time validator already guarantees every placeholder is declared, so this is defensive only).
+ *  The ONE render helper shared by the TS + Dart renderers (each reimplements the same trivial substitution). */
+export function renderActivityTemplate(template: string, vars: Record<string, string>): string {
+  return template.replace(/\{([a-zA-Z0-9_]+)\}/g, (_m, name: string) => vars[name] ?? "");
+}
+
+/** The `{placeholder}` names referenced by a template. */
+function templateVars(template: string): string[] {
+  const out: string[] = [];
+  for (const m of template.matchAll(/\{([a-zA-Z0-9_]+)\}/g)) out.push(m[1]!);
+  return out;
+}
+
+/** Top-level payload field names (best-effort — a plain `z.object`); `undefined` when the schema isn't a
+ *  destructurable object (validation of `from` roots is then skipped, staying permissive). */
+function payloadFieldNames(schema: unknown): Set<string> | undefined {
+  const def = (schema as { _def?: { shape?: unknown }; def?: { shape?: unknown } })?._def
+    ?? (schema as { def?: { shape?: unknown } })?.def;
+  const shape = (def as { shape?: unknown })?.shape;
+  const resolved = typeof shape === "function" ? (shape as () => Record<string, unknown>)() : shape;
+  if (resolved === undefined || resolved === null || typeof resolved !== "object") return undefined;
+  return new Set(Object.keys(resolved as Record<string, unknown>));
+}
+
+/**
+ * Validate + normalize an `.activity({...})` input at author time (throws a typed error naming the problem).
+ * Checks: `kind`/`message` non-empty; `severity` valid; every message/title `{placeholder}` is `actor` or a
+ * declared param; every ref/param `from` ROOT names a real payload field (when the payload shape is
+ * introspectable). Returns the serializable {@link ActivityDescriptor}. Pure.
+ */
+export function normalizeActivity(
+  directiveId: string,
+  input: ActivityInput,
+  payloadSchema?: unknown,
+  createdAggregateIds?: readonly string[],
+): ActivityDescriptor {
+  const where = `directive '${directiveId}' .activity(...)`;
+  if (typeof input.kind !== "string" || input.kind.trim().length === 0) {
+    throw new Error(`${where}: 'kind' must be a non-empty stable string (e.g. "site.created").`);
+  }
+  if (typeof input.message !== "string" || input.message.trim().length === 0) {
+    throw new Error(`${where}: 'message' must be a non-empty template string.`);
+  }
+  const severity = input.severity ?? "info";
+  if (!SEVERITIES.has(severity)) {
+    throw new Error(`${where}: 'severity' must be one of info|success|warning|critical (got '${severity}').`);
+  }
+  const params = Object.entries(input.params ?? {}).map(([name, from]) => {
+    if (typeof from !== "string" || from.length === 0) {
+      throw new Error(`${where}: param '${name}' must map to a payload field path string.`);
+    }
+    return { name, from };
+  });
+  const paramNames = new Set(params.map((p) => p.name));
+  // Every {placeholder} must be `actor` or a declared param — an undeclared var is a typo, refuse it.
+  for (const tmpl of [input.title ?? "", input.message]) {
+    for (const v of templateVars(tmpl)) {
+      if (v !== "actor" && !paramNames.has(v)) {
+        throw new Error(
+          `${where}: template references '{${v}}' but no such param is declared (known: actor${
+            paramNames.size > 0 ? ", " + [...paramNames].join(", ") : ""
+          }). Declare it in params or fix the template.`,
+        );
+      }
+    }
+  }
+  const refs = Object.entries(input.refs ?? {}).map(([name, r]) => {
+    const targetId = (r?.type as { id?: unknown })?.id;
+    const isTarget = typeof targetId === "string" && ((r.type as { __isAggregateHandle?: unknown }).__isAggregateHandle === true || isContractHandle(r.type));
+    if (!isTarget) {
+      throw new Error(`${where}: ref '${name}'.type must be an aggregate handle or a contract(...) (got ${typeof r?.type}).`);
+    }
+    if (typeof r.from !== "string" || r.from.length === 0) {
+      throw new Error(`${where}: ref '${name}'.from must be a payload field path string.`);
+    }
+    return { name, type: targetId as string, from: r.from };
+  });
+  // "@created" refs: the id comes from the intent's sealed Create events, not the payload — so the
+  // directive must actually CREATE that aggregate type (when the creates-set is known, enforce it).
+  for (const r of refs) {
+    if (r.from === "@created" && createdAggregateIds !== undefined && !createdAggregateIds.includes(r.type)) {
+      throw new Error(
+        `${where}: ref '${r.name}' uses "@created" but this directive does not .creates ${r.type} ` +
+          `(creates: ${createdAggregateIds.length > 0 ? createdAggregateIds.join(", ") : "nothing"}). ` +
+          `"@created" binds to the law-minted id of a created aggregate.`,
+      );
+    }
+  }
+  // Best-effort payload-field existence check (root of a dotted path). "@created" is not a payload path.
+  const fields = payloadFieldNames(payloadSchema);
+  if (fields !== undefined) {
+    for (const { name, from } of [...params, ...refs.filter((r) => r.from !== "@created").map((r) => ({ name: `ref ${r.name}`, from: r.from }))]) {
+      const root = from.split(".")[0]!;
+      if (!fields.has(root)) {
+        throw new Error(
+          `${where}: ${name} reads payload field '${root}' which the payload does not declare ` +
+            `(known: ${[...fields].sort().join(", ")}). Fix the path or add the field.`,
+        );
+      }
+    }
+  }
+  return {
+    kind: input.kind,
+    title: input.title ?? input.kind,
+    message: input.message,
+    ...(input.category !== undefined ? { category: input.category } : {}),
+    ...(input.icon !== undefined ? { icon: input.icon } : {}),
+    severity,
+    refs: refs.sort((a, b) => a.name.localeCompare(b.name)),
+    params: params.sort((a, b) => a.name.localeCompare(b.name)),
+    titleKey: activityKey(input.kind, "title"),
+    messageKey: activityKey(input.kind, "message"),
+  };
+}
+
+/** Re-exported so directive.ts can accept the zod payload type in the `.activity` overload without a cycle. */
+export type { z };

package/src/codegen_dart.ts

@@ -1197,6 +1197,10 @@ function emitAggregate(
     `  /// indexed/by-id accessor matched on (e.g. the siteId). Empty string only when`,
     `  /// the aggregate is built from a bare \`data\` map with no row id (e.g. a unit test).`,
     `  final ${idType} aggregateId;`,
+    `  /// THE ONE REFERENCE (architecture/nomos_ref.md): this instance's canonical, workspace-qualified`,
+    `  /// [NomosRef] (\`nomos://<workspace>/<type>/<id>\`) — composed at decode from the session workspace +`,
+    `  /// the row's type/id. Workspace is '' when decoded off the bare bridge (the client accessors fill it).`,
+    `  final NomosRef ref;`,
     ...specs.flatMap((s) => {
       const doc = s.nullReason !== undefined ? [`  /// null semantic: ${s.nullReason}`] : [];
       // NULL SEMANTICS: a null-admitting field is the sealed tri-state slot (Omitted / ExplicitNull /
@@ -1208,6 +1212,7 @@ function emitAggregate(
   ].join("\n");
   const ctorParams = [
     `    this.aggregateId = const ${idType}.fromRow(''),`,
+    `    this.ref = const NomosRef(workspace: '', type: '${agg.id}', id: ''),`,
     ...specs.map(
       // A required scalar stays `required`; an optional scalar OR a collection is not
       // `required` (an absent optional scalar is null; an absent collection is empty).
@@ -1229,6 +1234,7 @@ function emitAggregate(
   // threaded from the row id (GAP 2) — defaulting to '' for a bare-map call.
   const parseLines = [
     `      aggregateId: ${aggregateIdFromRowExpr(agg.id, "id")},`,
+    `      ref: NomosRef(workspace: workspace, type: type.isEmpty ? '${agg.id}' : type, id: id),`,
     ...specs.map((s) =>
       s.nullAdmits === true
         ? `      ${s.name}: NomosSlot.decode<${stripNullable(s.dartType)}>(data, '${s.wireName}', ${slotDecodeCallback(s, "aggregate")}),`
@@ -1281,7 +1287,10 @@ function emitAggregate(
     `  /// decoded to bare JSON), carrying the kernel aggregate [id] from the row \`id\``,
     `  /// (defaults to '' for a bare-map call). PARTIAL folds: every scalar decodes`,
     `  /// \`null\` when absent (never throws); absent collections decode empty.`,
-    `  factory ${className}.fromJson(Map<String, dynamic> data, [String id = '']) {`,
+    `  ///`,
+    `  /// [workspace] + [type] compose the canonical [ref] (both optional — the client accessors thread the`,
+    `  /// session workspace + the row type; a bare decode leaves workspace '' and falls back to the type '${agg.id}').`,
+    `  factory ${className}.fromJson(Map<String, dynamic> data, [String id = '', String workspace = '', String type = '']) {`,
     `    return ${className}(`,
     parseLines,
     `    );`,
@@ -2002,6 +2011,154 @@ export function generateDartContracts(contracts: readonly import("./contract.js"
   ].join("\n");
 }
 
+// ── ACTIVITY DESCRIPTORS (architecture/activity_descriptors.md) — shared registry codegen ──
+
+/** One directive's declared activity, tagged with its provenance (domain + directive id). */
+export interface PackageActivityEntry {
+  readonly domain: string;
+  readonly directiveId: string;
+  readonly desc: import("./activity.js").ActivityDescriptor;
+}
+
+/** Collect every directive's `.activity(...)` descriptor across the package's modules, tagged with its
+ *  domain + directive id, sorted by directive id (byte-deterministic switch/registry order). Empty when
+ *  no directive opts in — an activity-free package then emits NO registry (byte-identical). Shared by the
+ *  flat + layered Dart emit AND the TS client (one source of truth). */
+export function collectActivityDescriptors(modules: readonly DomainModule[]): PackageActivityEntry[] {
+  const out: PackageActivityEntry[] = [];
+  for (const mod of modules) {
+    const domain = mod.domain ?? mod.name;
+    for (const d of mod.directives as AnyDirective[]) {
+      const desc = (d as { activityDescriptor?: import("./activity.js").ActivityDescriptor }).activityDescriptor;
+      if (desc !== undefined) out.push({ domain, directiveId: d.id, desc });
+    }
+  }
+  return out.sort((a, b) => (a.directiveId < b.directiveId ? -1 : a.directiveId > b.directiveId ? 1 : 0));
+}
+
+/** Dart string literal (single-quoted, backslash/quote/`$` escaped). */
+const dartLit = (s: string): string => `'${s.replace(/\\/g, "\\\\").replace(/'/g, "\\'").replace(/\$/g, "\\$")}'`;
+
+/** Emit ONE `case '<directiveId>':` arm folding a raw row into a typed [ActivityEvent]. */
+function emitDartActivityArm(e: PackageActivityEntry): string[] {
+  const { directiveId, desc } = e;
+  const paramEntries = desc.params.map((p) => `        ${dartLit(p.name)}: _activityPayloadPath(payload, ${dartLit(p.from)}),`);
+  const refEntries = desc.refs.map((r) => {
+    // A `from: "@created"` ref reads the id the LAW MINTED (the row's `created` list, first type match); any
+    // other `from` is a payload path. Every ref carries the session workspace (the row's `workspace`).
+    const id = r.from === "@created"
+      ? `_activityCreatedId(created, ${dartLit(r.type)})`
+      : `_activityPayloadPath(payload, ${dartLit(r.from)})`;
+    return `          ${dartLit(r.name)}: ActivityRef(workspace: workspace, type: ${dartLit(r.type)}, id: ${id}),`;
+  });
+  return [
+    `    case ${dartLit(directiveId)}:`,
+    `      {`,
+    `        final params = <String, String>{`,
+    ...paramEntries,
+    `        };`,
+    `        final vars = <String, String>{'actor': actorSubject, ...params};`,
+    `        return ActivityEvent(`,
+    `          eventId: (rawRow['intentId'] ?? '') as String,`,
+    `          kind: ${dartLit(desc.kind)},`,
+    `          actorSubject: actorSubject,`,
+    `          occurredAt: (rawRow['occurredAt'] ?? '') as String,`,
+    `          title: renderActivityTemplate(${dartLit(desc.title)}, vars),`,
+    `          message: renderActivityTemplate(${dartLit(desc.message)}, vars),`,
+    `          titleKey: ${dartLit(desc.titleKey)},`,
+    `          messageKey: ${dartLit(desc.messageKey)},`,
+    `          params: params,`,
+    `          refs: <String, ActivityRef>{`,
+    ...refEntries,
+    `          },`,
+    ...(desc.category !== undefined ? [`          category: ${dartLit(desc.category)},`] : []),
+    ...(desc.icon !== undefined ? [`          icon: ${dartLit(desc.icon)},`] : []),
+    `          severity: ActivitySeverity.${desc.severity},`,
+    `          domain: (rawRow['domain'] ?? '') as String,`,
+    `          directiveId: ${dartLit(directiveId)},`,
+    `        );`,
+    `      }`,
+  ];
+}
+
+/**
+ * The full source of the shared `activity_registry.dart` file — the PURE per-directive activity registry
+ * + `renderActivity(rawRow) => ActivityEvent?`, emitted ONCE per package into the TYPES package (both the
+ * flat + layered emit). References only nomos_types (`ActivityEvent`/`ActivityRef`/`ActivitySeverity`/
+ * `renderActivityTemplate`), so the file is PURE (frontend-safe, no bridge). A raw row is
+ * `{ intentId, domain, directiveId, actorSubject, occurredAt, payload }` (the runtime's per-committed-intent
+ * shape); `renderActivity` returns null for a directive with no declared `.activity(...)`.
+ */
+export function generateDartActivityRegistry(entries: readonly PackageActivityEntry[]): string {
+  const sorted = [...entries].sort((a, b) => (a.directiveId < b.directiveId ? -1 : a.directiveId > b.directiveId ? 1 : 0));
+  return [
+    `// GENERATED by nomos-compile — the package's shared ACTIVITY REGISTRY (architecture/activity_descriptors.md). DO NOT EDIT.`,
+    `// A directive OPT-IN declares its user-facing activity metadata; \`renderActivity\` folds each committed-intent`,
+    `// raw row into a typed ActivityEvent. Pure (nomos_types only) — the kernel/ledger stays the audit truth.`,
+    `//`,
+    `// ignore_for_file: unused_import`,
+    `library;`,
+    ``,
+    `import 'package:nomos_client/nomos_client.dart';`,
+    ``,
+    `/// A NARRATIVE over the activity log (for an in-app LLM): the filtered [events] + a plain-English`,
+    `/// [transcript] (ONE LINE PER EVENT, oldest-first, \`"<occurredAt> — <title>: <message>"\`) grounded in`,
+    `/// the VERIFIED log, never raw payloads. Produced by the client's \`describe\` / \`describeHistory\`.`,
+    `class ActivityNarrative {`,
+    `  final List<ActivityEvent> events;`,
+    `  final String transcript;`,
+    `  const ActivityNarrative({required this.events, required this.transcript});`,
+    `}`,
+    ``,
+    `/// Wrap events into an [ActivityNarrative], building the LLM-ready transcript: one line per event,`,
+    `/// OLDEST-FIRST (the log yields newest-first).`,
+    `ActivityNarrative activityNarrative(List<ActivityEvent> events) => ActivityNarrative(`,
+    `      events: events,`,
+    `      transcript: events.reversed.map((e) => '\${e.occurredAt} — \${e.title}: \${e.message}').join('\\n'),`,
+    `    );`,
+    ``,
+    `/// Read a dotted path off a decoded intent payload, coerced to String ('' when absent/null).`,
+    `String _activityPayloadPath(Map<String, dynamic> payload, String path) {`,
+    `  dynamic cur = payload;`,
+    `  for (final seg in path.split('.')) {`,
+    `    if (cur is! Map) return '';`,
+    `    cur = cur[seg];`,
+    `  }`,
+    `  return cur == null ? '' : '\$cur';`,
+    `}`,
+    ``,
+    `/// The id the LAW minted for a \`from: "@created"\` ref — the first entry of the row's \`created\` list`,
+    `/// whose type matches the declared aggregate (the runtime type is uuid-stripped + may be namespaced, so`,
+    `/// match on equality OR \`<domain>.<Type>\` suffix). '' when the holon returned no created list (era-safe).`,
+    `String _activityCreatedId(List<Map<String, dynamic>> created, String declared) {`,
+    `  for (final c in created) {`,
+    `    final t = (c['type'] ?? '') as String;`,
+    `    if (t == declared || t.endsWith('.\$declared')) return (c['id'] ?? '') as String;`,
+    `  }`,
+    `  return '';`,
+    `}`,
+    ``,
+    `/// Fold ONE committed-intent raw row into a typed [ActivityEvent], or null when the directive declares`,
+    `/// no \`.activity(...)\`. rawRow = { intentId, domain, directiveId, actorSubject, occurredAt, payload,`,
+    `/// created, workspace } — \`created\` (\`[{type,id}]\`) backs \`from: "@created"\` refs; \`workspace\` stamps them.`,
+    `ActivityEvent? renderActivity(Map<String, dynamic> rawRow) {`,
+    `  final directiveId = (rawRow['directiveId'] ?? '') as String;`,
+    `  final actorSubject = (rawRow['actorSubject'] ?? '') as String;`,
+    `  final workspace = (rawRow['workspace'] ?? '') as String;`,
+    `  final payload = ((rawRow['payload'] as Map?)?.cast<String, dynamic>()) ?? const <String, dynamic>{};`,
+    `  final created = ((rawRow['created'] as List?) ?? const <dynamic>[])`,
+    `      .map((e) => (e as Map).cast<String, dynamic>())`,
+    `      .toList();`,
+    `  switch (directiveId) {`,
+    ...sorted.flatMap(emitDartActivityArm),
+    `    default:`,
+    `      return null;`,
+    `  }`,
+    `}`,
+    ``,
+  ].join("\n");
+}
+
 /** True when ANY aggregate field in the module is `t.evidence()` — gates emitting the
  * shared [emitEvidenceRefClass] once. */
 function moduleUsesEvidence(aggregates: readonly AggregateHandle[]): boolean {
@@ -2397,6 +2554,10 @@ function emitReadModel(
     `  /// The kernel aggregate id (the \`{type,id,data}\` row's \`id\`, e.g. the siteId).`,
     `  /// Empty string only when built from a bare \`data\` map with no row id (a unit test).`,
     `  final ${idType} aggregateId;`,
+    `  /// THE ONE REFERENCE (architecture/nomos_ref.md): this row's canonical, workspace-qualified [NomosRef]`,
+    `  /// (\`nomos://<workspace>/<type>/<id>\`) — composed at decode from the session workspace + the row's`,
+    `  /// type/id. The generated client accessors thread the session workspace; a bare decode leaves it ''.`,
+    `  final NomosRef ref;`,
     ...specs.flatMap((s) => {
       const doc = s.nullReason !== undefined ? [`  /// null semantic: ${s.nullReason}`] : [];
       return s.nullAdmits === true
@@ -2414,6 +2575,7 @@ function emitReadModel(
   ].join("\n");
   const ctorParams = [
     `    this.aggregateId = const ${idType}.fromRow(''),`,
+    `    this.ref = const NomosRef(workspace: '', type: '${agg.id}', id: ''),`,
     ...specs.map((s) =>
       // A required field is `required`; an optional scalar, a collection, OR a
       // permissive json leaf (already nullable `Object?`) takes its default/null.
@@ -2431,6 +2593,7 @@ function emitReadModel(
 
   const parseLines = [
     `      aggregateId: ${aggregateIdFromRowExpr(agg.id, "id")},`,
+    `      ref: NomosRef(workspace: workspace, type: type.isEmpty ? '${agg.id}' : type, id: id),`,
     ...specs.map((s) =>
       s.nullAdmits === true
         ? `      ${s.name}: NomosSlot.decode<${stripNullable(readModelDartType(s))}>(data, '${s.wireName}', ${slotDecodeCallback(s, "readModel")}),`
@@ -2464,7 +2627,10 @@ function emitReadModel(
     `  /// already decoded to bare/structured JSON), carrying the kernel aggregate [id] from`,
     `  /// the row \`id\` (defaults to '' for a bare-map call). PARTIAL folds: every scalar`,
     `  /// decodes \`null\` when absent (never throws); absent collections decode empty.`,
-    `  factory ${className}.fromProjected(Map<String, dynamic> data, [String id = '']) {`,
+    `  ///`,
+    `  /// [workspace] + [type] compose the canonical [ref] (both optional — the client accessors thread the`,
+    `  /// session workspace + the row type; a bare decode leaves workspace '' and falls back to the type '${agg.id}').`,
+    `  factory ${className}.fromProjected(Map<String, dynamic> data, [String id = '', String workspace = '', String type = '']) {`,
     `    return ${className}(`,
     parseLines,
     `    );`,