core/docs/architecture/edge-sync-artifact-contract.md

Edge Sync Artifact Contract

Status: Design contract
Builds on: docs/architecture/edge-s3-persistence.md
Scope: Artifact classes, manifest shape, authority boundaries, sync failure semantics, and future proof obligations for CORE edge/cloud synchronization.
Non-goal: This document does not introduce a runtime dependency on S3/object storage and does not implement a sync client.

Purpose

The S3 persistence architecture defines where cloud/object storage belongs:

Edge = thinking, acting, refusing, remembering hot.
S3   = preserving, auditing, syncing, distributing, training cold.

This contract defines what is allowed to cross that boundary and what authority, if any, each artifact has after crossing.

The load-bearing invariant:

Downloaded != activated.
Activated  != coherent.
Signed     != true.

Integrity, provenance, epistemic status, and runtime authority are separate axes. They must never collapse into one another.

Core rule

S3-compatible storage may preserve and distribute artifacts. It does not grant epistemic admissibility.

Any artifact imported from cloud/object storage enters CORE under the same truth-seeking schema as any other input:

• malformed or absent epistemic status defaults to speculative;
• source prestige, fleet frequency, or signature presence is not coherence;
• runtime-affecting artifacts require signature/hash/schema verification before activation;
• learning artifacts may inform sealed practice, but do not mutate serving knowledge directly;
• serving evidence still requires the reviewed/proven mutation path.

Artifact classes

Each artifact class has a fixed authority profile. Implementations may add fields, but they must not weaken these defaults without a follow-on ADR or explicitly ratified contract update.

Artifact class	Runtime-affecting	Hot-path allowed	Signature required	Review/proof required before serving influence	Epistemic default
trace	No	No	Recommended	No; audit input only	speculative
replay_bundle	No	No	Recommended	No; audit/proof input only	speculative
sealed_eval_result	No	No	Recommended	Yes, before claims/promotion	speculative
fleet_observation_batch	No	No	Recommended	Yes, before evidence use	speculative
curriculum_bundle	No direct effect	No	Required if distributed to devices	Yes, before pack/runtime mutation	speculative
pack_release	Yes	Pull-only, activation-gated	Required	Yes; release process must prove/review	as manifest declares, never implicit
policy_release	Yes	Pull-only, activation-gated	Required	Yes; release process must prove/review	as manifest declares, never implicit
modality_compiler_release	Yes	Pull-only, activation-gated	Required	Yes; compiler changes are runtime-affecting	as manifest declares, never implicit
cold_vault_snapshot	Yes during explicit restore	No live hot path	Required	Yes; restore is an activation event	preserved per entry, malformed => speculative

Prohibited implication

No artifact class may imply:

stored in S3 => reviewed
signed       => true
downloaded   => active
popular      => coherent
fleet-seen   => admissible

Manifest schema

Every artifact that is distributed or consumed by automation should have a manifest. Runtime-affecting artifacts must have one.

Minimal manifest:

{
  "schema_version": 1,
  "artifact_id": "...",
  "artifact_type": "pack_release",
  "artifact_version": "...",
  "created_at_utc": "...",
  "producer": {
    "type": "human|runtime|ci|fleet_aggregator",
    "id": "..."
  },
  "content": {
    "uri": "s3://bucket/path/object.zst",
    "digest": "sha256:...",
    "size_bytes": 0,
    "compression": "zstd|none",
    "media_type": "application/jsonl|application/zstd|application/octet-stream"
  },
  "authority": {
    "runtime_affecting": true,
    "hot_path_allowed": false,
    "requires_signature": true,
    "requires_activation": true,
    "requires_review_or_proof": true
  },
  "epistemic": {
    "default_status": "speculative",
    "admissible_as_evidence": false,
    "promotion_required": true
  },
  "compatibility": {
    "min_runtime_version": "...",
    "max_runtime_version": null,
    "requires_capabilities": []
  },
  "provenance": {
    "source_trace_ids": [],
    "source_eval_run_ids": [],
    "source_pack_digests": []
  },
  "signature": {
    "algorithm": "...",
    "key_id": "...",
    "signature": "..."
  }
}

Required manifest checks

Before a runtime-affecting artifact may be activated, the edge runtime or release manager must verify:

1. manifest schema version is supported;
2. artifact type is known;
3. content digest matches downloaded bytes;
4. signature is valid for the manifest and/or content according to release policy;
5. runtime compatibility is satisfied;
6. artifact class authority profile is not weakened by the manifest;
7. activation is recorded as an auditable trace;
8. previous verified release remains available for rollback where applicable.

Activation contract

A downloaded object is inert until activated.

Activation is the explicit transition:

downloaded + verified + compatible + authorized => active local release

Activation does not mean the artifact's claims are automatically COHERENT. It means the artifact is now allowed to participate according to its artifact class.

Examples:

• A pack_release may contain coherent entries only where the pack itself declares and proves the review status required by pack policy.
• A policy_release may constrain actions after activation, but the signature only proves the policy bundle came from an authorized release process.
• A fleet_observation_batch remains speculative learning input even when signed and downloaded.
• A cold_vault_snapshot preserves per-entry epistemic statuses; malformed or missing statuses default to speculative.

Sync failure semantics

Sync failures must preserve edge safety.

Failure	Required behavior
S3 unavailable	Continue local operation using last verified local state.
Upload failure	Retain local journal for retry; do not block hot path.
Download failure	Keep current active release; do not partially activate.
Hash mismatch	Reject object; log trace; keep current active release.
Invalid signature	Reject object; log trace; keep current active release.
Unknown artifact type	Reject unless explicitly configured as non-runtime archival input.
Unsupported schema	Reject or quarantine; never activate silently.
Compatibility failure	Reject activation; keep current active release.
Partial download	Discard or quarantine; never activate.
Clock skew	Do not grant authority based solely on local time; preserve trace.

Authority model

Artifacts have four independent authority axes:

1. Integrity — bytes match digest/signature.
2. Compatibility — runtime can safely parse and understand the artifact.
3. Activation — artifact is allowed to participate in local runtime behavior.
4. Epistemic admissibility — artifact claims may be used as evidence.

These axes are intentionally separate.

Integrity does not imply activation.
Activation does not imply coherence.
Coherence does not imply permanence.

Edge hot-path prohibition

The following decisions must not require S3/object storage round trips:

• stop/continue safety decisions;
• collision or force-limit decisions;
• active vault recall;
• current-field propagation;
• customer-facing refusal/answer generation;
• immediate policy/action gate evaluation;
• active contradiction checks required for current action;
• motor-control or embodied reflex loops.

If the edge runtime cannot decide safely without S3, it must choose the safe local fallback: refuse, ask, observe-only, stop, or escalate according to action class.

Learning and fleet aggregation

Fleet artifacts may feed sealed practice and offline aggregation.

They may not directly mutate serving knowledge.

Correct flow:

fleet traces / observations
  -> S3 archival
  -> offline aggregation
  -> candidate proposal
  -> proof / review / ratification
  -> signed release
  -> edge download
  -> verification
  -> activation

Incorrect flow:

fleet observation
  -> S3
  -> runtime fact

The incorrect flow is an epistemic-corruption path and must be rejected.

Required metadata by artifact class

trace

Required:

• trace_id
• runtime_version
• timestamp_utc
• field_state_digest_before
• field_state_digest_after when available
• input source digests
• selected decision/action/refusal
• epistemic states involved
• safety gate result where applicable

replay_bundle

Required:

• replay_hash
• source trace_id or eval run id
• runtime/version metadata
• pack/policy manifest digests
• deterministic replay inputs
• expected replay verdict

sealed_eval_result

Required:

• lane id
• run id
• case count
• verdict counts
• wrong/refusal/correct counts where applicable
• timing summary when measured
• runtime version
• input dataset digest

fleet_observation_batch

Required:

• producing robot/site/fleet ids where applicable
• capture time range
• source modalities
• per-observation provenance
• epistemic default = speculative
• no direct admissibility flag unless produced by a reviewed/proven release process

pack_release / policy_release / modality_compiler_release

Required:

• signed manifest
• content digest
• schema version
• runtime compatibility
• release notes or proof summary
• rollback reference where applicable
• activation trace requirement

cold_vault_snapshot

Required:

• snapshot id
• source runtime/device id
• vault schema version
• per-entry epistemic status
• per-entry digest or snapshot digest
• restore policy
• explicit restore activation trace

Future implementation targets

This contract should eventually be enforced by code. Likely targets:

core/sync/artifacts.py
core/sync/manifest.py
core/sync/verify.py
core/sync/journal.py
core/sync/activation.py
tests/test_edge_sync_artifact_contract.py

No implementation path may introduce S3 as a dependency of active recall, active reasoning, refusal, or safety gating.

Future proof obligations

A code implementation should include tests that fail if:

1. an unsigned runtime-affecting artifact activates;
2. a hash-mismatched artifact activates;
3. a downloaded artifact becomes active before verification;
4. a signed fleet observation becomes admissible evidence by signature alone;
5. malformed epistemic status imports as coherent;
6. S3 unavailability blocks local refusal/reasoning;
7. download failure clears the last verified local release;
8. hot-path code imports the S3 client directly;
9. a cold vault restore drops or upgrades per-entry epistemic status;
10. activation occurs without an auditable trace.

Summary

This contract turns edge/S3 separation into an authority model.

S3 may store.
S3 may distribute.
S3 may preserve evidence.
S3 may not decide truth.
S3 may not sit in the hot path.
S3 may not mutate serving knowledge directly.

Truth still enters by proof, review, coherence, replay, and ratified mutation paths — never by storage location, signature, popularity, or fleet frequency.