archgraph-argo 0.1.0

package/argo/scripts/graph-rag/ARCHITECTURE.md

@@ -0,0 +1,192 @@
+# Production Graph RAG Contract
+
+This local contract refines `OVERALL_ARCHITECTURE.md`.
+
+## Responsibilities
+
+- `productionGraphRagRuntime.js` is the single composition boundary for production semantic queries and index-delivery qualification.
+- `externalProductionConfig.js` reads Neo4j and embedding-provider credentials from injected or external secure configuration and returns typed blocking failures when required values are absent.
+- `embeddingQualificationGate.js` accepts only explicit human-approved provider, model identity, model version, and dimensions. It must reject missing approval, missing fields, and any inferred provider/model/version/dimensions.
+- `neo4jNativeRetrieval.js` owns Neo4j JavaScript-driver retrieval and returns projection identity/version evidence; it never becomes canonical authority.
+- `canonicalProjectionAuthority.js` compares projection evidence with the canonical graph and either selects canonical state or rejects stale/conflicting projection state.
+- `ensureArgoHarnessEnvironment.js`, through the projection/runtime path, must load only the approved repository-relative `.argo/.env` into `process.env` before Neo4j projection checks when direct process values are absent; it must ignore root or alternate env files, preserve process precedence/conflict behavior, and emit no secret-bearing diagnostics.
+- `liveEmbeddingProviderConfig.js` preflights the unique `.argo/.env`, resolves the approved process/file source policy for both secrets, and returns only sanitized configuration evidence.
+- `liveEmbeddingProviderClient.js` performs one explicitly opted-in HTTPS embedding request against the approved Beijing OpenAI-compatible endpoint; it is not a general generation or lifecycle component.
+- `liveEmbeddingIndexGate.js` sequences exact qualification, real-provider vector validation, and one controlled Neo4j evidence write. Invalid or failed paths never invoke the write boundary.
+- W4 seed retrieval owns only relevance-discovery output: Element, ArchitectureRelationship, and View seed channels must be separately observable, directly attributed, independently thresholded, and complete for every candidate meeting that channel gate. Zero-result channel outcomes are valid.
+- W3 seed selection proves exact threshold-all correctness before ANN comparison: every qualifying Element, ArchitectureRelationship, and View peer at or above its channel threshold is returned, unrelated queries have zero forced hits, and ANN top-k is recorded only as performance evidence.
+- W3 index lifecycle extracts only records affected by successful canonical mutations, advances canonical/content/index version evidence for Element, ArchitectureRelationship, and View records, and leaves partial or failed persistence non-Aligned.
+- W3 alignment gating rejects pure semantic queries for Updating, Stale, Failed, partial, or unknown index state while preserving no-argument full snapshots and explicit canonical-anchor reads.
+- W3 TS-09 is a blocking gate: `productionGraphRagRuntime.generateAffectedEmbeddings()` must expose `runtime: "nodejs"`, `neo4jGenAiPluginRequired: false`, provider-adapter invocation, parameterized persistence evidence, complete Element/ArchitectureRelationship/View metadata, and non-Aligned partial failure behavior before W3 can be accepted.
+- W3.1 mutation-vector integration is an automatic effect of the `applySystemArchitectureMutation` write success path. The mutation tool must pass its actual `touchedElementIds`, `touchedRelationshipIds`, and `touchedViewIds` to the lifecycle, invoke the real approved Qwen adapter under explicit live opt-in, persist complete vector/version/provider evidence into Neo4j, verify vector-query retrieval of the changed records, then return `embeddingLifecycle` and `alignment` in the MCP mutation response. Harness-created lifecycle execution, preset `expectedTouchedRecords`, or equivalent manual post-mutation evidence cannot satisfy W3.1.
+- W5 purpose-policy closure begins only after W4 seed retrieval. It must convert semantic seeds into mandatory graph ranges through named parameterized Cypher policies, bound parameters, explicit ArchiMate relationship direction semantics, category-specific stop conditions, and explicit exclusions. Free-generated Cypher, Agent identity, text similarity, arbitrary depth, and connected-component expansion are forbidden for mandatory closure decisions.
+- W6 structural result completion begins only after W5 range selection. It must add non-empty same-version endpoint relationship evidence with source/target ids and matching endpoint Element objects, return the explicitly targeted View, exclude named overlapping Views unless independently matched or explicitly requested, complete only selected View objects with exact metadata/member/relationship object sets and endpoints, assign exactly one ordered `firstInclusionReason` per returned object from explicit duplicate-path fixtures, preserve supplementary reasons without overwriting the first reason, and expose canonical graph, semantic content/index, alignment, purpose, policy id, policy parameters, and policy anchors.
+- BP-MCP-SEM relationship endpoint closure is the minimal ordinary semantic subset form of W6 endpoint closure. A selected Relationship returns its canonical Relationship object and both canonical endpoint Elements, but endpoint neighbors, endpoint-owned Views, unrelated Relationships, traversal expansion, and neighborhood closure remain excluded unless independently selected. Broken, missing, invalid, deleted, or cross-version endpoint references fail closed with `SEMANTIC_SUBSET_RELATIONSHIP_MISSING` and no partial successful subset.
+- BP-MCP-SEM View membership closure is the minimal ordinary semantic subset form of W6 View closure. A selected View returns complete canonical View metadata, declared included Elements, declared included Relationships, and endpoint Elements for included Relationships. Shared members do not cascade into overlapping Views unless those Views independently match or are explicitly selected. Broken View members, included Relationships, or in-View relationship endpoints fail closed with `SEMANTIC_SUBSET_VIEW_MISSING` and no incomplete View success.
+- W7 business acceptance begins only after W2-W6 acceptance evidence is present. It must evaluate the approved five-purpose business benchmark as business evidence: every purpose has non-empty mandatory key seed ids, actual recalled key seed ids, non-empty expected closure ids, actual observed closure ids, no missing key seeds, expected closure correctness, explicitly recorded unrelated forced-hit evidence, unrelated query fixtures produce zero forced hits, precision is recorded per purpose and in aggregate inside `[0, 1]`, and no release precision threshold is invented. Missing mandatory seed fixtures, missing expected closure fixtures, missing actual recall observations, wrong same-count recalled ids, non-empty missing key seed evidence, missing actual closure observations, closure correctness below 100%, missing or negative unrelated forced-hit evidence, positive unrelated forced hits, empty benchmarks, incomplete benchmarks, and out-of-range precision are blocking failures; expected seed, expected closure, arbitrary recalled-id counts, or default zero unrelated-hit values cannot be reused as fabricated observations.
+- DT-19 capacity evidence begins after real DT-18 quality evidence. It must preserve explicit `observedResultIds` or equivalent result ids from actual phase-1 query observations, never use closure fallback as result evidence, record measured precision for every declared purpose, validate any provided result cardinality against the result ID count so cardinality mismatch blocks, block explicitly when quality evidence or result evidence is missing, and must not return or infer cap, budget, pagination, truncation, continuation, top-k, token-budget, result-limit, or capacity-policy decisions. This is evidence for later human capacity governance, not a release threshold.
+- Seven-wave delivery gating must block W7 when W2-W6 prerequisite evidence is incomplete, block whole delivery when the W7 DT-18 business benchmark is missing, failing, incomplete, or carries precision outside `[0, 1]`, and permit overall delivery only after prerequisites and the W7 benchmark pass. DT-19 capacity controls remain evidence-only and cannot become a W7 release rule.
+- WP-P1 delegates durable production persistence and full-backfill orchestration inward to `semantic-persistence/`. `productionGraphRagRuntime.js` composes concrete production Neo4j projection/checkpoint adapters from `semanticPersistence` dependencies and exposes `runSemanticBackfill(request)`; it must not absorb checkpoint, durable-store, tombstone, or production-cleanup policy.
+- WP-P1 semantic backfill is invoked only by private canonical argo init composition after internal exact consent and verified same-version structural projection, never by a public standalone MCP route or inferred mutation signal. Missing consent, version match, external credentials, or provider qualification blocks before provider/store/checkpoint/index side effects. It independently completes Element, ArchitectureRelationship, and View through bounded durable checkpoints before Aligned.
+- The separate production store upserts changed stable canonical identities, deletes tombstones, preserves complete canonical/content/index/provider/model/version/dimensions/vector metadata across restart, rejects `runId` records, and exposes exactly four methods with no cleanup API. Existing `liveEmbeddingNeo4jBoundary.js` remains test-evidence infrastructure and unchanged.
+- `defaultSemanticRetrieval.js` is the WP-P2 deep composition module for the shipped uninjected MCP semantic path. `createDefaultSemanticRetrieval(dependencies)` accepts the unified production `readinessBoundary` and returns `retrieve(request)` plus the narrow read-only `readReadiness()`. Both methods resolve through one private `readAndEvaluatePersistentReadiness` path that retains the existing approved composition, normalization, threshold filtering, expanding-window exhaustion, purpose closure, endpoint/View closure, provenance, and canonical completion. The safe failure envelope preserves stored `category`, `message`, and `action` plus state/version/channel evidence and `fullSnapshotFallback: false`; unknown diagnostic fields and secrets never cross the boundary.
+- Approved external-source resolution must directly read and attribute all required embedding-profile, Neo4j, and provider-secret keys before readiness; success with zero or partial approved-source reads is forbidden. Production-semantic-query directly inspects all three legacy Neo4j alias keys and rejects legacy-only or mixed valid-canonical-plus-any-legacy-alias sources with `SECRET_SOURCE_PROVENANCE_PROHIBITED` before attribution, selection, readiness, provider, or driver effects. Inspection cannot attribute, normalize, return, or use a legacy value. It also rejects missing secrets, unsafe `.argo/.env` path/git/file/reparse/ACL state, conflicting process/file values, and test/default, literal, fallback, alias, or indirect credential operations. The test composition accepts raw `sourceBehavior` plus filesystem/git/ACL adapters; ready-made environment or normalized configuration objects are prohibited.
+- Persistent readiness is fail-closed. `SemanticIndexPending`, partial, stale, failed, unknown, channel-incomplete, explicit content-version mismatch, explicit index-version mismatch, canonical mismatch, and mixed-version evidence reject before provider or vector-query calls with the stored redacted category/message/action, exact state, canonical/content/index versions, completed/missing/mismatched channels, and `fullSnapshotFallback: false`. A single ordered ledger must place credential-source operations before readiness, readiness before provider, and provider before all vector windows. Only complete aligned evidence for all three channels permits retrieval.
+- The default retrieval module may expose a module-owned callback-scoped test composition that accepts raw source behavior/metadata, provider transport, and Neo4j driver operations. The callback still invokes `getSystemArchitecture` without a semantic retrieval boundary or runtime dependency override; fixtures may observe raw source reads, embedding requests, readiness reads, parameterized Vector Index windows, continuation, and exhaustion but may not return a preassembled semantic result, readiness verdict, or seed list.
+- WP-P2 reuses the accepted provider qualification, external credential, unified persistent readiness, persistent semantic record, threshold-all seed, deterministic purpose closure, endpoint/View completion, provenance, and canonical-authority boundaries. The canonical lifecycle may modify this file only to accept/read the unified production readiness boundary and preserve its safe failure evidence; all retrieval, credential, provider, vector, closure, result, and callback-scoped raw-port test-composition algorithms remain frozen.
+- Historical WP-P3 used `semanticOperatorJourney.js` with six function ports plus one mandatory non-secret `readinessAttestationStore`. The accepted successor retains the file as a private seam but does not require its explicit-attestation authorization for ordinary queries; the store remains frozen historical evidence and cannot become a second readiness authority.
+- The accepted canonical lifecycle supersedes WP-P3 public exposure while retaining this module as a private composition seam. Before every outcome, canonical argo init transforms the existing unified readiness record while preserving identity, `recordId`, and canonical version and increasing revision. Both exact `1` gates invalidate before provider/vector work and run WP-P1 full reconciliation; both disabled durably become SemanticIndexPending/disabled with zero provider/vector effects; half-enabled or malformed gates and missing/unsafe external configuration durably become actionable redacted Failed/Stale with zero provider/vector effects. Reconciliation failure records Failed/Stale with exact safe category/message/action on that same record and in exported init evidence; raw diagnostics and secret canaries remain private, public fallback is literal false, and only queryability then global coherence may produce verified Aligned. No third gate exists.
+- `mutationEmbeddingVectorLifecycle.js` adds `createPersistentMutationEmbeddingLifecycle(dependencies)` for both batch and focused canonical writes. Its `reconcile({ canonicalWrite, preview, gates })` invalidates readiness before semantic side effects, consumes exact touched ID arrays, maps add/update to durable upsert and remove to durable tombstone, and records Aligned only after touched-record queryability plus global coherence. Preview performs zero vector effects. Disabled writes record Pending/Stale without provider/vector work. Partial failure records Failed/Stale while preserving canonical authority. The production path has no runId, cleanup, clear, truncate, or test-marker deletion behavior.
+- Canonical argo init now owns the gate decision automatically; it does not require caller `automaticBackfillOptIn` or a separate public backfill/readiness command. Private WP-P1 calls still preserve explicit internal consent, readiness invalidation before external configuration/provider/vector work, approved configuration ordering, checkpoint/resume/no-replay evidence, durable failure, rerun idempotence, and redaction.
+- Every ordinary query now consumes a fresh WP-P2 persistent readiness evaluation on that invocation. Historical attestation records and process-local flags do not authorize or block the successor query path.
+- `semanticReadinessAttestationStore.js` exposes `createSemanticReadinessAttestationStore(...)` and owns `.argo/temp/semantic-readiness-attestation.json`. Its trust boundary is same OS user plus local workspace, matching canonical JSON authority; a malicious same-identity process is explicitly out of scope. It rejects malformed/extra/tampered/foreign records, files or parent directories that are symbolic links/reparse points, non-regular files, foreign owners, group/other POSIX permissions, and unparseable or unsafe Windows ACLs. Windows owner text must equal current `whoami` identity exactly; group ownership is foreign. Both file and parent ACLs must contain an effective current-identity modify/full allow after deny precedence. Protected effective `icacls` rights are exactly `F`, `M`, `RX`, `R`, `W`, `D`, `DE`, `RC`, `WDAC`, `WO`, `S`, `AS`, `MA`, `GR`, `GW`, `GE`, `GA`, `RD`, `WD`, `AD`, `REA`, `WEA`, `X`, `DC`, `RA`, and `WA`; foreign allows or current-identity denies containing any protected right fail closed. Protected allows may name only the current identity or `NT AUTHORITY\SYSTEM`. `BUILTIN\Users`, `BUILTIN\Administrators`, Everyone/S-1-1-0, Authenticated Users, arbitrary foreign allows, absent current-identity ACEs, or a current-identity deny fail closed. The exact redacted action is `Restrict .argo/temp and semantic-readiness-attestation.json ownership and ACLs to the current OS identity and SYSTEM, then run semantic readiness again`. Record uses an exclusive `wx` same-directory temporary file with mode `0600`, complete write, file flush/close, atomic rename, post-rename file ACL/owner verification, and parent-directory fsync on supported platforms. Because Node/Windows does not support directory fsync, the explicit Windows branch must prove same-directory/same-volume rename and record the `WINDOWS_DIRECTORY_FSYNC_UNSUPPORTED_SAME_DIRECTORY_RENAME` fallback; silent omission is prohibited. An interrupted temporary-only write never authorizes; a previously committed target remains authoritative. The deterministic integrity digest detects accidental tampering and is not a MAC, signature, or provenance proof.
+- System Architecture MCP and unified MCP expose only `getSystemArchitecture` for architecture read/query semantics. The former standalone start/backfill/readiness MCP tools are absent from discovery and routing; accepted WP-P1/WP-P2 functions remain private composition. Every ordinary query delegates into the same `defaultSemanticRetrieval.js` algorithm and uses the current unified readiness result from that invocation before provider/vector work. No-argument and graph-tidy bypasses remain exact. Canonical init composes the existing readiness store's invalidate, failure, and Aligned ports; each init invocation transforms the same durable record before its outcome, and successful canonical mutation still invalidates before semantic effects. The unified gateway's init-specific error path maps the approved safe reconciliation `message` beside category/action without forwarding raw diagnostics; shared `semanticOperatorError.js` query mapping remains unchanged. MCP wire errors preserve only approved redacted fields and `fullSnapshotFallback`; stack, arbitrary diagnostics, secrets, and unsafe source are excluded.
+
+## Public interface
+
+The four inward boundaries are independently callable and independently testable before runtime composition:
+
+- `resolveExternalProductionConfig(configuration, context)` identifies each missing Neo4j URI, username, password, or embedding credential and blocks both startup and semantic-query operations. No direct literal or logical/nullish/ternary fallback may synthesize these values.
+- `evaluateEmbeddingQualification(qualification)` accepts only `approvedByHuman === true`, trimmed non-empty provider/model identity/version, and `Number.isInteger(dimensions) && dimensions > 0`; it rejects coercion and implicit defaults.
+- `enforceCanonicalProjectionAuthority(input)` rejects or replaces stale/conflicting projection evidence without requiring runtime composition.
+- `createNeo4jNativeRetrieval(dependencies)` returns a `retrieve(request)` boundary that forwards each request exactly once and returns the injected query boundary's complete dynamic result unchanged.
+
+`resolveApprovedLiveConfiguration({ repositoryRoot })` is the single production configuration/preflight boundary and creates its sole production source adapter internally. It rejects caller-supplied `adapters.source`, cloned adapters, and self-issued `isIssuedTrace` claims with `SOURCE_ADAPTER_UNTRUSTED`. Frozen fixtures use `withApprovedLiveConfigurationTestComposition({ sourceBehavior, adapters, observeTrace }, callback)`: this module-owned composition root wraps raw behavior, creates and registers the trusted adapter/capability in private identity sets, and invokes the callback with a resolver closure; neither adapter nor capability is returned. Internally issued process reads are frozen `{ value, trace }`; file reads are frozen `{ key, value, trace }[]`. Each trace is generated during the actual wrapped operation and has the exact five-field schema `sourceKind/path/key/operation/aliasChain`. Accepted results expose complete normalized configuration plus per-key attribution; rejected results expose only stable categories.
+
+`createSystemMetadataCommandAdapter({ repositoryRoot })` in `systemMetadataCommandAdapter.js` remains the only production boundary allowed to import Node `child_process` and retains its exact four credential-source capabilities. The narrow sibling `createReadinessAttestationMetadataAdapter({ repositoryRoot })` closes over only the exact repository `.argo/temp` directory and `semantic-readiness-attestation.json` path and exposes four zero-argument metadata reads: current identity, directory ACL, file ACL, and file owner. It cannot accept a path, executable, flags, environment, stdin, or secret. `whoami` and `icacls` provide identity/ACL evidence; Windows owner evidence uses one fixed `powershell.exe -NoProfile -NonInteractive -Command` Get-Acl Owner expression whose literal path is generated only from the closure-bound repository root—no caller script or interpolation is accepted. This eighth Coding file is required because Node filesystem metadata reports unusable Windows uid/gid and exposes neither ACL nor owner APIs. Existing callback-scoped credential test composition, revocation, and capability identity behavior remain unchanged.
+
+`createApprovedNeo4jBoundary({ configuration, neo4j, logger })` is the production connection/composition boundary. It alone passes username/password to `neo4j.auth.basic`, opens the driver, verifies connectivity before queries, and returns the controlled count/write/read/cleanup boundary used by the live index gate.
+
+`createProductionGraphRagRuntime(dependencies)` returns:
+
+- `querySemantic(request)` for production semantic queries.
+- `evaluateIndexDelivery(request)` for the embedding qualification and credential release gate.
+- `selectThresholdAllSeeds(request)` for W4 exact per-channel threshold-all correctness. It must not collapse channels into one global rank, infer Relationship or View seeds from Element-only retrieval, perform graph closure, perform traversal or neighborhood expansion, force unrelated hits, or use ANN top-k as the correctness source.
+- `generateAffectedEmbeddings(input)` for all-mutation affected-record extraction, provider generation, vector/evidence persistence, lifecycle state transitions, and non-Aligned partial failure reporting.
+- `evaluateSemanticAlignment(request)` for pure semantic query availability; unaligned states return a stable rejection before seed retrieval.
+- `closePurposePolicyScope(request)` for W5 deterministic purpose closure plus W6 structural result completion. It must return closure policy evidence, bound parameters, ArchiMate relationship semantics, included range, excluded category scope, non-empty endpoint closure with identity/version checks, complete View closure with target View presence, overlapping View ID exclusion, exact member/relationship sets, and parent viewpoint evidence, ordered first-inclusion provenance over duplicate-path fixtures, policy/index/version evidence, and proof that free-generated Cypher did not decide mandatory inclusion.
+- `evaluatePhase1QualityBenchmark(request)` for W7 DT-18 business benchmark evidence. It must return the approved five-purpose benchmark id, per-purpose recall/closure/unrelated/precision observations, aggregate key seed recall `1` computed from actual mandatory-seed hits, aggregate closure correctness `1`, unrelated forced hits `0`, recorded precision, and no release precision threshold. Any missing key seed, closure miss, or positive unrelated forced hit blocks the benchmark.
+- `evaluateCapacityEvidence(request)` for DT-19 capacity evidence. It must consume real DT-18 quality evidence, return `capacityEvidence.byPurpose` for every declared purpose with integer `resultCardinality >= 0` derived from explicit `observedResultIds` or equivalent result ids and `measuredPrecision` inside `[0, 1]`, reject closure fallback, block missing quality or result evidence with clear categories, validate any result cardinality mismatch, and it must not expose cap, budget, pagination, truncation, continuation, top-k, token-budget, result-limit, or capacity-policy decision fields.
+- `evaluateDeliverySequence(request)` for TS-08. It must receive completed wave evidence and W7 quality benchmark evidence, report missing prerequisite waves before W7, block whole delivery when DT-18 is missing or failing, and allow delivery only after W2-W6 and W7 business benchmark evidence pass.
+- `runSemanticBackfill(request)` composes and delegates to the production semantic Neo4j adapter, durable checkpoint store, projection store, and backfill boundary as a private argo-init port. Structural mutation never invokes full backfill; it uses only the incremental lifecycle.
+
+`createDefaultSemanticRetrieval({ canonicalGraph, repositoryRoot, readinessBoundary })` in `defaultSemanticRetrieval.js` returns:
+
+- `retrieve(request)` for the shipped default uninjected MCP semantic path. It must resolve approved raw external sources, read persistent readiness before embedding or retrieval, preserve exact qualification evidence, issue one qualified query-embedding request, and independently query `argo_production_semantic_element_vector`, `argo_production_semantic_relationship_vector`, and `argo_production_semantic_view_vector` with exact parameterized `db.index.vector.queryNodes($indexName, $topK, $vector)` Cypher.
+- The accepted public boundary remains `createDefaultSemanticRetrieval(dependencies).retrieve(request)`; operator authorization wraps it but does not replace or alter its WP-P2 fail-closed evaluation.
+- Every channel request correlates the exact index name and the unmodified raw provider vector, begins with top-k/window size two, and expands top-k by following the raw continuation until exhaustion. Every response records `offset`, `windowSize`, `returnedCount`, `hasMore`, `nextOffset`, and `windowExhausted`; acceptance includes qualifying peers beyond the initial window. An all-zero result still performs readiness, embedding, and exactly one exhausted sequence for each channel.
+- Aligned retrieval output must preserve separate seed channels and feed their exact IDs into `w5.implementation-design.v1` bound parameters, exact ArchiMate Realization direction, endpoint source/target objects with governing versions, the complete selected View metadata and viewpoint binding, its parent viewpoint, ordered versioned member and relationship endpoint objects, overlapping-View exclusion, one unique first-inclusion provenance record for every returned object with ordered supplementary closure reasons, and matching canonical/content/index versions.
+- Rejected readiness output must identify the exact observed state, canonical/content/index versions, completed, missing, and mismatched channels, carry `fullSnapshotFallback: false`, terminate the ordered operation ledger at readiness, and produce zero provider and vector-query calls.
+- `readinessBoundary.read()` is the production composition hook for the shared durable identity/record/version/revision. It is not a test-only verdict or preassembled result. System and unified routers pass that boundary into this factory and may not duplicate embedding, Vector Index, threshold, exhaustion, closure, or canonical-completion behavior.
+- The production factory obtains credentials from approved external configuration only. Its `production-semantic-query` source-adapter use case requires all approved profile, Neo4j, and provider-secret values from direct process or protected canonical-file sources without E2E-only opt-ins; existing E2E operations retain their explicit opt-in security contracts. It directly inspects every legacy Neo4j alias and rejects any present alias even when all canonical values are valid, without attributing, selecting, or using the legacy value. No approved-test provider, default/test credential, legacy alias, fallback source, synthetic empty-seed adapter, caller-injected semantic retrieval boundary, content/anchor-based deterministic-runtime routing, or snapshot fallback is permitted. Legacy control words and explicit anchors do not bypass the production gate; omitted-query and every graph-tidy request, including anchored graph-tidy, retain full-snapshot behavior with zero semantic operations.
+
+`createProductionSemanticOperatorJourney(dependencies)` in `semanticOperatorJourney.js` is now private and returns:
+
+- `startNewProject(request)`, called only from canonical argo init, which applies the exact internal two-gate decision and composes structural projection plus optional WP-P1 reconciliation.
+- `query(request)`, called only from public `getSystemArchitecture(query)`, which freshly reads WP-P2 readiness and delegates only when current durable state is complete and Aligned.
+- `readFullSnapshot()`, retained as an internal compatibility adapter for the exact no-argument canonical envelope.
+
+No standalone MCP start/backfill/readiness command is exposed. Historical CLI/attestation code may remain frozen compatibility evidence but is not a public authorization path. The private composition ports are initialization, structural projection, approved gate/configuration resolution, WP-P1 backfill, WP-P2 readiness, semantic retrieval, and canonical snapshot reading.
+
+`createLiveEmbeddingIndexGate(dependencies)` returns one public gate:
+
+- `executeApprovedEmbedding(input)` for both the real opt-in path and all injected invalid/error cases. There is no production scenario-label shortcut.
+- Every rejected live-provider scenario produces zero index writes.
+- Only a finite numeric vector with exactly 1024 values can reach the write boundary.
+- A frozen Harness-owned transport wrapper independently observes request count, origin/path, method, dynamic input, explicit model/dimensions, protected-header presence, and the raw response vector. Production output and persisted vector evidence must match that observed response exactly.
+- Persisted evidence includes provider/model/qualification identity, dimensions, complete vector, canonical identity/version, content identity/version, and index identity/version. Cleanup is complete only when the Harness observes zero remaining test records.
+- Secret/file/path/git/reparse/ACL/conflict preflight completes before transport construction, Neo4j connection, or gate execution.
+
+`createMutationEmbeddingVectorLifecycle(dependencies)` in `mutationEmbeddingVectorLifecycle.js` is the W3.1 production lifecycle boundary. It returns `execute(input)` and must:
+
+- Accept the applied mutation observation from `applySystemArchitectureMutation`, not an independently fabricated record list.
+- Preserve `design/KG/SystemArchitecture.json` or the supplied `architecturePath` as canonical authority; Neo4j remains a vector projection and cannot overwrite canonical JSON semantics.
+- Extract exactly touched Element, ArchitectureRelationship, and View records from the mutation response's actual touched id arrays, including object identity, channel, canonical version, content version, and next index version.
+- Reuse the approved live configuration, Qwen profile, provider client, and Neo4j boundary; it must not introduce alternate secret sources, offline substitutes, Python sidecars, external Graph RAG frameworks, or Neo4j GenAI Plugin requirements.
+- Query Neo4j vector evidence after persistence and return the changed record ids from that query before reporting `alignmentState: "Aligned"`.
+- Return Stale or Failed and keep pure semantic queries rejected when provider generation, vector persistence, vector-query verification, or partial-record completion fails.
+- Be invoked by the MCP mutation write path and surface its result through response fields `embeddingLifecycle` and `alignment`; downstream tests must not create or execute this lifecycle themselves.
+
+`createPersistentMutationEmbeddingLifecycle(dependencies)` in the same module is the durable non-test production boundary used by batch and focused writes. It consumes approved external configuration, the production four-method semantic projection store, a readiness store, qualified provider, queryability verifier, and global-coherence verifier. It never adapts `liveEmbeddingNeo4jBoundary.js`, never creates a runId, and never calls cleanup. Controlled code-complete acceptance injects those ports but not a preassembled result; protected live release additionally requires both exact gates, safe external credentials, real finite 1024-dimensional provider output, durable Neo4j records, vector queryability, and global coherence.
+
+Dependencies are explicit: `configuration`, `canonicalGraph`, `neo4jRetrievalBoundary`, and `embeddingQualification`. Tests may inject fakes at these interfaces; production code must not import tests.
+
+Successful query evidence identifies `nodejs` as runtime, `neo4j-native` as retrieval platform, and reports that neither Python nor Neo4j GenAI Plugin is required. Blocking failures use stable categories:
+
+- `EXTERNAL_CREDENTIALS_REQUIRED`
+- `EMBEDDING_QUALIFICATION_REQUIRED`
+- `EMBEDDING_CONFIGURATION_REQUIRED`
+- `IMPLICIT_EMBEDDING_DEFAULT_PROHIBITED`
+- `CANONICAL_PROJECTION_CONFLICT`
+
+## Local dependencies
+
+- Runtime composition may depend inward on the configuration, qualification, retrieval, and authority modules in this directory; those modules never depend outward on runtime composition.
+- Neo4j retrieval may depend on `neo4j-driver`; no module here may depend on Python, an external Graph RAG framework, the Neo4j GenAI Plugin, or `tests/`.
+- `systemMetadataCommandAdapter.js` is the sole system-process exception and owns the private validator through which every invocation passes immediately before its private executor. It uses `spawnSync` with `shell: false`, exact repository cwd, UTF-8 output, Windows-hidden execution, and a sanitized PATH/PATHEXT/SystemRoot/WINDIR environment. The existing credential adapter allowlist is unchanged; the separate attestation profile adds only `whoami`, `icacls <exact repository .argo/temp directory>`, and `icacls <exact repository .argo/temp/semantic-readiness-attestation.json>`.
+- Command templates are structural constants, not strings: no command concatenation, extra flags, shell, stdin, caller-controlled executable/argv/path/script, Python/cmd/Node sidecar, arbitrary executable, network command, or secret-bearing argv/environment is permitted. The only PowerShell exception is the exact closure-bound, non-interactive readiness-owner Get-Acl template above. Git results become booleans; identity/ACL/owner stdout is parsed only as metadata. stderr, command records, and raw outputs never enter configuration evidence or logs.
+- A test-composed adapter is a frozen null-prototype object whose complete own reflection surface is exactly the four non-writable/non-configurable frozen capability functions, with no symbols, executor fields, hidden adapter/capability references, function prototype properties, or callable backdoor. Executor and mutation hooks remain private lexical state and are erased by revocation.
+- Authority policy reads `design/KG/SystemArchitecture.json` through an injected canonical graph boundary and treats Neo4j as a projection only.
+- Credentials are values, never module-level defaults; provider credentials must never be interpolated into or transported through Cypher.
+- Cypher credential protection follows query and parameter variables structurally into execution calls; keyword-distance windows are not acceptable enforcement.
+- The only file source is repository-relative `.argo/.env`; it may provide the five approved non-sensitive `ARGO_EMBEDDING_*` fields, `ARGO_NEO4J_DATABASE_URL`, `ARGO_NEO4J_DATABASE_USERNAME`, `ARGO_NEO4J_DATABASE_PASSWORD`, and `QWEN_KEY`.
+- Neo4j projection/runtime configuration accepts only `ARGO_NEO4J_DATABASE_URL`, `ARGO_NEO4J_DATABASE_USERNAME`, and `ARGO_NEO4J_DATABASE_PASSWORD`. Legacy `ARGO_NEO4J_URI`, `ARGO_NEO4J_USERNAME`, and `ARGO_NEO4J_PASSWORD` aliases are unsupported sources that fail closed before any driver, database, projection, or index write side effect.
+- The only secret keys are `QWEN_KEY` and `ARGO_NEO4J_DATABASE_PASSWORD`. Direct process values take precedence; matching process/file duplicates are accepted from process, differing duplicates fail closed, and missing/blank/duplicate/unknown-secret values are rejected.
+- Preflight requires exact canonical path, ignored/untracked evidence, regular non-reparse file state, and a Windows ACL result proving current-identity read access without `Everyone`, `BUILTIN\Users`, or `Authenticated Users` read access. Unverifiable ACL state blocks.
+- ACL evaluation parses individual `icacls` ACE lines, binds allow/deny and inherited flags to their principals, applies deny precedence, and requires an effective read grant for the actual execution identity. Broad-principal deny-only ACEs do not create access; broad allow ACEs are unsafe.
+- Frozen accepted source fixtures supply all five `ARGO_EMBEDDING_*` keys, `ARGO_NEO4J_DATABASE_URL`, `ARGO_NEO4J_DATABASE_USERNAME`, and both secret keys from process-only, file-only, or matching dual sources. Every rejected fixture starts from that complete profile and mutates only its named rejection dimension; no implicit default may satisfy normalization.
+- Loader provenance rejects root/alternate/tracked files, CLI, literal/default/fallback, alias, destructured, generated, or indirect secret sources.
+- The resolver validates every trace before consuming its value using its private composition capability: trace/alias-chain immutability, exact field set with no extras, field types, issued-object identity, requested-key equality, exact requested file path, source-kind/path/operation correlation, and a one-element alias chain equal to the requested key for approved direct reads. Trusted test composition can deliberately issue key/path mismatch, missing/extra-field, or wrong-type traces; each must fail exactly `SOURCE_TRACE_INVALID`. The same value with CLI/literal operation methods, fallback/indirect operation methods, or alias methods remains prohibited.
+- The approved live profile is provider `alibaba-cloud-model-studio-openai-compatible-cn-beijing`, endpoint `https://llm-clids9mqc5o1mbvb.cn-beijing.maas.aliyuncs.com/compatible-mode/v1`, model `qwen3.7-text-embedding`, qualification `qualification-2026-07-25`, dimensions `1024`.
+- Live network access requires explicit opt-in through the approved configuration source, normally the ignored/untracked `.argo/.env` containing `ARGO_LIVE_PROVIDER_E2E=1` and, for W3.1, `ARGO_W31_LIVE_MUTATION_VECTOR_E2E=1`; controlled process injection is allowed only through the same provenance-checked resolver. Default/offline CI remains deterministic but never substitutes fake evidence for a live pass.
+- Redaction verification includes a synthetic-success recording boundary that captures full Cypher text/parameter and graph-evidence values, detects canaries in neutral fields, and clears all in-memory persistence before inspecting generated artifacts.
+- The controlled Neo4j test boundary uses `ARGO_NEO4J_DATABASE_URL`, `ARGO_NEO4J_DATABASE_USERNAME`, and `ARGO_NEO4J_DATABASE_PASSWORD`; the password flows only to `neo4j.auth.basic`, never to Cypher or evidence.
+- A recording Neo4j adapter verifies the password is passed once to `neo4j.auth.basic`, authentication failure reaches no query, and recorded Cypher text/parameters contain no password canary.
+- Authentication redaction captures the raw exception—including message, stack, nested causes, and aggregate errors—before safe classification, then scans it together with the sanitized error, every injected logger event, stdout/stderr, auth/driver/query recordings, graph and persistence observations, and recursive artifacts. The probe leaves zero records and never persists its canary.
+- `.argo/.env.example` is the only committed example and contains empty placeholders/instructions; `.argo/.env` remains ignored and untracked.
+- Threshold-all seed selection depends on aligned semantic-index records and channel thresholds; ANN calls, if present, are benchmark-only and cannot remove above-threshold peers or force unrelated hits.
+- Closure begins after W4 seed retrieval. Purpose-policy graph closure, endpoint closure, View completeness expansion, traversal expansion, neighborhood closure, and downstream graph-completion behavior are not authorized by a DT-04/DT-05 seed-retrieval handoff.
+- W5 purpose closure depends on W4 seeds and canonical ArchiMate graph semantics. `intent-decision`, `implementation-design`, `coding-repair`, and `audit` may consume the same seed anchors, but each category must select a different policy id, parameter contract, included range, exclusions, and rationale. `graph-tidy` remains a full-snapshot bypass and must not inherit semantic closure filtering.
+- W6 endpoint, View, provenance, and coherent-version evidence depend on W5 selected ranges and canonical version evidence. Endpoint closure and View closure may complete returned objects, but they must not reselect the W5 purpose range, add unrelated neighboring relationships, or pull overlapping Views by shared membership alone.
+- BP-MCP-SEM closure depends inward on selected object identity and canonical graph authority. It must not depend on response-shape request controls, debug/evidence modes, tests, Harness fixtures, or field-level DTO shaping.
+- W7 quality evidence depends on W4 seed recall, W5 purpose closure, W6 provenance/coherent-result evidence, and runner-owned wave acceptance evidence. It must not re-score by ANN top-k, force unrelated hits to satisfy recall, treat precision as a release substitute, or mark whole delivery by manually editing `deliveryStatus`.
+- DT-19 capacity evidence depends on real DT-18 quality evidence and records only explicit observedResultIds/result ids plus measured precision by purpose. It must reject closure fallback, validate cardinality mismatch when resultCardinality is supplied, block missing quality or result evidence clearly, and must not add budgets, caps, top-k, pagination, truncation, continuation, or capacity-policy behavior.
+- Index lifecycle depends on canonical mutation evidence, qualified embedding generation, and vector persistence. It must not mark Aligned until every affected record has complete identity, channel, canonical/content/index version, provider, model, model version, and dimensions evidence. Outcome-level TS-09 evidence must identify the Node adapter path and cannot be inferred from DT-05/DT-16/DT-17 scoped passes alone.
+- Alignment gating depends inward on lifecycle state and canonical version evidence before invoking semantic retrieval. Complete canonical reads remain available without semantic fallback.
+- W3.1 depends on the MCP mutation boundary and the existing live provider/Neo4j boundaries through explicit interfaces. The mutation-vector lifecycle may consume mutation observations and approved live configuration, but it must not import MCP server internals from query/runtime code or mutate canonical JSON outside `applySystemArchitectureMutation`; the automatic mutation write path is the only accepted production trigger for live W3.1 delivery evidence.
+- Durable incremental indexing depends inward on the production semantic projection store rather than the live-E2E evidence boundary. Batch and focused MCP mutation adapters may call it only after canonical write success and readiness invalidation. Preview/dry-run, failed validation, and failed canonical writes do not call it. Existing live-E2E runId cleanup remains test-only and cannot select production labels or identities.
+- WP-P1 runtime composition depends inward on `semantic-persistence/`; that directory may consume canonical-read, structural-projection completion, qualified-provider, durable checkpoint, and durable projection ports. It must not depend outward on MCP internals or on `liveEmbeddingNeo4jBoundary.js`.
+- WP-P2 default retrieval depends inward on external configuration, embedding qualification/provider transport, persistent semantic records/readiness, Neo4j Vector Index access, threshold-all seed selection, deterministic closure, and canonical authority. `systemarchitecture-mcp-server.js` may compose this boundary but the module must not depend outward on MCP internals or tests.
+- WP-P2 raw test composition is callback-scoped and module-owned. Its exact input surface is `sourceBehavior`, `sourceAdapters`, `transport`, and `neo4jDriver`; it must not accept environment/configuration objects, semantic result objects, seed lists, readiness verdicts, test credentials, or a retrieval boundary as trusted production input.
+- WP-P3 operator composition depends only on public inward ports for workspace initialization, structural synchronization, approved configuration resolution, semantic backfill, persistent readiness, semantic query, and canonical snapshot reads. The CLI and MCP adapters depend inward on `semanticOperatorJourney.js`; the journey module never depends outward on MCP transport, CLI parsing, README content, tests, or Harness fixtures.
+- The canonical lifecycle supersedes the historical WP-P3 Coding authorization. Its authoritative minimal target set is exactly `.argo/scripts/argo-mcp-server.js`, `.argo/scripts/systemarchitecture-mcp-server.js`, `.argo/scripts/graph-rag/semanticOperatorJourney.js`, `.argo/scripts/graph-rag/mutationEmbeddingVectorLifecycle.js`, and `.argo/scripts/graph-rag/defaultSemanticRetrieval.js`. The fifth target is limited to unified readiness-boundary consumption and safe failure propagation while preserving all accepted WP-P2 algorithms. Accepted `productionSemanticBackfill.js`, `productionSemanticCheckpointStore.js`, `productionSemanticNeo4jAdapter.js`, `productionSemanticProjectionStore.js`, `liveEmbeddingProviderConfig.js`, and `productionGraphRagRuntime.js` remain frozen inward dependencies.
+- Default production composition is protected separately from deterministic sequencing fixtures. `default-composition-wiring.guard.js` requires exact imported/top-level bindings, exactly six function ports, and the sole attestation-store dependency. `operator-policy-provenance.guard.js` retains consent/verdict provenance. `readiness-public-boundary.guard.js` retains exact shared-reader provenance. `adapter-lifecycle-boundary.guard.js` uses AST/TypeChecker binding, active-call-graph reachability, exact diagnostic source mapping, and ordered executable-call analysis to protect operator MCP routing, explicit package consent, exclusive/flushed atomic replacement, owner/ACL metadata binding, actual init/backfill/mutation invalidation, strict record schema, and the exact structured error whitelist. Its adversarial fixtures include dead atomic helpers with active append/write, missing file or directory fsync, silent Windows fallback omission, wrong serializer constants/fields, bracket retrieval/stack access, comments/dead clears, and secret-bearing fields.
+
+## Owned tests
+
+Explicit entrypoints are owned by `tests/ARCHITECTURE.md`. This module is protected by the frozen guards in `tests/architecture/production-graph-rag/`, including the coding-scope authorization guard that excludes TS-08 while permitting corrected W3 handoffs to authorize TS-09 adapter/generation work and W3.1 handoffs to authorize mutation-vector lifecycle work.
+
+The BP MCP semantic query contract uses the focused guards under `tests/architecture/mcp-semantic-query-contract/` for request validation, canonical subset payloads, relationship endpoint closure, View membership closure, and exact graph-to-entrypoint traceability.
+
+WP-P1 adds a subordinate local contract at `.argo/scripts/graph-rag/semantic-persistence/ARCHITECTURE.md`; its two explicit entrypoints and four critical guards are owned by `tests/ARCHITECTURE.md`.
+
+WP-P3 adds one explicit entrypoint and nine critical guards under `tests/architecture/production-semantic-operator/`; they are owned by `tests/ARCHITECTURE.md`.
+
+## Completion attribution
+
+- This slice is complete when its six approved explicit entrypoints and seven frozen critical guards pass with no baseline delivered regression.
+- Passing TS-07 is sufficient evidence that this slice realizes the external credential boundary.
+- This harness-env and canonical Neo4j-name extension is complete only when `runProductionGraphRagRuntime.js`, `runExternalCredentialBoundary.js`, and `runLiveEmbeddingProviderSecretIsolation.js` pass with the production Graph RAG critical guards: TS-01 proves approved `.argo/.env` loading before projection without secret diagnostics, TS-07 proves canonical `ARGO_NEO4J_DATABASE_*` projection configuration and legacy-alias rejection, and TS-07 Provider Secret Isolation proves the same legacy-alias rejection through the live source matrix.
+- Global `grag-credential-boundary.deliveryStatus` remains runner-owned and may remain `not_delivered`; scoped attribution uses committed mounted TS-07 evidence, runner failure records, and the handoff scope rather than uncommitted intent relationships.
+- A deferred global status does not authorize TS-09 work, relationship changes, frozen-test edits, or manual delivery-status changes.
+- C1-C6 remain a protected checkpoint. The expanded live-provider slice completes only when all eight scoped explicit entrypoints and ten frozen critical guards pass, the live result proves a real HTTP call and controlled Neo4j evidence, and failure/redaction matrices pass with zero baseline delivered regression.
+- W3 index lifecycle and exact-threshold baseline completion requires DT-05, DT-16, DT-16-SemanticIndex, DT-17, TS-09-EmbeddingProviderAdapter, and TS-09-EmbeddingGeneration to pass together with the W3 critical guards. DT scoped passes are necessary evidence but not sufficient for W3 acceptance while TS-09 fails.
+- W3.1 completion requires `runApplyMutationEmbeddingVectorE2E.js` to pass under both `ARGO_LIVE_PROVIDER_E2E=1` and `ARGO_W31_LIVE_MUTATION_VECTOR_E2E=1` with exactly one `applySystemArchitectureMutation` call, automatic `embeddingLifecycle`/`alignment` response evidence, approved Qwen/Neo4j secret sources, and controlled Neo4j vector cleanup evidence. Default/offline failure with `W31_MUTATION_VECTOR_E2E_OPT_IN_REQUIRED` is expected pre-coding evidence, not live acceptance.
+- W4 seed retrieval completion requires `runIndependentSemanticSeeds.js` to pass for both `ExplicitAcceptanceTestcase-DT-04` and `ExplicitAcceptanceTestcase-DT-05`: observable Element/Relationship/View seed channels, independent channel thresholds, every qualifying candidate returned, zero forced unrelated hits, no fixed result limit, ANN performance-only evidence, and no closure-shaped output.
+- W5 purpose closure completion requires `runPurposePolicyClosure.js`, `runIntentDecisionClosure.js`, `runImplementationDesignClosure.js`, `runCodingRepairClosure.js`, `runAuditProofClosure.js`, and `runGraphTidyFullSnapshot.js` to pass together with the W5 critical guards. This proves DT-06 through DT-12: parameterized mandatory closure, caller-identity-independent dispatch, independent intent/implementation/repair/audit boundaries, and graph-tidy complete-snapshot bypass.
+- W6 coherent result completion requires `runCoherentIntentReading.js`, `runRelationshipEndpointClosure.js`, `runCompleteViewClosure.js`, and `runFirstInclusionProvenance.js` to pass together with the W6 critical guards. This proves DT-00-W6, DT-13, DT-14, and DT-15 without changing W4 seed discovery, W5 purpose-policy selection, graph-tidy full-snapshot bypass, W7 quality scoring, or capacity governance.
+- W7 Phase 1 business acceptance requires `runRetrievalQualityBenchmark.js` and `runSevenWaveDeliveryGates.js` to pass together with the W7 critical guards. This proves DT-18 and TS-08 with prerequisite W2-W6 evidence, approved five-purpose benchmark evidence, 100% key seed recall, 100% closure correctness, zero forced unrelated hits, recorded precision, and no DT-19 capacity decision.
+- DT-19 capacity evidence completion requires `runCapacityEvidence.js` to pass together with the production Graph RAG critical guards. This proves capacity evidence for `grag-capacity-residual`: real DT-18 output preserves explicit observedResultIds/result ids and measured precision for every declared purpose, closure fallback is rejected, missing quality/result evidence and cardinality mismatch block clearly, and no capacity policy decision or silent control is introduced.
+- WP-P1 completion requires `runProductionSemanticBackfill.js` and `runPersistentSemanticProjectionLifecycle.js` plus the four production-semantic-persistence guards to pass. Earlier W3/W3.1 provider/index/lifecycle evidence remains prerequisite context, while WP-P2 and WP-P3 remain excluded.
+- WP-P2 completion requires `runDefaultMcpNeo4jVectorRetrieval.js` and `runProductionSemanticReadinessGate.js` plus the four `production-default-retrieval` guards to pass. No-argument and graph-tidy compatibility controls must stay green, WP-P1 entrypoints must not regress, and the full runner remains the sole owner of `deliveryStatus`.
+- WP-P3 implementation completion requires `runNewProjectSemanticOperatorJourney.js` plus the nine `production-semantic-operator` critical guards to pass, including real child-process CLI and System/unified MCP adapter lifecycle controls, together with unchanged passing SP-01 through SP-04 and all inherited boundaries. This deterministic acceptance does not claim live Neo4j evidence or the `semprod-ready-plateau`.

package/argo/scripts/graph-rag/canonicalProjectionAuthority.js

@@ -0,0 +1,45 @@
+function enforceCanonicalProjectionAuthority(input) {
+  const canonicalGraph = input && input.canonicalGraph;
+  const projection = input && input.projection;
+  if (!canonicalGraph || !projection) {
+    throw projectionConflict('Canonical graph and projection evidence are required');
+  }
+
+  const canonicalIds = collectCanonicalIds(canonicalGraph);
+  const projectionIds = new Set(
+    Array.isArray(projection.seeds)
+      ? projection.seeds.map(seed => seed && seed.id).filter(Boolean)
+      : [],
+  );
+  const versionAligned = projection.canonicalVersion === canonicalGraph.version;
+  const identitiesAligned = [...projectionIds].every(id => canonicalIds.has(id));
+
+  if (!versionAligned || !identitiesAligned) {
+    throw projectionConflict('Neo4j projection conflicts with canonical intent');
+  }
+
+  return {
+    status: 'passed',
+    canonicalAuthority: 'canonical',
+    document: canonicalGraph,
+    projection,
+  };
+}
+
+function collectCanonicalIds(graph) {
+  return new Set([
+    ...(graph.elements || []).map(entry => entry.id),
+    ...(graph.relationships || []).map(entry => entry.id),
+    ...(graph.views || []).map(entry => entry.view_id),
+  ].filter(Boolean));
+}
+
+function projectionConflict(message) {
+  const error = new Error(message);
+  error.category = 'CANONICAL_PROJECTION_CONFLICT';
+  return error;
+}
+
+module.exports = {
+  enforceCanonicalProjectionAuthority,
+};