@hyperscale0/hsx 2.1.1 → 2.2.0

package/src/typecheck.ts

@@ -1,4 +1,6 @@
 import {
+  fixedIsoDurationMs,
+  referencedUdlInstrumentIds,
   deriveUdlActionEffects,
   resolveUdlActionPlans,
   udlDocumentSchema,
@@ -453,6 +455,28 @@ export function checkGeneralProgram(
     );
   }
 
+  const prefixByInstrument = new Map<string, string>();
+  if (options.publishedCatalog) {
+    for (const inst of options.publishedCatalog.instruments) {
+      if (inst.idPrefix) {
+        prefixByInstrument.set(inst.id, inst.idPrefix);
+      }
+    }
+  }
+  for (const [name, decl] of templates) {
+    const prefix =
+      stringSlot(decl.body, "idPrefix", "id_prefix") ?? prefixFor(name);
+    prefixByInstrument.set(name, prefix);
+  }
+  for (const candidate of allocated) {
+    const prefix =
+      stringSlot(candidate.body, "idPrefix", "id_prefix") ??
+      prefixFor(candidate.name.name);
+    prefixByInstrument.set(candidate.name.name, prefix);
+  }
+  const resolvePrefix = (target: string): string | undefined =>
+    prefixByInstrument.get(target);
+
   const instruments: TypedInstrument[] = [];
   const ids = new Set<string>();
   for (const candidate of allocated) {
@@ -483,6 +507,7 @@ export function checkGeneralProgram(
       candidate.ports,
       candidate.aliases,
       diagnostics,
+      resolvePrefix,
     );
     if (checked) instruments.push(checked);
   }
@@ -499,7 +524,11 @@ export function checkGeneralProgram(
     );
   }
 
-  crossInstrumentReferenceDiagnostics(instruments, diagnostics);
+  crossInstrumentReferenceDiagnostics(
+    instruments,
+    diagnostics,
+    new Set(templates.keys()),
+  );
 
   if (
     header &&
@@ -656,6 +685,15 @@ function checkPublishedProgram(
       );
       continue;
     }
+    if (action?.engineOwned || authoredAction?.slots.engineOwned === true) {
+      report(
+        "HSX1021",
+        exposure.span,
+        `${target} is engine-owned`,
+        "expose a caller action instead",
+      );
+      continue;
+    }
     if (!CAMEL_CASE.test(exposure.publicName.name)) {
       report(
         "HSX1020",
@@ -843,24 +881,7 @@ function publishedInstrumentDependencies(
   instrument: UdlInstrument,
   idByPrefix: ReadonlyMap<string, string>,
 ): readonly string[] {
-  const found = new Set<string>();
-  const visit = (value: unknown): void => {
-    if (Array.isArray(value)) {
-      value.forEach(visit);
-      return;
-    }
-    if (!value || typeof value !== "object") return;
-    for (const [key, child] of Object.entries(value)) {
-      if (
-        (key === "instrumentId" || key === "childInstrumentId") &&
-        typeof child === "string"
-      ) {
-        found.add(child);
-      }
-      visit(child);
-    }
-  };
-  visit(instrument);
+  const found = new Set(referencedUdlInstrumentIds(instrument));
   for (const field of Object.values(instrument.fields)) {
     const prefix =
       typeof field.pattern === "string"
@@ -1110,7 +1131,6 @@ const applicationMetadataKeys = new Set([
   "action",
   "agent_description",
   "description",
-  "journeys",
   "nav",
   "navigation",
   "summary",
@@ -1423,7 +1443,12 @@ function inferSettlementTypeArgument(
   typeParameter: string,
 ): Expr | undefined {
   for (const parameter of template.parameters) {
-    const parameterType = parameter.type;
+    const declaredType = parameter.type;
+    const parameterType =
+      declaredType.kind === "type_apply" &&
+      declaredType.callee.name === "optional"
+        ? (declaredType.args[0] ?? declaredType)
+        : declaredType;
     if (
       parameterType.kind !== "type_apply" ||
       parameterType.callee.name !== "money" ||
@@ -1727,9 +1752,53 @@ function instantiate(
     values,
     portDependencies,
   );
+  const binding: Entry = {
+    key: { kind: "ident", name: "template_binding", span: application.span },
+    qualifiers: [],
+    span: application.span,
+    value: {
+      kind: "block",
+      span: application.span,
+      entries: [
+        {
+          key: { kind: "ident", name: "id", span: application.span },
+          qualifiers: [],
+          span: application.span,
+          value: {
+            kind: "string",
+            value: template.name.name,
+            span: application.span,
+          },
+        },
+        {
+          key: { kind: "ident", name: "parameters", span: application.span },
+          qualifiers: [],
+          span: application.span,
+          value: {
+            kind: "block",
+            span: application.span,
+            entries: resolvedArgs.flatMap(({ parameter }) => {
+              const value = values.get(parameter.name.name);
+              return value &&
+                ["string", "number", "boolean"].includes(value.kind)
+                ? [
+                    {
+                      key: parameter.name,
+                      qualifiers: [],
+                      span: parameter.span,
+                      value,
+                    },
+                  ]
+                : [];
+            }),
+          },
+        },
+      ],
+    },
+  };
   return {
     ...body,
-    entries: body.entries.map((row) => {
+    entries: [...body.entries, binding].map((row) => {
       if (row.key.name !== "fields" || row.value.kind !== "block") return row;
       return {
         ...row,
@@ -2305,9 +2374,16 @@ function substituteExpr(expr: Expr, values: ReadonlyMap<string, Expr>): Expr {
               }
             : {}),
           key: substituteName(entry.key, nestedValues),
-          qualifiers: entry.qualifiers.map((qualifier, index) => {
+          qualifiers: entry.qualifiers.flatMap((qualifier, index) => {
             const value = nestedValues.get(qualifier.name);
             const fixed = fixedQualifier(entry.key.name, qualifier.name, index);
+            if (
+              entry.key.name === "on" &&
+              !fixed &&
+              index > 0 &&
+              value?.kind === "list"
+            )
+              return value.items.map((item) => nameFromValue(qualifier, item));
             return !fixed && value
               ? nameFromValue(qualifier, value)
               : substituteName(qualifier, nestedValues);
@@ -2804,6 +2880,17 @@ function evaluateCompileTimeCall(
         : undefined;
     case "basis_points":
       return first?.kind === "percent" ? numeric(first.bps) : undefined;
+    case "shift_date": {
+      const instant = first ? Date.parse(nameText(first)) : NaN;
+      const offset = second ? fixedIsoDurationMs(nameText(second)) : null;
+      if (!Number.isFinite(instant) || offset === null)
+        return text(NONE_SENTINEL);
+      const direction = third && nameText(third) === "before" ? -1 : 1;
+      const shifted = new Date(instant + direction * offset);
+      return Number.isFinite(shifted.getTime())
+        ? text(shifted.toISOString())
+        : text(NONE_SENTINEL);
+    }
     case "names": {
       const count = number(second);
       if (!first || count === undefined || count < 0 || !third)
@@ -2826,6 +2913,15 @@ function evaluateCompileTimeCall(
             span: expr.span,
           }
         : undefined;
+    case "without":
+      return first?.kind === "list" && second
+        ? {
+            ...first,
+            items: first.items.filter(
+              (item) => nameText(item) !== nameText(second),
+            ),
+          }
+        : undefined;
     case "concat_lists":
       return expr.args.every((arg) => arg.kind === "list")
         ? {
@@ -2992,9 +3088,16 @@ function expandComprehensions(
         const substituted: Entry = {
           ...row,
           key: substituteName(row.key, locals),
-          qualifiers: row.qualifiers.map((qualifier, index) => {
+          qualifiers: row.qualifiers.flatMap((qualifier, index) => {
             const value = locals.get(qualifier.name);
             const fixed = fixedQualifier(row.key.name, qualifier.name, index);
+            if (
+              row.key.name === "on" &&
+              !fixed &&
+              index > 0 &&
+              value?.kind === "list"
+            )
+              return value.items.map((item) => nameFromValue(qualifier, item));
             return !fixed && value
               ? nameFromValue(qualifier, value)
               : substituteName(qualifier, locals);
@@ -3077,6 +3180,7 @@ function checkInstrument(
   ports: ReadonlyMap<string, readonly PortDecl[]>,
   aliases: ReadonlyMap<string, Expr>,
   diagnostics: GeneralDiagnostic[],
+  resolvePrefix?: (target: string) => string | undefined,
 ): TypedInstrument | undefined {
   if (!SNAKE_CASE.test(name.name)) {
     diagnostics.push({
@@ -3090,7 +3194,7 @@ function checkInstrument(
   const fieldsEntry = entry(body, "fields");
   const fields =
     fieldsEntry?.value.kind === "block"
-      ? checkFields(fieldsEntry.value, aliases, diagnostics)
+      ? checkFields(fieldsEntry.value, aliases, diagnostics, resolvePrefix)
       : [];
   if (!fieldsEntry) {
     diagnostics.push({
@@ -3597,6 +3701,7 @@ function checkFields(
   block: BlockExpr,
   aliases: ReadonlyMap<string, Expr>,
   diagnostics: GeneralDiagnostic[],
+  resolvePrefix?: (target: string) => string | undefined,
 ): TypedField[] {
   const result: TypedField[] = [];
   const names = new Set<string>();
@@ -3622,7 +3727,7 @@ function checkFields(
       continue;
     }
     names.add(name);
-    result.push(lowerField(row, aliases, diagnostics));
+    result.push(lowerField(row, aliases, diagnostics, resolvePrefix));
   }
   return result;
 }
@@ -3631,6 +3736,7 @@ function lowerField(
   row: Entry,
   aliases: ReadonlyMap<string, Expr>,
   diagnostics: GeneralDiagnostic[],
+  resolvePrefix?: (target: string) => string | undefined,
 ): TypedField {
   const name = camel(row.key.name);
   let typeExpr = row.value;
@@ -3692,6 +3798,21 @@ function lowerField(
       severity: "error",
       span: declaredSpan,
     });
+  } else if (type.kind === "ref" && type.target) {
+    const prefix = resolvePrefix?.(type.target);
+    if (!extra.pattern) {
+      if (prefix) {
+        extra.pattern = `^${prefix}_(sandbox|live)_[a-z0-9]{8,64}$`;
+      } else if (resolvePrefix !== undefined) {
+        diagnostics.push({
+          code: "HSX1007",
+          fix: "reference an instrument declared in this program, imported from std, or published in the catalogue",
+          message: `field ${name} references unknown instrument ${type.target}`,
+          severity: "error",
+          span: declaredSpan,
+        });
+      }
+    }
   }
 
   const structuralType = Object.hasOwn(extra, "items")
@@ -4174,9 +4295,38 @@ function bindFieldReferences(
 ): void {
   const externalFieldSlot = (path: readonly string[]): boolean => {
     const key = path.at(-1);
+    const input =
+      slots.input !== undefined && isJsonObject(slots.input)
+        ? slots.input
+        : undefined;
+    const allocation =
+      slots.allocate !== undefined && isJsonObject(slots.allocate)
+        ? slots.allocate
+        : undefined;
+    const allocationOperand =
+      path.includes("allocate") &&
+      ["amountField", "sourceAccountField", "paymentIdentityField"].includes(
+        key ?? "",
+      );
     return (
+      (allocationOperand &&
+        Array.isArray(input?.required) &&
+        allocation !== undefined &&
+        input.required.includes(allocation[key!]!)) ||
+      (path.includes("funding") &&
+        [
+          "ticketRefField",
+          "ticketAmountField",
+          "ticketInvestorField",
+          "ticketAccountField",
+        ].includes(key ?? "")) ||
+      (path.includes("requiresExposure") && key === "minimumField") ||
       (path.includes("requiresAggregate") && key === "refField") ||
-      (path.includes("requiresAggregate") && key === "amountField") ||
+      (path.includes("requiresAggregate") &&
+        ["amountField", "dateField", "positionField"].includes(key ?? "")) ||
+      (path.includes("requiresAggregate") &&
+        path.includes("dueBefore") &&
+        key === "field") ||
       (path.includes("signedSum") && key === "refField") ||
       (path.includes("signedSum") && key === "amountField") ||
       (path.includes("remainder") && key === "refField") ||
@@ -4220,6 +4370,7 @@ function bindFieldReferences(
 function crossInstrumentReferenceDiagnostics(
   instruments: readonly TypedInstrument[],
   diagnostics: GeneralDiagnostic[],
+  knownTargets?: ReadonlySet<string>,
 ): void {
   const byId = new Map(
     instruments.map((instrument) => [instrument.id, instrument]),
@@ -4254,7 +4405,10 @@ function crossInstrumentReferenceDiagnostics(
   for (const owner of instruments) {
     for (const field of owner.fields) {
       if (field.type.kind !== "ref" || !field.type.target) continue;
-      if (!byId.has(field.type.target)) {
+      if (
+        !byId.has(field.type.target) &&
+        !knownTargets?.has(field.type.target)
+      ) {
         report(
           owner,
           field.origin,
@@ -4367,6 +4521,23 @@ function crossInstrumentReferenceDiagnostics(
         return;
       }
       const refField = relation.refField;
+      const anchorName =
+        relation.anchorField ??
+        (relation.over === "siblings" ? refField : undefined);
+      const anchor =
+        typeof anchorName === "string" ? fieldIn(owner, anchorName) : undefined;
+      const expectedTarget =
+        anchor?.type.kind === "ref" ? anchor.type.target : owner.id;
+      if (
+        typeof anchorName === "string" &&
+        (!anchor || anchor.type.kind !== "ref")
+      )
+        report(
+          owner,
+          action.origin,
+          `aggregate anchor ${anchorName} is not a reference`,
+          "declare the anchor as a typed parent reference",
+        );
       if (typeof refField === "string") {
         const field = fieldIn(target, refField);
         if (!field) {
@@ -4374,17 +4545,18 @@ function crossInstrumentReferenceDiagnostics(
             owner,
             action.origin,
             `${targetId}.${refField} does not exist`,
-            `declare ${refField} on ${targetId} as ref<${owner.id}> or correct the clause`,
+            `declare ${refField} on ${targetId} as ref<${expectedTarget}> or correct the clause`,
           );
         } else if (
           field.type.kind !== "ref" ||
-          (field.type.target !== undefined && field.type.target !== owner.id)
+          (field.type.target !== undefined &&
+            field.type.target !== expectedTarget)
         ) {
           report(
             owner,
             action.origin,
-            `${targetId}.${refField} has ${typeWords(field.type)}; this relation needs ref<${owner.id}>`,
-            `change ${targetId}.${refField} to ref<${owner.id}>`,
+            `${targetId}.${refField} has ${typeWords(field.type)}; this relation needs ref<${expectedTarget}>`,
+            `change ${targetId}.${refField} to ref<${expectedTarget}>`,
           );
         }
       }
@@ -4408,12 +4580,13 @@ function crossInstrumentReferenceDiagnostics(
       const targetField = check?.targetField;
       if (
         typeof targetField === "string" &&
-        fieldIn(owner, targetField)?.type.kind !== "money"
+        fieldIn(owner, targetField)?.type.kind !==
+          (check?.kind === "count_at_least" ? "integer" : "money")
       ) {
         report(
           owner,
           action.origin,
-          `${owner.id}.${targetField} is not declared money`,
+          `${owner.id}.${targetField} is not declared ${check?.kind === "count_at_least" ? "integer" : "money"}`,
           `declare ${owner.id}.${targetField} as money<C> or correct the aggregate target`,
         );
       }

package/src/version.ts

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

package/std/SEMANTICS.md

@@ -1,139 +1,44 @@
-# Settlement semantics frozen before legacy teardown
+# Standard library money flows semantics
 
-This note records the behavior that the former archetype branches emitted on
-2026-09-01. The in-place compiler family specs under `test/` are the semantic
-authority. This note is the human porting index.
+This document records the runtime semantics and settlement mechanics of standard library modules under `std.money_flows`. The compiler and its unit specifications under `test/` remain the authoritative implementation reference.
 
-## Direct and held payments
+## Direct checkout and card
 
-- `instant_transfer` stores the amount, currency, payer, and payee. Create pays
-  through one or more ordered pieces and ends in `paid`. A payer fee is an
-  `on_top` move. A payee fee is carved from the base amount. Exact, basis-point,
-  and tiered rules produce fee fields and `feeRules`. The finest common
-  refinement of all fee cuts produces piece fields and one partition. Floor
-  rounding sends the remainder to the named non-fee recipient. A derived
-  amount adds a floor percentage field, `derivedAmounts`, a platform party, and
-  its own transfer piece.
-- `held_payment` reserves every refined piece before release. It posts release
-  pieces, voids cancellation pieces, and keeps payer service fees outside the
-  held principal. Release and cancellation fee sides share the finest common
-  partition, so each stored piece has one release recipient and one cancel
-  recipient. States track each funding, release, cancellation, and abandonment
-  step. Abandonment refunds every still-held piece. A deadline release and a
-  caller decision release carry the named date or port clause. Retention is the
-  same form with one held piece, a release deadline, and cancellation back to
-  the contractor. Whole-amount mode funds the principal and on-top fee in one
-  action, then releases or cancels the principal whole. A condition and date
-  can coexist, with separate early and scheduled release actions.
-- `captured_payment` stores authorization total, reserve and reversal dates,
-  and both party accounts. It moves through `created`, `authorized`, optional
-  `partially_captured`, `settled`, `voided`, `expired`, `corrected`, or
-  `reversed`. Authorize reserves custody. Capture and capture-more consume the
-  authorized balance according to the declared mode. Settle posts the captured
-  amount. Void and expiry release the reserve. Correction and external reversal
-  use their declared ports and windows. Derived fees use the same floor,
-  partition, bearer, and position rules as direct payment.
-- `cancellable_booking` holds the booking amount in escrow away from guest and
-  host until the booking ends or is cancelled. Cancellation quotes a penalty
-  against the time remaining before the start date, frozen with offer life.
-  Lifecycle moves through `created`, `held`, `cancellation_quoted`, `canceled`,
-  `settled`, and `completed`. Penalty retention moves penalty funds to host and
-  remainder to guest; completion releases full amount to host.
-- `premium_forward` holds premium pieces, then forwards the net pieces after a
-  bind decision. It can abandon unbound custody. Policy reference, renewal due,
-  endorsement evidence, and lapse actions appear only when declared. Its fee
-  partition and floor remainder rules match `held_payment`.
+- `instant_transfer` stores the amount, currency, payer, and payee. Action `create` opens the payment record without moving funds. Action `pay_piece_1` and subsequent piece actions execute the money movements, transitioning to state `paid`. A payer fee executes as an `on_top` move. A payee fee carves out of the base amount. Exact, basis-point, and tiered rules generate fee fields and `feeRules`. The finest common refinement of all fee cuts produces piece fields and one partition. Floor rounding sends minor-unit remainder to the designated non-fee recipient. A derived amount adds a floor percentage field, `derivedAmounts`, a platform party account, and its own transfer piece.
+- `captured_payment` stores authorization total, reserve and reversal dates, and party accounts. The instrument moves through `created`, `authorized`, optional `partially_captured`, `settled`, `voided`, `expired`, `corrected`, or `reversed`. Action `authorize` reserves custody on the payer balance. Actions `capture` and `capture_more` consume the authorized balance using partial posts. Action `settle` posts the captured amount. Actions `void` and `expire` release the reserve. Actions for payee correction and external reversal use their declared condition ports and deadline windows. Derived fees use the same floor, partition, bearer, and position rules as direct payment. Four unused signature knobs (`capture_mode`, `correction_mode`, `negative_position`, `timeout`) are pruned.
 
-## Decisions and credit
+## Custody and escrow
 
-- `conditional_disbursement` emits a submitted parent with cap, currency,
-  source, destination, and the decision port. Denial terminates the parent. An
-  approved-amount child stores a runtime-bounded amount and a parent reference.
-  The child captures the port input, moves through `created`, `approved`, and
-  `paid`, and refuses reopening. Recovery is a separate transfer.
-- `advance` has two forms. A carved advance references a held settlement and
-  its recourse settlement, disburses once, and settles from the referenced
-  release without minting new value. A scheduled advance stores advance,
-  fee, repayable total, first due date, and one repayment field per fixed
-  installment. It partitions repayments to the repayable total and advances
-  before collecting each due installment.
-- `credit_facility` stores lender, borrower, draw destination, limit, currency,
-  and expiry. The facility can freeze and close. Each draw is a generated child
-  with amount, facility reference, and obligation reference. Draw admission
-  checks the facility state and aggregate limit. Resolution waits for the
-  referenced obligation state.
+- `held_payment` reserves every refined piece in a dedicated escrow account before release. It posts release pieces, voids cancellation pieces, and keeps payer service fees outside the held principal. Release and cancellation fee sides share the finest common partition, so each stored piece has one release recipient and one cancel recipient. States track funding, release, cancellation, and abandonment steps. Abandonment refunds every still-held piece. A deadline release and a caller decision release carry the named date or port clause. Retention forms reserve one held piece with a release deadline and cancellation back to the contractor. Whole-amount mode funds principal and on-top fees in one action, then releases or cancels the principal whole. Quoted cancellation uses `cancel_charge_bps` and `cancel_offer_life` to freeze penalty quotes before confirm and retain actions.
+- `cancellable_booking` holds booking funds in escrow away from guest and host until the booking ends or cancels. Cancellation quotes a penalty against the time remaining before `starts_at`, frozen for `offer_life`. Lifecycle moves through `created`, `held`, `cancellation_quoted`, `canceled`, `settled`, and `completed`. Penalty retention moves penalty funds to host and remainder to guest; completion releases full amount to host.
+- `security_deposit` reserves the full deposit amount in escrow. A claim port posts either the whole hold or an externally decided amount bounded by the hold. The explicit remainder returns to the payer. A return port voids the whole hold. The deadline form adds machine expiry and unfunded cancellation.
+- `premium_forward` holds premium pieces in escrow, then forwards net pieces after a carrier bind decision. It can abandon unbound custody. Policy reference, renewal due, endorsement evidence, and lapse actions activate when declared. Fee partition and floor remainder rules match `held_payment`.
 
-## Schedules and usage
+## Subscriptions, usage, and schedules
 
-- A finite `scheduled` transfer stores total, first due date, and one money
-  field per installment. Floor division creates equal pieces and gives the
-  final field the remainder. States and actions unroll in order. Each action
-  carries its due rule and cumulative duration offset.
-- Scheduled obligation mode emits a parent plus one generated payment child per
-  installment. The parent stores principal, delinquency dates, party accounts,
-  partitions, and aggregate invariants. It supports draft approval, optional
-  advance, fixed collection and delinquency actions, write-off, and completion.
-  Each child binds parent fields, repays once, and can refund once.
-- `recurring_collection` with a finite count uses the scheduled construction.
-  Open recurrence stores one amount and anchor, opens one period at a time,
-  collects that period, and permits cancellation. It never unrolls an unbounded
-  runtime loop.
-- `metered` stores one money field for each declared meter and a period end.
-  Every charge moves directly from payer to payee. The instrument never accrues
-  custody. Closing the period only changes state.
+- `scheduled` executes calendar-anchored payment series between one payer and one payee across three operational modes:
+  1. Finite installment plan: Stores total, first due date, and one money field per installment. The caller supplies each piece; a partition checks their sum, not equality. States and actions unroll in order with cumulative duration offsets.
+  2. Open recurring subscription: Charges a recurring amount on interval `every` until an `until` port fires, opening one period liability at a time.
+  3. Debt obligation: Emits a parent obligation plus one child payment instrument per installment. The parent stores principal, delinquency dates, party accounts, and aggregate invariants. Child instruments bind parent fields, repay against installment caps, and support full refunds. Finite obligation count generalization applies without grace periods.
+- `metered` stores one money field for each declared meter in its rate card and a period end date. Each usage charge executes an immediate transfer directly from payer to payee without escrow custody. Closing the period transitions state to `closed` at `close_by` and makes further charges unreachable.
 
-## Collections and distributions
+## Lending and credit
 
-- `pooled_split` stores the pool total, due date, and one share amount and
-  account per recipient. Positive shares total exactly 10,000 basis points.
-  Floor division assigns each share, and the named remainder recipient absorbs
-  minor-unit residue. Funding and distribution actions unroll in roster order.
-- `weighted_distribution` emits an open parent and an entitlement child. The
-  parent stores source, total, record date, and maximum recipient count. A port
-  freezes the entitlement snapshot. Child rows store recipient, weight, source,
-  currency, and parent reference. Largest-remainder distribution pays children
-  once. Aggregate clauses cap and total the child set. Withholding is refused
-  and correction creates a new distribution. Its `flat` form emits a single
-  claim instead. The caller supplies typed pool, weight, and group references,
-  their state gates, copy and match maps, and the pool amount path.
-- `threshold_pool` emits a pool parent and commitment child. The parent stores
-  target, close date, maximum contributors, beneficiary, and currency. It moves
-  through open, active, failed, or settled based on aggregate commitment gates.
-  Each commitment can cancel before collection, collect into the round, or
-  refund after failure. Its referenced-contribution form accepts a published
-  contribution instrument, beneficiary account, and memo and emits no child.
-- `security_deposit` reserves the full amount. A claim port posts either the
-  whole hold or a decided amount bounded by the hold. The explicit remainder
-  returns to the payer. A return port voids the whole hold. The deadline form
-  adds machine expiry and unfunded cancellation. Claim and return targets can
-  name either party.
+- `advance` provides upfront capital disbursed to a recipient and repaid through two distinct modes:
+  1. Carved advance: References an active escrow hold and recourse instrument through `against`. It disburses once and settles from the referenced release without minting new value. In this mode, the `fee` parameter is ignored.
+  2. Scheduled advance: Stores advance amount, fee amount, repayable total, first due date, and one repayment field per installment. A supplied `fee` derives feeAmount as a floor percentage of principal. The caller supplies principal, repayable total and repayment pieces, which partitions reconcile. `repayment_source` can differ from the capital recipient. `profit_to` splits each collection between principal returned to the funder and profit paid to its recipient. `dated: true` requires one stored signed due date per repayment. Equality, chronological ordering, partial servicing and arrears are not implied by those partitions.
+- `credit_facility` stores lender, borrower, draw destination, credit limit, currency, and expiry date. The facility transitions across `active`, `frozen`, and `closed`. Each draw creates a child instrument with draw amount, facility reference, and obligation reference. Draw admission checks facility active state and aggregate child exposure against the limit. Closure requires all child draws to reach status `resolved`. Unused signature knobs (`availability_policy`, `expiry_policy`, `close_policy`) are pruned.
+- `conditional_disbursement` emits a submitted parent instrument with cap, currency, source account, destination account, and decision port. Denial terminates the parent before child approvals. Child approval instruments store externally bounded amounts. Child actions capture port input, move through `created`, `approved`, and `paid`, and verify aggregate child exposure against the parent cap. Unused signature knobs (`reopen_policy`, `recovery_policy`) are pruned.
 
-## Composition and unwind
+## Multi-party distributions and pooling
 
-- `swap` stores both side amounts, accounts, fees, currency, and optional
-  clawback date. Funding is atomic across both sides. Release, settlement,
-  cancellation, dispute, abandonment, and clawback preserve the two-sided
-  conservation group. Side fees keep their declared bearer and position.
-  `distinctParties` prevents self-dealing. Unwind refunds each side and applies
-  the declared penalty tiers without changing the principal partition. Fixed
-  side names, state order, action bindings, parked-state reasons, and ID prefix
-  are general compile-time parameters.
-- `settlement_batch` emits a batch plus capture, credit-adjustment, and
-  debit-adjustment children. The batch stores close time, settlement and payout
-  accounts, beneficiary reference, and currency. Close freezes intake.
-  Calculate signs capture, fee, and reversal entries. Approve rejects a negative
-  position when configured. Instruct, acknowledge, and reconcile use the
-  declared payout port. Child references and statuses define every aggregate
-  and signed-sum input.
-- `rotating_pool` emits one parent plus one contribution child per fixed member.
-  The parent unrolls active and ready states for every cycle and checks that each
-  member row exists exactly once. Every child unrolls due, funded, defaulted,
-  guaranteed, paid, and completed states for every cycle. Due offsets scale the
-  fixed recurrence. A funded or guaranteed contribution pays the roster's fixed
-  beneficiary for that cycle. The final close requires the escrow account to be
-  drained. Its referenced-membership form delegates those member cycles to a
-  published membership instrument and emits only the parent.
-- `reconciled_payout` instructs an external payout with a tolerance dial,
-  waits for a matching bank debit statement line, and treats unmatched amounts
-  at the settle date as break rows. Lifecycle moves through `created`,
-  `instructed`, and `settled`.
+- `pooled_split` stores pool total, due date, and one share amount and account per recipient. Positive shares total exactly 10,000 basis points. Floor division assigns each share, and the designated remainder recipient absorbs minor-unit residues. Funding and distribution actions execute in roster order.
+- `weighted_distribution` emits a parent distribution instrument and child entitlement instruments. The parent stores source account, total amount, record date, and maximum recipient count. Child rows store recipient, weight, source, currency, and parent reference. A largest-remainder distribution algorithm pays children once. Aggregate clauses cap and total child records against the pool.
+- `threshold_pool` emits a pool parent instrument and child commitment instruments. The parent stores target amount, close date, maximum contributors, beneficiary, and currency. It transitions through `open`, `active`, `failed`, or `settled` based on aggregate commitment gates. Each commitment can cancel before collection, collect into the pool, or refund after campaign failure.
+- `rotating_pool` emits a parent pool instrument plus one contribution child instrument per member. The parent unrolls active and ready states for every cycle and checks that each member row exists exactly once. Member child instruments unroll due, funded, defaulted, guaranteed, paid, and completed states for every cycle. A funded or guaranteed contribution pays the fixed beneficiary for that cycle. Final closure requires the escrow balance to drain to zero.
+
+## Bilateral exchange, clearing, and reconciliation
+
+- `swap` stores amounts, accounts, fees, currency, and optional clawback dates for both sides. Funding is atomic across both sides. Release, settlement, cancellation, dispute, abandonment, and clawback preserve the two-sided conservation group. Side fees retain their declared bearer and position. Unwind refunds each side and applies declared penalty tiers without altering principal partitions.
+- `settlement_batch` emits a batch instrument alongside capture, credit-adjustment, and debit-adjustment child records. The batch stores close time, settlement and payout accounts, beneficiary reference, and currency. Closure freezes intake. Calculation applies signed arithmetic across capture, fee, and reversal entries. Actions instruct, acknowledge, and reconcile through the declared payout port.
+- `reconciled_payout` instructs an external payout with a tolerance window, waits for a matching bank debit statement line, and tracks unmatched amounts at settlement date as break rows. Lifecycle transitions through `created`, `instructed`, and `settled`.