@hazbase/simplicity 0.0.5 → 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,210 +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"
-}
-```
-
-To move from an issued bond into a redemption state, the SDK now also supports a minimal state transition model:
+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:
 
-- `ISSUED -> PARTIALLY_REDEEMED`
-- `ISSUED/PARTIALLY_REDEEMED -> REDEEMED`
-
-The next state records:
-
-- `previousStateHash`
-- `lastTransition.type`
-- `lastTransition.amount`
-- `lastTransition.at`
+```ts
+const evaluation = sdk.outputBinding.evaluateSupport({
+  assetId: "bitcoin",
+  requestedBindingMode: "descriptor-bound",
+  outputForm: { amountForm: "confidential" },
+});
 
-and the SDK verifies the principal invariant:
+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: "",
+  },
+});
+```
 
-- `issuedPrincipal = outstandingPrincipal + redeemedPrincipal`
+### Bond Runtime Confidence
 
-On top of that, the SDK can now build a `BondSettlementDescriptor`, which bundles the intended settlement envelope into one canonical document:
+Latest fresh Bond testnet reruns:
 
-- `definitionHash`
-- `previousStateHash`
-- `nextStateHash`
-- `nextContractAddress`
-- `nextAmountSat`
-- `maxFeeSat`
-- status progression and principal deltas
+| 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` |
 
-The redemption machine commits that settlement descriptor hash as an additional anchor. This does not yet mean full runtime output introspection, but it does mean the machine can now honestly claim a committed settlement envelope instead of just a scattered set of fields.
+For the current truth source and caveats, see [docs/design/bond-runtime-validation.md](./docs/design/bond-runtime-validation.md).
 
-Minimal TypeScript flow:
+### 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);
-```
-
-Minimal redemption flow:
-
-```ts
-const preview = await sdk.bonds.buildBondRedemption({
+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 compiled = await sdk.bonds.redeemBond({
+const settlement = await sdk.bonds.buildSettlement({
   definitionPath: "./docs/definitions/bond-definition.json",
   previousIssuancePath: "./docs/definitions/bond-issuance-state.json",
-  amount: 250000,
-  redeemedAt: "2027-03-10T00:00:00Z",
-  simfPath: "./docs/definitions/bond-issuance-anchor.simf",
-  artifactPath: "./bond-redemption.artifact.json",
-});
-
-const transition = await sdk.bonds.verifyBondTransition({
-  previousIssuancePath: "./docs/definitions/bond-issuance-state.json",
-  nextIssuancePath: "./docs/definitions/bond-issuance-state-partial-redemption.json",
+  nextIssuanceValue: redemption.preview.next,
+  nextStateSimfPath: "./docs/definitions/bond-issuance-anchor.simf",
+  nextAmountSat: 1900,
+  outputBindingMode: "script-bound",
 });
 
-const payload = await sdk.bonds.buildBondPayload({
-  artifactPath: "./bond-redemption.artifact.json",
+const closing = await sdk.bonds.prepareClosing({
   definitionPath: "./docs/definitions/bond-definition.json",
-  issuancePath: "./docs/definitions/bond-issuance-state-partial-redemption.json",
+  redeemedIssuancePath: "./docs/definitions/bond-issuance-state-redeemed.json",
+  settlementDescriptorValue: settlement.descriptor,
+  closedAt: "2027-03-10T00:00:00Z",
 });
 
-const transitionPayload = await sdk.bonds.buildBondTransitionPayload({
+const evidence = await sdk.bonds.exportEvidence({
+  artifactPath: "./bond-issuance.artifact.json",
   definitionPath: "./docs/definitions/bond-definition.json",
-  previousIssuancePath: "./docs/definitions/bond-issuance-state.json",
-  nextIssuancePath: "./docs/definitions/bond-issuance-state-partial-redemption.json",
+  issuancePath: "./docs/definitions/bond-issuance-state.json",
+  settlementDescriptorValue: settlement.descriptor,
 });
-
-console.log(preview.nextHash);
-console.log(compiled.state()?.hash);
-console.log(transition.transition.statusProgressionValid);
-console.log(payload.payload);
-console.log(transitionPayload.payload.redeemAmount);
 ```
 
-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 state verify \
-  --artifact ./bond-issuance.artifact.json \
-  --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 bond verify \
   --artifact ./bond-issuance.artifact.json \
   --definition-json ./docs/definitions/bond-definition.json \
   --issuance-json ./docs/definitions/bond-issuance-state.json
 
-simplicity-cli bond redeem \
+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 \
-  --simf ./docs/definitions/bond-issuance-anchor.simf \
-  --next-issuance-out ./next-bond-issuance-state.json \
-  --artifact ./bond-redemption.artifact.json
-
-simplicity-cli bond verify-transition \
-  --previous-issuance-json ./docs/definitions/bond-issuance-state.json \
-  --next-issuance-json ./docs/definitions/bond-issuance-state-partial-redemption.json
+  --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 compile-transition \
+simplicity-cli bond build-settlement \
   --definition-json ./docs/definitions/bond-definition.json \
   --previous-issuance-json ./docs/definitions/bond-issuance-state.json \
-  --next-issuance-json ./docs/definitions/bond-issuance-state-partial-redemption.json \
-  --simf ./docs/definitions/bond-redemption-transition.simf \
-  --artifact ./bond-transition.artifact.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 compile-redemption-machine \
+simplicity-cli bond prepare-closing \
   --definition-json ./docs/definitions/bond-definition.json \
-  --previous-issuance-json ./docs/definitions/bond-issuance-state.json \
-  --next-issuance-json ./docs/definitions/bond-issuance-state-partial-redemption.json \
-  --simf ./docs/definitions/bond-redemption-state-machine.simf \
-  --artifact ./bond-redemption-machine.artifact.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 verify-machine \
-  --artifact ./bond-redemption-machine.artifact.json \
-  --definition-json ./docs/definitions/bond-definition.json \
-  --previous-issuance-json ./docs/definitions/bond-issuance-state.json \
-  --next-issuance-json ./docs/definitions/bond-issuance-state-partial-redemption.json
-
-simplicity-cli bond plan-rollover \
-  --current-artifact ./bond-issuance.artifact.json \
+simplicity-cli bond export-evidence \
+  --artifact ./bond-issuance.artifact.json \
   --definition-json ./docs/definitions/bond-definition.json \
-  --previous-issuance-json ./docs/definitions/bond-issuance-state.json \
-  --next-issuance-json ./docs/definitions/bond-issuance-state-partial-redemption.json \
-  --next-simf ./docs/definitions/bond-issuance-anchor.simf \
-  --next-artifact ./bond-next.artifact.json
+  --issuance-json ./docs/definitions/bond-issuance-state.json
 
-simplicity-cli bond plan-machine-rollover \
-  --current-artifact ./bond-issuance.artifact.json \
-  --definition-json ./docs/definitions/bond-definition.json \
-  --previous-issuance-json ./docs/definitions/bond-issuance-state.json \
-  --next-issuance-json ./docs/definitions/bond-issuance-state-partial-redemption.json \
-  --machine-simf ./docs/definitions/bond-redemption-state-machine.simf \
-  --machine-artifact ./bond-redemption-machine.artifact.json
+simplicity-cli binding evaluate-support \
+  --asset-id bitcoin \
+  --output-binding-mode descriptor-bound \
+  --amount-form confidential
+```
 
-simplicity-cli bond transition-payload \
-  --definition-json ./docs/definitions/bond-definition.json \
-  --previous-issuance-json ./docs/definitions/bond-issuance-state.json \
-  --next-issuance-json ./docs/definitions/bond-issuance-state-partial-redemption.json
+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)
+```
 
-simplicity-cli bond payload \
-  --artifact ./bond-redemption.artifact.json \
-  --definition-json ./docs/definitions/bond-definition.json \
-  --issuance-json ./docs/definitions/bond-issuance-state-partial-redemption.json
+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:
@@ -1006,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.
@@ -1015,21 +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.
-- [redeem-bond-issuance.ts](./examples/redeem-bond-issuance.ts): build the next redemption state and compile a new anchored artifact.
-- [verify-bond-transition.ts](./examples/verify-bond-transition.ts): verify a previous/next issuance state transition.
-- [compile-bond-transition.ts](./examples/compile-bond-transition.ts): compile a transition contract that commits both previous and next issuance state hashes.
-- [compile-bond-redemption-machine.ts](./examples/compile-bond-redemption-machine.ts): compile a redemption transition contract that also commits redeem amount and transition kind.
-- [verify-bond-redemption-machine.ts](./examples/verify-bond-redemption-machine.ts): verify a compiled redemption machine artifact against definition, previous state, and next state inputs.
-- [plan-bond-rollover.ts](./examples/plan-bond-rollover.ts): build a runtime rollover plan that spends the current state UTXO into the next state's contract address.
-- [show-bond-transition-payload.ts](./examples/show-bond-transition-payload.ts): emit a bridge-ready payload for a previous/next redemption transition.
-- [show-bond-payload.ts](./examples/show-bond-payload.ts): emit a bridge-ready payload from a verified bond artifact.
-- [redeem-bond-issuance.ts](./examples/redeem-bond-issuance.ts): build a partially redeemed bond issuance state and anchor it in a new artifact.
-- [verify-bond-transition.ts](./examples/verify-bond-transition.ts): verify a redemption transition between two issuance state documents.
+
+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`
@@ -1037,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