@hyperscale0/hsx 2.2.0 → 2.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +27 -1
- package/dist/src/cli.d.ts +1 -1
- package/dist/src/diagnostics.d.ts.map +1 -1
- package/dist/src/diagnostics.js +7 -0
- package/dist/src/diagnostics.js.map +1 -1
- package/dist/src/std-bundle.js +2 -2
- package/dist/src/std-bundle.js.map +1 -1
- package/dist/src/typecheck.d.ts.map +1 -1
- package/dist/src/typecheck.js +32 -13
- package/dist/src/typecheck.js.map +1 -1
- package/dist/src/version.d.ts +1 -1
- package/dist/src/version.js +1 -1
- package/docs/guide/03-instruments.md +31 -1
- package/docs/llms-full.txt +94 -3
- package/docs/llms.txt +3 -3
- package/docs/reference/cli.md +2 -2
- package/docs/reference/diagnostics.md +21 -1
- package/docs/reference/grammar.md +1 -1
- package/docs/reference/std/advance.md +1 -1
- package/docs/reference/std/cancellable_booking.md +1 -1
- package/docs/reference/std/captured_payment.md +1 -1
- package/docs/reference/std/conditional_disbursement.md +1 -1
- package/docs/reference/std/credit_facility.md +1 -1
- package/docs/reference/std/held_payment.md +1 -1
- package/docs/reference/std/instant_transfer.md +1 -1
- package/docs/reference/std/metered.md +1 -1
- package/docs/reference/std/pooled_split.md +1 -1
- package/docs/reference/std/premium_forward.md +1 -1
- package/docs/reference/std/reconciled_payout.md +1 -1
- package/docs/reference/std/rotating_pool.md +1 -1
- package/docs/reference/std/scheduled.md +1 -1
- package/docs/reference/std/security_deposit.md +1 -1
- package/docs/reference/std/settlement_batch.md +1 -1
- package/docs/reference/std/swap.md +1 -1
- package/docs/reference/std/threshold_pool.md +1 -1
- package/docs/reference/std/weighted_distribution.md +1 -1
- package/docs/reference/types.md +42 -1
- package/docs/reference/udl-output.md +1 -1
- package/package.json +3 -3
- package/src/diagnostics.ts +7 -0
- package/src/std-bundle.ts +2 -2
- package/src/typecheck.ts +31 -13
- package/src/version.ts +1 -1
- package/std/money_flows/advance.hsx +1 -1
- package/std/money_flows/cancellable_booking.hsx +8 -8
package/dist/src/version.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
/** Package version reported by the command line. */
|
|
2
|
-
export declare const HSX_VERSION = "2.
|
|
2
|
+
export declare const HSX_VERSION = "2.3.0";
|
|
3
3
|
/** Canonical UDL contract version emitted by this compiler. */
|
|
4
4
|
export declare const HSX_TARGET_UDL_VERSION = 1;
|
|
5
5
|
//# sourceMappingURL=version.d.ts.map
|
package/dist/src/version.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
/** Package version reported by the command line. */
|
|
2
|
-
export const HSX_VERSION = "2.
|
|
2
|
+
export const HSX_VERSION = "2.3.0";
|
|
3
3
|
/** Canonical UDL contract version emitted by this compiler. */
|
|
4
4
|
export const HSX_TARGET_UDL_VERSION = 1;
|
|
5
5
|
//# sourceMappingURL=version.js.map
|
|
@@ -27,11 +27,41 @@ When declaring fields of type `account<C>`, the HSX compiler automatically lower
|
|
|
27
27
|
|
|
28
28
|
```hsx
|
|
29
29
|
fields {
|
|
30
|
-
customerAccountId
|
|
30
|
+
customerAccountId {
|
|
31
|
+
type: account<SAR>;
|
|
32
|
+
"x-hyperscale-reference-filter": { column: role; values: [customer_balance]; };
|
|
33
|
+
}
|
|
34
|
+
amount: money<SAR>;
|
|
35
|
+
}
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
The account type pins the currency and identifier shape. The reference filter
|
|
39
|
+
pins the allowed ledger roles. Product admission requires every account field
|
|
40
|
+
to declare a non-empty role list. Choose roles that match the accounts the
|
|
41
|
+
program will use; `customer_balance` is the role in this example.
|
|
42
|
+
|
|
43
|
+
Use the quoted `"x-hyperscale-reference-filter"` key inside the field block,
|
|
44
|
+
with `column: role` and `values: [...]`. There is no shorter role annotation.
|
|
45
|
+
A bare `customerAccountId: account<SAR>;` compiles as HSX but does not satisfy
|
|
46
|
+
the host's account-role admission law.
|
|
47
|
+
|
|
48
|
+
## Money fields
|
|
49
|
+
|
|
50
|
+
A `money<C>` field admits a minor-unit integer string and refuses zero: it lowers to the pattern `^[1-9][0-9]{0,17}$`. Marking the field `optional: true` lets a caller omit it; it does not let a caller send `"0"`. When zero is a real value for the field, opt in with `allow_zero: true`, which lowers to `^(0|[1-9][0-9]{0,17})$`:
|
|
51
|
+
|
|
52
|
+
```hsx
|
|
53
|
+
fields {
|
|
31
54
|
amount: money<SAR>;
|
|
55
|
+
discount { type: money<SAR>; optional: true; allow_zero: true; }
|
|
32
56
|
}
|
|
33
57
|
```
|
|
34
58
|
|
|
59
|
+
`allow_zero` on any other type is HSX1105. Decision port shapes set it on their money fields, because a decided amount may be zero.
|
|
60
|
+
|
|
61
|
+
## Date fields
|
|
62
|
+
|
|
63
|
+
A `date` field lowers to the UDL `hyperscale-date-time` format. Callers may send any RFC 3339 offset, such as `2026-10-03T09:00:00+03:00`; the host admits it and stores the UTC instant, `2026-10-03T06:00:00.000Z`. A value already in `Z` is stored byte for byte. A local date-time without an offset is refused.
|
|
64
|
+
|
|
35
65
|
## Port declarations and action clauses
|
|
36
66
|
|
|
37
67
|
HSX supports two distinct port syntaxes depending on scope:
|
package/docs/llms-full.txt
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
<!-- Generated by scripts/docs/build.ts for HSX 2.
|
|
1
|
+
<!-- Generated by scripts/docs/build.ts for HSX 2.3.0. Do not edit. -->
|
|
2
2
|
|
|
3
3
|
# HSX full documentation
|
|
4
4
|
|
|
@@ -82,11 +82,41 @@ When declaring fields of type `account<C>`, the HSX compiler automatically lower
|
|
|
82
82
|
|
|
83
83
|
```hsx
|
|
84
84
|
fields {
|
|
85
|
-
customerAccountId
|
|
85
|
+
customerAccountId {
|
|
86
|
+
type: account<SAR>;
|
|
87
|
+
"x-hyperscale-reference-filter": { column: role; values: [customer_balance]; };
|
|
88
|
+
}
|
|
89
|
+
amount: money<SAR>;
|
|
90
|
+
}
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
The account type pins the currency and identifier shape. The reference filter
|
|
94
|
+
pins the allowed ledger roles. Product admission requires every account field
|
|
95
|
+
to declare a non-empty role list. Choose roles that match the accounts the
|
|
96
|
+
program will use; `customer_balance` is the role in this example.
|
|
97
|
+
|
|
98
|
+
Use the quoted `"x-hyperscale-reference-filter"` key inside the field block,
|
|
99
|
+
with `column: role` and `values: [...]`. There is no shorter role annotation.
|
|
100
|
+
A bare `customerAccountId: account<SAR>;` compiles as HSX but does not satisfy
|
|
101
|
+
the host's account-role admission law.
|
|
102
|
+
|
|
103
|
+
## Money fields
|
|
104
|
+
|
|
105
|
+
A `money<C>` field admits a minor-unit integer string and refuses zero: it lowers to the pattern `^[1-9][0-9]{0,17}$`. Marking the field `optional: true` lets a caller omit it; it does not let a caller send `"0"`. When zero is a real value for the field, opt in with `allow_zero: true`, which lowers to `^(0|[1-9][0-9]{0,17})$`:
|
|
106
|
+
|
|
107
|
+
```hsx
|
|
108
|
+
fields {
|
|
86
109
|
amount: money<SAR>;
|
|
110
|
+
discount { type: money<SAR>; optional: true; allow_zero: true; }
|
|
87
111
|
}
|
|
88
112
|
```
|
|
89
113
|
|
|
114
|
+
`allow_zero` on any other type is HSX1105. Decision port shapes set it on their money fields, because a decided amount may be zero.
|
|
115
|
+
|
|
116
|
+
## Date fields
|
|
117
|
+
|
|
118
|
+
A `date` field lowers to the UDL `hyperscale-date-time` format. Callers may send any RFC 3339 offset, such as `2026-10-03T09:00:00+03:00`; the host admits it and stores the UTC instant, `2026-10-03T06:00:00.000Z`. A value already in `Z` is stored byte for byte. A local date-time without an offset is refused.
|
|
119
|
+
|
|
90
120
|
## Port declarations and action clauses
|
|
91
121
|
|
|
92
122
|
HSX supports two distinct port syntaxes depending on scope:
|
|
@@ -426,7 +456,7 @@ Exit code `0` means the command accepted the program. Exit code `1` means compil
|
|
|
426
456
|
# CLI
|
|
427
457
|
|
|
428
458
|
```text
|
|
429
|
-
hsx 2.
|
|
459
|
+
hsx 2.3.0, the HSX compiler
|
|
430
460
|
|
|
431
461
|
Usage:
|
|
432
462
|
hsx check <file.hsx> [--catalog <catalog.udl>] [--strict]
|
|
@@ -864,6 +894,26 @@ instrument probe {
|
|
|
864
894
|
}
|
|
865
895
|
```
|
|
866
896
|
|
|
897
|
+
## HSX1105: allow_zero needs a money field
|
|
898
|
+
|
|
899
|
+
Stage: `typecheck`
|
|
900
|
+
|
|
901
|
+
Fix: Put allow_zero: true on a money field, or remove it; amounts are strictly positive unless a money field opts in.
|
|
902
|
+
|
|
903
|
+
```hsx expect=HSX1105
|
|
904
|
+
program catalog_probe "Catalog probe"
|
|
905
|
+
instrument probe {
|
|
906
|
+
agent_description: "Probe instrument for catalog diagnostics.";
|
|
907
|
+
fields { memo { type: text; allow_zero: true; } }
|
|
908
|
+
lifecycle { states created; initial created; }
|
|
909
|
+
action create {
|
|
910
|
+
agent_description: "Create a probe instance.";
|
|
911
|
+
steps: [];
|
|
912
|
+
}
|
|
913
|
+
|
|
914
|
+
}
|
|
915
|
+
```
|
|
916
|
+
|
|
867
917
|
## HSX1110: Unsupported parameter combination
|
|
868
918
|
|
|
869
919
|
Stage: `typecheck`
|
|
@@ -3577,6 +3627,47 @@ HSX checks types before it emits UDL. Money and account values carry a currency
|
|
|
3577
3627
|
| `text` | A finite string value. |
|
|
3578
3628
|
| `unknown` | An internal checker result that source must resolve before lowering. |
|
|
3579
3629
|
|
|
3630
|
+
## Account fields
|
|
3631
|
+
|
|
3632
|
+
When declaring fields of type `account<C>`, the HSX compiler automatically lowers the field schema with the UDL2002 account pattern (`^acct_(sandbox|live)_[a-z0-9]{8,64}$`). Authors do not need to write an explicit `pattern` clause on account fields.
|
|
3633
|
+
|
|
3634
|
+
```hsx
|
|
3635
|
+
fields {
|
|
3636
|
+
customerAccountId {
|
|
3637
|
+
type: account<SAR>;
|
|
3638
|
+
"x-hyperscale-reference-filter": { column: role; values: [customer_balance]; };
|
|
3639
|
+
}
|
|
3640
|
+
amount: money<SAR>;
|
|
3641
|
+
}
|
|
3642
|
+
```
|
|
3643
|
+
|
|
3644
|
+
The account type pins the currency and identifier shape. The reference filter
|
|
3645
|
+
pins the allowed ledger roles. Product admission requires every account field
|
|
3646
|
+
to declare a non-empty role list. Choose roles that match the accounts the
|
|
3647
|
+
program will use; `customer_balance` is the role in this example.
|
|
3648
|
+
|
|
3649
|
+
Use the quoted `"x-hyperscale-reference-filter"` key inside the field block,
|
|
3650
|
+
with `column: role` and `values: [...]`. There is no shorter role annotation.
|
|
3651
|
+
A bare `customerAccountId: account<SAR>;` compiles as HSX but does not satisfy
|
|
3652
|
+
the host's account-role admission law.
|
|
3653
|
+
|
|
3654
|
+
## Money fields
|
|
3655
|
+
|
|
3656
|
+
A `money<C>` field admits a minor-unit integer string and refuses zero: it lowers to the pattern `^[1-9][0-9]{0,17}$`. Marking the field `optional: true` lets a caller omit it; it does not let a caller send `"0"`. When zero is a real value for the field, opt in with `allow_zero: true`, which lowers to `^(0|[1-9][0-9]{0,17})$`:
|
|
3657
|
+
|
|
3658
|
+
```hsx
|
|
3659
|
+
fields {
|
|
3660
|
+
amount: money<SAR>;
|
|
3661
|
+
discount { type: money<SAR>; optional: true; allow_zero: true; }
|
|
3662
|
+
}
|
|
3663
|
+
```
|
|
3664
|
+
|
|
3665
|
+
`allow_zero` on any other type is HSX1105. Decision port shapes set it on their money fields, because a decided amount may be zero.
|
|
3666
|
+
|
|
3667
|
+
## Date fields
|
|
3668
|
+
|
|
3669
|
+
A `date` field lowers to the UDL `hyperscale-date-time` format. Callers may send any RFC 3339 offset, such as `2026-10-03T09:00:00+03:00`; the host admits it and stores the UTC instant, `2026-10-03T06:00:00.000Z`. A value already in `Z` is stored byte for byte. A local date-time without an offset is refused.
|
|
3670
|
+
|
|
3580
3671
|
# UDL output
|
|
3581
3672
|
|
|
3582
3673
|
An accepted compile returns three artifacts.
|
package/docs/llms.txt
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
|
-
<!-- Generated by scripts/docs/build.ts for HSX 2.
|
|
1
|
+
<!-- Generated by scripts/docs/build.ts for HSX 2.3.0. Do not edit. -->
|
|
2
2
|
|
|
3
3
|
# HSX documentation
|
|
4
4
|
|
|
5
|
-
> Repository guide and generated compiler reference for HSX 2.
|
|
5
|
+
> Repository guide and generated compiler reference for HSX 2.3.0.
|
|
6
6
|
|
|
7
7
|
## Guide
|
|
8
8
|
|
|
@@ -20,7 +20,7 @@
|
|
|
20
20
|
## Reference
|
|
21
21
|
|
|
22
22
|
[Grammar](reference/grammar.md): Lexer, clause, and module vocabulary.
|
|
23
|
-
[Types](reference/types.md): HSX type kinds.
|
|
23
|
+
[Types](reference/types.md): HSX type kinds and account role pins.
|
|
24
24
|
[Diagnostics](reference/diagnostics.md): Stable HSX diagnostic codes and fixes.
|
|
25
25
|
[CLI](reference/cli.md): Generated command usage.
|
|
26
26
|
[UDL output](reference/udl-output.md): Compile artifacts and canonical output.
|
package/docs/reference/cli.md
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
|
-
<!-- Generated by scripts/docs/build.ts for HSX 2.
|
|
1
|
+
<!-- Generated by scripts/docs/build.ts for HSX 2.3.0. Do not edit. -->
|
|
2
2
|
|
|
3
3
|
# CLI
|
|
4
4
|
|
|
5
5
|
```text
|
|
6
|
-
hsx 2.
|
|
6
|
+
hsx 2.3.0, the HSX compiler
|
|
7
7
|
|
|
8
8
|
Usage:
|
|
9
9
|
hsx check <file.hsx> [--catalog <catalog.udl>] [--strict]
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
<!-- Generated by scripts/docs/build.ts for HSX 2.
|
|
1
|
+
<!-- Generated by scripts/docs/build.ts for HSX 2.3.0. Do not edit. -->
|
|
2
2
|
|
|
3
3
|
# Diagnostics
|
|
4
4
|
|
|
@@ -406,6 +406,26 @@ instrument probe {
|
|
|
406
406
|
}
|
|
407
407
|
```
|
|
408
408
|
|
|
409
|
+
## HSX1105: allow_zero needs a money field
|
|
410
|
+
|
|
411
|
+
Stage: `typecheck`
|
|
412
|
+
|
|
413
|
+
Fix: Put allow_zero: true on a money field, or remove it; amounts are strictly positive unless a money field opts in.
|
|
414
|
+
|
|
415
|
+
```hsx expect=HSX1105
|
|
416
|
+
program catalog_probe "Catalog probe"
|
|
417
|
+
instrument probe {
|
|
418
|
+
agent_description: "Probe instrument for catalog diagnostics.";
|
|
419
|
+
fields { memo { type: text; allow_zero: true; } }
|
|
420
|
+
lifecycle { states created; initial created; }
|
|
421
|
+
action create {
|
|
422
|
+
agent_description: "Create a probe instance.";
|
|
423
|
+
steps: [];
|
|
424
|
+
}
|
|
425
|
+
|
|
426
|
+
}
|
|
427
|
+
```
|
|
428
|
+
|
|
409
429
|
## HSX1110: Unsupported parameter combination
|
|
410
430
|
|
|
411
431
|
Stage: `typecheck`
|
package/docs/reference/types.md
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
<!-- Generated by scripts/docs/build.ts for HSX 2.
|
|
1
|
+
<!-- Generated by scripts/docs/build.ts for HSX 2.3.0. Do not edit. -->
|
|
2
2
|
|
|
3
3
|
# Types
|
|
4
4
|
|
|
@@ -18,3 +18,44 @@ HSX checks types before it emits UDL. Money and account values carry a currency
|
|
|
18
18
|
| `ref` | A typed reference to another instrument. |
|
|
19
19
|
| `text` | A finite string value. |
|
|
20
20
|
| `unknown` | An internal checker result that source must resolve before lowering. |
|
|
21
|
+
|
|
22
|
+
## Account fields
|
|
23
|
+
|
|
24
|
+
When declaring fields of type `account<C>`, the HSX compiler automatically lowers the field schema with the UDL2002 account pattern (`^acct_(sandbox|live)_[a-z0-9]{8,64}$`). Authors do not need to write an explicit `pattern` clause on account fields.
|
|
25
|
+
|
|
26
|
+
```hsx
|
|
27
|
+
fields {
|
|
28
|
+
customerAccountId {
|
|
29
|
+
type: account<SAR>;
|
|
30
|
+
"x-hyperscale-reference-filter": { column: role; values: [customer_balance]; };
|
|
31
|
+
}
|
|
32
|
+
amount: money<SAR>;
|
|
33
|
+
}
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
The account type pins the currency and identifier shape. The reference filter
|
|
37
|
+
pins the allowed ledger roles. Product admission requires every account field
|
|
38
|
+
to declare a non-empty role list. Choose roles that match the accounts the
|
|
39
|
+
program will use; `customer_balance` is the role in this example.
|
|
40
|
+
|
|
41
|
+
Use the quoted `"x-hyperscale-reference-filter"` key inside the field block,
|
|
42
|
+
with `column: role` and `values: [...]`. There is no shorter role annotation.
|
|
43
|
+
A bare `customerAccountId: account<SAR>;` compiles as HSX but does not satisfy
|
|
44
|
+
the host's account-role admission law.
|
|
45
|
+
|
|
46
|
+
## Money fields
|
|
47
|
+
|
|
48
|
+
A `money<C>` field admits a minor-unit integer string and refuses zero: it lowers to the pattern `^[1-9][0-9]{0,17}$`. Marking the field `optional: true` lets a caller omit it; it does not let a caller send `"0"`. When zero is a real value for the field, opt in with `allow_zero: true`, which lowers to `^(0|[1-9][0-9]{0,17})$`:
|
|
49
|
+
|
|
50
|
+
```hsx
|
|
51
|
+
fields {
|
|
52
|
+
amount: money<SAR>;
|
|
53
|
+
discount { type: money<SAR>; optional: true; allow_zero: true; }
|
|
54
|
+
}
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
`allow_zero` on any other type is HSX1105. Decision port shapes set it on their money fields, because a decided amount may be zero.
|
|
58
|
+
|
|
59
|
+
## Date fields
|
|
60
|
+
|
|
61
|
+
A `date` field lowers to the UDL `hyperscale-date-time` format. Callers may send any RFC 3339 offset, such as `2026-10-03T09:00:00+03:00`; the host admits it and stores the UTC instant, `2026-10-03T06:00:00.000Z`. A value already in `Z` is stored byte for byte. A local date-time without an offset is refused.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@hyperscale0/hsx",
|
|
3
|
-
"version": "2.
|
|
3
|
+
"version": "2.3.0",
|
|
4
4
|
"description": "The strictly typed HSX language: compile total financial programs into canonical UDL.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"hsx",
|
|
@@ -85,7 +85,7 @@
|
|
|
85
85
|
"generate": "bun run std:bundle && bun run docs:build && bun run playground:build"
|
|
86
86
|
},
|
|
87
87
|
"dependencies": {
|
|
88
|
-
"@hyperscale0/udl": "2.
|
|
88
|
+
"@hyperscale0/udl": "2.5.0"
|
|
89
89
|
},
|
|
90
90
|
"devDependencies": {
|
|
91
91
|
"bun-types": "1.4.2",
|
|
@@ -96,5 +96,5 @@
|
|
|
96
96
|
"Amir Ayub",
|
|
97
97
|
"Sara AlBakaawi"
|
|
98
98
|
],
|
|
99
|
-
"gitHead": "
|
|
99
|
+
"gitHead": "a537ff33ff29340cc2849ea049df4d65889c5d5c"
|
|
100
100
|
}
|
package/src/diagnostics.ts
CHANGED
|
@@ -294,6 +294,13 @@ port pass_inspection { allowed: [seller] shape { invalidField: mystery_type } }`
|
|
|
294
294
|
fix: "Pass the type declared by the parameter or UDL slot.",
|
|
295
295
|
example: instrument("summary: money(SAR, 2500);"),
|
|
296
296
|
},
|
|
297
|
+
{
|
|
298
|
+
code: "HSX1105",
|
|
299
|
+
stage: "typecheck",
|
|
300
|
+
title: "allow_zero needs a money field",
|
|
301
|
+
fix: "Put allow_zero: true on a money field, or remove it; amounts are strictly positive unless a money field opts in.",
|
|
302
|
+
example: instrument("", "memo { type: text; allow_zero: true; }"),
|
|
303
|
+
},
|
|
297
304
|
{
|
|
298
305
|
code: "HSX1110",
|
|
299
306
|
stage: "typecheck",
|