docs(openspec): add-worker-original-filename-tracking proposal by monkey1sai · Pull Request #15 · monkey1sai/AI-BIM-governance

monkey1sai · 2026-05-08T02:54:28Z

Summary

新增 OpenSpec change add-worker-original-filename-tracking,在 _worker 與 _bim-control 之間補上原始檔名 traceability。
兩個 capability deltas:worker-artifact-pipeline (ADDED Requirement) 與 worker-dev-ifc-source-selection (MODIFIED Requirement)。
本 PR 只含 propose 階段文件,不動產品程式碼。實作另開 session、依 tasks.md 執行。

Why

_worker/app/store.py 的 safe_filename 把非 ASCII 字元全換成 _、再 strip 掉開頭/結尾底線。實機驗證 許良宇圖書館建築_2026.ifc(89 MB,Worker 邊界 smoke run,SHA-256 一致)落地後 disk 名僅剩 54d77fe1_2026.ifc。metadata.json、_index/source_artifacts.json、worker → _bim-control callback payload 均不記錄原檔名,因此 sanitize 後 traceability 完全斷裂 — 13 個 89 MB 中文檔副本,從 disk 與 _bim-control 都無法分辨對應原檔哪一份。

What Changes

_worker source artifact metadata.json 新增 original_filename(raw,未 sanitize)
_worker/data/objects/_index/source_artifacts.json 每筆 entry 加 original_filename
POST /api/artifacts / POST /api/dev/ifc-sources/{id}/conversions / GET /api/conversions/{id}/result response 帶 original_filename
worker → _bim-control callback payload 帶 original_filename
_bim-control._update_artifacts_from_conversion 用 original_filename 設 source IFC artifact name(沒帶就 fallback 原 hardcoded 字串)

Boundary Preservation

❌ 不改 disk 檔名 sanitize(path 安全保留)
❌ 不改 source_id 計算公式
❌ 不改 path traversal 防護
❌ 不改 artifact ID schema、不做 disk 檔案改名
✅ 既有 metadata / _index / callback 缺欄位仍可正常讀(向前相容)

Validation

openspec validate add-worker-original-filename-tracking ✅ pass
5 個檔案,157 行新增,純 documentation(openspec/changes/...)

Test plan

Reviewer 確認 change-id 命名與 tasks.md 拆解粒度
Reviewer 確認 worker-artifact-pipeline ADDED 與 worker-dev-ifc-source-selection MODIFIED 的 scenarios 涵蓋足夠
Reviewer 確認 out-of-scope 列表(disk sanitize、source_id、path traversal、artifact ID schema、disk migration)是否合理
Merge 後另開 implementation session,依 tasks.md 第 3-8 章節執行
Implementation 完成後 openspec archive add-worker-original-filename-tracking,把 specs sync 到 openspec/specs/

🤖 Generated with Claude Code

`_worker` 目前在 source artifact metadata、`_index/source_artifacts.json`、 API response 與 callback payload 都不記錄原始檔名;中文/非 ASCII 檔名經 `safe_filename` sanitize 後就再也找不回。實機驗證 89 MB 中文檔名 IFC 落地後 disk 名稱僅剩 `<sha8>_<殘片>.ifc`,從 `_bim-control` 也看不出 artifact 對應哪個原檔。本 change 在 metadata 層補上 `original_filename`:disk 檔名仍 sanitize (保留 path 安全),但語意層保留原檔名,讓 traceability 不會因為檔名清洗而斷裂。 Capability deltas: - worker-artifact-pipeline (ADDED): 新 Requirement 「Worker preserves original filename in source metadata」, 涵蓋 metadata.json、`_index` 條目、API response、conversion result、 callback payload 五處皆須含 `original_filename`,並要求向前相容讀取舊資料。 - worker-dev-ifc-source-selection (MODIFIED): 修改「Start Conversion From Selected Source」response shape, 並新增 scenario 確保非 ASCII 檔名 end-to-end 保留。向前相容:既有 metadata.json / `_index` 條目缺欄位仍可讀取;callback 不帶欄位時 `_bim-control` fallback 到原 hardcoded name。 Validated with `openspec validate add-worker-original-filename-tracking`. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

coderabbitai · 2026-05-08T02:54:35Z

Warning

Rate limit exceeded

@monkey1sai has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 21 minutes and 42 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 6ee9ddd5-dc0b-4bf1-a61b-77a9b7c7b540

📥 Commits

Reviewing files that changed from the base of the PR and between 17dd741 and a8c1150.

📒 Files selected for processing (5)

openspec/changes/add-worker-original-filename-tracking/.openspec.yaml
openspec/changes/add-worker-original-filename-tracking/proposal.md
openspec/changes/add-worker-original-filename-tracking/specs/worker-artifact-pipeline/spec.md
openspec/changes/add-worker-original-filename-tracking/specs/worker-dev-ifc-source-selection/spec.md
openspec/changes/add-worker-original-filename-tracking/tasks.md

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch codex/openspec/add-worker-original-filename-tracking

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Copilot

Pull request overview

This PR proposes an OpenSpec change (add-worker-original-filename-tracking) to restore end-to-end traceability of the unsanitized source IFC filename across _worker metadata/index, API responses, conversion results, and the _worker → _bim-control callback—while explicitly keeping on-disk object key sanitization unchanged.

Changes:

Add a new requirement to the worker artifact pipeline specifying original_filename propagation through metadata, index, API responses, conversion results, and callback.
Modify the dev IFC selected-source conversion requirement to require original_filename in the selected-source conversion response and subsequent result contract.
Add proposal + implementation task breakdown for the follow-up implementation session.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
openspec/changes/add-worker-original-filename-tracking/.openspec.yaml	Registers the OpenSpec change (schema + created date).
openspec/changes/add-worker-original-filename-tracking/proposal.md	Explains the traceability break caused by filename sanitization and the additive metadata-field solution.
openspec/changes/add-worker-original-filename-tracking/tasks.md	Implementation checklist covering `_worker` metadata/index/API/result changes and `_bim-control` name mapping + tests.
openspec/changes/add-worker-original-filename-tracking/specs/worker-artifact-pipeline/spec.md	Adds new requirements/scenarios for preserving and propagating `original_filename`.
openspec/changes/add-worker-original-filename-tracking/specs/worker-dev-ifc-source-selection/spec.md	Modifies the selected-source conversion requirement to require `original_filename` in response/result.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

+#### Scenario: Source artifact metadata records the original filename
+
+- **WHEN** a client calls `POST /api/artifacts` with a `filename` containing non-ASCII characters or characters outside `[A-Za-z0-9_.-]`
+- **THEN** the source artifact `metadata.json` written under the versioned object layout MUST include `original_filename` equal to the request `filename` byte-for-byte (no sanitization), while the on-disk object key MAY use a sanitized filename for path safety


+#### Scenario: Non-ASCII source filename is preserved end-to-end
+
+- **WHEN** a dev IFC under `WORKER_DEV_STORAGE_ROOT` has a filename containing non-ASCII characters (for example, traditional Chinese characters, spaces, or parentheses)
+- **THEN** the selected-source conversion response, the worker source `metadata.json`, the conversion result, and the `_bim-control` callback payload MUST all include `original_filename` equal to the original `relative_path` filename, even though the on-disk object key uses a sanitized form for path safety


@@ -0,0 +1,41 @@
+## Why
+
+`_worker` 在收到 source artifact 時，會用 `SAFE_FILENAME_RE` 把非 ASCII 字元（中文、空格、括號、連字符）全部換成 `_`，再 `.strip("._")` 把開頭/結尾的底線清掉。對於常見的中文檔名 `許良宇圖書館建築_2026.ifc`，落地檔名變成 `54d77fe1_2026.ifc`（只剩 sha256 prefix + `2026.ifc`），原始檔名完全消失。


+
+## 3. `_worker` Source Artifact Metadata
+
+- [ ] 3.1 修改 `_worker/app/store.py` `create_source_artifact()` 的 metadata dict，加入 `original_filename: str = request.filename`（保留 raw，不經 `safe_filename`）。


- #32(A): _initStream 改 globalThis.GFN 讀取,缺失走 onStreamFailed,避免 onload 後 GFN 未建立仍裸變數 ReferenceError(Copilot+Codex) - #15(B): selectSpectatorBinding 先驗 primaryKitInstanceId 在 bindings 內才用 id 挑,否則退 port-diff,避免 coordinator 資料不一致時誤選 primary(Copilot) - #16(D): spectator 僅在 viewport_sharing.spectator_ready 時 stageLoadStatus='matched',否則 pending(Codex);連帶 verify 斷言 + spec scenario 精確化 - envHelpers.test 補 null case(CodeRabbit);vitest.config 補分號對齊 .prettierrc semi(Copilot) 驗證:build + vitest 34 passed(32→34) + struct-log 10 + session-first 全綠。 defer(PR 揭露):reconnect await terminate、GFN unmount guard(pre-existing async / gfn 窄窗競態)。 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

harden-web-viewer-test-resilience: #17 vitest+jsdom 骨架(34 test) / #27 timer / #8 terminate(false) / #28 poll 上限 / #15 spectator binding / #16 spectator_ready gate / #18 env boundary / #32 GFN 動態載入。雙層 review(opus 5-lens + Copilot/Codex/CodeRabbit)。

Copilot AI review requested due to automatic review settings May 8, 2026 02:54

Copilot started reviewing on behalf of monkey1sai May 8, 2026 02:55 View session

monkey1sai merged commit 0b57fbb into main May 8, 2026
3 checks passed

monkey1sai deleted the codex/openspec/add-worker-original-filename-tracking branch May 8, 2026 02:57

Copilot AI reviewed May 8, 2026

View reviewed changes

cursor Bot mentioned this pull request May 8, 2026

docs: v3 依新版架構圖 v1+v2 重寫專案開發流程（7 層架構 + IFC→USD 品質管線） #8

Merged

monkey1sai mentioned this pull request Jun 2, 2026

feat(web-viewer): 引入 vitest 測試骨架 + 修 8 個健壯性風險 (harden-web-viewer-test-resilience) #146

Merged

monkey1sai mentioned this pull request Aug 19, 2026

test(contracts): rvt-ifc-usdc-lineage Slice L1b — cloud publication 契約與協議測試（tasks 2.5–2.7，L1 全結） #657

Merged

Navigation Menu

docs(openspec): add-worker-original-filename-tracking proposal - #15

docs(openspec): add-worker-original-filename-tracking proposal#15
monkey1sai merged 1 commit into
mainfrom
codex/openspec/add-worker-original-filename-tracking

monkey1sai commented May 8, 2026

Uh oh!

coderabbitai Bot commented May 8, 2026

Rate limit exceeded

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		@@ -0,0 +1,41 @@
		## Why

		`_worker` 在收到 source artifact 時，會用 `SAFE_FILENAME_RE` 把非 ASCII 字元（中文、空格、括號、連字符）全部換成 `_`，再 `.strip("._")` 把開頭/結尾的底線清掉。對於常見的中文檔名 `許良宇圖書館建築_2026.ifc`，落地檔名變成 `54d77fe1_2026.ifc`（只剩 sha256 prefix + `2026.ifc`），原始檔名完全消失。


		## 3. `_worker` Source Artifact Metadata

		- [ ] 3.1 修改 `_worker/app/store.py` `create_source_artifact()` 的 metadata dict，加入 `original_filename: str = request.filename`（保留 raw，不經 `safe_filename`）。

Conversation

monkey1sai commented May 8, 2026

Summary

Why

What Changes

Boundary Preservation

Validation

Test plan

Uh oh!

coderabbitai Bot commented May 8, 2026

Rate limit exceeded

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants