Development approach c

.github/workflows/lint.yml

@@ -4,7 +4,7 @@ on:
   push:
     branches: [main,development]
   pull_request:
-    branches: [main,development]
+    branches: [main, development, 'development-*']
 
 jobs:
   lint:
@@ -23,7 +23,7 @@ jobs:
         uses: astral-sh/setup-uv@v6
 
       - name: Install linter
-        run: uv pip install --system ruff
+        run: uv pip install --system ruff==0.16.1
 
       - name: Run linter
         run: |

.github/workflows/tests.yml

@@ -9,7 +9,7 @@ on:
       - 'alembic.ini'
       - '.github/workflows/tests.yml'
   pull_request:
-    branches: [main,development]
+    branches: [main, development, 'development-*']
     paths:
       - '**.py'
       - 'requirements.txt'

Makefile

@@ -34,6 +34,7 @@ help:
 	@echo "make docs         - Serve interactive API docs from the OpenAPI contract"
 	@echo "make migrate      - Run pending Alembic migrations"
 	@echo "make migration    - Generate new migration (msg='description')"
+	@echo "make generate-contract-models - Regenerate Pydantic models from the incident contract"
 	@echo "make clean        - Stop containers (preserves volumes)"
 	@echo "make super-clean  - [CAUTION] Stop containers, delete volumes, prune Docker"
 
@@ -114,7 +115,11 @@ migrate:
 	@$(COMPOSE) exec -T app alembic upgrade head
 
 migration:
-	@$(COMPOSE) exec -T app alembic revision --autogenerate -m "$(msg)"
+	@test -n "$(rev)" || { echo "rev is required, e.g. make migration rev=003 msg=\"...\""; exit 1; }
+	@$(COMPOSE) exec -T app alembic revision --autogenerate --rev-id "$(rev)" -m "$(msg)"
+
+generate-contract-models:
+	@$(COMPOSE) exec -T app sh -c "uv pip install --system -r requirements-dev.txt && python3 scripts/generate_contract_models.py"
 
 clean:
 	@$(COMPOSE) down

alembic/versions/003_move_incident_contract_onto_incident_row.py

@@ -0,0 +1,73 @@
+"""move incident contract onto incident row
+
+Revision ID: 003
+Revises: 002
+Create Date: 2026-07-30 09:26:53.879663
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+import sqlmodel
+from sqlalchemy.dialects import postgresql
+
+# revision identifiers, used by Alembic.
+revision: str = '003'
+down_revision: Union[str, None] = '002'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.add_column('extractions', sa.Column('partial_result', sa.JSON(), nullable=True))
+    op.drop_column('extractions', 'incident_contract')
+    op.add_column('incidents', sa.Column('incident_contract', sa.JSON(), nullable=True))
+    op.add_column('incidents', sa.Column('incident_category', sqlmodel.sql.sqltypes.AutoString(), nullable=True))
+    op.add_column('incidents', sa.Column('incident_datetime', sa.DateTime(), nullable=True))
+    op.add_column('incidents', sa.Column('city', sqlmodel.sql.sqltypes.AutoString(), nullable=True))
+    op.add_column('incidents', sa.Column('state', sqlmodel.sql.sqltypes.AutoString(), nullable=True))
+    op.add_column('incidents', sa.Column('country', sqlmodel.sql.sqltypes.AutoString(), nullable=True))
+    op.add_column('incidents', sa.Column('civilian_injuries', sa.Integer(), nullable=True))
+    op.add_column('incidents', sa.Column('civilian_fatalities', sa.Integer(), nullable=True))
+    op.add_column('incidents', sa.Column('responder_injuries', sa.Integer(), nullable=True))
+    op.add_column('incidents', sa.Column('responder_fatalities', sa.Integer(), nullable=True))
+    op.add_column('incidents', sa.Column('people_rescued', sa.Integer(), nullable=True))
+    op.add_column('incidents', sa.Column('people_evacuated', sa.Integer(), nullable=True))
+    op.add_column('incidents', sa.Column('structures_destroyed', sa.Integer(), nullable=True))
+    op.add_column('incidents', sa.Column('area_burned_ha', sa.Float(), nullable=True))
+    op.add_column('incidents', sa.Column('total_loss_amount', sa.Float(), nullable=True))
+    op.add_column('incidents', sa.Column('total_loss_currency', sqlmodel.sql.sqltypes.AutoString(), nullable=True))
+    op.add_column('incidents', sa.Column('call_to_arrival_seconds', sa.Integer(), nullable=True))
+    op.add_column('incidents', sa.Column('turnout_seconds_first_unit', sa.Integer(), nullable=True))
+    op.add_column('incidents', sa.Column('travel_seconds_first_unit', sa.Integer(), nullable=True))
+    op.add_column('incidents', sa.Column('on_scene_duration_seconds', sa.Integer(), nullable=True))
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_column('incidents', 'on_scene_duration_seconds')
+    op.drop_column('incidents', 'travel_seconds_first_unit')
+    op.drop_column('incidents', 'turnout_seconds_first_unit')
+    op.drop_column('incidents', 'call_to_arrival_seconds')
+    op.drop_column('incidents', 'total_loss_currency')
+    op.drop_column('incidents', 'total_loss_amount')
+    op.drop_column('incidents', 'area_burned_ha')
+    op.drop_column('incidents', 'structures_destroyed')
+    op.drop_column('incidents', 'people_evacuated')
+    op.drop_column('incidents', 'people_rescued')
+    op.drop_column('incidents', 'responder_fatalities')
+    op.drop_column('incidents', 'responder_injuries')
+    op.drop_column('incidents', 'civilian_fatalities')
+    op.drop_column('incidents', 'civilian_injuries')
+    op.drop_column('incidents', 'country')
+    op.drop_column('incidents', 'state')
+    op.drop_column('incidents', 'city')
+    op.drop_column('incidents', 'incident_datetime')
+    op.drop_column('incidents', 'incident_category')
+    op.drop_column('incidents', 'incident_contract')
+    op.add_column('extractions', sa.Column('incident_contract', postgresql.JSON(astext_type=sa.Text()), autoincrement=False, nullable=True))
+    op.drop_column('extractions', 'partial_result')
+    # ### end Alembic commands ###

alembic/versions/004_form_templates.py

@@ -0,0 +1,78 @@
+"""form templates registry and pdf upload drafts
+
+Revision ID: 004
+Revises: 003
+Create Date: 2026-08-10
+
+Two tables, both new in the contract Layer 6 template work.
+
+`form_templates` is the registry, keyed by `form_type` and distinct from the
+legacy `template` table (int PK + uploaded PDF). Its `fields` JSON column holds
+the TemplateField list, each with a nested `layout`. `form_type` stays a plain
+VARCHAR rather than a Postgres enum, because jurisdictions register their own
+form types and those are not part of the built-in FormType enum.
+
+`template_uploads` holds the drafts behind the PDF authoring flow: the stored
+blank PDF, its page geometry, and the fields commonforms detected. Rows here
+are working state, not templates. Registering a template copies the edited
+fields across and keeps only the `pdf_template_ref` pointing back.
+
+Both JSON columns use sa.JSON for consistency with migrations 001-003 and for
+the SQLite test harness.
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+import sqlmodel
+
+
+# revision identifiers, used by Alembic.
+revision: str = '004'
+down_revision: Union[str, None] = '003'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table('form_templates',
+    sa.Column('template_id', sa.Uuid(), nullable=False),
+    sa.Column('form_type', sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+    sa.Column('display_name', sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+    sa.Column('jurisdiction', sqlmodel.sql.sqltypes.AutoString(), nullable=True),
+    sa.Column('agency_type', sqlmodel.sql.sqltypes.AutoString(), nullable=True),
+    sa.Column('fields', sa.JSON(), nullable=False),
+    sa.Column('source_standard', sqlmodel.sql.sqltypes.AutoString(), nullable=True),
+    sa.Column('pdf_template_ref', sqlmodel.sql.sqltypes.AutoString(), nullable=True),
+    sa.Column('version', sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+    sa.Column('status', sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+    sa.Column('created_at', sa.DateTime(), nullable=False),
+    sa.Column('updated_at', sa.DateTime(), nullable=False),
+    sa.PrimaryKeyConstraint('template_id')
+    )
+    op.create_index(op.f('ix_form_templates_form_type'), 'form_templates', ['form_type'], unique=True)
+    op.create_table('template_uploads',
+    sa.Column('upload_id', sa.Uuid(), nullable=False),
+    sa.Column('status', sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+    sa.Column('pdf_path', sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+    sa.Column('pdf_template_ref', sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+    sa.Column('original_filename', sqlmodel.sql.sqltypes.AutoString(), nullable=True),
+    sa.Column('page_count', sa.Integer(), nullable=False),
+    sa.Column('pages', sa.JSON(), nullable=False),
+    sa.Column('detected_fields', sa.JSON(), nullable=True),
+    sa.Column('detection_error', sqlmodel.sql.sqltypes.AutoString(), nullable=True),
+    sa.Column('job_id', sqlmodel.sql.sqltypes.AutoString(), nullable=True),
+    sa.Column('created_at', sa.DateTime(), nullable=False),
+    sa.Column('updated_at', sa.DateTime(), nullable=False),
+    sa.PrimaryKeyConstraint('upload_id')
+    )
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_table('template_uploads')
+    op.drop_index(op.f('ix_form_templates_form_type'), table_name='form_templates')
+    op.drop_table('form_templates')
+    # ### end Alembic commands ###

alembic/versions/005_form_incident_template_batch.py

@@ -0,0 +1,59 @@
+"""forms: key by template, require incident, group by batch, drop extract_id
+
+Revision ID: 005
+Revises: 004
+Create Date: 2026-08-17
+
+Form generation (contract Layer 3, #552) keys a form by which template filled
+it and reaches the extraction through the incident rather than a direct link
+(incidents already FK the extraction, so extract_id was a redundant hop).
+Batching is a grouping key only — batch_id has no Batch table, batch status is
+derived on the fly from the Form rows that share an id.
+
+No route or repository writes a v1 Form row yet (form generation itself is
+still unimplemented), so the forms table is empty in every environment and
+the NOT NULL adds below are safe — there is no existing data to backfill.
+
+FK constraints are named explicitly, matching Postgres' own default
+`<table>_<column>_fkey` pattern, so downgrade can drop them by name. The same
+naming_convention is handed to batch_alter_table so SQLite's reflect-and-
+recreate path (needed for the incident_id nullable flip and the extract_id
+drop, neither of which SQLite can ALTER in place) assigns identical names.
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = '005'
+down_revision: Union[str, None] = '004'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+NAMING_CONVENTION = {"fk": "%(table_name)s_%(column_0_name)s_fkey"}
+
+
+def upgrade() -> None:
+    with op.batch_alter_table('forms', naming_convention=NAMING_CONVENTION) as batch_op:
+        batch_op.add_column(sa.Column('template_id', sa.Uuid(), nullable=False))
+        batch_op.create_foreign_key(
+            'forms_template_id_fkey', 'form_templates', ['template_id'], ['template_id']
+        )
+        batch_op.add_column(sa.Column('batch_id', sa.Uuid(), nullable=True))
+        batch_op.drop_constraint('forms_extract_id_fkey', type_='foreignkey')
+        batch_op.drop_column('extract_id')
+        batch_op.alter_column('incident_id', existing_type=sa.Uuid(), nullable=False)
+
+
+def downgrade() -> None:
+    with op.batch_alter_table('forms', naming_convention=NAMING_CONVENTION) as batch_op:
+        batch_op.alter_column('incident_id', existing_type=sa.Uuid(), nullable=True)
+        batch_op.add_column(sa.Column('extract_id', sa.Uuid(), nullable=False))
+        batch_op.create_foreign_key(
+            'forms_extract_id_fkey', 'extractions', ['extract_id'], ['extract_id']
+        )
+        batch_op.drop_constraint('forms_template_id_fkey', type_='foreignkey')
+        batch_op.drop_column('template_id')
+        batch_op.drop_column('batch_id')

alembic/versions/006_incidents_crud_indexes.py

@@ -0,0 +1,35 @@
+"""incidents crud indexes
+
+Revision ID: 006
+Revises: 005
+Create Date: 2026-08-22 06:49:34.422095
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+import sqlmodel
+
+
+# revision identifiers, used by Alembic.
+revision: str = '006'
+down_revision: Union[str, None] = '005'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_index('ix_incidents_live_datetime', 'incidents', ['deleted_at', 'incident_datetime'], unique=False)
+    op.create_index('ix_incidents_number_live', 'incidents', ['incident_number'], unique=True, postgresql_where=sa.text('incident_number IS NOT NULL AND deleted_at IS NULL'), sqlite_where=sa.text('incident_number IS NOT NULL AND deleted_at IS NULL'))
+    op.drop_column('incidents', 'incident_date')
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.add_column('incidents', sa.Column('incident_date', sa.DATE(), autoincrement=False, nullable=True))
+    op.drop_index('ix_incidents_number_live', table_name='incidents', postgresql_where=sa.text('incident_number IS NOT NULL AND deleted_at IS NULL'), sqlite_where=sa.text('incident_number IS NOT NULL AND deleted_at IS NULL'))
+    op.drop_index('ix_incidents_live_datetime', table_name='incidents')
+    # ### end Alembic commands ###

app/api/router.py

@@ -1,13 +1,33 @@
 from fastapi import APIRouter
 
-from app.api.routes import forms, input, jobs, system, templates, weather, zipcode
+from app.api.routes import (
+    extraction,
+    form_generation,
+    forms,
+    form_templates,
+    incidents,
+    input,
+    jobs,
+    system,
+    weather,
+    zipcode,
+)
 from app.core.config import API_PREFIX
 
 api_router = APIRouter()
-api_router.include_router(templates.router, prefix=API_PREFIX)
+api_router.include_router(form_templates.router, prefix=API_PREFIX)
 api_router.include_router(forms.router, prefix=API_PREFIX)
+# v1 form generation — same "/forms" prefix as the legacy router above, kept
+# in a separate file/router rather than added to forms.py. Included AFTER
+# `forms` on purpose: the legacy router's literal GET paths (/forms/models,
+# /forms/submissions, ...) must be matched before this router's catch-all
+# GET /forms/{form_id}, same reasoning form_templates.py uses for /pdf vs
+# /{template_id} — otherwise "models"/"submissions" would be read as a form_id.
+api_router.include_router(form_generation.router, prefix=API_PREFIX)
 api_router.include_router(system.router, prefix=API_PREFIX)
 api_router.include_router(jobs.router, prefix=API_PREFIX)
 api_router.include_router(weather.router, prefix=API_PREFIX)
 api_router.include_router(zipcode.router, prefix=API_PREFIX)
-api_router.include_router(input.router, prefix=API_PREFIX)
+api_router.include_router(input.router, prefix=API_PREFIX)
+api_router.include_router(extraction.router, prefix=API_PREFIX)
+api_router.include_router(incidents.router, prefix=API_PREFIX)

app/api/routes/__init__.py

@@ -1,3 +1,3 @@
-from . import templates, forms
+from . import form_templates, forms
 
-__all__ = ["templates", "forms"]
+__all__ = ["form_templates", "forms"]