docs: prepare GitNexus 1.6.10-electric.11

.agents/plugins/marketplace.json

@@ -6,7 +6,7 @@
   "plugins": [
     {
       "name": "gitnexus",
-      "version": "1.6.10-electric.10",
+      "version": "1.6.10-electric.11",
       "source": {
         "source": "local",
         "path": "./gitnexus-claude-plugin"

.claude-plugin/marketplace.json

@@ -11,7 +11,7 @@
   "plugins": [
     {
       "name": "gitnexus",
-      "version": "1.6.10-electric.10",
+      "version": "1.6.10-electric.11",
       "source": "./gitnexus-claude-plugin",
       "description": "Code intelligence powered by a knowledge graph. Provides execution flow tracing, blast radius analysis, and augmented search across your codebase."
     }

ARCHITECTURE.md

@@ -362,19 +362,43 @@ Inheritance is captured by the `@reference.inherits` tag and emitted by the scop
 
 ```
 CLI (analyze.ts) → runFullAnalysis(repoPath, options, callbacks)
-  1. Early exit if lastCommit == HEAD (unless --force)     [0%]
-  2. Cache existing embeddings from prior index             [0%]
-  3. runPipelineFromRepo() → KnowledgeGraph                [0-60%]
-  4. Clean up legacy KuzuDB files                          [60%]
-  5. initLbug() → loadGraphToLbug() via CSV streaming      [60-85%]
-  6. Create FTS indexes (File, Function, Class, Method...) [85-90%]
-  7. Restore cached embeddings (batch insert)              [88%]
-  8. Generate new embeddings if --embeddings               [90-98%]
-  9. Save metadata + register repo + update .gitignore     [98-100%]
- 10. Generate AI context files (AGENTS.md, CLAUDE.md)      [100%]
+  1. Early exit if lastCommit == HEAD (unless --force)                 [0%]
+  2. Read metadata and select surgical incremental, full, or staged    [0%]
+  3. Capture a bounded embedding snapshot when a rebuild needs restore [0%]
+  4. runPipelineFromRepo() → KnowledgeGraph                            [0-60%]
+  5. Write changed rows surgically, or wipe + bulk-COPY a full graph   [60-85%]
+  6. Create FTS indexes (File, Function, Class, Method...)              [85-90%]
+  7. Restore cached embeddings in bounded batches                        [88%]
+  8. Generate new embeddings within the requested cap                    [90-98%]
+  9. Validate, save metadata, register repo, and update .gitignore       [98-100%]
+ 10. Generate AI context files (AGENTS.md, CLAUDE.md)                    [100%]
 ```
 
-**Options:** `--force` (rebuild regardless), `--embeddings` (opt-in, skipped if >50k nodes), `--skipGit`, `--noStats`.
+**Options:** `--force` (rebuild regardless), `--embeddings [n]` (opt-in; a positive `n` is the
+embedding node cap, `0` disables it), `--staged` (isolated generation plus validated promotion),
+`--skipGit`, `--noStats`.
+
+### Bounded embedding preservation and staged recovery
+
+- For a healthy index that is stale against its source, a positive-cap incremental run (`--embeddings <n>`)
+  first admits or refuses the entire embedding pass against the provider-free pipeline's total graph
+  node count, before graph persistence, final metadata, registry update, or staged promotion. Transient
+  pipeline caches and prepared stage recovery files may already exist. When admitted,
+  it rewrites only the changed/effective file set and regenerates changed or new embedding owners.
+  Unaffected owners retain their complete logical embedding-row payload. If the effective write set is
+  large, the existing escalation valve selects the full-write plan; the bounded snapshot and restore
+  contract remains the same.
+- For malformed or provenance-unproven embedding state, use an explicit staged clean rebuild with a
+  positive cap on total graph nodes (`--staged --embeddings <n> --drop-embeddings`). The staged database is disposable and the
+  canonical generation stays readable until validation and journaled promotion complete. The injected
+  milestone-10 pre-promotion failure restores the exact canonical logical embedding-row and metadata
+  preimage. A later promotion failure may retain the new metadata, old database backup, and journal so
+  the next analyze can complete the recorded promotion forward.
+- The deterministic M8b proof compares every unaffected embedding-row payload field (identity, owner,
+  chunk, line range, content hash, and vector). It proves logical payload-byte preservation on that
+  supported path, not unchanged raw LadybugDB container bytes.
+- Legacy rows whose metadata lacks durable provider or identity proof remain unproven and are not
+  described as verified preservation. A clean staged rebuild replaces that unclassified state.
 
 ## Storage
 
@@ -385,6 +409,8 @@ CLI (analyze.ts) → runFullAnalysis(repoPath, options, callbacks)
   ├── lbug.shadow    # Shadow sidecar (checkpoint staging)
   ├── lbug.lock      # Single-writer lock
   ├── lbug.{wal,shadow}.dirty-recovery  # parked sidecars from a crashed run; safe to delete
+  ├── embedding-preservation.jsonl         # transient checksummed restore snapshot
+  ├── embedding-table-rebuild.json         # transient staged-table recovery marker
   ├── gitnexus.json  # lastCommit, indexedAt, stats (primary metadata file)
   └── meta.json      # legacy mirror of gitnexus.json, kept in sync (see MIGRATION.md)
 

Documentation/releases/1.6.10-electric.11.md

@@ -0,0 +1,64 @@
+# GitNexus 1.6.10-electric.11
+
+`1.6.10-electric.11` carries the post-M8b release-preparation contract for bounded embedding
+preservation and staged recovery. It adds no preservation schema, service, or public
+preservation command surface.
+
+Relative to `1.6.10-electric.10`, the artifact also includes the milestone 9 source aggregate:
+shared canonical analyze ownership across supported writers, owner/generation compare-and-swap
+protection for registry projections, recovery-safe implicit branch adoption, and additive Doctor
+registry, freshness, identity, integrity, readiness, and strict exit-status reporting.
+
+## Behavior contract
+
+- **Healthy/source-stale copy:** run incremental analysis with a positive total-graph node cap,
+  for example `gitnexus analyze --embeddings <n>`. GitNexus refuses the whole embedding pass
+  when the graph has more than `<n>` nodes, before graph persistence, final metadata, registry
+  update, or staged promotion. Provider-free pipeline caches and prepared stage recovery files may
+  already exist. When admitted, unaffected embedding owners retain their complete logical row
+  payload bytes while changed or new owners are regenerated.
+- Automatic `--force` recovery of an already-embedded local index may cross the implicit 50,000
+  node cap. That exact implicit path restores cached vectors and continues in preserve-only mode;
+  explicit embedding requests and explicit positive caps still refuse the whole pass when
+  exceeded.
+- **Malformed/provenance-unproven copy:** run an explicit staged clean rebuild with a positive cap
+  on total graph nodes:
+  `gitnexus analyze --staged --embeddings <n> --drop-embeddings`. The disposable staged
+  generation is validated before promotion; the canonical generation remains readable and
+  unchanged until that boundary.
+- The M8b disposable canary deterministically compared the complete unaffected embedding-row
+  payload (identity, owner, chunk, line range, content hash, and vector). This proves logical
+  row-payload preservation for that supported path; it does not claim raw LadybugDB container
+  bytes are unchanged.
+- Rows inherited from older metadata without durable provider or identity proof remain
+  unproven and are not called verified preservation. The clean staged rebuild replaces that
+  unclassified state rather than upgrading its claim. Doctor's structural health result is not
+  provider provenance: incremental admission additionally requires an independent, recorded
+  provider/model/dimensions identity match.
+
+## Safety and rollback boundary
+
+- Staged recovery uses a journal and a canonical database backup. The M8b receipt proves exact
+  logical embedding-row and metadata preimage restoration for its injected repository-identity
+  failure, with no staged, backup, or journal residue. Later promotion failures may deliberately
+  retain the new metadata, old database backup, and journal for forward recovery; do not treat
+  every failed promotion as an automatic exact rollback.
+- `1.6.10-electric.10` remains available as the immediate non-writing rollback artifact.
+- This source gate is local and disposable-copy evidence only. It does not prove the canonical
+  65-index estate, fleet, production, customer, browser, or runtime readiness.
+
+## Distribution boundary
+
+- Electric releases are GitHub Release assets only. `.11` is not published to npm, a container
+  registry, or any other package registry, and no floating tag is used.
+- This release-prep change does not install, dispatch the release workflow, mutate a registry or
+  live index, or perform a runtime/customer rollout.
+
+## Source-gate evidence
+
+- Exact post-M8b main: `50a0553c01fea92edff560f9e43df838235b3cf0`.
+- Milestone 10 closeout receipt: SHA-256
+  `0f6193fa5066745108a79acbeeccf485e4a52c7d08e0a5c67a6fa334ba0c94f8`.
+- Receipt and retrieval record: [issue #197 milestone 10 acceptance](https://github.com/electricsheephq/evaOS-gitnexus/issues/197#issuecomment-5472113345).
+- The receipt is the source/disposable-copy gate carried into this release-prep PR; release,
+  install, and runtime claims require their separate exact-head workflow evidence.

GUARDRAILS.md

@@ -20,6 +20,7 @@ Maintainer may widen scope per task.
 3. **Run impact analysis before editing shared symbols** — `impact` (upstream) for functions/classes/methods others call. Do not ignore HIGH/CRITICAL without maintainer sign-off.
 4. **Run `detect_changes` before commit** — confirm diffs map to expected symbols/processes when the graph is available.
 5. **Preserve embeddings** — plain `npx gitnexus analyze` now preserves any embeddings recorded in the index metadata (`.gitnexus/gitnexus.json`, mirrored to the legacy `meta.json`) — the previous behavior wiped them. Use `--embeddings` to also generate vectors for new/changed nodes; use `--drop-embeddings` only when an explicit wipe is intended (e.g., model swap).
+6. **Use the bounded recovery contract** — for healthy indexes that are stale against source, use a positive cap on total graph nodes (`--embeddings <n>`). The cap admits or refuses the whole embedding pass after the provider-free pipeline but before graph persistence, final metadata, registry update, or staged promotion; transient caches or prepared stage recovery files may already exist. When admitted, the incremental path retains unaffected logical embedding-row payloads and regenerates only changed/new owners. For malformed or provenance-unproven state, use an explicit staged clean rebuild with the same positive total-graph cap (`--staged --embeddings <n> --drop-embeddings`) and keep the canonical generation as the rollback preimage until validated promotion completes. Older rows without durable provider or identity proof remain unproven; never call them verified preservation.
 
 ---
 
@@ -45,6 +46,12 @@ Format: **Trigger → Instruction → Reason**. Append new Signs when the same m
 - **Do:** Re-run `npx gitnexus analyze --embeddings` to regenerate. Check the analyze log for a `Warning: could not load cached embeddings` line — if present, the cache restore failed (corrupt DB / schema mismatch) and the rebuild had nothing to preserve. If you intentionally passed `--drop-embeddings`, this is expected.
 - **Why:** Plain `analyze` preserves prior vectors by re-inserting them after the rebuild; the only ways to end up at zero are an explicit `--drop-embeddings`, a cache-load failure (now logged), or a model/dimension change that invalidates the cache. A dirty-recovery run that cannot move the crashed WAL aside now either discards it (logged: forensics lost, embeddings still preserved) or fails fast with a lock error naming the holder — it never silently zeroes embeddings.
 
+### Embedding state is malformed or provenance is unproven
+
+- **Trigger:** Doctor or read-only integrity inspection reports malformed, duplicate, orphaned, wrong-dimension, or otherwise unproven embedding state, or the operator cannot independently bind the existing rows to the expected provider, model, and dimensions. Doctor structural health alone is not provider provenance.
+- **Do:** Preserve the canonical logical embedding-row and metadata preimage, then run an explicit staged clean rebuild with a positive cap on total graph nodes: `npx gitnexus analyze --staged --embeddings <n> --drop-embeddings`. Validate the isolated generation before journaled promotion. Follow the journal state after a failure: the injected milestone 10 boundary proved exact rollback, while later failures may retain the old database backup and new metadata for forward recovery.
+- **Why:** A staged clean rebuild gives malformed or unclassified derived state a bounded replacement path without treating old rows as verified. The deterministic proof covers logical row payloads, not raw LadybugDB container bytes.
+
 ### MCP lists no repos
 
 - **Trigger:** MCP stderr says no indexed repos.
@@ -74,6 +81,7 @@ Format: **Trigger → Instruction → Reason**. Append new Signs when the same m
 ## Publishing & supply chain
 
 - **npm:** Do not publish from unreviewed automation. Bump version intentionally; tag releases to match `package.json`.
+- **Electric releases:** Distribution is GitHub Release assets only. Do not publish an Electric version to npm, a container registry, or another package registry, and do not use a floating tag. Keep `1.6.10-electric.10` available as the immediate non-writing rollback artifact while `.11` release/install/runtime work is proved separately.
 - **Dependencies:** Minimal, auditable `package.json` changes; run tests and CI after lockfile updates.
 - **License:** PolyForm Noncommercial 1.0.0 — do not relicense without maintainer approval.
 

MIGRATION.md

@@ -110,3 +110,25 @@ repo as never analyzed.
 
 The `meta.json` mirror will remain until a future major version. Removal
 will be announced in this file and in the changelog before it happens.
+
+## Bounded embedding preservation and staged recovery (`1.6.10-electric.11`)
+
+There is no embedding-schema migration. The release documents two existing paths:
+
+- A healthy index that is stale against its source can use an incremental run with a positive cap
+  on total graph nodes,
+  run, `gitnexus analyze --embeddings <n>`. The pass is refused when the graph has more than
+  `<n>` nodes. Refusal happens before graph persistence, final metadata, registry update, or staged
+  promotion, although transient pipeline caches or prepared stage recovery files may already exist.
+  When admitted, unaffected logical embedding-row payloads remain intact and changed or new owners
+  are regenerated.
+- Malformed or provenance-unproven embedding state uses an explicit staged clean rebuild with the
+  same positive total-graph cap, `gitnexus analyze --staged --embeddings <n> --drop-embeddings`. The staged generation is
+  validated before promotion, and the canonical logical embedding-row and metadata preimage stays
+  available for journaled rollback.
+
+Rows inherited from metadata without durable provider or identity proof remain unproven. They are
+not called verified preservation; the clean staged rebuild is the replacement path for that state.
+The deterministic proof covers logical row payloads, not raw LadybugDB container bytes. Existing
+`1.6.10-electric.10` installation bytes remain suitable for non-writing rollback while `.11`
+release and runtime steps are handled separately.

RUNBOOK.md

@@ -56,7 +56,11 @@ npx gitnexus list
 npx gitnexus analyze --embeddings
 ```
 
-**Important:** If you already had embeddings, **always** pass `--embeddings` on later analyzes, or they can be dropped. See `stats.embeddings` in `.gitnexus/gitnexus.json` (or its legacy `meta.json` mirror; 0 means none).
+**Important:** A plain `analyze` preserves existing embeddings. Pass `--embeddings <n>` when
+you also want changed or new owners regenerated under a positive node cap; use
+`--drop-embeddings` only when intentionally replacing the existing vectors. See
+`stats.embeddings` in `.gitnexus/gitnexus.json` (or its legacy `meta.json` mirror; 0 means
+none).
 
 **Large repos:** Analyze may skip or limit embedding work when node counts are very high; watch CLI output.
 
@@ -164,6 +168,35 @@ If the error text is `"Only one write transaction at a time is allowed in the sy
 - Agent safety rules: [GUARDRAILS.md](GUARDRAILS.md)  
 - Tests: [TESTING.md](TESTING.md)
 
+## Bounded embedding preservation and staged recovery
+
+For a healthy index that is stale against its source, run incremental analysis with a positive
+total-graph node cap:
+
+```bash
+npx gitnexus analyze --embeddings <n>
+```
+
+GitNexus refuses the whole embedding pass when the provider-free pipeline reports more than `<n>`
+nodes. Refusal happens before graph persistence, final metadata, registry update, or staged
+promotion; transient pipeline caches or prepared stage recovery files may already exist. When
+admitted, the incremental path rewrites the changed/effective file set, regenerates changed or new
+embedding owners, and retains unaffected logical embedding-row payloads. If the effective write set
+is large, the existing escalation valve may select a full write while retaining the same bounded
+snapshot and restore contract.
+
+For malformed or provenance-unproven embedding state, use an explicit staged clean rebuild:
+
+```bash
+npx gitnexus analyze --staged --embeddings <n> --drop-embeddings
+```
+
+The staged generation is disposable and the canonical generation remains readable until
+validation and journaled promotion complete. Keep the canonical logical embedding-row and
+metadata preimage available for rollback. The deterministic proof covers logical row payloads,
+not raw LadybugDB container bytes; legacy rows without durable provider or identity proof remain
+unproven and are not called verified preservation.
+
 ---
 
 ## Electric fork releases
@@ -173,8 +206,8 @@ to npm, GitHub Container Registry, Docker Hub, or another package registry.
 
 Prepare each version through a reviewed release PR:
 
-1. Set `gitnexus/package.json` and `gitnexus/package-lock.json` to a version such
-   as `1.6.10-electric.1`.
+1. Set `gitnexus/package.json` and `gitnexus/package-lock.json` to the reviewed
+   fork version, such as `1.6.10-electric.11`.
 2. Run `node gitnexus/scripts/sync-plugin-versions.mjs` from the repository root.
 3. Add `Documentation/releases/<version>.md` and update `gitnexus/CHANGELOG.md`.
 4. Run `npm run check:electric-release-policy`, the plugin-version test, build,
@@ -187,7 +220,7 @@ Create the release from the current `main` branch with the protected workflow:
 gh workflow run electric-release.yml \
   --repo electricsheephq/evaOS-gitnexus \
   --ref main \
-  -f expected_version=1.6.10-electric.1 \
+  -f expected_version=1.6.10-electric.11 \
   -f prerelease=false
 ```
 
@@ -219,10 +252,11 @@ After downloading both assets, verify and install locally:
 
 ```bash
 shasum -a 256 --check SHA256SUMS
-npm install --global ./gitnexus-1.6.10-electric.1.tgz
+npm install --global ./gitnexus-1.6.10-electric.11.tgz
 gitnexus --version
 ```
 
 A GitHub Release does not authorize an OpenClaw/evaOS rollout. Keep the prior
-installation available for rollback, switch runtime source separately, and do
-not rebuild or migrate a live index unless that rollout explicitly requires it.
+`1.6.10-electric.10` installation available as non-writing rollback bytes, switch
+runtime source separately, and do not rebuild or migrate a live index unless that
+rollout explicitly requires it.

gitnexus-claude-plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "gitnexus",
   "description": "Code intelligence powered by a knowledge graph. Provides execution flow tracing, blast radius analysis, and augmented search across your codebase.",
-  "version": "1.6.10-electric.10",
+  "version": "1.6.10-electric.11",
   "author": {
     "name": "GitNexus"
   },

gitnexus-claude-plugin/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "gitnexus",
   "description": "Code intelligence powered by a knowledge graph. Provides execution flow tracing, blast radius analysis, and augmented search across your codebase.",
-  "version": "1.6.10-electric.10",
+  "version": "1.6.10-electric.11",
   "skills": "./skills",
   "mcpServers": "./.mcp.json",
   "hooks": "./hooks/hooks.json",