@hyperscale0/udl 1.0.0-rc.1 → 1.0.123

package/docs/reference/cli.md

@@ -1,22 +0,0 @@
-<!-- Generated by scripts/docs/build.ts from @hyperscale0/udl 1.0.0-rc.1. Edit the source, not cli.md. -->
-
-# Command reference
-
-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,32 +0,0 @@
-<!-- Generated by scripts/docs/build.ts from @hyperscale0/udl 1.0.0-rc.1. 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.                                                        |
-| `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.                               |
-| `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.                      |
-| `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/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/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/effects.ts

@@ -1,163 +0,0 @@
-export const udlEffectKinds = [
-  "decides",
-  "holds",
-  "moves",
-  "notifies",
-  "reads",
-  "schedules",
-] as const;
-
-export type UdlEffectKind = (typeof udlEffectKinds)[number];
-
-type EffectDescriptor = {
-  readonly kind: UdlEffectKind;
-  readonly per: "clause" | "element";
-  readonly signature:
-    | { readonly fixed: string }
-    | { readonly fromField: string }
-    | { readonly movementClass: true };
-};
-
-type ActionClauseDescriptor = {
-  readonly effects?: readonly EffectDescriptor[];
-  readonly scope: "action" | "instrument";
-  readonly target: string;
-};
-
-type EffectRow = {
-  readonly channel?: string;
-  readonly role?: string;
-  readonly signature: string;
-  readonly source: string;
-};
-
-export type DerivedUdlEffects = Partial<
-  Readonly<Record<UdlEffectKind, readonly EffectRow[]>>
->;
-
-export type UdlMovementClass =
-  | "collection.pay_in"
-  | "deposit.attributed"
-  | "payout.external"
-  | "transfer.internal";
-
-interface Movement {
-  readonly bind?: Readonly<Record<string, unknown>>;
-  readonly operation: string;
-}
-
-function boundPath(move: Movement, endpoint: string): string | undefined {
-  const binding = move.bind?.[endpoint];
-  if (binding === null || typeof binding !== "object") return undefined;
-  const path = (binding as { readonly path?: unknown }).path;
-  return typeof path === "string" ? path : undefined;
-}
-
-/**
- * Maps a UDL money operation to the meter and pricing class that owns it.
- * Internal-transfer endpoint bindings are product accounts by construction.
- * External collection, deposit, and payout operations carry their role in the
- * operation family because their remote endpoint is not a UDL account binding.
- */
-export function movementClass(move: Movement): UdlMovementClass {
-  if (move.operation.startsWith("internal_transfer.")) {
-    const source = boundPath(move, "sourceAccountId");
-    const destination = boundPath(move, "destinationAccountId");
-    if (
-      source?.startsWith("fields.") &&
-      destination === "refs.escrowAccountId"
-    ) {
-      return "collection.pay_in";
-    }
-    return "transfer.internal";
-  }
-  if (move.operation.startsWith("collection.pay_in.")) {
-    return "collection.pay_in";
-  }
-  if (move.operation.startsWith("deposit.")) {
-    return "deposit.attributed";
-  }
-  if (move.operation.startsWith("payout.")) {
-    return "payout.external";
-  }
-  throw new Error(`cannot classify UDL movement operation ${move.operation}`);
-}
-
-/** Derive the ABI effect rows declared by the action-clause vocabulary. */
-export function deriveUdlActionEffects(
-  action: Readonly<Record<string, unknown>>,
-  vocabulary: readonly ActionClauseDescriptor[],
-): DerivedUdlEffects {
-  const effects: Partial<Record<UdlEffectKind, EffectRow[]>> = {};
-  for (const clause of vocabulary) {
-    if (clause.scope !== "action" || !clause.effects) continue;
-    const value = actionClauseValue(action, clause.target);
-    if (value === undefined) continue;
-    for (const descriptor of clause.effects) {
-      const values =
-        descriptor.per === "element" && Array.isArray(value) ? value : [value];
-      for (const [index, candidate] of values.entries()) {
-        const object = recordValue(candidate);
-        if (
-          descriptor.kind === "holds" &&
-          "fixed" in descriptor.signature &&
-          descriptor.signature.fixed === "reserve" &&
-          object?.operation !== "internal_transfer.reserve"
-        ) {
-          continue;
-        }
-        const suffix = effectSignatureSuffix(descriptor, object);
-        if (!suffix) continue;
-        (effects[descriptor.kind] ??= []).push({
-          signature: `${descriptor.kind}.${suffix}`,
-          source:
-            descriptor.per === "element"
-              ? `${clause.target}[${index}]`
-              : clause.target,
-          ...(descriptor.kind === "notifies" &&
-          typeof object?.channel === "string" &&
-          typeof object.role === "string"
-            ? { channel: object.channel, role: object.role }
-            : {}),
-        });
-      }
-    }
-  }
-  return effects;
-}
-
-function actionClauseValue(
-  action: Readonly<Record<string, unknown>>,
-  target: string,
-): unknown {
-  const [head, tail] = target.split(".");
-  if (!head) return undefined;
-  const value = action[head];
-  if (!tail) return value;
-  return recordValue(value)?.[tail];
-}
-
-function effectSignatureSuffix(
-  descriptor: EffectDescriptor,
-  value: Readonly<Record<string, unknown>> | undefined,
-): string | undefined {
-  if ("fixed" in descriptor.signature) return descriptor.signature.fixed;
-  if ("fromField" in descriptor.signature) {
-    const field = value?.[descriptor.signature.fromField];
-    return typeof field === "string" ? field : undefined;
-  }
-  if (!value || !("movementClass" in descriptor.signature)) return undefined;
-  const operation = value.operation;
-  const bind = recordValue(value.bind);
-  return typeof operation === "string"
-    ? movementClass({ ...(bind ? { bind } : {}), operation })
-    : undefined;
-}
-
-function recordValue(
-  value: unknown,
-): Readonly<Record<string, unknown>> | undefined {
-  return value !== null && typeof value === "object" && !Array.isArray(value)
-    ? (value as Readonly<Record<string, unknown>>)
-    : undefined;
-}