176 lines
6.3 KiB
Markdown
176 lines
6.3 KiB
Markdown
# ADR 0033: Central session artifacts and bounded operator-host cache
|
|
|
|
Date: 2026-07-30
|
|
Status: accepted and implemented
|
|
|
|
## Decision
|
|
|
|
Mission Core can exchange portable recorded-session products through an
|
|
optional provider-neutral, content-addressed artifact gateway. The canonical
|
|
current operator contour is local and complete without a shared store. An
|
|
external filesystem provider is an auxiliary transport/prefetch capability,
|
|
not an operational-readiness dependency and not a production topology
|
|
decision.
|
|
|
|
The historical RAVNOVES00 migration acceptance used an existing SMB-backed
|
|
filesystem as one experimental provider. That provider, its mount and its host
|
|
configuration are outside the current Mission Core runtime contract. Mission
|
|
Core does not own its authentication, does not require it at startup and does
|
|
not receive a NAS password.
|
|
|
|
Every immutable object is stored under:
|
|
|
|
```text
|
|
objects/sha256/<first-two-hex>/<full-sha256>
|
|
```
|
|
|
|
Canonical JSON manifests are themselves addressed by SHA-256. Mutable names
|
|
exist only as small, atomically replaced references:
|
|
|
|
```text
|
|
refs/<namespace>/<key>.json -> manifest SHA-256
|
|
```
|
|
|
|
An operator host never serves a central SMB file directly. It first streams the
|
|
object into a temporary local file, proves the expected SHA-256 and byte length,
|
|
and atomically publishes it into:
|
|
|
|
```text
|
|
<MISSIONCORE_DATA_DIR>/artifact-cache
|
|
```
|
|
|
|
The local cache has:
|
|
|
|
- an 8 GiB default byte quota;
|
|
- a 2 GiB default free-space reserve;
|
|
- persistent SQLite metadata;
|
|
- persistent pin sets;
|
|
- LRU eviction of unpinned objects only;
|
|
- no automatic deletion of source evidence;
|
|
- offline resolution through locally sealed reference and manifest snapshots.
|
|
|
|
The limits are configurable with:
|
|
|
|
```text
|
|
MISSIONCORE_ARTIFACT_CACHE_MAX_BYTES
|
|
MISSIONCORE_ARTIFACT_CACHE_FREE_SPACE_RESERVE_BYTES
|
|
```
|
|
|
|
An optional shared root is configured explicitly with:
|
|
|
|
```text
|
|
MISSIONCORE_ARTIFACT_STORE_ROOT
|
|
```
|
|
|
|
## Recorded playback behavior
|
|
|
|
The base RRD and integrated E10 overlay are separate immutable roles in one
|
|
recorded-session manifest.
|
|
|
|
On a normal cache hit, recorded playback uses the existing private RRD cache.
|
|
On a private-cache miss it may restore the exact `base-rrd` role from the
|
|
bounded artifact cache. Restoration is admitted only when:
|
|
|
|
- the manifest type and subject match the requested session;
|
|
- the RRD content digest and length match the manifest;
|
|
- the local source evidence still hashes to `base-source-sha256`;
|
|
- the manifest carries the exact session timeline bounds.
|
|
|
|
The restored RRD is republished through the existing private recording-cache
|
|
transaction and receives a fresh sidecar bound to the current local evidence
|
|
stats. The exporter is not run.
|
|
|
|
The integrated-perception endpoint resolves
|
|
`integrated-overlay:<recording-id>` before scanning or validating local worker
|
|
results. A sealed central/local CAS hit therefore needs neither Worker 006 nor
|
|
the original E10 result tree. Invalid central metadata fails closed; a genuinely
|
|
absent central role can still use the existing local materialization path.
|
|
When the central store is unavailable, however, a missing local CAS role is not
|
|
treated as an absent role: base RRD export and overlay rendering both fail with
|
|
an explicit offline-cache error. This prevents one disconnected operator host
|
|
from silently producing a second derived truth.
|
|
|
|
## Persistent pins and offline use
|
|
|
|
The CLI surface is:
|
|
|
|
```bash
|
|
k1link artifact publish ...
|
|
k1link artifact pin ...
|
|
k1link artifact unpin ...
|
|
k1link artifact resolve ...
|
|
k1link artifact status ...
|
|
```
|
|
|
|
Pinning is a local operator-host decision. A pin downloads and verifies every
|
|
member of the selected manifest. If any member fails, the new pin is removed;
|
|
objects already downloaded remain ordinary unpinned cache entries.
|
|
|
|
When the central root is unavailable:
|
|
|
|
- a sealed local reference, manifest, and object resolve normally;
|
|
- an absent local object returns an explicit offline-cache error;
|
|
- Mission Core does not invoke the local RRD exporter, scan stale worker
|
|
results, render an overlay, fetch from Worker 006 or start a heavy AI run.
|
|
|
|
`GET /api/health` exposes the effective shared/standalone mode, central-store
|
|
availability, bounded CAS and RRD-cache occupancy, media-tool availability and
|
|
the background catalog reconciler state without disclosing filesystem paths.
|
|
`GET /api/health` reports local operational readiness independently. Optional
|
|
shared artifacts are exposed as a non-required capability with separate
|
|
`configured` and `ready` values. Their absence or temporary unavailability does
|
|
not degrade a healthy local contour. When an operator explicitly configures
|
|
that capability, its fail-closed cache-miss semantics still apply to artifacts
|
|
that were expected from the configured gateway.
|
|
|
|
## RAVNOVES00 migration acceptance
|
|
|
|
The source session is `20260720T065719Z_viewer_live`, displayed as
|
|
`RAVNOVES00`.
|
|
|
|
The reference used by that bounded migration acceptance pointed to:
|
|
|
|
```text
|
|
092f758c09965be98fd76d8191474c528ee20540dce5f4761c2a087f6056a6d5
|
|
```
|
|
|
|
It contains nine logical roles totaling `721626746` bytes:
|
|
|
|
- the source evidence archive;
|
|
- the base RRD and its original audit sidecar;
|
|
- the accepted E10 result archive;
|
|
- the compute-job manifest;
|
|
- the LiDAR pack and its manifest;
|
|
- the sealed integrated overlay and its sidecar.
|
|
|
|
The host pin is:
|
|
|
|
```text
|
|
session:20260720T065719Z_viewer_live
|
|
```
|
|
|
|
Acceptance facts:
|
|
|
|
- all nine roles are cached and pinned;
|
|
- base RRD SHA-256:
|
|
`4db5f2519caa61aca3683499094329b35cf3c24d1cc242953c54d2a228762e13`;
|
|
- base source SHA-256:
|
|
`70da0edad5cbf0e89b6e2355c0aac294f8c36a67249cd33b8918353fd88c83af`;
|
|
- overlay SHA-256:
|
|
`c2bb73fca8bb616a3929df236c6dc63d071b6466a6ca57d06487ef18ed985b57`;
|
|
- an offline overlay resolve completed in 0.76 seconds;
|
|
- an isolated offline base restore produced the exact RRD without invoking the
|
|
exporter;
|
|
- an isolated offline overlay materialization succeeded with nonexistent local
|
|
worker-result, job, and LiDAR roots.
|
|
|
|
The migration was copy-only. Existing evidence, derived recordings, accepted
|
|
worker results, and historical overlay generations were not deleted.
|
|
|
|
## Resource boundary
|
|
|
|
Artifact publication, fetch, hashing, and restoration are sequential and use a
|
|
1 MiB streaming buffer. They do not start Docker or parallel workers. This is
|
|
the required operating envelope for the 14-inch 2023 MacBook Pro with 18 GiB
|
|
RAM used as the current combined operator and test host.
|