fix: warm() metadata surface routes through the active provider (warm hook added to the metadata contract); add maintenanceDebt() observability surface
A production deployment's warm report showed metadata: 'unavailable' under a native metadata provider. brain.warm()'s metadata leg only duck-typed the built-in JS manager's hydrateAll() method, which a native provider has no reason to implement. - MetadataIndexProvider (src/plugin.ts) gains an optional warm?(): Promise<void> hook, mirroring the existing vector and graph provider hooks. brain.warm() now checks the active provider's own warm() FIRST, falls back to the JS manager's hydrateAll() when absent, and reports 'unavailable' only when neither exists -- never init() as a stand-in, since a native provider's init() may be a cheap verify rather than a real warm. - Tests (tests/unit/brainy/warm.test.ts): a live provider instance shaped to have warm() reports 'warmed' and the hook called with no hydrateAll fallback; shaped to have neither hook reports 'unavailable' (pins the honest branch); the unmodified built-in JS manager still reports 'warmed' via hydrateAll(), unchanged. Additive scope agreed mid-flight with the native-provider team: a maintenance-debt observability seam so an operator sees a grind coming instead of discovering it as a CPU storm. - New optional maintenanceDebt?(): Promise<ProviderMaintenanceDebt> hook on all three provider contracts (vector, metadata, graph -- the same three warm?() lives on). ProviderMaintenanceDebt is fields-all-optional: a provider reports only what it truly measures (pendingBytes, pendingItems, lastPassCompletedAt, lastPassOutcome, converging), never an estimate dressed as fact. - New public brain.maintenanceDebt(): a pure passthrough -- for each surface it calls only the active provider's own hook and reports the payload verbatim, or 'unavailable' when absent. No thresholds, no polling, no JS-side estimation; the provider owns the numbers, the operator owns the policy. - ProviderMaintenanceDebt, MaintenanceDebtReport, and MaintenanceDebtOutcome are exported from the package root. - Tests (tests/unit/brainy/maintenance-debt.test.ts): hook present reports 'reported' with the exact payload passed through; hook absent reports 'unavailable' on every surface; mixed surfaces resolve independently of each other. RELEASES.md gains the 8.10.1 entry covering both fixes above and this feature, including the no-hot-retry contract from the prior commit.
This commit is contained in:
parent
003e2a74ea
commit
5b2cbf74e5
6 changed files with 471 additions and 6 deletions
10
src/index.ts
10
src/index.ts
|
|
@ -31,6 +31,11 @@ export type { DiagnosticsResult } from './brainy.js'
|
|||
// brain.warm() — eager index/storage readiness report (per-surface honest
|
||||
// outcome + timing). See the WarmReport JSDoc in brainy.ts.
|
||||
export type { WarmReport, WarmOutcome } from './brainy.js'
|
||||
// brain.maintenanceDebt() — per-surface passthrough of each active
|
||||
// provider's self-reported background maintenance debt. See the
|
||||
// MaintenanceDebtReport JSDoc in brainy.ts and ProviderMaintenanceDebt in
|
||||
// plugin.ts for the measure-only-what-you-track contract.
|
||||
export type { MaintenanceDebtReport, MaintenanceDebtOutcome } from './brainy.js'
|
||||
export type {
|
||||
GraphAuditReport,
|
||||
GraphAuditDiscrepancy
|
||||
|
|
@ -227,6 +232,11 @@ export type { FamilyStamp, StampMembers, StampVerdict } from './db/familyStamp.j
|
|||
export { isVersionedIndexProvider } from './plugin.js'
|
||||
export type { VersionedIndexProvider } from './plugin.js'
|
||||
export type { ProviderInvariantReport, InvariantResult, InvariantHeal } from './plugin.js'
|
||||
// Optional provider self-report of outstanding background maintenance work
|
||||
// (compaction, deferred writes, etc.) — the payload type for
|
||||
// brain.maintenanceDebt(). See the measure-only-what-you-track contract on
|
||||
// ProviderMaintenanceDebt in plugin.ts.
|
||||
export type { ProviderMaintenanceDebt } from './plugin.js'
|
||||
// Optional native graph-acceleration engine (cor 3.0) — the published provider
|
||||
// contract + its columnar wire types. Brainy feature-detects an implementation
|
||||
// and falls back to its pure-TS adjacency when absent.
|
||||
|
|
|
|||
Reference in a new issue