feat(interface): construct complete profile diffs

[drewstone]

Outcome

Adds the canonical exported diffAgentProfiles(baseline, candidate) constructor using the existing AgentProfileDiff contract. It covers every AgentProfile and AgentProfileResources field, emits ordered reset/set steps for exact replacement, returns no steps for canonical no-ops, and produces detached deterministic output. No candidate or container type was added.

The existing profile canonicalizer moved unchanged into an internal shared module so profile identity and profile diffs agree on undefined open-record entries.

This should merge before #98 so the pending Interface 0.39 release includes the source primitive instead of forcing Runtime to retain a local copy.

Proof

• 0/1,521 reconstruction mismatches across the schema-valid transition matrix
• 236/236 agent-interface tests
• 682/682 workspace tests
• all workspace typechecks
• all workspace builds
• 8 isolated packages, 18 exports, and 36 export targets checked
• built root export smoke-tested
• git diff --check clean

[tangletools]

✅ Auto-approved drewstone PR — 494c9ee4

This PR was opened by the trusted drewstone account.
The full PR reviewer audit still runs separately and will publish findings if it detects issues.

_{tangletools · auto-approval · reason: drewstone_author · 2026-07-29T21:47:59Z}

[tangletools]

🟢 Value Audit — sound

Verdict	sound
Concerns	0 (none)
Heuristic	0.0s
Duplication	0.0s
Interrogation	87.3s (2 bridge agents)
Total	87.3s

💰 Value — sound

Adds diffAgentProfiles, the inverse constructor for the existing apply primitive, by extracting a shared profile canonicalizer so identity and diffs agree; coherent, on-grain, no existing equivalent to reuse.

• What it does: Adds a canonical exported diffAgentProfiles(baseline, candidate) in packages/agent-interface/src/profile-diff.ts:139 that returns ordered AgentProfileDiff[] steps (a reset diff, then a set diff) which reproduce candidate exactly when applied via the existing applyAgentProfileDiff. It compares values through canonical RFC-8785 JSON so reordered object keys and undefined open-record entries are no-o
• Goals it achieves: Close the apply/diff round-trip: the package already had applyAgentProfileDiff (forward apply) and the AgentProfileDiff contract/schema, but no constructor. This gives optimizers/improvement loops a deterministic way to materialize the exact diff between two profiles as portable improvement artifacts (the package's stated purpose per agent-profile.ts:1-13 and the improvement schema consuming Agent
• Assessment: Good change on its merits. It reuses the existing AgentProfileDiff contract, schema (verified in tests via agentProfileDiffSchema.parse), and merge semantics rather than inventing a new diff type — the body's 'no candidate or container type added' claim holds (diff touches only 4 files, no new schema/type). The reset-then-set two-step emission is not arbitrary: applyAgentProfileDiff (profile-diff.
• Better / existing approach: none — this is the right approach. Searched the whole workspace (grep for diffAgentProfiles|diffProfile|deriveDiff|buildDiff|profileDiff across packages/, excluding agent-interface) and found no existing diff constructor anywhere — the only AgentProfileDiff consumers are the improvement schema (changedAgentProfileAxes + type import) and lineage id-arrays, none of which construct diffs. The canonic
• Model: opencode/zai-coding-plan/glm-5.2
• Bridge attempts: 2
• Bridge warning: opencode/kimi-for-coding/k2p7: bridge stream ended without value-audit content

🎯 Usefulness — sound

Adds the canonical inverse constructor for the already-shipped AgentProfileDiff contract, exported on the public surface and consumed internally by the improvement-experiment types; ships ahead of its imminent Runtime caller (#98) as intended.

• Assessment: This is a source primitive, not dead surface: it constructs the exact artifact the improvement-experiment contract persists and activates, and it removes the need for Runtime (#98) to keep a local copy. It is the canonical inverse of an established, schema-validated contract, reuses the existing canonicalization, and is exported on the public root. No existing equivalent and no materially better a
• Integration: Reachable and correctly wired. diffAgentProfiles is exported via the package root at packages/agent-interface/src/index.ts:852 (export * from "./profile-diff.js"), so it lands on the public @tangle-network/agent-interface surface alongside the rest of the diff family. The AgentProfileDiff contract it targets is already heavily consumed inside the package: agent-profile-improvement.ts:79 define
• Fit with existing patterns: Fits the codebase grain precisely. profile-diff.ts already shipped applyAgentProfileDiff (the forward direction), plus changedAgentProfileAxes, pruneAgentProfileDiff, defineAgentProfileDiff, and a zod schema in profile-schema.ts:427. diffAgentProfiles is the obvious missing inverse — (baseline, candidate) => AgentProfileDiff[] whose output round-trips through the existing apply. Rather than rein
• Real-world viability: Holds up beyond the happy path. The implementation is deterministic and detached: candidate values are round-tripped through canonical JSON (canonicalProfileValue at profile-diff.ts:242) so mutation of the input after the call cannot leak into the emitted diff — explicitly tested at profile-diff.test.ts:302-304. Canonical no-ops return [] (profile-diff.ts:184), and the comparison goes through cano
• Model: opencode/zai-coding-plan/glm-5.2
• Bridge attempts: 1

No concerns — sound change, no better or existing approach found. ✅

---

What this audit checks

It judges the change on its merits — not whether it was tasked out in an issue. Unticketed, fast-moving work is fine; the question is whether the change is good and whether a better or existing approach should be used instead.

Pass	What it asks
Heuristic	Vague title? Whitespace-only or cruft-bearing diff? (content signals only)
Duplication	Do added function/class names already exist elsewhere in the repo?
Value Audit	What does it do? What goal does it achieve? Is it good? Better architecture or already-exists?
Usefulness Audit	Does it integrate and fit? Will it hold up in real use and actually get used?

Findings are concerns, not blocks — the human reviewer decides what to do with them.

_{value-audit · 20260729T214941Z}