# 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.