|
| 1 | +# Stage 2A NoKV AuthorityStore candidate qualification (TEST ONLY) |
| 2 | + |
| 3 | +This directory contains an explicit, write-producing single-node conformance |
| 4 | +probe for the Stage 2A `NoKVAuthorityStore` candidate. It is **TEST ONLY**. |
| 5 | +LoopX does not select NoKV by importing this code, and a successful run does |
| 6 | +not connect a runtime shadow, run a multi-Agent canary, or flip an authority |
| 7 | +source. |
| 8 | + |
| 9 | +The integration priority remains: |
| 10 | + |
| 11 | +1. the native, full NoKV CLI as the primary operator and production surface; |
| 12 | +2. the NoKV Python SDK as the secondary programmable surface; and |
| 13 | +3. optional sidecars only as adapters around those surfaces, never as the main |
| 14 | + authority API. |
| 15 | + |
| 16 | +This probe intentionally exercises the current Python SDK bridge because it is |
| 17 | +the available raw byte-CAS seam. It always starts this checkout's reviewed |
| 18 | +`NoKVJsonLinesTransport` and `nokv_jsonl_helper.py`; it has no fake, skip, or |
| 19 | +"unverified but successful" CLI path. The helper admits exactly NoKV SDK |
| 20 | +`0.11.0` / Python API `1`, and the successful report repeats both values. |
| 21 | + |
| 22 | +## What it proves |
| 23 | + |
| 24 | +Against one **already existing** NoKV workbench, the probe starts three |
| 25 | +independent helper processes and verifies: |
| 26 | + |
| 27 | +- the selected tenant/goal path is initially absent and can be created; |
| 28 | +- the stored path generation advances from 1 to 2 under exact generation CAS; |
| 29 | +- after the generation-2 CAS lands, an injected response loss is reconciled |
| 30 | + from the durable authority envelope and operation receipt rather than from |
| 31 | + the lower-layer response; |
| 32 | +- every successful CAS response is accepted only after a fresh read proves the |
| 33 | + exact transaction in the current workbench incarnation; |
| 34 | +- two writes released together against generation 2 produce exactly one |
| 35 | + generation-3 winner and one typed conflict; |
| 36 | +- the losing operation does not acquire a durable receipt; and |
| 37 | +- a third, freshly opened transport reads the winning envelope, its complete |
| 38 | + three-entry history, the response-lost operation receipt, and the retained |
| 39 | + winner receipt. |
| 40 | + |
| 41 | +If the SDK, helper, workbench, backend, CAS, or independent readback cannot be |
| 42 | +proved, the process exits nonzero. The normal test suite uses deterministic |
| 43 | +fakes only to test this sequence and does **not** count as live evidence. |
| 44 | + |
| 45 | +The probe does not prove an atomic expected-incarnation publication fence, |
| 46 | +runtime shadow parity, a multi-Agent canary, authority promotion, HA, failover, |
| 47 | +restart recovery, capacity, or performance. NoKV generation can restart after |
| 48 | +workbench recreation, so the current adapter fails closed through authoritative |
| 49 | +post-write readback; preventing the stale-incarnation write itself requires a |
| 50 | +future provider primitive. The probe also does not create a workbench. A green |
| 51 | +run is Stage 2A single-node storage conformance evidence only. |
| 52 | + |
| 53 | +## Inputs |
| 54 | + |
| 55 | +Use a current NoKV Python environment. Keep the client configuration in an |
| 56 | +ignored local file; do not commit credentials. Static routing is valid for a |
| 57 | +single-node NoKV deployment—etcd is not required by this probe. The following |
| 58 | +shape is illustrative: |
| 59 | + |
| 60 | +```json |
| 61 | +{ |
| 62 | + "root_id": "00000000000000000000000000000000", |
| 63 | + "routing": { |
| 64 | + "kind": "static", |
| 65 | + "endpoint": "127.0.0.1:7412", |
| 66 | + "logical_shard_id": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", |
| 67 | + "object_namespace_id": "cccccccccccccccccccccccccccccccc", |
| 68 | + "placement_generation": 1, |
| 69 | + "owner_epoch": 1 |
| 70 | + }, |
| 71 | + "object_store": { |
| 72 | + "kind": "s3", |
| 73 | + "bucket": "qualification-bucket", |
| 74 | + "region": "us-east-1", |
| 75 | + "root": "/loopx-qualification", |
| 76 | + "endpoint": "http://127.0.0.1:9000", |
| 77 | + "access_key_id": "set-in-your-ignored-local-file", |
| 78 | + "secret_access_key": "set-in-your-ignored-local-file", |
| 79 | + "virtual_host_style": false, |
| 80 | + "skip_signature": false |
| 81 | + } |
| 82 | +} |
| 83 | +``` |
| 84 | + |
| 85 | +Configuration objects are exact-key contracts. An unknown top-level, routing, |
| 86 | +or object-store key fails before an SDK routing config, object-store config, or |
| 87 | +client is constructed. In particular, a misspelled explicit credential cannot |
| 88 | +silently fall through to NoKV's ambient provider chain. Intentionally omitted |
| 89 | +optional S3 credential fields retain the NoKV SDK's normal behavior. |
| 90 | + |
| 91 | +Pass only the absolute path to the Python executable that resolves the qualified |
| 92 | +NoKV SDK. The probe itself fixes the remaining argv to the interpreter isolation |
| 93 | +flag `-I` followed by the reviewed helper in this checkout; callers cannot |
| 94 | +supply a wrapper argument or an alternate helper path, and `PYTHONPATH`, |
| 95 | +`PYTHONHOME`, or user site-packages cannot redirect the `nokv` import away from |
| 96 | +that executable's own environment: |
| 97 | + |
| 98 | +```text |
| 99 | +/path/to/nokv-python-environment/bin/python |
| 100 | +``` |
| 101 | + |
| 102 | +Choose a fresh tenant/goal pair for every run. The probe refuses to overwrite |
| 103 | +an existing authority envelope and deliberately leaves its three-generation |
| 104 | +test envelope behind for inspection. Use a disposable qualification namespace |
| 105 | +or remove it later with the native NoKV CLI according to that environment's |
| 106 | +retention policy. |
| 107 | + |
| 108 | +## Run |
| 109 | + |
| 110 | +From the LoopX repository root: |
| 111 | + |
| 112 | +```bash |
| 113 | +node --no-warnings --experimental-strip-types \ |
| 114 | + examples/nokv-authority-store/live-qualification.ts \ |
| 115 | + --execute-live \ |
| 116 | + --config-json /path/to/ignored/nokv-client.json \ |
| 117 | + --python-executable /path/to/nokv-python-environment/bin/python \ |
| 118 | + --tenant-id qualification-tenant-20260902 \ |
| 119 | + --goal-id qualification-goal-20260902-01 \ |
| 120 | + --workbench existing-qualification-workbench |
| 121 | +``` |
| 122 | + |
| 123 | +`--execute-live` is mandatory and is checked before any helper starts. Exit 0 |
| 124 | +means every listed live check passed. Any unavailable, failed, ambiguous, |
| 125 | +unfenced, pre-existing, or unreadable state exits nonzero with a compact JSON |
| 126 | +reason; provider stderr, endpoints, credentials, and raw SDK errors are not |
| 127 | +copied into that result. A successful JSON report includes |
| 128 | +`"qualification_scope":"stage_2a_single_node_store_conformance"`, |
| 129 | +`"nokv_sdk_version":"0.11.0"`, and `"nokv_api_version":1`. The two version |
| 130 | +fields are the helper's admission constants: the helper refuses to open a client |
| 131 | +for any other SDK version or API version, so a successful report implies them, |
| 132 | +but they are not values read back from the NoKV server. The report is Stage |
| 133 | +2A/helper-admission evidence only, not runtime-shadow, canary, HA, or |
| 134 | +production-readiness evidence. |
0 commit comments