interlaced 2.4.0__tar.gz → 2.5.0__tar.gz

{interlaced-2.4.0/src/interlaced.egg-info → interlaced-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: interlaced
-Version: 2.4.0
+Version: 2.5.0
 Summary: Python and SQL models in one DAG. Transformation, orchestration and durable streaming in one process, on DuckDB and Postgres.
 Author-email: Mark <mark@interlace.sh>
 License-Expression: MIT
@@ -192,7 +192,8 @@ $ interlace plan
 - **`interlace env rollback`** repoints an environment's views at any earlier promotion — nothing
   rebuilds, the views move; every apply records a generation, so a bad deploy reverts in one
   command. `interlace gc` removes snapshots no environment references (reference-aware: tables
-  shared through reuse survive).
+  shared through reuse survive). `interlace reset --yes` wipes owned state for a fresh apply
+  without dropping `materialise: table` / `file` destinations.
 
 ## Streaming
 

{interlaced-2.4.0 → interlaced-2.5.0}/README.md

@@ -126,7 +126,8 @@ $ interlace plan
 - **`interlace env rollback`** repoints an environment's views at any earlier promotion — nothing
   rebuilds, the views move; every apply records a generation, so a bad deploy reverts in one
   command. `interlace gc` removes snapshots no environment references (reference-aware: tables
-  shared through reuse survive).
+  shared through reuse survive). `interlace reset --yes` wipes owned state for a fresh apply
+  without dropping `materialise: table` / `file` destinations.
 
 ## Streaming
 

{interlaced-2.4.0 → interlaced-2.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "interlaced"
-version = "2.4.0"
+version = "2.5.0"
 description = "Python and SQL models in one DAG. Transformation, orchestration and durable streaming in one process, on DuckDB and Postgres."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -138,6 +138,7 @@ module = [
     "sqlglot.*",
     "pyarrow.*",
     "yaml",
+    "adbc_driver_postgresql.*",  # optional 'adbc' extra — absent in the base env
     "adbc_driver_snowflake.*",  # optional 'adbc-snowflake' extra — absent in the base env
     "adbc_driver_bigquery.*",  # optional 'adbc-bigquery' extra — absent in the base env
     "pyspark.*",  # optional 'spark' extra — absent in the base env
@@ -180,6 +181,7 @@ markers = [
     "integration: Integration tests (slower, require database)",
     "slow: Slow tests (may take a long time)",
     "requires_db: Needs a reachable external database (e.g. Postgres)",
+    "requires_network: Needs the public internet (e.g. an example reading a remote CSV)",
 ]
 asyncio_mode = "auto"
 asyncio_default_fixture_loop_scope = "function"

{interlaced-2.4.0 → interlaced-2.5.0}/src/interlace/cli/main.py

@@ -4,6 +4,8 @@ from __future__ import annotations
 
 import asyncio
 import contextlib
+import os
+import time
 from datetime import datetime
 from pathlib import Path
 from typing import Any
@@ -15,10 +17,11 @@ from rich.markup import escape
 from rich.progress import Progress, SpinnerColumn, TaskID, TextColumn, TimeElapsedColumn
 from rich.table import Table
 
-from interlace.exceptions import CheckError, ConfigurationError, InterlaceError, QueryError, SelectionError
+from interlace.exceptions import CheckError, ConfigurationError, InterlaceError, LockError, QueryError, SelectionError
 from interlace.graph.column_lineage import column_impact, column_lineage, split_target
 from interlace.graph.project import CompiledProject
 from interlace.graph.selectors import select_models, wants_state
+from interlace.physical.annotate import annotate_plan
 from interlace.plan.apply import ApplyResult
 from interlace.plan.apply import apply as apply_plan
 from interlace.plan.differ import diff
@@ -29,6 +32,7 @@ from interlace.scaffold import list_templates, scaffold_project
 from interlace.scheduler.engine import TriggerEngine, build_triggers
 from interlace.scheduler.worker import drain
 from interlace.sinks import target_ref
+from interlace.state.locks import hold_apply_lock
 from interlace.streaming import ensure_stream_tables, flush_streams
 
 # pretty_exceptions_enable=False: let InterlaceError propagate out of app() so main()
@@ -107,9 +111,9 @@ _END = typer.Option("", "--end", help="Window end (ISO), for incremental models.
 _FORWARD_ONLY = typer.Option(
     False,
     "--forward-only",
-    help="Modified history-keeping models (merge/full_merge/scd/incremental) carry their history "
-    "forward: it is copied to the new version, the new logic applies to the copy, and checks gate "
-    "before views move. Requires a shape-compatible change.",
+    help="Modified history-keeping models (merge/full_merge/hash_merge/scd/incremental) carry their "
+    "history forward: it is copied to the new version, the new logic applies to the copy, and "
+    "checks gate before views move. Requires a shape-compatible change.",
 )
 _JSON = typer.Option(False, "--json", help="Emit JSON instead of a table (for scripts and CI).")
 _PARALLELISM = typer.Option(
@@ -301,17 +305,22 @@ async def _plan(
     project = Project.load(path)
     compiled = project.compile()
     state = await project.open_state()
+    engines = project.open_engines()
     try:
         promoted = await _promoted_if_needed(state, environment, select)
         result = await diff(
             compiled, environment, state, select=_selection(compiled, select, promoted), forward_only=forward_only
         )
+        await annotate_plan(result, compiled, engines)
         if as_json:
             _emit_json(_plan_dict(result, environment))
         else:
             _render(result, environment)
+        if result.blocking:
+            raise typer.Exit(1)
     finally:
         await state.close()
+        engines.close()
 
 
 def _plan_dict(plan: Plan, environment: str) -> dict:
@@ -334,6 +343,12 @@ def _plan_dict(plan: Plan, environment: str) -> dict:
             f"{t.model}: {t.source.name} -> {t.target.name} ({t.via} -> {t.table.schema}.{t.table.name})"
             for t in plan.transfers
         ],
+        "physical": [
+            f"{'+' if change.op == 'add' else '-'} {change.kind} {change.name}"
+            for action in plan.physical
+            for change in action.changes
+        ],
+        "drift": [note.message for note in plan.drift],
     }
 
 
@@ -358,6 +373,7 @@ async def _apply(
         plan_result = await diff(
             compiled, environment, state, select=_selection(compiled, select, promoted), forward_only=forward_only
         )
+        await annotate_plan(plan_result, compiled, engines)
         _render(plan_result, environment)
         if plan_result.is_empty:
             return
@@ -370,18 +386,22 @@ async def _apply(
         progress = _build_progress(plan_result)
         try:
             with progress.progress if progress else contextlib.nullcontext():
-                result = await apply_plan(
-                    plan_result,
-                    compiled=compiled,
-                    engines=engines,
-                    state=state,
-                    base_path=project.root,
-                    on_progress=progress,
-                    parallelism=parallelism or project.config.parallelism,  # --parallelism wins over config
-                )
+                async with hold_apply_lock(state, owner=f"cli:{os.getpid()}:apply"):
+                    result = await apply_plan(
+                        plan_result,
+                        compiled=compiled,
+                        engines=engines,
+                        state=state,
+                        base_path=project.root,
+                        on_progress=progress,
+                        parallelism=parallelism or project.config.parallelism,  # --parallelism wins over config
+                    )
         except CheckError as exc:
             console.print(f"[red]{escape(exc.message)}[/red]")
             raise typer.Exit(1) from exc
+        except LockError as exc:
+            console.print(f"[red]{escape(exc.message)}[/red]")
+            raise typer.Exit(1) from exc
         _render_build_results(result, compiled)
         _render_checks(result)
         await _render_empty_incrementals(result, compiled, engines)
@@ -467,27 +487,32 @@ async def _execute(
             restate=restate,
         )
         progress = _build_progress(plan_result)
+        started = time.perf_counter()
         try:
             with progress.progress if progress else contextlib.nullcontext():
-                result = await apply_plan(
-                    plan_result,
-                    compiled=compiled,
-                    engines=engines,
-                    state=state,
-                    base_path=project.root,
-                    on_progress=progress,
-                    parallelism=parallelism or project.config.parallelism,  # --parallelism wins over config
-                )
+                async with hold_apply_lock(state, owner=f"cli:{os.getpid()}:run"):
+                    result = await apply_plan(
+                        plan_result,
+                        compiled=compiled,
+                        engines=engines,
+                        state=state,
+                        base_path=project.root,
+                        on_progress=progress,
+                        parallelism=parallelism or project.config.parallelism,  # --parallelism wins over config
+                    )
         except CheckError as exc:
             console.print(f"[red]{escape(exc.message)}[/red]")
             raise typer.Exit(1) from exc
+        except LockError as exc:
+            console.print(f"[red]{escape(exc.message)}[/red]")
+            raise typer.Exit(1) from exc
         _render_build_results(result, compiled)
         _render_checks(result)
         _render_warnings(plan_result)
         await _render_empty_incrementals(result, compiled, engines)
         verb = "Restated" if restate else "Ran"
         console.print(
-            f"[green]{verb} {len(set(result.built))} model(s) ({len(result.built)} task(s)); "
+            f"[green]{verb} {len(set(result.built))} model(s) in {time.perf_counter() - started:.2f}s; "
             f"promoted {result.promoted} to '{environment}'.[/green]"
         )
     finally:
@@ -519,7 +544,8 @@ async def _gc(path: Path, grace: str, dry_run: bool) -> None:
     engines = project.open_engines()
     state = await project.open_state()
     try:
-        result = await run_gc(state, engines=engines, grace=parsed_grace, dry_run=dry_run)
+        async with hold_apply_lock(state, owner=f"cli:{os.getpid()}:gc"):
+            result = await run_gc(state, engines=engines, grace=parsed_grace, dry_run=dry_run)
         verb = "Would remove" if dry_run else "Removed"
         console.print(
             f"{verb} {len(result.removed_snapshots)} snapshot(s), dropped {len(result.dropped_tables)} table(s); "
@@ -547,6 +573,77 @@ async def _gc(path: Path, grace: str, dry_run: bool) -> None:
         engines.close()
 
 
+@app.command()
+def reset(
+    path: Path = _PATH,
+    yes: bool = typer.Option(False, "--yes", help="Required. Confirm the reset."),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Report what would be removed without touching anything."),
+    as_json: bool = _JSON,
+) -> None:
+    """Wipe Interlace-owned state for a fresh apply.
+
+    Drops environment views, snapshot tables, runs, events, and the stream log.
+    External table/file destinations are not dropped; terminal models stay
+    recorded so the next apply will not re-deliver into them. API keys are kept.
+    """
+    asyncio.run(_reset(path, yes, dry_run, as_json))
+
+
+async def _reset(path: Path, yes: bool, dry_run: bool, as_json: bool) -> None:
+    from dataclasses import asdict
+
+    from interlace.state.janitor import reset as run_reset
+
+    if not yes and not dry_run:
+        console.print(
+            "This wipes Interlace-owned views, snapshot tables, runs, and stream state. "
+            "External table/file destinations are not dropped."
+        )
+        console.print("Pass [bold]--yes[/bold] to proceed (or [bold]--dry-run[/bold] to preview).")
+        raise typer.Exit(1)
+    project = Project.load(path)
+    compiled = project.compile()
+    keep = [model.name for model in compiled.models.values() if model.is_terminal]
+    engines = project.open_engines()
+    state = await project.open_state()
+    stream_log = None
+    stream_path = project.root / project.config.stream_path
+    if project.streams or stream_path.exists():
+        stream_log = await project.open_stream_log()
+    try:
+        async with hold_apply_lock(state, owner=f"cli:{os.getpid()}:reset"):
+            result = await run_reset(
+                state,
+                engines=engines,
+                keep_models=keep,
+                stream_log=stream_log,
+                clear_streams=bool(project.streams),
+                dry_run=dry_run,
+            )
+        if as_json:
+            _emit_json(asdict(result))
+            return
+        verb = "Would drop" if dry_run else "Dropped"
+        console.print(
+            f"{verb} {len(result.dropped_views)} view(s), {len(result.dropped_schemas)} schema(s); "
+            f"{'would clear' if dry_run else 'cleared'} {result.cleared_snapshots} snapshot(s)."
+        )
+        if result.kept_terminals:
+            console.print(
+                f"[dim]Left {len(result.kept_terminals)} terminal model(s) recorded "
+                f"(table/file destinations were not dropped).[/dim]"
+            )
+        if result.stream_log_cleared:
+            console.print("[dim]Stream log cleared.[/dim]")
+        if not dry_run:
+            console.print("[dim]Next apply rebuilds owned models from scratch.[/dim]")
+    finally:
+        if stream_log is not None:
+            await stream_log.close()
+        await state.close()
+        engines.close()
+
+
 @app.command()
 def scheduler(
     environment: str = _ENV,
@@ -574,16 +671,17 @@ async def _scheduler(environment: str, path: Path, interval: float, once: bool)
             await trigger_engine.tick(datetime.now())
             # materialize anything published since the last tick, then run models
             # (an API-only `serve --no-scheduler` process relies on this loop to flush)
-            if stream_log is not None:
-                await flush_streams(project.streams, stream_log, engines.get())
-            ran = await drain(
-                state,
-                compiled,
-                engines=engines,
-                environment=environment,
-                base_path=project.root,
-                parallelism=project.config.parallelism,
-            )
+            async with hold_apply_lock(state, owner=f"cli:{os.getpid()}:scheduler"):
+                if stream_log is not None:
+                    await flush_streams(project.streams, stream_log, engines.get())
+                ran = await drain(
+                    state,
+                    compiled,
+                    engines=engines,
+                    environment=environment,
+                    base_path=project.root,
+                    parallelism=project.config.parallelism,
+                )
             if ran:
                 console.print(f"[green]ran {ran} scheduled run(s) in '{environment}'[/green]")
             if stream_log is not None:
@@ -641,6 +739,11 @@ def serve(
         True, "--scheduler/--no-scheduler", help="Run the scheduler loop in this process (combined daemon)."
     ),
     interval: float = typer.Option(60.0, "--interval", help="Seconds between scheduler ticks."),
+    allow_open: bool = typer.Option(
+        False,
+        "--allow-open",
+        help="Permit a non-loopback bind with no API keys (insecure). Refused without this flag.",
+    ),
 ) -> None:
     """Run the interlace daemon: HTTP API + scheduler in one process (requires the `service` extra).
 
@@ -657,15 +760,22 @@ def serve(
     if bound != port:
         console.print(f"[yellow]port {port} is in use — serving on {bound}[/yellow]")
     port = bound
-    # Auth is open until the first API key exists (see auth.py). That's fine on
-    # loopback; on a routable bind it exposes every endpoint — including the SQL
-    # console and apply/gc — to the network unauthenticated. Warn loudly.
+    # Auth is open until the first API key exists (see auth.py). Fine on loopback;
+    # on a routable bind it exposes apply/gc/query unauthenticated — refuse unless
+    # --allow-open (or keys already exist).
     if host not in ("127.0.0.1", "localhost", "::1"):
         keyed = asyncio.run(_has_api_keys(path))
+        if not keyed and not allow_open:
+            console.print(
+                f"[bold red]refusing[/bold red] to serve on [bold]{host}[/bold] with no API keys — "
+                "create one ([bold]interlace apikey create <name> --scope admin[/bold]) or pass "
+                "[bold]--allow-open[/bold] (insecure)."
+            )
+            raise typer.Exit(1)
         if not keyed:
             console.print(
                 f"[bold red]WARNING[/bold red] serving on [bold]{host}[/bold] with no API keys — "
-                "the API is open to the network. Create one first: [bold]interlace apikey create <name> --scope admin[/bold]"
+                "the API is open to the network (--allow-open)."
             )
     console.print(f"UI at [bold cyan]http://{host}:{port}/ui[/bold cyan]")
     token = quack_token
@@ -819,7 +929,8 @@ async def _env_drop(name: str, path: Path, force: bool) -> None:
         if not await state.get_environment(name):
             console.print(f"No environment {name!r}.")
             raise typer.Exit(1)
-        dropped = await drop_environment(state, engines=engines, environment=name)
+        async with hold_apply_lock(state, owner=f"cli:{os.getpid()}:env-drop"):
+            dropped = await drop_environment(state, engines=engines, environment=name)
         console.print(f"Dropped environment [bold]{name}[/bold] ({len(dropped)} view(s) removed).")
         console.print("[dim]Its snapshots are now unreferenced — `interlace gc` reclaims their tables.[/dim]")
     finally:
@@ -867,10 +978,14 @@ async def _env_rollback(name: str, path: Path, to: int | None, history: bool, as
             return
         engines = project.open_engines()
         try:
-            result = await rollback_environment(state, engines=engines, environment=name, to_generation=to)
+            async with hold_apply_lock(state, owner=f"cli:{os.getpid()}:env-rollback"):
+                result = await rollback_environment(state, engines=engines, environment=name, to_generation=to)
         except PlanError as exc:
             console.print(f"[red]{escape(exc.message)}[/red]")
             raise typer.Exit(1) from exc
+        except LockError as exc:
+            console.print(f"[red]{escape(exc.message)}[/red]")
+            raise typer.Exit(1) from exc
         if as_json:
             _emit_json(result)
             return
@@ -1407,39 +1522,55 @@ async def _apikey_list(path: Path) -> None:
 
 
 def _render(plan: Plan, environment: str) -> None:
-    if plan.is_empty:
+    if not plan.changes and not plan.physical and not plan.transfers and not plan.drift and not plan.warnings:
         console.print(f"No changes for [bold]{environment}[/bold].")
         return
     reused = {snapshot.name for snapshot in plan.reuses}
-    table = _table(f"Plan · {environment}")
-    table.add_column("Model")
-    table.add_column("Change")
-    table.add_column("Category")
-    table.add_column("Build")
-    change_colours = {"added": "green", "removed": "red", "modified": "yellow"}
-    category_colours = {"breaking": "red", "non_breaking": "green", "forward_only": "cyan"}
-    for change in plan.changes:
-        build = (
-            "[cyan]reuse[/]"
-            if change.name in reused
-            else ("[dim]—[/]" if change.change_type is ChangeType.REMOVED else "rebuild")
-        )
-        kind = change.change_type.value
-        category = change.category.value if change.category else None
-        table.add_row(
-            change.name,
-            f"[{change_colours.get(kind, 'white')}]{kind}[/]",
-            f"[{category_colours.get(category, 'white')}]{category}[/]" if category else "[dim]—[/]",
-            build,
-        )
-    console.print(table)
+    if plan.changes:
+        table = _table(f"Plan · {environment}")
+        table.add_column("Model")
+        table.add_column("Change")
+        table.add_column("Category")
+        table.add_column("Build")
+        change_colours = {"added": "green", "removed": "red", "modified": "yellow"}
+        category_colours = {"breaking": "red", "non_breaking": "green", "forward_only": "cyan"}
+        for change in plan.changes:
+            build = (
+                "[cyan]reuse[/]"
+                if change.name in reused
+                else ("[dim]—[/]" if change.change_type is ChangeType.REMOVED else "rebuild")
+            )
+            kind = change.change_type.value
+            category = change.category.value if change.category else None
+            table.add_row(
+                change.name,
+                f"[{change_colours.get(kind, 'white')}]{kind}[/]",
+                f"[{category_colours.get(category, 'white')}]{category}[/]" if category else "[dim]—[/]",
+                build,
+            )
+        console.print(table)
     if reused:
         console.print(f"[dim]{len(reused)} model(s) have provably identical output — reusing existing tables.[/dim]")
+    for action in plan.physical:
+        for physical in action.changes:
+            mark = "[green]+[/]" if physical.op == "add" else "[red]-[/]"
+            console.print(f"{mark} {physical.kind} {physical.name}  [dim]{action.name}[/]")
+        for warning in action.warnings:
+            console.print(f"[yellow]note:[/yellow] {warning}")
     for transfer in plan.transfers:
         console.print(
             f"[cyan]transfer[/cyan] {transfer.model}: {transfer.source.name} → {transfer.target.name} "
             f"({transfer.via} → {transfer.table.schema}.{transfer.table.name})"
         )
+    for note in plan.drift:
+        style = "red" if note.blocking else "yellow"
+        console.print(f"[{style}]drift:[/{style}] {note.message}")
+    for warning in plan.warnings:
+        if any(warning == note.message for note in plan.drift):
+            continue
+        if any(warning in action.warnings for action in plan.physical):
+            continue
+        console.print(f"[yellow]note:[/yellow] {warning}")
 
 
 def _flatten_exceptions(exc: BaseException) -> list[BaseException]:

{interlaced-2.4.0 → interlaced-2.5.0}/src/interlace/config/config.py

@@ -79,9 +79,9 @@ _TYPE_DIALECT = {
 class EngineConfig(BaseModel):
     """One named execution engine (warehouse gateway).
 
-    DuckDB-family types (``duckdb`` / ``ducklake`` / ``quack``) are fully supported.
-    Additional types are reserved for remote adapters (Postgres, Snowflake, …);
-    declaring them fails at open until an adapter ships.
+    DuckDB-family types (``duckdb`` / ``ducklake`` / ``quack``) and ``postgres`` are
+    the tested set. ``spark`` is beta; ``motherduck`` / ``redshift`` / ``snowflake`` /
+    ``bigquery`` are alpha (wired and dialect-correct, not yet live-validated).
     """
 
     type: str = "duckdb"
@@ -145,6 +145,9 @@ class ProjectConfig(BaseModel):
     # This is T0 federation (all SQL still runs in DuckDB) — see docs/architecture/MULTI_ENGINE.md.
     attach: dict[str, str] = Field(default_factory=dict)
     model_paths: list[str] = Field(default_factory=lambda: ["models"])
+    # Directories of CREATE MACRO definitions, expanded into every model at compile
+    # time (see interlace.ir.macros). Missing directories are ignored.
+    macro_paths: list[str] = Field(default_factory=lambda: ["macros"])
     # How many models build concurrently. Lower it to serialise a build end-to-end
     # when diagnosing a crash or a warehouse that dislikes parallel writers; `run`
     # and `apply` also take --parallelism, which wins over this.

{interlaced-2.4.0 → interlaced-2.5.0}/src/interlace/dsl/decorators.py

@@ -8,12 +8,22 @@ Compilation, planning, and execution happen later over the registry. UK spelling
 
 from __future__ import annotations
 
+import re
 from collections.abc import Callable, Sequence
 from dataclasses import dataclass, field
 from typing import Any
 
 from interlace.checks.spec import CheckSpec, parse_checks
 from interlace.exceptions import DefinitionError
+from interlace.physical.spec import (
+    ConstraintSpec,
+    IndexSpec,
+    SchemaPolicy,
+    parse_constraints,
+    parse_indexes,
+    parse_schema_policy,
+    validate_physical_allowed,
+)
 from interlace.sinks import FILE_FORMATS
 
 ModelFn = Callable[..., Any]
@@ -24,6 +34,8 @@ ModelFn = Callable[..., Any]
 _MATERIALISATIONS = frozenset({"virtual", "view", "ephemeral", "table", "file"})
 _KEYED_STRATEGIES = frozenset({"merge", "full_merge", "hash_merge", "scd"})
 _DRIFT_MODES = frozenset({"evolve", "reject", "quarantine"})
+# Stream names become SQL identifiers / watermark keys — keep them safe to quote.
+_STREAM_NAME = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
 
 
 def _as_tuple(value: str | Sequence[str]) -> tuple[str, ...]:
@@ -113,6 +125,9 @@ class ModelDef:
     environments: tuple[str, ...] = ("prod",)  # which environments actually deliver a terminal model
     schedule: dict[str, str] | None = None  # {"cron": "0 * * * *"} or {"every": "5m"} for `interlace serve`
     checks: tuple[CheckSpec, ...] = ()  # data-quality checks; error severity gates promotion
+    indexes: tuple[IndexSpec, ...] = ()  # physical indexes; not part of the data fingerprint
+    constraints: tuple[ConstraintSpec, ...] = ()  # physical constraints; engine-enforced, not checks
+    schema_policy: SchemaPolicy = SchemaPolicy()  # external-table drift: columns / indexes / constraints
 
     def __post_init__(self) -> None:
         # `@model(checks=…)` normalises through parse_checks, but a ModelDef built
@@ -125,6 +140,10 @@ class ModelDef:
         # (TypeError on a CheckSpec; a dict silently degraded to its keys). Always run,
         # so `checks=[]` normalises to the declared tuple rather than staying a list.
         self.checks = parse_checks(self.checks, self.name)
+        self.indexes = parse_indexes(self.indexes, self.name)
+        self.constraints = parse_constraints(self.constraints, self.name)
+        self.schema_policy = parse_schema_policy(self.schema_policy, self.name)
+        validate_physical_allowed(self.name, self.materialise, self.indexes, self.constraints, self.schema_policy)
 
     @property
     def is_terminal(self) -> bool:
@@ -202,6 +221,9 @@ def model(
     columns: dict[str, str | None] | Sequence[str] | None = None,
     schedule: dict[str, str] | None = None,
     checks: Sequence[dict[str, Any] | CheckSpec] | None = None,
+    indexes: Sequence[dict[str, Any] | IndexSpec] | None = None,
+    constraints: Sequence[dict[str, Any] | ConstraintSpec] | None = None,
+    schema: dict[str, str] | None = None,
     export: Any = None,  # removed in 2.0 — kept only to raise a migration error
 ) -> Callable[[ModelFn], ModelFn]:
     """Declare a Python model. The function returns a ``Relation`` (or composes one).
@@ -218,6 +240,10 @@ def model(
     spelling for both surfaces — e.g. ``checks=[{"not_null": "customer_id"},
     {"row_count": {"min": 1}}]``. A :class:`~interlace.CheckSpec` also works if you
     prefer the typed form.
+
+    ``indexes`` and ``constraints`` are physical DDL applied after the table
+    exists. They do not change the data fingerprint. ``schema`` is the external
+    table drift policy (``columns`` / ``indexes`` / ``constraints``).
     """
     model_name = name or "<model>"
     if export is not None:
@@ -260,6 +286,9 @@ def model(
                 columns=_as_columns(columns),
                 schedule=schedule,
                 checks=parse_checks(checks, name or fn.__name__),
+                indexes=parse_indexes(indexes, name or fn.__name__),
+                constraints=parse_constraints(constraints, name or fn.__name__),
+                schema_policy=parse_schema_policy(schema, name or fn.__name__),
             )
         )
         return fn
@@ -276,6 +305,10 @@ def stream(
     on_schema_drift: str = "reject",
 ) -> Callable[[ModelFn], ModelFn]:
     """Declare a durable ingestion stream with an HTTP publish endpoint."""
+    if not _STREAM_NAME.fullmatch(name):
+        raise DefinitionError(
+            f"stream name {name!r} must match [A-Za-z_][A-Za-z0-9_]* (it becomes streams.<name> and a watermark key)"
+        )
     if on_schema_drift not in _DRIFT_MODES:
         raise DefinitionError(f"unknown on_schema_drift {on_schema_drift!r}; expected one of {sorted(_DRIFT_MODES)}")