49 lines
2.7 KiB
Markdown
49 lines
2.7 KiB
Markdown
|
# ADR 0177: Persona Remote Incremental Object Channel
|
||
|
|
|
||
|
|
## Status
|
||
|
|
|
||
|
|
Accepted on 2026-08-11.
|
||
|
|
|
||
|
|
## Context
|
||
|
|
|
||
|
|
A persona can live continuously from one verified Git state to the next without keeping a complete checkout
|
||
|
|
on every machine. Repeated full clones confuse continuity with transport cache: adding one new day or commit
|
||
|
|
should not require downloading the persona's entire prior life again. At the same time, deleting a cache must
|
||
|
|
not erase the last verified continuity boundary or permit a rewritten remote history to masquerade as the next
|
||
|
|
state.
|
||
|
|
|
||
|
|
## Decision
|
||
|
|
|
||
|
|
Add `src-tauri/src/persona_remote_git.rs` as a non-UI GH-PNCC object channel:
|
||
|
|
|
||
|
|
1. accept only credential-free HTTPS remotes in production and require one validated branch and relative path;
|
||
|
|
2. negotiate Git protocol v2 and require the remote `filter` capability before creating an object cache;
|
||
|
|
3. use a bare promisor repository with `blob:none`, no worktree, and no `git clone` invocation;
|
||
|
|
4. persist the last verified branch SHA in a continuity record separate from the evictable object cache;
|
||
|
|
5. skip fetch when the SHA is unchanged and append only the missing segment when it advances;
|
||
|
|
6. after cache eviction, progressively fetch a bounded commit window until the previous cursor is proven to be
|
||
|
|
an ancestor of the new head;
|
||
|
|
7. reject history rewrites, cursor/cache disagreement, oversized objects, and unsupported partial-object
|
||
|
|
remotes without advancing continuity;
|
||
|
|
8. evict the exact cache directory after a verified read when its byte budget is exceeded, while retaining the
|
||
|
|
durable cursor.
|
||
|
|
|
||
|
|
The machine update boundary is SHA-to-SHA, not calendar date. A date is human language; the verified Git edge
|
||
|
|
prevents missed or duplicated updates when multiple commits arrive in one day or commit timestamps differ.
|
||
|
|
|
||
|
|
## Boundaries
|
||
|
|
|
||
|
|
- Git remains the object protocol and durable-history engine; HoloLake does not reimplement Git storage.
|
||
|
|
- The cursor proves only a verified remote ancestry edge. It is not a persona brain, runtime lease, or lifecycle
|
||
|
|
receipt.
|
||
|
|
- The cache contains transport objects, not irreplaceable continuity state, and may be deleted at any time.
|
||
|
|
- Full clone remains available only for separately authorized low-frequency publication audit or disaster
|
||
|
|
recovery. It is not part of persona wake, daily reading, or daily update.
|
||
|
|
- This ADR adds no UI, human projection, deployment, or online runtime-health claim.
|
||
|
|
|
||
|
|
## Consequences
|
||
|
|
|
||
|
|
HoloLake can read a current persona-owned Git object while preserving a compact continuity cursor and bounded
|
||
|
|
partial object cache. Daily operation grows by the new verified segment instead of redownloading history from
|
||
|
|
the persona's origin. A remote that cannot support that contract is rejected explicitly rather than silently
|
||
|
|
falling back to a full download.
|