@hyperscale0/hsx 2.0.3 → 2.0.4

package/src/typecheck.ts

@@ -1,6 +1,7 @@
 import {
   deriveUdlActionEffects,
   udlClauseVocabulary,
+  type UdlAction,
   type UdlDocument,
   type UdlInstrument,
 } from "@hyperscale0/udl";
@@ -54,6 +55,7 @@ type ClauseDefinition = (typeof udlClauseVocabulary)[number];
 interface ConcreteInstrument {
   readonly aliases: ReadonlyMap<string, Expr>;
   readonly body: BlockExpr;
+  readonly callee?: string;
   readonly generatedPrefix: boolean;
   readonly name: IdentExpr;
   readonly parties: ReadonlySet<string>;
@@ -350,6 +352,7 @@ export function checkGeneralProgram(
         ).map((candidate) => ({
           ...candidate,
           aliases: scoped.aliases,
+          callee: candidate.name.name,
           parties: scoped.parties,
         })),
       );
@@ -397,11 +400,21 @@ export function checkGeneralProgram(
           constructedInstruments(decl.name, merged, diagnostics),
           boundPorts,
           applicationPorts,
-        ).map((candidate) => ({
-          ...candidate,
-          aliases: scoped.aliases,
-          parties: scoped.parties,
-        })),
+        ).map((candidate) => {
+          let candidateCallee = callee;
+          if (
+            candidate.name.name !== decl.name.name &&
+            candidate.name.name.startsWith(`${decl.name.name}_`)
+          ) {
+            candidateCallee = `${callee}${candidate.name.name.slice(decl.name.name.length)}`;
+          }
+          return {
+            ...candidate,
+            aliases: scoped.aliases,
+            callee: candidateCallee,
+            parties: scoped.parties,
+          };
+        }),
       );
       for (const port of boundPorts.values()) {
         if (applicationPorts.has(port)) reachedPorts.add(port);
@@ -422,6 +435,15 @@ export function checkGeneralProgram(
 
   const allocated = allocateGeneratedPrefixes(concrete);
 
+  if (options.publishedCatalog) {
+    checkPortCaptureTypes(
+      allocated,
+      options.publishedCatalog,
+      aliases,
+      diagnostics,
+    );
+  }
+
   const instruments: TypedInstrument[] = [];
   const ids = new Set<string>();
   for (const candidate of allocated) {
@@ -913,6 +935,149 @@ function publishedFieldType(
   return target ? { kind: "ref", target: target.id } : { kind: "text" };
 }
 
+const STRING_BACKED_PORT_KINDS: ReadonlySet<HsxType["kind"]> = new Set([
+  "account",
+  "condition",
+  "date",
+  "party",
+  "ref",
+  "text",
+]);
+const INTEGER_BACKED_PORT_KINDS: ReadonlySet<HsxType["kind"]> = new Set([
+  "bps",
+  "integer",
+  "percent",
+]);
+
+/**
+ * A published schema keeps less than the HSX type: dates and accounts publish
+ * as plain strings, percents and bps as integers. Compare by the family the
+ * schema can still express so the check never rejects a richer declared type.
+ */
+function samePortType(declared: HsxType, captured: HsxType): boolean {
+  if (captured.kind === "unknown" || declared.kind === "unknown") return true;
+  if (captured.kind === "text")
+    return STRING_BACKED_PORT_KINDS.has(declared.kind);
+  if (captured.kind === "integer") {
+    return INTEGER_BACKED_PORT_KINDS.has(declared.kind);
+  }
+  if (declared.kind !== captured.kind) return false;
+  if (captured.currency && declared.currency !== captured.currency) {
+    return false;
+  }
+  if (captured.target && declared.target !== captured.target) {
+    return false;
+  }
+  return true;
+}
+
+function portTypeWords(type: HsxType): string {
+  if (type.kind === "ref" && type.target) return `ref<${type.target}>`;
+  return typeWords(type);
+}
+
+function getFieldSchemaFromAction(
+  action: UdlAction,
+  fieldName: string,
+): Readonly<Record<string, JsonValue>> | undefined {
+  if (!action.captureInput) return undefined;
+  const properties = action.input?.properties as
+    | Record<string, Record<string, JsonValue>>
+    | undefined;
+  if (!properties) return undefined;
+
+  for (const inputKey of Object.values(action.captureInput)) {
+    if (inputKey !== fieldName && camel(inputKey) !== camel(fieldName)) {
+      continue;
+    }
+    const schema = properties[inputKey] ?? properties[camel(inputKey)];
+    if (schema && typeof schema === "object") return schema;
+  }
+
+  return undefined;
+}
+
+function findCapturedFieldSchema(
+  catalogInstrument: UdlInstrument,
+  actionName: string,
+  fieldName: string,
+): Readonly<Record<string, JsonValue>> | undefined {
+  const targetAction = catalogInstrument.actions[actionName];
+  return targetAction
+    ? getFieldSchemaFromAction(targetAction, fieldName)
+    : undefined;
+}
+
+function checkPortCaptureTypes(
+  candidates: readonly ConcreteInstrument[],
+  publishedCatalog: UdlDocument,
+  topLevelAliases: ReadonlyMap<string, Expr>,
+  diagnostics: GeneralDiagnostic[],
+): void {
+  const catalogById = new Map<string, UdlInstrument>(
+    publishedCatalog.instruments.map((instrument) => [
+      instrument.id,
+      instrument,
+    ]),
+  );
+
+  for (const candidate of candidates) {
+    const catalogInstrument =
+      catalogById.get(candidate.name.name) ??
+      (candidate.callee ? catalogById.get(candidate.callee) : undefined);
+    if (!catalogInstrument) continue;
+
+    const aliases = new Map([...topLevelAliases, ...candidate.aliases]);
+
+    for (const [actionName, declaredPorts] of candidate.ports) {
+      for (const port of declaredPorts) {
+        const rawShape = entry(port.body, "shape")?.value;
+        if (rawShape?.kind !== "block") continue;
+
+        for (const fieldEntry of rawShape.entries) {
+          const fieldName = fieldEntry.key.name;
+          const capturedSchema = findCapturedFieldSchema(
+            catalogInstrument,
+            actionName,
+            fieldName,
+          );
+          if (!capturedSchema) continue;
+
+          const capturedType = publishedFieldType(
+            capturedSchema,
+            publishedCatalog.instruments,
+          );
+          const declaredType = typeOf(fieldEntry.value, aliases);
+
+          if (!samePortType(declaredType, capturedType)) {
+            const declaredWords = portTypeWords(declaredType);
+            const capturedWords = portTypeWords(capturedType);
+            const message = `decision port ${port.name.name} field ${fieldName} declares ${declaredWords} but instrument ${catalogInstrument.id} captures it as ${capturedWords}`;
+            const fix = `declare ${fieldName} as ${capturedWords} in decision port ${port.name.name}`;
+            if (
+              !diagnostics.some(
+                (prior) =>
+                  prior.code === "HSX1026" &&
+                  prior.span.start === fieldEntry.value.span.start &&
+                  prior.span.end === fieldEntry.value.span.end &&
+                  prior.message === message,
+              )
+            ) {
+              diagnostics.push({
+                code: "HSX1026",
+                fix,
+                message,
+                severity: "error",
+                span: fieldEntry.value.span,
+              });
+            }
+          }
+        }
+      }
+    }
+  }
+}
+
 function typedPublishedSubject(
   subject: UdlDocument["subjects"][number],
   origin: Span,

package/std/money_flows/held_payment.hsx

@@ -39,6 +39,7 @@ module std.money_flows.held_payment
 // - `cancel_charge_bps`: Optional cancellation charge in basis points. Declaring it gives the settlement a
 //   quoted cancellation: `quote_cancellation` prices the charge and the refund and freezes both,
 //   `cancel` pays the refund to the payer, and `retain_cancellation_charge` pays the charge to the payee.
+//   A zero charge keeps the flow with a zero fee.
 // - `cancel_offer_life`: ISO 8601 duration a cancellation quote stays open, required with `cancel_charge_bps`.
 //
 // ### Decision ports
@@ -70,6 +71,8 @@ export instrument held_payment<C>(payer: party, payee: party, amount: money<C>,
   let(payee_fee): get(fees, payee);
   let(payer_fee_kind): kind(payer_fee);
   let(payee_fee_kind): kind(payee_fee);
+  let(has_cancel_quote): if_eq(kind(cancel_charge_bps), "boolean", false, true);
+  let(has_charge): if_eq(cancel_charge_bps, 0, false, true);
   when_eq(payee_fee_kind, binding) {
     when(on_cancel) {
       unsupported {
@@ -79,7 +82,7 @@ export instrument held_payment<C>(payer: party, payee: party, amount: money<C>,
       }
     }
   }
-  when(cancel_charge_bps) {
+  when(has_cancel_quote) {
     when(on_cancel) {
       unsupported {
         code: HSX1110;
@@ -110,10 +113,10 @@ export instrument held_payment<C>(payer: party, payee: party, amount: money<C>,
     }
   }
   when(cancel_offer_life) {
-    when_not(cancel_charge_bps) {
+    when_not(has_cancel_quote) {
       unsupported {
         code: HSX1110;
-        message: "cancel_offer_life needs a nonzero cancel_charge_bps to quote";
+        message: "cancel_offer_life needs cancel_charge_bps to quote";
         fix: "declare the cancellation charge in basis points, or drop cancel_offer_life";
       }
     }
@@ -202,7 +205,7 @@ export instrument held_payment<C>(payer: party, payee: party, amount: money<C>,
       when_not(cancel_splits) {
         states created funded disputed released;
         when(on_cancel) { states cancelled; }
-        when(cancel_charge_bps) { states cancellation_quoted cancelled settled; }
+        when(has_cancel_quote) { states cancellation_quoted cancelled settled; }
         states abandoned;
       }
       when(cancel_splits) { states created funding_1 funded disputed releasing_1 released cancelling_1 cancelled abandoned; }
@@ -219,14 +222,14 @@ export instrument held_payment<C>(payer: party, payee: party, amount: money<C>,
     when_not(payee_fee) {
       when_not(cancel_splits) {
         on fund_piece_1: created -> funded;
-        when_not(cancel_charge_bps) {
+        when_not(has_cancel_quote) {
           on [release_name]: funded -> released;
           when(release_deadline) { on release_on_deadline: funded -> released; }
         }
-        when(cancel_charge_bps) {
+        when(has_cancel_quote) {
           on [release_name]: funded | cancellation_quoted -> released;
           when(release_deadline) { on release_on_deadline: funded | cancellation_quoted -> released; }
-          on quote_cancellation: funded -> cancellation_quoted;
+          on quote_cancellation: funded | cancellation_quoted -> cancellation_quoted;
           on cancel: cancellation_quoted -> cancelled;
           on retain_cancellation_charge: cancelled -> settled;
         }
@@ -275,7 +278,12 @@ export instrument held_payment<C>(payer: party, payee: party, amount: money<C>,
         on unfund_piece_1: funding_1 | abandoning_1 -> abandoned;
       }
     }
-    on dispute: funded -> disputed;
+    when_not(has_cancel_quote) {
+      on dispute: funded -> disputed;
+    }
+    when(has_cancel_quote) {
+      on dispute: funded | cancellation_quoted -> disputed;
+    }
     on resume: disputed -> funded;
     on abandon: created -> abandoned;
   }
@@ -520,7 +528,7 @@ export instrument held_payment<C>(payer: party, payee: party, amount: money<C>,
       steps: [];
     }
   }
-  when(cancel_charge_bps) {
+  when(has_cancel_quote) {
     action quote_cancellation {
       agent_description: concat("Price the cancellation and hold that price open. No money moves. The charge the ", words(payee), " keeps and the refund the ", words(payer), " gets back are worked out here and frozen for ", cancel_offer_life, ", after which a fresh call prices it again. Call cancel to spend the quote.");
       summary: "Price the cancellation and hold that price open";
@@ -554,7 +562,12 @@ export instrument held_payment<C>(payer: party, payee: party, amount: money<C>,
       let(metadata_phase): "metadata.phase";
       agent_description: concat("Pay the quoted cancellation charge out of escrow to the ", words(payee), ". This moves money and does not reverse. The settlement must already be cancelled, so the figure is the one the quote fixed and the escrow ends empty.");
       summary: concat("Pay the quoted cancellation charge to the ", words(payee));
-      moves: [{ key: charge; operation: internal_transfer.create; bind: { amount: { from: instance; path: refs.cancellationChargeAmount; }; currency: { from: instance; path: fields.currency; }; destinationAccountId: { from: instance; path: concat("fields.", payee_account_field); }; [metadata_instrument]: { from: const; value: instrument; }; [metadata_instance]: { from: instance; path: instrumentInstanceId; }; [metadata_phase]: { from: const; value: retain_cancellation_charge; }; productId: { from: instance; path: productId; }; sourceAccountId: { from: instance; path: refs.escrowAccountId; }; }; capture: { retainCancellationChargeTransferId: transferId; }; }];
+      when(has_charge) {
+        moves: [{ key: charge; operation: internal_transfer.create; bind: { amount: { from: instance; path: refs.cancellationChargeAmount; }; currency: { from: instance; path: fields.currency; }; destinationAccountId: { from: instance; path: concat("fields.", payee_account_field); }; [metadata_instrument]: { from: const; value: instrument; }; [metadata_instance]: { from: instance; path: instrumentInstanceId; }; [metadata_phase]: { from: const; value: retain_cancellation_charge; }; productId: { from: instance; path: productId; }; sourceAccountId: { from: instance; path: refs.escrowAccountId; }; }; capture: { retainCancellationChargeTransferId: transferId; }; }];
+      }
+      when_not(has_charge) {
+        moves: [];
+      }
       steps: [];
     }
   }