Skip to content

feat(instructions): compile the instruction set into a content-addressed adherence contract - #1112

Merged
HugoXK merged 2 commits into
mainfrom
dev4/364-adherence-contract
Nov 19, 2026
Merged

HugoXK merged 2 commits into
mainfrom
dev4/364-adherence-contract

Conversation

@HugoXK

@HugoXK HugoXK commented Nov 19, 2026 •

Copy link
Copy Markdown
Owner

Written-by: HugoXK
Author: Fledge Platform Dev-4

Part of #364 — slice 1 of three on dev4/364-adherence-contract, tip f2906693.

What this slice is

The job's instruction set — goal, playbook, AGENTS.md and 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 one InstructionContract and instructionContractHash takes 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 is pass, violation, or unverifiable — never pass for something the callback could not observe. The record is violation if any clause is, else unverifiable if any is, else pass, and every clause keeps its own reason even when a stronger status decides the record.
  • A callback whose echoed hash is another contract's, or missing, records hashVerified: false and cannot produce a pass record. null in the observation means "not observed"; [] means "observed, nothing there", and the two are never conflated.

Path matching reuses matchesPath from src/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 tryMerge refusal 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 066a9cc8

test/instructions.test.ts was written first, then the module's exported surface was stubbed with throw new Error('not implemented') so the red would be an assertion-class failure rather than a missing module:

not ok 1 - the contract is content-addressed over every instruction it carries
  error: 'not implemented'
… 9 cases, # tests 9 # pass 0 # fail 9

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 locale

The finding is right, and it broke the one promise the module makes. contextFiles was sorted with left.path.localeCompare(right.path), which sorts by the collation of the locale Node started in, and paths.allow/paths.deny were 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:

LC_ALL=en_US.UTF-8 0c781dcfb0813111fbf00a721079359142ad1bf37f0c2add5c3e3788cdf2302b
LC_ALL=zh_CN.UTF-8 ab0c1ab2dd8c9451735a7fde3e079dbe53b55c0e72fc4229885fa676ebb61b66

The fix, in src/lib/instructions.ts:

  • byCodeUnit compares with </>, so the order is UTF-16 code unit order and localeCompare is gone from the module.
  • canonicalSet de-duplicates and sorts the lists the contract treats as sets — paths.allow, paths.deny, required.evidence, required.sections, forbidden — before they are hashed. carryOver stays in its recorded order, because it is a sequence of earlier turns and its order is meaning.
  • contextFiles sorts 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 under en_US.UTF-8 and zh_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 9e57ee6 with the new case only, source from that tip:

not ok 2 - the same instruction set hashes the same under another locale and another input order
  error: |-
    the order a caller reads a set in is not part of the contract
    + 'e2b7e498b0278dbdeeb9ec2d015e612ee6525c81d5cab9243a64e4c6f4ff8093'
    - '93f1efb5f8f1bffdb7dce4aefd8da4c59a82b509a9219c985081cc3a3a99a790'
# tests 10 # pass 9 # fail 1

Green at f2906693: # tests 10 # pass 10 # fail 0, and the two locales agree.

docs/architecture.md now says what canonicalisation the hash rests on, beside the sentence it made false.

Docs

docs/architecture.md gains the paragraph beside the #433 strategy 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 check at 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.ts at this tip — pass, # tests 10 # pass 10 # fail 0.
  • At 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 by node --import tsx -e under LC_ALL=en_US.UTF-8 and LC_ALL=zh_CN.UTF-8 — 0c781dcf…302b and ab0c1ab2…1b66.
  • npm run mock:check — mock-snapshot: ok (14 files); this slice has no UI surface, so no mock/ file changed.
  • npm run test:coverage then node 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-lint itself is not runnable here (it requires GITHUB_TOKEN and 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 over 9e57ee6.
  • The module is pure and unreferenced by any route or job path in this slice, so the running platform cannot change behaviour. Reverting the commit removes it entirely.
  • The hash the fix produces differs from the broken one. Nothing has stored a contract hash yet — slice 2 is what writes it — so no record is invalidated by the change; if anything had, a hash is a value to recompute from the input, not a migration.
  • Residual: the clause set is the one this card enumerates. A clause the runner cannot report is unverifiable by construction, so the first real runs under slice 2 will likely be unverifiable rather than pass — that is the intended reading, not a bug to tune away.

…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 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 f290669
Written-by: HugoXK-bot
Author: Fledge Platform Verdict

  • The locale dependency is gone, not papered over: byCodeUnit (src/lib/instructions.ts:25-27) replaces localeCompare, canonicalSet de-duplicates and sorts every set-like list before hashing (:30-32, applied :101-104), contextFiles sorts by (path, sha) (:95-97), and carryOver keeps 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…fee9 under LC_ALL=en_US.UTF-8, zh_CN.UTF-8 and C, with the canonical order README.md, src/z.ts, src/上海.ts, src/北京.ts — the order the body pins.
  • Clause evaluation keeps "not observed" out of "clean": null and [] never collapse (:116-119, :145-167), an echoed hash that is missing or another contract's records hashVerified: false and cannot produce pass (:125-135), and the record takes the strongest clause while keeping each clause's own reason (:208-213).
  • Path matching reuses matchesPath from src/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, canonicalJson and matchesPath are 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 pass
  • npm run typecheck — clean
  • compiled the same input under LC_ALL=en_US.UTF-8, zh_CN.UTF-8 and C with npx tsx — one hash 088aaf9f…fee9 in all three
    Not run: a real dispatched job carrying this contract (slice 2), the Docker image, a real FlyBot run. No UI face (no src/views/ or public/ change), so no before/after frames and npm run mock:check was not needed.

@HugoXK
HugoXK merged commit 186e71d into main Nov 19, 2026
36 of 37 checks passed
@HugoXK
HugoXK deleted the dev4/364-adherence-contract branch November 19, 2026 15:04
)

`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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants