[SDK post-0.1] Ship encrypted offline reads and advanced developer tooling

[BunsDev]

Blocked by:

• [SDK 0.1.0][P0] Execute the first public release and validate registry provenance #41

Completed dependency:

• [SDK 0.1.0][P1] Add non-secret profiles, redacted diagnostics, and public API governance #39

Outcome

Extend the released read-only foundation with restart-safe, bounded offline reads and polished developer tooling without creating a second canonical database or an offline mutation authority.

Scope

Offline reads

• native AES-256-GCM replaceable cache keyed from OS-keychain-held material;
• cache scoped by Cave instance ID and resource revision;
• bounded familiars/projects/conversations/transcripts only;
• explicit stale/cache versus live/Cave source state;
• canonical supersession and stale-response rejection;
• purge on Cave instance replacement;
• visible corruption/undecryptable diagnostics and explicit reset.

SDK/CLI tooling

• stable shell completions after CLI grammar is frozen;
• fixed TypeScript scaffolds for supported read-only journeys;
• scaffold compile/run tests from packed public packages;
• browser-limitations and native-boundary documentation;
• richer but still redacted diagnostic bundles;
• deterministic examples for Cave read, Coven observer, and unified status.

Architectural invariants

• Offline state is a replaceable cache, not canonical authority.
• No bearer, secret-store metadata, draft, pending mutation, idempotency key, full event stream, attachment byte, action payload, or diagnostic archive enters the cache.
• Offline mode is read-only; reconnect and fresh canonical refresh are required before any mutation.
• Scaffolds use fixed reviewed templates, never arbitrary remote code.
• Existing non-empty or symlinked scaffold destinations fail closed unless an explicit safe policy is approved.

Dependencies and blockers

• Released and stable read DTO/revision semantics
• Public profiles/diagnostics/API governance from [SDK 0.1.0][P1] Add non-secret profiles, redacted diagnostics, and public API governance #39
• Native keychain and filesystem boundary shared with Chat
• Approved cache size/retention limits

Acceptance criteria

• Cache encryption uses a fresh nonce per write and authenticated instance/version metadata.
• Plaintext, secrets, and excluded resource classes are absent from cache bytes.
• Tamper, wrong key, schema mismatch, oversize, interrupted replacement, and instance mismatch fail safely.
• Cached data is always marked stale and cannot overwrite newer canonical revisions.
• Offline writes remain disabled.
• Completions exactly match the released command grammar.
• Scaffolds never overwrite unsafe/non-empty destinations and compile from exact tarballs.
• Browser limitations and required native trust/custody boundaries are documented.
• Diagnostics remain bounded and redacted across every output format.

Validation

Rust/native encryption tests, plaintext scans, cache ordering/fault tests, reconnect journeys, scaffold destination attacks, packed-template builds, completion golden tests, and a dedicated security review of native storage.

Non-goals

No offline send queue, conflict-free replicated canonical store, cloud sync, bearer cache, arbitrary template download, shell execution, or privileged action while offline.