Skip to content

memory: make incremental view maintenance evidence-grounded - #3289

Merged
Hillary Mutisya (hillary-mutisya) merged 5 commits into
mainfrom
dev/hillarym/incremental-view-maintenance
Nov 16, 2026
Merged

Hillary Mutisya (hillary-mutisya) merged 5 commits into
mainfrom
dev/hillarym/incremental-view-maintenance

Conversation

@hillary-mutisya

@hillary-mutisya Hillary Mutisya (hillary-mutisya) commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Summary

  • Make Wiki/project-brief maintenance incremental, with revision-bound completeness reviews, recoverable gaps/deferrals, and bounded factual repair.
  • Add explicitly confirmed, additive article separation across the service, client/MCP/RPC contracts and Memory Hub.
  • Correct evidence/prompt contracts and extend the existing live-only evaluation workflow with source-bound maintenance metrics, citation execution receipts and blinded reviewer preparation.

Why

Initial informational builds could bypass actual-output factual checks, topic summaries could reject citations that had actually been supplied, and generic prompt instructions produced unnecessary caveats or incomplete downstream contracts. An early ambiguity or sparse source set also needs to remain recoverable when later evidence clarifies the article.

This change separates factual support, purpose-relative completeness, freshness and approval. It does not turn model confidence, API success or a saved article into independently established quality.

Behavior and compatibility

  • Every informational first build/update checks the actual merged output against original indexed evidence. One bounded repair is permitted; protected human edits are remerged and the actual result is checked again. Repeated rejection retains the accepted prior revision.
  • Daily semantic review is bounded to one due article per eligible family maintenance pass. Assessments bind the accepted revision, content and evidence; assessment-only changes do not churn article revisions. This uses the existing maintenance scheduler, not an external always-running task.
  • Facets and actionable gaps distinguish missing evidence, explicit unknowns and contradictions. There is no invented confidence probability. Competing canonical revisions invalidate stale ambiguity; later matching evidence can reopen deferred topic candidates without deleting their provenance.
  • A native explicit no-gap result saves an empty coverage note and renders no notice. Missing legacy assessment remains distinct. Project summaries prioritize supported current blockers/required work without inventing formal severity.
  • Topic summary parsing validates against the exact dispatched citation set, including citations beyond the eighth. Compact topic assessments no longer request informational-article diagnostics.
  • New separateView operations are read, preview, confirm and cancel. Preview creates no child; confirmation must match that exact persisted proposal. Automatic splitting remains disabled.
  • Separation preserves the original overview, anchors and human units. Children use original evidence and factual checks. Stable receipts/child IDs support partial-failure recovery; navigation activates only when every exact child index is ready.
  • Source eligibility, exclusions and uncited influence remain privacy dependencies. Forgetting purges affected receipts/children/navigation; authorization loss invalidates the operation. Consolidation checks intended separation participants again at acceptance.
  • Existing live-only campaign contracts gain issue-ordering, topic admission/false-merge/false-split, correction, stale-removal, preservation, forgetting and protected-edit tasks. Independent judgments, calibration and preregistered confirmation remain required; missing denominators stay unknown.
  • Maintenance gold contains shared semantic requirements, while each arm/generation binds its own predecessor and operation receipt bytes. Outputless failures retain their scheduled denominator without fabricated output quotes or success credit.
  • Integrates main's bounded Wiki choice judgments and restricted topic-reconciliation routing without dropping factual diagnostics/repair or deferred recovery. The combined v26 synthesis identity includes both prose and decision identities.
  • Inventory projection v2 includes separation receipts, preserving pinned-snapshot reuse during consolidation nomination. Normal projection maintenance refreshes older versions; legacy reads retain committed-head binding.

Reviewer guide

  1. Semantic review and its integration in fileMemoryService.ts: exact accepted-input binding, due/retry lifecycle, recovery and fair scheduling.
  2. viewSynthesis.ts, informationalWiki.ts, and topicGeneration.ts: actual-output checks/repair, purpose-relative limits and exact citation contracts.
  3. viewSeparation.ts, service/store integration, client protocol, and Memory Hub controls: explicit confirmation, additive preservation, index readiness and privacy/restart behavior.
  4. Campaign contract/workflow: actual provider capture, exact saved-byte/source binding, task receipts, blinded review and whole-cluster confirmation guards.
  5. Maintenance architecture: default behavior, API lifecycle and development-evidence limitations.

Validation

  • pnpm run build from ts: passed.
  • 444 service tests passed across 27 suites on the final repair tree, including all six suites that exposed publication CI regressions. The unchanged client protocol (33), browser UI (84), browser gateway/lifecycle (41), and campaign/review/preparation/dataset adapters (66) previously passed on the integrated branch.
  • Pinned changed-file formatting and whitespace checks passed.
  • All four committed-head PR gates passed against fetched origin/main on 10e124f08cc7e52a072c0722cb2786a3ece6f2a7: lint checked 40 changed source files, violations 281 -> 281; above-threshold cyclomatic/cognitive complexity 0 -> 0; circular dependencies 210 -> 210; debt checked 74 changed files, with no newly skipped tests (0 -> 0).
  • Final branch scope: 77 files, 8,772 insertions and 220 deletions. The working tree is clean.
  • Local environment: Windows, standalone pnpm, Node 24.13.0. That installed Node is below the declared 24.22.1 minimum; the build/tests passed with the existing engine warning. Supported-runtime and cross-platform coverage remain CI responsibilities.
  • An expanded, unsharded all-service run exhausted Node's default 4-GiB heap before completion; no full-suite pass is claimed. The final bounded 27-suite run passed. CI uses its existing sharded matrix.

The focused commands use existing runners:

# ts\packages\memory\service
$suites = @(
  "viewEditorial", "viewEditorialTemporal", "viewEditorialTopics",
  "informationalWiki", "informationalProjectPrompt", "informationalProjectRegression",
  "informationalProjectSchema", "wikiAdmission", "wikiConsolidation",
  "wikiConsolidationRecovery", "wikiConsolidationTemporal", "viewSemanticReview",
  "topicGeneration", "viewSeparation", "viewSeparationService", "viewStore",
  "topicFrozenPreparation", "topicGenerativeDecision", "wikiDecision",
  "topicWorkReuse", "schemaRequestAdmission", "wikiContribution", "wikiGrouping",
  "sourceFollowing", "snapshotReuse", "maintenanceFoundation", "nextWaveLatency"
)
pnpm run jest-esm --runInBand --runTestsByPath @($suites | ForEach-Object { "dist\test\$($_).spec.js" })

# ts\packages\memory\client
node --test test\viewProtocol.spec.mjs test\viewSeparationProtocol.spec.mjs

# ts\packages\agents\browser
pnpm exec jest --runInBand --testMatch '**/memoryHubProjectBrief.test.ts' '**/memoryHubViews.test.ts' '**/memoryHubSeparation.test.ts'
node --test test\viewGateway.test.mjs test\viewDraftGateway.test.mjs test\viewLifecycle.test.mjs test\memoryHub.test.mjs

# ts
node --test tools\memory-maintenance-qualification\quality-view-campaign.test.mjs tools\memory-maintenance-qualification\quality-view-campaign-cli.test.mjs tools\memory-maintenance-qualification\quality-view-campaign-review.test.mjs tools\memory-maintenance-qualification\quality-view-campaign-prepare.test.mjs tools\memory-maintenance-qualification\quality-freshwiki.test.mjs tools\memory-maintenance-qualification\quality-qmsum.test.mjs

pnpm run prettier:changed
pnpm run code-lint -- --ratchet --base origin/main
pnpm run code-complexity -- --ratchet --base origin/main --cyclomatic 25 --cognitive 30 --new-file-cyclomatic 25 --new-file-cognitive 30
pnpm run code-circular -- --ratchet --base origin/main --exceptions-file tools\scripts\code\circular-baseline-exception.json
pnpm run code-debt -- --gate --base origin/main

Author-run v25 live development observations (before base integration)

  • 19/19 original checkpoints saved across five independent synthetic scenario clusters, not 19 independent samples.
  • All checkpoints have actual service citation-resolution receipts verified against accepted selections, exact saved bytes, original block hashes, UTF-16 ranges and source revisions.
  • Native review proposed two independently useful destinations; explicit synthetic-client confirmation produced readable, index-ready children and retained the overview across restart.
  • A protected human goals/scope edit survived contradictory staging evidence and restart. Source forgetting purged the overview/history/old citation/split navigation/children and preserved an unrelated accepted reference, including after restart.
  • The Topics review material retains 24 raw topics and two curated concepts with original source mappings.
  • 81 instrumented logical view calls completed, totaling 236,371 prompt and 62,709 completion tokens. Extraction, embedding/backfill, topic calls outside that adapter and internal transport retries are not included.
  • Earlier harness errors remain retained: the forgetting-preview call shape and read-only Topics collector policy/result projection were corrected without regenerating accepted views.

These are development observations, not an independently approved benchmark, a first-pass reliability improvement, or evidence that ranking/topic quality meets calibrated thresholds. The temporal rerun required five bounded repairs; its predecessor required two. Raw payloads, local stores, model requests and reviewer custody are intentionally excluded from this PR.
These observations predate the later choice-only Wiki and restricted topic-reconciliation changes integrated from main. They do not constitute a live rerun or qualification of the combined decision policy.

Risks and follow-up

  • Initial publication CI exposed missing factual-check callbacks in older offline fixtures, a t1-only source-following assertion being applied at t0, and a full-history receipt read on the consolidation nomination path. The follow-up supplies explicit fixture callbacks, scopes the assertion to updates, and includes receipts in the committed projection without relaxing snapshot-reuse assertions.
  • Stateful scheduling/separation changes require care around stale inputs, concurrent edits and partial index installation; focused tests cover these bindings, restart/retry, source forgetting and authorization.
  • Existing accepted content remains the fallback after rejected maintenance; failed/stale work cannot advance its accepted checkpoint.
  • Independent source/output review, reviewer calibration, numeric confirmation thresholds and sealed confirmation remain pending. No human approval is implied, and no sealed holdout was opened.
  • No migration of old informational formats, new dataset acquisition, automatic publication approval or automatic splitting is introduced.

Bind bounded completeness reviews to accepted evidence and preserve recovery
when later sources resolve gaps or ambiguity. Validate and repair actual
informational output, retain explicit no-gap state, and keep topic citation
contracts exact.

Add explicitly confirmed additive separation with protected overview content,
durable child/index recovery and source-privacy guards. Extend live-only
campaign tooling with maintenance metrics, actual citation receipts and
blinded review preparation without manufacturing independent approval.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Preserve restricted topic-reconciliation routing and choice-only Wiki
decisions alongside revision-bound review, deferred recovery, actual-output
diagnostics and confirmed additive separation.

Keep v25 live observations explicitly historical and invalidate combined
decision-policy identities rather than attributing old results to new models.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Include the additive separation tool in the advertised protocol surface. Serve distinct synthesis, factual-check and semantic-review responses in the project brief loopback fixture, and verify completed review without extra calls on index retry.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@hillary-mutisya

Copy link
Copy Markdown
Contributor Author

Fixed the failing MCP tests in 923c91b.

  • The advertised-tool expectation now includes memory_view_separate.
  • The synthetic project-brief endpoint now responds separately to summary generation, factual checks and semantic review, rejects unexpected schemas, and verifies semantic review completion and no extra calls on index retry.
  • Both original CI failures were reproduced locally before the fix. No production checks or thresholds were weakened.

Validation on Windows / Node 26.13.0 / pnpm 11.9.0:

  • pnpm run build and pnpm run prettier:changed: passed.
  • Lint, complexity (25/30), circular-dependency and test-debt gates against origin/main: passed on the fix commit.
  • Both previously failing MCP spec files: 17/17 passed.
  • All 23 branch-modified memory-service spec files: 425/425 passed.
  • Browser view client: 520/520; view gateway: 130/130; memory-client: 83/83; changed quality-campaign harness tests: 41/41 passed.

No review comments or threads were present at the latest refresh. Monitoring CI and feedback for the pushed head; CI results remain pending until the new run completes.

@hillary-mutisya

Copy link
Copy Markdown
Contributor Author

Follow-up CI triage: the original MCP failures now pass on both Linux and Windows Node versions. The new run's sole underlying failure is the unchanged macOS Node 26 root-script storage-write benchmark (5 !== 4 index copies).

The benchmark assumes ideal two-document grouping, while the unchanged ingestion coordinator intentionally flushes after a 25 ms admission window. A late member can therefore produce an additional group under runner load. All four storage-write benchmark tests pass locally. I requested one targeted rerun of the failed macOS job and its downstream checks; no assertions, timing policy or thresholds were changed. CI remains pending until that attempt completes.

@hillary-mutisya

Copy link
Copy Markdown
Contributor Author

Final verification for head 923c91b28db6a8d73200bacb571f2017276a4f29:

  • All required checks pass, including all six TypeScript compatibility checks, both .NET configurations, repository policy and Azure smoke tests.
  • 106 reported checks passed; three conditional jobs were skipped. No failed or pending checks remain.
  • The complete TypeScript workflow passed on attempt 2 after the single targeted rerun of the unchanged timing-sensitive macOS root benchmark.
  • Final feedback refresh found no reviews, inline comments or review threads to address. Human approval is still required; the PR has not been merged.

The bounded monitoring window has ended. The fix is pushed and the local working tree is clean.

@hillary-mutisya
Hillary Mutisya (hillary-mutisya) merged commit 7920501 into main Nov 16, 2026
188 of 197 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant