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

package/docs/guide/09-cost.md

@@ -0,0 +1,24 @@
+# Cost
+
+Compilation emits a deterministic cost manifest beside the UDL document. The manifest pins the cost-table version and effective digest. It records fixed structural cost, action effect rows, payer, settlement policy, meters, per-event prices, and any basis-point volume price.
+
+```hsx
+program direct_sale "Direct sale"
+import { instant_transfer } from "std/settlements"
+party buyer: person
+party seller: business
+settlement sale = instant_transfer {
+  payer: buyer
+  payee: seller
+  amount: saleAmount: money(SAR)
+  fees { buyer: 1% }
+}
+```
+
+Read an action line as `instrument.action`, followed by the effect signature and its count. The payer tells whether the product or end customer bears the row. `perEventMinor` prices one occurrence in the cost table's billing currency. A row with `bps` also names a volume meter.
+
+The monthly estimate is an expression over declared meter variables. Billing supplies observed readings to that frozen expression. Recomposition emits a new manifest for the next commercial snapshot. It does not rewrite a prior manifest.
+
+An effect without a price row reports `HSX1301`. An invalid price reports `HSX1302`. A missing cost table also reports `HSX1301`. Use the single rate card shipped at `examples/cost-table.json`; do not create a second table for documentation.
+
+Do not confuse an action `quote` with the commercial cost manifest. `cancellable_booking.cancel` quotes a customer-visible cancellation penalty and `confirm` commits it. The compiler counts an instrument that carries a quote as unwind work because an expired or abandoned offer still needs bounded cleanup. The cost manifest prices that runtime work from the shipped rate card. It does not replace, spend, or alter the quoted financial amount.

package/docs/guide/10-diagnostics.md

@@ -0,0 +1,27 @@
+# Diagnostics
+
+An HSX diagnostic carries a stable code, severity, stage, source line and column, message, and fix. Match automation on the code. Treat the message as explanation rather than a stable interface.
+
+The stages locate the refusal:
+
+- `parse` means the source did not form valid declarations or expressions.
+- `bind` means an import, name, port, or reference did not resolve.
+- `typecheck` and `check` mean the program formed but violated a type or language law.
+- `lower` means the typed program could not emit valid UDL.
+
+Use one loop: compile, find the first error code in the diagnostics reference, apply its stated fix, and compile again. Do not suppress the diagnostic or alter generated UDL by hand.
+
+```hsx
+program repaired_transfer "Repaired transfer"
+import { instant_transfer } from "std/settlements"
+party sender: person
+party recipient: business
+settlement transfer = instant_transfer {
+  payer: sender
+  payee: recipient
+  amount: transferAmount: money(SAR)
+  fees { sender: 1% }
+}
+```
+
+Exit code `0` means the command accepted the program. Exit code `1` means compilation refused it. Exit code `2` means the invocation or file operation failed. `hsx explain HSX1201` prints the catalog entry for one code.