@hyperscale0/udl 2.5.0 → 2.6.0

package/docs/llms-full.txt

@@ -1,4 +1,4 @@
-<!-- Generated by scripts/docs/build.ts from @hyperscale0/udl 2.5.0. Edit the source, not llms-full.txt. -->
+<!-- Generated by scripts/docs/build.ts from @hyperscale0/udl 2.6.0. Edit the source, not llms-full.txt. -->
 
 # UDL complete reference
 
@@ -266,6 +266,8 @@ The engine proves the advance and supplies trusted paid/consumed facts to the pl
 
 `transitionsRefs` invokes named noncash lifecycle actions on referenced instruments in the same transaction. The engine applies every target gate, authority check and lifecycle precondition. Cycles, repeated target actions and cash-bearing or input-dependent target actions refuse. A child can lapse its cover; a refund can cancel a referenced funding record and prevent future actions through that record's lifecycle gates. This does not replace durable approval consumption tied to a downstream operation.
 
+`cascade` executes a named lifecycle action on linked instances of another instrument inside the same transaction before evaluating the parent action's own admission gates. Target instances are identified either through caller input IDs via `inputField` or by matching a parent reference on target rows via `refField` filtered by lifecycle statuses. The cascading action cannot be create and cannot declare a decision. The target action must exist in lifecycle, cannot be create or engine-owned, cannot declare a decision, and cannot declare a cascade of its own. Because the cascade runs before the parent's admission gates, child status transitions take effect in time for parent aggregate requirements.
+
 `requiresRefs.unique` accepts `{namespace, byFields}`. The uniqueness key contains the Product, namespace, referenced instance identity and immutable key values. It excludes instrument aliases and current status. A waived or refunded fine still occupies its key; cost uses a different kind value. The engine enforces this key under a shared constraint or lock.
 
 Decision authentication, attestation verification and request hashing are admission concerns. The decision record must carry the requested instrument kind, instance, action, canonical input digest, deciding role and actor, expiry, verdict and evidence references. The engine computes the digest from the admitted request, authenticates the authority, checks expiry and revocation under locks, and binds consumption to the durable operation identity. Submitted actor and operation fields are not proof.
@@ -611,6 +613,28 @@ This page lists every entry in `udlClauseVocabulary`. The examples are copied fr
 ]
 ```
 
+## cascade
+
+- Scope: action
+- UDL target: `cascade`
+- Cardinality: many
+- Linear outputs: none
+- Effects: decides.cascade_transition per element
+- Law: Requirements-as-data law and closure law
+- Conformance source: `vocabulary.udl`
+
+A cascade target action that declares a `port` is allowed only when the parent action declares a `port`: the engine forwards the port actor.
+
+```json
+[
+  {
+    "action": "close",
+    "inputField": "sliceIds",
+    "instrumentId": "slice"
+  }
+]
+```
+
 ## action library
 
 - Scope: instrument

package/docs/llms.txt

@@ -1,4 +1,4 @@
-<!-- Generated by scripts/docs/build.ts from @hyperscale0/udl 2.5.0. Edit the source, not llms.txt. -->
+<!-- Generated by scripts/docs/build.ts from @hyperscale0/udl 2.6.0. Edit the source, not llms.txt. -->
 
 # UDL documentation
 

package/docs/reference/clauses.md

@@ -1,4 +1,4 @@
-<!-- Generated by scripts/docs/build.ts from @hyperscale0/udl 2.5.0. Edit the source, not clauses.md. -->
+<!-- Generated by scripts/docs/build.ts from @hyperscale0/udl 2.6.0. Edit the source, not clauses.md. -->
 
 # Clause reference
 
@@ -254,6 +254,28 @@ This page lists every entry in `udlClauseVocabulary`. The examples are copied fr
 ]
 ```
 
+## cascade
+
+- Scope: action
+- UDL target: `cascade`
+- Cardinality: many
+- Linear outputs: none
+- Effects: decides.cascade_transition per element
+- Law: Requirements-as-data law and closure law
+- Conformance source: `vocabulary.udl`
+
+A cascade target action that declares a `port` is allowed only when the parent action declares a `port`: the engine forwards the port actor.
+
+```json
+[
+  {
+    "action": "close",
+    "inputField": "sliceIds",
+    "instrumentId": "slice"
+  }
+]
+```
+
 ## action library
 
 - Scope: instrument

package/docs/reference/cli.md

@@ -1,4 +1,4 @@
-<!-- Generated by scripts/docs/build.ts from @hyperscale0/udl 2.5.0. Edit the source, not cli.md. -->
+<!-- Generated by scripts/docs/build.ts from @hyperscale0/udl 2.6.0. Edit the source, not cli.md. -->
 
 # Command reference
 

package/docs/reference/diagnostics.md

@@ -1,4 +1,4 @@
-<!-- Generated by scripts/docs/build.ts from @hyperscale0/udl 2.5.0. Edit the source, not diagnostics.md. -->
+<!-- Generated by scripts/docs/build.ts from @hyperscale0/udl 2.6.0. Edit the source, not diagnostics.md. -->
 
 # Diagnostic reference
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperscale0/udl",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "The Universal Domain Language: format spec, parser, validator, canonical serializer, and evolution diff.",
   "keywords": [
     "udl",
@@ -83,5 +83,5 @@
     "Amir Ayub",
     "Sara AlBakaawi"
   ],
-  "gitHead": "a537ff33ff29340cc2849ea049df4d65889c5d5c"
+  "gitHead": "cd1e1ff5c188de94ff8bb0761cb3258746196bf2"
 }

package/spec/udl.schema.json

@@ -1719,6 +1719,68 @@
                     "additionalProperties": false
                   }
                 },
+                "cascade": {
+                  "minItems": 1,
+                  "maxItems": 8,
+                  "type": "array",
+                  "items": {
+                    "anyOf": [
+                      {
+                        "type": "object",
+                        "properties": {
+                          "instrumentId": {
+                            "type": "string",
+                            "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$",
+                            "x-udl-reference": "instrument"
+                          },
+                          "action": {
+                            "type": "string",
+                            "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$"
+                          },
+                          "inputField": {
+                            "type": "string",
+                            "pattern": "^[a-z][A-Za-z0-9]*$"
+                          }
+                        },
+                        "required": ["instrumentId", "action", "inputField"],
+                        "additionalProperties": false
+                      },
+                      {
+                        "type": "object",
+                        "properties": {
+                          "instrumentId": {
+                            "type": "string",
+                            "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$",
+                            "x-udl-reference": "instrument"
+                          },
+                          "action": {
+                            "type": "string",
+                            "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$"
+                          },
+                          "refField": {
+                            "type": "string",
+                            "pattern": "^[a-z][A-Za-z0-9]*$"
+                          },
+                          "statuses": {
+                            "minItems": 1,
+                            "type": "array",
+                            "items": {
+                              "type": "string",
+                              "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$"
+                            }
+                          }
+                        },
+                        "required": [
+                          "instrumentId",
+                          "action",
+                          "refField",
+                          "statuses"
+                        ],
+                        "additionalProperties": false
+                      }
+                    ]
+                  }
+                },
                 "agentDescription": {
                   "type": "string",
                   "maxLength": 400

package/src/evolution.ts

@@ -80,6 +80,8 @@ export interface EvolutionActionSnapshot {
   readonly setsAt: unknown;
   /** Missing on snapshots written before signed child sums existed. */
   readonly signedSum?: unknown;
+  /** Missing on snapshots written before cascade transitions existed. */
+  readonly cascade?: unknown;
   readonly moves: readonly EvolutionMoveSnapshot[];
   readonly steps: readonly EvolutionStepSnapshot[];
 }
@@ -578,6 +580,9 @@ function snapshotUdlAction(definition: UdlAction): EvolutionActionSnapshot {
     publicAction: definition.publicAction ?? null,
     setsAt: definition.setsAt ?? null,
     signedSum: definition.signedSum ?? null,
+    cascade: definition.cascade
+      ? definition.cascade.map((entry) => ({ ...entry }))
+      : null,
     moves: definition.moves.map((move) => ({
       bind: move.bind,
       capture: move.capture ?? {},
@@ -887,6 +892,12 @@ function diffActions(
     ) {
       violations.push(`action ${action} changed its signed child sum`);
     }
+    if (
+      descriptor.cascade !== undefined &&
+      stableStringify(descriptor.cascade) !== stableStringify(current.cascade)
+    ) {
+      violations.push(`action ${action} changed its cascade rules`);
+    }
   }
   for (const [action, descriptor] of Object.entries(next)) {
     if (previous[action] || descriptor.payout == null) continue;

package/src/schema.ts

@@ -909,6 +909,20 @@ const udlRequestAuthoritySchema = z.strictObject({
   expiresField: udlFieldNameSchema,
 });
 
+const udlCascadeEntrySchema = z.union([
+  z.strictObject({
+    instrumentId: udlInstrumentIdSchema,
+    action: udlActionNameSchema,
+    inputField: udlFieldNameSchema,
+  }),
+  z.strictObject({
+    instrumentId: udlInstrumentIdSchema,
+    action: udlActionNameSchema,
+    refField: udlFieldNameSchema,
+    statuses: z.array(udlSnakeCaseSchema).min(1),
+  }),
+]);
+
 const udlActionShape = {
   requestAuthority: udlRequestAuthoritySchema.optional(),
   funding: udlFundingSchema.optional(),
@@ -954,6 +968,7 @@ const udlActionShape = {
     .min(1)
     .max(16)
     .optional(),
+  cascade: z.array(udlCascadeEntrySchema).min(1).max(8).optional(),
   agentDescription: udlAgentDescriptionSchema.optional(),
   calls: z.array(udlCallSchema).min(1).optional(),
   captureInput: z.record(udlFieldNameSchema, udlFieldNameSchema).optional(),
@@ -1217,6 +1232,19 @@ export const udlClauseVocabulary = [
       },
     ],
   },
+  {
+    cardinality: "many",
+    scope: "action",
+    spelling: "cascade",
+    target: "cascade",
+    effects: [
+      {
+        kind: "decides",
+        per: "element",
+        signature: { fixed: "cascade_transition" },
+      },
+    ],
+  },
   {
     cardinality: "one",
     literalKeys: true,
@@ -1893,3 +1921,4 @@ export type UdlActionLibraryModule = z.infer<
   typeof udlActionLibraryModuleSchema
 >;
 export type UdlActionLibrary = z.infer<typeof udlActionLibrarySchema>;
+export type UdlCascadeEntry = z.infer<typeof udlCascadeEntrySchema>;

package/src/vocabulary.ts

@@ -32,6 +32,12 @@ const mutable = (instrument: UdlInstrument, field: string) =>
   Object.values(instrument.actions).some((action) =>
     action.updates?.includes(field),
   );
+function instrumentInstanceKey(instrumentId: string): string {
+  const camel = instrumentId.replaceAll(/_([a-z])/g, (_, letter: string) =>
+    letter.toUpperCase(),
+  );
+  return `${camel}Id`;
+}
 
 /** Validate product laws independently of any instrument catalogue. */
 /** The children buckets of an allocation owner that select this instrument or its template alias. */
@@ -952,6 +958,127 @@ export function validateVocabulary(
         outgoing.push(`${target.id}.${transition.action}`);
       }
       edges.set(`${instrument.id}.${name}`, outgoing);
+      if (action.cascade) {
+        const ap = [...path, "cascade"];
+        if (name === "create" || action.decision) {
+          add(
+            ap,
+            "cascade is not allowed on create or actions with a decision",
+          );
+        }
+        const seenInputFields = new Set<string>();
+        for (const [i, entry] of action.cascade.entries()) {
+          const ep = [...ap, i];
+          const hasInput =
+            "inputField" in entry && entry.inputField !== undefined;
+          const hasRef = "refField" in entry && entry.refField !== undefined;
+          if ((!hasInput && !hasRef) || (hasInput && hasRef)) {
+            add(
+              ep,
+              "cascade must specify exactly one of inputField or refField",
+            );
+          }
+          const target = byId.get(entry.instrumentId);
+          if (!target) {
+            add(
+              ep,
+              "cascade target instrument must be declared in the document",
+            );
+          } else {
+            const targetAction = target.actions[entry.action];
+            const targetTransition = target.lifecycle.transitions[entry.action];
+            if (
+              !targetAction ||
+              !targetTransition ||
+              entry.action === "create"
+            ) {
+              add(
+                ep,
+                "cascade target action must exist in lifecycle and cannot be create",
+              );
+            } else {
+              if (targetAction.engineOwned) {
+                add(ep, "cascade target action cannot be engine-owned");
+              }
+              if (targetAction.cascade) {
+                add(
+                  ep,
+                  "cascade target action cannot have a cascade of its own",
+                );
+              }
+              if (targetAction.decision) {
+                add(ep, "cascade target action cannot have a decision");
+              }
+              if (targetAction.port && !action.port) {
+                add(
+                  ep,
+                  `cascade target action ${entry.action} declares a port; the parent action ${name} must declare a port so the actor is forwarded`,
+                );
+              }
+              if (
+                Array.isArray(targetAction.input?.required) &&
+                targetAction.input.required.length > 0
+              ) {
+                add(ep, "cascade target action cannot have required inputs");
+              }
+            }
+            if ("refField" in entry && entry.refField !== undefined) {
+              if (!entry.statuses || entry.statuses.length === 0) {
+                add(ep, "cascade with refField requires statuses");
+              }
+              const targetRef = reference(target, entry.refField, ep);
+              if (targetRef && targetRef.id !== instrument.id) {
+                add(
+                  ep,
+                  "cascade target refField must reference this instrument",
+                );
+              }
+              if (targetTransition) {
+                for (const status of entry.statuses ?? []) {
+                  if (!targetTransition.from.includes(status)) {
+                    add(
+                      ep,
+                      `cascade status ${status} is not an allowed from-state for ${target.id}.${entry.action}`,
+                    );
+                  }
+                }
+              }
+            }
+          }
+          if ("inputField" in entry && entry.inputField !== undefined) {
+            const reservedFields = new Set([
+              "tenantId",
+              "productId",
+              "actorAccountId",
+              instrumentInstanceKey(instrument.id),
+            ]);
+            if (reservedFields.has(entry.inputField)) {
+              add(
+                ep,
+                `cascade inputField ${entry.inputField} collides with a reserved field`,
+              );
+            }
+            if (Object.hasOwn(instrument.fields, entry.inputField)) {
+              add(
+                ep,
+                `cascade inputField ${entry.inputField} collides with an instrument field`,
+              );
+            }
+            if (
+              Object.hasOwn(object(action.input?.properties), entry.inputField)
+            ) {
+              add(
+                ep,
+                `cascade inputField ${entry.inputField} collides with an action input property`,
+              );
+            }
+            if (seenInputFields.has(entry.inputField)) {
+              add(ep, `cascade inputField ${entry.inputField} is repeated`);
+            }
+            seenInputFields.add(entry.inputField);
+          }
+        }
+      }
       if (action.allocate || action.contributionStage) {
         if (
           name === "create" ||