|
| 1 | +# Value-kind and query-operator profiles |
| 2 | + |
| 3 | +`record-value-kinds-v1` and `record-query-operators-v1` enroll the existing |
| 4 | +Rust/Go fixtures in the conformance contract. They are experimental profiles |
| 5 | +of the cases those fixtures contain, not exhaustive type/operator certification. |
| 6 | +They use the plain record resolver (`NoTargets`), with public deterministic |
| 7 | +keys and no database or live credentials. |
| 8 | + |
| 9 | +The fixtures remain at their existing paths: |
| 10 | + |
| 11 | +- [`value_kinds.json`](../../packages/stack-encrypt/tests/fixtures/value_kinds.json) |
| 12 | +- [`query_operators.json`](../../packages/stack-encrypt/tests/fixtures/query_operators.json) |
| 13 | + |
| 14 | +Their [existing schema documentation](../../packages/stack-encrypt/tests/fixtures/README.md) |
| 15 | +continues to own the formats. No expected frames, ciphertexts, terms, verified |
| 16 | +pages or fetch limits are copied into this directory. |
| 17 | + |
| 18 | +[`v1/fixture-profiles.json`](v1/fixture-profiles.json) maps stable requirement IDs |
| 19 | +to the existing Rust test functions and Go tests that provide their evidence. |
| 20 | +It is an enrollment index, not another input corpus or a runtime capability |
| 21 | +negotiation format. The CI wiring test checks that its fixtures/tests exist, |
| 22 | +that each requirement is documented here, and that the conformance command |
| 23 | +selects every listed test. Both language implementations are mandatory for |
| 24 | +these profiles; Python and TypeScript remain pending. |
| 25 | + |
| 26 | +## Value-kind requirements |
| 27 | + |
| 28 | +The fixture represents int8, int16, uint8, uint16, int128, uint128, date, |
| 29 | +timestamp and decimal values. It includes the signed 128-bit minimum and |
| 30 | +unsigned 128-bit maximum. These are representative cases, not every boundary |
| 31 | +of every type. Values use the fixture's `type` and `text` with a frozen `frame`; |
| 32 | +128-bit integers must never pass through a floating-point JSON number. |
| 33 | + |
| 34 | +| Requirement ID | Required observation | Fixture evidence | |
| 35 | +|---|---|---| |
| 36 | +| `values.typed-frames` | The actual host value encodes to the exact frozen typed frame, preserving integer width, decimal scale and timestamp nanoseconds. | Every `values` entry | |
| 37 | +| `values.frozen-open` | The committed Rust record opens to those values and types, retaining decimal scale and timestamp precision. | `record` and `values` | |
| 38 | +| `values.stored-terms` | Fresh records round-trip and store the frozen equality/order terms. Queries for their values derive the corresponding stored terms. Randomized ciphertext bytes are not compared. | Every non-`c` output in `record`, under `plan` | |
| 39 | +| `values.normalized-queries` | Decimal queries differing only in trailing zeros and timestamp queries truncated to microseconds derive the stored equality and order terms, while the opened values retain their original precision. | Every `queries` entry and its field's order output | |
| 40 | + |
| 41 | +Rust additionally compares dynamic execution with typed term derivation and |
| 42 | +retains its wrong-width write refusal test. Go runs the real generated |
| 43 | +`testusers.ValueKinds` encrypt/decrypt and field-query methods, including its |
| 44 | +field-context substitution refusal. These assertions stay in their owning |
| 45 | +tests. The separate Go invalid-date/decimal/timestamp tests remain in the full |
| 46 | +Go suite; they are not claimed as shared fixture requirements here. |
| 47 | + |
| 48 | +## Query-operator requirements |
| 49 | + |
| 50 | +The fixture covers equality on text and uint32, scalar/range ordering on uint32 |
| 51 | +and float64, and probabilistic text matching. Its operators are `eq`, `lt`, |
| 52 | +`lte`, `gt`, `gte`, `between` and `matches`, in the combinations declared by |
| 53 | +the fixture. It does not claim every operator for every kind or index. |
| 54 | + |
| 55 | +| Requirement ID | Required observation | Fixture evidence | |
| 56 | +|---|---|---| |
| 57 | +| `queries.term-contract` | Derive the frozen operand bytes and metadata: operator, fidelity, index, domain, and scalar versus ordered low/high range shape. | Every `queries` entry | |
| 58 | +| `queries.match-verification` | Verify the complete page in input order, including matches, nonmatches and null; results agree with the frozen boolean vector. | `verify` | |
| 59 | +| `queries.fetch-limits` | Given the frozen match term, requested count and statistics, return the recorded bounded row count or explicit unbounded result. | Every `target_limit` entry | |
| 60 | + |
| 61 | +Rust compares the dynamic path with typed query chains, `MatchQuery::verify` |
| 62 | +and typed fetch sizing, and checks that the fixture contains both verification |
| 63 | +outcomes and both bounded/unbounded limits. Go exercises the record interface |
| 64 | +and generated query methods. Generated string-page verification omits null, |
| 65 | +which the record-interface test covers. Its existing SQL parameter conversion, |
| 66 | +empty-page, zero-query, inverted-range and floating-point ordering assertions |
| 67 | +remain in those selected tests. Wider operator refusal and secret-diagnostic |
| 68 | +tests remain in the full suites; this slice does not turn them into shared |
| 69 | +negative cases. |
| 70 | + |
| 71 | +## Running and maintaining the profiles |
| 72 | + |
| 73 | +`mise run test:conformance` selects the existing `value_kinds` and |
| 74 | +`query_operators` Rust binaries and the Go tests listed in the enrollment index, |
| 75 | +alongside the earlier profiles. Each existing test runs once per invocation; |
| 76 | +no wrapper test invokes another test a second time. The ordinary Rust and Go |
| 77 | +CI suites already run these tests, so enrollment adds no duplicate CI suite. |
| 78 | + |
| 79 | +When `STACK_CONFORMANCE_REQUIRED=1`, a missing deterministic guest fails the |
| 80 | +enrolled Go tests instead of skipping them. The aggregate command rejects both |
| 81 | +`STACK_CONFORMANCE_UPDATE` and `STACK_ENCRYPT_UPDATE_FIXTURES`, even when set to |
| 82 | +an empty value. The enrolled Rust fixture writers independently reject updates |
| 83 | +in required mode. Deliberate fixture maintenance remains available outside |
| 84 | +required mode through the existing documented regeneration commands. |
| 85 | + |
| 86 | +Keep requirement IDs stable. Add a new profile version for incompatible |
| 87 | +expectations, and review fixture regeneration explicitly. The enrollment |
| 88 | +index's `version` is its metadata format, not a production storage version. |
| 89 | + |
| 90 | +This slice consolidates the coverage inventory and execution selection, not |
| 91 | +the underlying test assertions. No test or frozen artifact is removed. Fresh |
| 92 | +cross-language artifact exchange remains the scalar profile's guarantee; |
| 93 | +these wider fixtures prove frozen Rust-to-Go opening, local round trips and |
| 94 | +term agreement, not fresh Go-to-Rust opening of every represented kind. |
| 95 | + |
| 96 | +Python and TypeScript should consume these same fixture paths and implement |
| 97 | +the listed observations through their own host values and public APIs. Their |
| 98 | +integer/decimal/time mappings and actual backends must be specified by those |
| 99 | +implementations. EQL domains, JSON operations, all-type boundary matrices, |
| 100 | +shared query refusals and supported-release matrices remain separate work. |
0 commit comments