slicelab 0.0.1__tar.gz

slicelab-0.0.1/.editorconfig

@@ -0,0 +1,28 @@
+# EditorConfig — consistent formatting across editors
+# https://editorconfig.org
+
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 2
+
+[*.{py,rs}]
+indent_size = 4
+
+[*.go]
+indent_style = tab
+
+[*.md]
+trim_trailing_whitespace = false
+
+[Makefile]
+indent_style = tab
+
+[justfile]
+indent_style = space
+indent_size = 4

slicelab-0.0.1/.github/dependabot.yml

@@ -0,0 +1,24 @@
+version: 2
+updates:
+  # The pins live in pyproject.toml's [dependency-groups] and uv.lock. slicelab
+  # has no runtime dependencies by design (docs/DECISIONS.md, and org AGENTS.md
+  # section 10 makes adding one an escalation), so everything here is dev tooling.
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: weekly
+    commit-message:
+      prefix: build
+    groups:
+      python:
+        patterns: ["*"]
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    commit-message:
+      prefix: ci
+    groups:
+      actions:
+        patterns: ["*"]

slicelab-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,81 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  # No branch filter: a stacked pull request is based on its parent branch, not
+  # on main, and a base change fires `edited`, which is not a default activity
+  # type -- so filtering on main means a retargeted PR gets no checks at all.
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  check:
+    name: Check
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v7
+      - uses: extractions/setup-just@v4
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - run: just setup
+      - run: just check
+
+  test:
+    name: Test (Python ${{ matrix.python-version }}, ${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+        os: [ubuntu-latest]
+        include:
+          - python-version: "3.11"
+            os: windows-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: extractions/setup-just@v4
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python-version }}
+      - run: just setup
+      - run: just test
+
+  # The engine matrix is engine.yml, not a job here: it installs a real slicer on
+  # four host shapes and is scheduled rather than run per pull request. It sets
+  # SLICELAB_REQUIRE_ENGINE=1, so a failed engine install is loud rather than a
+  # silent skip. The jobs below run on hosts with no engine, where the
+  # engine-dependent tests skip and `-ra` prints how many were withheld.
+
+  ok:
+    name: ok
+    if: always()
+    needs: [check, test]
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      # Requires SUCCESS rather than testing for failure. `contains(needs.*.result,
+      # 'failure')` does not match 'skipped', so an `if: false` on `check` or `test`
+      # produced a fully green pull request with nothing checked -- measured in a
+      # sibling repo, where that is exactly what happened.
+      #
+      # The tolerant form is right for a workflow with path filtering, where jobs
+      # skip legitimately on a docs-only change. This one has none, so a skipped job
+      # here is always a defect.
+      - name: Fail unless every upstream job succeeded
+        if: >-
+          needs.check.result != 'success' ||
+          needs.test.result != 'success'
+        run: exit 1
+      - name: Pass
+        run: echo 'All checks passed'

slicelab-0.0.1/.github/workflows/engine.yml

@@ -0,0 +1,161 @@
+name: Engine
+
+# The real engines, across the ways people actually install them.
+#
+# ci.yml runs the suite everywhere and SKIPS the engine tests, because no
+# standard runner has a slicer. That leaves discovery -- the thing `which`
+# exists to do -- covered by fake launchers alone. Fakes are exactly what would
+# hide the finding this verb was written for: PrusaSlicer's Flathub entrypoint
+# backgrounds its child and therefore returns 0 for every invocation, so its
+# exit status carries no information (notes/evidence.md V10).
+#
+# Every job sets SLICELAB_REQUIRE_ENGINE=1, so a failed install is a LOUD
+# failure rather than a green run full of skips. A job that could not get an
+# engine must not look like a job that tested one.
+#
+# THIS MATRIX IS ALSO A CONTROL. Every empirical finding behind this project
+# was taken on one Linux host against two Flatpaks. A Flatpak is a materially
+# different execution environment -- sandboxed filesystem, its own /tmp,
+# translated paths -- so behaviour observed only there is not established for
+# native builds. The macOS and Windows jobs run the same code against native
+# 2.9.6, which is the only control available: PrusaSlicer publishes no Linux
+# asset on its GitHub releases (checked across 2.9.6 and the four before it --
+# only setup.exe, .dmg and a Windows .zip), and Debian/Ubuntu ship 2.9.2, a
+# different version.
+#
+# Not on every push: these install large GUI applications and are slower and
+# more fragile than the gate. On demand, and weekly so upstream packaging
+# changes surface without anyone remembering to look.
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 6 * * 1" # Mondays, 06:00 UTC
+
+permissions:
+  contents: read
+
+concurrency:
+  group: engine-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  SLICELAB_REQUIRE_ENGINE: "1"
+
+jobs:
+  flatpak:
+    name: Linux / Flatpak (Flathub, both engines)
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    steps:
+      - uses: actions/checkout@v7
+      - uses: extractions/setup-just@v4
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - name: Install both engines from Flathub
+        run: |
+          set -euo pipefail
+          sudo apt-get update
+          sudo apt-get install -y flatpak
+          sudo flatpak remote-add --if-not-exists flathub \
+            https://dl.flathub.org/repo/flathub.flatpakrepo
+          sudo flatpak install -y --noninteractive flathub com.prusa3d.PrusaSlicer
+          sudo flatpak install -y --noninteractive flathub com.orcaslicer.OrcaSlicer
+      - name: Show what was installed
+        run: flatpak list --app
+      - run: just setup
+      - run: just test
+      - name: Report what discovery chose, and why
+        # The interesting output of this whole workflow. On the development
+        # host PrusaSlicer's default entrypoint is REJECTED for returning 0 and
+        # the --command= bypass wins, while OrcaSlicer keeps its entrypoint
+        # (which carries the packager's LC_NUMERIC=C fix). If a Flathub update
+        # ever changes either, this is where it surfaces.
+        run: uv run slicelab which
+
+  linux-apt:
+    name: Linux / distro package on PATH
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    steps:
+      - uses: actions/checkout@v7
+      - uses: extractions/setup-just@v4
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - name: Install PrusaSlicer from the distro archive
+        run: |
+          set -euo pipefail
+          sudo apt-get update
+          sudo apt-get install -y prusa-slicer
+          command -v prusa-slicer
+      - run: just setup
+      - run: just test
+      - name: Report what discovery chose, and why
+        # Plain PATH discovery, no sandbox. Note this is a DIFFERENT VERSION
+        # from the Flatpak jobs -- Ubuntu ships an older PrusaSlicer -- so it
+        # controls for the install mode, not for the version.
+        run: uv run slicelab which prusaslicer
+
+  macos:
+    name: macOS / Homebrew cask (.app bundle)
+    runs-on: macos-latest
+    timeout-minutes: 45
+    steps:
+      - uses: actions/checkout@v7
+      - uses: extractions/setup-just@v4
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - name: Install PrusaSlicer
+        run: |
+          set -euo pipefail
+          brew install --cask prusaslicer
+          ls -d /Applications/*rusa* || true
+      - name: Put the bundle's binary on PATH, and record what it is called
+        # A macOS .app is a directory, so installing the cask puts nothing on
+        # PATH. The binary inside carries the APPLICATION's name, not the
+        # command's -- discovery looking only for the POSIX name reported the
+        # engine absent on a runner that had just installed it. The listing is
+        # not decoration: the bundle's executable name is a packaging decision
+        # that can change, and this is where we would see it change.
+        run: |
+          set -euo pipefail
+          bundle=$(ls -d /Applications/*rusa*.app | head -1)
+          echo "executables in $bundle/Contents/MacOS:"
+          ls -l "$bundle/Contents/MacOS"
+          echo "$bundle/Contents/MacOS" >> "$GITHUB_PATH"
+      - run: just setup
+      - run: just test
+      - name: Report what discovery chose, and why
+        run: uv run slicelab which prusaslicer
+
+  windows:
+    name: Windows / official portable zip
+    runs-on: windows-latest
+    timeout-minutes: 45
+    steps:
+      - uses: actions/checkout@v7
+      - uses: extractions/setup-just@v4
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - name: Install PrusaSlicer from the official portable zip
+        # The one native build of the EXACT version this project's findings
+        # were taken against (2.9.6). Windows is where the Flatpak-versus-
+        # native control actually lands.
+        shell: pwsh
+        run: |
+          $ErrorActionPreference = "Stop"
+          $url = "https://github.com/prusa3d/PrusaSlicer/releases/download/version_2.9.6/PrusaSlicer-2.9.6.zip"
+          Invoke-WebRequest -Uri $url -OutFile prusaslicer.zip
+          Expand-Archive prusaslicer.zip -DestinationPath $env:RUNNER_TEMP\prusaslicer
+          $exe = Get-ChildItem -Recurse -Filter prusa-slicer-console.exe $env:RUNNER_TEMP\prusaslicer |
+                 Select-Object -First 1
+          if (-not $exe) { throw "prusa-slicer-console.exe not found in the portable zip" }
+          Add-Content -Path $env:GITHUB_PATH -Value $exe.Directory.FullName
+      - run: just setup
+      - run: just test
+      - name: Report what discovery chose, and why
+        run: uv run slicelab which prusaslicer

slicelab-0.0.1/.github/workflows/release.yml

@@ -0,0 +1,149 @@
+name: Release
+
+# Publishes to PyPI via Trusted Publishing (OIDC). No API token is stored.
+#
+# The publisher on PyPI is pinned to heibench/slicelab, this workflow filename,
+# and the `pypi` environment -- all three must match or the publish is refused.
+#
+# This workflow is INERT until a release is published. It exists now because the
+# PyPI pending publisher binds to a workflow filename, so the file must be on
+# main before the name can be reserved.
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      expected_version:
+        description: "Exact version the dist must carry (e.g. 0.1.0) — guards against publishing the wrong ref"
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build and verify
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v7
+      - uses: extractions/setup-just@v4
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Gate on the same checks a pull request runs
+        run: |
+          just setup
+          just check
+          just test
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Guard built version against the intended release
+        # A tag and a version are two statements of one fact; publishing when
+        # they disagree ships something nobody asked for under a name someone
+        # will trust.
+        run: |
+          set -eu
+          version=$(ls dist/*.tar.gz | sed -E 's|.*/slicelab-(.+)\.tar\.gz|\1|')
+          echo "built: $version"
+          case "${{ github.event_name }}" in
+            release) want="${GITHUB_REF_NAME#v}" ;;
+            workflow_dispatch) want="${{ inputs.expected_version }}" ;;
+          esac
+          if [ "$version" != "$want" ]; then
+            echo "::error::built version '$version' does not match intended release '$want'"
+            exit 1
+          fi
+          case "$version" in
+            *.dev*|*rc*|*a[0-9]*|*b[0-9]*)
+              echo "::error::refusing to publish pre-release version '$version'"
+              exit 1 ;;
+          esac
+
+      - name: Assert no distribution carries engine-derived bytes
+        # docs/DECISIONS.md D11. The repository half is tests/test_no_engine_data.py.
+        #
+        # This step used to inspect the wheel only. `packages = ["slicelab"]`
+        # means the wheel can only ever contain slicelab's own module, so that
+        # check was green over a stray it structurally could not see -- while
+        # the sdist, which takes everything git does not IGNORE, shipped a
+        # committed OrcaSlicer `result.json` from the repository root. A guard
+        # that cannot fail is not a guard. Both artifacts are read now.
+        run: |
+          set -eu
+          python3 - <<'PY'
+          import glob, sys, tarfile, zipfile
+
+          # The wheel is slicelab's own module and nothing else.
+          WHEEL_ALLOWED = (".py", ".typed", ".txt", ".md")
+          # The sdist is the working tree minus what git ignores, so it
+          # legitimately carries config and docs. What it must never carry is a
+          # format an engine writes -- the same vocabulary
+          # tests/test_no_engine_data.py uses, including `.log` for the
+          # `00000.log` that D20 and V13 are actually written about.
+          ENGINE_WRITTEN = (
+              ".json", ".ini", ".gcode", ".bgcode", ".log",
+              ".3mf", ".stl", ".obj", ".amf", ".step",
+          )
+
+          bad = []
+
+          wheels = glob.glob("dist/*.whl")
+          sdists = glob.glob("dist/*.tar.gz")
+          if not wheels or not sdists:
+              # Silence must not read as success: no artifacts means this step
+              # examined nothing, which is not the same as finding nothing.
+              print(f"::error::expected a wheel and an sdist, got {wheels + sdists}")
+              sys.exit(1)
+
+          for whl in wheels:
+              for name in zipfile.ZipFile(whl).namelist():
+                  if name.endswith("/") or ".dist-info/" in name:
+                      continue
+                  if not name.endswith(WHEEL_ALLOWED):
+                      bad.append(f"{whl}:{name}")
+
+          for sd in sdists:
+              with tarfile.open(sd) as tf:
+                  for m in tf.getmembers():
+                      if not m.isfile():
+                          continue
+                      if m.name.lower().endswith(ENGINE_WRITTEN):
+                          bad.append(f"{sd}:{m.name}")
+
+          if bad:
+              print("::error::distribution carries unexpected files (D11):")
+              for b in bad:
+                  print("  " + b)
+              sys.exit(1)
+          print(f"checked {len(wheels)} wheel(s) and {len(sdists)} sdist(s): D11 holds")
+          PY
+
+      - name: Check the metadata PyPI will see
+        run: uv run --with twine twine check dist/*
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    environment: pypi
+    permissions:
+      id-token: write # PyPI Trusted Publishing (OIDC)
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1

slicelab-0.0.1/.gitignore

@@ -0,0 +1,42 @@
+# Python
+__pycache__/
+*.py[cod]
+.Python
+build/
+dist/
+*.egg-info/
+.venv/
+venv/
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Engine-derived data is NEVER committed -- see docs/DECISIONS.md D11.
+# slicelab ships zero engine-derived bytes; characterisation output is
+# generated on the user's machine into XDG cache and stays there.
+/characterisation/
+*.characterisation.json
+
+# Generated locks and slicer output from local experiments.
+# A real project's slice.lock IS committed -- these are ours, from scratch runs.
+/scratch/
+*.gcode
+*.bgcode
+slice.lock
+
+# Engine litter. OrcaSlicer writes into the process CWD: 00000.log on a failing
+# run (D20, V13), and result.json on any run at all -- including a successful
+# `which` probe. It is swept now, but the one that got committed was result.json
+# and it was NOT listed here, so nothing objected. Both are named, and both are
+# in the D11 vocabulary that tests/test_no_engine_data.py enforces.
+00000.log
+result.json
+
+# Editors / OS
+.DS_Store
+.idea/
+.vscode/

slicelab-0.0.1/.pre-commit-config.yaml

@@ -0,0 +1,22 @@
+repos:
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.27.2
+    hooks:
+      - id: gitleaks
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-merge-conflict
+      - id: check-added-large-files
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.11.12
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

slicelab-0.0.1/AGENTS.md

@@ -0,0 +1,178 @@
+# AGENTS.md — slicelab
+
+Instructions for humans and AI coding agents working in this repository.
+
+The org-wide contract at <https://github.com/heibench/.github/blob/main/AGENTS.md>
+is the floor. This file carries what is specific to slicelab; where the two
+conflict, this file wins.
+
+## Project
+
+`slicelab` is a **driver**, not a checker. It puts a Slic3r-descended slicer under
+program control and records exactly what that engine resolved. It does not
+adjudicate G-code — that is `slicespec`'s job, and it does not exist yet.
+
+**One mechanism justifies the whole tool and nothing else does:** ask the engine
+what it *actually resolved*, diff that against what was requested, per key, and
+refuse to call the run green when they disagree.
+
+Everything else — the lock file, the multi-engine story, a native backend —
+is downstream of that one move. If the readback diff is ever weakened, delete
+the project rather than ship it.
+
+**Status: pre-alpha. Two verbs work: `slicelab which` and `slicelab presets`.**
+`which` discovers an installed engine, probes whether that engine's exit status
+can be believed, and reports its identity. `presets` enumerates an engine's
+printer presets, adjudicated on the JSON rather than the exit code. Nothing
+slices, reads a `slice.toml`, or writes a lock.
+
+Treat this section as code: the moment another verb works, this paragraph is
+false and the change that made it work is not finished until it is corrected
+(org AGENTS.md 2.5). It has been corrected once when the exit map landed, once
+when `which` did, and once when `presets` did — stated as causes rather than as
+a tally, because the tally in `SECURITY.md` kept being the stale claim.
+
+## Start here
+
+1. `docs/DECISIONS.md` — numbered decisions, with the reasoning that produced each.
+   Do not relitigate a numbered decision; if it is wrong, add a superseding entry.
+2. `docs/RESEARCH.md` — what was empirically established, what was refuted, and
+   what remains unverified. Read the third list before planning anything.
+3. `notes/` — the frozen dossier the decisions cite. `notes/evidence.md` carries
+   the reproductions; issues and decisions cite them by tag.
+
+## Stack
+
+- **Python >= 3.11** (`tomllib`), packaged with `hatchling`, `uv` against a
+  committed `uv.lock`.
+- **No runtime dependencies.** `tomllib`, `hashlib`, `subprocess` and `argparse`
+  are stdlib. Adding one is org AGENTS.md section 10 — escalate, do not decide.
+- **Tooling** — `ruff` (format + lint), `mypy` (types), `pytest`, `just`,
+  `pre-commit`.
+
+## Commands
+
+```sh
+just setup          # uv sync
+just fmt            # format + autofix
+just check          # fmt-check + lint + typecheck (CI-equivalent)
+just test           # run tests; engine tests skip when no slicer is installed
+just test-engine    # run tests and FAIL if no engine is installed
+just hooks          # every pre-commit hook over the whole tree
+```
+
+Run `just check && just test` before every commit. Never `--no-verify`.
+
+## The rules that are not negotiable
+
+Each is a decision with evidence behind it. The tag in brackets is the
+reproduction in `notes/evidence.md`.
+
+1. **The readback diff is the mechanism; a compatibility flag is not** (D4).
+   Every authored override is compared against the engine's own resolved output.
+   PrusaSlicer silently coerces `--perimeters 4.7` to `4` at exit 0 with zero
+   bytes on stderr [V1], and silently drops an unknown key from a `--load`ed ini
+   the same way [V2]. `--config-compatibility=disable` catches neither [V3], and
+   does not exist on OrcaSlicer.
+2. **Capture is gated on the artifact; the artifact is staged then promoted**
+   (D7). `--save` runs before the slice block and is not conditioned on it: an
+   out-of-bounds object gives exit 0, no G-code, and a complete ini anyway [V4].
+   A run that did not write the file must never report as one that did.
+3. **The core vocabulary is EMPTY** (D2). Authored keys are the engine's own
+   native names under an engine-namespaced table. `CORE_KEYS == frozenset()`,
+   asserted by a test. A key enters only through D3's recorded admission
+   procedure. A vocabulary written from one engine *is* the PrusaSlicer-shaped
+   abstraction this project exists to avoid.
+4. **Never adjudicate on an engine's exit code without probing it first** (D17,
+   D18). `--query-printer-models` returns exit 1 with 6550 bytes of valid JSON —
+   the same code it returns for "not found" [V5]. And the Flatpak entrypoint
+   backgrounds its child, so *every* invocation returns 0 unless the
+   `--command=` bypass is used [V10]. That bypass is mandatory for PrusaSlicer
+   and harmful for OrcaSlicer. Probe per package; never copy it as a constant.
+5. **Reproducibility is a measured value, never an assumption** (D8). Three runs
+   of one part with `--fuzzy-skin all` gave three distinct normalized hashes and
+   three distinct filament-used values [V8]. Without the measurement, a hash
+   mismatch from fuzzy skin is indistinguishable from real drift and `verify`
+   reports *violated* — a false red, which is the silence rule inverted.
+6. **Ship zero engine-derived bytes** (D11). Engine help text, default key sets,
+   preset catalogues and option metadata are generated on the user's machine into
+   XDG cache and gitignored. The subprocess argument settles *linking* and says
+   nothing about *copying*.
+7. **No escape hatches** (org 2.1). No `--allow-coercion`, no
+   `--allow-engine-drift`, no `--force-lock`. Shipping the escape hatch alongside
+   the discipline means the discipline is never tested. `--report PATH` is the
+   answer: machine-readable, naming exactly which key diverged.
+
+## Outcomes and exit codes
+
+Two levels, never one flat list — matching partspec's Status-per-check /
+Verdict-per-part and netspec's D9/D26 split.
+
+| Outcome | Exit | Meaning |
+|---|---|---|
+| `sliced` | 0 | Artifact exists, non-empty, **promoted by this run**, its config export captured in the *same invocation*, every requested key `applied`, `adapter.exact` true. |
+| `refused` | 1 | slicelab established the intent was not honoured. The driver's analogue of *violated*: we looked, the answer is no. |
+| `incomplete` | 2 | slicelab ran but cannot stand behind the result. **Never reachable from an unexamined success path.** |
+| `empty` | 3 | The run verified nothing, because nothing was requested. Neither success nor a finding (D24). |
+| `error` | 4 | Environment fault. Not a verdict on the intent. |
+| — | 64 | Usage: slicelab's own argv. |
+
+These are org contract **section 6.2**'s codes, which is now the settled org-wide
+vocabulary: A1, A2 and A3 closed on 2026-09-06 and partspec, netspec and gerberdiff
+all answer on the same five. slicelab conforms rather than chooses. Only the *words*
+diverge, and deliberately — see D14.
+
+**`empty` (3) is not `sliced`.** A `slice.toml` with a `[base]` triple and no
+`[set]` keys produces a real artifact and verifies nothing — "every requested key
+was applied" is vacuously true over zero keys. That run is `empty`, the artifact
+is still promoted, and no lock is written. `3` is partspec's code for the same
+idea and is **not** in §6.2's table; slicelab is the second member using it, and
+that is escalated rather than assumed. See D24.
+
+**`refused` outranks `incomplete`.** When one requested key is `coerced` and another
+is `absent`, the run is `refused` (1), not `incomplete` (2). A finding about the
+request stays a finding even when some other key could not be evaluated; the reverse
+would let one unreadable key mask a real one. Taken from netspec D26, which settled
+the same precedence for the verify layer — this is the driver's form of it, adopted
+rather than re-derived.
+
+The renderer prints the outcome word as the **first token** of output (D14). A
+past-tense verb leading a non-zero run reads green to a human skimming CI logs.
+
+## Constraints
+
+- **`readback.py` knows no engine's option names.** Engine-specific logic lives
+  under `adapters/<engine>/`. A structural test confirms it — scoped to the FFF
+  config-key namespace, not to every string constant.
+- **The `sliced` outcome must be unreachable with an empty subject set.** With
+  zero requested keys, "every requested key was applied" is vacuously true, and
+  a base-only `slice.toml` is the first file anyone writes. See G1 in
+  `notes/critique.md`; this is the highest-priority correctness constraint in
+  the project.
+- **Map option names to config keys by probing, never by string transform.**
+  411 CLI options, 343 config keys, 70 options with no matching key.
+  `--after-layer-gcode` writes `layer_gcode`, so dash-to-underscore reports a
+  false `absent` on a perfect run. See G2 in `notes/critique.md`.
+- **Do not reimplement the engine's arithmetic.** The premise is that the engine
+  knows what the slice is and we do not.
+- **Do not write a test that reads a doc, reads the code, and diffs them**, and
+  do not assert that a phrase appears in prose. A doc test must assert something
+  executable.
+- Always name an encoding when reading or writing engine output, and decode the
+  engine itself with `errors="replace"` (inherited from prusaslicer-py D5).
+- Do not add AI attribution to commits or PR descriptions — no co-author
+  trailers, session links, or "generated with" footers.
+- Do not name, link, or describe any private repository in public output.
+
+## Related
+
+Siblings, deliberately non-overlapping:
+
+- `prusaslicer-py` — a narrow, finished, single-engine PrusaSlicer driver. It is
+  **maintained separately and slicelab does not import it** (org section 5: the
+  stable surface is never the Python API). Two files' worth of Flatpak path
+  handling were copied with attribution and one fix; see D19.
+- `partspec` — verifies CAD-as-code parts. `netspec` — PCB connectivity.
+  `gerberdiff` — fabrication output. `orlab` — the reference DRIVE-layer member.
+- `slicespec` — does not exist. When it does, it reads `slice.lock` as a **file**
+  and never imports slicelab (D22).