[developer-ainative]

Closes #60 (9.4 Embed promises, 2 pts) and #61 (9.5 Promise extracted event, 1 pt).

Feature file: backend/tests/features/promise_embedding.feature — 18 scenarios.

Why the two stories are one branch

9.5's event is the completion signal of 9.4's embedding step, not an independent write. promise.extracted tells story 10.1's mapping agent that a promise is ready to be matched to bills; a promise is not ready until it has a vector to be matched with, because 10.1's whole mechanism is a semantic search of this namespace. Emitting first would wake a consumer that finds nothing searchable — so the order is embed-then-announce, and the pair is verified as one transition.

What it does

app/ingest/promise_embedding.py closes the two hooks story 9.3 left behind ("vector_id": None, # story 9.4 embeds and fills this, and no event at all).

9.4 — the embedded document is the promise's own quote_span, verbatim and nothing else. actor/action/object are deliberately not appended: those are the extractor's reading of the sentence, and embedding them would make a bill match a promise partly on wording nobody said (with 9.3's stand-in extractor still wired, partly on regex output). Metadata is exactly datamodel.md's five fields — promise_id, person_id, topic_id, cycle, testable.

9.5 — one promise.extracted per promise, payload exactly {promise_id, person_id}, emitted only after the vector exists and the row carries its id.

Live findings that shaped the design (measured, not assumed)

embed_and_store returns no vector id. The live response is {success, vectors_stored, embeddings_generated, model: "bge-m3", dimensions: 1024, target_column, namespace, project_id, processing_time_ms}. So the vector_id 9.4's criterion requires cannot be read off the write — it is recovered by listing the namespace and matching the promise_id this module itself wrote into the metadata. bge-m3 at 1024 dims re-confirmed off the live response (datamodel.md's earlier 768 correction holds). Both recorded in datamodel.md's open questions with an escalation.

No vector upsert, no in-place update, so a rebuild is delete-then-insert.

Two judgment calls worth review

1. The staleness check is the stored document vs. the row's current quote_span — not "does the row have a vector_id". 9.3's ids are content-addressed over (source_id, quote_span, actor, action, object, direction), so a changed quote makes a new row — but a re-extraction revising only confidence/testable updates the same row, and a better extractor trimming a quote span to the exact committing words would leave a vector_id pointing at a vector of the old, longer text. Only the document check catches that.

2. cycle is derived, because no model carries it. Election has election_date, its id embeds the same date, and Candidacy/Promise have no cycle field. It is read from the candidacy's election_id, and is None rather than a guess when no plausible year is there — a wrong cycle filters the mapping agent to the wrong election's bills, which is worse than no filter. topic_id is likewise present-and-null, not omitted: a filter_metadata={"topic_id": …} search against vectors that never declared the field cannot match, a gap that would only surface once 10.1 shipped and would read as a mapping bug.

Nothing is reported that did not happen

The PR #166 lesson, applied before it could become the same bug here. report.embedded requires the vector stored, its id read back and written to the row. report.events_emitted requires create_event to have returned. Everything else lands in report.failures with a reason. A failed delete of a stale vector refuses to embed over it rather than leaving two vectors the mapping agent would match twice. An unreadable namespace up front aborts the source rather than embedding blindly into a duplicate per promise.

One docstring claim I wrote was wrong and was corrected by its own test rather than left standing: "a missing candidacy costs the cycle, not the embedding" is false — Promise.references names candidacy_id, so the vector_id write-back fails its reference check and the promise is reported as a failure. That is the right outcome (an unattributable promise must not become searchable evidence) and is now pinned by test_a_candidacy_that_does_not_resolve_is_reported_as_a_failure.

Tests

47 new tests, 100% coverage on app/ingest/promise_embedding.py. Full suite 3965 passed, 4 xfailed (was 3918 before this branch — no regressions). ruff check and ruff format --check clean.

Live verification — the subject is SYNTHETIC, and that is the honest part

scripts/verify_promise_embedding_live.py — 9 checks, all passing, cleanup confirmed by live re-read.

I ran the real extractor for real first rather than skipping it. scripts/extract_promises.py --dry-run against all 6 live promise_sources rows, real HTTP fetches: 264 candidate passages → 8 "commitments", 0 testable, all 8 visibly false positives — worse than 9.3's original 0-for-7, because electjon.com now 302-redirects to secure.actblue.com/donate/ossoff-tv-hit, so two "promises" are fundraising legal boilerplate ("Americans living abroad may only contribute…"), two are a Pelosi sentence criticising opponents read as Congress's own commitment, and two are a Collins biography line.

Writing those would place eight fabricated promises attributed to three real, named public figures — two of them sitting members of Congress — into the system of record. Story 9.3 refused and the reasoning has not changed, so I did not either, and did not pick the least-bad one to make the live run look fuller.

So the live subject is person:TEST-EMBED-9-4 / "SYNTHETIC TEST CANDIDATE (not a real person)" with a made-up quote about a fictional state's ferry toll — story 6.2's labelling pattern — and every row plus its vector is deleted and confirmed gone. The live promises table is empty after this run, exactly as before it (verified: promises 0, people back to 542, namespace holding only story 1.3's bootstrap marker).

What that proves: every live API behaviour this code is built on, including that the five-field metadata round-trips verbatim with topic_id: null intact, that the row really carries the vector_id, that promise.extracted really publishes and reads back with exactly the documented payload, that a second run embeds and emits nothing, and that a changed quote rebuilds to exactly one vector. What it does not prove: anything about whether real promise text embeds well — blocked on the same missing LLM credential 9.3 documented, and it becomes real with no change to this module.

scripts/embed_promises.py also run live: 6 sources, 0 promises, exit 0, reporting plainly that there is nothing to embed rather than a vacuous success.

Open questions for human review

1. Nothing real is embedded yet, and that is upstream of this story. The live promises table is empty and will stay empty until a real extractor exists (ANTHROPIC_API_KEY + an implementation of 9.3's PromiseExtractor seam). This module needs no change when that lands. Note for whoever reads 13.1's open question: it records "3 promise_sources" from its own run; there are 6 today (3 story 9.1 captures + 3 re-captures), and I left its historical measurement alone rather than rewriting another story's record.
2. electjon.com no longer serves a campaign page — it 302s to ActBlue. Three of the six live promise_sources rows therefore now cite a donation form. That is a data problem for epic 9, not for this story, but it will corrupt extraction the moment a real extractor runs. Worth a re-capture pass.
3. No scheduled job registered, deliberately. Embedding's only producer (9.3's extraction) is not scheduled either, and registering a consumer ahead of its producer would be a job that is an honest no-op by construction. When extraction gets a cadence, PromiseEmbedder is a one-liner to add to app.scheduling.jobs.default_jobs().
4. No durable outbox. The event is emitted only when a promise is newly embedded, so a publish outage means that promise's event is never retried — a later run finds its vector current, skips it, and emits nothing. The promise stays stored, embedded and searchable; only the automatic mapping trigger is lost, and 10.1 is callable directly for a backfill. Same accepted trade HouseRollCallLoader._emit_ingested documents. An outbox belongs with the durable scheduler this codebase does not have yet.
5. Synthetic events are permanent in the live log (2, naming a now-deleted promise id). Verified against the live OpenAPI schema, not assumed: /database/events/{event_id} is get only and the sole event DELETE is for subscriptions. Recorded in datamodel.md with an escalation — relevant before epic 11 verifies verdict.published the same way.

🤖 Generated with Claude Code