docs and stuff

docs/successor-boundary-interface-map.md

@@ -0,0 +1,148 @@
+# Successor Boundary And Interface Map
+
+Date: 2026-05-14
+
+## Purpose
+
+This document defines the operational boundary between `infospace-bench`,
+`markitect-tool`, and `kontextual-engine` for the infospace successor effort.
+
+## Direction Of Dependency
+
+```text
+infospace-bench
+  uses markitect-tool for Markdown syntax capabilities
+  optionally uses kontextual-engine for durable operational state
+
+markitect-tool
+  does not depend on infospace-bench
+  does not depend on kontextual-engine for core syntax behavior
+
+kontextual-engine
+  may call syntax adapters such as markitect-tool for Markdown ingestion
+  does not depend on infospace-bench for engine identity
+```
+
+## What `infospace-bench` Expects From `markitect-tool`
+
+`infospace-bench` should consume a narrow adapter over `markitect-tool`.
+
+Required capabilities:
+
+- Parse Markdown files into structured document objects.
+- Expose headings, sections, frontmatter, source locations, and blocks.
+- Validate Markdown files against schemas/contracts.
+- Return structured diagnostics with source locations.
+- Resolve references and deterministic transformations where workflows need
+  Markdown-native composition.
+- Provide stable CLI/library behavior that can be used in tests and agents.
+
+`infospace-bench` should not:
+
+- Reimplement Markdown tokenization or section-tree parsing.
+- Re-export the entire `markitect-tool` API.
+- Add infospace-specific concepts to `markitect-tool`.
+
+## What `infospace-bench` Expects From `kontextual-engine`
+
+`kontextual-engine` is optional at first. File-backed behavior remains the
+default until engine integration is explicitly implemented.
+
+Expected future capabilities:
+
+- Durable asset identity for source and generated artifacts.
+- Metadata and provenance storage.
+- Relationship storage and retrieval.
+- Search, filtering, and query access over knowledge assets.
+- Workflow run records and operational audit trails.
+- Permission and review gates for agent-safe operations.
+- Transform records that link inputs, configuration, actor, and outputs.
+
+`infospace-bench` should not:
+
+- Become a persistence engine.
+- Build its own general retrieval platform.
+- Own generic permissions, audit, or workflow orchestration primitives.
+
+## What Remains File-Backed In `infospace-bench`
+
+File-backed behavior is part of the application contract and should remain
+first-class:
+
+- `infospaces/<slug>/infospace.yaml`
+- `artifacts/index.yaml`
+- source and generated artifact fixtures
+- evaluation files
+- metrics and history files
+- inspection reports
+- exports
+- reference pilot corpora
+
+The file-backed implementation is the testable baseline. Engine-backed
+operation should behave like a durable backend for the same application model,
+not a replacement for inspectable project artifacts.
+
+## Adapter Boundaries
+
+### Markdown Adapter
+
+Planned module:
+
+```text
+src/infospace_bench/markdown_adapter.py
+```
+
+Responsibilities:
+
+- call `markitect_tool.parse_markdown_file`
+- extract named sections by heading
+- call `markitect_tool` validation APIs
+- normalize diagnostics into `infospace-bench` result/error objects
+
+### Repository Adapter
+
+Planned module:
+
+```text
+src/infospace_bench/repository.py
+```
+
+Responsibilities:
+
+- provide local file-backed artifact reads/writes
+- later provide `kontextual-engine` backed asset lookup/sync
+- expose dry-run sync plans before mutation
+- keep provenance and digest handling explicit
+
+### Workflow Adapter
+
+Planned module:
+
+```text
+src/infospace_bench/workflow.py
+```
+
+Responsibilities:
+
+- load workflow definitions from `infospace.yaml`
+- run deterministic file-backed stages
+- delegate Markdown operations to `markitect-tool`
+- define assisted-stage contracts without binding to a provider
+- later submit or mirror workflow runs to `kontextual-engine`
+
+## Cross-Repo Non-Goals
+
+- `markitect-tool` should not learn about concrete infospaces.
+- `kontextual-engine` should not become a Markdown-specific runtime.
+- `infospace-bench` should not become a general platform or engine.
+- No repo should reproduce the old `markitect-project` monolith by accretion.
+
+## First Integration Slice
+
+The first implementation slice after this architecture workplan is
+`IB-WP-0006`:
+
+1. Add `markitect-tool` as a local dependency.
+2. Add a narrow Markdown adapter.
+3. Validate real infospace artifacts through `markitect-tool`.
+4. Keep all tests deterministic and file-backed.