diff --git a/CHANGELOG.md b/CHANGELOG.md index 97c5d059..b3821c3b 100644 --- a/CHANGELOG.md +++ b/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: validateIndexConsistency delegates to provider invariants (ADR-004 Pass 3) (6bcb54f) +- feat: registered-blob family contract — declared index blobs are undeletable (bfa1762) +- 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) diff --git a/src/coreTypes.ts b/src/coreTypes.ts index 4b1ebfb9..c345624b 100644 --- a/src/coreTypes.ts +++ b/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 diff --git a/src/errors/brainyError.ts b/src/errors/brainyError.ts index 6aa1f919..a58236e3 100644 --- a/src/errors/brainyError.ts +++ b/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 diff --git a/src/plugin.ts b/src/plugin.ts index c0fda10f..df7c7224 100644 --- a/src/plugin.ts +++ b/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 diff --git a/src/storage/adapters/memoryStorage.ts b/src/storage/adapters/memoryStorage.ts index 6b2564d5..41987ea0 100644 --- a/src/storage/adapters/memoryStorage.ts +++ b/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 { - // 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) diff --git a/tests/unit/storage/registered-blob-contract.test.ts b/tests/unit/storage/registered-blob-contract.test.ts index ef450163..6ad51ae7 100644 --- a/tests/unit/storage/registered-blob-contract.test.ts +++ b/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 () => { diff --git a/tests/unit/validate-invariants-delegation.test.ts b/tests/unit/validate-invariants-delegation.test.ts index 953c6b91..45e12ccd 100644 --- a/tests/unit/validate-invariants-delegation.test.ts +++ b/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'