refactor(vocabulary): align graph-facing terminology (#534)

* test(vocabulary): guard public terminology surfaces

* refactor(vocabulary): align graph-facing terminology

* ci(vocabulary): bound cold public API guard

Author: aaltshuler

.github/branch-protection.json

@@ -5,6 +5,7 @@
     "contexts": [
       "Classify Changes",
       "Check AGENTS.md Links",
+      "Graph Vocabulary Guard",
       "Test omnigraph-server --features aws",
       "Format (rustfmt)",
       "Lint (clippy)"

.github/workflows/ci.yml

@@ -97,6 +97,126 @@ jobs:
       - name: Verify AGENTS.md ↔ docs/ cross-links
         run: bash scripts/check-agents-md.sh
 
+  graph_vocabulary_guard:
+    name: Graph Vocabulary Guard
+    # Required PR context: keep this job independent of the documentation-only
+    # classifier so it always reports. The review-owned inventory protects the
+    # OpenAPI, Rust presentation-string, user-doc, and public-Rust surfaces.
+    runs-on: ubuntu-latest
+    # A cold default + relevant all-features rustdoc pass over all seven public
+    # library crates is substrate-sized. The first hosted run completed the
+    # public-Rust step in 39 minutes, while the larger breaking-contract tree
+    # was still compiling when a 45-minute whole-job bound cancelled it. Keep
+    # current/base targets isolated for correctness and retain a finite cold-run
+    # ceiling; the pinned-tool and build-target caches make warm runs cheaper.
+    timeout-minutes: 75
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout source and comparison history
+        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1
+        with:
+          # `check` reads both the inventory and openapi.json from the exact
+          # comparison commit. A shallow checkout could turn that proof into a
+          # false missing-base failure.
+          fetch-depth: 0
+
+      - name: Install pinned toolchain
+        run: rustup toolchain install
+
+      - name: Resolve vocabulary comparison base
+        id: comparison_base
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          PR_BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          PUSH_BEFORE_SHA: ${{ github.event.before }}
+          REF_TYPE: ${{ github.ref_type }}
+        run: |
+          set -euo pipefail
+
+          zero_sha=0000000000000000000000000000000000000000
+          if [[ "$EVENT_NAME" == "pull_request" ]]; then
+            base="$PR_BASE_SHA"
+          elif [[ "$EVENT_NAME" == "push" && "$REF_TYPE" != "tag" && "$PUSH_BEFORE_SHA" != "$zero_sha" ]]; then
+            base="$PUSH_BEFORE_SHA"
+          else
+            # Tag creation commonly reports an all-zero `before`, while a
+            # manual run has no event base. Compare both with the checked-out
+            # commit's first parent rather than inventing a mutable branch tip.
+            base="$(git rev-parse "${GITHUB_SHA}^")"
+          fi
+
+          if [[ -z "${base:-}" || "$base" == "$zero_sha" ]]; then
+            echo "::error::unable to resolve a vocabulary comparison base"
+            exit 1
+          fi
+          git cat-file -e "${base}^{commit}"
+          echo "sha=$base" >> "$GITHUB_OUTPUT"
+
+      - name: Install public-Rust system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y protobuf-compiler libprotobuf-dev
+
+      - name: Restore pinned public-Rust tooling
+        id: public_rust_tool_cache
+        uses: actions/cache@5a3ec84eff668545956fd18022155c47e93e2684 # v4.2.3
+        with:
+          path: |
+            ~/.rustup/toolchains/nightly-2026-08-01-x86_64-unknown-linux-gnu
+            ~/.rustup/update-hashes/nightly-2026-08-01-x86_64-unknown-linux-gnu
+            ${{ runner.temp }}/cargo-public-api
+          key: vocabulary-public-api-${{ runner.os }}-${{ runner.arch }}-nightly-2026-08-01-cargo-public-api-0.52.0-v1
+
+      - name: Install exact public-Rust tooling
+        id: public_rust_tool
+        run: |
+          set -euo pipefail
+
+          rustup toolchain install nightly-2026-08-01 --profile minimal
+          tool_root="$RUNNER_TEMP/cargo-public-api"
+          tool="$tool_root/bin/cargo-public-api"
+          if [[ ! -x "$tool" ]] || [[ "$($tool --version)" != "cargo-public-api 0.52.0" ]]; then
+            CARGO_INSTALL_ROOT="$tool_root" \
+              cargo install cargo-public-api --version 0.52.0 --locked
+          fi
+          [[ "$($tool --version)" == "cargo-public-api 0.52.0" ]]
+          echo "binary=$tool" >> "$GITHUB_OUTPUT"
+
+      - name: Cache public-Rust build data
+        uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
+        with:
+          workspaces: |
+            . -> target/vocabulary-public-api
+          key: vocabulary-public-api-nightly-2026-08-01-v1
+
+      - name: Test vocabulary guard
+        run: cargo test -p omnigraph-vocabulary-guard --locked
+
+      - name: Check OpenAPI, Rust-string, and user-doc vocabulary
+        env:
+          BASE_SHA: ${{ steps.comparison_base.outputs.sha }}
+        run: |
+          set -euo pipefail
+          for surface in openapi rust-string user-docs; do
+            cargo run -p omnigraph-vocabulary-guard --locked -- \
+              check --surface "$surface" --base "$BASE_SHA" \
+              --inventory tools/omnigraph-vocabulary-guard/graph-vocabulary-inventory.tsv \
+              --openapi openapi.json
+          done
+
+      - name: Check public-Rust vocabulary
+        env:
+          BASE_SHA: ${{ steps.comparison_base.outputs.sha }}
+          CARGO_PUBLIC_API: ${{ steps.public_rust_tool.outputs.binary }}
+        run: |
+          tool="${CARGO_PUBLIC_API:-cargo-public-api}"
+          cargo run -p omnigraph-vocabulary-guard --locked -- \
+            check --surface public-rust --base "$BASE_SHA" \
+            --inventory tools/omnigraph-vocabulary-guard/graph-vocabulary-inventory.tsv \
+            --cargo-public-api "$tool" \
+            --public-api-target-dir target/vocabulary-public-api
+
   entrypoint_test:
     name: Container Entrypoint
     runs-on: ubuntu-latest

Cargo.lock

@@ -9,6 +9,7 @@ members = [
     "crates/omnigraph-cluster",
     "crates/omnigraph-policy",
     "crates/omnigraph-server",
+    "tools/omnigraph-vocabulary-guard",
 ]
 default-members = [
     "crates/omnigraph",
@@ -83,6 +84,11 @@ url = "2"
 cedar-policy = "4.9"
 sha2 = "0.10"
 subtle = "2"
+pulldown-cmark = "0.13"
+proc-macro2 = "1"
+quote = "1"
+syn = { version = "2", features = ["full", "visit"] }
+walkdir = "2"
 
 [workspace.lints.clippy]
 # Nested guards often read clearer than one merged condition (Polars allows this too).

Cargo.toml

@@ -283,7 +283,7 @@ pub struct IngestOutput {
 /// One logical declaration touched by a graph-batch load.
 ///
 /// This deliberately carries the accepted-schema name, not the backing
-/// manifest table key, dataset path, or Lance identity.
+/// retained table-key compatibility selector, dataset path, or Lance identity.
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, ToSchema)]
 pub struct GraphBatchDeclarationOutput {
     pub name: String,
@@ -382,8 +382,8 @@ impl ChangeOpOutput {
 }
 
 /// Graph-scoped type identity. `id` is opaque: it survives a supported rename
-/// and changes after drop/re-add. It is never a table, dataset, or path
-/// identifier.
+/// and changes after drop/re-add. It is never a retained table-key
+/// compatibility selector, dataset, or path identifier.
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, ToSchema)]
 pub struct ChangeTypeOutput {
     pub id: String,
@@ -435,7 +435,7 @@ pub struct ChangeCauseOutput {
     pub authored_branch: String,
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub actor_id: Option<String>,
-    /// Authorship time as Unix epoch microseconds — minted before table
+    /// Authorship time as Unix epoch microseconds — minted before dataset
     /// effects and stable across retries; deliberately not labeled a commit or
     /// publication time.
     #[schema(example = 1714000000000000i64)]
@@ -951,7 +951,7 @@ pub struct SchemaApplyRequest {
     )]
     pub schema_source: String,
     /// When true, promote every `DropMode::Soft` step in the plan to
-    /// `DropMode::Hard`, making the prior column data unreachable
+    /// `DropMode::Hard`, making the prior property data unreachable
     /// after the apply. Matches the CLI's `--allow-data-loss` flag.
     /// Defaults to `false` (drops remain reversible via time travel).
     #[serde(default)]
@@ -983,7 +983,7 @@ pub struct IngestRequest {
     /// creation is opt-in by presence of this field; omit it to require an
     /// existing branch.
     pub from: Option<String>,
-    /// How existing rows are handled. Defaults to `merge`.
+    /// How existing entities are handled. Defaults to `merge`.
     #[schema(value_type = Option<LoadModeSchema>)]
     pub mode: Option<LoadMode>,
     /// NDJSON payload: one record per line, each shaped
@@ -1001,7 +1001,7 @@ pub struct GraphBatchLoadQuery {
     pub branch: Option<String>,
     /// Parent branch used to create a missing target branch.
     pub from: Option<String>,
-    /// How existing rows are handled. Defaults to `merge`.
+    /// How existing entities are handled. Defaults to `merge`.
     #[param(value_type = Option<LoadModeSchema>)]
     pub mode: Option<LoadMode>,
 }
@@ -1013,7 +1013,8 @@ pub struct ExportRequest {
     /// Restrict the export to these node/edge type names. Empty exports all types.
     #[serde(default)]
     pub type_names: Vec<String>,
-    /// Restrict the export to these table keys. Empty exports all tables.
+    /// Restrict the export using retained table-key compatibility selectors.
+    /// Empty exports all node and edge types.
     #[serde(default)]
     pub table_keys: Vec<String>,
 }
@@ -1059,8 +1060,8 @@ pub enum ErrorCode {
 
 /// Structured details for a publisher-level OCC failure. Surfaces alongside
 /// HTTP 409 when a write was rejected because the caller's pre-write view of
-/// one table's manifest version was stale relative to the current head. The
-/// expected/actual fields tell the client which table to refresh.
+/// one backing dataset's published version was stale relative to the current
+/// head. The expected/actual fields tell the client which dataset to refresh.
 #[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
 pub struct ManifestConflictOutput {
     pub table_key: String,
@@ -1070,16 +1071,16 @@ pub struct ManifestConflictOutput {
 
 /// Structured authority mismatch for a prepared write. Values are
 /// strings because members include optional graph commit ids and future
-/// authority tokens, not only numeric table versions.
+/// authority tokens, not only numeric published dataset versions.
 #[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
 pub struct ReadSetConflictOutput {
     pub member: String,
     pub expected: Option<String>,
     pub actual: Option<String>,
 }
 
-/// A strict insert rejected because `key` already names a row in the keyed
-/// graph table.  The operation is effect-free when this output is returned;
+/// A strict insert rejected because `key` already names an entity in the
+/// selected node or edge type. The operation is effect-free when this output is returned;
 /// partial or ambiguous attempts surface `recovery_required` instead.
 #[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
 pub struct KeyConflictOutput {
@@ -1180,8 +1181,8 @@ pub struct ErrorOutput {
     pub merge_conflicts: Vec<MergeConflictOutput>,
     /// Set when the conflict is a publisher CAS rejection
     /// (`ManifestConflictDetails::ExpectedVersionMismatch`). The caller's
-    /// pre-write view of `table_key` was at version `expected` but the
-    /// manifest is now at `actual`. Refresh and retry.
+    /// pre-write view of `table_key` was at published dataset version
+    /// `expected`, but the graph manifest now publishes `actual`. Refresh and retry.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub manifest_conflict: Option<ManifestConflictOutput>,
     /// Set when a prepared write's logical authority changed before effects.
@@ -1193,7 +1194,7 @@ pub struct ErrorOutput {
     #[serde(skip_serializing_if = "Option::is_none")]
     pub key_conflict: Option<KeyConflictOutput>,
     /// Set when the request must be split into smaller graph commits. The
-    /// rejected attempt has no durable sidecar and no table effect.
+    /// rejected attempt has no durable sidecar and no dataset effect.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub resource_limit: Option<ResourceLimitOutput>,
     /// Set with HTTP 416 for a valid but unsatisfiable managed Blob byte range.
@@ -1207,7 +1208,7 @@ pub struct ErrorOutput {
     #[serde(skip_serializing_if = "Option::is_none")]
     pub external_blob_source: Option<ExternalBlobSourceOutput>,
     /// Set when an overlapping durable recovery intent must be resolved before
-    /// retry. Its table effects may or may not have started.
+    /// retry. Its dataset effects may or may not have started.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub recovery_required: Option<RecoveryRequiredOutput>,
     /// Set when a mutation's graph-commit precondition failed