generated from coulomb/repo-seed
158 lines
4.9 KiB
Markdown
158 lines
4.9 KiB
Markdown
---
|
|
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.
|
|
|