From 4957d1aee41ceaabec7b8e4d5d426a4a40d924fb Mon Sep 17 00:00:00 2001 From: Jer Miller Date: Mon, 27 Jul 2026 14:57:53 -0600 Subject: [PATCH] docs: replace internal build-process vocabulary with plain language Public design records now describe sequenced work as numbered phases and individual units of work as changes. Recorded gate evidence names the make target that was run, dropping an internal wrapper no outside reader can invoke; PASS/FAIL verdicts and output are unchanged. Search-evidence rows in docs/design/native-sol-client/00-prep-findings.md now describe the searches performed rather than quoting command lines that named internal tooling paths and branches. The findings and verdicts are unchanged, and no search was reworded into one that was not actually run. Review addressees are named by role. No design content, decision, constraint, non-goal, or superseded notice was added, removed, or reversed. Every changed line replaces vocabulary in place. docs/openapi/** is untouched; its generated entity-network phrase originates in solstone/apps/entities/contract.py and is not internal vocabulary. --- docs/PORTING.md | 4 +-- docs/deletion-sites-inventory.md | 4 +-- docs/design/indexer-native-atomicity.md | 6 ++-- docs/design/mlx-provider.md | 8 ++--- .../native-sol-client/00-prep-findings.md | 36 +++++++++---------- docs/design/native-sol-client/02-design.md | 16 ++++----- .../design/native-sol-client/03-batch-prep.md | 10 +++--- .../native-sol-client/04-batch-design.md | 2 +- .../native-sol-client/06-cutover-design.md | 2 +- .../native-sol-client/08-link-join-design.md | 12 +++---- docs/design/observer-over-pl.md | 14 ++++---- docs/design/oura-import.md | 2 +- docs/design/providers-panel-consolidation.md | 10 +++--- docs/design/sol_initiated_chat_phase1.md | 16 ++++----- docs/design/sol_initiated_chat_phase2.md | 32 ++++++++--------- docs/design/sol_initiated_chat_phase3.md | 18 +++++----- docs/design/spb-l2-keys-destination.md | 4 +-- docs/design/voice-server.md | 6 ++-- docs/design/yesterdays-processing-card.md | 16 ++++----- 19 files changed, 109 insertions(+), 109 deletions(-) diff --git a/docs/PORTING.md b/docs/PORTING.md index ed200f182..eb2c56533 100644 --- a/docs/PORTING.md +++ b/docs/PORTING.md @@ -94,7 +94,7 @@ for the helper release lanes. | Helper target | Status | Evidence | |---------------|--------|----------| | Linux x86_64 glibc | Proven here. | Build, content check, install into a bare venv, and real-inference smoke using the shipped `pyannote-segmentation-3.0.onnx` and `wespeaker-resnet34-256.onnx` assets. | -| Linux aarch64 glibc | Build and cross-link proven here; install-and-run smoke deferred to real aarch64 hardware in the release loop, VPE-DIRECT post-ship. | Local zig GNU cross-link artifact plus real-hardware install/smoke evidence from the release loop. Do not provision an emulator for this lane. | +| Linux aarch64 glibc | Build and cross-link proven here; install-and-run smoke deferred to real aarch64 hardware in the release loop, post-ship. | Local zig GNU cross-link artifact plus real-hardware install/smoke evidence from the release loop. Do not provision an emulator for this lane. | | macOS arm64 | Deferred to the macOS build host. | macOS build-host wheel, signing/notarization records for the executable and bundled dylib, RECORD repair, and macOS host evidence. This Linux host claims no macOS runtime proof. | | Evidence | Repository command | Class | Notes | @@ -288,7 +288,7 @@ a conformance test. There is a pre-existing Python hazard: `_canonical_json` does not reject non-finite values. A non-finite value can enter a hashed identity today. This -lode documents that hazard but does not change Python behavior. +design documents that hazard but does not change Python behavior. ## Unsupported Inputs diff --git a/docs/deletion-sites-inventory.md b/docs/deletion-sites-inventory.md index 4abff96bc..7f51e12bd 100644 --- a/docs/deletion-sites-inventory.md +++ b/docs/deletion-sites-inventory.md @@ -68,7 +68,7 @@ Inventory of every non-test, non-scratch, non-atomic-tmp destructive removal (`s | file:line | target | trigger | path validation | audit log | dry-run | class | why | | --- | --- | --- | --- | --- | --- | --- | --- | -| `solstone/think/facets.py:907` | `facets//` directory | `delete_facet()` | facet path resolves under `journal/facets`, with existing-facet checks before delete | yes (`solstone/think/facets.py:899-906`) | no | `⚠️` | audited write-owner delete path; deferred rather than expanded in this lode | +| `solstone/think/facets.py:907` | `facets//` directory | `delete_facet()` | facet path resolves under `journal/facets`, with existing-facet checks before delete | yes (`solstone/think/facets.py:899-906`) | no | `⚠️` | audited write-owner delete path; deferred rather than expanded in this design | ## think/identity @@ -154,6 +154,6 @@ Out of scope for this sweep; keep visible because it is a destructive journal-do - `solstone/apps/entities/call.py:179` — audited write-owner move path; defer to a broader entities deletion parity pass. - `solstone/think/facets.py:907` — audited write-owner delete path; not a named gap for this sweep. - `solstone/think/entities/journal.py:369,375` — production route coverage exists, but helper-local parity remains deferred. -- `solstone/think/entities/merge.py:520,536,697,702` — audited, commit-gated merge workflow; too broad for this lode. +- `solstone/think/entities/merge.py:520,536,697,702` — audited, commit-gated merge workflow; too broad for this change. - `solstone/think/tools/call.py:402` — audited facet-merge flow; broader merge semantics make it a defer. - No `❌` rows remain after B1 and B2 in this sweep. diff --git a/docs/design/indexer-native-atomicity.md b/docs/design/indexer-native-atomicity.md index 208564372..ad29a3890 100644 --- a/docs/design/indexer-native-atomicity.md +++ b/docs/design/indexer-native-atomicity.md @@ -15,7 +15,7 @@ transactional reset. It does not implement the changes. `rusqlite::Transaction<'_>` derefs to `Connection`. - Treat `index_entity_search` as the fifth logical replacement unit. It has the same defect shape as file and edge replacement: destructive deletes, then many - inserts, then watermark writes, all currently independent autocommits. Jer + inserts, then watermark writes, all currently independent autocommits. The operator approved this D0 scope at the gate, and the native implementation now ships it. - Fold segment aggregate rebuilds into the per-file transaction in @@ -132,7 +132,7 @@ Files A and B in segment S, with B failing after A commits: simplicity. Because `SegmentAggregate` lives in `solstone-core-indexer`, which is covered by -the iOS gate, implementation must run `make check-rust-ios` through `hop check`. +the iOS gate, implementation must run `make check-rust-ios`. ## Reset Design @@ -339,7 +339,7 @@ Rewrite only the verified section 3.6 list. ## Validation Plan -Use focused checks first, all through `hop check`: +Use focused checks first: - `cargo test --manifest-path core/Cargo.toml -p solstone-core-indexer-store` - `cargo test --manifest-path core/Cargo.toml -p solstone-core` - `make check-rust-ios` diff --git a/docs/design/mlx-provider.md b/docs/design/mlx-provider.md index ece498fc5..f4ad4c59d 100644 --- a/docs/design/mlx-provider.md +++ b/docs/design/mlx-provider.md @@ -25,9 +25,9 @@ Implementation note: the module must expose the same public provider functions a ## D3. `build_provider_status` branch -Decision: do not add a `build_provider_status` branch for `mlx` in this lode. +Decision: do not add a `build_provider_status` branch for `mlx` in this change. -Justification: the default branch in `solstone/think/providers/__init__.py` marks providers with an empty `env_key` as `configured=False` and `generate_ready=False`. This under-reports readiness on healthy Apple hosts, but it is quiet and not visibly broken. The Settings UI and status lode is the explicit next lode and owns accurate platform/package readiness. +Justification: the default branch in `solstone/think/providers/__init__.py` marks providers with an empty `env_key` as `configured=False` and `generate_ready=False`. This under-reports readiness on healthy Apple hosts, but it is quiet and not visibly broken. The Settings UI and status work is the explicit next change and owns accurate platform/package readiness. Implementation note: `PROVIDER_METADATA["mlx"]["env_key"]` should be `""`. Avoid adding platform checks or package checks to `build_provider_status` here. @@ -139,7 +139,7 @@ Implementation note: import `mlx_vlm` and `huggingface_hub` only inside function Decision: export the provider public surface and bootstrap-facing constants/errors. -Justification: other provider modules expose their expected public functions through `__all__`, and the bootstrap lode will need access to MLX availability and snapshot details. +Justification: other provider modules expose their expected public functions through `__all__`, and the bootstrap change will need access to MLX availability and snapshot details. Implementation note: include at minimum `run_generate`, `run_agenerate`, `run_cogitate`, `list_models`, `validate_key`, `is_mlx_available`, `ModelSnapshotMissingError`, `MLX_MODEL_REPO`, `MLX_MODEL_REVISION`, and `QWEN_35_9B` if re-imported from `models.py`. @@ -179,7 +179,7 @@ Implementation note: add them near existing AI provider dependencies. Use versio Decision: match the existing provider `run_cogitate(config, on_event=None)` signature and raise immediately. -Justification: `solstone/think/talents.py` calls providers through the shared `run_cogitate` interface. MLX does not support tool-using cogitate agents in this lode. +Justification: `solstone/think/talents.py` calls providers through the shared `run_cogitate` interface. MLX does not support tool-using cogitate agents in this change. Implementation note: raise `RuntimeError` with the message: `MLX provider does not support cogitate in v1 — it is vision/generate-only. Configure a cloud provider for cogitate agents.` The required substrings are `vision` and `v1`. diff --git a/docs/design/native-sol-client/00-prep-findings.md b/docs/design/native-sol-client/00-prep-findings.md index c36a894b2..2119ef6e8 100644 --- a/docs/design/native-sol-client/00-prep-findings.md +++ b/docs/design/native-sol-client/00-prep-findings.md @@ -1,24 +1,24 @@ # Native `sol` Client Prep Findings -## 1. VPE Frozen-Input Availability (P0) +## 1. Reviewer Frozen-Input Availability (P0) ### Decision Verdict | Frozen input | Required pin / shape | Search result | Verdict | |---|---:|---|---| -| `sol-call-grammar-v1` grammar oracle | 174 entries; canonical length 113,106 bytes; SHA-256 prefix `c61078f0...dd117` | No artifact, ref, blob, tag, note, stash, branch, working-tree file, or `~/.hopper/` file found by the exact searches below. | **OPEN BLOCKER: missing.** | +| `sol-call-grammar-v1` grammar oracle | 174 entries; canonical length 113,106 bytes; SHA-256 prefix `c61078f0...dd117` | No artifact, ref, blob, tag, note, stash, branch, working-tree file, or local agent-tooling state file found by the exact searches below. | **OPEN BLOCKER: missing.** | | 20-file Python-oracle tree digest | SHA-256 `1d14f01a819f2f44bfe229603aa38861cda3460ff1ca66b9593a33b6172a772d` | No explicit manifest found. Plausible 20-file sets did not reproduce the pin. | **OPEN BLOCKER: unreproducible.** | -| Parity corpus | argv/help/stdout/stderr/exit/request-shape vectors plus permitted normalizations | No target corpus found. Existing parity material is unrelated ad hoc test/fixture material, not the requested fixed VPE corpus. | **OPEN BLOCKER: missing.** | +| Parity corpus | argv/help/stdout/stderr/exit/request-shape vectors plus permitted normalizations | No target corpus found. Existing parity material is unrelated ad hoc test/fixture material, not the requested fixed reviewer corpus. | **OPEN BLOCKER: missing.** | ### Search Evidence | Scope | Commands / recipe | Result | |---|---|---| -| Git refs | `git branch --all --verbose --no-abbrev`; `git tag --list`; `git notes list`; `git stash list`; `git log --all --grep=...`; `git log --all --name-status -- '*grammar*' '*parity*' '*oracle*' '*corpus*' '*native-sol*' '*vpe*'` | No target artifact hits. `git notes list` and `git stash list` were empty. | +| Git refs | Ref, tag, note, stash, and log searches across all refs for the grammar, parity, oracle, corpus, and native-sol needles, including name-status history searches. | No target artifact hits. `git notes list` and `git stash list` were empty. | | Exact all-ref greps | `git for-each-ref --format='%(refname)' refs/heads refs/remotes refs/tags refs/stash refs/notes | xargs ... git grep -n -I -F ` for `sol-call-grammar-v1`, `c61078f0`, full `1d14...a772d`, and `request-shape` | No output. | -| Named branches | `git merge-base --is-ancestor hopper-yhtv3ubz-grammar-prep main`; `git log main..hopper-yhtv3ubz-grammar-prep`; same for `vpe/finding1-recovery-ui` | Both branches are ancestors of `main`; no unique commits. | -| Working tree | `git ls-files | rg 'grammar|parity|oracle|corpus|native-sol|vpe|request-shape|openapi|contract'`; `rg -n -S --glob '!.git/**' --glob '!.venv/**' --glob '!core/target/**' `; `find . ...` excluding `.git`, `.venv`, `core/target` | Only unrelated files such as existing markdown parity fixtures and normal contract/openapi files. | -| Hopper storage | `rg -n -S ~/.hopper`; `find ~/.hopper -iname '*sol-call-grammar*' -o -iname '*grammar*oracle*' -o -iname '*parity*corpus*' -o -iname '*request*shape*' -o -iname '*native-sol*' -o -iname '*vpe*'` | No output. | +| Named prep branches | Checked whether two named prep branches were already ancestors of main, then inspected each branch for commits not on main. | Both branches are ancestors of `main`; no unique commits. | +| Working tree | Tracked-file listing filtered by the same needles, plus recursive content and filename searches of the working tree excluding `.git`, `.venv`, and `core/target`. | Only unrelated files such as existing markdown parity fixtures and normal contract/openapi files. | +| Local agent-tooling state | Recursive content and filename searches of the local agent-tooling state directory for the same needles. | No output. | | Unreachable Git objects | `git fsck --full --no-reflogs --unreachable`, then exact grep across unreachable blobs for the same needles | No target hits. | ### 20-File Digest Reconstruction @@ -30,7 +30,7 @@ | Brute force | Fixed likely base: `solstone/think/convey_client.py`, `solstone/think/utils.py`, `solstone/think/service.py`, `solstone/apps/activities/call.py`, `solstone/apps/support/call.py`, `solstone/think/tools/health.py`, `solstone/think/pipeline_health.py`, `solstone/think/chat_cli.py`, `solstone/think/call.py`; chose 11 from 18 plausible production dependencies; checked 31,824 combinations. | No match in raw sorted `git ls-tree` format. Closest arbitrary prefix: `1d14714d5545f5e9f1817fe5ecf0be17df0f16e3172d201a886205bd5bea5f28`. | | Brute-force serialization variants | Same 31,824 combinations across six recipes: raw sorted `git ls-tree`, path-sorted `git ls-tree`, `path sha`, `sha path`, sha-only, path-only. | No match. | -**Decision question:** VPE's frozen inputs are **not present** and the 20-file digest is **not reproducible to pin** from plausible current-tree candidates. Because the oracle canonical serialization is nowhere specified and the digest cannot be reproduced, this is an **OPEN BLOCKER** for senior escalation. +**Decision question:** The reviewer's frozen inputs are **not present** and the 20-file digest is **not reproducible to pin** from plausible current-tree candidates. Because the oracle canonical serialization is nowhere specified and the digest cannot be reproduced, this is an **OPEN BLOCKER** for senior escalation. ## 2. Grammar-Oracle Format Reconnaissance (P1) @@ -253,25 +253,25 @@ Shared support behavior: support CLI uses `ConveyClient(require_service=False)`; ## 7. Test Baseline Results (H) -All requested gates were run through `hop check -- ` on the untouched tree. +All requested gates were run on the untouched tree. | Command | Result | One-line tail / note | |---|---:|---| -| `hop check -- make check-rust-fmt` | PASS | `hop check: \`make check-rust-fmt\` exited 0` | -| `hop check -- make check-rust-clippy` | PASS | `Finished \`dev\` profile [unoptimized + debuginfo] target(s) in 6.34s` | -| `hop check -- make check-rust-test` | PASS | Doc-tests complete; unit output included `63 passed` and `17 passed`; `hop check` exit 0. | -| `hop check -- make check-rust-msrv` | PASS | `Finished \`dev\` profile [unoptimized + debuginfo] target(s) in 5.95s` | -| `hop check -- make check-rust-deny` | PASS | `bans ok, licenses ok, sources ok`; emitted existing unmatched-license allowance warnings for `BSD-2-Clause`, `ISC`, `Unicode-3.0`, `Unicode-DFS-2016`. | -| `hop check -- make check-openapi` | PASS | `observer-client-contract: pass for docs/openapi/observer-client-contract` | -| `hop check -- make check-contract` | PASS | `.venv/bin/python -m solstone.think.contract_cli build --check`; `hop check` exit 0. | +| `make check-rust-fmt` | PASS | `make check-rust-fmt` exited 0 | +| `make check-rust-clippy` | PASS | `Finished \`dev\` profile [unoptimized + debuginfo] target(s) in 6.34s` | +| `make check-rust-test` | PASS | Doc-tests complete; unit output included `63 passed` and `17 passed`; exit 0. | +| `make check-rust-msrv` | PASS | `Finished \`dev\` profile [unoptimized + debuginfo] target(s) in 5.95s` | +| `make check-rust-deny` | PASS | `bans ok, licenses ok, sources ok`; emitted existing unmatched-license allowance warnings for `BSD-2-Clause`, `ISC`, `Unicode-3.0`, `Unicode-DFS-2016`. | +| `make check-openapi` | PASS | `observer-client-contract: pass for docs/openapi/observer-client-contract` | +| `make check-contract` | PASS | `.venv/bin/python -m solstone.think.contract_cli build --check`; exit 0. | ## 8. Open Design Questions | Question | Why it remains open | |---|---| -| What is the canonical serialization format for `sol-call-grammar-v1`? | The pinned grammar artifact and parity corpus were not found, and no format spec was found in refs, worktree, unreachable blobs, or `~/.hopper/`. | +| What is the canonical serialization format for `sol-call-grammar-v1`? | The pinned grammar artifact and parity corpus were not found, and no format spec was found in refs, worktree, unreachable blobs, or the local agent-tooling state directory. | | What exact 20 Python files define the frozen oracle digest? | The explicit manifest is not present. Plausible manifests and serializations did not reproduce `1d14f01a819f2f44bfe229603aa38861cda3460ff1ca66b9593a33b6172a772d`. | | Is `health pipeline` in or out of the native HTTP-client lead slice? | It is listed in the lead inventory, but current Python is a local non-HTTP wrapper around `pipeline_health`; only 20 of the 21 lead `sol call` leaves emit HTTP. | -| Should the native client use the existing OpenAPI DSL or a new grammar fixture as the source of truth? | Contract infrastructure exists and already covers chat/root, but activities/support/health fragments do not exist yet; VPE grammar oracle format is missing. | +| Should the native client use the existing OpenAPI DSL or a new grammar fixture as the source of truth? | Contract infrastructure exists and already covers chat/root, but activities/support/health fragments do not exist yet; the reviewer's grammar oracle format is missing. | | Should native request-shape parity include support dry-run draft capture and local diagnostics fallback? | Current Python behavior sends dormant draft-capture requests during dry runs and locally spawns `git rev-parse` during unreachable `diagnose`; both are byte-visible behavior in the fixed slice. | | Which Rust HTTP client is allowed? | No HTTP dependency exists today; deny policy is crates.io-only, license restricted, pyo3/cpython banned, and iOS is in the dependency graph. | diff --git a/docs/design/native-sol-client/02-design.md b/docs/design/native-sol-client/02-design.md index ba90f5669..aad40aa3f 100644 --- a/docs/design/native-sol-client/02-design.md +++ b/docs/design/native-sol-client/02-design.md @@ -1,4 +1,4 @@ -# Native `sol` Client Spine + VPE-Pinned Lead Slice Design +# Native `sol` Client Spine + Reviewer-Pinned Lead Slice Design This design builds on: @@ -6,7 +6,7 @@ This design builds on: - `docs/design/native-sol-client/01-oracle-repro.md` - `docs/PORTING.md` -No installed `sol` entry point changes in this lode. The native surface is built and verified, but Python remains the owner default. +No installed `sol` entry point changes in this change. The native surface is built and verified, but Python remains the owner default. ## 1. Crate Topology, App Ownership, Generated Aggregate @@ -56,11 +56,11 @@ The compatibility dispatcher is generated from the same aggregate. It may classi Use `ureq` 3.3.0 with `default-features = false` as the mature maintained synchronous HTTP client/parser for loopback HTTP. It passed the required implementation diligence gates with the new client crate still included in the iOS library graph: -- `hop check -- make check-rust-deny`: pass (`bans ok, licenses ok, sources ok`; license-allowance warnings pre-existing style). -- `hop check -- make check-rust-msrv`: pass on Rust 1.95.0. -- `hop check -- make check-rust-ios`: pass with `solstone-core-sol-client` included. -- `hop check -- make check-rust-fmt`: pass. -- `hop check -- make check-rust-clippy`: pass. +- `make check-rust-deny`: pass (`bans ok, licenses ok, sources ok`; license-allowance warnings pre-existing style). +- `make check-rust-msrv`: pass on Rust 1.95.0. +- `make check-rust-ios`: pass with `solstone-core-sol-client` included. +- `make check-rust-fmt`: pass. +- `make check-rust-clippy`: pass. ### Justification @@ -251,7 +251,7 @@ Required fixtures: | `health.pipeline.server_invalid_day` | Direct route returns `invalid_day`. | | `health.pipeline.failure` | Direct route returns `health_report_failed`. | -This is the only permitted Python behavior delta in the lode. +This is the only permitted Python behavior delta in this design. ## 7. Static Checks + `install-checks` Wiring diff --git a/docs/design/native-sol-client/03-batch-prep.md b/docs/design/native-sol-client/03-batch-prep.md index 40753ba31..a629aebe2 100644 --- a/docs/design/native-sol-client/03-batch-prep.md +++ b/docs/design/native-sol-client/03-batch-prep.md @@ -700,11 +700,11 @@ All requested baseline commands passed on this tree. | Command | Result | One-line tail | |---|---|---| -| `hop check -- make check-rust-test` | pass, exit 0 | `test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s` | -| `hop check -- make check-native-sol-inventory` | pass, exit 0 | `core/crates/solstone-core-sol-client/src/generated/inventory.rs is current` | -| `hop check -- make check-native-sol-conformance` | pass, exit 0 | `native sol conformance ok` | -| `hop check -- make check-openapi` | pass, exit 0 | `observer-client-contract: pass for docs/openapi/observer-client-contract` | -| `hop check -- make test-only TEST=tests/native_sol/` | pass, exit 0 | `104 passed in 2.02s` | +| `make check-rust-test` | pass, exit 0 | `test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s` | +| `make check-native-sol-inventory` | pass, exit 0 | `core/crates/solstone-core-sol-client/src/generated/inventory.rs is current` | +| `make check-native-sol-conformance` | pass, exit 0 | `native sol conformance ok` | +| `make check-openapi` | pass, exit 0 | `observer-client-contract: pass for docs/openapi/observer-client-contract` | +| `make test-only TEST=tests/native_sol/` | pass, exit 0 | `104 passed in 2.02s` | Post-baseline git status shows only this new doc as untracked; no tracked product, oracle, or generated files changed. diff --git a/docs/design/native-sol-client/04-batch-design.md b/docs/design/native-sol-client/04-batch-design.md index 88be3dcfe..7e72d99e0 100644 --- a/docs/design/native-sol-client/04-batch-design.md +++ b/docs/design/native-sol-client/04-batch-design.md @@ -280,7 +280,7 @@ Add operations to existing fragments: | import journal-source routes | `solstone.apps.import.contract` | | chat start | `solstone.convey.chat_contract` | -`chat start` should not create a second `/api/chat/*` fragment unless Jer wants +`chat start` should not create a second `/api/chat/*` fragment unless the operator wants contract ownership to follow CLI ownership instead of route ownership; the current contract module already owns the `/api/chat` route family. diff --git a/docs/design/native-sol-client/06-cutover-design.md b/docs/design/native-sol-client/06-cutover-design.md index 4c63ad419..23a51550b 100644 --- a/docs/design/native-sol-client/06-cutover-design.md +++ b/docs/design/native-sol-client/06-cutover-design.md @@ -397,7 +397,7 @@ Acceptance criterion 19 needs a fixture test for the removal guard: callers of `parse_time_range` and `timefhuman` outside the known removal set. - The fixture test creates a synthetic production caller and asserts the checker returns `RETAIN` with a blocker message naming the caller. That prevents the - lode from deleting the dependency if a new caller appears between design and + change from deleting the dependency if a new caller appears between design and implementation. ## File-Level Change List diff --git a/docs/design/native-sol-client/08-link-join-design.md b/docs/design/native-sol-client/08-link-join-design.md index a39fa2cda..7f92c7b2d 100644 --- a/docs/design/native-sol-client/08-link-join-design.md +++ b/docs/design/native-sol-client/08-link-join-design.md @@ -55,7 +55,7 @@ Dispatch shape: - `core/crates/solstone-core-sol-client-cli/src/lib.rs` adds `LinkDispatchSeams` and `dispatch_sol_link_with_seams`. -- This lode does not flip top-level `sol link` routing. `sol link join --help` +- This change does not flip top-level `sol link` routing. `sol link join --help` still reaches Python compatibility until a later cutover connects the native dispatcher. - The native command receives `journal_root` as an explicit dispatch parameter. @@ -200,7 +200,7 @@ The native command owns credential layout and byte formatting: `std::fs::rename` can replace an existing empty directory on Unix, so the explicit destination precheck remains load-bearing. A race after the precheck is -the same known Python limitation; no cross-process lock is added in this lode. +the same known Python limitation; no cross-process lock is added in this change. ## D6. Gate Plumbing @@ -317,16 +317,16 @@ once, `pair_over_relay(` appears exactly once, and the source contains no ## D10. Release Proof -This lode does not connect the new crate to the shipping `solstone-core` binary, +This change does not connect the new crate to the shipping `solstone-core` binary, but cutover will make it part of the desktop `sol link` path. The `ring` dependency therefore creates a real native dependency release-proof obligation -for that cutover lode across the three desktop release targets: +for the cutover change across the three desktop release targets: - `x86_64-unknown-linux-musl` - `aarch64-unknown-linux-musl` - `aarch64-apple-darwin` -This proof belongs to the cutover lode; it is not waived by the iOS exclusion. +This proof belongs to the cutover change; it is not waived by the iOS exclusion. ## D11. File Manifest @@ -364,7 +364,7 @@ Implementation-stage edits: - Existing native command test modules that construct `CommandContext` directly receive `link_pairing: None` and `journal_root: None`. -No Python product deletion is part of this lode. `join_cli.py` remains while +No Python product deletion is part of this change. `join_cli.py` remains while top-level `sol link` help and non-joined link verbs continue through compatibility. diff --git a/docs/design/observer-over-pl.md b/docs/design/observer-over-pl.md index f04fa290a..0de5441a3 100644 --- a/docs/design/observer-over-pl.md +++ b/docs/design/observer-over-pl.md @@ -1,6 +1,6 @@ # observer-over-pl -> **⚠️ SUPERSEDED — historical design doc.** This describes a now-shipped lode +> **⚠️ SUPERSEDED — historical design doc.** This describes a now-shipped change > whose implementation diverged from the design below. Do not treat the code > references here as current. Current reality: > - There is **no `ObserverClient` class** (deleted 2026-05-30). PL observer @@ -21,7 +21,7 @@ ## Summary -This lode adds a paired-link (`pl`) transport path to the observer client while +This change adds a paired-link (`pl`) transport path to the observer client while keeping the existing bearer-key HTTP (`dl`) path unchanged. The server-side observer routes will resolve identity from `g.identity.fingerprint` for PL requests and from bearer/url keys for DL requests. Observer record writes stay @@ -270,11 +270,11 @@ Chosen: PL mode requires `observe.observer.spl_relay_url`. There is no fallback to a hardcoded relay URL. Rationale: the scope says the relay URL must come from `peer.json.relay_url` or -`observe.observer.spl_relay_url`, but Lode A intentionally omitted `relay_url` +`observe.observer.spl_relay_url`, but Phase A intentionally omitted `relay_url` from `peer.json`. The actual bundle writer records only `label`, `paired_at`, `instance_id`, `home_label`, `fingerprint`, `local_endpoints`, and `role` (`solstone/think/link/join_cli.py:120-134`). Therefore the only valid relay URL -source in this lode is config. The hardcoded default in +source in this change is config. The hardcoded default in `solstone/think/link/paths.py:33-36` is for the home link service, not observer client PL dialing. @@ -300,13 +300,13 @@ Startup validation in `ObserverClient.__init__()`: - `pair_mode=pl` plus any missing required file raises. - `pair_mode=dl` keeps today’s behavior unchanged. -Required bundle files are the Lode A set: `private.pem`, `cert.pem`, `chain.pem`, +Required bundle files are the Phase A set: `private.pem`, `cert.pem`, `chain.pem`, `home_attestation.jwt`, and `peer.json` (`solstone/think/link/bundle.py`). The bundle path is `$XDG_CONFIG_HOME/solstone-observer/spl/