@hyperscale0/udl 4.9.0 → 5.1.0

package/docs/README.md

@@ -1,294 +0,0 @@
-# UDL 4
-
-UDL is the Universal Domain Language, the typed contract between an HSX program
-and its executor. The grammar
-lives in `src/schema.ts`. Generate `udl.schema.json` with
-`bun scripts/emit-spec.ts --write`. There is no migration reader for earlier UDL.
-
-## Reading a compiled program
-
-Start with `product`, `title` and `currency`. `objects` describes business records
-and their attachments. Follow an attachment's instrument identity into
-`instruments` for its retained fields, lifecycle and actions. `actionOrder`
-preserves authored action order even though canonical JSON sorts object keys.
-An action's `publicAction` supplies its exposed name; its actor and requirements
-still control who may execute it and when.
-
-Object metadata describes the subject. Instrument fields retain the agreement's
-terms, account bindings and receipts. Party names identify authenticated or
-configured participants. None of these makes a caller-supplied account ID valid.
-A Build freezes this contract and its bindings for the executor.
-
-Business instructions are actions composed from typed requirements and effects.
-The four `internal_transfer` instructions are their money effects. The contract
-expresses valid conditions; execution can still refuse for the current state,
-authority, evidence or balance. Parsing and validation execute nothing.
-
-## JSON admission and canonical bytes
-
-The parser refuses duplicate JSON member names, including escaped spellings of
-one name. Decoded documents must contain finite JSON data. Accessors, cycles,
-sparse arrays, symbol keys, hidden properties and `__proto__` members refuse
-before schema parsing. Shared values count once per occurrence toward the budget.
-Admission permits at most 100,000 visited values, 32 nesting levels, 240 code units
-per key and 1 MiB of UTF-8 key and string data. Source text has a separate 1 MiB
-byte limit. These bounds live in `src/limits.ts`.
-
-Canonical JSON sorts object keys recursively, preserves array order and ends
-with a newline. Schema defaults are part of the admitted document. Equivalent
-key insertion orders and explicit defaults have the same digest. Object field
-compatibility and evolution comparisons use the same key ordering.
-
-## Objects and subjects
-
-An object kind declares identity, title, authored field names, normalized fields
-and display columns. Each attachment freezes its instrument identity and party
-parameter bindings to `owner`, `actor`, `operator`, or a declared Product party. Core resolves role bindings from the object row, session and Product, and
-declared parties from the Product party binding. `authoredFields` records only names declared in the HSX
-object block. `fields` is their union with attached action requirements. Matching
-names must have matching types and constraints. Account fields belong to
-instruments, never objects.
-
-An instrument may name its object kind with `subject`. An action's `subject`
-contains its requirements and any frozen adapter binding. Each requirement keeps
-its source field and optional `objectField` rename. Adapter snapshots contain
-provider, capability, operation, declaration digest and requirements. A null snapshot
-marks an unbound adapter. It permits discovery but blocks that action. No provider
-requirement is inferred from an operation name.
-
-Object creation accepts `{}`. Its optional `fields` property accepts every
-normalized field as optional. Requirements become mandatory only when the
-attached action runs. Object creation performs no financial action. Instrument
-creation remains internal; an attached create action may expose a public name.
-Attachment parties resolve from authenticated authority, never from party account
-IDs supplied in a caller body.
-
-`object-contract.ts` projects `ObjectDiscovery` for
-`GET /v1/products/{productId}/objects`. It exports the discovery, instance, list
-and action response types. Discovery preserves Build identity, authored field
-names, the full optional create schema and each exposed action's requirements.
-Object instances carry `objectId`, `kind`, `revision`, optional `externalId`,
-`fields` and `productBuildId`. Action responses carry the object and either a
-financial instrument outcome or null.
-
-An object may declare `entryActions`, a list of exposed attachment creation
-names. The host admits an active enrolled customer only to an entry action whose
-actor is the session's `actor` role. Other records remain closed. Retained
-participants can read their record and use the actions granted to their roles;
-participation never changes the owner.
-
-An instrument may declare `scope: "product"`. Object creation can resolve a
-reference to that instrument on another record in the same Product when every
-retained party account matches the current bindings. Otherwise references stay
-on the current record. Create and approve shared limits once per Product or
-borrower; referencing them does not create a new limit.
-
-## Object operations
-
-The host owns transport routes for object discovery, creation, listing,
-retrieval, action availability, execution and agreement evidence.
-`src/object-contract.ts` defines the language package's object projections.
-
-Execution binds `productBuildId`, `digest`, `target` and `expectedRevision`.
-The target identifies an attachment or an existing instance on that attachment.
-The optional `fields` collect subject metadata; optional `input` carries the action's typed input.
-Missing requirements refuse execution. Callers reuse an idempotency key only for
-retries of the same request. Staff Create for may name `ownerPrincipalId` through
-its authorized path; ordinary ownership comes from the session.
-
-## Accounts and money
-
-A document declares SAR once. Money is a nonnegative minor-unit decimal string
-of at most 18 digits. Percentages are basis points, durations are positive integer
-milliseconds, and dates are timestamps with explicit offsets.
-
-An account field binds a party, the instrument itself, or an adapter. Party owners
-are names; `owner: "self"` provisions an account per instance. An adapter owner
-is `{ "adapter": "insurer" }`, where `insurer` names an adapter declared in one
-of the instrument's action subjects. The agreement retains that declaration's
-provider identity. Missing or conflicting bindings refuse with
-`subject_adapter_unbound`; changing an existing account binding refuses with
-`account_binding_changed`. A null declaration can describe a draft but cannot
-create an adapter-owned account.
-
-Account creation and binding are executor work. Callers never supply account IDs.
-Accounts declare `book: "cash" | "claim"`, defaulting to cash. Moves never cross books.
-Only claim accounts may declare `contra: true` and permit a negative balance.
-Party and adapter accounts share owner, book and key within a Product; the key
-defaults to `balance`. Adapter aliases for the same provider share that account. Transfers between
-known aliases of one account refuse, including self fields with the same key.
-The executor scopes provider accounts to the tenant and Product, with the Product
-participant as ledger custodian. Providers are not parties. An account owned by
-self defaults its key to the field name. Named capital, premium, income, debt and
-loss balances use explicit keys. `party.buyer` is the buyer's default cash account.
-
-A plain move to an adapter account credits its ledger balance. It does not prove
-an external payout. Provider confirmation still uses a boundary reservation and
-instruction-bound evidence. Account ownership adds no settlement operation.
-
-Disbursement moves cash from lender to borrower and claims from borrower debt to
-principal and profit receivables. Repayment moves borrower cash to lender cash and
-the same claim amounts from receivables back to borrower debt. Unearned profit is
-cancelled by the claim move alone. Write-off moves the principal claim to the
-lender's loss account, with no cash movement. The library declares when profit
-is earned: on payment, by schedule or at disbursement.
-These are ordinary paired moves in HSX, not executor loan rules.
-
-A value is `{literal: value}` or `{field: path}`. Paths start with `self`, `input`, `subject`
-or `party`. Reference fields allow typed traversal. Account paths expose locked,
-read-only `.balance` and `.reserved` money values. `self.id`, `self.status`,
-`self.createdAt` and `self.now` are sealed executor values. Callers cannot set
-constants, calculated fields, account bindings or capture fields. Create supplies
-declared typed references; later actions cannot replace them. A ref declares `targetKind: "object" | "instrument"` and one target id or
-a list of 1 to 16 distinct target ids in that namespace. Its stored value is an
-identity from one listed target. Path traversal exposes only fields
-with compatible types on every target. Nested refs combine their target sets;
-accounts must agree on owner, key, book and contra flags, and enums must
-have the same values. A comparison or selection anchor must share a possible
-reference target. An invoked input must accept every possible supplied target.
-The executor checks the actual instance type at admission.
-
-## Calculation and movement
-
-Calculations form a finite dependency graph. `sum`, `subtract` and `minimum`
-operate on money or integer fields, with operands of the same type as the target.
-`rate`, `multiply`, `divide` and `shift` retain their typed operands. A shift's
-`milliseconds` operand is a duration field or a non-negative safe integer literal.
-Zero leaves the date unchanged; duration fields still require positive values. Rate and
-division round down. Weighted shares also round down; residual minor units go
-to the declared residual account. Cash and loss use this one rounding rule.
-There is no largest-remainder allocation. Subtraction refuses a negative result. Integer results must
-be safe integers. No calculation evaluates source text.
-
-The only move instructions are `internal_transfer.create`,
-`internal_transfer.reserve`, `internal_transfer.post` and `internal_transfer.void`.
-Create and reserve declare an amount, from account and to account. Reserve captures
-its executor-produced transfer identity into a declared self text field. Post and
-void consume that identity. Callers cannot create or replace captured identities.
-Adapter-owned endpoints use the same move vocabulary.
-
-Each move may declare `economics: { purpose, sourceParty, reversalOf? }`.
-Purpose is `earning`, `principal`, `participant_payout`, `internal`,
-`prepaid_credit`, or `pass_through`. Pass-through money is excluded from earnings
-and costs. `sourceParty` names an authored party whose retained
-participant must own the debit account. For an earning realized from company-held
-customer money, it identifies the retained payer instead. The debit must be an
-instrument account bound to the same agreement or a retained referenced agreement
-in the same Build with the same payer; the company credit must be outside the
-agreement. Evidence also retains the actual debit account participant.
-`reversalOf` is a transfer reference path. A reversal preserves purpose, Product, Build and agreement, debits the
-original recipient account and credits the original source participant. The
-combined refunds cannot exceed the original posted amount. A post inherits its
-reservation's economics; it cannot change them.
-The terminal ledger evidence keeps these fields with the agreement, Build,
-account participants, and move key. A move without economics has no inferred
-classification.
-
-A loan, refund, payoff, write-off or distribution is library behavior built from
-accounts, calculations and ordered moves. None has a privileged executor clause.
-Outstanding principal is an account balance. A schedule consists of explicit
-dated child records, with positions 1 through n in declaration order. The library
-uses ordinary comparisons and aggregates to constrain those records. There is no
-recurrence process, allocation bucket, partition expander or schedule requirement
-in the UDL kernel.
-
-## Admission and lifecycle
-
-Actions declare typed input lists, requirements, an actor and an event. Lifecycle
-edges name their source and destination states. Requirements and effects execute
-atomically under the same account and reference locks. `set` copies typed values
-to mutable fields. Action calculations read the locked snapshot and populate the
-action draft before requirements. Ordered moves and invocations follow admission;
-a zero create move refuses unless the action declares `allowZero: true`.
-With that permission it records no transfer or capture. A reserve amount must
-always be positive.
-Invariants check the completed transaction. A due instant
-is inclusive; a deadline is exclusive. Clock delays never extend deadlines.
-
-Requirements are compare, state, unique, aggregate, evidence and hours.
-A typed selection names one instrument or a bounded union, a reference field,
-anchor, accepted states and row limit. Exceeding the limit refuses rather than
-truncates. Optional equality filters apply to every selected type. An optional
-window selects date values between `self.now - milliseconds` and `self.now`.
-Aggregate sums use typed paths on the selected records, including account
-balances. An invariant holds before and after every affected transaction.
-
-`hours` converts a date path to its literal IANA timezone and accepts `[start,end)`.
-A start greater than end wraps midnight; equal endpoints admit no time.
-`evidence` declares subject, family, check, result and maxAge. The subject is an
-account or text id. The executor selects the newest matching subject binding,
-checks its retained Build, protected input digest and adapter declaration, then
-requires the declared result and age. A newer matching refusal or pending result
-prevents reuse of an older success.
-
-`invoke` supplies typed inputs to a linked action or bounded selection. Its graph
-is acyclic and bounded. Public names grant no authority; clock and parent actors
-remain executor-owned. A public action on a subject instrument requires an
-attachment on that object kind. State requirements refer to instrument instances;
-objects have no instrument lifecycle. List extraction preserves the reference
-namespace and target. Selection anchors and filters participate in calculation
-cycle detection. Literal assignments must satisfy the destination field's constraints.
-
-A captured transfer exposes its executor-owned `.status`. A boundary payout
-reserves before dispatch. Only matching terminal confirmation can post or void
-the reservation. An acknowledgement, transport failure or missing response
-keeps the reservation. A refund is a separately funded move. Account balances
-alone do not prove an external effect. The language adds no automatic
-provider-failure reversal or deadline settlement policy.
-
-## Ten laws
-
-1. Each concept has one concrete meaning.
-2. Provider transport and credentials stay outside the contract.
-3. Every state change emits its declared event.
-4. Four transfer instructions are the only money movement vocabulary.
-5. Instances have an opaque identity and money uses integer minor units.
-6. Typed requirements and effects execute atomically.
-7. Live additions preserve existing meaning; development estates may recreate.
-8. Business names identify object kinds, attached instruments and public actions.
-9. Waiting uses lifecycle states and clocks. Before admission, the executor
-   catches up actor: clock actions with due instants on the locked instance,
-   references and selected rows, in chronological order. Catch-up commits its
-   own transaction and events before the caller request is evaluated. A refused
-   caller request rolls back only its own drafts. Caller deadlines are refusal
-   boundaries; they never execute the caller action. Separate clock actions
-   carry expiry consequences. Requirements and selections observe the resulting
-   clock state.
-10. References close, states are reachable, captures are linear, and terminal
-    instances have no remaining owned-account balances or reservations.
-
-## Clause inventory
-
-The generated [JSON schema](../spec/udl.schema.json) owns the complete field
-inventory, defaults and constraints. `src/schema.ts` is its source.
-
-`calculate.aggregate` reads a typed selection and yields its count or a money sum. `calculate.ratio` computes floor(amount * numerator / denominator) with arbitrary-precision intermediates and refuses a zero denominator. Numerator and denominator share a numeric type. Selection order is a list of typed ascending paths, followed by identity as the final tie-break. `invoke {instrument, action: "create", input}` creates a child record in the same transaction; its inputs resolve in the caller, and the ordinary create actor and requirements still apply.
-
-`calculate.at` reads a typed list at a one-based position and refuses an out-of-range index. Its result has the list item type. Integer divide accepts integer operands and rounds down. Every move may capture its transfer identity into a declared self text field; reserve requires a capture. Captures and their status paths are executor-owned.
-
-## Reporting definitions
-
-An instrument may declare `reports`, a bounded array of strict ReportDefinition
-values. Each definition contains identity/version, scope, datasets, time,
-selection, calculation, validation, output and authority. The JSON schema defines
-all fields. Expressions form an ordered graph with backward references, typed
-money in integer minor units, explicit ratios and date operations. Source fields
-must exist in every bound instrument. A scalar field cannot acquire a suffix;
-account balances use the declared `<account>.balance` path. Company instrument reports require
-cross-Build bindings and are not admitted in this version.
-
-Joins declare one-or-many cardinality, missing-record policy and aggregates;
-implicit row multiplication is forbidden. Compilation checks currencies, column
-and expression types, output columns and sort keys. Execution must check complete
-source populations, required facts, unique row and sort identities, reconciliation
-and declared limits before publishing any result. Empty-population behavior and
-unavailable facts are definition data. Request, read and release roles are
-separate. Independent activation and retained deterministic replay belong to the
-host; language acceptance alone does not authorize an artifact or external release.
-
-Reporting source selections and foreign join keys must be computable from
-PostgreSQL facts; ledger balances and ratios belong after capture. Aggregate
-names are unique across stages. `average` requires an explicit `rounding` policy
-(`floor` or `halfUp`) to retain integer and money minor-unit types. Numeric and
-min/max aggregates skip nulls, return null for all-null inputs, and emit per-row
-`_skippedNulls_<name>` counters in JSON and CSV. Required facts still refuse nulls.

package/src/cli.ts

@@ -1,196 +0,0 @@
-#!/usr/bin/env node
-/**
- * The `udl` command. Actions over the same library the compiler uses:
- * `validate` answers whether a document is admissible, `fmt` writes the
- * canonical bytes, and `diff` answers whether a change is legal against a
- * document that already has live instances.
- */
-import { readFile, writeFile } from "node:fs/promises";
-
-import {
-  canonicalizeUdl,
-  canonicalDigest,
-  diffValidatedUdlEvolution,
-  parseUdl,
-  UdlError,
-  type UdlDocument,
-  udlDiagnostic,
-} from "./index.js";
-
-const USAGE = `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`;
-
-async function main(argv: readonly string[]): Promise<number> {
-  const [command, ...rest] = argv;
-  switch (command) {
-    case "help":
-    case "-h":
-    case "--help":
-      console.log(USAGE);
-      return 0;
-    case "validate":
-      return validateCommand(rest);
-    case "fmt":
-      return formatCommand(rest);
-    case "canon":
-      return canonCommand(rest);
-    case "diff":
-      return diffCommand(rest);
-    case "explain":
-      return explainCommand(rest);
-    case undefined:
-      return usageError("udl: no command given");
-    default:
-      return usageError(`udl: unknown command ${command}`);
-  }
-}
-
-async function canonCommand(args: readonly string[]): Promise<number> {
-  const digest = args.includes("--digest");
-  const [file, ...extra] = args.filter((argument) => argument !== "--digest");
-  if (file === undefined || extra.length > 0) {
-    return usageError("usage: udl canon <file> [--digest]");
-  }
-  const bytes = await readDocument(file);
-  if (bytes === null) return 2;
-  let document: UdlDocument;
-  try {
-    document = parseUdl(bytes);
-  } catch (error) {
-    return reportIssues(file, error);
-  }
-  if (digest) console.log(await canonicalDigest(document));
-  else process.stdout.write(canonicalizeUdl(bytes));
-  return 0;
-}
-
-function explainCommand(args: readonly string[]): number {
-  const [code, ...extra] = args;
-  if (code === undefined || extra.length > 0) {
-    return usageError("usage: udl explain UDL####");
-  }
-  const diagnostic = udlDiagnostic(code);
-  if (!diagnostic) {
-    return usageError(`udl: unknown diagnostic code ${code}`);
-  }
-  console.log(`${code} ${diagnostic.title}`);
-  console.log(`category: ${diagnostic.category}`);
-  console.log(`family: ${diagnostic.family}`);
-  console.log(`fix: ${diagnostic.fix}`);
-  return 0;
-}
-
-async function validateCommand(args: readonly string[]): Promise<number> {
-  const [file, ...extra] = args;
-  if (file === undefined || extra.length > 0) {
-    return usageError("usage: udl validate <file>");
-  }
-  const bytes = await readDocument(file);
-  if (bytes === null) return 2;
-  if (parseDocument(file, bytes) === null) return 1;
-  console.log(`${file}: ok`);
-  return 0;
-}
-
-async function formatCommand(args: readonly string[]): Promise<number> {
-  const write = args.includes("--write");
-  const [file, ...extra] = args.filter((argument) => argument !== "--write");
-  if (file === undefined || extra.length > 0) {
-    return usageError("usage: udl fmt <file> [--write]");
-  }
-  const bytes = await readDocument(file);
-  if (bytes === null) return 2;
-
-  let canonical: string;
-  try {
-    canonical = canonicalizeUdl(bytes);
-  } catch (error) {
-    return reportIssues(file, error);
-  }
-
-  if (!write) {
-    process.stdout.write(canonical);
-    return 0;
-  }
-  // The bytes decoded cleanly already: canonicalizeUdl refuses anything else.
-  if (new TextDecoder().decode(bytes) === canonical) return 0;
-  await writeFile(file, canonical);
-  console.log(`${file}: formatted`);
-  return 0;
-}
-
-async function diffCommand(args: readonly string[]): Promise<number> {
-  const [livePath, nextPath, ...extra] = args;
-  if (livePath === undefined || nextPath === undefined || extra.length > 0) {
-    return usageError("usage: udl diff <live> <next>");
-  }
-  const liveBytes = await readDocument(livePath);
-  const nextBytes = await readDocument(nextPath);
-  if (liveBytes === null || nextBytes === null) return 2;
-
-  const live = parseDocument(livePath, liveBytes);
-  const next = parseDocument(nextPath, nextBytes);
-  if (live === null || next === null) return 1;
-
-  // `parseDocument` already validated both, so take the door that does not
-  // validate a second time.
-  const violations = diffValidatedUdlEvolution(live, next);
-  if (violations.length === 0) {
-    console.log(`${nextPath}: additive`);
-    return 0;
-  }
-  for (const violation of violations) {
-    console.error(
-      `${nextPath}: ${violation.code} ${violation.path}: ${violation.message}`,
-    );
-  }
-  return 1;
-}
-
-async function readDocument(file: string): Promise<Uint8Array | null> {
-  try {
-    return await readFile(file);
-  } catch (error) {
-    const reason = error instanceof Error ? error.message : String(error);
-    console.error(`udl: cannot read ${file}: ${reason}`);
-    return null;
-  }
-}
-
-/** Parses one document, printing its issues. Null means the document was refused. */
-function parseDocument(file: string, bytes: Uint8Array): UdlDocument | null {
-  try {
-    return parseUdl(bytes);
-  } catch (error) {
-    reportIssues(file, error);
-    return null;
-  }
-}
-
-function reportIssues(file: string, error: unknown): number {
-  if (!(error instanceof UdlError)) throw error;
-  for (const issue of error.issues) {
-    console.error(`${file}: ${issue.code} ${issue.path}: ${issue.message}`);
-  }
-  return 1;
-}
-
-function usageError(message: string): number {
-  console.error(message);
-  console.error(USAGE);
-  return 2;
-}
-
-process.exitCode = await main(process.argv.slice(2));

package/src/evolution.ts

@@ -1,46 +0,0 @@
-import type { UdlDocument } from "./schema.js";
-import { issue, type UdlIssue } from "./diagnostics.js";
-import { writeJson } from "./json.js";
-
-/** Existing instruments are frozen; a live document may add independent instruments. */
-export function diffValidatedUdlEvolution(
-  live: UdlDocument,
-  next: UdlDocument,
-): UdlIssue[] {
-  const issues: UdlIssue[] = [];
-  const refuse = (path: string, message: string) =>
-    issues.push(issue("UDL7001", path, message));
-  if (live.product !== next.product || live.currency !== next.currency)
-    refuse("$", "product identity and currency are immutable");
-  for (const [name, party] of Object.entries(live.parties))
-    if (
-      !Object.hasOwn(next.parties, name) ||
-      writeJson(party) !== writeJson(next.parties[name])
-    )
-      refuse(`$.parties.${name}`, "a live party cannot change or disappear");
-  for (const object of live.objects) {
-    const updated = next.objects.find((o) => o.id === object.id);
-    if (!updated || writeJson(object) !== writeJson(updated))
-      refuse(
-        `$.objects.${object.id}`,
-        "a live object kind cannot change or disappear; recreate development estates",
-      );
-  }
-  for (const instrument of live.instruments) {
-    const updated = next.instruments.find((i) => i.id === instrument.id);
-    if (!updated || writeJson(instrument) !== writeJson(updated))
-      refuse(
-        `$.instruments.${instrument.id}`,
-        "a live instrument cannot change or disappear; recreate development estates",
-      );
-  }
-  if (writeJson(live) !== writeJson(next) && next.version <= live.version)
-    issues.push(
-      issue(
-        "UDL7002",
-        "$.version",
-        "a changed document needs a higher version",
-      ),
-    );
-  return issues;
-}

package/src/instrument-references.ts

@@ -1,123 +0,0 @@
-import * as z from "zod";
-import {
-  udlDocumentSchema,
-  type UdlDocument,
-  type UdlInstrument,
-} from "./schema.js";
-
-type Schema = Record<string, unknown>;
-const object = (value: unknown): value is Schema =>
-  value !== null && typeof value === "object" && !Array.isArray(value);
-let documentSchema: Schema | undefined;
-
-/** Visit identities through schema annotations, never through user JSON keys. */
-export function mapUdlInstrumentReferences(
-  document: UdlDocument,
-  map: (id: string) => string,
-): UdlDocument {
-  const root = (documentSchema ??= z.toJSONSchema(udlDocumentSchema));
-  const result = structuredClone(document);
-  const locations = new Map<
-    string,
-    { parent: Schema | unknown[]; key: string | number; kind: string }
-  >();
-  function visit(
-    schema: unknown,
-    value: unknown,
-    parent: Schema | unknown[],
-    key: string | number,
-    path: readonly (string | number)[],
-  ): void {
-    if (!object(schema)) return;
-    if (typeof schema.$ref === "string") {
-      if (!schema.$ref.startsWith("#/"))
-        throw new Error("UDL reference schema must be local");
-      let target: unknown = root;
-      for (const part of schema.$ref.slice(2).split("/")) {
-        target = object(target)
-          ? target[part.replaceAll("~1", "/").replaceAll("~0", "~")]
-          : undefined;
-      }
-      visit(target, value, parent, key, path);
-    }
-    const kind = schema["x-udl-reference"];
-    if (typeof kind === "string" && typeof value === "string")
-      locations.set(JSON.stringify(path), { parent, key, kind });
-    for (const union of [schema.anyOf, schema.oneOf, schema.allOf])
-      if (Array.isArray(union))
-        for (const branch of union) visit(branch, value, parent, key, path);
-    if (Array.isArray(value)) {
-      value.forEach((entry, index) =>
-        visit(schema.items, entry, value, index, [...path, index]),
-      );
-    } else if (object(value)) {
-      const properties = object(schema.properties) ? schema.properties : {};
-      const discriminator = object(properties.type)
-        ? properties.type.const
-        : undefined;
-      if (
-        (discriminator === "ref" || discriminator === "list") &&
-        value.type === discriminator &&
-        value.targetKind === "instrument"
-      ) {
-        if (typeof value.target === "string")
-          locations.set(JSON.stringify([...path, "target"]), {
-            parent: value,
-            key: "target",
-            kind: "instrument",
-          });
-        else if (Array.isArray(value.target))
-          value.target.forEach((_, index) =>
-            locations.set(JSON.stringify([...path, "target", index]), {
-              parent: value.target as unknown[],
-              key: index,
-              kind: "instrument",
-            }),
-          );
-      }
-      for (const [name, entry] of Object.entries(value))
-        visit(
-          properties[name] ?? schema.additionalProperties,
-          entry,
-          value,
-          name,
-          [...path, name],
-        );
-    }
-  }
-  visit(root, result, [result], 0, []);
-  for (const { parent, key, kind } of locations.values()) {
-    const holder = parent as Record<string | number, unknown>;
-    const value = holder[key] as string;
-    if (kind === "instrument") holder[key] = map(value);
-    else if (kind === "instrument_event") {
-      const separator = value.indexOf(".");
-      holder[key] = map(value.slice(0, separator)) + value.slice(separator);
-    }
-  }
-  return result;
-}
-
-export function referencedUdlInstrumentIds(
-  instrument: UdlInstrument,
-): readonly string[] {
-  const found = new Set<string>();
-  mapUdlInstrumentReferences(
-    {
-      udl: 4,
-      version: 1,
-      product: "references",
-      title: "References",
-      currency: "SAR",
-      parties: {},
-      objects: [],
-      instruments: [instrument],
-    },
-    (id) => {
-      found.add(id);
-      return id;
-    },
-  );
-  found.delete(instrument.id);
-  return [...found];
-}