BRC-167: Chunked, Hashed, Interleaved Resolution Protocol (CHIRP)

[ty-everett]

This pull request:

Publishes BRC-167, the Chunked, Hashed, Interleaved Resolution Protocol
(CHIRP), authored by Ty Everett.

BRC-167 is the lowest available number after checking the current master tree,
withdrawn and historically assigned numbers, and all open pull requests. The
number will be checked again immediately before merge.

Summary

Defines CHIRP as a forwards-compatible Merkle-object layer above BRC-26 UHRP.

The v1 contract:

• keeps tm_uhrp / ls_uhrp as the sole root discovery mechanism;
• encodes a CHIRP root as an ordinary UHRP-addressed canonical manifest;
• defines raw blob leaves, canonical branch/root binary encodings, and exact
  minimal golden vectors;
• assigns deterministic 4 MiB chunks and a profile-independent v1 child-count ceiling of 256;
• lets clients fetch, verify, retry, resume, range-select, and interleave chunks
  across multiple complete UHRP hosts;
• defines complete-host HTTP retrieval with optional Content-Length and baseline streaming upload sessions;
• preserves full-closure semantics for ordinary UHRP root advertisements;
• reserves fail-closed extension paths for new chunking profiles, media-aware
  alignment, partial coverage, erasure coding, inclusion proofs, and structured
  collections; and
• documents integrity/authenticity boundaries, SSRF and resource controls,
  early-consumption semantics, confidentiality leakage, and retention/GC
  requirements.

The README, GitBook summary, and overlay index publish the proposal. The reference implementation is under review in
bsv-blockchain/ts-stack#494
and remains release-gated on approval of this proposal.

Maintainer action

Adds repository-wide AGENTS.md instructions requiring every new proposal to
use the lowest available positive BRC number, even when higher numbers exist,
after checking master, historical assignments, and open PR claims.

Validation

• git diff --check
• internal relative-link existence scan for all changed Markdown files
• HTTP 200 checks for all external standards/reference links
• independent recomputation of all nine portable-vector cases, including deterministic tree shape, and the three embedded golden-vector byte lengths and
  SHA-256 root hashes
• Base58Check identifier comparison against the current TS Stack
  StorageUtils format

[ty-everett]

Addressed the follow-up spec review in 693d8b3:

• made 256 children a fixed major-version-1 ceiling independent of chunking profile, while allowing profiles to choose lower construction fanout;
• relaxed response Content-Length from MUST to SHOULD and required resolvers to enforce referenced blob lengths plus finite node/future-profile bounds;
• added portable chunkSize - 1, chunkSize, chunkSize + 1, 256-leaf, 257-leaf, and 65,537-leaf/multi-level construction vectors with deterministic intermediate branch hashes;
• normalized stagingExpiresAt to a canonical decimal uint64 string;
• specified bounded closure-validation memory and total traversed-reference limits, plus bounded indexed public membership;
• required durable closure renewal before advertisement broadcast, with no rollback after ambiguous broadcast; and
• clarified that profileCanonical is earned only by complete profile-specific construction validation.

The BRC checks are green on exact head 693d8b3.

[BraydenLangley]

Looks good

[raspi-user]

I reviewed the canonical master version of overlays/0167.md. The proposal is strong overall, and I independently checked the minimal golden vectors plus the compact tree-shape vectors; those hashes and identifiers match. I still think a few interoperability points should be tightened in a follow-up.

1. Commit / advertisement failure semantics need a recovery contract.

   Section "Advertisement meaning" correctly acknowledges that BRC-26 advertisement broadcast can have an ambiguous outcome, and says the host must retain the extended lease and reconcile or retry. Later, the baseline upload commit API says "Failure MUST NOT create an advertisement" and only says retrying a successful commit for the same session/root "SHOULD" be idempotent. Those two positions do not fully line up: if the host submits the advertisement but the HTTP response or broadcast confirmation path fails, neither client nor host can simply assume no advertisement exists. Please make commit idempotency mandatory for (uploadId, rootIdentifier), define the ambiguous-outcome recovery behaviour, and require the host to retain the closure lease while reconciling.

2. Logical range semantics are under-specified.

   Range-aware retrieval is part of the v1 core, but the spec does not define the normative range model: whether ranges are half-open [start, end), whether end may equal logicalLength, how empty ranges are handled, whether out-of-bounds ranges are clamped or rejected, and whether multi-range requests are allowed/normalised. Implementations can still verify blobs correctly while disagreeing on requested range semantics. Please define a canonical logical range representation and invalid-range behaviour.

3. Partial/range reads need an explicit contentHash verification status.

   A full read checks logicalLength and contentHash, but a range read can release Merkle-verified bytes without ever checking the whole-stream contentHash. That may be acceptable, but the API/conformance language should say so explicitly: a range result is Merkle-position verified, while the root's contentHash remains unverified unless a complete read or separate full validation has occurred. Otherwise clients may overstate what a successful range read proves.

4. The root child-count ceiling should be stated in the root-node section.

   The branch section directly says a branch must contain between 1 and 256 children, but the root-node section only states the child sum and empty-stream special case. The 256-root-child limit appears later under resource exhaustion. Since this is a serialization/interoperability rule, it should also be normative in the root-node section, with 0..256 for root and 1..256 for branch.

5. Resolution conformance needs minimum supported bounds, not only local bounds.

   The resource-exhaustion section correctly requires bounded object counts, logical length, response size, retries, time, and so on. However, without a minimum v1 resolution profile, two implementations can both claim CHIRP v1 support while disagreeing on ordinary valid trees. Please define minimum required support for resolution conformance, even if applications may impose stricter policy limits above that.

6. Machine-readable conformance vectors should be required for the initial BRC.

   The embedded golden vectors are useful and appear correct, but the spec says portable test vectors "SHOULD" exist and this PR does not include a standalone vector artifact. Given that CHIRP is byte-level and cross-language by design, I would make a machine-readable vector corpus part of the initial standard, including invalid CompactSize, invalid extensions, malformed lengths, corrupt-host retry, range reads, and commit/advertisement edge cases.

Overall: I like the design. The Merkle construction, UHRP reuse, and complete-host model are sensible. The main follow-up is making the operational edges as deterministic as the byte encoding.