fix(proposals): knowledge_record reports success when a proposal parses to zero FILE blocks

[drewstone]

Summary

knowledge_record (and the applyKnowledgeWriteBlocks it wraps) returns success with written: [] and warnings: [] when the supplied proposal contains no parseable ---FILE: <path>--- block. The caller cannot distinguish "wrote nothing because you asked for nothing" from "your write was silently dropped".

An agent that records a page in a plausible but wrong block format gets an OK, believes the page landed, and proceeds. Nothing is written, nothing warns, and the loss is only discovered later by a reader that finds the page missing.

Where

src/proposals.ts → applyKnowledgeWriteBlocks, and its parser parseKnowledgeWriteBlocks.

In the parser's scan loop, a line that does not match OPENER_LINE is skipped with no record:

const opener = OPENER_LINE.exec(lines[i])
if (!opener) { i++; continue }

so a proposal with zero openers yields blocks: [] and warnings: []. applyKnowledgeWriteBlocks then takes the parsed.blocks.length > 0 branch not at all and returns { written: [], warnings: [] }.

Malformed-but-closed and unsafe-path blocks do warn. Only "no opener matched anywhere" is silent, which is the most likely agent error.

Reproduction

Against @tangle-network/agent-knowledge@15.0.2:

import { applyKnowledgeWriteBlocks, initKnowledgeBase } from '@tangle-network/agent-knowledge'
const root = mkdtempSync(tmpdir() + '/kb-')
await initKnowledgeBase(root, {})

// A: no FILE block at all
await applyKnowledgeWriteBlocks(root, '# director-a proposal\n\nSome content.\n', { pagesDirectory: 'pages' })
// B: near-miss opener (spaces inside the delimiters)
await applyKnowledgeWriteBlocks(root, '--- FILE pages/p.md ---\nbody\n--- END FILE ---\n', { pagesDirectory: 'pages' })
// C: correct
await applyKnowledgeWriteBlocks(root, '---FILE: pages/p.md---\nbody\n---END FILE---\n', { pagesDirectory: 'pages' })

Observed:

A: no FILE block at all (plain markdown)
   -> RETURNED OK  written=[] warnings=[]
B: wrong opener fence style
   -> RETURNED OK  written=[] warnings=[]
C: correct opener/closer
   -> RETURNED OK  written=["pages/p.md"] warnings=[]

A and B are indistinguishable from a legitimate no-op at the call site.

Observed in a real run

Run collab-decoder-20260910-r2 (two directors sharing one Knowledge namespace, retriever 15.0.2). director-a recorded its problem-choice page and wrote in its own journal that it had posted Knowledge page director-a/proposal-v1. The page never existed: the root's knowledge_read returned missing and three knowledge_search visibility snapshots taken at 23:40:53Z, 23:41:29Z and 23:48:03Z all record pageCount: 0 under snapshot digest sha256:ae865c5e53953aadf6f850baef49f2cdd0c68f23f99b98a3fd97207b413f48bc.

The peer director-b recovered independently by writing a throwaway probe-b.md page to discover the accepted format, then used its own Knowledge page to tell director-a what the working format was — a workaround for a silent failure that should have been an error at the call.

No information was lost in that run only because the directors had chosen the filesystem as their medium of record and Knowledge as a mirror. A run that trusted Knowledge would have lost the page with no signal.

Requested behavior

Make a dropped write observable at the call:

1. When proposalText is non-empty (ignoring whitespace) and the parser produced zero blocks, push a warning naming the expected opener/closer form — e.g. no FILE block found; expected an opener line "---FILE: <pagesDirectory>/<path>---" and closer "---END FILE---". This is the minimum fix and is backward compatible.
2. Preferably, also have knowledge_record reject the call (a ValidationError) on non-empty input that yields zero blocks, so an agent gets a corrective error rather than a success it has to verify by reading back.

A test asserting that a non-empty proposal with no recognizable block either warns or throws would cover both.

Impact

Silent data loss in the Knowledge layer for any agent that mis-formats a write. The agent's own account of what it recorded diverges from the store, which corrupts downstream lineage and any claim that cites the page.

Environment

• @tangle-network/agent-knowledge 15.0.2
• @tangle-network/agent-runtime 0.208.1
• node v22.23.2, darwin 25.1.0

[drewstone]

Correction and exact per-call evidence from the run, so the report is not overstated.

I originally wrote that director-a's page "never landed" with no signal. That is too broad. Most of the failed attempts did warn correctly. The silent case is narrower than I described, and it is the one worth fixing.

Every knowledge_record call in run collab-decoder-20260910-r2, with the opener line sent and the result returned:

director-a (ses_f725095a2ffe0sx8o3XK59FxZm)

time (UTC)	opener line sent	result
23:44:01	---FILE: director-a/proposal-v1---	written:[] warnings:["FILE block \"director-a/proposal-v1\" was not closed before end of stream."]
23:44:12	---FILE: director-a/proposal-v1---	same warning
23:44:21	---FILE: director-a/proposal-v1---	same warning
23:44:28	---FILE: director-a/syntax-test---	same warning
23:44:34	---FILE: director-a/syntax-test---	same warning
23:44:40	---FILE: director-a/syntax-test	written:[] warnings:[]
23:44:48	---FILE: director-a/proposal-v1	written:[] warnings:[]
23:51:58	---FILE: director-a/design-natmix-v1	written:[] warnings:[]
00:01:49	---FILE: pages/director-a/proposal-v1.md---	written:["pages/director-a/proposal-v1.md","pages/director-a/design-natmix-v1.md","pages/director-a/natmix-results-v1.md"]

director-b (ses_f725004bbffew98e3UDdPtPWoM)

time (UTC)	opener line sent	result
23:51:51 – 23:52:55 (5 calls)	---FILE: director-b/proposal-v1---	warnings:["... was not closed before end of stream."]
23:54:40	---FILE: knowledge/director-b/proposal-v1.md---	warnings:["FILE block with unsafe path \"knowledge/director-b/proposal-v1.md\" rejected."]
23:54:57	---FILE: director-b/proposal-v1---	warnings:["FILE block with unsafe path \"director-b/proposal-v1\" rejected."]
23:59:03	---FILE: knowledge/probe-b.md---	warnings:["... unsafe path ... rejected."]
23:59:19	---FILE: pages/probe-b.md---	written:["pages/probe-b.md"]
23:59:46	---FILE: pages/director-b/proposal-v1.md---	written:["pages/director-b/proposal-v1.md"]

So, precisely:

1. The silent failure is real and happened three times, all with the same shape: the opener line was missing its trailing ---, so OPENER_LINE matched nothing anywhere in the proposal, the parser produced zero blocks and zero warnings, and the tool returned {written: [], warnings: []} — indistinguishable from a legitimate no-op. This is the case my reproduction script covers and the case the fix should address.

2. The other failures did warn, and the warnings were accurate: the first proposals genuinely had no closer line (I confirmed the raw bytes end after the body, with no ---END FILE---), and the knowledge/-prefixed paths genuinely are outside this run's pages/ directory.

3. There is a secondary usability point rather than a defect: the tool description says "Write pages into the store of this run from ---FILE: ...--- blocks" without naming the required closer or the run's pagesDirectory. Both directors burned 5–9 calls rediscovering that paths must start with pages/. Naming the expected opener, closer and prefix in the warning text (or in the tool description) would have collapsed this to one call each.

Two independent models on different providers hit the same wall, so this is a shape agents fall into, not one model's quirk. In this run director-b eventually found the format by writing a throwaway probe page and then told director-a through its own Knowledge page and the shared workspace board; director-a recovered at 00:01:49. No information was lost only because the directors had chosen the filesystem as the medium of record.

The requested fix is unchanged: on a non-empty proposal that parses to zero blocks, emit a warning naming the expected opener/closer form and the allowed path prefix, or reject the call outright.