@githolon/dsl 0.61.3 → 0.62.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.61.3",
+  "version": "0.62.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

@@ -1406,8 +1406,15 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
         ? `      const _sealed = await _sealFields(holon, keyStore, ${encConst}[${JSON.stringify(domain)}].directives[${JSON.stringify(d.id)}] as Record<string, { scope: string; aggSid: string; fieldSid: string }>, payload as Record<string, unknown>, callOpts?.seal !== false) as ${payloadName};`
         : "";
       const pv = wantSeal ? "_sealed" : "payload";
+      // MULTI-OUTPUT: name every aggregate this directive writes (primary marker target + declared
+      // secondaryOutputs), so the frontend dev sees "writes A + B" at the call site (not one by convention).
+      const dd = d as unknown as { aggregateId: string; marker: string; secondaryOutputs?: readonly { aggregateId: string; marker: string }[] };
+      const allOutputs = [{ aggregateId: dd.aggregateId, marker: dd.marker }, ...(dd.secondaryOutputs ?? [])];
+      const writesClause = allOutputs.length > 1
+        ? ` Writes ${allOutputs.map((o) => `\`${o.aggregateId}\` (${o.marker})`).join(" + ")}.`
+        : "";
       out.push(
-        `/** \`${domain}/${d.id}\` payload (mirrors the engine's zod schema).${stamps.length ? ` Omitted ${stamps.map((s) => `\`${s}\``).join("/")} auto-stamp(s) ISO now() at offer.` : ""}${mint ? ` Omitted \`${mint.field}\` is KERNEL-MINTED at offer (returned on the result).` : ""}${placed.length ? " Omitted `shard` is picked LEAST-LOADED at offer (the routed holon)." : ""} */`,
+        `/** \`${domain}/${d.id}\` payload (mirrors the engine's zod schema).${writesClause}${stamps.length ? ` Omitted ${stamps.map((s) => `\`${s}\``).join("/")} auto-stamp(s) ISO now() at offer.` : ""}${mint ? ` Omitted \`${mint.field}\` is KERNEL-MINTED at offer (returned on the result).` : ""}${placed.length ? " Omitted `shard` is picked LEAST-LOADED at offer (the routed holon)." : ""} */`,
         `export type ${payloadName} = ${tsTypeOfPayload(schema, stamps, mint ? [mint.field] : [], placed, lazyReg, d.id)};`,
         ``,
       );

package/src/directive.ts

@@ -74,10 +74,26 @@ export interface PreconditionDescriptor {
  * the intent's HLC against exactly this scope.
  */
 
+/** One additional aggregate a directive DECLARES it writes (a multi-output directive), beyond its primary
+ *  `.creates/.mutates/.ensures/.archives` target. Descriptive metadata (docs/proof/client), NOT a kernel
+ *  write-restriction — the plan's ops are what fold. */
+export interface SecondaryOutput {
+  readonly marker: ReferentialMarker;
+  readonly aggregateId: string;
+}
+
 export interface Directive<P = unknown> {
   readonly id: string;
   readonly marker: ReferentialMarker;
   readonly aggregateId: string;
+  /**
+   * MULTI-OUTPUT DIRECTIVES: additional aggregates this directive declares it writes, beyond the primary
+   * marker target. Present iff the directive chained `.alsoEnsures/.alsoCreates/.alsoMutates/.alsoArchives`
+   * (or `.alsoWrites`). Purely additive metadata — generated docs/proof/client say "writes A + B" instead
+   * of picking one by convention; the kernel folds by the plan's ops regardless. Omit-when-empty (era-safe:
+   * a single-output directive is byte-identical in the IR to before this existed).
+   */
+  readonly secondaryOutputs?: readonly SecondaryOutput[];
   readonly payloadSchema: z.ZodType<P>;
   readonly plan: (payload: P, ctx: Ports) => PlannedOp[];
   /**
@@ -300,6 +316,18 @@ export interface Directive<P = unknown> {
  * each `plan` — the kernel resolves it WITHIN the one shared `admit` gate.
  */
 export interface RequirableDirective<P> extends Directive<P> {
+  /**
+   * MULTI-OUTPUT: declare an ADDITIONAL aggregate this directive writes (beyond its primary marker target),
+   * so generated docs/proof/client metadata name every output ("writes A + B") instead of one by convention.
+   * `.alsoEnsures/.alsoCreates/.alsoMutates/.alsoArchives` are the marker-specific sugar; `.alsoWrites` takes
+   * an explicit marker. Chainable + additive (a directive that never calls these is byte-identical). The
+   * kernel folds by the plan's ops regardless — this is descriptive law metadata, not a write-restriction.
+   */
+  alsoWrites(aggregate: AggregateHandle, marker: ReferentialMarker): RequirableDirective<P>;
+  alsoEnsures(aggregate: AggregateHandle): RequirableDirective<P>;
+  alsoCreates(aggregate: AggregateHandle): RequirableDirective<P>;
+  alsoMutates(aggregate: AggregateHandle): RequirableDirective<P>;
+  alsoArchives(aggregate: AggregateHandle): RequirableDirective<P>;
   /**
    * Declare the authz pre-condition: the `capability` the actor must hold (defaults
    * to the directive id) at the scope `scopeFrom(payload)` derives (defaults to root).
@@ -636,8 +664,22 @@ export function recordObject(
  * declaration site reads `directive(id)…plan(fn).requires("cap", p => […])`.
  */
 function makeRequirable<P>(base: Directive<P>): RequirableDirective<P> {
+  const alsoWrites = (aggregate: AggregateHandle, marker: ReferentialMarker): RequirableDirective<P> => {
+    // Dedup by (marker, aggregateId) + the primary target — declaring the same output twice is a no-op, and
+    // re-declaring the primary aggregate is ignored (it is already the marker target). Sorted at emit time.
+    const next: SecondaryOutput = { marker, aggregateId: aggregate.id };
+    const isPrimary = aggregate.id === base.aggregateId;
+    const already = (base.secondaryOutputs ?? []).some((s) => s.marker === marker && s.aggregateId === aggregate.id);
+    if (isPrimary || already) return makeRequirable(base);
+    return makeRequirable({ ...base, secondaryOutputs: [...(base.secondaryOutputs ?? []), next] });
+  };
   return {
     ...base,
+    alsoWrites,
+    alsoEnsures: (aggregate: AggregateHandle) => alsoWrites(aggregate, "ensures"),
+    alsoCreates: (aggregate: AggregateHandle) => alsoWrites(aggregate, "creates"),
+    alsoMutates: (aggregate: AggregateHandle) => alsoWrites(aggregate, "mutates"),
+    alsoArchives: (aggregate: AggregateHandle) => alsoWrites(aggregate, "archives"),
     requires(
       relation: string,
       opts?: { object?: string; objectFrom?: { recordType: string; idField: string } },

package/src/index.ts

@@ -121,6 +121,7 @@ export {
   recordObject,
   type Directive,
   type ReferentialMarker,
+  type SecondaryOutput,
   type PreconditionDescriptor,
 } from "./directive.js";
 // FIRST-CLASS WORKSPACE TYPES (sharding §10 RATIFIED, slice 1) live on the SUBPATH

package/src/manifest.ts

@@ -29,6 +29,7 @@ import { createHash } from "node:crypto";
 import { z } from "zod";
 import { encodeKernelSchema, encodeRefMode } from "./wire_encode.js";
 import type { WireSchema, WireRefMode } from "./wire.js";
+import type { ReferentialMarker } from "./directive.js";
 import type { DomainModule } from "./codegen_dart.js";
 import type { WorkspaceInvariantDecl } from "./framework/workspace_invariant.js";
 import type { QueryDecl } from "./query.js";
@@ -114,6 +115,13 @@ export interface CanonicalDirective {
   /** The target aggregate id. */
   readonly target: string;
   readonly marker: WireRefMode;
+  /**
+   * MULTI-OUTPUT DIRECTIVES: additional aggregates this directive declares it writes, beyond the primary
+   * `target`/`marker` — `{ target, marker }` pairs SORTED by (target, marker). Descriptive law metadata
+   * (docs/proof/client name every output). OMITTED ENTIRELY when the directive declares none, so a
+   * single-output directive is byte-identical to before this key existed (pinned golden hashes unchanged).
+   */
+  readonly secondaryOutputs?: readonly { target: string; marker: WireRefMode }[];
   /** The payload's top-level object shape as SORTED `[name, type]` pairs. */
   readonly payload: CanonicalPayloadField[];
   /**
@@ -645,6 +653,18 @@ function canonicalReads(declared: string[]): { reads?: string[] } {
   return { reads: [...declared].sort() };
 }
 
+/** Canonicalize a directive's MULTI-OUTPUT secondary writes → `{ target, marker }` sorted by (target,
+ *  marker). Omit-when-empty (the era rule — a single-output directive contributes no key). */
+function canonicalSecondaryOutputs(
+  declared: readonly { marker: ReferentialMarker; aggregateId: string }[] | undefined,
+): { secondaryOutputs?: { target: string; marker: WireRefMode }[] } {
+  if (declared === undefined || declared.length === 0) return {};
+  const out = declared
+    .map((s) => ({ target: s.aggregateId, marker: encodeRefMode(s.marker) }))
+    .sort((a, b) => (a.target !== b.target ? (a.target < b.target ? -1 : 1) : a.marker < b.marker ? -1 : a.marker > b.marker ? 1 : 0));
+  return { secondaryOutputs: out };
+}
+
 /**
  * Canonicalize a directive's declared required HOST CAPABILITY ports into a manifest fragment
  * (the HOST/PORT axis, invariant 3). OMIT-WHEN-EMPTY: returns `{}` (no `requiresHostCapability`
@@ -1046,6 +1066,7 @@ export function domainManifest(mod: DomainModule): CanonicalManifest {
       id: d.id,
       target: d.aggregateId,
       marker: encodeRefMode(d.marker),
+      ...canonicalSecondaryOutputs(d.secondaryOutputs),
       payload: canonicalPayload(d.payloadSchema),
       payloadJsonSchema: canonicalPayloadJsonSchema(d.payloadSchema),
       // Omit-when-empty: a directive declaring NO boundary contributes neither key,

package/src/usd.ts

@@ -106,6 +106,12 @@ export type UsdPrim =
        * (`undefined`) when no emits are declared (omit-when-empty hash invariance).
        */
       readonly emits?: Record<string, { max?: number }>;
+      /**
+       * MULTI-OUTPUT: the ADDITIONAL aggregates this directive declares it writes (beyond `target`/`marker`),
+       * `{ target, marker }` sorted. OMITTED (`undefined`) for a single-output directive (omit-when-empty
+       * hash invariance). Descriptive law metadata — docs/proof/client name every output.
+       */
+      readonly secondaryOutputs?: readonly { target: string; marker: WireRefMode }[];
       /**
        * Standard JSON Schema for the directive payload, emitted from TS/Zod into the
        * IR so cross-language tooling validates against the same schema source.
@@ -664,6 +670,9 @@ function encodeModuleToPrims(layerPath: string, manifest: CanonicalManifest): Us
       // directive declared them, so a boundary-free prim is byte-identical to before.
       ...(d.reads !== undefined ? { reads: d.reads } : {}),
       ...(d.emits !== undefined ? { emits: d.emits } : {}),
+      // MULTI-OUTPUT: the additional aggregates this directive declares it writes (self-describing law).
+      // Omit-when-empty from the manifest, so a single-output prim is byte-identical to before.
+      ...(d.secondaryOutputs !== undefined ? { secondaryOutputs: d.secondaryOutputs } : {}),
       payloadJsonSchema: d.payloadJsonSchema,
       // `scope`/`payloadRef` deliberately omitted (undefined): no static scope in
       // the DSL today, payload is the stage-2 certified artifact.

package/src/usd_layers.ts

@@ -349,6 +349,11 @@ export function usdaLayerText(
           `${ind3}custom string nomos:emitsHex = ${usdaString(hexUtf8(JSON.stringify(prim.emits)))}`,
         );
       }
+      if (prim.secondaryOutputs !== undefined) {
+        body.push(
+          `${ind3}custom string nomos:secondaryOutputsHex = ${usdaString(hexUtf8(JSON.stringify(prim.secondaryOutputs)))}`,
+        );
+      }
       if (prim.payloadJsonSchema !== undefined) {
         body.push(
           `${ind3}custom string nomos:payloadJsonSchemaHex = ${usdaString(
@@ -503,6 +508,7 @@ function foldOpinionPrim(base: UsdPrim, over: UsdPrim): UsdPrim {
     // flattened bytes match `encodeModuleToPrims` exactly.
     const reads = over.reads ?? base.reads;
     const emits = over.emits ?? base.emits;
+    const secondaryOutputs = over.secondaryOutputs ?? base.secondaryOutputs;
     const payloadJsonSchema = over.payloadJsonSchema ?? base.payloadJsonSchema;
     return {
       kind: "directive",
@@ -512,6 +518,7 @@ function foldOpinionPrim(base: UsdPrim, over: UsdPrim): UsdPrim {
       requires: over.requires,
       ...(reads !== undefined ? { reads } : {}),
       ...(emits !== undefined ? { emits } : {}),
+      ...(secondaryOutputs !== undefined ? { secondaryOutputs } : {}),
       ...(payloadJsonSchema !== undefined ? { payloadJsonSchema } : {}),
     };
   }
@@ -1244,6 +1251,9 @@ export function parseUsdaDocument(text: string): UsdDocument {
       const emits = p.attrs.has("nomos:emitsHex")
         ? (JSON.parse(unhexUtf8(attrString(p, "nomos:emitsHex"))) as Record<string, { max?: number }>)
         : undefined;
+      const secondaryOutputs = p.attrs.has("nomos:secondaryOutputsHex")
+        ? (JSON.parse(unhexUtf8(attrString(p, "nomos:secondaryOutputsHex"))) as { target: string; marker: WireRefMode }[])
+        : undefined;
       const payloadJsonSchema = p.attrs.has("nomos:payloadJsonSchemaHex")
         ? (JSON.parse(unhexUtf8(attrString(p, "nomos:payloadJsonSchemaHex"))) as unknown)
         : undefined;
@@ -1255,6 +1265,7 @@ export function parseUsdaDocument(text: string): UsdDocument {
         requires: attrStringArray(p, "nomos:requires"),
         ...(reads !== undefined ? { reads } : {}),
         ...(emits !== undefined ? { emits } : {}),
+        ...(secondaryOutputs !== undefined ? { secondaryOutputs } : {}),
         ...(payloadJsonSchema !== undefined ? { payloadJsonSchema } : {}),
       });
     } else if (kind === "query") {