Phase 6: HITL review endpoints + audit trail

- New job_corrections table (append-only audit log) + migration
- Add approved / reviewed_by / reviewed_at columns to jobs
- PATCH  /documents/{id}         apply field-level corrections
- GET    /documents/{id}/history return chronological audit trail
- POST   /documents/{id}/approve lock final version (idempotent)
- Dotted field-path applier with root allow-list + list-index support
- Auto-clear `missing_field` review flag when required header keys filled
- Atomic batch apply: malformed path in batch rolls back all changes
- 22 new tests (11 repository-level, 11 API-level); 184 total passing

Co-Authored-By: adrian kuman firmansah <adriancuman@gmail.com>

alembic/versions/3b1f2c9a4d56_phase6_hitl_tables.py

@@ -0,0 +1,60 @@
+"""phase6 hitl: job_corrections + approval columns
+
+Revision ID: 3b1f2c9a4d56
+Revises: ff8c14fbf8a0
+Create Date: 2026-04-25 14:30:00.000000
+"""
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "3b1f2c9a4d56"
+down_revision: str | None = "ff8c14fbf8a0"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    with op.batch_alter_table("jobs") as batch:
+        batch.add_column(
+            sa.Column(
+                "approved",
+                sa.Boolean(),
+                nullable=False,
+                server_default=sa.false(),
+            )
+        )
+        batch.add_column(sa.Column("reviewed_by", sa.String(length=128), nullable=True))
+        batch.add_column(sa.Column("reviewed_at", sa.DateTime(timezone=True), nullable=True))
+
+    op.create_table(
+        "job_corrections",
+        sa.Column("id", sa.Integer(), autoincrement=True, nullable=False),
+        sa.Column("job_id", sa.Uuid(), nullable=False),
+        sa.Column("field_path", sa.String(length=256), nullable=False),
+        sa.Column("old_value", sa.JSON(), nullable=True),
+        sa.Column("new_value", sa.JSON(), nullable=True),
+        sa.Column("corrected_by", sa.String(length=128), nullable=True),
+        sa.Column("reason", sa.String(length=512), nullable=True),
+        sa.Column("corrected_at", sa.DateTime(timezone=True), nullable=False),
+        sa.ForeignKeyConstraint(["job_id"], ["jobs.job_id"], ondelete="CASCADE"),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index(
+        op.f("ix_job_corrections_job_id"),
+        "job_corrections",
+        ["job_id"],
+        unique=False,
+    )
+
+
+def downgrade() -> None:
+    op.drop_index(op.f("ix_job_corrections_job_id"), table_name="job_corrections")
+    op.drop_table("job_corrections")
+    with op.batch_alter_table("jobs") as batch:
+        batch.drop_column("reviewed_at")
+        batch.drop_column("reviewed_by")
+        batch.drop_column("approved")

alembic/versions/ff8c14fbf8a0_phase4_jobs_table.py

@@ -1,17 +1,17 @@
 """phase4 jobs table
 
 Revision ID: ff8c14fbf8a0
-Revises: 
+Revises:
 Create Date: 2026-04-25 15:54:18.579147
 """
+
 from collections.abc import Sequence
 
-from alembic import op
 import sqlalchemy as sa
-
+from alembic import op
 
 # revision identifiers, used by Alembic.
-revision: str = 'ff8c14fbf8a0'
+revision: str = "ff8c14fbf8a0"
 down_revision: str | None = None
 branch_labels: str | Sequence[str] | None = None
 depends_on: str | Sequence[str] | None = None
@@ -19,24 +19,25 @@ depends_on: str | Sequence[str] | None = None
 
 def upgrade() -> None:
     # ### commands auto generated by Alembic - please adjust! ###
-    op.create_table('jobs',
-    sa.Column('job_id', sa.Uuid(), nullable=False),
-    sa.Column('status', sa.String(length=32), nullable=False),
-    sa.Column('source_kind', sa.String(length=16), nullable=False),
-    sa.Column('filename', sa.String(length=512), nullable=False),
-    sa.Column('blob_key', sa.String(length=512), nullable=True),
-    sa.Column('confidence', sa.Float(), nullable=True),
-    sa.Column('review_flags', sa.JSON(), nullable=False),
-    sa.Column('result', sa.JSON(), nullable=True),
-    sa.Column('error', sa.String(length=2048), nullable=True),
-    sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
-    sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False),
-    sa.PrimaryKeyConstraint('job_id')
+    op.create_table(
+        "jobs",
+        sa.Column("job_id", sa.Uuid(), nullable=False),
+        sa.Column("status", sa.String(length=32), nullable=False),
+        sa.Column("source_kind", sa.String(length=16), nullable=False),
+        sa.Column("filename", sa.String(length=512), nullable=False),
+        sa.Column("blob_key", sa.String(length=512), nullable=True),
+        sa.Column("confidence", sa.Float(), nullable=True),
+        sa.Column("review_flags", sa.JSON(), nullable=False),
+        sa.Column("result", sa.JSON(), nullable=True),
+        sa.Column("error", sa.String(length=2048), nullable=True),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
+        sa.PrimaryKeyConstraint("job_id"),
     )
     # ### end Alembic commands ###
 
 
 def downgrade() -> None:
     # ### commands auto generated by Alembic - please adjust! ###
-    op.drop_table('jobs')
+    op.drop_table("jobs")
     # ### end Alembic commands ###