feat(decisions): make SQLite the canonical judgment graph

docs/Decision-Structure.md

@@ -21,6 +21,7 @@
 | [repository-native-controlled-corpus](https://github.com/Liplus-Project/neuron-graph-rag/wiki/repository-native-controlled-corpus) | active | repository-native controlled corpus v2 は、固定 SHA の公開 documentation と本文中の明示的な同一 directory 相対 link だけから、node、doc path、source URL、credited edge identity が相互に分離した development / holdout の各 3-edge path を導出する。v1 は provenance として保持する。これは controlled benchmark であり、外部 corpus への一般化、評価 query、gold、result、既定値変更を含まない。 |
 | [soft-start-feedback-reinforcement](https://github.com/Liplus-Project/neuron-graph-rag/wiki/soft-start-feedback-reinforcement) | active | 最初の credited `used` に通常 bounded updateの小さなprovisional fractionを適用し、最初の独立`confirmed`がremainder、後続confirmationがgeometric decayを適用する。v1 snapshot評価の不支持を保持し、baseline-aware successorはfresh initial evidenceからq3 first mutationを導出する。v2 freeze-only PRとsquash後のobserved registrationを分離し、development全gate通過時だけholdoutを一度開く。source database、live config、defaultを変更しない。 |
 | [github-rag-mcp-replacement-compatibility](https://github.com/Liplus-Project/neuron-graph-rag/wiki/github-rag-mcp-replacement-compatibility) | active | public GitHub repository一つのread-only snapshotをNGR local indexへ接続する。github-rag-mcp `search` の保存済み raw capture と source URL、根拠を比較する。共有 source identity を確認しても最小 doc 検索 path の候補に限り、production github-rag-mcp、MCP authentication / transport、remote deployment、default変更は含まない。 |
+| [sqlite-canonical-judgment-graph](https://github.com/Liplus-Project/neuron-graph-rag/wiki/sqlite-canonical-judgment-graph) | active | NGR 自身の判断構造は SQLite の stable identity、revision、lifecycle、typed relation を machine-native 正本とし、raw SQL でなく atomic domain API で変更する。Wiki は移行 fixture の検証後に optional generated view へ下げる。 |
 
 ## Entry format
 
@@ -50,6 +51,9 @@ edge target は Decision Structure node slug とする。外部資料は `Edges`
 
 ## Source-of-truth boundary
 
+- 新規に domain API から登録された judgment graph の machine-readable 正本は SQLite である。詳細契約は [Canonical SQLite judgment graph](canonical-sqlite-judgment-graph.md) に置く。
+- 既存 Wiki entry は検証済み import が行われるまで従来の正本境界を維持する。本変更だけで本番 Wiki entry を自動移行または削除しない。
+
 - `docs/Decision-Structure.md` は main repository における索引、format、vocabulary、所有境界、lifecycle の正本である。これは docs-owned であり、GitHub Wiki の `Decision-Structure.md` へ mirror する。
 - lowercase kebab-case の Decision Structure entry と `_Sidebar.md` は Wiki-only である。docs-to-Wiki synchronization は、`docs/` に対応物がないことを理由にこれらを create、overwrite、delete しない。
 - 個別 Wiki entry は、その判断の current state の正本である。GitHub issue、pull request、commit、test output、fixture、gold、manifest、gate、result artifact は、それぞれの所有境界に従う根拠または契約であり、リンクしただけで Decision Structure entry にはならない。

docs/canonical-sqlite-judgment-graph.md

@@ -0,0 +1,29 @@
+# Canonical SQLite judgment graph
+
+## 正本境界
+
+NGR の新規 judgment は SQLite の `judgments`、`judgment_revisions`、`judgment_relations` を machine-readable 正本とする。`nodes` と `edges` は既存 retrieval contract を保つ検索 projection であり、判断の lifecycle や provenance の正本ではない。既存 Wiki entry の本番移行は fixture による import / export 検証後の別操作とし、この実装は自動移行しない。
+
+## Domain API
+
+`NeuronGraphRAG.judgments` は add、update、supersede、archive、restore、hard delete を transaction 単位で提供する。update、supersede、archive、restore、hard delete は `expected_revision` による楽観的 concurrency check を要求する。relation target 不在、部分更新、stale revision、同一 predecessor の再 supersede は transaction 全体を失敗させる。
+
+archive 済み judgment の再 archive と active judgment の再 restore は no-op として成功させず、fail closed にする。同一 revision の反復操作によって `updated_at` を暗黙更新しない。
+
+supersede は新しい stable identity を作り、旧判断を archive し、successor から predecessor への `supersedes` relation と predecessor の `superseded_by` を保持する。superseded judgment は restore できない。
+
+archive は通常 retrieval から外す論理的忘却であり、revision、provenance、relation は監査 API から取得できる。hard delete は明示操作で、archived、revision 一致、inbound relation と successor history がない候補にだけ許可する。
+
+MCP の `write_judgment` は同じ domain API へ写像し、model に raw SQL を公開しない。既存 `search`、`record_source_use`、`record_outcome` の contract と既定値は変更しない。
+
+## Portability and recovery
+
+`tools/judgment_graph.py` は次を提供する。
+
+- `export SOURCE_DB OUTPUT_JSON`: key と judgment / relation 順序を固定した UTF-8 LF JSON を出力する。
+- `import INPUT_JSON DESTINATION_DB`: 全 identity と relation target を事前検証し、一つの transaction で再構築する。
+- `backup SOURCE_DB BACKUP_DB`: SQLite backup API で transaction-consistent copy を作る。既存出力は上書きしない。
+- `restore BACKUP_DB DESTINATION_DB`: integrity check 後に新規 destination へ復元する。既存 database は上書きしない。
+- `integrity DATABASE`: SQLite integrity、foreign key、dangling relation、二重 successor、および `superseded_by` と archived lifecycle / successor の明示的 `supersedes` relation の双方向整合を fail closed に検査する。
+
+backup は export より多くの revision history と retrieval / feedback state を保持するため、完全復旧の正本である。export は current judgment graph の決定論的 portability surface である。

docs/requirements.md

@@ -104,6 +104,7 @@
 85. baseline-aware soft-start snapshot evaluation は、v1のprotocol、gate、observed result、private snapshotを変更、再実行、再集計、入力再利用せず、fresh snapshot、新規namespace、新規output、v1 observed developmentと異なるcredited edge identityを使う。各relation caseのinitial weight、reinforced count、evidence count、confirmation countを結果前に登録し、q3/s1のfirst mutationを`max(1, quorum - initial evidence count)`で導出する。導出不能、baseline不一致、event budget内のquorum capacity不足はregistered resultを作らずfailure reportで停止する。v2 protocolはregistered output不在のfreeze-only PRで固定し、そのsquash merge後の別Issueでdevelopmentを一度だけ実行する。全8 hard gate通過時だけholdoutを一度開き、支持結果もlocal cutover候補に限定してsource database、live config、library defaultを変更しない。
 86. outcome-driven feedback deactivation はsoft-startと同時にだけ有効化できるdefault-off candidateとする。provisional / confirmationごとにcredited加算と同時発生したsame-source sibling normalization減算を一つのsigned mutation journalへ永続化し、因果帰属できる`corrected` / `rolled_back`だけが未反転contributionを基礎weight未満へ下げずexact reversalする。`superseded`はedge、evidence、trace、outcomeを削除せずrelation edgeをdormantにして通常activationから除外し、同じ保存済みcredited pathの後続`confirmed`で再活性化する。duplicate、retry、restart、transaction failure、lexical、zero-hop、別source、uncredited edge、因果帰属不能outcomeは二重減算または局所外mutationを行わない。
 87. outcome-driven deactivation evaluation はcontrol / candidate、`corrected` / `rolled_back` / `superseded`、exact credited / sibling inverse、baseline floor、dormancy / reactivation、rank / locality、source isolation、exclusive outputを結果観測前に固定する。protocolはregistered output不在のfreeze-only PRで固定し、そのsquash merge後のsuccessor Issueでdevelopmentを一度だけ実行する。全hard gate通過時だけholdoutを一度開き、観測前後にquery、case、schedule、metric、gate、default、live configを変更しない。
+88. NGR 自身の新規 judgment graph は SQLite の stable identity、revision、lifecycle、provenance、typed relation を machine-readable 正本とする。add / update / supersede / archive / restore / hard-delete candidate は raw SQL でなく atomic domain API を通し、stale revision、dangling relation、部分更新、二重 successor を fail closed にする。archive は通常 retrieval から外す論理的忘却、hard delete は履歴参照のない archived candidate だけに許す物理削除として分離する。current graph の deterministic export / atomic import と SQLite backup / integrity-checked restore を維持し、既存 Wiki entry の本番移行は fixture 検証後に分離する。
 75. v3 implementation、prompt、manifest、query override、schema、集約、path audit、hash規則、gate、stop rule、testsをresult-free commitでpushした後、development stage / 4 case packet / 12 responses / resultを各一度だけ生成する。
 76. development全12 gate通過時だけholdout stageを一度生成し、異なるfresh 12 judgesで同じgateを評価する。packet、response、resultの上書き、観測後の規則変更、実LLM品質値のCI再生成を拒否する。
 
@@ -143,3 +144,4 @@
 - [Soft-start snapshot evaluation](soft-start-snapshot-evaluation.md) が transaction-consistent private snapshot、固定4 arm、result-free freeze、privacy、one-time development、conditional holdout、local cutover境界を定義する。
 - [Outcome-driven feedback deactivation](outcome-driven-feedback-deactivation.md) がsigned contribution journal、exact reversal、dormancy / reactivation、default-off境界、result-free freezeを定義する。
 - [Baseline-aware soft-start snapshot evaluation](baseline-aware-soft-start-snapshot-evaluation.md) がfresh baseline stateからのq3 boundary導出、v1 evidence isolation、capacity preflight、新規one-time result境界を定義する。
+- [Canonical SQLite judgment graph](canonical-sqlite-judgment-graph.md) が judgment source-of-truth、domain write API、logical forgetting、hard-delete boundary、deterministic portability、backup / restore を定義する。

src/neuron_graph_rag/__init__.py

@@ -1,5 +1,6 @@
 from .engine import EngineConfig, NeuronGraphRAG
 from .feedback import FeedbackLedger
+from .judgments import JudgmentContractError, JudgmentGraph
 from .models import (
     ActivationPath,
     ConfirmedEdge,
@@ -39,6 +40,8 @@
     "FeedbackEvidence",
     "FeedbackLedger",
     "FeedbackReceipt",
+    "JudgmentContractError",
+    "JudgmentGraph",
     "NeuronGraphRAG",
     "NormalizedSiblingEdge",
     "OutcomeReceipt",

src/neuron_graph_rag/engine.py

@@ -23,6 +23,7 @@
 from .dynamics import DynamicsSettings, propagate
 from .retrieval import BM25Retriever, DenseEncoder, DenseRetriever, normalize_scores
 from .storage import SQLiteStore
+from .judgments import JudgmentGraph
 
 
 @dataclass(frozen=True, slots=True)
@@ -134,6 +135,7 @@ def __init__(
     ) -> None:
         self.config = config or EngineConfig()
         self.store = SQLiteStore(database)
+        self.judgments = JudgmentGraph(self.store)
         self.sparse_retriever = BM25Retriever()
         self.dense_retriever = DenseRetriever(dense_encoder)