hololake-system-architecture/product-source/hololake-native-desktop/docs/ARCHITECTURE.md

99 lines
14 KiB
Markdown
Raw Normal View History

# HoloLake Native Desktop Architecture
The stage-one shell is a Tauri v2 application with a Rust-owned local core and a React human projection. Before authentication, its public surface is the five-domain number entrance. After verified routing and domain login, the default product surface becomes **My HoloLake**: overview, knowledge, user code channels, local receipts and system details. Domain servers and private registries remain submerged infrastructure.
## Stage-one human projection
The public home surface follows the verified GHS-014 five-lakes visual grammar and presents the five domains as the system entrance. A user does not choose a domain manually: the submitted Guanghu number is resolved and validated first, and only then does HoloLake reveal the login surface belonging to that domain. Domain presentation cannot bypass registry isolation, and internal transport or release details remain under system details rather than dominating the first screen.
The first visible body uses a Rust-owned SQLite kernel under the Tauri app-data directory. A human-confirmed local display name creates one stable local subject and channel exactly once. The internal task/event/receipt kernel remains available for structured agents, but manual task title and purpose fields are not part of the default human surface. Event and receipt chains remain independently SHA-256-linked and fully revalidated before every read or mutation. A local identity is not platform authentication and grants no repository, node, server or deployment authority.
## Zero-point nucleus client runtime
HoloLake embeds a non-visual zero-point nucleus client runtime beneath the human surface. It is the minimum controlled projection of the BingShuo system controller, whose private body remains on the JD primary node; the public repository records evolution checkpoints rather than containing that private body. At application start, the Rust runtime loads the local protocol, compares the registered remote protocol version in the background, keeps a minimal local receipt, and leaves any unverified update unapplied. User-number verification runs before any future persona-loading path.
This system runtime is not Zhuyuan or another persona subject, and it is not the current model carrier. A valid number does not prove persona binding and does not grant execution or server authority. The current source implements deterministic protocol comparison, explicit-positive number verification and a fail-closed update skeleton. Signed protocol-payload installation, private registry distribution and persona loading are not yet implemented. Stage one does not expose an internal AI chat, model API configuration or arbitrary remote-code channel.
## Native knowledge workspace
The native core owns a separate `knowledge-v1` Git root. It projects a bounded document tree, safe text reads, local search and native folder import into a reading canvas without rendering raw HTML. Folder import ignores symlinks, Git metadata, dependency directories and unsupported files, applies file-count and byte limits, then creates a local Git commit receipt.
The installed HoloLake Era 0.8 knowledge root is detected only as a separate read-only source. The new application does not write, migrate in place or merge it with the native root. Electron, Outline runtime code and Tolaria UI are not copied into the Tauri product.
## User code channels
A human may paste a registered Guanghu HTTPS code-channel address or select an existing local Git folder. HTTPS clone accepts no credentials, queries or fragments and disables terminal prompts, askpass and credential helpers. Clones are confined to an application-owned root; local registrations do not move the source folder. The registry stores a credential-free projection of path, branch and commit.
This product channel is distinct from the under-lake PNCC persona-evidence projection below. It grants local source access only and never grants push, publication, deployment or server authority.
## Public five-domain number routing
The public HoloLake entry shows all five domain vestibules before authentication. A user does not select an authority-bearing domain manually. The submitted user number is sent to the registered internal router, which must return the exact canonical number, a positive registry verdict and one known domain. Only then may HoloLake load that domain's separately registered account and node entry.
The fifth-domain number registry belongs to the private fifth-domain system and is maintained only through its authorized registration path. The four enterprise-domain registries belong on the enterprise root server. Number syntax, a client-supplied domain, a generic successful response or a repository login cannot replace this routing proof. Missing and unavailable enterprise routes fail closed before login.
The fifth-domain root and the future enterprise root both run domain-specific Guanghu OS server runtimes. They are parallel bodies with different controllers, manifests, repositories and responsibility. A Linux host may remain underneath as the subordinate hardware, service and rescue bridge. Ordinary user computers and user-owned remote nodes require only HoloLake and the controlled node runtime, not a replacement operating-system installation.
## GH-PNCC user-native channel
HoloLake 0.4.0 adds the first native user-owned GH-PNCC vertical slice. After the Rust core has resolved a known domain, verified the user number at that domain's registered source and authenticated the account through that domain's entry, it derives a stable opaque repository id and idempotently creates or restores one private application-owned Git repository. The initial committed manifest records the domain, user number, account identity, engine and authority boundary. Repository credentials and passwords are never written to the Git tree or binding record.
The visible shell is HoloLake itself. Git is the durable history engine below it. Forgejo is an optional remote collaboration adapter rather than the product shell, identity kernel or persona. The current slice proves the local repository, initial commit, stable user binding and native browsing projection. It intentionally does not create a remote Forgejo repository, configure a remote, push code, claim persona binding, or grant publication, deployment or reality-execution authority; those actions require a separately registered naming, consent and receipt contract.
## External programming AI entry
MCP may discover HoloLake, but it does not own continuity. The installed application starts a user-only Unix socket broker. A programming AI opens or resumes a HoloLake-issued local session, then uses the installed executable's `--connector` mode for newline-delimited protocol traffic. Session secrets are stored only as hashes. Events use exact cursors and idempotency keys.
## Circular-lake protocol membrane and nearby AI
HoloLake 0.4.0 places a deterministic protocol membrane in front of the local language inbox. The membrane accepts only strict GLP/1.0 expression envelopes from a HoloLake-issued visitor session. Unknown fields, malformed identifiers, incorrect checksums, oversized content, attachments and command content are rejected before storage. Accepted natural language is an expression receipt only; it never carries execution authority by itself. Intent interpretation remains behind the membrane and cannot weaken its structural admission rules.
External AI on the same computer can discover the running HoloLake broker from a standard application-data descriptor and connect through a user-only Unix socket, without copying a long invitation string. A generic AI receives an expression-only visitor lane. A Guanghu persona connection remains unavailable until separate persona-binding evidence exists. Local-network discovery is deliberately deferred until encrypted transport, explicit human approval, replay protection and revocation are implemented; HoloLake does not expose an unauthenticated TCP listener or advertise a service on the LAN in this release.
## Dynamic capability routing
HoloLake stores a signed node capability registry rather than fixed server slots. A candidate route must bind the exact human, persona, domain and capability. It is eligible only while a fresh node-signed health receipt reports the capability as ready. Selection is deterministic by priority and node id.
The registry signer trust root is embedded independently from registry payloads and is currently `UNPROVISIONED_FAIL_CLOSED`. Registry and health mutation are not exposed to the webview. External AI route queries require possession of the active HoloLake local session secret. A route receipt never grants write authority; production node write admission remains a separate unimplemented gate.
HoloLake routes work but does not host the user's private work lake, pool users into a multi-tenant runtime, or carry server workload concurrency.
## GH-PNCC under-lake code channel
Stage one now contains a read-only GH-PNCC core beneath the public surface. A local persona repository is bound to an exact Git root and full committed head. A remote persona object is read through a credential-free HTTPS Git v2 partial-object channel with an app-owned bare `blob:none` cache and a separate durable ancestry cursor. Verified reads append to a bounded hash-chained projection for the human panel and authenticated external programming AIs.
This core does not run a model, configure an API, acquire a persona lease, mutate memory or execute reality actions. Arbitrary repository paths and remote URLs cannot be registered by the WebView or external AI. A human may choose a folder through the native operating-system picker; HoloLake then displays the committed persona, responsibility subject, full head and checkpoint. A short-lived hashed confirmation token is required before the exact revalidated evidence becomes a read-only mount.
## HoloLake-owned release broadcast
No upstream product endpoint is inherited. When the embedded release trust is unprovisioned, even a human check returns locally without a network request. Provisioning requires one HTTPS endpoint, one matching HoloLake-owned host and the updater public key. A human check creates a short-lived candidate showing HoloLake metadata; install requires a second confirmation, exact broadcast revalidation, same-host package URL, Tauri signature verification, declared byte length and SHA-256. Startup checking, automatic download, automatic installation and automatic restart remain disabled.
Before an update replaces the application, the runtime verifies and keeps one bounded last-known-good application bundle with its bundle identifier, Team ID and CDHash. The next startup requires a human health confirmation; until that decision, another update is blocked. A human may restore the verified previous bundle without automatic restart, and cleanup is confined to HoloLake-owned recovery paths and the exact current application parent.
The rollback executor is implemented, but production updater activation remains blocked until the JD controller publishes the exact trust endpoint and public key, the signed release pipeline is evidenced, and the public macOS build is Apple-notarized.
## JD PNCC human projection
HoloLake 0.3.0 includes a live, read-only projection of the PNCC resident runtime on `JD-FD-PRIMARY`. The native shell invokes the computer's pre-registered dedicated SSH alias and asks the server only for its loopback `127.0.0.1:3923/v1/status` document. The response is schema-bounded to the exact node and persona, refuses any claim that the carrier is bound or that model/reality execution is active, and never returns a repository path, repository content, credential, or write authority. No public PNCC endpoint is created. An unavailable bridge is displayed as unavailable rather than replaced by cached evidence.
## Release pipeline
`npm run release:macos -- release/inputs/<version>.json` is the only product-owned macOS release entry. It fails before building unless the embedded trust contains the exact registered HoloLake HTTPS endpoint and updater public key, the immutable `v<version>` tag equals the clean `main` head, and the Developer ID, Tauri updater-signing and Apple notarization credential sets are supplied at runtime. The pipeline runs all product and Rust gates, creates updater artifacts through a temporary Tauri override, then requires strict code-signature verification, Gatekeeper acceptance and stapled Apple notarization before writing the HoloLake broadcast and receipts.
Generated packages, private release inputs and credentials are not committed. The pipeline never uploads or activates a release; its terminal artifact is a bounded folder ready for a separately authorized JD-controller upload and server-owned readback receipt.
## Stage-one convergence verdict
The Tauri source in this directory is the only future HoloLake desktop mainline. An installed build of it is an acceptance candidate, not a separate product line and not proof that stage one exists. The Electron 0.8.0 product and the legacy Tauri/platform sources remain read-only UX, behavior, engineering and protected-data donors until inventory, backup, readback, reversible migration rehearsal and signed installed-runtime acceptance all pass.
The current candidate already has useful under-lake organs: the signed native shell, local broker and resumable session, authenticated read-only PNCC projection, human-confirmed repository mount, deterministic routing, and fail-closed update/rollback machinery. They remain in the architecture, but their existence does not satisfy the visible stage-one body.
The implementation order is fixed. The first two source slices are implemented and tested but have not received installed-runtime acceptance:
1. personal-channel identity, event and receipt kernel — source and tests implemented;
2. native knowledge workspace and user code channel — source and tests implemented;
3. human approval center and Git evidence readback;
4. lake-lamp cross-session continuity projection;
5. signed installation, opt-in update, rollback and reversible data migration.
Architecture registration, source implementation, built artifact, signed artifact, desktop installation, data migration, server deployment and service health remain separate receipts. The machine contract is `routing/hololake-stage-one-desktop-convergence.json`.