feat(graph): add relation taxonomy guardrails

[marcelsamyn]

Summary

Graph extraction and cleanup now have hard relation-shape guardrails instead of relying on the model to infer valid edge direction and endpoint types. Invalid relationships are rejected during extraction, prioritized during iterative cleanup, and auditable through a dedicated predicate-health report.

This also makes organizations first-class graph nodes, replaces passive OWNED_BY with canonical OWNS/ASSIGNED_TO, and moves bookkeeping date facts from overloaded OCCURRED_ON edges to RECORDED_ON.

Design Decisions

Area	Decision
Predicate taxonomy	Add a central domain/range table for relationship predicates and include it in extraction + cleanup prompts.
Ownership direction	Migrate away from OWNED_BY; ownership is owner OWNS owned, task responsibility is Task ASSIGNED_TO Person.
Date semantics	Keep OCCURRED_ON for real-world occurrence dates and use RECORDED_ON for observed/ingested/bookkeeping dates.
Organization modeling	Add Organization for companies, institutions, named teams, communities, clubs, and informal named groups.
Cleanup targeting	Feed invalid relationship-shape nodes into the regular iterative cleanup seed pool before ordinary entry nodes.

Real-Data Dry Run

Ran the migrations in a rollback-only transaction against the imported graph:

Metric	Before	Projected After
Invalid relationship shapes	470	445
Deprecated OWNED_BY predicates	46	0
Active OWNED_BY claims	45	0
New OWNS claims	0	24
New RECORDED_ON claims	0	272
Organization nodes	0	11

The remaining invalid-shape buckets are now regular cleanup targets rather than taxonomy-migration fallout.

Test Plan

• pnpm exec vitest run src/db/migrations-claims.test.ts --pool=threads --poolOptions.threads.singleThread=true
• pnpm exec vitest run src/evals/memory/run-all.test.ts --pool=threads --poolOptions.threads.singleThread=true
• pnpm exec vitest run src/types/graph.test.ts src/lib/claims/predicate-shapes.test.ts src/lib/claims/predicate-shape-repair.test.ts src/lib/structured-output-schemas.test.ts src/lib/context/assemble-bootstrap-context.test.ts --pool=threads --poolOptions.threads.singleThread=true
• pnpm run build:check
• git diff --check

---

[gemini-code-assist]

Code Review

This pull request refines the relationship taxonomy by splitting the overloaded OWNED_BY predicate into ASSIGNED_TO and OWNS, separating real-world occurrence dates (OCCURRED_ON) from bookkeeping dates (RECORDED_ON), and introducing Organization as a first-class node type. It also adds relationship predicate shape guardrails to filter out invalid relationship shapes during extraction. The feedback recommends optimizing database query performance by joining object nodes and metadata directly in the predicate shape audit to avoid large inArray clauses, splitting an OR condition in a migration subquery into separate NOT EXISTS clauses to allow efficient index usage, and importing aliasedTable in the cleanup graph job.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.