Phase 7a: Schema + Hierarchy Relaxation

phase-postgres-7a-schema-hierarchy Phase

Project

Goal: Create the blocks and compiled_pages tables. Relax the parent-child hierarchy so any note type can nest under any other.

Owner: Dev agent

Repo: pal-e-docs

Depends on: Phase 5 (COMPLETED)

Parent phase: Phase 7 (Block-Structured Content Model)

Why First

The tables must exist before any parser, compiler, or migration code can run. The hierarchy relaxation is a simple constraint removal that immediately unblocks nesting 6 orphaned docs — value delivered on day one with zero risk.

Deliverables

Alembic migration: blocks table

blocks
  id          serial PK
  note_id     FK → notes
  position    integer
  block_type  varchar (heading/paragraph/code/table/mermaid/list/callout)
  content     jsonb
  anchor_id   varchar (deterministic, generated from content)
  created_at  timestamp
  updated_at  timestamp

Alembic migration: compiled_pages table

compiled_pages
  id            serial PK
  note_id       FK → notes (unique)
  html          text
  toc_json      jsonb
  content_hash  varchar(64)
  compiled_at   timestamp

Relax parent_note_id constraint: Remove the validation that only phase notes can have a parent and that parents must be plan type. Any note type can have a parent of any type.
SQLAlchemy models: Block and CompiledPage models with relationships to Note.

Acceptance Criteria

Tables exist in Postgres with correct columns, indexes, and FKs
Hierarchy relaxation works: update_note(slug="concept-phase5-database-side-intelligence", parent_slug="phase-postgres-5-fulltext-search") succeeds
All 6 orphaned docs can be nested under their logical parents
Existing behavior unchanged — blocks/compiled_pages tables are empty, no reads/writes touch them yet
All existing tests pass

Immediate Value

After this phase ships, Betty Sue can nest the 6 orphaned docs (see benchmark-phase7-block-baseline). No parser needed — just a constraint removal.

Estimated Scope

1 Alembic migration, 2 SQLAlchemy models, 1 validation change. Small, clean PR.