@hyperscale0/hsx 1.0.0-beta.1 → 1.0.0-rc.1

package/src/emit.ts

@@ -0,0 +1,447 @@
+import {
+  serializeUdl,
+  validateUdl,
+  type UdlDocument,
+  type UdlIssueCode,
+} from "@hyperscale0/udl";
+import type { JsonValue, TypedInstrument, TypedProgram } from "./ir.ts";
+
+export interface OriginMapEntry {
+  readonly path: string;
+  readonly span: { readonly end: number; readonly start: number };
+}
+
+export interface GeneralLoweringIssue {
+  readonly code: string;
+  readonly fix: string;
+  readonly message: string;
+  readonly path: string;
+  readonly span: { readonly end: number; readonly start: number };
+  readonly udlCode: UdlIssueCode;
+}
+
+export type GeneralLowerResult =
+  | { readonly issues: readonly GeneralLoweringIssue[]; readonly ok: false }
+  | {
+      readonly ok: true;
+      readonly value: {
+        readonly canonicalUdl: string;
+        readonly document: UdlDocument;
+        readonly frame: Record<string, JsonValue>;
+        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),
+    })),
+    product: program.name,
+    subjects: program.subjects.map((subject) => ({
+      declaredValue: subject.declaredValue,
+      kind: subject.kind,
+      schema: subject.schema,
+      title: subject.title,
+      version: subject.version,
+    })),
+    title: program.title,
+    udl: 1,
+    version: 1,
+  };
+  const frame = frameFor(program);
+  const unresolved = [
+    ...unresolvedCompilerMarkers(candidate),
+    ...unresolvedCompilerMarkers(frame, "$.frame"),
+  ];
+  if (unresolved.length > 0) {
+    const origins = originMapFor(program);
+    return {
+      issues: unresolved.map(({ marker, path }) => ({
+        code: "HSX1603",
+        fix: "correct the compile-time block keys or parameter bindings",
+        message: `${path}: emitted value contains unresolved compiler marker ${marker}`,
+        path,
+        span: originForUdlPath(path, origins)?.span ?? program.origin,
+        udlCode: "UDL1003",
+      })),
+      ok: false,
+    };
+  }
+  const validation = validateUdl(candidate);
+  if (!validation.ok) {
+    const origins = originMapFor(program);
+    return {
+      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",
+          message: `${issue.path}: ${issue.message}`,
+          path: issue.path,
+          span: origin?.span ?? program.origin,
+          udlCode: issue.code,
+        };
+      }),
+      ok: false,
+    };
+  }
+  const document = validation.value;
+  return {
+    ok: true,
+    value: {
+      canonicalUdl: serializeUdl(document),
+      document,
+      frame,
+      originMap: originMapFor(program),
+    },
+  };
+}
+
+const COMPILER_MARKERS = ["__hsx_none__", "invalid_compile_time_name"] as const;
+
+function unresolvedCompilerMarkers(
+  value: unknown,
+  path = "$",
+): readonly { readonly marker: string; readonly path: string }[] {
+  if (typeof value === "string") {
+    return COMPILER_MARKERS.filter((marker) => value.includes(marker)).map(
+      (marker) => ({ marker, path }),
+    );
+  }
+  if (Array.isArray(value)) {
+    return value.flatMap((item, index) =>
+      unresolvedCompilerMarkers(item, `${path}[${index}]`),
+    );
+  }
+  if (!value || typeof value !== "object") return [];
+  return Object.entries(value).flatMap(([key, item]) => {
+    const childPath = /^[A-Za-z_][A-Za-z0-9_]*$/.test(key)
+      ? `${path}.${key}`
+      : `${path}[${JSON.stringify(key)}]`;
+    const keyIssues = COMPILER_MARKERS.filter((marker) =>
+      key.includes(marker),
+    ).map((marker) => ({ marker, path: childPath }));
+    return [...keyIssues, ...unresolvedCompilerMarkers(item, childPath)];
+  });
+}
+
+function originForUdlPath(
+  path: string,
+  origins: readonly OriginMapEntry[],
+): OriginMapEntry | undefined {
+  return (
+    [...origins]
+      .filter(
+        (entry) =>
+          path === entry.path ||
+          path.startsWith(`${entry.path}.`) ||
+          path.startsWith(`${entry.path}[`),
+      )
+      .sort((left, right) => right.path.length - left.path.length)[0] ??
+    origins.find((entry) => entry.path === "$")
+  );
+}
+
+export function requiredFields(instrument: TypedInstrument): string[] {
+  const explicit = instrument.slots.required;
+  if (
+    Array.isArray(explicit) &&
+    explicit.every((field): field is string => typeof field === "string")
+  ) {
+    return [...explicit];
+  }
+  const required = new Set(
+    instrument.fields
+      .filter((field) => field.required)
+      .map((field) => field.name),
+  );
+  const partyFields =
+    instrument.slots.parties &&
+    typeof instrument.slots.parties === "object" &&
+    !Array.isArray(instrument.slots.parties)
+      ? Object.values(instrument.slots.parties).filter(
+          (value): value is string =>
+            typeof value === "string" && required.has(value),
+        )
+      : [];
+  return [
+    ...new Set(partyFields),
+    ...instrument.fields
+      .map((field) => field.name)
+      .filter((name) => required.has(name) && !partyFields.includes(name)),
+  ];
+}
+
+function frameFor(program: TypedProgram): Record<string, JsonValue> {
+  const actors = new Map<string, Record<string, JsonValue>>();
+  const moneyEvents: Record<string, JsonValue>[] = [];
+  const design: string[] = [];
+  const fees: Record<string, JsonValue>[] = [];
+  const mechanics = new Set<string>();
+  const eventKeys = new Set<string>();
+  const ensureActor = (rawKey: string, role: string): string => {
+    const key = frameKey(rawKey);
+    if (!actors.has(key)) {
+      actors.set(key, {
+        key,
+        label: titleize(key),
+        maxCount: 1,
+        minCount: 1,
+        role,
+      });
+    }
+    return key;
+  };
+  const uniqueEventKey = (raw: string): string => {
+    const base = frameKey(raw);
+    let key = base;
+    let ordinal = 2;
+    while (eventKeys.has(key)) {
+      const suffix = `_${ordinal}`;
+      key = `${base.slice(0, 40 - suffix.length)}${suffix}`;
+      ordinal += 1;
+    }
+    eventKeys.add(key);
+    return key;
+  };
+  for (const instrument of program.instruments) {
+    const actorByField = new Map<string, string>();
+    const parties = instrument.slots.parties;
+    if (parties && typeof parties === "object" && !Array.isArray(parties)) {
+      for (const [role, value] of Object.entries(parties)) {
+        if (typeof value !== "string") continue;
+        const actor = ensureActor(role, frameActorRole(role, "source"));
+        actorByField.set(value, actor);
+      }
+    }
+    for (const action of instrument.actions) {
+      if (action.slots.due) mechanics.add("recurring_billing");
+      const moves = action.slots.moves;
+      if (!Array.isArray(moves)) continue;
+      moves.forEach((move, index) => {
+        if (moneyEvents.length >= 20) return;
+        if (!move || typeof move !== "object" || Array.isArray(move)) return;
+        const bind =
+          move.bind &&
+          typeof move.bind === "object" &&
+          !Array.isArray(move.bind)
+            ? move.bind
+            : {};
+        const source = frameActorForBinding(
+          bind.sourceAccountId,
+          actorByField,
+          "source",
+          ensureActor,
+        );
+        const destination = frameActorForBinding(
+          bind.destinationAccountId,
+          actorByField,
+          "destination",
+          ensureActor,
+        );
+        const operation =
+          typeof move.operation === "string" ? move.operation : "transfer";
+        if (source === "escrow" || destination === "escrow") {
+          mechanics.add("escrow");
+        }
+        moneyEvents.push({
+          allocationTotalBps: 0,
+          amount: bindingWords(bind.amount) || "the declared amount",
+          amountDependencies: [],
+          amountMode: "fixed",
+          amountSchedule: [],
+          distribution: "single",
+          fromActor: source,
+          key: uniqueEventKey(
+            typeof move.key === "string"
+              ? move.key
+              : `${instrument.id}_${action.name}_${index + 1}`,
+          ),
+          kind: frameEventKind(operation, source, destination),
+          label: `${titleize(action.name)} movement`,
+          occurrence: action.slots.due ? "repeatable" : "once",
+          timing: action.name === "create" ? "on_create" : "on_lifecycle",
+          toActor: destination,
+          trigger: `when ${action.name.replaceAll("_", " ")} runs`,
+        });
+      });
+    }
+    if (design.length < 10) {
+      design.push(
+        `${instrument.id}: ${instrument.fields.length} fields and ${instrument.actions.length} actions`,
+      );
+    }
+    const feeRules = instrument.slots.feeRules;
+    if (Array.isArray(feeRules)) {
+      feeRules.forEach((fee, index) => {
+        if (fees.length >= 4) return;
+        if (!fee || typeof fee !== "object" || Array.isArray(fee)) return;
+        fees.push({
+          label: `${titleize(instrument.id)} fee ${index + 1}`,
+          on:
+            typeof fee.baseField === "string"
+              ? fee.baseField
+              : `${instrument.id} movement`,
+          structure:
+            typeof fee.position === "string"
+              ? `${fee.position.replaceAll("_", " ")} fee`
+              : "declared fee",
+        });
+      });
+    }
+  }
+  if (actors.size === 0) ensureActor("platform", "platform");
+  if (moneyEvents.length === 0) {
+    const actor = actors.keys().next().value ?? "platform";
+    moneyEvents.push({
+      allocationTotalBps: 0,
+      amount: "the declared settlement amount",
+      amountDependencies: [],
+      amountMode: "fixed",
+      amountSchedule: [],
+      distribution: "single",
+      fromActor: actor,
+      key: uniqueEventKey(`${program.name}_create`),
+      kind: "charge",
+      label: `${program.title} movement`,
+      occurrence: "once",
+      timing: "on_create",
+      toActor: actor,
+      trigger: "when the settlement is created",
+    });
+  }
+  if (mechanics.size === 0) mechanics.add("escrow");
+  return {
+    actors: [...actors.values()],
+    confidence: "high",
+    conservationGroups: [],
+    design,
+    feePolicy: fees.length > 0 ? "defined" : "none",
+    fees,
+    headline: program.title,
+    mechanics: [...mechanics],
+    moneyEvents,
+    offPlatform: [],
+    openQuestions: [],
+    rules: [],
+    subjects: program.subjects.map((subject) => ({
+      kind: subject.kind,
+      title: subject.title,
+    })),
+    summary: `${program.title} compiles ${program.instruments.length} financial instrument${program.instruments.length === 1 ? "" : "s"}.`,
+  };
+}
+
+function frameActorForBinding(
+  value: JsonValue | undefined,
+  actorByField: ReadonlyMap<string, string>,
+  direction: "destination" | "source",
+  ensureActor: (key: string, role: string) => string,
+): string {
+  const path = bindingWords(value);
+  if (path.includes("escrowAccountId")) return "escrow";
+  const field = path.startsWith("fields.")
+    ? path.slice("fields.".length)
+    : path;
+  const declared = actorByField.get(field);
+  if (declared) return declared;
+  if (field.toLowerCase().includes("platform")) {
+    return ensureActor("platform", "platform");
+  }
+  return ensureActor(
+    direction === "source" ? "payer" : "beneficiary",
+    direction === "source" ? "payer" : "beneficiary",
+  );
+}
+
+function frameActorRole(
+  role: string,
+  direction: "destination" | "source",
+): string {
+  return [
+    "payer",
+    "beneficiary",
+    "platform",
+    "provider",
+    "guardian",
+    "holder",
+  ].includes(role)
+    ? role
+    : direction === "source"
+      ? "payer"
+      : "beneficiary";
+}
+
+function frameEventKind(
+  operation: string,
+  source: string,
+  destination: string,
+): string {
+  if (operation.endsWith(".reserve")) return "hold";
+  if (operation.endsWith(".void") || operation.endsWith(".return")) {
+    return "refund";
+  }
+  if (operation.startsWith("payout.")) return "payout";
+  if (source === "escrow" || destination === "escrow") return "release";
+  return "charge";
+}
+
+function frameKey(value: string): string {
+  const snake = value
+    .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+    .replace(/[^A-Za-z0-9]+/g, "_")
+    .replace(/^_+|_+$/g, "")
+    .toLowerCase();
+  const leading = /^[a-z]/.test(snake) ? snake : `event_${snake}`;
+  return leading.slice(0, 40) || "event";
+}
+
+function bindingWords(value: JsonValue | undefined): string {
+  if (typeof value === "string") return value;
+  if (!value || typeof value !== "object" || Array.isArray(value)) return "";
+  const binding = value as Readonly<Record<string, JsonValue>>;
+  if (binding.from === "const" && typeof binding.value === "string")
+    return binding.value;
+  if (typeof binding.path === "string") return binding.path;
+  return "";
+}
+
+function originMapFor(program: TypedProgram): OriginMapEntry[] {
+  const entries: OriginMapEntry[] = [{ path: "$", span: program.origin }];
+  program.subjects.forEach((subject, index) => {
+    entries.push({ path: `$.subjects[${index}]`, span: subject.origin });
+  });
+  program.instruments.forEach((instrument, index) => {
+    const base = `$.instruments[${index}]`;
+    entries.push({ path: base, span: instrument.origin });
+    instrument.fields.forEach((field) => {
+      entries.push({
+        path: `${base}.fields.${field.name}`,
+        span: field.origin,
+      });
+    });
+    instrument.actions.forEach((action) => {
+      entries.push({
+        path: `${base}.actions.${action.name}`,
+        span: action.origin,
+      });
+    });
+  });
+  return entries;
+}
+
+function titleize(value: string): string {
+  return value
+    .replaceAll("_", " ")
+    .replace(/\b[a-z]/g, (letter) => letter.toUpperCase());
+}