S436 — OKF Design Lineage Synthesis + s435 Explainer Cross-Check

Task: synthesize the OKF design lineage from .user-scratch/ and cross-check the S435 client-deployment-architecture explainer (written WITHOUT the lineage docs) against it. Read-only evidence pass. In-force rulings honoured, not re-litigated: DR-014 (forms manual-upload; corpus forms-route retired → BL-392), DR-012 (source-doc route re-point owned by id-131), DR-013 (id-135 surfaces net-new-by-design). Date: 2026-07-01.

A. Lineage narrative (what drove what)

id-127 {127.4} research (id127-corpus-structure-research.md) — assembling a synthetic ingestion corpus surfaced the “one record, many views” principle and the OKF format as the target shape (§1.3, §3). Its load-bearing recommendation: D5 — seed record identity on an “OKF frontmatter record id” (§6, Decision register).
Owner round-1 feedback (corpus-structure-feedback.md) — Liam flags that the research conflates the raw client-documentation corpus with the OKF concept bundle (L41, L43), questions whether content_item/workspace are needed at all (L82), and sketches a flow: Raw Sources → CocoIndex (producer) → OKF bundle in git → agents/UI (L53-66). Names gate-keeping authoritative docs as OKF’s enrichment Pass-2 (L45).
Reframe synthesis (okf-corpus-reframe-synthesis.md, 06-27) — adjudicates: conflation SUPPORTED (§2); D5’s premise is FALSE — OKF is path-as-identity, not a durable id (§0.2, D5-CORRECTED); ratifies the (A) two-layer derivation model over (B) git-as-canonical-store (§2.3, decision (e)); drop content_item_workspaces M2M (H2); RAG reduced-not-removed (H3). Two layers here (raw substrate / curated concepts).
v2 record model (okf-record-model-v2.md, 06-27) — supersedes the reframe: sharpens to THREE layers L-raw/L-records/L-concepts (§1), concept ≠ record (“a Q&A pair would never be an OKF concept”, §0.1), content_items FULLY eliminated (§3), producer 2-pass: Pass-1 from L-records, Pass-2 from L-raw (diagram L83; PRODUCER row L436), L-concepts = client-owned private git repo (L86/L103). Critic (...v2-CRITIC-CORRECTIONS.md) flags the content_hash seed as collision-prone and rel_path idempotency as by-design.
Owner round-3 feedback (okf-v3-owner-feedback.md) — resolves v2 blockers: single-tenant (each client = own DB+pipeline, §B) → namespace collision moot; corpus is GATED (§B); keep rel_path for source_documents (§B); governance → its own shared facet? (§E); entities STAY in DB (§F); forms need no manifest (§J); {127.4} is promotion-confidence E2E, not id-45 validation (§K).
v3 record model (okf-record-model-v3.md, 06-28) — folds round-3 in; per-axis governance facet (§5); producer = self-updating-wiki declare_file (.md writer) + reference_agent two-pass agent-loop, Pass-2 gated to the authoritative corpus (§7.2); ontology 9-item pass (§6); irreversibility moves from the DB write to FIRST bundle publication (§2.4); Task A/B/C/D split (§11). Critic (...v3-CRITIC-NOTES.md) ratifies bundle cites deterministic anchors only — q_a_pair citation is DB-internal (BLOCKER-resolved).
Decision log (okf-DECISION-LOG.md, 06-28) — round-4 board ratification (D1-D10 + F1-F4): FULL-REPLACE wipes-and-rebuilds client-prod; Q&A editor exists (reuse-not-build); id-133 builds on id-63 ontology.
Search/sourcing v1 (okf-search-sourcing-design-v1.md, 06-28) — {131.20} G-SEARCH-RESEARCH; grain-aware search over EMB-STORE (not a flat UNION); ratified S428; drove id-135 (net-new human search/browse surfaces after the IMS-UI elimination). Per-application_type ranking: only procurement is q_a_pair-primary; sales-proposals doc-primary; sector-intel reference-primary.
Tasks — id-131 (Task B, L-records refactor) · id-132 (Task A, L-concepts + producer) · id-133 (Task D, ontology pass) · id-134 (Task C, {127.4} promotion-confidence E2E + release gate) · id-135 (net-new search/browse surfaces). Per-task feedback: id-131-2-3-4-user-feedback.md.

B. Explainer cross-check (s435 vs the lineage)

#	Load-bearing s435 claim	What the lineage docs say	Verdict
B1	OKF bundle lives in a client-owned private git repo (id-132); not in app repo, not in DB (§a, §c, §d)	v3 §1 (L-concepts owner = THE CLIENT, private git repo); v2 L86/L103; owner v3 §D (“the private repo storing the OKF bundles is CLIENT-OWNED”)	CONFIRMED
B2	Producer runs as a separate cocoindex flow, 2-pass (§d step 7)	v3 §7.2 + v2 L83/L436: 2-pass producer; `.md` writer = cocoindex `declare_file`; agent logic = reference_agent two-pass	CONFIRMED (mechanism nuance in B7)
B3	Pass 1 drafts one concept per named asset purely from L-records (no web) (§d step 7)	v3 §7.2: Pass-1 `enrich_concept()` reads L-records via a bespoke Source adapter (list_concepts/read_concept_raw/sample_rows). “L-records, no web” holds	CONFIRMED, but “one per named asset” understates that concept granularity is a PRODUCT decision (product/topic/cert/company/metric) from the id-71 strawman + the client’s hand-built topic index → NUANCE-MISSING
B4	Pass 2 enriches only from the gated authoritative corpus (host-allowlist/depth, never open web) (§d step 7)	v3 §7.2 (“constrain Pass-2 to the GATED authoritative corpus … NOT the open web”); owner v3 §B; reframe FB8/decision (c)	CONFIRMED
B5	L-raw is the GATED corpus (topology diagram, §c)	v3 §1 + owner v3 §B: gating = authoritative-source curation discipline (“we define the source-doc structure + Q&A format for the first client”); ratified GATE-KEEP over ingest-all-then-sort (reframe (c))	CONFIRMED but s435 uses “gated” mainly in the network/bearer sense; the design sense (authoritative curation, ties to Pass-2) is unexplained → NUANCE-MISSING
B6	Concepts cite records via `canonical://<table>/<uuid>` (§b, §d step 8)	v3 §3.4 + v3-CRITIC-NOTES: bundle citation target set = {source_document, reference_item, concept} ONLY; q_a_pair citation is DB-INTERNAL only (bundles are not record-based by design; a Q&A pair is a record, never a concept)	CONFIRMED at surface, NUANCE-MISSING on the q_a_pair exclusion + that the `resource:`/seed-string contract is the true point-of-no-return (Task A/id-132)
B7	”written via `declare_file`, then a separate git writer commits — one commit per run” (§d step 7)	v3 §7.2: git “knowledge-sync” is OUTSIDE cocoindex, and commit timing (per-run vs batched) is UNSPECIFIED — a Task-A decision	NUANCE-MISSING — s435 states an open id-132 detail (“one commit per run”) as settled
B8	L-records model = source_documents, q_a_pairs (+ q_a_extractions), reference_items, content_chunks, entity graph, citations; id-131 adds record_lifecycle + record_embeddings, kills content_items (§d step 5, §g flag 5)	v3 §3/§4/§5/§7.3: exactly this. record_embeddings = EMB-STORE; record_lifecycle = GOV-FACET (per-axis, D7)	CONFIRMED (correctly reflects the id-131 elimination)
B9	Producer’s working copy “lands transiently on the pipeline VPS (producer runs co-located with ingest)” (§d)	Producer-run location is an id-132 TECH detail; the lineage docs (reframe/v2/v3) don’t specify co-location — they specify the mechanism, not the host	NOT-COVERED by lineage (id-132 TECH claim; plausible, unverified here)
B10	Producer is “[PLAN — id-132]”; RAG framing implicit	Lineage: RAG reduced not removed — keep the EMB-STORE vector index over bundle + long tail (v3 RAG row; owner v3 §A); s435 doesn’t state this	NUANCE-MISSING (minor for a deploy doc)

No hard CONTRADICTIONS found — s435 is accurate on topology/networking; its gaps are all OKF knowledge-model nuances (expected, since it was written from deploy files, not these docs).

C. Owner questions — doc-cited answers

C1. Pass-1 “purely from L-records (no web)” vs owner’s “OKF bundles determined from the current client corpus & ontology” — reconcile

They are consistent — the apparent gap is a layer-naming difference, and the ontology enters at two named points. Spelled out for a non-technical reader:

The client’s gated raw files are L-raw. The cocoindex pipeline extracts them into L-records — the structured DB rows (source_documents, q_a_pairs, reference_items, content_chunks, the entity graph). So L-records IS the extracted/structured form of the client corpus (v3 §1 diagram: “cocoindex pipeline derives ↓”). When v3 §7.2 says Pass-1 reads “purely from L-records,” that is the same thing as the owner’s “from the current client corpus” — Pass-1 reads the distillation of the corpus, not the raw files, and adds no web content. “Purely from L-records” and “derived from the corpus” are the same statement at two layers (v3 §7.2 Source adapter over L-records; owner v3 §D “the pipeline extracts CONCEPTS … the source docs remain the authoritative source”).
The ontology enters twice, not inside Pass-1’s data read. (a) As a semantic linter that gates every concept write — the 12-entity/10-relation ontology + the OKF concept-frontmatter validator (v3 §6 item 6, §7.2 “gate declare_file … as a semantic linter”). (b) As id-133 (Task D), the three-layer ontology register that promotes entity_type/relationship to CVs and governs what may be extracted AND what may enter the OKF directory (owner v3 §H; v3 §6).
One caveat s435 hides: “one concept per named asset” is a simplification. Concept granularity is a deliberate PRODUCT decision (product/topic/cert/company/metric), driven by the id-71 strawman and the client’s own hand-built “BID RESPONSE TOPIC INDEX” (v3 §7.2, §4 real-corpus validation) — not a mechanical one-row-per-asset mapping. Pass-2 then enriches each concept from the gated L-raw authoritative sources (v3 §7.2). So the owner’s mental model is correct; “purely from L-records” is the accurate description of Pass-1’s input, with the ontology governing the output and Pass-2 re-touching L-raw.

C2. Change propagation when source_documents arrive/change — is the process specified?

Partial mechanism, but the cadence/trigger/reconciliation is an explicit GAP.

What IS specified: the producer’s .md writer is cocoindex declare_file, “a native cocoindex FILE target, incremental via memo — delta-only OKF regeneration for free” (v3 §7.2). So when a source_document changes → L-records update → the Source adapter re-reads → cocoindex memoisation regenerates only the affected concept files. Mechanism-level, propagation is incremental.
What is NOT specified (GAP): the trigger and cadence of the producer flow — v3 §7.2 verbatim: git “knowledge-sync … Ownership/timing (per-run vs batched) is unspecified — a Task-A decision.” s435 asserts “different cadence … one commit per run,” but the lineage leaves cadence open. No staleness-detection or scheduled re-run cadence is defined anywhere in the lineage.
Second GAP — human-edit reconciliation: v3-CRITIC-NOTES flags that declare_file’s orphan-delete + fingerprint-overwrite semantics mean a machine-regenerated, client-owned bundle dir will OVERWRITE human hand-edits — “Task A must define the human-edit-vs-regeneration reconciliation, not just git-sync.” This is unresolved. Net: incremental regeneration is implied by v3/id-132; the concrete trigger, cadence, staleness detection, and human-edit reconciliation are open id-132 (Task A) decisions.

C3. OKF repo model — who accesses the git repo; was storing the CLIENT CORPUS in git considered?

Ownership/access: L-concepts is client-owned (v3 §1; “two of three layers are client-owned” — L-raw and L-concepts). The platform-operated producer writes a working copy; a separate git “knowledge-sync” writer commits/pushes (v3 §7.2). The value of git is version rollback + audit + authorship + point-in-time — owner round-1 step 4: “gaining authorship and point-in-time version rollback natively.” Auth is never git: reframe risk 4 — “keep the DB/API as the auth layer OVER the bundle … never assume the git tree is the security boundary.” The lineage does not specify the client directly cloning/pushing day-to-day; the emphasis is ownership + rollback/audit, with the producer as writer. So git is best characterised as client-owned versioned storage for observability/audit/rollback, read by platform consumers under DB/API auth.
Was storing the CLIENT CORPUS (L-raw) in git considered/ruled on? YES — considered and RULED OUT. The owner’s round-1 step-4 “host the files in a private git repo … bulletproof single source of truth” was adjudicated in reframe §2.3 as the (A) derivation vs (B) canonical-store fork. (B) = git tree becomes the canonical store (would invert the “KH is not the storage layer” vision). Ratified (A): git holds only the derived OKF bundle; L-raw stays client-side canonical (local-fs/Notion/Gmail — “Canonical never hosts it,” v3 §1). Owner v3 §D confirms: “‘Host the files in a private git repo’ referred ONLY to the OKF bundles.” (Coolify-S3 is a git-remote/backup host, not a corpus store — reframe FB7/D8.)

C4. What the s435 explainer should have said but didn’t (material omissions)

Bundle citation excludes q_a_pairs — the bundle cites {source_document, reference_item, concept} only; q_a_pair citation is DB-internal (v3 §3.4). s435’s blanket “concepts cite records” over-includes.
The true point-of-no-return is FIRST bundle publication (Task A/id-132), not the DB write — L-records is disposable/reproducible via full-replace + deterministic uuid5; the SEED-CONTRACT (frozen seed strings sd:{rel_path}/ri:{source_url}/qa:{rel_path}:{idx} + _KH_PIPELINE_DOC_NS
- the canonical://<table>/<uuid> scheme) must be frozen before the first bundle ships or every citation orphans (v3 §2.4, §10 SEED-CONTRACT). s435 omits this entirely.
Concept granularity is a product decision, not one-per-asset (v3 §7.2) — see C1.
The ontology (id-133) is a semantic linter gating BOTH extraction and concept writes (v3 §6) — s435’s producer description omits the ontology’s governing role.
Change-propagation cadence + human-edit-vs-regeneration reconciliation are OPEN (C2) — a durable deployment doc should flag these as unresolved id-132 decisions rather than imply a settled “one commit per run.”
RAG is reduced, not removed; the EMB-STORE vector index is retained over the bundle + long tail (v3 RAG row; owner v3 §A).
The corpus is gated in the DESIGN sense (authoritative curation; we define the source-doc + Q&A structure for the first client), which is what makes Pass-2’s authoritative-only enrichment coherent (owner v3 §B) — distinct from the network-level bearer gating s435 focuses on.

D. Facts that MUST survive into the durable reference doc (one per line)

Three-layer model: L-raw (client-owned, stays put, GATED) → L-records (Canonical-operated DB) → L-concepts (client-owned private git bundle). Two of three layers are client-owned.
content_items is ELIMINATED (id-131 / Task B). L-records = source_documents, q_a_extractions→q_a_pairs, reference_items, content_chunks, entity_mentions/entity_relationships, citations, EMB-STORE (record_embeddings), record_lifecycle facet (per-axis governance).
Record-identity seeds: sd:{rel_path}, ri:{source_url}, qa:{rel_path}:{idx}; q_a_pairs master PK = opaque gen_random_uuid(); namespace _KH_PIPELINE_DOC_NS. Single-tenant (each client = own DB + pipeline) → no cross-tenant collision.
L-records is DISPOSABLE/reproducible: full-replace re-ingest + deterministic uuid5 WIPES-and-rebuilds (covers client-prod). The irreversible point is FIRST bundle publication (Task A/id-132), NOT the DB write.
SEED-CONTRACT: freeze seed strings + namespace + the canonical://<table>/<uuid> resource-URI scheme BEFORE the first bundle ships, or every citation silently orphans.
Producer = 2-pass. Pass 1: L-records only, no web (via a bespoke Source adapter). Pass 2: enrich from the GATED authoritative corpus only (host-allowlist/depth), never the open web.
Producer mechanism: cocoindex declare_file (incremental .md writer) + reference_agent agent-loop ported ADK+Gemini → Anthropic + a SEPARATE git “knowledge-sync” writer (outside cocoindex). Commit cadence/trigger UNSPECIFIED (open id-132 decision).
Concept granularity (product/topic/cert/company/metric) is a PRODUCT decision from the id-71 strawman + the client’s hand-built topic index. A Q&A pair is a RECORD, never a concept, never in a bundle.
Bundle citation target set = {source_document, reference_item, concept} ONLY. q_a_pair citation is DB-INTERNAL. Bundles are not record-based by design.
Corpus GATING = authoritative-source curation discipline (we define source-doc structure + Q&A format for the first client). GATE-KEEP ratified over ingest-all-then-sort.
Ontology (id-133 / Task D) = semantic linter gating BOTH extraction into L-records AND concept writes; promotes entity_type(12)/relationship(10) to register CVs. The OKF 3-layer model ≠ the audience-axis 03-layer-vocabulary CV.
Git repo = client-owned versioned storage (rollback/audit/authorship/point-in-time). Auth stays at DB/API — the git tree is NEVER the security boundary. L-raw (the client corpus) is NOT stored in git (option B ruled out; (A) derivation ratified).
RAG = REDUCED, not removed. Keep the EMB-STORE vector index over the bundle + long tail.
Change propagation is incremental via cocoindex memo, but cadence/trigger/staleness-detection + human-edit-vs-regeneration reconciliation are OPEN id-132 decisions.
Task→id map: id-131 = L-records refactor (Task B) · id-132 = L-concepts + producer (Task A) · id-133 = ontology pass (Task D) · id-134 = {127.4} promotion-confidence E2E + release gate (Task C) · id-135 = net-new human search/browse surfaces (DR-013).
Forms: manual-upload (DR-014), no corpus manifest; forms-matching re-points to q_a_pairs (primary) + reference_items (optional); source_documents is NOT a match target (provenance only).
Search: grain-aware over EMB-STORE (not a table-agnostic UNION); default scope = ALL owner_kinds, per-grain normalised + answer-first bounded boost; ranking profile per application_type (only procurement is q_a_pair-primary; sales-proposals doc-primary; sector-intel reference-primary).