Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 44 additions & 0 deletions docs/DOMAIN_MODEL.md
Original file line number Diff line number Diff line change
Expand Up @@ -133,6 +133,50 @@ projections. They exist to retrieve and traverse knowledge efficiently.
- Search results point back to entities and notes; they do not become independent documents.
- Deleting or rebuilding an index must not mutate canonical content.

### Accepted Change Journal

`RuntimeAcceptedProjectNoteChange` is the canonical temporal record of one accepted note mutation
inside a project partition, and `Project.partition_position` is the strictly ordered per-project
watermark those records advance.

- An accepted change is replay-complete evidence: operation, paths, accepted content version and
checksum, actor, source, and acceptance time. It is recorded with the accepted mutation, not
reconstructed later from derived state.
- Consumers that need ordering, coalescing, or idempotency — projectors, routines, temporal
reads — consume the journal watermark. Human-facing feeds are presentations of the journal,
not the substrate.
- Materialization settling records when durable storage caught up with an accepted position. A
consumer that must not run ahead of durable files (the Wiki Projector, portable logs) holds
behind unsettled positions instead of guessing.
- The journal is note-scoped and project-partitioned today. A fuller event envelope (causation,
correlation, depth, workspace scope) grows this record; it does not introduce a second journal
beside it.

### Event Surfaces And Derivation

Every event-shaped surface is the journal, a projection of it, ingress toward it, or a separate
family that must not be mistaken for it:

```text
storage notifications / webhooks ingress evidence
-> reconciliation commands
-> accepted change journal canonical time
-> wiki projections index.md, log.md, navigation
Comment on lines +161 to +164

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Scope the journal diagram to DB-first mutations

For direct file edits handled by the observed-object index_file path or by run_external_file_delete, reconciliation never calls advance_partition_position() or record_accepted_note_change(); repository-wide, those calls exist only in accepted_note_mutation_runner.record_accepted_project_note_change(). Therefore the documented storage notifications / webhooks -> reconciliation commands -> accepted change journal flow is not currently true: local file-first mutations leave the journal watermark unchanged and are invisible to journal consumers. Either journal those reconciliation paths or explicitly scope this diagram and the canonical-record claim to DB-first accepted-note mutations.

AGENTS.md reference: AGENTS.md:L156-L160

Useful? React with 👍 / 👎.

-> search / graph / vector retrieval projections
-> activity feeds, live updates human presentation and transient delivery
-> temporal reads (bm log) CLI/API views over the journal
```

- A projection may lag the journal and must be rebuildable from it plus canonical Markdown.
- Delivery events (webhook attempts, storage notifications, SSE publishes) prove delivery, not
acceptance; they are never the canonical semantic log.
- Run ledgers (projection runs, index runs) record operational work, and product telemetry
(usage, subscription, journey events) records behavior. Neither is a knowledge event, and
neither derives from the journal.

POSIX-shaped reads describe memory space; the accepted change journal describes time; the
knowledge graph describes meaning; runtimes describe behavior.

## Source Of Truth And Authority

"Markdown is the source of truth" describes the product representation. Operational authority
Expand Down
12 changes: 5 additions & 7 deletions src/basic_memory/indexing/wiki_projector.py
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,8 @@
from pathlib import PurePosixPath, PureWindowsPath
import unicodedata

from basic_memory.runtime.project_partition import RuntimeProjectNoteOperation

OKF_VERSION = "0.2"
WIKI_PROFILE = "wiki/1"
WIKI_PROJECTOR_VERSION = "wiki/1.0.0"
Expand All @@ -32,13 +34,9 @@ class WikiProjectionReason(StrEnum):
manual_rebuild = "manual_rebuild"


class WikiChangeOperation(StrEnum):
"""Accepted note operation represented in generated Wiki logs."""

created = "created"
updated = "updated"
moved = "moved"
deleted = "deleted"
# Wiki logs present the accepted-change journal, so they reuse its operation vocabulary
# instead of maintaining a twin enum that can drift from the journal it renders.
WikiChangeOperation = RuntimeProjectNoteOperation


class WikiProjectionState(StrEnum):
Expand Down
Loading