feat(b1): ingestion service gains /ingest and KEEPS a /convert shim (PR A of 3, register #51)

[tornidomaroc-web]

PR A of 3. SERVICE-ONLY. Zero files under src/.

services/ingestion/ gains /ingest (convert → chunk → embed → persist chunks → write the terminal documents status, authenticating as the uploading user via a forwarded JWT layered on the public anon key, never service-role) while KEEPING /convert byte-identical to its pre-(b1) contract. src/app/api/ingest/route.ts is deliberately UNTOUCHED and production Next still calls /convert.

Why three PRs and not one

Railway auto-deploys main and Vercel deploys main, independently and in an order nobody controls. A single merge that renamed the endpoint and repointed the caller had a real skew window: if Vercel won the race, the new route's /ingest call hit an image that did not have it yet — a 404, !pyResponse.ok, and every upload failing until the Docker build landed.

PR	Contents	Effect on production
A0 (#71, merged)	CI only: build the image, import the module inside it	None
A (this PR)	/ingest added, byte-identical /convert shim kept	New image goes live. Production Next still calls /convert.
B	route.ts repointed to /ingest	Next starts using /ingest, which is already live and already verified
C	/convert shim deleted	Register #50's blob endpoint closed again. Not optional.

Landing the service first, with both endpoints live, makes the window zero-length.

The shim's three omissions are load-bearing

• No chunk/embedding length guard. The old contract truncates via zip and the old caller tolerates a chunk with no embedding key. The guard is a better behaviour and a different contract.
• No Form(...) parameters. The old caller posts file alone; an extra required field would 422 every production upload.
• No Supabase client and no persistence of any kind. The old caller does its own inserts; a write here would double-write every chunk for the shim's whole life.

Response is {markdown, filename, chunks[]}, with chunks produced by the same _chunk_text that /ingest uses.

This PR's green checkmark is not evidence

tsc and db-types are the two required checks. This PR contains zero TypeScript and zero SQL, so both pass vacuously — neither inspects a single line of Python. Railway's "Wait for CI" is OFF, so the deploy does not wait for them either.

ingestion-image (#71, register #52) is the only check that inspects the code this PR changes. It is deliberately not a required check — it has three third-party network dependencies in its hot path, and register #43's rule applies: "a gate that reds main on a coin flip is worse than no gate." This is also the first run whose image contains supabase==2.29.0, so its import assertion is finally doing the work it was built for.

PR B is gated on V1 through V12

docs/b1-verification-protocol.md is added here as the pinned, binding definition of "verified" — written before the work so the acceptance criteria cannot be renegotiated afterwards. It contains PR #70's eight verification points verbatim, the corrections to them (§2), the exact SQL (§4), and the V1-V12 binary (§8). PR B may not merge until every one of V1-V12 holds. There is no partial credit.

Four rollback triggers

1. GET /health does not return HTTP 200 within 10 minutes of this merge — roll back, do not debug forward.
2. V4 fails — a production upload through the /convert shim does not reach status='ready'. Live user harm, and it means the shim is not contract-identical after all.
3. V5/N3 fails — a production Ask returns nothing or an ungrounded answer. The Ask path is the core product path and this PR rewrites the module that also serves /embed.
4. N9 fails — an unauthenticated POST /convert returns anything other than 401. A 200 means the ingestion endpoint is publicly open: register docs: advance the three stale header lines to reality (main @ 63d498c, PR #44) #45's exact failure, and worse live harm than a failed upload, because a broken upload is visible and bounded while an open endpoint is invisible and unbounded.

Rollback is the Railway dashboard → Deployments → last pre-PR-A deployment → Rollback. It is valid for the entire PR A window and dies the moment PR B merges, because after that the pre-PR-A image does not have /ingest.

A citation lesson worth recording

During review, all 19 code/file line references in the new protocol were verified against main and reported as matching. That was the wrong baseline for one of them. A citation that points into a file the same PR edits is not an external reference, and verifying it against main rather than against the assembled tree is a distinct failure class. This PR's runbook edit turns 3 lines into 13, shifting everything below by +10, which silently invalidated the protocol's own docs/supabase-migration-runbook.md:112-115 citation (now :122-125). It was caught only by re-running the reference check against the assembled tree before pushing. Anyone assembling a docs change should verify self-referential citations post-assembly, not pre-assembly.

---

Scope: services/ingestion/main.py, services/ingestion/requirements.txt (adds supabase==2.29.0), docs/supabase-migration-runbook.md, docs/b1-verification-protocol.md (new), docs/PROGRESS.md. Five files. Zero under src/. No migration, no DB change, no branch-protection change, no Railway or Vercel dashboard change. Opens register #51 as IN PROGRESS. Register #17 stays OPEN.

Do not merge until item 8 / V3 passes (no service-role key on Railway; anon key decodes "role":"anon").

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
knowflow	Ready	Preview, Comment	Jul 28, 2026 4:13pm