Django Adapter Technical Specification

Date: 2026-08-08 · Status: Draft 1 · Purpose: the engineering design for adapters/django (package fieldseal-django), targeting Django 6.1 / 5.2 LTS. Built directly on the verified hook analysis in docs/04-orm-adapter-notes.md §1; ORM facts below that were verified there are cited as such, everything else is flagged.

Conformance target (spec §10.1): L0 ✅ · L1 ✅ · L2 (a)+(b) ✅ · L3 via documented contextvar side channel ⚠️ · L3-row only with client-generated PKs ⚠️ · L4 ❌.

Hard rule (spec §11.3 / AD-1): zero cryptography in this package. The only calls into fieldseal are the five sync operations plus warm.

1. Declaration surface

Composition over Django’s existing field types — the Rails encrypts shape that docs/04 §8 says to adopt:

from fieldseal_django import Encrypted, BlindIndex, FieldsealMeta

class Patient(models.Model):
    email = Encrypted(
        models.EmailField(),                 # the logical type; drives to_python/validation/forms
        column_uuid="018f3c2e-…",            # REQUIRED, immutable surrogate (spec §6.1)
        index=BlindIndex(                    # optional; presence declares L2
            index_id="exact",
            idf="argon2id",
            normalize="nfc-casefold-v1",
            truncate_bits=15,                # §7.4 band for P=100,000 is 9–15 bits; 16 is out of band
            projected_population=100_000,
        ),
    )
    email_bidx = Encrypted.index_column("email")   # explicit sibling column — see §1.2

    class Meta:
        pass

    fieldseal = FieldsealMeta(table_uuid="018f3c2e-…")   # REQUIRED per model

1.1 Why explicit UUID surrogates in code

table_uuid/column_uuid MUST be immutable surrogates, not SQL names (spec §6.1). They are supplied literally in the model source and captured by deconstruct() into migrations, so a rename never changes them. The adapter ships a management command fieldseal_gen_uuids that prints ready-to-paste values; a system check (E004, §5) fails if any encrypted field lacks one. Deriving them from app_label.ModelName.field is forbidden — that is a rename time bomb, exactly what §6.1’s justification warns about.

1.2 The index sibling column

The blind-index column is a real, explicit field (Encrypted.index_column), not a hidden auto-injected one, for two reasons:

1. Declaration-order clarity. With an explicit column the order is visible in source, and system check E001 asserts it at startup. Corrected at implementation (2026-08-25): the original reason given here was wrong. This section claimed the index field’s pre_save “must run after the encrypted field’s” because SQLInsertCompiler.as_sql iterates in declaration order. Measured: a model with the sibling declared first produces the byte-identical index value, because pre_save reads the instance attribute, which Python set long before any field hook ran. Declaration order cannot affect the index today. E001 is kept for the reasons that are true — deterministic column order in migrations and DDL, readability, and the fact that L3-row binding would make the source’s pre_save mutate the instance and turn order into a real dependency whose failure would be silent. Establishing it now is free; claiming a failure that cannot happen is not.
2. Migration transparency. makemigrations emits the column with no magic; the operator sees exactly what DDL runs.

Encrypted.index_column("email") returns a BinaryField-backed field whose pre_save reads the sibling plaintext off the instance (available — pre_save receives model_instance, docs/04 §1) and calls core.blind_index. Storage: raw bytes, length ceil(b/8), per spec §7.11 (G8 resolved) — normative now, not interim. The generated column is BinaryField, and the adapter’s migration check MUST verify the column’s collation is binary where the backend allows a text index column at all (§7.11); MySQL is the case that bites, since a VARCHAR index column under a _ci collation silently matches values the core treats as distinct.

2. Value path

3. Query path

3.1 L2 (a) — explicit index property

Patient.objects.filter(email_bidx=plaintext): the index field’s get_db_prep_value derives the blind index from the plaintext parameter through ordinary parameter conversion. Works today with zero rewriting; the query surface is explicit (spec §10 L2(a)).

3.2 L2 (b) — transparent rewrite

A registered Exact lookup on the encrypted field compiles to a Col for the sibling index column (the clean route docs/04 §1 documents, composing with Q, joins, and subqueries):

class EncryptedExact(Lookup):
    lookup_name = "exact"
    def as_sql(self, compiler, connection):
        bidx_field = self.lhs.output_field.fieldseal_index_field
        bidx_col = bidx_field.get_col(self.lhs.alias)
        lhs_sql, lhs_params = compiler.compile(bidx_col)
        rhs = core.blind_index(serialize(self.rhs), bidx_field.fieldseal_ctx)
        return f"{lhs_sql} = %s", [*lhs_params, rhs]

In gets the same treatment (N index values IN’d, spec §7.10).

Mandatory over-fetch re-verification (spec §7.5) — decided at implementation, 2026-08-26. The design note this paragraph used to carry is settled as option C: FieldsealQuerySet._fetch_all re-verifies by default and .candidates() opts out. The rejected alternative was an explicit .verified(), whose failure mode is silent — one forgotten call returns collision rows, which is the §10.2 wrong answer the adapter exists to prevent. The safe path has to be the default path.

The manager arrives without being asked for. A default that must be installed by hand is not a default, so class_prepared installs FieldsealManager on any model with an indexed encrypted column that declares no manager of its own — Django marks its own auto-created objects with auto_created, which is an exact test for “the author did not choose”. Where the author did choose, the adapter does not overwrite it; system check E008 requires them to mix FieldsealQuerySet in.

What re-verification compares is spec §7.5’s comparison rule (G19 #78, resolved 2026-08-26 — this adapter was the rule’s prototype): normalize(stored) against normalize(queried) under the index’s own normalizer. The normalizer comes from the core (fieldseal.normalize, made public for this); an adapter that reimplemented nfc-casefold-v1 would be reimplementing portability surface where a disagreement is a silent lookup miss.

The design work is not the rewrite, it is what shrinks. Verification drops rows after the database has applied COUNT, LIMIT and OFFSET, so every queryset method answered from SQL is wrong by default. Each is handled explicitly:

.candidates() lifts the verification refusals in that table — including the filter-time Q under OR, since the SQL semantics they refuse are exactly what it hands over — and returns bucket semantics, documented as unverified. An escape hatch that refuses the same things is not one.

It does not lift negation, and that changed here: G24 #100, decided 2026-09-06 in the Prisma adapter’s direction. This adapter lifted exclude() and its refusal message recommended doing so; spec §10.2 now forbids both. The deciding argument is what the caller can do with what they were handed: under filter(...).candidates() they hold a superset of the answer and reach it by dropping rows — that is §7.5, and handing it over is the entire point of the hatch — while under exclude(...).candidates() they hold a subset, and no operation on it restores a row the database already removed. The hatch was transferring a responsibility that is not dischargeable from what it transferred with it. XOR came in on the same test and was not in the issue’s filing: a XOR b is (a AND NOT b) OR (NOT a AND b), so a widened bucket drops rows from it exactly as an exclusion does. The refusal is by position, not by operator — spec §10.2 states it that way — and IS [NOT] NULL is outside it, reading the envelope column’s own null-ness with no bucket involved.

Position also means a position the bucket is only an operand of, and the closure did not cover those (G24 review round, 2026-09-08). exclude(pk__in=Owner.objects.filter(col=v).candidates()) names no encrypted column in the outer predicate and subtracts the whole bucket; so do the relation form, difference(…candidates()) and annotate(has=Exists(…candidates())).filter(has=False). All four were measured served, with the colliding row dropped. resolve_expression cannot hold this line — it is handed the operand without the position, so it cannot distinguish these from filter(…__in=qs.candidates()), which is exactly what the traversal and cross-model messages recommend. The queryset therefore marks its own Query (fieldseal_indexed / fieldseal_verify, which survive the clone Subquery.__init__ takes) and the position is read at filter(), exclude(), difference() and annotate(). A .candidates() queryset that never touched an index is not a bucket and embeds anywhere: the rule is about the semantics, not the method name.

Refusal honesty on a column with no bucket (G24 review round, item 5, 2026-09-08). The refusals in this section justify themselves with §7.4 bucket mechanics — an exclusion drops the whole bucket, a database-answered operation computes over one, an OR branch leaves a candidate §7.5 cannot decide — and each is checked before the column is checked for having an index at all. On a column with no BlindIndex, or under a lookup §7.1 keeps off the index, that justification described a bucket that is not there, and the remedy it prescribed (run the positive form instead) is refused on its own account. The check order is deliberate and unchanged: reversing it sends a caller to run a schema migration for a shape that is refused with the index too. So the fact travels in the message — the refusal names the real reason first, keeps the position rule as an explicitly counterfactual second half, and points at the fallback that works either way (fetch, then filter after decryption). Spec §10.2 states this principle as two instances rather than one clause — the G23 bytes-computation sentence and the G24 escape-hatch sentence — and this is a third instance implemented without one.

The other refusal it cannot lift is the cross-model traversal, because another model’s queryset cannot take on §7.5; the opt-in there is the owning model’s .candidates(), embedded as above.

filter() was not the only door, and every rule in this section lived behind it (G24 review round item 1, #118, 2026-09-08). Two routes reached the blind index without passing FieldsealQuerySet._filter_or_exclude, so §7.5 obligation recording, the OR refusal and the G24 subtractive refusal were all simply absent on them. complex_filter(Q) calls query.add_q directly — Django’s own body routes only the dict form through _filter_or_exclude — so complex_filter(Q(email=v)) served the bucket as the answer, complex_filter(~Q(email=v)) dropped it, and complex_filter(Q(email=v) | Q(…)) served what the OR refusal exists to stop; all three measured. Model._base_manager is a plain Manager returning a plain QuerySet — Django builds it that way deliberately, so its own internals are not filtered by a custom default manager — so on the owning model there is no queryset layer at all, and the compile-time traversal backstop passes there by design, because the owner is the querying model; no unusual method was needed, an ordinary filter() was enough. Neither route is one a caller has to type: Django applies limit_choices_to through complex_filter at five sites, two of them on _base_manager, so an ordinary full_clean() and a ModelForm’s choice list both arrived here.

The fix is one per layer, deliberately not one per entry point — an adapter enumerating Django’s doors is the failure mode this was an instance of. complex_filter is overridden with the same walk filter(Q(…)) runs, which is the half that needs queryset state. The other half moves down to _IndexedLookup, beside the cross-model backstop and by the same argument one relation shorter: an encrypted equality compiles only for a query whose rows a verifying queryset will materialize and re-verify — or one whose caller took §7.5 on with .candidates(). FieldsealQuerySet marks its Query at birth as well as on every clone, and the refusal reaches only predicates that touch the index, so _base_manager keeps answering primary keys, IS [NOT] NULL and unfiltered reads, which is what Django’s own FK validation, cascade collection and refresh_from_db need from it.

Two distinct ways to fail that, and the first cut only checked one (found by this PR’s review round, 2026-09-08). The first is the absence of the mark — no queryset of ours ever held this Query, which is what _base_manager builds. Note the asymmetry that makes the check work: fieldseal_verify = False is a caller opting out with .candidates() and stays served, while the attribute missing is nobody having opted in. The second is a mark that is real but belongs to the wrong query: Exists(qs) and Subquery(qs) take qs.query and never touch the queryset again, so the lookup compiles for an inner query carrying a genuine mark while the rows are fetched by an enclosing statement that may have no layer at all. Measured with a forged collision: _base_manager.filter(Exists(objects.filter(pk=OuterRef("pk"), email=v))) returned the §7.4 bucket and the exclude() form returned G24’s subtractive wrong answer — so the shape the first check refuses was rewritable as a correlated Exists and served. The second check keys on Query.subquery together with fieldseal_verify, and on verify alone rather than verify and indexed, because §7.5 runs over rows the queryset materializes and a subquery’s rows never leave the database, whatever its index mark says. FieldsealQuerySet already refuses this embedding at filter()/annotate() time, which is why the same subquery under a verifying outer was refused before; this is that rule at the layer the enclosing querysets that never reach the first one still pass through.

The residue, stated rather than claimed away. A .candidates() bucket in a subtractive operand is refused on any FieldsealQuerySet by the bucket-as-operand rule above, and from Model._base_manager there is nobody to read the position. It has two spellings, and the compile-time layer misses each for its own reason (the second was raised on this PR’s re-review round). exclude(pk__in=Owner_qs.candidates()) never reaches that layer at all: the outer predicate is on a plain column and the operand is a queryset, so no _IndexedLookup compiles anywhere in the statement. exclude(Exists(Owner_qs.candidates())) does reach it — an indexed lookup compiles inside the subquery — and is allowed through deliberately, because fieldseal_verify is False there and the boundary check must not refuse the embedding three refusal messages recommend; the lookup is handed the operand without the position, which is the same argument _refuse_bucket_operand exists for one layer up. Both are served, short by the collision. That is the same residue this section already records for a model with no encrypted column of its own, with the owning model’s plain manager as a second instance; it stays a residue rather than a hole for the same reason, which is that the caller had to construct the bucket deliberately to arrive there. Both spellings are asserted as residues in the test suite so that neither can drift back into a claim.

One route the issue did not list, found writing the tests. forms.models.apply_limit_choices_to_to_formfield wraps the condition in Exists(…), which the subquery-embedding rule above refuses — but on Django 6.1 it builds that subquery from _base_manager, so the embedded queryset carries no fieldseal_indexed mark and the expression walk never sees one. Measured before the fix: a ModelForm over a FK whose limit_choices_to names an encrypted column offered the §7.4 collision row as a valid choice. It is door 2 wearing door 1’s clothes, and the lookup-layer refusal is what closes it — which is the argument for putting the backstop below the entry points rather than at them.

The G20 family (#80, closed 2026-08-26; discriminator narrowed to bytes-reading by G23, #89): SQL that reads envelope bytes. A second refusal family, orthogonal to §7.5 verification and active on every FieldsealQuerySet, obligations or none — a meaningless order needs no filter present to be wrong — and not lifted by .candidates(): bucket semantics are a meaningful thing to accept for a filter; ciphertext order has no semantics to accept. Measured before the refusals were written: order_by("email") returned envelope-byte order; values("email").annotate(n=Count("pk")) returned four groups of n=1 where the truth was three with one n=2, two groups printing the identical key; aggregate(Min("age")) over {30, 40} returned 40 — the byte-wise minimum envelope decrypts cleanly to an arbitrary row’s value, presented as the minimum, with nothing raised.

Interception honesty (docs/04 §1): Django resolves ordering names to a plain Col with no field hook in the path, so the refusals are queryset-level plus the two checks — which means a plain-manager model ordering through a relation onto another model’s encrypted column is not reachable, unlike the equality traversal, which is closed at the lookup layer. That residue is documented in the raw-SQL class.

The same honesty applies to the bucket-as-operand rule above: the position is read on a FieldsealQuerySet, so a model with no encrypted column of its own has no queryset of ours to read it from and Plain.objects.exclude(fk__in=Owner_qs.candidates()) is not reachable. Unlike the equality traversal there is no lookup-layer backstop to fall to, because the outer predicate is on a plain column; unlike ordering, the caller had to construct the bucket deliberately to get there. It is a documented residue, not a covered case.

3.3 Refused lookups (spec §10.2 — throw, never degrade)

On the encrypted field, every lookup except the rewritten exact/in (and isnull) raises FieldsealNotSupported with the honest-fallback text from spec §7.10: contains, icontains, startswith, gt/gte/lt/lte, range, regex, iexact (case folding belongs to the normalizer, not the query — and since G19 (#78, resolved 2026-08-26) that is spec §7.5’s normative rule rather than an aside: §7.5 re-verification compares normalized values, so on a nfc-casefold-v1 column exact is the caseless lookup and a second one would be a second equality the index cannot serve), search. Without a declared index, exact/in raise too (“no blind index declared for this column”).

4. Context assembly and modes

• FieldContext per column is built once at contribute_to_class time (table/column UUIDs, suite from settings). Tenant: fieldseal.django.context.set_tenant(tenant_id) contextvar, with a shipped middleware example; documented as the L3 side channel of spec §10 — including that any code path outside the middleware scope (management commands, celery tasks) must set it explicitly or encryption fails closed (ConfigurationError), never silently falls back to tenantless context when a tenant-bound column is declared.
• row_id binding: not in v0 of the adapter. Django cannot see the PK at INSERT with identity keys (docs/04 PK table); L3-row support arrives only for models the check system can prove use client-generated PKs (default=uuid7-style) — deferred, tracked in the coverage matrix as ❌ with the reason.
• Read mode has exactly one owner: settings.FIELDSEAL["READ_MODE"] feeds the client the adapter constructs (§7) — there is no second mode knob, and the client is immutable after construction (docs/09 §2), so a mode change is a process restart. permissive emits a fieldseal.plaintext_read signal per event plus a counter metric (spec §10.3 requires the warning + SHOULD metric).

5. System checks (startup-enforced correctness)

6. Coverage matrix (the AD-2 normative deliverable)

Shipped in the package README, kept in sync with tests by generating both from one table:

7. Async, warm-up, and operations

• All field hooks are sync; Django’s async ORM wraps sync (docs/04 §1) — so the DEK cache is mandatory, and the adapter’s docs say so in bold. Implemented 2026-08-26, with one deliberate departure from the sentence this bullet used to carry. manage.py fieldseal_warm primes the cache for every declared column, and the AppConfig.ready() hook exists but is opt-in (FIELDSEAL["WARM_ON_READY"]) rather than automatic: ready() runs for makemigrations, shell, collectstatic and every test process, so warming unconditionally would make a command that touches no encrypted row pay a KMS round trip — and fail when the key service is unreachable, so a migration could not run because of it. A migration blocked by a cold KMS is a worse failure than a cold cache. The honest consequence is documented instead of defaulted around: under an EnvelopeKeyProvider, §8.2 confines unwrapping to warm and forbids the value path from blocking on network, so something must warm the cache before the first read — the setting or the command, with no third option and no silent fallback that would make a cold read work. A warming failure at ready() warns and continues, because a web worker that exits on a transient KMS blip takes the deployment down for a condition the next request might not have.
• Warming covers index keys, not just data keys. Spec §5.2 makes the index key a sibling of the tenant DEK rather than something derived from it, so a cache warmed only for the data key still stalls every indexed lookup — and the symptom looks like a slow query rather than a cold cache. Tenant-bound columns need their tenants named (--tenant, or FIELDSEAL["WARM_TENANTS"]): a tenant-bound context carries a tenant_id, and the adapter cannot enumerate a deployment’s tenants, which live in application data under a schema this package knows nothing about. A run that omits them names the columns it skipped rather than reporting a warm cache it did not warm.
• Settings surface and client construction: FIELDSEAL = {"KEY_PROVIDER": callable, "READ_MODE": …, "ALLOWED_SUITES": …, "WRITE_SUITE": …, "CACHE": …}. The adapter constructs the Fieldseal client in AppConfig.ready(), after model loading, assembling the IndexDeclaration registry from the model-level BlindIndex(...) declarations — that is the only way the core’s construction-time validation (docs/09 §2: §7.6 gate, §7.4 band) runs against the indexes actually declared on models. Escape hatch: FIELDSEAL["CLIENT"] (callable returning a pre-built client) for deployments that must own provider wiring, gated by system check E006 — its index registry must exactly match the model declarations, or startup fails.
• Migration/backfill: the adapter ships nothing beyond field defaults; the zero-downtime procedure and tooling live in tools/backfill (docs/15-tooling.md), following the dual-write shape of docs/04 §11 (backfill MUST use bulk_update, never queryset.update(F(...))).

8. Test plan

The index half, 2026-08-31 (cross/v2). The producer also emits five index cases: the blind-index sibling column as the database holds it, plus the declaration read off the model’s own BlindIndex(...) rather than restated. A consumer in another language re-derives each one. This is the half docs/07 §7 calls the more valuable assertion — a mismatched index is a silent lookup miss, so the row stays stored and decryptable and simply stops being findable, and the envelope half stays green through it. The case only an adapter can produce is the last: a value nfc-casefold-v1 refuses, where the field stored the §7.2 reserved marker by itself because Person.legal_name declares on_unindexable="bucket". A core alone cannot demonstrate that — it has no column declaration and no write path.

• Path matrix tests: one integration test per row of §6, against Postgres and SQLite in CI (binary column behavior differs; both are supported targets).

• Refusal tests: every §3.3 lookup and every 🛑 row asserts the typed exception, not a generic error.

• Ordering regression: a model with index-before-encrypted declaration must fail E001; a model without the check bypassed must produce correct sibling values under bulk_create.

• Candidate re-verification: seed two plaintexts that collide at the configured truncation length (construct via brute force at small b in the test), assert the collision row is filtered out.

• Permissive-mode metric: plaintext read increments the signal exactly once per value.

• Cross-language sharing test (the point of the project) — implemented 2026-08-26. adapters/django/tests/cross_produce.py writes rows through the real ORM path (real save(), runtime CSPRNG, no test-mode injection), reads the raw column back through a database cursor, and emits a standard fieldseal-vectors/cross/v1 document. Every existing consumer reads it unmodified, so the adapter joins the N×N matrix as one more producer — django is now a third value of the cross-produce matrix, and both core consumers take cross-django.json alongside the others.

  What this covers that no core test can. Three decisions between an application value and the stored column belong to the adapter: the codec’s rendering (IntegerField(45) becoming b"45" — a choice until spec §3.6 pinned it, and pinned now by the codec/ vectors (docs/08 §4.8), which this adapter runs; a consumer expecting another encoding would decrypt successfully and read the wrong value), the storage form (binary versus base64), and context assembly from model declarations plus the tenant contextvar (a consumer reconstructing it differently gets COMMITMENT_INVALID — a decrypt-side error for a write-side configuration mismatch). A core round trip sees none of them.

  The local suite runs the producer and decrypts it with a client built independently from vectors/keys/, so a case passes only if the stored bytes are readable from the shared key material alone. The true cross-language leg needs Node and therefore runs in CI. Two runs must also disagree on every envelope, since a producer that had drifted onto the injection seam would otherwise pass everything (spec §4.4).

  Still to do: the index half — a blind index written by Django, derived identically by the TypeScript core. It is the more valuable assertion of the two, because a mismatched index is a silent lookup miss rather than an error, and it needs the cross/v1 schema to carry the index declaration. Tracked as the next cross-language increment rather than half-done here.

9. Deliberate non-goals

No transparent row_id binding (v0), no query support beyond exact/in/isnull, no admin search integration, no automatic tenant inference from the request (explicit contextvar only), no support for Encrypted on relational fields (ForeignKey stays plaintext — spec §7.10), no Django < 5.2 support.

10. Unindexable values (docs/09 §7.2 — normative for this adapter)

encrypt does not normalize and blind_index does, so a value containing a code point the pinned Unicode version does not define stores but cannot be fingerprinted. Every Encrypted* field carrying an index therefore declares on_unindexable, and the adapter’s behaviour follows from it. This section is the obligation docs/09 §7.1 refers to; it is normative for this adapter, and it is the reason refuse is a default rather than the only option.

10.1 What the adapter does

refuse MUST surface as a field-level ValidationError, not as a generic 500 or a silently dropped index. A ModelForm then renders it beside the offending input, which is the only place the person who typed the value can act on it.

Where the refusal is raised is load-bearing, and was corrected at implementation (2026-08-26). The index can only be derived in pre_save, which is the one field hook that receives the instance — and pre_save runs inside the INSERT, so a ValidationError raised there propagates out of Model.save(), whose transaction.atomic(savepoint=False) marks the connection for rollback. The caller then has their field error and a transaction they cannot use, which is not a form error in any sense that helps. The check therefore also lives in Encrypted.validate(), which full_clean() calls — so the ModelForm path fails before the database is touched, and pre_save remains the backstop for code calling create() directly. That second path still marks the transaction; it is Django’s behaviour for every exception in save() rather than something this adapter chose, and it is documented in the package README rather than pretended away.

One implementation note that costs an hour to rediscover: ValidationError discards code and params when its message is a dict. The machine-readable half has to be carried by the inner error — ValidationError({field: ValidationError(msg, code=..., params=...)}) — and a caller who builds the dict itself loses it with no warning that it did.

10.2 The message (normative in shape, not in wording)

“Unsupported character” fails every part of this. The message MUST:

1. Name the specific character and where it is. The user cannot act on “somewhere in this field”.
2. Put the fault on the system. The value is not invalid — it is a name, and the system’s tables are out of date. Wording that implies the user made a mistake is wrong on the facts.
3. Offer a route that ends with the real value stored. A refusal with no escape hatch is a dead end for the person on the other side of it, which is why refuse and bucket are specified as a pair: bucket is the operator-applied escape hatch, not an alternative philosophy.

We can't save this name yet. Our systems don't recognise the character 𠮷
(3rd character). This is a gap on our side, not a problem with your name —
it's a recently added character we haven't added support for yet.

[Save with a different spelling]   [Contact support — we can enter it manually]

The support path has to be real. “Contact support” is only honest if support can actually store the value, which means an operator can move that column to bucket, or store the row through a path that does not derive the index.

Where rule 1’s two halves come from. fieldseal.first_unassigned(text) returns the offending code point and its offset, in code points — the unit this section’s own example counts. It is exported from the package root for exactly this (docs/09 §7.1; G22, #88), so no adapter needs to parse an error message to build the message above, and no adapter needs a second copy of the Unicode assignment table — a second copy that drifts is a silent lookup miss, not a wrong message. This adapter’s locate_unindexable keeps its normalizer-aware probe rather than calling the accessor directly, and deliberately: the accessor answers nfc-casefold-v1’s refusal rule, while a column may declare a normalizer whose rule is narrower (identity refuses surrogates and accepts unassigned code points). Probing the declared normalizer is the general answer; the accessor is the right one for any adapter that knows it is on the nfc-casefold-v1 path.

10.3 Choosing per column

The answer differs by column and a single rule is wrong somewhere:

• A login email — refuse. An account that exists and cannot be found by its own login is worse than a rejected signup, and the value is machine-shaped: a character outside the pin in an email address almost always means something upstream is broken.
• A legal or display name — bucket. Refusing a person’s name is a hard failure for that person, and names are exactly where rare characters legitimately appear.

bucket requires unindexable_override={"reason": ..., "approved_by": ..., "date": ...}, refused at model-definition time (E-series check) if absent — the same ceremony spec §7.6 requires to relax the cardinality gate, and for the same reason: it is a per-column relaxation of a default-deny rule, so it should be a recorded act rather than a setting that gets copied.

10.4 What bucket costs, stated

The marker is a real index value derived under the column’s own index key, so it is not distinguishable as the marker without that key. But the bucket is an equivalence class that can grow far past §7.4’s expected P × 2^(−b), so it is distinguishable by frequency: an observer who can read the index column sees one unusually popular value and can infer that those rows share “contains a character outside the pin”. The class is also growable by anyone who can write to the column, which makes lookups against it progressively more expensive — bounded by re-verification cost, not by anything cryptographic. A column where either is unacceptable keeps refuse. The adapter documents both in its README rather than only here.

View source: docs/12-adapter-django.md