Skip to content

docs(openspec): 延後多 Kit 驗證至 GPU 部署後 #28

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
monkey1sai merged 1 commit into from
May 12, 2026
Merged

docs(openspec): 延後多 Kit 驗證至 GPU 部署後 #28

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 18 additions & 18 deletions docs/PROJECT_DEVELOPMENT_WORKFLOW.md
View file
Open in desktop

Large diffs are not rendered by default.

1,769 changes: 1,005 additions & 764 deletions docs/plans/AI-BIM-governance-saas-roadmap-2026-05.html
View file
Open in desktop

Large diffs are not rendered by default.

106 changes: 62 additions & 44 deletions docs/plans/AI-BIM-governance-saas-roadmap-2026-05.md
View file
Open in desktop

Large diffs are not rendered by default.

22 changes: 19 additions & 3 deletions openspec/specs/multi-artifact-kit-routing/spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,17 @@
# multi-artifact-kit-routing Specification

## Purpose
TBD - created by archiving change introduce-worker-review-session-lifecycle. Update Purpose after archive.
Define how review sessions bind multiple artifacts to one or more Kit runtime
instances. The coordinator records artifact bindings, Kit instance bindings,
routing policy, stream configuration, capacity identity, and same/dedicated/
shared topology decisions while keeping collaboration session identity separate
from Kit runtime capacity.

Dedicated multi-Kit runtime execution is deferred until GPU purchase and
deployment provide at least two GPU-backed Kit endpoints. Before that capacity
exists, this specification remains the control-plane contract and routing
target, not proof that dedicated runtime evidence has passed.

## Requirements
### Requirement: Sessions contain artifact bindings

Expand Down Expand Up @@ -33,7 +43,7 @@ TBD - created by archiving change introduce-worker-review-session-lifecycle. Upd

### Requirement: Routing policy determines Kit topology

The coordinator SHALL decide Kit topology from routing policy and artifact characteristics. `same_instance` MUST allow multiple compatible USDC artifacts to load as layers or payloads in one Kit instance. `dedicated_instance` MUST allocate separate Kit instances for large models, tenant isolation, or GPU-heavy artifact groups. `shared_state` MUST synchronize selection and issue focus through coordinator events rather than video synchronization.
The coordinator SHALL decide Kit topology from routing policy and artifact characteristics. `same_instance` MUST allow multiple compatible USDC artifacts to load as layers or payloads in one Kit instance. `dedicated_instance` MUST record separate Kit instance allocation intent for large models, tenant isolation, or GPU-heavy artifact groups and MUST allocate separate Kit instances when GPU capacity is available. `shared_state` MUST synchronize selection and issue focus through coordinator events rather than video synchronization.

#### Scenario: Compatible artifacts share an instance

Expand All @@ -42,9 +52,15 @@ The coordinator SHALL decide Kit topology from routing policy and artifact chara

#### Scenario: Large model gets a dedicated instance

- **WHEN** a session requests a large or isolated artifact group with `routing_policy=dedicated_instance`
- **WHEN** a session requests a large or isolated artifact group with `routing_policy=dedicated_instance` and deployed GPU capacity is available
- **THEN** coordinator assigns that artifact group to its own Kit instance binding

#### Scenario: Dedicated runtime capacity is not deployed yet

- **WHEN** a session requests `routing_policy=dedicated_instance` before purchased and deployed GPU capacity exposes two or more Kit endpoints
- **THEN** the coordinator records the requested dedicated topology and leaves runtime allocation evidence pending
- **AND** the workspace does not classify dedicated_instance runtime evidence as passed or failed
Comment on lines +60 to +62

@coderabbitai coderabbitai Bot May 12, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Inconsistency with runtime-verification-evidence spec regarding evidence states.

Line 62 states "the workspace does not classify dedicated_instance runtime evidence as passed or failed", but the corresponding requirement in runtime-verification-evidence/spec.md (line 51) says "MUST NOT classify the dedicated runtime tier as in-progress, passed, or failed" (emphasis added).

For consistency, line 62 should match all three prohibited states:

-- **AND** the workspace does not classify dedicated_instance runtime evidence as passed or failed
+- **AND** the workspace does not classify dedicated_instance runtime evidence as in-progress, passed, or failed

This ensures both specs have aligned semantics about which evidence states are prohibited when capacity is not available.

📝 Proposed fix for state consistency 
 - **WHEN** a session requests `routing_policy=dedicated_instance` before purchased and deployed GPU capacity exposes two or more Kit endpoints
 - **THEN** the coordinator records the requested dedicated topology and leaves runtime allocation evidence pending
-- **AND** the workspace does not classify dedicated_instance runtime evidence as passed or failed
+- **AND** the workspace does not classify dedicated_instance runtime evidence as in-progress, passed, or failed
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@openspec/specs/multi-artifact-kit-routing/spec.md` around lines 60 - 62,
Update the statement that currently reads "the workspace does not classify
dedicated_instance runtime evidence as passed or failed" to match the
runtime-verification-evidence spec by prohibiting all three states:
"in-progress, passed, or failed"; locate the clause tied to the
`routing_policy=dedicated_instance` scenario and replace the existing phrasing
so it explicitly mirrors the requirement that the workspace MUST NOT classify
the dedicated runtime tier as in-progress, passed, or failed.

Comment on lines +60 to +62

@chatgpt-codex-connector chatgpt-codex-connector Bot May 12, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Forbid in-progress in the no-capacity scenario

This no-capacity scenario only says the workspace must not classify dedicated_instance evidence as passed or failed, but the roadmap and runtime-verification-evidence scenario added in this commit also forbid marking it in-progress before GPU capacity exists. As written, a status report can mark the tier in-progress and still satisfy this capability while violating the other updated documents; add in-progress here too so all specs enforce the same hold state.

Useful? React with 👍 / 👎.


#### Scenario: Shared state spans instances

- **WHEN** a session uses multiple Kit instances with shared review context
Expand Down
6 changes: 5 additions & 1 deletion openspec/specs/review-session-request-lifecycle/spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,11 @@
# review-session-request-lifecycle Specification

## Purpose
TBD - created by archiving change introduce-worker-review-session-lifecycle. Update Purpose after archive.
Define the review intent and session lifecycle contract across `_bim-control`
and `bim-review-coordinator`. `_bim-control` records review session requests and
artifact readiness, the coordinator creates and manages explicit session states,
and close/release semantics remain auditable without making either service a
file store or Kit renderer.
## Requirements
### Requirement: BIM control stores review session requests

Expand Down
16 changes: 13 additions & 3 deletions openspec/specs/runtime-verification-evidence/spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,11 @@
# runtime-verification-evidence Specification

## Purpose
TBD - created by archiving change complete-spec-runtime-verification. Update Purpose after archive.
Define the evidence tiers and acceptance rules for runtime verification. This
spec separates contract checks, single-Kit render evidence, dedicated multi-Kit
routing evidence, stress evidence, and real IFC conversion quality metrics so
the roadmap can distinguish API success, geometry/render success, blocked
hardware prerequisites, and deferred capacity tiers.
## Requirements
### Requirement: Runtime verification evidence is tiered

Expand Down Expand Up @@ -38,11 +42,17 @@ The workspace SHALL only treat Kit viewport render as verified when the loaded m

### Requirement: Dedicated Kit routing evidence requires multiple Kit instances

The workspace SHALL only classify `dedicated_instance` routing as runtime-verified when the environment provides two or more distinct Kit instance endpoints.
The workspace SHALL only classify `dedicated_instance` routing as runtime-verified when the purchased and deployed GPU environment provides two or more distinct Kit instance endpoints. Dedicated multi-Kit runtime verification SHALL remain deferred until GPU purchase and deployment provide that capacity.

#### Scenario: GPU capacity purchase and deployment is pending

- **WHEN** no purchased and deployed GPU capacity tier provides at least two Kit endpoints
- **THEN** dedicated_instance runtime verification is recorded as deferred pending capacity
- **AND** the evidence MUST NOT classify the dedicated runtime tier as in-progress, passed, or failed
Comment on lines +49 to +51

@chatgpt-codex-connector chatgpt-codex-connector Bot May 12, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Resolve the deferred-vs-blocked evidence conflict

When there are no two GPU-backed Kit endpoints, this new scenario requires dedicated_instance evidence to be recorded as “deferred pending capacity”, but the earlier hardware-dependent scenario in the same spec still requires unavailable multiple Kit instances to be recorded as blocked with missing prerequisites. A verifier for the no-capacity case cannot satisfy both statuses, so downstream roadmap/status updates can keep oscillating between blocked and deferred; narrow the earlier scenario or define deferred as the status for this dedicated-capacity case.

Useful? React with 👍 / 👎.


#### Scenario: Root scripts coordinate multi Kit startup

- **WHEN** multi Kit runtime verification needs to launch or check more than one service
- **WHEN** GPU capacity has been purchased and deployed and multi Kit runtime verification needs to launch or check more than one service
- **THEN** the orchestration entrypoint MUST live under root `scripts/` while `bim-streaming-server/scripts/` may remain the low-level single-instance launcher
Comment on lines 53 to 56

#### Scenario: Single local_fixed instance cannot verify dedicated routing
Expand Down
2 changes: 1 addition & 1 deletion openspec/specs/runtime-verification-task-status/spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,4 +84,4 @@ Same-Kit concurrent browser runtime validation SHALL use one GPU-backed Kit proc
#### Scenario: Dedicated multi-Kit process routing is out of scope for this pass

- **WHEN** the product requires isolated GPU runtimes or multiple Kit processes
- **THEN** that validation MUST be tracked as a separate dedicated capacity tier with its own endpoint pool and E2E evidence
- **THEN** that validation MUST remain deferred until GPU purchase and deployment provide a dedicated capacity tier with its own endpoint pool and E2E evidence
6 changes: 5 additions & 1 deletion openspec/specs/session-first-review-viewer/spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,11 @@
# session-first-review-viewer Specification

## Purpose
TBD - created by archiving change introduce-worker-review-session-lifecycle. Update Purpose after archive.
Define the session-first browser review experience for `web-viewer-sample`.
The viewer bootstraps from review request/session state, respects lifecycle
transitions, sends USD runtime commands through the Kit DataChannel, sends
collaboration events through coordinator contracts, and exposes multi-artifact
review controls without becoming a data authority or GPU runtime manager.
## Requirements
### Requirement: Viewer bootstraps from review request or session

Expand Down
6 changes: 5 additions & 1 deletion openspec/specs/streaming-multi-layer-payload-loading/spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,11 @@
# streaming-multi-layer-payload-loading Specification

## Purpose
TBD - created by archiving change add-dev-ifc-source-selection-flow. Update Purpose after archive.
Define how `bim-streaming-server` loads multiple ready artifact bindings into a
single Kit runtime stage for `same_instance` review sessions. Runtime responses
must honestly report the applied loading mode, loaded bindings, missing paths,
and partial failures while preserving the existing single-URL stage loading
path.
## Requirements
### Requirement: Load Multiple Artifact Bindings Into One Runtime Stage

Expand Down
6 changes: 5 additions & 1 deletion openspec/specs/worker-artifact-pipeline/spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,11 @@
# worker-artifact-pipeline Specification

## Purpose
TBD - created by archiving change introduce-worker-review-session-lifecycle. Update Purpose after archive.
Define `_worker` as the artifact and conversion facade for source model files,
derived USDC artifacts, indices, mapping files, versioned object layout,
conversion lineage, original filename traceability, real IFC conversion output,
and conversion quality reporting. `_worker` owns file bytes and derived
artifact bodies while publishing metadata only to `_bim-control`.
Comment on lines 3 to +8
## Requirements
### Requirement: Worker accepts source artifacts

Expand Down
5 changes: 4 additions & 1 deletion openspec/specs/worker-demo-upload-convert-ui/spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,10 @@
# worker-demo-upload-convert-ui Specification

## Purpose
TBD - created by archiving change add-dev-ifc-source-selection-flow. Update Purpose after archive.
Define the `_worker` demo UI boundary for local artifact intake and conversion
steps. The UI supports IFC source selection, conversion job progress, artifact
group readiness, and handoff toward review session creation without replacing
the browser review viewer, session control plane, or review metadata editor.
## Requirements
### Requirement: Worker Demo UI Entry

Expand Down
6 changes: 5 additions & 1 deletion openspec/specs/worker-dev-ifc-source-selection/spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,11 @@
# worker-dev-ifc-source-selection Specification

## Purpose
TBD - created by archiving change add-dev-ifc-source-selection-flow. Update Purpose after archive.
Define the dev-only local IFC source selection flow for `_worker`. This spec
keeps demo file discovery bounded by `WORKER_DEV_STORAGE_ROOT`, starts selected
source conversions through the normal worker artifact pipeline, preserves the
original filename for traceability, and publishes only metadata/readiness back
to `_bim-control`.
## Requirements
### Requirement: Dev IFC Source Root

Expand Down