Document scene module trust boundary and sandboxing non-goals

[Brad-Edwards]

Problem

Scene modules are executable code. That is appropriate for repo-owned authored scenes, but the project should explicitly state the trust boundary so future import, authoring, plugin, or sharing workflows do not accidentally imply that untrusted scene code is safe to execute.

Proposal

Document the scene-module trust model. The default position should be explicit: Pulsar scene modules are trusted application code unless and until a separate sandbox model is designed. User-submitted or third-party scene execution is out of scope for the current runtime unless a future requirement adds isolation.

Acceptance criteria

• Add documentation stating that scene modules execute with application privileges.
• Clarify that current scene validation checks shape and metadata, not code safety.
• State that third-party/user-submitted scenes are not sandboxed by default.
• Identify APIs that scene code can affect through lifecycle hooks and context.
• Link or cross-reference asset policy and no-remote-code-execution guidance where relevant.
• Add a future-work note only if the project intends to design a sandbox model later.

[Brad-Edwards]

🛠️ Picked up by /implement — driver Claude Code, branch 102-scene-module-trust, 2026-05-23T05:56:03Z.

[Brad-Edwards]

gc workflow phase recorded: preflight (issue #102). Posted by the MCP server to enforce ordering between workflow steps (issue #794 MVP-2). Do not edit or delete — used by downstream tools to gate phase prerequisites.

[Brad-Edwards]

gc workflow phase recorded: plan (issue #102). Posted by the MCP server to enforce ordering between workflow steps (issue #794 MVP-2). Do not edit or delete — used by downstream tools to gate phase prerequisites.

Plan

Documentation-only change. No runtime behavior changes, no schema changes, no new gates.
Plan addresses every acceptance criterion in the issue body and the binding guardrails
in docs/design/issue-102-scene-module-trust-boundary-preflight.md.

Files

Add

• docs/scene-trust-model.md — single canonical trust-boundary policy doc, sibling of
  docs/asset-url-policy.md. One source of truth for the position; related docs
  cross-link to it instead of restating the boundary.

Modify

• docs/asset-url-policy.md — add docs/scene-trust-model.md to the "Related" section.
  Asset policy is a narrower URL/credential gate; readers should not infer code-trust
  guarantees from it.
• README.md — add a one-line pointer to the trust-model doc alongside the ADR
  reference, so the top-level entry point surfaces the boundary.

docs/scene-trust-model.md shape

The doc states the position the preflight binds to and enumerates the capability surface
acceptance criterion #4 requires. Sections:

1. Scope — who the doc is for (scene authors, future import/workflow designers,
   security reviewers) and what it does not govern (asset URLs, source policy — both
   link out).
2. Trust position — scene modules are trusted, repo-owned application code loaded
   through the authored bundle. create(ctx), timeline(ctx), and cleanup(ctx)
   execute with application privileges. There is no sandbox.
3. What runtime validation does cover — assertSceneModule() checks shape, ids,
   captions, asset/audio membership; validateRuntime() checks structural metadata
   across the scene + composition graph. Cross-link to src/runtime/scene.ts and
   src/runtime/validation.ts.
4. What runtime validation does NOT cover — code safety, hook isolation, capability
   reduction in WorkbenchSceneCtx, third-party scene execution. "Validated scene" is
   not "safe scene".
5. Capability surface (lifecycle + context) — enumerates each WorkbenchSceneCtx
   field with the authority it grants:
   • ctx.stage — workbench stage DOM element (mount/teardown surface).
   • ctx.chrome — L2 chrome slot refs (title/brand/centerpiece/etc.).
   • ctx.presenter — mode=present advance/pause subscription.
   • ctx.gsap — timeline engine (GSAP) for timeline(ctx).
   • ctx.audio — per-navigation audio service (load/play/fade/stop/mute).
   • ctx.mode — effective workbench mode (read-only).
   • ctx.rng — deterministic seeded random.
   • ctx.activation — per-occurrence identity.
     Lifecycle hooks: create, timeline, cleanup — name each as
     application-privileged.
6. Related guardrails (narrower scopes, not sandboxing) — PUL-Q007 source-policy
   gate (bans eval / Function / unsafe dynamic import in authored bundle source);
   asset URL policy (governs declared URLs and credentials, not code behavior); scene
   failure isolation (ADR-028, reliability boundary, not security containment).
   Each link is captioned so a reader does not mistake them for sandboxing.
7. Third-party / user-submitted scenes — non-goal — explicit non-goal. No plugin
   loading, marketplace import, user upload, remote registry, code signing, CSP,
   iframe/worker isolation, or per-scene trusted / sandboxed field is in scope.
8. Future sandbox seam (note, not commitment) — if a future requirement accepts
   untrusted scene execution, it must define a separate import/execution model and a
   capability-reduced context at the runtime entrypoint that chooses which scene
   catalog is loaded; parameterized by execution profile and granted capabilities, not
   by per-scene metadata. Cross-reference the preflight design note.
9. Related — docs/asset-url-policy.md, docs/design/issue-102-scene-module-trust-boundary-preflight.md,
   ADR-001, ADR-002, ADR-008, ADR-028, tests/runtime/policy-q007-remote-code-execution.test.ts,
   docs/design/pul-q007-runtime-code-execution-preflight.md.

Tests

No new tests. The preflight binds: "Do not add telemetry, SARIF, audit logs, or a
separate security workflow for a documentation-only boundary." The position the doc
states is already enforced by existing structural gates (assertSceneModule,
validateRuntime, Q007 source policy, asset URL policy) — the doc cites them, it does
not introduce new ones.

Whole-repo / FAANG L6+ review

• Security: the doc must not weaken any existing gate or imply sandboxing. The
  preflight cross-cutting layers (source execution, schema, runtime validation,
  registry/composition graph, lifecycle, ctx, asset/network, auth/secrets, env, error
  envelope, observability, persistence) are the checklist. Every section that names a
  gate links to it; no section claims a gate it does not link.
• Maintainability: one canonical doc + cross-links, not scattered warnings. The
  sibling pattern (docs/asset-url-policy.md) is reused so a contributor learning the
  repo finds both policies in the same place. Acceptance criterion phrasing matches
  runtime vocabulary (SceneModule, WorkbenchSceneCtx, lifecycle hook names) so
  drift between source and doc is detectable on review.
• Extensibility: the future-sandbox seam is named at the runtime entrypoint /
  context boundary, not per-scene metadata, so a future ADR can supersede this doc
  without re-editing every cross-link.
• Whole-repo view: scenes, validation, error isolation, asset policy, and source
  policy each have their own ADR/test/doc; the new doc sits at docs/ (top level,
  alongside asset-url-policy.md) because the trust model crosses every one of those
  layers. The design preflight already updated docs/design/README.md to register the
  preflight note; the user-facing doc does not need a separate registry entry.

Changelog

Docs-only diff (docs/** + README.md). Per .gc/plan-rules.md, no fragment under
changelog.d/ is required.

Out of scope (per preflight)

No SceneModule schema field, no new validator, no Q007 widening, no asset-policy
change, no test, no telemetry, no CI gate, no plugin/import/upload/marketplace surface,
no CSP/iframe/worker/code-signing introduction.

[Brad-Edwards]

gc_codex_review — cycle 1 of 1 (pre-push) on issue #102 (branch 102-scene-module-trust)

Core review

Verdict: ship

This is shaped correctly: the change keeps issue #102 as a documentation-boundary update, anchors the trust model in one canonical doc, cross-links adjacent policy docs without changing runtime contracts, and adds a narrow drift gate that pins the documented capability surface to the incumbent runtime types. It respects the existing seams: scene module shape validation remains metadata-only, asset/source policies stay narrower guardrails, and future untrusted execution is kept outside the current scene schema rather than smuggled in as per-scene metadata. The obvious next variation, a future sandbox/import design, is not foreclosed; the doc names the seam without implementing it.

No blocking findings.

Security review

Verdict: ship

This change is shaped as a documentation-only trust-boundary clarification plus a narrow drift test tying the published capability-surface language to the existing scene/runtime TypeScript interfaces. It touches the right cross-cutting concerns for security review: scene lifecycle authority, validation scope, asset/source-policy boundaries, diagnostics, and future third-party import surfaces. The design seam is correctly placed outside the current SceneModule schema, at any future import/execution model that would choose a capability-reduced context. It does not change runtime execution, repository scoping, request handling, secrets handling, or module loading behavior, and it does not foreclose the obvious next variation of adding a separately designed sandbox profile later.

No blocking findings.

[Brad-Edwards]

gc_codex_review pre-push cycle 1 of 1 complete for issue #102 on branch '102-scene-module-trust'. Posted by the MCP server to enforce the pre-push hard-cap-1 contract (issues #796, #804, #906). Do not edit or delete — used by the next gc_codex_review (uncommitted) invocation to count cycles.

[Brad-Edwards]

Review decision record — codex cycle 1 (issue #102)

Reviewer: codex
Cycle: 1

Architectural read:

Core reviewer: This is shaped correctly: the change keeps issue #102 as a documentation-boundary update, anchors the trust model in one canonical doc, cross-links adjacent policy docs without changing runtime contracts, and adds a narrow drift gate that pins the documented capability surface to the incumbent runtime types. It respects the existing seams: scene module shape validation remains metadata-only, asset/source policies stay narrower guardrails, and future untrusted execution is kept outside the current scene schema rather than smuggled in as per-scene metadata. The obvious next variation, a future sandbox/import design, is not foreclosed; the doc names the seam without implementing it.

Security reviewer: This change is shaped as a documentation-only trust-boundary clarification plus a narrow drift test tying the published capability-surface language to the existing scene/runtime TypeScript interfaces. It touches the right cross-cutting concerns for security review: scene lifecycle authority, validation scope, asset/source-policy boundaries, diagnostics, and future third-party import surfaces. The design seam is correctly placed outside the current SceneModule schema, at any future import/execution model that would choose a capability-reduced context. It does not change runtime execution, repository scoping, request handling, secrets handling, or module loading behavior, and it does not foreclose the obvious next variation of adding a separately designed sandbox profile later.

Blocking findings: 0 (clean run)

[Brad-Edwards]

gc_test_quality_review cycle 1 of 1 — issue #102

Reviewer: test-quality (claude-sonnet-4-6 via gc_test_quality_review)
Branch: 102-scene-module-trust
Cycle: 1 / 1
Findings: 1

Finding 1 — [warning] tests/runtime/policy-scene-trust-model-doc.test.ts::names every SceneModule lifecycle hook as (ctx)``

Problem: LIFECYCLE_HOOKS is hardcoded as ['create', 'timeline', 'cleanup']. The second test only verifies that those three specific names (a) still exist on SceneModule and (b) appear in the doc. If a fourth lifecycle hook (e.g. init) is added to SceneModule, memberNamesOf would return it in sceneMembers, but since LIFECYCLE_HOOKS never includes it, neither the existence-check nor the doc-check would fire. The test would pass even though init(ctx) was omitted from the trust-model doc.
Why it matters: The test's own comment states that this gate exists precisely to catch the scenario where 'adding... a fourth lifecycle hook would silently drift the trust-model doc away from the runtime's actual capability surface — exactly the failure mode AC4 exists to prevent.' The actual coverage does not match that claim: a new hook on SceneModule passes silently.
Fix: Derive the lifecycle hook list dynamically from the parsed interface instead of from the hardcoded constant. SceneModule types its lifecycle members as SceneLifecycleFn; a lifecycleMembersOf(file, interfaceName) helper (alongside memberNamesOf) can filter to PropertySignature nodes whose type is a TypeReferenceNode with identifier text SceneLifecycleFn. Replace LIFECYCLE_HOOKS with the output of that helper so any future hook added to the interface is automatically checked against the doc. The step-3 guard ('hooks must still exist on SceneModule') then becomes a no-op and can be removed — derivation from the live interface is itself the integrity check.

[Brad-Edwards]

gc_test_quality_review cycle 1 of 1 complete for issue #102 on branch '102-scene-module-trust'. Posted by the MCP server to enforce the gc_test_quality_review hard-cap-1 contract (issue #884 follow-up, default lowered in #906). Do not edit or delete — used by the next gc_test_quality_review invocation to count cycles.

[Brad-Edwards]

Review decision record — test-quality cycle 1 (issue #102)

Reviewer: test-quality
Cycle: 1

Architectural read:

This is a documentation drift gate — a policy test that pins docs/scene-trust-model.md to the live TypeScript type surface by parsing the source files with the TypeScript compiler API and asserting doc coverage. The shape fits the repo's existing source-policy gate vocabulary perfectly: it reuses parseSource from the shared source-policy.ts seam, mirrors the same 'walk the AST, assert findings are empty' structure as the Q007 and A-series gates, and the two test cases cleanly separate ctx-field coverage (dynamic, driven by memberNamesOf) from lifecycle-hook coverage. The approach is principled and the guard on ctxFields.length > 0 correctly blocks a vacuous pass if the interface were renamed or removed. The seam is correct.

Blocking findings: 1

Finding 1 — one-off

• ID: F1
• Title: (no title)
• Decision: fix
• Rationale: Addressed by next cycle