Engineering decisions and tradeoffs behind Edge Evidence

Author recollection (owner-supplied; retrospective, not a contemporaneous engineering record). My recollection is that Edge Evidence grew out of the drone project. I wanted a reliable system for transferring and handling its video—the preservation, processing, recovery, and verification responsibilities that became Edge Evidence. The reliability foundation developed into a separate engineering project, while drone detection remained a distinct workload.

Early engineering planning records describe a relationship between the evidence foundation and a separate future drone workload. They do not independently establish my personal motivation or the precise chronology. This recollection does not establish completed end-to-end drone integration, and it does not change the frozen Project 03 findings.

Evidence boundary. Beyond this recollected origin, the technical records establish choices and—in some cases—explicit reasons, but not which personal experiences, incidents, alternatives or chronology prompted every individual choice. Where no original rationale is documented, the tradeoff discussed below is present-day interpretation, not a reconstructed motivation.

Source attribution boundary. The public Reference Platform source identified in this page’s provenance supports its synthetic gateway and inspector examples, not the original capture and recovery implementation. Those mechanisms are summarized from separately reviewed material without reproducing its private locations; the linked public Processor and Replication chapters have separate source authorities. Tests present in source and earlier recorded executions are not fresh tests of this publication.

A small success message is not enough

Imagine a recording command reporting success. It could mean a process returned zero. It might also mean media was written to disk. Neither statement, by itself, answers whether the saved bytes are still there, whether they describe the intended capture attempt, whether the database registered that attempt, or whether a copy elsewhere was independently read and checked.

Edge Evidence separates those questions instead of compressing them into one “done” flag. The result is not one uniform runtime. The original edge platform handles capture and authority; standalone Processor and Replication products expose bounded worker behaviors; the Showcase demonstrates one synthetic worker handoff; and the Visual Gateway explains supplied synthetic records. The design has a through-line, but these surfaces do not form one continuously attested deployed pipeline.

That separation is useful precisely because each boundary has a failure mode. It also has a price: extra records, state machines, checks, storage operations and explanations that can feel laborious compared with a simple “upload succeeded” message. Whether the extra complexity was justified for every intended deployment is not established by the available measurements. What follows distinguishes the recorded technical choices from present-day readings of their consequences.

Preserve the original, then derive without rewriting it

The platform’s early finalization specification chooses the SHA-256 of finalized media bytes as the artifact’s content identity. It validates the source descriptor and bounded media profile, writes the media under a content-addressed path, and publishes the final media before the exact artifact-manifest.v1 document. No-replace publication is deliberate: an overwrite-capable rename was excluded in the specification, and a collision does not silently replace an existing final artifact. The finalized bytes can be checked again rather than trusted merely because a previous command completed.

The later processing contract works in the other direction: it reads a verified immutable raw artifact and creates a different derived report, with its own identity and a one-parent derivation relationship. The source is not made to stand in for the result, and the result is not allowed to erase the source.

What this gains: a reviewer can ask two distinct questions—“what bytes were preserved?” and “what result was derived from them?”—and compare each against its own stored evidence. A derived report may be rerun or independently inspected without silently changing the recording from which it came.

What it costs: storage for source and derived objects, explicit lineage and identity checks, and more failure windows during staged publication. The finalization guarantee depends on the stated single-filesystem/POSIX primitives and verified bytes; a SHA-256 value does not authenticate the camera, prove the represented scene, or guarantee every kind of power-loss durability.

See Processor recovery for the complete derived-job transaction.

One file may represent more than one event

Two capture attempts can produce identical media bytes. If the system used the content digest as the only identity, those two occasions would be collapsed. Conversely, re-registering the same occasion with inconsistent facts should not create a harmless-looking second occurrence.

The ledger specification therefore records a content artifact separately from a capture occurrence keyed by source, session and sequence. Multiple occurrences may point to the same artifact, but conflicting claims about one occurrence key are rejected. An event ID is different again: it names the logical completion notification for that occurrence.

This distinction also explains why the final content manifest omits session and sequence. Those operational facts belong to the occurrence ledger, not the manifest of immutable content. The specification explicitly defines both layers; later multi-source work preserves their distinction when several sources share the same bytes.

Benefit: reuse of identical content without rewriting history about how many attempts or sources were involved. Cost: two identities must be reconciled, relational constraints must agree with the filesystem, and someone inspecting only filenames will not recover the complete capture story.

This is a documented identity-model decision.

The filesystem, SQLite and the local outbox answer different questions

A content-addressed file tells us which bytes are stored. SQLite records the authoritative relationship among artifact, occurrence and completion state. A local outbox row records that the system has committed a logical event for later distribution. None can replace the others.

The SPEC-004 registration contract commits the verified artifact row, capture-occurrence row and deterministic SegmentFinalized outbox event in one SQLite transaction. An exact retry becomes a no-op; a mismatched artifact or occurrence becomes a conflict. If the database transaction fails, the filesystem may still contain valid finalized objects, but they are not promoted to authoritative completion merely because the files exist.

The optional event-distribution specification adds a further tradeoff. A publisher may send the exact canonical outbox payload to JetStream and wait for acknowledgment, but it marks the local event published after that acknowledgment in a separate database transaction. Broker I/O does not hold the primary SQLite writer transaction. An outage therefore need not block capture through that lock. A crash between broker acknowledgment and local marking can produce a repeated delivery, so the consumer must be idempotent; exactly-once delivery is not claimed. Distribution state is not evidence authority.

Benefit: a local authoritative capture can be committed independently of a network listener, and an event can be retried without fabricating a new capture. Cost: there is no single atomic transaction spanning SQLite, the filesystem and a message broker. There are pending-event states, delivery attempts, duplicate handling and operational responsibility for a later publisher/consumer. The message bus is an optional reference capability, not proof that every deployed installation uses it.

A useful present-day way to read this boundary is to ask what a stored event can truthfully prove; committing it locally does not prove delivery to a receiver.

Make interruption a state, not a mystery

The clearest recorded problem → choice appears in the crash-reconciliation specification. Its governing constraint says a filesystem scan cannot reconstruct every occurrence after every crash window: final filenames contain content hashes, the final manifest lacks session and sequence, and publication may already have removed the temporary path that carried them.

The response is explicit: commit an expected-occurrence PREPARED intent before any staging, then reconcile it after interruption. If verified evidence proves completion, the intent can terminate as COMPLETE. If the expected result cannot be supported under the specified recovery rules, it becomes a durable GAP with a different outbox event. Corruption or logically impossible evidence stops for intervention; the reconciler does not improvise missing facts. The specification and tests examine named crash barriers—including process death between file and database operations—under stated POSIX/FFmpeg prerequisites.

Consider a documented failure class, not an asserted historical incident: the final media exists but the manifest never survived. A naive success claim would hide the missing proof. A naive retry might overwrite bytes. The reconciliation table instead makes a deliberate outcome visible—verified recovery where enough evidence survives, a gap or reported orphan where it does not, and refusal where the observed state contradicts authority.

Benefit: interruptions become inspectable, replay can avoid duplicate effects, and terminal loss cannot quietly become success. Cost: conservatism is visible. Some cases become GAP rather than optimistic COMPLETE; partial material may require quarantine; single-node locking, explicit recovery commands and operator decisions remain. “Crash-safe” is bounded to the documented local primitives and scenarios, not universal filesystem or power-loss immunity.

Capture’s PREPARED intent is not the Processor’s PREPARED derived-job checkpoint. The public Processor uses a separately identified job and staged derived report: replay verifies and finishes the same work, rather than treating a published result as committed before SQLite catches up. Nor is either state the Visual Gateway’s supplied synthetic prepared label. The similarly spelled words identify different authorities. The lifecycle chapter and Processor recovery explain these transactions in detail.

Copy, adopt, verify—three different verbs

Replication begins after finalized evidence exists. Its specification and standalone implementation require a destination bound in advance; the worker neither chooses a provider nor provisions a target on the operator’s behalf.

For an eligible object, the worker may create the destination only if absent. If the object already exists, it may be adopted only when its bytes and expected identity match exactly. A collision with contradictory bytes is refused, not “fixed” by overwriting. A write or adoption still does not finish the proof: the worker independently reads the final target and checks its expected size and digest before recording it as verified.

The specification explicitly retains the primary local SQLite/spool as capture authority. A warm copy is neither the original record nor an automatic restore authority. The design even distinguishes the occurrence assertion as fresh replica work when the underlying media is already present.

Benefit: a lost response or rerun need not create a second copy, wrong-target identity is treated as an error, and a “successful write” is not accepted as a successful readback. Cost: extra reads, hashing, target markers, filesystem/provider assumptions and potentially expensive retries. Refusing contradictory objects preserves ambiguity for review but sacrifices the convenience of automatic overwrite-and-continue. The public standalone demonstration substitutes an NFS mount probe; its successful local tests do not establish every physical NFS mount, optional GCS provider, or production service.

Replication verification and readback contains the complete create/adopt/refuse/recheck story. Separately retained physical-replica and recovery records have their own evidence scopes; they are not smuggled into this standalone test claim.

Simplify the reviewer’s path without moving evidence authority into the UI

The Reference Platform began as three distinguishable services: Web UI for presentation, Evidence API for disposable synthetic projections, and Edge Agent for deterministic inspection. A dated October 13 PR records a different presentation choice: assemble those existing handlers into an optional single-process, same-origin gateway so a first-time reviewer could use a small hosted demonstration with less setup and clearer navigation.

This was an explicitly described deployment adapter, not a decision to let the UI become the ledger. The gateway exposes a narrow allowlist of read/inspection routes and deliberately excludes the demo-reset endpoint. It does not load the canonical capture database, start Processor or Replication workers, or verify an external copy.

What is gained: one browser origin, a simpler hosted demo surface, and fewer moving parts for a short synthetic walkthrough. What is traded away: the service isolation and deployment flexibility of independently running UI, API and inspector. A single-process demonstration must not be mistaken for production fault isolation, durability or an end-to-end engine. The separately packaged services remain part of the source. This is a rare case where both the reason and the accepted limit are explicit in the same recorded PR.

It also explains a frequent misreading of the public demonstrations. The Showcase exercises a separate bounded synthetic Processor-to-Replication handoff and readback; the Visual Gateway uses supplied synthetic ArtifactProjection records and a deterministic HTTP explanation. Showing both proves neither that they share one live database nor that original camera capture flowed automatically into both.

Keep deterministic inspection as the known baseline

The hosted inspector is intentionally plain: it classifies a supplied synthetic record through code paths that reviewers can inspect. COMPLETE is explained as healthy-complete, DEFERRED as bounded-defer, and PREPARED as prepared-awaiting-catch-up. A proposal in a response does not mean a command has been executed; mutation authorization stays false. It does not retrieve fresh truth from the canonical SQLite ledger.

A deterministic boundary gains predictable results on the three supplied examples, makes side effects easier to exclude, and allows the visitor to understand the interface before debating the value of a model. Its cost is limited flexibility: it can only apply the authored rules to the states and inputs it has been given. Predictability is a feature for this demonstration, not proof that deterministic classification solves every real operational diagnostic problem.

There are two separate agent tracks that must not be collapsed. The public Reference Platform contains a default-off optional ADK adapter with a single read-only inspection tool. In the private processor track, a recorded design challenge deliberately deferred ADK until a framework-neutral deterministic read-only core was accepted; a later read-only ADK adapter was implemented and tested in its separately gated scope. Those facts do not establish a hosted model-assisted Visual Gateway, a working local Ollama comparison, or permission for an agent to invoke jobs. A proposed ADK/Ollama comparison would need to measure whether a model adds interpretive value over the deterministic baseline without acquiring new evidence or action authority. No comparative results are asserted here.

A useful future experiment would compare a deterministic explanation, a model explanation without tools, and a model with one explicitly read-only inspection tool on the same labeled synthetic examples. Whether the gain is worth additional dependencies, latency, cost, nondeterminism, grounding checks and review work is a question, not a finding. The inspector baseline remains the authority for what the public HTTP route currently does.

What is demonstrated—and what we can still not honestly say

The record supports implemented behaviors in the pinned sources, test assertions in those sources, and separately retained earlier test executions for named candidates. The original platform has synthetic capture/finalization and bounded RTSP/recovery evidence; the standalone Processor and Replication products have scoped local worker tests; the Showcase has its own synthetic component handoff; and the Visual Gateway has browser/API inspection of supplied synthetic records. These are different layers of support, not one continuous production acceptance receipt. They do not certify source authenticity, physical camera interoperability, all provider configurations, current uptime, or a model experiment.

A methodological connection, not an origin story

Project 03 asks what auditable evidence remained after an engineering period, and what it can and cannot say about “done.” Its accepted historical repository packages, candidate verification, engineering acceptance, scoped provenance, whole-candidate lineage and projection-specific runtime observations are a frozen analytical study, not measurements of today’s Edge Evidence components. Its author described the period as AI-heavy retrospectively; that is not measured AI intensity or causal productivity evidence. The later reorganization of Obsidian notes explains how the study was presented, not why it originally began.

The engineering choices in this chapter share a method with that research: identify the thing being claimed, name its evidence authority and scope, then preserve the uncertainty instead of silently upgrading it. Project 03 did not thereby cause this architecture; no dated causal record supporting that claim was found. The same is true in reverse: a successful replay test does not establish Project 03 engineering acceptance or whole-candidate lineage. Verification versus acceptance and Lineage and provenance explain the frozen study on its own terms.

The through-line is therefore a modest engineering judgment: a system should not call an event a fact merely because one component said it succeeded. That judgment creates more work and more visible limits, and the chapter keeps those costs in view.