docs: add edge S3 persistence architecture
This commit is contained in:
Shay
parent
f008550d79
commit
c654b3f22d
1 changed files with 238 additions and 0 deletions
238
docs/architecture/edge-s3-persistence.md
Normal file
238
docs/architecture/edge-s3-persistence.md
Normal file
|
|
@ -0,0 +1,238 @@
|
|||
# Edge S3 Persistence Architecture
|
||||
|
||||
**Status:** Design note
|
||||
**Scope:** CORE edge/runtime persistence, fleet trace archival, signed pack distribution, replay artifacts, and cold-storage synchronization.
|
||||
**Non-goal:** S3/object storage is not part of the active cognition, recall, safety, or motor-control hot path.
|
||||
|
||||
## Decision
|
||||
|
||||
CORE's real-time intelligence stays edge-local. S3-compatible object storage is used as the cloud-side persistence and distribution layer for immutable artifacts, fleet-scale learning inputs, audits, and signed releases.
|
||||
|
||||
The split is deliberate:
|
||||
|
||||
```text
|
||||
Edge = thinking, acting, refusing, remembering hot.
|
||||
S3 = preserving, auditing, syncing, distributing, training cold.
|
||||
```
|
||||
|
||||
Object storage may preserve and distribute evidence. It must not become an authority source that bypasses CORE's epistemic law.
|
||||
|
||||
## Why this matters
|
||||
|
||||
CORE is designed to run primarily at the edge: local substrate, local vault recall, local action gates, local refusal, local traces, and local safety boundaries. That edge-native posture is essential for robotics, retail/commercial deployments, privacy-sensitive domains, and disconnected or degraded-network environments.
|
||||
|
||||
S3 is valuable because a fleet still needs durable storage, audit replay, signed releases, and large-scale curriculum aggregation. The correct role for S3 is therefore cold/nearline persistence, not active cognition.
|
||||
|
||||
## Architecture
|
||||
|
||||
```text
|
||||
Robot / edge runtime
|
||||
├─ active field state
|
||||
├─ hot local vault
|
||||
├─ local pack cache
|
||||
├─ local policy/action gates
|
||||
├─ local safety controller integration
|
||||
├─ local trace journal
|
||||
└─ sync agent
|
||||
↓ append / pull signed releases
|
||||
S3-compatible object storage
|
||||
├─ traces/
|
||||
├─ replay-artifacts/
|
||||
├─ sealed-evals/
|
||||
├─ packs/
|
||||
├─ curriculum/
|
||||
├─ fleet-observations/
|
||||
├─ audit/
|
||||
├─ releases/
|
||||
└─ cold-vault-backups/
|
||||
```
|
||||
|
||||
The edge runtime must remain capable of safe local operation without a live S3 round trip.
|
||||
|
||||
## S3 responsibilities
|
||||
|
||||
S3-compatible storage is appropriate for:
|
||||
|
||||
| Use | Purpose |
|
||||
|---|---|
|
||||
| Immutable trace archive | Preserve turn/action evidence for replay and audit. |
|
||||
| Replay artifacts | Store proof bundles, field digests, recall digests, and decision traces. |
|
||||
| Sealed eval outputs | Persist lane results, comparison artifacts, and timing reports. |
|
||||
| Pack distribution | Publish signed, versioned packs to edge devices. |
|
||||
| Curriculum storage | Hold practice corpora, modality corpora, and offline learning inputs. |
|
||||
| Fleet telemetry snapshots | Aggregate non-hot-path observations for later analysis. |
|
||||
| Audit/compliance | Preserve append-only evidence for review and accountability. |
|
||||
| Cold vault backups | Restore edge devices after hardware failure without making S3 the hot vault. |
|
||||
|
||||
S3 is not appropriate for:
|
||||
|
||||
- real-time vault recall;
|
||||
- active field propagation;
|
||||
- motor-control loops;
|
||||
- safety vetoes;
|
||||
- immediate perception/action decisions;
|
||||
- active contradiction checks needed for a current action;
|
||||
- direct unreviewed knowledge mutation.
|
||||
|
||||
## Object model
|
||||
|
||||
Objects should be append-first and content-addressable where practical.
|
||||
|
||||
Recommended layout:
|
||||
|
||||
```text
|
||||
s3://<bucket>/traces/<site_id>/<robot_id>/<yyyy-mm-dd>/<trace_id>.jsonl.zst
|
||||
s3://<bucket>/replay-artifacts/<site_id>/<robot_id>/<yyyy-mm-dd>/<replay_hash>.bundle.zst
|
||||
s3://<bucket>/sealed-evals/<lane>/<run_id>/result.json
|
||||
s3://<bucket>/fleet-observations/<site_id>/<yyyy-mm-dd>/<batch_id>.jsonl.zst
|
||||
s3://<bucket>/releases/packs/<pack_id>/<version>/manifest.json
|
||||
s3://<bucket>/releases/packs/<pack_id>/<version>/pack.zst
|
||||
s3://<bucket>/releases/packs/<pack_id>/<version>/signature.sig
|
||||
s3://<bucket>/cold-vault-backups/<site_id>/<robot_id>/<snapshot_id>.bundle.zst
|
||||
```
|
||||
|
||||
Every release object that can influence runtime behavior must be referenced by a signed manifest. Runtime devices pull releases only after signature, hash, schema, and compatibility checks pass.
|
||||
|
||||
## Trace schema sketch
|
||||
|
||||
A trace object should preserve enough information for deterministic replay and audit without requiring S3 to be present during the live decision.
|
||||
|
||||
Minimum fields:
|
||||
|
||||
```json
|
||||
{
|
||||
"schema_version": 1,
|
||||
"trace_id": "...",
|
||||
"robot_id": "...",
|
||||
"site_id": "...",
|
||||
"timestamp_utc": "...",
|
||||
"runtime_version": "...",
|
||||
"pack_manifest_digests": ["..."],
|
||||
"input_sources": [
|
||||
{
|
||||
"source_id": "front_camera",
|
||||
"source_type": "vision",
|
||||
"capture_digest": "...",
|
||||
"timestamp_utc": "..."
|
||||
}
|
||||
],
|
||||
"field_state_digest_before": "...",
|
||||
"vault_recall_digests": ["..."],
|
||||
"candidate_actions": ["..."],
|
||||
"selected_action": "...",
|
||||
"decision": "act|refuse|ask|escalate|observe_only",
|
||||
"decision_reason": "...",
|
||||
"epistemic_states": ["..."],
|
||||
"safety_gate_result": "cleared|blocked|escalated",
|
||||
"field_state_digest_after": "...",
|
||||
"replay_hash": "..."
|
||||
}
|
||||
```
|
||||
|
||||
The exact schema may evolve, but the invariant does not: replay-critical claims must carry provenance, status, and digests.
|
||||
|
||||
## Epistemic law for S3 objects
|
||||
|
||||
S3 is storage, not truth.
|
||||
|
||||
Objects loaded from S3 must enter CORE under the same epistemic discipline as any other input:
|
||||
|
||||
- unknown or malformed status defaults to speculative;
|
||||
- content provenance is preserved;
|
||||
- source prestige or fleet frequency is not sufficient for coherence;
|
||||
- signed release status proves integrity, not truth;
|
||||
- contested or falsified objects must not become admissible evidence;
|
||||
- unreviewed fleet observations are learning inputs, not runtime facts;
|
||||
- runtime mutation still flows through the single reviewed/proven path.
|
||||
|
||||
A fleet upload may become evidence only after the appropriate review, proof, or ratification corridor promotes it.
|
||||
|
||||
## Sync model
|
||||
|
||||
The edge sync agent has two directions:
|
||||
|
||||
### Upload
|
||||
|
||||
- append local traces;
|
||||
- append replay bundles;
|
||||
- append sealed practice outcomes;
|
||||
- append non-hot-path telemetry snapshots;
|
||||
- upload cold vault snapshots when configured.
|
||||
|
||||
Upload failure must not block safe local operation. The local journal should retain unsynced artifacts until acknowledged or until a configured retention boundary is reached.
|
||||
|
||||
### Download
|
||||
|
||||
- fetch signed pack releases;
|
||||
- fetch signed policy bundles;
|
||||
- fetch approved curriculum/practice bundles;
|
||||
- fetch restore snapshots only during explicit recovery flows.
|
||||
|
||||
Download failure must not weaken local safety. The device continues using the last verified local release.
|
||||
|
||||
## Security and integrity requirements
|
||||
|
||||
Runtime-affecting S3 artifacts require:
|
||||
|
||||
1. content hash in manifest;
|
||||
2. manifest signature;
|
||||
3. schema version check;
|
||||
4. runtime compatibility check;
|
||||
5. monotonic release/version rule where applicable;
|
||||
6. local verification before activation;
|
||||
7. append-only audit trail for activation decisions.
|
||||
|
||||
Audit-critical buckets should enable versioning and, where operationally appropriate, object lock / retention policies.
|
||||
|
||||
## Robotics / embodied autonomy implications
|
||||
|
||||
For humanoid or commercial robots, S3 must never sit between perception and immediate safe action. A robot cannot wait on object storage to decide whether to stop, refuse, avoid a person, or keep force within bounds.
|
||||
|
||||
Correct split:
|
||||
|
||||
```text
|
||||
Hot path:
|
||||
sensors → modality compiler → local field → local recall → local gate → local action/safety
|
||||
|
||||
Cold path:
|
||||
traces/practice/fleet observations → S3 → offline aggregation → proof/review → signed release → edge pull
|
||||
```
|
||||
|
||||
This preserves edge autonomy while still allowing fleet learning and auditability.
|
||||
|
||||
## Failure modes guarded against
|
||||
|
||||
| Failure mode | Guardrail |
|
||||
|---|---|
|
||||
| S3 outage blocks robot safety | Edge runtime remains locally safe and operational. |
|
||||
| Fleet observation becomes truth by frequency | S3 objects enter as speculative unless ratified. |
|
||||
| Malicious object mutation | Signed manifests, hashes, versioning, local verification. |
|
||||
| Practice contaminates serving | Practice uploads become proposals/signals, not runtime facts. |
|
||||
| Stale cloud state overrides local perception | Hot path prefers current local evidence and safety gates. |
|
||||
| Audit gaps | Append-first trace/replay archival with digests. |
|
||||
| Hidden knowledge mutation | S3 imports still pass through the one mutation/proposal path. |
|
||||
|
||||
## Acceptance criteria for implementation
|
||||
|
||||
An implementation of this architecture should prove:
|
||||
|
||||
1. the runtime can complete local recall/reasoning/refusal with S3 unavailable;
|
||||
2. S3 download failures preserve the last verified pack/policy release;
|
||||
3. unsigned or hash-mismatched packs are rejected;
|
||||
4. uploaded traces contain enough digests for replay validation;
|
||||
5. fleet observations are not admissible as evidence without promotion;
|
||||
6. object versioning or content-addressing prevents silent overwrite of meaning;
|
||||
7. sync retries do not block motor/safety hot paths;
|
||||
8. activation of a downloaded release is itself logged as an auditable trace.
|
||||
|
||||
## Summary
|
||||
|
||||
S3-compatible object storage is the right cloud-side complement to CORE's edge-native architecture. It preserves evidence, distributes signed knowledge artifacts, supports fleet learning, and enables audit/replay. It must remain outside the hot path and outside epistemic admission authority.
|
||||
|
||||
The governing rule is simple:
|
||||
|
||||
```text
|
||||
Edge thinks and acts.
|
||||
S3 remembers and distributes.
|
||||
Truth still enters only by proof.
|
||||
```
|
||||
Loading…
Reference in a new issue