From 472b9482dd0326df0225e4b30e330a1b23029bf7 Mon Sep 17 00:00:00 2001
From: Derek <derek@hyperi.io>
Date: Fri, 13 Nov 2026 13:34:00 +1100
Subject: [PATCH 1/3] docs(transport): document the common header for every
 record

Document the common header as the base of every DFE table: events, context and metrics. Row-level security, deduplication, partitions and the console's queries all key on its fields.
---
 docs/transport/common-header.md | 29 ++++++++++++++++-------------
 1 file changed, 16 insertions(+), 13 deletions(-)

diff --git a/docs/transport/common-header.md b/docs/transport/common-header.md
index fb62925..70267bc 100644
--- a/docs/transport/common-header.md
+++ b/docs/transport/common-header.md
@@ -1,7 +1,7 @@
 <!--
   Project:      dfe-loader
   File:         docs/transport/common-header.md
-  Purpose:      Common header schema injected into every event table
+  Purpose:      The common header every record in every DFE table carries
   Language:     Markdown
 
   License:      BUSL-1.1
@@ -10,15 +10,18 @@
 
 # Common header schema v2
 
-Every event the loader writes -- regardless of the transport it arrived on
-(a Kafka topic or a gRPC push) -- gets a standardised common header injected before
-insert. This is the base schema shared by all event tables in the DFE (Data
-Fusion Engine) pipeline. This page documents the full field set, the DDL, and the
-ORDER BY / PARTITION BY / codec / index decisions behind it.
+Every record in every DFE table starts with the common header: events, context,
+metrics, whatever the table holds. The loader injects it before insert, whichever
+transport the record arrived on (a Kafka topic or a gRPC push). The rest of the
+stack keys on it: row-level security on `_org_id`, deduplication on `_uuid`, time
+windows and partitions on its timestamps, and the console's queries on all three.
+Change a header field and every table and every reader moves with it. This page
+documents the full field set, the DDL, and the ORDER BY / PARTITION BY / codec /
+index decisions behind it.
 
 ## Overview
 
-Every event table shares a common header that provides:
+Every table shares a common header that provides:
 
 1. **Temporal ordering** -- multiple timestamp fields for different use cases.
 2. **Multi-tenancy** -- organisation ID for row-level security (RLS).
@@ -29,10 +32,10 @@ Every event table shares a common header that provides:
 ## Common header vs complete table schema
 
 The common header is the **base** of every table's schema -- not the complete
-schema itself. The loader injects these system fields into every event.
+schema itself. The loader injects these system fields into every record.
 
 - **Landing table** (`dfe.main`): schema IS just the common header. This is the
-  catch-all for unrouted events.
+  catch-all for unrouted records.
 - **Other tables** (e.g., `dfe.auth`, `dfe.metrics`): schema = common header
   plus data-specific columns, alongside the common header.
 
@@ -207,7 +210,7 @@ column the header pass fills, not only this one.
 | Codec | None (UUID is already compact) |
 | Source | `@generated: generateUUIDv7()` |
 
-**Purpose:** Unique identifier for each event.
+**Purpose:** Unique identifier for each record.
 
 **Rationale:**
 
@@ -396,7 +399,7 @@ for backwards compatibility and mapped onto `capture_mode`.
 - Config-driven source field list (first match wins).
 - Stored as JSON for flexible querying.
 - Contains collector metadata, enrichment tags, routing info.
-- Nullable -- not all events have tags.
+- Nullable -- not all records have tags.
 
 **Field resolution order:**
 
@@ -660,7 +663,7 @@ The common header DDL carries this index on every `_raw` column. Under
 | Index type | Pros | Cons |
 |------------|------|------|
 | `text` (default) | GA in 26.2+, accurate, no false positives | ~50% insert overhead on `_raw` |
-| `ngrambf_v1` (legacy) | Lower storage | False positives; no reason to prefer on 26.2+ |
+| `ngrambf_v1` (legacy) | Lower storage | False positives, and no reason to prefer it on 26.2+ |
 | None | Zero overhead | Full scan for text search -- use `capture_mode = "extracted_only"` instead |
 
 If you do not need full-text search on the raw payload, set
@@ -788,7 +791,7 @@ definitions that specify which system fields to inject and how to populate them.
 
 | Profile | Fields | Use case |
 |---------|--------|----------|
-| `timeseries` (default) | 9 | Full common header for event ingestion |
+| `timeseries` (default) | 9 | Full common header for record ingestion |
 | `minimal` | 5 | High-volume structured data (no _raw,_tags, _source) |
 | `passthrough` | 4 | Transparent bridge (no _timestamp injection) |
 

From 70377863a4657bd696cd1b521d9b997906004338 Mon Sep 17 00:00:00 2001
From: Derek <derek@hyperi.io>
Date: Fri, 13 Nov 2026 13:48:27 +1100
Subject: [PATCH 2/3] docs(transport): say what a header change reaches

The opening explains which tables and queries a header change affects. A changed header field reaches every table the schema phase creates and every query that filters on it.
---
 docs/transport/common-header.md | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)

diff --git a/docs/transport/common-header.md b/docs/transport/common-header.md
index 70267bc..e7b6c12 100644
--- a/docs/transport/common-header.md
+++ b/docs/transport/common-header.md
@@ -10,12 +10,14 @@
 
 # Common header schema v2
 
-Every record in every DFE table starts with the common header: events, context,
-metrics, whatever the table holds. The loader injects it before insert, whichever
-transport the record arrived on (a Kafka topic or a gRPC push). The rest of the
-stack keys on it: row-level security on `_org_id`, deduplication on `_uuid`, time
-windows and partitions on its timestamps, and the console's queries on all three.
-Change a header field and every table and every reader moves with it. This page
+Every record in every DFE table starts with the common header: events, context
+and metrics alike. The loader injects it before insert, whichever transport the
+record arrived on (a Kafka topic or a gRPC push). The rest of the stack keys on
+it: row-level security on `_org_id`, deduplication on `_uuid`, time windows and
+partitions on its timestamps, and the console's queries on all three. A change
+to a header field reaches every table the engine's schema phase creates and
+every query that filters on it, which is why the header moves only with its
+schema version. This page
 documents the full field set, the DDL, and the ORDER BY / PARTITION BY / codec /
 index decisions behind it.
 

From 5c6e40bf109d060e77418f75719536a78cfc13a7 Mon Sep 17 00:00:00 2001
From: Derek <derek@hyperi.io>
Date: Fri, 13 Nov 2026 13:53:12 +1100
Subject: [PATCH 3/3] docs(transport): name the configurable landing table

The landing table line now says dfe.main is the default and routing.default_table picks another. The opening paragraph sits on one source line.
---
 docs/transport/common-header.md | 15 +++------------
 1 file changed, 3 insertions(+), 12 deletions(-)

diff --git a/docs/transport/common-header.md b/docs/transport/common-header.md
index e7b6c12..954cc93 100644
--- a/docs/transport/common-header.md
+++ b/docs/transport/common-header.md
@@ -10,16 +10,7 @@
 
 # Common header schema v2
 
-Every record in every DFE table starts with the common header: events, context
-and metrics alike. The loader injects it before insert, whichever transport the
-record arrived on (a Kafka topic or a gRPC push). The rest of the stack keys on
-it: row-level security on `_org_id`, deduplication on `_uuid`, time windows and
-partitions on its timestamps, and the console's queries on all three. A change
-to a header field reaches every table the engine's schema phase creates and
-every query that filters on it, which is why the header moves only with its
-schema version. This page
-documents the full field set, the DDL, and the ORDER BY / PARTITION BY / codec /
-index decisions behind it.
+Every record in every DFE table starts with the common header: events, context and metrics alike. The loader injects it before insert, whichever transport the record arrived on (a Kafka topic or a gRPC push). The rest of the stack keys on it: row-level security on `_org_id`, uniqueness on `_uuid`, time windows and partitions on its timestamps, and the console's time and organisation filters on the same columns. A change to a header field reaches every table the engine's schema phase creates and every query that filters on it, which is why the header moves only with its schema version. This page documents the full field set, the DDL, and the ORDER BY / PARTITION BY / codec / index decisions behind it.
 
 ## Overview
 
@@ -36,8 +27,8 @@ Every table shares a common header that provides:
 The common header is the **base** of every table's schema -- not the complete
 schema itself. The loader injects these system fields into every record.
 
-- **Landing table** (`dfe.main`): schema IS just the common header. This is the
-  catch-all for unrouted records.
+- **Landing table** (`dfe.main` by default, another with `routing.default_table`):
+  schema IS just the common header. This is the catch-all for unrouted records.
 - **Other tables** (e.g., `dfe.auth`, `dfe.metrics`): schema = common header
   plus data-specific columns, alongside the common header.