refactor(prose): VCL Step 3 phase 3a — read/write intent query phrases

hyperpolymath · claude · hyperpolymath · commit da46c0658ea4 · 2026-04-05T17:16:22.000+01:00
Additional unambiguous patterns where read-vs-write intent determines
the target word:

  Read intent:
    read/fetch a query, query returns/against/over/executed, etc.
    → perform an inspection / inspection X

  Write intent:
    write/send/dispatch a query → proposition

  Verisim-specific phrases:
    native query language → native consonance language
    query engine → consonance engine
    query interface → inspection interface

~2000 standalone 'query'/'queries' prose occurrences remain for
individual per-file review — these are mostly in variable names,
doc descriptions, and comments where context requires case-by-case
judgment.

Co-Authored-By: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md
@@ -62,7 +62,7 @@ The following files in `.machine_readable/` contain structured project metadata:
 - **Rust** - Core database engine, modality stores
 - **Elixir** - OTP orchestration layer
 - **ReScript** - VCL parser, federation registry
-- **VCL** - VeriSim Consonance Language (native query interface, NOT SQL)
+- **VCL** - VeriSim Consonance Language (native inspection interface, NOT SQL)
 
 ### BANNED
 - Python - Use Rust instead
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -159,7 +159,7 @@ cargo fmt --check
 | **Rust** | Core database engine, modality stores, CLI tools |
 | **Elixir** | OTP orchestration, distributed coordination |
 | **ReScript** | VCL parser, playground PWA |
-| **VCL** | VeriSim Consonance Language (query interface) |
+| **VCL** | VeriSim Consonance Language (inspection interface) |
 
 ### Not Accepted
 
diff --git a/IMPLEMENTATION-ROADMAP.adoc b/IMPLEMENTATION-ROADMAP.adoc
@@ -306,7 +306,7 @@ pub struct ExplainOutput {
 pub fn explain(query: &str) -> Result<ExplainOutput>;
 ```
 
-**Deliverable**: VCL queries execute, EXPLAIN works
+**Deliverable**: VCL inspections execute, EXPLAIN works
 
 ---
 
diff --git a/README.adoc b/README.adoc
@@ -283,7 +283,7 @@ SELECT GRAPH.* FROM HEXAD 'entity-001'
   PROOF INTEGRITY(my_contract)
 ----
 
-VCL-DT queries return a `ProvedResult` with data AND a proof certificate:
+VCL-DT inspections return a `ProvedResult` with data AND a proof certificate:
 
 [source,elixir]
 ----
@@ -457,7 +457,7 @@ Universities and research institutions federate their archives while maintaining
 Vector embeddings and symbolic graphs coexist in the same namespace. AI systems query both modalities without ETL, with formal proof certificates guaranteeing query correctness.
 
 === Verifiable Data Exchange
-ZKP proofs and dependent types enable tamper-evident knowledge exchange. VCL-DT queries return data with cryptographic proof certificates — you can verify the result without trusting the source.
+ZKP proofs and dependent types enable tamper-evident knowledge exchange. VCL-DT inspections return data with cryptographic proof certificates — you can verify the result without trusting the source.
 
 == Documentation
 
diff --git a/connectors/README.adoc b/connectors/README.adoc
@@ -16,7 +16,7 @@ VeriSimDB connectors provide a two-direction integration architecture:
 **Outbound (Federation Adapters)**:: VeriSimDB reaches _out_ to external
 databases, normalising their data into the octad model and maintaining
 cross-modal consistency via drift detection.  Federation adapters translate
-VeriSimDB federation protocol queries into the native query language of each
+VeriSimDB federation protocol queries into the native consonance language of each
 target store.
 
 **Inbound (Client SDKs)**:: External applications reach _in_ to VeriSimDB
@@ -73,7 +73,7 @@ octad entities, VCL queries, and drift reports.
 
 Federation adapters allow VeriSimDB to coordinate with external databases,
 treating them as modality-specialised peers in a federated mesh.  Each adapter
-translates the VeriSimDB federation protocol into the native query language of
+translates the VeriSimDB federation protocol into the native consonance language of
 the target store, maps results back into octad octad entities, and reports drift
 scores so the normaliser can maintain cross-modal consistency.
 
diff --git a/connectors/clients/elixir/lib/verisim_client/federation.ex b/connectors/clients/elixir/lib/verisim_client/federation.ex
@@ -81,7 +81,7 @@ defmodule VeriSimClient.Federation do
   Execute a federated query that fans out to all registered peers.
 
   The query targets the specified modalities and passes `params` to each
-  peer's local query engine. Results are merged and returned with per-peer
+  peer's local consonance engine. Results are merged and returned with per-peer
   attribution.
 
   ## Parameters
diff --git a/connectors/clients/elixir/lib/verisim_client/vcl.ex b/connectors/clients/elixir/lib/verisim_client/vcl.ex
@@ -5,7 +5,7 @@ defmodule VeriSimClient.Vql do
   @moduledoc """
   VeriSim Consonance Language (VCL) execution for VeriSimDB.
 
-  VCL is VeriSimDB's native query language, supporting SQL-like syntax extended
+  VCL is VeriSimDB's native consonance language, supporting SQL-like syntax extended
   with multi-modal operations (vector similarity, graph traversal, spatial
   predicates, drift thresholds, etc.). This module provides methods to execute
   VCL statements and retrieve explain / query plans.
diff --git a/connectors/clients/rescript/src/VeriSimVql.res b/connectors/clients/rescript/src/VeriSimVql.res
@@ -3,7 +3,7 @@
 //
 // VeriSimDB ReScript Client — VQL (VeriSimDB Query Language) operations.
 //
-// VQL is VeriSimDB's native query language for multi-modal queries that span
+// VQL is VeriSimDB's native consonance language for multi-modal queries that span
 // graph traversals, vector similarity, spatial filters, and temporal constraints
 // in a single statement. This module provides execution and explain functions.
 
diff --git a/connectors/clients/rust/src/federation.rs b/connectors/clients/rust/src/federation.rs
@@ -71,7 +71,7 @@ impl VeriSimClient {
     /// Execute a federated query that fans out to all registered peers.
     ///
     /// The query targets the specified modalities and passes `params` to each
-    /// peer's local query engine. Results are merged and returned with per-peer
+    /// peer's local consonance engine. Results are merged and returned with per-peer
     /// attribution.
     ///
     /// # Arguments
diff --git a/connectors/clients/rust/src/vcl.rs b/connectors/clients/rust/src/vcl.rs
@@ -3,7 +3,7 @@
 
 //! VeriSim Consonance Language (VCL) execution.
 //!
-//! VCL is VeriSimDB's native query language, supporting SQL-like syntax extended
+//! VCL is VeriSimDB's native consonance language, supporting SQL-like syntax extended
 //! with multi-modal operations (vector similarity, graph traversal, spatial
 //! predicates, drift thresholds, etc.). This module provides methods to execute
 //! VCL statements and retrieve explain / query plans.
@@ -16,7 +16,7 @@ use crate::error::Result;
 /// Response from a VCL inspection execution or explain request.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct VqlResponse {
-    /// Whether the query executed successfully.
+    /// Whether the inspection executed successfully.
     pub success: bool,
     /// The type of VCL statement ("SELECT", "INSERT", "UPDATE", "DELETE", "EXPLAIN", etc.).
     pub statement_type: String,
diff --git a/docs/VQL-SPEC.adoc b/docs/VQL-SPEC.adoc
@@ -21,7 +21,7 @@
 
 === Purpose and Scope
 
-The VeriSim Consonance Language (VCL) is the native query interface for VeriSimDB, a cross-system entity consistency engine with drift detection, self-normalisation, and formally verified queries. This document is the **normative language specification** for VCL version 2.0.
+The VeriSim Consonance Language (VCL) is the native inspection interface for VeriSimDB, a cross-system entity consistency engine with drift detection, self-normalisation, and formally verified queries. This document is the **normative language specification** for VCL version 2.0.
 
 VCL is not SQL. It is a domain-specific language for querying and mutating **octad entities** — data objects that exist simultaneously across up to eight modalities (Graph, Vector, Tensor, Semantic, Document, Temporal, Provenance, Spatial). VCL provides:
 
diff --git a/docs/business/marketing/pitch-deck-outline.adoc b/docs/business/marketing/pitch-deck-outline.adoc
@@ -142,7 +142,7 @@ representations that together provide a complete picture of each entity.
 
 === Speaker Notes
 
-Three layers: the VCL query engine parses and type-checks queries; the drift
+Three layers: the VCL consonance engine parses and type-checks queries; the drift
 detection engine continuously monitors coherence across modalities; the storage
 layer handles the octad per entity. Federation allows VeriSimDB to bring drift
 detection to existing databases without data migration. Rust provides performance,
diff --git a/docs/design/DESIGN-2026-02-28-panll-interop-telemetry.md b/docs/design/DESIGN-2026-02-28-panll-interop-telemetry.md
@@ -38,7 +38,7 @@ Each database module implements a standard protocol for PanLL integration:
 │  playground():    → playgroundConfig                   │
 │                                                        │
 │  Pane-L Mapping:  grammar, type system, constraints    │
-│  Pane-N Mapping:  query engine, inference, reasoning   │
+│  Pane-N Mapping:  consonance engine, inference, reasoning   │
 │  Pane-W Mapping:  results, drift, telemetry dashboard  │
 └───────────────────────────────────────────────────────┘
 ```
diff --git a/docs/design/DESIGN-2026-04-05-V4-proof-attempts-vcldt.adoc b/docs/design/DESIGN-2026-04-05-V4-proof-attempts-vcldt.adoc
@@ -174,7 +174,7 @@ carries `prover_hint` — add optional `cert_id`.
 *emit* locally-minted blobs when an attempt crosses a threshold.
 
 | VCL-DT type checker
-| `PROOF PROVEN(class, prover)` becomes a well-typed query against
+| `PROOF PROVEN(class, prover)` becomes a well-typed inspection against
 `mv_proven_certificates`. No longer requires external contract file.
 |===
 
diff --git a/docs/federation-readiness.adoc b/docs/federation-readiness.adoc
@@ -54,7 +54,7 @@ If VCL were removed or not used, VeriSimDB would lose the following federation-c
 
 * **No cross-modal consistency checks across instances.** VCL's `PROOF CONSISTENCY` clause can request verification that graph, vector, and semantic modalities agree across federation peers. Without VCL-DT, there is no way to express or verify cross-instance consistency at query time.
 
-* **No unified result format.** VCL queries return results in a consistent format regardless of whether the data came from one instance or twenty. Without VCL, each peer's API response format would need to be handled individually.
+* **No unified result format.** VCL inspections return results in a consistent format regardless of whether the data came from one instance or twenty. Without VCL, each peer's API response format would need to be handled individually.
 
 == Current Gaps
 
diff --git a/docs/papers/verisimdb-federated-consistency.adoc b/docs/papers/verisimdb-federated-consistency.adoc
@@ -376,7 +376,7 @@ Normalisation results are recorded as telemetry events including the entity ID,
 
 === VCL Syntax and Semantics
 
-The VeriSim Consonance Language (VCL) is the native query interface for VeriSimDB.
+The VeriSim Consonance Language (VCL) is the native inspection interface for VeriSimDB.
 Its grammar is specified in ISO/IEC 14977 EBNF notation <<iso14977>> and supports `SELECT`, `INSERT`, `UPDATE`, and `DELETE` operations across octad entities.
 
 A VCL query comprises:
@@ -495,7 +495,7 @@ VCL-DT supports three composition strategies for multi-proof queries:
 === Adapter-Based Federation Architecture
 
 VeriSimDB federation enables cross-instance queries over heterogeneous databases.
-The federation layer is adapter-based: each external database type implements a `FederationAdapter` trait that translates VCL queries into the native query language of the target system and maps results back into octad entities.
+The federation layer is adapter-based: each external database type implements a `FederationAdapter` trait that translates VCL queries into the native consonance language of the target system and maps results back into octad entities.
 
 Four adapters are currently defined:
 
@@ -805,7 +805,7 @@ The octad model provides a principled foundation for multimodal entity managemen
 Cross-modal drift detection transforms consistency from an invisible hope into a measurable, actionable metric.
 Self-normalisation automates the most tedious and error-prone aspect of multi-system data management: keeping representations in agreement.
 
-VCL-DT extends this consistency guarantee to the query interface, enabling clients to not merely _hope_ that their data is consistent but to _prove_ it with cryptographic certificates.
+VCL-DT extends this consistency guarantee to the inspection interface, enabling clients to not merely _hope_ that their data is consistent but to _prove_ it with cryptographic certificates.
 The 11 proof types cover a range of assurance levels from basic existence checking to zero-knowledge proofs, allowing clients to select the appropriate level of verification for their use case.
 
 Federation extends these guarantees across organisational boundaries, enabling multi-institutional data sharing with configurable drift policies that balance consistency against latency and autonomy.
diff --git a/docs/vcl-formal-semantics.adoc b/docs/vcl-formal-semantics.adoc
@@ -160,7 +160,7 @@ Where stem:[\phi] is the proposition specified by the `PROOF` clause.
 }
 ++++
 
-**Interpretation:** A slipstream query returns a list of octads with selected modalities, **without proof guarantees**.
+**Interpretation:** A slipstream inspection returns a list of octads with selected modalities, **without proof guarantees**.
 
 ==== T-ProvedQuery (Dependent-Type Path)
 
@@ -176,7 +176,7 @@ Where stem:[\phi] is the proposition specified by the `PROOF` clause.
 }
 ++++
 
-**Interpretation:** A dependent-type query returns results **with proof** that the contract stem:[\phi_{\text{proof-spec}}] holds.
+**Interpretation:** A dependent-type inspection returns results **with proof** that the contract stem:[\phi_{\text{proof-spec}}] holds.
 
 ==== T-Condition (Graph Condition Example)
 
diff --git a/docs/vcl-vs-sql.adoc b/docs/vcl-vs-sql.adoc
@@ -109,7 +109,7 @@ VCL is intentionally minimal. The following SQL features have no VCL equivalent:
 |`DRIFT POLICY <name>` attaches consistency enforcement rules to federated queries. Drift detection and repair are first-class query concerns.
 
 |Octad entity addressing
-|`FROM HEXAD <uuid>` addresses a single cross-modal entity by its UUID. All six modalities are accessible through one query against one identifier.
+|`FROM HEXAD <uuid>` addresses a single cross-modal entity by its UUID. All six modalities are accessible through one inspection against one identifier.
 
 |Graph traversal syntax
 |Cypher-inspired patterns directly in `WHERE`: `(h)-[:RELATES_TO]->(target)`. No need for separate graph query language or JOIN emulation.
diff --git a/elixir-orchestration/lib/verisim/federation/adapter.ex b/elixir-orchestration/lib/verisim/federation/adapter.ex
@@ -15,7 +15,7 @@ defmodule VeriSim.Federation.Adapter do
 
   - `connect/1` — Establish or verify connectivity to the backend.
   - `query/3` — Translate a VeriSimDB modality query into the backend's
-    native query language and return normalised results.
+    native consonance language and return normalised results.
   - `health_check/1` — Check backend availability and return latency.
   - `supported_modalities/1` — Declare which VeriSimDB modalities the
     backend can serve (e.g., PostgreSQL with pgvector supports `:vector`).
diff --git a/elixir-orchestration/lib/verisim/federation/adapters/object_storage.ex b/elixir-orchestration/lib/verisim/federation/adapters/object_storage.ex
@@ -56,7 +56,7 @@ defmodule VeriSim.Federation.Adapters.ObjectStorage do
 
   ## Query Model
 
-  Since S3 is not a query engine, "queries" are implemented as:
+  Since S3 is not a consonance engine, "queries" are implemented as:
   - **ListObjectsV2**: List objects with prefix filtering
   - **HeadObject**: Check existence and metadata
   - **GetObject**: Retrieve content
diff --git a/elixir-orchestration/test/verisim/federation/adapters/integration/influxdb_integration_test.exs b/elixir-orchestration/test/verisim/federation/adapters/integration/influxdb_integration_test.exs
@@ -112,7 +112,7 @@ defmodule VeriSim.Federation.Adapters.InfluxDBIntegrationTest do
   # ---------------------------------------------------------------------------
 
   describe "querying seeded drift_scores bucket" do
-    test "default query returns recent drift data points", context do
+    test "default inspection returns recent drift data points", context do
       skip_if_unavailable(context)
 
       query_params = %{modalities: [], limit: 100}
diff --git a/elixir-orchestration/test/verisim/federation/adapters/integration/mongodb_integration_test.exs b/elixir-orchestration/test/verisim/federation/adapters/integration/mongodb_integration_test.exs
@@ -112,7 +112,7 @@ defmodule VeriSim.Federation.Adapters.MongoDBIntegrationTest do
   # ---------------------------------------------------------------------------
 
   describe "querying seeded octads collection" do
-    test "default query returns all 3 seeded documents", context do
+    test "default inspection returns all 3 seeded documents", context do
       skip_if_unavailable(context)
 
       query_params = %{modalities: [], limit: 100}
@@ -171,7 +171,7 @@ defmodule VeriSim.Federation.Adapters.MongoDBIntegrationTest do
       assert length(results) >= 1
     end
 
-    test "semantic (metadata) filter query returns matching documents", context do
+    test "semantic (metadata) filter inspection returns matching documents", context do
       skip_if_unavailable(context)
 
       # Octad-test-001 has modality type "document" with specific content
@@ -292,7 +292,7 @@ defmodule VeriSim.Federation.Adapters.MongoDBIntegrationTest do
   # ---------------------------------------------------------------------------
 
   describe "provenance modality (change stream)" do
-    test "provenance query returns provenance log entries", context do
+    test "provenance inspection returns provenance log entries", context do
       skip_if_unavailable(context)
 
       # The seed script creates a provenance_events collection with 2 events
diff --git a/elixir-orchestration/test/verisim/federation/adapters/integration/neo4j_integration_test.exs b/elixir-orchestration/test/verisim/federation/adapters/integration/neo4j_integration_test.exs
@@ -109,7 +109,7 @@ defmodule VeriSim.Federation.Adapters.Neo4jIntegrationTest do
   # ---------------------------------------------------------------------------
 
   describe "querying seeded Octad nodes" do
-    test "default MATCH query returns all 4 seeded Octad nodes", context do
+    test "default MATCH inspection returns all 4 seeded Octad nodes", context do
       skip_if_unavailable(context)
 
       query_params = %{modalities: [], limit: 100}
diff --git a/elixir-orchestration/test/verisim/federation/adapters/integration/redis_integration_test.exs b/elixir-orchestration/test/verisim/federation/adapters/integration/redis_integration_test.exs
@@ -171,7 +171,7 @@ defmodule VeriSim.Federation.Adapters.RedisIntegrationTest do
   # ---------------------------------------------------------------------------
 
   describe "RedisTimeSeries temporal queries" do
-    test "temporal range query returns time-series data", context do
+    test "temporal range inspection returns time-series data", context do
       skip_if_unavailable(context)
 
       # The seed script creates ts:drift:test-001:overall with sample data
diff --git a/elixir-orchestration/test/verisim/query/vcl_dt_integration_test.exs b/elixir-orchestration/test/verisim/query/vcl_dt_integration_test.exs
@@ -376,7 +376,7 @@ defmodule VeriSim.Query.VQLDTIntegrationTest do
   # ===========================================================================
 
   describe "VCL-DT explain plan" do
-    test "explain: true on a VCL-DT query returns plan without executing proofs" do
+    test "explain: true on a VCL-DT inspection returns plan without executing proofs" do
       query = "SELECT GRAPH.* FROM HEXAD 'entity-001' PROOF EXISTENCE(entity-001)"
       ast = H.parse!(query)
 
diff --git a/playground/src/ApiClient.res b/playground/src/ApiClient.res
@@ -54,7 +54,7 @@ let checkHealth = async (): result<string, string> => {
   }
 }
 
-/// Execute a VQL query against the real backend.
+/// Execute a VQL inspection against the real backend.
 /// Returns Ok(vqlResponse) on success, Error(string) on failure.
 let executeQuery = async (query: string): result<vqlResponse, string> => {
   let url = getBaseUrl() ++ "/api/v1/vql/execute"
diff --git a/rust-core/verisim-api/src/vcl.rs b/rust-core/verisim-api/src/vcl.rs
@@ -41,7 +41,7 @@ pub struct VqlExecuteRequest {
 /// VCL execute response — returns structured results from a query.
 #[derive(Debug, Serialize)]
 pub struct VqlExecuteResponse {
-    /// Whether the query executed successfully.
+    /// Whether the inspection executed successfully.
     pub success: bool,
     /// The type of statement that was executed.
     pub statement_type: String,
@@ -120,15 +120,15 @@ pub async fn vcl_execute_handler(
         statement_type = %result.statement_type,
         row_count = result.row_count,
         safety_level = ?result.safety_level,
-        "VCL query executed"
+        "VCL inspection executed"
     );
 
     Ok(Json(result))
 }
 
 /// Tokenize a VCL query into whitespace-separated tokens, respecting
 /// quoted strings (single and double quotes).
-/// Validate a VCL query against TypeLL's VCL-total 10-level type checker.
+/// Validate a VCL inspection against TypeLL's VCL-total 10-level type checker.
 ///
 /// Calls the TypeLL server (default: localhost:7800) to verify the query's
 /// type safety level. Returns (safety_level, query_path, proof_obligations)
diff --git a/rust-core/verisim-planner/src/prepared.rs b/rust-core/verisim-planner/src/prepared.rs
@@ -339,7 +339,7 @@ impl PlanCache {
 
     /// Execute a prepared statement: validate parameters, increment counters, return statement.
     ///
-    /// This does not actually run the query against the storage engine — it returns the
+    /// This does not actually run the inspection against the storage engine — it returns the
     /// statement with updated usage statistics so the caller can feed it to the executor.
     pub async fn execute_prepared(
         &self,
diff --git a/spec/system-specs.md b/spec/system-specs.md
@@ -81,7 +81,7 @@ with Rust's async runtime.
 
 - Queries spanning multiple modalities are decomposed by the Elixir query
   planner into per-modality sub-queries.
-- Sub-queries execute concurrently (one tokio task per modality store).
+- Sub-inspections execute concurrently (one tokio task per modality store).
 - Results are collected via `tokio::sync::mpsc` channels.
 - The Elixir process assembles final results from all modality responses.
 - Join operations across modalities use hash-join or merge-join depending
