feat(1k.1a): Hub Layout-Engine — replaces 21 templates with semantic engine

backend/alembic/versions/20260605_phase1k1a_drop_preset_template_id.py

@@ -0,0 +1,63 @@
+"""Phase 1k.1a: drop presets.template_id column and templates table
+
+The Template model and TemplateLoader were removed in Phase 1k.1a (layout
+engine replaces template-based rendering). This migration:
+  1. Drops the presets.template_id column (includes its FK to templates.id)
+  2. Drops the templates table (no longer managed by any SQLModel class)
+
+SQLite note: SQLite does not support named FK constraints. Alembic batch
+mode handles FK removal implicitly when the column is dropped — no explicit
+drop_constraint call is needed.
+
+Revision ID: 20260605a1b2c3d4
+Revises: a0516c04278c
+Create Date: 2026-06-05 00:00:00.000000
+"""
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "20260605a1b2c3d4"
+down_revision: str | Sequence[str] | None = "a0516c04278c"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    """Drop template_id from presets, then drop templates table."""
+    # Batch mode recreates the table without the dropped column, which
+    # also removes the FK constraint in SQLite (no explicit drop_constraint).
+    with op.batch_alter_table("presets", schema=None) as batch_op:
+        batch_op.drop_column("template_id")
+
+    # Drop the templates table — no Python model references it any more.
+    op.drop_table("templates")
+
+
+def downgrade() -> None:
+    """Recreate templates table and restore template_id column on presets."""
+    # Recreate the minimal templates table schema from migration 54f963fdb994.
+    op.create_table(
+        "templates",
+        sa.Column("id", sa.Uuid(), nullable=False),
+        sa.Column("key", sa.String(), nullable=False),
+        sa.Column("name", sa.String(), nullable=False),
+        sa.Column("app", sa.String(), nullable=True),
+        sa.Column("printer_model", sa.String(), nullable=True),
+        sa.Column("tape_width_mm", sa.Integer(), nullable=False),
+        sa.Column("schema_version", sa.Integer(), nullable=False, server_default="1"),
+        sa.Column("definition", sa.JSON(), nullable=True),
+        sa.Column("source", sa.String(), nullable=False, server_default="seed"),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
+        sa.PrimaryKeyConstraint("id"),
+        sa.UniqueConstraint("key"),
+    )
+    with op.batch_alter_table("presets", schema=None) as batch_op:
+        batch_op.add_column(sa.Column("template_id", sa.Uuid(), nullable=True))
+        # SQLite does not support named FK constraints and alembic batch mode
+        # requires a name for create_foreign_key. FK is omitted in downgrade
+        # (column is re-added without FK constraint — acceptable for rollback).

backend/alembic/versions/20260605b_jobs_template_key_nullable.py

@@ -0,0 +1,41 @@
+"""Phase 1k.1a: make jobs.template_key nullable to match SQLModel definition
+
+The Job model defines template_key as Optional[str] (nullable=True) but the
+initial jobs migration (e0d573b37f5b) created it as NOT NULL. This migration
+corrects the nullable mismatch so alembic check passes.
+
+Revision ID: 20260605b2c3d4e5
+Revises: 20260605a1b2c3d4
+Create Date: 2026-06-05 00:01:00.000000
+"""
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "20260605b2c3d4e5"
+down_revision: str | Sequence[str] | None = "20260605a1b2c3d4"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    """Make jobs.template_key nullable (SQLite batch mode)."""
+    with op.batch_alter_table("jobs", schema=None) as batch_op:
+        batch_op.alter_column(
+            "template_key",
+            existing_type=sa.String(),
+            nullable=True,
+        )
+
+
+def downgrade() -> None:
+    """Restore jobs.template_key to NOT NULL."""
+    with op.batch_alter_table("jobs", schema=None) as batch_op:
+        batch_op.alter_column(
+            "template_key",
+            existing_type=sa.String(),
+            nullable=False,
+        )

backend/app/api/error_handlers.py

@@ -15,7 +15,6 @@
     docs/superpowers/specs/2026-05-16-phase6a-rest-api-design.md
     app/services/errors.py
     app/printer_backends/exceptions.py
-    app/services/template_loader.py
 """
 
 from __future__ import annotations
@@ -34,15 +33,13 @@
 )
 from app.schemas.problem import ProblemDetail
 from app.services.errors import AppLookupNotFoundError
-from app.services.template_loader import TemplateNotFoundError
 
 # Mapping: exception class → (HTTP status code, problem-type slug)
 _MAPPING: dict[type[Exception], tuple[int, str]] = {
     PrinterOfflineError: (503, "printer-offline"),
     TapeMismatchError: (409, "tape-mismatch"),
     TapeEmptyError: (409, "tape-empty"),
     PrinterCoverOpenError: (409, "printer-cover-open"),
-    TemplateNotFoundError: (404, "template-not-found"),
     AppLookupNotFoundError: (404, "app-lookup-not-found"),
 }
 

backend/app/api/routes/batch.py

@@ -12,7 +12,6 @@
 from app.auth.scope_deps import require_print
 from app.db.session import get_session
 from app.models.print_batch import PrintBatch
-from app.printer_backends.base import PrinterBackend  # noqa: F401 — used by dispatch_batch typing
 from app.printer_backends.exceptions import (
     PrinterCoverOpenError,
     PrinterOfflineError,
@@ -22,7 +21,7 @@
 from app.repositories import print_batches as batches_repo
 from app.repositories import printers as printers_repo
 from app.schemas.print_batch import BatchRequest, BatchResponse
-from app.services.batch_dispatch import MixedTapeSizesError, dispatch_batch
+from app.services.batch_dispatch import dispatch_batch
 
 # SessionDep locally — Hub has no central app/api/deps.py module.
 SessionDep = Annotated[AsyncSession, Depends(get_session)]
@@ -106,13 +105,18 @@ async def create_batch(
             },
         ) from err
 
-    # 6. Best-effort dispatch
+    # 6. Dispatch (half_cut: override takes precedence over backend capability)
+    backend_supports_half_cut: bool = getattr(backend, "half_cut_supported", False)
+    if body.half_cut_override is not None:
+        use_half_cut = body.half_cut_override and backend_supports_half_cut
+    else:
+        use_half_cut = backend_supports_half_cut
+
     try:
-        job_ids, errors = await dispatch_batch(
-            service,
-            body.items,
-            half_cut_override=body.half_cut_override,
-            backend=backend,
+        job_ids = await dispatch_batch(
+            service=service,
+            items=body.items,
+            half_cut=use_half_cut,
         )
     except (PrinterOfflineError, PrinterCoverOpenError, SnmpQueryError, TapeMismatchError) as exc:
         raise HTTPException(
@@ -122,22 +126,13 @@ async def create_batch(
                 "error_message": str(exc),
             },
         ) from exc
-    except MixedTapeSizesError as exc:
-        raise HTTPException(
-            400,
-            detail={
-                "error_code": "mixed_tape_sizes",
-                "error_message": str(exc),
-                "tape_mm_values": sorted(set(exc.tape_mm_values)),
-            },
-        ) from exc
 
     # 7. Persist tracking row
     # auth.subject_id does NOT exist — use api_key_id or source
     created_by = str(auth.api_key_id) if auth.api_key_id else auth.source
     batch_row = PrintBatch(
         printer_id=printer.id,
-        job_ids=job_ids,
+        job_ids=[str(jid) for jid in job_ids],
         created_by=created_by,
     )
     await batches_repo.create(session, batch_row)
@@ -146,6 +141,5 @@ async def create_batch(
         batch_id=batch_row.id,
         printer_id=printer.id,
         queued_at=datetime.now(UTC).isoformat().replace("+00:00", "Z"),
-        job_ids=job_ids,
-        errors=errors,
+        job_ids=[str(jid) for jid in job_ids],
     )

backend/app/api/routes/print.py

@@ -1,31 +1,37 @@
-"""POST /print + GET /jobs/{job_id} + POST /jobs/{job_id}/resume."""
+"""POST /print + GET /jobs/{job_id} + POST /jobs/{job_id}/resume + POST /render/preview."""
 
 from __future__ import annotations
 
+import io
 import logging
 from typing import Annotated, Any
 from uuid import UUID
 
 from fastapi import APIRouter, Depends, HTTPException, Request, status
-from fastapi.responses import JSONResponse
+from fastapi.responses import JSONResponse, Response
 from pydantic import BaseModel
 
 from app.auth.dependencies import AuthContext
 from app.auth.scope_deps import require_print, require_read
 from app.printer_backends.exceptions import (
+    ContentTypeDataMismatchError,
+    NoTapeLoadedError,
     PrinterCoverOpenError,
     PrinterOfflineError,
     SnmpQueryError,
     TapeEmptyError,
     TapeMismatchError,
+    UnsupportedTapeError,
 )
 from app.printer_backends.snmp_helper import LiveStatus, query_live_status
-from app.schemas.print_request import PrintRequest
+from app.schemas.content_type import ContentType
+from app.schemas.label_data import LabelData
+from app.schemas.print_request import PrintRequest, RawLabelData
 from app.schemas.print_response import PrintJobResponse, PrintJobStatusResponse
 from app.services.job_lifecycle import JobState
+from app.services.layout_engine import LayoutEngine
 from app.services.lookup_service import LookupFailedError
 from app.services.print_queue import PrinterAlreadyActiveError
-from app.services.template_loader import TemplateNotFoundError
 
 _log = logging.getLogger(__name__)
 
@@ -40,10 +46,10 @@
 
 
 _SYNC_ERROR_MAP: dict[type[Exception], tuple[int, str]] = {
-    TemplateNotFoundError: (404, "template_not_found"),
     LookupFailedError: (502, "integration_lookup_failed"),
     TapeMismatchError: (409, "tape_mismatch"),
     TapeEmptyError: (409, "tape_empty"),
+    NoTapeLoadedError: (409, "no_tape_loaded"),
     PrinterCoverOpenError: (409, "printer_cover_open"),
     PrinterOfflineError: (503, "printer_offline"),
 }
@@ -244,3 +250,73 @@
         finished_at=getattr(job, "finished_at", None),
         live=None,
     )
+
+
+class _PreviewRequest(BaseModel):
+    """Request body for POST /render/preview.
+
+    Phase 1k.1a (Task 25): render-only endpoint — no printer, no queue, no DB.
+    """
+
+    content_type: ContentType
+    data: RawLabelData
+    tape_mm: int = 12
+
+
+@router.post(
+    "/render/preview",
+    tags=["print"],
+    summary="Render a label preview as PNG",
+    description=(
+        "Render a label using the LayoutEngine and return the result as a "
+        "PNG image (no printer interaction, no job created).  "
+        "Useful for UI preview and debugging.  "
+        "Returns 422 when ``data`` is missing fields required by ``content_type``.  "
+        "Returns 409 when ``tape_mm`` is not a supported tape width."
+    ),
+    response_class=Response,
+    responses={
+        200: {"content": {"image/png": {}}, "description": "PNG label bitmap"},
+        409: {"description": "Unsupported tape width"},
+        422: {"description": "Data missing required fields for content_type"},
+    },
+)
+async def render_preview(
+    body: _PreviewRequest,
+    _auth: Annotated[AuthContext, Depends(require_read)],
+) -> Response:
+    """Render a label preview without touching the printer or DB.
+
+    Uses a fresh LayoutEngine instance so that this endpoint works even
+    when no printer is configured (dev / CI mode).
+
+    Returns 200 with Content-Type: image/png on success.
+    Returns 409 (unsupported_tape) when tape_mm is not in TAPE_GEOMETRY.
+    Returns 422 (data_mismatch) when data is missing fields for content_type.
+    """
+    engine = LayoutEngine()
+    label_data = LabelData(
+        primary_id=body.data.primary_id,
+        title=body.data.title,
+        qr_payload=body.data.qr_payload,
+        source_app="preview",
+        secondary=body.data.secondary,
+        items=body.data.items,
+    )
+    try:
+        image = engine.render(body.tape_mm, body.content_type, label_data)
+    except UnsupportedTapeError as exc:
+        return JSONResponse(
+            status_code=status.HTTP_409_CONFLICT,
+            content={"error_code": "unsupported_tape", "error_message": str(exc)},
+        )
+    except ContentTypeDataMismatchError as exc:
+        return JSONResponse(
+            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            content={"error_code": "data_mismatch", "error_message": str(exc)},
+        )
+
+    buf = io.BytesIO()
+    image.save(buf, format="PNG")
+    buf.seek(0)
+    return Response(content=buf.read(), media_type="image/png")