generated from coulomb/repo-seed
101 lines
2.5 KiB
Markdown
101 lines
2.5 KiB
Markdown
# 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:
|
|
|
|
```python
|
|
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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```bash
|
|
python3 -m infospace_bench engine plan-sync infospaces/bootstrap-pilot
|
|
python3 -m infospace_bench engine sync infospaces/bootstrap-pilot
|
|
```
|
|
|
|
Mutation requires explicit apply:
|
|
|
|
```bash
|
|
python3 -m infospace_bench engine sync infospaces/bootstrap-pilot --apply
|
|
```
|
|
|
|
Apply writes the local adapter store and a sync run record under:
|
|
|
|
```text
|
|
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.
|