OKF Record-Model — Owner feedback round 3 (authoritative direction)

This is the product owner’s verbatim feedback after reviewing okf-record-model-v2.md and okf-record-model-v2-CRITIC-CORRECTIONS.md. It RESOLVES several v2 blockers with domain knowledge and OPENS new design questions. Treat as authoritative direction for the v3 pass.

Read alongside (prior-round context, all in .user-scratch/):

corpus-structure-feedback.md (round-1 feedback + the “Valuable Documentation” historic doc list)
okf-record-model-v2.md (the v2 model — being refined)
okf-record-model-v2-CRITIC-CORRECTIONS.md (the adversarial critic’s defects)

A. Confirmed / settled (do NOT re-litigate — fold in)

3-layer model (L-raw / L-records / L-concepts) — RATIFIED.
OKF = knowledge map, not a record store — confirmed.
content_items elimination (direction) — RATIFIED (“100%, but cheaper than it appears” — owner believes the consumer surface is less scary than the critic implied; see §C).
op_id = per-run provenance, no identity role — settled.
Drop Canonical-id-in-bundle (D5 superseded) — settled. BUT see §D record-identity nuance.
Drop content_item_workspaces M2M coupling — RATIFIED.
FULL-REPLACE re-ingest — CONFIRMED. Re-ingest runs on a NEW, EMPTY, preview branch; when ready, cut over to replace Phew’s current DB content.
CITE-EXT (extend citations target kinds) — RATIFIED, subject to §C/§D context.
RAG: goal is NOT “remove RAG”. Goal = best outcomes from the underlying data — OKF as a map for humans AND AI, plus records to bring applications to life. Reduce lossy RAG where the curated layer makes direct traversal better; keep retrieval where it serves the outcome.

B. Single-tenant + gated-corpus corrections (RESOLVE v2 critic blockers)

Each tenant has their OWN DB and pipeline instance. _KH_PIPELINE_DOC_NS being a single global constant is therefore FINE — there is no cross-tenant collision surface. The DB + pipeline were designed multi-tenant, but multi-tenant is NOT a requirement — the concept “crept in” to prior context and should be dropped. → This dissolves the critic’s “no tenant discriminator” half of BLOCKER 1.
The corpus is GATED. Original + ongoing intent: gate the source_documents that get ingested so (i) they are authoritative sources, and (ii) we help businesses prepare/organise their data to create and upload more authoritative sources. The ontology pipeline was “phase 0” of enabling this capability. The v1 cocoindex pipeline monitors a gated corpus for changes, with the corpus structure for source documents arranged in a way WE define (at least initially, for the first client), and Q&A pairs structured in a format WE define. The first client HAS Q&A pairs; future clients may NOT.
rel_path seed is BY-DESIGN for source_documents (flow.py:1630-1640). The owner AGREES with the critic: re-ingesting the same file mints the same PK → UPSERT-in-place idempotency. The “rel_path is THE offender / switch to content_hash” framing over-generalised a Q&A problem onto documents. → v3 must KEEP rel_path for source_documents and treat the Q&A identity as the real (and separable) problem (see §D).

C. content_items decomposition — owner’s read (re-ground against CURRENT head)

Owner can “quite quickly cut through what is/isn’t required for hybrid_search”. Result-shape change should NOT be dramatic: reference_items and q_a_pairs were EXTRACTED from content_items, and much of what is actually valuable on content_items is likely already on source_documents.
cite_content should already be sourcing from the dedicated table.
get_content_win_rate “already doesn’t sound logical” — likely already migrated to q&a-pair / form-related tables. VERIFY.
Column homes (owner’s view): author_name → source_document; thumbnail_url → reference_items; platform / source_domain MAY or may not be required (the ontology may help decide, or owner can advise).
content_text_hash / dedup: content_items.content_text_hash is a GENERATED md5 of NORMALISED text. Could source_documents carry a content_text_hash (normalised) rather than the plain file hash? MORE IMPORTANTLY: under the new model, where is dedup actually valuable, given that the concept of a content_item is already incorrect? (i.e., don’t port dedup blindly — justify it.)
Removing the content_item abstraction should SIMPLIFY manual/TS authoring (see 0.9-edit-flow-investigation for the edit use-cases). When AI-tooling creates content — a user with Claude + the Canonical MCP, or a headless agent creating something a user approves — the artifact will clearly be ONE of the three types (source_document / reference_item / q_a_pair), so how it is seeded becomes much clearer. There is no requirement for “~58 cols”.

D. Record-identity (D5-v2) — owner nuance

Concept-identity = OKF path (client-owned bundle). Settled.
The .md files represent CONCEPTS (tables, datasets, metrics, playbooks, runbooks…), NOT data records and NOT what we previously called a content_item. Client raw sources stay with the client (local-fs, Notion, Gmail). The cocoindex pipeline extracts CONCEPTS + related info to create OKF bundles; the source docs remain the authoritative source (provenance, audit trail, historical context, citations), which an enrichment agent populates during a second pass.
“Host the files in a private git repo” (round-1 step 4) referred ONLY to the OKF bundles. The private GitHub repo storing the OKF bundles is CLIENT-OWNED.
Given client-owned bundle: a “Canonical-owned frontmatter id” would cause issues. A Q&A pair isn’t a concept, it’s a record — so it would presumably never be IN an OKF bundle. (Confirm this understanding.)
Open: §2.2 record-identity — do we separate qa:{rel_path}:{idx} to simplify? E.g. Q&A pairs as DB-only (no rel_path-derived identity)?

E. Governance / freshness / lifecycle — promote to its own schema?

Should the governance / freshness / lifecycle column family be promoted to its OWN schema (table), ALONG WITH the current governance_config, and then be applicable to source_document, reference_item, AND q_a_pair — or just source_document? (v2 landed it on source_documents only; owner is asking whether a shared governance facet is better.)

F. Entities stay in the DB (corrects v2 §8 risk 5)

There is NO intention for entity_relationships / entity_mentions to “leave the DB”. They would be extracted from source_document / reference_item / q_a_pair, just no longer from content_items. The cocoindex docs-to-knowledge-graph example describes this. → v3 must drop the “entities may leave the DB” risk and replace it with “re-parent the extraction source to the 3 typed tables”.

G. cocoindex docs-to-knowledge-graph — central grounding question

Reference: https://cocoindex.io/docs/examples/docs-to-knowledge-graph/ (and the self-updating wiki blog: https://cocoindex.io/blogs/multi-codebase-summarization/).
Are we already using (or intending to use) this approach for (a) source-doc extraction (entities/relationships from the 3 typed tables) and/or (b) the approach to CREATING the OKF bundles?
Owner’s PRODUCER hypothesis: cocoindex docs-to-knowledge-graph adapted to create the .md’s, then a pre-built enrichment agent (Google reference_agent) for the enrichment pass.
EMB-STORE: is the dedicated embeddings store covered by adopting the docs-to-knowledge-graph approach + related feedback, or still net-new?

H. Ontology pass

We may need a PASS of the ontology to ensure it accurately reflects the three-layer model and moves away from content_items. The ontology also contains valuable context for platform-related concepts, INCLUDING where something is core-platform vs client-configurable.
Ontology docs: docs-site/.../specs/wp6-ontology-harness/, .../themes/phase-0-investigation/phase-b-prerequisite-1-onthology-pipeline (+ its -feedback-investigation).
Ontology as semantic linter (allowed_types / allowed_relations kept in sync; governance for what gets added to the OKF directory AND what gets extracted).

I. content_templates

We have content_templates. What is the current purpose? Could these be used as part of how our AI-tooling creates NEW content (source_document / reference_item / q_a_pair)?

J. Forms

Do forms need a MANIFEST? Or could it be: a user provides a form → our cataloguing skill “maps” the form → it gets added to the platform → Q&A pairs are used to COMPLETE the form?
Relevant: specs/id-80-forms-path-b/, the catalogue-form-requirements skill, form_templates.

K. id-127.4 — purpose reframe (CHANGES Task C)

The MAIN purpose of {127.4} is to ensure we have a synthetic corpus for our Platform staging/prod pipeline and DB, for E2E / dogfooding — NOT to validate id-45. So what {127.4} ultimately requires is whatever is needed to ensure robust E2E is in place that lets us CONFIDENTLY PROMOTE CLIENTS to new DB / App / pipeline releases.
(v2 said “shrink to a tiny fixture” because it mis-read the purpose as id-45 validation. Re-derive what {127.4} actually needs for promotion-confidence E2E / dogfooding.)

Misc

the-propel-pathways Supabase project = NOT a client; a separate project’s DB on the same org. Ignore it.
source_url: drop from content_items (confirmed). Open: drop from source_documents too? (Check whether SD even has it.) It MUST remain on reference_items.
Full first-client corpus: Documents/development/local-fs-client (corpus at .../local-fs-client/corpus).