Skip to content

Safety Model

Current authority

optiflow v0.1.x has read authority only. It can create state and report artifacts in its configured state directory, but it cannot change source media.

Invariants

  • Scanning never mutates source files.
  • Accepted content, identity, and allocation evidence comes from one opened read-only handle and one stable path-observation window.
  • An unstable attempt is discarded as a unit; evidence is never combined across bounded retries.
  • Detection and resolution remain separate phases.
  • Equal duration, dimensions, filenames, or partial fingerprints never prove exact identity.
  • An exact group requires identical byte length and complete BLAKE3-256 hash.
  • A plan is immutable evidence, not permission to execute.
  • A media-profile opportunity is review evidence, not an output, executable plan action, or promise of physical savings.
  • Missing, stale, partial, contradictory, unavailable, or semantically invalid media evidence never produces an opportunity.
  • New related artifacts are consumable only as a committed, digest-verified artifact set; incomplete and incompatible sets fail closed.
  • Configuration cannot enable mutation, apply behavior, shell execution, validation bypasses, non-atomic artifact commits, or acceptance of unstable evidence as exact.
  • The deterministic keep_path is not a quality score.
  • Perceptual or containment matches will default to review in future releases.
  • RAW files, paired assets, Live Photos, and generated pipeline masters may be inventoried but receive no special destructive policy.

Future apply gate

Before any later release can mutate a duplicate candidate, it must:

  1. Require an explicit apply command and approved plan identifier.
  2. Verify the plan schema and source-run identity.
  3. Re-stat every path and reject changed size or modification time.
  4. Recalculate every complete content hash.
  5. Compare candidate bytes directly with the selected retained file.
  6. Check target filesystem and available space.
  7. Use same-filesystem temporary artifacts where atomic rename matters.
  8. Validate generated outputs before replacing an original.
  9. Record attempts, validation, commits, and failures durably.
  10. Default to recoverable backup or quarantine behavior.

Space-reclamation without backup may eventually exist, but it must be a deliberate policy and never the universal default.

Threats addressed

  • Stale plans after a file changes
  • Incorrect assumptions from filename extensions
  • Symlink traversal outside the intended collection
  • Unexpected mount traversal
  • Hash collision risk before destructive resolution
  • Interrupted report writes
  • Crashes and disk exhaustion between related artifact writes
  • Untrusted configuration, shell expansion, and policy-fingerprint mismatch
  • Optional adapter absence or malformed output
  • Optional provider replacement, timeout, non-zero exit, nominal success with stderr, and nominal success with incomplete semantic observations
  • External-volume and network-filesystem SQLite behavior

Remaining risks

  • Files can change after an accepted read-only observation; a future apply engine must re-open each object and re-prove all preconditions.
  • Modification-time precision varies by filesystem.
  • Portable Unix identity signatures do not provide a universal object generation number, and unusual filesystems may not provide strong enough identity or timestamp semantics. Current evidence is refused when required fields are unavailable.
  • Successful decoding by one tool does not guarantee universal compatibility.
  • Cryptographic hashes provide extremely strong identity evidence but direct byte confirmation remains the final destructive gate.

See the artifact-set commit protocol for staging, commit markers, recovery, and durability boundaries. See the handle-bound observation protocol for the stage checks, cache binding, retry behavior, and filesystem limits. See media-profile evidence for the first profile's exact claim boundary and required future-output validations.

Approved dry-run boundary

Current development source can validate explicitly selected and separately approved execution plans through a non-mutating dry run. The preview changes no source authority. Linux-only bounded quarantine requires an explicit live invocation and a separate v2 mutation journal. Approval binds every selection, root/subtree, policy, location and bound; a review suggestion is never authorization. State/evidence must stay outside protected roots and quarantine. Physical savings stay unknown, and v1 commit evidence cannot claim mutation. After a proven cross-filesystem restore, v4 finalization may permanently remove only explicitly selected retained quarantine copies with a separately reviewed manifest-bound authorization. It never targets the original source and treats a pending removal as irreversible ambiguity.