@opengroundplan/core 0.1.1

package/templates/architectures/hexagonal/files/tests/ArchitectureTests/ArchitectureTests.csproj

@@ -0,0 +1,34 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>{{ dotnetTargetFramework }}</TargetFramework>
+    <!-- xUnit v3 test projects are executables. -->
+    <OutputType>Exe</OutputType>
+    <RootNamespace>{{ solutionName | dot }}.ArchitectureTests</RootNamespace>
+    <AssemblyName>{{ solutionName | dot }}.ArchitectureTests</AssemblyName>
+    <IsPackable>false</IsPackable>
+    <IsTestProject>true</IsTestProject>
+    <!-- CA1707 polices public API naming; underscored test names are the convention here. -->
+    <NoWarn>$(NoWarn);CA1707</NoWarn>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="xunit.v3" />
+    <PackageReference Include="xunit.runner.visualstudio" />
+    <PackageReference Include="Microsoft.NET.Test.Sdk" />
+    <!-- The maintained fork; NetArchTest.Rules stopped at 1.3.2 in 2021. Same namespace. -->
+    <PackageReference Include="NetArchTest.eNhancedEdition" />
+  </ItemGroup>
+
+  <!-- References every zone: the rules are checked against loaded assemblies, so each one has
+       to be here even though the boundary itself is what is under test. -->
+  <ItemGroup>
+    <ProjectReference Include="../../src/{{ solutionName | dot }}.Domain/{{ solutionName | dot }}.Domain.csproj" />
+    <ProjectReference Include="../../src/{{ solutionName | dot }}.Application/{{ solutionName | dot }}.Application.csproj" />
+    <ProjectReference Include="../../src/{{ solutionName | dot }}.Adapters.Inbound.Http/{{ solutionName | dot }}.Adapters.Inbound.Http.csproj" />
+    <ProjectReference Include="../../src/{{ solutionName | dot }}.Adapters.Outbound.Persistence/{{ solutionName | dot }}.Adapters.Outbound.Persistence.csproj" />
+    <ProjectReference Include="../../src/{{ solutionName | dot }}.Adapters.Outbound.InMemory/{{ solutionName | dot }}.Adapters.Outbound.InMemory.csproj" />
+    <ProjectReference Include="../../src/{{ solutionName | dot }}.Bootstrap/{{ solutionName | dot }}.Bootstrap.csproj" />
+  </ItemGroup>
+
+</Project>

package/templates/architectures/hexagonal/files/tests/ArchitectureTests/HexagonBoundaryTests.cs

@@ -0,0 +1,135 @@
+using System.Reflection;
+using NetArchTest.Rules;
+using Xunit;
+using ApplicationMarker = {{ solutionName | dot }}.Application.ApplicationMarker;
+using DomainMarker = {{ solutionName | dot }}.Domain.DomainMarker;
+using HttpAdapterMarker = {{ solutionName | dot }}.Adapters.Inbound.Http.HttpAdapterMarker;
+using InMemoryAdapterMarker = {{ solutionName | dot }}.Adapters.Outbound.InMemory.InMemoryAdapterMarker;
+using PersistenceAdapterMarker = {{ solutionName | dot }}.Adapters.Outbound.Persistence.PersistenceAdapterMarker;
+// Both xUnit and NetArchTest ship a TestResult.
+using TestResult = NetArchTest.Rules.TestResult;
+
+namespace {{ solutionName | dot }}.ArchitectureTests;
+
+// Project references already stop most of this at compile time. These tests exist for the
+// rules the compiler cannot see — namespace direction inside an assembly, ports that stopped
+// being abstractions, and infrastructure types leaking into the domain.
+public sealed class HexagonBoundaryTests
+{
+    private const string ApplicationNamespace = "{{ solutionName | dot }}.Application";
+    private const string PortsNamespace = "{{ solutionName | dot }}.Application.Ports";
+    private const string InboundAdapters = "{{ solutionName | dot }}.Adapters.Inbound";
+    private const string OutboundAdapters = "{{ solutionName | dot }}.Adapters.Outbound";
+    private const string BootstrapNamespace = "{{ solutionName | dot }}.Bootstrap";
+
+    private static readonly Assembly Domain = typeof(DomainMarker).Assembly;
+    private static readonly Assembly Application = typeof(ApplicationMarker).Assembly;
+    private static readonly Assembly InboundHttp = typeof(HttpAdapterMarker).Assembly;
+    private static readonly Assembly OutboundPersistence = typeof(PersistenceAdapterMarker).Assembly;
+    private static readonly Assembly OutboundInMemory = typeof(InMemoryAdapterMarker).Assembly;
+
+    [Fact]
+    public void Domain_depends_on_nothing_else_in_the_solution()
+    {
+        var result = Types.InAssembly(Domain)
+            .ShouldNot()
+            .HaveDependencyOnAny(ApplicationNamespace, InboundAdapters, OutboundAdapters, BootstrapNamespace)
+            .GetResult();
+
+        Assert.True(result.IsSuccessful, Describe(
+                "The domain is the centre of the hexagon; naming anything outside it inverts the dependency.",
+                result));
+    }
+
+    [Fact]
+    public void Domain_reaches_the_outside_only_through_a_port()
+    {
+        var result = Types.InAssembly(Domain)
+            .ShouldNot()
+            .HaveDependencyOnAny(
+                "System.Net.Http",
+                "System.Data",
+                "System.IO.File",
+                "Microsoft.EntityFrameworkCore",
+                "Microsoft.Extensions.DependencyInjection")
+            .GetResult();
+
+        Assert.True(result.IsSuccessful, Describe(
+                "The domain reached infrastructure directly. Express the need as a port and let an adapter satisfy it.",
+                result));
+    }
+
+    [Fact]
+    public void Application_depends_on_ports_not_on_adapters()
+    {
+        var result = Types.InAssembly(Application)
+            .ShouldNot()
+            .HaveDependencyOnAny(InboundAdapters, OutboundAdapters, BootstrapNamespace)
+            .GetResult();
+
+        Assert.True(result.IsSuccessful, Describe(
+                "The application layer names an adapter. It may depend on ports only, so the adapter stays replaceable.",
+                result));
+    }
+
+    [Fact]
+    public void Ports_are_abstractions()
+    {
+        // This overlay ships the layout, not an application, so a fresh repo has no ports yet.
+        // A namespace filter matching no types satisfies every condition, so without this the
+        // rule would report a passing boundary it never checked. Skipping says so out loud, and
+        // the first port added turns the rule back on by itself.
+        Assert.SkipWhen(
+            PortTypes().Count == 0,
+            $"No ports yet. Add one under {PortsNamespace} and this rule starts enforcing.");
+
+        var result = Types.InAssembly(Application)
+            .That()
+            .ResideInNamespace(PortsNamespace)
+            .Should()
+            .BeInterfaces()
+            .GetResult();
+
+        Assert.True(result.IsSuccessful, Describe("A port stopped being an abstraction.", result));
+    }
+
+    [Fact]
+    public void Driving_adapters_do_not_know_driven_adapters()
+    {
+        var result = Types.InAssembly(InboundHttp)
+            .ShouldNot()
+            .HaveDependencyOnAny(OutboundAdapters, BootstrapNamespace)
+            .GetResult();
+
+        Assert.True(result.IsSuccessful, Describe(
+                "A driving adapter names a driven one. They meet through the application, never each other.",
+                result));
+    }
+
+    [Fact]
+    public void Driven_adapters_do_not_know_driving_adapters()
+    {
+        var result = Types.InAssemblies([OutboundPersistence, OutboundInMemory])
+            .ShouldNot()
+            .HaveDependencyOnAny(InboundAdapters, BootstrapNamespace)
+            .GetResult();
+
+        Assert.True(result.IsSuccessful, Describe(
+                "A driven adapter names a driving one, which couples storage to transport.",
+                result));
+    }
+
+    /// <summary>Types found in the ports namespace, so the rule above cannot pass by inspecting nothing.</summary>
+    private static List<Type> PortTypes() =>
+        Application.GetTypes()
+            .Where(type => type.Namespace?.StartsWith(PortsNamespace, StringComparison.Ordinal) == true)
+            .ToList();
+
+    private static string Describe(string violation, TestResult result)
+    {
+        // FailingTypes is null on a passing test, and this message is built either way.
+        var failing = result.FailingTypes ?? [];
+        var lines = failing.Select(type => $"  {type.FullName} — {type.Explanation}");
+        return string.Join(Environment.NewLine, lines.Prepend(violation));
+    }
+}

package/templates/architectures/lakehouse/blueprint.yaml

@@ -0,0 +1,103 @@
+id: lakehouse
+kind: architecture
+name: Lakehouse
+description: >-
+  Folder overlay for an open table format over object storage: table definitions kept as data,
+  a catalog that is the only module allowed to name a storage location, time travel as a read
+  argument, and the maintenance jobs (compaction, snapshot expiry, orphan cleanup) shipped as a
+  runnable schedule instead of a runbook line. A fitness test fails the build when query code
+  names a bucket, a prefix, or a file.
+
+tags:
+  - lakehouse
+  - iceberg
+  - delta-lake
+  - table-format
+  - object-storage
+  - time-travel
+  - compaction
+  - import-linter
+
+requires: []
+conflicts: []
+provides:
+  - lakehouse-layout
+  - table-catalog
+  - boundary-enforcement
+
+# An overlay is chosen through the architecture question, never listed as a supported target.
+supportsArchitectures: []
+
+variables:
+  # Iceberg and Delta differ most in what the *Python client* can do unattended: delta-rs
+  # compacts and vacuums in-process, pyiceberg leaves both to a compute engine. The adapter
+  # picked here is what makes that difference visible instead of surprising.
+  - name: tableFormat
+    prompt: Open table format the catalog adapter targets
+    type: select
+    choices:
+      - value: iceberg
+        label: Apache Iceberg (pyiceberg)
+      - value: delta
+        label: Delta Lake (delta-rs / deltalake)
+    default: iceberg
+    required: true
+
+  # The layout is meaningless without one table to show the shape: schema as data, a partition
+  # column, a read that time-travels, and a maintenance job that already knows about it.
+  - name: firstTable
+    prompt: Name of the first table (a business fact, e.g. "orders")
+    type: string
+    default: events
+    required: true
+
+files:
+  - from: files/docs/architecture/lakehouse.python.md
+    to: .
+    when: "stack == 'python'"
+
+  # lakehouse/*.py — the format-neutral core: settings, schema, ports.
+  - from: files/src/__solutionName.snake__/lakehouse/*.py
+    to: .
+    when: "stack == 'python'"
+
+  # Enumerated rather than globbed so exactly one adapter ships — a glob would emit both and
+  # `catalog/__init__.py` imports only the chosen one.
+  - from: files/src/__solutionName.snake__/lakehouse/catalog/__init__.py
+    to: .
+    when: "stack == 'python'"
+  - from: files/src/__solutionName.snake__/lakehouse/catalog/_iceberg.py
+    to: .
+    when: "stack == 'python' && tableFormat == 'iceberg'"
+  - from: files/src/__solutionName.snake__/lakehouse/catalog/_delta.py
+    to: .
+    when: "stack == 'python' && tableFormat == 'delta'"
+
+  - from: files/src/__solutionName.snake__/lakehouse/tables/*.py
+    to: .
+    when: "stack == 'python'"
+  - from: files/src/__solutionName.snake__/lakehouse/queries/*.py
+    to: .
+    when: "stack == 'python'"
+  - from: files/src/__solutionName.snake__/lakehouse/maintenance/*.py
+    to: .
+    when: "stack == 'python'"
+
+  # Boundary rules that live only in prose get violated; these two fail a command instead.
+  - from: files/tests/architecture/test_lakehouse_boundaries.py
+    to: .
+    when: "stack == 'python'"
+  - from: files/.importlinter
+    to: .
+    when: "stack == 'python'"
+
+  # Declared, not installed by a post-apply step: a package added after generation is
+  # missing from the first install (ADR 0005, spec 003). Both clients are declared because a
+  # TOML fragment cannot branch on `tableFormat` the way a file rule can.
+  - from: files/pyproject.toml
+    to: .
+    onConflict: merge
+    when: "stack == 'python'"
+
+# Nothing imperative to run: every dependency is declared in the manifest fragment above.
+postApply: []

package/templates/architectures/lakehouse/files/.importlinter

@@ -0,0 +1,51 @@
+# import-linter contracts — the standard-tool half of the boundary enforcement.
+# `lint-imports` fails the build; wire it into CI next to pytest and ruff.
+# The full "no storage location outside the catalog" rule is enforced by
+# tests/architecture/test_lakehouse_boundaries.py, which also catches path *literals*.
+[importlinter]
+root_package = {{ solutionName | snake }}
+include_external_packages = True
+
+# The rule the whole architecture rests on, stated for the import graph.
+[importlinter:contract:catalog-owns-storage]
+name = Only the catalog adapter may import a storage or table-format client
+type = forbidden
+# Direct imports only: reaching a client *through* the catalog is the sanctioned path, and
+# without this every module that calls open_catalog() reports as importing the client.
+allow_indirect_imports = True
+source_modules =
+    {{ solutionName | snake }}.lakehouse.queries
+    {{ solutionName | snake }}.lakehouse.tables
+    {{ solutionName | snake }}.lakehouse.maintenance
+    {{ solutionName | snake }}.lakehouse.ports
+    {{ solutionName | snake }}.lakehouse.schema
+    {{ solutionName | snake }}.lakehouse.settings
+forbidden_modules =
+    pyiceberg
+    deltalake
+    boto3
+    botocore
+    s3fs
+    gcsfs
+    adlfs
+    fsspec
+
+[importlinter:contract:lakehouse-layers]
+name = Lakehouse layers
+type = layers
+layers =
+    {{ solutionName | snake }}.lakehouse.maintenance
+    {{ solutionName | snake }}.lakehouse.queries
+    {{ solutionName | snake }}.lakehouse.catalog
+    {{ solutionName | snake }}.lakehouse.tables
+    {{ solutionName | snake }}.lakehouse.ports
+    {{ solutionName | snake }}.lakehouse.schema
+    {{ solutionName | snake }}.lakehouse.settings
+
+# The layers contract would permit maintenance -> queries; nothing should couple them.
+[importlinter:contract:reads-and-maintenance-are-separate]
+name = Query code and maintenance jobs do not import one another
+type = independence
+modules =
+    {{ solutionName | snake }}.lakehouse.queries
+    {{ solutionName | snake }}.lakehouse.maintenance

package/templates/architectures/lakehouse/files/docs/architecture/lakehouse.python.md

@@ -0,0 +1,134 @@
+# Architecture — Lakehouse (Python)
+
+An open table format over object storage: cheap, directly-readable files with a transactional
+metadata layer on top, giving ACID commits, schema evolution, and time travel without a second
+copy of the data in a warehouse.
+
+## The one rule that matters
+
+> **Nothing outside `lakehouse/catalog/` may name a storage location.** Query code asks the
+> catalog for a table by name. Buckets, prefixes, partitions, and file paths are the catalog's
+> private business, and `tests/architecture/test_lakehouse_boundaries.py` fails the build the
+> moment a URI, a `.parquet` path, or a storage client import appears anywhere else.
+
+This is not tidiness. The lakehouse trade-off is that the storage format becomes a public API —
+you gain open access and lose the freedom to reorganise. One `pd.read_parquet("s3://…")` in a
+notebook-turned-production-job re-imposes that cost on you *and* keeps none of the benefits: no
+snapshot isolation, no schema enforcement, no time travel, and a silent break the first time
+compaction rewrites the files underneath it.
+
+## Layout
+
+```
+src/{{ solutionName | snake }}/lakehouse/
+  settings.py          # every tunable, defaulted once — retention, file sizes, warehouse URI
+  schema.py            # Column / TableDefinition / AsOf — table descriptions as plain data
+  ports.py             # Table + TableCatalog Protocols; the seam that keeps clients out
+  catalog/
+    __init__.py        #   open_catalog() — the only door
+    _{{ tableFormat }}.py
+                       #   the {{ tableFormat | title }} adapter — THE ONLY MODULE
+                       #   THAT MAY NAME A STORAGE LOCATION
+  tables/
+    __init__.py        #   the registry; a table not listed here is unreachable
+    {{ firstTable | snake }}.py
+  queries/
+    reads.py           #   current reads and time-travel reads, both via the catalog
+  maintenance/
+    jobs.py            #   evolve, compact, expire_snapshots, remove_orphan_files
+    __main__.py        #   python -m {{ solutionName | snake }}.lakehouse.maintenance
+tests/architecture/
+  test_lakehouse_boundaries.py
+.importlinter
+```
+
+Add a table by writing a module under `tables/` and listing it in `tables/__init__.py`. The
+maintenance runner picks it up automatically — there is no second place to register it.
+
+## Time travel
+
+`AsOf` carries exactly one coordinate: `snapshot_id` (Iceberg), `version` (Delta), or
+`timestamp_ms` (both). Reads take it as an argument, so the audit query and the production
+query are the same function:
+
+```python
+recent_{{ firstTable | snake }}()                       # current state
+{{ firstTable | snake }}_as_of(timestamp_ms=1743206400000)   # what it said then
+```
+
+Retention is a cost, not a setting you leave alone: expired snapshots pin data files, and every
+hour of `snapshot_retention_hours` is storage you keep paying for.
+
+## Maintenance — the part that gets skipped
+
+Compaction, snapshot expiry, and orphan-file cleanup are what stop a working lakehouse from
+degrading into an unqueryable pile of small files. They ship here as a runnable job precisely
+because they are always the first line cut from a plan.
+
+```bash
+python -m {{ solutionName | snake }}.lakehouse.maintenance          # all jobs, all tables
+python -m {{ solutionName | snake }}.lakehouse.maintenance compact  # one job
+```
+
+`dry_run_maintenance` defaults to **true**: `remove_orphan_files` reports before it deletes.
+Deleting a file a live reader or an in-flight write still needs is unrecoverable, which is also
+why `orphan_file_grace_hours` defaults to 168 — Delta refuses shorter windows outright.
+
+### What the Python client can and cannot do
+
+This is the sharpest practical difference between the two formats, and it is an operational
+budget line, not a detail:
+
+| Job | Delta (`deltalake`) | Iceberg (`pyiceberg`) |
+|---|---|---|
+| `evolve` | applied in-process | applied in-process |
+| `compact` | applied — `optimize.compact` | **delegated** to a compute engine |
+| `expire_snapshots` | applied — `cleanup_metadata` | **delegated** to a compute engine |
+| `remove_orphan_files` | applied — `vacuum` | **delegated** to a compute engine |
+
+`delegated` is not a failure. pyiceberg is a catalog and read/write client; Iceberg table
+maintenance lives in engine procedures (`system.rewrite_data_files`,
+`system.expire_snapshots`, `system.remove_orphan_files`). The adapter prints the exact call,
+with your configured thresholds already substituted, so the work is visible and schedulable
+rather than forgotten. **If you chose Iceberg, you still need Spark, Trino, or Flink on a
+timer** — budget for it now, not after the first query-latency incident.
+
+Both client libraries are declared in `pyproject.toml` even though only the adapter you chose
+ships. A TOML fragment cannot branch on the answer the way a file rule can; drop the one you
+are not using if the install size matters.
+
+## Enforcement — two layers, both fail a command
+
+1. **`tests/architecture/test_lakehouse_boundaries.py`** (pytest, standard library only) parses
+   every module under `src/` and fails on a storage URI literal, a data-file path literal, or a
+   storage/table-format client import outside `lakehouse/catalog/` and `lakehouse/settings.py`.
+   It carries self-test cases so the rule cannot silently stop firing, and runs standalone:
+
+   ```bash
+   pytest tests/architecture/test_lakehouse_boundaries.py
+   python tests/architecture/test_lakehouse_boundaries.py     # no pytest needed
+   ```
+
+2. **`.importlinter` contracts** (`lint-imports`) are the standard-tool guard: the same
+   forbidden-client rule expressed against the import graph, a layers contract
+   (`maintenance → queries → catalog → tables → ports → schema → settings`), and an
+   independence contract keeping query code and maintenance jobs uncoupled.
+
+### What is not enforced mechanically
+
+- **SQL and notebooks.** The test parses Python source under `src/`. A path inside a `.sql`
+  file, a notebook, a dbt model, or a Spark job submitted from CI is invisible to it. Point
+  those at the catalog too; nothing here can make you.
+- **Runtime configuration.** `warehouse_uri` is read from the environment, so an operator can
+  still point the catalog somewhere unintended. That is a deployment control, not a code one.
+- **Partition quality.** The definition rejects partitions on undefined columns, but nothing
+  can tell you that partitioning by a high-cardinality column was a mistake — the layout
+  documents the rule (partition on a date, never a raw timestamp); the query planner enforces
+  it later, expensively.
+- **Whether maintenance actually runs.** The job exists and reports. Only your scheduler can
+  make it true.
+
+Sources: [Lakehouse: A New Generation of Open Platforms… (CIDR
+2021)](https://www.cidrdb.org/cidr2021/papers/cidr2021_paper17.pdf) ·
+[Apache Iceberg table spec](https://github.com/apache/iceberg/blob/main/format/spec.md) ·
+[Delta Lake](https://delta.io/) · [import-linter](https://import-linter.readthedocs.io/).

package/templates/architectures/lakehouse/files/pyproject.toml

@@ -0,0 +1,5 @@
+[project]
+dependencies = ["deltalake>=1.6.2", "pyiceberg[sql-sqlite,pyarrow]>=0.11.1", "tzdata>=2026.3"]
+
+[dependency-groups]
+dev = ["import-linter==2.13"]

package/templates/architectures/lakehouse/files/src/__solutionName.snake__/lakehouse/__init__.py

@@ -0,0 +1,20 @@
+"""Lakehouse: an open table format over object storage.
+
+`catalog` is deliberately not re-exported here. Opening the catalog is a door you walk through
+on purpose, and importing this package must not drag a client library into every module.
+"""
+
+from .ports import MaintenanceOutcome, Table, TableCatalog
+from .schema import AsOf, Column, TableDefinition
+from .settings import LakehouseSettings, get_settings
+
+__all__ = [
+    "AsOf",
+    "Column",
+    "LakehouseSettings",
+    "MaintenanceOutcome",
+    "Table",
+    "TableCatalog",
+    "TableDefinition",
+    "get_settings",
+]

package/templates/architectures/lakehouse/files/src/__solutionName.snake__/lakehouse/catalog/__init__.py

@@ -0,0 +1,21 @@
+"""The single door to the lakehouse.
+
+Query code names a table; only the adapter beside this file knows where that table's files
+live. `tests/architecture/test_lakehouse_boundaries.py` fails the build if anything else does.
+"""
+
+from __future__ import annotations
+
+from functools import lru_cache
+
+from ..ports import Table, TableCatalog
+from ..settings import get_settings
+from ._{{ tableFormat }} import build_catalog
+
+__all__ = ["Table", "TableCatalog", "open_catalog"]
+
+
+@lru_cache
+def open_catalog() -> TableCatalog:
+    """Cached: one client per process, so table metadata is not re-fetched on every query."""
+    return build_catalog(get_settings())

package/templates/architectures/lakehouse/files/src/__solutionName.snake__/lakehouse/catalog/_delta.py

@@ -0,0 +1,155 @@
+"""Delta Lake adapter — one of only two modules allowed to name a storage location.
+
+delta-rs runs the whole maintenance triad in-process, so every job here reports `applied`.
+That is the one real asymmetry with the Iceberg adapter: there, compaction and orphan cleanup
+are engine procedures. Same architecture, very different operational bill.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from deltalake import DeltaTable, write_deltalake
+from deltalake.schema import Field, PrimitiveType, Schema
+
+from ..ports import MaintenanceOutcome, Table
+from ..schema import AsOf, TableDefinition
+from ..settings import LakehouseSettings
+from ..tables import TABLES, definition_of
+
+# Logical type -> Delta primitive. "timestamptz" is Delta's UTC-adjusted `timestamp`.
+_TYPES = {
+    "string": "string",
+    "long": "long",
+    "double": "double",
+    "boolean": "boolean",
+    "date": "date",
+    "timestamptz": "timestamp",
+}
+
+
+def _fields(definition: TableDefinition) -> list[Field]:
+    return [
+        Field(column.name, PrimitiveType(_TYPES[column.type]), nullable=not column.required)
+        for column in definition.columns
+    ]
+
+
+class DeltaTableHandle(Table):
+    def __init__(
+        self, table: DeltaTable, definition: TableDefinition, settings: LakehouseSettings
+    ) -> None:
+        self._table = table
+        self.definition = definition
+        self._settings = settings
+
+    def scan(self, *, columns: tuple[str, ...] = (), as_of: AsOf | None = None) -> Any:
+        # A pinned read builds its own handle: time travel must not leave this one in the past.
+        source = self._table
+        if as_of is not None:
+            source = DeltaTable(self._table.table_uri, version=self._version_for(as_of))
+        return source.to_pyarrow_table(columns=list(columns) or None)
+
+    def append(self, rows: Any) -> None:
+        write_deltalake(self._table.table_uri, rows, mode="append")
+        self._table.update_incremental()  # the handle must see what it just wrote
+
+    def evolve_to(self, definition: TableDefinition) -> tuple[str, ...]:
+        """Additive only. Dropping or retyping a column breaks readers still on an old version."""
+        existing = {field.name for field in self._table.schema().fields}
+        added = [column for column in definition.columns if column.name not in existing]
+        if added:
+            # New columns must be nullable: existing rows have no value for them.
+            self._table.alter.add_columns(
+                [Field(c.name, PrimitiveType(_TYPES[c.type]), nullable=True) for c in added]
+            )
+        self.definition = definition
+        return tuple(column.name for column in added)
+
+    def history(self) -> tuple[dict[str, Any], ...]:
+        commits = self._table.history()
+        entries = ({"version": c["version"], "timestamp_ms": c["timestamp"]} for c in commits)
+        return tuple(sorted(entries, key=lambda entry: entry["version"]))
+
+    def _version_for(self, as_of: AsOf) -> int:
+        if as_of.snapshot_id is not None:
+            raise ValueError("Delta addresses history by version or timestamp, not snapshot_id")
+        if as_of.version is not None:
+            return as_of.version
+        # Newest commit at or before the instant asked about.
+        at_or_before = [c for c in self.history() if c["timestamp_ms"] <= as_of.timestamp_ms]
+        if not at_or_before:
+            raise ValueError(f"{self.definition.name}: no version at {as_of.timestamp_ms}")
+        return max(at_or_before, key=lambda commit: commit["version"])["version"]
+
+    def compact(self) -> MaintenanceOutcome:
+        metrics = self._table.optimize.compact(target_size=self._settings.target_file_size_bytes)
+        return MaintenanceOutcome(
+            job="compact",
+            table=self.definition.name,
+            status="applied",
+            detail=str(metrics),
+        )
+
+    def expire_snapshots(self) -> MaintenanceOutcome:
+        """Delta expires by log retention, so this prunes checkpointed log entries."""
+        self._table.cleanup_metadata()
+        return MaintenanceOutcome(
+            job="expire_snapshots",
+            table=self.definition.name,
+            status="applied",
+            detail=(
+                f"log cleaned; time travel reaches back "
+                f"{self._settings.snapshot_retention_hours}h via delta.logRetentionDuration"
+            ),
+        )
+
+    def remove_orphan_files(self) -> MaintenanceOutcome:
+        dry_run = self._settings.dry_run_maintenance
+        removed = self._table.vacuum(
+            retention_hours=self._settings.orphan_file_grace_hours,
+            dry_run=dry_run,
+            enforce_retention_duration=True,
+        )
+        verb = "would delete" if dry_run else "deleted"
+        return MaintenanceOutcome(
+            job="remove_orphan_files",
+            table=self.definition.name,
+            status="applied",
+            detail=f"{verb} {len(removed)} file(s)",
+        )
+
+
+class DeltaCatalog:
+    """A path-based catalog: the name-to-location rule lives here and nowhere else."""
+
+    def __init__(self, settings: LakehouseSettings) -> None:
+        self._settings = settings
+
+    def _location(self, name: str) -> str:
+        return f"{self._settings.warehouse_uri.rstrip('/')}/{self._settings.namespace}/{name}"
+
+    def load(self, name: str) -> Table:
+        table = DeltaTable(self._location(name))
+        return DeltaTableHandle(table, definition_of(name), self._settings)
+
+    def create_if_absent(self, definition: TableDefinition) -> Table:
+        location = self._location(definition.name)
+        if not DeltaTable.is_deltatable(location):
+            DeltaTable.create(
+                location,
+                Schema(_fields(definition)),
+                mode="ignore",
+                partition_by=list(definition.partition_by) or None,
+                name=definition.name,
+                description=definition.description or None,
+            )
+        return DeltaTableHandle(DeltaTable(location), definition, self._settings)
+
+    def list_tables(self) -> tuple[str, ...]:
+        existing = (n for n in sorted(TABLES) if DeltaTable.is_deltatable(self._location(n)))
+        return tuple(existing)
+
+
+def build_catalog(settings: LakehouseSettings) -> DeltaCatalog:
+    return DeltaCatalog(settings)