Skip to content

Commit b7a7c55

Browse files
author
DavidQ
committed
APPLY_PR_PLUGIN_SYSTEM
Applies plugin architecture layer. & PR_VERSIONED_CONTRACTS_FULL Plan+Build+Apply versioned contracts.
1 parent 92e8337 commit b7a7c55

20 files changed

Lines changed: 1298 additions & 78 deletions

‎docs/dev/BIG_PICTURE_ROADMAP.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -108,9 +108,9 @@ Do NOT change structure or wording.
108108
# 🧠 TRACK J — ENGINE MATURITY
109109

110110
- [x] Stable debug API
111-
- [.] Plugin system
111+
- [x] Plugin system
112112
- [.] External documentation
113-
- [.] Versioned contracts
113+
- [x] Versioned contracts
114114
- [.] Performance benchmarks
115115

116116
---

‎docs/dev/CODEX_COMMANDS.md‎

Lines changed: 2 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,7 @@ MODEL: GPT-5.3-codex
22
REASONING: high
33

44
COMMAND:
5-
Create BUILD_PR_PLUGIN_SYSTEM
6-
7-
- Implement docs defined in PLAN_PR_PLUGIN_SYSTEM
8-
- Docs-only
9-
- No runtime changes
5+
Execute PLAN + BUILD + APPLY for VERSIONED_CONTRACTS
106

117
OUTPUT:
12-
<project folder>/tmp/BUILD_PR_PLUGIN_SYSTEM_delta.zip
8+
<project folder>/tmp/PR_VERSIONED_CONTRACTS_FULL_bundle.zip

‎docs/dev/COMMIT_COMMENT.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
docs: build plugin system contract bundle from PLAN with lifecycle, isolation, and registration boundaries
1+
build(versioned-contracts): execute plan/build/apply bundle with shared contract policy normalization and compatibility checks

‎docs/dev/ENGINE_MATURITY_API_INVENTORY.md‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,11 @@
66
- provider registration and read-only snapshot contract
77
- debug visibility and deterministic render-order control seams
88
- plugin lifecycle seam (`register/enable/disable/dispose`)
9+
- shared contract version policy seam (`createVersionedContractPolicy`, `evaluateContractVersion`)
10+
11+
## Versioned Metadata Export Seams
12+
- `getRenderContractVersionMetadata()`
13+
- `getDevDiagnosticsContractVersionMetadata()`
914

1015
## Internal (Not Promoted)
1116
- internal overlay composition internals
@@ -14,7 +19,7 @@
1419
- sample-specific hacks/bindings
1520

1621
## Transitional
17-
- compatibility shims for legacy paths only when required
22+
- compatibility shims for legacy version string forms only
1823
- deprecation notes with replacement path
1924

2025
## Promotion Gate

‎docs/dev/ENGINE_MATURITY_VERSIONING_STRATEGY.md‎

Lines changed: 30 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,35 @@
11
# Engine Maturity Versioning Strategy
22

3-
## Contract Metadata
4-
Each promoted contract should declare:
3+
## Objective
4+
Provide one reusable version-policy seam for mature debug/render contracts while preserving stable behavior for the current production contract version.
5+
6+
## Required Metadata
7+
Each promoted contract should define:
58
- `contractId`
6-
- `contractVersion`
7-
- `compatibility` (`backwardCompatible`, `notes`)
8-
- `status` (`active|deprecated`)
9-
- `deprecatedSince` (optional)
10-
- `replacementContractId` (optional)
9+
- `currentVersion`
10+
- `supportedVersions`
11+
- `deprecatedVersions`
12+
13+
## Runtime Rules
14+
1. Normalize incoming version strings to canonical semver (`MAJOR.MINOR.PATCH`).
15+
2. Accept only versions listed in `supportedVersions`.
16+
3. Treat unsupported versions as hard validation failures.
17+
4. Allow deprecation signaling without silent auto-upgrade.
18+
19+
## SemVer Guidance
20+
- MAJOR: breaking contract changes
21+
- MINOR: additive backward-compatible changes
22+
- PATCH: non-breaking fixes/clarifications
23+
24+
## Compatibility Guidance
25+
- Alias-style inputs (for example `v1.0`) may be normalized to a supported canonical version.
26+
- Unsupported major upgrades (for example `2.x`) must be rejected explicitly.
1127

12-
## SemVer Rules
13-
- MAJOR: breaking
14-
- MINOR: additive/backward-compatible
15-
- PATCH: non-breaking fix/clarification
28+
## Current Adopted Policies
29+
- Render contract (`toolbox.render.contract`): current `1.0.0`, supported `1.0.0` aliases normalized from `1`, `1.0`, `v1.0`.
30+
- Dev diagnostics contract (`toolbox.dev.diagnostics`): current `1.0.0`, same compatibility normalization policy.
1631

17-
## Deprecation
18-
- mark deprecated with replacement guidance
19-
- keep transition window
20-
- remove only on MAJOR boundary
32+
## Deprecation Rules
33+
- Mark deprecations in policy metadata before removal.
34+
- Keep replacement guidance in docs before advancing MAJOR.
35+
- Remove deprecated versions only after explicit migration window closure.

‎docs/dev/NEXT_COMMAND.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
APPLY_PR_PLUGIN_SYSTEM
1+
Create PR_PERFORMANCE_BENCHMARKS_FULL_bundle

‎docs/dev/reports/change_summary.txt‎

Lines changed: 16 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,18 @@
1-
Created BUILD_PR_PLUGIN_SYSTEM docs-only bundle from PLAN_PR_PLUGIN_SYSTEM.
1+
Toolbox Aid
2+
David Quesenberry
3+
04/05/2026
4+
change_summary.txt
25

3-
Included:
4-
- BUILD and APPLY docs for plugin system lifecycle/registration/isolation contracts
5-
- updated active codex/commit/next-command control files
6-
- refreshed reports and file tree
6+
Executed PLAN + BUILD + APPLY for VERSIONED_CONTRACTS in one scoped bundle.
77

8-
Constraints respected:
9-
- docs-only scope
10-
- no runtime code changes
11-
- no engine refactor or breaking change work in this step
8+
Implemented:
9+
- Added shared version policy helper module for contract normalization/evaluation.
10+
- Wired render and diagnostics contract validators to the shared policy seam.
11+
- Exposed version metadata helpers for both contract surfaces.
12+
- Updated targeted tests for metadata visibility and compatibility alias acceptance.
13+
- Updated Track J roadmap bracket state for Versioned contracts.
14+
15+
Non-goals preserved:
16+
- No engine core API redesign.
17+
- No unrelated runtime feature expansion.
18+
- No destructive changes.

‎docs/dev/reports/file_tree.txt‎

Lines changed: 22 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,22 @@
1-
BUILD_PR_PLUGIN_SYSTEM_delta.zip
2-
- docs/pr/PLAN_PR_PLUGIN_SYSTEM.md
3-
- docs/pr/BUILD_PR_PLUGIN_SYSTEM.md
4-
- docs/pr/APPLY_PR_PLUGIN_SYSTEM.md
5-
- docs/dev/codex_commands.md
6-
- docs/dev/commit_comment.txt
7-
- docs/dev/next_command.txt
8-
- docs/dev/reports/change_summary.txt
9-
- docs/dev/reports/file_tree.txt
10-
- docs/dev/reports/validation_checklist.txt
1+
Toolbox Aid
2+
David Quesenberry
3+
04/05/2026
4+
file_tree.txt
5+
6+
docs/pr/PLAN_PR_VERSIONED_CONTRACTS.md
7+
docs/pr/BUILD_PR_VERSIONED_CONTRACTS.md
8+
docs/pr/APPLY_PR_VERSIONED_CONTRACTS.md
9+
docs/dev/codex_commands.md
10+
docs/dev/commit_comment.txt
11+
docs/dev/next_command.txt
12+
docs/dev/ENGINE_MATURITY_VERSIONING_STRATEGY.md
13+
docs/dev/ENGINE_MATURITY_API_INVENTORY.md
14+
docs/dev/reports/change_summary.txt
15+
docs/dev/reports/validation_checklist.txt
16+
docs/dev/reports/file_tree.txt
17+
docs/dev/BIG_PICTURE_ROADMAP.md
18+
tools/shared/contractVersioning.js
19+
tools/shared/renderPipelineContract.js
20+
tools/shared/devConsoleDebugOverlay.js
21+
tests/tools/RenderPipelineContractAll4Tools.test.mjs
22+
tests/tools/DevConsoleDebugOverlay.test.mjs

‎docs/dev/reports/validation_checklist.txt‎

Lines changed: 25 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,26 @@
1-
Validation Checklist
1+
Toolbox Aid
2+
David Quesenberry
3+
04/05/2026
4+
validation_checklist.txt
25

3-
[x] PLAN_PR -> BUILD_PR -> APPLY_PR flow preserved
4-
[x] BUILD_PR_PLUGIN_SYSTEM created
5-
[x] APPLY_PR_PLUGIN_SYSTEM created
6-
[x] PluginRegistry contract documented
7-
[x] PluginContext contract documented
8-
[x] CapabilityDescriptor contract documented
9-
[x] Lifecycle hooks and ordering documented
10-
[x] Isolation rules documented
11-
[x] Optional/lazy loading model documented
12-
[x] Docs-only scope maintained (no runtime changes)
6+
[x] PLAN_PR authored and aligned to scope
7+
[x] BUILD_PR authored and aligned to scope
8+
[x] APPLY_PR authored and aligned to scope
9+
[x] Shared contract version policy module added
10+
[x] Render contract version policy integration applied
11+
[x] Dev diagnostics version policy integration applied
12+
[x] Compatibility aliases accepted and normalized
13+
[x] Unsupported versions rejected
14+
[x] node --check passed for touched JS files
15+
[x] Targeted contract tests passed
16+
[x] Roadmap updated with bracket-only edit
17+
[x] Delta bundle ZIP created at requested path
18+
19+
Validation command results:
20+
- node --check tools/shared/contractVersioning.js -> PASS
21+
- node --check tools/shared/renderPipelineContract.js -> PASS
22+
- node --check tools/shared/devConsoleDebugOverlay.js -> PASS
23+
- node --check tests/tools/RenderPipelineContractAll4Tools.test.mjs -> PASS
24+
- node --check tests/tools/DevConsoleDebugOverlay.test.mjs -> PASS
25+
- RenderPipelineContractAll4Tools.test.mjs run() -> PASS
26+
- DevConsoleDebugOverlay.test.mjs run() -> PASS

‎docs/pr/APPLY_PR_PLUGIN_SYSTEM.md‎

Lines changed: 22 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,30 @@
11
# APPLY_PR_PLUGIN_SYSTEM
22

33
## Purpose
4-
Apply plugin system contracts exactly as defined by PLAN and BUILD docs.
4+
Apply BUILD_PR_PLUGIN_SYSTEM exactly as defined.
55

6-
## Apply Scope
7-
- implement `PluginRegistry`, `PluginContext`, and `CapabilityDescriptor` seams
8-
- implement lifecycle ordering and isolation behavior
9-
- implement optional/lazy loading paths
10-
- expose only approved registration APIs
6+
## Scope
7+
- Plugin system contracts finalized
8+
- Lifecycle hooks enforced
9+
- Isolation rules applied
10+
- Optional loading model preserved
1111

12-
## Apply Rules
13-
- no scope expansion beyond BUILD contract
14-
- preserve engine/runtime separation
15-
- no direct runtime mutation paths for plugins
16-
- no breaking changes to existing behavior
12+
## Rules
13+
- No runtime mutation outside approved boundaries
14+
- No breaking changes
15+
- Preserve engine/runtime separation
1716

18-
## Apply Validation
19-
- lifecycle hooks execute in strict order
20-
- plugin failures remain isolated
21-
- registration/discovery APIs are deterministic
22-
- lazy activation and unload flows are validated
17+
## Validation
18+
- Plugins register/unregister correctly
19+
- Lifecycle works (init, activate, deactivate, dispose)
20+
- Isolation enforced
21+
- No regressions
22+
23+
## Roadmap Update
24+
Track J:
25+
- Plugin system -> [x]
26+
27+
(Bracket-only change)
2328

2429
## Output
25-
<project folder>/tmp/APPLY_PR_PLUGIN_SYSTEM_delta.zip
30+
<project folder>/tmp/APPLY_PR_PLUGIN_SYSTEM_delta.zip

0 commit comments

Comments
 (0)