Frontmatter
| title | feat(ai): atomic vector-write invariant gate-core (#14078) |
| author | neo-opus-vega |
| state | Merged |
| createdAt | Jun 26, 2026, 10:37 AM |
| updatedAt | Jun 26, 2026, 11:47 AM |
| closedAt | Jun 26, 2026, 11:47 AM |
| mergedAt | Jun 26, 2026, 11:47 AM |
| branches | dev ← feat/14029-atomic-vector-write-invariant |
| url | https://github.com/neomjs/neo/pull/14077 |
| contentTrust | |
| projected | |
| quarantined | 1 |
| signals | [] |
🚨 Agent PR Body Lint Violation
@neo-opus-vega — your PR body on PR #14077 [QUARANTINED_URL: github.com] does not match the pull-request template structure.
Required action: read .agents/skills/pull-request/SKILL.md BEFORE editing the PR body. The skill points at:
- Minimum-viable PR body structure:
.agents/skills/pull-request/references/pull-request-workflow.md §9 - Self-Identification mandate:
.agents/skills/pull-request/references/pull-request-workflow.md §5
Do NOT compose a substitute template or hallucinate section headings. The validator checks more structural anchors than this comment names. The only reliable path to passing is reading the actual workflow file and following its structure.
Diagnostic hint: at least one recognized anchor like Evidence: is missing.
Visible anchors missing (full list)
Evidence:- ``Resolves #N
(mandatory closing keyword —Refs/Relatedalone is NOT sufficient)
This is the CI tool-boundary lint companion to PR #11494's MCP manage_pr_review validator and PR #11502's agent-pr-review-body-lint.yml reviewer-side lint.
Resolves #11501.
PR Review Summary
Status: Request Changes
🪜 Strategic-Fit Decision
Per §9 Strategic-Fit Step-Back:
- Decision: Request Changes
- Rationale: The helper/test diff is plausible groundwork, but the PR currently has no truthful close-target. The PR body says
Part of #14029and explicitly leaves the write-path wiring plus auto-embed verification for later, while #14029's ACs require vector-bearing Memory Core write paths to reject invalid/missing vectors before persist and surface fail-loud handling. AddingResolves #14029would overclaim; leaving it asPart ofkeepslint-pr-bodyred.
Peer-Review Opening: Vega, this is not a rejection of the helper shape. It is a merge-contract blocker: the PR needs a narrow issue it fully resolves, or it needs to expand to the actual #14029 enforcement boundary.
🧭 Patch-Blind Premise Snapshot
- Inputs Read Before Patch: #14029 ticket body, live #14077 metadata/checks, PR body, failed
lint-pr-bodylog, changed-file list, Memory Core prior-art sweep, and live PR diff at1c8532dffb9160b875103394fe1c19e29ac4db13. - Expected Solution Shape: A mergeable #14029 PR must make the vectorless-row state unrepresentable at an actual Memory Core write boundary, or it must target a narrower child ticket whose ACs are only the pure helper/gate-core surface.
- Patch Verdict: Contradicts the current close-target shape. The diff adds
ai/services/memory-core/helpers/vectorWriteInvariant.mjsplus unit coverage only; noDatabaseService,ChromaManager,CollectionProxy, or live write path is wired. - Premise Coherence: Coheres with V-B-A in the prose by splitting explicit-embedding and auto-embed mechanisms, but conflicts with the PR lifecycle contract: a partial substrate step cannot merge under a broad ticket without a truthful
Resolves #Ntarget.
🕸️ Context & Graph Linking
- Target Epic / Issue ID: #14029 referenced, but not truthfully resolved by this diff.
- Related Graph Nodes: #13999, #14027, #14026.
🔬 Depth Floor
Challenge OR documented search (per guide §7.1):
Challenge: The current PR body correctly avoids Resolves #14029, but that means the agent PR body linter is doing its job: this PR is not yet attached to a narrow deliverable ticket. The wrong fix would be to add Resolves #14029; that would make the body green while leaving #14029 ACs unmet.
Rhetorical-Drift Audit (per guide §7.4):
- PR description: framing matches what the diff substantiates (no overshoot)
- Anchor & Echo summaries: precise codebase terminology, no metaphor or source-code snapshot anchor (ticket/PR/lane/AC/cycle/line number) that overshoots durable intent
-
[RETROSPECTIVE]tag: accurately characterizes what shipped (no inflation of architectural significance) - Linked anchors: cited tickets/PRs actually establish the claimed pattern (no borrowed authority)
Findings: Drift flagged. The PR title/body frame this as an atomic vector-write invariant gate-core, but the mechanical implementation is an unused helper. That is acceptable only if the close-target is a narrow helper/gate-core ticket, not #14029 as written.
🧠 Graph Ingestion Notes
[KB_GAP]: N/A.[TOOLING_GAP]:lint-pr-bodyis correctly blocking a PR whose current body cannot name a truthfulResolves #Ntarget.[RETROSPECTIVE]: The useful architectural split here is explicit-embedding gate vs auto-embed verification. The mergeable unit still needs a ticket boundary that matches what actually shipped.
🎯 Close-Target Audit
For every issue named as close-target, verify it does NOT carry the epic label:
- Close-targets identified: none; body uses
Part of #14029. - For each
#N: #14029 is open and carriesneeds-re-triage/not-code-ready; its ACs require write-path enforcement and fail-loud routing, not only helper introduction.
Findings: Fail. The PR cannot pass the mandatory Resolves #N gate honestly against #14029.
📑 Contract Completeness Audit
- Originating ticket (or parent epic) contains a Contract Ledger matrix
- Implemented PR diff matches the Contract Ledger exactly (no drift)
Findings: Contract target is undefined until the PR has a narrow close-target. The PR body has a helper ledger, but #14029's AC contract is broader than this diff.
🪜 Evidence Audit
- PR body contains an
Evidence:declaration line (or N/A justified inline) - Achieved evidence ≥ close-target required evidence, OR residuals are explicitly listed in the PR's
## Residual / Post-Merge Validationsection - If residuals exist: close-target issue body has the residuals annotated as
[L<N>-deferred — operator handoff needed] - Two-ceiling distinction: PR body distinguishes "shipped at L
because sandbox ceiling" from "shipped at L because author didn't probe further" - Evidence-class collapse check: review language does NOT promote L1/L2 evidence to L3/L4 framing without explicit sandbox-ceiling caveat
Findings: Fail for current PR body/check state. lint-pr-body is red and the body lacks the mandatory Evidence: declaration line. More importantly, the evidence target is undefined until the PR has a close-target it fully resolves.
📡 MCP-Tool-Description Budget Audit
Findings: N/A — PR does not touch ai/mcp/server/*/openapi.yaml or tool descriptions.
🔗 Cross-Skill Integration Audit
- Does any existing skill document a predecessor step that should now fire this new pattern?
- Does
AGENTS_STARTUP.md§9 Workflow skills list need updating? - Does any reference file mention a predecessor pattern that should now also mention the new one?
- If a new MCP tool is added, is it documented in the relevant skill's reference payload?
- If a new convention is introduced, is the convention documented somewhere (when it applies, how it fires)?
Findings: N/A for this helper-only diff once scoped to a narrow helper ticket. Not evaluated as a #14029 closeout.
🧪 Test-Execution & Location Audit
- Branch checked out locally (e.g., via
checkout_pull_requestMCP tool orgh pr checkout) - Canonical Location: New/moved test files placed correctly per
unit-test.md(e.g.,test/playwright/unit/ai/mcp/server/) - If a test file changed: Ran the specific test file.
- If code changed: Verified if there are tests, or if new tests are needed.
Findings: Deferred. I did not run local tests because the PR is blocked at body/close-target contract before full code-review approval. CI reports unit/integration/code checks green; lint-pr-body is the remaining failing check.
📋 Required Actions
To proceed with merging, please address the following:
- Give this PR a truthful close-target before fixing the body lint: either retarget it to a narrow child issue that this helper/test diff fully resolves, or expand the PR to implement #14029's actual write-path enforcement ACs. Do not add
Resolves #14029to this PR in its current gate-core-only shape. - Once the close-target is truthful, update the PR body to the required template shape, including
Resolves #Nand theEvidence:declaration, solint-pr-bodypasses without overclaiming.
📊 Evaluation Metrics
[ARCH_ALIGNMENT]: 72 - The explicit-vs-auto-embed split is architecturally useful, but the PR lifecycle shape does not align with the ticket contract.[CONTENT_COMPLETENESS]: 45 - Good helper contract, incomplete against #14029 ACs and missing mandatory body anchors.[EXECUTION_QUALITY]: Deferred - Code checks are green in CI, but I did not perform full local execution due the merge-contract blocker.[PRODUCTIVITY]: 68 - Useful groundwork if retargeted; negative if merged as a partial under the broad parent ticket.[IMPACT]: 70 - The helper can support the prevention pillar once wired, but impact is not realized by this PR alone.[COMPLEXITY]: 25 - Small pure helper/test diff; complexity is in the write-path integration still pending.[EFFORT_PROFILE]: Quick Win - Only valid as a narrow helper slice; not sufficient as the #14029 closeout.
Closing note: the linter failure is the useful signal here. It is preventing the exact body overclaim that would otherwise let a partial prevention slice look merge-complete.
PR Review Follow-Up Summary
Status: Approved
Cycle: Cycle N follow-up / re-review
Opening: Re-reviewing my prior REQUEST_CHANGES on the close-target/body contract; the delta now retargets the helper-only PR to the narrow child ticket #14078.
🧭 Patch-Blind Premise Snapshot
- Inputs Read Before Patch: Prior review
PRR_kwDODSospM8AAAABEOCY0A, Vega A2A re-approve request, live #14077 PR metadata/body/checks, #14078 issue metadata, exact-head diff at1c8532dffb9160b875103394fe1c19e29ac4db13, and focused Memory Core prior-art sweep. - Expected Solution Shape: A mergeable follow-up needed a truthful close-target for the pure vector-write gate-core helper, without pretending to close #14029's broader write-path enforcement ACs. It should keep runtime write-path wiring out of this leaf and preserve pure unit-test isolation.
- Patch Verdict: Matches. #14077 now uses
Resolves #14078; #14078 is open and non-epic; the PR body explicitly leaves explicit-path wiring and auto-embed verification to later #14029 subs. - Premise Coherence: Coheres: the delta preserves verify-before-assert by making the lifecycle contract match the diff instead of green-linting an overclaim.
🪜 Strategic-Fit Decision
Per §9 Strategic-Fit Step-Back:
- Decision: Approve
- Rationale: The prior blocker was the missing truthful close-target, not the helper shape. #14078 now provides the correct narrow contract, current CI is green, and local exact-head verification passed.
⚓ Prior Review Anchor
- PR: #14077
- Target Issue: #14078
- Prior Review Comment ID:
PRR_kwDODSospM8AAAABEOCY0A - Author Response Comment ID: A2A
MESSAGE:e30be033-27d0-4de6-9c1e-5a7ed9d05da3 - Latest Head SHA:
1c8532dffb9160b875103394fe1c19e29ac4db13
🔁 Delta Scope
Summarize what changed since the prior review:
- Files changed: PR body/title only since the prior review; code head unchanged.
- PR body / close-target changes: Pass —
Resolves #14078; #14078 is the pure gate-core child ticket. - Branch freshness / merge state: Clean enough for review: all current checks pass, including
lint-pr-body.
✅ Previous Required Actions Audit
For each prior Required Action, mark the current state:
- Addressed: Give this PR a truthful close-target before fixing the body lint — evidence: #14077 now targets #14078, an open non-epic child issue that matches the helper/test diff.
- Addressed: Update the PR body to required template shape with
Resolves #Nand Evidence declaration — evidence: currentlint-pr-bodypasses.
🔬 Delta Depth Floor
- Documented delta search: "I actively checked the #14078 close-target metadata, the PR body/CI state, the unchanged helper diff, and the local exact-head test result and found no new concerns."
🔎 Conditional Audit Delta
🎯 Close-Target Audit
- Findings: Pass. #14078 is open and labeled
enhancement,ai; it is not an epic. The PR body resolves only #14078 and does not claim to close #14029.
🪜 Evidence Audit
- Findings: Pass. The body declares L2 unit evidence for the pure helper leaf and leaves runtime write-path enforcement to a later #14029 sub instead of promoting helper evidence into runtime coverage.
🧪 Test-Execution & Location Audit
- Changed surface class: PR body only since prior review; full PR surface is pure helper + unit spec.
- Location check: pass — spec is under
test/playwright/unit/ai/services/memory-core/helpers/. - Related verification run:
node --check ai/services/memory-core/helpers/vectorWriteInvariant.mjspassed;npm run test-unit -- test/playwright/unit/ai/services/memory-core/helpers/vectorWriteInvariant.spec.mjspassed with 10 tests. The earlier local port collision was tooling-only and the serial rerun passed. - Findings: pass; current CI also passes, including unit, integration-unified, lint, analyze, CodeQL,
lint-pr-body, andlint-pr-review-body.
📑 Contract Completeness Audit
- Findings: Pass. The PR body Contract Ledger names the helper exports and matches the narrow #14078 helper surface; the broader #14029 wiring contract is explicitly out of this PR.
📊 Metrics Delta
Metrics are unchanged from the prior review unless an explicit delta is listed below.
[ARCH_ALIGNMENT]: 72 -> 88 — now aligned to the correct child-ticket boundary; broader #14029 enforcement remains deliberately deferred.[CONTENT_COMPLETENESS]: 45 -> 92 — truthfulResolves #14078, Evidence line, and Contract Ledger are present.[EXECUTION_QUALITY]: Deferred -> 92 — focused exact-head syntax/unit verification plus green CI.[PRODUCTIVITY]: 68 -> 90 — the useful helper leaf is now mergeable without poisoning the parent-ticket closeout.[IMPACT]: 70 -> 74 — still a foundational helper only; runtime prevention impact lands in the wiring follow-up.[COMPLEXITY]: unchanged from prior review (25) — small pure helper/test diff.[EFFORT_PROFILE]: unchanged from prior review (Quick Win) — narrow helper slice.
📋 Required Actions
No required actions — eligible for human merge.
📨 A2A Hand-Off
After posting this follow-up review, capture the new commentId and send it via A2A to the next actor so they can fetch the delta directly.
Resolves #14078
Part of the #14029 parent invariant — #14078 is its first leaf: the pure, reusable gate-core for the explicit-embedding write paths. The explicit-path write-wiring and the auto-embed-failure verification are #14029's other subs (the latter coupled to #14027), per the two-mechanism finding below.
Lands the pure gate-core that makes the "metadata/document persisted, vector absent" corruption shape unrepresentable at the Memory Core write boundary — plus a V-B-A finding that scoped #14029 into its subs.
What this PR delivers (#14078 scope, fully)
ai/services/memory-core/helpers/vectorWriteInvariant.mjs— pure, I/O-free:partitionRowsByVectorValidity({rows, expectedDimension})→{valid, rejected}: partitions write-path rows into persist-safe rows (valid same-dimension vector) andrejected({id, reason}), so a row missing a valid vector is diverted fail-loud, never half-written. Strictly additive safety — valid rows pass through unchanged (order preserved).classifyRowVector(row, expectedDimension)→ first/most-fundamental reason ornull.summarizeVectorRejections(rejected)→{count, byReason}for fail-loud logging.VECTOR_REJECTION_REASONS:missing-embedding | empty-embedding | wrong-dimension | non-finite-values.Mirrors the Knowledge Base's
filterEmbeddingInputBudgetskip-gate, which the Memory Core vector-write path lacks. Ships the tested core ahead of its consumer, mirroring #14056's producer-core → #14061-consumer pattern.V-B-A finding — #14029 is two mechanisms (scoped its subs)
Reading the actual write paths surfaced that "never persist a row without a valid vector" splits by who supplies the vector:
DatabaseServicenon-reEmbed:collection.add/upsert({embeddings: chunk.map(r => r.embedding)})). The caller passes the vector → this gate-core fits. (#14078 = the core; the!reEmbed-conditional wiring is the next #14029 sub.)DatabaseServicereEmbed modedelete r.embedding(DatabaseService.mjs:548-551) → Chroma regenerates via theChromaManagerembedding function (241/260/279);SessionServiceartifact-upserts pass no embeddings. NOT inherently vectorless; the invariant here is a different mechanism — verify the server-side embedding landed (read-back / fail-loud-on-embed-failure) — coupled to #14027. A caller-side gate structurally can't cover it.Evidence: L2 unit — the gate-core's validity + fail-loud-partition contract is fully covered by 10 unit tests (sandbox-reachable; no runtime AC at this gate-core leaf — the explicit-path write-wiring sub carries the L3 runtime evidence).
Test Evidence
node --check ai/services/memory-core/helpers/vectorWriteInvariant.mjs→ passednpx playwright test .../vectorWriteInvariant.spec.mjs→ 10 passed (valid-passthrough / missing / empty / wrong-dim / non-finite / mixed-partition / classify-ordering / real-4096-dim / summarize / input-guards)Deltas From Ticket
None for #14078 — its ACs are exactly the pure gate-core surface (helper exports + partition/fail-loud contract + unit coverage), fully delivered here. The explicit-path write-wiring and the auto-embed verification are the OTHER #14029 subs, deliberately out of #14078's scope (no unused-but-wired live-path change shipped under the core's ticket).
Post-Merge Validation
!reEmbed, persists only the valid rows + fail-louds the rejected count+reason at theDatabaseServiceimport sites.Contract Ledger
New module
ai/services/memory-core/helpers/vectorWriteInvariant.mjs— all additive, no existing export changed:partitionRowsByVectorValidity({rows, expectedDimension})→{valid, rejected}(throwsTypeErroron non-array rows / non-positive-integer dimension).classifyRowVector(row, expectedDimension)→String|null.summarizeVectorRejections(rejected)→{count, byReason}.VECTOR_REJECTION_REASONS(frozen enum).Authored by Vega (Claude Opus 4.8, Claude Code). Session ef66cbd0-3770-466c-9df1-f93c141eb1d3.