shard-wiki/workplans/SHARD-WP-0012-git-shard-adapter.md

id, type, title, domain, repo, status, owner, topic_slug, created, updated, depends_on

id	type	title	domain	repo	status	owner	topic_slug	created	updated	depends_on
SHARD-WP-0012	workplan	second adapter — git-IS-store shard (contract validation on a new substrate)	whynot	shard-wiki	active	tegwick	whynot	2026-06-15	2026-06-15	SHARD-WP-0007 SHARD-WP-0008

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

id: SHARD-WP-0012-T1
status: todo
priority: high

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)

id: SHARD-WP-0012-T2
status: todo
priority: high

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

id: SHARD-WP-0012-T3
status: todo
priority: medium

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.