@hyperscale0/udl 2.6.0 → 3.0.0

package/docs/reference/cli.md

@@ -1,24 +0,0 @@
-<!-- Generated by scripts/docs/build.ts from @hyperscale0/udl 2.6.0. Edit the source, not cli.md. -->
-
-# Command reference
-
-In the full repository checkout, run `bun open/udl/src/cli.ts validate <file.udl.json>` from the repository root. The entrypoint is `open/udl/src/cli.ts`; in a standalone package checkout it is `src/cli.ts`. Use this local validator for local HSX output.
-
-The installed `udl` binary exposes the following commands and exit codes.
-
-```text
-udl - the Universal Domain Language toolchain
-
-usage:
-  udl validate <file>          parse <file> and report every issue found
-  udl fmt <file> [--write]     print the canonical form, or rewrite the file
-  udl canon <file> [--digest]  print canonical bytes, or their SHA-256 digest
-  udl diff <live> <next>       check <next> against the append-only law
-  udl explain UDL####          explain one stable diagnostic code
-  udl help                     print this
-
-exit codes:
-  0  the document is admissible, or the change is additive
-  1  the document was refused, or the change breaks the append-only law
-  2  the command line was wrong, or a file could not be read
-```

package/docs/reference/diagnostics.md

@@ -1,38 +0,0 @@
-<!-- Generated by scripts/docs/build.ts from @hyperscale0/udl 2.6.0. Edit the source, not diagnostics.md. -->
-
-# Diagnostic reference
-
-Codes are stable. Titles and messages may become clearer without changing the code. Apply the listed fix, then validate the whole document again.
-
-| Code      | Family    | Category          | Title                                                   | Fix                                                                                                                |
-| --------- | --------- | ----------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
-| `UDL1001` | admission | invalid_utf8      | Invalid UTF-8                                           | Encode the document as valid UTF-8.                                                                                |
-| `UDL1002` | admission | invalid_json      | Invalid JSON                                            | Repair the JSON syntax before validation.                                                                          |
-| `UDL1003` | admission | invalid_shape     | Invalid document shape                                  | Match the published UDL JSON Schema.                                                                               |
-| `UDL1004` | admission | resource_limit    | Resource limit exceeded                                 | Reduce the source size, nesting, values, strings, references, or financial paths named by the message.             |
-| `UDL2001` | document  | invalid_semantics | Duplicate declaration                                   | Give each declaration a unique name.                                                                               |
-| `UDL2002` | document  | invalid_semantics | Document law violation                                  | Repair the declaration, subject contract, or derived effects named by the message.                                 |
-| `UDL2005` | document  | invalid_semantics | Derived effects mismatch                                | Regenerate the action effects from its clauses.                                                                    |
-| `UDL2010` | document  | invalid_semantics | Action graph violation                                  | Order all actions and calls without cycles or collisions, within depth and count limits.                           |
-| `UDL2011` | document  | invalid_semantics | Action binding violation                                | Bind parameters to declared instance, piece, or caller variables without forward references or duplicate captures. |
-| `UDL2012` | document  | invalid_semantics | Action authority violation                              | Match principal, approval, and recovery policies and keep field paths within tenant boundary.                      |
-| `UDL2013` | document  | invalid_semantics | Action effect or evidence violation                     | Provide valid effect kind, matching effect signature, and non-empty evidence for every leaf.                       |
-| `UDL3001` | lifecycle | invalid_semantics | Lifecycle is not closed                                 | Declare every state and action transition, and make every state reachable.                                         |
-| `UDL4001` | finance   | invalid_semantics | Money graph violation                                   | Balance every funded amount and close every hold on each lifecycle path.                                           |
-| `UDL4002` | finance   | invalid_semantics | Piece partition violation                               | Match piece plan total, amounts, and payees to required immutable fields and declared partition.                   |
-| `UDL5001` | gates     | invalid_semantics | Reference gate violation                                | Point the gate at a declared instrument, action, state, field, and reference.                                      |
-| `UDL5002` | gates     | invalid_semantics | Check requirement violation                             | Use a declared check with compatible evidence and recurrence.                                                      |
-| `UDL5003` | gates     | invalid_semantics | Exposure gate violation                                 | Use declared account and money fields for the exposure gate.                                                       |
-| `UDL5004` | gates     | invalid_semantics | Aggregate law violation                                 | Point the aggregate at compatible parent and child fields.                                                         |
-| `UDL5005` | gates     | invalid_semantics | Settlement or payout violation                          | Use a declared settlement account and a compatible payout statement line.                                          |
-| `UDL5006` | gates     | invalid_semantics | Quote and commit violation                              | Declare one complete quote freeze set and one matching commit action.                                              |
-| `UDL5007` | gates     | invalid_semantics | Reconcile exception child violation                     | Name a declared child whose reference points back to this instrument.                                              |
-| `UDL5008` | gates     | invalid_semantics | Action clause violation                                 | Repair the clause fields and keep incompatible clauses separate.                                                   |
-| `UDL5009` | gates     | invalid_semantics | Reconcile exception amount field is missing or optional | Name the exception child's required money field in amountField.                                                    |
-| `UDL5010` | gates     | invalid_semantics | Reconcile exception amount field has the wrong type     | Point amountField at a money field declared by the exception child.                                                |
-| `UDL5011` | gates     | invalid_semantics | Reconcile exception reason field is missing or optional | Name the exception child's required text field in reasonField.                                                     |
-| `UDL5012` | gates     | invalid_semantics | Reconcile exception reason field has the wrong type     | Point reasonField at a required plain text field declared by the exception child.                                  |
-| `UDL5013` | gates     | invalid_semantics | Piece stage violation                                   | Reference a declared piece plan and stage in the containing instrument.                                            |
-| `UDL6001` | schema    | invalid_semantics | Unsupported JSON Schema                                 | Use only the sealed UDL JSON Schema subset.                                                                        |
-| `UDL7001` | evolution | invalid_evolution | Stored contract changed                                 | Keep stored identities and contracts unchanged, and add only allowed optional declarations.                        |
-| `UDL7002` | evolution | invalid_evolution | Version was not increased                               | Increase the product version for every semantic change.                                                            |

package/skills/udl/SKILL.md

@@ -1,28 +0,0 @@
----
-name: udl
-description: Read, validate, explain, or write Universal Domain Language documents directly. Use for canonical UDL JSON and format-level diagnostics. SDK and MCP consumers should use their generated contracts instead.
----
-
-# UDL
-
-Use UDL when the task concerns the canonical product document, format conformance, or a validator implementation. Use HSX when authoring a product from reusable modules.
-
-## Read first
-
-1. Read `docs/guide/01-a-document.md` for the document frame.
-2. Read `docs/guide/03-laws.md` before changing lifecycle, money, gates, or references.
-3. Look up exact fields in `spec/udl.schema.json` and clauses in `docs/reference/clauses.md`.
-
-## Edit loop
-
-1. Change the smallest complete clause.
-2. Run `udl validate <file>`.
-3. Look up each `UDL####` code with `udl explain UDL####` or `docs/reference/diagnostics.md`.
-4. Apply the listed fix. Validate the whole document again.
-5. Run `udl canon <file> --digest` before pinning bytes or an identity.
-
-Never hand-author `effects`. Derive them from action clauses. Never represent money as a JSON number. Use an integer minor-unit string and its declared currency. Never add a money move without checking every terminal lifecycle path for a matching drain or unwind.
-
-For a stored definition, validate both documents before `udl diff <live> <next>`. Treat any `UDL7xxx` result as a refused change. A data migration does not make an incompatible document edit additive.
-
-Validator work must run the complete `conformance/` contract and follow `docs/reference/canonical.md` byte for byte.

package/src/allocation.ts

@@ -1,259 +0,0 @@
-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/check-profiles.ts

@@ -1,80 +0,0 @@
-/**
- * Evidence profiles that an instrument action may require before it runs.
- * The public grammar and the runtime both read this table. A pair absent here
- * cannot gate an action.
- */
-export interface UdlCheckEvidenceProfile {
-  readonly family: string;
-  readonly checkKind: string;
-  readonly kindField?: string;
-  readonly statusField: string;
-  readonly statuses: readonly string[];
-}
-
-export const udlCheckEvidenceProfiles = [
-  {
-    family: "national_identity",
-    checkKind: "identity_verification",
-    kindField: "checkKind",
-    statusField: "verificationStatus",
-    statuses: [
-      "requested",
-      "waiting",
-      "completed",
-      "rejected",
-      "expired",
-      "error",
-    ],
-  },
-  {
-    family: "national_identity",
-    checkKind: "contact_ownership_verification",
-    kindField: "checkKind",
-    statusField: "matchResult",
-    statuses: ["match", "no_match"],
-  },
-  {
-    family: "credit_bureau",
-    checkKind: "consumer_inquiry",
-    kindField: "inquiryType",
-    statusField: "bureauStatus",
-    statuses: ["returned", "acknowledged", "correction_required"],
-  },
-  {
-    family: "credit_bureau",
-    checkKind: "commercial_inquiry",
-    kindField: "inquiryType",
-    statusField: "bureauStatus",
-    statuses: ["returned", "acknowledged", "correction_required"],
-  },
-  {
-    family: "credit_bureau",
-    checkKind: "facility_report",
-    kindField: "inquiryType",
-    statusField: "bureauStatus",
-    statuses: ["returned", "acknowledged", "correction_required"],
-  },
-  {
-    family: "sanctions_screening",
-    checkKind: "screen",
-    kindField: "checkKind",
-    statusField: "screeningStatus",
-    statuses: ["clear", "hit", "manual_review"],
-  },
-  {
-    family: "enforcement_instrument",
-    checkKind: "note_request",
-    statusField: "requestStatus",
-    statuses: ["debtor_approved", "debtor_rejected", "auto_cancelled"],
-  },
-] as const satisfies readonly UdlCheckEvidenceProfile[];
-
-/** Returns the tenant-gateable evidence profile for one family and check. */
-export function udlCheckEvidenceProfile(
-  family: string,
-  checkKind: string,
-): UdlCheckEvidenceProfile | undefined {
-  return udlCheckEvidenceProfiles.find(
-    (profile) => profile.family === family && profile.checkKind === checkKind,
-  );
-}

package/src/distribution.ts

@@ -1,61 +0,0 @@
-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 };
-}