@hyperscale0/hsx 1.0.0-beta.1 → 1.0.0-rc.1

package/docs/llms.txt

@@ -0,0 +1,45 @@
+<!-- Generated by scripts/docs/build.ts for HSX 1.0.0-rc.1. Do not edit. -->
+
+# HSX documentation
+
+> Repository guide and generated compiler reference for HSX 1.0.0-rc.1.
+
+## Guide
+
+[Your first program](guide/01-first-program.md): Hand-written chapter with compiler-checked programs.
+[Money](guide/02-money.md): Hand-written chapter with compiler-checked programs.
+[Instruments](guide/03-instruments.md): Hand-written chapter with compiler-checked programs.
+[Lifecycles](guide/04-lifecycles.md): Hand-written chapter with compiler-checked programs.
+[Fees and splits](guide/05-fees-and-splits.md): Hand-written chapter with compiler-checked programs.
+[Schedules](guide/06-schedules.md): Hand-written chapter with compiler-checked programs.
+[Composition](guide/07-composition.md): Hand-written chapter with compiler-checked programs.
+[Writing a module](guide/08-writing-a-module.md): Hand-written chapter with compiler-checked programs.
+[Cost](guide/09-cost.md): Hand-written chapter with compiler-checked programs.
+[Diagnostics](guide/10-diagnostics.md): Hand-written chapter with compiler-checked programs.
+
+## Reference
+
+[Grammar](reference/grammar.md): Lexer, clause, and module vocabulary.
+[Types](reference/types.md): HSX type kinds.
+[Diagnostics](reference/diagnostics.md): Stable HSX diagnostic codes and fixes.
+[CLI](reference/cli.md): Generated command usage.
+[UDL output](reference/udl-output.md): Compile artifacts and canonical output.
+[advance](reference/std/advance.md): Standard-library module.
+[cancellable_booking](reference/std/cancellable_booking.md): Standard-library module.
+[captured_payment](reference/std/captured_payment.md): Standard-library module.
+[conditional_disbursement](reference/std/conditional_disbursement.md): Standard-library module.
+[credit_facility](reference/std/credit_facility.md): Standard-library module.
+[held_payment](reference/std/held_payment.md): Standard-library module.
+[instant_transfer](reference/std/instant_transfer.md): Standard-library module.
+[metered](reference/std/metered.md): Standard-library module.
+[pooled_split](reference/std/pooled_split.md): Standard-library module.
+[premium_forward](reference/std/premium_forward.md): Standard-library module.
+[reconciled_payout](reference/std/reconciled_payout.md): Standard-library module.
+[recurring_collection](reference/std/recurring_collection.md): Standard-library module.
+[rotating_pool](reference/std/rotating_pool.md): Standard-library module.
+[scheduled](reference/std/scheduled.md): Standard-library module.
+[security_deposit](reference/std/security_deposit.md): Standard-library module.
+[settlement_batch](reference/std/settlement_batch.md): Standard-library module.
+[swap](reference/std/swap.md): Standard-library module.
+[threshold_pool](reference/std/threshold_pool.md): Standard-library module.
+[weighted_distribution](reference/std/weighted_distribution.md): Standard-library module.

package/docs/reference/cli.md

@@ -0,0 +1,33 @@
+<!-- Generated by scripts/docs/build.ts for HSX 1.0.0-rc.1. Do not edit. -->
+
+# CLI
+
+```text
+hsx 1.0.0-rc.1, the HSX compiler
+
+Usage:
+  hsx check <file.hsx> [--strict]
+  hsx build <file.hsx> [--out <file.json>] [--strict]
+  hsx cost <file.hsx> [--json] [--out <file.json>] [--strict]
+  hsx explain <HSX####>
+  hsx format <file.hsx>
+  hsx --version
+  hsx --help
+
+Commands:
+  check   Compile and report diagnostics. Prints nothing when the program is clean.
+  build   Compile and write canonical UDL and its Business Frame as JSON.
+  cost    Compile and print the version-pinned cost manifest as a table or JSON.
+  explain Print one diagnostic title, fix, and source example.
+  format  Print the source in the one canonical HSX style.
+
+Options:
+  --json        Print the cost manifest as JSON instead of a table.
+  --out <file>  Write build or cost JSON to this path instead of stdout.
+  --strict      Treat warning-severity diagnostics as failures.
+
+Exit codes:
+  0  the program compiled (verdict valid, or warning without --strict)
+  1  the program was refused (verdict invalid, or warning with --strict)
+  2  the command line or the input file could not be used
+```

package/docs/reference/diagnostics.md

@@ -0,0 +1,619 @@
+<!-- Generated by scripts/docs/build.ts for HSX 1.0.0-rc.1. Do not edit. -->
+
+# Diagnostics
+
+Use `hsx explain HSX####` for the same catalog entry.
+
+## HSX1000: Missing file declaration
+
+Stage: `typecheck`
+
+Fix: Add one program header or module declaration.
+
+No source-only witness exists. The compiler host or lowering input must supply the invalid value.
+
+## HSX1001: Unbound name
+
+Stage: `bind`
+
+Fix: Declare or import the name before using it.
+
+```hsx expect=HSX1001
+program catalog_probe "Catalog probe"
+instrument probe = missing()
+```
+
+## HSX1002: Duplicate program declaration
+
+Stage: `typecheck`
+
+Fix: Keep exactly one program declaration.
+
+```hsx expect=HSX1002
+program catalog_probe "Catalog probe"
+instrument probe {
+  fields {}
+  lifecycle { states created; initial created; }
+  action create { steps: []; }
+
+}
+program second "Second"
+```
+
+## HSX1003: Invalid declaration name
+
+Stage: `typecheck`
+
+Fix: Use lowercase snake_case for program and instrument names.
+
+```hsx expect=HSX1003
+program NotSnake "Catalog probe"
+```
+
+## HSX1004: Duplicate declaration
+
+Stage: `typecheck`
+
+Fix: Keep one declaration or give each declaration a distinct name.
+
+```hsx expect=HSX1004
+program catalog_probe "Catalog probe"
+instrument probe {
+  fields {}
+  lifecycle { states created; initial created; }
+  action create { steps: []; }
+
+}
+instrument probe { fields {}; lifecycle { states created; initial created; }; action create { steps: []; }; }
+```
+
+## HSX1005: Invalid field name
+
+Stage: `typecheck`
+
+Fix: Rename the field in lower camelCase.
+
+No source-only witness exists. The parser normalizes every accepted field spelling before typechecking.
+
+## HSX1006: Invalid module import
+
+Stage: `bind`
+
+Fix: Resolve one module that exports each imported name exactly once.
+
+No source-only witness exists. This refusal requires a compiler-host module resolver result.
+
+## HSX1007: Invalid cross-instrument reference
+
+Stage: `typecheck`
+
+Fix: Name an existing target instrument in the ref type.
+
+```hsx expect=HSX1007
+program catalog_probe "Catalog probe"
+instrument probe {
+  fields { parentId { type: ref; description: "Parent"; } }
+  lifecycle { states created; initial created; }
+  action create { steps: []; }
+}
+```
+
+## HSX1008: Invalid subject or decision port
+
+Stage: `typecheck`
+
+Fix: Complete the declaration and bind every referenced decision port.
+
+```hsx expect=HSX1008
+program catalog_probe "Catalog probe"
+instrument probe {
+  fields {}
+  lifecycle { states created; initial created; }
+  action create { steps: []; }
+
+}
+subject vehicle { title: "Vehicle"; }
+```
+
+## HSX1009: Imported declaration collision
+
+Stage: `bind`
+
+Fix: Rename the importer-owned declaration or the module-local declaration.
+
+No source-only witness exists. This refusal requires declarations returned by a compiler-host module resolver.
+
+## HSX1010: Wrong type-argument count
+
+Stage: `typecheck`
+
+Fix: Supply exactly the type arguments declared by the instrument function.
+
+```hsx expect=HSX1010
+program catalog_probe "Catalog probe"
+export instrument template<C>() { fields {}; lifecycle { states created; initial created; }; action create { steps: []; }; }
+instrument probe = template<SAR, USD>()
+```
+
+## HSX1011: Missing required argument
+
+Stage: `typecheck`
+
+Fix: Pass every required instrument-function argument.
+
+```hsx expect=HSX1011
+program catalog_probe "Catalog probe"
+export instrument template(value: text) { fields {}; lifecycle { states created; initial created; }; action create { steps: []; }; }
+instrument probe = template()
+```
+
+## HSX1012: Unknown named argument
+
+Stage: `typecheck`
+
+Fix: Remove the argument or use a parameter declared by the instrument function.
+
+```hsx expect=HSX1012
+program catalog_probe "Catalog probe"
+export instrument template() { fields {}; lifecycle { states created; initial created; }; action create { steps: []; }; }
+instrument probe = template(typo: true)
+```
+
+## HSX1013: Duplicate named argument
+
+Stage: `typecheck`
+
+Fix: Pass each named argument once.
+
+```hsx expect=HSX1013
+program catalog_probe "Catalog probe"
+export instrument template(value: text) { fields {}; lifecycle { states created; initial created; }; action create { steps: []; }; }
+instrument probe = template(value: "one", value: "two")
+```
+
+## HSX1014: JSON supplied as HSX
+
+Stage: `parse`
+
+Fix: Replace the JSON object with HSX declarations.
+
+```hsx expect=HSX1014
+{ "hsx": 1 }
+```
+
+## HSX1015: Invalid composed program identity
+
+Stage: `typecheck`
+
+Fix: Give the composed program a bounded product id and title.
+
+No source-only witness exists. This refusal requires a compiler-host published catalog.
+
+## HSX1016: Empty published composition
+
+Stage: `typecheck`
+
+Fix: Select at least one published instrument with use.
+
+No source-only witness exists. This refusal requires a compiler-host published catalog.
+
+## HSX1017: Duplicate published instrument
+
+Stage: `typecheck`
+
+Fix: Keep one use declaration for each published instrument.
+
+No source-only witness exists. This refusal requires a compiler-host published catalog.
+
+## HSX1018: Unavailable published instrument
+
+Stage: `typecheck`
+
+Fix: Use an instrument id from the supplied published catalog.
+
+```hsx expect=HSX1018
+program catalog_probe "Catalog probe"
+use missing
+```
+
+## HSX1020: Invalid public action name
+
+Stage: `typecheck`
+
+Fix: Expose each action once under a distinct lower camelCase name.
+
+No source-only witness exists. This refusal requires a compiler-host published catalog.
+
+## HSX1021: Invalid exposed action
+
+Stage: `typecheck`
+
+Fix: Expose an action on an explicitly used published instrument.
+
+No source-only witness exists. This refusal requires a compiler-host published catalog.
+
+## HSX1022: Authored instrument in a composition
+
+Stage: `typecheck`
+
+Fix: Publish the instrument separately, then select it with use.
+
+No source-only witness exists. This refusal requires a compiler-host published catalog.
+
+## HSX1023: Invalid required-field list
+
+Stage: `typecheck`
+
+Fix: List declared, non-optional field names once each.
+
+```hsx expect=HSX1023
+program catalog_probe "Catalog probe"
+instrument probe {
+  fields {}
+  lifecycle { states created; initial created; }
+  action create { steps: []; }
+  required: missing;
+}
+```
+
+## HSX1101: Currency mismatch
+
+Stage: `typecheck`
+
+Fix: Use the declared currency because money values never coerce.
+
+```hsx expect=HSX1101
+program catalog_probe "Catalog probe"
+instrument probe {
+  fields {}
+  lifecycle { states created; initial created; }
+  action create { steps: []; }
+
+}
+const fee: money<SAR> = USD 1.00
+```
+
+## HSX1102: Money precision exceeds minor units
+
+Stage: `typecheck`
+
+Fix: Round the literal to the currency's minor-unit precision.
+
+```hsx expect=HSX1102
+program catalog_probe "Catalog probe"
+instrument probe {
+  fields {}
+  lifecycle { states created; initial created; }
+  action create { steps: []; }
+
+}
+const fee: money<SAR> = SAR 1.001
+```
+
+## HSX1103: Invalid numeric value
+
+Stage: `typecheck`
+
+Fix: Use an integer, percent, bps, or valid fixed-money binding.
+
+```hsx expect=HSX1103
+program catalog_probe "Catalog probe"
+instrument probe {
+  fields {}
+  lifecycle { states created; initial created; }
+  action create { steps: []; }
+  summary: 1.5;
+}
+```
+
+## HSX1104: Value has the wrong type
+
+Stage: `typecheck`
+
+Fix: Pass the type declared by the parameter or UDL slot.
+
+```hsx expect=HSX1104
+program catalog_probe "Catalog probe"
+instrument probe {
+  fields {}
+  lifecycle { states created; initial created; }
+  action create { steps: []; }
+  summary: money(SAR, 2500);
+}
+```
+
+## HSX1110: Unsupported parameter combination
+
+Stage: `typecheck`
+
+Fix: Choose a supported compile-time parameter combination.
+
+```hsx expect=HSX1110
+program catalog_probe "Catalog probe"
+export instrument template() {
+  unsupported { message: "Not supported"; fix: "Choose another form"; }
+  fields {}
+  lifecycle { states created; initial created; }
+  action create { steps: []; }
+}
+instrument probe = template()
+```
+
+## HSX1201: Linear money consumed more than once
+
+Stage: `typecheck`
+
+Fix: Leave exactly one sink for each produced money value.
+
+```hsx expect=HSX1201
+program catalog_probe "Catalog probe"
+instrument probe {
+  fields {}
+  lifecycle { states created; initial created; }
+  action create { steps: []; }
+  fields { amount: money<SAR>; }
+action pay { computes remainder rest { amount_ref: total; on_zero: refuse; total_path: fields.amount; }; moves: [{ amount: rest; }, { amount: rest; }]; }
+}
+```
+
+## HSX1202: Linear money is unconsumed
+
+Stage: `typecheck`
+
+Fix: Route each produced money value to one explicit sink.
+
+```hsx expect=HSX1202
+program catalog_probe "Catalog probe"
+instrument probe {
+  fields {}
+  lifecycle { states created; initial created; }
+  action create { steps: []; }
+  fields { amount: money<SAR>; }
+action pay { computes remainder rest { amount_ref: total; on_zero: refuse; total_path: fields.amount; }; }
+}
+```
+
+## HSX1301: Missing cost-table price
+
+Stage: `typecheck`
+
+Fix: Supply a versioned cost table with a row for every emitted effect.
+
+```hsx expect=HSX1301
+program catalog_probe "Catalog probe"
+instrument probe {
+  fields {}
+  lifecycle { states created; initial created; }
+  action create { steps: []; }
+
+}
+```
+
+## HSX1302: Invalid cost-table row
+
+Stage: `typecheck`
+
+Fix: Use non-negative integer prices and a supported settlement timing.
+
+No source-only witness exists. This refusal requires a malformed compiler-host cost table.
+
+## HSX1303: Invalid cost-table currency
+
+Stage: `typecheck`
+
+Fix: Use the supported uppercase cost-table currency.
+
+No source-only witness exists. This refusal requires an invalid compiler-host cost-table currency.
+
+## HSX1401: Unbounded action
+
+Stage: `typecheck`
+
+Fix: Replace runtime iteration with a bounded compile-time comprehension.
+
+```hsx expect=HSX1401
+program catalog_probe "Catalog probe"
+instrument probe {
+  fields {}
+  lifecycle { states created; initial created; }
+  action create { steps: []; }
+  action run { while { condition: true; }; }
+}
+```
+
+## HSX1402: Missing lifecycle
+
+Stage: `typecheck`
+
+Fix: Declare lifecycle states and an initial state.
+
+```hsx expect=HSX1402
+program catalog_probe "Catalog probe"
+instrument probe { fields {}; action create { steps: []; }; }
+```
+
+## HSX1403: Runtime comprehension bound
+
+Stage: `typecheck`
+
+Fix: Use an integer literal or literal finite list as the bound.
+
+```hsx expect=HSX1403
+program catalog_probe "Catalog probe"
+export instrument template(count: integer) {
+  fields {}
+  lifecycle { states created; initial created; }
+  action create { steps: []; }
+  for item in count { action run_[item] { steps: []; } }
+}
+instrument probe = template(count: runtimeCount: integer)
+```
+
+## HSX1404: Comprehension expansion limit
+
+Stage: `typecheck`
+
+Fix: Reduce the fixed expansion to the compiler limit.
+
+```hsx expect=HSX1404
+program catalog_probe "Catalog probe"
+instrument probe {
+  fields {}
+  lifecycle { states created; initial created; }
+  action create { steps: []; }
+  for item in 257 { action run_[item] { steps: []; } }
+}
+```
+
+## HSX1405: Invalid compile-time selection
+
+Stage: `typecheck`
+
+Fix: Give compile-time conditions and unsupported branches fixed blocks.
+
+```hsx expect=HSX1405
+program catalog_probe "Catalog probe"
+export instrument template() { unsupported: true; fields {}; lifecycle { states created; initial created; }; action create { steps: []; }; }
+instrument probe = template()
+```
+
+## HSX1406: Invalid companion instrument
+
+Stage: `typecheck`
+
+Fix: Construct each companion with a compile-time id.
+
+```hsx expect=HSX1406
+program catalog_probe "Catalog probe"
+export instrument template() {
+  fields {}
+  lifecycle { states created; initial created; }
+  action create { steps: []; }
+  instruments { invalid: true; }
+}
+instrument probe = template()
+```
+
+## HSX1501: Unknown UDL clause
+
+Stage: `typecheck`
+
+Fix: Use a clause exported by the targeted UDL vocabulary.
+
+```hsx expect=HSX1501
+program catalog_probe "Catalog probe"
+instrument probe {
+  fields {}
+  lifecycle { states created; initial created; }
+  action create { steps: []; }
+  unknown_clause: true;
+}
+```
+
+## HSX1502: Program emits no instruments
+
+Stage: `typecheck`
+
+Fix: Declare or instantiate at least one instrument.
+
+```hsx expect=HSX1502
+program catalog_probe "Catalog probe"
+```
+
+## HSX1503: Missing fields block
+
+Stage: `typecheck`
+
+Fix: Add a fields block, even when it is empty.
+
+```hsx expect=HSX1503
+program catalog_probe "Catalog probe"
+instrument probe { lifecycle { states created; initial created; }; action create { steps: []; }; }
+```
+
+## HSX1504: Missing create action
+
+Stage: `typecheck`
+
+Fix: Add an action create block.
+
+```hsx expect=HSX1504
+program catalog_probe "Catalog probe"
+instrument probe { fields {}; lifecycle { states created; initial created; }; }
+```
+
+## HSX1505: Repeated single-valued clause
+
+Stage: `typecheck`
+
+Fix: Keep one occurrence of the clause.
+
+```hsx expect=HSX1505
+program catalog_probe "Catalog probe"
+instrument probe {
+  fields {}
+  lifecycle { states created; initial created; }
+  action create { steps: []; }
+  title: "First"; title: "Second";
+}
+```
+
+## HSX1506: Conflicting public action settings
+
+Stage: `typecheck`
+
+Fix: Keep either public: none or a public action name.
+
+```hsx expect=HSX1506
+program catalog_probe "Catalog probe"
+instrument probe {
+  fields {}
+  lifecycle { states created; initial created; }
+  action create { steps: []; }
+  action finish { public: none; public_action: finishProbe; steps: []; }
+}
+```
+
+## HSX1507: Invalid application metadata
+
+Stage: `typecheck`
+
+Fix: Keep contract mechanics in the parameterized instrument.
+
+```hsx expect=HSX1507
+program catalog_probe "Catalog probe"
+export instrument template() { fields {}; lifecycle { states created; initial created; }; action create { steps: []; }; }
+instrument probe = template() { fields: {}; }
+```
+
+## HSX1601: Invalid UDL shape
+
+Stage: `lower`
+
+Fix: Correct the named clause so it matches the targeted UDL definition.
+
+No source-only witness exists. Typed source cannot bypass the checker to emit an invalid UDL shape.
+
+## HSX1602: Invalid UDL semantics
+
+Stage: `lower`
+
+Fix: Correct the named clause so it satisfies the targeted UDL law.
+
+No source-only witness exists. Typed source cannot bypass the checker to emit invalid UDL semantics.
+
+## HSX1603: Unresolved compiler marker
+
+Stage: `lower`
+
+Fix: Correct compile-time block keys or parameter bindings.
+
+```hsx expect=HSX1603
+program catalog_probe "Catalog probe"
+instrument probe {
+  fields {}
+  lifecycle { states created; initial created; }
+  action create { steps: []; }
+  title: "__hsx_none__";
+}
+```