scene-capability-engine 3.6.54 → 3.6.55

package/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.6.55] - 2026-03-16
+
+### Added
+- Added `sce device current` as a read-only current-device identity projection that avoids persisting a machine-id file when no persistent device id exists yet.
+- Added `sce device override show|upsert` so local per-device add/remove overlays can be inspected and updated through explicit CLI governance instead of hand-editing `.sce/state/device/device-override.json`.
+- Added `sce app collection list/show` as file-backed intent read models rooted at `.sce/app/collections/*.json`.
+- Added `sce scene workspace list/show` as file-backed scene-profile read models rooted at `.sce/app/scene-profiles/*.json`.
+- Added `sce app install-state list` so MagicBall and CLI users can inspect current cross-app installation facts from one local device-oriented view.
+- Added plan-first `sce app collection apply` and `sce scene workspace apply` diff commands with guarded explicit execution. `--execute` now reuses existing runtime install/uninstall only when the plan is fully resolvable; unresolved collections, missing app bundles, and active-release protection still block execution.
+
+### Changed
+- `sce app runtime install` and `sce app runtime uninstall` now stamp runtime installation metadata with the current device identifier and hostname, making local installation facts attributable without introducing a second install-management mechanism.
+- Collection/workspace resolution now respects file-backed local device overrides at `.sce/state/device/device-override.json` and item-level `capability_tags`, so per-device add/remove decisions and capability mismatch skips are explained in the generated plan instead of being silently ignored.
+
 ## [3.6.54] - 2026-03-16
 
 ### Added

package/README.md

@@ -163,7 +163,12 @@ For IDEs, AI shells, or custom frontends, the most important SCE surfaces are:
 
 MagicBall-specific integration surfaces now also include:
 
+- `sce device current`
+- `sce device override show|upsert`
 - `sce app bundle list|show|register`
+- `sce app collection list|show|apply`
+- `sce app install-state list`
+- `sce scene workspace list|show|apply`
 - `sce app registry status|configure|sync*`
 - `sce app runtime show|releases|install|activate|uninstall`
 - `sce app engineering show|attach|hydrate|activate`
@@ -218,5 +223,5 @@ MIT. See [LICENSE](LICENSE).
 
 ---
 
-**Version**: 3.6.54
+**Version**: 3.6.55
 **Last Updated**: 2026-03-16

package/README.zh.md

@@ -168,7 +168,12 @@ SCE 默认是强治理的。
 
 面向 MagicBall 的当前关键接口还包括：
 
+- `sce device current`
+- `sce device override show|upsert`
 - `sce app bundle list|show|register`
+- `sce app collection list|show|apply`
+- `sce app install-state list`
+- `sce scene workspace list|show|apply`
 - `sce app registry status|configure|sync*`
 - `sce app runtime show|releases|install|activate|uninstall`
 - `sce app engineering show|attach|hydrate|activate`
@@ -223,5 +228,5 @@ MIT，见 [LICENSE](LICENSE)。
 
 ---
 
-**版本**：3.6.54
+**版本**：3.6.55
 **最后更新**：2026-03-16

package/bin/scene-capability-engine.js

@@ -1054,7 +1054,9 @@ registerStateCommands(program);
 registerCapabilityCommands(program);
 
 const { registerAppCommands } = require('../lib/commands/app');
+const { registerDeviceCommands } = require('../lib/commands/device');
 const { registerModeCommands } = require('../lib/commands/mode');
+registerDeviceCommands(program);
 registerAppCommands(program);
 registerModeCommands(program);
 const { registerPmCommands } = require('../lib/commands/pm');

package/docs/command-reference.md

@@ -378,11 +378,26 @@ sce workspace team
 ### App Bundle & MagicBall Mode Projection
 
 ```bash
+# Current device baseline
+sce device current --json
+sce device override show --json
+sce device override upsert --input device-override.patch.json --json
+
 # List/show/register app bundles
 sce app bundle list --json
 sce app bundle show --app customer-order-demo --json
 sce app bundle register --input bundle.json --json
 
+# File-backed app collection intent
+sce app collection list --json
+sce app collection show --collection sales-workbench --json
+sce app collection apply --collection sales-workbench --json
+
+# File-backed scene workspace intent
+sce scene workspace list --json
+sce scene workspace show --workspace sales --json
+sce scene workspace apply --workspace sales --json
+
 # Configure and sync remote registries
 sce app registry status --json
 sce app registry configure --bundle-index-url <path-or-url> --service-index-url <path-or-url> --json
@@ -395,6 +410,10 @@ sce app runtime install --app customer-order-demo --release <release-id> --json
 sce app runtime activate --app customer-order-demo --release <release-id> --json
 sce app runtime uninstall --app customer-order-demo --release <release-id> --json
 
+# Cross-app local install-state view
+sce app install-state list --json
+sce app install-state list --install-status installed --json
+
 # Engineering projection
 sce app engineering show --app customer-order-demo --json
 sce app engineering attach --app customer-order-demo --repo <repo-url> --branch main --json
@@ -407,6 +426,10 @@ sce mode ontology home --app customer-order-demo --json
 sce mode engineering home --app customer-order-demo --json
 ```
 
+Device override notes:
+- `sce device override show` returns the normalized local per-device overlay from `.sce/state/device/device-override.json`.
+- `sce device override upsert --input <json>` merges only explicitly provided fields; omitted fields remain unchanged so local override policy is not blindly replaced.
+
 ### PM Delivery Data Plane
 
 ```bash

package/docs/magicball-app-collection-phase-1.md

@@ -0,0 +1,133 @@
+# MagicBall App Collection Phase 1
+
+## Status
+
+Shipped phase-1 baseline in SCE.
+
+Current shipped read-model baseline:
+
+- `sce device current`
+- `sce device override show`
+- `sce device override upsert`
+- `sce app collection list`
+- `sce app collection show`
+- `sce app collection apply` with plan-first diff and explicit execute for non-blocked install/uninstall actions
+- `sce app install-state list`
+- `sce scene workspace list`
+- `sce scene workspace show`
+- `sce scene workspace apply` with plan-first diff and explicit execute for non-blocked install/uninstall actions
+
+Current shipped runtime controls remain:
+
+- `sce app runtime show`
+- `sce app runtime releases`
+- `sce app runtime install`
+- `sce app runtime activate`
+- `sce app runtime uninstall`
+
+## Goal
+
+Add a scene-oriented installation model above the current single-app runtime controls so MagicBall can manage "what this workbench wants" separately from "what this device actually has installed".
+
+## Core decision
+
+SCE should split the model into two layers plus one local overlay:
+
+- intent layer: `app_collection` and `scene_profile`
+- device fact layer: `device_installation`
+- local override layer: `device_override`
+
+This means:
+
+- users or workspaces sync the desired app set
+- devices decide their own actual install set
+- one user on multiple devices does not get forced into identical installs
+
+## Why SCE should support this
+
+The current runtime commands are enough for single-app control, but they are not enough to express:
+
+- sales workbench vs planning workbench vs development workbench
+- device-specific install differences
+- reasoned batch install and uninstall planning
+
+Without this layer, frontend code has to invent business grouping and install logic outside SCE, which would fragment the contract.
+
+## Phase 1 scope
+
+Phase-1 should stay local-device-first.
+
+It should add:
+
+- current device identity and capability view
+- file-backed app collections
+- file-backed scene profiles
+- local install-state listing
+- collection or scene apply diff planning
+- explicit execute step for apply
+
+It should not require:
+
+- user account system
+- cross-device installation-state sync
+- organization policy rollout
+
+## Storage position
+
+SCE already has a selective SQLite policy. This capability should follow it.
+
+Recommended split:
+
+- shared intent stays file-backed or registry-backed
+- device facts and rebuildable resolution projections may use SQLite
+- local device override stays file-backed at `.sce/state/device/device-override.json`
+
+This boundary matters because SQLite is suitable for local query-heavy facts, but it should not become the only source of truth for portable shared intent.
+
+## Recommended phase-1 command shape
+
+Phase-1 overall command surface:
+
+- `sce device current`
+- `sce device override show`
+- `sce device override upsert`
+- `sce app collection list`
+- `sce app collection show`
+- `sce app collection apply`
+- `sce app install-state list`
+- `sce scene workspace list`
+- `sce scene workspace show`
+- `sce scene workspace apply`
+
+Execution rule:
+
+- `apply` should return a plan or diff by default
+- actual mutation requires explicit execute confirmation
+- execute stays blocked when the plan still contains unresolved collections, missing app bundles, or active-release protection skips
+- resolution now also considers local `device_override` add/remove overlays and item-level `capability_tags`
+- local override updates now also have an explicit CLI governance surface instead of requiring manual file edits
+- execution should reuse the existing app runtime path
+
+## Frontend implication for MagicBall
+
+MagicBall should keep using current per-app runtime controls until this phase ships.
+
+Today, MagicBall can already use:
+
+1. `sce device current` for current device identity and capability tags
+2. `sce device override show/upsert` for local per-device add/remove overlays
+3. `sce app collection list/show/apply` for file-backed shared collection intent and plan-first diff
+4. `sce scene workspace list/show/apply` for file-backed scene-profile intent and plan-first diff
+5. `sce app install-state list` for current cross-app installation projection
+6. existing per-app runtime controls for concrete runtime actions
+
+Once phase-1 lands, the preferred top-level interaction should become:
+
+1. pick a scene workspace or app collection
+2. inspect the proposed device diff
+3. explicitly apply the plan
+4. continue using per-app runtime controls for detail views
+
+## Practical conclusion
+
+SCE should support this direction, but it should do so by extending the current app/runtime model rather than replacing it.

package/docs/magicball-cli-invocation-examples.md

@@ -21,6 +21,46 @@ Assume:
 
 ## 1. Workspace Bootstrap
 
+### 1.0 Read current device baseline
+```bash
+sce device current --json
+sce device override show --json
+sce app collection list --json
+sce app collection show --collection sales-workbench --json
+sce app collection apply --collection sales-workbench --json
+sce scene workspace list --json
+sce scene workspace show --workspace sales --json
+sce scene workspace apply --workspace sales --json
+sce app install-state list --json
+```
+
+Expected use:
+- cache current device id / tags
+- load file-backed shared app collection intent
+- load file-backed shared scene workspace intent
+- render cross-app local install baseline before scene-oriented collection flows arrive
+
+Optional local override input:
+- `.sce/state/device/device-override.json`
+- use this for per-device add/remove exceptions instead of mutating shared collection/workspace definitions
+- update it explicitly via `sce device override upsert --input <json> --json`
+
+Example local override patch:
+```json
+{
+  "removed_apps": ["crm"],
+  "added_apps": [
+    {
+      "app_key": "notes",
+      "required": false
+    }
+  ],
+  "metadata": {
+    "reason": "tablet kiosk profile"
+  }
+}
+```
+
 ### 1.1 App bundle identity
 ```bash
 sce app bundle show --app customer-order-demo --json

package/docs/magicball-integration-doc-index.md

@@ -14,6 +14,7 @@ It is a navigation layer, not a new source of truth.
 
 These are the current first-line integration documents:
 - `docs/magicball-sce-adaptation-guide.md`
+- `docs/magicball-app-collection-phase-1.md`
 - `docs/magicball-ui-surface-checklist.md`
 - `docs/magicball-mode-home-and-ontology-empty-state-playbook.md`
 - `docs/magicball-frontend-state-and-command-mapping.md`
@@ -32,28 +33,32 @@ These are the current first-line integration documents:
    - implementation checklist
    - milestone-oriented execution order
 
-3. `docs/magicball-mode-home-and-ontology-empty-state-playbook.md`
+3. `docs/magicball-app-collection-phase-1.md`
+   - current device / collection / workspace / override baseline
+   - shipped phase-1 install orchestration contract
+
+4. `docs/magicball-mode-home-and-ontology-empty-state-playbook.md`
    - two active frontend-sensitive defaults
    - serialized mode-home loading
    - ontology empty-state and starter-seed behavior
 
-4. `docs/magicball-frontend-state-and-command-mapping.md`
+5. `docs/magicball-frontend-state-and-command-mapping.md`
    - page state ownership
    - command-to-action mapping
    - error and retry boundaries
 
-5. `docs/magicball-write-auth-adaptation-guide.md`
+6. `docs/magicball-write-auth-adaptation-guide.md`
    - write authorization and lease handling
 
-6. `docs/magicball-task-feedback-timeline-guide.md`
+7. `docs/magicball-task-feedback-timeline-guide.md`
    - task feedback cards
    - timeline view integration
 
-7. `docs/magicball-cli-invocation-examples.md`
+8. `docs/magicball-cli-invocation-examples.md`
    - copy-ready CLI examples
    - wrapper and smoke verification patterns
 
-8. `docs/magicball-integration-issue-tracker.md`
+9. `docs/magicball-integration-issue-tracker.md`
    - current cross-project truth
    - only open issues, active decisions, and verified resolutions
 
@@ -62,6 +67,7 @@ These are the current first-line integration documents:
 ### I need to bootstrap the three-mode app shell
 Use:
 - `docs/magicball-sce-adaptation-guide.md`
+- `docs/magicball-app-collection-phase-1.md`
 - `docs/magicball-mode-home-and-ontology-empty-state-playbook.md`
 - `docs/magicball-frontend-state-and-command-mapping.md`
 
@@ -95,6 +101,7 @@ Use:
 | Document | Role | Should change often? |
 | --- | --- | --- |
 | `magicball-sce-adaptation-guide.md` | main overview | low |
+| `magicball-app-collection-phase-1.md` | next-phase install model | medium |
 | `magicball-adaptation-task-checklist-v1.md` | execution checklist | medium |
 | `magicball-mode-home-and-ontology-empty-state-playbook.md` | frontend behavior policy | medium |
 | `magicball-frontend-state-and-command-mapping.md` | frontend implementation mapping | medium |
@@ -127,6 +134,7 @@ As of the current tracker state:
 - fresh ontology pages use `fallback + optional seed apply`
 - seed apply stays explicit and user-triggered
 - command failures should be preserved in copyable form for AI-assisted diagnosis
+- app installation orchestration should use `scene_profile` and `app_collection` intent, not a global identical install set
 
 ## Maintenance Rule
 

package/docs/magicball-integration-issue-tracker.md

@@ -17,7 +17,11 @@
 ### Current SCE capabilities ready for MagicBall integration
 
 SCE changes completed and now available for MagicBall:
+- `device current`
 - `app bundle` registry local state and CLI
+- `app collection list/show/apply`
+- `scene workspace list/show/apply`
+- `app install-state list`
 - `mode application home --app ... --json`
 - `mode ontology home --app ... --json`
 - `mode engineering home --app ... --json`
@@ -32,9 +36,10 @@ SCE changes completed and now available for MagicBall:
 
 ### Current recommended MagicBall consumption order
 1. consume `mode * home` as the top-level source for the three modes
-2. consume `pm`, `ontology`, and `assurance` table payloads
-3. wire runtime install/activate/uninstall and engineering attach/hydrate/activate actions
-4. use demo app: `customer-order-demo`
+2. consume `device current`, `app collection list/show/apply`, `scene workspace list/show/apply`, and `app install-state list` as the local device/install baseline
+3. consume `pm`, `ontology`, and `assurance` table payloads
+4. wire runtime install/activate/uninstall and engineering attach/hydrate/activate actions
+5. use demo app: `customer-order-demo`
 
 ### Related SCE docs
 - `docs/magicball-sce-adaptation-guide.md`
@@ -65,6 +70,11 @@ SCE changes completed and now available for MagicBall:
    - expected payload
    - UI impact
 
+### Cross-project decision recorded
+- The next install-management phase should not use a single global install set.
+- SCE will separate shared app intent from local device installation facts.
+- Planned phase-1 capability is documented in `docs/magicball-app-collection-phase-1.md`.
+
 ## Open Items
 
 ### Issue 001: SQLite lock when frontend triggers multiple SCE projection commands concurrently
@@ -153,6 +163,35 @@ Status:
 - local verification covered: `triad summary` empty -> `seed list/show` preview -> `seed apply` -> `triad summary` ready
 - keep open until broader field verification confirms the UX is stable
 
+### Issue 006: scene-profile and app-collection install orchestration is not yet command-ready
+
+Context:
+- MagicBall now needs a scene-oriented install-management model above current per-app runtime controls.
+- Current SCE already supports per-app runtime install, activate, uninstall, but not shared app intent vs device fact resolution.
+
+Cross-project decision:
+- Do not model this as one global install set shared blindly across devices.
+- Separate:
+  - shared intent: `app_collection`, `scene_profile`
+  - local fact: `device_installation`
+  - local override: `device_override`
+- Keep shared intent file-backed or registry-backed.
+- Use SQLite only for local facts and rebuildable projections.
+- `apply` must be plan-first and require explicit execution confirmation.
+
+Reference:
+- `docs/magicball-app-collection-phase-1.md`
+- `.sce/specs/128-00-app-collection-scene-profile-device-installation/`
+
+Status:
+- architecture decision aligned
+- spec added in SCE
+- read-model and plan-first diff commands implemented
+- explicit execute path now implemented for non-blocked install/uninstall actions
+- execute remains blocked when unresolved collections, missing app bundles, or active-release protection skips are present
+- local `device_override` file is now respected during resolution, so per-device add/remove exceptions no longer require mutating shared intent definitions
+- local `device_override` now also has explicit `show/upsert` command support, so frontend or operator flows no longer need to hand-edit the override file
+
 ## Resolved
 
 ### Issue 002: pm requirement upsert succeeds but requirement list still returns empty

package/docs/magicball-sce-adaptation-guide.md

@@ -12,6 +12,7 @@ Implementation detail should live in the specialized documents listed below.
 
 Use these documents together:
 - `docs/magicball-integration-doc-index.md`
+- `docs/magicball-app-collection-phase-1.md`
 - `docs/magicball-ui-surface-checklist.md`
 - `docs/magicball-mode-home-and-ontology-empty-state-playbook.md`
 - `docs/magicball-frontend-state-and-command-mapping.md`
@@ -23,15 +24,40 @@ Use these documents together:
 ## Current Scope
 
 SCE currently provides MagicBall-facing support for:
-1. `app bundle registry`
-2. `application / ontology / engineering home projections`
-3. `app runtime install / activate / uninstall`
-4. `app engineering attach / hydrate / activate`
-5. `pm` delivery data plane
-6. `ontology` triad data plane
-7. `assurance` data plane
-8. `write authorization`
-9. `task feedback + timeline`
+1. `device current` identity read model
+2. `device override show/upsert` local overlay governance
+3. `app bundle registry`
+4. `app collection list/show/apply` with plan-first diff and guarded explicit execution
+5. `scene workspace list/show/apply` with plan-first diff and guarded explicit execution
+6. `app install-state` local device projection
+7. `application / ontology / engineering home projections`
+8. `app runtime install / activate / uninstall`
+9. `app engineering attach / hydrate / activate`
+10. `pm` delivery data plane
+11. `ontology` triad data plane
+12. `assurance` data plane
+13. `write authorization`
+14. `task feedback + timeline`
+
+## Planned Next Scope
+
+The next planned SCE capability line for MagicBall is lightweight cross-device sync and richer collection resolution above the current shipped local-device-first baseline.
+
+Planned model split:
+- `app_collection` and `scene_profile` as shared intent
+- `device_installation` as local device fact
+- `device_override` as local device overlay
+
+Planned phase-1 position:
+- local device-first
+- file-backed shared intent
+- SQLite only for local facts and rebuildable projections
+- `apply` must be plan-first, not blind mutation
+- local device override is file-backed and applied during collection/workspace resolution
+- local device override mutation now uses explicit CLI upsert rather than manual-only file editing
+
+Reference:
+- `docs/magicball-app-collection-phase-1.md`
 
 ## Core Integration Positioning
 
@@ -100,6 +126,7 @@ Use `docs/magicball-cli-invocation-examples.md` for copy-ready commands.
 - `sce app engineering show`
 
 ### Runtime and engineering control
+- `sce device override show/upsert`
 - `sce app runtime show/releases/install/activate/uninstall`
 - `sce app engineering show/attach/hydrate/activate`
 - `sce app registry status/configure/sync*`

package/docs/releases/README.md

@@ -9,6 +9,8 @@ This directory stores release-facing documents:
 ## Archived Versions
 
 - [Release checklist](../release-checklist.md)
+- [v3.6.55 release notes](./v3.6.55.md)
+- [v3.6.54 release notes](./v3.6.54.md)
 - [v3.6.48 release notes](./v3.6.48.md)
 - [v3.6.47 release notes](./v3.6.47.md)
 - [v3.6.46 release notes](./v3.6.46.md)

package/docs/releases/v3.6.55.md

@@ -0,0 +1,18 @@
+# v3.6.55 Release Notes
+
+Release date: 2026-03-16
+
+## Highlights
+
+- Added explicit local device override governance commands: `sce device override show` and `sce device override upsert --input <json>`.
+- Scene-oriented install planning now keeps `device_override` mutation on one conservative path instead of requiring manual file edits or introducing a parallel state mechanism.
+- `device_override` updates now merge only explicitly provided fields, which aligns with the SCE core rule against blind replacement and preserves unrelated local device policy state.
+
+## Validation
+
+- `npx jest tests/unit/commands/device-and-install-state.test.js tests/unit/commands/scene-workspace.test.js tests/unit/commands/app-mode.test.js --runInBand`
+- `node scripts/release-doc-version-audit.js --fail-on-error`
+
+## Release Notes
+
+- This patch closes the last obvious usability gap in the phase-1 MagicBall install-management baseline. Shared intent, local device facts, and local override policy were already modeled, but local override updates still depended on hand-editing JSON. `3.6.55` makes that layer governable through the CLI while keeping the same single source of truth and conservative merge semantics.

package/docs/zh/releases/README.md

@@ -9,6 +9,8 @@
 ## 历史版本归档
 
 - [发布检查清单](../release-checklist.md)
+- [v3.6.55 发布说明](./v3.6.55.md)
+- [v3.6.54 发布说明](./v3.6.54.md)
 - [v3.6.48 发布说明](./v3.6.48.md)
 - [v3.6.47 发布说明](./v3.6.47.md)
 - [v3.6.46 发布说明](./v3.6.46.md)

package/docs/zh/releases/v3.6.55.md

@@ -0,0 +1,18 @@
+# v3.6.55 发布说明
+
+发布日期：2026-03-16
+
+## 重点变化
+
+- 新增显式的本地设备覆盖治理命令：`sce device override show` 和 `sce device override upsert --input <json>`。
+- 面向场景的安装规划现在把 `device_override` 的修改也收敛到统一治理路径，不再依赖手工改 JSON，也没有再引入并行状态机制。
+- `device_override` 更新采用“只合并明确给出的字段”的保守语义，符合 SCE 的“禁止盲改/禁止盲替换”核心原则，并保留未触及的本地设备策略状态。
+
+## 验证
+
+- `npx jest tests/unit/commands/device-and-install-state.test.js tests/unit/commands/scene-workspace.test.js tests/unit/commands/app-mode.test.js --runInBand`
+- `node scripts/release-doc-version-audit.js --fail-on-error`
+
+## 发布说明
+
+- 这个补丁版把 MagicBall phase-1 安装管理基线里最后一个明显缺口补上了。共享意图、本地设备事实和本地覆盖策略此前都已经建模完成，但本地覆盖更新仍依赖手工改 JSON。`3.6.55` 把这层能力补成了可治理的 CLI 命令，同时继续保持单一事实来源和保守合并语义。