@hazbase/simplicity 0.0.4 → 0.1.1

package/README.md

@@ -11,7 +11,411 @@ This SDK is designed to help Node developers get productive quickly, but it is s
 
 Consumer validation note:
 - The published npm package has been validated from a fresh external Node.js project using `npm install @hazbase/simplicity`.
-- Verified flows include preset-based contract execution, custom `.simf` execution, and relayer-backed gasless execution on `liquidtestnet`.
+- Verified flows include preset-based contract execution, custom `.simf` execution, relayer-backed gasless execution, and LP-fund business-flow validation on `liquidtestnet`.
+
+## Recursive Policy SDK
+
+The SDK now also exposes a generic `sdk.policies` domain for **parametric recursive covenants**.
+
+That means you can model a UTXO as:
+- a policy template definition,
+- a concrete policy state for the current recipient,
+- and a next constrained output that can re-apply the same `.simf` template to the next hop.
+
+Initial reference implementation:
+- `recursive-delay-required.simf`
+- `recursive-delay-optional.simf`
+
+Main entrypoints:
+- `sdk.outputBinding.describeSupport()`
+- `sdk.outputBinding.evaluateSupport(...)`
+- `sdk.policies.describeTemplate(...)`
+- `sdk.policies.validateTemplateParams(...)`
+- `sdk.policies.issue(...)`
+- `sdk.policies.prepareTransfer(...)`
+- `sdk.policies.inspectTransfer(...)`
+- `sdk.policies.executeTransfer(...)`
+- `sdk.policies.verifyState(...)`
+- `sdk.policies.verifyTransfer(...)`
+- `sdk.policies.exportEvidence(...)`
+
+Reference examples:
+- [describe-policy-template.ts](./examples/describe-policy-template.ts)
+- [custom-recursive-delay-required.manifest.json](./examples/custom-recursive-delay-required.manifest.json)
+- [show-required-policy-transfer.ts](./examples/show-required-policy-transfer.ts)
+- [show-optional-policy-transfer.ts](./examples/show-optional-policy-transfer.ts)
+- [execute-required-policy-transfer.ts](./examples/execute-required-policy-transfer.ts)
+- [execute-optional-policy-transfer.ts](./examples/execute-optional-policy-transfer.ts)
+
+### Policy Quickstart
+
+The shortest happy path is:
+1. Describe the template and validate params
+2. Issue the first policy-aware UTXO
+3. Prepare, inspect, execute, and verify the next transfer
+
+Required 1tx recursive hop:
+
+```ts
+const templates = sdk.policies.listTemplates();
+const bindingSupport = sdk.outputBinding.describeSupport();
+const bindingEvaluation = sdk.outputBinding.evaluateSupport({
+  assetId: "bitcoin",
+  requestedBindingMode: "descriptor-bound",
+  outputForm: { amountForm: "confidential" },
+});
+
+const manifest = sdk.policies.describeTemplate({
+  templateId: "recursive-delay",
+  propagationMode: "required",
+});
+
+const params = sdk.policies.validateTemplateParams({
+  templateId: manifest.templateId,
+  propagationMode: "required",
+  params: { lockDistanceBlocks: 2 },
+});
+
+const externalManifest = await sdk.policies.loadTemplateManifest({
+  manifestPath: "./examples/custom-recursive-delay-required.manifest.json",
+});
+
+const issued = await sdk.policies.issue({
+  recipient: { mode: "policy", recipientXonly: currentRecipientXonly },
+  template: { templateId: "recursive-delay", value: { policyTemplateId: "recursive-delay" } },
+  params,
+  amountSat: 6000,
+  assetId: "bitcoin",
+  propagationMode: "required",
+});
+
+const prepared = await sdk.policies.prepareTransfer({
+  currentArtifact: issued.compiled.artifact,
+  template: { templateId: "recursive-delay", value: { policyTemplateId: "recursive-delay" } },
+  currentStateValue: issued.state,
+  nextReceiver: { mode: "policy", recipientXonly: nextRecipientXonly },
+  nextAmountSat: 6000,
+  nextParams: { lockDistanceBlocks: 2 },
+  outputBindingMode: "descriptor-bound",
+});
+```
+
+`sdk.outputBinding.describeSupport()` is the public support matrix for generalized binding. It tells you:
+- which output forms can be auto-derived today,
+- when manual `nextOutputHash` is still allowed,
+- when `descriptor-bound` falls back to `script-bound`,
+- and which runtime paths are validated locally vs on testnet.
+
+`sdk.outputBinding.evaluateSupport(...)` is the quick deterministic answer for a specific scenario. It tells you:
+- the requested binding mode,
+- the resolved binding mode,
+- the reason code,
+- which unsupported features are blocking auto-derive,
+- and whether the manual-hash path would keep `descriptor-bound` available.
+
+If you want the `optional` branch instead, swap:
+- `propagationMode: "optional"`
+- `nextReceiver: { mode: "plain", address: ... }` for plain exit, or keep `mode: "policy"` for the recursive branch
+
+The matching CLI flow is:
+- `policy list-templates`
+- `binding describe-support`
+- `binding evaluate-support`
+- `policy describe-template`
+- `policy validate-template-params`
+- `policy issue`
+- `policy build-output-descriptor`
+- `policy prepare-transfer`
+- `policy inspect-transfer`
+- `policy execute-transfer`
+- `policy verify-state`
+- `policy verify-transfer`
+- `policy export-evidence`
+
+For a testnet runtime example that spends an already-funded current policy UTXO, see:
+- [execute-required-policy-transfer.ts](./examples/execute-required-policy-transfer.ts)
+- [execute-optional-policy-transfer.ts](./examples/execute-optional-policy-transfer.ts)
+
+The intended model is:
+- `propagationMode: "required"`: next hop must remain policy-aware
+- `propagationMode: "optional"`: next hop may remain policy-aware or exit to a plain address
+- `propagationMode: "none"`: the policy ends at this hop
+
+In `required` mode, the current state uses a **1tx direct hop**. The contract checks the current recipient, the relative timelock, the fee output shape, and the next constrained output script hash in the same spend.
+In `optional` mode, the same current state can either:
+- exit to a plain address, or
+- bind the next constrained output in the same transaction
+and the verification report marks the recursive branch as `conditional-hop`.
+
+Current policy enforcement labels:
+- `direct-hop`: `required` 1tx current -> next constrained output
+- `conditional-hop`: `optional` mode when the recursive branch is chosen
+- `sdk-path`: plain exit / no recursive enforcement
+
+If a caller can supply `nextOutputHash`, both recursive policy templates can also take the stronger `descriptor-bound` path and compare `output_hash(0)` at runtime. In that case the amount becomes runtime-bound together with the rest of the output descriptor.
+To make that path easier to use from the public policy API, the SDK now also exposes `sdk.policies.buildOutputDescriptor(...)` and the CLI command `policy build-output-descriptor`. These help derive the next constrained output address, script hash, and canonical descriptor summary before the transfer call.
+The public binding paths are now:
+- `explicit-v1`: `buildOutputDescriptor(...)` auto-derives `nextOutputHash` from high-level inputs when the asset is supplied as `bitcoin` or as a 64-character asset id
+- `raw-output-v1`: advanced callers pass `assetBytesHex`, `amountBytesHex`, `nonceBytesHex`, plus either `scriptPubKeyHex` or `scriptPubKeyHashHex`, and either `rangeProofHex` or `rangeProofHashHex`, and the SDK derives `output_hash(0)` deterministically
+- `manual-hash`: callers supply `nextOutputHash` directly and keep `descriptor-bound` even when auto-derive is unavailable or intentionally bypassed
+- unsupported: the SDK falls back to `script-bound` and records the reason explicitly
+Advanced callers can also pass output-form hints (`assetForm`, `amountForm`, `nonceForm`, `rangeProofForm`) to make confidential/generalized shapes explicit in the descriptor metadata.
+Elements excludes surjection proofs from `output_hash(0)`, so the current generalized binding surface does not require `surjectionProofHex`.
+If that auto-derivation is not available, the SDK now falls back to `script-bound` and records the fallback reason in the verification report instead of silently pretending the stronger mode succeeded.
+The descriptor build result, transfer verification report, and evidence bundle now all carry the same derivation metadata:
+- `supportedForm`
+- `reasonCode`
+- `autoDerived`
+- `fallbackReason`
+- `bindingInputs`
+
+The policy verification and evidence JSON shapes are now versioned:
+- `PolicyVerificationReport.schemaVersion = "policy-verification-report/v1"`
+- `PolicyEvidenceBundle.schemaVersion = "policy-evidence-bundle/v1"`
+and built-in/external template manifests use:
+- `PolicyTemplateManifest.manifestVersion = "policy-template-manifest/v1"`
+
+For relative timelocks, the public policy flow now also derives the contract input sequence from `lockDistanceBlocks`, so `check_lock_distance(...)` can be exercised on testnet without dropping back to the default spend sequence.
+
+The public verification report now uses the same trust vocabulary across policy flows:
+- `committed`
+- `runtimeBound`
+- `sdkVerified`
+
+When an output binding is present, the report can also include:
+- `supportedForm`
+- `reasonCode`
+- `nextOutputHash`
+- `autoDerived`
+- `fallbackReason`
+- `bindingInputs`
+
+This is intentionally explicit about current scope:
+- `explicit-v1`:
+  - explicit asset
+  - explicit amount
+  - null nonce
+  - empty range proof
+  - asset input as `bitcoin` or a 64-character asset id
+- `raw-output-v1`:
+  - caller provides raw output field bytes
+  - SDK derives `output_hash(0)` from those bytes deterministically
+- `manual-hash`:
+  - caller provides `nextOutputHash` directly
+- not yet treated as a default path:
+  - wallet/RPC-driven confidential output reconstruction
+
+For the current runtime validation scope and timelock test-environment caveats, see [docs/design/recursive-policy-runtime-validation.md](./docs/design/recursive-policy-runtime-validation.md).
+Reproducible policy confidence commands:
+- `npm run e2e:policy-local`
+- `POLICY_OUTPUT_BINDING_MODE=script-bound npm run e2e:policy-testnet`
+- `POLICY_OUTPUT_BINDING_MODE=descriptor-bound npm run e2e:policy-testnet`
+- `npm run e2e:policy-consumer`
+
+## LP Fund Settlement Layer
+
+The SDK now also exposes `sdk.funds` as a dedicated business layer for **LP fund settlement on Liquid**.
+
+Security-first vNext model:
+- capital calls are explicit `open -> rollover -> refund-only`
+- manager claim exists only on the `open` artifact
+- LP refund exists only on the `refund-only` artifact
+- `LPPositionReceipt` is an off-chain canonical document wrapped in a manager-attested envelope
+- closing accepts only the latest attested receipt envelope
+
+This layer is intentionally narrower than a full fund-admin system. It focuses on:
+- capital call funding / manager claim / rollover / LP refund
+- signed `LPPositionReceiptEnvelope` generation and reconciliation
+- later one-shot distribution claim contracts
+- finality / close-out evidence
+
+It does **not** introduce `sdk.rwas`. The public architecture remains:
+- `sdk.outputBinding`: shared binding support / fallback contract
+- `sdk.policies`: generic recursive covenant engine
+- `sdk.bonds`: credit / bond business layer
+- `sdk.funds`: LP fund settlement business layer
+
+Main entrypoints:
+- `sdk.funds.define(...)`
+- `sdk.funds.verify(...)`
+- `sdk.funds.load(...)`
+- `sdk.funds.prepareCapitalCall(...)`
+- `sdk.funds.inspectCapitalCallClaim(...)`
+- `sdk.funds.executeCapitalCallClaim(...)`
+- `sdk.funds.inspectCapitalCallRollover(...)`
+- `sdk.funds.executeCapitalCallRollover(...)`
+- `sdk.funds.inspectCapitalCallRefund(...)`
+- `sdk.funds.executeCapitalCallRefund(...)`
+- `sdk.funds.verifyCapitalCall(...)`
+- `sdk.funds.signPositionReceipt(...)`
+- `sdk.funds.verifyPositionReceipt(...)`
+- `sdk.funds.prepareDistribution(...)`
+- `sdk.funds.inspectDistributionClaim(...)`
+- `sdk.funds.executeDistributionClaim(...)`
+- `sdk.funds.verifyDistribution(...)`
+- `sdk.funds.reconcilePosition(...)`
+- `sdk.funds.prepareClosing(...)`
+- `sdk.funds.verifyClosing(...)`
+- `sdk.funds.exportEvidence(...)`
+- `sdk.funds.exportFinalityPayload(...)`
+
+Reference examples:
+- [show-fund-claim-close-flow.ts](./examples/show-fund-claim-close-flow.ts)
+- [show-fund-refund-flow.ts](./examples/show-fund-refund-flow.ts)
+- [fund-definition.json](./docs/definitions/fund-definition.json)
+- [fund-capital-call-state.json](./docs/definitions/fund-capital-call-state.json)
+
+### Fund Quickstart
+
+The intended split for LP fund workflows is:
+
+- off-chain:
+  - KYC/AML
+  - subscription docs
+  - capital account / waterfall / NAV
+  - allocation calculation
+- on-chain SDK:
+  - capital call funding / claim / rollover / refund
+  - distribution payout
+  - finality / close-out evidence
+
+Minimal flow:
+
+```ts
+const capitalCall = await sdk.funds.prepareCapitalCall({
+  definitionPath: "./docs/definitions/fund-definition.json",
+  capitalCallPath: "./docs/definitions/fund-capital-call-state.json",
+});
+
+const initialReceipt = buildLPPositionReceipt({
+  positionId: "POS-001",
+  capitalCall: capitalCall.capitalCallValue,
+  effectiveAt: "2026-03-18T00:00:00Z",
+});
+
+const signedInitialReceipt = await sdk.funds.signPositionReceipt({
+  definitionPath: "./docs/definitions/fund-definition.json",
+  positionReceiptValue: initialReceipt,
+  signer: { type: "schnorrPrivkeyHex", privkeyHex: managerPrivkeyHex },
+  signedAt: "2026-03-18T00:00:00Z",
+});
+
+const firstDistribution = await sdk.funds.prepareDistribution({
+  definitionPath: "./docs/definitions/fund-definition.json",
+  positionReceiptValue: signedInitialReceipt.positionReceiptEnvelope,
+  distributionId: "DIST-001",
+  assetId: capitalCall.capitalCallValue.currencyAssetId,
+  amountSat: 2000,
+  approvedAt: "2027-03-18T00:00:00Z",
+});
+
+const afterFirst = await sdk.funds.reconcilePosition({
+  definitionPath: "./docs/definitions/fund-definition.json",
+  positionReceiptValue: signedInitialReceipt.positionReceiptEnvelope,
+  distributionValue: firstDistribution.distributionValue,
+  signer: { type: "schnorrPrivkeyHex", privkeyHex: managerPrivkeyHex },
+  signedAt: "2027-03-18T00:00:00Z",
+});
+
+const secondDistribution = await sdk.funds.prepareDistribution({
+  definitionPath: "./docs/definitions/fund-definition.json",
+  positionReceiptValue: afterFirst.reconciledReceiptEnvelope,
+  distributionId: "DIST-002",
+  assetId: capitalCall.capitalCallValue.currencyAssetId,
+  amountSat: initialReceipt.fundedAmount - 2000,
+  approvedAt: "2028-03-18T00:00:00Z",
+});
+
+const afterSecond = await sdk.funds.reconcilePosition({
+  definitionPath: "./docs/definitions/fund-definition.json",
+  positionReceiptValue: afterFirst.reconciledReceiptEnvelope,
+  distributionValue: secondDistribution.distributionValue,
+  signer: { type: "schnorrPrivkeyHex", privkeyHex: managerPrivkeyHex },
+  signedAt: "2028-03-18T00:00:00Z",
+});
+
+const closing = await sdk.funds.prepareClosing({
+  definitionPath: "./docs/definitions/fund-definition.json",
+  positionReceiptValue: afterSecond.reconciledReceiptEnvelope,
+  closingId: "CLOSE-001",
+  finalDistributionHashes: [
+    firstDistribution.distributionSummary.hash,
+    secondDistribution.distributionSummary.hash,
+  ],
+  closedAt: "2029-03-18T00:00:00Z",
+});
+```
+
+The split examples are:
+- `show-fund-claim-close-flow.ts`: receipt envelope -> two distributions -> manager-attested reconciliation -> closing/finality
+- `show-fund-refund-flow.ts`: open capital call -> rollover -> refund-only evidence/finality
+
+The matching CLI flow is:
+- `fund define`
+- `fund verify`
+- `fund prepare-capital-call`
+- `fund inspect-capital-call-claim`
+- `fund execute-capital-call-claim`
+- `fund inspect-capital-call-rollover`
+- `fund execute-capital-call-rollover`
+- `fund inspect-capital-call-refund`
+- `fund execute-capital-call-refund`
+- `fund verify-capital-call`
+- `fund sign-position-receipt`
+- `fund verify-position-receipt`
+- `fund prepare-distribution`
+- `fund inspect-distribution-claim`
+- `fund execute-distribution-claim`
+- `fund verify-distribution`
+- `fund reconcile-position`
+- `fund prepare-closing`
+- `fund verify-closing`
+- `fund export-evidence`
+- `fund export-finality-payload`
+
+Reproducible fund confidence commands:
+- `npm run e2e:fund-local`
+- `npm run e2e:fund-consumer`
+- `FUND_OUTPUT_BINDING_MODE=script-bound npm run e2e:fund-testnet`
+- `FUND_OUTPUT_BINDING_MODE=descriptor-bound npm run e2e:fund-testnet`
+- `FUND_FLOW_MODE=refund FUND_OUTPUT_BINDING_MODE=script-bound npm run e2e:fund-testnet`
+- `FUND_OUTPUT_BINDING_MODE=script-bound FUND_DISTRIBUTION_AMOUNTS_SAT=2000,4000 FUND_DISTRIBUTION_IDS=DIST-...-1,DIST-...-2 FUND_APPROVED_ATS=2027-03-18T00:00:00Z,2028-03-18T00:00:00Z npm run e2e:fund-testnet`
+- `FUND_OUTPUT_BINDING_MODE=descriptor-bound FUND_DISTRIBUTION_AMOUNTS_SAT=2000,4000 FUND_DISTRIBUTION_IDS=DIST-...-1,DIST-...-2 FUND_APPROVED_ATS=2027-03-18T00:00:00Z,2028-03-18T00:00:00Z npm run e2e:fund-testnet`
+
+Security notes for `sdk.funds`:
+- on-chain enforced:
+  - `open` capital call allows manager claim only
+  - `refund-only` capital call allows LP refund only
+  - cutoff height is committed into the `open` artifact
+  - output binding uses the shared `script-bound` / `descriptor-bound` / `raw-output-v1` engine
+- off-chain attested:
+  - `LPPositionReceiptEnvelope`
+  - manager attestation over receipt hash and sequence
+- operationally enforced:
+  - watcher/keeper monitors `open` capital calls through `claimCutoffHeight`
+  - watcher/keeper submits rollover after cutoff
+  - LP refund becomes operationally available only after rollover confirmation
+
+Latest fund testnet reruns:
+
+| Flow | Funding txid | Main execution txid(s) | Closing / receipt | Rerun command |
+| --- | --- | --- | --- | --- |
+| `script-bound` claim-close | `a488a5c6e7c56ecca8d5860bf495590d38cfe8087f678f5664241b8eb90396de` | claim `43974a18c048f67f3399b614ea476ffb87c4622d8083636d1aeacbb51747d94d`; distributions `90fb3abdb000d9f66a18b1e2061fa06b56a51fe64513d358c47cc992c374e209`, `0644820b7fee4c11a9a66dbd1a14733ed2420435449717f4895d589f55b05b30` | receipt `f1f294c0f33405f31abbdd8a3a258e57c614bd381b61a7fba2ae420a35e77c70`; closing `19dfd60dfe04cbe1f145a2ab112ef5cf30a087e084837fa7bcce3ed80df72a2a` | `FUND_OUTPUT_BINDING_MODE=script-bound npm run e2e:fund-testnet` |
+| `descriptor-bound` claim-close | `201b66c3843b9999703b08d242c547ca1d1f35619ca99e916d93e4ed70338bc6` | claim `c27621a27cb3b99b4d960cfa4be98de925beed7c3a7bd799fd3f88a3cb680762`; distributions `d4066986e90a9faa000032198307955583e318c0afd09d98691db7b07dc1b022`, `bbfe830790ef5a86a5595d0dccdd2a344efc7d3eebe7a597be1f2a5c2330dabb` | receipt `05b3e4b2c33518b22bd28939cef36972e7fe0c7273b24a6867fba40a0e374fce`; closing `b1ff75e989628130ec56e753f7bc48cc0648b82272c90dfee03f7582879835dd` | `FUND_OUTPUT_BINDING_MODE=descriptor-bound npm run e2e:fund-testnet` |
+| `script-bound` refund | `3adf9025c4656d099752f2e5f43738495fbad712177b75f9330c05273eff12ff` | rollover `8b1224e808ad9824d7bf85924a07d62c75c038987a4163b2e450c455b962ed9d`; refund `6be225448ff062e1f2e8992cf3319601098b7b19edb0ea27823487e9a881f415` | refund-only settlement | `FUND_FLOW_MODE=refund FUND_OUTPUT_BINDING_MODE=script-bound npm run e2e:fund-testnet` |
+
+Current runtime truth for claim-close / refund commands, latest txids, and rerun guidance lives in:
+- [docs/design/fund-runtime-validation.md](./docs/design/fund-runtime-validation.md)
+
+Latest Bond testnet reruns:
+
+| Mode | Funding txid | Execution txid | Rerun command |
+| --- | --- | --- | --- |
+| `script-bound` | `1c982864ef6c83da4eb7f8018edc4cbdff439db7c6366984b3f85ad4937e2c4f` | `d659c4bdce6b32650ff58ac37ccaa55209a9f04d5dc4595f956fad034089f580` | `BOND_OUTPUT_BINDING_MODE=script-bound npm run e2e:bond-testnet` |
+| `descriptor-bound` | `72d0015b51a74c3cc81f7abb74a4f6f894c7f7bbd1e83647939459d7b40e504f` | `85e0830a7b2ba33ca37d5f11bd981938418fc472e98657095680ada71387974c` | `BOND_OUTPUT_BINDING_MODE=descriptor-bound npm run e2e:bond-testnet` |
+
+For current fund runtime scope and caveats, see:
+- [docs/design/fund-runtime-validation.md](./docs/design/fund-runtime-validation.md)
 
 ## Validated Scenarios
 
@@ -24,6 +428,7 @@ The published package has been exercised from a blank external consumer project.
 | Preset flow (`p2pkLockHeight`) | Success | compile -> fund -> inspect -> execute(`broadcast=true`) |
 | Custom `.simf` flow | Success | `compileFromFile(...)` -> fund -> inspect -> execute(`broadcast=true`) |
 | Relayer-backed gasless flow | Success | `executeGasless(...)` succeeded from the external project |
+| LP fund business flow | Success | packaged `sdk.funds` consumer smoke covers capital call, distribution, and finality |
 
 ## Who This Is For
 
@@ -136,80 +541,289 @@ For a bond-oriented walkthrough, see [docs/definitions/README.md](./docs/definit
 
 ## Trusted Issuance State JSON
 
-The same hash-anchor model now also applies to issuance state documents such as a bond issuance record.
-
-This is useful when you want to say not only:
+The same hash-anchor model also applies to issuance state documents such as a bond issuance record.
 
+This lets us say not only:
 - "these are the bond terms,"
 
 but also:
-
 - "this bond was issued in this amount, with this outstanding principal, under this controller."
 
-The SDK now supports:
-
+The SDK supports:
 - loading and hashing a state JSON with `sdk.loadStateDocument(...)`,
 - storing its hash in the artifact,
 - committing `STATE_HASH` into custom `.simf` contract logic,
 - verifying later that the issuance state JSON still matches the compiled contract.
 
-For Bond issuance, the recommended shape is:
-
-```json
-{
-  "issuanceId": "BOND-2026-001-ISSUE-1",
-  "bondId": "BOND-2026-001",
-  "issuerEntityId": "hazbase-treasury",
-  "issuedPrincipal": 1000000,
-  "outstandingPrincipal": 1000000,
-  "redeemedPrincipal": 0,
-  "currencyAssetId": "bitcoin",
-  "controllerXonly": "<xonly>",
-  "issuedAt": "2026-03-10T00:00:00Z",
-  "status": "ISSUED"
-}
+The recommended Bond issuance shape still captures:
+- `issuanceId`
+- `bondId`
+- `issuedPrincipal`
+- `outstandingPrincipal`
+- `redeemedPrincipal`
+- `currencyAssetId`
+- `controllerXonly`
+- `issuedAt`
+- `status`
+
+## Public Architecture
+
+The SDK is now organized around four public layers:
+- `sdk.outputBinding`: cross-domain output-binding support matrix and fallback behavior
+- `sdk.policies`: generic recursive covenant / transfer engine
+- `sdk.bonds`: Bond business layer built on Policy Core primitives and shared output binding
+- `sdk.funds`: LP fund settlement business layer for capital calls, distributions, closing, and finality
+
+This means:
+- use `sdk.policies` when you want a generic constrained-transfer engine,
+- use `sdk.bonds` when you want bond definition / issuance / redemption / settlement / closing / evidence semantics,
+- use `sdk.funds` when you want LP capital call / distribution / closing semantics,
+- use `sdk.outputBinding.describeSupport()` when you want the canonical explanation of supported forms, manual hash paths, and fallback behavior,
+- use `sdk.outputBinding.evaluateSupport(...)` when you want the deterministic answer for one concrete output-form scenario.
+
+## Bond Domain Layer
+
+`sdk.bonds` is now intentionally a **thin business facade**.
+
+Its public responsibility is:
+- bond definition / issuance / settlement / closing schema and invariant handling,
+- business event orchestration,
+- audit / evidence / finality payload export.
+
+Public Bond API:
+- `sdk.bonds.define(...)`
+- `sdk.bonds.verify(...)`
+- `sdk.bonds.load(...)`
+- `sdk.bonds.issue(...)`
+- `sdk.bonds.prepareRedemption(...)`
+- `sdk.bonds.inspectRedemption(...)`
+- `sdk.bonds.executeRedemption(...)`
+- `sdk.bonds.verifyRedemption(...)`
+- `sdk.bonds.buildSettlement(...)`
+- `sdk.bonds.verifySettlement(...)`
+- `sdk.bonds.prepareClosing(...)`
+- `sdk.bonds.inspectClosing(...)`
+- `sdk.bonds.executeClosing(...)`
+- `sdk.bonds.verifyClosing(...)`
+- `sdk.bonds.exportEvidence(...)`
+- `sdk.bonds.exportFinalityPayload(...)`
+
+What is no longer part of the public Bond surface:
+- machine / rollover / state-machine helpers,
+- script-bound / descriptor-bound machine compile helpers,
+- expected-output descriptor helpers as a standalone public API.
+
+Those lower-level primitives are kept only for internal regression and protocol research under:
+- `src/internal/experimental/bond.ts`
+- `examples/internal/experimental/bonds/`
+
+### Shared Output Binding
+
+Bond settlement/build/verify now uses the same binding engine as Policy Core.
+That means Bond and Policy return the same binding metadata vocabulary:
+- `supportedForm`
+- `reasonCode`
+- `autoDerived`
+- `fallbackReason`
+- `bindingInputs`
+
+Current practical behavior:
+- `script-bound`: runtime binds next output script hash, output count, and fee output position
+- `descriptor-bound`: runtime binds `output_hash(0)` when the output form is supported or when the caller supplies a manual `nextOutputHash`
+- unsupported `descriptor-bound` requests fall back to `script-bound` with an explicit reason code
+- supported advanced paths:
+  - `explicit-v1`
+  - `raw-output-v1`
+  - `manual-hash`
+- current generalized/confidential story is explicit on purpose:
+  - unsupported high-level confidential forms still report why they fall back
+  - `raw-output-v1` exists for callers that already know the output bytes or already know the SHA-256 hashes of the scriptPubKey / range proof
+  - surjection proofs are intentionally outside this contract because Elements excludes them from `output_hash(0)`
+  - wallet/RPC-backed confidential auto-reconstruction is still a non-goal in this phase
+
+You can evaluate a concrete binding scenario before building a transfer:
+
+```ts
+const evaluation = sdk.outputBinding.evaluateSupport({
+  assetId: "bitcoin",
+  requestedBindingMode: "descriptor-bound",
+  outputForm: { amountForm: "confidential" },
+});
+
+const rawEvaluation = sdk.outputBinding.evaluateSupport({
+  assetId: "unsupported-asset-alias",
+  requestedBindingMode: "descriptor-bound",
+  rawOutput: {
+    assetBytesHex: "01" + "22".repeat(32),
+    amountBytesHex: "01000000000000076c",
+    nonceBytesHex: "00",
+    scriptPubKeyHex: "5120" + "11".repeat(32),
+    rangeProofHex: "",
+  },
+});
 ```
 
-Minimal TypeScript flow:
+### Bond Runtime Confidence
+
+Latest fresh Bond testnet reruns:
+
+| Binding | Funding txid | Execution txid | Rerun command |
+| --- | --- | --- | --- |
+| `script-bound` | `1c982864ef6c83da4eb7f8018edc4cbdff439db7c6366984b3f85ad4937e2c4f` | `d659c4bdce6b32650ff58ac37ccaa55209a9f04d5dc4595f956fad034089f580` | `BOND_OUTPUT_BINDING_MODE=script-bound npm run e2e:bond-testnet` |
+| `descriptor-bound` | `72d0015b51a74c3cc81f7abb74a4f6f894c7f7bbd1e83647939459d7b40e504f` | `85e0830a7b2ba33ca37d5f11bd981938418fc472e98657095680ada71387974c` | `BOND_OUTPUT_BINDING_MODE=descriptor-bound npm run e2e:bond-testnet` |
+
+For the current truth source and caveats, see [docs/design/bond-runtime-validation.md](./docs/design/bond-runtime-validation.md).
+
+### Minimal Bond Flow
 
 ```ts
-const compiled = await sdk.bonds.defineBond({
+const compiled = await sdk.bonds.define({
   definitionPath: "./docs/definitions/bond-definition.json",
   issuancePath: "./docs/definitions/bond-issuance-state.json",
   simfPath: "./docs/definitions/bond-issuance-anchor.simf",
   artifactPath: "./bond-issuance.artifact.json",
 });
 
-const verification = await sdk.bonds.verifyBond({
+const verified = await sdk.bonds.verify({
   artifactPath: "./bond-issuance.artifact.json",
   definitionPath: "./docs/definitions/bond-definition.json",
   issuancePath: "./docs/definitions/bond-issuance-state.json",
 });
 
-console.log(verification.crossChecks.principalInvariantValid);
-console.log(verification.issuance.trust.effectiveMode);
+const redemption = await sdk.bonds.prepareRedemption({
+  definitionPath: "./docs/definitions/bond-definition.json",
+  previousIssuancePath: "./docs/definitions/bond-issuance-state.json",
+  amount: 250000,
+  redeemedAt: "2027-03-10T00:00:00Z",
+  nextStateSimfPath: "./docs/definitions/bond-issuance-anchor.simf",
+  nextAmountSat: 1900,
+  outputBindingMode: "script-bound",
+});
+
+const settlement = await sdk.bonds.buildSettlement({
+  definitionPath: "./docs/definitions/bond-definition.json",
+  previousIssuancePath: "./docs/definitions/bond-issuance-state.json",
+  nextIssuanceValue: redemption.preview.next,
+  nextStateSimfPath: "./docs/definitions/bond-issuance-anchor.simf",
+  nextAmountSat: 1900,
+  outputBindingMode: "script-bound",
+});
+
+const closing = await sdk.bonds.prepareClosing({
+  definitionPath: "./docs/definitions/bond-definition.json",
+  redeemedIssuancePath: "./docs/definitions/bond-issuance-state-redeemed.json",
+  settlementDescriptorValue: settlement.descriptor,
+  closedAt: "2027-03-10T00:00:00Z",
+});
+
+const evidence = await sdk.bonds.exportEvidence({
+  artifactPath: "./bond-issuance.artifact.json",
+  definitionPath: "./docs/definitions/bond-definition.json",
+  issuancePath: "./docs/definitions/bond-issuance-state.json",
+  settlementDescriptorValue: settlement.descriptor,
+});
 ```
 
-CLI equivalents:
+### Bond CLI Flow
 
 ```bash
-simplicity-cli state show \
-  --type bond-issuance \
-  --id BOND-2026-001-ISSUE-1 \
-  --json-path ./docs/definitions/bond-issuance-state.json
+simplicity-cli bond define \
+  --definition-json ./docs/definitions/bond-definition.json \
+  --issuance-json ./docs/definitions/bond-issuance-state.json \
+  --simf ./docs/definitions/bond-issuance-anchor.simf \
+  --artifact ./bond-issuance.artifact.json
 
-simplicity-cli state verify \
+simplicity-cli bond verify \
   --artifact ./bond-issuance.artifact.json \
-  --type bond-issuance \
-  --id BOND-2026-001-ISSUE-1 \
-  --json-path ./docs/definitions/bond-issuance-state.json
+  --definition-json ./docs/definitions/bond-definition.json \
+  --issuance-json ./docs/definitions/bond-issuance-state.json
 
-simplicity-cli bond verify \
+simplicity-cli bond prepare-redemption \
+  --definition-json ./docs/definitions/bond-definition.json \
+  --previous-issuance-json ./docs/definitions/bond-issuance-state.json \
+  --amount 250000 \
+  --redeemed-at 2027-03-10T00:00:00Z \
+  --next-state-simf ./docs/definitions/bond-issuance-anchor.simf \
+  --next-amount-sat 1900 \
+  --output-binding-mode script-bound \
+  --next-issuance-out ./next-bond-issuance-state.json
+
+simplicity-cli bond build-settlement \
+  --definition-json ./docs/definitions/bond-definition.json \
+  --previous-issuance-json ./docs/definitions/bond-issuance-state.json \
+  --next-issuance-json ./next-bond-issuance-state.json \
+  --next-state-simf ./docs/definitions/bond-issuance-anchor.simf \
+  --next-amount-sat 1900 \
+  --output-binding-mode script-bound
+
+simplicity-cli bond prepare-closing \
+  --definition-json ./docs/definitions/bond-definition.json \
+  --redeemed-issuance-json ./docs/definitions/bond-issuance-state-redeemed.json \
+  --settlement-descriptor-json ./bond-settlement.json \
+  --closed-at 2027-03-10T00:00:00Z
+
+simplicity-cli bond export-evidence \
   --artifact ./bond-issuance.artifact.json \
   --definition-json ./docs/definitions/bond-definition.json \
   --issuance-json ./docs/definitions/bond-issuance-state.json
+
+simplicity-cli binding evaluate-support \
+  --asset-id bitcoin \
+  --output-binding-mode descriptor-bound \
+  --amount-form confidential
+```
+
+Example `bond build-settlement` summary:
+
+```text
+descriptorHash=4d8f...
+bindingMode=descriptor-bound
+previousStateHash=8c3b...
+nextStateHash=56ae...
+nextContractAddress=tex1p...
+nextAmountSat=1900
+maxFeeSat=100
+supportedForm=explicit-v1
+reasonCode=OK_EXPLICIT
+autoDerived=true
+nextOutputHash=0b9a...
+bindingInputs(asset=bitcoin, amountSat=1900, nextOutputIndex=0, feeIndex=1, maxFeeSat=100)
+bindingInputForms(assetForm=explicit, amountForm=explicit, nonceForm=null, rangeProofForm=empty)
+```
+
+Example `bond verify-redemption` summary:
+
+```text
+phase=verify
+mode=descriptor-bound
+descriptorHash=4d8f...
+nextStateHash=56ae...
+nextAmountSat=1900
+verified=true
+bindingMode=descriptor-bound
+supportedForm=explicit-v1
+reasonCode=OK_EXPLICIT
+autoDerived=true
+nextOutputHash=0b9a...
+outputBinding.mode=descriptor-bound
+outputBinding.nextContractAddressCommitted=true
+outputBinding.outputCountRuntimeBound=true
+outputBinding.feeIndexRuntimeBound=true
+outputBinding.nextOutputHashRuntimeBound=true
+outputBinding.nextOutputScriptRuntimeBound=false
 ```
 
+Important limitation:
+- Bond finality is stronger than before, but still intentionally partial.
+- `script-bound` currently runtime-binds output count, fee position, and next output script hash.
+- `descriptor-bound` adds runtime `output_hash(0)` binding for supported explicit/manual-hash paths.
+- exact next output amount is still not a fully generalized covenant across all output forms.
+- unsupported confidential/generalized output forms fall back deterministically and report why.
+
+For a Bond-oriented walkthrough that matches the current public surface, see [docs/definitions/README.md](./docs/definitions/README.md).
+For a packaged external-consumer smoke of the public business flow, run `npm run e2e:bond-consumer`.
+For the resumable Bond runtime/testnet validation flow, see [docs/design/bond-runtime-validation.md](./docs/design/bond-runtime-validation.md).
+
 ## Install
 
 You need three things:
@@ -876,6 +1490,7 @@ simplicity-cli gasless request \
 
 These examples are included to help you jump to the right workflow quickly.
 
+Core contract workflows:
 - [compile-custom.ts](./examples/compile-custom.ts): compile a custom `.simf` file.
 - [compile-preset.ts](./examples/compile-preset.ts): compile a built-in preset.
 - [inspect-contract.ts](./examples/inspect-contract.ts): inspect a contract spend before broadcast.
@@ -885,11 +1500,28 @@ These examples are included to help you jump to the right workflow quickly.
 - [execute-htlc.ts](./examples/execute-htlc.ts): HTLC preset with custom witness values.
 - [execute-transfer-with-timeout-cooperative.ts](./examples/execute-transfer-with-timeout-cooperative.ts): cooperative multi-witness timeout flow.
 - [gasless-transfer.ts](./examples/gasless-transfer.ts): standard relayer-backed gasless L-BTC transfer.
-- [define-bond.ts](./examples/define-bond.ts): compile a bond example with a trusted definition hash anchor.
-- [show-bond-definition.ts](./examples/show-bond-definition.ts): verify and retrieve a trusted bond definition from JSON + artifact.
-- [define-bond-issuance.ts](./examples/define-bond-issuance.ts): compile a bond example with both trusted definition and issuance state anchors.
-- [show-bond-issuance.ts](./examples/show-bond-issuance.ts): load a bond artifact together with its verified issuance state.
-- [verify-bond-issuance.ts](./examples/verify-bond-issuance.ts): run combined Bond definition/state verification and invariant checks.
+
+Policy Core examples:
+- [describe-policy-template.ts](./examples/describe-policy-template.ts): inspect a public policy manifest and validate params.
+- [show-required-policy-transfer.ts](./examples/show-required-policy-transfer.ts): preview a required 1tx recursive transfer.
+- [show-optional-policy-transfer.ts](./examples/show-optional-policy-transfer.ts): preview an optional plain-or-recursive transfer.
+- [execute-required-policy-transfer.ts](./examples/execute-required-policy-transfer.ts): execute a funded required policy UTXO.
+- [execute-optional-policy-transfer.ts](./examples/execute-optional-policy-transfer.ts): execute an optional plain or recursive branch.
+- [custom-recursive-delay-required.manifest.json](./examples/custom-recursive-delay-required.manifest.json): example external manifest for custom template loading.
+
+Bond business-layer examples:
+- [define-bond.ts](./examples/define-bond.ts): compile a bond definition anchor with the generic contract API.
+- [show-bond-definition.ts](./examples/show-bond-definition.ts): verify and retrieve a trusted bond definition.
+- [define-bond-issuance.ts](./examples/define-bond-issuance.ts): define a bond issuance artifact.
+- [show-bond-issuance.ts](./examples/show-bond-issuance.ts): load a bond artifact with verified issuance state.
+- [verify-bond-issuance.ts](./examples/verify-bond-issuance.ts): run bond invariant checks against artifact + JSON inputs.
+- [show-bond-business-flow.ts](./examples/show-bond-business-flow.ts): walk the business-layer flow from definition through finality payload export.
+- [redeem-bond-issuance.ts](./examples/redeem-bond-issuance.ts): prepare a bond redemption preview and next issuance state.
+- [show-bond-settlement-payload.ts](./examples/show-bond-settlement-payload.ts): build a public settlement descriptor.
+- [verify-bond-settlement.ts](./examples/verify-bond-settlement.ts): verify a settlement descriptor against bond inputs.
+
+Internal / experimental Bond regressions:
+- [examples/internal/experimental/bonds/README.md](./examples/internal/experimental/bonds/README.md): low-level machine / rollover / transition helpers retained for research and regression only.
 
 In addition to the in-repo examples, the package has also been validated from a blank external consumer project with:
 - `npm install @hazbase/simplicity`
@@ -897,6 +1529,11 @@ In addition to the in-repo examples, the package has also been validated from a
 - preset compile -> fund -> inspect -> execute
 - custom `.simf` compile -> fund -> inspect -> execute
 - relayer-backed gasless execution
+- policy quickstart smoke via `npm run e2e:policy-consumer`
+
+## Covenant Roadmap
+
+If you want to see how the current bond lifecycle work can evolve toward stronger output binding, see [docs/design/full-covenant-output-binding.md](./docs/design/full-covenant-output-binding.md). That note captures what the local SimplicityHL examples appear to expose today and what the next realistic covenant milestones are.
 
 ## FAQ / Practical Notes