NODEDC_MISSION_CORE/docs/adr/0033-central-session-artifacts-and-bounded-host-cache.md

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:

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:

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:

<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:

MISSIONCORE_ARTIFACT_CACHE_MAX_BYTES
MISSIONCORE_ARTIFACT_CACHE_FREE_SPACE_RESERVE_BYTES

An optional shared root is configured explicitly with:

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:

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:

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:

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.