sqlseed-web 0.2.5__tar.gz → 0.2.6__tar.gz

{sqlseed_web-0.2.5 → sqlseed_web-0.2.6}/.gitignore

@@ -59,6 +59,16 @@ dmypy.json
 *.db
 *.sqlite
 *.sqlite3
+# SQLite runtime sidecars
+*.db-wal
+*.db-shm
+*.db-journal
+*.sqlite-wal
+*.sqlite-shm
+*.sqlite-journal
+*.sqlite3-wal
+*.sqlite3-shm
+*.sqlite3-journal
 .sqlseed_cache/
 snapshots/
 .env

{sqlseed_web-0.2.5 → sqlseed_web-0.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sqlseed-web
-Version: 0.2.5
+Version: 0.2.6
 Summary: Local sqlseed workbench for SQLite and PostgreSQL rules, previews, generation and optional AI suggestions
 Project-URL: Homepage, https://github.com/sunbos/sqlseed
 Project-URL: Repository, https://github.com/sunbos/sqlseed/tree/main/plugins/sqlseed-web
@@ -30,19 +30,40 @@ A local browser workbench for declarative SQLite and PostgreSQL test data genera
 Connect a database, edit field rules, preview samples, inspect dependencies and review
 generation results. The Python core runs offline; AI suggestions are optional.
 
+## A look at the workbench
+
+![sqlseed Web in English: selected tables and a four-table relationship graph in the light theme](https://raw.githubusercontent.com/sunbos/sqlseed/992ba0e733d5b41f73e37b0a9d02d573d6e2bb23/docs/assets/screenshots/web-workbench-en-light.png)
+
+The actual 0.2.5 interface with the repository's fictional SQLite order example.
+[Open the full-size PNG](https://raw.githubusercontent.com/sunbos/sqlseed/992ba0e733d5b41f73e37b0a9d02d573d6e2bb23/docs/assets/screenshots/web-workbench-en-light.png)
+or [see the read-only sample preview in the dark theme](https://raw.githubusercontent.com/sunbos/sqlseed/992ba0e733d5b41f73e37b0a9d02d573d6e2bb23/docs/assets/screenshots/web-workbench-en-dark.png).
+
+Connect an existing database, select tables and row counts, review field rules and
+dependencies, preview samples, then confirm the generation plan.
+
+| Page | What you can do |
+| --- | --- |
+| Workbench | Edit rules, inspect the relationship graph, preview samples without writing, and confirm generation. |
+| Configs | Save reusable rules, import or export YAML, and reopen configurations for the matching database. |
+| Runs | Review per-table outcomes, committed row counts, and the configuration snapshot used for a run. |
+| Settings | Choose generation defaults, light/dark appearance, optional AI settings, and available components. |
+
+The [order workflow example](https://github.com/sunbos/sqlseed/tree/main/examples/order_workflow)
+includes the schema, rules, and instructions for creating your own disposable demo.
+
 ## Installation
 
-These instructions target version 0.2.5. Check [Releases](https://github.com/sunbos/sqlseed/releases)
+These instructions target version 0.2.6. Check [Releases](https://github.com/sunbos/sqlseed/releases)
 for publication status; use the source installation below to test an unpublished candidate.
 Use a Python 3.10+ virtual environment:
 
 ```bash
-python -m pip install "sqlseed==0.2.5" "sqlseed-web==0.2.5"
+python -m pip install "sqlseed==0.2.6" "sqlseed-web==0.2.6"
 sqlseed-web
 ```
 
 Open `http://127.0.0.1:8630`. The wheel includes the frontend; no Node or npm build
-is needed to use the app. For PostgreSQL, also install `"sqlseed[postgres]==0.2.5"`.
+is needed to use the app. For PostgreSQL, also install `"sqlseed[postgres]==0.2.6"`.
 Core 0.2.4 and older lack the shared connection and diagnostic interfaces required by this version.
 
 For development, install local Core and Web together from the repository root:
@@ -51,13 +72,13 @@ For development, install local Core and Web together from the repository root:
 python -m pip install -e . -e ./plugins/sqlseed-web
 ```
 
-Version 0.2.5 and its source candidates require Core `>=0.2.5.dev0,<0.3` for
+Version 0.2.6 and its source candidates require Core `>=0.2.5.dev0,<0.3` for
 connection-target parsing and diagnostic redaction. Install matching Core and Web
 versions; do not disable dependency checks to keep an older Core.
 
 ## Interface language
 
-Version 0.2.5 offers **简体中文 / English** in the top bar.
+Version 0.2.6 offers **简体中文 / English** in the top bar.
 The browser remembers your choice and synchronizes it with other tabs on the same
 origin. Without a saved choice, the first supported browser language is used,
 falling back to English. If storage is unavailable, switching still works for the
@@ -89,10 +110,10 @@ install local Core, CLI, AI, and Web together in the same resolution:
 python -m pip install -e . -e ./plugins/sqlseed-cli -e ./plugins/sqlseed-ai -e ./plugins/sqlseed-web
 ```
 
-For version 0.2.5, `python -m pip install "sqlseed-web[ai]==0.2.5"` installs
+For version 0.2.6, `python -m pip install "sqlseed-web[ai]==0.2.6"` installs
 the optional AI component. The page does not fall back to an incompatible older release.
 
-The version 0.2.5 default launcher manages optional packages
+The version 0.2.6 default launcher manages optional packages
 in supported writable Windows, macOS and Linux virtual environments and restores
 the service automatically. Externally hosted apps and read-only/system environments
 can use the workbench but do not offer in-page package changes. Missing components

{sqlseed_web-0.2.5 → sqlseed_web-0.2.6}/README.md

@@ -6,19 +6,40 @@ A local browser workbench for declarative SQLite and PostgreSQL test data genera
 Connect a database, edit field rules, preview samples, inspect dependencies and review
 generation results. The Python core runs offline; AI suggestions are optional.
 
+## A look at the workbench
+
+![sqlseed Web in English: selected tables and a four-table relationship graph in the light theme](https://raw.githubusercontent.com/sunbos/sqlseed/992ba0e733d5b41f73e37b0a9d02d573d6e2bb23/docs/assets/screenshots/web-workbench-en-light.png)
+
+The actual 0.2.5 interface with the repository's fictional SQLite order example.
+[Open the full-size PNG](https://raw.githubusercontent.com/sunbos/sqlseed/992ba0e733d5b41f73e37b0a9d02d573d6e2bb23/docs/assets/screenshots/web-workbench-en-light.png)
+or [see the read-only sample preview in the dark theme](https://raw.githubusercontent.com/sunbos/sqlseed/992ba0e733d5b41f73e37b0a9d02d573d6e2bb23/docs/assets/screenshots/web-workbench-en-dark.png).
+
+Connect an existing database, select tables and row counts, review field rules and
+dependencies, preview samples, then confirm the generation plan.
+
+| Page | What you can do |
+| --- | --- |
+| Workbench | Edit rules, inspect the relationship graph, preview samples without writing, and confirm generation. |
+| Configs | Save reusable rules, import or export YAML, and reopen configurations for the matching database. |
+| Runs | Review per-table outcomes, committed row counts, and the configuration snapshot used for a run. |
+| Settings | Choose generation defaults, light/dark appearance, optional AI settings, and available components. |
+
+The [order workflow example](https://github.com/sunbos/sqlseed/tree/main/examples/order_workflow)
+includes the schema, rules, and instructions for creating your own disposable demo.
+
 ## Installation
 
-These instructions target version 0.2.5. Check [Releases](https://github.com/sunbos/sqlseed/releases)
+These instructions target version 0.2.6. Check [Releases](https://github.com/sunbos/sqlseed/releases)
 for publication status; use the source installation below to test an unpublished candidate.
 Use a Python 3.10+ virtual environment:
 
 ```bash
-python -m pip install "sqlseed==0.2.5" "sqlseed-web==0.2.5"
+python -m pip install "sqlseed==0.2.6" "sqlseed-web==0.2.6"
 sqlseed-web
 ```
 
 Open `http://127.0.0.1:8630`. The wheel includes the frontend; no Node or npm build
-is needed to use the app. For PostgreSQL, also install `"sqlseed[postgres]==0.2.5"`.
+is needed to use the app. For PostgreSQL, also install `"sqlseed[postgres]==0.2.6"`.
 Core 0.2.4 and older lack the shared connection and diagnostic interfaces required by this version.
 
 For development, install local Core and Web together from the repository root:
@@ -27,13 +48,13 @@ For development, install local Core and Web together from the repository root:
 python -m pip install -e . -e ./plugins/sqlseed-web
 ```
 
-Version 0.2.5 and its source candidates require Core `>=0.2.5.dev0,<0.3` for
+Version 0.2.6 and its source candidates require Core `>=0.2.5.dev0,<0.3` for
 connection-target parsing and diagnostic redaction. Install matching Core and Web
 versions; do not disable dependency checks to keep an older Core.
 
 ## Interface language
 
-Version 0.2.5 offers **简体中文 / English** in the top bar.
+Version 0.2.6 offers **简体中文 / English** in the top bar.
 The browser remembers your choice and synchronizes it with other tabs on the same
 origin. Without a saved choice, the first supported browser language is used,
 falling back to English. If storage is unavailable, switching still works for the
@@ -65,10 +86,10 @@ install local Core, CLI, AI, and Web together in the same resolution:
 python -m pip install -e . -e ./plugins/sqlseed-cli -e ./plugins/sqlseed-ai -e ./plugins/sqlseed-web
 ```
 
-For version 0.2.5, `python -m pip install "sqlseed-web[ai]==0.2.5"` installs
+For version 0.2.6, `python -m pip install "sqlseed-web[ai]==0.2.6"` installs
 the optional AI component. The page does not fall back to an incompatible older release.
 
-The version 0.2.5 default launcher manages optional packages
+The version 0.2.6 default launcher manages optional packages
 in supported writable Windows, macOS and Linux virtual environments and restores
 the service automatically. Externally hosted apps and read-only/system environments
 can use the workbench but do not offer in-page package changes. Missing components

{sqlseed_web-0.2.5 → sqlseed_web-0.2.6}/README.zh-CN.md

@@ -4,16 +4,35 @@
 
 面向 SQLite 与 PostgreSQL 声明式测试数据生成的本机浏览器工作台。连接数据库、编辑字段规则、预览样例、检查依赖并查看生成结果。Python core 离线运行；AI 建议是可选功能。
 
+## 工作台概览
+
+![sqlseed Web 简体中文浅色界面：左侧选表和四表关系图](https://raw.githubusercontent.com/sunbos/sqlseed/992ba0e733d5b41f73e37b0a9d02d573d6e2bb23/docs/assets/screenshots/web-workbench-zh-CN-light.png)
+
+0.2.5 正式界面的实际截图，使用仓库中的虚构 SQLite 订单示例。
+[查看原尺寸高清 PNG](https://raw.githubusercontent.com/sunbos/sqlseed/992ba0e733d5b41f73e37b0a9d02d573d6e2bb23/docs/assets/screenshots/web-workbench-zh-CN-light.png)，
+或[查看深色主题下的只读样例预览](https://raw.githubusercontent.com/sunbos/sqlseed/992ba0e733d5b41f73e37b0a9d02d573d6e2bb23/docs/assets/screenshots/web-workbench-zh-CN-dark.png)。
+
+连接已有数据库 → 选择表和生成数量 → 核对字段规则与依赖 → 预览样例 → 确认生成计划。
+
+| 页面 | 可以做什么 |
+| --- | --- |
+| 工作台 | 编辑规则、浏览关系图、只读预览样例，并确认生成。 |
+| 配置管理 | 保存可复用规则、导入导出 YAML、重新打开对应数据库的配置。 |
+| 运行记录 | 查看逐表结果、实际已提交行数和本次使用的配置快照。 |
+| 设置 | 调整生成默认值、浅色/深色外观、可选 AI 设置与组件。 |
+
+[订单工作流示例](https://github.com/sunbos/sqlseed/tree/main/examples/order_workflow)提供建表结构、生成规则和操作说明，可用于创建自己的独立演示库。
+
 ## 安装
 
-本文安装说明对应 0.2.5 版本；发布状态以 [Releases](https://github.com/sunbos/sqlseed/releases) 为准。测试尚未发布的候选版本时，使用下方的源码安装方式。请先创建并激活 Python 3.10+ 虚拟环境：
+本文安装说明对应 0.2.6 版本；发布状态以 [Releases](https://github.com/sunbos/sqlseed/releases) 为准。测试尚未发布的候选版本时，使用下方的源码安装方式。请先创建并激活 Python 3.10+ 虚拟环境：
 
 ```bash
-python -m pip install "sqlseed==0.2.5" "sqlseed-web==0.2.5"
+python -m pip install "sqlseed==0.2.6" "sqlseed-web==0.2.6"
 sqlseed-web
 ```
 
-打开 `http://127.0.0.1:8630`。wheel 包含前端，使用时无需 Node 或 npm 构建。PostgreSQL 还需安装 `"sqlseed[postgres]==0.2.5"`。Core 0.2.4 及更早版本缺少本版本所需的共享连接和诊断接口。
+打开 `http://127.0.0.1:8630`。wheel 包含前端，使用时无需 Node 或 npm 构建。PostgreSQL 还需安装 `"sqlseed[postgres]==0.2.6"`。Core 0.2.4 及更早版本缺少本版本所需的共享连接和诊断接口。
 
 开发源码从仓库根同时安装 Core 与 Web：
 
@@ -21,15 +40,15 @@ sqlseed-web
 python -m pip install -e . -e ./plugins/sqlseed-web
 ```
 
-0.2.5 版本及其源码候选要求 Core `>=0.2.5.dev0,<0.3`，用于连接目标解析与诊断脱敏。请使用匹配的 Core 与 Web 版本，不要关闭依赖检查来保留旧 Core。
+0.2.6 版本及其源码候选要求 Core `>=0.2.5.dev0,<0.3`，用于连接目标解析与诊断脱敏。请使用匹配的 Core 与 Web 版本，不要关闭依赖检查来保留旧 Core。
 
 ## 界面语言
 
-0.2.5 版本在顶栏提供 **简体中文 / English**。浏览器记住选择，并与同源标签页同步。没有已存偏好时，采用浏览器偏好中第一个支持的语言，无匹配则使用 English；存储不可用时仍能在当前页切换。
+0.2.6 版本在顶栏提供 **简体中文 / English**。浏览器记住选择，并与同源标签页同步。没有已存偏好时，采用浏览器偏好中第一个支持的语言，无匹配则使用 English；存储不可用时仍能在当前页切换。
 
 切换就地更新标签、帮助和受支持的诊断，不刷新页面、不提交表单，也不发数据库或 AI 请求；未保存的修改、焦点和选择保持不变。**数据语言与地区**是独立的生成配置：切换界面语言不改变生成内容、配置名称、表列标识、YAML 或数据库原值。旧记录或第三方诊断可能保留原文，并附当前语言说明。
 
-语言资源随 wheel 分发，不需要翻译服务。覆盖与新增文案所需验证见 [Web 双语维护](https://sunbos.github.io/sqlseed/development/web-i18n/)。
+语言资源随 wheel 分发，不需要翻译服务。覆盖与新增文案所需验证见 [Web 双语维护](https://sunbos.github.io/sqlseed/zh-CN/development/web-i18n/)。
 
 ## 可选组件
 
@@ -41,9 +60,9 @@ python -m pip install -e . -e ./plugins/sqlseed-web
 python -m pip install -e . -e ./plugins/sqlseed-cli -e ./plugins/sqlseed-ai -e ./plugins/sqlseed-web
 ```
 
-0.2.5 使用 `python -m pip install "sqlseed-web[ai]==0.2.5"` 安装可选 AI 组件。页面不会回退到不兼容的旧版本。
+0.2.6 使用 `python -m pip install "sqlseed-web[ai]==0.2.6"` 安装可选 AI 组件。页面不会回退到不兼容的旧版本。
 
-0.2.5 的默认启动器可在受支持、可写的 Windows、macOS 与 Linux 虚拟环境中管理可选包，并自动恢复服务。外部托管、只读或系统环境仍可使用工作台，但不开放网页包变更。组件缺失会显示原因和恢复入口，不会静默替换配置中的引擎。更新必须审阅兼容 wheel，保持其他已安装组件的版本；Core 与 Web 由环境的包管理工具更新。
+0.2.6 的默认启动器可在受支持、可写的 Windows、macOS 与 Linux 虚拟环境中管理可选包，并自动恢复服务。外部托管、只读或系统环境仍可使用工作台，但不开放网页包变更。组件缺失会显示原因和恢复入口，不会静默替换配置中的引擎。更新必须审阅兼容 wheel，保持其他已安装组件的版本；Core 与 Web 由环境的包管理工具更新。
 
 ## 数据与部署边界
 
@@ -51,7 +70,7 @@ python -m pip install -e . -e ./plugins/sqlseed-cli -e ./plugins/sqlseed-ai -e .
 
 服务面向一个可信的本机用户，没有多用户认证，默认只监听 loopback。不要直接暴露到不可信网络；同源请求检查不能替代认证或数据库权限。
 
-详见[工作台指南](https://sunbos.github.io/sqlseed/web-workbench/)与[支持边界](https://sunbos.github.io/sqlseed/maintainable-release/)。
+详见[工作台指南](https://sunbos.github.io/sqlseed/zh-CN/web-workbench/)与[支持边界](https://sunbos.github.io/sqlseed/zh-CN/maintainable-release/)。
 
 ## 依赖
 

{sqlseed_web-0.2.5 → sqlseed_web-0.2.6}/src/sqlseed_web/AGENTS.md

@@ -30,6 +30,7 @@
 - SQLite URI 中解码后的 NUL、原始 TAB/CR/LF、无效 UTF-8 百分号编码也在注册前拒绝：SQLite 字符串截断与 Python URL 清理/替代解码不同，不能把异常编码折叠成另一目标。合法 UTF-8 与经过百分号编码的 TAB/CR/LF 文件名仍按真实路径识别。
 - URI 文件路径须经平台路径转换；Windows 的 `/C:/...` 与普通 `C:\...` 指向同一文件。百分号只解码一次，文件名中的字面 `%41` 不能被误识别为 `A`；真实文件别名回归覆盖空格、百分号及编码盘符。
 - 列表、打开和运行只接受当前 canonical `target_key`，不提供或接受旧身份 aliases。旧 URI hash 可能恰好属于另一个真实的 `file:` 前缀文件，不能仅凭当前连接写法推导旧 hash 并自动授权；没有可信身份版本的记录不得通过同 schema 或解析 target_label 猜库迁移。普通路径的旧 key 不变；身份发生变化的旧 URI 配置与运行仍保留可导出，由用户明确导入当前目标创建新配置，历史运行快照不改。历史记录未存原始连接或身份算法版本，旧错 hash 与真实字面 `file:` 路径 hash 的反向碰撞无法可靠区分，这是既有数据的限制，不自动推断或重绑。
+- macOS 的 SQLite 文件身份通过 Darwin libc `realpath(3)` 获取实际拼写，兼容文件系统认可的大小写和 Unicode 别名；不能直接 lower 路径或只凭文字归一化合并不同文件。身份查询不得打开再关闭数据库文件，否则可能释放同进程 SQLite 的 POSIX 锁；原生调用固定 ctypes 签名并使用 Python 持有的 PATH_MAX buffer，失败不采用部分输出。缺失路径不创建文件，其他查验失败不猜测身份；已保存的非规范别名历史不自动重绑，沿用明确导入策略。
 - Web locale 使用 Faker 风格（`zh_CN`/`en_US`）；`SUPPORTED_LOCALES` 与 `MimesisProvider.set_locale` 的映射保持一致。
 
 ## 后台任务与终态
@@ -103,6 +104,7 @@
 ## 可选组件自动管理
 
 - `supervisor.py` 在默认启动时持有监听 socket 与管理状态，`managed_worker.py` 分别启动业务/维护 worker，`worker_control.py` 以有界匿名 IPC 传递控制与临时会话。保留原 NDJSON，不代理 HTTP。旧 `--manage-plugins` 仅兼容入口；普通网页无需命令切换或手动重启。
+- Worker 就绪与恢复准入确认是两个步骤。`resume` 确认丢失时可能已有业务请求，必须保留该进程与控制通道，确认自然排空退出后才启动维护 worker；不得覆盖引用或强杀可能已恢复准入的进程。启动失败保留固定阶段、错误码、耗时与退出码，任务输出和 `recovery_error` 不带原始异常/凭据；`/recover` 仅恢复服务和原会话，不重复安装器。启动期限仍为有界的 20 秒，不用扩大期限代替退出/超时诊断。
 - 维护 worker 业务 `/api/` 一律拒绝，仅保留 health、environment 与 `/api/settings/plugins/*`；HTML 固定标识用于首次导航，API 门禁不能依赖前端，受管维护标识不得永久锁定恢复后的导航。
 - `plugin_environment.py` 只接受当前解释器与可写独立 virtualenv，解析真实 distribution metadata/Requires-Dist；不使用 import 缓存判断新安装状态。系统/只读/共享系统包/环境外 metadata 不可管理，但保留普通 Web。
 - `plugin_management.py` 白名单仅 ai/cli/mcp/mimesis。管理请求检查 loopback client/Host；POST 必须同 Origin 及 token。计划绑定五分钟内 metadata 快照，一次领取。新计划可在同一受锁解释器且权限仍满足时重新绑定合法安装器；计划到执行及更新下载后的环境变化仍须拒绝，不能将短时安装器探测结果固定为进程生命周期身份。Core/Web/Faker/Base 不接受操作，不自动卸载依赖。`supervised_plugins.py` 仅在新业务就绪后发布任务终态，恢复失败保留页面与只恢复服务的重试入口。

{sqlseed_web-0.2.5 → sqlseed_web-0.2.6}/src/sqlseed_web/managed_worker.py

@@ -28,6 +28,33 @@ if TYPE_CHECKING:
 
     from sqlseed_web.runtime_lifecycle import RuntimeGate
 
+_WORKER_STARTUP_FAILED = "backend.supervisor.worker_startup_failed"
+
+
+class WorkerLifecycleError(RuntimeError):
+    """Only fixed lifecycle facts may cross the public recovery boundary."""
+
+    def __init__(self, code: str, *, mode: str, phase: str, elapsed_ms: int, exit_code: int | None) -> None:
+        """Build a localized error from fixed lifecycle facts without private exception text."""
+        messages = {
+            "worker_startup_timeout": tr("backend.supervisor.worker_startup_timeout"),
+            "worker_exited_before_ready": tr("backend.supervisor.worker_exited_before_ready"),
+            "worker_startup_failed": tr(_WORKER_STARTUP_FAILED),
+            "worker_resume_failed": tr("backend.supervisor.worker_resume_failed"),
+            "worker_shutdown_timeout": tr("backend.supervisor.worker_shutdown_timeout"),
+            "worker_stop_pending": tr("backend.supervisor.worker_stop_pending"),
+        }
+        message = messages[code]
+        super().__init__(message)
+        self.detail: dict[str, Any] = {
+            "code": code,
+            "message": message,
+            "worker_mode": mode,
+            "phase": phase,
+            "elapsed_ms": elapsed_ms,
+            "exit_code": exit_code,
+        }
+
 
 class RemotePluginManager:
     """The HTTP worker cannot execute package operations itself."""
@@ -145,6 +172,33 @@ def _serve_worker(server: uvicorn.Server, listener: socket.socket) -> None:
         asyncio.set_event_loop(None)
 
 
+def _restore_worker_session(mode: str, session: dict[str, Any]) -> dict[str, Any]:
+    """Restore business connections only; maintenance workers must not open databases."""
+    if mode != "business":
+        return {}
+    from sqlseed_web.runtime_session import restore_session
+
+    if session:
+        return restore_session(session)
+    return {"restored_connections": 0, "failed_connections": [], "ai_session_restored": True}
+
+
+def _wait_for_http_start(server: uvicorn.Server, thread: threading.Thread) -> None:
+    """Wait for HTTP readiness or report a safe error if its serving thread exits first."""
+    while thread.is_alive() and not server.started:
+        time.sleep(0.01)
+    if not server.started:
+        raise RuntimeError(tr(_WORKER_STARTUP_FAILED))
+
+
+def _report_startup_failure(channel: ControlChannel, mode: str, stage: str) -> None:
+    """Send only the failed stage, tolerating a parent control channel that has already closed."""
+    try:
+        channel.call("worker_failed", {"mode": mode, "phase": stage})
+    except (OSError, RuntimeError):
+        pass
+
+
 def run_worker(
     listener: socket.socket,
     connection: ControlTransport,
@@ -163,7 +217,6 @@ def run_worker(
     signal.signal(signal.SIGTERM, signal.SIG_IGN)
     channel = ControlChannel(connection)
     manager = RemotePluginManager(channel, token)
-    result: dict[str, Any] = {}
     server: uvicorn.Server | None = None
     thread: threading.Thread | None = None
     lock_fd = lock_descriptor.detach() if lock_descriptor is not None else None
@@ -172,20 +225,14 @@ def run_worker(
         return _worker_control(method, mode, server, runtime_gate)
 
     channel.start(control)
+    stage = "session"
+    announced_ready = False
     try:
+        channel.call("worker_starting", {"mode": mode, "phase": stage})
         runtime_gate.pause_if_idle()
-        if mode == "business":
-            from sqlseed_web.runtime_session import restore_session
-
-            result = (
-                restore_session(session)
-                if session
-                else {
-                    "restored_connections": 0,
-                    "failed_connections": [],
-                    "ai_session_restored": True,
-                }
-            )
+        result = _restore_worker_session(mode, session)
+        stage = "application"
+        channel.call("worker_starting", {"mode": mode, "phase": stage})
         app = create_app(manage_plugins=mode == "maintenance", management_service=manager, supervised_worker=True)
         config = uvicorn.Config(
             app, log_level="warning", access_log=False, lifespan="on", timeout_graceful_shutdown=None
@@ -194,14 +241,20 @@ def run_worker(
         thread = threading.Thread(
             target=_serve_worker, args=(server, listener), daemon=False, name="sqlseed-http-worker"
         )
+        stage = "http"
+        channel.call("worker_starting", {"mode": mode, "phase": stage})
         thread.start()
-        while thread.is_alive() and not server.started:
-            time.sleep(0.01)
-        if server.started:
-            channel.call("worker_ready", {"mode": mode, "restoration": result})
+        _wait_for_http_start(server, thread)
+        channel.call("worker_ready", {"mode": mode, "restoration": result})
+        announced_ready = True
         while thread.is_alive():
             if channel.wait_closed(0.1):
                 break
+    except (HTTPException, ImportError, OSError, RuntimeError, TypeError, ValueError):
+        if not announced_ready:
+            _report_startup_failure(channel, mode, stage)
+        # Import/ASGI failures may contain credentials or driver parameters.
+        raise RuntimeError(tr(_WORKER_STARTUP_FAILED)) from None
     finally:
         _drain_worker_runtime(mode, runtime_gate)
         if server is not None:

{sqlseed_web-0.2.5 → sqlseed_web-0.2.6}/src/sqlseed_web/sqlite_target.py

@@ -2,7 +2,12 @@
 
 from __future__ import annotations
 
+import ctypes
+import errno
+import os
+import sys
 from dataclasses import dataclass
+from functools import cache
 from pathlib import Path
 from typing import Literal
 from urllib.parse import parse_qs, quote, unquote, urlencode, urlsplit
@@ -15,6 +20,36 @@ from sqlseed.database._connection_url import connection_url
 from sqlseed_web.messages import message as tr
 
 
+@cache
+def _macos_libc() -> ctypes.CDLL:
+    """Bind Darwin realpath once with its native pointer signature."""
+    library = ctypes.CDLL(None, use_errno=True)
+    library.realpath.argtypes = [ctypes.c_char_p, ctypes.POINTER(ctypes.c_char)]
+    library.realpath.restype = ctypes.c_void_p
+    return library
+
+
+def _canonical_file_path(filename: str) -> str:
+    """Resolve macOS filesystem spellings without folding distinct filenames."""
+    path = Path(filename).resolve()
+    if sys.platform != "darwin":
+        return str(path)
+    # Unlike Python's realpath, Darwin libc reads each component's actual
+    # filesystem name. It neither scans directories nor opens the database;
+    # closing an extra database descriptor would release active POSIX locks.
+    # Darwin sys/syslimits.h defines PATH_MAX=1024. Passing our own buffer
+    # avoids libc-allocated memory and retains ownership on every error path.
+    buffer = ctypes.create_string_buffer(1024)
+    if _macos_libc().realpath(os.fsencode(path), buffer):
+        return os.fsdecode(buffer.value)
+    if (error := ctypes.get_errno()) in {errno.ENOENT, errno.ENOTDIR}:
+        # Identity lookup must not create a missing database; existing callers
+        # retain their own create/no-create policy when opening it later.
+        return str(path)
+    # realpath's partial output on failure is not a valid target identity.
+    raise OSError(error, os.strerror(error), str(path))
+
+
 @dataclass(frozen=True)
 class SQLiteTarget:
     """A file, a named shared memory database, or one private connection."""
@@ -86,7 +121,7 @@ def sqlite_target(target: str, conn_id: str) -> SQLiteTarget | None:
         # Re-encode the validated text so literal percent sequences are not
         # decoded twice by url2pathname; keep drive colons visible to it.
         filename = url2pathname(quote(filename, safe="/:"))
-    return SQLiteTarget("sqlite", str(Path(filename).resolve()))
+    return SQLiteTarget("sqlite", _canonical_file_path(filename))
 
 
 def existing_sqlite_connection_target(target: str, conn_id: str) -> str:

{sqlseed_web-0.2.5 → sqlseed_web-0.2.6}/src/sqlseed_web/static/i18n/backend-messages.json

@@ -731,6 +731,34 @@
     "业务进程意外退出，原有连接与会话密钥需要重新配置。",
     "The application process stopped unexpectedly. Reconfigure connections and session keys."
   ],
+  "backend.supervisor.worker_startup_timeout": [
+    "应用进程未在启动期限内就绪，请重试恢复；不会重复安装组件。",
+    "The application process did not become ready before its startup deadline. Retry recovery; the component will not be installed again."
+  ],
+  "backend.supervisor.worker_exited_before_ready": [
+    "应用进程在就绪前退出，请检查组件环境后重试恢复。",
+    "The application process exited before becoming ready. Check the component environment and retry recovery."
+  ],
+  "backend.supervisor.worker_startup_failed": [
+    "应用进程初始化失败，请检查组件环境后重试恢复。",
+    "Application process initialization failed. Check the component environment and retry recovery."
+  ],
+  "backend.supervisor.worker_resume_failed": [
+    "未能确认应用进程已恢复服务，将先等待该进程安全退出，再恢复工作台。",
+    "The application process did not acknowledge service resumption. Wait for that process to exit safely before restoring the workbench."
+  ],
+  "backend.supervisor.worker_shutdown_timeout": [
+    "原应用进程尚未安全退出，已保留进程与环境锁；请稍后重试恢复。",
+    "The previous application process has not exited safely. Its ownership and environment lock are retained; retry recovery shortly."
+  ],
+  "backend.supervisor.worker_stop_pending": [
+    "原应用进程尚未完成清理，不能启动替代进程；请稍后重试恢复。",
+    "The previous application process has not finished cleanup. A replacement cannot start yet; retry recovery shortly."
+  ],
+  "backend.supervised_plugins.service_restore_failed": [
+    "服务恢复未完成，请重试恢复；组件操作不会重复执行。",
+    "Service recovery did not complete. Retry recovery; the component operation will not run again."
+  ],
   "backend.supervisor.another_web_service_is_using_this_python": [
     "此 Python 环境正被另一个 Web 服务使用，无法启动受管服务。",
     "Another Web service is using this Python environment. Cannot start the managed service."

{sqlseed_web-0.2.5 → sqlseed_web-0.2.6}/src/sqlseed_web/static/js/design-system.js

@@ -67,9 +67,9 @@ const readingTable = table(['#', '字段', '规则', '示例'], [
 readingTable.classList.add('wb-preview-data');
 root.append(section('foundation', '材质与文字', '透明度服从信息层级。功能层轻盈，数据与代码保持稳定阅读。', 'fields',
   h('div', { class: 'ds-grid ds-grid-three' },
-    surface('wb-config-context', '控制层', '用于配置工具栏与导航，柔和区分背景。', '--glass'),
-    surface('wb-content', '阅读层', '用于字段、记录和配置正文，减少背景干扰。', '--paper'),
-    surface('drawer-help', '内嵌说明', '用于规则说明与样例，边缘保持自然。', '--glass')),
+    surface('wb-config-context', '控制层', '导航与临时操作使用轻透表面，通过边缘区分层级。', '--surface-control'),
+    surface('wb-content', '阅读层', '字段、记录和配置正文使用稳定底色，不模糊其后的内容。', '--surface-data'),
+    surface('drawer-help', '内嵌说明', '规则说明与写入事实使用安静的底板，不在浮层中叠加玻璃。', '--wash')),
   h('div', { class: 'ds-fonts' }, h('div', { class: 'table-title' }, h('h2', {}, 'users · 用户基础信息')),
     h('span', {}, 'orders · 每一行，都有依据。'), h('code', { class: 'mono' }, 'user_id INTEGER'),
     h('span', {}, '1,024 行 · 2026-09-26')),
@@ -125,6 +125,11 @@ const countInput = h('input', { type: 'text', inputmode: 'numeric', value: '0',
 const countField = field('生成数量 · 错误恢复示例', countInput);
 countField.append(countError);
 const stageSample = h('ol', {class:'wb-guide-stages', 'aria-label':'生成流程样式示例'});
+const pathShortcutSample = button('', () => {
+  const selected = pathShortcutSample.getAttribute('aria-pressed') !== 'true';
+  pathShortcutSample.setAttribute('aria-pressed', String(selected));
+  actionStatus.textContent = selected ? '依赖路径入口已选中；此样例未修改配置。' : '依赖路径入口恢复普通状态；此样例未修改配置。';
+}, {glyph:'relations', plain:true, class:'table-graph-shortcut', 'aria-label':'查看依赖路径样例', title:'查看依赖路径样例', 'aria-pressed':'false'});
 let stageIndicator;
 for (const [index, [label, hint]] of [['设定规则','选择表与字段'],['预览样例','只读查看结果'],['确认写入','核对生成计划']].entries()) {
   const stage = button('', () => {
@@ -143,8 +148,7 @@ root.append(section('controls', '基础控件', '悬停、键盘焦点与选中
   actionStatus,
   h('h3',{},'关系图入口 · 节点与分支'),
   h('div', {class:'ds-row'},
-    button('', () => { actionStatus.textContent = '依赖路径入口样例；正式工作台会定位当前表的关系图。'; },
-      {glyph:'relations', plain:true, class:'table-graph-shortcut', 'aria-label':'查看依赖路径样例', title:'查看依赖路径样例'}),
+    pathShortcutSample,
     button('查看关系图', () => { actionStatus.textContent = '带文字的关系图入口样例，没有修改配置。'; }, {glyph:'relations',small:true})),
   h('h3',{},'生成流程 · 分段导航'), stageSample,
   h('h3',{},'连接恢复 · 主次操作'),
@@ -164,7 +168,7 @@ root.append(section('controls', '基础控件', '悬停、键盘焦点与选中
   notes('Tab 逐项移动焦点，Space 切换复选框；焦点环不等同于已选状态。',
     '鼠标悬停呈现柔和阴影，按钮不移动；已选底色仍然保留，键盘焦点继续有清晰外圈。',
     '绿色主按钮使用同色相渐变、低反光内缘与柔和外阴影表达厚度；按下时回落，不出现白色亮顶线。',
-    '关系入口使用三个圆角节点和正交分支；检查小尺寸轮廓、明暗描边与键盘提示，不依赖图标独自解释功能。',
+    '关系入口使用居中的三个圆角节点和正交分支；点击样例切换选中状态。桌面触发区为 32×32px，窄屏及触控为 44×44px；检查明暗、悬停和键盘焦点，图标与触发区保持同心。',
     '生成流程共用底槽，选中底板短暂滑动，编号和文字保持原位；窄屏换行、初载和尺寸变化直接定位。',
     '快速来回切换时底板从当前位置转向；系统选择减少动态效果时立即切换。复选框和单选框只让标记短暂浮现，输入框不会位移。',
     '连接恢复按钮居中并保持间距，窄屏自然换行；主操作和次操作使用正式按钮样式。',

{sqlseed_web-0.2.5 → sqlseed_web-0.2.6}/src/sqlseed_web/static/js/dropdown.js

@@ -372,7 +372,7 @@ export function createDropdown({
   }
   function reposition(event) {
     // 列表内部滚动只更新方向提示，不重新测量定位或改动其滚动位置。
-    if (event?.target && popup.contains(event.target)) {
+    if (event?.type === 'scroll' && event.target && popup.contains(event.target)) {
       return;
     }
     // 属性面板被 render() 整体重绘时（切列 / 切生成器 / AI 回填），旧的 dropdown

{sqlseed_web-0.2.5 → sqlseed_web-0.2.6}/src/sqlseed_web/static/js/generation-defaults-control.js

@@ -1,4 +1,4 @@
-import {tr, formatNumber, setText, setAttr, UserFacingError, errorText, serverText} from './i18n.js';
+import {tr, formatNumber, setText, setAttr, UserFacingError, errorText} from './i18n.js';
 import './i18n/messages/components.js';
 import {h, api} from './api.js';
 import {button} from './workbench/ui.js';
@@ -70,7 +70,7 @@ export function createGenerationDefaultsControl() {
     try {
       const [languages, providers] = await Promise.all([api('/api/meta/locales', {signal: controller.signal}), api('/api/meta/providers', {signal: controller.signal})]);
       if (destroyed) return;
-      localeOptions = languages.locales.map(item => ({value: item.code, label: serverText(item, 'label')}));
+      localeOptions = languages.locales.map(item => ({value: item.code, label: item.label}));
       providerFacts = providers.statuses || {};
       // Keep unavailable stored choices visible; never silently switch their meaning.
       const value = locale.get();

{sqlseed_web-0.2.5 → sqlseed_web-0.2.6}/src/sqlseed_web/static/js/i18n/messages/shell.json

@@ -10,7 +10,7 @@
     ],
     "configs": [
       "配置管理",
-      "Configurations"
+      "Configs"
     ],
     "runs": [
       "运行记录",

{sqlseed_web-0.2.5 → sqlseed_web-0.2.6}/src/sqlseed_web/static/js/i18n/messages/workbench.json

@@ -1,5 +1,19 @@
 {
   "workbench": {
+    "scope.viewing": ["当前查看：{table}", "Viewing: {table}"],
+    "scope.noTable": ["暂无表", "No table"],
+    "scope.selectedCount": ["已选 {count} 张表用于生成", {"one":"{count} table selected for generation", "other":"{count} tables selected for generation"}],
+    "guide.currentStage": ["{stage}/3 · {title}", "{stage}/3 · {title}"],
+    "guide.rulesShort": ["规则", "Rules"],
+    "guide.previewShort": ["样例", "Preview"],
+    "guide.confirmShort": ["确认", "Confirm"],
+    "execution.status.ready": ["已核对，确认后将写入数据库。", "Reviewed. Confirm to write to the database."],
+    "execution.status.checking": ["正在核对写入方案，请稍候。", "Checking the write plan. Please wait."],
+    "execution.status.busy": ["正在提交写入，请勿重复操作。", "Submitting the write. Please wait."],
+    "execution.status.blocked": ["暂不能写入，请查看原因并调整。", "Writing is blocked. Review the reasons and adjust."],
+    "execution.status.failure": ["未能完成，请查看原因后重试。", "The request failed. Review the reasons before retrying."],
+    "execution.viewReasons": ["查看原因", "View reasons"],
+    "execution.diagnostics": ["详细诊断", "Detailed diagnostics"],
     "unsupported.title": ["当前工作台不支持此生成范围", "This generation scope is not supported"],
     "unsupported.body": [
       "所选范围包含当前不支持的跨表循环：{tables}。这不是行数或生成器参数错误。具体原因见下方；SQLite 追加仅在循环内每条单列外键已有可用父键时受支持，缺少来源时全选或原样重试无法解除限制。",