bingshuo/hololake-system-architecture
Watch
1
0
Fork
You've already forked hololake-system-architecture
 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity
hololake-system-architecture/product-source/hololake-platform/docs/adr/0173-mobile-git-knowledge-and-device-secret-boundary.md

3.3 KiB
Raw Blame History

ADR 0173: Mobile Git knowledge and device-secret boundary

Status

Accepted for the next HoloLake Era iOS internal build.

Context

The mobile client cannot reuse a desktop folder picker, a desktop Git process, or a plaintext provider-secret file. Treating the app-owned knowledge lake as a renamed Tolaria vault also leaves first launch, repository synchronization, and the knowledge Agent without a truthful mobile execution path.

HoloLake needs three different stores whose boundaries remain visible:

  1. a bundled foundation world that can open offline;
  2. normal Markdown knowledge that can synchronize with the registered Guanghu code-channel repository;
  3. device-only credentials that must never enter Markdown, Git, model context, logs, receipts, archives, or server synchronization.

Decision

  • iOS creates and opens managed knowledge directories inside the application sandbox. It never invokes the unsupported mobile folder picker.

  • The foundation world is seeded locally and is not evidence of a server connection, authenticated identity, persona residency, or repository synchronization.

  • A synchronized personal lake contains a typed .hololake-sync-policy.json. Normal Markdown pages are eligible for synchronization. 本地密钥/**, .hololake-*, and .git/** are excluded.

  • Email OTP creates a short, device-bound HoloLake session. The production token is stored in iOS Keychain with AccessibleWhenUnlockedThisDeviceOnly and synchronization disabled. The metadata file contains only a stable handle, device id, and expiry.

  • User-supplied model keys use the same device-only Keychain protection. Server-supplied model keys never leave the server.

  • The mobile model target uses the existing bounded knowledge-Agent tool contract. It may search and read the active lake and create or replace a normal Markdown page.

  • A synchronized create or edit is complete only after the server atomically advances the registered bare repository from the exact previous main commit and returns the new 40-character commit plus content SHA-256. A conflict or missing receipt rolls back the local mutation.

  • The server accepts only bounded Markdown paths and content. Traversal, non-Markdown paths, 本地密钥, oversized content, and stale base commits fail closed. Receipts never echo page content.

  • Deletion from a synchronized lake remains disabled until it has the same atomic server receipt and rollback semantics.

  • The model is not an authority. The execution sequence remains:

    human event and real state
→ constrained model request
→ native allowlisted knowledge executor
→ local filesystem result
→ atomic repository update
→ verifiable commit receipt

Consequences

  • Mobile and desktop share Markdown semantics without pretending their storage and credential environments are identical.
  • The knowledge Agent can perform useful read/write work on iOS while every external mutation still has a native receipt.
  • A server outage leaves local knowledge readable but makes synchronized writes fail closed.
  • A TestFlight archive or an App Store Connect upload is not proof of this capability. Acceptance requires iOS compilation, automated non-leak tests, deployed server health, repository readback, and a real-device TestFlight run.