stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity

save changes

Browse Source
This commit is contained in:
master
2026-02-17 00:51:35 +02:00
parent 70fdbfcf25
commit fb46a927ad
324 changed files with 4976 additions and 1499 deletions
Download Patch File Download Diff File Expand all files Collapse all files

126
docs/implplan/SPRINT_20260216_001_BinaryIndex_hybrid_diff_patch_pipeline.md Normal file
View File

@@ -0,0 +1,126 @@
# Sprint 20260216-001 - Hybrid Diff Patch Pipeline
## Topic & Scope
- Translate advisory guidance into an executable cross-module delivery plan for source-to-binary patch evidence.
- Define deterministic contracts for semantic edit scripts, symbol maps, symbol patch plans, and normalized per-symbol deltas.
- Wire policy and verification expectations so Release Orchestrator can gate on function-level change intent and byte-level proof.
- Working directory: `src/BinaryIndex/`.
- Expected evidence: targeted unit/integration tests, deterministic fixture artifacts, DSSE predicate samples, updated module docs.
## Dependencies & Concurrency
- Depends on existing DeltaSig v2 predicate baseline in `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.DeltaSig/`.
- Safe parallel workstreams:
- source semantic edit artifact generation (`src/Tools/` or `src/ReleaseOrchestrator/` integration)
- symbol map extraction contracts (`src/Symbols/`)
- normalized delta and verifier integration (`src/BinaryIndex/`, `src/Attestor/`, `src/Doctor/`)
- Cross-module edits are explicitly allowed for this sprint in:
- `src/Symbols/`
- `src/EvidenceLocker/`
- `src/Policy/`
- `src/ReleaseOrchestrator/`
- `src/Attestor/`
- `src/Doctor/`
- `src/Web/`
- `docs/modules/**`
## Documentation Prerequisites
- `docs/hybrid-diff-patching.md`
- `docs/modules/binary-index/hybrid-diff-stack.md`
- `docs/modules/binary-index/semantic-diffing.md`
- `docs/modules/binary-index/deltasig-v2-schema.md`
- `docs/modules/evidence-locker/guides/evidence-pack-schema.md`
## Delivery Tracker
### BHP-01 - Source semantic edit script artifact
Status: TODO
Dependency: none
Owners: Developer, Documentation author
Task description:
- Add deterministic source semantic edit artifact generation that emits stable
node identifiers and symbol anchors for changed code elements.
- Integrate artifact emission into release comparison flow and persist into
evidence pipelines.
Completion criteria:
- [ ] A `semantic_edit_script.json` contract is implemented and validated with tests.
- [ ] Artifact generation is deterministic across repeated runs with identical inputs.
- [ ] Documentation for schema and limits is added to module dossier docs.
### BHP-02 - Build symbol map contract and build-id binding
Status: TODO
Dependency: BHP-01
Owners: Developer
Task description:
- Emit canonical `symbol_map.json` with source ranges, symbol boundaries, and
build-id metadata from DWARF/PDB capable pipelines.
- Ensure map digests and build-id values are linked into DeltaSig/attestation
subjects for replay validation.
Completion criteria:
- [ ] Symbol map generation is implemented for supported binary formats in scope.
- [ ] Build-id and map digest are bound in emitted attestation payloads.
- [ ] Tests cover mapping correctness and deterministic ordering.
### BHP-03 - Symbol patch plan and normalized per-symbol delta manifests
Status: TODO
Dependency: BHP-02
Owners: Developer
Task description:
- Join semantic edits and symbol maps into `symbol_patch_plan.json` and
generate normalized per-symbol deltas and `patch_manifest.json` outputs.
- Remove placeholder function address/size derivation in DeltaSig generation
where exact boundaries are required for audit claims.
Completion criteria:
- [ ] Symbol patch plan artifact exists and links to AST anchors and symbol ids.
- [ ] Patch manifest includes pre/post hashes, address ranges, and delta digests.
- [ ] DeltaSig function-level outputs use real boundaries and sizes in covered paths.
### BHP-04 - Verifier and attestation enforcement
Status: TODO
Dependency: BHP-03
Owners: Developer, Test Automation
Task description:
- Add verifier flow for build-id matching, re-normalization checks, dry-run delta
application, and boundary/hash reconciliation.
- Extend attestation validation logic in Attestor/Doctor and produce actionable
verification evidence for release decisions.
Completion criteria:
- [ ] Verifier checks fail closed on build-id mismatch, boundary mismatch, or hash mismatch.
- [ ] DSSE validation and replay checks are captured in test evidence.
- [ ] CLI/API surfaces expose verification outcome details for operators.
### BHP-05 - Policy and Evidence Locker integration
Status: TODO
Dependency: BHP-04
Owners: Developer, Product Manager
Task description:
- Add policy gate inputs for symbol-count change budgets, namespace restrictions,
API-surface invariants, and byte budget thresholds.
- Store hybrid diff artifacts in Evidence Locker and expose summary/read paths in
UI and release records.
Completion criteria:
- [ ] Policy rules can gate promotions using hybrid diff metrics.
- [ ] Evidence Locker stores and retrieves the full hybrid artifact chain.
- [ ] UI/CLI render concise "what changed" summaries with links to signed evidence.
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2026-02-16 | Sprint created from product advisory review for hybrid source-symbol-binary diff pipeline. | Product Manager |
## Decisions & Risks
- Advisory overlap confirmed with archived advisories:
- `docs-archived/product/advisories/30-Dec-2025 - Binary Diff Signatures for Patch Detection.md`
- `docs-archived/product/advisories/18-Dec-2025 - Building Better Binary Mapping and Call-Stack Reachability.md`
- Decision: treat this advisory as an extension that unifies source intent and binary proof in one contract chain, not as a duplicate effort.
- Risk: multi-module coordination can drift schemas; mitigation is to keep canonical contracts in BinaryIndex dossier and require digest-linked schema versions in attestations.
- Risk: AST differencing backend choice may vary by language; mitigation is a language-agnostic output schema with adapter-specific provenance fields.
## Next Checkpoints
- 2026-02-18: Contract freeze review for artifact schemas (`semantic_edit_script`, `symbol_map`, `symbol_patch_plan`, `patch_manifest`).
- 2026-02-22: First end-to-end dry run in CI with signed evidence and verifier replay.
- 2026-02-26: Policy gate integration demo with allow/deny examples on symbol namespaces.

102
docs/implplan/SPRINT_20260216_001_Signals_ebpf_micro_witness_determinism_profile.md Normal file
View File

@@ -0,0 +1,102 @@
# Sprint SPRINT_20260216_001_Signals_ebpf_micro_witness_determinism_profile - eBPF Micro-Witness Determinism
## Topic & Scope
- Translate the eBPF micro-witness advisory into implementation-ready contracts and sprint tasks.
- Close determinism gaps for runtime witness replay across kernel/distro/toolchain variance.
- Define one portable evidence profile for DSSE + Sigstore bundle based offline replay.
- Working directory: `docs/`.
- Cross-module edits explicitly allowed for implementation tasks: `src/Signals/`, `src/Scanner/`, `src/Attestor/`, `src/EvidenceLocker/`.
- Expected evidence: contract docs, schema/API updates, targeted module tests, offline verification artifacts.
## Dependencies & Concurrency
- Upstream contracts: `docs/contracts/witness-v1.md`, `docs/modules/attestor/repro-bundle-profile.md`, `docs/modules/evidence/unified-model.md`.
- Safe parallelism:
- Signals loader/BTF work can run in parallel with Attestor/Evidence Locker bundle contract work.
- Scanner witness model updates should run after profile fields are frozen.
## Documentation Prerequisites
- `docs/product/ebpf-micro-witness-determinism.md`
- `docs/modules/signals/contracts/ebpf-micro-witness-determinism-profile.md`
- `docs/reachability/deployment-guide.md`
- `docs/contracts/witness-v1.md`
## Delivery Tracker
### MWD-001 - Signals BTF fallback contract and metadata emission
Status: TODO
Dependency: none
Owners: Product Manager, Developer
Task description:
- Implement deterministic BTF selection order in the runtime collector and emit selected source metadata (`source_kind`, `source_path`, `source_digest`, `selection_reason`) into runtime evidence/witness context.
- Ensure behavior is explicit for kernel BTF, external vmlinux BTF, and split-BTF fallback.
Completion criteria:
- [ ] Collector no longer fails solely on missing `/sys/kernel/btf/vmlinux` when configured fallback BTF exists.
- [ ] Runtime evidence includes immutable BTF selection metadata required for replay.
### MWD-002 - Runtime witness schema extensions for deterministic symbolization
Status: TODO
Dependency: MWD-001
Owners: Developer, Documentation author
Task description:
- Extend runtime witness payload schema to include deterministic symbolization tuple: `build_id`, debug/symbol pointer(s), symbolizer identity/version/digest, libc variant, and sysroot digest.
- Update witness contracts and validation rules in docs and implementation.
Completion criteria:
- [ ] Witness schema and code models carry required symbolization fields.
- [ ] Validation rejects witnesses missing required deterministic symbolization inputs.
### MWD-003 - Implement Scanner runtime witness generation pipeline
Status: TODO
Dependency: MWD-002
Owners: Developer, Test Automation
Task description:
- Deliver concrete `IRuntimeWitnessGenerator` implementation, integrating runtime observations, witness building, DSSE signing, and storage.
- Ensure deterministic ordering/canonicalization for runtime observation payloads.
Completion criteria:
- [ ] Runtime witness generation is implemented (not interface-only) and wired into runtime instrumentation flow.
- [ ] Determinism tests show stable witness bytes for fixed inputs.
### MWD-004 - DSSE plus Sigstore bundle witness packaging
Status: TODO
Dependency: MWD-003
Owners: Developer, Documentation author
Task description:
- Standardize and implement per-witness artifact triplet: `trace.json`, `trace.dsse.json`, `trace.sigstore.json`.
- Store and export this profile through Evidence Locker with offline verification compatibility.
Completion criteria:
- [ ] Evidence Locker manifest/index model supports the Sigstore bundle artifact and links it to witness identity.
- [ ] Offline verify workflow succeeds using bundle-contained material only.
### MWD-005 - Cross-distro deterministic replay test matrix
Status: TODO
Dependency: MWD-004
Owners: Test Automation, QA
Task description:
- Add targeted replay verification across kernel/libc matrix (minimum 3 kernels, glibc + musl), asserting byte-identical replay frames for fixed witness artifacts.
- Capture command output and evidence artifacts for deterministic QA sign-off.
Completion criteria:
- [ ] Matrix tests run against targeted projects (not solution filters) and show deterministic replay output.
- [ ] Execution evidence is recorded with artifact hashes and replay verification logs.
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2026-02-16 | Sprint created from eBPF micro-witness advisory review; gaps confirmed and translated to implementation tasks. | Project Manager |
## Decisions & Risks
- Decision: Adopt a single micro-witness determinism profile defined in `docs/modules/signals/contracts/ebpf-micro-witness-determinism-profile.md`.
- Decision: Product-level promise and current baseline are captured in `docs/product/ebpf-micro-witness-determinism.md`.
- Decision: Advisory translation record archived at `docs-archived/product/advisories/16-Feb-2026 - eBPF micro-witness deterministic replay across distros.md`.
- Risk: Existing runtime collector hard dependency on kernel BTF may block non-BTF kernels until fallback path is implemented.
- Risk: Runtime witness generation remains incomplete without a concrete generator implementation; downstream attestation/export is blocked.
- Risk: Absence of standardized Sigstore witness bundle may produce non-portable replay evidence across environments.
- External web fetches: none.
## Next Checkpoints
- 2026-02-18: Contract review sign-off (Signals/Scanner/Attestor/Evidence Locker owners).
- 2026-02-21: MWD-001 and MWD-002 implementation readiness checkpoint.
- 2026-02-25: First end-to-end deterministic replay demo with DSSE + Sigstore witness bundle.