Three-Layer Model

Three-Layer Model

Definition

The OKF (Open Knowledge Framework) storage-layer axis: the three storage layers any piece of client knowledge occupies as it moves from raw input to distilled, reusable concept. It is the architectural spine of the “Where does new data live?” decision procedure in the register README — it answers where does this live?. The three layers are closed and core (l_raw / l_records / l_concepts); clients cannot add a fourth.

• l_raw (L-raw) — client raw sources, client-owned. The original inputs: uploaded files, fetched URLs, feed items. Custody and extraction lineage live here. This layer is owned by the client; the platform does not mint it.
• l_records (L-records) — the Canonical DB (typed records). The platform’s typed record classes — source_documents, q_a_pairs, reference_items, and the Knowledge-Graph entity mentions / relationships. This is the machine-readable middle layer the AI retrieves, classifies, and cites.
• l_concepts (L-concepts) — the client OKF bundle (distilled concepts). Synthesised, reusable ideas distilled from the records into the client’s Open Knowledge Framework bundle. An L-concept is client-owned and is NOT a DB table — it is a bundle artefact, not a typed record row.

Synonyms / Acronyms

• OKF — Open Knowledge Framework (the client concept bundle that holds L-concepts).
• L-raw / L-records / L-concepts — the three layer keys; “the three-layer model” names the axis as a whole.

Baseline values

key	label	provenance
l_raw	L-raw	core
l_records	L-records	core
l_concepts	L-concepts	core

Relationships

The only legitimate cross-layer pointers are between adjacent layers, always running from the more-distilled layer to the less-distilled one (any other coupling is an anti-pattern):

• L-records → L-raw provenance. A typed record carries provenance back to the raw source it was derived from (e.g. source_documents custody / extraction lineage). Records point down to their raw input.
• L-concepts → L-records citation. An L-concept cites the records it distils via the canonical://<table>/<uuid> citation scheme (the URI scheme is owned by ID-132). Concepts point down to the records they synthesise; they never duplicate record bodies.
• There is no upward pointer (L-raw never references L-records or L-concepts) and no L-raw → L-concepts shortcut — concepts are distilled from records, not from raw input directly.

Consumers

• The “Where does new data live?” decision procedure (README) routes every new artefact class into exactly one of these three layers.
• ID-132’s OKF concept producer writes L-concepts and stamps the canonical://<table>/<uuid> citations that realise the L-concepts → L-records pointer.
• ID-131’s L-records refactor owns the typed record homes (source_documents / q_a_pairs / Knowledge-Graph entities) that constitute L-records.

Notes

• ORTHOGONAL to 03-layer-vocabulary — do NOT conflate the two “layer” axes. This CV (three_layer_model) is the OKF storage-layer axis (where knowledge is stored: l_raw / l_records / l_concepts). 03-layer-vocabulary (layer_vocabulary) is the audience/depth axis (who reads it, at what depth: sales_brief / bid_detail / company_reference / research). A record at any audience layer still occupies exactly one storage layer; the two axes are independent. Prompts and classifiers reading the bare word “layer” MUST disambiguate which axis is meant (anti-conflation guard, v3 Lens E / ID-133 Risk 4).
• L-concepts are client-owned and NOT a DB table. The OKF bundle is a client artefact; a distilled concept is never stored as a typed record row. Storing a concept as a record would make it an L-records member (a different layer) — which the “Where does new data live?” rule routes explicitly, rather than silently re-classing the concept.
• The three keys are closed and core (client_extensible: false): the storage model is a platform invariant, edited only by database_migration, never by clients.