Add phase-memory architecture workplan

docs/architecture.md

@@ -0,0 +1,157 @@
+# Phase Memory Architecture Sketch
+
+Date: 2026-05-18
+Status: initial sketch
+
+## Purpose
+
+`phase-memory` should be the memory operating layer between Markitect's
+contract compiler, Kontextual Engine's durable knowledge runtime, and
+Infospace Bench's evaluation fixtures.
+
+The adjacent repositories already cover important slices:
+
+- `markitect-tool` owns deterministic memory profile, graph, event, and
+  selection contracts, plus compilation of selected graph items into context
+  packages.
+- `kontextual-engine` owns durable knowledge and memory graph records,
+  permission-aware retrieval, audit events, retention, refresh, compaction,
+  review-gated updates, and Markitect-compatible export envelopes.
+- `infospace-bench` owns concrete corpus pilots, restart-package evaluation,
+  metrics, and fixture feedback.
+
+The missing layer is memory-native orchestration: interpreting profile intent
+as phase-aware runtime plans, deciding which lifecycle actions are allowed or
+required, planning activation packages, and coordinating adapter behavior
+without becoming a markdown contract library, knowledge database, or benchmark.
+
+## Architecture Layers
+
+```mermaid
+flowchart TB
+  MT["markitect-tool\ncontracts + package compiler"]
+  PM["phase-memory\nprofile execution + phase policy"]
+  KE["kontextual-engine\ndurable graph/runtime records"]
+  IB["infospace-bench\nfixtures + evaluation"]
+  EXT["optional adapters\ngraph, vector, policy, audit, registry"]
+
+  MT -->|"profile, graph, selection contracts"| PM
+  PM -->|"runtime plan, lifecycle actions"| KE
+  KE -->|"graph records, audit traces, context inputs"| PM
+  PM -->|"selection/package request"| MT
+  IB -->|"profile + graph fixtures, metrics"| PM
+  PM -->|"planned retrieval/evaluation envelopes"| IB
+  PM -->|"adapter calls"| EXT
+```
+
+### 1. Contract Ingress
+
+Accept Markitect-compatible memory profiles, graph snapshots, events, and
+selections as input contracts. `phase-memory` may call Markitect validators, but
+it should not fork the Markitect vocabulary or become the syntax owner.
+
+Primary input contracts:
+
+- `markitect.memory.profile.v1`
+- `markitect.memory.graph.v1`
+- `markitect.memory.selection.v1`
+
+### 2. Phase Domain Model
+
+Introduce a memory-native model that explains what a profile means at runtime:
+
+- phases: `ephemeral`, `fluid`, `stabilized`, `rigid`
+- memory kinds: `reasoning`, `conversation`, `knowledge`, `package`,
+  `identity`, `preference`, `source`, `task`, `tool`
+- lifecycle states: active, stale, review-needed, compacted, superseded,
+  delete-requested, archived
+- profile intent: limits, latency, retention, deletion, decay, refresh,
+  compaction, merge/conflict policy, activation, failure behavior, and policy
+  reauthorization
+- action plans: deterministic dry-run records that explain proposed writes,
+  reads, activations, compactions, and denials
+
+### 3. Planning Engines
+
+The first useful implementation should be deterministic and local-first.
+
+Core planners:
+
+- Profile execution planner: turns a profile into a runtime capability and
+  adapter plan.
+- Phase transition planner: decides which records can move from ephemeral or
+  fluid memory into stabilized or rigid memory.
+- Retention planner: proposes stale, delete-requested, archived, or refresh
+  actions without physical deletion by default.
+- Compaction planner: groups trace windows or graph neighborhoods into
+  reviewable summary-node proposals.
+- Activation planner: turns graph neighborhoods and event paths into
+  Markitect-compatible selections under token/item budgets.
+- Policy planner: surfaces required reauthorization, labels, trust zones, and
+  review gates before a runtime applies durable writes.
+
+### 4. Runtime Ports
+
+`phase-memory` should define ports before committing to infrastructure:
+
+- `MemoryGraphStore`: graph node, edge, event, and profile access
+- `MemoryEventLog`: append-only fluid/conversational path events
+- `ContextPackageCompiler`: Markitect-backed package compilation boundary
+- `SemanticIndex`: optional vector or hybrid retrieval
+- `PolicyGateway`: read/write/activation authorization
+- `AuditSink`: durable operation and policy-decision recording
+- `RuntimeRegistry`: remote or sibling runtime envelope exchange
+
+Local in-memory or file-backed adapters are enough for the first slice. External
+graph databases, vector stores, LLM extraction, enterprise policy systems, and
+remote registries should remain optional adapters.
+
+## Repository Boundaries
+
+`phase-memory` owns:
+
+- phase semantics and lifecycle policy
+- profile execution planning
+- retention, deletion, decay, refresh, compaction, and stabilization decisions
+- activation planning and adapter orchestration
+- memory-specific audit and observability envelopes
+- deterministic local runtime behavior for tests and small deployments
+
+`phase-memory` does not own:
+
+- Markitect syntax vocabulary or context package internals
+- generic content/knowledge artifact persistence
+- benchmark corpus ownership or evaluation dashboards
+- full identity or authorization platforms
+- generic vector database behavior
+- provider-specific LLM memory plugins
+
+## First Viable Slice
+
+The first implementation should establish a small package with:
+
+1. Python project scaffold and tests.
+2. Domain dataclasses for phases, profile intent, lifecycle actions, and
+   runtime plans.
+3. A Markitect contract adapter that accepts already-valid profile/graph
+   dictionaries and reports diagnostics without redefining schemas.
+4. A deterministic profile execution planner.
+5. A local in-memory store/event-log adapter for tests.
+6. A fixture set derived from Markitect examples and the Infospace Bench
+   agentic-memory pilot.
+7. Docs that keep the Markitect, Kontextual, Infospace, and Phase Memory
+   boundaries explicit.
+
+The slice should emit plans first, not mutate durable memory by surprise.
+Durable writes, external adapters, live LLM extraction, vector retrieval, and
+service deployment can follow once the plan model is stable.
+
+## Open Questions
+
+- Should `phase-memory` depend directly on `markitect-tool` for validation, or
+  shell out/consume JSON diagnostics to keep the boundary looser?
+- Should the first local store be pure in-memory, JSONL/file-backed, or SQLite?
+- Which actions belong in a stable public API first: activation planning,
+  retention planning, compaction planning, or profile capability inspection?
+- How should `kontextual-engine` delegate phase-specific decisions without
+  creating circular imports?