feat(manifest): implement Store + round-trip invariant against #505 interface + #504 C2 schema

bosun commented

2026-07-26 09:49:54 +02:00

Owner

Implement internal/manifest package (Store) satisfying the Go interface landed in #505 + the C2 schema landed in #504.

Motivation

Phase 4 continues contract-driven TDD-per-phase per ADR-0009 §3.1. internal/manifest is one of two Phase 4 packages (sibling: #541 forgejo client). Interface (Store + round-trip invariant) is Surveyor-approved in #505; C2 schema (manifest.schema.json) landed in #504; implementation lands here.

Scope

internal/manifest/*.go — implementation satisfying #505 interface (Store.Load, Store.Save, typed Manifest struct matching C2 schema)
Property invariant: manifest round-trip (Load → Save → Load == original), verified via property test (per ADR-0009 §3.2 property invariants section)
C2 schema validation: load-time validation against manifest.schema.json — parse errors + schema-violation errors have distinct sentinels
Bash byte-oracle: existing bash manifest logic (in lib/manifest.sh or embedded in release.sh/release-prep.sh — VERIFY on-disk before starting)
TDD approach (contract-driven per ADR-0009 §3.1):
1. Test against interface first
2. Oracle harness case using internal/harness (reuse Phase-1 vehicle)
3. Implementation to green
Sentinel errors: fail-loud discipline per §5 (manifest-not-found, schema-violation, parse-error, atomic-write-failure)
Fixture corpus at testdata/fixtures/manifest/ — real .release-toolkit-manifest.json shapes + malformed + edge cases (empty, missing required fields, unknown fields per C2 additionalProperties)

AC

internal/manifest implementation compiles + all #505 interface methods satisfied — verified in PR#543 9475e9e (Store.Read/Write/CheckDesync landed)
C2 schema validation wired at Load time — substrate observation: NO bash JSON-schema validator exists in toolkit → Go C2 strictness is CONTRACT-AUTHORITY (not bash-equivalence). Disclosed + asserted as standing divergence test per AC "disclose honestly" clause. Same substrate-class as Verdict-lift-with-alias — Go establishes what bash never enforced
Manifest round-trip property invariant test green — verified in PR#543
Unit tests green — verified: TestManifestSchemaStricterThanBash (4 cases post-fold, complete boundary: empty-input + trailing-data + neighbors)
Equivalence-harness cases against bash oracle green — verified: Surveyor reproduced all 4 disclosed boundaries + swept complete on schema-strictness axis (17 C2 cases) + CheckDesync 5a/5b/5c one-to-one with manifest-check.sh §5 (5d deferral legit) + atomic tmp+rename verified + jq -n writer byte-identical across edge vectors. Undisclosed second-writer neighbor (update path) converges byte-identical. Harness teeth via her key-order mutation (review 4579/4581)
go vet ./... + golangci-lint run clean — verified: gate own instrument (golangci-lint 2.12.1) fired 0 issues on both amend heads (c3268f7 initial + 9475e9e post-SC-fold)

Depends on: #505 (interfaces), #504 (C2 schema), #503 (harness vehicle)
Sibling: #541 (forgejo client — parallelizable OR sequential Engineer continuation)
Downstream: Phase 6 orchestrators (#508) consume Store; #499 (fail-atomic transactional cut — Phase 6 root cause of the manifest orphan class) will land against this Store impl
Cross-phase: #499 (Phase 6) depends on this manifest impl providing the atomic-write semantics
Refs ADR-0009 §3.1 (contract-driven TDD), §3.2 C2 + manifest round-trip invariant, §3.3 phase 4 row, §5 (fail-loud + trivalent-verdict discipline), §6 (#499 fail-atomic transactional cut design)

Anchor

Filed 2026-07-26 by Bosun on operator continuation direction for Phase 4 dispatch.

Implement `internal/manifest` package (Store) satisfying the Go interface landed in #505 + the C2 schema landed in #504. ## Motivation Phase 4 continues contract-driven TDD-per-phase per ADR-0009 §3.1. `internal/manifest` is one of two Phase 4 packages (sibling: [[#541 forgejo client]]). Interface (`Store` + round-trip invariant) is Surveyor-approved in #505; C2 schema (`manifest.schema.json`) landed in #504; implementation lands here. ## Scope - `internal/manifest/*.go` — implementation satisfying #505 interface (Store.Load, Store.Save, typed Manifest struct matching C2 schema) - **Property invariant**: **manifest round-trip** (Load → Save → Load == original), verified via property test (per ADR-0009 §3.2 property invariants section) - **C2 schema validation**: load-time validation against `manifest.schema.json` — parse errors + schema-violation errors have distinct sentinels - **Bash byte-oracle**: existing bash manifest logic (in `lib/manifest.sh` or embedded in `release.sh`/`release-prep.sh` — VERIFY on-disk before starting) - **TDD approach** (contract-driven per ADR-0009 §3.1): 1. Test against interface first 2. Oracle harness case using `internal/harness` (reuse Phase-1 vehicle) 3. Implementation to green - **Sentinel errors**: fail-loud discipline per §5 (manifest-not-found, schema-violation, parse-error, atomic-write-failure) - Fixture corpus at `testdata/fixtures/manifest/` — real `.release-toolkit-manifest.json` shapes + malformed + edge cases (empty, missing required fields, unknown fields per C2 additionalProperties) ## AC - [x] `internal/manifest` implementation compiles + all `#505` interface methods satisfied — verified in PR#543 9475e9e (Store.Read/Write/CheckDesync landed) - [x] C2 schema validation wired at Load time — **substrate observation**: NO bash JSON-schema validator exists in toolkit → Go C2 strictness is CONTRACT-AUTHORITY (not bash-equivalence). Disclosed + asserted as standing divergence test per AC "disclose honestly" clause. Same substrate-class as Verdict-lift-with-alias — Go establishes what bash never enforced - [x] Manifest round-trip property invariant test green — verified in PR#543 - [x] Unit tests green — verified: TestManifestSchemaStricterThanBash (4 cases post-fold, complete boundary: empty-input + trailing-data + neighbors) - [x] Equivalence-harness cases against bash oracle green — verified: Surveyor reproduced all 4 disclosed boundaries + swept complete on schema-strictness axis (17 C2 cases) + CheckDesync 5a/5b/5c one-to-one with manifest-check.sh §5 (5d deferral legit) + atomic tmp+rename verified + jq -n writer byte-identical across edge vectors. Undisclosed second-writer neighbor (update path) converges byte-identical. Harness teeth via her key-order mutation (review 4579/4581) - [x] `go vet ./...` + `golangci-lint run` clean — verified: gate own instrument (golangci-lint 2.12.1) fired 0 issues on both amend heads (c3268f7 initial + 9475e9e post-SC-fold) ## Related - Depends on: #505 (interfaces), #504 (C2 schema), #503 (harness vehicle) - Sibling: #541 (forgejo client — parallelizable OR sequential Engineer continuation) - Downstream: Phase 6 orchestrators (#508) consume Store; #499 (fail-atomic transactional cut — Phase 6 root cause of the manifest orphan class) will land against this Store impl - Cross-phase: #499 (Phase 6) depends on this manifest impl providing the atomic-write semantics - Refs ADR-0009 §3.1 (contract-driven TDD), §3.2 C2 + manifest round-trip invariant, §3.3 phase 4 row, §5 (fail-loud + trivalent-verdict discipline), §6 (#499 fail-atomic transactional cut design) ## Anchor Filed 2026-07-26 by Bosun on operator continuation direction for Phase 4 dispatch.

bosun added this to the Phase 4 — Forgejo client + manifest milestone

2026-07-26 09:49:54 +02:00

bosun added the

priority/high

size/M

kind/feature

labels

2026-07-26 09:49:54 +02:00

engineer self-assigned this

2026-07-26 09:51:15 +02:00

engineer referenced this issue from a commit

2026-07-26 10:06:34 +02:00

feat(manifest): implement Store — Read/Write/CheckDesync + round-trip (#542)

engineer referenced this issue

2026-07-26 10:07:36 +02:00

feat(manifest): implement Store — Read/Write/CheckDesync + round-trip (#542) #543

engineer referenced this issue from a commit

2026-07-26 10:23:05 +02:00

feat(manifest): implement Store — Read/Write/CheckDesync + round-trip (#542)

bosun closed this issue

2026-07-26 10:26:44 +02:00

bosun commented

2026-07-26 10:26:44 +02:00

Author

Owner

Closed by hand — PR#543 merged as 9475e9e09067f34fe9123207d2e2021b3f5b8ae0 on v2/next (fast-forward). All 6 ACs ticked with substrate anchors above.

Two amend cycles:

c3268f7 (initial) → Surveyor stamp 4579 with non-blocking SC (comment/test only, false-parity on store.go:113 "matches jq empty" claim)
9475e9e (SC fold: comment correction + test promotion to complete boundary + oracle comment tightening) → Surveyor re-stamp 4581 clean

Substrate discovery worth banking: contract-authority when no oracle exists — NO bash JSON-schema validator exists in toolkit; Go C2 strictness IS the enforcement substrate for the first time. Same class as Verdict-lift-with-alias (Go establishes what bash never enforced). Different from byte-equivalence-port class — this is a NEW substrate assertion, disclosed + asserted as standing divergence test.

Second stamp-with-SC-hiding-false-parity-in-comment pattern (first was #540 ComposeVerifyNoVersion). Worth banking as review-pattern note: SC on stamp can hide comment-level false-parity that logic-verification doesn.t touch; disclosed-boundary discipline says fix, not bank as forward-note.

Cross-references:

Depends on: #505 (interfaces), #504 (C2 schema), #503 (harness vehicle)
Sibling: #541 (forgejo client — Engineer sequential next; harness-shape design ratified as hybrid: mutation-payload-diff + captured-fixture-replay + fault-injection-server)
Cross-phase: #499 (Phase 6 fail-atomic transactional cut) can now build against this manifest impl providing atomic tmp+rename semantics
Refs ADR-0009 §3.1 (contract-driven TDD), §3.2 C2 + manifest round-trip invariant, §3.3 phase 4 row, §5 (fail-loud + trivalent-verdict discipline), §6 (#499 fail-atomic design)

Phase 4 status: 1/2 complete (#542 manifest). #541 forgejo client is Engineer.s sequential next.

**Closed by hand** — PR#543 merged as `9475e9e09067f34fe9123207d2e2021b3f5b8ae0` on v2/next (fast-forward). All 6 ACs ticked with substrate anchors above. **Two amend cycles**: - **c3268f7** (initial) → Surveyor stamp 4579 with non-blocking SC (comment/test only, false-parity on store.go:113 "matches jq empty" claim) - **9475e9e** (SC fold: comment correction + test promotion to complete boundary + oracle comment tightening) → Surveyor re-stamp 4581 clean **Substrate discovery worth banking**: **contract-authority when no oracle exists** — NO bash JSON-schema validator exists in toolkit; Go C2 strictness IS the enforcement substrate for the first time. Same class as Verdict-lift-with-alias (Go establishes what bash never enforced). Different from byte-equivalence-port class — this is a NEW substrate assertion, disclosed + asserted as standing divergence test. **Second stamp-with-SC-hiding-false-parity-in-comment pattern** (first was #540 ComposeVerifyNoVersion). Worth banking as review-pattern note: SC on stamp can hide comment-level false-parity that logic-verification doesn.t touch; disclosed-boundary discipline says fix, not bank as forward-note. **Cross-references**: - Depends on: #505 (interfaces), #504 (C2 schema), #503 (harness vehicle) - Sibling: #541 (forgejo client — Engineer sequential next; harness-shape design ratified as hybrid: mutation-payload-diff + captured-fixture-replay + fault-injection-server) - Cross-phase: #499 (Phase 6 fail-atomic transactional cut) can now build against this manifest impl providing atomic tmp+rename semantics - Refs ADR-0009 §3.1 (contract-driven TDD), §3.2 C2 + manifest round-trip invariant, §3.3 phase 4 row, §5 (fail-loud + trivalent-verdict discipline), §6 (#499 fail-atomic design) **Phase 4 status**: 1/2 complete (#542 manifest). #541 forgejo client is Engineer.s sequential next.

engineer referenced this issue from a commit

2026-07-26 14:34:03 +02:00

feat(forgejo): #541 typed Forgejo API client (Phase 4 2/2)

engineer referenced this issue

2026-07-26 14:34:19 +02:00

feat(forgejo): #541 typed Forgejo API client (Phase 4 2/2) #545

bosun referenced this issue

2026-07-26 14:47:04 +02:00

feat(forgejo): implement Client (17-function surface) + typed request/response against #505 interface + #504 C7 contract #541

bosun referenced this issue

2026-07-26 14:47:04 +02:00

feat(forgejo): implement Client (17-function surface) + typed request/response against #505 interface + #504 C7 contract #541