previously 0.1.0a1__tar.gz

previously-0.1.0a1/.dockerignore

@@ -0,0 +1,3 @@
+*
+!pyproject.toml
+!uv.lock

previously-0.1.0a1/.github/workflows/audit.yml

@@ -0,0 +1,72 @@
+# The dependency audit: `pip-audit` against the locked environment, which
+# the architecture record lists among the tools and which was never built
+# until 2026-10-04.
+#
+# A workflow of its own, not a seventh step in `gates.yml`, because it
+# answers a different question. The six gates judge the tree: their result
+# changes only when the tree does, so a commit that was green stays green.
+# An audit's result changes when an advisory is published, on a day when
+# nobody touched anything. As a gate it would turn a pull request red for a
+# reason that is not in the pull request, and run only when somebody pushes
+# it would miss the day the advisory arrives. Hence the weekly schedule
+# beside the two triggers it shares with the gates.
+#
+# The same care as `gates.yml`: read-only permissions, actions pinned by
+# commit, the locked dependencies, the versions named in the log.
+name: Audit
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  schedule:
+    # Mondays at 05:17 UTC. Not on the hour: GitHub's documentation of the
+    # `schedule` event names the start of every hour as a time of high load,
+    # when a scheduled run can be delayed or dropped.
+    - cron: "17 5 * * 1"
+
+# Nothing here writes: the audit reads the environment and reports its exit
+# code.
+permissions:
+  contents: read
+
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+
+    steps:
+      # The same pins as `gates.yml`, by commit with the version beside it.
+      - name: Check out
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Set up uv and Python 3.14
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          python-version: "3.14"
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+
+      - name: Install the locked dependencies
+        # `--locked`, so the run fails when `uv.lock` does not match
+        # `pyproject.toml` instead of auditing a fresh resolution.
+        # `--all-extras`, so every package the gates install is audited,
+        # and `pip-audit` itself, which lives in [dev].
+        run: uv sync --locked --all-extras
+
+      - name: Name the versions
+        run: |
+          uv --version
+          uv run python -VV
+          uv run pip-audit --version
+
+      - name: Audit the dependencies
+        # The installed environment, which is the locked one. The project
+        # itself is installed editable and is not on PyPI, so there is
+        # nothing to look it up against; `--skip-editable` leaves it out and
+        # names it as skipped in the log. `--strict` cannot be added: it
+        # fails the run on that very skip (measured on 2026-10-04, exit 1
+        # with "previously: distribution marked as editable").
+        #
+        # A finding fails this workflow. Nothing is suppressed here: a
+        # vulnerability is answered by a lock update, not by an ignore list.
+        run: uv run pip-audit --skip-editable --progress-spinner off

previously-0.1.0a1/.github/workflows/gates.yml

@@ -0,0 +1,103 @@
+# The five gates out of CLAUDE.md, plus a sixth for the documentation build
+# (task 1 of the 2026-10-03 documentation plan), run on a machine that is not
+# the author's.
+#
+# Acceptance condition 4 in §11 of the stage 1a spec reads "a deliberately
+# wrong import lets CI fail". Until this file there was no CI, so the
+# condition was asserted rather than met: `tests/test_contracts.py` ran only
+# when somebody started `pytest` by hand, and `.pre-commit-config.yaml` runs
+# ruff and five hygiene hooks — no pyright, no lint-imports, no pytest.
+#
+# Deliberately nothing beyond the gates: no publishing, no uploading of
+# reports, no secrets, no access to anything outside the repository. The
+# repository is public (AGPL-3.0-or-later) and compute minutes are free, but a
+# workflow with write permissions would be attack surface without a use.
+# `release.yml` calls this file as its first job, through `workflow_call`, and
+# it is there, not here, that anything gets published.
+name: Gates
+
+on:
+  push:
+  pull_request:
+  workflow_call:
+
+# The minimum, stated explicitly instead of inherited from the repository's
+# default. Nothing here writes: the gates read the tree and report their exit
+# code.
+permissions:
+  contents: read
+
+jobs:
+  gates:
+    # Docker is needed, because `tests/conftest.py` raises a real PostgreSQL
+    # 17 and a real S3 server, RustFS, via testcontainers — no mock stands in
+    # for the database or the blob store (CLAUDE.md).
+    # Checked, not assumed: the runner image for ubuntu-24.04, which
+    # `ubuntu-latest` currently resolves to, lists "Docker Client 28.0.4",
+    # "Docker Server 28.0.4" and "Docker Compose 2.38.2"
+    # (actions/runner-images, images/ubuntu/Ubuntu2404-Readme.md). So no
+    # service container: `conftest.py` brings its own containers up, and a
+    # second route to either server beside it would be a trap for the next
+    # reader.
+    runs-on: ubuntu-latest
+
+    steps:
+      # Both actions are pinned by commit, not by tag: a tag can be moved, a
+      # commit cannot. The version stands beside it so that the pin is
+      # legible.
+      - name: Check out
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Set up uv and Python 3.14
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          # Python 3.14 is not a preference: the annotations in `canonical.py`
+          # and `hashing.py` work only thanks to PEP 649, and an older version
+          # fails there. `requires-python = ">=3.14"` says the same thing, but
+          # saying it here as well makes the log name the version.
+          python-version: "3.14"
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+
+      - name: Install the locked dependencies
+        # `--locked`, not `--frozen` and not a free resolution: the run fails
+        # if `uv.lock` does not match `pyproject.toml`, instead of quietly
+        # resolving something else and testing a different project than the
+        # development tree. `--all-extras` brings [test], [dev] and [docs],
+        # which is where pytest, pyright, ruff, import-linter, sphinx and
+        # vale live. So gate 6 installs nothing of its own.
+        run: uv sync --locked --all-extras
+
+      - name: Name the versions
+        # So that the log says what was tested, instead of this file claiming
+        # it. Two lines, no gate — but the version is part of every result
+        # underneath.
+        run: |
+          uv --version
+          uv run python -VV
+
+      # The six gates, each as its own step: that way the log names which
+      # one failed instead of one block going red.
+      - name: Gate 1 — ruff check
+        run: uv run ruff check .
+
+      - name: Gate 2 — ruff format
+        run: uv run ruff format --check .
+
+      - name: Gate 3 — pyright
+        run: uv run pyright
+
+      - name: Gate 4 — lint-imports
+        run: uv run lint-imports
+
+      - name: Gate 5 — pytest
+        run: uv run pytest --cov --cov-report=term-missing
+
+      - name: Gate 6 — documentation
+        # Warnings are errors (-W in docs/Makefile). linkcheck runs here too:
+        # the hosts that rate-limit crawlers are listed in conf.py's
+        # linkcheck_ignore, so a failure means a genuinely broken link.
+        run: |
+          make -C docs html
+          make -C docs vale
+          make -C docs linkcheck

previously-0.1.0a1/.github/workflows/release.yml

@@ -0,0 +1,348 @@
+# The way out: the package to PyPI and the image to ghcr.io, built only from
+# a tree that passed the six gates.
+#
+# Three triggers, and what each one reaches:
+#
+#   push to main       gates -> build -> publish-testpypi
+#   manual start       the same, when started on main; elsewhere build only
+#   published release  gates and tag, side by side -> build -> publish-pypi
+#                      -> image (amd64 and arm64) -> manifest
+#
+# A tag alone publishes nothing, and neither does a merge: only publishing the
+# GitHub release does. The environments hold the second lock: `testpypi`
+# accepts a deployment only from the branch main, `pypi` only from a tag
+# `v*`, and the trusted publishers on PyPI and Test-PyPI name this file and
+# those two environments, so no upload token lies in the repository.
+#
+# Every job after `tag` states its whole condition, `!cancelled()` and the
+# result of the job it needs, instead of leaning on the implicit `success()`.
+# On a push to main `tag` is skipped, and the implicit `success()` counts a
+# skipped job as not passed: directly upstream (actions/runner#491), and also
+# further up, below a job that did run (actions/runner#2205, still open on
+# 2026-10-05) — `publish-testpypi` would never run. Spelled out, a failing
+# gate or a failing tag check leaves `build` skipped, and every job below it
+# is skipped with it, because each one asks for `success` from the one above.
+name: Release
+
+on:
+  push:
+    branches: [main]
+  release:
+    types: [published]
+  workflow_dispatch:
+
+# One run per ref at a time, and a running one is never cancelled by a newer
+# one: a run cut off halfway could leave a version on PyPI without its image.
+# A run that still waits can be: GitHub keeps one waiting run per group, and
+# a newer one replaces it. A release has a ref of its own, its tag, so that
+# touches only pushes and manual starts on a branch, where the newer run
+# builds the newer tree.
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+# The default for every job. A job that sets `permissions:` of its own
+# replaces this default instead of adding to it, so each such job names all
+# it needs, `contents: read` included where it checks out.
+permissions:
+  contents: read
+
+jobs:
+  gates:
+    # The same file a push and a pull request run, so the gates stand in one
+    # place. On a push to main they therefore run twice, once there and once
+    # here: the price of not copying them.
+    uses: ./.github/workflows/gates.yml
+
+  tag:
+    # Before anything is uploaded: a tag in another form would otherwise only
+    # be refused after the package is on PyPI. The version on PyPI and in the
+    # image is the tag without its `v` (hatch-vcs reads it, `image` strips
+    # it), so the tag must have a form that PEP 440 normalization leaves as
+    # it is. The four forms do; a leading zero (`v1.02.3`) passes this check
+    # and does not, because hatch-vcs makes it `1.2.3` while `image` waits for
+    # `1.02.3`. That is a mistake in the tag, named here, not tested for.
+    if: github.event_name == 'release'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check the tag's form
+        run: |
+          re='^v[0-9]+\.[0-9]+\.[0-9]+((a|b|rc)[0-9]+)?$'
+          [[ "$GITHUB_REF_NAME" =~ $re ]] || {
+            echo "::error::tag $GITHUB_REF_NAME is not vX.Y.Z, vX.Y.ZaN, vX.Y.ZbN or vX.Y.ZrcN"; exit 1; }
+
+  build:
+    needs: [gates, tag]
+    # `tag` is skipped everywhere but on a release, so skipped counts as
+    # passed here; failed and cancelled do not.
+    if: >-
+      ${{ !cancelled() && needs.gates.result == 'success'
+      && (needs.tag.result == 'success' || needs.tag.result == 'skipped') }}
+    runs-on: ubuntu-latest
+    steps:
+      # Pinned by commit with the version beside it, as in `gates.yml`, and
+      # these two with the same commits.
+      - name: Check out
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          # hatch-vcs reads the version from the tags, so it needs the
+          # history: on a release the tag itself; on main a development
+          # version, `0.1.devN` before the first tag (`0.1.dev178`, measured
+          # on 2026-10-05), and after it one counted from the last tag.
+          fetch-depth: 0
+
+      - name: Set up uv and Python 3.14
+        # No `enable-cache`: its default, `auto`, leaves the cache off for
+        # release and tag-push events (the input's own description in
+        # setup-uv's action.yml), so what goes to PyPI is built without
+        # anything an earlier run left behind.
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          python-version: "3.14"
+
+      - name: Build the sdist and the wheel
+        run: uv build
+
+      - name: Upload the distributions
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish-testpypi:
+    needs: build
+    # `github.ref` and not the event: a manual start on main publishes here
+    # as a push does, a manual start anywhere else reaches nothing beyond
+    # the build.
+    if: ${{ !cancelled() && needs.build.result == 'success' && github.ref == 'refs/heads/main' }}
+    runs-on: ubuntu-latest
+    environment: testpypi
+    # Trusted publishing: the OIDC token is the only credential.
+    permissions:
+      id-token: write
+    steps:
+      - name: Download the distributions
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to Test-PyPI
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          # A rerun on main would otherwise fail on the files the first run
+          # already uploaded.
+          skip-existing: true
+
+  publish-pypi:
+    needs: build
+    # No `skip-existing` here: a version that is on PyPI never comes back,
+    # and a release that finds its version taken has to fail, not pass.
+    if: ${{ !cancelled() && needs.build.result == 'success' && github.event_name == 'release' }}
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download the distributions
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+
+  image:
+    needs: publish-pypi
+    # The image installs Previously from PyPI, so it comes after PyPI and
+    # never on main, where `publish-pypi` is skipped.
+    if: ${{ !cancelled() && needs.publish-pypi.result == 'success' }}
+    strategy:
+      matrix:
+        include:
+          - {platform: linux/amd64, runner: ubuntu-latest}
+          - {platform: linux/arm64, runner: ubuntu-24.04-arm}
+    # Each platform on a runner of its own architecture: no emulation, and the
+    # smoke test runs the image natively.
+    runs-on: ${{ matrix.runner }}
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - name: Check out
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Version from the tag
+        id: version
+        run: echo "version=${GITHUB_REF_NAME#v}" >> "$GITHUB_OUTPUT"
+
+      - name: Wait for the version on PyPI
+        # The upload has finished, but the index may answer a moment later.
+        # 30 attempts, 10 seconds apart: five minutes of waiting at most,
+        # plus the time the requests take.
+        env:
+          VERSION: ${{ steps.version.outputs.version }}
+        run: |
+          echo "waiting for previously==$VERSION on PyPI"
+          for i in $(seq 1 30); do
+            if curl -sf "https://pypi.org/pypi/previously/$VERSION/json" > /dev/null; then
+              echo "available on PyPI"
+              exit 0
+            fi
+            echo "attempt $i: not yet available, waiting 10 s"
+            sleep 10
+          done
+          echo "::error::previously==$VERSION did not appear on PyPI"
+          exit 1
+
+      - name: Platform suffix and an empty wheels context
+        # `linux/amd64` becomes `linux-amd64` for the intermediate tag.
+        # `wheels` stays empty, so the Dockerfile has nothing to find there and
+        # installs the package from PyPI.
+        id: platform
+        env:
+          PLATFORM: ${{ matrix.platform }}
+        run: |
+          echo "suffix=${PLATFORM//\//-}" >> "$GITHUB_OUTPUT"
+          mkdir -p "$RUNNER_TEMP/wheels"
+
+      - name: Log in to ghcr.io
+        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1
+
+      - name: Build and push the platform image
+        # Under an intermediate tag `<version>-linux-<arch>` that nobody is
+        # meant to use: the tags people use arise only in `manifest`, once both
+        # platforms passed the smoke test.
+        id: build
+        uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0
+        with:
+          # `.` and not the default, a git context of the ref: the build reads
+          # the checked-out `pyproject.toml` and `uv.lock`.
+          context: .
+          build-contexts: wheels=${{ runner.temp }}/wheels
+          push: true
+          platforms: ${{ matrix.platform }}
+          tags: ghcr.io/${{ github.repository }}:${{ steps.version.outputs.version }}-${{ steps.platform.outputs.suffix }}
+          # The revision and the moment the labels name: the commit of the
+          # release and the time it was published, both fixed for the
+          # release, so a rerun labels the image the same way.
+          build-args: |
+            PREVIOUSLY_VERSION=${{ steps.version.outputs.version }}
+            PREVIOUSLY_REVISION=${{ github.sha }}
+            PREVIOUSLY_CREATED=${{ github.event.release.published_at }}
+
+      - name: Set up uv
+        # For `uv export` in the smoke test, which reads `uv.lock` and needs no
+        # Python: measured on 2026-10-05 with UV_PYTHON_DOWNLOADS=never in an
+        # image that has uv and no interpreter, exit 0.
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+
+      - name: Smoke test
+        # Against the image as pushed: nothing is loaded locally, so
+        # `docker run` pulls it from ghcr.io. If it fails, this job fails,
+        # `manifest` does not run, and the version stays without the tags
+        # anyone uses — only the intermediate ones exist. The package is on
+        # PyPI by then; that is the price of an image installed from PyPI.
+        env:
+          IMAGE: ghcr.io/${{ github.repository }}:${{ steps.version.outputs.version }}-${{ steps.platform.outputs.suffix }}
+        run: bash scripts/smoke-image.sh "$IMAGE"
+
+      - name: Export the digest
+        # An empty file named after the digest: `manifest` needs the names,
+        # not the contents.
+        env:
+          DIGEST: ${{ steps.build.outputs.digest }}
+        run: |
+          mkdir -p "$RUNNER_TEMP/digests"
+          touch "$RUNNER_TEMP/digests/${DIGEST#sha256:}"
+
+      - name: Upload the digest
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: digests-${{ steps.platform.outputs.suffix }}
+          path: ${{ runner.temp }}/digests/*
+          if-no-files-found: error
+          # A week: `manifest` reads both digests, also when it is rerun on
+          # its own, days later, after a failure. Expired, they are gone, and
+          # the rerun fails with the package on PyPI and no image. The files
+          # are empty, so keeping them costs nothing.
+          retention-days: 7
+
+  manifest:
+    needs: image
+    # A matrix job's result is `success` only when every platform succeeded.
+    if: ${{ !cancelled() && needs.image.result == 'success' }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - name: Download the digests
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          path: ${{ runner.temp }}/digests
+          pattern: digests-*
+          merge-multiple: true
+
+      - name: Log in to ghcr.io
+        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1
+
+      - name: Image tags
+        # `pep440`, not `semver`: `v0.1.0a1` is no valid semver, and the
+        # `semver` type skips such a tag with a warning — the first release
+        # would get no tag at all. Measured on 2026-10-05 by running this
+        # action's own `dist/index.cjs` at the pinned commit with these inputs:
+        # `v1.2.3` gives `1.2.3`, `1.2` and `latest`; `v0.1.0a1` and
+        # `v1.2.3rc4` give the version alone, because the action extends a
+        # pre-release to `{{version}}` only; and the `semver` rules give
+        # `v0.1.0a1` no tag, with "No Docker tag has been generated".
+        #
+        # `latest=false` takes away the automatic `latest`, which the action
+        # derives from the tag's form — without it, `v1.2.3` marked as a
+        # pre-release still got `latest` in the same measurement. The rule
+        # below derives it from the release's mark instead. A tag whose form
+        # and mark disagree is a mistake made when publishing, and this file
+        # does not second-guess it: the mark decides.
+        id: meta
+        uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6.2.0
+        with:
+          images: ghcr.io/${{ github.repository }}
+          flavor: |
+            latest=false
+          tags: |
+            type=pep440,pattern={{version}}
+            type=pep440,pattern={{major}}.{{minor}}
+            type=raw,value=latest,enable=${{ github.event.release.prerelease == false }}
+
+      - name: Create and push the manifest list
+        # One manifest list over both platform images, under every tag of the
+        # step above.
+        env:
+          IMAGE: ghcr.io/${{ github.repository }}
+        run: |
+          tags=()
+          while IFS= read -r tag; do
+            tags+=(-t "$tag")
+          done < <(jq -r '.tags[]' <<< "$DOCKER_METADATA_OUTPUT_JSON")
+          sources=()
+          for digest in "$RUNNER_TEMP"/digests/*; do
+            sources+=("$IMAGE@sha256:${digest##*/}")
+          done
+          docker buildx imagetools create "${tags[@]}" "${sources[@]}"

previously-0.1.0a1/.gitignore

@@ -0,0 +1,28 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+*.egg-info/
+dist/
+build/
+
+# Tools
+.ruff_cache/
+.pytest_cache/
+.mypy_cache/
+.coverage
+.coverage.*
+htmlcov/
+
+# Editor and system
+.idea/
+.vscode/
+.DS_Store
+
+# Worktrees and agent workspaces
+.claude/
+.superpowers/
+
+# Documentation
+docs/_build/
+.vale-styles/Microsoft/

previously-0.1.0a1/.importlinter

@@ -0,0 +1,116 @@
+[importlinter]
+root_package = previously
+# Five of the six contracts forbid external packages (sqlalchemy, psycopg,
+# alembic, anthropic, openai, pyrage, boto3, botocore). import-linter requires
+# this setting for that, otherwise it aborts with a configuration error — it
+# is not a loosening of the contracts themselves.
+include_external_packages = True
+
+[importlinter:contract:layers]
+name = Layers: core beside migrations, both above storage, contract below all
+type = layers
+layers =
+    previously.cli
+    previously.core | previously.migrations
+    previously.storage
+    previously.contract
+
+[importlinter:contract:core-is-clean]
+name = core knows no foreign system and no model
+type = forbidden
+source_modules =
+    previously.core
+forbidden_modules =
+    sqlalchemy
+    psycopg
+    alembic
+# Until 2026-10-04 this contract carried two named exemptions,
+# `core.append -> storage.postgres` and `core.verify -> storage.postgres`,
+# because both modules typed their `storage` parameter as the concrete
+# `PostgresStorage` under `TYPE_CHECKING`. They were granted by ruling T7-a
+# and by ruling T8-c of the 2026-10-02 stage 1a plan, whose execution ledger
+# was never shipped and is lost, so both labels are provenance and nothing
+# more — the reasoning is the paragraph you are reading.
+#
+# There is no directory to follow them into, and until 2026-10-04 this
+# comment named one. Measured that day against the only record under
+# `docs/superpowers/sdd/`: `2026-10-03-dokumentation/progress.md` carries a
+# `Ruling T7-a` about an unrelated decision and no `Ruling T8-c` at all, so
+# the pointer sent a reader to the wrong decision — worse than a label with
+# no pointer, because the reader stops with an answer.
+#
+# The exemptions were enumerated by name and not matched by a wildcard, so
+# that a third module following the same pattern would break this contract
+# until somebody granted it deliberately — measured with a throwaway module,
+# a wildcard let the new edge through silently.
+#
+# Stage 1b typed `core` against `contract.store.LogStore[Conn]` instead, and
+# the edge is gone. There is nothing to exempt. Should an exemption ever come
+# back here, it is a named edge, never a pattern; {ref}`module-boundaries`
+# carries the measurement that says why.
+
+[importlinter:contract:core-and-contract-know-no-sql]
+name = core and contract import no sqlalchemy
+type = forbidden
+source_modules =
+    previously.core
+    previously.contract
+forbidden_modules =
+    sqlalchemy
+    psycopg
+# Until 2026-10-04 this contract carried the same two named exemptions as
+# `core-is-clean`: edges enumerated one by one, no wildcard across `core`. See
+# there for the reasoning, and for what the two stage 1a ruling labels are
+# worth. Stage 1b typed `core` against `contract.store.LogStore[Conn]`, the
+# edge `core -> storage.postgres` is gone, and there is nothing left to exempt
+# here either.
+#
+# The contract was named `Only storage imports sqlalchemy`, with the id
+# `only-storage-knows-sql`, until 2026-10-05. That day the migrations moved into
+# the package, and they import SQLAlchemy too, so the old name stated
+# something false while the contract still checked the right thing: its
+# sources were always `core` and `contract`, and the name now says so.
+
+[importlinter:contract:no-vendor-sdk]
+name = No vendor SDK in the package
+type = forbidden
+source_modules =
+    previously
+forbidden_modules =
+    anthropic
+    openai
+
+[importlinter:contract:only-sealing-knows-age]
+name = Only core.sealing imports pyrage
+type = forbidden
+source_modules =
+    previously
+forbidden_modules =
+    pyrage
+ignore_imports =
+    previously.core.sealing -> pyrage
+# Sealing happens where the rules are, in `core`, so that the store below
+# gets and gives ciphertext only: a module in `storage` that could open what
+# it stores is the mistake this contract exists to catch. The whole package
+# is the source, and the one edge that may exist is named — never a pattern,
+# for the reason `core-is-clean` gives. Should `core.sealing` stop importing
+# `pyrage`, `lint-imports` fails with "No matches for ignored import"
+# (measured on 2026-10-05), so the exemption cannot outlive its edge.
+
+[importlinter:contract:only-s3-knows-boto3]
+name = Only storage.s3 imports boto3
+type = forbidden
+source_modules =
+    previously
+forbidden_modules =
+    boto3
+    botocore
+ignore_imports =
+    previously.storage.s3 -> boto3
+    previously.storage.s3 -> botocore
+# Storing happens where the foreign systems are, in `storage`, the way SQL
+# stays in `storage.postgres`: what reaches `core` is the protocol in
+# `contract.blobs` and the errors in `storage.errors`, no `botocore` type.
+# `botocore` is forbidden beside `boto3` because the exceptions and the
+# client configuration come from there, and an import of either would carry
+# the foreign system upwards. Two named edges, out of one module.