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

id, type, title, domain, repo, status, owner, topic_slug, created, updated, state_hub_workstream_slug, state_hub_workstream_id

id	type	title	domain	repo	status	owner	topic_slug	created	updated	state_hub_workstream_slug	state_hub_workstream_id
IB-WP-0014	workplan	Infospace Backend Abstraction	markitect	infospace-bench	planned	markitect	markitect	2026-05-14	2026-05-14	ib-wp-0014-infospace-backend-abstraction	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

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

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

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

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

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.