feat(halachot): canonical principles model — V41 schema + backfill (Phase 1+2) #298

chaim · 2026-06-17T17:25:52Z

chaim commented

2026-06-17 17:25:52 +00:00

סיכום

מימוש Phase 1+2 של מודל ההלכות הקנוניות: במקום שורת halachot לכל (פסיקה × עיקרון), עיקרון משפטי מוגדר פעם אחת ב-canonical_halachot ופסיקות שמאזכרות אותו נקשרות כ-instances.

שינויים

Schema V41 (`mcp-server/src/legal_mcp/services/db.py`)

טבלה חדשה canonical_halachot:

canonical_statement — ניסוח קנוני (LLM-synthesized, pending_synthesis עד אישור יו"ר)
rule_type, practice_areas, subject_tags, embedding (ivfflat לחיפוש similarity)
review_status: pending_synthesis → pending_review → approved → published
first_established_in FK → case_law (מאיזו פסיקה הוגדר העיקרון לראשונה)
instance_count (denormalized)

שינויים ב-halachot:

+canonical_id UUID FK → canonical_halachot (NULL עד backfill)
+instance_type: original | citation | application
+treatment: כיצד פסיקה זו מתייחסת לעיקרון
rule_statement + embedding → nullable (citation instances יורשים מהקנונית)

שינויים ב-halacha_citation_corroboration (X11):

+canonical_id FK → canonical_halachot — X11 יצבור ברמת-העיקרון, לא ברמת-האינסטנס
store_corroboration מאכלס canonical_id אוטומטית דרך INSERT...SELECT

פונקציות DB חדשות:

create_canonical_halacha(...) — לחילוץ Phase 3
nearest_canonical_halacha(vec, threshold=0.85) — lookup-before-insert Phase 3
refresh_canonical_instance_count(canonical_id)
get_canonical_halacha(canonical_id) — עיקרון + רשימת instances

Backfill (`scripts/backfill_canonical_halachot.py`)

dry-run כברירת-מחדל; --apply לביצוע
union-find על equivalent_halachot → connected components
לכל אשכול: canonical representative (corroboration → confidence → earliest)
סינגלטונים: 1:1 canonical
מאכלס halacha_citation_corroboration.canonical_id
idempotent (דולג על halachot עם canonical_id קיים)

`scripts/SCRIPTS.md`

הוספת backfill_canonical_halachot.py
עדכון halacha_batch_reconcile.py → deprecated post-V41

Invariants

Invariant	סטטוס
G2 (אין מסלולים מקבילים)	✅ `equivalent_halachot` deprecated post-backfill
INV-G10 (שער-יו"ר)	✅ `canonical_halachot.review_status` — שער חדש לאישור עיקרון
INV-DM7 (סמכות נגזרת)	✅ authority נגזר מ-`first_established_in.precedent_level`, לא מאוחסן
INV-AH (anti-hallucination)	✅ `canonical_statement` grounded, `pending_synthesis` עד אישור
X11 (corroboration)	✅ aggregate על canonical level — סיגנל משמעותי יותר

תוכנית ביצוע אחרי merge

# 1. deploy → V41 migration רץ אוטומטית בהפעלה
# 2. dry-run (בדיקת מה יקרה)
mcp-server/.venv/bin/python scripts/backfill_canonical_halachot.py
# 3. apply
mcp-server/.venv/bin/python scripts/backfill_canonical_halachot.py --apply
# 4. verify
psql $POSTGRES_URL -c "SELECT COUNT(*) FROM canonical_halachot;"
psql $POSTGRES_URL -c "SELECT COUNT(*) FROM halachot WHERE canonical_id IS NULL;"

PRs הבאים

Phase 3+4: שינוי פייפליין-החילוץ (lookup-before-insert) + כלי MCP חדשים (canonical_halacha_list, canonical_halacha_get)
Phase 5: UI redesign (אחרי שער Claude Design)

🤖 Generated with Claude Code

## סיכום מימוש Phase 1+2 של מודל ההלכות הקנוניות: במקום שורת `halachot` לכל **(פסיקה × עיקרון)**, עיקרון משפטי מוגדר **פעם אחת** ב-`canonical_halachot` ופסיקות שמאזכרות אותו נקשרות כ-instances. ## שינויים ### Schema V41 (`mcp-server/src/legal_mcp/services/db.py`) **טבלה חדשה `canonical_halachot`:** - `canonical_statement` — ניסוח קנוני (LLM-synthesized, pending_synthesis עד אישור יו"ר) - `rule_type`, `practice_areas`, `subject_tags`, `embedding` (ivfflat לחיפוש similarity) - `review_status`: `pending_synthesis → pending_review → approved → published` - `first_established_in` FK → case_law (מאיזו פסיקה הוגדר העיקרון לראשונה) - `instance_count` (denormalized) **שינויים ב-`halachot`:** - `+canonical_id UUID FK → canonical_halachot` (NULL עד backfill) - `+instance_type`: `original` | `citation` | `application` - `+treatment`: כיצד פסיקה זו מתייחסת לעיקרון - `rule_statement` + `embedding` → nullable (citation instances יורשים מהקנונית) **שינויים ב-`halacha_citation_corroboration` (X11):** - `+canonical_id FK → canonical_halachot` — X11 יצבור ברמת-העיקרון, לא ברמת-האינסטנס - `store_corroboration` מאכלס `canonical_id` אוטומטית דרך `INSERT...SELECT` **פונקציות DB חדשות:** - `create_canonical_halacha(...)` — לחילוץ Phase 3 - `nearest_canonical_halacha(vec, threshold=0.85)` — lookup-before-insert Phase 3 - `refresh_canonical_instance_count(canonical_id)` - `get_canonical_halacha(canonical_id)` — עיקרון + רשימת instances ### Backfill (`scripts/backfill_canonical_halachot.py`) - dry-run כברירת-מחדל; `--apply` לביצוע - union-find על `equivalent_halachot` → connected components - לכל אשכול: canonical representative (corroboration → confidence → earliest) - סינגלטונים: 1:1 canonical - מאכלס `halacha_citation_corroboration.canonical_id` - idempotent (דולג על halachot עם canonical_id קיים) ### `scripts/SCRIPTS.md` - הוספת `backfill_canonical_halachot.py` - עדכון `halacha_batch_reconcile.py` → deprecated post-V41 ## Invariants | Invariant | סטטוס | |-----------|--------| | **G2** (אין מסלולים מקבילים) | ✅ `equivalent_halachot` deprecated post-backfill | | **INV-G10** (שער-יו"ר) | ✅ `canonical_halachot.review_status` — שער חדש לאישור עיקרון | | **INV-DM7** (סמכות נגזרת) | ✅ authority נגזר מ-`first_established_in.precedent_level`, לא מאוחסן | | **INV-AH** (anti-hallucination) | ✅ `canonical_statement` grounded, `pending_synthesis` עד אישור | | **X11** (corroboration) | ✅ aggregate על canonical level — סיגנל משמעותי יותר | ## תוכנית ביצוע אחרי merge ```bash # 1. deploy → V41 migration רץ אוטומטית בהפעלה # 2. dry-run (בדיקת מה יקרה) mcp-server/.venv/bin/python scripts/backfill_canonical_halachot.py # 3. apply mcp-server/.venv/bin/python scripts/backfill_canonical_halachot.py --apply # 4. verify psql $POSTGRES_URL -c "SELECT COUNT(*) FROM canonical_halachot;" psql $POSTGRES_URL -c "SELECT COUNT(*) FROM halachot WHERE canonical_id IS NULL;" ``` ## PRs הבאים - **Phase 3+4**: שינוי פייפליין-החילוץ (lookup-before-insert) + כלי MCP חדשים (`canonical_halacha_list`, `canonical_halacha_get`) - **Phase 5**: UI redesign (אחרי שער Claude Design) 🤖 Generated with [Claude Code](https://claude.com/claude-code)

chaim added 1 commit 2026-06-17 17:25:52 +00:00

feat(halachot): canonical principles model — V41 schema + backfill (Phase 1+2)

G12 Leak-Guard / leak-guard (pull_request) Successful in 4s

Details

Lint — undefined names / undefined-names (pull_request) Successful in 10s

Details

0c20f2054b

Introduces canonical_halachot table: one row per unique legal principle,
replacing the equivalent_halachot bidirectional-link model (V28/G2 improvement).
Per-precedent halachot rows become instances that point to their canonical.

Schema (V41):
- canonical_halachot: canonical_statement, rule_type, practice_areas,
  subject_tags, embedding (ivfflat), review_status (pending_synthesis→published),
  first_established_in FK → case_law, instance_count.
- halachot: +canonical_id FK, +instance_type (original|citation|application),
  +treatment; rule_statement + embedding become nullable for citation instances.
- halacha_citation_corroboration: +canonical_id FK so X11 aggregates at
  principle level, not instance level. store_corroboration auto-populates it
  via INSERT...SELECT.

New DB functions: create_canonical_halacha, nearest_canonical_halacha
(threshold search for Phase 3 lookup-before-insert), refresh_canonical_instance_count,
get_canonical_halacha (principle + instance list).

Backfill: scripts/backfill_canonical_halachot.py — dry-run by default,
--apply to execute. Uses union-find over equivalent_halachot pairs, picks
canonical representative (corroboration→confidence→earliest), creates canonicals,
sets canonical_id + instance_type on all instances.

Invariants: G2 (equivalent_halachot deprecated post-backfill), INV-G10
(canonical review_status gate), INV-DM7 (authority derived, not stored),
INV-AH (canonical_statement grounded in source statements, pending_synthesis
until chair approves).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

chaim merged commit aba87737e3 into main

2026-06-17 17:27:53 +00:00

chaim deleted branch worktree-canonical-halachot

2026-06-17 17:27:53 +00:00

chaim referenced this issue from a commit

2026-06-17 17:27:54 +00:00

Merge pull request 'feat(halachot): canonical principles model — V41 schema + backfill (Phase 1+2)' (#298) from worktree-canonical-halachot into main

chaim referenced this pull request

2026-06-17 17:36:34 +00:00

feat(halachot): canonical lookup-before-insert + MCP tools (Phase 3+4) #299

Sign in to join this conversation.