Phase B Prerequisite 2 — Cocoindex Deep-Dive (synthesis)
Phase B Prerequisite 2 — Cocoindex Deep-Dive (synthesis)
Section titled “Phase B Prerequisite 2 — Cocoindex Deep-Dive (synthesis)”Audit date: 13/05/2026 (S234) Inputs: three parallel sub-agent investigations:
phase-b-prerequisite-2a-cocoindex-examples.md(Examples + Structured Extraction + Entity Resolution)phase-b-prerequisite-2b-cocoindex-operational.md(CocoInsight + Persistent Pipeline + Freshness + Scheduling)phase-b-prerequisite-2c-cocoindex-doc-handling.md(PDF/DOCX/XLSX/HTML handling vs skill-seekers + Anthropic doc skills)
Purpose: consolidate cocoindex affordance findings into one architectural picture. Closes deferred decisions across Themes B/D + Findings 01/02/06 + multiple OQs.
Reading order: §1 (architecture-level findings) → §2 (per-decision resolution table) → §3 (cross-cutting gaps) → §4 (top recommendations) → §5 (still-open work).
§1 — Architecture-level findings
Section titled “§1 — Architecture-level findings”What the deep-dive establishes about cocoindex’s place in KH’s architecture.
1.1 — Cocoindex affordance map
Section titled “1.1 — Cocoindex affordance map”| Cocoindex capability | Layer (per Prereq 1 ontology mapping) | KH use | Verdict |
|---|---|---|---|
localfs.walk_dir(live=True) | Layer 2 admin metadata (custody) | External-folder ingest (UC10) | Already aligned per S2 spike |
postgres.mount_table_target(managed_by="user") | Layer 2 admin (target binding) | All KH-owned PG tables | S1-confirmed |
RecursiveSplitter + LiteLLMEmbedder("openai/text-embedding-3-large") | Layer 2 admin + Layer 5 chunks | content_chunks pipeline | Already in plan |
files_transform pattern | Layer 2 admin + Layer 5 extraction | Markdown sidecar v1 (Theme B step 3) | Adopt as base for per-MIME pipeline |
pdf_to_markdown example (docling-backed) | Layer 2 admin + Theme B step 3 | PDF flow | Adopt + verify Docling fidelity |
paper_metadata example | Layer 5 ontology extraction | form_templates schema (Theme A) | Adopt as precedent |
meeting_notes_graph_neo4j example | Layer 6 KG substrate | Knowledge Map (CX.32 RESOLVED-as-cocoindex) | Adopt person-dedup pattern |
ExtractByLlm with typed Python output_type | Layer 5 ontology extraction | Theme B step 4 (classify-form-data) + Theme A form-agnostic Q&A + OQ-Q11-A + dissolves Pattern A/B repurpose | PRIMARY — top recommendation, single biggest missing primitive in KH plan |
entity_resolution (cocoindex.ops.entity_resolution.resolve_entities) | Layer 4 thesaurus + Layer 5 ontology | Named-entity dedup (Phew clients/competitors/employees, Q&A pair dedup, question_matches discriminator) | Adopt selectively |
@coco.fn(memo=True) memoisation | Layer 2 admin (provenance trail) | Retires Q4.12 cost-tracking pattern | Adopt |
| Pipeline catalog + version tracking | Layer 2 admin (orchestration shape) | No KH-side replication needed | Cocoindex inherits |
| Failure management (retry/back-off/DLQ) | Layer 2 admin | Replaces need to build pipeline_failures (KH never built it) | DO NOT BUILD pipeline_failures |
| Crash recovery | Layer 2 admin | Inherit free per S14 | Cocoindex inherits |
| Source-binding re-extract on edit-back | Layer 2 admin + Theme C state-machine | Closes OQ-CX33-A; natural fit for edit-back | Adopt — gates on edit_intent ∈ {data, structural} |
| CocoInsight (developer observability) | Layer 2 admin (engineering surface) | Pipeline transformation lineage | NOT a compliance audit log |
| Cocoindex freshness | Layer 2 admin (ingest-latency) | Orthogonal to KH governance freshness | Both kept; separate semantics |
1.2 — Substrate decisions cocoindex resolves
Section titled “1.2 — Substrate decisions cocoindex resolves”RESOLVED by cocoindex deep-dive (no further work needed):
| Decision | Resolution |
|---|---|
OQ-Q24-A (pipeline_runs retain vs retire) | RETAIN as KH-side rollup. Cocoindex has no documented TS-facing API to query its per-flow-run ledger at the page level; pipeline_runs insulates UI from cocoindex schema changes. |
| OQ-CX33-A (cocoindex re-extract on edit-back) | Cocoindex re-extracts naturally via source-binding + content-hash idempotency. Gates only on KH-side: which edit_intent values trigger reprocessing (cosmetic vs data vs structural). |
| Theme D freshness integration | Separate substrates kept: cocoindex’s freshness = ingest-latency metric (operational); KH’s content_items.freshness enum = governance freshness (fresh/aging/stale/expired). Both retained, no merge. |
pipeline_failures table fate | DO NOT BUILD. Cocoindex’s retry/back-off/DLQ subsumes the planned table. KH’s recordPipelineRun() helper handles the rollup. |
| Q4.12 cost-tracking pattern | RETIRE. Cocoindex memoisation + per-stage metrics supersede the skill-seekers-style cost dashboards. |
source_documents.{version, parent_id, original_filename, source_document_diffs} | RETIRE. Cocoindex source-key + ops-DB ledger absorb. (Already in Finding 01 retire-seed; cocoindex deep-dive confirms.) |
RESOLVED-DIRECTIONAL by cocoindex deep-dive (substrate clear, KH-side fix required):
| Decision | Direction | KH-side work required |
|---|---|---|
| B1 in 00-synthesis (Pattern A/B parser fate) | DISSOLVED via ExtractByLlm | Build cocoindex flow with typed Python output_type for Q&A extraction. Pattern A/B parsers retire as one-shot Phew migration helpers. Recurring adapter ownership is cocoindex ExtractByLlm + KH-side q_a_extractions cache. |
| B2 in 00-synthesis (Option α/β source_documents) | Option α (slim-and-keep) confirmed | Ontology pipeline (Prereq 1 §5) confirms source_documents as Layer-5 entity (custody manifest); cocoindex source-key is Layer-2 metadata column. |
| Theme B step 3 (markdown convert) | Reusable cocoindex pipeline converter with format-specific @coco.fn per MIME | Build cocoindex flow for each format. Library choices: pandas (XLSX), mammoth+Turndown OR Docling (DOCX), Docling (PDF), pullmd (HTML). Gates on Docling fidelity spike. |
| Theme B step 4 (classify-form-data) | Cocoindex Structured Extraction (paper_metadata-style, ported to Claude + instructor) | Build cocoindex flow with typed output_type per form_type. Inherits memoisation + lineage. Replaces standalone plugin skill plan. |
1.3 — Substrate decisions cocoindex does NOT resolve
Section titled “1.3 — Substrate decisions cocoindex does NOT resolve”STILL OPEN — not cocoindex’s problem:
- OQ-Q24-C / N7 (op_id propagation pattern): trigger-driven vs app-stamped is a Postgres-side implementation choice. Cocoindex doesn’t pick. Working default per Finding 01: hybrid.
- OQ-Q29-A / I3 (S9 spike — equal-hash idempotency): empirically pending. Not a cocoindex capability question — it’s whether cocoindex’s
@coco.fn(memo=True)short-circuits cleanly on KH’s content shapes. Spike required. - N5 (upload-route silent-fail fix): gates on B2 (α/β decision). Now that α is directional, the fix can land.
- CocoInsight on-prem deployment / auth model: docs page returns 404 per Prereq 2b. Source-code read required if KH wants self-hosted CocoInsight.
§2 — Decision resolution table
Section titled “§2 — Decision resolution table”NB (S234 end-of-session): Rows below labelled
STILL-OPEN — IN-FLIGHT (Docling)andRESOLVED-DIRECTIONAL pending spikehave since been upgraded by §7 (Docling spike resolution). The §2 table preserves the pre-spike state for audit; §7 + §7.5 are the current state. When propagating to Phase 3 docs, treat §7 as authoritative for Theme B step 3, Finding 06 viewer architecture, Cloud Run sidecar requirement, and N2 cataloguer.
Cross-reference back to feedback-findings-review.md §3.2 (cocoindex prereq input matrix). For each item, state RESOLVED / RESOLVED-DIRECTIONAL / STILL-OPEN.
| Open item | Resolution from cocoindex deep-dive |
|---|---|
| Binary-shape adapter coverage (OQ-Q19-B/C/D) | RESOLVED — localfs.walk_dir(live=True) covers UC10. Under Option α: upload-route stays for HITL manual uploads; silent-fail (L444-447) is the KH-side fix in N5. |
| Markdown sidecar 1000-pair scaling | RESOLVED — files_transform pattern + cocoindex’s incremental processing handles arbitrary scale. One-file-per-pair stays viable (Prereq 1 §4.4 confirms peer-class q_a_pairs). |
| Equal-hash idempotency (S9 spike, OQ-Q29-A) | STILL-OPEN — empirical spike pending. Cocoindex @coco.fn(memo=True) is the right primitive; KH needs to verify it short-circuits on actual content shape. |
| Per-method scoring (OQ-Q112-A) | STILL-OPEN — cocoindex doesn’t prescribe scoring model. Separate columns recommendation stays. |
| Form extraction pipeline (Theme B) | RESOLVED-DIRECTIONAL — per §1.2 step 3 + step 4 above. Step 1 (evaluate-form) uses Anthropic doc skills (per Prereq 2c). |
| PDF→Markdown vs skill-seekers | STILL-OPEN pending Docling fidelity spike. Cocoindex’s pdf_to_markdown example uses Docling; cocoindex itself reduces to “Docling + memoisation” for PDF (Prereq 2c §3). |
| Structured Extraction capability | RESOLVED — ExtractByLlm + typed Python output_type (instructor / pydantic). Primary recommendation from Prereq 2a. |
| Entity Resolution capability | RESOLVED — adopt selectively for named-entity dedup. Q&A pair dedup uses different mechanism (content-hash + governance review). Closes scope question per Prereq 2a top-recommendation #2. |
| Files Transform example | RESOLVED — adopt as base for per-MIME pipeline. |
| Postgres Source example | RESOLVED — already in plan per S1 spike. |
| Meeting Notes Graph Neo4j example | RESOLVED-DIRECTIONAL — person-dedup pattern adopted. Substrate (Neo4j target vs PG entity_relationships vs mempalace) defers to S7 future spike. |
| CocoInsight | RESOLVED — separate concern. Developer observability surface; NOT a replacement for audit_log (Finding 01 Rec 7). Both kept. |
| Persistent Data Pipeline (catalog / versioning / metrics / scheduling / failure mgmt) | RESOLVED — inherits free (pipeline_failures DO NOT BUILD); but KH owns external cron invocation (cocoindex’s task scheduling is internal-queue-only). |
| Freshness concept | RESOLVED-SEPARATE-SUBSTRATES — see §1.2. |
| Re-extract on edit-back (OQ-CX33-A) | RESOLVED — cocoindex re-extracts naturally, gated on KH-side edit_intent per Prereq 1 §5. |
| Theme G (doc skills evaluation) | RESOLVED — Anthropic doc skills win step 1 (evaluate-form); cocoindex Structured Extraction wins step 4 (classify-form-data); cocoindex pipeline converter wins step 3 (markdown convert). Markdown-converter skill (markitdown-backed) becomes a fallback option for step 3. |
| OQ-Q35-B (cataloguer skill output shape) | RESOLVED — generated scripts/catalogue-<slug>.ts seed-script-and-commit. Per Finding 04 Rec 5. |
| N2 (cataloguer skill build-now vs defer) | STILL-OPEN pending Docling fidelity spike. If Docling fails: build cataloguer skill earlier as fallback. If Docling succeeds: cataloguer skill becomes optional. |
| OQ-Q24-A (pipeline_runs) | RESOLVED — RETAIN per §1.2. |
| Finding 06 DOCX/PDF viewer rewrite | STILL-OPEN pending Docling fidelity spike. Under sidecar-v1: viewer becomes “markdown → Tiptap ContentEditor” + read-only PDF view (per user’s notes in feedback-findings-review.md §4.6). |
| Finding 06 zero-new-deps for v1 claim | REOPENED — Docling is heavyweight (layout models, possibly VLMs/GPU). If Docling adopted, the claim becomes obsolete. Spike + Liam ruling required. |
§3 — Cross-cutting gaps
Section titled “§3 — Cross-cutting gaps”Items the cocoindex deep-dive surfaces as STILL-OPEN, with clear shape and next-step recommendation.
3.1 — Docling fidelity spike (HIGH PRIORITY)
Section titled “3.1 — Docling fidelity spike (HIGH PRIORITY)”The problem: Cocoindex’s PDF→Markdown example uses Docling under the hood. Docling’s vendor claims (layout preservation, table extraction, OCR, language coverage) are plausible but unverified against KH’s actual fixtures.
Why it matters:
- Step 3 (markdown convert) of Theme B form pipeline gates on a backend choice
- Finding 06 source-doc explorer “zero new dependencies” claim depends on whether Docling lands
- skill-seekers (current KH PDF scraper choice per
0.8.5-skill-seekers-evaluation.md) was selected before Docling was on the table
Recommended approach:
3-way bake-off on representative KH fixtures (docs/client-documentation-base/forms/standard-selection-questionnaire.pdf, docs/client-documentation-base/forms/Cloud Security Principles Checklist.xlsx, plus a representative Phew DOCX). Compare:
- Docling (cocoindex’s native backend) — layout fidelity + table preservation + dependency footprint
- skill-seekers (current choice) — KH-fit per existing evaluation
- Anthropic markdown-converter (
.claude/skills/markdown-converter/SKILL.md, markitdown-backed) — lightweight fallback
Bake-off output: per-fixture quality assessment + dependency-footprint comparison + recommendation per format.
Confidence today: ~55% on Docling for SSQ/Cloud-Security-Checklist (Prereq 2c flag).
3.2 — Entity Resolution scope
Section titled “3.2 — Entity Resolution scope”The problem: Cocoindex entity_resolution is broad (“resolve entities of any type”). Q&A pair dedup is a different problem (semantic equivalence + governance review) from named-entity dedup (canonical-form mapping).
Recommended scope:
- Named entities (Phew clients, competitors, employees, products, technologies): adopt cocoindex
entity_resolution. Replaces partial coverage inentity_aliases(Layer-4 thesaurus per Prereq 1 §2.4). - Q&A pair dedup: KEEP KH-side mechanism (content-hash + governance review +
dedup_statusstate machine). Cocoindex doesn’t model semantic-equivalence governance. - Content_items dedup: KEEP KH-side mechanism (already shipped per S183/S184/S186). Cocoindex doesn’t replace governance.
This scoping closes Prereq 2a top-recommendation #2’s “selectively” framing.
3.3 — CocoInsight vs audit_log
Section titled “3.3 — CocoInsight vs audit_log”The distinction:
- CocoInsight = developer-pipeline-observability surface. Captures transformation lineage (which pipeline stage produced which row when). Not designed for compliance/non-engineering users.
audit_log(Finding 01 Rec 7) = human-readable compliance UX audit. Captures business events (“Liam edited capability X on 12 May 2026; old value Y, new value Z”).
Recommendation: build both. CocoInsight is operational (engineering visibility into pipeline behaviour). audit_log is product (compliance + governance UX). They have different audiences + different retention + different query patterns.
3.4 — TS-facing API for cocoindex’s per-flow-run ledger
Section titled “3.4 — TS-facing API for cocoindex’s per-flow-run ledger”The gap: Prereq 2b flagged that cocoindex’s per-flow-run ledger query semantics + retention aren’t documented at the TS-facing API level. KH’s pipeline_runs rollup is the workaround — but the workaround relies on recordPipelineRun() being called from every cron entry.
Recommended: keep pipeline_runs as the KH-facing surface; document the cocoindex→pipeline_runs mapping in 02-data-flow.md (WP4) so future engineers don’t try to query cocoindex’s ledger directly.
3.5 — Multi-instance consolidated view
Section titled “3.5 — Multi-instance consolidated view”The gap: cocoindex at v1.0.3 uses LMDB-per-container. Multi-instance deployments don’t have a consolidated view. For KH’s single-instance deployment today this is a non-issue; if KH scales to multi-region or multi-tenant containers, the gap surfaces.
Recommended: defer until KH has a deployment shape that triggers it. Note in 02-data-flow.md as a known limitation.
3.6 — S9 spike status
Section titled “3.6 — S9 spike status”The gap: S9 spike (cocoindex equal-hash idempotency on KH content shapes) is referenced in Finding 02 + 00-synthesis I3 but not run.
Recommended: schedule the spike post-prereq-acceptance. Spike scope: build a minimal cocoindex flow against a sample of KH content_items + q_a_pairs; verify @coco.fn(memo=True) short-circuits when input content_hash unchanged.
§4 — Top recommendations
Section titled “§4 — Top recommendations”In dependency order:
Recommendation 1 — Centre KH’s Q&A + extraction architecture on ExtractByLlm
Section titled “Recommendation 1 — Centre KH’s Q&A + extraction architecture on ExtractByLlm”Single biggest missing primitive in the planning corpus. It directly subsumes:
- Theme B step 4 (classify-form-data — replaces standalone plugin-skill plan)
- Theme A form-agnostic Q&A (extraction returns typed
q_a_pairshape regardless of form) - OQ-Q11-A (form-question-extraction strategy)
- Dissolves the Pattern A/B parser repurpose question (B1 in 00-synthesis)
Action: Update WP4 05-qa-flow.md to centre cocoindex ExtractByLlm with typed Python output_type (instructor / pydantic schemas) as the recurring Q&A markdown adapter + form-cataloguing extractor. Pattern A/B parsers retire post one-shot Phew migration.
Recommendation 2 — Run Docling fidelity spike (HIGH PRIORITY)
Section titled “Recommendation 2 — Run Docling fidelity spike (HIGH PRIORITY)”Gates Theme B step 3 commitment + Finding 06 “zero new deps” claim + N2 cataloguer skill build-trigger.
Action: Schedule 3-way bake-off (Docling vs skill-seekers vs Anthropic markdown-converter) on representative KH fixtures. Output drives:
- Format-specific markdown converter library choice per MIME
- Finding 06 viewer architecture confirmation
- N2 cataloguer skill build-now-or-defer
Recommendation 3 — Adopt cocoindex entity_resolution selectively
Section titled “Recommendation 3 — Adopt cocoindex entity_resolution selectively”Scope: named-entity dedup only (Phew clients/competitors/employees/products/technologies). KEEP KH-side mechanisms for Q&A pair + content_items dedup (semantic-equivalence + governance review).
Action: Update entity_aliases planned migration to materialise as cocoindex flow output. Closes Layer-4 thesaurus retrofit per Prereq 1 §2.4.
Recommendation 4 — Retire what cocoindex absorbs; build what it doesn’t
Section titled “Recommendation 4 — Retire what cocoindex absorbs; build what it doesn’t”Retire (or DO NOT BUILD):
source_documents.{version, parent_id, original_filename, source_document_diffs}(Finding 01 Option α retire-seed; cocoindex source-key absorbs)pipeline_failurestable (cocoindex retry/DLQ subsumes)- Q4.12 skill-seekers-style cost-tracking dashboards (cocoindex metrics + memoisation supersede)
- KH-side cocoindex flow-run ledger replication (cocoindex inherits;
pipeline_runsis the rollup surface)
Build (cocoindex doesn’t provide):
audit_log(Finding 01 Rec 7 — compliance UX, NOT engineering observability)pipeline_runsKH-side rollup (retain — closes OQ-Q24-A)op_idpropagation (trigger or app-stamped — orthogonal to cocoindex)- KH
content_items.freshnessenum (governance, NOT cocoindex’s ingest-latency) - Per-method scoring columns on
question_matches(OQ-Q112-A — orthogonal)
Recommendation 5 — Apply Prereq 1 ontology mapping to cocoindex flows
Section titled “Recommendation 5 — Apply Prereq 1 ontology mapping to cocoindex flows”Per Prereq 1 §3.7:
- Cocoindex source-binding → Layer 1+2
- Cocoindex memoisation + lineage → Layer 2
- Cocoindex
ExtractByLlm→ Layer 5 ontology extraction - Cocoindex
entity_resolution→ Layer 4 thesaurus + Layer 5 - Cocoindex graph examples → Layer 6 KG substrate
This binding lets WP4 architecture docs reference both prereqs cohesively.
§5 — Still-open work
Section titled “§5 — Still-open work”NB (S234 end-of-session): The table below preserves the pre-Docling-spike still-open list. §7.5 (Updated still-open list) supersedes this table — items previously HIGH-priority due to Docling spike are now closed; three new partial-failure-surface items added; Cloud Run sidecar architecture added as new HIGH-priority blocker. Treat §7.5 as authoritative.
Items requiring further investigation before WP4 architecture docs land:
| Open item | Closes via | Priority |
|---|---|---|
| Docling fidelity spike on KH fixtures | Spike (3-way bake-off) | HIGH — blocks Theme B step 3 + Finding 06 + N2 |
| S9 spike (cocoindex equal-hash idempotency) | Empirical spike | HIGH — blocks Finding 02 sidecar v1 promotion + I3 in 00-synthesis |
| TS-facing API for cocoindex per-flow-run ledger | Source-code read | MEDIUM — informs pipeline_runs documentation |
| CocoInsight on-prem deployment / auth | Source-code read (docs page 404s) | MEDIUM — only matters if KH self-hosts CocoInsight |
| Per-row failure isolation pattern | S1-Q2 spike | MEDIUM |
Anthropic prompt-cache passthrough in LlmApiType.ANTHROPIC | Verification | MEDIUM — affects extraction cost projections |
Discriminated-union Pydantic schemas with ExtractByLlm | Verification (Q-EX2) | MEDIUM |
| XLSX structure-preserving conversion for form-templates | Spike (Q-XL1; Docling may flatten tables) | MEDIUM — affects Theme B step 3 for XLSX specifically |
| Knowledge Map graph substrate (Neo4j vs PG vs mempalace) | S7 future spike | DEFERRED — not blocking Phase B WP4 |
None of these gate Phase 2 (re-touch findings-review) or Phase 3 (decision-graph + collapse-candidates + 00-synthesis-v2). The Docling + S9 spikes gate WP4 02-data-flow.md + 05-qa-flow.md substrate-paragraph rewrites.
§6 — Per-finding-doc closures
Section titled “§6 — Per-finding-doc closures”Cross-reference back to the 6 finding docs:
| Finding | Cocoindex deep-dive impact |
|---|---|
| Finding 01 (source_documents + audit) | Option α confirmed. source_documents versioning cols + source_document_diffs retire (cocoindex source-key + ledger absorb). pipeline_runs RETAIN. audit_log BUILD (CocoInsight does NOT replace). N5 upload-route silent-fail fix proceeds. |
| Finding 02 (Q&A write-back) | Sidecar v1 promotion confirmed (gates only on S9 spike). Pattern A/B parser fate dissolved via ExtractByLlm. q_a_extractions recurring adapter ownership = cocoindex ExtractByLlm + KH cache. |
| Finding 03 (workspace types + renames) | No direct cocoindex impact. Shape B + workspace_id rename unaffected. |
| Finding 04 (historical extraction + coverage) | Pattern A/B retire confirmed (post Phew migration). Forward path (Theme B): Anthropic doc skills (step 1) + cocoindex pipeline converter (step 3) + cocoindex ExtractByLlm (step 4). Cataloguer skill build-trigger gates on Docling spike (N2). |
| Finding 05 (bid feedback loop) | No direct cocoindex impact on schema. Cocoindex entity_resolution could surface bid-evaluator-feedback patterns at scale (future enhancement, not v1). |
| Finding 06 (source-doc explorer) | “Zero new deps for v1” claim REOPENS if Docling adopted (heavyweight new dep). Markdown sidecar v1 = Tiptap ContentEditor unchanged. PDF flow: cocoindex pdf_to_markdown OR existing PdfReaderView (gates on Docling spike). XLSX flow: cocoindex converter + structured form UI (Theme B). DOCX flow: cocoindex converter or mammoth+Turndown (gates on Docling fidelity). |
§7 — Docling spike resolution (closed S234 end-of-session)
Section titled “§7 — Docling spike resolution (closed S234 end-of-session)”Docling bake-off completed — full results in phase-b-prerequisite-2d-docling-bakeoff.md (387-line empirical report, 88% confidence). The Phase B follow-ups noted in §3.1 + §5 are updated below.
7.1 — Per-format verdicts
Section titled “7.1 — Per-format verdicts”| Format | Verdict | Closes |
|---|---|---|
| Docling — decisive win (75 headings + 299 GFM table rows vs markitdown’s 0+0). Q-number↔question-text association intact. | §3.1, Theme B step 3 PDF | |
| DOCX | Docling — narrow win, conditional. Consolidate IFF PDF is Docling. mammoth+Turndown stays as fallback for tracked-changes DOCX edge cases. | §3.1, Theme B step 3 DOCX |
| XLSX | Docling — wins with caveat (NCSC URL drops on some single-content cells — broader corpus verification scheduled). | §3.1, Theme B step 3 XLSX |
| HTML | KEEP pullmd — no consolidation. Docling matches static-HTML tier but cannot replace pullmd’s Playwright/Cloudflare/Reddit/share-id stack. | §3.1 HTML question |
7.2 — License + footprint resolution
Section titled “7.2 — License + footprint resolution”- Docling = MIT (verified via PyPI + pyproject.toml). KH-compatible.
- markitdown = MIT. KH-compatible.
- pullmd = AGPL v3 (already tracked per 0.8.4 PM-Q2; not reopened).
- Docling footprint: ~1.8 GB on disk (1.3 GB site-packages + 506 MB HF model cache for layout-heron + docling-models). CPU-only viable.
7.3 — Architecture implication (NEW finding)
Section titled “7.3 — Architecture implication (NEW finding)”Docling’s 1.8 GB footprint cannot land in Vercel functions (250 MB limit). The form-extraction pipeline must run as a Cloud Run sidecar. KH already runs Cloud Run for the Python pipeline (kh-prod-494815 / kh-staging-494815 per CLAUDE.md) — extend the deployment to host the Docling-backed cocoindex flow.
Implications:
- Finding 06’s “zero new dependencies for v1” claim is OBSOLETE. Update
phase-b-prerequisite-2c-cocoindex-doc-handling.md§1.1 + Finding 06 source-doc explorer doc. - WP4
02-data-flow.mdmust specify Cloud Run sidecar deployment for cocoindex + Docling. Vercel hosts the Next.js app + UI; Cloud Run hosts ingest + extraction. - Cost projection must factor Cloud Run hot-path (Docling model load on first call = 506 MB download; subsequent calls amortise. Keep instances warm to avoid cold-start cost on every form extraction).
7.4 — Partial-failure surfaces (NEW Phase B follow-ups)
Section titled “7.4 — Partial-failure surfaces (NEW Phase B follow-ups)”| Surface | Severity | Recommendation |
|---|---|---|
| Docling XLSX drops NCSC URLs from cells where URL is sole content | MEDIUM | Verify on broader XLSX corpus before WP4 land. Add HITL surfacing rule if recurring. |
| markitdown 0.0.2 resolved on Python 3.14 (head = 0.1.5) | LOW | Re-run bake-off on KH target Python version. Architectural verdict unchanged. |
| Tracked-changes DOCX not tested | MEDIUM | Add tracked-changes DOCX to Theme B regression suite. May surface the python-docx Gotcha (Document(path) direct calls). |
7.4.a — N2 cataloguer skill build-trigger (post-spike disposition)
Section titled “7.4.a — N2 cataloguer skill build-trigger (post-spike disposition)”| Item | Status | Notes |
|---|---|---|
| N2 cataloguer skill build-now-or-defer | RESOLVED — DEFER. Docling fidelity is high enough that a cataloguer skill isn’t needed pre-launch. Build-now flagged only if Docling fails on broader XLSX corpus verification (see §7.4 partial-failure). | Mirrors feedback-findings-review.md §5.5 disposition. |
7.5 — Updated still-open list (replaces §5)
Section titled “7.5 — Updated still-open list (replaces §5)”| Item | Status | Priority |
|---|---|---|
| Docling fidelity spike on KH fixtures | RESOLVED (was HIGH) | — |
| S9 spike (cocoindex equal-hash idempotency) | STILL-OPEN | HIGH |
| Docling XLSX broader-corpus URL-drop verification | NEW — STILL-OPEN | MEDIUM |
| Tracked-changes DOCX regression test | NEW — STILL-OPEN | MEDIUM |
| markitdown 0.1.5 re-bench on KH target Python | NEW — STILL-OPEN | LOW |
| Cloud Run sidecar architecture decision | NEW — gated by Docling adoption | HIGH (WP4 02-data-flow.md blocker) |
| TS-facing API for cocoindex per-flow-run ledger | STILL-OPEN | LOW |
| CocoInsight on-prem deployment / auth | STILL-OPEN | LOW |
| Per-row failure isolation pattern | STILL-OPEN | MEDIUM |
| Anthropic prompt-cache passthrough | STILL-OPEN | MEDIUM |
Discriminated-union Pydantic with ExtractByLlm | STILL-OPEN | MEDIUM |
| Knowledge Map graph substrate (Neo4j vs PG vs mempalace) | DEFERRED | DEFERRED |
End of Phase B Prerequisite 2. Closes B1 (directional), B2 (directional), OQ-Q24-A, OQ-CX33-A, OQ-Q35-B, Theme B (all 6 steps — RESOLVED post-Docling-spike), Theme D, Theme G, OQ-Q19-B/C/D (directional), pipeline_failures fate, Q4.12, Finding 06 viewer architecture (post-Docling-spike — sidecar v1 confirmed; “zero new deps” claim obsolete), N2 cataloguer (deferred). Still-open: S9 spike, XLSX URL-drop verification, tracked-changes DOCX regression, Cloud Run sidecar architecture.