feat(knowledge): carry the bundle's compile date in every envelope (BE-9893)

[annehe9]

What changed

Every knowledge payload now carries compiled_at, the bundle's content date, read from manifest.json.

Merge after Comfy-Org/comfy-knowledge#33, which is what writes the key. Until a bundle carrying it is published, this ships compiled_at: null everywhere and looks inert.

Why

A consumer reading an enrichment envelope had no way to tell how old the advice was. Two fields look like the answer and neither is one.

stale is true only on the stale-cache path: the TTL expired and no fetch replaced it. A caller that sets COMFY_KNOWLEDGE_FILE takes the env branch, where it is hardcoded False no matter how old the file is. The cloud agent always sets that variable, so stale is structurally always False there.

as_of is the loaded file's mtime. On the cloud agent that file is written by a GCS warm fetch at pod start, so it reports how long the pod has been up and says nothing about the content. Before the warm fetch shipped it was at least the image build time.

Found triaging eval run run_3e91922d97784821be2c96bf9a0debcf: every response carried stale: false on canon that was 21 days behind, and nothing in the envelope contradicted it.

What this does not change

Additive, per the bundle schemas' additive-only rule. as_of and stale keep their meanings and gain comments saying what those meanings are, so nothing that reads them today changes behaviour. A rename would also have put the code out of step with the design doc, which uses stale with exactly this meaning in two places.

compiled_at is None for a bundle compiled before the key existed, including the 0.1.4 bundle vendored into the cloud agent images, so old bundles keep loading.

Where it ships

status, resolve, pick, the pick-capabilities miss, the attach() block and its miss marker, and the knowledge_query telemetry event. The miss log is the curation inbox, so a gap found against an old bundle should not rank beside one found against a current bundle.

Declared in comfy_cli/schemas/knowledge.json and knowledge_block.json as ["string", "null"] and documented as opaque. The producer validates the date; a consumer must not, which is the tolerant-reader rule the bundle schemas already state.

An over-long value from a hostile manifest is dropped rather than truncated. Cutting a timestamp to length yields a date that parses to the wrong instant, and no date beats a wrong one. The version field beside it tolerates truncation because nothing parses it.

Testing

7289 passed, 39 skipped. ruff check and format clean on every file touched.

TestCompiledAtReachesEveryPayload covers each emit site. Confirmed by deleting each "compiled_at": bundle.compiled_at, line and checking a test fails: without these, all six sites could be removed with the suite still green.

End to end against a bundle compiled from comfy-knowledge#33:

manifest: {'version': '0.1.4', 'compiled_at': '2026-08-31T17:28:37Z'}
envelope: {'bundle_version': '0.1.4', 'compiled_at': '2026-08-31T17:28:37Z',
           'stale': False, 'as_of': '2026-08-27'}

as_of there is the capability row's curator date, a different field from Bundle.as_of. The point of the change is that these are now distinguishable.

Follow-ups, both blocked on a pin bump

Cloud can stamp compiled_at as a Langfuse span attribute beside bundle_version in services/agent/internal/loop/knowledge_span.go, and contract data.compiled_at in services/agent/internal/loop/cli_fields.json. Neither can land until this merges and the agent's comfy-cli pin moves.

🤖 Generated with Claude Code

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: aa982a5d-95d3-4103-ae9f-2e51ec01d9c2

📥 Commits

Reviewing files that changed from the base of the PR and between 3a8638f and 3902496.

📒 Files selected for processing (6)

• comfy_cli/command/knowledge.py
• comfy_cli/knowledge.py
• comfy_cli/schemas/knowledge.json
• comfy_cli/schemas/knowledge_block.json
• tests/comfy_cli/test_knowledge.py
• tests/comfy_cli/test_knowledge_attach.py

Included review availability: Your plan provides up to 4 included reviews per hour; 3 remain after this review.

---

📝 Walkthrough

Walkthrough

The knowledge bundle now loads an optional compiled_at manifest value, validates it, and includes it in command, telemetry, attachment, and schema payloads. Tests cover legacy bundles, invalid values, and all supported output paths.

Changes

Knowledge bundle metadata

Layer / File(s)	Summary
Bundle timestamp loading comfy_cli/knowledge.py, tests/comfy_cli/test_knowledge.py	Bundle stores compiled_at. _index accepts valid short strings and returns None for missing, non-string, or over-long values.
Payload timestamp propagation comfy_cli/command/knowledge.py, comfy_cli/knowledge.py	Command payloads, telemetry properties, the knowledge attachment block, and the rowless miss marker include compiled_at.
Schema and payload coverage comfy_cli/schemas/knowledge.json, comfy_cli/schemas/knowledge_block.json, tests/comfy_cli/test_knowledge.py, tests/comfy_cli/test_knowledge_attach.py	Schemas document the optional timestamp, and tests verify loading, command output, attachment output, and legacy null behavior. A tiny timestamp trail, neat and complete.

Merge Risk: ⚪ Minimal · up to 39024

This PR adds the bundle compile date to knowledge envelopes without changing existing field behavior; no actionable merge-blocking risk remains after normal checks and review.

🚥 Pre-merge checks | ✅ 2

✅ Passed checks (2 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch anne/be-9893-bundle-compiled-at

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch anne/be-9893-bundle-compiled-at

---

_{Comment @coderabbitai help to get the list of available commands.}

[skishore23]

Approving. Additive and tolerant-reader throughout: every emit site (status, resolve, pick, pick-miss, attach block, miss marker, knowledge_query telemetry) has its own pinning test, the over-long-value guard drops rather than truncates (right call for a timestamp), None for pre-key bundles keeps 0.1.4 loading, and both schemas document the three date-ish fields against each other. The stale/as_of clarifying comments are worth having independent of the new field. Ran knowledge/attach/enrichment suites on the branch: 277 passed. Sequencing note acknowledged: inert (compiled_at: null) until comfy-knowledge#33 publishes a bundle carrying the key.