infospace-bench/docs/kontextual-engine-boundary.md

Kontextual Engine Boundary

infospace-bench can use kontextual-engine for durable knowledge operations, but it must not become an engine itself. The default remains file-backed and fully inspectable.

This boundary follows kontextual-engine/INTENT.md: the engine owns durable asset identity, persistence, provenance, relationships, retrieval, workflow runs, permissions, and audit. infospace-bench owns concrete infospaces, manifests, evaluation methodology, workflow declarations, and reference pilots.

Capability Contract

The current contract is exposed by:

from infospace_bench.engine import engine_capability_contract

File-backed application responsibilities:

• infospace.yaml
• artifacts/index.yaml
• Markdown artifacts
• evaluation history and metrics
• workflow run records
• dry-run sync plans

Engine-backed future responsibilities:

• durable asset identity and persistence
• provenance graph and relationship index
• retrieval
• workflow run persistence
• permissions and audit

Explicit non-goals for the engine boundary:

• Markdown syntax rules
• infospace-specific methodology
• repo identity
• provider-specific LLM calls

Local Adapter

LocalAssetRepository is the default adapter. It writes asset records to:

output/engine/assets.yaml

This file is a local evidence store, not a replacement for the infospace manifest. The manifest remains authoritative for this repository.

Each asset record includes:

• asset_id
• artifact_id
• infospace_slug
• kind
• path
• digest
• version
• artifact provenance and relationships

Sync Safety

Sync is dry-run by default:

python3 -m infospace_bench engine plan-sync infospaces/bootstrap-pilot
python3 -m infospace_bench engine sync infospaces/bootstrap-pilot

Mutation requires explicit apply:

python3 -m infospace_bench engine sync infospaces/bootstrap-pilot --apply

Apply writes the local adapter store and a sync run record under:

output/engine/sync-runs/<run-id>.yaml

Future kontextual-engine client configuration, permission changes, and apply operations should be review-gated.

First Safe Integration Scenario

The first safe scenario is one-way mirroring from file-backed infospace artifacts into an engine-backed asset store:

1. Inspect the capability contract.
2. Run a dry-run sync plan.
3. Review creates, updates, unchanged assets, and digests.
4. Apply only after review.
5. Treat artifacts/index.yaml as the source of truth until a later workplan explicitly changes that operational mode.