@hyperscale0/hsx 2.0.4 → 2.1.0

package/src/cost.ts

@@ -1,5 +1,6 @@
 import {
   udlEffectKinds,
+  resolveUdlActionPlans,
   type UdlDocument,
   type UdlEffectKind,
 } from "@hyperscale0/udl";
@@ -247,8 +248,17 @@ export function buildUdlCostManifest(
   const rowsBySignature = indexCostRows(table);
   const actions: UdlCostManifest["actions"][number][] = [];
   for (const instrument of document.instruments) {
-    for (const [actionName, action] of Object.entries(instrument.actions)) {
-      const effects = (action.effects ?? {}) as Readonly<
+    const resolved = resolveUdlActionPlans(instrument);
+    if (resolved.issues.length > 0)
+      throw new Error(resolved.issues[0]!.message);
+    for (const actionName of instrument.actionOrder) {
+      const action = instrument.actions[actionName]!;
+      const plan = resolved.plans.find(
+        (candidate) => candidate.action === actionName,
+      );
+      const effects = (
+        action.calls && plan ? plan.effects : (action.effects ?? {})
+      ) as Readonly<
         Partial<
           Record<
             HsxEffectKind,
@@ -526,7 +536,15 @@ function typedStructuralCounts(
     aggregate += arrayValue(instrument.slots.aggregateInvariants).length;
     for (const action of instrument.actions) {
       flow += 1;
-      move += arrayValue(action.slots.moves).length;
+      const plan = instrument.actionPlans?.find(
+        (plan) => plan.action === action.name,
+      );
+      move +=
+        action.slots.calls && plan
+          ? plan.leaves.filter((leaf) =>
+              leaf.step.operation.startsWith("internal_transfer."),
+            ).length
+          : arrayValue(action.slots.moves).length;
       gate += arrayValue(action.slots.requiresRefs).length;
       if (action.slots.deadline !== undefined) timer += 1;
       if (action.slots.due !== undefined) timer += 1;
@@ -565,9 +583,18 @@ function udlStructuralCounts(
     if (Object.values(instrument.actions).some((action) => action.quote))
       unwind += 1;
     aggregate += instrument.aggregateInvariants?.length ?? 0;
-    for (const action of Object.values(instrument.actions)) {
+    const resolved = resolveUdlActionPlans(instrument);
+    if (resolved.issues.length > 0)
+      throw new Error(resolved.issues[0]!.message);
+    for (const [name, action] of Object.entries(instrument.actions)) {
       flow += 1;
-      move += action.moves.length;
+      const plan = resolved.plans.find((plan) => plan.action === name);
+      move +=
+        action.calls && plan
+          ? plan.leaves.filter((leaf) =>
+              leaf.step.operation.startsWith("internal_transfer."),
+            ).length
+          : action.moves.length;
       gate += action.requiresRefs?.length ?? 0;
       if (action.deadline) timer += 1;
       if (action.due) timer += 1;

package/src/diagnostics.ts

@@ -543,4 +543,71 @@ instrument probe {
     fix: "Correct compile-time block keys or parameter bindings.",
     example: instrument('title: "__hsx_none__";'),
   },
+  {
+    code: "HSX1610",
+    stage: "typecheck",
+    title: "Invalid piece partition",
+    fix: "Bind immutable money and account fields to one declared partition.",
+    example: null,
+    reason:
+      "The shared UDL action-plan validator supplies the code and source path.",
+  },
+  {
+    code: "HSX1611",
+    stage: "typecheck",
+    title: "Invalid piece stage",
+    fix: "Use a declared piece stage and let the compiler derive pieceId.",
+    example: null,
+    reason:
+      "The shared UDL action-plan validator supplies the code and source path.",
+  },
+  {
+    code: "HSX1612",
+    stage: "typecheck",
+    title: "Invalid action graph",
+    fix: "Declare an acyclic action graph within the expansion bound.",
+    example: null,
+    reason:
+      "The shared UDL action-plan validator supplies the code and source path.",
+  },
+  {
+    code: "HSX1613",
+    stage: "typecheck",
+    title: "Invalid static call binding",
+    fix: "Bind declared typed targets with unique captures and money consumption.",
+    example: null,
+    reason:
+      "The shared UDL action-plan validator supplies the code and source path.",
+  },
+  {
+    code: "HSX1614",
+    stage: "typecheck",
+    title: "Incompatible action boundary",
+    fix: "Keep the parent principal, approval and recovery boundary.",
+    example: null,
+    reason:
+      "The shared UDL action-plan validator supplies the code and source path.",
+  },
+  {
+    code: "HSX1615",
+    stage: "typecheck",
+    title: "Invalid leaf evidence or effects",
+    fix: "Declare evidence and the exact effects of each expanded leaf.",
+    example: null,
+    reason:
+      "The shared UDL action-plan validator supplies the code and source path.",
+  },
 ] as const;
+
+/** Preserve the UDL diagnostic family when reporting a typed clause. */
+export function hsxClauseDiagnosticCode(code: string): string {
+  const codes: Readonly<Record<string, string>> = {
+    UDL4002: "HSX1610",
+    UDL5013: "HSX1611",
+    UDL2010: "HSX1612",
+    UDL2011: "HSX1613",
+    UDL2012: "HSX1614",
+    UDL2013: "HSX1615",
+  };
+  return codes[code] ?? "HSX1602";
+}

package/src/emit.ts

@@ -1,9 +1,18 @@
 import {
   validateUdl,
+  resolveUdlActionPlans,
+  udlClauseVocabulary,
   type UdlDocument,
   type UdlIssueCode,
 } from "@hyperscale0/udl";
-import type { TypedInstrument, TypedProgram } from "./ir.ts";
+import type {
+  JsonValue,
+  TypedInstrument,
+  TypedProgram,
+  ResolvedProgramActionPlan,
+} from "./ir.ts";
+
+import { hsxClauseDiagnosticCode } from "./diagnostics.ts";
 
 export interface OriginMapEntry {
   readonly path: string;
@@ -25,24 +34,14 @@ export type GeneralLowerResult =
       readonly ok: true;
       readonly value: {
         readonly document: UdlDocument;
+        readonly actionPlans?: readonly ResolvedProgramActionPlan[];
         readonly originMap: readonly OriginMapEntry[];
       };
     };
 
 export function lowerGeneralProgram(program: TypedProgram): GeneralLowerResult {
   const candidate = {
-    instruments: program.instruments.map((instrument) => ({
-      ...instrument.slots,
-      actionOrder: instrument.actions.map((action) => action.name),
-      actions: Object.fromEntries(
-        instrument.actions.map((action) => [action.name, action.slots]),
-      ),
-      fields: Object.fromEntries(
-        instrument.fields.map((field) => [field.name, field.schema]),
-      ),
-      id: instrument.id,
-      required: requiredFields(instrument),
-    })),
+    instruments: program.instruments.map(generalInstrumentValue),
     product: program.name,
     subjects: program.subjects.map((subject) => ({
       declaredValue: subject.declaredValue,
@@ -79,8 +78,11 @@ export function lowerGeneralProgram(program: TypedProgram): GeneralLowerResult {
       issues: validation.issues.map((issue) => {
         const origin = originForUdlPath(issue.path, origins);
         return {
-          code: issue.category === "invalid_semantics" ? "HSX1602" : "HSX1601",
-          fix: "correct the named clause so it matches the targeted UDL definition",
+          code:
+            issue.category === "invalid_semantics"
+              ? hsxClauseDiagnosticCode(issue.code)
+              : "HSX1601",
+          fix: issue.fix,
           message: `${issue.path}: ${issue.message}`,
           path: issue.path,
           span: origin?.span ?? program.origin,
@@ -91,10 +93,17 @@ export function lowerGeneralProgram(program: TypedProgram): GeneralLowerResult {
     };
   }
   const document = validation.value;
+  const actionPlans = document.instruments.flatMap((instrument) =>
+    resolveUdlActionPlans(instrument).plans.map((plan) => ({
+      ...plan,
+      instrument: instrument.id,
+    })),
+  );
   return {
     ok: true,
     value: {
       document,
+      ...(actionPlans.length > 0 ? { actionPlans } : {}),
       originMap: originMapFor(program),
     },
   };
@@ -213,3 +222,61 @@ function originMapFor(program: TypedProgram): OriginMapEntry[] {
   });
   return entries;
 }
+
+/** Emit a canonical clause value through the same generic HSX block syntax. */
+export function emitUdlClause(
+  scope: "instrument" | "action",
+  target: string,
+  value: JsonValue,
+): string {
+  const clause = udlClauseVocabulary.find(
+    (entry) => entry.scope === scope && entry.target === target,
+  );
+  if (!clause) throw new Error(`Unknown ${scope} clause ${target}`);
+  return `${clause.spelling.replaceAll(" ", "_")}: ${clauseLiteral(value)};`;
+}
+
+function clauseLiteral(value: JsonValue): string {
+  if (Array.isArray(value)) return `[${value.map(clauseLiteral).join(", ")}]`;
+  if (value !== null && typeof value === "object") {
+    return `{ ${Object.entries(value)
+      .map(([key, item]) => `${JSON.stringify(key)}: ${clauseLiteral(item)};`)
+      .join(" ")} }`;
+  }
+  if (
+    value === null ||
+    (typeof value === "number" && !Number.isSafeInteger(value))
+  ) {
+    throw new Error(
+      "HSX clause literals require non-null values and safe integers",
+    );
+  }
+  return JSON.stringify(value);
+}
+
+export function hasActionPlanClauses(instrument: TypedInstrument): boolean {
+  return (
+    instrument.slots.piecePlan !== undefined ||
+    instrument.slots.actionLibrary !== undefined ||
+    instrument.actions.some(
+      (action) =>
+        action.slots.calls !== undefined ||
+        action.slots.pieceStage !== undefined,
+    )
+  );
+}
+
+export function generalInstrumentValue(instrument: TypedInstrument) {
+  return {
+    ...instrument.slots,
+    actionOrder: instrument.actions.map((action) => action.name),
+    actions: Object.fromEntries(
+      instrument.actions.map((action) => [action.name, action.slots]),
+    ),
+    fields: Object.fromEntries(
+      instrument.fields.map((field) => [field.name, field.schema]),
+    ),
+    id: instrument.id,
+    required: requiredFields(instrument),
+  };
+}

package/src/index.ts

@@ -28,7 +28,11 @@ export {
   type ProgramEntryOverrideValue,
 } from "./entry-overrides.ts";
 export { type OriginMapEntry } from "./emit.ts";
-export { lowerGeneralProgram, originForUdlPath } from "./emit.ts";
+export {
+  lowerGeneralProgram,
+  originForUdlPath,
+  emitUdlClause,
+} from "./emit.ts";
 export { parseProgram } from "./parse.ts";
 export { checkGeneralProgram, type GeneralCheckOptions } from "./typecheck.ts";
 export {
@@ -40,3 +44,4 @@ export {
   type UseDecl,
 } from "./ast.ts";
 export { bundledStandardLibrary, type StandardLibrary } from "./std-library.ts";
+export type { ResolvedActionPlan, ResolvedProgramActionPlan } from "./ir.ts";

package/src/ir.ts

@@ -1,5 +1,9 @@
 import type { Span } from "./ast.ts";
-import type { UdlEffectKind } from "@hyperscale0/udl";
+import type {
+  resolveUdlActionPlans,
+  UdlEffectKind,
+  UdlIssueCode,
+} from "@hyperscale0/udl";
 
 export type JsonValue =
   | boolean
@@ -59,7 +63,15 @@ export interface TypedAction {
   readonly slots: Readonly<Record<string, JsonValue>>;
 }
 
+export type ResolvedActionPlan = ReturnType<
+  typeof resolveUdlActionPlans
+>["plans"][number];
+export type ResolvedProgramActionPlan = ResolvedActionPlan & {
+  readonly instrument: string;
+};
+
 export interface TypedInstrument {
+  readonly actionPlans?: readonly ResolvedActionPlan[];
   readonly actions: readonly TypedAction[];
   readonly fields: readonly TypedField[];
   readonly id: string;
@@ -86,6 +98,8 @@ export interface TypedProgram {
 }
 
 export interface GeneralDiagnostic {
+  readonly path?: string;
+  readonly udlCode?: UdlIssueCode;
   readonly code: string;
   readonly fix: string;
   readonly message: string;

package/src/limits.ts

@@ -6,6 +6,8 @@
  * on. The deepest nests 5 levels; the largest is 13,934 bytes.
  */
 export const HSX_LIMITS = Object.freeze({
+  /** Shared ceiling for finite comprehensions and action-call expansion. */
+  maxExpansions: 256,
   /**
    * How deep the recursive-descent productions may nest. Measured on this
    * machine, the parser exhausted the call stack at 9,217 nested blocks and

package/src/typecheck.ts

@@ -1,5 +1,7 @@
 import {
   deriveUdlActionEffects,
+  resolveUdlActionPlans,
+  udlDocumentSchema,
   udlClauseVocabulary,
   type UdlAction,
   type UdlDocument,
@@ -24,7 +26,14 @@ import type {
   SubjectDecl,
   UseDecl,
 } from "./ast.ts";
-import { requiredFields } from "./emit.ts";
+import {
+  requiredFields,
+  generalInstrumentValue,
+  hasActionPlanClauses,
+  lowerGeneralProgram,
+} from "./emit.ts";
+import { hsxClauseDiagnosticCode } from "./diagnostics.ts";
+import { HSX_LIMITS } from "./limits.ts";
 import type {
   GeneralCheckResult,
   GeneralDiagnostic,
@@ -43,7 +52,7 @@ const CURRENCY = /^[A-Z]{3}$/;
 const MONEY_PATTERN = "^[1-9][0-9]{0,17}$";
 const OPTIONAL_MONEY_PATTERN = "^(0|[1-9][0-9]{0,17})$";
 const ACCOUNT_PATTERN = "^acct_(sandbox|live)_[a-z0-9]{8,64}$";
-const MAX_COMPREHENSION_EXPANSIONS = 256;
+
 const NONE_SENTINEL = "__hsx_none__";
 
 export interface GeneralCheckOptions {
@@ -517,7 +526,7 @@ export function checkGeneralProgram(
     subjects,
     title: header?.title?.value ?? sentenceCase(name),
   };
-  return { diagnostics, program: typed };
+  return prepareActionPlanProgram(typed, diagnostics);
 }
 
 function checkPublishedProgram(
@@ -766,7 +775,7 @@ function checkPublishedProgram(
     ],
     title: header?.title?.value ?? sentenceCase(name),
   };
-  return { diagnostics, program: typed };
+  return prepareActionPlanProgram(typed, diagnostics);
 }
 
 function projectedPublishedInstrument(
@@ -3014,11 +3023,11 @@ function expandComprehensions(
         });
         continue;
       }
-      if (budget.used + values.length > MAX_COMPREHENSION_EXPANSIONS) {
+      if (budget.used + values.length > HSX_LIMITS.maxExpansions) {
         diagnostics.push({
           code: "HSX1404",
-          fix: `reduce the fixed expansion to at most ${MAX_COMPREHENSION_EXPANSIONS} rows`,
-          message: `bounded comprehensions expand past the ${MAX_COMPREHENSION_EXPANSIONS}-row compiler limit`,
+          fix: `reduce the fixed expansion to at most ${HSX_LIMITS.maxExpansions} rows`,
+          message: `bounded comprehensions expand past the ${HSX_LIMITS.maxExpansions}-row compiler limit`,
           severity: "error",
           span: bound.span,
         });
@@ -3481,7 +3490,10 @@ function checkInstrument(
     ];
   }
 
-  return { actions, fields, id: name.name, origin: name.span, slots };
+  return derivePieceInputs(
+    { actions, fields, id: name.name, origin: name.span, slots },
+    diagnostics,
+  );
 }
 
 // Mirrors the catalog law agent_description_required: every action a caller
@@ -4787,6 +4799,7 @@ function blockToObject(
   block: BlockExpr | undefined,
   substitutions: ReadonlyMap<string, Expr>,
   diagnostics: GeneralDiagnostic[],
+  literalKeys = false,
 ): Record<string, JsonValue> {
   if (!block) return {};
   const result: Record<string, JsonValue> = {};
@@ -4802,10 +4815,8 @@ function blockToObject(
       });
       continue;
     }
-    result[row.key.quoted ? row.key.name : camel(row.key.name)] = exprToJson(
-      value,
-      diagnostics,
-    );
+    result[literalKeys || row.key.quoted ? row.key.name : camel(row.key.name)] =
+      exprToJson(value, diagnostics, literalKeys);
   }
   return result;
 }
@@ -4832,10 +4843,21 @@ function exprToJsonForUdlSlot(
       ]),
     );
   }
-  return exprToJson(expr, diagnostics);
+  // Declaration maps retain their authored keys; field-spelling aliases still normalize.
+  const literalKeys = udlClauseVocabulary.some(
+    (clause) =>
+      clause.target === slot &&
+      "literalKeys" in clause &&
+      clause.literalKeys === true,
+  );
+  return exprToJson(expr, diagnostics, literalKeys);
 }
 
-function exprToJson(expr: Expr, diagnostics: GeneralDiagnostic[]): JsonValue {
+function exprToJson(
+  expr: Expr,
+  diagnostics: GeneralDiagnostic[],
+  literalKeys = false,
+): JsonValue {
   switch (expr.kind) {
     case "boolean":
       return expr.value;
@@ -4880,9 +4902,11 @@ function exprToJson(expr: Expr, diagnostics: GeneralDiagnostic[]): JsonValue {
     case "settlement_ref":
       return `${expr.owner.name}.${expr.member.name}`;
     case "list":
-      return expr.items.map((item) => exprToJson(item, diagnostics));
+      return expr.items.map((item) =>
+        exprToJson(item, diagnostics, literalKeys),
+      );
     case "block":
-      return blockToObject(expr, new Map(), diagnostics);
+      return blockToObject(expr, new Map(), diagnostics, literalKeys);
     case "call":
       return `${expr.callee.name}(${expr.args.map((arg) => String(exprToJson(arg, diagnostics))).join(",")})`;
     case "type_apply":
@@ -5055,3 +5079,110 @@ function sentenceCase(value: string): string {
   const words = value.replaceAll("_", " ");
   return `${words[0]?.toUpperCase() ?? ""}${words.slice(1)}`;
 }
+
+function prepareActionPlanProgram(
+  program: TypedProgram,
+  diagnostics: GeneralDiagnostic[],
+): GeneralCheckResult {
+  if (!program.instruments.some(hasActionPlanClauses))
+    return { diagnostics, program };
+  const instruments = program.instruments.map((instrument): TypedInstrument => {
+    if (!hasActionPlanClauses(instrument)) return instrument;
+    const parsed = udlDocumentSchema.shape.instruments.element.safeParse(
+      generalInstrumentValue(instrument),
+    );
+    if (!parsed.success) {
+      for (const issue of parsed.error.issues)
+        diagnostics.push({
+          code: "HSX1601",
+          severity: "error",
+          span: instrument.origin,
+          message: `${instrument.id}.${issue.path.join(".")}: ${issue.message}`,
+          fix: "match the typed UDL clause declaration",
+        });
+      return instrument;
+    }
+    const resolved = resolveUdlActionPlans(parsed.data);
+    for (const issue of resolved.issues)
+      diagnostics.push({
+        code: hsxClauseDiagnosticCode(issue.code),
+        severity: "error",
+        span: instrument.origin,
+        message: `${instrument.id}${issue.path}: ${issue.message}`,
+        udlCode: issue.code,
+        path: issue.path,
+        fix: issue.fix,
+      });
+    return {
+      ...instrument,
+      actionPlans: resolved.plans,
+      actions: instrument.actions.map((action) => {
+        if (!action.slots.calls) return action;
+        const plan = resolved.plans.find((plan) => plan.action === action.name);
+        if (!plan) return action;
+        const effects = plan.effects;
+        return {
+          ...action,
+          effects,
+          slots: { ...action.slots, effects: effects as JsonValue },
+        };
+      }),
+    };
+  });
+  if (diagnostics.some((issue) => issue.severity === "error"))
+    return { diagnostics };
+  const prepared = { ...program, instruments };
+  const lowered = lowerGeneralProgram(prepared);
+  if (!lowered.ok) {
+    for (const issue of lowered.issues)
+      diagnostics.push({
+        code: issue.code,
+        fix: issue.fix,
+        message: issue.message,
+        udlCode: issue.udlCode,
+        path: issue.path,
+        severity: "error",
+        span: issue.span,
+      });
+    return { diagnostics };
+  }
+  return { diagnostics, program: prepared };
+}
+
+function derivePieceInputs(
+  instrument: TypedInstrument,
+  diagnostics: GeneralDiagnostic[],
+): TypedInstrument {
+  return {
+    ...instrument,
+    actions: instrument.actions.map((action) => {
+      const stage = jsonObject(action.slots.pieceStage);
+      if (!stage) return action;
+      if (action.slots.input !== undefined) {
+        diagnostics.push({
+          code: "HSX1611",
+          severity: "error",
+          span: action.origin,
+          message: `action ${action.name} overrides its compiler-derived pieceId input`,
+          fix: "remove input; piece_stage derives the strict pieceId enum",
+        });
+        return action;
+      }
+      const plan = jsonObject(instrument.slots.piecePlan);
+      const order = plan?.[`${stage.stage}_order`];
+      if (!Array.isArray(order) || order.length === 0) return action;
+      return {
+        ...action,
+        slots: {
+          ...action.slots,
+          input: {
+            type: "object",
+            additionalProperties: false,
+            required: ["pieceId"],
+            properties: { pieceId: { type: "string", enum: order } },
+          },
+        },
+      };
+    }),
+  };
+}

package/src/version.ts

@@ -1,5 +1,5 @@
 /** Package version reported by the command line. */
-export const HSX_VERSION = "2.0.3";
+export const HSX_VERSION = "2.1.0";
 
 /** Canonical UDL contract version emitted by this compiler. */
 export const HSX_TARGET_UDL_VERSION = 1;