sha256-promotion
git-object-format specs/git-object-format/sha256-promotion.kmd
Specification body
SHA-256 default — promotion gate
Why this exists
#149 shipped [repository] DEFAULT_OBJECT_FORMAT as a per-instance knob.
The default stays sha1 "while git's sha1↔sha256 push/pull/mirror interop
is still in flight" (RFC-006 §5.2). Without a written promotion gate the
flip becomes an unscheduled judgment call instead of a tracked, auditable
transition.
This doc lists the concrete signals the Stack needs before flipping the Koder default to sha256.
R1 — Promotion gates
The default flips from sha1 to sha256 when all of the following
hold simultaneously. Each gate has a binary state (open / closed) tracked
in §3.
| Gate | Closed when |
|---|---|
| G1 — upstream git interop | Two consecutive upstream git releases (X.Y and X.(Y+1)) ship stable sha1↔sha256 push/pull/mirror semantics with no opt-in flags. Reference: git release notes; Koder Flow target git ≥ that minor pair. |
| G2 — Hub interop | hub.koder.dev/api/v1/apps/<slug> consumes sha256-formatted repo URLs (clone/release-asset paths) without breakage. Probe: a sha256 repo published as a Koder package installs cleanly via kpkg. |
| G3 — Mobile clients | Flow's app/ mobile clients fetch + render commit OIDs as full sha256 hashes (no UI truncation that conflicts with sha1 assumptions). |
| G4 — CI runners | Every Koder-published CI runner image can git fetch from a sha256-format repo (act_runner / ci-runner-linux / ci-runner-android base images). |
| G5 — kdb-next refs schema | git_refs rows fit sha256 (64-char hex) without column-size truncation. Phase 2 CAS validates both formats. (Closes alongside RFC-006 §3 work.) |
| G6 — IDE integrations | Koda IDE (engines/lang/koda) git plugin lists/diffs sha256 repos. |
R2 — Default flip — what it actually changes
When all gates close, the change is one line:
# products/dev/flow/engine/koder.toml or app.ini
[repository]
DEFAULT_OBJECT_FORMAT = sha256 # was: sha1
It affects new repos only. Existing repos keep their format (per-repo column). Migration of existing repos to sha256 is a separate, opt-in operator action (out of scope here; track in a follow-up if/when demand surfaces).
R3 — Out of scope
- Migrating existing repos (touches every clone-tool downstream).
- BLAKE3 (no upstream git support — RFC-006 §5.2 RESOLVED decision).
- Hash-embedded tamper-evident provenance (deferred per RFC-006 §5.2; gated on KVS#187 trailers/notes being shown insufficient).
R4 — koder.toml tracking
Flow's koder.toml declares the gate as planned and tracks state. When
all six close, the planned-gate row drops and the default flips in one PR.
[gates.planned]
sha256_default = "doc:meta/docs/stack/specs/git-object-format/sha256-promotion.kmd"
Status
All six gates open. No status changes recorded yet — this doc is the initial filing.
| Gate | State | Last checked | Evidence |
|---|---|---|---|
| G1 — upstream git interop | open | 2026-05-28 | no consecutive-release stability confirmed |
| G2 — Hub interop | open | 2026-05-28 | not probed |
| G3 — Mobile clients | open | 2026-05-28 | not audited |
| G4 — CI runners | open | 2026-05-28 | not audited |
| G5 — kdb-next refs schema | open | 2026-05-28 | sha1-shaped reftable today |
| G6 — IDE integrations | open | 2026-05-28 | not audited |
Refresh this table whenever a gate state changes. The flip PR cites this doc + the closed state of all six rows as evidence.