feat: add BRC-170 LCH reference implementation

[ty-everett]

Keep this pull request in draft while BRC-170 and its reference implementation
are reviewed together. Publication remains release-workflow-only after approval.

Program and scope

• Tracker or issue: draft BRC-170, BRC-170: Locked Content Header (LCH) BRCs#236
• Program gate(s) advanced: first neutral reference implementation, portable vectors, and executable profile feedback for draft BRC-170.
• Why this change is needed: BRC-170 needs interoperable TypeScript primitives and an application that exercises acquisition, enforcement, composition, provenance, and training boundaries before the proposal is stabilized.
• Explicitly out of scope: npm publication, production payments, live storefront behavior, application-specific catalogue/social schemas, selective settlement mapping, and deployment.
• Exact head SHA reviewed: 971eb4f6690a4ca9f8fa65fc872a5a507b978cd4.

Impact

• No public package source or manifest changed
• Public package source or manifest changed; affected packages are listed below
• Infrastructure source, dependency, image, or deployment configuration changed
• Public API, exports, types, runtime targets, or browser/mobile behavior changed
• Security-sensitive boundary changed
• Documentation or examples changed

Affected packages/services and intended versions (publication occurs only through the release workflow after approval):

• New public @bsv/lch 0.1.0 package with SDK and optional CHIRP integration, CLI, deterministic encodings, content protection, entitlement/payment, authority/revocation, transport, composition/provenance, and core-profile APIs.
• New private apps/lch-reference neutral conformance workbench. It deliberately avoids vendor branding and exercises all six core profiles after license acquisition, including unknown-critical rejection, metered boundaries, entitlement reuse, half-open rental times, training semantics, repeated placements, reversal, exact-ratio time warping, and distortion.
• No publication or deployment performed.

Verification

• Local commands and results: full root build, typecheck, and test passed. On the final test-only property-generator change, the exact failing seed passed 10,000 cases, overlay-discovery coverage passed 97/97 with the URI module at 100%, LCH coverage passed 12 suites / 71 tests, the reference app passed 8 tests, and root lint, formatting, and repository health passed.
• Hosted exact-head CI: 36 successful checks, three expected scope-based skips, zero failed, cancelled, stale, or pending checks; merge gate passed.
• Conformance evidence: 6,690 existing TS Stack vectors pass. BRC-170 vectors regenerate deterministically at SHA-256 92c834e0be390cde0f3935c2cc0e7f96657c6ad56bc478d6bd643ccd8770598a and independently validate 14 objects, 9 signatures, 6 segments, six editorial placements, unique repeated-placement C2PA bindings, BRC-78 recovery, time boundaries, and randomized payment outputs.
• Coverage: @bsv/lch 94.20% statements, 82.71% branches, 93.75% functions, and 95.21% lines. Authority validation is 100% statements/functions/lines and 95.31% branches. Hosted changed-code coverage is 90.19% (1,452/1,610 points; 90% gate).
• Mutation: exact-head lch-cbor run instrumented 146 mutants and scored 92.47% (134 killed, 11 survived, one timeout); the mutation quality gate passed.
• Security analysis: exact-head Actions and JavaScript/TypeScript CodeQL passed. Sonar reports zero unresolved PR issues and zero unreviewed hotspots; the repository zero-new-findings gate passed.
• Browser/mobile/packed-consumer evidence: exact package tarball, Node ESM/CJS exports, declaration maps, publint, CLI, Vite/esbuild browser consumers, browser-platform matrices, wallet browser, and wallet mobile all pass. Exact tarball consumers measured 421,729 bytes raw / 114,757 gzip / 95,330 Brotli with Vite and 328,010 raw / 105,951 gzip / 89,830 Brotli with esbuild, within repository gates.
• Notices: both the public package and neutral app ship release-consistent third-party notices; the app build includes the notice plus 18 exact dependency license texts, and package/release/notice checks pass.
• I self-reviewed the complete diff for correctness, security, compatibility, public API, artifacts, dependencies, docs, and operations
• All applicable checks are terminal and successful on the exact head; scope-based skips are expected and validated by the merge gate

Security and dependencies

• No dependency or lockfile change
• Changelog, runtime relevance, peer compatibility, transitive graph, and audit results were reviewed
• CodeQL/negative tests cover changed trust boundaries
• The exact-head CodeQL analysis has no new alert
• The exact-head repository quality gate reports zero new Sonar findings and zero unreviewed hotspots
• No new override, advisory dismissal, quality suppression, or skipped test
• Any temporary exception is registered with owner, evidence, review date, and removal condition
• Workflow permissions and lifecycle-script behavior remain least privilege

Dependency evidence

• Release notes and necessity: first additive BRC-170 package; the draft spec remains authoritative while both PRs are open.
• Runtime, build, and peer compatibility: @bsv/sdk 2.4 peer plus optional @bsv/chirp 0.1 peer; exact packed consumers and browser bundlers pass.
• Deduplicated lockfile: workspace lockfile resolution and repository health checks pass.
• Audit and CodeQL: governed security audit and exact-head CodeQL pass; dependency review and Socket checks pass.
• Package and consumer tests: LCH unit/property/coverage/mutation, tarball, ESM/CJS, CLI, Vite, esbuild, platform, and reference-app tests pass.
• Affected public package version: @bsv/lch 0.1.0.

Release and operations

• No npm publication was performed from a workstation or from this PR
• Required npm patch bumps are included or intentionally deferred by the controlling program
• Image/SBOM/provenance/deployment/rollback impact is documented
• Documentation, changelog, migration, and operational guidance are current

Completion evidence

• The linked spec draft reflects implementation discoveries proved by tests and portable vectors
• Review conversations are resolved (neither PR currently has a review thread)
• Documentation, changelog, release notes, third-party notices, and operator guidance are current or concretely not applicable
• No pending, failed, stale, cancelled, or unexpectedly skipped check is being handed to another contributor as “complete”
• One qualified maintainer approval has been received

[ty-everett]

Exact head 971eb4f6690a4ca9f8fa65fc872a5a507b978cd4 is now fully green: 36 successful checks, three expected scope skips, zero pending/failing checks, and merge-gate success. Hosted changed-code coverage is 90.19% (1,452/1,610), LCH CBOR mutation score is 92.47%, and Sonar reports 0 unresolved issues / 0 hotspots. The draft also includes the neutral reference-workbench pass, release-consistent third-party notices, and the repeat/reversal/exact-ratio time-warp/distortion conformance scenarios. This PR remains draft pending joint review with BRC-170.

[codecov]

Codecov Report

❌ Patch coverage is 90.20619% with 190 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
packages/content/lch/src/multipayClient.ts	72.47%	28 Missing and 21 partials ⚠️
packages/content/lch/src/core.ts	82.89%	7 Missing and 19 partials ⚠️
packages/content/lch/src/storage.ts	82.97%	8 Missing and 8 partials ⚠️
packages/content/lch/src/policy.ts	71.42%	7 Missing and 7 partials ⚠️
packages/content/lch/src/http.ts	91.61%	5 Missing and 8 partials ⚠️
packages/content/lch/src/cli.ts	68.42%	8 Missing and 4 partials ⚠️
packages/content/lch/src/acquisition.ts	96.30%	0 Missing and 10 partials ⚠️
packages/content/lch/src/selection.ts	76.74%	6 Missing and 4 partials ⚠️
packages/content/lch/src/endpoints.ts	87.14%	3 Missing and 6 partials ⚠️
packages/content/lch/src/settlement.ts	95.78%	4 Missing and 4 partials ⚠️
... and 9 more

📢 Thoughts on this report? Let us know!

[ty-everett]

Exact head 2d78df64c54a00248641f0f6f579c43ff5af627b turns the LCH draft into an executable acquisition stack.

The reference path is now concrete end to end: a creator wizard publishes protected content and an Offer; the issuer produces buyer-bound Payment Demands; a BRC-100 buyer wallet funds one Atomic BEEF transaction; each Payee verifies and internalizes its exact BRC-29 wallet-payment output; the issuer verifies the signed receipts and releases the License; and the player decrypts and exercises every initial profile. Ambiguous delivery recovery reuses the same funded transaction and cannot double-pay.

The package includes the deterministic-CBOR HTTP binding, reusable server/client, Payee receiver and ledger boundary, multilateral payment client, endpoint policy, recovery, and deployment adapters. The executable reference server exposes health, asset publication, acquisition, and range-capable content endpoints; DEPLOYMENT.md defines single-process and durable topologies, connected-wallet module wiring, and CHIRP/UHRP content adapters. The neutral workbench visibly exercises repeat, trim, exact rational time-warp, reversal, distortion, mixing, C2PA placement, training provenance, and all six initial profiles. Release-consistent third-party notices are retained in the built artifact.

Exact-head hosted CI is fully green: 36 successful checks, 3 expected scope skips, 0 pending/failing; merge gate, Sonar, CodeQL, dependency review, browser/mobile lanes, package artifact checks, and mutation gates all pass. Hosted changed-code coverage is 90.65% (2,122/2,341 points; 90% target). Local @bsv/lch coverage is 94.03% statements / 83.87% branches / 95.11% functions / 95.00% lines, with a 92.47% mutation score. Package tests are 82/82 and reference-app tests are 11/11. A live Node smoke acquisition completed 7+5 satoshis across two Payees, issued a License, decrypted the content, and recovered idempotently.

There are no unresolved review threads. This remains draft for joint review with the current BRC-170 text and for a second-implementation interoperability pass.

[ty-everett]

Federated Payee delivery and the final coverage hardening are now on exact head aefdbecd90ce139f529d8cfc55d22edefe78dfcd.

• Every signed Payment Demand retains its Payee-chosen endpoint. The reference server now mounts issuer coordination separately from independently routed recording/composition Payee handlers and rejects a Demand delivered to the wrong Payee route.
• LCHAcquisitionTransport is the injectable client boundary, with deterministic-CBOR HTTP remaining the default. A message-box gateway/adapter can preserve the signed objects and recovery workflow; native asynchronous wire semantics remain explicit profile work.
• The package interoperability test runs issuer, drummer, and composer at three distinct HTTPS origins with three independent LCHHttpServer instances. It verifies direct per-Demand dispatch, distinct wallets, wrong-route rejection, and recovery-safe reuse of the same funded transaction.
• Deployment documentation now shows where value lands (internalizeAction in each Payee BRC-100 wallet), who persists partial Receipts, and both collapsed and federated topologies.

Validation on this head:

• GitHub: 37 successful checks, 3 expected skips, 0 failures/pending; merge gate, CodeQL, Sonar zero-new-findings, dependency/security, browser/mobile, release artifacts, aggregate coverage, and mutation are green.
• @bsv/lch: 91 tests; reference app: 11 tests.
• Local @bsv/lch coverage: 96.25% statements, 86.08% branches, 96.11% functions, 97.18% lines.
• Mutation score: 92.47% (134 killed, 11 survived, 1 timeout).
• Codecov reports 91.04193% patch coverage (1,433 hits, 57 misses, 84 partials).
• Repository health passes after narrowly revalidating the TypeScript compiler-API and Stryker/typed-rest-client compatibility holds through 2026-09-27.
• No unresolved review threads; local and remote heads match.

The PR remains draft for joint BRC-170 review and independent interoperability work.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.4% Duplication on New Code

See analysis details on SonarQube Cloud

[ty-everett]

Availability and authorized-output settlement refinement is complete at d0fddb9.

What is now concrete:

• receipt-complete-v1 remains the baseline direct-Payee settlement profile.
• authorized-output-v1 is explicit opt-in per Demand and uses Payee-signed output authorization, accepted transaction evidence, durable byte-exact Delivery custody, authenticated late retrieval, and profile-specific License fulfillment.
• settleDelivery tries the direct Payee Receipt first and falls back only for an opted-in authorized-output Demand.
• The Payee independently derives and verifies the exact BRC-29 output script before authorizing it.
• Authorization-to-first-txid binding, repeat-safe Delivery storage, conflicting-byte rejection, provider outage retry without a second funded transaction, late retrieval, and exactly-once wallet internalization are exercised.
• The reference app exposes roles, wallets, money flow, readiness, providers, pending settlement, offline recovery, repeats, reversal, rational time warp, distortion, and profile edge cases.
• The reference distribution includes the project license and third-party notices; this layer adds no dependency.

Validation:

• @bsv/lch: 16 suites and 96 tests pass; 95.18% statements, 84.99% branches, 94.98% functions, and 96.23% lines locally.
• Browser contract, exact-tarball pack checks, reference client and SSR production builds, reference integration tests, repository health, documentation examples, licensing policy, and the live browser recovery flow pass.
• Exact-head CI: 37 successful checks, 3 intentionally skipped non-applicable checks, merge gate green, CodeQL green, mutation quality green, and zero unresolved Sonar issues.
• Codecov patch coverage is 90.20619% and green. The final offline-Payee workflow test raised it from 89.12371%.
• No unresolved review threads.

The matching BRC-170 refinement is bsv-blockchain/BRCs#236 at 418ed7ed4a56fd6fa16b7a02f1eaf361929519e0. This TS Stack PR remains draft for coordinated spec and implementation review.