Skip to content
Canonical

Platform Context — session-start load anchor

Platform Context

Section titled “Platform Context”

Purpose. The single load-at-session-start anchor for the Canonical platform. It holds the current facts and points to the authoritative runbooks. Keep it short and current — if a fact here is wrong, fix it here first, then propagate.

DB topology — FOUR databases

Section titled “DB topology — FOUR databases”
EnvironmentPROJECT_REFNotes
Platform prodzjqbrdctesqvouboziae
Platform stagingrbwqewalexrzgxtvcqrh.env.local / local-dev + CI target (PLATFORM_PROJECT_REF)
client prodrovrymhhffssilaftdwdPROD_PROJECT_REF
client stagingturayklvaunphgbgscatSTAGING_PROJECT_REF

  • Platform and client staging DBs are Supabase persistent staging branches of their respective prod project, accessible via supabase link --project-ref {PROJECT_REF} - they won’t appear via list_projects.

  • .env.local targets Platform staging rbwqewalexrzgxtvcqrh. Prod-targeted CLI work opts in via --env=prod; CLI scripts take --env={prod,staging,auto}.

  • Squash-baseline caveat (Retro S410, corrected S493): the 20260617130000 squash captures schema only — NOT seeded data rows, NOT ACLs. The data half still needs an explicit step (supabase db push --include-seed). The ACL half does not: forward migrations in the chain carry it (…id115_api_schema_anon_revoke, …id61_dr035_default_privileges, …id347_anon_lockdown), and S493 proved a from-zero replay of all 106 migrations lands the DR-035 invariant unaided — 0 anon table grants, exactly two anon-EXECUTE set_config functions, byte-identical to both Platform DBs. Verify as a spot-check; never re-apply ACLs by hand.

  • After any prod/client db push, re-link back to rbwqewalexrzgxtvcqrh (drift hazard; cat supabase/.temp/project-ref before every push).

Deploy surfaces

Section titled “Deploy surfaces”
  • Platform staging Vercel host: canonical-platform-git-staging-tw-group.vercel.app
  • Two-server split (id-127): a dedicated Platform VPS physically separate from the client box, ONE Coolify control-plane (on the Platform box) managing both servers; reuse the existing Production/Staging Coolify creds (no new GH environment); distinguish by server + app UUID + deploy input.
  • GH environments (OQ-2 / id-95): ONE public repo; the Platform owns the GH Production/Staging environments; each client gets its own Vercel + Supabase project (config in the client’s Vercel env + tenant_config).
  • Pipeline ingress — the platform pair is PRIVATE (S558, 2026-08-12): ca-platform-pipeline-staging (S555) and ca-platform-pipeline (S558) on Server B sit behind a Cloudflare Tunnel + Access service-token policy — proxied tunnel CNAME, and Server B’s inbound 443+80 CLOSED at the VPS firewall. App→pipeline calls send CF-Access-Client-Id/-Secret (CF_ACCESS_* in Vercel Production+Preview and the GH Production/Staging environments); PIPELINE_TRIGGER_SECRET/EXTRACT_API_TOKEN are unchanged as the second factor; the external /health monitor is retired (DR-046). The two CLIENT pipeline hosts on Server A are still public — cutover ordered 3rd/4th. Procedure/rollback: runbooks/private-ingress-cutover.md.
  • Raindrop = local dev/CI eval tooling only (localhost:5899, zero egress — enforced in lib/eval/graduation.ts).

Key context anchors — read before re-deriving

Section titled “Key context anchors — read before re-deriving”

High-value prior-context records that carry settled platform facts. Read these instead of re-investigating from scratch:

AnchorHoldsRead via
okf-platform/corpus-reframe-review.htmlTHE corpus-model authority. R1 the evidence reframe (sources are evidence streams w/ per-binding retention class; supersedes the “client source files are the canonical content store” framing wherever it appears); R2 two gates — the light binding gate (connect a source, assign retention class, DR-020 restated) vs the authoritative knowledge-admission gate (promotion + dedup + confidence; ontology linter + publish gate). Read R1/R2 before naming anything in the source lifecyclethe doc itself (initiatives/core-product/knowledge-base-foundations/okf-platform/)
reference/entity-glossary.mdCanonical core-entity definitions (application_type, workspace-as-legacy, form, q_a_pair, containment chain), split out S504 R6 to be reused verbatim. Note: the source-lifecycle terms (binding gate, knowledge admission, retention classes) are NOT yet in it — see id-408the doc itself
reference/platform-direction.mdMission, five guiding principles, v1 shape. Names the four retention classes (keep-and-watch / ingest-once / live-connected / external-referenced) and uses knowledge-admission gate correctlythe doc itself
reference/deployment-architecture.mdTHE durable client+platform deployment topology: servers, public/private surface table, OKF three-layer model, corpus admission, goose, per-client rolloutthe doc itself
Retro S410platform config: the squash-baseline schema-only gap, id-127 two-server amendment, OQ-2 GH-environments resolution, api anon-revoke posturesrc/content/docs/ledgers/retros/S410.md
Diary S428 (wing_claude, 2026-06-28)OKF record-model: the four-DB correction (origin), L-raw/L-records/L-concepts model, {131.20} search redesignmempalace_diary_read agent=claude wing=wing_claude (find the 2026-06-28 entry)
reference_items ≠ source_documents (key pivot; owner, S511 board)Reference items and source documents are SEPARATE concepts — the pivot gave references their own nav surface + detail pages. reference_items.source_document_id is a live provenance FK (NOT NULL, ON DELETE RESTRICT; reference_ingest() mints a 1:1 sd row by design), NOT identity coupling — and pre-launch, “it’s enforced in prod” carries zero architectural weight. Whether a reference should mint a synthetic sd row at all is id-364 F1’s open question.specs/id-370-unanswered-question-routing/RESEARCH.md §5; pivot lineage in specs/id-110-url-import-reference-items/ + 20260708160000_id139 migration

Evidence precedence — docs outrank code (added S515, owner directive)

Section titled “Evidence precedence — docs outrank code (added S515, owner directive)”

The reference set, runbooks, platform-direction.md, the OKF doctrine and corpus-reframe-review.html were deliberately corrected so the platform has a north star, precisely because the codebase is known to be inaccurate. Large parts of the tree are half-repointed work that later sessions are fixing.

Therefore, when deciding what is correct:

  1. Ratified docs are the authority. corpus-reframe-review.html (R1–R8), the Decision Register, platform-direction.md, reference/entity-glossary.md, the OKF doctrine, then the task’s own spec chain.
  2. Code is evidence of what exists, never of what is correct. In rebase-class work (initiative 12 especially) an existing reference is the symptom under investigation, not proof the thing is right.
  3. These readings are NOT evidence of correctness — each produced a wrong verdict in S515, and each is a trap that looks like diligence:
    • “N production callers import it, so it is live.” Many callers is exactly what incomplete repointing looks like. Check whether the callers were migrated — S515 found one module with 18 callers of which one passed the current fields.
    • “There are rows in the DB, so the write path works.” Platform staging AND prod are internal dev environments pre-launch. A populated column proves nothing; an empty one may be merely unexercised, not dead.
    • “Grep found nothing, so the design never existed / was abandoned.” Absence is the thing being fixed. Confirm intent against the docs before concluding.
    • “Every assertion binds a live table, so this spec matches the model.” A test can bind live tables while asserting a retired concept. Check the naming and framing, not only the identifiers.
  4. A term with no glossary entry is a drift risk. Definitions belong in reference/entity-glossary.md, reused verbatim (S504 R6). A coinage that only ever appeared in a session working note is not vocabulary — S515 found one such term in 10 code sites and 0 decision records.

Applies to sub-agent dispatch too: a brief that cites only task files, specs and code will reproduce the codebase’s errors. Cite the north-star docs and this rule.

Not every doc is a north-star doc (owner ruling, S516)

Section titled “Not every doc is a north-star doc (owner ruling, S516)”

DR-104 says ratified docs outrank code. It does not say every document in the docs-site is current. Two large families are stale, and S516 produced two wrong verdicts in one session by citing them:

  • initiatives/core-product/canonical-pipeline/intended-architecture/ — stale, EXCEPT 01-vision.md. Owner, S516: “the intended-architecture docs, except 01-vision.md, are now incredibly out of date.” That includes 09-diagrams.md and 02-data-flow.md. Note 09-diagrams.md is doubly weak as evidence: its own §1 boundary 1 is “no new schema or flow content” and it sources column lists from supabase/types/database.types.ts — an ERD traced from the generated types shows what EXISTS, so citing it is DR-104’s code-evidence trap one step removed.
  • 07-collapse-list.md is the qualified case — do not dismiss it wholesale. Owner, S516: “collapse-list was originally accurate, so most of what it retires is correct, but I do think some items flipped later in the project.” Read it asymmetrically:
    • Its [RATIFIED-RETIRE] rows are usually still sound — it is a reasonable starting citation for a retire, subject to checking whether that specific item flipped in a later ruling.
    • Its retain / NOT-COLLAPSING entries are the ones most likely to have flipped, and they carry no column-level detail — “the table is on the not-collapsing list” says nothing about which of its columns are in the target shape.
    • Absence from it is not evidence of anything — that is the standard absence trap, listed above.
  • canonical-pipeline/phase-0-investigation/ — the whole OQ-resolution chain (feedback-findings-review.md, phase-b-prerequisite-*). Historical record of how decisions were reached, not current authority.
  • Any spec or invariant belonging to a task id below ~130 is presumed stale unless a current document re-affirms it. Owner, S516: “if a reference task id is pre-130, it’s likely stale context.”

Read them for how the current state arose; never cite one as authority.

Two failure shapes, both seen in S516 on the same question:

  1. Following a citation instead of opening it. phase-b-prerequisite-1-verification.md states “RESOLVED-RETAIN per feedback-findings-review §5.2.1”. That document says DEFER-COCOINDEX — it does not contain the ruling attributed to it. When a verdict rests on “doc A says X per doc B”, read doc B.
  2. Retain-the-table read as retain-the-shape. A closing ruling can keep a table while enumerating a shape that excludes the columns you are asking about. Check what the ruling enumerated, not just its verdict word.

Read-never-written: which half is stale? (S516)

Section titled “Read-never-written: which half is stale? (S516)”

A column with readers and no writer has two possible diagnoses, and the default matters — S516 found three instances and they did NOT all resolve the same way.

The discriminator: does a current ratified writer exist that COULD have written the column and did not?

  • No such writer → the reader is right and the writer is missing. Wire it. (id-345 catalogue writer; id-407 source_documents.uploaded_by.)
  • Yes, and it deliberately omits the column → the reader outlived its model. “Wire the writer” is the wrong default; retiring the read surface may be right. (id-409 source_documents.parent_id/version: the ratified admission writer resolve_or_mint_source_identity omits both, and because identity is uuid5(NS,'sd:'||rel_path) with ON CONFLICT (id) DO NOTHING, a changed file at the same path resolves to the SAME row — the chain is unreachable by construction, not merely unwritten.)

Zero population never distinguishes the two. The writer’s column list does.

For pipeline/corpus work the current authority is: reference/cocoindex-pipeline.md, the cocoindex skill (scripts/.claude/skills/cocoindex/), corpus-reframe-review.html, the OKF doctrine, the Decision Register, and this page. The owner’s standing frame: “the correct approach is using cocoindex correctly” — a high-quality working pipeline aligned to cocoindex, not a KH-side reimplementation of what cocoindex already provides.

The nightly has never walked the Platform corpus (owner ruling, S522)

Section titled “The nightly has never walked the Platform corpus (owner ruling, S522)”

Two facts that will otherwise be re-derived every time someone opens the cocoindex lane. Both are load-bearing and neither is visible from the workflow file alone.

1. The walked corpus is the wrong corpus, not merely in the wrong place. cocoindex-nightly.yml docker cps form-extraction fixtures and walks only what individual tests stage. It has never seeded the vendored synthetic Platform corpus (scripts/cocoindex_pipeline/fixtures/platform-corpus/) as its baseline, so the lane has not been dogfooding the Platform E2E path at all — which is the entire reason the lane exists. Owner, S522:

Pointing to docs/testing/ was incorrect, and whilst repointing to form-extraction isn’t the correct approach, it’s also what led to the finding that neither location was correct, and pointing at the actual synthetic platform corpus had been missed entirely.

The best-practice mechanism already exists and should not be re-invented: deploy/onprem/sync-platform-corpus.sh (ID-134) treats the vendored tree as the single source of truth and stages it onto /cocoindex-state/corpus via rsync → docker cp, after which COCOINDEX_SOURCE_PATH points at it and a supervised /walk ingests it. Owned by id-412; grounding in specs/id-412-cocoindex-nightly-reliability/RESEARCH.md.

2. docs/testing/ no longer exists. It moved to scripts/tests/fixtures/form-extraction/templates/ (b9c55abf, 90cc3b03, eb9ccac9), and c64be60b then aligned the census gate and verify_driver dest paths to a flat verify/<basename> scheme. Any doc, spec or task citing a docs/testing/ path is stale — id-406’s entire AC set was, and had to be re-grounded. The relocation is not the fix for (1) and must not be read as progress on it.

Corollary for the corpus-content distinction, which is the shape of several live defects: a blank extraction form (form-extraction/templates/**) is not a content document. Tests that need prose — entity extraction, chunking, MIME-coverage — must consume Platform-corpus content docs; the form fixtures belong only to tests that genuinely exercise form extraction.

Runbook and References index (progressive disclosure)

Section titled “Runbook and References index (progressive disclosure)”

Authoritative depth lives in the runbooks and reference files — follow the pointer rather than duplicating.

Current

  • Deployment architecture (client + platform topology) → reference/deployment-architecture.md

  • CI topology + failure modes → runbooks/ci.md

  • GH environments → runbooks/github-environments.md (note: §8 “fork-per-client” model is superseded by the id-95 single-public-repo model)

  • Local development (default-DB topology refreshed S436) → runbooks/local-development.md

  • On-prem B1 deploy → runbooks/onprem-b1-deploy.md

  • Private pipeline ingress (Cloudflare Tunnel + Access; DR-046) → runbooks/private-ingress-cutover.md

  • Staging refresh → runbooks/staging-refresh.md

  • Secret rotation (pipeline + app surfaces) → runbooks/secret-rotation.md

  • Platform → client promote → runbooks/platform-to-client-promote.md

  • Per-client release pinning → runbooks/per-client-release-pins.md

  • Client app deploy → runbooks/client-app-deploy.md

  • Python ingestion pipeline built on cocoindex → reference/cocoindex-pipeline.md

  • The three-layer knowledge model (OKF) → initiatives/core-product/knowledge-base-foundations/okf-platform/bundle-doctrine.md + initiatives/core-product/knowledge-base-foundations/okf-platform/corpus-reframe-review.html

  • Ontology → initiatives/core-product/knowledge-base-foundations/ontology/, initiatives/core-product/knowledge-base-foundations/okf-platform/ontology-sync.md and docs/ontology/

  • Agentic approach → reference/platform-agents-architecture.md and specs/id-71-ai-tooling/

Known-stale (do not trust without verifying against the live state):

  • reference/_archive/state-of-the-product.md — archived S504 (R8); historical platform context only.