org-knowledge-layer 0.1.0__py3-none-any.whl

okl/seed/geospatial-enforcement-defects.json

@@ -0,0 +1,121 @@
+{
+  "_comment": "Enforcement/encoding-loop lessons earned in the geospatial pipeline (2026-08-02) while hardening PR #75's CI. All WORLD-FACTS — portable to any repo — so org-scoped: a repo's first `okl check` returns them before the same mistake recurs. Tagged 'method' (encoding-loop/CI discipline), plus 'geospatial'/'data-quality' where the class is subject-specific. No 'ci' tag exists in the controlled vocabulary yet; add one to store.py KNOWN_TAGS if this class grows. Review, then `okl seed seed/geospatial-enforcement-defects.json`.",
+  "nodes": [
+    {
+      "key": "d_invoked_by_nothing",
+      "type": "Defect", "scope": "org", "repo": "geospatial-ml-pipeline", "verified": true,
+      "found_by": "auditing the encoding-loop surfaces — the arch-reviewer, once actually run, caught a must-fix an automatic surface missed",
+      "title": "An 'enforcement surface' that only runs on-demand runs never",
+      "body": "The architecture-reviewer agent was listed in CLAUDE.md as one of the encoding-loop's enforcement surfaces, but was invoked by nothing — no hook, no CI job, only a human typing /check-rules. For the repo's whole life it never ran. A review agent, lint rule, or checklist with no mechanical trigger is documentation, not enforcement: it provides zero protection while appearing on the ledger as covered.",
+      "symptom": "a review agent / rule / checklist is described as enforcement but nothing automatically triggers it",
+      "fix": "wire it to a mechanical trigger (hook or CI job), or relabel it honestly as on-demand-only",
+      "tags": "method"
+    },
+    {
+      "key": "g_review_agent_in_ci",
+      "type": "Gate", "scope": "org", "repo": "geospatial-ml-pipeline", "verified": true,
+      "found_by": "architecture-review.yml — runs the reviewer agent headless on every PR diff",
+      "title": "Run the architecture/review agent headless in CI on every PR diff",
+      "body": "A CI job runs the review agent against `git diff origin/BASE...HEAD` on every PR and fails on any must-fix finding. Self-owned — does not depend on a third-party review SaaS. Soft-passes until its API-key secret is set so it never wedges merges before setup, then becomes a hard gate via branch protection. Portable to any repo that has a review agent or a written architecture checklist.",
+      "symptom": "architecture rules live only as an agent/checklist that a human must remember to run",
+      "fix": "add a CI job that runs the agent on the diff and fails on must-fix; soft-pass until the key is configured",
+      "tags": "method,agent-safety"
+    },
+    {
+      "key": "r_surface_needs_trigger",
+      "type": "Rule", "scope": "org", "repo": "geospatial-ml-pipeline", "verified": true,
+      "found_by": "CLAUDE.md 'What is AUTOMATIC vs what you must RUN' ledger",
+      "title": "Every enforcement surface needs a mechanical trigger and an honest AUTOMATIC-vs-RUN ledger",
+      "body": "Keep an explicit table of what runs automatically (hooks, CI) vs what a human must remember to run; a surface with no trigger belongs in the second column or nowhere. Update the ledger in the SAME change that adds or closes a gate — a ledger claiming coverage it doesn't have is worse than none, because it stops people looking.",
+      "symptom": "a rules doc lists surfaces without saying which actually run automatically",
+      "fix": "maintain an AUTOMATIC-vs-RUN ledger; update it whenever a gate is added or closed",
+      "tags": "method"
+    },
+    {
+      "key": "d_unpinned_linter",
+      "type": "Defect", "scope": "org", "repo": "geospatial-ml-pipeline", "verified": true,
+      "found_by": "ci-python.yml lint gate failing a branch that changed no linted code",
+      "title": "Unpinned linter/formatter in CI retro-fails a branch that changed nothing",
+      "body": "CI ran `pip install ruff` (unpinned). A new release (0.15→0.16) promoted rules to default (RUF059, I001, RUF012, SIM117) and failed a previously-green branch on pre-existing code the PR never touched. Any CI step installing a linter/formatter/type-checker without a pinned version is a time-bomb that fires on the vendor's release schedule, not yours.",
+      "symptom": "a CI lint/format/type step fails on code the PR didn't change, right after a tool release",
+      "fix": "pin the exact tool version; treat bumps as deliberate PRs that address the new findings",
+      "tags": "method"
+    },
+    {
+      "key": "r_pin_gating_tools",
+      "type": "Rule", "scope": "org", "repo": "geospatial-ml-pipeline", "verified": true,
+      "found_by": "the 0.15→0.16 ruff incident above",
+      "title": "Pin every tool that gates CI; an unpinned linter is a time-bomb",
+      "body": "Any tool whose output can fail a build — ruff, black, mypy, eslint, prettier, a Sonar scanner image — must be version-pinned in CI. Unpinned, the gate's behavior changes on the vendor's release cadence and fails work that changed nothing. Pin it; bump it in its own PR where the new findings are visible and addressed.",
+      "symptom": "a CI gate step runs `pip install <tool>` / `npm i -g <tool>` with no version",
+      "fix": "pin the exact version; bumps are deliberate PRs",
+      "tags": "method"
+    },
+    {
+      "key": "d_ungated_zone",
+      "type": "Defect", "scope": "org", "repo": "geospatial-ml-pipeline", "verified": true,
+      "found_by": "the arch-reviewer's 'ungated zone' checklist section — code outside the source roots",
+      "title": "Code outside the linter/type/scan source-roots is gated by nothing",
+      "body": "Python under olmoearth_run_data/ and docs/ was covered by no linter, no type-checker, no Sonar rule, and no AI-review path rule: CI ran ruff only on the package, sonar.sources listed three dirs, CodeRabbit path_instructions matched the package only, and the CI trigger paths didn't even fire on those dirs. Untyped params, bare excepts, and hardcoded-constant drift shipped straight through review because no gate watched that directory. Every repo has these zones; they must be enumerated, not assumed covered.",
+      "symptom": "a .py/.ts/.cs dir ships code but appears in no linter/type/scan source-root and no CI trigger path",
+      "fix": "add the dir to CI trigger paths + the lint/scan invocation; list remaining ungated zones in the ledger",
+      "tags": "method"
+    },
+    {
+      "key": "g_gate_every_dir",
+      "type": "Gate", "scope": "org", "repo": "geospatial-ml-pipeline", "verified": true,
+      "found_by": "ci-python.yml — added olmoearth_run_data to triggers + a dedicated repo-root lint step",
+      "title": "Gate every executable directory; lint each import-tree from its own root",
+      "body": "Add each shipping dir to the CI trigger paths and the lint/type/scan invocation. Subtlety: ruff's isort first-party detection is CWD-anchored, so `ruff check ../otherdir` from a subpackage classifies the other tree's sibling imports differently than the repo root would, and flags I001 in CI though it's clean locally. Give each import tree its own lint step with working-directory at that tree's root.",
+      "symptom": "lint clean locally but I001/import-order fails in CI, or a dir has no gate at all",
+      "fix": "one lint step per import-tree run from that tree's root; add every shipping dir to CI trigger paths",
+      "tags": "method"
+    },
+    {
+      "key": "d_cwd_isort",
+      "type": "Defect", "scope": "org", "repo": "geospatial-ml-pipeline", "verified": true,
+      "found_by": "reproducing the CI I001 locally by matching the working directory",
+      "title": "ruff isort is CWD-anchored: sibling imports sort differently from a subdir vs the repo root",
+      "body": "`ruff check ../olmoearth_run_data` invoked from the python-etl working dir classified the zone's sibling-module imports as third-party and demanded a different grouping than `ruff check olmoearth_run_data` from the repo root — so the same files passed locally (root) and failed in CI (subdir) with I001. The invocation's working directory determines first-party detection; reproduce a CI lint failure with the SAME cwd CI uses.",
+      "symptom": "ruff I001 in CI on files that pass ruff locally",
+      "fix": "lint each import tree from its own root (separate step, working-directory at that root)",
+      "tags": "method"
+    },
+    {
+      "key": "d_masked_gate_order",
+      "type": "Defect", "scope": "org", "repo": "geospatial-ml-pipeline", "verified": true,
+      "found_by": "a test failure that only appeared once the lint step ahead of it went green",
+      "title": "A failing early gate step masks a later gate's failure in the same job",
+      "body": "The CI python job ran ruff before pytest in one job; while ruff failed (the unpinned-bump debt) the job short-circuited before pytest, hiding a real test failure (a test fake's signature missing a newly-added kwarg). Fixing ruff 'revealed' a second red that had been there all along. A single job chaining gates reports only the first failure; green-after-fix is not proof the rest pass.",
+      "symptom": "fixing one CI failure immediately surfaces a different one that was always broken",
+      "fix": "after greening a gate, re-run the full downstream; prefer independent jobs so one red can't hide another",
+      "tags": "method"
+    },
+    {
+      "key": "r_single_source_sets",
+      "type": "Rule", "scope": "org", "repo": "geospatial-ml-pipeline", "verified": true,
+      "found_by": "architecture-reviewer must-fix: hardcoded 2020 in 5 places + a re-defined label frozenset",
+      "title": "Single-source a derived fact — including SETS and class schemes, not just scalars",
+      "body": "A canonical constant (IMAGERY_YEAR=2020) or set (INVASIVE_LABELS=frozenset({TAMARISK, RUSSIAN_OLIVE})) must be imported wherever used, never re-written as a literal. Re-hardcoding 2020 in five places, or re-defining the frozenset locally, is the same drift class: two definitions of one fact are two facts free to diverge. Applies equally to class-index schemes, label sets, peak-season months, and vintages.",
+      "symptom": "a module re-writes a constant, frozenset, or class-list that already exists as a canonical import",
+      "fix": "import the canonical constant/set; never restate it as a literal",
+      "tags": "method,data-quality"
+    },
+    {
+      "key": "d_month_range_28",
+      "type": "Defect", "scope": "org", "repo": "geospatial-ml-pipeline", "verified": true,
+      "found_by": "CodeRabbit review of a monthly-composite date range",
+      "title": "Monthly STAC query ending at day-28 drops days 29-31 of imagery",
+      "body": "A per-month scene search built as `{y}-{m}-01`/`{y}-{m}-28` silently omits days 29, 30, 31 — fewer candidate scenes and a possibly-worse least-cloudy pick. End the range at the first day of the FOLLOWING month (with December→January rollover) so every day is covered uniformly (28/29/30/31). It was inherited by copy into a second script before being caught.",
+      "symptom": "a monthly composite/search date range hard-codes -28 (or -30) as the month end",
+      "fix": "end at first-of-next-month with Dec→Jan rollover; covers all month lengths",
+      "tags": "geospatial"
+    }
+  ],
+  "edges": [
+    { "src": "g_review_agent_in_ci", "rel": "CATCHES", "dst": "d_invoked_by_nothing" },
+    { "src": "g_review_agent_in_ci", "rel": "ENCODES", "dst": "r_surface_needs_trigger" },
+    { "src": "g_gate_every_dir", "rel": "CATCHES", "dst": "d_ungated_zone" },
+    { "src": "g_gate_every_dir", "rel": "CATCHES", "dst": "d_cwd_isort" }
+  ]
+}

okl/seed/geospatial-eval-defects.json

@@ -0,0 +1,25 @@
+{
+  "_comment": "Experiment-methodology lessons from the geospatial repo Stage-2 (2026-08-04). The beetle-inversion RF arm returned a clean NEGATIVE: a pre-registered control vetoed an underpowered cross-era result, and leave-one-trip-out CV crashed on single-cluster field data. Both are WORLD-FACTS → org scope, portable to any repo running transfer/cross-era evals. Review, then `okl seed seed/geospatial-eval-defects.json`.",
+  "nodes": [
+    {
+      "key": "r_preregistered_control_vetoes",
+      "type": "Rule", "scope": "org", "repo": "geospatial-ml-pipeline", "verified": true,
+      "found_by": "phase3c beetle-inversion — the Russian-olive control dropped 0.285 where it should be flat",
+      "title": "A pre-registered negative control can VETO a transfer/cross-era result the sample is too small or confounded to support",
+      "body": "In a cross-era / cross-sensor / cross-domain comparison, add a control that SHOULD NOT move and declare it in advance. If the control moves, its movement is the noise floor — the claimed effect must clear it or the result is unproven. Pre-registering the control lets it VETO the result instead of being quietly dropped when inconvenient. In phase3c the tamarisk 'signal' moved ~0.05 while the Russian-olive control (the beetle doesn't touch it) moved 0.285 pre-beetle, so the beetle claim was unprovable on that data — and saying so honestly was only possible because the control was declared first.",
+      "symptom": "a small or confounded transfer experiment shows a modest effect in the hoped-for direction",
+      "fix": "pre-register a negative control that should be flat; require the effect to exceed the control's movement; if it doesn't, report a null, not a hint",
+      "tags": "eval-integrity,method,data-quality"
+    },
+    {
+      "key": "d_loo_group_single_class",
+      "type": "Defect", "scope": "org", "repo": "geospatial-ml-pipeline", "verified": true,
+      "found_by": "phase3c IndexError: predict_proba(...)[:, 1] out of bounds — a leave-one-trip-out fold was single-class",
+      "title": "Leave-one-group-out CV crashes or degenerates when a group can be single-class (one-cluster field data)",
+      "body": "Field campaigns cluster geographically, so grouping CV by field trip / site can hand a fold a training set with only ONE class present. The classifier then learns one class, predict_proba returns a single column, and a hard `[:, 1]` throws (or the fold is meaningless). Two fixes: (1) group by SPATIAL BLOCK — bin coordinates into tiles — so blocks within the one cluster mix classes; (2) map the positive-class column via `estimator.classes_` and handle the single-class fold gracefully, never hard-index `[:, 1]`.",
+      "symptom": "predict_proba(...)[:, 1] IndexError, or a grouped-CV fold with only one class present",
+      "fix": "spatial-block folds (bin lat/lon) instead of by-trip; index the positive column via classes_ and guard the degenerate fold",
+      "tags": "eval-integrity,method,data-quality"
+    }
+  ]
+}

okl/seed/rag-defects.json

@@ -0,0 +1,120 @@
+{
+ "_comment": "Seed for the OKL — real, dated, receipted lessons from the RAG service (Python/FastAPI RAG: Qdrant hybrid, Redis, Postgres, Ollama, deepeval). Eval-integrity and retrieval-vs-identity lessons are org-scoped (portable to any RAG/agent/ML-eval work); pipeline-plumbing quirks are scoped repo:python-rag-service.",
+ "nodes": [
+  {
+   "key": "qz_judge_crash",
+   "type": "Defect",
+   "scope": "org",
+   "repo": "python-rag-service",
+   "found_by": "commit 60bbed7",
+   "verified": true,
+   "title": "'LLM Judge 5.0/5.0' while 19 of 20 cases crashed — a metric that can't report its own failure rate",
+   "body": "The eval harness averaged only the cases that completed; one survived, scored 5, printed a perfect score. The most dangerous bug of the effort — it made everything downstream unfalsifiable. Portable fix: the summary LEADS with its own failure count and prints RESULTS NOT USABLE above a failure-rate threshold, before any score.",
+   "symptom": "a summary score prints while some cases threw or were skipped",
+   "fix": "lead the report with the crash/failure count; mark results unusable above threshold",
+   "tags": "eval-integrity"
+  },
+  {
+   "key": "qz_judge_self",
+   "type": "Defect",
+   "scope": "org",
+   "repo": "python-rag-service",
+   "found_by": "findings-log Part 2 #5",
+   "verified": true,
+   "title": "The LLM judge was grading its own homework (same model as the generator)",
+   "body": "The judge defaulted to the same model as the generator — a mirror, not a signal (its default was even an embedding model that can't generate). Portable rule: the judge must be a different model from the generator; refuse to run if they're equal.",
+   "symptom": "the eval's judge model equals (or defaults to) the generator model",
+   "fix": "require judge≠generator; refuse to run if they're equal",
+   "tags": "eval-integrity"
+  },
+  {
+   "key": "qz_crosstab",
+   "type": "Rule",
+   "scope": "org",
+   "repo": "python-rag-service",
+   "found_by": "findings-log Part 2 #6",
+   "verified": true,
+   "title": "Run the retrieval_hit × judge_score cross-tab — it names which component is actually failing",
+   "body": "A whole session optimized retrieval; the cross-tab revealed generation was the dominant failure mode. The conclusion 'agentic retrieval is architecturally weaker' was exactly backwards, and that eval-results doc was retracted. Portable: bake the precondition×outcome cross-tab into every eval run, not as a one-off.",
+   "tags": "eval-integrity"
+  },
+  {
+   "key": "qz_fixtures",
+   "type": "Defect",
+   "scope": "org",
+   "repo": "python-rag-service",
+   "found_by": "findings-log Part 3",
+   "verified": true,
+   "title": "Invented fixtures can't falsify assumptions the author holds",
+   "body": "Entity tests used invented fixtures (Apple_10K.html) and passed at 100% while the live index had exhibit number '10.1' indexed as a company. Fixtures written by the person who wrote the parser encode the same assumptions as the parser. Portable rule: test against real inputs sampled from the actual corpus, verbatim (the RAG service switched to its 25 real filenames).",
+   "tags": "eval-integrity,data-quality"
+  },
+  {
+   "key": "qz_identity",
+   "type": "Rule",
+   "scope": "org",
+   "repo": "python-rag-service",
+   "found_by": "findings-log Part 3/4 (the through-line)",
+   "verified": true,
+   "title": "Don't infer by resemblance what you can look up — document identity is indexed & pre-filtered, not ranked",
+   "body": "Semantic search ranks by content and cannot distinguish one document from another (every contract has a termination clause). A corpus-wide question ('do any two docs share a company?') is a GROUP BY, not a similarity question — a ranked retriever cannot answer it at any top-k. Make the model choose the constraint and make code satisfy it. Portable across RAG/agent retrieval design.",
+   "tags": "retrieval-design"
+  },
+  {
+   "key": "qz_wrong_corpus",
+   "type": "Defect",
+   "scope": "repo",
+   "repo": "python-rag-service",
+   "found_by": "commits 36db337, 8cab711",
+   "verified": true,
+   "title": "Different eval runs were measuring different Qdrant collections",
+   "body": "Four collections existed (python-rag-service_hybrid / _ids / _full (zero entities) / _entities); the container was hand-pointed at one while config.py named another. Runs were compared as if the same system. Fix: one canonical collection, strays deleted+tombstoned. Stack-specific (Qdrant), scoped repo.",
+   "tags": "python-rag,eval-integrity"
+  },
+  {
+   "key": "qz_broken_tool",
+   "type": "Defect",
+   "scope": "org",
+   "repo": "python-rag-service",
+   "found_by": "commits 8df8bbc, c1b80f5",
+   "verified": true,
+   "title": "An agent whose primary tool throws on every call measures a broken tool, not an architecture",
+   "body": "search_filtered defaulted to a paid Voyage reranker with no key configured and threw on every call; the agent burned its whole step budget retrying because the error told it nothing actionable. 'Agentic loses on the real corpus' measured that, not architecture. Portable: empty/failed results should return actionable guidance (e.g. the entity vocabulary) so the agent can self-correct.",
+   "tags": "agent-safety"
+  },
+  {
+   "key": "qz_unequal_budget",
+   "type": "Defect",
+   "scope": "org",
+   "repo": "python-rag-service",
+   "found_by": "findings-log Part 2 #4",
+   "verified": true,
+   "title": "Comparing arms with unequal budgets attributes the gap to the wrong cause",
+   "body": "search_corpus inherited top_k=3 (the FACTUAL default) while classic used 8 on the same COMPARISON question — comparing an agent given 3 chunks against a pipeline given 8 and blaming the architecture. Portable: give each arm the same retrieval/token budget before concluding anything about the arms.",
+   "tags": "eval-integrity"
+  },
+  {
+   "key": "qz_agent_contract",
+   "type": "Rule",
+   "scope": "org",
+   "repo": "python-rag-service",
+   "found_by": "docs/agent-contract.md",
+   "verified": true,
+   "title": "The agent's capability surface is an allowlist; side-effect machinery is built with the first mutating tool",
+   "body": "A tool exists only if registered; unknown names are never executed ('the loop must never invent capabilities'). Budgets (max steps, token budget, tool timeout) are explicit and env-overridable; finish is the explicit stop. A tool with side effects requires arg-schema validation, a pre-execution control mode (audit/approval/block), and severity-gated alerting BEFORE it ships — built deliberately with the first mutating tool, not speculatively. Portable agent-safety rule.",
+   "tags": "agent-safety"
+  }
+ ],
+ "edges": [
+  {
+   "src": "qz_crosstab",
+   "rel": "REFUTES",
+   "dst": "qz_judge_crash"
+  },
+  {
+   "src": "qz_fixtures",
+   "rel": "RECURS_IN",
+   "dst": "python-rag-service"
+  }
+ ]
+}

okl/seed/react-defects.json

@@ -0,0 +1,45 @@
+{
+ "_comment": "Seed for the OKL — React/frontend-SPA lessons ported from the .NET platform's frontend canon (frontend/CLAUDE.md + the vendored vercel-react-best-practices skill, frozen 2026-06-12). React is backend-agnostic, so these are org-scoped: they propagate to any repo with a React UI. This closes the coverage gap the A/B experiment measured — react_fetch reproduced the useEffect-fetching defect 3/3 in BOTH arms because no React node existed in the store to inject.",
+ "nodes": [
+  {
+   "key": "rx_useeffect_fetch",
+   "type": "Defect",
+   "scope": "org",
+   "repo": "dotnet-microservices",
+   "found_by": "frontend/CLAUDE.md + vercel-react-best-practices (You Might Not Need an Effect)",
+   "verified": true,
+   "title": "Hand-rolled data fetching in useEffect+useState reimplements caching/dedup/races badly",
+   "body": "cause: fetching server data inside a useEffect and storing it in useState re-derives — poorly — the caching, request dedup, race-cancellation, and refetch logic a query library already solves. .NET platform canon: ALL server data goes through TanStack Query v5; fetching-in-useEffect is banned. Query keys are [feature, entity, params].",
+   "symptom": "a component fetches from an API inside useEffect and stores the result in useState",
+   "fix": "use TanStack Query (useQuery) with a [feature,entity,params] key; reserve useEffect for non-data side effects only",
+   "tags": "react"
+  },
+  {
+   "key": "rx_tokens_localstorage",
+   "type": "Defect",
+   "scope": "org",
+   "repo": "dotnet-microservices",
+   "found_by": "frontend/CLAUDE.md (auth)",
+   "verified": true,
+   "title": "Access tokens in localStorage are XSS-exfiltratable",
+   "body": "cause: tokens in localStorage are readable by any script on the page, so one XSS steals the session. .NET platform canon: PKCE auth-code flow (oidc-client-ts → Keycloak), tokens held in memory; the localStorage-vs-BFF trade-off is documented, not defaulted.",
+   "symptom": "auth tokens written to or read from localStorage/sessionStorage",
+   "fix": "hold tokens in memory via the auth library; use PKCE; if persistence is required, document the BFF/cookie trade-off explicitly",
+   "tags": "react,security"
+  },
+  {
+   "key": "rx_fight_compiler",
+   "type": "Rule",
+   "scope": "org",
+   "repo": "dotnet-microservices",
+   "found_by": "vercel-react-best-practices",
+   "verified": true,
+   "title": "Don't fight the React Compiler — no manual memo when it's on",
+   "body": "With the React Compiler enabled, hand-written useMemo/useCallback/React.memo add noise and can pessimize. Let the compiler memoize; keep components pure. Bundle budget is CI-checked (≤200 KB gz); virtualize lists over ~50 items.",
+   "symptom": "manual useMemo/useCallback/React.memo added for performance while the React Compiler is enabled",
+   "fix": "remove the manual memoization; keep the component pure and let the compiler handle it",
+   "tags": "react"
+  }
+ ],
+ "edges": []
+}

okl/seed.py

@@ -0,0 +1,55 @@
+"""Seed the layer from a JSON file of nodes and edges.
+
+The canonical first seed is the geospatial pipeline's defect table + the gates
+that catch each defect — so a brand-new repo's very first `okl check` can return
+a real, earned lesson (e.g. error #14's class-path gate) rather than an empty set.
+
+File format:
+{
+  "nodes": [ {"key": "d14", "type": "Defect", "title": "...", "scope": "org", ...}, ... ],
+  "edges": [ {"src": "g_classpath", "rel": "CATCHES", "dst": "d14"}, ... ]
+}
+`key` is a local alias used only to wire edges within the file; the store
+assigns the real id. Edges reference keys, which are resolved to ids on load.
+"""
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+from .client import Client
+
+
+def seed_from_file(client: Client, path: str) -> int:
+    """Ingest a *-defects.json file. Idempotent: re-seeding the same file REPLACES
+    its own nodes instead of duplicating them.
+
+    Each node's stable id is derived from the seed file's stem + the node's local
+    `key` (e.g. `seed:geospatial-defects:d14`). `key` remains the in-file alias used
+    to wire edges; here it does double duty as the persistent identity so a second
+    `okl seed` run upserts the same rows. A node without a `key` falls back to a
+    fresh random id (non-idempotent) — every bundled seed node has a key.
+    """
+    p = Path(path)
+    data = json.loads(p.read_text())
+    ns = f"seed:{p.stem}"
+    keymap: dict[str, str] = {}
+    for node in data.get("nodes", []):
+        key = node.pop("key", None)
+        # Seed nodes carry provenance from ANOTHER repo. Client.record defaults a
+        # missing `repo` to the CURRENT repo, which would mislabel it — pass None
+        # explicitly ("unknown") and warn, rather than inherit that default.
+        if "repo" not in node:
+            node["repo"] = None
+            print(f"  ! {key or node.get('title', '?')}: seed node has no 'repo' — "
+                  "recording provenance as unknown, not this repo", file=sys.stderr)
+        stable_id = f"{ns}:{key}" if key else None
+        node_id = client.record(id=stable_id, **node) if stable_id else client.record(**node)
+        if key:
+            keymap[key] = node_id
+    for edge in data.get("edges", []):
+        src = keymap.get(edge["src"], edge["src"])
+        dst = keymap.get(edge["dst"], edge["dst"])
+        client.link(src, edge["rel"], dst)
+    return len(data.get("nodes", []))

okl/service.py

@@ -0,0 +1,137 @@
+"""The shared OKL service — a small FastAPI app exposing check/record/search/link.
+
+This is the "option 3" piece: one always-on service that owns the database, so
+any repo on any machine reaches the SAME curated knowledge via a URL. Storage is
+selected by OKL_DATABASE_URL (sqlite:///okl.db default, or postgres://... when
+you deploy) — the code here never changes when you promote the backend.
+
+Run: `okl serve` (or `uvicorn okl.service:app`).
+"""
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from . import core
+from .store import Store
+
+try:
+    from fastapi import FastAPI, Header, HTTPException
+    from pydantic import BaseModel
+except ImportError as e:  # pragma: no cover
+    raise RuntimeError("The service needs FastAPI — install okl[service]") from e
+
+
+class CheckReq(BaseModel):
+    repo: str
+    task: str
+    limit: int = 12
+    interests: list[str] | None = None   # the calling repo's declared subject tags
+
+
+class RecordReq(BaseModel):
+    type: str
+    title: str
+    scope: str
+    repo: str | None = None
+    body: str | None = None
+    status: str | None = None
+    found_by: str | None = None
+    ttl_days: int | None = None
+    owner: str | None = None
+    files: str | None = None
+    symptom: str | None = None
+    fix: str | None = None
+    tags: str | None = None
+    id: str | None = None
+    verified: bool = False
+
+
+class SearchReq(BaseModel):
+    query: str
+    scope: str | None = None
+    node_types: list[str] | None = None
+    limit: int = 25
+
+
+class LinkReq(BaseModel):
+    src: str
+    rel: str
+    dst: str
+
+
+class VerifyReq(BaseModel):
+    id: str
+    evidence: str   # the observed check that passed (command + timestamp)
+
+
+def create_app(store: Store | None = None) -> FastAPI:
+    app = FastAPI(title="OKL — the sixth surface", version="0.1.0")
+    _store = store or Store(os.environ.get("OKL_DATABASE_URL"))
+    # Optional shared-secret gate. If OKL_TOKEN is set, writes require it.
+    write_token = os.environ.get("OKL_TOKEN")
+
+    def _auth(authorization: str | None) -> None:
+        if write_token and authorization != f"Bearer {write_token}":
+            raise HTTPException(status_code=401, detail="missing or bad bearer token")
+
+    @app.get("/health")
+    def health() -> dict[str, Any]:
+        return {"ok": True, "nodes": len(_store.all_nodes()), "backend": _store.url.split(":")[0]}
+
+    @app.post("/check")
+    def check(req: CheckReq) -> dict[str, Any]:
+        return core.check(_store, req.repo, req.task, limit=req.limit,
+                          interests=req.interests)
+
+    @app.post("/record")
+    def record(req: RecordReq, authorization: str | None = Header(default=None)) -> dict[str, str]:
+        _auth(authorization)
+        try:
+            node_id = core.record(_store, **req.model_dump())
+        except ValueError as e:
+            # Validation (unknown tag, bad scope) is the CALLER's error and must carry the
+            # message (e.g. the tag vocabulary) — a 500 hides it and reads as an outage.
+            raise HTTPException(status_code=400, detail=str(e)) from e
+        return {"id": node_id}
+
+    @app.post("/search")
+    def search(req: SearchReq) -> dict[str, Any]:
+        return {"results": core.search(_store, req.query, req.scope, req.node_types, req.limit)}
+
+    @app.post("/link")
+    def link(req: LinkReq, authorization: str | None = Header(default=None)) -> dict[str, bool]:
+        _auth(authorization)
+        core.link(_store, req.src, req.rel, req.dst)
+        return {"ok": True}
+
+    @app.post("/verify")
+    def verify(req: VerifyReq, authorization: str | None = Header(default=None)) -> dict[str, Any]:
+        _auth(authorization)
+        try:
+            return core.verify(_store, req.id, req.evidence)
+        except ValueError as e:
+            raise HTTPException(status_code=400, detail=str(e)) from e
+
+    @app.get("/metric/recurrence")
+    def recurrence() -> dict[str, Any]:
+        rows = _store.recurrence_after_arming()
+        return {"recurrence_after_arming": rows, "count": len(rows)}
+
+    @app.get("/nodes")
+    def nodes() -> dict[str, Any]:
+        from dataclasses import asdict
+        rows = [asdict(n) for n in _store.all_nodes()]
+        return {"nodes": rows, "count": len(rows)}
+
+    return app
+
+
+app = None
+
+
+def run(host: str = "0.0.0.0", port: int = 8080) -> None:
+    import uvicorn
+    global app
+    app = create_app()
+    uvicorn.run(app, host=host, port=port)