infospace-bench/docs/successor-boundary-interface-map.md

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

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:

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:

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:

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.