Skip to content

Commit a9dfb30

Browse files
author
DavidQ
committed
PLAN_PR_DEBUG_SURFACES_INSPECTORS
Defines inspector layer (read-only).
1 parent c72c59e commit a9dfb30

9 files changed

Lines changed: 113 additions & 36 deletions

‎docs/dev/BIG_PICTURE_ROADMAP.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -97,7 +97,7 @@ Do NOT change structure or wording.
9797

9898
# 🔬 TRACK I — INSPECTORS & TOOLING
9999

100-
- [ ] Entity inspector
100+
- [.] Entity inspector
101101
- [ ] Component inspector
102102
- [ ] State diff viewer
103103
- [ ] Timeline debugger

‎docs/dev/CODEX_COMMANDS.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1-
MODEL: GPT-5.4
1+
MODEL: GPT-5.3-codex
22
REASONING: high
3-
COMMAND: Create BUILD_PR_ENGINE_MATURITY implementation bundle for HTML-JavaScript-Gaming. Respect PLAN_PR -> BUILD_PR -> APPLY_PR. Keep scope docs-first and surgical. Do not pollute engine core APIs. Promote only proven public debug surfaces. Define stable debug API seams, plugin lifecycle boundaries, versioned contract metadata, external documentation ownership, and performance benchmark entry points/rules. Preserve docs/pr history. Treat docs/dev/BIG_PICTURE_ROADMAP.md as bracket-only immutable structure except approved state transitions. Package output as repo-structured ZIP to <project folder>/tmp/BUILD_PR_ENGINE_MATURITY_delta.zip.
3+
4+
COMMAND:
5+
Create BUILD_PR_DEBUG_SURFACES_INSPECTORS

‎docs/dev/COMMIT_COMMENT.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
docs: build engine maturity migration and stabilization bundle using proven public debug seams
1+
docs: build inspector surfaces bundle with read-only boundaries and apply-ready contracts

‎docs/dev/NEXT_COMMAND.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
APPLY_PR_ENGINE_MATURITY
1+
APPLY_PR_DEBUG_SURFACES_INSPECTORS

‎docs/dev/reports/change_summary.txt‎

Lines changed: 10 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,12 @@
1-
Created BUILD_PR_ENGINE_MATURITY docs-first implementation bundle.
1+
Created docs-only BUILD_PR_DEBUG_SURFACES_INSPECTORS bundle.
22

3-
Updated scope:
4-
- stable public debug API seams
5-
- plugin lifecycle boundaries
6-
- versioned contract metadata requirements
7-
- external documentation ownership map
8-
- benchmark entry points and rules
3+
Updated:
4+
- BUILD_PR_DEBUG_SURFACES_INSPECTORS.md
5+
- active command/commit/next-command docs
6+
- reports and file tree
7+
- roadmap bracket-state transition under Track I
98

10-
Constraints enforced:
11-
- docs-first and surgical
12-
- no new features
13-
- no engine-core API pollution
14-
- preserve docs/pr history
15-
- roadmap updates constrained to bracket-state transitions only
9+
Constraints preserved:
10+
- docs only
11+
- no runtime or engine-core API changes
12+
- inspector scope remains read-only

‎docs/dev/reports/file_tree.txt‎

Lines changed: 4 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,11 @@
1-
BUILD_PR_ENGINE_MATURITY_delta.zip
2-
- docs/pr/PLAN_PR_ENGINE_MATURITY.md
3-
- docs/pr/BUILD_PR_ENGINE_MATURITY.md
4-
- docs/pr/APPLY_PR_ENGINE_MATURITY.md
5-
- docs/dev/ENGINE_MATURITY_API_INVENTORY.md
6-
- docs/dev/ENGINE_MATURITY_VERSIONING_STRATEGY.md
7-
- docs/dev/ENGINE_MATURITY_PERFORMANCE_RULES.md
8-
- docs/dev/ENGINE_MATURITY_DOCUMENTATION_MAP.md
1+
BUILD_PR_DEBUG_SURFACES_INSPECTORS_delta.zip
2+
- docs/pr/PLAN_PR_DEBUG_SURFACES_INSPECTORS.md
3+
- docs/pr/BUILD_PR_DEBUG_SURFACES_INSPECTORS.md
94
- docs/dev/BIG_PICTURE_ROADMAP.md
105
- docs/dev/ROADMAP_GUARDRAILS.md
116
- docs/dev/codex_commands.md
127
- docs/dev/commit_comment.txt
8+
- docs/dev/next_command.txt
139
- docs/dev/reports/change_summary.txt
1410
- docs/dev/reports/validation_checklist.txt
1511
- docs/dev/reports/file_tree.txt

‎docs/dev/reports/validation_checklist.txt‎

Lines changed: 6 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,10 @@
11
Validation Checklist
22

33
[x] PLAN_PR -> BUILD_PR -> APPLY_PR workflow preserved
4-
[x] Bundle is docs-only
5-
[x] Scope is migration/stabilization, not feature expansion
6-
[x] Stable debug API seams are explicitly defined
7-
[x] Plugin lifecycle boundaries are explicitly defined
8-
[x] Versioned contract metadata is explicitly defined
9-
[x] External documentation ownership is explicitly defined
10-
[x] Benchmark entry points and rules are explicitly defined
11-
[x] docs/pr history preserved
4+
[x] BUILD_PR_DEBUG_SURFACES_INSPECTORS created
5+
[x] Bundle remains docs-only
6+
[x] No runtime code changes
7+
[x] No engine-core API changes
8+
[x] Inspector boundaries are read-only
9+
[x] Adapter ownership boundaries are explicit
1210
[x] BIG_PICTURE_ROADMAP.md changed by brackets only
13-
[x] ROADMAP_GUARDRAILS.md unchanged
14-
[x] ZIP packaged with repo-structured paths

‎docs/pr/BUILD_PR_DEBUG_SURFACES_INSPECTORS.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# BUILD_PR_DEBUG_SURFACES_INSPECTORS
2+
3+
## Purpose
4+
Build a docs-first, implementation-ready bundle for the first inspector layer in debug surfaces.
5+
6+
## Workflow
7+
PLAN_PR -> BUILD_PR -> APPLY_PR
8+
9+
## Build Scope
10+
- define read-only inspector contracts
11+
- define entity/component/state/timeline/event inspector boundaries
12+
- define adapter ownership (shared vs project-specific)
13+
- define validation and rollout for inspector apply
14+
15+
## Hard Constraints
16+
- docs only in this BUILD bundle
17+
- no runtime implementation code
18+
- no engine core API pollution
19+
- inspectors remain read-only in this phase
20+
- preserve existing debug behavior and boundaries
21+
22+
## Inspector Contract Targets (v1)
23+
1. Entity inspector surface:
24+
- id/label/type summaries
25+
- filtered listing and selection contract
26+
27+
2. Component inspector surface:
28+
- component type summaries
29+
- read-only component payload preview contract
30+
31+
3. State diff viewer surface:
32+
- deterministic before/after summary format
33+
- bounded diff size and truncation rules
34+
35+
4. Timeline debugger surface:
36+
- event marker summaries
37+
- timestamped sequence contract
38+
39+
5. Event stream viewer surface:
40+
- normalized event record shape
41+
- severity/category tagging contract
42+
43+
## Adapter Boundaries
44+
Shared layer:
45+
- inspector interface contracts
46+
- read-only normalization rules
47+
- registration and lifecycle seams
48+
49+
Project/sample layer:
50+
- source extraction adapters
51+
- domain-specific mapping/formatting
52+
- sensitive field redaction policy
53+
54+
## Validation Targets
55+
- all inspector surfaces remain read-only
56+
- no direct mutation paths are introduced
57+
- adapter boundaries are explicit and enforceable
58+
- apply sequence remains additive and non-destructive
59+
60+
## Apply Handoff
61+
`APPLY_PR_DEBUG_SURFACES_INSPECTORS` should implement only approved read-only seams and keep project-specific extraction outside shared engine-debug surfaces.

‎docs/pr/PLAN_PR_DEBUG_SURFACES_INSPECTORS.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# PLAN_PR_DEBUG_SURFACES_INSPECTORS
2+
3+
## Objective
4+
Introduce a read-only inspector layer:
5+
- Entity inspector
6+
- Component inspector
7+
- State diff viewer
8+
- Timeline debugger
9+
- Event stream viewer
10+
11+
## Constraints
12+
- Docs-only PR
13+
- No runtime mutation
14+
- Use existing debug providers only
15+
16+
## Contracts
17+
- InspectorRegistry
18+
- InspectorContext
19+
- FrameBufferProvider (bounded)
20+
- EventStreamProvider (read-only)
21+
22+
## Acceptance
23+
- No performance regression
24+
- No runtime changes
25+
- Inspectors render correctly

0 commit comments

Comments
 (0)