docs: add edge sync completion status
This commit is contained in:
Shay
parent
cde30f5b05
commit
4e36abff6e
1 changed files with 145 additions and 0 deletions
145
docs/architecture/edge-sync-status.md
Normal file
145
docs/architecture/edge-sync-status.md
Normal file
|
|
@ -0,0 +1,145 @@
|
|||
# Edge Sync Completion Status
|
||||
|
||||
**Status:** Complete for the planned Edge/S3 Sync implementation brief
|
||||
**Branch:** `main`
|
||||
**Governing docs:**
|
||||
- [`edge-s3-persistence.md`](./edge-s3-persistence.md)
|
||||
- [`edge-sync-artifact-contract.md`](./edge-sync-artifact-contract.md)
|
||||
- [`edge-sync-implementation-brief.md`](./edge-sync-implementation-brief.md)
|
||||
|
||||
## Summary
|
||||
|
||||
The Edge/S3 Sync track is complete for the planned six-slice scope defined in `edge-sync-implementation-brief.md`.
|
||||
|
||||
```text
|
||||
Docs complete: 3/3
|
||||
Implementation slices complete: 6/6
|
||||
Runtime integration: intentionally not started
|
||||
Live network tests: prohibited
|
||||
S3 in hot path: prohibited
|
||||
Credentials in repo: prohibited
|
||||
Automatic epistemic promotion: prohibited
|
||||
```
|
||||
|
||||
The implementation establishes local contracts, validation, activation, journaling, an object-store seam, and an optional S3-compatible adapter. It does not integrate cloud/object storage into CORE's active cognition path.
|
||||
|
||||
## Completed documents
|
||||
|
||||
| Document | Status | Purpose |
|
||||
|---|---:|---|
|
||||
| `edge-s3-persistence.md` | Complete | Defines the edge-local / S3-cold split. |
|
||||
| `edge-sync-artifact-contract.md` | Complete | Defines artifact classes, authority boundaries, manifests, and sync semantics. |
|
||||
| `edge-sync-implementation-brief.md` | Complete | Defines the six-slice implementation plan. |
|
||||
|
||||
## Completed implementation slices
|
||||
|
||||
| Slice | Status | Files |
|
||||
|---|---:|---|
|
||||
| ES-0 / ES-1 — artifact authority model + contract tests | Complete | `core/sync/artifacts.py`, `tests/test_edge_sync_artifact_contract.py` |
|
||||
| ES-2 — manifest parser/validator | Complete | `core/sync/manifest.py`, `tests/test_edge_sync_manifest.py` |
|
||||
| ES-3 — activation ledger | Complete | `core/sync/activation.py`, `tests/test_edge_sync_activation.py` |
|
||||
| ES-4 — local sync journal | Complete | `core/sync/journal.py`, `tests/test_edge_sync_journal.py` |
|
||||
| ES-5 — object-store adapter seam | Complete | `core/sync/object_store.py`, `tests/test_edge_sync_hot_path_imports.py` |
|
||||
| ES-6 — optional S3 adapter | Complete | `core/sync/s3_store.py`, `tests/test_edge_sync_s3_store.py` |
|
||||
|
||||
Package exports are collected in:
|
||||
|
||||
```text
|
||||
core/sync/__init__.py
|
||||
```
|
||||
|
||||
## Invariants now represented in code/tests
|
||||
|
||||
The completed implementation codifies these rules:
|
||||
|
||||
```text
|
||||
Downloaded != activated.
|
||||
Activated != coherent.
|
||||
Signed != true.
|
||||
```
|
||||
|
||||
And proves:
|
||||
|
||||
- artifact authority classes are closed;
|
||||
- no edge-sync artifact is hot-path allowed;
|
||||
- runtime-affecting artifacts require signature and activation;
|
||||
- signed artifacts do not become admissible evidence by signature alone;
|
||||
- fleet observations remain speculative unless promoted through proof/review;
|
||||
- unknown artifact types reject;
|
||||
- unsupported manifest schema versions reject;
|
||||
- hash mismatch rejects;
|
||||
- missing content digest rejects when bytes are supplied;
|
||||
- malformed epistemic status defaults to speculative;
|
||||
- downloaded artifacts remain inert until activated;
|
||||
- activation does not confer evidence authority;
|
||||
- activation and rollback emit audit records;
|
||||
- local journal failures preserve retryable local state;
|
||||
- hot-path packages are statically guarded from object-store/S3 imports;
|
||||
- optional S3 behavior is tested with an injected fake client only.
|
||||
|
||||
## Verification command
|
||||
|
||||
Run the Edge/S3 Sync test set with:
|
||||
|
||||
```bash
|
||||
pytest \
|
||||
tests/test_edge_sync_artifact_contract.py \
|
||||
tests/test_edge_sync_manifest.py \
|
||||
tests/test_edge_sync_activation.py \
|
||||
tests/test_edge_sync_journal.py \
|
||||
tests/test_edge_sync_hot_path_imports.py \
|
||||
tests/test_edge_sync_s3_store.py
|
||||
```
|
||||
|
||||
## Scope intentionally not implemented
|
||||
|
||||
The following remain out of scope for this completed slice:
|
||||
|
||||
- live S3 credentials;
|
||||
- live bucket access;
|
||||
- background sync daemon;
|
||||
- multipart upload;
|
||||
- object-lock enforcement;
|
||||
- fleet aggregation logic;
|
||||
- runtime pack activation against real pack stores;
|
||||
- motor/safety integration;
|
||||
- automatic teaching-pack promotion;
|
||||
- cloud-driven serving mutation;
|
||||
- S3/object-store calls from hot-path cognition.
|
||||
|
||||
Any of the above requires a follow-on ADR, implementation brief, or explicit continuation plan.
|
||||
|
||||
## Hot-path boundary
|
||||
|
||||
The current static guard covers these hot-path directories:
|
||||
|
||||
```text
|
||||
algebra/
|
||||
chat/
|
||||
generate/
|
||||
vault/
|
||||
core/physics/
|
||||
```
|
||||
|
||||
They must not import:
|
||||
|
||||
```text
|
||||
boto3
|
||||
botocore
|
||||
core.sync.object_store
|
||||
core.sync.s3_store
|
||||
```
|
||||
|
||||
Future hot-path directories should be added to the guard if the runtime boundary expands.
|
||||
|
||||
## Completion statement
|
||||
|
||||
The Edge/S3 Sync track is complete for the planned local-contract scope.
|
||||
|
||||
The result is a safe cloud/fleet persistence foundation that preserves CORE's edge-native law:
|
||||
|
||||
```text
|
||||
Edge thinks and acts.
|
||||
S3 remembers and distributes.
|
||||
Truth still enters only by proof.
|
||||
```
|
||||
Loading…
Reference in a new issue