Workplans to actually create infospaces

workplans/IB-WP-0014-infospace-backend-abstraction.md

@@ -0,0 +1,157 @@
+---
+id: IB-WP-0014
+type: workplan
+title: "Infospace Backend Abstraction"
+domain: markitect
+repo: infospace-bench
+status: planned
+owner: markitect
+topic_slug: markitect
+created: "2026-05-14"
+updated: "2026-05-14"
+state_hub_workstream_slug: "ib-wp-0014-infospace-backend-abstraction"
+state_hub_workstream_id: "c2d23ee7-6b2b-4db0-b660-a9e295c94956"
+---
+
+# IB-WP-0014 - Infospace Backend Abstraction
+
+## Goal
+
+Allow an infospace to live behind a selectable backend instead of assuming only
+a local filesystem directory.
+
+Target backends:
+
+- local folder
+- remote or mounted folder
+- S3-compatible bucket/prefix
+- git repository
+
+This is a new successor capability, not legacy parity. It should be designed so
+generation, validation, evaluation, and inspection logic do not care where the
+infospace is physically stored.
+
+## Intent
+
+The current repo is intentionally file-backed. That should remain the default.
+The improvement is to formalize the storage boundary so the same lifecycle and
+workflow APIs can operate on other backing stores through explicit adapters.
+
+The design should keep `infospace-bench` as an application workspace, not a
+durable storage engine. Credentials, remote locking, rich audit, and runtime
+orchestration should be delegated or integrated carefully rather than invented
+inside core application logic.
+
+## Non-Goals
+
+- Replace the existing local folder behavior.
+- Require S3 or git dependencies for ordinary local use.
+- Store secrets in `infospace.yaml`.
+- Build a general database, sync server, or object storage service inside this
+  repo.
+- Solve multi-writer conflict resolution beyond clear detection and reporting
+  in the first pass.
+
+## Tasks
+
+### T01 - Backend contract and URI model
+
+```task
+id: IB-WP-0014-T01
+status: todo
+priority: high
+state_hub_task_id: "75b7df31-066a-47ac-bb94-a4ae908569fd"
+```
+
+- Define a backend-neutral infospace location model
+- Support local paths without changing current user flows
+- Define URI examples for local, mounted folder, S3-compatible, and git-backed
+  infospaces
+- Define backend capabilities: read, write, list, exists, atomic write,
+  digest, version, sync, lock, and credentials-required
+- Document where credentials and remote configuration are allowed to live
+
+### T02 - Local and remote folder backend baseline
+
+```task
+id: IB-WP-0014-T02
+status: todo
+priority: high
+state_hub_task_id: "2e33d98a-0cd0-4608-b7a1-76c5a7bb26ca"
+```
+
+- Refactor lifecycle reads and writes behind a backend adapter while preserving
+  current `Path`-based behavior
+- Keep local folders as the default backend
+- Treat mounted or remote folders as folder backends when the OS exposes them
+  as paths
+- Add tests proving current pilots and CLI commands still work unchanged
+- Add tests for backend errors such as missing files, write failures, and
+  unsafe paths
+
+### T03 - S3 object-store backend adapter
+
+```task
+id: IB-WP-0014-T03
+status: todo
+priority: high
+state_hub_task_id: "e2ee9497-0a6c-419f-a045-fb994bf73b05"
+```
+
+- Design an optional S3-compatible backend adapter
+- Use a fake in-memory or local test double for default tests
+- Keep real credentials and network calls out of the default test suite
+- Define object key layout for manifests, artifacts, reports, exports, and run
+  records
+- Decide how digests, optimistic concurrency, and partial writes are reported
+
+### T04 - Git repository backend adapter
+
+```task
+id: IB-WP-0014-T04
+status: todo
+priority: high
+state_hub_task_id: "e2938c5b-e6c2-468a-b782-b39962e5a81b"
+```
+
+- Support opening or initializing an infospace backed by a git repository
+- Prove behavior against local test repositories before any remote network
+  workflow
+- Define when commits are created, when they are only suggested, and how dirty
+  trees are reported
+- Keep automatic commits opt-in
+- Preserve compatibility with the existing State Hub and workplan workflow
+
+### T05 - Backend CLI docs and migration path
+
+```task
+id: IB-WP-0014-T05
+status: todo
+priority: medium
+state_hub_task_id: "20d75d49-f62a-4236-a895-698cd2fae45a"
+```
+
+- Expose backend selection in CLI/API docs
+- Add examples for local, mounted folder, S3-compatible, and git-backed
+  infospaces
+- Document backend capabilities and limitations
+- Add a migration guide for moving a local infospace to another backend
+- Update acceptance docs so backend support is distinct from Wealth/VSM
+  generation parity
+
+## Acceptance
+
+- Existing local-folder behavior remains backward compatible
+- Lifecycle, validation, inspection, workflow, metrics, history, and graph
+  commands can operate through the backend contract
+- Default tests remain deterministic and do not require network credentials
+- Backend-specific capabilities and failure modes are visible to callers
+- S3 and git support are optional and clearly documented
+- Storage backend concerns stay separate from generation workflow semantics
+
+## Relationship To IB-WP-0013
+
+`IB-WP-0013` should prove generation parity on the default local backend first.
+This workplan then makes the same infospace operations portable across storage
+backends.
+