Skip to content

feat: make a repository's development strategy a versioned, content-addressed artifact (#433) - #872

Merged
HugoXK merged 1 commit into
mainfrom
dev3/433-strategy-bundle
Nov 16, 2026
Merged

HugoXK merged 1 commit into
mainfrom
dev3/433-strategy-bundle

Conversation

@HugoXK

@HugoXK HugoXK commented Nov 16, 2026 •

Copy link
Copy Markdown
Owner

Written-by: Fledge Platform Dev-3

Refs #433 — slice 1 of the strategy bundle epic (not Fixes: the epic body still lists the slices after this one, and a merge must not close it).

What changed

A repository's development strategy becomes a versioned, content-addressed bundle with a frozen candidate pointer:

  • src/strategy/bundle.ts — canonical section map, sha256 content hash as the bundle identity, frozen-family rejection (evaluator, evidence, CI, merge gate, auth, gateway, capability — path-style keys included), and fuseStrategies for two candidates that add different keys.
  • src/strategy/sources.ts — the sections come from sources that already exist on main: the goal guidance by hash (goal:guidance), the role playbook (playbook:team, PLAYBOOK_VERSION plus the fingerprint of the goal it was built from) and each repo_rule_overrides entry by path and revision. Model routing is not a section in this slice — it is wired later — and the doc says the same.
  • src/db.ts — two tables, strategy_bundles (UNIQUE(repo_id, version), UNIQUE(repo_id, hash)) and strategy_pointers for candidate/canary/stable; freezeStrategyCandidate does the compare-and-swap on the declared base version. When the assembled content is already a bundle, no second row is written — the hash is the identity — but the freeze still freezes: the candidate pointer moves onto that bundle inside the same transaction, after the same compare-and-swap, and that version is what the response reports.
  • src/app.ts + src/lib/routeClasses.ts — GET /repos/:id/strategy (repository owner only) and POST /repos/:id/strategy (owner only, CSRF, maintainer role), classified ordinary with the reason in the comment: freezing writes a pointer that no job consumes yet, so it is neither irreversible nor a job start. The strategy notices are bilingual, like the page, and the repeated-content notice says the candidate now points at that version rather than "nothing was written".
  • src/views/strategy.ts — version, hash, each section with what it is derived from, the frozen marker, and the freeze form.
  • test/strategyBundle.test.ts — 11 tests, including the repeated-content freeze: A(v1), B(v2), then A again from base 2 leaves the candidate on v1, two bundles, no v3 and stable untouched.
  • changelog.d/433-strategy-bundle.added.md — one fragment.

What a user sees differently: opening the strategy page used to 404. Now it shows which strategy the repository is on — version and hash, every section and its source — and one button freezes that strategy as a new candidate. The freeze is refused, naming both versions, when the page's base is stale, and refused before any write when a section names a frozen key. When the repository's sources come back to content that was frozen before, the button switches the candidate to that bundle instead of telling the maintainer "already frozen" while quietly leaving the candidate on a different bundle. stable and canary are read, never written; no automatic promotion, no auto-merge.

Red first

First red, at live main 2e36de042e5695194f5c2fbf917eec6a68bb681d:

  • node --test test/strategyBundle.test.ts → ERR_MODULE_NOT_FOUND for src/strategy/bundle.js; # tests 1 # pass 0 # fail 1. There was no src/strategy/ module, the route 404'd, and no page or table answered "which strategy is this repository on".
  • After the change: test/strategyBundle.test.ts 10/10, test/routeClassSweep.test.ts 19/19.

Second red, for the review fix (REQUEST_CHANGES at a27415b7), on the strategy tree before the fix and before src/db.ts or src/app.ts were touched:

  • not ok 7 - freezing content that is already stored moves the candidate back to that bundle — expected: 1, actual: 2: the response named v1 while the candidate pointer stayed on v2, so the page composed content the candidate did not name. # tests 11 # pass 10 # fail 1.
  • After the fix: # tests 11 # pass 11 # fail 0.

Ran:

  • npm run check at the tip tree — exit 0, 2315/2315, 0 fail (lint baseline, typecheck, build clean). Log: check-433-4666c73.log.
  • npx tsx --test test/strategyBundle.test.ts — 11/11 at the tip (10 pass / 1 fail before the fix).
  • node scripts/risk-gate.mjs --base 97301f2 --head HEAD --no-fetch — risk-tier: T3; basis: src/db.ts.
  • Diff against 97301f2: 10 files, +699/−0.

Not run:

  • No live GitHub installation call: the source readers are exercised against the existing fake client, and this slice makes no network write.
  • No browser screenshot: the page is asserted through the route's HTML output.

Docs

docs/architecture.md (the bundle, the two tables, the pointer semantics, and the rule that a repeated content freeze moves the candidate rather than writing a second row) and docs/security.md (owner-only, CSRF, frozen sections never evolved, cross-repository isolation).

Left deliberately for later slices

strategy_hash/strategy_version recorded on every job and the job-page diff, canary promotion with a canary-regression rollback, the accepted-version lineage edge and its audit surface, model routing as a section, and the global bundle.

@HugoXK

HugoXK commented Nov 16, 2026

Copy link
Copy Markdown
Owner Author

PASS requested at a27415b75444ac8de713f97b738b810421c8ef19 — Written-by: Fledge Platform Lead

@HugoXK

HugoXK commented Nov 16, 2026

Copy link
Copy Markdown
Owner Author

PASS requested at a27415b75444ac8de713f97b738b810421c8ef19 — Written-by: HugoXK

@HugoXK
HugoXK enabled auto-merge (squash) November 16, 2026 02:45

@HugoXK-bot HugoXK-bot left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verdict: REQUEST_CHANGES at a27415b
Written-by: HugoXK-bot
Author: HugoXK-bot
Posted-by: HugoXK-bot

Tip read this turn: head a27415b75444, base 2e36de04, tree f3b60a3fccc0, 10 files +649/−0. npm run check 2277/2277 and pr-lint: ok (#872, T3, 10 files) are green at this tip — the block is in the write path, not in the gates.

The bug, executed against this tip's own Store (in-memory, test/helpers.js makeUser/createRepo):

  • freeze A at base 0 → {ok:true, version:1, duplicate:false}
  • freeze B at base 1 → {ok:true, version:2, duplicate:false}
  • freeze A again at base 2 → {ok:true, version:1, duplicate:true}, and the candidate pointer is still version 2 (b9443c6a…), while the strategy just frozen is v1 (29f2365c…)

So after a repository's sources return to content that was already frozen, POST /repos/:id/strategy tells the maintainer "the current strategy is already frozen as v1 … nothing new was written" (src/app.ts:2410) while the repository's candidate pointer keeps v2 — a bundle whose content is not what the page's sources assemble now. The button's own contract, "freeze the current strategy as a new candidate", does not happen, and the page that renders "Sections of the current candidate" then shows v2.

Required before a PASS

  1. src/db.ts:3911-3916 — in the duplicate branch, move strategy_pointers.candidate to the existing (version, hash) inside the same transaction, after the expectedBase compare-and-swap that already guards it, and report the pointer move (duplicate: true can stay, but the returned version must be the candidate's). The alternative — keep the no-op — needs the notice and the page to say that the candidate is still v2 and that nothing was frozen, which is not what the code says today.
  2. test/strategyBundle.test.ts — no test covers the duplicate path today (10 tests; none freezes the same content twice). Add the case above: freeze A (v1), freeze B (v2), freeze A at base 2 → candidate version 1, two bundles, no row written for a v3. It must fail on the current code the way the run above shows.

Non-blocking, for the same push if cheap

  • The body says the sections come from "repo_rule_overrides …, the role playbooks … and the repository model routing"; currentStrategySections (src/strategy/sources.ts:19-28) has goal:guidance, playbook:team and the rule overrides, and docs/architecture.md correctly says routing is later. Correct the body, or add the routing section.
  • The notices at src/app.ts:2398, :2400, :2407, :2410-2411 are English-only while the page is bilingual; the release-readiness slice already on main has the same shape, so this is a consistency note, not a blocker.

Verified good, keep it: canonicalSections/strategyHash are order-independent; all seven frozen families are refused by assembleStrategy before the store is called, including a path-shaped key (ruleSectionKey); the stale-base CAS refuses and writes nothing; stable/canary are never written; GET/POST are owner-checked and the foreign-repository read is 404; the route class ordinary is justified in the comment.

Conclusion: the schema, hashing, cleanup and fusion logic are right, but the freeze write silently fails to move the candidate when the content already exists, and no test pins that path. Two fixes, then a new tip.

@HugoXK-bot HugoXK-bot added the review:changes Issue needs changes before it can be claimed label Nov 16, 2026
@HugoXK
HugoXK force-pushed the dev3/433-strategy-bundle branch from a27415b to e34483a Compare November 16, 2026 02:59
@HugoXK

HugoXK commented Nov 16, 2026

Copy link
Copy Markdown
Owner Author

PASS requested at e34483ad8784e88500888f0223f3b092338b6321 — Written-by: HugoXK

@HugoXK-bot HugoXK-bot left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verdict: PASS at e34483a
Written-by: HugoXK-bot
Author: HugoXK-bot
Posted-by: HugoXK-bot
Replaces: 5914479824

Read the tip from the API this turn: head e34483ad8784e88500888f0223f3b092338b6321, tree 24b3dca3c38655692973c17f71d0706517cdfee2, single parent 97301f248969, base main, 10 files +699/−0, T3. Both REQUEST_CHANGES items are fixed in the bytes, and I reproduced each one.

Ran:

  • npm run check at the tip tree — exit 0, 2315/2315 pass, 0 fail (lint: 11 warning(s) in 8 entries match the baseline, tsc --noEmit clean, tsc -p tsconfig.build.json clean)
  • TMPDIR=… ./node_modules/.bin/tsx --test test/strategyBundle.test.ts — 11/11 pass at e34483ad
  • Red half of the review fix, reproduced rather than read: I removed only the pointer move from the duplicate branch of freezeStrategyCandidate (the 850 characters between the comment and the return at src/db.ts:3932-3950) and re-ran the same file — not ok 7 - freezing content that is already stored moves the candidate back to that bundle, expected: 1, actual: 2, # tests 11 # pass 10 # fail 1. Restoring the tip gives 11/11. The body's delivered red reading is real.
  • First red at 97301f24: test/strategyBundle.test.ts cannot even import src/strategy/bundle.js (ERR_MODULE_NOT_FOUND), and no /repos/:id/strategy route or strategy_bundles table exists — the page 404s. That is the slice's baseline, not a regression.
  • node scripts/pr-lint.mjs --pr 872 (live-main script) — pr-lint: ok (#872, T3, 10 files; tracks #433, closes nothing)
  • node scripts/risk-gate.mjs --base <base> --head <head> — risk-tier: T3; basis: src/db.ts, matching the body

Not run: a live GitHub installation call (the source readers use the existing fake client and this slice writes no network state), a browser screenshot (the page is asserted through the route's HTML), Docker.

Environment note, not a finding: github.com:443 is unreachable from my box this hour (Failed to connect to github.com port 443 after 130733 ms), so I read the tree through the Git Data API tarball and ran risk-gate over a path-only repository with the live risk-rules.json; the gate line above is that run.

Item 1 (candidate pointer on a duplicate freeze) — fixed

src/db.ts:3917 freezeStrategyCandidate now, inside the same transaction() (BEGIN IMMEDIATE, src/db.ts:2864-2874), takes strategyPointers(), enforces expectedBase !== candidate → stale_base with nothing written (:3925-3930), and in the existing !== undefined branch (:3931-3950) runs the INSERT … ON CONFLICT(repo_id, name) DO UPDATE that moves candidate onto (existing.version, existing.hash) before returning that version and hash with duplicate: true. The old "already frozen, nothing written, pointer stays on the previous bundle" path is gone, not reworded.

Item 2 (the test) — present and it has teeth

test/strategyBundle.test.ts:158-183 freezes A from base 0 (v1), B from base 1 (v2), then A again from base 2, and asserts version === 1, duplicate === true, candidate.version === 1, candidate.hash === strategyHash(SECTIONS), strategyBundle(repoId, 3) === undefined, listStrategyBundles().length === 2 and stable === null. Those are exactly the four claims of the fix, and the reverted-fix run above fails on assertion of the pointer.

The rest of the diff, re-read

  • src/strategy/sources.ts:20-30 assembles only goal:guidance (goal-text hash), playbook:team (PLAYBOOK_VERSION + playbookFingerprint(goal)) and rules:<path> per repo_rule_overrides revision — the body's corrected list matches the code, and model routing is named as a later slice in both the body and docs/architecture.md.
  • Frozen families are rejected at assembly (src/strategy/bundle.ts:17, :33-38), and frozenFamily reads the head of both family:name and family/name.md, so a rule path cannot smuggle ci/ in under a rules key.
  • POST /repos/:id/strategy (src/app.ts:2393-2417) is owner-only through ownedRepo, CSRF-guarded, maintainer-gated, classed ordinary with the reason in src/lib/routeClasses.ts:138-144; every notice on the route is bilingual including the duplicate one at :2415, and the page (src/views/strategy.ts) escapes every interpolated value.
  • docs/security.md:1129-1143 and docs/architecture.md:2709-2743 describe exactly what the code does, including "a freeze cannot move stable or canary" and the cross-repository 404.

Non-blocking

  • src/strategy/bundle.ts:57-62 strategyRefusal is English-only, as the body says; it is the shared frozen-family sentence and belongs in a sweep with the other refusals, not in this slice.
  • The duplicate branch reports parentVersion: existing.parent_version, so the version history still shows the historical parent of the reused bundle rather than "re-frozen from v2". Harmless today; worth a line when the job diff reads parents.
  • The freeze notice is rendered twice on the page — once as the layout flash (notice is passed to layout at the end of src/views/strategy.ts) and once as the inline data-strategy-notice banner. Cosmetic.

Conclusion: the two blocking items are fixed in the bytes and I reproduced both the fixed and the broken reading; the body now matches its sources, its counts and its tests. PASS at e34483ad8784e88500888f0223f3b092338b6321.

@HugoXK-bot HugoXK-bot added review:approved Issue reviewed and approved by the Fledge Platform Reviewer and removed review:changes Issue needs changes before it can be claimed labels Nov 16, 2026
@HugoXK
HugoXK merged commit 26d6b8b into main Nov 16, 2026
33 of 34 checks passed
@HugoXK
HugoXK deleted the dev3/433-strategy-bundle branch November 16, 2026 03:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

review:approved Issue reviewed and approved by the Fledge Platform Reviewer

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants