Skip to content

FORKING_PATH.md

Latest commit

 

History

History
79 lines (58 loc) · 3.5 KB

FORKING_PATH.md

File metadata and controls

79 lines (58 loc) · 3.5 KB

Forking Path: From Visibility Tool to Control System

This upstream project is a visibility tool only:

  • It will not ship enforcement.
  • It will not block CI/CD.
  • It will not integrate IAM/RBAC/signing.
  • It will provide stable extension hooks so forks can add those.

Stable Extension Hooks (First‑Class Interfaces)

Upstream ships interface contracts + no‑op defaults:

  • ActorResolver: map actor_claim → external identity (IAM in fork)
  • ProvenanceProvider: callsite fingerprints (stack hash, signed provenance)
  • SinkPolicy: sink scanning (regex → AST in forks)
  • GatePolicy: gating logic (fork blocks CI on critical obligations)
  • LedgerBackend: obligation lifecycle (tickets/workflow in forks)

Ring Profiles (Visibility Only Upstream)

  • Ring 0: heuristic regex scan only
  • Higher rings (AST enforcement, wrapper tokens, CI gates) belong to forks

Fork Recipe (1 Paragraph)

Fork this repo and implement: GatePolicy + SinkPolicy(AST) + IO wrappers with capability tokens + ActorResolver(IAM) + LedgerBackend(ticketing). Then configure CI to block on UNASSESSABLE or critical open obligations.

Why This Boundary Exists

Upstream is intentionally non‑enforcing to avoid false confidence and governance theater. Control features are explicitly out of scope here.

Optional Improvements (Tradeoff‑Sensitive)

These stay within the visibility‑first philosophy but increase rigor and cost. Consider in forks:

  • Instrumentation honesty hardening

    • Golden transcripts for error paths (not just happy path).
    • Negative tests: “no execute without authority_check”.
    • CI sink scans to catch un‑instrumented writes.
    • Tradeoff: higher test maintenance and brittleness.

  • Coverage enforcement

    • Fail builds if any AnchorSpec has zero observed events across suites.
    • Tradeoff: requires broader fixtures; may be noisy early on.

  • Correlation‑scoped assessment

    • Group events by correlation_id before ordering checks to avoid interleaving false positives.
    • Tradeoff: more complex assessment logic; may hide cross‑flow ordering bugs.

  • Order‑matching flexibility

    • Allow repeated anchor sequences or subsequence ordering for loops.
    • Tradeoff: weaker detection of extra/unexpected events.

  • Transcript tightening

    • Require location_id and/or correlation_id in transcript matchers for systems.
    • Tradeoff: more verbose transcripts; more test setup plumbing.

Retrofit‑Oriented Fork Ideas

These focus on making brownfield adoption less painful while preserving visibility‑only scope:

  • Anchor helpers / decorators

    • Provide @anchor_input, @anchor_commit, @anchor_summary helpers that emit events consistently.
    • Tradeoff: adds framework‑specific API surface.

  • Auto‑instrumented wrappers

    • Offer drop‑in wrappers for common sinks (file writes, DB writes, HTTP calls) that emit events by default.
    • Tradeoff: requires code touchpoints and standardization.

  • AST‑based sink scanning

    • Replace regex scan with AST detection to reduce false positives and find more bypasses.
    • Tradeoff: more complexity, language‑specific.

  • Correlation‑scoped assessment

    • Group events by correlation_id before ordering checks to reduce interleaving noise.
    • Tradeoff: may miss cross‑flow ordering issues.

  • Transcript capture tooling

    • Provide utilities to record observed events and generate draft transcripts/Plan stubs.
    • Tradeoff: tooling maintenance, still requires human review.