docs: complete lease broker architecture slice
This commit is contained in:
Jason Woltje
@@ -7,6 +7,8 @@ This chapter is the canonical home for Mosaic Stack's system model, component bo
|
||||
## Promoted pages
|
||||
|
||||
- [`lease-broker-protocol.md`](lease-broker-protocol.md) — authenticated Unix-socket protocol, identity binding, framing, persistence, and lease transitions.
|
||||
- [`lease-broker-security.md`](lease-broker-security.md) — identity, ancestry, filesystem, whole-class, observer, and named residual security boundaries.
|
||||
- [`mutator-class-gate.md`](mutator-class-gate.md) — default-deny tool authorization, runtime adapters, launch choke point, and parser assurance boundary.
|
||||
- [`compaction-revocation.md`](compaction-revocation.md) — Claude/Pi observer lifecycle, runtime generations, revocation, and the bounded residual stale window.
|
||||
|
||||
These pages are current security-contract references and are consumed by the lease-broker acceptance suites. Their live deployment gaps remain explicitly labeled in the pages; this migration does not change runtime behavior.
|
||||
|
||||
+4
@@ -1,5 +1,9 @@
|
||||
# WI-1 lease broker security notes
|
||||
|
||||
> **Status:** Current contract reference.
|
||||
> **Audience:** Developer and security reviewer.
|
||||
> **Evidence:** The lease-broker implementation and acceptance material cross-check this boundary; deployment-review requirements remain explicitly labeled below.
|
||||
|
||||
- Trusted identity comes only from Linux `SO_PEERCRED` plus `/proc` starttime, never request identity fields.
|
||||
- Descendant authorization is anchored to `(pid,starttime)` and uses a complete second starttime pass to fail closed on disappearance or PID-reuse races.
|
||||
- Runtime generations are monotonic per anchor; a bump revokes prior-incarnation tokens before persistence commits. WI-3 stores the live generation in an owner-only locked file so same-PID Pi reload/new/resume/fork and Claude resume/clear transitions cannot inherit a VERIFIED lease.
|
||||
+4
@@ -1,5 +1,9 @@
|
||||
# Whole mutator-class lease gate
|
||||
|
||||
> **Status:** Current contract reference.
|
||||
> **Audience:** Developer and security reviewer.
|
||||
> **Evidence:** Runtime launch-guard and mutator-gate tests cross-check this boundary; parser residuals and deployment gaps remain explicitly labeled below.
|
||||
|
||||
WI-2 adds the framework-native authorization boundary for Claude (including the supported Claudex overlay) and Pi. Every runtime-reported tool name reaches the lease broker before execution. The gate classifies capabilities by the whole tool class; it never parses a Bash command to decide whether that particular string looks read-only.
|
||||
|
||||
## Default-deny policy
|
||||
+4
-2
@@ -10,6 +10,8 @@
|
||||
- [Developer guide index](DEVELOPER-GUIDE/README.md) — partially migrated contributor and architecture documentation.
|
||||
- [Architecture index](DEVELOPER-GUIDE/architecture/README.md) — system design, security contracts, decisions, and RFCs.
|
||||
- [Lease-broker protocol](DEVELOPER-GUIDE/architecture/lease-broker-protocol.md) — authenticated runtime lease-broker protocol and persistence boundary.
|
||||
- [Lease-broker security notes](DEVELOPER-GUIDE/architecture/lease-broker-security.md) — identity, ancestry, filesystem, and residual security boundaries.
|
||||
- [Whole mutator-class gate](DEVELOPER-GUIDE/architecture/mutator-class-gate.md) — default-deny tool authorization and launch choke point.
|
||||
- [Compaction revocation lifecycle](DEVELOPER-GUIDE/architecture/compaction-revocation.md) — Claude/Pi lifecycle observers, generation fencing, and residual boundary.
|
||||
- [API documentation index](API/README.md) — scaffold for the consolidated gateway contract.
|
||||
- [Documentation catalog and truth audit](reports/documentation/2026-08-10-docs-catalog-audit.md) — evidence and migration recommendations.
|
||||
@@ -25,8 +27,8 @@ Canonical pages added to a book must be linked from that book's README and this
|
||||
- [Internal broker protocol](DEVELOPER-GUIDE/architecture/lease-broker-protocol.md) — kernel identity, ancestry and generation invariants, framed requests, responses, and persisted cycle bindings.
|
||||
- [Broker operations](guides/lease-broker-operations.md) — protected paths, startup, constrained recovery, fail-closed posture, distinct-principal deployment, and residual risk.
|
||||
- [Constrained recovery skill](../packages/mosaic/framework/skills/mosaic-context-refresh/SKILL.md) — source-resident thin wrapper, receipt scope, C4 replay boundary, and T-C middle-drop disclosure.
|
||||
- [Lease-broker security notes](architecture/lease-broker-security.md) — identity, whole-class authorization, threat boundaries, and coordinator review requirements.
|
||||
- [Whole mutator-class gate](architecture/mutator-class-gate.md) — default-deny policy, revoke-first/promote-last state machine, TTL, runtime adapters, and T-B/T-C assurance boundary.
|
||||
- [Lease-broker security notes](DEVELOPER-GUIDE/architecture/lease-broker-security.md) — identity, whole-class authorization, threat boundaries, and coordinator review requirements.
|
||||
- [Whole mutator-class gate](DEVELOPER-GUIDE/architecture/mutator-class-gate.md) — default-deny policy, revoke-first/promote-last state machine, TTL, runtime adapters, and T-B/T-C assurance boundary.
|
||||
- [Compaction revocation lifecycle](DEVELOPER-GUIDE/architecture/compaction-revocation.md) — Claude/Pi observer matrix, same-PID generation rollover, failure fencing, and the named bounded residual stale window.
|
||||
|
||||
## CLI and skill management
|
||||
|
||||
@@ -36,7 +36,7 @@ The four isolated worktrees were clean and removed after report collection.
|
||||
- [x] Archive the contradicted TUI PRD/task pair with unchanged content and an explicit archive index.
|
||||
- [x] Create and promote the verified user quickstart from the empty root placeholder.
|
||||
- [x] Rewrite and promote the SSO administrator runbook from current auth/web source evidence.
|
||||
- [x] Promote the lease-broker protocol and compaction-revocation contracts with their acceptance-test path consumers.
|
||||
- [x] Promote the lease-broker protocol, security, mutator-gate, and compaction-revocation contracts with their navigation and acceptance-test consumers.
|
||||
|
||||
## Initial findings
|
||||
|
||||
@@ -55,7 +55,7 @@ The four isolated worktrees were clean and removed after report collection.
|
||||
- `PRD-TUI_Improvements.md` and `TASKS-TUI_Improvements.md` had no live source/test dependencies beyond their internal relative link; both moved unchanged to `docs/archive/tui/`, and `docs/archive/README.md` labels them historical.
|
||||
- The empty `docs/QUICKSTART.md` placeholder was replaced by `docs/USER-GUIDE/getting-started/quickstart.md`, based on verified installer, wizard, CLI, and runtime-safety behavior. The page explicitly excludes held PostgreSQL/source-checkout routes.
|
||||
- The SSO guide now documents Authentik/WorkOS/Keycloak discovery, OIDC callbacks, Keycloak SAML fallback, partial-config failures, and the absence of frontend feature flags. The root guide and stale `.env.example` flags were removed.
|
||||
- The lease-broker acceptance suites directly consumed two quarantined `docs/architecture/` paths; promoting the protocol and compaction-revocation contracts to `DEVELOPER-GUIDE/architecture/` and updating those consumers restored the intended contract paths without changing runtime behavior.
|
||||
- The lease-broker acceptance suites directly consumed two quarantined `docs/architecture/` paths; promoting the protocol, security, mutator-gate, and compaction-revocation contracts to `DEVELOPER-GUIDE/architecture/` and updating those consumers restored the intended contract family without changing runtime behavior.
|
||||
|
||||
## Method
|
||||
|
||||
@@ -75,22 +75,22 @@ The four isolated worktrees were clean and removed after report collection.
|
||||
|
||||
## Verification log
|
||||
|
||||
| Check | Result |
|
||||
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| File inventory | PASS — 11 root files, 269 archived files, plus task artifacts |
|
||||
| Initial link audit | FINDING — 219 links, 98 unresolved |
|
||||
| Code-surface audit | PASS — corrected manifest/script and legacy-reference scans; first attempt was discarded due to a `require()` path bug |
|
||||
| Truth probes | PASS — root docs, SSO, performance, TUI, OpenAPI, and source-path evidence triaged |
|
||||
| Final report | Written — `docs/reports/documentation/2026-08-10-docs-catalog-audit.md` |
|
||||
| Scoped commit | PASS — audit plan, report, and scratchpad committed together; `.mosaic/orchestrator/*` remains outside the commit |
|
||||
| Report formatting and scope | PASS — `pnpm exec prettier --ignore-path /dev/null --check` passed; ignored report path identified and force-add is required |
|
||||
| Commit hook behavior | FINDING — lint-staged emitted an ignored `docs/reports` path error during commit even though the report was force-staged; remediation remains open |
|
||||
| Index scaffold | PASS — six indexes formatted, all new Markdown/wikilinks resolve, and target directories exist; legacy pages were not changed |
|
||||
| Sitemap scaffold | PASS — additive current section is formatted, all seven links resolve, and legacy sections are unchanged |
|
||||
| First migration selection | PASS — P8-003 report selected as a no-rewrite evidence migration; live references identified before move |
|
||||
| P8-003 migration | PASS — destination is byte-identical, live references were updated, formatting and navigation checks pass, and only the scoped migration files are pending commit |
|
||||
| TUI archive migration | PASS — both pages are byte-identical, internal links and archive navigation resolve, formatting passes, and only the scoped archive files are pending commit |
|
||||
| Quickstart migration | PASS — current page content is source-checked, held routes are labeled, navigation resolves, root placeholder is removed, and formatting passes |
|
||||
| SSO migration | PASS — auth/gateway/web SSO tests pass (15+2+2), source claims and navigation resolve, obsolete env flags are removed, and the root guide is retired |
|
||||
| Parallel Pi audits | PASS — four requested `openai-codex/gpt-5.6-luna:max` read-only lanes completed in clean isolated worktrees; no agent changes were imported |
|
||||
| Lease-broker architecture | PASS — two contract pages promoted, two source/test consumers and navigation updated, 20/20 Vitest acceptance tests passed, and the 3-test Python portability suite passed |
|
||||
| Check | Result |
|
||||
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| File inventory | PASS — 11 root files, 269 archived files, plus task artifacts |
|
||||
| Initial link audit | FINDING — 219 links, 98 unresolved |
|
||||
| Code-surface audit | PASS — corrected manifest/script and legacy-reference scans; first attempt was discarded due to a `require()` path bug |
|
||||
| Truth probes | PASS — root docs, SSO, performance, TUI, OpenAPI, and source-path evidence triaged |
|
||||
| Final report | Written — `docs/reports/documentation/2026-08-10-docs-catalog-audit.md` |
|
||||
| Scoped commit | PASS — audit plan, report, and scratchpad committed together; `.mosaic/orchestrator/*` remains outside the commit |
|
||||
| Report formatting and scope | PASS — `pnpm exec prettier --ignore-path /dev/null --check` passed; ignored report path identified and force-add is required |
|
||||
| Commit hook behavior | FINDING — lint-staged emitted an ignored `docs/reports` path error during commit even though the report was force-staged; remediation remains open |
|
||||
| Index scaffold | PASS — six indexes formatted, all new Markdown/wikilinks resolve, and target directories exist; legacy pages were not changed |
|
||||
| Sitemap scaffold | PASS — additive current section is formatted, all seven links resolve, and legacy sections are unchanged |
|
||||
| First migration selection | PASS — P8-003 report selected as a no-rewrite evidence migration; live references identified before move |
|
||||
| P8-003 migration | PASS — destination is byte-identical, live references were updated, formatting and navigation checks pass, and only the scoped migration files are pending commit |
|
||||
| TUI archive migration | PASS — both pages are byte-identical, internal links and archive navigation resolve, formatting passes, and only the scoped archive files are pending commit |
|
||||
| Quickstart migration | PASS — current page content is source-checked, held routes are labeled, navigation resolves, root placeholder is removed, and formatting passes |
|
||||
| SSO migration | PASS — auth/gateway/web SSO tests pass (15+2+2), source claims and navigation resolve, obsolete env flags are removed, and the root guide is retired |
|
||||
| Parallel Pi audits | PASS — four requested `openai-codex/gpt-5.6-luna:max` read-only lanes completed in clean isolated worktrees; no agent changes were imported |
|
||||
| Lease-broker architecture | PASS — four contract pages promoted, two source/test consumers and navigation updated, 20/20 Vitest acceptance tests passed, and the 3-test Python portability suite passed |
|
||||
|
||||
Reference in New Issue
Block a user