generated from coulomb/repo-seed
151 lines
4.4 KiB
Markdown
151 lines
4.4 KiB
Markdown
# 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
|
|
|
|
Current module:
|
|
|
|
```text
|
|
src/infospace_bench/engine.py
|
|
```
|
|
|
|
Responsibilities:
|
|
|
|
- provide local file-backed artifact reads/writes
|
|
- expose an `AssetRepository` protocol
|
|
- provide `LocalAssetRepository` as the default adapter
|
|
- 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.
|