[Fooftilly]

Requested by Nikola · project thread

Summary

First PR of slice L-R-1 (Research). Like L-O-1 and L-P-1, it starts with the schema, so the domain PRs that follow have every Research table to build on.

backend/db/schema/130_research.sql adds:

• Concepts with concept_aliases and a concept_keys table. A Concept's name and the aliases of every Concept share one UNIQUE (library_id, key) namespace on prks.identity_key (the same rule as normalize_concept_key). It is built like tag_keys, with deferred keys checked at COMMIT, so a name and a concurrent alias of the same key cannot both commit. [[concept:…]] resolution will use this index, not the Python full scan (§8.1, §8.4). A rename moves the name's key row and keeps the old name as an alias, as concept_sync.set_identity_on_conn does.
• The Concept hierarchy (concept_parents), Positions, Arguments/Stances, the global argument_verdicts seed (SQLite's four rows) and Argument targets. Names are stored canonical, and the text bounds are research_network.py's, counted in characters.
• argument_sources with the [Roadmap] Work Identity, Editions, Versions & Deduplication #60 §8.5 identity. The row key is the list position. A citation is either Work-level or pinned to a Version of the cited Work, and only exact duplicates are refused (NULLS NOT DISTINCT). A pinned citation follows its Version on a move (ON UPDATE CASCADE).
• derived.concept_mentions, derived.argument_mentions and derived.work_note_state, with no foreign keys. Only research.reindex_work will write them, and it deletes a gone Work's rows itself (§8.4).

Revision ownership (§13.2 gate). A Concept's aliases and key rows, and an Argument's targets and sources, are the only cascades into revision-owning rows. Their owner's own scopes (concept-identity, argument-targets, argument-sources) describe them, and the owner's delete tombstones those scopes. Everything else is NO ACTION:

• Concept hierarchy edges also advance concept-parents on the other end, so they do not cascade.
• A Position or Argument that another Argument targets refuses its delete. This matches SQLite's POSITION_IN_USE and ARGUMENT_TARGETED.
• A cited Work refuses its delete. SQLite's cascade drops citations without advancing argument-sources. On PostgreSQL, the Work delete will remove them and advance that scope once the Research commands land.

Work merge registry. argument_sources moves from merge.DEFERRED to merge.RELATIONSHIPS:

• the Work key is UNION and REFUSED, and is a peer table;
• the Manifestation key is FOLLOWS.

merge.prepare now also reports citing_arguments, the Arguments whose argument-sources revision a merge advances, and citations_collapsed, the Work-level citations of the source that the target already has exactly. A comment in PEER_WRITERS notes that CREATE_ARGUMENT and SET_ARGUMENT_SOURCES must join it with their PostgreSQL handlers.

Related issues

Refs #634
Refs #613
Refs #614

Scope / non-goals

Schema, schema tests and the merge registry only. Planned L-R-1 follow-ups, one PR each:

1. Concepts: domain, facade and sync families (create, field, identity, parents, delete) and key-based resolution.
2. Positions and Arguments: fields, targets and sources, with the Work delete removing citations and advancing argument-sources, and CREATE_ARGUMENT/SET_ARGUMENT_SOURCES joining PEER_WRITERS.
3. Research Notes and mentions: the research.reindex_work job (per-Work advisory lock, note FOR SHARE, gone-Work cleanup), enqueued by note commands and by the Work delete, plus the §8.4 pause-point tests.
4. Graph projection and Research read endpoints.

No facade method, sync handler or route changes in this PR. server.py and shared lane files other than the listed one-liners are untouched.

Validation

Local (PostgreSQL 18.x through scripts/test-postgres, throwaway cluster):

• tests.pg.test_research_schema: 23 tests OK. These cover names/aliases sharing one key (Greek, Cyrillic, ß, NFC), three concurrency races on concept_keys, rename, hierarchy, targets and verdicts, citation identity, Library isolation, derived tables, and the cascade list.
• tests.pg.test_work_merge_foundations: OK, including the new citation-plan test and the registry and peer-table checks against live keys.
• Full tests/pg suite: 1118 tests OK.
• scripts/check_pg_schema.py: the fresh schema matches the regenerated snapshot.json.
• ruff check backend tests/pg: clean. Pyright (pyrightconfig.typed-slice.json, 1.1.414): 0 errors. scripts/check_invariants.py: OK.
• No E2E run locally: no browser-visible change.

Migration / compatibility impact

New PostgreSQL baseline file 130_research.sql (pre-1.0, no data migration). SQLite is unchanged. On PostgreSQL, a Work cited by an Argument refuses deletion until Research PR 2 lands. No API can create a citation on PostgreSQL yet.

---

Generated by Claude Code

---

    

[coldtea-pr-lens]

Architecture

Inside the changed components — 1 view

Component view — Research Storage

Internal schema tables and external relational bounds introduced for Research.

Data flow

Review

✨ Nothing flagged · reviewed 1b77503

Tip

Set github.description: false in .github/pr-lens.yml to stop PR Lens adding buttons to your PR descriptions

🪧 More tips

• Run npx skills add coldteadotai/pr-lens, then tell your coding agent: "Diagram the change you just made with PR Lens and attach it to the pull request."
• Run npx @coldtea/pr-lens-cli analyze --base origin/main on a branch, then npx @coldtea/pr-lens-cli render .pr-lens/graph.json. Same lenses, your own model key, before the pull request exists
• Click the link under each diagram to open it on a canvas you can zoom, pan and step through
• The diagrams are links. Click one to open it on the canvas, then press W or click play to walk through the change
• Open a diagram on the canvas, then press W or click play to walk through the change one step at a time
• The CLI's render reads .github/pr-lens.yml and applies your renames, exclusions and lane pins at draw time
• Set github.comment.collapsed: true in .github/pr-lens.yml to fold the comment behind one View architecture and data flow row. Drawing still runs as before
• Set github.draw: on-demand in .github/pr-lens.yml and PR Lens stops drawing pull requests on its own. Comment @pr-lens draw on a pull request when you want that one drawn
• Add .github/workflows/pr-lens.yml with coldteadotai/pr-lens/packages/action@v0 and your model provider's key as its api-key to run PR Lens from your own CI. Any /chat/completions endpoint works
• After a push, tick Redraw to draw the latest commit
• Switch GitHub to dark mode and the diagrams follow. The moving dots are this pull request's data in motion

_{Thanks for using PR Lens! It's free for OSS. If it helped, a star helps other teams find it.} 

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.