Documentation Maintenance

This wiki is the current project manual and architecture contract. It describes the supported target behavior for v2, not a changelog.

Status Classes

Every deep technical page uses one status:

Do not mix architecture, runtime findings, and history in one paragraph. Runtime findings, dated score reports, and work-in-progress deltas belong in project memory or evaluation reports unless they are part of a supported operator procedure.

Authority Depends On The Question

Architecture question

%%{init: {"flowchart": {"curve": "linear"}}}%%
flowchart TD
  Decision["Explicit approved design decision"] --> Memory["Recorded project decision<br/>or accepted design record"]
  Memory --> Canonical["Canonical target manual page"]
  Canonical --> Tests["Target contract and invariant tests"]
  Tests --> Code["Refactor implementation"]
  Code --> Old["Older wiki prose or legacy code"]

Current code is conformance evidence; it does not silently supersede the architecture. A design change needs an explicit decision, a concrete risk analysis, and an update to the canonical page before dependent implementation is treated as the new contract.

Current-runtime question

%%{init: {"flowchart": {"curve": "linear"}}}%%
flowchart TD
  Runtime["Reproduced runtime behavior<br/>on exact image"] --> Tests["Passing tests for that revision"]
  Tests --> Code["Source and registry declarations"]
  Code --> Schema["Migrations and schema bootstrap"]
  Schema --> Workflow["CI/deployment workflow"]
  Workflow --> Docs["Current-runtime prose"]

When runtime and source disagree, reproduce with the exact image, configuration, database version, and feature flags before deciding what shipped.

Resolving a conflict

Canonical Page Ownership

Home is the navigation map. This table is the ownership map. Do not reproduce either map on another page.

Single-Source Rules

A referencing page may state the local consequence of a rule, then link to its owner. It must not copy the owner's:

• request/response schema
• lifecycle table or decision matrix
• limits/defaults/configuration table
• complete process diagram
• detailed storage shape
• troubleshooting decision tree
• migration procedure

When content gains its own responsibility, move it to a new canonical page and replace old copies with narrow links. Git history preserves removed prose.

Examples:

Design Change Process

%%{init: {"flowchart": {"curve": "linear"}}}%%
flowchart LR
  Problem["Concrete problem or ambiguity"] --> Verify["Inspect memory, manual,<br/>source, tests, and data"]
  Verify --> Options["Compare valid designs"]
  Options --> Risk["Falsify proposal and<br/>document failure modes"]
  Risk --> Decision["Obtain explicit design decision"]
  Decision --> Record["Record durable project decision"]
  Record --> Canonical["Update canonical page"]
  Canonical --> Dependents["Update dependent summaries"]
  Dependents --> Tests["Define conformance tests"]
  Tests --> Implement["Begin refactor slice"]

Do not change a high-blast-radius design because it is convenient for the current code. Identify the mismatch and obtain the decision.

Implementation Documentation Process

%%{init: {"flowchart": {"curve": "linear"}}}%%
flowchart LR
  Slice["Refactor slice"] --> Trace["Trace transport, service,<br/>domain, store, and tests"]
  Trace --> Compare["Compare with target invariants"]
  Compare --> Code["Implement and verify"]
  Code --> Conformance["Update conformance status"]
  Conformance --> Ops["Update affected operational pages"]
  Ops --> Validate["Links, Mermaid, terminology,<br/>schemas, and diff"]

Fix the source context

Record without modifying either worktree:

git -C ../dense-mem status --short --branch
git -C ../dense-mem rev-parse HEAD
git -C ../dense-mem log -1 --format='%cI %s'

A dirty working tree is not a stable revision. State whether evidence comes from HEAD, a named branch, a working tree, or a deployed image.

Trace the path

%%{init: {"flowchart": {"curve": "linear"}}}%%
flowchart LR
  Contract["Versioned interface contract"] --> Transport["MCP and first-party portal mapping"]
  Transport --> Application["Application service"]
  Application --> Domain["Domain policy"]
  Application --> Port["Repository/provider interface"]
  Port --> Adapter["PostgreSQL, Redis,<br/>or AI adapter"]
  Adapter --> Tests["Contract, integration,<br/>and failure tests"]

For configuration, trace parsing, startup validation, effective lookup, deployment examples, and operator output. For database behavior, trace migrations, constraints, transaction boundaries, repository queries, and recovery tests.

Try to falsify the claim

Ask:

• Can the authenticated role and scope perform this operation?
• Does an async response mean staged, semantically committed, vector-current, or processing-completed?
• Can an empty candidate set be confused with a retrieval error?
• Can two workers create duplicate Entities or Relationships?
• Can graph context accidentally count as evidence?
• What remains readable when embedding work fails?
• Does Redis contain the only copy of anything important?
• Can a same-name Entity cross a team boundary?
• Can same-team visibility mutate another profile's knowledge?
• Can a Hypothesis enter primary recall?
• Can the migration marker commit while corpus or vector work is still mutable?
• Can 2.2.0+ distinguish a valid fresh database from a skipped v1 migration?
• Can a v1 client silently misread a v2 response?

If the failure changes the contract, add a specific Risk and mitigation before implementation.

Removing Stale Material

Remove material that no longer describes a supported or required path. Keep old terminology only when:

• a compatibility adapter currently accepts it
• an operator must migrate stored data containing it
• an explicit tombstone behavior matters

Mark the removal condition. Do not keep old architecture prose for history.

The retired term Assertion may appear in the single retirement note or a migration mapping. It must not name an active target record, metric, API field, graph label, or service.

Page Template

Deep target pages should use the parts that fit:

# Feature
​
## Outcome and responsibility
​
## End-to-end flow
​
## Decision or state model
​
## Failure semantics
​
## Security and tenant boundary
​
## Risks and mitigations
​
## Acceptance invariants

Current-runtime or operational pages additionally name the exact supported release/commit and link to runtime discovery where appropriate.

Mermaid Conventions

Every flowchart begins with:

%%{init: {"flowchart": {"curve": "linear"}}}%%

Every sequence begins with:

%%{init: {"sequence": {"rightAngles": true}}}%%

Use flowcharts instead of diagram types that cannot guarantee the required straight-line rendering.

Guidelines:

• keep labels short
• quote labels containing punctuation
• show failure/retry branches
• distinguish durable stores from calls
• avoid color as the only meaning
• split unreadably large diagrams
• parse every Mermaid block
• reject a diagram missing its type-specific directive

Validation

Workspace and diff

git status --short
git diff --check

Do not stage, commit, or discard unrelated user changes.

Links

Resolve each wiki target after stripping an optional anchor. For anchored links, verify the target heading's GitHub-style slug.

Mermaid

Extract and parse every mermaid fence with the repository's pinned Mermaid CLI/parser. Syntax success is not enough; spot-check large diagrams for readable layout.

Terminology

rg -n -i 'assertion|assertion_id|legacy fact|legacy claim|43f3e38' --glob '*.md'

Inspect every match. Target pages should contain only deliberate retirement or migration references.

Also scan for target terms used inconsistently:

rg -n 'RelationshipObservation|VerificationEvent|RelationshipRecord|SemanticEdge|Hypothesis|entity_id|relationship_id' --glob '*.md'

Contract reconciliation

Freshness Metadata

Architecture pages describe the current approved v2 contract and should not carry dated runtime-conformance notes. Current-runtime pages say:

This page documents runtime behavior at <commit or image digest> on <date>.

Do not write “latest” without a resolved tag, digest, commit, or explicit target decision.

Reviewing A Reported Mismatch

%%{init: {"sequence": {"rightAngles": true}}}%%
sequenceDiagram
  actor User
  participant Manual as Canonical manual
  participant Source as Source and tests
  participant Runtime as Exact runtime

  User->>Manual: Ask whether behavior is correct
  Manual->>Manual: Identify target or current question
  Manual->>Source: Trace contract through implementation
  alt Current runtime remains uncertain
    Source->>Runtime: Reproduce on exact revision/config
    Runtime-->>Manual: Observed result
  end
  Manual-->>User: Target, implemented, deployed,<br/>and remaining gap

Answer with actual file/line paths for current-code claims. Keep four categories separate:

• approved target behavior
• implemented source behavior
• deployed runtime behavior
• historical compatibility behavior

Review Checklist

• page status and source context are explicit
• the relevant canonical owner was identified
• current behavior and target behavior are not conflated
• conflicting project decisions were resolved and recorded
• tenant, role, scope, and feature gates are explicit
• processing state and vector-search freshness are distinct
• Entity reuse/create/ambiguity occurs before Relationship identity
• graph context is not evidence
• Redis is not described as durable memory
• failure, retry, job recovery, migration, and rollback boundaries are explicit
• Risk contains specific failure modes and mitigations
• stale material was removed instead of accumulated
• schemas/defaults live on one owner page
• links, headings, Mermaid, terminology, and git diff --check pass
• unrelated user changes remain untouched