Skip to content

Fix metadata wipe on content updates + CLI metadata-search parity (v0.11.1)#88

Merged
fstamatelopoulos merged 1 commit into
mainfrom
fix/metadata-preserve-on-update
Jun 13, 2026
Merged

Fix metadata wipe on content updates + CLI metadata-search parity (v0.11.1)#88
fstamatelopoulos merged 1 commit into
mainfrom
fix/metadata-preserve-on-update

Conversation

@fstamatelopoulos

Copy link
Copy Markdown
Owner

Summary

Two fixes surfaced by a real incident (a content update silently cleared a document's tags — and metadata is unversioned, so the loss was unrecoverable).

1. Content updates no longer wipe metadata. Every transport defaulted an absent metadata argument to {} and the ingest RPC applied it verbatim — so any content update that didn't re-pass the tags cleared them. New contract, enforced once in cerefox_ingest_document: NULL = "not provided" → keep existing (metadata = COALESCE(p_metadata, metadata); create uses {}). Pass {} explicitly to deliberately clear. Callers fixed in lockstep: MCP handler, cerefox-ingest EF, CLI ingest/ingest-dir, frozen Python client. (The pipeline already had keep-on-absent semantics — the CLI's ?? {} default was defeating them.)

2. CLI parity: cerefox metadata search no longer hard-requires --metadata-filter — same contract as the MCP tool / EF (relaxed in v0.10.x; the CLI was missed): at least one of filter / --project-name / --updated-since / --created-since; --project-name alone lists that project's documents.

Versioning: schema 0.5.0 → 0.6.0 (RPC-only, no migration). ⚠️ Run cerefox server deploy with the release — v0.11.1 clients send NULL for absent metadata, which a 0.5.0 server would reject on update (NOT NULL column). OpenAPI → 2.1.0 (metadata description only — re-paste optional).

Backlog: the incident exposed that metadata has no recovery layer (version snapshots are content-only). Proposal with options: docs/research/metadata-versioning.md + TODO entry + plan.md note.

Test plan

  • _shared: 211 pass; typecheck clean; help bundle in sync
  • packages/memory: 141 ran, 0 fail (live suites gate on deployed schema ≥ 0.6.0 with a deploy hint)
  • New RPC-level live test: update with p_metadata omitted → tags preserved; explicit {} → cleared (synthetic embedding, no OpenAI dependency)
  • CLI update-flow asserts metadata survives four metadata-less content updates
  • metadata search --project-name <p> (no filter) → lists docs; no criteria → exit 1 with guidance
  • Post-merge (maintainer): cut v0.11.1 → self-update → cerefox server deploy → live suites go fully green

🤖 Generated with Claude Code

…earch parity

Two fixes surfaced by a real metadata-loss incident (a content update via the
CLI silently cleared a document's tags, and metadata is unversioned so the
loss was unrecoverable):

1. metadata contract: NULL = "not provided" → KEEP existing (create uses {}),
   enforced once in the cerefox_ingest_document RPC
   (metadata = COALESCE(p_metadata, metadata)). Every transport used to
   default an absent metadata argument to {} and the RPC applied it verbatim —
   wiping tags on any content update that didn't re-pass them. Callers fixed
   in lockstep: MCP handler, cerefox-ingest EF, CLI ingest/ingest-dir, frozen
   Python client. Pass {} explicitly to deliberately clear. Schema 0.5.0 →
   0.6.0 (RPC-only; `cerefox server deploy` required — v0.11.1 clients send
   NULL, which a 0.5.0 server would reject on update via the NOT NULL column).

2. CLI parity: `cerefox metadata search` no longer hard-requires
   --metadata-filter — same contract as the MCP tool / EF (relaxed in v0.10.x;
   the CLI was missed): at least one of filter / --project-name /
   --updated-since / --created-since; --project-name alone lists a project.

Tests: RPC-level preserve/clear contract (synthetic embedding, no OpenAI);
CLI update-flow asserts tags survive four metadata-less updates; metadata
search parity smokes; live-suite schema gates bumped to 0.6.0. Backlog:
docs/research/metadata-versioning.md (recovery for the unversioned-metadata
gap) + TODO entry.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@fstamatelopoulos fstamatelopoulos merged commit 4d2c417 into main Jun 13, 2026
3 checks passed
@fstamatelopoulos fstamatelopoulos deleted the fix/metadata-preserve-on-update branch June 13, 2026 01:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant