Anto01
f521aab97b
Codifies the helper-at-every-service-boundary rule that fb6298a
implemented across the eight current callsites. The contract is
intentionally simple but easy to forget, so it lives in its own
doc that the engineering layer V1 implementation sprint can read
before adding new project-keyed entity surfaces.
docs/architecture/project-identity-canonicalization.md
------------------------------------------------------
- The contract: every read/write that takes a project name MUST
call resolve_project_name() before the value crosses a service
boundary; canonicalization happens once, at the first statement
after input validation, never later
- The helper API: resolve_project_name(name) returns the canonical
project_id for registered names, the input unchanged for empty
or unregistered names (the second case is the backwards-compat
path for hand-curated state predating the registry)
- Full table of the 8 current callsites: builder.build_context,
project_state.set_state/get_state/invalidate_state,
interactions.record_interaction/list_interactions,
memory.create_memory/get_memories
- Where the helper is intentionally NOT called and why: legacy
ensure_project lookup, retriever's own _project_match_boost
(which already calls get_registered_project), _rank_chunks
secondary substring boost (multiplicative not filter, can't
drop relevant chunks), update_memory (no project field update),
unregistered names (the rule applied to a name with no record)
- Why this is the trust hierarchy in action: Layer 3 trusted
state has to be findable to win the trust battle; an
un-canonicalized lookup silently makes Layer 3 invisible and
the system falls through to lower-trust retrieved chunks with
no signal to the human
- The 4-step rule for new entry points: identify project-keyed
reads/writes, place the call as the first statement after
validation, add a regression test using the project_registry
fixture, verify None/empty paths
- How the project_registry fixture works with a copy-pasteable
example
- What the rule does NOT cover: alias creation (registry's own
write path), registry hot-reloading (no in-process cache by
design), cross-project dedup (collision detection at
registration), time-bounded canonicalization (canonical id is
stable forever), legacy data migration (open follow-up)
- Engineering layer V1 implications: every new service entry
point in the entities/relationships/conflicts/mirror modules
must apply the helper at the first statement after validation;
treated as code review failure if missing
- Open follow-ups: legacy data migration script (~30 LOC),
registry file caching when projects scale beyond ~50, case
sensitivity audit when entity-side storage lands, _rank_chunks
cleanup, documentation discoverability (intentional redundancy
between this doc, the helper docstring, and per-callsite comments)
- Quick reference card: copy-pasteable template for new service
functions
master-plan-status.md updated
-----------------------------
- New doc added to the engineering-layer planning sprint listing
- Marked as required reading before V1 implementation begins
- Note that V1 must apply the contract at every new service-layer
entry point
Pure doc work, no code changes. Full suite stays at 174 passing
because no source changed.
184 lines
6.6 KiB
Markdown
184 lines
6.6 KiB
Markdown
# AtoCore Master Plan Status
|
|
|
|
## Current Position
|
|
|
|
AtoCore is currently between **Phase 7** and **Phase 8**.
|
|
|
|
The platform is no longer just a proof of concept. The local engine exists, the
|
|
core correctness pass is complete, Dalidou hosts the canonical runtime and
|
|
machine database, and OpenClaw on the T420 can consume AtoCore safely in
|
|
read-only additive mode.
|
|
|
|
## Phase Status
|
|
|
|
### Completed
|
|
|
|
- Phase 0 - Foundation
|
|
- Phase 0.5 - Proof of Concept
|
|
- Phase 1 - Ingestion
|
|
|
|
### Baseline Complete
|
|
|
|
- Phase 2 - Memory Core
|
|
- Phase 3 - Retrieval
|
|
- Phase 5 - Project State
|
|
- Phase 7 - Context Builder
|
|
|
|
### Partial
|
|
|
|
- Phase 4 - Identity / Preferences
|
|
- Phase 8 - OpenClaw Integration
|
|
|
|
### Baseline Complete
|
|
|
|
- Phase 9 - Reflection (all three foundation commits landed:
|
|
A capture, B reinforcement, C candidate extraction + review queue)
|
|
|
|
### Not Yet Complete In The Intended Sense
|
|
|
|
- Phase 6 - AtoDrive
|
|
- Phase 10 - Write-back
|
|
- Phase 11 - Multi-model
|
|
- Phase 12 - Evaluation
|
|
- Phase 13 - Hardening
|
|
|
|
### Engineering Layer Planning Sprint
|
|
|
|
**Status: complete.** All 8 architecture docs are drafted. The
|
|
engineering layer is now ready for V1 implementation against the
|
|
active project set.
|
|
|
|
- [engineering-query-catalog.md](architecture/engineering-query-catalog.md) —
|
|
the 20 v1-required queries the engineering layer must answer
|
|
- [memory-vs-entities.md](architecture/memory-vs-entities.md) —
|
|
canonical home split between memory and entity tables
|
|
- [promotion-rules.md](architecture/promotion-rules.md) —
|
|
Layer 0 → Layer 2 pipeline, triggers, review queue mechanics
|
|
- [conflict-model.md](architecture/conflict-model.md) —
|
|
detection, representation, and resolution of contradictory facts
|
|
- [tool-handoff-boundaries.md](architecture/tool-handoff-boundaries.md) —
|
|
KB-CAD / KB-FEM one-way mirror stance, ingest endpoints, drift handling
|
|
- [representation-authority.md](architecture/representation-authority.md) —
|
|
canonical home matrix across PKM / KB / repos / AtoCore for 22 fact kinds
|
|
- [human-mirror-rules.md](architecture/human-mirror-rules.md) —
|
|
templates, regeneration triggers, edit flow, "do not edit" enforcement
|
|
- [engineering-v1-acceptance.md](architecture/engineering-v1-acceptance.md) —
|
|
measurable done definition with 23 acceptance criteria
|
|
- [engineering-knowledge-hybrid-architecture.md](architecture/engineering-knowledge-hybrid-architecture.md) —
|
|
the 5-layer model (from the previous planning wave)
|
|
- [engineering-ontology-v1.md](architecture/engineering-ontology-v1.md) —
|
|
the initial V1 object and relationship inventory (previous wave)
|
|
- [project-identity-canonicalization.md](architecture/project-identity-canonicalization.md) —
|
|
the helper-at-every-service-boundary contract that keeps the
|
|
trust hierarchy dependable across alias and canonical-id callers;
|
|
required reading before adding new project-keyed entity surfaces
|
|
in the V1 implementation sprint
|
|
|
|
The next concrete next step is the V1 implementation sprint, which
|
|
should follow engineering-v1-acceptance.md as its checklist, and
|
|
must apply the project-identity-canonicalization contract at every
|
|
new service-layer entry point.
|
|
|
|
### LLM Client Integration
|
|
|
|
A separate but related architectural concern: how AtoCore is reachable
|
|
from many different LLM client contexts (OpenClaw, Claude Code, future
|
|
Codex skills, future MCP server). The layering rule is documented in:
|
|
|
|
- [llm-client-integration.md](architecture/llm-client-integration.md) —
|
|
three-layer shape: HTTP API → shared operator client
|
|
(`scripts/atocore_client.py`) → per-agent thin frontends; the
|
|
shared client is the canonical backbone every new client should
|
|
shell out to instead of reimplementing HTTP calls
|
|
|
|
This sits implicitly between Phase 8 (OpenClaw) and Phase 11
|
|
(multi-model). Memory-review and engineering-entity commands are
|
|
deferred from the shared client until their workflows are exercised.
|
|
|
|
## What Is Real Today
|
|
|
|
- canonical AtoCore runtime on Dalidou
|
|
- canonical machine DB and vector store on Dalidou
|
|
- project registry with:
|
|
- template
|
|
- proposal preview
|
|
- register
|
|
- update
|
|
- refresh
|
|
- read-only additive OpenClaw helper on the T420
|
|
- seeded project corpus for:
|
|
- `p04-gigabit`
|
|
- `p05-interferometer`
|
|
- `p06-polisher`
|
|
- conservative Trusted Project State for those active projects
|
|
- first operational backup foundation for SQLite + project registry
|
|
- implementation-facing architecture notes for future engineering knowledge work
|
|
- first organic routing layer in OpenClaw via:
|
|
- `detect-project`
|
|
- `auto-context`
|
|
|
|
## Now
|
|
|
|
These are the current practical priorities.
|
|
|
|
1. Finish practical OpenClaw integration
|
|
- make the helper lifecycle feel natural in daily use
|
|
- use the new organic routing layer for project-knowledge questions
|
|
- confirm fail-open behavior remains acceptable
|
|
- keep AtoCore clearly additive
|
|
2. Tighten retrieval quality
|
|
- reduce cross-project competition
|
|
- improve ranking on short or ambiguous prompts
|
|
- add only a few anchor docs where retrieval is still weak
|
|
3. Continue controlled ingestion
|
|
- deepen active projects selectively
|
|
- avoid noisy bulk corpus growth
|
|
4. Strengthen operational boringness
|
|
- backup and restore procedure
|
|
- Chroma rebuild / backup policy
|
|
- retention and restore validation
|
|
|
|
## Next
|
|
|
|
These are the next major layers after the current practical pass.
|
|
|
|
1. Clarify AtoDrive as a real operational truth layer
|
|
2. Mature identity / preferences handling
|
|
3. Improve observability for:
|
|
- retrieval quality
|
|
- context-pack inspection
|
|
- comparison of behavior with and without AtoCore
|
|
|
|
## Later
|
|
|
|
These are the deliberate future expansions already supported by the architecture
|
|
direction, but not yet ready for immediate implementation.
|
|
|
|
1. Minimal engineering knowledge layer
|
|
- driven by `docs/architecture/engineering-knowledge-hybrid-architecture.md`
|
|
- guided by `docs/architecture/engineering-ontology-v1.md`
|
|
2. Minimal typed objects and relationships
|
|
3. Evidence-linking and provenance-rich structured records
|
|
4. Human mirror generation from structured state
|
|
|
|
## Not Yet
|
|
|
|
These remain intentionally deferred.
|
|
|
|
- automatic write-back from OpenClaw into AtoCore
|
|
- automatic memory promotion
|
|
- reflection loop integration
|
|
- replacing OpenClaw's own memory system
|
|
- live machine-DB sync between machines
|
|
- full ontology / graph expansion before the current baseline is stable
|
|
|
|
## Working Rule
|
|
|
|
The next sensible implementation threshold for the engineering ontology work is:
|
|
|
|
- after the current ingestion, retrieval, registry, OpenClaw helper, organic
|
|
routing, and backup baseline feels boring and dependable
|
|
|
|
Until then, the architecture docs should shape decisions, not force premature
|
|
schema work.
|