generated from coulomb/repo-seed
tegwick
def699c1eb
Adopt git-native history (TSD §A.5): a VERSION-gated history(key) surfaces the commit list for a path (newest-first sha + subject) — declared by every git-IS-store shard, read-only or not. Integration proves the union/overlay/edit machinery works unchanged across folder + git substrates: resolve/chorus span both, edit through a git shard fast-forwards as a commit, apply-under-drift refuses on an external commit (sha drift) without clobbering, and a read-only git target keeps the overlay as a draft. SCOPE updated; WP-0012 done. 196 tests green. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
101 lines
3.6 KiB
Markdown
101 lines
3.6 KiB
Markdown
---
|
|
id: SHARD-WP-0012
|
|
type: workplan
|
|
title: "second adapter — git-IS-store shard (contract validation on a new substrate)"
|
|
domain: whynot
|
|
repo: shard-wiki
|
|
status: done
|
|
owner: tegwick
|
|
topic_slug: whynot
|
|
created: "2026-06-15"
|
|
updated: "2026-06-15"
|
|
depends_on:
|
|
- SHARD-WP-0007
|
|
- SHARD-WP-0008
|
|
state_hub_workstream_id: "9e24eeb0-c0f0-41e6-a1ca-88d71e4139ea"
|
|
---
|
|
|
|
# SHARD-WP-0012 — git-IS-store shard adapter
|
|
|
|
## Goal
|
|
|
|
Add a **second adapter on a different substrate** to validate the contract beyond the plain
|
|
folder: a **git-IS-store** shard (`FederationArchitecture` T17 / TSD §A.3 — the home case where
|
|
git is the store *and* the journal). It exercises git-native history (TSD §A.5 *adopt*),
|
|
commit-as-write, `current_rev`=commit-sha drift detection, and the implication rules
|
|
(attachment=git-IS-store ⟹ substrate=git ∧ history=git-native). Proves "writing an adapter +
|
|
declaring a verified profile" is all it takes — no core changes.
|
|
|
|
**Non-goal:** remote push/pull federation (VCS-replication+ping is a federation workplan);
|
|
merge beyond fast-forward (apply-under-drift refuse is enough, as in SHARD-WP-0008).
|
|
|
|
## Context
|
|
|
|
- Contract: `TechnicalSpecificationDocument.md` §A; binding taxonomy §A.3; history §A.5.
|
|
- Reuses the existing contract/conformance/overlay machinery unchanged.
|
|
|
|
---
|
|
|
|
## GitShardAdapter — read over a git working tree/repo
|
|
|
|
```task
|
|
id: SHARD-WP-0012-T1
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "8a1c7c80-a0cc-4e02-a611-1f1fd7dec57b"
|
|
```
|
|
|
|
A `GitShardAdapter` reading Markdown from a git repo: keys = tracked `*.md` paths; `read`
|
|
returns a `Page` whose `source_rev` is the **commit sha** (HEAD or blob commit); profile =
|
|
git-IS-store / substrate=git / history=git-native / addressing=path, validated against the
|
|
implication rules. Tests: read tracked files; profile validates; conformance read path passes.
|
|
|
|
## Write = commit; current_rev = sha (drift)
|
|
|
|
```task
|
|
id: SHARD-WP-0012-T2
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "b47dfb86-46c1-4e97-a62f-377719499ff2"
|
|
```
|
|
|
|
`write(key, body)` stages + **commits** (author/message), returning the updated `Page` at the
|
|
new sha; `current_rev(key)` returns the current commit sha for drift detection. Declare `WRITE`
|
|
+ `version`. Tests: write commits; conformance positive-write probe passes; `current_rev`
|
|
changes after an external commit.
|
|
|
|
## History adopt + integration with union/overlay
|
|
|
|
```task
|
|
id: SHARD-WP-0012-T3
|
|
status: done
|
|
priority: medium
|
|
state_hub_task_id: "4c895f42-671d-4948-8bdf-941fd85644bb"
|
|
```
|
|
|
|
Adopt git-native history (TSD §A.5 *adopt*): expose a minimal page history (commit list for a
|
|
path) behind a `version`-gated method. Integration: attach a `GitShardAdapter` to an
|
|
`InformationSpace` alongside a `FolderAdapter` → resolve/chorus/edit/overlay/apply all work
|
|
across substrates (apply-under-drift uses sha rev). Update SCOPE; `pytest` + pyflakes green.
|
|
|
|
---
|
|
|
|
## Acceptance criteria
|
|
|
|
- `GitShardAdapter` passes the conformance suite (read + positive write) with a profile whose
|
|
implication rules hold (git-IS-store ⟹ git substrate + git-native history).
|
|
- Write = commit; `current_rev` = sha drives apply-under-drift correctly.
|
|
- The union/overlay/edit machinery works unchanged across folder + git shards (no core change —
|
|
capability-as-data proven on a second substrate).
|
|
- `pytest` + pyflakes green; each task committed; state-hub synced.
|
|
|
|
## Notes
|
|
|
|
If `git` plumbing via subprocess proves heavy for tests, a thin in-repo git helper (or
|
|
`tmp_path` repos created in tests) is acceptable; no new runtime dependency — use stdlib +
|
|
`git` CLI already present.
|
|
|
|
## Suggested task order
|
|
|
|
T1 read adapter + profile → T2 write=commit + current_rev → T3 history adopt + integration.
|