Branch main Algo surface difference generation

Algorithm: Surface Difference Generation

Back to Branch Overview

Field	Value
Branch	main
Source	specs/algorithms/surface_difference_generation.pseudo.md
Commit	5b2aac39fcf8
Synced (UTC)	2026-06-21T06:02:23Z

Visual Context

Algorithm pages define deterministic platform-neutral behavior that downstream repos implement behind native adapters.

flowchart LR
  Input["Input contract"] --> Preconditions["Preconditions"]
  Preconditions --> Decision["Deterministic decision"]
  Decision --> Output["Output contract"]
  Decision --> Diagnostic["Diagnostic envelope"]
  Diagnostic --> Audit["Audit chain"]

Loading

Reading Checklist

Question	Where to look
What is deterministic?	Read the pseudocode branch table and preconditions.
What blocks unsafe behavior?	Look for blocked, ambiguous, policy, or precondition paths.
How is the decision reconstructable?	Trace diagnostic and audit requirements.

---

Source Content

Surface Difference Generation

Surface differences are evidence only. They do not classify state, choose recovery, or override semantic projection.

FUNCTION generate_surface_differences(observed, desired) -> List[SurfaceDifference]
  differences = []
  WALK desired and observed by JSON Pointer tokens
  FOR each present/missing/replaced/type-changed node:
    append SurfaceDifference with diagnosticReference
  RETURN differences
END FUNCTION

A surface difference may trigger semantic projection, but semantic projection determines meaning.