Groundnote — knowledge graph and agent guidance#

Status: built (slices G1–G8; the agent guide G9 is agents.md). Architect draft of 2026-11-05. Extends architecture.md (§14 links here) and becomes part of the binding contract once accepted. Source: the German contract, datenmodell.md section "Wissensgraph" (rules G1–G8) and api-vertrag.md section H, decided by Ruben on 2026-11-05. Places where this file departs from it are D59–D66 in abweichungen.md; new terms are in glossary.md.

A small graph inside each scope file: entities in one tree of any depth, with history, and links with an origin between rules, sources, attachments and entities. Queries use the closure table or WITH RECURSIVE; no graph database.

1. Decisions#

Slices G1–G9 follow slice 12 of the core plan (D-f).

2. Ids and refs (extends architecture.md §4.3, domain/ids.ts)#

const EntityId  = z.string().regex(/^[a-z][a-z0-9-]{1,39}-e\d{4,}$/);              // sales-e0007
const EntityRef = z.string().regex(/^entity\/[a-z][a-z0-9-]{1,39}-e\d{4,}(@[1-9]\d*)?$/);
const LinkId    = z.string().regex(/^[a-z][a-z0-9-]{1,39}-l\d{4,}$/);              // sales-l0042
const ReviewId  = z.string().regex(/^[a-z][a-z0-9-]{1,39}-r\d{4,}$/);
const Endpoint  = z.union([                                                        // versionless; stored in `link`
  z.string().regex(/^rule\/[a-z][a-z0-9-]{1,39}-\d{4,}$/),
  z.string().regex(/^source\/(jamie:[A-Za-z0-9._-]{1,200}|mail:<[^<>\s]+>)$/),
  z.string().regex(/^attachment\/(jamie:[A-Za-z0-9._-]{1,200}|mail:<[^<>\s]+>)#[1-9]\d*$/),
  z.string().regex(/^entity\/[a-z][a-z0-9-]{1,39}-e\d{4,}$/),
]);

The number is the row's seq, zero-padded to 4. Scope of an id = id without -e\d+, -l\d+, -r\d+; rule ids keep -\d{4,}, so the forms never collide. Source and attachment refs carry no scope; every tool that accepts them also takes scope (D61).

3. Migration src/db/migrations/scope/0002-graph.ts#

One transaction, meta.schema_version = 2, foreign_keys = ON, legacy_alter_table off (default).

3.1 Log rebuild#

CREATE TABLE search_log_new ( /* columns exactly as 0001 */ ...,
  operation TEXT NOT NULL CHECK (operation IN ('search','read_rule','list_rules','provenance',
    'propose','list_proposals','list_rejected','decide','store_source','feedback','list_scopes','status',
    'resolve_entity','read_entity','create_entity','move_entity','update_entity','propose_link','list_links',
    'list_structure','review_structure','archive_entity','export')), ...);
INSERT INTO search_log_new (id, at, grant_id, channel, operation, outcome, cross_scope, refs, terms, variants, stages, input_sha256)
  SELECT id, at, grant_id, channel, operation, outcome, cross_scope, refs, terms, variants, stages, input_sha256 FROM search_log;
CREATE TABLE feedback_new ( /* as 0001 */ ..., search_id TEXT NOT NULL REFERENCES search_log_new(id), ...);
INSERT INTO feedback_new (id, search_id, ref, verdict, given_by, given_at) SELECT id, search_id, ref, verdict, given_by, given_at FROM feedback;
DROP TABLE feedback;                                  -- child first, so no FK sees a missing parent
DROP TABLE search_log;
ALTER TABLE search_log_new RENAME TO search_log;      -- rewrites feedback_new's REFERENCES to search_log
ALTER TABLE feedback_new RENAME TO feedback;          -- sqlite_sequence follows the rename

Rights (auth/scope-check.ts OPERATION_RIGHT): resolve_entity, read_entity, list_links, list_structure → read; create_entity, move_entity, update_entity, propose_link → propose; review_structure, archive_entity → decide.

3.2 Entities#

CREATE TABLE entity (                                  -- head, immutable
  seq INTEGER PRIMARY KEY,                             -- explicit max+1
  id TEXT NOT NULL UNIQUE,                             -- <scope>-e<nnnn>, never reused
  scope TEXT NOT NULL,                                 -- contract `area`
  created_at TEXT NOT NULL CHECK (created_at GLOB '????-??-??T??:??:??*Z'),
  created_by TEXT NOT NULL CHECK (created_by IN ('human','agent','import')));   -- channel approval | mcp | api
CREATE TRIGGER entity_in_scope BEFORE INSERT ON entity
WHEN NEW.scope IS NOT (SELECT scope FROM meta) OR NEW.id IS NOT NEW.scope || '-e' || printf('%04d', NEW.seq)
BEGIN SELECT RAISE(ABORT, 'entity-id-not-in-scope'); END;

CREATE TABLE entity_version (
  id TEXT NOT NULL REFERENCES entity(id),
  version INTEGER NOT NULL CHECK (version >= 1),
  type TEXT NOT NULL CHECK (length(type) BETWEEN 2 AND 30 AND type NOT GLOB '*[^a-z0-9_]*'),  -- vocabulary from config
  name TEXT NOT NULL CHECK (length(trim(name)) BETWEEN 1 AND 200),
  aliases TEXT NOT NULL CHECK (json_valid(aliases) AND json_type(aliases) = 'array' AND json_array_length(aliases) <= 20),
  parent_id TEXT REFERENCES entity(id),
  status TEXT NOT NULL CHECK (status IN ('active','unconfirmed','archived')),
  valid_from TEXT NOT NULL CHECK (valid_from GLOB '[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]'),
  valid_to TEXT CHECK (valid_to IS NULL OR valid_to GLOB '[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]'),
  evidence TEXT CHECK (evidence IS NULL OR length(evidence) BETWEEN 1 AND 1000),   -- ref (source/…, URL) or short text
  change TEXT NOT NULL CHECK (change IN ('create','move','update','confirm','revert','archive')),
  channel TEXT NOT NULL CHECK (channel IN ('mcp','api','approval')),
  changed_by TEXT NOT NULL,                            -- grant id
  changed_at TEXT NOT NULL CHECK (changed_at GLOB '????-??-??T??:??:??*Z'),
  reason TEXT NOT NULL CHECK (length(trim(reason)) > 0),
  PRIMARY KEY (id, version),
  CHECK (parent_id IS NULL OR parent_id <> id),
  CHECK (valid_to IS NULL OR valid_to >= valid_from),
  CHECK ((status = 'archived') = (valid_to IS NOT NULL)),
  CHECK ((channel = 'approval') = (change IN ('confirm','revert','archive'))),       -- G7: agents never confirm, revert, archive
  CHECK (channel <> 'approval' OR changed_by GLOB 'person:*'),
  CHECK (change <> 'create' OR status = 'unconfirmed'),
  CHECK (change <> 'confirm' OR status = 'active'),
  CHECK (change <> 'archive' OR status = 'archived'));

CREATE VIEW entity_current AS SELECT v.* FROM entity_version v
WHERE v.version = (SELECT max(w.version) FROM entity_version w WHERE w.id = v.id);

CREATE TABLE entity_closure (                          -- derived; written only by src/graph/closure.ts (AT5)
  ancestor_id TEXT NOT NULL REFERENCES entity(id),
  descendant_id TEXT NOT NULL REFERENCES entity(id),
  depth INTEGER NOT NULL CHECK (depth >= 0),
  PRIMARY KEY (ancestor_id, descendant_id),
  CHECK ((depth = 0) = (ancestor_id = descendant_id))) WITHOUT ROWID;
CREATE INDEX entity_closure_up ON entity_closure(descendant_id, depth);
CREATE INDEX entity_closure_down ON entity_closure(ancestor_id, depth);

CREATE TRIGGER entity_version_rules BEFORE INSERT ON entity_version BEGIN
  SELECT RAISE(ABORT, 'version-gap') WHERE NEW.version <>
    1 + coalesce((SELECT max(version) FROM entity_version WHERE id = NEW.id), 0);
  SELECT RAISE(ABORT, 'invalid-transition') WHERE (NEW.version = 1) <> (NEW.change = 'create');
  SELECT RAISE(ABORT, 'terminal-state') WHERE
    (SELECT status FROM entity_version WHERE id = NEW.id AND version = NEW.version - 1) = 'archived';
  SELECT RAISE(ABORT, 'invalid-transition') WHERE NEW.change = 'confirm' AND
    (SELECT status FROM entity_version WHERE id = NEW.id AND version = NEW.version - 1) <> 'unconfirmed';
  SELECT RAISE(ABORT, 'invalid-transition') WHERE NEW.change IN ('move','update') AND NEW.status IS NOT
    (SELECT status FROM entity_version WHERE id = NEW.id AND version = NEW.version - 1);   -- agents never change status
  SELECT RAISE(ABORT, 'state-changed') WHERE NEW.change IN ('confirm','archive') AND EXISTS (
    SELECT 1 FROM entity_version p WHERE p.id = NEW.id AND p.version = NEW.version - 1 AND (p.type IS NOT NEW.type
      OR p.name IS NOT NEW.name OR p.aliases IS NOT NEW.aliases OR p.parent_id IS NOT NEW.parent_id));
  SELECT RAISE(ABORT, 'cycle') WHERE NEW.parent_id IS NOT NULL AND EXISTS (   -- G2: parent is self or a descendant
    SELECT 1 FROM entity_closure WHERE ancestor_id = NEW.id AND descendant_id = NEW.parent_id);
  SELECT RAISE(ABORT, 'parent-archived') WHERE NEW.status <> 'archived' AND NEW.parent_id IS NOT NULL
    AND (SELECT status FROM entity_current WHERE id = NEW.parent_id) = 'archived';
  SELECT RAISE(ABORT, 'has-children') WHERE NEW.status = 'archived' AND EXISTS (       -- G3: cascade archives bottom-up
    SELECT 1 FROM entity_closure c JOIN entity_current k ON k.id = c.descendant_id
    WHERE c.ancestor_id = NEW.id AND c.depth = 1 AND k.status <> 'archived');
END;

CREATE VIRTUAL TABLE entity_fts USING fts5(name, aliases, tokenize = 'trigram');
-- rowid = entity.seq; normalized text (§5.1) of the current version; written only by src/graph/fts.ts

Closure maintenance (graph/closure.ts, after the version insert, same transaction): create → INSERT (X, X, 0) and INSERT SELECT ancestor_id, X, depth + 1 FROM entity_closure WHERE descendant_id = :parent; move →

DELETE FROM entity_closure
 WHERE descendant_id IN (SELECT descendant_id FROM entity_closure WHERE ancestor_id = :x)
   AND ancestor_id NOT IN (SELECT descendant_id FROM entity_closure WHERE ancestor_id = :x);
INSERT INTO entity_closure (ancestor_id, descendant_id, depth)
  SELECT p.ancestor_id, s.descendant_id, p.depth + s.depth + 1
    FROM entity_closure p JOIN entity_closure s ON s.ancestor_id = :x
   WHERE p.descendant_id = :new_parent;                -- nothing for a move to the top level

rebuildClosure(db) recomputes it from entity_current.parent_id with WITH RECURSIVE; tests compare both after every move.

3.3 Links and reviews#

CREATE TABLE link (                                    -- stored links only (K2)
  seq INTEGER PRIMARY KEY,
  id TEXT NOT NULL UNIQUE,                             -- <scope>-l<nnnn>
  from_ref TEXT NOT NULL, to_ref TEXT NOT NULL,        -- Endpoint (§2)
  type TEXT NOT NULL CHECK (length(type) BETWEEN 3 AND 40 AND type NOT GLOB '*[^a-z_]*'),  -- vocabulary in code (§9.3)
  origin TEXT NOT NULL CHECK (origin IN ('deterministic','proposed','human')),
  confidence REAL CHECK (confidence IS NULL OR (confidence >= 0 AND confidence <= 1)),
  reason TEXT CHECK (reason IS NULL OR length(trim(reason)) > 0),
  evidence TEXT CHECK (evidence IS NULL OR length(evidence) BETWEEN 1 AND 1000),
  valid_from TEXT NOT NULL CHECK (valid_from GLOB '????-??-??T??:??:??*Z'),
  valid_to TEXT CHECK (valid_to IS NULL OR valid_to GLOB '????-??-??T??:??:??*Z'),
  created_at TEXT NOT NULL CHECK (created_at GLOB '????-??-??T??:??:??*Z'),
  created_by TEXT NOT NULL,                            -- 'code' for deterministic, else grant id
  CHECK (from_ref <> to_ref),
  CHECK ((origin = 'proposed') = (confidence IS NOT NULL)),          -- G4
  CHECK (origin = 'deterministic' OR reason IS NOT NULL),
  CHECK ((origin = 'deterministic') = (created_by = 'code')),
  CHECK (valid_to IS NULL OR valid_to >= valid_from),
  CHECK (substr(from_ref, 1, 5) = 'rule/' OR substr(from_ref, 1, 7) IN ('source/','entity/') OR substr(from_ref, 1, 11) = 'attachment/'),
  CHECK (substr(to_ref, 1, 5) = 'rule/' OR substr(to_ref, 1, 7) IN ('source/','entity/') OR substr(to_ref, 1, 11) = 'attachment/'));
CREATE UNIQUE INDEX link_open ON link(from_ref, type, to_ref) WHERE valid_to IS NULL;
CREATE INDEX link_to ON link(to_ref, type);

CREATE TRIGGER link_in_scope BEFORE INSERT ON link
WHEN NEW.id IS NOT (SELECT scope FROM meta) || '-l' || printf('%04d', NEW.seq)
BEGIN SELECT RAISE(ABORT, 'link-id-not-in-scope'); END;
CREATE TRIGGER link_endpoints BEFORE INSERT ON link BEGIN            -- G1: both ends in THIS file
  SELECT RAISE(ABORT, 'link-endpoint-unknown') WHERE NOT (
       EXISTS (SELECT 1 FROM rule WHERE 'rule/' || id = NEW.from_ref)
    OR EXISTS (SELECT 1 FROM entity WHERE 'entity/' || id = NEW.from_ref)
    OR EXISTS (SELECT 1 FROM source WHERE 'source/' || id = NEW.from_ref)
    OR EXISTS (SELECT 1 FROM source_attachment WHERE 'attachment/' || source_id || '#' || n = NEW.from_ref));
  SELECT RAISE(ABORT, 'link-endpoint-unknown') WHERE NOT ( /* same four for NEW.to_ref */ );
  SELECT RAISE(ABORT, 'entity-archived') WHERE EXISTS (SELECT 1 FROM entity_current
    WHERE status = 'archived' AND 'entity/' || id IN (NEW.from_ref, NEW.to_ref));
END;
CREATE TRIGGER link_end_once BEFORE UPDATE ON link WHEN NOT (OLD.valid_to IS NULL AND NEW.valid_to IS NOT NULL
  AND NEW.seq IS OLD.seq AND NEW.id IS OLD.id AND NEW.from_ref IS OLD.from_ref AND NEW.to_ref IS OLD.to_ref
  AND NEW.type IS OLD.type AND NEW.origin IS OLD.origin AND NEW.confidence IS OLD.confidence
  AND NEW.reason IS OLD.reason AND NEW.evidence IS OLD.evidence AND NEW.valid_from IS OLD.valid_from
  AND NEW.created_at IS OLD.created_at AND NEW.created_by IS OLD.created_by)
BEGIN SELECT RAISE(ABORT, 'append-only'); END;       -- contract: valid_to set once; no route sets it in this phase

CREATE TABLE review (                                  -- person verdicts on agent versions and proposed links
  seq INTEGER PRIMARY KEY,
  id TEXT NOT NULL UNIQUE,                             -- <scope>-r<nnnn>; same id-in-scope trigger as link
  target TEXT NOT NULL,                                -- entity/<id>@<n> | link/<id>
  verdict TEXT NOT NULL CHECK (verdict IN ('confirm','reject','revert')),
  decided_by TEXT NOT NULL CHECK (decided_by GLOB 'person:*'),     -- API field `by`
  decided_by_identity TEXT NOT NULL,                   -- email, approval UI only (as D14)
  decided_at TEXT NOT NULL CHECK (decided_at GLOB '????-??-??T??:??:??*Z'),   -- API field `at`
  reason TEXT,
  new_version INTEGER,                                 -- entity version written by this review, else NULL
  CHECK (target GLOB 'entity/*@*' OR target GLOB 'link/*'),
  CHECK (verdict <> 'reject' OR target GLOB 'link/*'),
  CHECK (verdict <> 'revert' OR target GLOB 'entity/*'),
  CHECK (verdict = 'confirm' OR length(trim(coalesce(reason, ''))) > 0));
CREATE UNIQUE INDEX review_once ON review(target);    -- one verdict per entity version or link

-- append-only pairs (BEFORE UPDATE / BEFORE DELETE → RAISE(ABORT, 'append-only')) on entity,
-- entity_version, review; on link only BEFORE DELETE (updates go through link_end_once).

4. Writers and checks in code#

Create (entity_create, POST /v1/entities), in this order: type in graph.entity_types (else 400 validation-failed); parent exists in the scope (reference-unknown; parent of another scope → scope-mismatch) and is not archived (parent-archived); depth of the new node ≤ graph.max_depth (depth-limit); literal duplicate — same parent, same type, same name case-insensitively among non-archived current versions → duplicate-candidate, force does not override; similar duplicate — resolve (§5) with the name and each alias, same type, score ≥ 0.85 → duplicate-candidate unless force: true with reason (reason-missing without). Then one transaction: entity (seq = max + 1), version 1 (unconfirmed, valid_from = today in config.zone, reason = given or "created via <channel>"), closure, FTS, search_log.

Move (entity_move): entity exists and is not archived; new parent as above; cycle if the new parent is the entity or a descendant (checked in code first, so the answer carries both paths; the trigger is the backstop); depth of the deepest moved node ≤ graph.max_depth; literal duplicate under the new parent; same parent → answer moved: false, nothing written. New version copies the current one with the new parent_id, change = 'move', status unchanged; closure for the subtree.

Update (entity_update): rename and add/remove aliases as one agent version (change = 'update', status unchanged, pending until a review like a move); the new name and the added aliases pass the same duplicate checks as a create, excluding the entity itself (force with reason overrides a similar duplicate, never a literal one); removing an alias the entity lacks → 400 validation-failed; nothing changed → updated: false, nothing written.

Link (link_propose): both endpoints exist in the scope (reference-unknown), a rule endpoint is not rejected (not-found, invariant 8), rule/entity ids of another scope → scope-mismatch, an archived entity end → reference-unknown (remedy names it archived); type proposable (§9.3); an open link with the same (from_ref, type, to_ref) → answer it with created: false (also when rejected: status: "rejected", never re-proposed).

Validity. link.valid_from = time of writing; bundles and lists use links open on the target day (valid_from ≤ end of day, valid_to null or later).

5. entity_resolve algorithm (src/graph/normalize.ts, src/graph/resolve.ts)#

5.1 Normalization#

normalize(s) = NFKC → lowercase → ä→ae, ö→oe, ü→ue, ß→ss → NFD and drop \p{M} → every character outside [\p{L}\p{N}] to a space → collapse spaces, trim → drop trailing legal-form tokens (gmbh, mbh, ag, kg, ohg, ug, gbr, ev, se, co, inc, ltd, llc, plc) while ≥ 1 token remains. entity_fts stores normalize(name) and the normalized aliases joined by |.

5.2 Recall#

1. key = normalize(q). Empty → 400 validation-failed.
2. Exact pass (always): current, non-archived versions whose normalize(name) or a normalized alias equals key (loaded with json_each; covers keys shorter than 3 characters such as vn).
3. Trigram pass (length(key) ≥ 3): MATCH with every trigram of key as a quoted phrase, joined by OR (user text never reaches MATCH unquoted), ORDER BY rank LIMIT 50.
4. Initials pass (key is one token of 2–6 letters): names whose token initials equal key.

5.3 Score (per entity: best over name and aliases; s = normalized string)#

Candidates: score ≥ 0.50, optional type filter, archived excluded; order score desc, active before unconfirmed, smaller depth, id; at most 5. Duplicate threshold for create/move: 0.85. Examples (G2 tests): Mueller GmbH = Müller (exact); Vetrieb Nord → Vertrieb Nord (typo); VN → alias VN (alias) or Vertrieb Nord without alias (initials); Nord Vertrieb (tokens); Nord vs Nordwest below 0.85, so no duplicate refusal.

Bounds. name, every alias and q are limited to 200 characters both as given and after normalization: NFKC expands some characters (one Arabic ligature becomes 18 letters), so 197 input characters could otherwise be stored and scored as 3,546. A longer normalized form is refused by the input schema on HTTP (400 validation-failed) and MCP alike; aliases_remove keeps only the raw bound, since it is matched against stored aliases and never stored or scored. The distance is computed only up to the typo limit 2: strings whose lengths differ by more than 2 are not compared, only the diagonal band |i − j| ≤ 2 is filled, and the walk stops once a whole row exceeds 2, so one comparison costs O(length) instead of O(length²).

6. Queries#

-- path (breadcrumb), root first
SELECT k.id, k.name, k.type FROM entity_closure c JOIN entity_current k ON k.id = c.ancestor_id
WHERE c.descendant_id = :id ORDER BY c.depth DESC;
-- direct children with counts, page of 50
SELECT k.id, k.name, k.type, k.status,
  (SELECT count(*) FROM entity_closure g JOIN entity_current h ON h.id = g.descendant_id
    WHERE g.ancestor_id = k.id AND g.depth = 1 AND h.status <> 'archived') AS children
FROM entity_closure c JOIN entity_current k ON k.id = c.descendant_id
WHERE c.ancestor_id = :id AND c.depth = 1 AND k.status <> 'archived'
ORDER BY lower(k.name), k.id LIMIT 50 OFFSET (:page - 1) * 50;
-- level counts below :id
SELECT c.depth, count(*) FROM entity_closure c JOIN entity_current k ON k.id = c.descendant_id
WHERE c.ancestor_id = :id AND c.depth BETWEEN 1 AND :depth AND k.status <> 'archived' GROUP BY c.depth;

Tree (entity_tree): level 1 = the page of direct children of id (top-level entities when only scope is given); levels 2…depth add, node by node in order, up to 50 children each while the answer holds fewer than 200 nodes. Every node carries children and hidden_children (children not in this answer). depth default 1, maximum 3 (depth-limit above; the input schema accepts any depth ≥ 1 so the answer can carry the remedy instead of an SDK validation error).

Everything about X (link_list with grouped: true on an entity): stored and computed links of the entity and its descendants (descendant_id IN (SELECT descendant_id FROM entity_closure WHERE ancestor_id = :x)), other ends resolved to entries, grouped by kind like a bundle (§11), newest first, counted per G5.

Computed links (never stored, id: null, origin: "deterministic"):

7. Configuration (groundnote.json, extends architecture.md §3; schema in src/graph/config.ts)#

const EntityType = z.string().regex(/^[a-z][a-z0-9_]{1,29}$/);
const DEFAULT_ENTITY_TYPES = ["organisation", "department", "project", "customer", "object", "person", "case", "topic"];
graph: z.object({
  entity_types: z.array(EntityType).min(1).refine(unique).default(DEFAULT_ENTITY_TYPES),  // the full list; extend by adding
  max_depth: z.number().int().min(2).max(64).default(16),                                // levels incl. the top level
  proposed_min_confidence: z.number().min(0).max(1).nullable().default(null),            // null: only confirmed proposals count
}).strict().prefault({}),                     // Zod 4: prefault parses {} so the inner defaults apply

Removing a type from config keeps existing entities of it readable; new ones of that type fail. Tree limits (depth ≤ 3, pages of 50, 200 nodes) and resolve thresholds (0.50 / 0.85, 5 candidates) are contract constants, not config.

8. Guidance envelope and errors#

Refusals of the scope check on a graph tool (scope-not-allowed, channel-not-allowed, …) use the same envelope {error, remedy, next}; a foreign, missing or in-graph foreign scope gives the same body, so the answer never says whether a scope or entity exists (src/mcp/result.ts).

const PathItem = z.object({ id: EntityId, name: z.string(), type: z.string() });     // full, from the top
const Next     = z.object({ tool: z.string(), why: z.string() });                    // tool or prompt name
const Guidance = z.object({ path: z.array(PathItem), next: z.array(Next).max(3) });  // in every graph answer
const EntityOut = z.object({
  ref: EntityRef, id: EntityId, scope: ScopeName, type: z.string(), name: z.string(), aliases: z.array(z.string()),
  status: z.enum(["active", "unconfirmed", "archived"]), parent_id: EntityId.nullable(),
  valid_from: Day, valid_to: Day.nullable(), children: z.number().int(),
  pending: z.boolean(),                          // an agent version without review (§12)
  approval_url: z.string().url().nullable(),     // <public_url>/approval/structure?scope=<scope>#<id> when pending
});
const Candidate = z.object({ id: EntityId, name: z.string(), type: z.string(), status: EntityOut.shape.status,
  aliases: z.array(z.string()), path: z.array(z.string()), score: z.number(),
  match: z.enum(["exact", "alias", "tokens", "typo", "initials", "similar"]) });
const GraphErrorBody = ErrorBody.extend({        // `error` as in architecture.md §6.6
  remedy: z.string(), next: z.array(Next).max(3),
  candidates: z.array(Candidate).max(5).optional(),                                  // duplicate-candidate
  paths: z.object({ entity: z.array(PathItem), target: z.array(PathItem) }).optional(),  // cycle
  limit: z.number().int().optional() });                                             // depth-limit

path is the path of the entity the answer is about (for links: of the entity end, else []). Errors raised inside graph tools are isError: true results with this body; HTTP uses the status below. Schema rejections by the MCP SDK stay "Input validation error" (D45); the allowed type values are therefore an enum in each tool's input schema (built per request from config).

next rules (code, ≤ 3, in this order): resolve exact/alias → entity_path ("check the place"), link_propose ("file the item there"); candidates without exact → entity_path of the best, entity_create ("only if the person says none is meant"); none → entity_tree ("find the parent"), entity_create; create/move done → link_propose, entity_tree of the parent; tree with hidden children → entity_tree on the first node with hidden_children > 0, or the next page; duplicate-candidate → entity_path of the first candidate; cycle → entity_path of the target.

9. MCP (src/mcp/instructions.ts, src/mcp/prompts.ts, src/mcp/tools/entity-*.ts, link-*.ts)#

new McpServer({name: "groundnote", version}, {instructions: INSTRUCTIONS}). tools/list returns the seven core tools (with rule_retract, approval-modes.md §8) and the eight graph tools; prompts/list the five prompts of §9.4.

9.1 Server instructions (verbatim)#

Groundnote keeps confirmed business rules with their evidence and, per scope, a small knowledge graph: entities (organisations, departments, projects, customers, objects, people, cases, topics) in one tree, and links between rules, sources, attachments and entities. Always name the scope; links exist only inside one scope. Call entity_resolve before entity_create, and whenever a name from a mail or conversation should be matched to an entity. Every graph answer contains the full path of the entity: tell the person the path. What you create or move takes effect at once but is unconfirmed until a person confirms it on the approval page: say so and give the approval_url. You never confirm, archive or revert structure, and you never confirm rules: point to the approval page. Read large trees step by step with entity_tree; never ask for a whole tree. Follow next when unsure; on an error follow remedy instead of repeating the call. For every rule you use, give its date and source, and pass on "still valid?". For standard tasks use the prompts create_level, file_incoming_mail, assign_document, restructure and where_does_this_belong. A rule marked auto-adopted was adopted by the policy without a person: say "auto-adopted" when you cite it. When the person asks, you may retract an auto-adopted rule with rule_retract; you never confirm a rule.

The last two sentences come from approval-modes.md §9 (slice A).

9.2 Tools#

const ProposableType = z.enum(["concerns", "belongs_to", "contradicts", "mentions", "same_as"]);
const LinkType = z.enum([...ProposableType.options, "replies_to", "attachment_of", "sourced_from", "supersedes"]);
const LinkOut = z.object({ id: LinkId.nullable(), from_ref: z.string(), to_ref: z.string(), type: LinkType,
  origin: z.enum(["deterministic", "proposed", "human"]), confidence: z.number().nullable(),
  status: z.enum(["confirmed", "proposed", "rejected"]),   // deterministic/human: confirmed; proposed: by review
  reason: z.string().nullable(), evidence: z.string().nullable(), valid_from: Instant, valid_to: Instant.nullable(),
  created_at: Instant.nullable() });                        // null for computed links

Descriptions (verbatim, the description of each registerTool):

• entity_resolve — "Find existing entities by name, alias or misspelling in one scope. Call it before every entity_create and whenever a name from a mail, document or conversation should be matched to an entity. Returns at most five candidates with score, how they matched and their full path. An exact or alias match means: use it. Several close candidates: show their paths and ask the person."
• entity_create — "Create one entity under a parent found with entity_resolve (parent_id null only for a new top level). Use it only when entity_resolve found nothing that fits. It is usable at once, with status unconfirmed, until a person confirms it on the approval page. It checks for duplicates itself: if a similar entity exists it creates nothing and answers duplicate-candidate with the candidates; use force: true with a reason only when the person says the new one is different."
• entity_move — "Move an entity with its whole subtree under another parent (parent_id null: top level), for example a department into another division. Takes effect at once as a new version; the old version stays in the history, and the move is unconfirmed until a person confirms or reverts it on the approval page. Show the person the old and the new path first. Refused with cycle if the new parent lies inside the moved subtree."
• entity_update — "Rename an entity or add and remove its aliases, for example a short name or a spelling used in mails. Takes effect at once as a new version; the old version stays in the history, and the change is unconfirmed until a person confirms or reverts it on the approval page. The new name and added aliases are checked for duplicates like entity_create: on duplicate-candidate use force: true with a reason only when the person says the entity is different."
• entity_tree — "Show the entities below one entity (or the top level of a scope): direct children by default, at most depth 3, 50 per page. Every node says how many children it has and how many are hidden; expand a node by calling again with its id. Use it step by step to get an overview or to find a parent; never page through a whole tree unasked."
• entity_path — "Return the full path of one entity from the top level down, its status and its versions including moves. Use it when only the place of an entity is asked, and to check a candidate before filing something under it."
• link_propose — "Propose a link inside one scope between a rule, source, attachment or entity, for example a mail concerns a project or a document belongs to an object. Give an honest confidence from 0 to 1 and a reason that names the evidence. A proposed link counts in search bundles only once a person confirms it or its confidence reaches the configured minimum, and it is always marked as proposed. Thread, attachment, source and supersedes links exist already; do not propose them."
• link_list — "List the links of one item: stored and derived ones, proposed ones with their confidence. With grouped: true on an entity it returns everything about the entity and its descendants, grouped by kind with dates. 50 per page."

9.3 Link vocabulary#

9.4 Prompts (server.registerPrompt; arguments are strings)#

Arguments are checked before any text is built: scope is a ScopeName, source a mail or jamie id, ref an Endpoint; names ≤ 200 characters, subject, sender, hint, reason and evidence ≤ 1000, description ≤ 2000. Every argument except scope and type is foreign text — name, parent, evidence, entity, new_parent, subject, sender, hint, reason, description, and the refs source and ref: the message names each by its label ("the subject quoted below", "the document ref quoted below") and appends it in its own untrusted block with one boundary, followed by the untrusted-text preamble (F4, src/mcp/prompts.ts). The {…} of these arguments in the table below stand for that reference. Every prompt has at least one required foreign argument and therefore always carries the preamble.

10. HTTP routes (contract H; same domain functions, channel api unless noted)#

/v1/reviews and /v1/entities/:id/archive belong to the approval channel (aud aud_approval, session cookie in dev) although they sit under /v1/ — like the rule decision route. An entity created via api gets created_by = 'import'.

const ReviewRequest = z.object({
  target: z.union([EntityRef.refine(hasVersion), z.string().regex(/^link\/[a-z][a-z0-9-]{1,39}-l\d{4,}$/)]),
  verdict: z.enum(["confirm", "reject", "revert"]),
  reason: z.string().min(1).max(1000).optional(),           // required for reject and revert (reason-missing)
}).strict();

11. Bundles (extends architecture.md §6.5 and §8)#

const EntryKind = z.enum(["rule", "note", "meeting", "mail", "attachment", "entity"]);
const Entry = /* as §6.5 */ .extend({
  origin: z.enum(["deterministic", "proposed", "human"]),    // of the link the entry hangs on
  proposed: z.boolean() });                                  // proposed and not yet confirmed (G5)
const Head = /* as §6.5 */ .extend({
  entities: z.array(z.object({ ref: z.string(), name: z.string(), type: z.string(),
    path: z.array(z.object({ ref: z.string(), name: z.string(), type: z.string() })),
    proposed: z.boolean() })).max(10) });
const Group = /* kind */ z.enum(["source", "thread", "attachment", "entity", "predecessor", "successor",
                                 "contradicts", "same-relation"]);              // fixed order, empty omitted
const SearchRequest = /* as §6.5 */ .extend({ entity: EntityId.optional() });   // one scope only (else 400)

• Counted links (G5): computed and deterministic/human links always; proposed links only if reviewed confirm, or proposed_min_confidence is not null, the confidence reaches it and no reject exists. Rejected never. Open on the target day (as_of or today).
• entity group / head.entities: entities linked to the head rule (concerns, belongs_to, mentions), not archived; entry ref entity/<id>, title = path joined with ›, date = link valid_from, excerpt/link null. Order: not proposed first, then confidence, then date.
• contradicts: rules linked to the head by contradicts (either direction), passing the head filter.
• same-relation additionally holds rules with a counted link to the same entity or one of its ancestors (G8, via entity_closure).
• Existing groups get origin: "deterministic", proposed: false (computed links of §6).
• entity filter (G8): heads with a counted link to the entity or any of its ancestors.
• Compact MCP answer (architecture.md §6.5): head.entities is left out; the entity group names the entities by ref and related carries each one's path as title, once per answer.
• line: parts after <n> attachment(s): <n> entit(y|ies); after superseded by <id>: <n> contradicting rule(s); when any shown entry is proposed, the parts end with (of which <p> proposed). Bundles without graph data are unchanged.

12. Approval: "Structure changes" (src/structure/, src/approval/)#

Pending = per entity, the agent versions (channel mcp/api) after its latest approval version that have no review; plus every proposed link without a review. GET /approval shows a section Structure changes per scope (counts, newest five, link to the full page). GET /approval/structure?scope= lists every pending item newest first: entity with path before and after (create: "new under …"; move: old → new path, subtree size), who (grant, channel), reason, evidence, the duplicate candidates the create overrode, and for links both ends (entity path, rule statement, source title) with type, confidence and reason; plus forms with target = the current version, csrf, and (archive) version. The rule page (/approval/rules/:id) lists the rule's pending concerns links with their own confirm/reject forms (G8).

A review whose target is not the current version → 409 version-outdated (current: entity/<id>@<n>); a second review → 409 already-decided. Pages escape all output; no client JavaScript (D34).

13. Architecture tests (extend test/arch/architecture.test.ts)#

• AT1 the import closure of src/mcp/** contains no file of src/decision/** or src/structure/**.
• AT2b src/structure/** is imported only by src/http/routes/structure.ts and src/approval/**.
• AT3 additionally: INSERT INTO entity_version only in src/graph/entities.ts (create insert with literal 'unconfirmed') and src/structure/**; INSERT INTO entity\b only in src/graph/entities.ts; INSERT INTO link\b only in src/graph/links.ts ('proposed' and 'deterministic'); INSERT INTO review\b only in src/structure/**.
• AT4 the regex becomes /confirm|reject|revoke|review|decide|approve|archive|revert/ and applies to tool and prompt names.
• AT5 statements writing entity_closure / entity_fts (INSERT, UPDATE, DELETE) occur only in src/graph/closure.ts / src/graph/fts.ts and src/db/migrations/**.

14. Slice plan#

Each slice ends green on pnpm lint && pnpm typecheck && pnpm test and is one commit.

15. Open questions#

1. Agents cannot add aliases or rename. Decided 2026-11-05: entity_update now (§4 "Update"), an agent change that stays pending until a person reviews it; its MCP description is in §9.2 (G4).
2. Archived is terminal; restoring means a new entity. Enough, or an "unarchive" verdict?
3. Should a person create or move entities directly on the approval page (created_by = 'human', active at once)? No route exists in the contract, so human links and creates have no writer yet.