Repository navigation
feat(instructions): compile the instruction set into a content-addressed adherence contract - #1112
Merged
Merged
Conversation
…sed adherence contract (#364) Slice 1 of #364. compileInstructionContract collects the instruction set a job runs under — repo identity, goal, playbook version and hash, context files, allow/deny paths, branch and base, required evidence and sections, forbidden actions, carry-over, model and role — into one contract, and instructionContractHash takes its SHA-256 over canonical JSON. evaluateAdherence answers one clause at a time from what a callback reports: pass when observed and satisfied, violation when observed and broken, unverifiable when not observed — never pass. A callback whose echoed hash is another contract's, or missing, records hashVerified false. Pure functions: the job column, the bridge echo, the job page and the merge refusal are the next slice.
HugoXK-bot
approved these changes
Nov 19, 2026
HugoXK-bot
left a comment
Collaborator
There was a problem hiding this comment.
Verdict: PASS at f290669
Written-by: HugoXK-bot
Author: Fledge Platform Verdict
- The locale dependency is gone, not papered over:
byCodeUnit(src/lib/instructions.ts:25-27) replaceslocaleCompare,canonicalSetde-duplicates and sorts every set-like list before hashing (:30-32, applied:101-104),contextFilessorts by(path, sha)(:95-97), andcarryOverkeeps its recorded order because it is a sequence (:105). - I reproduced the fix independently: the same input (context files, path rules, evidence, sections and forbidden actions all reversed and repeated) compiled to one hash
088aaf9f…fee9underLC_ALL=en_US.UTF-8,zh_CN.UTF-8andC, with the canonical orderREADME.md, src/z.ts, src/上海.ts, src/北京.ts— the order the body pins. - Clause evaluation keeps "not observed" out of "clean":
nulland[]never collapse (:116-119,:145-167), an echoed hash that is missing or another contract's recordshashVerified: falseand cannot producepass(:125-135), and the record takes the strongest clause while keeping each clause's own reason (:208-213). - Path matching reuses
matchesPathfromsrc/lib/pathGuard.ts:37, so the evaluator and the merge path guard agree on a deny pattern by construction rather than by a second implementation. - Pure and unreferenced in this slice: only
node:crypto,canonicalJsonandmatchesPathare imported; no route, job, DB or bridge path consumes it, so the running platform's behaviour is unchanged.
Ran:
npx tsx --test test/instructions.test.ts— 10/10 passnpm run typecheck— clean- compiled the same input under
LC_ALL=en_US.UTF-8,zh_CN.UTF-8andCwithnpx tsx— one hash088aaf9f…fee9in all three
Not run: a real dispatched job carrying this contract (slice 2), the Docker image, a real FlyBot run. No UI face (nosrc/views/orpublic/change), so no before/after frames andnpm run mock:checkwas not needed.
) `localeCompare` sorts by the machine's collation, so the same instruction set hashed differently under en_US and zh_CN, and the path rules were copied in the caller's order. Both break the module's one promise. The set-like lists are now de-duplicated and ordered by UTF-16 code unit before hashing; the carry-over keeps its recorded order. The new case compiles the same input twice in this process and once each in two children started under en_US.UTF-8 and zh_CN.UTF-8.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Written-by: HugoXK
Author: Fledge Platform Dev-4
Part of #364 — slice 1 of three on
dev4/364-adherence-contract, tipf2906693.What this slice is
The job's instruction set — goal, playbook,
AGENTS.mdand rules, path constraints, evidence and section requirements, forbidden actions, carry-over, model and role — reaches the agent as prose. Nothing afterwards can check the job against what it was told, so Fledge cannot tell a compliant run from one that says it complied.This slice is the compiler and the evaluator, as pure functions in
src/lib/instructions.ts:compileInstructionContract(input)builds oneInstructionContractandinstructionContractHashtakes its SHA-256 over the canonical JSON of the compiled object. Two compilations of the same instructions hash the same; any changed input is a different contract. The lists the contract treats as sets — the path rules, the required evidence and sections, the forbidden actions and the context files — are de-duplicated and ordered by UTF-16 code unit before hashing, so neither the order a caller read them in nor the machine's collation can move the hash. The carry-over keeps the order it was recorded in, because it is a sequence of earlier turns and not a set.evaluateAdherence(contract, observation)answers one clause at a time:contract.hash,branch.base,paths.denied,paths.allowed,evidence.required,sections.required,actions.forbidden. Each ispass,violation, orunverifiable— neverpassfor something the callback could not observe. The record isviolationif any clause is, elseunverifiableif any is, elsepass, and every clause keeps its own reason even when a stronger status decides the record.hashVerified: falseand cannot produce apassrecord.nullin the observation means "not observed";[]means "observed, nothing there", and the two are never conflated.Path matching reuses
matchesPathfromsrc/lib/pathGuard.ts, so a deny pattern the merge path guard rejects is a deny pattern this evaluator rejects.What this slice does not do
It writes nothing. No column, no bridge payload, no route and no merge refusal: the job record storing the contract, the hash echo in the bridge, the job-page clause list and the
tryMergerefusal all read this record and are slices 2 and 3 of the same card on the same branch. Nothing in the running platform changes behaviour with this commit.Red first, at base
066a9cc8test/instructions.test.tswas written first, then the module's exported surface was stubbed withthrow new Error('not implemented')so the red would be an assertion-class failure rather than a missing module:At the first tip the same file is
# tests 9 # pass 9 # fail 0, including the case the card names — a changed denied path with green test evidence is a violation, not a pass.Review at
9e57ee6— the hash depended on the machine's localeThe finding is right, and it broke the one promise the module makes.
contextFileswas sorted withleft.path.localeCompare(right.path), which sorts by the collation of the locale Node started in, andpaths.allow/paths.denywere copied in the caller's order — so the same instruction set had more than one hash.Two child processes, the same input, the base module:
The fix, in
src/lib/instructions.ts:byCodeUnitcompares with</>, so the order is UTF-16 code unit order andlocaleCompareis gone from the module.canonicalSetde-duplicates and sorts the lists the contract treats as sets —paths.allow,paths.deny,required.evidence,required.sections,forbidden— before they are hashed.carryOverstays in its recorded order, because it is a sequence of earlier turns and its order is meaning.contextFilessorts by(path, sha), so the order is total and a repeated path cannot fall back on the caller's order.The case that would have caught it is now in
test/instructions.test.ts: the same input compiled twice in this process with the context files, the path rules, the requirements and the forbidden actions reversed, plus once each in two child processes started underen_US.UTF-8andzh_CN.UTF-8, all asserting one hash — and the canonical order pinned entry by entry (['README.md', 'src/z.ts', 'src/上海.ts', 'src/北京.ts']), so a future change to the comparator has to be deliberate.Red at
9e57ee6with the new case only, source from that tip:Green at
f2906693:# tests 10 # pass 10 # fail 0, and the two locales agree.docs/architecture.mdnow says what canonicalisation the hash rests on, beside the sentence it made false.Docs
docs/architecture.mdgains the paragraph beside the#433strategy precedent: the compiled contract, its hash, the clause list with its three statuses, and that the record's stronger status never erases a clause's reason — plus the ordering the hash depends on, so the next reader does not sort it back.Ran:
npm run checkat this tip (f290669) — pass,# tests 2993 # pass 2993 # fail 0(oxlint,tsc --noEmit, the suites and the build included).npx tsx --test test/instructions.test.tsat this tip — pass,# tests 10 # pass 10 # fail 0.9e57ee6, the same test file with the module restored from that tip —not ok 2 … the order a caller reads a set in is not part of the contract,# tests 10 # pass 9 # fail 1; and the same input compiled bynode --import tsx -eunderLC_ALL=en_US.UTF-8andLC_ALL=zh_CN.UTF-8—0c781dcf…302bandab0c1ab2…1b66.npm run mock:check—mock-snapshot: ok (14 files); this slice has no UI surface, so nomock/file changed.npm run test:coveragethennode scripts/coverage-diff.mjs --base 066a9cc890cb1f792bff866638517ee7b2f2aa9c --head HEAD --report coverage.txt --floor 80—coverage-diff: ok — 121/126 changed lines covered (96%, floor 80%).node scripts/risk-gate.mjs --base 066a9cc890cb1f792bff866638517ee7b2f2aa9c—risk-tier: T2; basis: src/lib/instructions.ts.node scripts/version.mjs check—version: 0.4.2 ok;node scripts/changelog.mjs check—changelog: 57 fragment(s) ok.checkBody(body, .github/agent/review-policy.json)locally — no findings.pr-lintitself is not runnable here (it requiresGITHUB_TOKENand a PR number).Not run: a real dispatched job carrying this contract (slice 2 reads it); the Docker image; a real FlyBot run.
Changelog-not-needed: no user-visible surface changes in this slice; the job page half is slice 3.
Risk and rollback
risk-tier: T2; basis: src/lib/instructions.ts, so this tip needs a PASS. The slice is 3 files, +452/−0; the locale fix alone is +92/−6 over9e57ee6.unverifiableby construction, so the first real runs under slice 2 will likely beunverifiablerather thanpass— that is the intended reading, not a bug to tune away.