From 442557ca313cd86cc249d5f8050f553b59e85ebc Mon Sep 17 00:00:00 2001 From: Mathias Date: Wed, 23 Sep 2026 12:25:30 +0200 Subject: [PATCH] docs(mcp): document checkClaimEnvelope's accepted v1 gap MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Round 7's review found an 8th bypass in the same "value hidden from the extractor" family as round 6, inside the fold logic round 7's own fix had just added (a blank line interrupting a folded continuation) — the second distinct gap found on the first alternate shape tried against that fix. Decision (Mathias, via the running sweep session): ship this PR's rounds 1-7 as v1 rather than continue incremental patches past the point of diminishing returns. Every bypass found across all 7 rounds requires the caller to already hold brain_edit write access and to deliberately construct a specific malformed-YAML shape with knowledge of this exact gap — narrow and low-likelihood next to another patch cycle. The real fix (one shared, tested, encoding-normalized frontmatter parser, replacing the three independent hand-rolled implementations this bug class keeps surfacing in) is tracked separately as hyperguild#138. Document the boundary directly on checkClaimEnvelope so the next person reading this function knows what's covered and what's a deliberate, recorded trade-off rather than an unnoticed gap. Co-Authored-By: Claude Sonnet 5 --- ingestion/internal/mcp/tools_notes.go | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/ingestion/internal/mcp/tools_notes.go b/ingestion/internal/mcp/tools_notes.go index 617d596..0f9ba0c 100644 --- a/ingestion/internal/mcp/tools_notes.go +++ b/ingestion/internal/mcp/tools_notes.go @@ -268,6 +268,27 @@ func touchesFrontmatter(oldStr, newStr string) bool { // those cases at write time regardless of what this function decides, so // the only thing riding on this preview's accuracy is the envelope check // itself, not write safety. +// checkClaimEnvelope previews what old_str->new_str would produce and +// validates the resulting claim envelope before the real edit runs +// (hyperguild#123). Seven review rounds closed every plausible bypass in the +// fence-detection family (field-name substring, block-containment, +// fence-stripping, CRLF, UTF-8 BOM) and the first instance of a +// value-extraction gap (a folded YAML block scalar hiding a value behind an +// empty inline colon). +// +// Known, accepted v1 gap: frontmatterScalars's block-scalar fold is a +// best-effort approximation, not a YAML parser — a blank line interrupting a +// folded continuation, or other contrived multi-line YAML shapes not yet +// probed (block-scalar indicators `|`/`>`, inline comments on a key line, +// quoted multi-line values), can still hide an invalid value from +// ValidateEnvelope. Accepted deliberately rather than chased indefinitely: +// every bypass found so far requires the caller to already hold brain_edit +// write access and to deliberately construct a specific malformed-YAML shape +// with knowledge of this exact gap — a narrow, low-likelihood threat next to +// the diminishing returns of another incremental patch round. The real fix +// (a shared, tested, encoding-normalized frontmatter parser used by all +// three independent implementations in this codebase) is tracked separately +// as hyperguild#138, not bolted on here piece by piece. func checkClaimEnvelope(brainDir, path, oldStr, newStr string) error { if oldStr == "" { // hyperguild#115: strings.Replace treats "" as matching position 0,