diff --git a/docs/plans/2026-10-13-python-sdk-tracer-findings.md b/docs/plans/2026-10-13-python-sdk-tracer-findings.md
new file mode 100644
index 000000000..b57cb043d
--- /dev/null
+++ b/docs/plans/2026-10-13-python-sdk-tracer-findings.md
@@ -0,0 +1,298 @@
+# Python SDK tracer — findings from the first attempt
+
+> **Superseded on `next` (2026-10-20).** This is a snapshot of `main` on
+> 13 October 2026. The engine has since moved on the `next` branch: a
+> record crosses as a frame (`ValueFrame`), not an `FfiValue` tree; Stack
+> Encrypt's EQL types are v4 only (`public.eql_v4_text_eq`), not the v3
+> domains this tracer stored into; most of the 51 EQL v4 types are
+> producible (40 on 2026-10-20; `languages/golang/encrypt/eql/eql_gen.go`
+> on `next` says which), not only `TextEq`; and the new kinds (`decimal`,
+> `date`, `timestamp`) have landed. Read the engine sections as history. The
+> Python and toolchain section (pyo3 0.29, maturin-only `extension-module`,
+> libpython on the loader path, `Pending` as `IntoFuture`, width narrowing,
+> the psycopg plumbing) still holds. The restart plan reads
+> `packages/stack-encrypt/docs/language-integration.md` first; that guide
+> is PR #1287, open against `next` as this header is written, and this
+> document merges after it.
+
+**Status:** a proto-prototype, stopped by decision on 2026-10-13 after 7 of 9
+tasks, to be restarted fresh. The branch is kept as a reference under
+`prototype/python-sdk-tracer`. **Do not merge it.** Read this file, then
+the Python SDK discovery ticket, then start again from `next`.
+
+The code is disposable. What follows is not: it is what the code proved,
+and most of it would take days to rediscover.
+
+## What was proven, live
+
+Against ZeroKMS (through the `stash auth login` profile) and a Postgres with
+EQL v3.0.6 applied — 53 tests green, 3 Rust unit tests green:
+
+1. `import stackencrypt` from an `abi3-py39` wheel built by maturin over
+   `stack-encrypt`, in a fourth Cargo workspace at `languages/python`.
+2. `Plan.of(User).context("users").build()` reads `Annotated` hints into the
+   engine's data plan, fails closed at `build()` on an undeclared field
+   (import time when that call sits at module level — by convention, not by
+   construction; see "Gaps against the discovery ticket's wording"), and the engine's
+   own `plan_with` validates the rest with no credentials.
+3. `Cipher(plan).encrypt(models)` seals a batch in **one** ZeroKMS request;
+   an empty batch makes none; `decrypt` returns the model type; `query`
+   returns a term.
+4. **Byte parity with Rust**, produced at test time: the shell opens what
+   Rust sealed, Rust opens what the shell sealed, and the equality term is
+   byte-identical.
+5. **The whole six-step path through PostgreSQL**: insert into
+   `public.eql_v3_text_eq`, equality query through `eql_v3.query_text_eq`,
+   read back, decrypt. This is the "TextEq proven end-to-end in PostgreSQL"
+   that the catalog's storage-only `Text` domain records as its own blocker.
+
+Not done: CI (Task 8) and the scorecard (Task 9).
+
+## Findings about the engine and the catalog
+
+These are facts about `main` as of 2026-10-13, independent of any Python
+design choice.
+
+- **`stack-encrypt`'s `dynamic` feature is the entire binding surface, and
+  it is off by default.** `stack_encrypt::dynamic::record` — the data plan,
+  `FfiValue`, `plan_with`, `encrypt_with`, `decrypt_with`, `query` — does not
+  exist without it. `eql-bindings`' own `stack-encrypt` feature takes the
+  crate with `default-features = false` and does **not** enable it; the
+  binding crate must. `http` (credential discovery) is a default and should
+  be named explicitly so it cannot be dropped silently.
+- **The catalog produces exactly one EQL type: `TextEq`.** Every other entry
+  resolves `Unproducible`, with four recorded reasons: 42 types because
+  "how this family encodes a plaintext for the stack-encrypt producer
+  profile is not specified; only the text family's encoding is"; `TextMatch`
+  and the `Ope` types because "the engine derives match and OPE terms, but
+  no EQL type is built from them yet"; the ORE types because "EQL stores a
+  block ORE term and the engine derives a CLLW ORE term; the two are
+  different algorithms"; `Text` because it "follows once TextEq is proven
+  end-to-end in PostgreSQL". (Superseded: both are producible on `next`;
+  see open question 1.) **Consequence for the discovery ticket:** decision 9 lists
+  `equality`, `match`, `ore` as the engine features the four tasks need, and
+  backlog item 5 is "`match` and `ore` queries". Neither is a Python change;
+  both wait on the engine. Amend the ticket before anyone builds against it.
+- **The engine-side design for that gap already exists:** "Value encodings
+  for new EQL kinds" (7 Oct 2026, the same day as the discovery ticket's
+  decisions; an internal design draft, since landed on `next` as
+  `vitaminc-ore` and the new kinds, so the engine source is now the
+  reference). What it established at the time:
+  - The 42 non-text families are tracked in **#1130** and are "blocked on
+    encoding, not on code". A kind must exist in **three** encodings owned
+    by three crates — the ciphertext tag (`vitaminc-aead-value`), the
+    equality domain (`vitaminc-prf`), the order encoding (`cllw-ore` /
+    `ore-rs`) — and today they disagree about which types exist (`i16` is in
+    two of three, so it cannot be a kind).
+  - The ORE refusal is **#1132**: EQL v3 stores **block ORE** for the
+    `_ord_ore` domains and **CLLW OPE** for `_ord` / `_ord_ope`; Stack
+    Encrypt derives CLLW ORE and CLLW OPE and no block ORE. That is why
+    `TextOrdOre` is refused although text is a kind.
+  - The proposal: a `vitaminc-ore` crate with one order-preserving plaintext
+    encoding (adopting `orderable-bytes`) and pluggable schemes (block ORE,
+    CLLW ORE, CLLW OPE); new kinds `Int16`, `Date`, `Timestamp`, `Decimal`
+    with new frozen tags from `0x0C`; a conformance test that fails unless
+    every kind has all three encodings.
+  - It does **not** cover `TextMatch`, whose blocker is different ("the
+    engine derives match terms, but no EQL type is built from them yet").
+    So `match` is a smaller, separate, unticketed piece of work; `ore` is
+    this proposal.
+  - **It reaches Python directly.** The kind table is "a cross-language
+    commitment", and every new kind means a codec "in each binding": when
+    `Int16` / `Date` / `Timestamp` / `Decimal` land, the shell's
+    `convert.rs` grows an arm each, the width markers gain four names, and
+    `Date` versus `Timestamp` is the same declaration ambiguity it already
+    flags for Go's `time.Time`. The restart's declaration shape should
+    leave room for that rather than hard-code today's nine scalar kinds.
+- **The engine core does more than the catalog.** Through the bare-outputs
+  path (`"outputs": ["c", "match"]`) it seals any kind and derives `eq`,
+  `match`, `ore`, `ope`. What is `TextEq`-only is the *framing* into an EQL
+  v3 column type, which is `eql-bindings`' catalog, not the engine.
+- **`"type"` is required on every field with a term output** (#1096, now on
+  `main`), and `admits` decides which kinds an index accepts: `Equality`
+  takes the integer kinds, `string`, `bytes`; `Match` takes `string` only;
+  `Ore`/`Ope` take anything but arrays and objects. Kind names are
+  vitaminc's lowercase vocabulary (`string`, `int64`, `float64`, `bool`…),
+  parsed with `ValueKind: FromStr`; use that parser, never a table.
+- **A stored record is a `CipherText` tree, not bytes.** Per row a `Map`;
+  per field a `Map` keyed by output: a target field's EQL JSON rides as a
+  passthrough `FfiValue::Bytes` under `"eql"`, a passthrough field's value
+  as a passthrough `FfiValue` under `"passthrough"`, a ciphertext as a
+  sealed subtree under `"c"`. The first two extract directly to column
+  values; the third needs a tree codec (the Go host has one). The tracer
+  refused bare-`"c"` fields by name and lost nothing.
+- **Ciphertexts are never byte-equal** (fresh IV per seal). "The bytes
+  agree" can only mean the deterministic equality term; the ciphertext is
+  proven by cross-opening.
+- **The EQL identifier `i` is stamped from the plan's context** at encrypt
+  time — `{"t": "<first context piece>", "c": "<field name>"}` — and is
+  authenticated into the ciphertext. `.context("<table>")` and the SQL
+  table should be the same word. Postgres does not check it.
+- **Credentials:** `StackCipher::new()` → `AutoStrategy`: `CS_CLIENT_ACCESS_KEY`
+  + `CS_WORKSPACE_CRN` (`auto_strategy.rs:120`), else the device session in
+  `~/.cipherstash/<current_workspace>/auth.json` (`:129-133`); the client
+  key likewise from `CS_CLIENT_ID`/`CS_CLIENT_KEY` or `secretkey.json`. A
+  logged-in developer machine needs nothing set. **Any committed bytes
+  keyed to a workspace keyset (equality terms) pass only in that
+  workspace.** Produce the Rust side of a parity check at test time instead.
+- **`TextEq` needs nothing from Postgres that does not already exist**, which
+  is part of why it could ship first. Equality lives entirely in `hm`, the
+  HMAC; the ciphertext `c` is sealed with a fresh IV, so two stored values
+  for the same plaintext are *different* JSON and an index on the column
+  itself never matches. The index EQL v3 is built for is a functional one on
+  the extracted term —
+  `create index … using hash (eql_v3.eq_term(col))` (or `btree`:
+  the term's type rides on `bytea`'s default operator classes, so both work
+  and only `=` means anything) — and the bundle marks the extractor
+  `IMMUTABLE` and inlinable so the domain's `=` operator folds into the
+  query and the planner engages that index "structurally". The tracer
+  created **no** index on the encrypted column; its equality queries were
+  sequential scans. The ORE / OPE domains are the ones that need EQL's own
+  operator classes, because their terms do not sort as bytes.
+
+## Findings about Python and the toolchain
+
+- **pyo3 0.29, not 0.23**, for CPython 3.14. `abi3-py39` gives one wheel
+  per platform and builds against an interpreter newer than pyo3 knows.
+  Renames since the plan was written: `downcast` → `cast`, `allow_threads`
+  → `detach`, `PyObject` → `Py<PyAny>`.
+- **`extension-module` must be maturin-only** (`[tool.maturin].features`),
+  not in `Cargo.toml`. On by default it stops `cargo test` and `cargo build`
+  linking (`Undefined symbols … _Py*`); maturin supplies
+  `-undefined dynamic_lookup`. `cargo check` is the compile check,
+  `maturin develop` the link check.
+- **Anything that links pyo3 outside a wheel needs libpython on the loader
+  path** at run time (`DYLD_FALLBACK_LIBRARY_PATH` / `LD_LIBRARY_PATH` =
+  `sysconfig.get_config_var("LIBDIR")`), including `cargo test` and a
+  parity binary. CI must set it.
+- **`Pending` is `IntoFuture`, not `Future`.** A sync shell is one Tokio
+  runtime, `into_future()` *before* `py.detach`, then `block_on`. There is
+  no second engine entry for sync, which keeps G6 reachable when async
+  comes.
+- **Python's `int` has no width** and `34`/`34.0` derive different ORE
+  terms, so the annotation carries one (`Int64`, `Text`, …) and the shell
+  narrows exactly — stricter than `dynamic::read`, which converts lossless
+  widths and is right only for query literals. Check `bool` before `int`.
+  `None` encodes to `FfiValue::Null` and is refused by the declared kind.
+- **The width markers should be a type, not a bare string**, or an unrelated
+  `Annotated[str, "a note"]` reads as a declaration.
+- **psycopg plumbing** that touches no bytes: send a stored EQL value as
+  text with `::jsonb` in the SQL (`Jsonb(str)` wraps a JSON *string* and
+  fails the domain check); read it back as `email::text` and `.encode()`
+  (psycopg otherwise returns a `dict`). Postgres reorders keys; read by
+  name, never by position.
+- **Environment quirks on this machine:** cargo and pip need the sandbox
+  off (shared `~/.cargo` writes; the proxy's TLS breaks pip and `gh`);
+  the repo's node scripts need node ≥ 20.11 (`import.meta.dirname`) — the
+  shell's is 20.3.1, mise has 24.11.1; `ghcr.io/cipherstash/postgres-eql`
+  needs a fresh `docker login ghcr.io`; the asdf `psql` shim has no
+  version, so install EQL through the container's own `psql`.
+
+## Design decisions made along the way (provisional — reviewers decide)
+
+- Targets resolve by **(kind, index)**, not by EQL name: Python writes
+  `{"kind": "string", "index": "eq"}` and the engine answers `TextEq` plus
+  both SQL domains. No EQL name is written in Python. An explicit
+  `EQL(name=...)` escape hatch exists.
+- A **record is a dict of field name → column value** (EQL JSON as `bytes`,
+  passthrough as itself). It is what SQL wants, and no record ever needs a
+  serialised form.
+- The **SQLAlchemy layer should be a separate PyPI distribution**, pure
+  Python, depending on the core wheel — the user's call on 2026-10-13;
+  not yet on the ticket. Backlog item 2 covers the call site, not the
+  shipping unit, so this is unowned.
+- The live-test gate is "does the engine construct", not "are `CS_*` set".
+
+## Gaps against the discovery ticket's wording, found on re-reading
+
+Two places where what was built is narrower than what the ticket says, and
+the findings above would otherwise imply the ticket was met.
+
+- **"The engine checks the declaration when Python defines the class"
+  (week-1 step 2) — not quite.** The check runs at `build()`, one call
+  later, wherever the caller puts that call.
+  `Plan.of(User).context(…).build()` at module scope runs at import time
+  **by convention**, because the call sits at module scope; nothing fires
+  when the `class` statement finishes. A class decorator — `@stash.model("users")` above `@dataclass`
+  — would run `build()` at class definition **by construction**, hold the
+  `PlanSpec` on the class, and let the call site be `Cipher(User)`. It is a
+  second way in (G6), so it has to earn its place: it carries the context,
+  which is per-model and which `Annotated` cannot express, and it reaches
+  the moment the ticket names. The stronger form makes it *the* way and
+  retires `Plan.of` from the public surface. Costs: decorator order
+  (`@dataclass(slots=True)` returns a new class, so a plan set below it is
+  lost; a transforming base such as Pydantic's or SQLAlchemy's declarative
+  may rewrite the class after it was read), and committing to "the model
+  class owns its plan". A plain `@dataclass` below the decorator is
+  **fine** — a class's annotations exist before `@dataclass` runs, so an
+  earlier claim that the wrong order "sees no fields" was mistaken. Backlog
+  item 1.
+- **The model contract is not "a dataclass", and should not become one.**
+  psycopg imposes nothing — it sees tuples and parameters. The shell relies
+  on exactly three things: annotated fields readable through
+  `get_type_hints(cls, include_extras=True)`; attribute access (`getattr`)
+  on the way in; and a **keyword-argument constructor** matching the field
+  names on the way out (`model(**row)` in `decrypt`). Dataclasses meet that
+  with the least ceremony, which is the only reason the tracer used them.
+  So do `attrs`, Pydantic, `NamedTuple`, and SQLAlchemy declarative models
+  (default constructor takes kwargs) — the first user's actual classes.
+  Restricting to `@dataclass` would exclude them while enforcing more than
+  the code needs. State the contract explicitly (a `Protocol`), and let the
+  SQLAlchemy layer supply a base that meets it. `is_dataclass` is the cheap
+  guard for decorator order, not the right one.
+
+## Defects found in the plan (`2026-10-08-python-sdk-tracer.md`)
+
+All ruled on and ledgered; listed so the restart's plan does not repeat them:
+missing `dynamic`/`http` features; pyo3 0.23; `cargo build` as a check;
+`"Utf8Str"`-style kind names; `FfiValue::String(Vec<u8>)` (it is
+`Utf8String`); an invented `Value::kind_of`; a committed workspace-keyed
+fixture; "Python encrypted" wording (Python never encrypts — the check is
+the engine *through the shell* against the engine bare); the record as
+`list[bytes]`; `decrypt_with`'s fifth argument (`expected: Option<Label>`,
+`None` for a declared context).
+
+## Open questions for the restart
+
+1. Re-read the discovery ticket's decision 9 and backlog item 5 against
+   `next`, not against the catalog gap this document recorded on 13
+   October. On `next` 40 of the 51 EQL v4 types are producible
+   (`languages/golang/encrypt/eql/eql_gen.go` says which): `Text`,
+   `TextMatch`, `TextSearch` (#1274) and the block ORE `Ord` types (#1280)
+   among them, both merged on 2026-10-19. The 11 that are not are the
+   order terms for `date`, `timestamp` and `decimal`, whose ordering is
+   not decided, and the two JSON types (#1060). Amend the ticket from
+   that list, and name only the dependencies that remain.
+2. Which of those lands first, and does the week-1 restart wait for any of
+   them? (Nothing in the six-step path needs them; `TextEq` is enough to
+   prove the path, which it did.)
+3. Width markers in annotations: `Annotated[int, Int64, ...]` works; is it
+   acceptable to Python developers? (Backlog item 1's user test.)
+4. Should `targets.rs` be pyo3-free, so a parity binary does not link the
+   interpreter? Relevant to the FFI comparison (backlog item 3).
+5. Packaging of the SQLAlchemy layer (above) — put it on the ticket.
+6. Declaration entry point: keep `Plan.of(cls).context(…).build()`, add a
+   class decorator beside it, or make the decorator the one way? This
+   decides whether "checked when the class is defined" holds by
+   construction.
+7. The model contract: write it down as a `Protocol` (annotated fields,
+   attribute access, kwargs constructor), and check SQLAlchemy declarative
+   models against it before the layer is designed.
+8. Indexing guidance for the SDK docs: the functional hash index on the
+   extracted term is the one a `TextEq` column wants; on the v4 bundle the
+   restart installs that is `eql_v4.eq_term(col)` on a
+   `public.eql_v4_text_eq` column (`eql_v3.eq_term` on v3; there is no
+   `_internal` extractor). The tracer never created one, and a user
+   copying its SQL would not either.
+
+## Where the record is
+
+- The prototype branch: `prototype/python-sdk-tracer` — commits
+  `6c3bc191f..` (Tasks 1–7), each message self-contained. This document
+  and the ledger land on `next`; the files below exist only on that
+  branch.
+- The plan: `docs/plans/2026-10-08-python-sdk-tracer.md` on the prototype
+  branch (revised in place there).
+- The ledger: `docs/plans/2026-10-13-python-sdk-tracer-ledger.md` — every
+  ruling with its cost, copied from the gitignored SDD workspace.
+- How to run it: `languages/python/README.md` on the prototype branch.
diff --git a/docs/plans/2026-10-13-python-sdk-tracer-ledger.md b/docs/plans/2026-10-13-python-sdk-tracer-ledger.md
new file mode 100644
index 000000000..ed5d71a94
--- /dev/null
+++ b/docs/plans/2026-10-13-python-sdk-tracer-ledger.md
@@ -0,0 +1,398 @@
+# SDD ledger — plan: docs/plans/2026-10-08-python-sdk-tracer.md
+
+Spec: the Python SDK discovery ticket (read in full, 2026-10-08).
+Execution: native (inline), per the user's choice at the plan handoff.
+Worktree: `.claude/worktrees/python-sdk-tracer`, branch `worktree-python-sdk-tracer`,
+cut from `origin/main` @ 6f388478c.
+
+Setup: Ruling: base branch `feat/stack-encrypt-required-type` → `origin/main` —
+PRs #1095 and #1096 were squash-merged into main (no ancestry, so
+`merge-base --is-ancestor` says no; the content check says yes). Verified on
+`origin/main`: `FieldPlan.target: Option<String>`, the grammar line
+`{ "context": …, "target": "<EQL type name>", "type": … }`, `"type"` **required
+on every field with a term output**, plus both templates Task 4 needs
+(`languages/golang/encrypt/guest/src/targets.rs`,
+`packages/eql/crates/eql-bindings/src/encryption/targets.rs`) — cost if wrong:
+the branch is cut from the wrong base and every task rebases once.
+
+## Pre-flight scan
+
+| Tasks | Produces → consumes | Finding |
+|---|---|---|
+| 1 → 2 | `stackencrypt._engine` (module with `version()`) → same | clean |
+| 2 → 3 | `_markers`, `errors` → same | clean |
+| 2 → 4 | `convert`, `errors` (Rust) → same | clean |
+| 3 → 4 | `PlanSpec(model, context, fields)` → Task 4 adds `domains` and rewrites `fields[name]["target"]` from the pair form to the resolved name | **CONFLICT, known.** Task 3's `test_a_target_field_carries_context_and_type_but_no_outputs` asserts the pair form `{"index": "eq", "kind": "Utf8Str"}`; Task 4 Step 5 replaces it with `"TextEq"`. Ruling below. |
+| 4 → 5 | `targets::Resolver`, `_engine.check_plan` → same | clean |
+| 4 → 7 | `PlanSpec.domains[field]["sql_domain"]`, `["query_sql_domain"]` → same | clean |
+| 5 → 6 | `Cipher.encrypt/.decrypt/.query` → same | clean |
+| 5 → 7 | same | clean |
+| 1-7 → 8 | the suite and the crate → CI invokes them | clean |
+
+Setup: Ruling: the Task 3 / Task 4 `PlanSpec` conflict stands as the plan
+wrote it — Task 3 asserts the pair form because that is what `_declare.py`
+produces at that point, and Task 4 substitutes the resolved name because
+that is what the wire grammar takes. Both assertions are correct at their own
+task. Task 4 Step 5 carries the replacement text. — cost if wrong: one
+assertion edited twice.
+
+Setup: Ruling: `convert.rs`'s "no declared kind defaults to Int64" branch is
+described in the plan as transitional behaviour of the data plan's optional
+`"type"`. On `origin/main` `"type"` is **required** on any field with a term
+output, so that branch is now reachable only for a passthrough or
+ciphertext-only field. Keep the branch (those fields are real) and correct the
+comment when Task 2 writes it. — cost if wrong: a stale comment.
+
+Baseline: `cargo build -p stack-encrypt` (the dependency Task 1 adds) and
+`cargo metadata --locked` on the root workspace. The repo-wide suite is not the
+baseline: nothing in this plan touches the JS packages, EQL or the Go module,
+and running their suites would prove nothing about the first failure that
+matters here.
+
+Baseline: `cargo metadata --locked` OK; `cargo build -p stack-encrypt` OK
+(45.69s, exit 0). Log at `baseline.log`.
+
+Setup: Ruling: every cargo command in this run needs
+`dangerouslyDisableSandbox` — the sandbox denies writes to
+`~/.cargo/registry`, so cargo cannot cache an index read or a crate
+download, and `cargo metadata --locked` fails before it reaches the
+lockfile. Sandboxed cargo is not recoverable by allowlisting a host; the
+denial is a filesystem write to the shared cargo home. — cost if wrong: cargo
+runs outside the sandbox, with the write access a normal local build has.
+Task 1: complete (commits 6f38847..3f5a853, tests: ./languages/python/.venv/bin/python -m pytest languages/python/tests -v → ============================== 1 passed in 0.01s ===============================)
+
+Task 1: Ruling: `stack-encrypt` dependency gains `features = ["dynamic",
+"http"]` — the plan named neither. `dynamic` is NOT a default and gates the
+entire `stack_encrypt::dynamic` module, which is every call site this shell
+has; `eql-bindings`' own `stack-encrypt` feature takes the crate with
+`default-features = false` and does not enable it, so this crate's line is
+what turns it on for the graph. `http` is a default, named explicitly because
+Task 5 needs `StackCipher::new()`'s credential discovery and a later
+`default-features = false` would remove it silently. — cost if wrong: nothing
+compiles, loudly, at the first `use`.
+
+Task 1: Ruling: pyo3 `0.23` → `0.29` — 0.23 predates CPython 3.14, which is
+the local interpreter (3.14.2, via mise). `cargo search pyo3` gives 0.29.3 as
+current. abi3 would carry a build against an unknown-newer CPython anyway,
+but there is no reason to start six years behind. — cost if wrong: a pyo3 API
+difference in a later task; 0.29 keeps the `Bound<'_, PyModule>` shape the
+plan's code already uses.
+
+Task 1: Ruling: Step 11's `cargo build` → `cargo check && cargo fmt --check
+&& cargo clippy --all-targets`. `pyo3`'s `extension-module` deliberately does
+not link libpython, so `cargo build` fails with ~40 `Undefined symbols …
+"_PyBytes_AsString"` lines on a correct crate. maturin passes `-undefined
+dynamic_lookup`, so `maturin develop` in Step 8 is the link check. Plan
+updated in place with the reason. — cost if wrong: none; the link is still
+proven, by the step that can prove it.
+
+Task 1: Ruling: two `.gitignore` additions the plan did not name — `.venv/`
+and friends (maturin needs a virtualenv to install into, and the repo had no
+Python ignores at all), and
+`languages/python/python/stackencrypt/_engine*.so`, because `maturin
+develop` installs editable by writing the built library into the package
+SOURCE directory. The second was caught by reading `git status` after
+staging: the `.so` was staged. — cost if wrong: a build artefact in git
+history.
+
+Task 1: Note (environment, not a ruling): cargo needs
+`dangerouslyDisableSandbox` (see Setup), pip needs it too (the proxy's TLS
+interception fails CPython's cert verification with `OSStatus -26276`, the
+same error `gh` gives), and the repo's node scripts need node >= 20.11 for
+`import.meta.dirname` — the shell's `node` and `mise x -- node` are both
+20.3.1, so `lint-no-eql-registry-pins.mjs` was run with
+`$(mise where node)/bin/node` (node 24.11.1) and passes
+with the new `eql-bindings` path dependency.
+
+Task 2: Ruling: the plan's kind names are wrong — `"Utf8Str"` → `"string"`,
+`"Int64"` → `"int64"`, and so on. `dynamic::record`'s parser reads `"type"`
+with `ValueKind: FromStr` over `ValueKind::name`'s LOWERCASE vocabulary
+(`bool int32 int64 uint32 uint64 float32 float64 string bytes array
+object`). `convert::kind` uses that same `parse()` rather than a table of its
+own, so the shell cannot disagree with the engine about a name. Every test
+and marker updated. — cost if wrong: every declaration is refused with
+`Reason::UnknownType`, loudly.
+
+Task 2: Ruling: the plan's `FfiValue` shapes are wrong —
+`FfiValue::String` carries `Utf8String` (not `Vec<u8>`), which validates
+UTF-8 at construction and holds the bytes in `Protected`; `FfiValue::Bytes`
+carries `Protected<Vec<u8>>`. Both use `From`, and reading back needs
+`risky_ref` from the `Controlled` trait, so `vitaminc-protected = "0.5.1"` is
+a new dependency the plan did not name. `FfiValue` also has `Null`,
+`Undefined`, `UInt32`, `UInt64` and `Float32`, all now handled. — cost if
+wrong: none; the compiler named each one.
+
+Task 2: Ruling: the plan's invented `Value::kind_of` does not exist. The real
+check is `ValueKind::holds(&FfiValue) -> bool`, vitaminc's own, and
+`FfiValue::kind() -> Option<ValueKind>` for a message. Using the engine's
+predicate is the point — a shell that decided for itself what a kind accepts
+would be a second rule. — cost if wrong: none.
+
+Task 2: Ruling: the conversion is EXACT, and deliberately stricter than
+`stack_encrypt::dynamic::read`. That function converts a number of another
+width when the conversion is lossless, which is right for a QUERY value a
+caller wrote as a literal. It is wrong for a stored field: `34` and `34.0`
+derive different ORE terms, so accepting a float for a declared integer field
+stores terms a later query cannot match. `float32` is refused rather than
+narrowed for the same reason. — cost if wrong: a caller who passes `34.0` to
+an `int64` field gets an error instead of a silent conversion; the remedy is
+to pass `34`.
+
+Task 2: Ruling: `PyObject` is not in pyo3 0.29's prelude; the type is
+`Py<PyAny>`. — cost if wrong: none.
+
+Task 2: Ruling: the width markers are a frozen `Kind` dataclass, not bare
+strings as the plan wrote them. A bare `"int64"` in an `Annotated` is
+indistinguishable from an unrelated `Annotated[str, "a note"]`, and
+`_declare.py` would read the note as a declaration. `Kind("int64")` cannot be
+confused with anything. — cost if wrong: one more name in the public
+surface; backlog item 1 revisits the declaration shape anyway.
+
+Task 2: Ruling: Python `None` encodes to `FfiValue::Null` and is then refused
+by the declared kind, rather than being rejected as "no encoding". That keeps
+the message accurate (`field declares string, got a value of kind null`) and
+leaves `Null` available for a future nullable field, which the spec does not
+ask for. Review Focus 4, covered by
+`test_none_against_a_declared_kind_is_refused`. — cost if wrong: a nullable
+field would need the kind check relaxed, which is a deliberate change rather
+than a surprise.
+Task 2: complete (commits 3f5a853..023ebe5, tests: ./languages/python/.venv/bin/python -m pytest languages/python/tests -q → 15 passed in 0.01s)
+
+Task 3: Ruling: `_declare.fields` matches a width with `isinstance(e, Kind)`
+rather than the plan's `e in _WIDTH_NAMES` string set — the Task 2 ruling
+made the width markers a `Kind` dataclass. Covered by
+`test_an_unrelated_annotation_is_not_read_as_a_declaration`, which would
+have declared the kind "a note for the reader" under the string form. — cost
+if wrong: none.
+
+Task 3: Ruling: `"type"` is written for a TARGET field too, though the engine
+takes it from the EQL type when absent. The module docs say a declared type
+"must be the kind the EQL type is produced from", so writing it buys a free
+agreement check between the annotation and the EQL catalog. — cost if wrong:
+a declaration whose width disagrees with its EQL type is refused at plan
+parse instead of silently taking the catalog's kind, which is the better
+failure.
+
+Task 3: Ruling: `PlanSpec.domains` is added NOW, defaulting to `{}`, rather
+than in Task 4 as the plan wrote it. The pre-flight scan called the Task 3 /
+Task 4 `PlanSpec` change a known conflict; giving the field a default here
+means Task 4 fills it instead of changing the dataclass, so no Task 3
+assertion moves and the frozen dataclass has one shape across the branch. The
+Task 3 tests still assert the PAIR form of `"target"`, which is what
+`_declare.py` produces; Task 4's substitution is what turns it into a name.
+— cost if wrong: one unused field for one commit.
+Task 3: complete (commits 023ebe5..f8f3036, tests: ./languages/python/.venv/bin/python -m pytest languages/python/tests -q → 26 passed in 0.02s)
+
+Task 4: Ruling: `describe` and `convert` were copied verbatim from
+`languages/golang/encrypt/guest/src/targets.rs`, as the plan's Step 3 said
+to, and the two `todo_*` placeholders are gone. The real types are
+`eql_bindings::encryption::targets::{Target, TargetError}` (not `Entry` /
+`Error` as the plan guessed), and `plaintext_kind()` is a method. — cost if
+wrong: none; these are the one mapping between eql-bindings' catalog and the
+engine's, and a second spelling would be a second rule.
+
+Task 4: FINDING from the Go guest's own test, now pinned here too: **the
+engine produces exactly one EQL type today, `TextEq`.** Every other catalog
+entry resolves `Unproducible`. So `match` and `ore` through an EQL target are
+blocked by the CATALOG, not only by week-1 scope — backlog item 5 depends on
+the engine producing those types, which is work outside this plan. The
+scorecard must say so. `select` lists what is producible in its refusal, so
+the message is actionable rather than "no such type".
+
+Task 4: Ruling: `extension-module` moved OUT of `Cargo.toml`'s pyo3 features
+and is supplied only by `[tool.maturin].features` in `pyproject.toml`. With
+it on by default `cargo test` cannot link (a test binary is its own
+executable and must link libpython, which the feature forbids). This is
+pyo3's documented arrangement. The wheel still gets the feature; the Rust
+tests now run. — cost if wrong: a `cargo build` of the lib now links
+libpython, which is fine and is what every non-wheel build wants.
+
+Task 4: Note (environment): `cargo test` here needs
+`DYLD_FALLBACK_LIBRARY_PATH` pointing at the interpreter's `LIBDIR`
+(`$(mise where python)/lib`, Python 3.14.2), because the
+test binary links libpython by rpath and mise's install is not on the
+default search path. Linux CI uses `LD_LIBRARY_PATH`. Task 8 must set it in
+the workflow or the Rust tests fail at load with
+`Library not loaded: @rpath/libpython3.14.dylib`.
+
+Task 4: Ruling: pyo3 0.29 renamed `Bound::downcast` to `Bound::cast`. — cost
+if wrong: none.
+
+Task 4: Ruling: the Task 3 conflict resolved differently from the pre-flight
+ruling. I had said Task 3's pair-form assertion "stands"; it does not —
+`build()` substitutes the resolved name, so the pair is never visible from
+`PlanSpec.fields`. Rather than flip the assertion, the pair is now asserted
+against `_declare.fields()` directly
+(`test_the_declaration_writes_a_target_request_not_an_eql_name`) and the name
+against `build()` (`test_the_resolved_name_replaces_the_pair_in_the_wire_plan`).
+Both facts stay covered, each at the layer that owns it — and the first is
+the test that would catch an EQL type name creeping into Python. — cost if
+wrong: none; strictly more coverage than either single assertion.
+Task 4: complete (commits f8f3036d4a..d45f2f3, tests: ./languages/python/.venv/bin/python -m pytest languages/python/tests -q → 37 passed in 0.04s)
+
+Rebase (2026-10-13): the branch was rebased by the user onto `main` @
+576b8986e (#1175, Go release pipeline). Tasks 1-4 are now
+6c3bc191f..bc785b2e6. One conflict, AGENTS.md's `languages/golang` entry —
+main rewrote its last sentence and Task 1 had inserted `languages/python`
+after that sentence; resolved by keeping both. Checked after: zero diff in
+`packages/stack-encrypt`, `packages/eql/crates/eql-bindings` and
+`languages/golang/encrypt/guest` between the bases, so the catalog is still
+`TextEq`-only with the same four reasons; wheel rebuilds; 37/37 pass. Task 5's
+untracked files survived. Task-done BASE for Task 5 is now bc785b2e6.
+
+Task 5: Ruling: `encrypt` returns a list of DICTS (field name → column value),
+not the plan's `list[bytes]`. The engine's result is a `CipherText` tree with
+no byte form this shell knows, and SQL wants per-column values anyway: a
+target field's EQL JSON as `bytes`, a passthrough's value as itself. `decrypt`
+takes the same dicts and rebuilds the tree (`record_tree`, the inverse of
+`stored_row`). So no record ever needs a serialised form, and Task 7 inserts
+the dict's values directly. — cost if wrong: a caller who wanted one opaque
+blob per row has to join the dict; none does.
+
+Task 5: Ruling: a field with a bare `"c"` output (encrypted, not an EQL
+target) is REFUSED by `stored_row` / `record_tree` with the field named. Its
+node is a sealed subtree the shell cannot turn into a column value without a
+tree codec, which the Go host has and this tracer does not need — its path is
+EQL targets and passthroughs only. Refusing keeps that a decision rather
+than a silent drop. — cost if wrong: a bare-ciphertext column needs the
+codec added, which is a deliberate change.
+
+Task 5: Ruling: the live gate is "does `_engine.Engine()` construct", not
+"are `CS_*` set". No `CS_*` is set here, but `~/.cipherstash` holds a
+`stash auth login` profile and the engine's `AutoStrategy` found it — the
+live tests RAN, which the plan's env-var check would have skipped. The
+`live` fixture returns the handle and `Cipher(plan, engine=live)` reuses it
+across modules. — cost if wrong: a session with no credentials skips with
+the engine's own reason in the message, which is better than guessing.
+
+Task 5: Ruling: `plan::target` is idempotent — a bare string is an
+already-resolved EQL name and goes back through `targets::named`. `build()`
+stores the NAME in `PlanSpec.fields`, and every engine call re-parses those
+fields; the first live run failed all eight calls on exactly this. Re-
+resolving rather than trusting means a name that stopped being producible
+between `build()` and the call is refused at the call. — cost if wrong: one
+catalog lookup per call, no I/O.
+
+Task 5: Ruling: `runtime::block_on` is bounded on `IntoFuture`, not
+`Future` — the engine's `Pending` is a value that becomes a future when
+awaited, so the chain can be built and zipped first. Converted before
+`py.detach` so only the future, not `F`, must be `Send`. — cost if wrong:
+none; the compiler named both.
+
+Task 5: Ruling: `decrypt_with`'s `expected: Option<Label>` is `None`. It
+guards a plan whose context comes from a field of the record
+(`context_field` → `ContextMismatch`); this plan declares its context. —
+cost if wrong: a context-field plan would skip that check; none exists here.
+
+Task 5: Ruling: `from_ffi` maps `Object` → dict and `Array` → list,
+recursively; the plan's version refused every container. An opened row IS an
+`Object`. — cost if wrong: none.
+
+Task 5: Ruling: `stack-auth = { path = "../../packages/stack-auth" }` added,
+only to NAME `StackCipher<StackKms<stack_auth::AutoStrategy>>` in the
+pyclass; stack-encrypt does not re-export `AutoStrategy`. — cost if wrong:
+one more path dependency the lockfile already carried transitively.
+Task 5: complete (commits bc785b2..8085642, tests: ./languages/python/.venv/bin/python -m pytest languages/python/tests -q → 46 passed in 4.54s)
+
+Task 6: Ruling (plan revised, with the user, 2026-10-13): NO committed
+fixture. The plan's `tests/fixtures/record.json` carried an equality term
+that is an HMAC under the workspace keyset, so the committed bytes would pass
+only in the workspace that generated them — the author's `<workspace-id>`
+here, not CI's. The Rust side is now produced AT TEST TIME by a `parity`
+bin (`seal` / `open`) under the same credentials as the Python side, so the
+comparison holds in any workspace and nothing keyed to a keyset is
+committed. The "do not commit your workspace's value" caveat is gone with
+it. — cost if wrong: the parity test needs `cargo` and credentials at test
+time; it needed credentials anyway, and the suite already needs a Rust
+toolchain to build the wheel.
+
+Task 6: Ruling (wording, from the user's correction): the check is NOT
+"Python encrypted" vs "Rust encrypted" — Python never encrypts (G1). It is
+the engine invoked THROUGH THE SHELL against the engine with nothing in
+front of it, so the one thing it can catch is the shell drifting from the
+engine's grammar. Docstrings and the plan say so. — cost if wrong: none; a
+wrong description of a right test.
+
+Task 6: Ruling: the record-tree walk moved out of `engine.rs` into
+`src/tree.rs`, pure `FfiValue` in/out, and the bin includes it by `#[path]`
+along with `targets.rs`. One walk and one resolver serve both sides; a copy
+in each is exactly the disagreement the parity test exists to catch. The
+bin's `#[allow(dead_code)]` on `mod targets` covers `select`/`named`, which
+only the lib's plan resolution calls. — cost if wrong: `#[path]` is a
+compile-time include, so a change to either file is a change to both,
+which is the point.
+
+Task 6: Note (environment): the bin links pyo3 through `targets.rs`, so like
+`cargo test` it needs libpython on the loader path at run time. The test's
+`subprocess` sets `DYLD_FALLBACK_LIBRARY_PATH` and `LD_LIBRARY_PATH` from
+`sysconfig.get_config_var("LIBDIR")`, so it works under any interpreter
+without a hand-set variable. Task 8's workflow needs the same for `cargo
+test`. Making `targets.rs` pyo3-free would remove the need; left for the
+FFI-comparison backlog item, since it is the kind of seam that decision
+cares about.
+
+Task 6: Finding: ciphertexts are never byte-equal (a fresh IV per seal), so
+"the bytes agree" can only mean the deterministic TERM bit-for-bit; the
+ciphertext is proven by cross-opening. The test says so in its docstring.
+Task 6: complete (commits 8085642..a06d448, tests: ./languages/python/.venv/bin/python -m pytest languages/python/tests -q → 50 passed, 3 skipped in 11.53s)
+
+Task 7 (in progress, 2026-10-13): `tests/test_postgres.py` written; it
+collects and SKIPS (3) without `DATABASE_URL`, which is its RED until a
+database exists. Database: `local/docker-compose.postgres.yml` (the file
+CI's `integration-db` composes for its `postgres` variant), port 55432. The
+pull of `ghcr.io/cipherstash/postgres-eql:17-2.3.1` was DENIED — the daemon
+has a stale/underscoped `ghcr.io` login — and that is the user's credential,
+so it is a stop. EQL v3 will be applied from the in-tree bundle
+`packages/eql/packages/eql/sql/cipherstash-encrypt.sql` (3.0.6) through
+psycopg rather than the `stash` CLI, which is not built here; the image
+bakes in EQL v2 only, so the install is needed either way.
+
+Task 7: Ruling: a stored EQL value crosses to psycopg as `Jsonb(bytes.decode())`,
+not raw bytes. psycopg sends `bytes` as `bytea`, which no EQL domain
+accepts; the domains are declared over `jsonb`. `Jsonb` is an adapter, not
+an encoding — the bytes are neither inspected nor reshaped, and the domain
+cast in the SQL is what the column applies. — cost if wrong: none for G1;
+if a future driver accepts the bytes natively the helper goes away.
+
+Task 7: Ruling (CORRECTS the Jsonb ruling above): a stored EQL value crosses
+to psycopg as TEXT with a `::jsonb` cast in the SQL, not as `Jsonb(text)`.
+`Jsonb(str)` wraps a Python STRING as the JSON value, so Postgres receives a
+JSON string literal, `jsonb_typeof` is `'string'`, and
+`eql_v3_text_eq_check` fails — which is how the first live run failed, all
+three tests, on a correct engine output. Verified before changing anything:
+the engine's JSON is `{v: 3, i: {t, c}, c, hm}` and the domain's check is
+exactly `object ∧ has v,i,c,hm ∧ v = '3'`. `json.loads` + `Jsonb(dict)` would
+also pass but re-serialises in Python; `text::jsonb` lets Postgres parse the
+bytes untouched (G1). — cost if wrong: none; the cast is standard SQL.
+
+Task 7: Ruling: the column is read back as `email::text` and `.encode()`d,
+because psycopg loads a `jsonb` column into a Python dict and the shell
+takes a stored EQL value as bytes. Postgres serialises the canonical jsonb
+text; `.encode()` is the one Python step and reshapes nothing. — cost if
+wrong: the canonical text is Postgres's key order, not the engine's; the
+EQL type's opener reads keys by name, so order is immaterial (proven: the
+read-back record decrypts).
+
+Task 7: FINDING for the scorecard and the catalog: `TextEq` is now proven
+end to end in PostgreSQL from Python — insert into `public.eql_v3_text_eq`,
+equality query through `eql_v3.query_text_eq`, read back, open. That is the
+proof the storage-only `Text` domain's `reason` says it is waiting on.
+
+Task 7: Note (environment): the database was `local/docker-compose.postgres.yml`
+(CI's `postgres` variant), image `postgres-eql:17-2.3.1` which bakes EQL v2
+only; EQL v3 (3.0.6) was applied from the in-tree bundle
+`packages/eql/packages/eql/sql/cipherstash-encrypt.sql` via
+`docker exec -i … psql -v ON_ERROR_STOP=1`, because the `stash` CLI is not
+built here and the asdf `psql` shim has no version. The GHCR pull needed the
+user to re-login (`docker login ghcr.io`); the stored token was stale.
+Task 7: complete (commits a06d448..01e09e8, tests: ./languages/python/.venv/bin/python -m pytest languages/python/tests -q → 53 passed in 19.37s)
+
+STOPPED BY DECISION (2026-10-13), after Task 7 of 9. The user is treating
+this attempt as a proto-prototype and restarting from `main` in a fresh
+session: knowledge gained along the way, and a model they did not mean to
+use. Tasks 8 (CI) and 9 (scorecard) were not started. The branch is kept
+as `prototype/python-sdk-tracer`, not merged. The distilled handoff is
+`docs/plans/2026-10-13-python-sdk-tracer-findings.md`; this ledger is
+copied beside it as `…-ledger.md`. No final review was run — there is
+nothing to merge — so the final-review section of this ledger is
+deliberately absent.
diff --git a/languages/python/docs/adr/0001-a-declaration-is-checked-when-the-class-is-defined.md b/languages/python/docs/adr/0001-a-declaration-is-checked-when-the-class-is-defined.md
new file mode 100644
index 000000000..2a5cd0058
--- /dev/null
+++ b/languages/python/docs/adr/0001-a-declaration-is-checked-when-the-class-is-defined.md
@@ -0,0 +1,413 @@
+---
+status: proposed
+date: 2026-10-16
+extends: ADR-0007, ADR-0008 (packages/stack-encrypt/docs/adr)
+ticket: the Python SDK discovery ticket, backlog item 1 (its 15 October 2026 amendment)
+---
+
+# A declaration is checked when Python defines the class, by construction
+
+The Python SDK declares a model with one class decorator.
+The decorator carries the context, reads the `Annotated` hints, asks the
+engine to check the plan, and stores the result on the class.
+The check runs as the `class` statement finishes, every time, wherever the
+class is defined.
+The call site takes the class: `Cipher(User)`.
+No public name is a plan or returns one.
+
+This is the trade-off memo for backlog item 1's first question, written as
+the ADR the gate will accept or amend.
+The reviewers decide (the ticket, decision 7).
+
+## The problem
+
+The Python SDK discovery ticket says the engine checks a declaration "when Python defines the
+class" (week-1 step 2) and "at import" (decisions 6 and 20).
+The first tracer checked at `build()`:
+
+```python
+plan = Cipher(Plan.of(User).context("users").build())
+```
+
+That is import time only when the statement sits at module level.
+Put it in a function, a fixture or a lazy factory and a forgotten field is
+found at the first write, which can be in production.
+Nothing fires when the `class` statement finishes.
+So the ticket's sentence held by convention, and the amendment asks which
+it must be: by construction or by convention.
+
+The same amendment asks for the model contract.
+The tracer used `@dataclass`, which is one way to meet the contract and
+not the contract itself.
+
+## Options considered
+
+### 1. By convention: a plan statement beside the class
+
+`Plan.of(User).context("users").build()` as the tracer wrote it.
+
+- The check runs where the statement runs.
+  The ticket's sentence is a description, not a guarantee.
+- The user holds a plan object and hands it to `Cipher`.
+  Go principle 7 ("the user never sees the plan") is Go-only, but its
+  reason is not: a plan is engine vocabulary the user cannot act on
+  (principle order, rule 3).
+- The context is a method call, apart from the class it describes.
+- No ordering question with other decorators.
+
+### 2. By construction: a class decorator (recommended)
+
+```python
+import stackencrypt as stash
+
+@stash.model("users")
+@dataclass
+class User:
+    email: Annotated[str, stash.TextEq]
+    age: Annotated[int, stash.Passthrough]
+    nickname: str          # DeclarationError here, at the class statement
+
+cipher = stash.Cipher(User)
+```
+
+- The check runs as the class is defined, always.
+  A class defined inside a function is checked when that function runs,
+  which is still "when Python defines the class".
+- The context sits on the class.
+  One class, one context, which is how SQLAlchemy and Django already think
+  (one class, one table).
+  The engine stamps the EQL identifier `i.t` from the first context piece,
+  so that piece and the table name should be the same word.
+- A class the user does not own is declared by the same callable:
+  `stash.model("users")(ThirdPartyModel)`.
+  A decorator is a function; applying it after the fact is the same way in,
+  through the same code, so principle G6 holds with one way.
+  The reader `Plan.of` leaves the public surface.
+- The decorator must be outermost.
+  See "Decorator order" below for what happens when it is not.
+
+### 3. By construction: a base class or metaclass
+
+`class User(stash.Model)` with `__init_subclass__` running the check.
+
+- Also runs at class definition.
+- Rejected: the first user's classes already have a base
+  (`DeclarativeBase`, `pydantic.BaseModel`), and `NamedTuple` takes none.
+  Two metaclasses do not combine.
+  Python's current idiom for "this class is one of these" is the decorator
+  (`dataclass`, `attrs.define`, `registry.mapped`), not the base class.
+
+### 4. Both the decorator and `Plan.of`
+
+Rejected by principle G6, test 1: the only need named for `Plan.of`, a
+class the user does not own, is met by calling the decorator as a function.
+
+## Decision
+
+Option 2.
+
+1. **The check at class definition is a requirement, not a description.**
+   Principle G3 says run each check at the earliest stage the language
+   allows.
+   For a declaration, the earliest moment it exists is the end of the
+   `class` statement.
+   A decorator, a metaclass and `__init_subclass__` all reach that moment.
+   The decorator is the one that also works with the bases the first
+   user's classes already have (option 3).
+2. **One decorator, and it carries the context.**
+   `@stash.model("users")`, with one required argument: the table.
+   Its one option, `redact=False`, is decision 9's and changes no label.
+   The engine's target context is exactly a table and a column, and the
+   column is the field's name, so the class needs nothing more.
+   That name is an input to the key ZeroKMS derives and to the
+   authentication tag, so it is permanent once a row is written: a rename
+   in Python changes both, and no stored row opens.
+   A rename is a migration, and the first version has none.
+   A field that names its column part itself, so the attribute can move
+   while the label stays, is deferred with the Go SDK's #1308, so both
+   SDKs get one answer, including what `i.c` then holds.
+   Where the library shows a column name that differs from the attribute,
+   SQLAlchemy's `mapped_column("email_addr")`, the decorator refuses at the
+   class statement, since `i.c` would not match the SQL column.
+   A Pydantic alias is a JSON name, not a column, and is left alone.
+   The name is open to the reviewers; the alternatives are
+   `@stash.encrypted(...)` and `@stash.declare(...)`.
+   The argument is documented once as the engine's `context`.
+   A record that names its own tenant (the engine's `context_field`) is
+   a record-level setting in the plan grammar, so if the SDK supports it,
+   it is a second decorator argument and not a field marker.
+   The first version has no per-caller tenant, by either route.
+   On `next` the engine refuses both for a field that names an EQL type,
+   because the field's label becomes the EQL value's `i` and must be
+   exactly a table and a column: an extended cipher is refused with
+   `TargetError::Extended`, and a plan with `context_field` with
+   `TargetError::ContextField` (`packages/stack-encrypt/src/dynamic/record.rs`).
+   Every sealed marker in this ADR names an EQL type, so the refusal
+   covers every sealed field.
+   The route that fits an EQL field is the ZeroKMS lock context, bound
+   into the key and not into the label, which stack-encrypt does not send
+   yet (#1067).
+3. **The decorator does five things and nothing else.**
+   It reads the field list, builds the field map, asks the engine to check
+   the plan, stores the result on the class under one dunder attribute,
+   and writes the print methods of decision 9.
+   It stores it in the class's own `__dict__`, so a subclass does not
+   inherit it: a subclass is decorated itself, and its decorator checks
+   every field the subclass has, inherited or added, since
+   `get_type_hints` returns both.
+   It makes no network request and needs no credentials.
+
+   Two checks run, and they are not the same check:
+   - **Python's**: every field carries a marker (rule A), and the decorator
+     is outermost (the constructor check in decision 5).
+   - **The engine's**: the plan grammar, which indexes the declared kind
+     admits (`dynamic::admits`), and whether a named EQL type is one the
+     build can produce.
+     The call is `dynamic::record::plan_with` with the target resolver,
+     the same call the Go generator makes through `se_plan_check`.
+4. **The call site takes the class.** `Cipher(User)`.
+   `Cipher` refuses a class the decorator has not seen, with the remedy in
+   the message.
+   It looks for the decorator's attribute in `cls.__dict__`, not through
+   `getattr`, so an undecorated subclass of a decorated class is refused
+   with the same message.
+   No public name is called a plan or returns one.
+
+   `DeclarationError` and that refusal are built from structured facts:
+   the field name and the engine's `Reason`, as the language-integration
+   guide (`packages/stack-encrypt/docs/language-integration.md`, PR #1287,
+   open on `next` as this ADR is written) gives them, never by parsing
+   the engine's message text.
+   No message carries a value.
+   A dataclass default is a value, so a message names the field and not
+   its default.
+5. **The model contract is a `Protocol`, not a dataclass.**
+   A model class must give:
+   - a field list, each field carrying its stash markers in `Annotated`;
+   - a constructor that accepts every declared field as a keyword argument;
+   - attribute access by field name on an instance.
+
+   The field list is the library's own where one exists:
+   `dataclasses.fields`, `attrs.fields`, Pydantic's `model_fields`, and
+   SQLAlchemy's mapper columns.
+   Those lists exist because the decorator is outermost, and they leave
+   out what is not a column: `ClassVar`, `InitVar`, Pydantic's
+   `model_config`, and a SQLAlchemy relationship.
+   For a class with no such list, the fields are the hints that
+   `typing.get_type_hints(cls, include_extras=True)` returns, minus
+   `ClassVar` and `InitVar`.
+   A field's hint is evaluated at decoration.
+   One that cannot be evaluated then, a forward reference under
+   `from __future__ import annotations` or a deferred annotation on 3.14,
+   is a `DeclarationError` naming the field; a relationship never reaches
+   that point, since it is not in the column list.
+   Skipping a relationship covers only this class: the related class is
+   checked by its own decorator, or not at all, and `Cipher(Post)` refuses
+   an undecorated `Post` as decision 4 says.
+
+   The first two are checked at decoration.
+   The constructor check reads `inspect.signature(cls)` and accepts a
+   `**kwargs` parameter.
+   A base that supplies one, Pydantic or SQLAlchemy, passes that check in
+   any decorator order, so decision 9 adds a second order check at
+   `Cipher(User)`.
+   The third is checked only when a row is read; Python cannot check it
+   earlier.
+   `is_dataclass` is not the guard: it rejects classes that meet the
+   contract.
+6. **Plaintext crosses the binding as a frame built in Rust.**
+   On `next` the engine reads a record as a `ValueFrame` and holds no
+   tree type for plaintext.
+   The extension reads the model's attributes straight into a frame, and
+   builds the model instance straight from the decrypted frame.
+   No plaintext passes through a Python `dict` on the way in or out.
+   The model instance is the one plaintext copy Python owns, and Python
+   cannot wipe a `str` or `bytes`, so that copy is documented as the
+   user's.
+   The plan the decorator sends is a frame too; its grammar is the guide's.
+7. **Rule A is assumed and not decided here.**
+   Every field carries a marker; a plain field carries `Passthrough`.
+   Backlog item 1.2 decides it after the user test.
+   The decorator is what makes the rule fire at class definition.
+8. **The marker spelling is the recommended option for item 1.1, not a
+   decision of this ADR.**
+   A sealed field's marker names an EQL type, such as `TextEq`.
+   The marker names are generated from the EQL catalog by `eql-codegen`,
+   the way the Go SDK's `encrypt/eql` package is, so Python holds no
+   table that maps a kind and an index to an EQL type (principle G1).
+   `Passthrough` is the one hand-written marker: a field stored as it is,
+   and the engine's word for it (principle G2).
+   Markers are names, not calls.
+   The decorator finds a marker by identity, not by name: it walks the
+   `Annotated` metadata and keeps the objects that are stash markers, so
+   another library's metadata on the same field is ignored, and a marker
+   from another package that is also called `TextEq` is not a stash marker
+   and leaves the field unmarked, which rule A refuses by field name.
+   Two stash markers on one field is a refusal: one field, one marker.
+
+   | Field | Spelling |
+   | --- | --- |
+   | Encrypted, equality index | `Annotated[str, stash.TextEq]` |
+   | Encrypted, no index | `Annotated[str, stash.Text]` |
+   | Not encrypted | `Annotated[int, stash.Passthrough]` |
+
+   Whether the kind can also come from the Python type (`str` for text)
+   instead of the marker is the user-test question of item 1.1.
+   An earlier draft of this ADR spelled a field as a kind marker plus an
+   index marker (`stash.Text, stash.Equality`).
+   That spelling needs a Python copy of the catalog's kind-and-index
+   table, which is what G1 forbids, so it was dropped at review.
+
+9. **A model does not print a sealed value through `repr`, `str` or
+   `logging`, by default.**
+   The decorator writes `__repr__` and `__str__` on the class it
+   decorates and on the encrypted type the SDK returns.
+   Both print the passthrough fields and `[sealed]` in place of each
+   sealed field's value, the format of Go's generated `String` and
+   `LogValue`.
+   The same markers that drive encryption drive the print, so a sealed
+   field added later is hidden the day it is added; no per-field
+   `repr=False` is needed, and none is read.
+   Python's `logging` calls `__str__`, so logs are covered by the same
+   methods.
+   Serialisation is not printing and is not covered: `dataclasses.asdict`,
+   `attrs.asdict`, Pydantic's `model_dump` and `model_dump_json`, `vars`,
+   a NamedTuple's `_asdict`, iteration and indexing all return the
+   plaintext, because the user asked for the data, and that is how a row
+   reaches an ORM.
+   A log line that formats one of those is the user's print, not the
+   model's.
+   The linter rule below should report those calls on a model when it
+   reports a print.
+   `@stash.model("users", redact=False)` is the class-level opt-out.
+   A class that defines its own `__repr__` or `__str__` by hand is
+   refused at the class statement with the remedy named (`redact=False`,
+   or remove the method); the decorator does not replace a method the
+   user wrote.
+   The methods `dataclass`, attrs and Pydantic generate are replaced,
+   since the decorator is outermost.
+   The rule that tells the two apart looks only at `cls.__dict__`.
+   A method there whose code comes from the class's own module file
+   (`__code__.co_filename`) is hand-written and refused; one from another
+   file, the standard library for `dataclass` or attrs' generated source,
+   is generated and replaced.
+   A method the user assigns from another module is therefore replaced,
+   not refused; that is the one known miss, and `redact=False` is its
+   answer.
+   An inherited method is not in `cls.__dict__` and is neither refused
+   nor touched: Pydantic's `BaseModel.__repr__`, or a hand-written one on
+   a SQLAlchemy `Base`, stays for undecorated classes, and the decorated
+   class's own method shadows it, as a subclass override does.
+   The decorator keeps the methods it wrote in the result it stores under
+   the dunder attribute (decision 3), and `Cipher(User)` checks by
+   identity that `cls.__dict__` still holds them; a decorator that ran
+   later and replaced one means this decorator was not outermost, and
+   `Cipher` refuses with the wrong-order message.
+   That closes the case where a base class supplies a `**kwargs`
+   constructor and the constructor check in decision 5 passes in any
+   order.
+   This is Go's `stashgen -redact` made the default, which Python can do
+   because the decorator holds the user's class and a generator does not.
+   A linter rule that reports a print of an opted-out model is open
+   (principle G3).
+
+## What was run
+
+A probe on 2026-10-16, Python 3.14.2, attrs 26.1.0, pydantic 2.14.1,
+SQLAlchemy 2.1.4, with stand-in markers and no engine.
+The restart's test suite carries these as tests; the probe is not
+committed.
+
+| Class style | Reader finds the markers | kwargs constructor | `getattr` |
+| --- | --- | --- | --- |
+| `@dataclass` | yes | yes | yes |
+| `@dataclass(slots=True)` under the decorator | yes | yes | yes |
+| `NamedTuple` | yes | yes | yes |
+| `@attrs.define` | yes | yes | yes |
+| `pydantic.BaseModel` | yes | yes (keyword-only) | yes |
+| SQLAlchemy `DeclarativeBase` | yes, through `Mapped[Annotated[...]]` | yes (`**kwargs`) | yes |
+
+Two more facts from the probe:
+
+- SQLAlchemy writes its hints as `Mapped[Annotated[str, ...]]`.
+  The reader found the markers by looking through the `Mapped` wrapper,
+  and SQLAlchemy ignored the unknown marker objects and mapped the column.
+  Which wrappers the core reader looks through is decided with the
+  SQLAlchemy layer (backlog item 2); the core must not import SQLAlchemy.
+- With `@dataclass(slots=True)` **above** the decorator (the wrong order),
+  the stored attribute survived, because `dataclass` copies the class
+  dictionary.
+  What fails is the constructor check: at decoration time the class has no
+  `__init__` yet, so its signature is `()`.
+  The decorator therefore reports the wrong order itself, naming the fix.
+
+A second rig on 2026-10-20 put the engine call inside the decorator.
+It used the prototype's built extension only as the engine entry
+(`plan_with` behind its `check_plan`), with every `CS_*` variable unset:
+
+| Class | Who refused | Where it fired |
+| --- | --- | --- |
+| a good declaration | nobody; the engine resolved the target to `TextEq` | the class statement |
+| a field with no marker | Python's check | the class statement |
+| `Match` on an `Int64` field | the engine: "the declared type has no such index" | the class statement |
+
+The rig ran against `main`'s engine, before the frame change on `next`.
+The claim it tests, that a decorator reaches the engine as the class is
+defined, does not depend on the plan's wire form.
+The rig is not committed.
+
+Not run: the error text a user sees, which the restart builds from the
+engine's structured reason fields; the replacement of the `__repr__`
+that attrs and Pydantic generate, which the probe did not cover; and the
+hand-written-method rule of decision 9 across Python versions, run on
+3.14.2 only, where `dataclass`'s `__repr__` reports `reprlib.py` as its
+file and a hand-written one reports the class's module.
+
+## Consequences
+
+- The restart plan carries the language-integration guide's checklist
+  (its section 11): the frame conformance corpus byte for byte, a
+  differential fuzz target over the Python codec, plaintext hygiene tests
+  for the extension's copies, a frozen stored-rows fixture, the engine and
+  frame-format versions named in the wheel's release notes, and the
+  cross-language fixtures read from the Python tests.
+  The first test is the guide's section 10 bytes reproduced from Python.
+- Importing a module that declares a model imports the native extension.
+  The check needs the engine's rules and holds no copy of them
+  (principle G1).
+  It makes no network request.
+- "Was this class declared?" is an import-time check, not a type-check.
+  pyright and mypy see the decorator as identity, `type[T] -> type[T]`,
+  and cannot require a decorated class at `Cipher(User)`.
+  This is a strain against G3 that backlog item 1.3 (a generate step, or a
+  typed wrapper) may close.
+- The decorator stacks above every other decorator.
+  The documentation says so once, and the constructor check reports the
+  wrong order with the fix.
+- A class the user does not own gains one dunder attribute.
+  That is what `dataclass` and `attrs` do too.
+- One context per class, and no per-caller part in the first version.
+  Principle G4 puts what varies per caller on the cipher, not on the
+  class, but the engine refuses an extended cipher for an EQL-typed field
+  (decision 2), so per-caller tenant or per-user locking on these fields
+  waits on the ZeroKMS lock context (#1067).
+- `Plan`, `PlanBuilder` and `PlanSpec` leave the public surface.
+  The engine's plan grammar still exists behind the decorator; the user
+  never names it.
+- The marker set is generated, so a new EQL type needs no change to the
+  declaration reader.
+  The reader passes a marker's name to the engine as the plan's `target`,
+  and the engine decides whether the catalog produces it.
+  A new kind (`date`, `timestamp`, `decimal` landed on `next`) needs a
+  codec in the shell for the value's bytes and a regeneration of the
+  markers, and nothing else in Python.
+- Python has less kind ambiguity than Go.
+  Go's `time.Time` can mean a date or a timestamp.
+  Python's `datetime.date` and `datetime.datetime` are different types, so
+  the hint alone can pick the kind when those kinds land.
+- The week-1 step 2 sentence becomes true by construction, and the
+  scorecard marks G3 "held" for the declaration check.
+- Backlog item 1 still owes two memos: 1.1 (`Annotated` against other
+  shapes) and 1.3 (typing the encrypted output).
+  This ADR takes `Annotated` as the input they compare against, which is
+  decision 5's default.