engine and lifecycle

docs/infospace-layout.md

@@ -28,6 +28,7 @@ artifacts/generated/
 workflows/templates/
 output/evaluations/
 output/metrics/
+output/engine/sync-runs/
 output/workflows/runs/
 reports/
 exports/

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.

docs/replacement-acceptance-matrix.md

@@ -27,7 +27,7 @@ considered a replacement for each in-scope legacy infospace behavior from
 | Evaluate with LLM assistance | Provider-neutral assisted evaluation workflow | Dry-run plan, adapter contract, audited output | `IB-WP-0009` | boundary done |
 | Process source chapters | Explicit infospace workflow stages | Deterministic runner tests, generated artifact provenance | `IB-WP-0009` | deterministic baseline done |
 | Track stale outputs | Digest/provenance comparison | Tests after workflow provenance exists | `IB-WP-0009` | deferred |
-| Persist durable assets | Optional engine-backed repository adapter | Dry-run sync tests and integration design | `IB-WP-0010` | planned |
+| Persist durable assets | Optional engine-backed repository adapter | Dry-run sync tests and integration design | `IB-WP-0010` | boundary done |
 | Run a legacy-derived pilot | Pruned `infospace-with-history` migration | Pilot corpus, migration report, parity comparison | `IB-WP-0011` | planned |
 | Provide command migration path | Legacy command parity guide | Command table and examples | `IB-WP-0012` | planned |
 

docs/successor-boundary-interface-map.md

@@ -101,15 +101,17 @@ Responsibilities:
 
 ### Repository Adapter
 
-Planned module:
+Current module:
 
 ```text
-src/infospace_bench/repository.py
+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