docs: document scene module trust boundary

[Brad-Edwards]

Summary

Documents the scene module trust boundary. Pulsar scene modules are trusted, repo-owned application code; lifecycle hooks execute with application privileges, runtime validation is shape-only, and there is no sandbox. The canonical position is now stated in docs/scene-trust-model.md, cross-linked from docs/asset-url-policy.md and README.md. A structural drift gate pins the documented capability surface to the live WorkbenchSceneCtx and SceneModule TypeScript interfaces so a future ctx field or lifecycle hook cannot ship undocumented. No runtime behavior or contract changes.

Requirement UIDs

• (none — bug/refactor/maintenance run; see Traceability section below)

Related Issues

Closes #102

ADR Impact

• ADR-021
• ADR-029

Changes

• Add docs/scene-trust-model.md — canonical trust-boundary policy doc. Sections: scope, trust position, what runtime validation does and does not cover, capability surface (lifecycle hooks + every WorkbenchSceneCtx field), related guardrails (PUL-Q007 source policy, asset URL policy, ADR-028 reliability boundary — each framed as narrower scope, not a sandbox), third-party/user-submitted scenes non-goal, future sandbox seam.
• Cross-link the new doc from docs/asset-url-policy.md Related section and from README.md top-level orientation so the position is reachable from both adjacent policy reading and repo entry point.
• Add tests/runtime/policy-scene-trust-model-doc.test.ts — structural drift gate. Parses src/runtime/scene-loader.ts for WorkbenchSceneCtx fields and src/runtime/scene.ts for SceneLifecycleFn-typed SceneModule members; asserts each appears in the trust-model doc as ctx.<field> / <hook>(ctx). Lifecycle hooks are derived from the live interface rather than a hardcoded list so a fourth hook added to SceneModule cannot ship undocumented.
• Land the architecture preflight design note for issue Document scene module trust boundary and sandboxing non-goals #102 at docs/design/issue-102-scene-module-trust-boundary-preflight.md and register it in the design index.

Test Plan

• make check passes (Spotless, SpotBugs, Error Prone, Checkstyle, JaCoCo)
• make policy passes (documentation/workflow guardrails)
• Unit tests / integration tests: N/A — docs-only change

No new runtime behavior; the new structural test (pnpm vitest run tests/runtime/policy-scene-trust-model-doc.test.ts) pins the doc to the live TypeScript types via parseSource from the shared source-policy.ts seam. Full pnpm lint && pnpm typecheck && pnpm test (2596 tests) passes locally. No src/ change, so no changelog.d/ fragment is required per .gc/plan-rules.md ("Pure-housekeeping diffs ... do not require a fragment. The line is 'did user-visible behavior change,' not 'are any non-docs paths in the diff.'").

Ground Control Checks

• make policy passes
• gc_evaluate_quality_gates passes or is unchanged by this repo-only change
• gc_run_sweep reviewed; findings fixed or recorded with rationale

Traceability

• IMPLEMENTS: Document scene module trust boundary and sandboxing non-goals #102 ← docs/scene-trust-model.md, Document scene module trust boundary and sandboxing non-goals #102 ← docs/asset-url-policy.md (Related cross-link), Document scene module trust boundary and sandboxing non-goals #102 ← README.md (top-level pointer)
• TESTS: Document scene module trust boundary and sandboxing non-goals #102 ← tests/runtime/policy-scene-trust-model-doc.test.ts

Checklist

• Code follows project coding standards (docs/CODING_STANDARDS.md)
• No business logic in API layer
• Domain layer has no framework imports
• Envers @Audited on new entities if applicable
• Changelog fragment: N/A — docs-only change
• Architectural docs updated if stack, package structure, or key behaviors changed

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud