leyline-code 0.8.1__py3-none-any.whl

leyline/roslyn_refs/Program.cs

@@ -0,0 +1,179 @@
+// Reads a manifest of C# modules, binds each with the compiler, and prints one JSON line per
+// call or field access that the compiler resolved to a declaration in the same workspace.
+//
+//   dotnet run -- manifest.json > refs.jsonl
+//
+// manifest: {"root": "...", "modules": [{"name": "...", "files": ["rel/path.cs"], "refs": ["other module"]}]}
+using System.Text;
+using System.Text.Json;
+using Microsoft.CodeAnalysis;
+using Microsoft.CodeAnalysis.CSharp;
+using Microsoft.CodeAnalysis.CSharp.Syntax;
+
+var manifest = JsonDocument.Parse(File.ReadAllText(args[0])).RootElement;
+var root = manifest.GetProperty("root").GetString();
+var modules = manifest.GetProperty("modules").EnumerateArray().ToList();
+
+// Framework reference assemblies: the newest pack under the running SDK's root.
+var dotnetRoot = Path.GetFullPath(Path.Combine(Path.GetDirectoryName(typeof(object).Assembly.Location), "..", "..", ".."));
+var packs = Path.Combine(dotnetRoot, "packs", "Microsoft.NETCore.App.Ref");
+var refDir = Directory.Exists(packs)
+    ? Directory.GetDirectories(packs).OrderBy(d => d).Select(d => Directory.GetDirectories(Path.Combine(d, "ref")).FirstOrDefault()).LastOrDefault(d => d != null)
+    : Path.GetDirectoryName(typeof(object).Assembly.Location);
+var framework = Directory.GetFiles(refDir, "*.dll").Select(f => (MetadataReference)MetadataReference.CreateFromFile(f)).ToList();
+
+var built = new Dictionary<string, CSharpCompilation>();
+var stdout = new StreamWriter(Console.OpenStandardOutput(), new UTF8Encoding(false)) { AutoFlush = false };
+var pending = modules.ToList();
+// The compiler parses and binds recursively; deeply nested code (a long else-if chain, a generated expression)
+// overflows the main thread's stack, which ends the process. A worker thread gets a 1 GB stack instead.
+var work = new Thread(() => {
+while (pending.Count > 0)
+{
+    // A module is ready when everything it references is built; a cycle is broken by taking the first.
+    var next = pending.FirstOrDefault(m => m.GetProperty("refs").EnumerateArray().All(r => built.ContainsKey(r.GetString()) || !modules.Any(x => x.GetProperty("name").GetString() == r.GetString())));
+    if (next.ValueKind == JsonValueKind.Undefined) next = pending[0];
+    pending.Remove(next);
+    var name = next.GetProperty("name").GetString();
+    var trees = new List<SyntaxTree>();
+    var options = new CSharpParseOptions(LanguageVersion.Preview);
+    foreach (var f in next.GetProperty("files").EnumerateArray())
+    {
+        var rel = f.GetString();
+        var path = Path.Combine(root, rel);
+        if (File.Exists(path)) trees.Add(CSharpSyntaxTree.ParseText(File.ReadAllText(path), options, rel));
+    }
+    // Projects that use implicit usings compile against these; adding them never hides a real error we care about.
+    trees.Add(CSharpSyntaxTree.ParseText("global using System; global using System.Collections.Generic; global using System.IO; global using System.Linq; global using System.Threading; global using System.Threading.Tasks;", options, "<implicit>"));
+    var refs = new List<MetadataReference>(framework);
+    foreach (var r in next.GetProperty("refs").EnumerateArray())
+        if (built.TryGetValue(r.GetString(), out var dep)) refs.Add(dep.ToMetadataReference());
+    var compilation = CSharpCompilation.Create(name, trees, refs,
+        new CSharpCompilationOptions(OutputKind.DynamicallyLinkedLibrary, allowUnsafe: true, nullableContextOptions: NullableContextOptions.Enable));
+    built[name] = compilation;
+
+    int ok = 0, candidate = 0, none = 0, outside = 0;
+    foreach (var tree in trees)
+    {
+        if (tree.FilePath == "<implicit>") continue;
+        var model = compilation.GetSemanticModel(tree);
+        foreach (var node in tree.GetRoot().DescendantNodes())
+        {
+            switch (node)
+            {
+                case InvocationExpressionSyntax inv:
+                {
+                    var nameNode = inv.Expression switch
+                    {
+                        MemberAccessExpressionSyntax m => (SyntaxNode)m.Name,
+                        MemberBindingExpressionSyntax b => b.Name,
+                        _ => inv.Expression,
+                    };
+                    var written = nameNode is SimpleNameSyntax s ? s.Identifier.ValueText : null;
+                    if (written == null || written == "nameof") break;
+                    EmitCall(model.GetSymbolInfo(inv), written, nameNode.GetLocation(), ref ok, ref candidate, ref none, ref outside);
+                    break;
+                }
+                case BaseObjectCreationExpressionSyntax made:
+                    EmitCall(model.GetSymbolInfo(made), ".ctor", made.GetLocation(), ref ok, ref candidate, ref none, ref outside);
+                    break;
+                case ConstructorInitializerSyntax init:
+                    EmitCall(model.GetSymbolInfo(init), ".ctor", init.GetLocation(), ref ok, ref candidate, ref none, ref outside);
+                    break;
+                case IdentifierNameSyntax id:
+                {
+                    if (id.Parent is InvocationExpressionSyntax call && call.Expression == id) break;
+                    if (id.Parent is MemberAccessExpressionSyntax ma && ma.Name == id && ma.Parent is InvocationExpressionSyntax) break;
+                    var symbol = model.GetSymbolInfo(id).Symbol;
+                    if (symbol is not (IFieldSymbol or IPropertySymbol)) break;
+                    if (symbol is IFieldSymbol { ContainingType.TypeKind: TypeKind.Enum }) break;
+                    var decl = Declared(symbol);
+                    if (decl == null) break;
+                    Emit(Access(id), id.GetLocation(), symbol.Name, decl.Value.file, decl.Value.line, "ok");
+                    break;
+                }
+            }
+        }
+    }
+    // Per file: how many binding errors, so a reader knows whether "nothing found" means "nothing there".
+    foreach (var tree in trees)
+    {
+        if (tree.FilePath == "<implicit>") continue;
+        var errors = compilation.GetSemanticModel(tree).GetDiagnostics().Count(d => d.Severity == DiagnosticSeverity.Error);
+        stdout.WriteLine("{\"k\":\"file\",\"f\":" + JsonSerializer.Serialize(tree.FilePath) + ",\"e\":" + errors + "}");
+    }
+    Console.Error.WriteLine($"{name}: {trees.Count - 1} files, {ok} calls bound, {candidate} by candidate, {none} unbound, {outside} to code outside");
+}
+}, 1 << 30);
+work.Start();
+work.Join();
+stdout.Flush();
+
+void EmitCall(SymbolInfo info, string written, Location at, ref int ok, ref int candidate, ref int none, ref int outside)
+{
+    var symbol = info.Symbol as IMethodSymbol;
+    var state = "ok";
+    if (symbol == null && info.CandidateSymbols.Length == 1) { symbol = info.CandidateSymbols[0] as IMethodSymbol; state = "candidate"; }
+    if (symbol == null)
+    {
+        // Several candidates, or none: the compiler could not settle it (often a missing package). Say so.
+        none++;
+        Emit("call", at, written, null, 0, info.CandidateSymbols.Length > 1 ? "ambiguous" : "none");
+        return;
+    }
+    if (symbol.MethodKind == MethodKind.LocalFunction || symbol.MethodKind == MethodKind.Ordinary || symbol.MethodKind == MethodKind.Constructor
+        || symbol.MethodKind == MethodKind.ReducedExtension || symbol.MethodKind == MethodKind.UserDefinedOperator || symbol.MethodKind == MethodKind.DelegateInvoke)
+    {
+        var target = (symbol.ReducedFrom ?? symbol).OriginalDefinition;
+        if (target.PartialImplementationPart != null) target = target.PartialImplementationPart;
+        var decl = Declared(target);
+        if (decl == null) { outside++; Emit("call", at, written, null, 0, "outside"); return; }
+        if (state == "ok") ok++; else candidate++;
+        Emit("call", at, written, decl.Value.file, decl.Value.line, state, target.MethodKind == MethodKind.Constructor ? ".ctor" : target.Name);
+    }
+}
+
+(string file, int line)? Declared(ISymbol symbol)
+{
+    foreach (var r in symbol.OriginalDefinition.DeclaringSyntaxReferences)
+    {
+        if (r.SyntaxTree.FilePath == "<implicit>") continue;
+        var syntax = r.GetSyntax();
+        // A field is declared inside a declaration that may hold several: point at the whole statement.
+        if (syntax is VariableDeclaratorSyntax && syntax.Parent?.Parent is BaseFieldDeclarationSyntax whole) syntax = whole;
+        return (r.SyntaxTree.FilePath, syntax.GetLocation().GetLineSpan().StartLinePosition.Line + 1);
+    }
+    return null;
+}
+
+string Access(IdentifierNameSyntax id)
+{
+    SyntaxNode cur = id;
+    if (cur.Parent is MemberAccessExpressionSyntax m && m.Name == id) cur = m;
+    while (cur.Parent is ParenthesizedExpressionSyntax p) cur = p;
+    var up = cur.Parent;
+    if (up is AssignmentExpressionSyntax a && a.Left == cur)
+    {
+        if (a.Parent is InitializerExpressionSyntax) return "init";
+        return a.IsKind(SyntaxKind.SimpleAssignmentExpression) ? "write" : "readwrite";
+    }
+    if (up is PostfixUnaryExpressionSyntax || up is PrefixUnaryExpressionSyntax pre && (pre.IsKind(SyntaxKind.PreIncrementExpression) || pre.IsKind(SyntaxKind.PreDecrementExpression)))
+        return up is PostfixUnaryExpressionSyntax post && post.IsKind(SyntaxKind.SuppressNullableWarningExpression) ? "read" : "readwrite";
+    if (up is ArgumentSyntax arg && !arg.RefKindKeyword.IsKind(SyntaxKind.None))
+        return arg.RefKindKeyword.IsKind(SyntaxKind.OutKeyword) ? "write" : arg.RefKindKeyword.IsKind(SyntaxKind.RefKeyword) ? "readwrite" : "read";
+    if (up is ElementAccessExpressionSyntax e && e.Expression == cur && e.Parent is AssignmentExpressionSyntax ea && ea.Left == e) return "readwrite";
+    return "read";
+}
+
+void Emit(string kind, Location at, string written, string targetFile, int targetLine, string state, string targetName = null)
+{
+    var pos = at.GetLineSpan();
+    var sb = new StringBuilder(160);
+    sb.Append("{\"k\":\"").Append(kind).Append("\",\"f\":").Append(JsonSerializer.Serialize(pos.Path))
+      .Append(",\"l\":").Append(pos.StartLinePosition.Line + 1).Append(",\"n\":").Append(JsonSerializer.Serialize(written))
+      .Append(",\"s\":\"").Append(state).Append('"');
+    if (targetFile != null) sb.Append(",\"tf\":").Append(JsonSerializer.Serialize(targetFile)).Append(",\"tl\":").Append(targetLine)
+        .Append(",\"tn\":").Append(JsonSerializer.Serialize(targetName ?? written));
+    sb.Append('}');
+    stdout.WriteLine(sb.ToString());
+}

leyline/roslyn_refs/RoslynRefs.csproj

@@ -0,0 +1,16 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <!-- Built against the compiler that ships inside the .NET SDK, so it needs no package restore. -->
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net8.0</TargetFramework>
+    <Nullable>disable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <RollForward>Major</RollForward>
+    <SatelliteResourceLanguages>en</SatelliteResourceLanguages>
+    <NoWarn>$(NoWarn);CS8632;MSB3277</NoWarn>
+  </PropertyGroup>
+  <ItemGroup>
+    <Reference Include="Microsoft.CodeAnalysis"><HintPath>$(MSBuildToolsPath)/Roslyn/bincore/Microsoft.CodeAnalysis.dll</HintPath></Reference>
+    <Reference Include="Microsoft.CodeAnalysis.CSharp"><HintPath>$(MSBuildToolsPath)/Roslyn/bincore/Microsoft.CodeAnalysis.CSharp.dll</HintPath></Reference>
+  </ItemGroup>
+</Project>

leyline/rules.py

@@ -0,0 +1,171 @@
+"""Architecture rules: constraints over the graph that are checked without any inference.
+
+A rule is the user's intent. An agent may suggest one, but a suggested rule stays marked as
+suggested until the user confirms it.
+"""
+
+from __future__ import annotations
+
+import datetime
+import json
+from collections import defaultdict
+from typing import Optional
+
+from . import store
+
+KINDS = ("forbid", "no_cycle", "must_be_tested")
+EDGE_KINDS = ("calls", "imports", "uses_type", "instantiates", "extends", "implements", "depends_on", "communicates",
+              "reads", "writes")
+# What a forbid rule looks at unless told otherwise. A channel is left out: the sender of an event
+# does not depend on whoever listens to it.
+DEPENDENCY_KINDS = ("calls", "imports", "uses_type", "instantiates", "extends", "implements", "depends_on", "reads", "writes")
+
+
+def _select(con, selector: str) -> set[str]:
+    """Node ids a selector covers. Forms: module:Name, system:Name, external:Name, path:prefix, id:prefix, *"""
+    selector = selector.strip()
+    if selector == "*":
+        return {r[0] for r in con.execute("SELECT id FROM nodes WHERE layer = 'fact'")}
+    kind, _, value = selector.partition(":")
+    if kind == "module":
+        row = con.execute("SELECT id FROM nodes WHERE kind = 'module' AND (name = ? OR path = ?)", (value, value)).fetchone()
+        if not row:
+            return set()
+        return {row[0]} | {r[0] for r in con.execute("SELECT node_id FROM ancestry WHERE module_id = ?", (row[0],))}
+    if kind == "system":
+        row = con.execute(
+            "SELECT n.id FROM nodes n LEFT JOIN annotations a ON a.node_id = n.id AND a.key = 'name'"
+            " WHERE n.kind = 'system' AND (a.value = ? OR n.name = ?)", (value, value)).fetchone()
+        if not row:
+            return set()
+        out = set()
+        for u in con.execute("SELECT dst_id FROM edges WHERE kind = 'groups' AND src_id = ?", (row[0],)):
+            out |= {r[0] for r in con.execute(
+                "WITH RECURSIVE d(id) AS (SELECT ? UNION SELECT n.id FROM nodes n JOIN d ON n.parent_id = d.id)"
+                " SELECT id FROM d", (u[0],))}
+        return out
+    # A name or prefix as written: LIKE would read `_` and `%` in it as patterns, and ignore case.
+    if kind == "external":
+        return {r[0] for r in con.execute("SELECT id FROM nodes WHERE kind = 'external' AND (name = ? OR substr(name, 1, ?) = ?)",
+                                          (value, len(value) + 1, value + "."))}
+    if kind == "path":
+        under = value.rstrip("/") + "/"
+        return {r[0] for r in con.execute("SELECT id FROM nodes WHERE path = ? OR substr(path, 1, ?) = ?",
+                                          (value, len(under), under))}
+    if kind == "id":
+        return {r[0] for r in con.execute("SELECT id FROM nodes WHERE substr(id, 1, ?) = ?", (len(value), value))}
+    return set()
+
+
+def add_rule(con, kind: str, selector_from: str, selector_to: str = "", edge_kinds: Optional[list[str]] = None,
+             severity: str = "error", reason: str = "", status: str = "suggested", source: str = "mcp") -> dict:
+    if kind not in KINDS:
+        return {"error": f"kind must be one of {KINDS}"}
+    if status not in ("suggested", "confirmed"):
+        return {"error": "status must be suggested or confirmed"}
+    if kind == "forbid" and not selector_to:
+        return {"error": "a forbid rule needs selector_to"}
+    if kind != "no_cycle" and not _select(con, selector_from):
+        return {"error": f"selector {selector_from!r} matches nothing"}
+    if kind == "forbid" and not _select(con, selector_to):
+        return {"error": f"selector {selector_to!r} matches nothing"}
+    with con:
+        cur = con.execute(
+            "INSERT INTO rules (kind, selector_from, selector_to, edge_kinds, severity, reason, status, source, created)"
+            " VALUES (?,?,?,?,?,?,?,?,?)",
+            (kind, selector_from, selector_to, json.dumps(edge_kinds or []), severity, reason, status, source,
+             datetime.datetime.now(datetime.timezone.utc).isoformat(timespec="seconds")))
+    return {"id": cur.lastrowid, "kind": kind, "status": status}
+
+
+def confirm_rule(con, rule_id: int) -> dict:
+    with con:
+        n = con.execute("UPDATE rules SET status = 'confirmed' WHERE id = ?", (rule_id,)).rowcount
+    return {"id": rule_id, "status": "confirmed"} if n else {"error": f"no rule {rule_id}"}
+
+
+def _links(con, kinds: list[str], sure_only: bool = False):
+    """The links a rule reads. `sure_only` leaves out links the map guessed by name (a call is a guess only when
+    every call site behind it is one)."""
+    kinds = kinds or list(DEPENDENCY_KINDS)
+    if "calls" in kinds:
+        q = ("SELECT src_id, dst_id FROM calls GROUP BY src_id, dst_id HAVING MIN(precision = 'guess') = 0"
+             " ORDER BY dst_id, src_id" if sure_only else "SELECT DISTINCT src_id, dst_id FROM calls ORDER BY dst_id, src_id")
+        for r in con.execute(q):
+            yield r[0], r[1], "calls"
+    rest = [k for k in kinds if k != "calls"]
+    if rest:
+        sure = " AND (precision IS NULL OR precision != 'guess')" if sure_only else ""
+        for r in con.execute(f"SELECT src_id, dst_id, kind FROM edges WHERE kind IN ({','.join('?' * len(rest))}){sure}", rest):
+            yield r[0], r[1], r[2]
+
+
+def check(con, rules_from=None, sure_only: bool = False) -> dict:
+    """Evaluate every rule against the graph in `con`. `rules_from` reads the rules from another store.
+    `sure_only` reads no link the map guessed by name, so a rule that fails only through guesses passes."""
+    names = {r["id"]: r["name"] for r in con.execute("SELECT id, name FROM nodes")}
+    out = []
+    for rule in (rules_from or con).execute("SELECT * FROM rules ORDER BY id").fetchall():
+        kinds = json.loads(rule["edge_kinds"] or "[]")
+        violations = []
+        if rule["kind"] == "forbid":
+            a, b = _select(con, rule["selector_from"]), _select(con, rule["selector_to"])
+            for s, d, k in _links(con, kinds, sure_only):
+                if s in a and d in b:
+                    violations.append({"from": s, "to": d, "kind": k})
+        elif rule["kind"] == "no_cycle":
+            # Scope: "modules", or "systems" for systems and ungrouped types across the repo.
+            scope = (rule["selector_from"] or "modules").strip()
+            group = {r["node_id"]: r["module_id"] for r in con.execute("SELECT node_id, module_id FROM ancestry")}
+            if scope.startswith("system"):
+                unit_sys = {r["dst_id"]: r["src_id"] for r in con.execute("SELECT src_id, dst_id FROM edges WHERE kind = 'groups'")}
+                parent = {r["id"]: r["parent_id"] for r in con.execute("SELECT id, parent_id FROM nodes")}
+                def owner(i):
+                    cur = i
+                    while cur:
+                        if cur in unit_sys:
+                            return unit_sys[cur]
+                        cur = parent.get(cur)
+                    return None
+                group = {i: owner(i) for i in parent}
+            graph = defaultdict(set)
+            for s, d, k in _links(con, kinds or ["calls", "uses_type", "instantiates", "extends", "implements", "imports"],
+                                 sure_only):
+                gs, gd = group.get(s), group.get(d)
+                if gs and gd and gs != gd:
+                    graph[gs].add(gd)
+            seen, done = set(), set()
+
+            def visit(v, path):
+                seen.add(v)
+                for w in sorted(graph[v]):
+                    if w in path:
+                        cyc = path[path.index(w):] + [w]
+                        key = tuple(sorted(cyc[:-1]))
+                        if key not in done:
+                            done.add(key)
+                            violations.append({"cycle": [names.get(c, c) for c in cyc], "ids": cyc})
+                    elif w not in seen:
+                        visit(w, path + [w])
+            for v in sorted(graph):
+                if v not in seen:
+                    visit(v, [v])
+        elif rule["kind"] == "must_be_tested":
+            scope = _select(con, rule["selector_from"])
+            tested = {r[0] for r in con.execute(store.TESTED)}
+            try:  # functions measured running under a test count as tested
+                tested |= {r[0] for r in con.execute("SELECT DISTINCT node_id FROM covered")}
+            except Exception:
+                pass
+            for r in con.execute("SELECT id FROM nodes WHERE kind = 'callable'"):
+                if r[0] in scope and r[0] not in tested:
+                    violations.append({"untested": r[0]})
+        for v in violations:
+            for key in ("from", "to", "untested"):
+                if key in v:
+                    v[key + "_name"] = names.get(v[key], v[key])
+        out.append({"id": rule["id"], "kind": rule["kind"], "from": rule["selector_from"], "to": rule["selector_to"],
+                    "edge_kinds": kinds, "severity": rule["severity"], "reason": rule["reason"],
+                    "status": rule["status"] or "confirmed", "passes": not violations,
+                    "violations": len(violations), "examples": violations[:25]})
+    return {"total": len(out), "failing": sum(1 for r in out if not r["passes"]), "rules": out}

leyline/schema.sql

@@ -0,0 +1,178 @@
+-- Leyline store, schema v0. One SQLite file per workspace.
+-- Layers: fact (deterministic), inferred (LLM), intent (human).
+
+CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT);
+
+CREATE TABLE IF NOT EXISTS nodes (
+  id            TEXT PRIMARY KEY,
+  kind          TEXT NOT NULL,
+  name          TEXT NOT NULL,
+  parent_id     TEXT REFERENCES nodes(id),
+  repo_id       TEXT,
+  language      TEXT,
+  path          TEXT,
+  span_start    INTEGER,
+  span_end      INTEGER,
+  content_hash  TEXT,
+  layer         TEXT NOT NULL DEFAULT 'fact',
+  source        TEXT NOT NULL,
+  commit_sha    TEXT,
+  attrs         TEXT
+);
+CREATE INDEX IF NOT EXISTS nodes_parent ON nodes(parent_id);
+CREATE INDEX IF NOT EXISTS nodes_kind ON nodes(kind);
+CREATE INDEX IF NOT EXISTS nodes_path ON nodes(path);
+
+-- Every id once, numbered, for the large tables below that would otherwise repeat long ids in every row
+-- and in each of their indexes.
+CREATE TABLE IF NOT EXISTS keys (k INTEGER PRIMARY KEY, id TEXT NOT NULL UNIQUE);
+
+-- Edges, with both ends as keys. Readers and writers use the `edges` view, which store.connect creates and
+-- which has the columns of the original table (id, kind, src_id, dst_id, precision, layer, source,
+-- commit_sha, attrs); inserting into or deleting from the view works.
+CREATE TABLE IF NOT EXISTS links (
+  id          INTEGER PRIMARY KEY,
+  kind        TEXT NOT NULL,
+  src         INTEGER NOT NULL,
+  dst         INTEGER NOT NULL,
+  precision   TEXT NOT NULL,
+  layer       TEXT NOT NULL DEFAULT 'fact',
+  source      TEXT NOT NULL,
+  commit_sha  TEXT,
+  attrs       TEXT
+);
+CREATE INDEX IF NOT EXISTS links_out ON links(src, kind);
+CREATE INDEX IF NOT EXISTS links_in ON links(dst, kind);
+
+-- Call edges are the largest kind, so they get a narrow table of their own, with both ends as keys. Readers
+-- use the `calls` view, which store.connect creates and which has the columns of the original table
+-- (src_id, dst_id, dispatch, precision, site_start, site_end, hit_count, commit_sha).
+CREATE TABLE IF NOT EXISTS call_sites (
+  src         INTEGER NOT NULL,
+  dst         INTEGER NOT NULL,
+  dispatch    TEXT NOT NULL,
+  precision   TEXT NOT NULL,
+  site_start  INTEGER,
+  site_end    INTEGER,
+  hit_count   INTEGER DEFAULT 0,
+  commit_sha  TEXT
+);
+CREATE INDEX IF NOT EXISTS call_sites_out ON call_sites(src, dst);
+CREATE INDEX IF NOT EXISTS call_sites_in ON call_sites(dst, src);
+
+CREATE TABLE IF NOT EXISTS annotations (
+  id             INTEGER PRIMARY KEY,
+  node_id        TEXT NOT NULL REFERENCES nodes(id),
+  key            TEXT NOT NULL,
+  value          TEXT NOT NULL,
+  layer          TEXT NOT NULL,
+  source         TEXT NOT NULL,
+  confidence     REAL,
+  evidence       TEXT,
+  evidence_hash  TEXT,
+  stale          INTEGER DEFAULT 0
+);
+CREATE INDEX IF NOT EXISTS annotations_node ON annotations(node_id, key);
+
+CREATE TABLE IF NOT EXISTS flows (
+  id TEXT PRIMARY KEY, name TEXT, origin TEXT, entry_id TEXT, weight REAL,
+  group_id TEXT, layer TEXT, source TEXT, attrs TEXT
+);
+-- Flow steps are the largest table by far (millions of rows on a big repository), so they are stored as
+-- integers: every id once in `keys`, every step as a row of numbers. Readers use the `flow_steps` view,
+-- which store.connect creates and which has the columns of the original table.
+CREATE INDEX IF NOT EXISTS flows_entry ON flows(entry_id);
+CREATE TABLE IF NOT EXISTS steps (
+  flow INTEGER, seq INTEGER, depth INTEGER, callable INTEGER,
+  via INTEGER,         -- index into store.VIA
+  site_line INTEGER,   -- line of the call that led here
+  parent_seq INTEGER,  -- the step this one was reached from
+  PRIMARY KEY (flow, seq)
+) WITHOUT ROWID;
+CREATE INDEX IF NOT EXISTS steps_callable ON steps(callable, flow);
+CREATE TABLE IF NOT EXISTS pattern_instances (
+  id TEXT PRIMARY KEY, pattern TEXT, matcher TEXT, rationale TEXT,
+  confidence REAL, evidence_hash TEXT, stale INTEGER DEFAULT 0
+);
+CREATE TABLE IF NOT EXISTS pattern_roles (instance_id TEXT, role TEXT, node_id TEXT);
+CREATE TABLE IF NOT EXISTS tours (id TEXT PRIMARY KEY, title TEXT, audience TEXT, layer TEXT, source TEXT);
+CREATE TABLE IF NOT EXISTS tour_stops (tour_id TEXT, seq INTEGER, ref_kind TEXT, ref_id TEXT, narrative TEXT);
+CREATE TABLE IF NOT EXISTS boundaries (id INTEGER PRIMARY KEY, system_id TEXT, selector TEXT);
+CREATE TABLE IF NOT EXISTS rules (
+  id INTEGER PRIMARY KEY, kind TEXT, selector_from TEXT, selector_to TEXT,
+  edge_kinds TEXT, severity TEXT, reason TEXT
+);
+CREATE TABLE IF NOT EXISTS change_proposals (
+  id TEXT PRIMARY KEY, intent TEXT, status TEXT, base_commit TEXT, head_commit TEXT, attrs TEXT
+);
+
+-- What each extractor did per repo, so "not analyzed" is distinguishable from "none found".
+CREATE TABLE IF NOT EXISTS extractor_coverage (
+  repo_id TEXT, extractor TEXT, version TEXT, status TEXT, commit_sha TEXT, stats TEXT,
+  PRIMARY KEY (repo_id, extractor)
+);
+
+-- Roll-up cache: the file and module each node sits in.
+CREATE TABLE IF NOT EXISTS ancestry (
+  node_id TEXT PRIMARY KEY, file_id TEXT, module_id TEXT
+);
+CREATE INDEX IF NOT EXISTS ancestry_module ON ancestry(module_id);
+CREATE INDEX IF NOT EXISTS ancestry_file ON ancestry(file_id);
+
+CREATE VIRTUAL TABLE IF NOT EXISTS search USING fts5(node_id UNINDEXED, name, qualified, path, kind UNINDEXED);
+
+-- A saved view: a named set of marked nodes with a narrative. Change proposals create one;
+-- an agent can also author its own.
+CREATE TABLE IF NOT EXISTS views (
+  id TEXT PRIMARY KEY, title TEXT NOT NULL, kind TEXT NOT NULL, layer TEXT NOT NULL,
+  source TEXT NOT NULL, created TEXT, change_id TEXT, spec TEXT NOT NULL
+);
+
+-- Outcomes of test runs, labelled so two runs can be compared.
+CREATE TABLE IF NOT EXISTS test_results (
+  run TEXT NOT NULL, name TEXT NOT NULL, test_id TEXT, status TEXT NOT NULL, message TEXT, recorded TEXT,
+  PRIMARY KEY (run, name)
+);
+
+-- Measured coverage: which functions actually ran, per test where the tool recorded it.
+CREATE TABLE IF NOT EXISTS coverage_runs (
+  run TEXT PRIMARY KEY, format TEXT, created TEXT, commit_sha TEXT, stats TEXT
+);
+CREATE TABLE IF NOT EXISTS covered (
+  run TEXT, test TEXT, test_id TEXT, node_id TEXT, lines INTEGER
+);
+CREATE INDEX IF NOT EXISTS covered_node ON covered (node_id);
+CREATE INDEX IF NOT EXISTS covered_test ON covered (test_id);
+
+-- A change stated as a spec: its tasks and scenarios tied to the map, and what reviewers found.
+CREATE TABLE IF NOT EXISTS spec_items (
+  change_id TEXT, kind TEXT, key TEXT, text TEXT, action TEXT, nodes TEXT, attrs TEXT,
+  PRIMARY KEY (change_id, kind, key)
+);
+CREATE TABLE IF NOT EXISTS findings (
+  id TEXT PRIMARY KEY, change_id TEXT, reviewer TEXT, severity TEXT, claim TEXT, evidence TEXT,
+  proposal TEXT, status TEXT, resolution TEXT, created TEXT
+);
+
+-- Spec drift (leyline.drift): what each code name a spec or a finished change names meant when it was last known
+-- to be right. change_id is the change's id, or specs/<capability> for a living spec. The same anchors are kept in
+-- openspec/leyline-anchors.json, which wins, so they outlive a fresh map. place is that openspec/ folder.
+CREATE TABLE IF NOT EXISTS spec_anchors (
+  place TEXT NOT NULL, change_id TEXT NOT NULL, written TEXT NOT NULL, node_id TEXT NOT NULL, kind TEXT, path TEXT,
+  decl TEXT, decl_hash TEXT, body_hash TEXT, attrs TEXT, recorded TEXT,
+  PRIMARY KEY (place, change_id, written, node_id)
+);
+
+-- Change coupling read from git history (leyline.coupling), kept per repository under the commit it was read from:
+-- how many commits changed each file, and each pair of files (and file and folder) changed together in two or more.
+CREATE TABLE IF NOT EXISTS coupling_runs (
+  repo_id TEXT, sha TEXT, commits INTEGER, bulk INTEGER, seconds REAL, created REAL,
+  PRIMARY KEY (repo_id, sha)
+);
+CREATE TABLE IF NOT EXISTS coupling_files (repo_id TEXT, sha TEXT, path TEXT, changes INTEGER, PRIMARY KEY (repo_id, sha, path));
+CREATE TABLE IF NOT EXISTS coupling_pairs (repo_id TEXT, sha TEXT, a TEXT, b TEXT, together INTEGER);
+CREATE INDEX IF NOT EXISTS coupling_pairs_a ON coupling_pairs (repo_id, sha, a);
+CREATE INDEX IF NOT EXISTS coupling_pairs_b ON coupling_pairs (repo_id, sha, b);
+-- A file and a folder outside it (dir ends in /): commits that changed the file and any file in the folder.
+CREATE TABLE IF NOT EXISTS coupling_dirs (repo_id TEXT, sha TEXT, path TEXT, dir TEXT, together INTEGER);
+CREATE INDEX IF NOT EXISTS coupling_dirs_path ON coupling_dirs (repo_id, sha, path);