From 835b727856cf193c165416e869626a41bc9d8f8f Mon Sep 17 00:00:00 2001
From: ggbdpq <ggbdpq@gmail.com>
Date: Sat, 5 Sep 2026 00:25:27 +0800
Subject: [PATCH 1/2] docs(architecture): audit Sandbox and privacy group
 against implementation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Audit the four Sandbox and privacy documents from the #3522
documentation audit against the current implementation (22715e84f).

workspace-privacy-context.md: one drift fixed — the authority section
still named `getWorkspacePrivacyContext()` / `defaultWorkspacePrivacyContext()`
in `apps/desktop/src/main/main.ts`; neither function exists any more
and `main.ts` carries no privacy logic. The effective state is the
Runtime Host runtime policy (`runtime-policy.ts` declares the readonly
`privacy.incognitoActive` and defaults it to false, patched through the
policy codec), desktop surfaces resolve it via `queryRuntimePolicy()`,
and core boundaries validate the projection with the unchanged
`validateWorkspacePrivacyContext()`. The section and the consumer
inventory sentence now describe that chain.

windows-sandbox-rfc-v1.md + zh-CN: no drift. The pair stays in lockstep
(twelve sections and five guarantee subsections 1:1); the status claims
hold (#2961 merged 2026-08-17, the AppContainer filesystem-worker
enforcement on the tree, the contract constants in
`packages/core/src/sandbox-boundary.ts`). Frontmatter added to both.

permission-onboarding-plan.md: no drift. Stage 1 files exist as named
(`permission-overlay-controller.ts` and the `src/overlay/` shell),
`permissions-actions.ts` still deep-links, and tracking issue #4328 is
open. Frontmatter added.

All four documents gained the standard frontmatter block with
`last_verified` (the RFC pair keeps `translation_status: synced`).

Refs #3522

Generated-by: GLM-5.3-Flash (ZCode)
---
 docs/architecture/windows-sandbox-rfc-v1.md   | 12 ++++++++++
 .../windows-sandbox-rfc-v1.zh-CN.md           | 12 ++++++++++
 docs/permission-onboarding-plan.md            | 12 ++++++++++
 docs/workspace-privacy-context.md             | 22 ++++++++++++++-----
 4 files changed, 53 insertions(+), 5 deletions(-)

diff --git a/docs/architecture/windows-sandbox-rfc-v1.md b/docs/architecture/windows-sandbox-rfc-v1.md
index afd0433c98..11691b85b0 100644
--- a/docs/architecture/windows-sandbox-rfc-v1.md
+++ b/docs/architecture/windows-sandbox-rfc-v1.md
@@ -1,3 +1,15 @@
+---
+doc_id: architecture.windows-sandbox-rfc-v1
+title: "Windows sandbox RFC v1"
+language: en
+source_language: en
+implementation_status: current
+document_status: current
+translation_status: synced
+last_verified: 2026-09-04
+owners:
+  - maka-backend
+---
 <!--
   Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
diff --git a/docs/architecture/windows-sandbox-rfc-v1.zh-CN.md b/docs/architecture/windows-sandbox-rfc-v1.zh-CN.md
index e525a8cebc..f0b2c27c88 100644
--- a/docs/architecture/windows-sandbox-rfc-v1.zh-CN.md
+++ b/docs/architecture/windows-sandbox-rfc-v1.zh-CN.md
@@ -1,3 +1,15 @@
+---
+doc_id: architecture.windows-sandbox-rfc-v1
+title: "Windows sandbox RFC v1"
+language: zh-CN
+source_language: en
+implementation_status: current
+document_status: current
+translation_status: synced
+last_verified: 2026-09-04
+owners:
+  - maka-backend
+---
 <!--
   Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
diff --git a/docs/permission-onboarding-plan.md b/docs/permission-onboarding-plan.md
index a372febe49..2876fba36b 100644
--- a/docs/permission-onboarding-plan.md
+++ b/docs/permission-onboarding-plan.md
@@ -1,3 +1,15 @@
+---
+doc_id: permission-onboarding-plan
+title: "Drag-to-grant permission onboarding (macOS)"
+language: en
+source_language: en
+implementation_status: current
+document_status: current
+translation_status: source-only
+last_verified: 2026-09-04
+owners:
+  - maka-backend
+---
 <!--
   Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
diff --git a/docs/workspace-privacy-context.md b/docs/workspace-privacy-context.md
index 1d75db64d3..a2c9dfb745 100644
--- a/docs/workspace-privacy-context.md
+++ b/docs/workspace-privacy-context.md
@@ -1,3 +1,15 @@
+---
+doc_id: workspace-privacy-context
+title: "Workspace privacy context"
+language: en
+source_language: en
+implementation_status: current
+document_status: current
+translation_status: source-only
+last_verified: 2026-09-04
+owners:
+  - maka-backend
+---
 <!--
   Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
@@ -29,21 +41,21 @@ export interface WorkspacePrivacyContext {
 
 ## Authority
 
-The main process owns the effective workspace privacy state. Renderers may request a change and display the current value, but a renderer-provided value is never proof of the effective state.
+The Runtime Host owns the effective workspace privacy state as runtime policy. Renderers may request a change and display the current value, but a renderer-provided value is never proof of the effective state.
 
 The current authority path is:
 
 - `apps/desktop/src/renderer/settings/general-settings-page.tsx` requests settings changes.
-- `apps/desktop/src/main/main.ts` resolves the effective state through `getWorkspacePrivacyContext()`.
-- Main-process consumers receive that resolved context rather than trusting renderer input.
+- The effective state is the Runtime Host runtime policy: `packages/core/src/runtime-policy.ts` declares the readonly `privacy.incognitoActive` field and defaults it to `false`; patches are validated by the policy codec's `privacy patch` record rule.
+- Desktop surfaces resolve the effective state from the policy via `queryRuntimePolicy()` (for example `apps/desktop/src/main/runtime-host-search-ipc-main.ts`), and core-boundary consumers validate the projected context through `validateWorkspacePrivacyContext()` (`packages/core/src/incognito.ts`) before reading any field.
 
-`defaultWorkspacePrivacyContext()` returns `{ incognitoActive: false }` for explicit initialization. `validateWorkspacePrivacyContext()` rejects malformed input; it never converts missing or invalid data to `false`. Boundaries that cannot resolve a valid authoritative context must fail closed.
+`validateWorkspacePrivacyContext()` rejects malformed input; it never converts missing or invalid data to `false`. Boundaries that cannot resolve a valid authoritative context must fail closed.
 
 ## Consumer rule
 
 `incognitoActive: false` only means that incognito mode did not block the operation. It is not general permission to read, write, search, capture, or transmit data. Every consumer must still apply its own settings, permission, and retention rules.
 
-When `incognitoActive` is true, each privacy-sensitive consumer defines a fail-closed result at its existing main-process boundary. The composition in `apps/desktop/src/main/main.ts` and focused consumer tests own the current inventory. Do not duplicate that inventory here, add another incognito flag, copy the state into a parallel store, or let a renderer self-attest.
+When `incognitoActive` is true, each privacy-sensitive consumer defines a fail-closed result at its existing main-process boundary. The Runtime Host composition, the desktop main-process consumers, and their focused tests own the current inventory. Do not duplicate that inventory here, add another incognito flag, copy the state into a parallel store, or let a renderer self-attest.
 
 ## Contract changes
 

From 012ca953b52b0bc56403ac7aa6d6dcc853472d7b Mon Sep 17 00:00:00 2001
From: ggbdpq <ggbdpq@gmail.com>
Date: Sat, 5 Sep 2026 20:58:59 +0800
Subject: [PATCH 2/2] docs: record the notification-gate exception to the
 workspace privacy authority

Review (hqhq1025) found the authority migration claim incomplete:
notifications-ipc-main.ts still reads privacy.incognitoActive from the local
settings store, which never receives privacy patches (settings-ownership.ts
excludes them), so the run-ended notification can raise the session title and
reply preview under a just-enabled incognito setting. Record this consumer as
the one documented deviation instead of claiming the migration is complete;
migrating the gate to the policy authority is a named follow-up issue.

Generated-by: GLM-5.3-Flash (ZCode)
---
 docs/workspace-privacy-context.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/docs/workspace-privacy-context.md b/docs/workspace-privacy-context.md
index a2c9dfb745..d6d7541ffb 100644
--- a/docs/workspace-privacy-context.md
+++ b/docs/workspace-privacy-context.md
@@ -49,6 +49,8 @@ The current authority path is:
 - The effective state is the Runtime Host runtime policy: `packages/core/src/runtime-policy.ts` declares the readonly `privacy.incognitoActive` field and defaults it to `false`; patches are validated by the policy codec's `privacy patch` record rule.
 - Desktop surfaces resolve the effective state from the policy via `queryRuntimePolicy()` (for example `apps/desktop/src/main/runtime-host-search-ipc-main.ts`), and core-boundary consumers validate the projected context through `validateWorkspacePrivacyContext()` (`packages/core/src/incognito.ts`) before reading any field.
 
+One documented exception: the run-ended notification gate (`apps/desktop/src/main/notifications-ipc-main.ts`) still reads `privacy.incognitoActive` from the local settings store, and privacy patches never reach that store (`apps/desktop/src/shared/settings-ownership.ts` excludes `privacy` from the local patch), so the gate keeps seeing the stale or default value after incognito is enabled and can raise a notification carrying the session title and reply preview. Migrating this gate to the policy authority is a named follow-up; until it lands, this gate is the one documented deviation from the rule above.
+
 `validateWorkspacePrivacyContext()` rejects malformed input; it never converts missing or invalid data to `false`. Boundaries that cannot resolve a valid authoritative context must fail closed.
 
 ## Consumer rule