engine and lifecycle

docs/kontextual-engine-boundary.md

@@ -0,0 +1,100 @@
+# 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.