@hyperscale0/udl 2.3.0 → 2.4.0

package/src/allocation.ts

@@ -0,0 +1,259 @@
+export type AllocationBucketKey = "principal" | "profit" | "cost" | "fine";
+export interface AllocationBalance {
+  readonly key: AllocationBucketKey;
+  readonly assessmentId: string;
+  readonly destinationAccountId: string;
+  readonly amount: bigint;
+  readonly consumed: bigint;
+}
+export interface AllocationSlice {
+  readonly id: string;
+  readonly dueAt: string;
+  readonly position: number;
+  readonly paid: boolean;
+  readonly buckets: readonly AllocationBalance[];
+}
+export interface AllocationInput {
+  readonly asOf: string;
+  readonly earningRule: "per_slice_on_due" | "on_disbursement";
+  readonly mode: "payment" | "payoff" | "write_off";
+  readonly payment?: bigint | undefined;
+  readonly assessmentId?: string;
+  readonly slices: readonly AllocationSlice[];
+}
+export interface AllocationPosting {
+  readonly sliceId: string;
+  readonly assessmentId: string;
+  readonly bucket: AllocationBucketKey;
+  readonly destinationAccountId: string;
+  readonly amount: bigint;
+}
+export interface AllocationCancellation {
+  readonly sliceId: string;
+  readonly assessmentId: string;
+  readonly bucket: AllocationBucketKey;
+  readonly amount: bigint;
+  readonly reason: "unearned_profit" | "write_off";
+}
+function clock(value: string): number {
+  if (!/^\d{4}-\d\d-\d\d(?:T\d\d:\d\d:\d\d(?:\.\d+)?Z)?$/.test(value))
+    throw new Error("allocation needs an authoritative UTC time");
+  const result = Date.parse(value);
+  if (
+    !Number.isFinite(result) ||
+    new Date(`${value.slice(0, 10)}T00:00:00Z`).toISOString().slice(0, 10) !==
+      value.slice(0, 10)
+  )
+    throw new Error("invalid allocation time");
+  return result;
+}
+
+/** Plan from locked balances. The engine owns identity claims and atomic posting. */
+export function planAllocation(
+  contract: {
+    readonly buckets: readonly { readonly key: AllocationBucketKey }[];
+  },
+  input: AllocationInput,
+) {
+  const priority = contract.buckets.map((bucket) => bucket.key);
+  const keys = new Set(priority);
+  if (
+    priority.length < 2 ||
+    priority.length > 4 ||
+    keys.size !== priority.length ||
+    !keys.has("principal") ||
+    !keys.has("profit") ||
+    priority.some(
+      (key) => !["principal", "profit", "cost", "fine"].includes(key),
+    )
+  )
+    throw new Error("invalid allocation priority");
+  if (
+    !["per_slice_on_due", "on_disbursement"].includes(input.earningRule) ||
+    !["payment", "payoff", "write_off"].includes(input.mode)
+  )
+    throw new Error("invalid earning rule or allocation mode");
+  if (!input.slices.length || input.slices.length > 366)
+    throw new Error("allocation requires 1 to 366 slices");
+  if (
+    input.assessmentId !== undefined &&
+    (input.mode !== "payment" || !input.assessmentId)
+  )
+    throw new Error("assessment selection requires payment mode");
+  const asOf = clock(input.asOf);
+  if (
+    input.mode === "write_off"
+      ? input.payment !== undefined
+      : input.payment === undefined
+        ? input.mode !== "payoff" && input.assessmentId === undefined
+        : typeof input.payment !== "bigint" ||
+          input.payment < 0n ||
+          (input.mode === "payment" && input.payment === 0n)
+  )
+    throw new Error("invalid allocation payment");
+  const ids = new Set<string>();
+  const positions = new Set<number>();
+  const assessments = new Set<string>();
+  const slices = input.slices
+    .map((slice) => {
+      const due = clock(slice.dueAt);
+      if (
+        !slice.id ||
+        ids.has(slice.id) ||
+        !Number.isInteger(slice.position) ||
+        slice.position < 1 ||
+        positions.has(slice.position) ||
+        typeof slice.paid !== "boolean" ||
+        slice.buckets.length > 256
+      )
+        throw new Error("invalid or duplicate slice");
+      ids.add(slice.id);
+      positions.add(slice.position);
+      for (const balance of slice.buckets) {
+        if (
+          !keys.has(balance.key) ||
+          !balance.assessmentId ||
+          assessments.has(balance.assessmentId) ||
+          !balance.destinationAccountId ||
+          typeof balance.amount !== "bigint" ||
+          typeof balance.consumed !== "bigint" ||
+          balance.amount < 0n ||
+          balance.consumed < 0n ||
+          balance.consumed > balance.amount
+        )
+          throw new Error("invalid or duplicate assessment balance");
+        assessments.add(balance.assessmentId);
+      }
+      return { slice, due };
+    })
+    .sort((a, b) => a.due - b.due || a.slice.position - b.slice.position);
+  const candidates: AllocationPosting[] = [];
+  const cancellations: AllocationCancellation[] = [];
+  for (const { slice, due } of slices) {
+    const earned =
+      input.earningRule === "on_disbursement" || due <= asOf || slice.paid;
+    for (const key of priority) {
+      // Multiple assessed charges of one kind have a deterministic identity order.
+      const balances = slice.buckets
+        .filter((balance) => balance.key === key)
+        .sort((a, b) =>
+          a.assessmentId < b.assessmentId
+            ? -1
+            : a.assessmentId > b.assessmentId
+              ? 1
+              : 0,
+        );
+      for (const balance of balances) {
+        const amount = balance.amount - balance.consumed;
+        if (
+          input.assessmentId !== undefined &&
+          balance.assessmentId !== input.assessmentId
+        )
+          continue;
+        if (amount === 0n) continue;
+        const unearned = key === "profit" && !earned;
+        if (
+          input.mode === "write_off" ||
+          (input.mode === "payoff" && unearned)
+        ) {
+          cancellations.push({
+            sliceId: slice.id,
+            assessmentId: balance.assessmentId,
+            bucket: key,
+            amount,
+            reason: unearned ? "unearned_profit" : "write_off",
+          });
+        } else {
+          candidates.push({
+            sliceId: slice.id,
+            assessmentId: balance.assessmentId,
+            bucket: key,
+            destinationAccountId: balance.destinationAccountId,
+            amount,
+          });
+        }
+      }
+    }
+  }
+  const outstanding = candidates.reduce((sum, row) => sum + row.amount, 0n);
+  if (input.mode === "write_off")
+    return { postings: [] as AllocationPosting[], cancellations, amount: 0n };
+  if (input.assessmentId !== undefined && !assessments.has(input.assessmentId))
+    throw new Error("assessment is not in the allocation");
+  const payment = input.payment ?? outstanding;
+  if (input.mode === "payment" && payment === 0n)
+    throw new Error("assessment already consumed");
+  if (
+    payment > outstanding ||
+    (input.mode === "payoff" && payment !== outstanding)
+  )
+    throw new Error("payment does not match outstanding allocation");
+  let remaining = payment;
+  const postings: AllocationPosting[] = [];
+  for (const candidate of candidates) {
+    const amount = candidate.amount < remaining ? candidate.amount : remaining;
+    if (amount > 0n) postings.push({ ...candidate, amount });
+    remaining -= amount;
+    if (remaining === 0n) break;
+  }
+  return { postings, cancellations, amount: payment };
+}
+
+/** Reverse recorded postings once, without reopening the consumed assessment. */
+export function planAllocationRefund(
+  postings: readonly AllocationPosting[],
+  originalPayer: string,
+  refundedAssessments: readonly string[],
+  assessmentId?: string,
+) {
+  if (!originalPayer || postings.length > 366 * 256)
+    throw new Error("invalid allocation receipt");
+  const selected = postings.filter(
+    (row) => assessmentId === undefined || row.assessmentId === assessmentId,
+  );
+  if (!selected.length)
+    throw new Error("assessment has no recorded allocation");
+  const seen = new Set<string>();
+  return selected.map((row) => {
+    if (
+      row.amount <= 0n ||
+      !row.destinationAccountId ||
+      !row.assessmentId ||
+      seen.has(row.assessmentId) ||
+      refundedAssessments.includes(row.assessmentId)
+    )
+      throw new Error("assessment already refunded or invalid receipt");
+    seen.add(row.assessmentId);
+    return {
+      assessmentId: row.assessmentId,
+      amount: row.amount,
+      sourceAccountId: row.destinationAccountId,
+      destinationAccountId: originalPayer,
+    };
+  });
+}
+
+/** Evaluate a slice gate from the same locked consumption balances used to allocate. */
+export function matchesAllocationConsumption(
+  clause: {
+    readonly buckets: readonly AllocationBucketKey[];
+    readonly check: "settled" | "outstanding";
+  },
+  slice: AllocationSlice,
+): boolean {
+  if (
+    !clause.buckets.length ||
+    new Set(clause.buckets).size !== clause.buckets.length
+  )
+    throw new Error("allocation gate needs distinct buckets");
+  const settled = clause.buckets
+    .map((key) => {
+      const rows = slice.buckets.filter((bucket) => bucket.key === key);
+      for (const row of rows)
+        if (row.consumed < 0n || row.consumed > row.amount || row.amount < 0n)
+          throw new Error("invalid consumption");
+      return rows.every((row) => row.consumed === row.amount);
+    })
+    .every(Boolean);
+  return clause.check === "settled" ? settled : !settled;
+}

package/src/diagnostics.ts

@@ -12,7 +12,6 @@ export type UdlDiagnosticFamily =
   | "evolution"
   | "finance"
   | "gates"
-  | "journey"
   | "lifecycle"
   | "schema";
 
@@ -191,37 +190,6 @@ const diagnosticDefinitions = {
     fix: "Use only the sealed UDL JSON Schema subset.",
   },
 
-  journey_unknown_operation: {
-    category: "invalid_semantics",
-    family: "journey",
-    title: "Journey operation is not in the composition",
-    fix: "Name an operation in the composition closure.",
-  },
-  journey_unknown_example: {
-    category: "invalid_semantics",
-    family: "journey",
-    title: "Journey example does not exist",
-    fix: "Name an authored example on the journey operation.",
-  },
-  journey_invalid_transition: {
-    category: "invalid_semantics",
-    family: "journey",
-    title: "Journey lifecycle transition is invalid",
-    fix: "Order the steps so each action starts from the state produced by earlier steps.",
-  },
-  journey_unbound_reference: {
-    category: "invalid_semantics",
-    family: "journey",
-    title: "Journey reference is unbound or has the wrong kind",
-    fix: "Bind every reference input to an earlier step that creates the required kind.",
-  },
-  journey_duplicate_step_id: {
-    category: "invalid_semantics",
-    family: "journey",
-    title: "Journey step id is duplicated",
-    fix: "Give every named step in the journey a unique id.",
-  },
-
   UDL7001: {
     category: "invalid_evolution",
     family: "evolution",

package/src/distribution.ts

@@ -0,0 +1,61 @@
+import type { UdlAction } from "./schema.js";
+
+/** Arithmetic only. The host resolves and consumes the receipt and snapshot under locks. */
+export function distributeReceiptAmounts(
+  clause: NonNullable<UdlAction["receiptDistribution"]>,
+  principal: bigint,
+  profit: bigint,
+  tickets: readonly { readonly id: string; readonly weight: bigint }[],
+) {
+  if (principal < 0n || profit < 0n || tickets.length === 0)
+    throw new Error(
+      "distribution requires nonnegative receipt amounts and tickets",
+    );
+  if (
+    new Set(tickets.map((ticket) => ticket.id)).size !== tickets.length ||
+    tickets.some((ticket) => ticket.weight <= 0n)
+  )
+    throw new Error(
+      "snapshot tickets must have unique identities and positive weights",
+    );
+  const loss = clause.mode === "loss";
+  if (loss && (profit !== 0n || clause.feeBps !== 0 || clause.vatBps !== 0))
+    throw new Error("loss allocation contains only principal and no fees");
+  const totalWeight = tickets.reduce((sum, ticket) => sum + ticket.weight, 0n);
+  const fee = (profit * BigInt(clause.feeBps)) / 10000n;
+  const vat = (fee * BigInt(clause.vatBps)) / 10000n;
+  const amount = principal + profit - fee - vat;
+  if (amount < 0n) throw new Error("fee and VAT exceed the receipt");
+  const shares = tickets.map((ticket) => ({
+    id: ticket.id,
+    amount: (amount * ticket.weight) / totalWeight,
+  }));
+  let residual = amount - shares.reduce((sum, share) => sum + share.amount, 0n);
+  if (loss) {
+    // A loss cannot be paid to a residual cash beneficiary. Largest remainder
+    // assigns every lost minor unit to an investor, with identity breaking ties.
+    const ordered = tickets
+      .map((ticket, index) => ({
+        index,
+        id: ticket.id,
+        remainder: (amount * ticket.weight) % totalWeight,
+      }))
+      .sort((a, b) =>
+        a.remainder === b.remainder
+          ? a.id < b.id
+            ? -1
+            : a.id > b.id
+              ? 1
+              : 0
+          : a.remainder > b.remainder
+            ? -1
+            : 1,
+      );
+    for (const ticket of ordered) {
+      if (residual === 0n) break;
+      shares[ticket.index]!.amount += 1n;
+      residual -= 1n;
+    }
+  }
+  return { fee, vat, residual, shares };
+}

package/src/effects.ts

@@ -133,6 +133,13 @@ export function deriveUdlActionEffects(
         ) {
           continue;
         }
+        if (
+          descriptor.kind === "moves" &&
+          ((clause.target === "allocate" && object?.mode === "write_off") ||
+            (clause.target === "receiptDistribution" &&
+              object?.mode === "loss"))
+        )
+          continue;
         const suffix = effectSignatureSuffix(descriptor, object);
         if (!suffix) continue;
         (effects[descriptor.kind] ??= []).push({
@@ -159,7 +166,26 @@ function actionClauseValue(
 ): unknown {
   const [head, tail] = target.split(".");
   if (!head) return undefined;
-  const value = action[head];
+  const value =
+    head === "transitionsRefs"
+      ? [
+          ...(Array.isArray(action.transitionsRefs)
+            ? action.transitionsRefs
+            : []),
+          ...(Array.isArray(action.requiresRefs)
+            ? action.requiresRefs
+            : []
+          ).flatMap((gate) => {
+            const requirement = recordValue(gate);
+            const attests = recordValue(requirement?.attests);
+            return attests
+              ? [{ field: requirement?.field, action: attests.consume }]
+              : [];
+          }),
+        ]
+      : action[head];
+  if (head === "transitionsRefs" && Array.isArray(value) && value.length === 0)
+    return undefined;
   if (!tail) return value;
   return recordValue(value)?.[tail];
 }

package/src/evolution.ts

@@ -26,6 +26,13 @@ export interface EvolutionMoveSnapshot extends EvolutionStepSnapshot {
 }
 
 export interface EvolutionActionSnapshot {
+  readonly requiresInput?: unknown;
+  readonly engineOwned?: unknown;
+  readonly captureEngine?: unknown;
+  readonly requiresAllocation?: unknown;
+  readonly allocate?: unknown;
+  readonly contributionStage?: unknown;
+  readonly transitionsRefs?: unknown;
   /** Missing on snapshots written before receipt-input capture existed. */
   readonly captureInput?: unknown;
   readonly deadline: unknown;
@@ -66,6 +73,7 @@ export interface EvolutionActionSnapshot {
   readonly requiresDrainedAccount: unknown;
   /** Missing on snapshots written before exposure gates entered open UDL. */
   readonly requiresExposure?: unknown;
+  readonly unique?: unknown;
   readonly requiresRefs: unknown;
   /** Missing on snapshots written before reconcile expectations existed. */
   readonly reconcile?: unknown;
@@ -83,6 +91,10 @@ export interface EvolutionTransitionSnapshot {
 
 /** The complete serializable algebra protected by append-only evolution. */
 export interface InstrumentEvolutionSnapshot {
+  readonly templateBinding?: unknown;
+  readonly allocation?: unknown;
+  readonly contributions?: unknown;
+  readonly dateOrder?: unknown;
   /** Missing on snapshots written before UDL carried authored action order. */
   readonly actionOrder?: readonly string[];
   readonly aggregateInvariants: readonly string[];
@@ -126,14 +138,19 @@ export function snapshotUdlInstrument(
 ): InstrumentEvolutionSnapshot {
   const required = new Set(instrument.required);
   return {
+    templateBinding: instrument.templateBinding ?? null,
+    allocation: instrument.allocation ?? null,
+    contributions: instrument.contributions ?? null,
+    dateOrder: instrument.dateOrder ?? [],
     actionOrder: [...instrument.actionOrder],
     aggregateInvariants: (instrument.aggregateInvariants ?? []).map(
       aggregateInvariantKey,
     ),
     callerParkedStates: instrument.callerParkedStates ?? {},
-    derivedAmounts: (instrument.derivedAmounts ?? []).map(
-      (amount) =>
-        `${amount.field}=floor(${amount.sourceField}*${amount.rule.bps}/10000)`,
+    derivedAmounts: (instrument.derivedAmounts ?? []).map((amount) =>
+      amount.rule.kind === "minimum"
+        ? `${amount.field}=min(${amount.sourceField},${amount.rule.capField})`
+        : `${amount.field}=floor(${amount.sourceField}*${typeof amount.rule.bps === "number" ? amount.rule.bps : `fields.${amount.rule.bps.field}`}/10000)`,
     ),
     dials: instrument.dials ?? [],
     ...(instrument.distinctParties ? { distinctParties: true as const } : {}),
@@ -372,6 +389,18 @@ function diffInstrumentEvolutionMessages(
   }
   violations.push(...diffActions(previous.actions, next.actions));
   violations.push(...diffParties(previous.parties, next.parties));
+  for (const key of [
+    "allocation",
+    "contributions",
+    "dateOrder",
+    "templateBinding",
+  ] as const) {
+    if (
+      stableStringify(previous[key] ?? (key === "dateOrder" ? [] : null)) !==
+      stableStringify(next[key] ?? (key === "dateOrder" ? [] : null))
+    )
+      violations.push(`${key} contract changed`);
+  }
   violations.push(...diffAggregates(previous, next));
   if (
     stableStringify(Object.keys(previous.callerParkedStates ?? {}).sort()) !==
@@ -517,6 +546,13 @@ function evolutionIssue(message: string, instrumentBase: string): UdlIssue {
 
 function snapshotUdlAction(definition: UdlAction): EvolutionActionSnapshot {
   return {
+    requiresInput: definition.requiresInput ?? null,
+    engineOwned: definition.engineOwned ?? null,
+    captureEngine: definition.captureEngine ?? null,
+    requiresAllocation: definition.requiresAllocation ?? null,
+    allocate: definition.allocate ?? null,
+    contributionStage: definition.contributionStage ?? null,
+    transitionsRefs: definition.transitionsRefs ?? [],
     captureInput: definition.captureInput ?? null,
     commit: definition.commit ?? null,
     deadline: definition.deadline ?? null,
@@ -551,6 +587,7 @@ function snapshotUdlAction(definition: UdlAction): EvolutionActionSnapshot {
     requiresAggregate: definition.requiresAggregate ?? [],
     requiresDrainedAccount: definition.requiresDrainedAccount ?? null,
     requiresExposure: definition.requiresExposure ?? [],
+    unique: definition.unique ?? null,
     requiresRefs: definition.requiresRefs ?? [],
     reconcile: definition.reconcile ?? null,
     steps: definition.steps.map((step) => ({
@@ -716,6 +753,12 @@ function diffActions(
     ) {
       violations.push(`action ${action} changed its drained-account gate`);
     }
+    if (
+      stableStringify(descriptor.unique ?? null) !==
+      stableStringify(current.unique ?? null)
+    ) {
+      violations.push(`action ${action} changed its subject uniqueness claim`);
+    }
     if (
       descriptor.requiresExposure !== undefined &&
       stableStringify(descriptor.requiresExposure) !==
@@ -736,6 +779,23 @@ function diffActions(
     ) {
       violations.push(`action ${action} changed its payout intent`);
     }
+    for (const key of [
+      "requiresInput",
+      "engineOwned",
+      "captureEngine",
+      "requiresAllocation",
+      "allocate",
+      "contributionStage",
+      "transitionsRefs",
+    ] as const) {
+      if (
+        stableStringify(
+          descriptor[key] ?? (key === "transitionsRefs" ? [] : null),
+        ) !==
+        stableStringify(current[key] ?? (key === "transitionsRefs" ? [] : null))
+      )
+        violations.push(`action ${action} changed its ${key} contract`);
+    }
     if (descriptor.earnable !== current.earnable) {
       violations.push(`action ${action} changed its earnable flag`);
     }