docs: cite the cross-layer integrity contract generically in comments and notes

CHANGELOG.md

@@ -4,10 +4,10 @@ All notable changes to this project will be documented in this file. See [standa
 
 ### [8.3.0](https://github.com/soulcraftlabs/brainy/compare/v8.2.8...v8.3.0) (2026-07-13)
 
-- docs: RELEASES.md entry for 8.3.0 (heal-cost + ADR-004 Pass 2/3) (7692c6f)
+- docs: RELEASES.md entry for 8.3.0 (heal-cost + cross-layer integrity contract) (7692c6f)
 - perf: parallel + id-only canonical enumeration (heal-cost dominant term) (ec5b933)
-- feat: registered-blob family contract — declared index blobs are undeletable (ADR-004 Pass 2) (bfa1762)
+- feat: registered-blob family contract — declared index blobs are undeletable (bfa1762)
-- feat: validateIndexConsistency delegates to provider invariants (ADR-004 Pass 3) (6bcb54f)
+- feat: validateIndexConsistency delegates to provider invariants (6bcb54f)
 
 
 ### [8.2.8](https://github.com/soulcraftlabs/brainy/compare/v8.2.7...v8.2.8) (2026-07-13)

src/coreTypes.ts

@@ -755,7 +755,7 @@ export interface Change {
 }
 
 /**
- * @description A declared derived-index blob FAMILY (ADR-004 §7 — the
+ * @description A declared derived-index blob FAMILY (the
  * registered-blob contract). A family names the set of on-disk blobs that a
  * derived index needs AS A SET (e.g. the vector base = `main.dkann` +
  * `main.slotmap` + `main.slotrev`): losing ANY member corrupts the index. Once a
@@ -1083,7 +1083,7 @@ export interface StorageAdapter {
   getBinaryBlobPath(key: string): string | null
 
   /**
-   * @description OPTIONAL (ADR-004 §7 registered-blob contract). Declare a
+   * @description OPTIONAL (registered-blob contract). Declare a
    * derived-index blob {@link DerivedFamilyDeclaration | family} whose members
    * become UNDELETABLE through this adapter — a subsequent `deleteBinaryBlob` /
    * `removeRawPrefix` that would remove a declared member throws a

src/errors/brainyError.ts

@@ -311,7 +311,7 @@ export class VectorIndexNotReadyError extends BrainyError {
 
 /**
  * Thrown when a delete (`deleteBinaryBlob` / `removeRawPrefix`) would remove a
- * blob that is a declared member of a protected derived-index FAMILY (ADR-004 §7
+ * blob that is a declared member of a protected derived-index FAMILY (the
  * registered-blob contract). Declared derived artifacts are undeletable through
  * the storage layer — this makes an in-process GC / sweeper INCAPABLE of removing
  * a load-bearing index file (the lost-`main.dkann` class). Intentional retirement

src/plugin.ts

@@ -116,7 +116,7 @@ export interface BrainyPluginContext {
 // ===========================================================================
 
 /**
- * @description How a failed provider invariant should be remediated (ADR-004 §6):
+ * @description How a failed provider invariant should be remediated:
  * - `'none'`    — informational; the invariant held or nothing to do.
  * - `'repair'`  — a targeted, cheap fix exists (e.g. re-derive a count/manifest field).
  * - `'rebuild'` — the derived state must be rebuilt from canonical (`provider.rebuild()`).
@@ -124,7 +124,7 @@ export interface BrainyPluginContext {
 export type InvariantHeal = 'none' | 'repair' | 'rebuild'
 
 /**
- * @description The result of ONE provider invariant check (ADR-004 §6). A failure
+ * @description The result of ONE provider invariant check. A failure
  * (`holds === false`) NAMES what diverged, with numbers, so it is diagnosable
  * from the report alone — never a bare boolean. `name` is a stable kebab-case id
  * for telemetry / remediation routing.
@@ -146,7 +146,7 @@ export interface InvariantResult {
 
 /**
  * @description A provider's self-report of its own cross-layer invariants
- * (ADR-004 §6 — the `validateInvariants()` hook). Contract:
+ * (the `validateInvariants()` hook). Contract:
  * - It NEVER throws — a failure is DATA (`healthy: false` + a failing invariant),
  *   not an exception.
  * - It is BOUNDED (<50ms): residency checks + O(1) counts only, NO canonical
@@ -196,7 +196,7 @@ export interface MetadataIndexProvider {
   isReady?(): boolean
 
   /**
-   * @description OPTIONAL (ADR-004 §6). The provider's self-report of its own
+   * @description OPTIONAL. The provider's self-report of its own
    * cross-layer invariants (manifest ↔ segments ↔ counts residency/coherence).
    * MUST NOT throw — a failure is DATA (`healthy: false` + a failing invariant).
    * MUST be bounded (<50ms): residency + O(1) counts only, NO canonical walks, so
@@ -358,7 +358,7 @@ export interface GraphIndexProvider {
   isReady?(): boolean
 
   /**
-   * @description OPTIONAL (ADR-004 §6). The provider's self-report of its own
+   * @description OPTIONAL. The provider's self-report of its own
    * cross-layer invariants (manifest ↔ segments ↔ counts residency/coherence).
    * MUST NOT throw — a failure is DATA (`healthy: false` + a failing invariant).
    * MUST be bounded (<50ms): residency + O(1) counts only, NO canonical walks, so
@@ -1024,7 +1024,7 @@ export interface VectorIndexProvider {
   isReady?(): boolean
 
   /**
-   * @description OPTIONAL (ADR-004 §6). The provider's self-report of its own
+   * @description OPTIONAL. The provider's self-report of its own
    * cross-layer invariants (manifest ↔ segments ↔ counts residency/coherence).
    * MUST NOT throw — a failure is DATA (`healthy: false` + a failing invariant).
    * MUST be bounded (<50ms): residency + O(1) counts only, NO canonical walks, so

src/storage/adapters/memoryStorage.ts

@@ -183,7 +183,7 @@ export class MemoryStorage extends BaseStorage {
    * @param key - The blob key.
    */
   public async deleteBinaryBlob(key: string): Promise<void> {
-    // Registered-blob contract (ADR-004 §7) — parity with the filesystem adapter:
+    // Registered-blob contract — parity with the filesystem adapter:
     // a declared family member is undeletable (throws ProtectedArtifactError).
     await this.assertBlobKeyDeletable(key)
     this.blobStore.delete(key)

tests/unit/storage/registered-blob-contract.test.ts

@@ -1,6 +1,6 @@
 /**
  * @module tests/unit/storage/registered-blob-contract
- * @description Pass 2 (ADR-004 §7): declared derived-index blob FAMILIES are
+ * @description Declared derived-index blob FAMILIES are
  * undeletable through the storage layer — an in-process GC/sweeper cannot remove
  * a load-bearing index file (the lost-main.dkann class). Covers declare →
  * protected-delete-throws; unregister → delete-ok; transient passthrough;
@@ -15,7 +15,7 @@ import { MemoryStorage } from '../../../src/storage/adapters/memoryStorage.js'
 import { FileSystemStorage } from '../../../src/storage/adapters/fileSystemStorage.js'
 import { ProtectedArtifactError } from '../../../src/index.js'
 
-describe('registered-blob family contract (Pass 2, ADR-004 §7)', () => {
+describe('registered-blob family contract', () => {
   let storage: any
 
   beforeEach(async () => {

tests/unit/validate-invariants-delegation.test.ts

@@ -1,6 +1,6 @@
 /**
  * @module tests/unit/validate-invariants-delegation
- * @description Pass 3 (ADR-004 §6): validateIndexConsistency() was blind to native
+ * @description validateIndexConsistency() was blind to native
  * providers — it only saw the JS metadata index, so a native manifest↔segments↔count
  * divergence read as "healthy". It now feature-detects + aggregates each provider's
  * validateInvariants(), and repairIndex() maps a failing invariant with heal:'rebuild'