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-native-desktop/docs/adr/0006-compiled-gls-protocol-runtime.md

4.9 KiB
Raw Blame History

ADR 0006: Compiled GLS protocol runtime

  • Status: accepted for the next HoloLake desktop candidate
  • Date: 2026-08-17

Context

REPO-012 contains dozens of numbered GLS protocol sources. Human-readable source is necessary for authorship, review and causal meaning, but asking a model to reread protocol prose for every operation does not make the software obey the protocol. It also creates non-deterministic behavior and makes it impossible to distinguish a protocol that is merely present from one that is enforced by the running product.

Decision

Compile the current numbered GLS sources into a deterministic v2 runtime manifest pinned to an exact REPO-012 commit. Every selected source records its stable GLS number, path and SHA-256. Duplicate historical source locations are resolved by a deterministic source preference, while alternate-source counts remain visible. The compiler also reconciles the protocol registry, GLS entry, source manifest, architecture catalog and routing references, preserving their independent source hashes and rejecting registration conflicts.

Legacy depends arrays are not silently interpreted as runtime edges. Bootstrap Compiler v1 classifies every source edge as NORMATIVE_REFERENCE, SCHEMA_IMPORT, BUILD_REQUIRES, BOOT_REQUIRES, RECOVERY_REQUIRES or EVIDENCE_ONLY; all remain audit-only. Only dependencies declared by an explicit executable projection enter the runtime graph as RUNTIME_REQUIRES; that graph must be acyclic and dependency-closed. The current exact source produces 183 typed source edges and zero unclassified edges.

An executable projection requires an explicit native adapter, event kinds, dependency list and fail-closed behavior. The compiler rejects missing executable dependencies and dependency cycles. The native runtime revalidates schema, source commit, counts, hashes, adapters and dependency closure before returning a protocol set to an organ.

Protocol prose is never evaluated as code. A protocol without an explicit projection remains INVENTORIED_NOT_EXECUTABLE. The product now embeds 25 dependency-closed projections: four P0 foundation contracts and 21 P1-P6 protocol organs. They provide the strict GLP codec, identity/context guards, hash-chain decision ledger, session/heartbeat/work-order/witness rules, causal time/memory/state guards, module/lifecycle/scheduler/control state machines, external/model/temporary-capability boundaries and the restricted HLDP-NP → GIR bootstrap compiler.

The kernel is an application-start prerequisite. If its embedded contract, projection closure, deterministic compiler self-check or local receipt/state ledger cannot load, HoloLake fails closed during startup. Receipt append and state-machine transition use one immediate SQLite transaction, so stale work-order/lifecycle transitions, conflicting time or broadcast owners, immutable module replacement and cross-owner runway release cannot race past the guards. Concurrent memory/state inputs are stored as conflicts rather than overwritten. The ledger stores per-user receipts and projections in application data; protocol authority and enforcement code are compiled into the signed application bundle and do not depend on the development machine.

P7 is intentionally different: the application embeds an 11-item target capability assembly registry for GLS-0836 and GLS-0840–0849, but records zero desktop physical capabilities as verified. Evidence from BS-SH-005 or JD-FD-PRIMARY is never transferred into desktop health. A target becomes active only after its own version-bound evidence exists.

Why

This creates the same hard boundary that a real API presents: a caller must satisfy the machine contract whether or not it has read the explanatory documentation. It also preserves factual honesty. HoloLake reports 75 inventoried sources, 25 native enforcement projections and 50 non-executable sources separately.

Rejected alternatives

  • Injecting all GLS prose into every model call: behavior would remain prompt-dependent and context growth would be unbounded.
  • Treating every inventoried source as automatically active: source presence is not runtime enforcement.
  • Executing scripts embedded in protocol documents: it would turn the authority source into an arbitrary-code supply chain.
  • Hand-copying protocol decisions into unrelated organs: duplicated rules would drift and no common protocol set could be written into receipts.
  • Blocking the product until all protocols are executable: incremental dependency-closed projections can be verified without overstating the remaining surface.

Evidence

  • scripts/compile-gls-runtime-registry.mjs
  • contracts/gls-executable-projections.json
  • contracts/gls-runtime-registry.json
  • src-tauri/src/gls_protocol_runtime.rs
  • src-tauri/src/gls_protocol_kernel.rs
  • src-tauri/src/gls_bootstrap_compiler.rs
  • contracts/gls-native-runtime-kernel.json
  • src-tauri/src/zero_core_numbering.rs
  • scripts/gls-protocol-runtime.test.mjs