Skip to content

feat(process): publish v0.3 system-evidence bridge - #3

Merged
stacknil merged 10 commits into
mainfrom
stacknil/release-v0.3-system-evidence-adapter
Aug 12, 2026
Merged

feat(process): publish v0.3 system-evidence bridge#3
stacknil merged 10 commits into
mainfrom
stacknil/release-v0.3-system-evidence-adapter

Conversation

@stacknil

@stacknil stacknil commented Aug 9, 2026

Copy link
Copy Markdown
Owner

Summary

  • add a local linux-process-observe adapt path for process_diff.json
  • emit telemetry-lab-compatible JSONL with versioned evidence and adapter contracts
  • add one minimal Ubuntu CI job that tests all four mini-labs sequentially on Python 3.11
  • publish v0.3.0 release materials while keeping the repository at four mini-labs

Design decision

The adapter stays inside linux-process-observe because its source contract is stacknil.system-evidence.v1. It maps process and socket-link diffs into the existing telemetry-lab event boundary and identifies that mapping as stacknil.system-evidence.telemetry.v1. The CI workflow deliberately uses one Ubuntu job, one Python version, and four ordered test steps; cross-repository reproduction remains release evidence rather than a per-PR dependency.

Main risk

Saved snapshot diffs are observation-time evidence, not live occurrence telemetry. Downstream consumers must honor metadata.time_semantics = snapshot_diff_observed_at and must not infer causality, compromise, or authoritative identity from PID, executable, or socket context. The adapter now rejects malformed change shapes and inconsistent process identities instead of silently weakening attribution.

Compatibility impact

Existing process snapshot, socket-link, diff, and report schemas are unchanged. The adapter is additive and preserves telemetry-lab's required timestamp, event_type, source, target, and status fields. Existing mini-lab CLIs are unchanged except for the process lab's additive adapt subcommand. CI adds validation only; it does not add packaging or release automation.

Rollback path

Revert the PR merge commit, or independently revert the adapter and CI commits. Existing snapshot/diff workflows require no data migration and remain usable without the bridge or workflow.

Validation

  • GitHub Actions Ubuntu 22.04 / Python 3.11: 48 passed total (14 auth + 8 socket + 6 permission + 20 process)
  • external clean clone at the final PR head: linux-process-observe 20 passed
  • telemetry-lab v1.2 consumer reproduction: 7 events, 1 window, 2 alerts, plus features, summary, manifest, and plot artifacts
  • adapter metadata: one evidence schema, one adapter contract, and snapshot_diff_observed_at on all 7 events
  • git diff --check and scoped privacy/secret pattern review pass

Release gate

The PR has remained open for more than three days. The final diff review findings were resolved, remote CI is green, and clean-clone plus consumer release evidence is complete. After merge, wait for the main CI run, tag v0.3.0, publish the prepared release note, and freeze feature growth at four mini-labs.

@stacknil

stacknil commented Aug 9, 2026

Copy link
Copy Markdown
Owner Author

Semantic contract follow-up in 5fc4673:

  • Design decision: add metadata.time_semantics = snapshot_diff_observed_at to every adapter record. Keep the required top-level timestamp mapped to the envelope observed_at, because it is the snapshot-comparison observation time.
  • Main risk: downstream window consumers may still read timestamp as an occurrence time. The new metadata and release documentation make that interpretation invalid: a window groups evidence deltas observed in one comparison, not proven system activities that happened together.
  • Compatibility impact: additive metadata only; existing telemetry-lab fields (timestamp, event_type, source, target, status) and event values remain unchanged. The golden JSONL now locks the metadata on all seven records.
  • Rollback path: revert 5fc4673; this removes only the semantic label and documentation, with no persisted-data migration required.

Validation: linux-process-observe 16 passed; auth/socket/permission suites 14/8/6 passed; adapter compatibility test 4 passed. This repository has no CI workflow configured beyond Dependabot, so GitHub reports no checks. Per the report/schema risk policy, keep PR #3 draft until a delayed review confirms the semantic boundary.

@stacknil

Copy link
Copy Markdown
Owner Author

Final delayed diff review completed after the release branch remained open for more than three days.

  • Design decision: keep one Ubuntu/Python 3.11 CI job with four sequential mini-lab steps; keep telemetry-lab cloning out of PR CI.
  • Resolved review findings: bounded CI runtime to 10 minutes, enforced process/socket-link change-shape and identity invariants, corrected CLI output-error attribution, and clarified workflow/artifact boundaries in AGENTS and README.
  • Main risk: snapshot observation time can be mistaken for event occurrence time; every adapted event now carries the locked snapshot_diff_observed_at semantic.
  • Compatibility impact: existing source evidence schemas and existing commands remain unchanged; the adapter and mapping contract are additive.
  • Rollback path: revert the merge commit or the adapter/CI commits independently; no storage or data migration is involved.

Evidence: GitHub CI passed all 48 tests. A separate clean clone passed all 20 process tests and reproduced the telemetry-lab v1.2 consumer path with 7 events, 1 window, 2 alerts, and the expected report artifacts. No unresolved reviewer or bot comments remain.

@stacknil
stacknil marked this pull request as ready for review August 12, 2026 07:37
@stacknil
stacknil merged commit 9f0998e into main Aug 12, 2026
1 check passed
@stacknil
stacknil deleted the stacknil/release-v0.3-system-evidence-adapter branch August 12, 2026 07:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant