# Hybrid Diff Stack Architecture (Source -> Symbols -> Normalized Bytes)

> Status: Planned (advisory translation, 2026-02-16)
> Module: BinaryIndex with cross-module contracts (Symbols, EvidenceLocker, Policy, Attestor, ReleaseOrchestrator)

## 1. Objective

Produce compact, auditable patch artifacts that preserve developer intent and
binary truth at the same time:

- Source-level intent: semantic edit scripts anchored to classes/functions.
- Build-level mapping: symbol map linked to immutable build identity.
- Binary-level patching: normalization-first per-symbol deltas.
- Release evidence: DSSE-signed contract consumed by policy and replay.

## 2. Current implementation baseline

Implemented today:

- ELF normalization passes and deterministic delta hash generation.
- DeltaSig predicate contracts (v1 and v2) with CLI author/sign/verify flows.
- Symbol manifest model with debug id, code id, source paths, and line data.

Gaps for full advisory scope:

- No AST semantic edit script artifact pipeline in current release workflow.
- No canonical builder output for source-range to symbol-address map as a
  first-class build artifact contract.
- No end-to-end "source edits -> symbol patch plan -> normalized deltas"
  bundle schema consumed by release policy.
- Existing function delta composition still contains placeholder address/size
  behavior in parts of DeltaSig generation.

## 3. Target contracts

### 3.1 Source semantic edit script (`semantic_edit_script.json`)

Required fields:

- `schemaVersion`
- `sourceTreeDigest`
- `edits[]` where each edit includes:
  - `editType`: `add|remove|move|update|rename`
  - `nodeKind`: `class|method|field|import|statement`
  - `nodePath`: stable language-specific path
  - `anchor`: symbol-like identifier (for example `Namespace.Type.Method`)
  - `pre` and `post` source spans and digests

Determinism rules:

- Stable sort by file path, then node path.
- Stable source digests and normalized paths.

### 3.2 Symbol map (`symbol_map.json`)

Produced during build from DWARF/PDB + build metadata.

Required fields:

- `schemaVersion`
- `buildId`
- `binaryDigest`
- `symbols[]`:
  - `name`
  - `kind` (`function|object|section`)
  - `addressStart` and `addressEnd`
  - `section`
  - `sourceRanges[]` (`file`, `lineStart`, `lineEnd`)

Determinism rules:

- Symbol ordering by address then name.
- Build id must match attestation subject.

### 3.3 Symbol patch plan (`symbol_patch_plan.json`)

Joins source edits with concrete symbols.

Required fields:

- `schemaVersion`
- `buildIdBefore` and `buildIdAfter`
- `editsDigest`
- `symbolMapDigestBefore` and `symbolMapDigestAfter`
- `changes[]`:
  - `symbol`
  - `changeType` (`added|removed|modified|moved`)
  - `astAnchors[]`
  - `preHash` and `postHash`
  - `deltaRef`

### 3.4 Patch manifest (`patch_manifest.json`)

Binds per-symbol normalized deltas to evidence and policy.

Required fields:

- `schemaVersion`
- `buildId`
- `normalizationRecipeId`
- `patches[]`:
  - `symbol`
  - `addressRange`
  - `deltaDigest`
  - `pre` (`size`, `hash`)
  - `post` (`size`, `hash`)
- `attestation` (`predicateType`, `dsseDigest`)

## 4. Evidence and policy integration

EvidenceLocker stores four linked artifacts per release comparison:

1. semantic edit script
2. symbol maps (before/after)
3. symbol patch plan
4. normalized patch manifest + delta blobs

Policy hooks:

- Allowlist/denylist by namespace or symbol path.
- Max function-count and max byte budget controls.
- API surface change checks.
- Hot-path and cryptography namespace protection rules.

## 5. Verifier contract (Attestor/Doctor)

Verifier must prove all of the following before promotion:

- Build-id and subject digest alignment.
- Re-normalization of target binary with matching recipe id.
- Dry-run delta application succeeds within declared symbol boundaries.
- Resulting hashes equal manifest `post` values.
- AST anchors reconcile to changed symbols in symbol patch plan.
- DSSE signatures and transparency references validate per policy.

## 6. Integration boundaries

Builder step (CI): emit symbol map and normalized segments.

ReleaseOrchestrator step: combine source edits, symbol maps, and normalized
bytes into patch plan and manifest.

BinaryIndex/DeltaSig: own normalization and per-symbol diff generation.

Attestor/Doctor: own verification and attestation checks.

EvidenceLocker: own storage schema and query surfaces.

Policy: consume summarized patch-plan metrics and rule evaluations.

## 7. Implementation tracker

Execution is tracked in:

- `docs/implplan/SPRINT_20260216_001_BinaryIndex_hybrid_diff_patch_pipeline.md`

## 8. Related documents

- `docs/hybrid-diff-patching.md`
- `docs/modules/binary-index/semantic-diffing.md`
- `docs/modules/binary-index/deltasig-v2-schema.md`
- `docs/modules/scanner/binary-diff-attestation.md`
- `docs/modules/evidence-locker/guides/evidence-pack-schema.md`