feat: enforce canonical pair ordering, and commit the first commit-history artifact (META-297 L1)

[qmarcelle]

Two logical increments, committed separately.

1. 850a4d4 — conformance suite enforces canonical pair ordering

docs/conformance.md said canonical pair ordering was enforced by the candidate-producer conformance suite. The suite examined coChange[].files not at all, so a producer emitting reversed endpoints passed a gate that advertised the check. Found by review on #26. The gate was added rather than the claim softened.

Three producer-scoped checks:

• every emitted observation-form pair ordered by ascending UTF-8 bytes — a real byte comparison, since < is UTF-16 code unit order and the two disagree on supplementary-plane characters;
• every emitted entry carries a two-string files pair;
• no emitted entry stores a derived rate.

The well-formedness check is separate on purpose, and that came out of review on this PR: an earlier version folded it into the ordering filter, so an entry whose files was not a two-string array could never be counted as misordered and silently passed. A structurally invalid observation was buying itself an exemption from the rule it could not be evaluated against.

Readers are untouched: pairs stay unordered with set semantics, reversed documents stay valid, joins are by membership.

A candidate emitting no observation-form entries is recorded NOT MEASURED, counted separately from passes — a property that could not be exercised has not been demonstrated.

Watched-red: injecting a candidate output with a one-element files array plus a reversed pair fails both checks — 29 passed / 2 failed of 31. Reverting returns 28 passed, 0 failed, 1 not measured.

2. 49ae90d — the first artifact carrying commit-history evidence

The first workspace.json in this lineage whose generated.coChange came from reading the commit graph.

Candidate interoperability, not published-package interoperability. Published spec@0.4.4/rules@0.4.4 reject it — their schema predates A-009. Produced and validated against candidates packed from pinned revisions.

Producer	workspacejson/cli @ 031c3504a0977b8d90ac518c82a39a2f4ec741a9 — merged to main (PR #20)
Evidence basis	workspacejson/standard @ 8e08c8c5cd110e7f95bbd52246ea295c22b072e3
spec tarball	sha256:2e0c326e7d8b50d3e3fa801944659803cd95d13dc253e65e1ace8dfccf949111
rules tarball	sha256:548dd788725899ccaded6568121a271eeb593f143c581ec7e4714b50d9e5dbb7
cli tarball	sha256:aa0ab7526a8f8fc6316f8b809d2ee5cdd04c80c5483a29d39e8dfbcc2e15ad18

Packed from clean detached worktrees, so build inputs are exactly the committed source. Tarball digests are pack-specific (gzip carries mtimes) and are recorded as such rather than as reproducible hashes; the durable identity is the two source revisions.

The producer was refreshed; the evidence basis was not

An earlier build used producer 44d374b, which carried a Greptile P1: an explicitly requested refresh that could not complete fell back to the recorded block silently. Fixed in 031c350 and merged; the artifact was regenerated with the corrected producer against the same 8e08c8c basis.

Refreshing the evidence to a newer standard revision was deliberately not done. basisRevision means "these observations were computed from this revision" — advancing it because main moved would claim a measurement never taken. A pin that lags main reads as stale, which is accurate.

This doubles as a perturbation test. The fix changes only refusal signalling on the unsuccessful path, so the successful path must produce identical output:

	Before (44d374b)	After (031c350)
basisRevision	8e08c8c…	unchanged
History-block sha256	7012352617df…	unchanged
coChange	50 entries	50, byte-identical
Moved	—	generatedAt, hygiene.scannedAt only

Had the block moved, this receipt would not have been written.

The artifact

No registry substitution: every @workspacejson entry resolves file:, zero registry URLs, one spec copy. Version strings could not distinguish candidate from registry, so the suite asserts the installed schema's shape, including that the validator the producer calls accepts the observation form.

History completeness: not shallow; 90 first-parent transitions against a 500 window, so the window did not bind — full first-parent history.

basisRevision	8e08c8c5cd110e7f95bbd52246ea295c22b072e3
Entries	50 (threshold support >= 3, ranked, capped; min emitted 4)
Validation	valid, 0 errors
History-block sha256	7012352617df37f442a627b8dfc334ed17d63dd2a69bb2d875f759bfddcc7b4f

The block digest is the receipt that matters — the whole-file digest includes generatedAt, which records the generation run, not the evidence.

All 50 entries carry exactly files/occurrences/support: no derived value, no generated flag (no deterministic classifier exists; A-010 defines absence as unclassified), canonical UTF-8 order, support <= occurrences.

The second-ranked pair is packages/spec/schema/v1.json and packages/spec/src/schema.ts — the two schema mirrors. There is no import edge between them. The measured claim is the counts: of the 11 qualifying commits touching either file, 10 touched both. Whether that generalises beyond this repository is not established here.

.agents/RECEIPT.md carries the full provenance and standing limits.

Verification

Suite	Result
Candidate-contract, from merged producer 031c350	22/22
Standard	spec 264/264, rules 173/173
Examples	11/11 positive, 12/12 negative
Conformance	28 passed, 0 failed, 1 not measured
Other gates	typecheck, build, architecture, schema, corpus, docs, adr, packed — all green

Watched-red against pinned candidates (rebuilt, repacked, clean-installed each time): drop carry-forward 7 failed; advance pin 6 failed; recompute on ordinary generate 1 failed; drop refresh-outcome field 2 failed; hardcode mined: true 1 failed; restored 22/22.

Boundaries

No publication. No outreach. The artifact authorizes neither, and RECEIPT.md records that limit.

Summary by Sourcery

Enforce canonical ordering and structural validation of co-change pairs in the producer conformance suite and add the first commit-history based workspace artifact with a detailed provenance receipt.

New Features:

• Add producer conformance checks that verify coChange pairs are ordered by ascending UTF-8 bytes, enforce two-string files arrays, and prohibit derived rate fields.
• Introduce explicit NOT MEASURED reporting in the producer conformance reporter and CLI output for properties the candidate gives no way to exercise.
• Add a committed .agents/workspace.json artifact carrying mined commit-history co-change evidence for this repository.
• Add .agents/RECEIPT.md documenting the provenance, constraints, and verification results for the new commit-history artifact.

Enhancements:

• Update conformance documentation to accurately reflect that canonical pair ordering and rate prohibition are now enforced by this repository's producer conformance suite rather than out-of-scope.

[sourcery-ai]

Reviewer's Guide

This PR tightens the producer conformance suite to actually enforce canonical coChange pair ordering and distinguish unmeasured properties, and introduces the first .agents/workspace.json artifact plus a detailed provenance receipt documenting commit-history based co-change evidence.

Sequence diagram for canonical coChange pair ordering check

sequenceDiagram
  participant Candidate
  participant ConformanceScript as check_producer_conformance_mjs
  participant Reporter as createReporter_check

  Candidate->>ConformanceScript: runDirect(candidate, repo)
  ConformanceScript->>Reporter: createReporter()
  ConformanceScript->>ConformanceScript: extract coChange
  ConformanceScript->>ConformanceScript: filter observationEntries
  alt no observation entries
    ConformanceScript->>Reporter: check.notMeasured("canonical pair ordering ...")
  else has observation entries
    ConformanceScript->>ConformanceScript: compareUtf8(a, b)
    ConformanceScript->>Reporter: check("every emitted coChange entry carries a two-string files pair", malformed.length === 0, detail)
    ConformanceScript->>Reporter: check("every emitted coChange pair is ordered by ascending UTF-8 bytes", misordered.length === 0, detail)
    ConformanceScript->>Reporter: check("no emitted coChange entry stores a derived rate", observationEntries.every(...), detail)
  end
  ConformanceScript->>ConformanceScript: summarize state.pass, state.fail, state.notMeasured
  ConformanceScript-->>Candidate: exit(status = state.fail ? 1 : 0)

Loading

File-Level Changes

Change	Details	Files
Enforce canonical UTF-8-ordered coChange pairs and treat missing observation-form entries as a separately reported, unmeasured property in the producer conformance suite.	Filter generated coChange entries down to observation-form entries (those with support) for ordering checks. Introduce a UTF-8 byte-based comparator to determine canonical ordering of coChange file pairs instead of relying on string <. Add a well-formedness check that requires each observation entry to have a two-element string files array and fail malformed entries explicitly. Add a check that all observation entries are ordered by ascending UTF-8 bytes and report reversed pairs as failures with examples. Add a check that no coChange entry includes a derived rate field, enforcing support + occurrences-only output. Treat candidates that emit no observation-form entries as NOT MEASURED via a dedicated reporter channel rather than counting them as passes. Update the conformance runner output to print NOT MEASURED items separately from passed/failed checks.	scripts/check-producer-conformance.mjs scripts/producer-conformance-lib.mjs
Align documentation with the new enforcement behavior and describe NOT MEASURED semantics for canonical pair ordering.	Clarify that canonical pair ordering and absence of derived rate are now enforced by this repository’s candidate-producer conformance suite, not just specified elsewhere. Explain the UTF-8 byte ordering requirement and why UTF-16 string comparison is insufficient for supplementary-plane characters. Document that candidates with no observation-form entries are reported as NOT MEASURED and not counted as passes to avoid green gates that measured nothing.	docs/conformance.md
Introduce the first commit-history-based co-change artifact and a detailed provenance receipt describing producer identity, evidence basis, history completeness, shape constraints, and verification limits.	Add .agents/workspace.json carrying generated.coChange derived from commit history rather than working-tree scans, with entries constrained to files/occurrences/support and canonical ordering. Add .agents/RECEIPT.md that documents the producer revision, evidence basis revision, packed candidate tarball digests, absence of registry substitution, history completeness, and the authoritative history-block sha256. Record the perturbation test comparing output before and after the producer refresh to ensure the refusal-signal fix does not alter successful mining output. Describe verification results across candidate-contract, producer-native, standard, and conformance suites, including watched-red experiments and the single NOT MEASURED ordering check. State explicit standing limits: no publication or external outreach is authorized by this artifact, and reproduction currently requires the named source revisions rather than registry packages.	.agents/workspace.json .agents/RECEIPT.md

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[qmarcelle]

@greptileai

[greptile-apps]

Greptile Summary

The PR adds executable producer-conformance checks for observation-form co-change pairs and commits the first history-derived workspace artifact with a detailed provenance receipt.

• Checks two-string pair shape, canonical UTF-8 byte ordering, and absence of derived rates.
• Reports unexercised ordering separately as NOT MEASURED.
• Adds a pinned co-change artifact containing 50 commit-history observations and documents its candidate-build provenance and limitations.

Confidence Score: 5/5

The PR appears safe to merge because no blocking failure remains.

No blocking failure remains.

Important Files Changed

Filename	Overview
scripts/check-producer-conformance.mjs	Adds producer-scoped structural, canonical ordering, and no-derived-rate checks while reporting absent observation evidence separately.
scripts/producer-conformance-lib.mjs	Extends the reporter with a distinct notMeasured collection without changing failure accounting.
docs/conformance.md	Updates the documented enforcement boundary to match the new executable producer checks.
.agents/workspace.json	Adds a schema-valid, pinned history-derived artifact containing observation-form co-change evidence.
.agents/RECEIPT.md	Documents artifact provenance, candidate-package limitations, verification results, and standing usage boundaries.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Run candidate producer] --> B[Read generated coChange]
  B --> C{Observation entries present?}
  C -- No --> D[Record NOT MEASURED]
  C -- Yes --> E[Check two-string files pairs]
  E --> F[Check ascending UTF-8 byte order]
  F --> G[Check derived rate is absent]
  D --> H[Report pass, fail, and not-measured totals]
  G --> H

Loading

_{Reviews (4): Last reviewed commit: "feat(evidence): commit the first artifac..." | Re-trigger Greptile}

[qmarcelle]

@sourcery-ai review

[sourcery-ai]

Hey - I've found 1 issue, and left some high level feedback:

• In the canonical pair ordering check, consider explicitly handling coChange entries whose files is not an array of length 2 (e.g., by asserting or reporting them as malformed) so that structurally invalid observations cannot silently bypass ordering validation.
• The UTF-8 comparison helper currently round-trips through TextEncoder and Buffer.from; you could simplify and reduce allocations by using a direct encoding/compare approach (for example, Buffer.compare(Buffer.from(a, 'utf8'), Buffer.from(b, 'utf8'))) and, if reused later, factoring it into a small utility.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- In the canonical pair ordering check, consider explicitly handling coChange entries whose `files` is not an array of length 2 (e.g., by asserting or reporting them as malformed) so that structurally invalid observations cannot silently bypass ordering validation.
- The UTF-8 comparison helper currently round-trips through `TextEncoder` and `Buffer.from`; you could simplify and reduce allocations by using a direct encoding/compare approach (for example, `Buffer.compare(Buffer.from(a, 'utf8'), Buffer.from(b, 'utf8'))`) and, if reused later, factoring it into a small utility.

## Individual Comments

### Comment 1
<location path=".agents/RECEIPT.md" line_range="131" />
<code_context>
+| Standard examples | 11/11 positive, 12/12 negative |
+| Producer conformance | 28 passed, 0 failed, **1 not measured** |
+
+Watched-red against the pinned candidates, each mutation rebuilt, repacked and
+clean-installed before measurement:
+
</code_context>
<issue_to_address>
**suggestion (typo):** The phrase "Watched-red" looks like a typo or unclear jargon.

This wording is likely confusing; “Watched-red” isn’t a standard term and looks like a typo. If it’s intentional jargon, please rephrase to a clearer description (e.g., “observed as failing against the pinned candidates”) so the behavior under test is immediately understandable.

Suggested implementation:

```
Observed as failing against the pinned candidates; each mutation was rebuilt, repacked, and
clean-installed before measurement:

```

If there is any surrounding explanation that relies on the term "Watched-red" (e.g., earlier definitions or references to "watching red/green"), those should be updated to use the clearer wording ("observed as failing" or similar) for consistency. Also verify line wrapping in the Markdown file so the sentence reads naturally in rendered form—adjust where the line break occurs if needed.
</issue_to_address>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[qmarcelle]

Reviewer findings reconciled — head da891fc

Handled individually per .github/REVIEW-MERGE-PROTOCOL.md step 4. No bulk resolution was used.

Sourcery — substantive: malformed files could bypass ordering validation

Fixed. This was a real gap and worth stating precisely: the well-formedness test was folded into the ordering filter, so an entry whose files was not a two-string array could never be counted as misordered and silently passed the ordering check. A structurally invalid observation was buying itself an exemption from the rule it could not be evaluated against — the same "green gate that measured nothing" failure the NOT MEASURED channel exists to prevent, arriving one level down.

Malformed entries are now failed, not skipped, by a separate check:

every emitted coChange entry carries a two-string files pair

Watched-red: injecting a candidate output carrying a one-element files array plus a reversed pair fails both checks — 29 passed / 2 failed of 31. Reverting returns 28 passed, 0 failed, 1 not measured.

Sourcery — advisory: simplify the UTF-8 comparison

Applied. Buffer.from(a, 'utf8') replaces the TextEncoder round-trip. Equivalent bytes, fewer allocations, less to read. The comparison is still a byte comparison rather than <, which is the property that matters — a bare string comparison is UTF-16 code unit order and the two disagree on supplementary-plane characters.

Sourcery — cosmetic: "Watched-red" reads as jargon

Term kept, definition added. It is established vocabulary in this project's governance records, so replacing it would break continuity with the rulings and commit messages that use it — but a public receipt should not assume the reader knows it. It is now defined at first use in .agents/RECEIPT.md.

Greptile

Completed on the previous head at 5/5, "safe to merge, no blocking failure remains", zero review threads. Re-running against da891fc.

Both fixes were folded into their originating commits by autosquash rather than appended as a third commit, so the branch remains the two logical increments it was landed as.

[qmarcelle]

@sourcery-ai review

[sourcery-ai]

Hey - I've reviewed your changes and they look great!

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[qmarcelle]

@sourcery-ai review

[sourcery-ai]

Hey - I've left some high level feedback:

• The UTF-8 ordering check currently allocates new Buffers for every comparison; if this starts touching larger datasets, consider extracting a reusable helper or using a more efficient comparison strategy to avoid repeated allocations on hot paths.
• The new check.notMeasured reporting path is only surfaced in the producer suite; if other callers construct reporters, make sure they are updated to use the new API or explicitly ignore notMeasured to avoid inconsistent result handling.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- The UTF-8 ordering check currently allocates new Buffers for every comparison; if this starts touching larger datasets, consider extracting a reusable helper or using a more efficient comparison strategy to avoid repeated allocations on hot paths.
- The new `check.notMeasured` reporting path is only surfaced in the producer suite; if other callers construct reporters, make sure they are updated to use the new API or explicitly ignore `notMeasured` to avoid inconsistent result handling.

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[qmarcelle]

Sourcery findings dispositioned — head 49ae90d

Both advisory, both declined with reasons rather than silently.

1. Buffer allocation in the UTF-8 comparison. Declined. The comparison runs over a candidate's emitted coChange, which is capped at 50 entries by the producer's own selection rule — so this is at most 50 comparisons per conformance run, not a hot path. Extracting a helper or hand-rolling a byte comparison would trade a correct, obvious three-line function for an optimisation with no measured cost behind it. If a future producer profile raises the cap materially, this is worth revisiting; today it would be speculative.

2. check.notMeasured visibility to other reporter callers. Verified rather than assumed: createReporter has exactly one caller in this repository, scripts/check-producer-conformance.mjs, and notMeasured is additive — existing check(...) calls and the state.pass/state.fail counters are unchanged, so a caller that never invokes it behaves exactly as before. The one real hazard the note points at is a caller reading state and assuming pass + fail is the whole story; that is why notMeasured is reported on its own line and counted separately rather than folded into either total.

No code change. Both are recorded here rather than resolved in bulk, per .github/REVIEW-MERGE-PROTOCOL.md step 4.

Gate status on 49ae90d

Step	State
1. Required CI on current head	test (20), test (22), Four-path producer conformance — 3/3 SUCCESS
2. Greptile completed on current head	SUCCESS, 5/5 — "no blocking failure remains"
3. Sourcery explicitly requested, tied to head	COMPLETED, review commit=49ae90d
4. Findings individually reconciled	2 of 2 dispositioned; no bulk resolve
5. Conversations resolved	0 unresolved
6. Fresh thread-aware read	done
7. Head satisfies every gate	yes

Proceeding to a normal squash merge. No admin bypass — META-319 removed required code-owner approval, and the point of that change was that a legitimate PR reaches mergeable through CI, current-head Greptile and conversation resolution alone. Carrying the old bootstrap exception forward by habit would defeat it.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.