---
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.