[coderdan]

Summary

EQL (Encrypt Query Language) is the SQL bundle that stores and queries encrypted values in PostgreSQL; EQL v4 is the version for values written by Stack Encrypt, the Rust encryption engine in packages/stack-encrypt. Its json_tree type (unreleased) stores an encrypted JSON document as one entry per JSON node: a small ciphertext c holding that node alone, plus keyed tags that let PostgreSQL search and walk the document without the decryption key. Two of those tags matter here. A selector s is a keyed hash of a node's path. A token is a secret 16-byte value per node that the client hands the server in a query: from it the server can find that node's children, through each child's parent tag p, and so walk the subtree under the node.

This PR shrinks what each entry stores from nine fields to four (s, c, p, op) and changes how the server walks a subtree, so a walk no longer costs the document's widest node for every node it visits. Stacked on #1325. The stored format changes with it, so it has to land before the family ships.

• Three fields had no reader once the containment projection q was stored (perf(eql, stack-encrypt): store the json_tree projection, walk by parent map, budget the subtree #1325). q is the document's selector pairs grouped by array element, so PostgreSQL's own jsonb @> over it decides containment. Those three fields were the per-entry value selector vs and the two group tags n and g. The engine now reads q back as the projection instead of rebuilding it from the entries.
• Two more fields existed only so the server could continue the token chain: the wrapped token w and the ordinal o. A child's token is now H("t" ‖ t(parent) ‖ s ‖ LE32(o)), a hash of its parent's token, its own selector s and its position among its siblings, which the server derives as it walks. The positions under a node run 0, 1, 2, … with no gaps, so the walk probes them in turn and stops at the first miss. A subtree of N nodes costs about 2N probes (a SHA-256 and a lookup each) plus N token hashes, where it cost every position up to the document's widest node at every node visited.
• The client can no longer derive an object member's token: its position is a rank among sibling keys the client does not know. So a query sends the deepest token it can derive (a top-level field's, then any array positions directly after it) plus one gate per further path step: that step's selector, or #n:<selector> for an array position, with the array elements' selector. The server descends through the gates and returns the node they reach at depth d = 0, with its descendants beneath it.
• The leaf ordering term op is opt-in per path (commit ba62e3fc5). op is an order-preserving ciphertext of a number or string leaf, about 80 bytes each, which ORDER BY and range queries at that path use through eql_v4.ord_term. It was derived for every number and string leaf, which made it the largest field of a nested document (24.8 KB of 85 KB) and the one field that reveals something across rows at rest (the order of that leaf's value among every row that holds one), on paths nobody orders. A JSON index now names the paths it orders, with [*] covering every element of an array (a position such as [2] is refused, since -> reads it as [*]); nothing is ordered by default; and an ordering query at a path the index does not order is refused before any key loads, instead of silently matching no row.

Changes

• SQL (packages/eql/src/v3/json_tree/, rendered into EQL v4 only):
  • The entry validator accepts s, c, p and op only, so a document written by the earlier build of this unreleased type is refused.
  • eql_v4.json_tree_subtree_at(doc, token, gates text[], budget DEFAULT 64) replaces the earlier (doc, token, selector, budget) form. It walks the gates and returns the reached node at d = 0 with its descendants. json_tree_subtree(doc, token, budget) is now that function with no gates, and still returns the token's node's descendants from d = 1.
  • json_tree_children and json_tree_child_count take the same optional gates.
  • The budget is unchanged: when the document's root is sealed (its ciphertext holds the whole document) and a walk would return more than budget entries, the walk returns the root entry alone at j = 0, d = 0, and the client opens it and selects the path itself.
  • eql_v4_internal.json_tree_child_token is added; json_tree_unwrap, json_tree_xor16 and json_tree_fanout are removed.
• stack-encrypt (src/json/):
  • JsonEntry is {s, c, p, op}, and JsonDocument carries its projection, which the wire form requires as q.
  • JsonSubtreeKey holds a token and gates(); a position gate is #n:<selector>.
  • JsonDocument::children() probes positions in turn.
  • Rows from a gated walk open to the reached node's value.
  • JsonOptions gains ordered: BTreeSet<JsonPath> (so it is Clone, no longer Copy), JsonOptions::ordering([..]) parses paths into it, and JsonPath::covers is the match rule the walk and the query share. The data-plan wire is {"json": {"sealed_root": true, "ordered": ["$.age", "$.orders[*].total"]}}; the header does not record the set, since a stored leaf shows whether it has a term. JsonHeader::options() is removed and json_subtree_key takes &JsonOptions.
  • TermError::JsonPathNotOrdered (code stack_encrypt::json_path_not_ordered) refuses Lt, Lte, Gt, Gte and Between at an unordered path when the query is awaited.
• stack-encrypt (src/plan/, src/target/): a typed plan had no place for index options, since encrypt_into::<JsonDocument>() reads the type's static EncryptFrom. target::Layout<S> is a target's layout chosen by value, with the index it answers queries through; Json::new(options) implements it, and Plan::value().encrypt_as(layout) builds a ValuePlan<_, Laid<X, T>> that seals under the options and resolves every query through the plan's own index, so a query does not name the options again. Error gains From<JsonPathError>.
• eql-bindings (src/v4/json_tree.rs): JsonTreeEntry drops vs, o, w, n and g, and the typed document hands q to the engine. JsonTree::new(options) is the json_tree layout under options (a Layout<Value> whose target is JsonTreeDocument); the type's own EncryptFrom is that layout under the defaults.
• Tests in all three places are updated for the new fields and the gated walk.
• Design doc (docs/plans/2026-10-17-json-tree-index.md): the Phase 3b implementation note carries the measured outcome below, and a Phase 3c note records the opt-in and its measured sizes. The earlier sections, which still describe the wrapped token, group tags and stored ordinal, are kept as the record, with dated notes where they would otherwise mislead.
• Doc comments that still described the old format are corrected (the header's SQL reader, the projection's source, the walk's cost).
• Changeset: @cipherstash/eql minor.
• Byte encodings (commit 37e02ab42): every field the SQL compares, derives or decodes is padded standard base64 (s, the s/vs pairs of q, p, op, tokens and gates), which PostgreSQL's encode/decode handle natively and which decode refuses unpadded; c is RFC 1924 base85 through the base85-simd 0.1.0 crate (no SQL function decodes c); h stays base64 because the SQL reads the iv and the sealed-root flag from it. p is the first eight bytes of its hash: a lookup key within one document, and the AAD binds s and j, not p. eql_v4_internal.json_tree_ope_cllw is added because the shared ope_cllw(jsonb) of the scalar types reads hex. eql-bindings gets JsonTreeSelector, JsonTreeCiphertext and JsonTreeOrderingTerm newtypes so the v4 wire is documented apart from the v3 hex types. Design doc: a Phase 3d note.

Verification

• cargo nextest run -p stack-encrypt --all-features: 733 passed.

• cargo test -p eql-bindings --all-features json_tree: passed.

• mise run test:encryption:postgres against a fresh database with the v4 bundle built from this tree: all suites passed, including the json_tree oracle, which compares containment over the encrypted column with jsonb @> over the plaintexts (postgres_containment_over_the_encrypted_column_is_jsonb_containment, postgres_extracts_walks_and_orders_by_path).

• After the docs follow-up commit (3860ecc3c): cargo clippy --all-features --all-targets -D warnings and cargo fmt --check clean for stack-encrypt and eql-bindings, mise run test:schema passed, and mise run docs:validate's coverage and required-tags checks passed. Its documented-sql step needs the Docker database on port 7432 and could not connect locally; CI runs it.

• For the opt-in commit (ba62e3fc5): cargo nextest run -p stack-encrypt --all-features 737 passed (new: an_ordering_term_sits_only_at_an_ordered_path, a_laid_out_plan_opens_what_it_wrote, the refusal cases in an_accessor_asks_at_a_path and an_accessor_is_refused_before_its_keyset_loads, the ordered wire round trip); the 46 doctests, including the new encrypt_as example; rustdoc with -D warnings; clippy and fmt clean; the trybuild snapshot op_matches_on_integer.stderr regenerated, its only change being the new Laid impl in rustc's help list. mise run test:encryption (eql-bindings and the encryption test crate, no database) passed. The json_tree PostgreSQL oracle (postgres_extracts_walks_and_orders_by_path, postgres_containment_over_the_encrypted_column_is_jsonb_containment) passed against a database carrying this branch's v4 bundle, with the corpus sealed under $.hello and $.number ordered; the SQL did not change in that commit. Docker was not running locally, so the full test:encryption:postgres task was not re-run. cargo-mutants over the commit's diff found five survivors, all on the new Laid plan shape, pinned by 2e405c462 (ValuePlan::specs added for the test).

• Benchmarks, cipherstash/benches@2d9d5f2 (branch feat/json-tree-benches, report/JSON_TREE_COMPARISON.md, "Third measurement"). They ran at 10,000 and 100,000 rows on one machine (Apple M1 Max, PostgreSQL 17.10), over the same documents before and after, so every scenario returned the same rows. Query-only criterion medians in ms, before → after, on the nested corpus (about 213 entries a document):

  scenario	10,000 rows	100,000 rows
  subtree/orders, default budget	9.48 → 5.71	8.77 → 5.46
  subtree_at/items ($.orders[*].items), default budget	12.95 → 8.21	10.92 → 7.18
  subtree/orders, walked out (budget 0)	22.97 → 10.92	24.57 → 11.35
  subtree_at/items, walked out (budget 0)	23.12 → 10.93	24.83 → 11.27
  subtree/user	3.90 → 2.38	3.99 → 2.45
  path_query/wildcard	2.24 → 1.64	1.80 → 1.41
  field_order/nested	4.81 → 3.81	5.23 → 4.12
  children/orders	1.63 → 1.54	1.64 → 1.49
  child_count/orders	1.62 → 1.53	1.66 → 1.52

  children and child_count moved only 6 to 9%. The report's explanation, not yet tested, is that a per-call fixed cost (detoasting the document and building the parent-tag map) dominates them, and this change does not touch it.

  Containment and field queries are unchanged within noise. The flat corpus read +7% to +13% on byte-identical operands, plans and indexes, and the native jsonb controls over unchanged plaintext drifted +5% to +19% in the same run, so this reads as machine noise rather than the format.

• Sizes:

  • Nested document: 113,458 → 85,157 characters (−25%); sv 94,324 → 66,023 (−30%).
  • Nested pg_column_size: 81,264 → 62,143 bytes.
  • Nested heap: 810 MB → 621 MB at 10,000 rows, 8,093 MB → 6,201 MB at 100,000.
  • GIN index unchanged (40 MB / 358 MB). GIN build 5 s at 10,000 rows; 58 → 65 s at 100,000, one sample.
  • Flat document: 2,346 → 2,136 characters; pg_column_size 2,452 → 2,250 bytes.

• Sizes with the ordering term opt-in (cipherstash/benches@cd9643d, "Fourth measurement"), each corpus re-sealed with the one path its scenarios order ($.age flat, $.company.salary nested), correctness 462 of 462 at both tiers:

  • Nested pg_column_size: 62,143 → 40,578 bytes (−35%); heap 621 → 408 MiB at 10,000 rows, 6,201 → 4,069 MiB at 100,000; GIN unchanged.
  • Flat pg_column_size: 2,250 → 1,596 bytes (−29%); heap 27.1 → 17.0 MiB at 10,000 rows. A flat document now sits under the TOAST threshold, so the flat heap moves into the main relation and the flat GIN grows 12% at 100,000 rows from the wider row spread. Query timings were not re-run.

• Correctness: a new benches task, check:v4:json_tree <N>, ran at both tiers. It decrypted every walk form for 25 random rows and compared each with the plaintext, and it compared the encrypted id sets with native jsonb for 10 needles per predicate. 462 passed, 0 failed, at both tiers.

• For the encodings commit: cargo nextest run -p stack-encrypt --all-features 751 passed; doctests 46 passed; clippy and rustdoc (-D warnings) clean; mise run wasm:wasi-check passed (base85-simd compiles for wasm32-wasip1 on its scalar path); mise run test:encryption:postgres passed against the v4 bundle built from the tree, including the json_tree oracle. Size (1,000 stored rows of each corpus from the Phase 3c tables, re-encoded field by field as the code now writes them, reloaded as jsonb, PostgreSQL 17.10, pg_column_size averaged after VACUUM FULL): nested 40,808 → 31,894 bytes (−22%), flat 1,596 → 1,398 bytes (−12%); wire characters nested 58,111 → 47,038, flat 1,419 → 1,224. The corpora were not re-ingested and no query re-timed for this commit.

Related

• Refs perf(eql, stack-encrypt): store the json_tree projection, walk by parent map, budget the subtree #1325, the base of this stack.
• Refs json_tree: the smaller performance findings from the first benchmarks #1324, whose item 4 (a nested document's size) this partly addresses: the stored document is 25% smaller. The encoding lever listed there is taken in 37e02ab42 (a further 22% off a nested document); the nonce lever is rejected (a caller-chosen nonce would weaken vitaminc's misuse resistance for a 7% saving; design doc Phase 3d), and -> (item 1) is 15 to 19% faster only because sv is shorter.

Review notes

• Start with the walk comment block in functions.sql and json_tree_subtree_at, then subtree_key_for in stack-encrypt/src/json/derive.rs, which decides what the client derives and what it gates.
• The one semantic subtlety is in DecryptInto<Value> for JsonSubtree: a d = 0 row means "the node the gates reached", so its value is returned, rather than a container assembled from the rows. A sealed-root fallback also comes back at d = 0, at j = 0, and is told apart by that.
• Trust is unchanged: only c is authenticated, through its AAD (the associated data the AEAD binds), and q was already what containment ran over. The w mask's binding to c is gone. A swapped ciphertext no longer breaks the walk on the server, but it still fails when the client opens the entry, because c is bound to s and its position j in the document.
• At rest the format leaks less: there are no stored positions to count children from.
• feat(stack-encrypt, eql): the JSON index and the json_tree EQL v4 domain family #1288's changeset still describes the format this PR replaces; it will sit beside this one in the same release's changelog, and this one says what superseded it. perf(eql, stack-encrypt): store the json_tree projection, walk by parent map, budget the subtree #1325's changeset is edited here, to carry the opt-in ordering paragraph.

What a query looks like to a user

Users never see selectors, tokens or gates. The SDK derives them from a path and a plaintext needle, and the only encrypted thing in the SQL text is one typed operand.

SQL, as the v4 bundle ships it, for a column profile of type public.eql_v4_json_tree:

-- containment, served by the GIN index; $1 is the encrypted needle
SELECT id FROM users WHERE profile @> $1::eql_v4.query_json_tree;

-- range at a path, served by a btree on the functional index; $sel is the path selector
SELECT id FROM users WHERE (profile -> $sel) >= $2::eql_v4.query_json_tree_leaf;
SELECT id FROM users ORDER BY eql_v4.ord_term(profile -> $sel);

-- one node, opens on the client
SELECT profile -> $sel FROM users WHERE id = 7;

-- a subtree: the token and the gates this PR introduces; rows open on the client into the value
SELECT e FROM users, eql_v4.json_tree_subtree_at(profile, $tok, $gates::text[]) e WHERE id = 7;

Rust, as stack-encrypt has it on this branch:

// The plan names the paths the index orders; nothing is ordered by default.
let options = JsonOptions::default().ordering(["$.age", "$.orders[*].total"])?;
let plan = Plan::value::<Value>().context("users/profile").encrypt_as(Json::new(options)).build()?;
let q = cipher.query(op::Contains, &json!({"orders": [{"id": 2}]})).on(&plan).await?;
let b = cipher.query(op::AtPath(op::Gte), &("$.age", 18)).on(&plan).await?;   // ordered: derives
// cipher.query(op::AtPath(op::Gte), &("$.name", "m")).on(&plan): refused, `$.name` is not ordered
let k = keyset.json_subtree_key(&"$.orders[*].items".parse()?, &options, column).await?;
// k.token() and k.gates() are the arguments of json_tree_subtree_at
let items: Vec<Value> = cipher.decrypt_as(JsonTreeSubtree::from_key(&k, rows), column).await?;

TypeScript through Drizzle, as the EQL v3 surface reads today; a v4 column keeps it and gains the walk, which has no adapter shape yet:

db.select().from(users).where(await ops.contains(users.profile, { orders: [{ id: 2 }] }))
db.select().from(users).where(await ops.selector(users.profile, "$.age").gte(18))
db.select().from(users).orderBy(ops.asc(ops.selector(users.profile, "$.age")))

Review fixes (2026-10-23)

The review is the comment above. The fixes are on this branch:

• 67b1f543e: the chain step binds the child's selector, H("t" ‖ t(parent) ‖ s ‖ LE32(o)), and a position gate is #n:<selector>. Without the selector, a position could reach an object member in rows whose node at the path is an object. eql_v4_internal.json_tree_child_token now takes (token, s, o).
• d72d9fe15: a path that names an array position is refused in JsonOptions::ordering, in the data plan's ordered, in an ordering query, and in a seal (TermError::JsonOrderingAtPosition).
• d267735af: a json_wire_decode fuzz target, and the fuzz crate's refreshed Cargo.lock.
• d3d7f764b, 151fd5d7c, 6d9ece2e7: the docs in types.sql, both CHANGELOGs, and the design doc's eight-byte p bound.

Two decisions from the owner followed the review, as separate commits:

• f1f27f218: this is option (c) for the walk budget. JsonSubtreeKey carries its path and builds the rows' wrapper: key.open(rows) in stack-encrypt, JsonTreeSubtree::from_key(&key, rows) in eql-bindings. From its gates the key decides whether the rows open below the path's node or at it, so a path-less open no longer compiles.
• 63bec8f71: the json module's plaintext is held under vitaminc's Protected. Node plaintexts are encoded straight into Protected<Vec<u8>>. Opened keys, scalars and documents stay in Protected<PlainJson> until they are handed to the caller. The sealed-root fallback's document is wiped once the path is selected from it.

Verification counts above predate these fixes. With them: cargo nextest run -p stack-encrypt --all-features 764 passed, and mise run test:encryption:postgres passed against PostgreSQL 17.10, including the new postgres_a_position_reaches_array_elements_only.

https://claude.ai/code/session_01N7bCqa3ZVJMcEE99RzVqEu

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

Run configuration

• Source mode: Auto
• Repository: Unavailable
• Branch: Unavailable
• File: No configuration file from this repository applied
• Commit: Unavailable
• Layers: Organization UI; Enforced overrides: Organization
• Review profile: CHILL
• Plan: Advanced
• Run ID: 733a1ea0-0bc6-481d-98ae-abaefd71d1e8

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Mutation testing (cargo-mutants, --in-diff, stack-auth + stack-encrypt)

caught	missed	unviable	timeout
97	0	37	0

cargo-mutants exited with no surviving mutants recorded. The run may not have completed cleanly; check the workflow run logs.

[changeset-bot]

🦋 Changeset detected

Latest commit: 9cc4c8a

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 12 packages

Name	Type
@cipherstash/eql	Minor
stash	Patch
@cipherstash/stack-prisma	Patch
@cipherstash/basic-example	Patch
@cipherstash/e2e	Patch
@cipherstash/prisma-example	Patch
@cipherstash/stack-drizzle	Patch
@cipherstash/stack-supabase	Patch
@cipherstash/stack	Patch
@cipherstash/wizard	Patch
@cipherstash/bench	Patch
@cipherstash/test-kit	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderdan]

The CI mutants gate failed on 63bec8f. Two mutants survived in the position arm of JsonPath::covers (path.rs:191). Once d72d9fe made ordered paths and ordering queries refuse positions, no test reached that arm any more, although covers is public and still matches positions. 1a86672 adds a_position_covers_its_own_position_only. Run locally over covers, cargo-mutants reports 9 mutants, 9 caught. #1336 is merged up to the new head (0d441a2).

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-23T13:34:29.940907Z	62f2132	Draft marked ready
🔒 Security Review	✅ Completed 2026-10-23T13:35:20.894313Z	62f2132	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 62f213233b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[coderdan]

Human review.

[coderdan]

It would be nice if these named types contained named wrapper types that represented the encoding that the value was in, instead of just a string, like a base64 wrapper type or a base85 wrapper type, et cetera, because that's really important to how these types are handled.

[coderdan]

Done in 14ccc86 (changeset wording in 5003d08). There was no encoding wrapper in eql-bindings to reuse: the v3 terms newtypes are named by role (Selector, OpeCllw, KeyHeader), not by encoding, and nothing else in the crate wraps base64 or base85. So there is a new encoding module with two #[serde(transparent)] newtypes:

• Base64Text: padded standard base64, as PostgreSQL's encode(x, 'base64') writes it.
• Base85Text: RFC 1924 base85, which no SQL function decodes.

JsonTreeSelector, JsonTreeTag and JsonTreeOrderingTerm now wrap Base64Text, and JsonTreeCiphertext wraps Base85Text. h was the v3 SteVec KeyHeader, whose docs describe base85 text that SQL never parses. That is wrong for v4, where h is base64 and the SQL decodes it for the iv and the sealed-root flag. It is now its own JsonTreeKeyHeader(Base64Text), and v3 is untouched.

Each newtype is still the bare string in JSON, and renders as string in TypeScript and JSON Schema. A unit test in encoding.rs pins all three. Deserializing still checks only that the value is a string. Stack Encrypt decodes the bytes and refuses text in the wrong encoding, and repeating that here would decode every field twice.

The blast radius was mechanical. The json_tree family is not in the catalog and none of its types is #[ts(export)], so no generated TypeScript, JSON Schema or Go output moves: mise run types:check and cargo test -p eql-codegen pass. The only code that read the inner strings was two assertions in the encryption test crate, which now call .as_str().

[coderdan]

Making the inner value public violates the contract.
A consumer of the base64 text type can't trust that the inner type is actually base64, because there's no guarantee that a caller upstream has just put a random string inside it.

Should have a constructor that encodes into the inner type. That should be the only way to create it.

[coderdan]

This needs some examples to explain what the layout is actually for

[coderdan]

Done in 021603c. The Layout trait's docs now say what a layout is for in short sentences and lead with a runnable example: a plan built with encrypt_with_layout(Json::new(options)), where the options order $.age, seals a JsonDocument with an ordering term on that leaf and answers op::AtPath(op::Gte) through the plan. The same target laid out by type, encrypt_into::<JsonDocument>(), uses the default options, which order no path, and the example shows that plan refusing the same query with TermError::JsonPathNotOrdered. The docs end by saying that the cipher's encrypt_as is a different layer: it seals one value as the type's own EncryptFrom does, with no plan and no options.

[coderdan]

What does ordered hold? String erases types.

[coderdan]

In memory it was already typed: IndexSpec::Json(JsonOptions), and JsonOptions::ordered is a BTreeSet<JsonPath>. The String was in the wire structs only. The writer rendered each path to text by hand, and the reader read Vec<String> and re-parsed each one in JsonWire's TryFrom through JsonOptions::ordering. So the type was lost one step before the serde boundary rather than at it, and I agree that was worse than it needed to be.

Changed in e10c93b. JsonPath now implements Serialize (its Display text, which is canonical and parses back) and Deserialize (through JsonPath::parse, refusing text that is not a path with the JsonPathError message). The writer's JsonOut holds &BTreeSet<JsonPath>, the reader's JsonOptionsWire holds BTreeSet<JsonPath>, and the TryFrom now checks only what a parse cannot, that an ordered path names no position (JsonOptions::check). The plan error's structured payload writes the set the same way. The wire form does not change: paths in canonical order, as text.

Tests: json_ordered_paths_round_trip_typed in dynamic/term.rs round-trips an IndexSpec::Json with two ordered paths (one with a quoted key) through serde and checks that a non-path and a positional path are refused. a_path_round_trips_through_serde_as_its_text in json/path.rs covers JsonPath alone. The existing wire tests in tests/json_index.rs pass unchanged.

[coderdan]

These docs are hard to follow. Can you simplify the language and include an example?

[coderdan]

Done in ba0c2a2 (the method has been encrypt_with_layout since 8930415). The method docs now say what it does and what the caller gets in two sentences ("Encrypt the value as layout does, with the layout's options. The plan's output is the layout's target."), lead with the example, and then say in one short paragraph when to use it rather than encrypt_into::<JsonDocument>(). The module docs at the top of plan/value.rs are now a list of the three ways to choose a one-value plan's output, one line each. The note about the cipher's encrypt_as moved to the Layout trait, which has its own example of the difference (021603c).

[coderdan]

Is opaque debug not suitable here? I guess the any type trick makes it impossible?

[coderdan]

OpaqueDebug would compile here, but I've kept the hand-written impls, because it does not fit what these types are.

#[derive(Debug)] is the one that cannot be used. It puts a T: Debug bound on the impl for every type parameter, and a target need not be Debug. It would also print the field as PhantomData<fn() -> T> rather than naming the target.

vitaminc's #[derive(OpaqueDebug)] (vitaminc-protected-derive 0.6.1, which JsonHeader and ValueFrame already use) does not have that problem. It only adds a Debug bound for a field marked #[non_sensitive], and it names the type with type_name::<Self>(), the same trick the manual impl uses, so the Any part is not what stops it. What it does is mask every field as "***" and mark the type with the OpaqueDebug trait, which says "this type holds something sensitive and its Debug hides it". Typed<T> holds nothing but a PhantomData, so Typed<JsonDocument> would print as stack_encrypt::plan::value::Typed<stack_encrypt::json::JsonDocument>("***"): a mask where nothing is hidden, and a claim the type has no reason to make. For Laid<X, T> the mask would hide the layout itself, Json { options: … }, which is index configuration (sealed_root and the ordered paths), not plaintext, and is what you want to see when debugging a plan. Marking both fields #[non_sensitive] would avoid the mask but print the target twice, once in the type name and once in PhantomData<…>. The manual impls print Typed<…JsonDocument> and Laid<…JsonDocument>(Json { … }), with no bound on T, so I left them as they are.

[coderdan]

Renamed the plan-layer ValueStart::encrypt_as(layout) to encrypt_with_layout(layout) in 8930415.

The verbs collided across layers. On the cipher, KeysetCipher::encrypt_as(&source, context) and EncryptInto::encrypt_into(&keyset) are one operation seen from two sides. On the plan, encrypt_into::<T>() lays a plan out by a target type, and encrypt_as(layout) laid it out by a layout value. So the same two names meant different things depending on the layer. The new name says what the method takes, and its rustdoc now says that the cipher's encrypt_as is unrelated.

The cipher-layer encrypt_as, encrypt_into, encrypt_into_with_context and encrypt_from are unchanged, and so is the plan-layer encrypt_into. The call sites in tests/json_index.rs and the EQL json_tree test, the changeset, the CHANGELOG entry and the json_tree design plan all use the new name. The rename is merged up into #1336.

https://claude.ai/code/session_01N7bCqa3ZVJMcEE99RzVqEu