pz-cli 5.0.1__tar.gz → 5.0.2__tar.gz

{pz_cli-5.0.1 → pz_cli-5.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pz-cli
-Version: 5.0.1
+Version: 5.0.2
 Summary: PZ CLI, runtime compiler, settings owner, and foundation runtime
 Project-URL: Homepage, https://github.com/JiXiangTools/pz
 Project-URL: Repository, https://github.com/JiXiangTools/pz

{pz_cli-5.0.1 → pz_cli-5.0.2}/docs/superpowers/specs/2026-07-13-pz-app-version-resolution-design.md

@@ -2,8 +2,11 @@
 
 ## Status
 
-This document defines the implemented contract for version-aware package
-installation in `pz app`.
+This document defines the original implemented contract for version-aware
+package installation in `pz app`. Source selection, Git package-tag installs,
+and the replacement of the index-only model are now owned by the formal
+`pz_core/pz_core/docs/pz规范与使用/09-CLI与Worker入口规范.md`; the exact-version,
+PEP 440, orchestration, and retry contracts below remain applicable.
 
 ## Goal
 
@@ -13,7 +16,8 @@ reproducible exact installed version.
 
 The normal workflow must be simple:
 
-- `pz app add <app_id>` installs the latest compatible stable version;
+- `pz app add <app_id>` installs the latest compatible stable version from the
+  selected source, defaulting to `internal-pypi`;
 - `pz app add <app_id> --version <version>` installs one exact version;
 - `pz app update <app_id>` resolves the latest compatible stable version;
 - `pz app update <app_id> --version <version>` moves to one exact version;
@@ -26,16 +30,16 @@ PZ retains the explicit atomic-command plus orchestration-command model.
 Orchestration commands are:
 
 - `pz app init`;
-- `pz app add <app_id> [--version <version>]`;
-- `pz app update <app_id> [--version <version>]`;
+- `pz app add <app_id> [--source <source>] [--version <version>]`;
+- `pz app update <app_id> [--source <source>] [--version <version>]`;
 - `pz app rm <app_id>`.
 
 Public atomic commands are:
 
 - `pz app versions <app_id>`;
-- `pz app declare <app_id> --version <version>`;
+- `pz app declare <app_id> --version <version> [--source <source>]`;
 - `pz app undeclare <app_id>`;
-- `pz app install <app_id> --version <version>`.
+- `pz app install <app_id> --version <version> [--source <source>]`.
 
 The orchestrators also reuse atomic `pz settings update` and environment sync
 capabilities. Each command belongs to exactly one layer. Normal human workflows
@@ -63,7 +67,10 @@ minimal apps.
 ## Version Resolution
 
 Without `--version`, `app add`, `app update`, and `app init` resolve the latest
-compatible stable version from the configured formal package index.
+compatible stable version from the configured `AppSourceCatalog` source.
+PyPI sources enumerate releases through the Simple API. Git sources enumerate
+formal `<distribution>@<version>` package tags and resolve the selected tag to
+one full commit and exact leaf subdirectory.
 
 The resolver must:
 
@@ -86,9 +93,9 @@ package dependency metadata, not an ambiguous project installation request.
 
 ## `pz app versions`
 
-`pz app versions <app_id>` is read-only and performs no project, environment,
-or index mutation. It resolves the formal distribution and configured package
-index, then reports:
+`pz app versions <app_id> [--source <source_id>]` is read-only and performs no
+project, environment, Git remote, or index mutation. It resolves the formal
+distribution and selected catalog source, then reports:
 
 - `app_id` and distribution name;
 - all available versions in descending PEP 440 order;
@@ -106,10 +113,19 @@ redacted.
 
 ### `pz app declare`
 
-`pz app declare <app_id> --version <version>` atomically writes the exact
-distribution pin and app identity/load-order declaration. It does not install
-the package or refresh app settings. Repeating an exact matching declaration is
-idempotent; conflicting local source ownership is a hard error.
+`pz app declare <app_id> --version <version> [--source <source>]` atomically
+writes the exact distribution plan and app identity/load-order declaration.
+Before install, a PyPI declaration contains the root identity. With a Git
+source, the command first compiles the complete formal app closure from the root
+package tag's full commit, then writes every member's exact version, the same
+credential-free Git URL/full commit, and its own leaf subdirectory in one
+project transaction; no member may fall back to an index. After `app install`,
+repeating the
+same atomic declaration inspects installed metadata, validates the complete
+formal app dependency closure against hard distribution dependencies and lock
+versions, and reconciles the closure into `installed_apps` in dependency-first
+order. It does not install packages or refresh app settings. Existing explicit
+dev source ownership is preserved and remains higher priority.
 
 ### `pz app undeclare`
 
@@ -119,11 +135,18 @@ or remote package artifacts.
 
 ### `pz app install`
 
-`pz app install <app_id> --version <version>` installs exactly one already
-resolved distribution version into the project environment and converges the
-corresponding `uv.lock` state. It does not choose latest, mutate
-`installed_apps`, or modify source directories. The locked and installed
-metadata must match the requested distribution and version before success.
+`pz app install <app_id> --version <version> [--source <source>]` installs the resolved root
+distribution and its compatible distribution dependency graph into the project
+environment and converges `uv.lock`. Missing formal app dependencies use the
+root app's same install source. A PyPI install does not inherit `UV_INDEX`, uses
+`first-index`, and cannot silently redirect a closure member to another private
+index. A PyPI resolution persists an exact version. A Git resolution consumes
+the exact same-commit closure entries already persisted by `app declare`; the
+explicit source also makes failure recovery reuse the same source. It does not
+choose latest or modify source directories. The
+second atomic `app declare` projects the installed graph into `installed_apps`.
+Locked and installed metadata must match the root request and every formal
+dependency before success.
 
 ## Orchestration
 
@@ -133,16 +156,18 @@ metadata must match the requested distribution and version before success.
 
 ```text
 resolve latest stable or validate --version
-  -> app declare exact version
-  -> app install exact version
+  -> app declare exact same-source plan
+  -> app install exact same-source plan
+  -> app declare installed dependency closure
   -> settings update
 ```
 
-Each successful atomic stage remains committed. If installation fails after
-declaration, the exact declaration remains and retry resumes from install. If
-settings refresh fails after declaration and installation succeed, retry
-resumes from settings refresh. The orchestration always reports completed
-stages, the selected exact version, and the first incomplete stage.
+Each successful atomic stage remains committed. If installation fails after the
+root declaration, that exact declaration remains and retry resumes from install.
+If closure declaration fails after installation, retry repeats `app declare`;
+if settings refresh fails, retry resumes from settings. The orchestration always
+reports completed stages, the selected exact version, and the first incomplete
+stage.
 
 ### `pz app update`
 
@@ -155,8 +180,9 @@ reinstalling.
 
 `pz app init` resolves every selected package first, forms one dependency-safe
 exact plan, then declares and installs in dependency order. A resolver conflict
-fails before project mutation. It never uses versions found in source checkout
-`pyproject.toml` files as production pins.
+fails before project mutation. It never uses a branch, `HEAD`, floating tag, or
+the current version of an arbitrary source checkout as a production pin. A Git
+source is valid only through a formal package tag resolved to a full commit.
 
 ### `pz app rm`
 
@@ -180,7 +206,8 @@ refresh. It does not remove local source or delete remote package versions.
 Publishing and installation remain separate chains. The leaf
 `[project].version`, package tag, wheel metadata, and package-index version must
 match under the Git release orchestration design. `pz app` consumes those
-published versions and never commits, tags, or publishes source.
+published versions from PyPI or a formal Git package tag and never commits,
+tags, or publishes source.
 
 ## Testing
 
@@ -194,12 +221,15 @@ Tests must cover:
 4. `app versions` reports available, latest, declared, locked, and installed
    versions consistently in human and JSON output without mutation;
 5. install validates installed distribution metadata;
-6. add/update/init preserve dependency order and fail before mutation on
-   resolution conflict;
+6. add/update/init install the formal dependency closure from the same source,
+   preserve dependency order, and fail deterministically on resolution conflict;
 7. staged declaration rollback and forward recovery after later-stage failure;
 8. source/distribution identity conflicts remain hard errors;
 9. repository-root version never overrides a leaf package version;
-10. credentials and authenticated index URLs are redacted.
+10. credentials and authenticated index URLs are redacted;
+11. inherited `UV_INDEX` cannot redirect a private formal dependency, while an
+    explicit existing dev source remains higher priority and is never deleted
+    or rewritten by `pz app`.
 
 ## Non-Goals
 
@@ -207,4 +237,6 @@ Tests must cover:
 - Giving every app in one repository the same release version.
 - Persisting floating `latest` dependencies.
 - Automatically selecting or bumping a package's publish version.
-- Installing directly from source checkout in the `pz app` command family.
+- Installing from a mutable branch, `HEAD`, floating tag, dirty checkout, or
+  unversioned local source in the `pz app` command family. Exact Git package-tag
+  installs are formal inputs under the unified source catalog design.

{pz_cli-5.0.1 → pz_cli-5.0.2}/docs/superpowers/specs/2026-07-13-pz-cli-single-wheel-design.md

@@ -140,7 +140,7 @@ The wheel exposes both existing entry-point contracts:
 pz = "pz_core.pz_launcher:main"
 
 [project.entry-points."pz.root_cli"]
-pz_foundation = "pz_foundation.root_cli:get_root_command_handlers"
+workers = "pz_foundation.root_cli:get_root_command_handlers"
 ```
 
 ## Dependency Metadata

{pz_cli-5.0.1 → pz_cli-5.0.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pz-cli"
-version = "5.0.1"
+version = "5.0.2"
 description = "PZ CLI, runtime compiler, settings owner, and foundation runtime"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -45,7 +45,7 @@ db-mysql = ["pymysql>=1.1,<2.0"]
 pz = "pz_core.pz_launcher:main"
 
 [project.entry-points."pz.root_cli"]
-pz_foundation = "pz_foundation.root_cli:get_root_command_handlers"
+workers = "pz_foundation.root_cli:get_root_command_handlers"
 
 [dependency-groups]
 dev = [

{pz_cli-5.0.1 → pz_cli-5.0.2}/pz_contrib/pz_foundation/pz_foundation/_contracts.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any, Protocol, runtime_checkable
 
@@ -10,6 +10,7 @@ class PresignInfo:
     method: str
     url: str
     expires_in_seconds: int
+    headers: dict[str, str] = field(default_factory=dict)
 
 
 @dataclass(frozen=True, slots=True)
@@ -23,6 +24,10 @@ class StoredObject:
 class StoragePort(Protocol):
     def store_bytes(self, object_key: str, payload: bytes, *, content_type: str | None = None) -> StoredObject: ...
 
+    def stat(self, object_key: str) -> StoredObject: ...
+
+    def read_range(self, object_key: str, *, offset: int = 0, length: int) -> bytes: ...
+
     def delete(self, object_key: str) -> None: ...
 
     def presign_get(self, object_key: str, *, expires_in_seconds: int) -> PresignInfo: ...

{pz_cli-5.0.1 → pz_cli-5.0.2}/pz_contrib/pz_foundation/pz_foundation/cli/workers.py

@@ -9,7 +9,6 @@ from pathlib import Path
 
 from pz_core.core.extensions import CliToolSpec
 from pz_core.cli_options import add_cli_option
-from pz_core.runtime import compile_runtime_plan
 from pz_core.runtime.cli._args import (
     PzArgumentParser,
     json_output_requested,
@@ -26,7 +25,6 @@ from pz_foundation.managed_workers import (
     stop_managed_workers,
 )
 
-
 def _coerce_bool(value: object, default: bool) -> bool:
     if isinstance(value, bool):
         return value
@@ -538,9 +536,14 @@ def main(argv: list[str] | None = None, *, project_dir: str | None = None, plan=
         ns = parser.parse_args(normalized)
         command = ns.command or "list"
         json_output = bool(getattr(ns, "json_output", False))
-        resolved_plan = plan or compile_runtime_plan(
-            project_dir=project_dir or ns.project_dir
-        )
+        resolved_plan = plan
+        if resolved_plan is None:
+            from pz_core.runtime import compile_runtime_plan
+
+            resolved_plan = compile_runtime_plan(
+                project_dir=project_dir or ns.project_dir,
+                include_cli_manifest=False,
+            )
         include_non_autostart = bool(
             getattr(ns, "include_non_autostart", False)
         )
@@ -641,4 +644,5 @@ tool = CliToolSpec(
     command=("workers",),
     summary="Manage project-attached worker runtimes.",
     tool=ManagedWorkersCliTool(),
+    requires_runtime_activation=False,
 )

{pz_cli-5.0.1 → pz_cli-5.0.2}/pz_contrib/pz_foundation/pz_foundation/configs/default.jsonc

@@ -156,7 +156,7 @@
       // shared_invalidation_versions 开启后，内容 tag 版本会进入 cache key，适配 8-20 worker 场景下的自动失效。
       "site_ui.public_html_response": {
         "enabled": true,
-        "ttl_seconds": 60,
+        "ttl_seconds": 7200,
         "max_entries": 512,
         "shared_invalidation_versions": true
       },
@@ -230,6 +230,15 @@
       "failure_window_seconds": 60.0,
       "base_backoff_seconds": 5.0,
       "max_backoff_seconds": 300.0
+    },
+    "logs": {
+      // 单个 managed worker 活跃日志达到 50 MiB 或跨 UTC 日期时轮转。
+      "max_bytes": 52428800,
+      "backup_count": 7,
+      "rotate_daily": true,
+      "compress": true,
+      // 同一完整 traceback 在窗口内仅保留首次全文，其余写入抑制摘要。
+      "duplicate_traceback_window_seconds": 300.0
     }
   },
   "mail": {
@@ -292,10 +301,26 @@
     "access_key_id": "",
     "secret_access_key": "",
     "force_path_style": false,
-    "public_base_url": ""
+    "public_base_url": "",
+    "private_bucket": "",
+    "private_key_patterns": []
   },
   "resources": {
     // 通用资源编译配置。图片响应式派生属于 foundation resource，而不是某个站点子包。
+    "delivery": {
+      // 可选静态 CDN 根地址，必须与 project.base_url 同源；空值表示继续使用当前站点相对 /static。
+      // 跨源静态域名还需要独立 CSP/CORS/字体合同，当前正式 resolver 会拒绝跨源值。
+      "cdn_base_url": "",
+      // develop/test 保持同源，避免本地调试被远端旧资源污染；product 仅在 cdn_base_url 非空时切换。
+      "cdn_enabled_by_pz_env": {
+        "dev": false,
+        "develop": false,
+        "development": false,
+        "local": false,
+        "test": false,
+        "product": true
+      }
+    },
     "images": {
       "enabled": true,
       // 默认让 `pz resources images` 等价启用 --force，绕过资源构建缓存并覆盖同名派生，避免站点图片变更后继续命中旧产物。

{pz_cli-5.0.1 → pz_cli-5.0.2}/pz_contrib/pz_foundation/pz_foundation/db/tortoise_manager.py

@@ -1,7 +1,6 @@
 from __future__ import annotations
 
 import asyncio
-import importlib
 import traceback
 from dataclasses import dataclass
 from types import SimpleNamespace
@@ -357,10 +356,6 @@ class _TortoiseManager:
                 continue
             engine = payload.get("engine")
             if isinstance(engine, str) and engine.strip():
-                try:
-                    importlib.import_module(engine.strip())
-                except Exception:
-                    return False
                 continue
             return False
         return True

{pz_cli-5.0.1 → pz_cli-5.0.2}/pz_contrib/pz_foundation/pz_foundation/docs/distribution-README.md

@@ -98,7 +98,10 @@ foundation 当前提供两层 API：
 - `<pkg>.urls` 只允许导出 `urlpatterns`
 - `urlpatterns` 必须是 `path(...)`、`include(...)`、`mount(...)` 或 `DeclaredUrlSpec(...)` 的声明序列
 - `<pkg>.urls` 使用 `path(...)` 时必须声明 `app_name`
-- `path(...)` 必须直接传入函数对象；不再支持字符串 handler 名
+- `path(...)` 的 handler 必须写成绝对 `module:callable` 导入引用；`urls.py` 不直接导入普通 handler
+- `mount(...)` 的 app factory 同样写成绝对 `module:callable` 导入引用；RuntimePlan 编译期不为 mount 导入 factory 模块
+- RuntimePlan 编译只读取路径、方法、名称等轻量声明，不导入普通 handler，也不构建对应 FastAPI router
+- Web 激活会在应用 ready 前一次性解析全部 handler 引用并构建 router；解析失败直接阻止启动，请求期不做首次导入
 - `path(...)` 的路径字符串使用 FastAPI / Starlette 原生 path 参数语法；既支持 `/{lang}/{module}/{slug}`，也支持 `/{lang:locale}/{slug}` 这类 convertor 形式
 - `path(...)` 声明的路径字符串会原样进入 FastAPI 路由表；foundation 不会在运行时再次重写业务声明层的 path 参数语法
 - `path(..., enabled_when="runtime_flag")` 表示这条路径只会在 `runtime.runtime_flag` 为真时注册
@@ -116,6 +119,7 @@ foundation 当前提供两层 API：
 - `include(...)` 负责子模块 include；上层 prefix 会与子模块 prefix 叠加；上层 namespace 会作为子模块 namespace 前缀继续下沉
 - `mount(...)` / `include(...)` 遵循 Django 风格父子 URLconf 语义：父级消费公共 prefix，子 app / 子 router 只声明相对路径，不得重复声明 mount prefix；例如挂载到 `/api/v1/payments` 时，子路由写 `/create-checkout-session`，不能写 `/api/v1/payments/create-checkout-session`
 - foundation 会先编译 `route_manifest`，再进入 FastAPI 挂载；同一路径/方法冲突必须在真实挂载前失败
+- route manifest 的 namespace、prefix 与路径/方法冲突校验直接使用已编译结构，不创建占位 FastAPI router
 - `host.route` / `admin.panel` 这类 host 扩展路由也会先转成 `DeclaredUrlSpec`，再进入同一条 registry 编译链
 - host 挂载后会把 mounted route namespace 记录到 `app.state.pz_route_registry`
 - host 也会保留已编译的 `app.state.pz_route_manifest`
@@ -127,13 +131,10 @@ from __future__ import annotations
 
 from pz_foundation.routing import include, path
 
-from .views import demo_page
-
-
 app_name = "pz_demo"
 
 urlpatterns = (
-    path("/demo", demo_page, name="pz_demo:demo-page"),
+    path("/demo", "pz_demo.views:demo_page", name="pz_demo:demo-page"),
     include("pz_demo.api", path_prefix="/api/v1", namespace="pz_demo.api"),
 )
 ```
@@ -248,6 +249,8 @@ managed worker 补充约定：
   - `pz workers stop [name ...]`
   - `pz workers restart [name ...]`
   - `pz workers run [name ...]`
+
+managed worker 的 stdout/stderr 由 detached supervisor 统一承接。`managed_workers.logs` 是日志生命周期的唯一正式配置：活跃日志按 `max_bytes` 或 UTC 日期轮转，历史日志按 `compress` 压缩并最多保留 `backup_count` 份；同一完整 traceback 在 `duplicate_traceback_window_seconds` 内只保留首次全文和抑制摘要，避免故障期间无限重复堆栈。
 - `workers restart --start-timeout <seconds>` 控制启动后等待状态刷新的时间，超时后继续用 `workers status` 读取最终状态。
 - `pz pz_foundation workers ...` 是同一实现的 app CLI 入口；root 入口与 app 入口不得分叉。
 

{pz_cli-5.0.1 → pz_cli-5.0.2}/pz_contrib/pz_foundation/pz_foundation/docs//350/256/276/350/256/241/346/226/207/346/241/243.md

@@ -22,6 +22,20 @@
 - `pz_foundation/public.py`
 - `pz_foundation/settings.py`
 - `pz_foundation/configs/default.jsonc`
+
+## Storage 对象事实合同
+
+`pz_foundation` 的 local 与 S3-compatible provider（包含通过 `endpoint_url` 接入的 R2）统一实现正式 `StorageFacade` 合同：
+
+- `stat(key)` 读取当前对象大小与 provider 已记录的 content type；S3-compatible backend 必须使用 `head_object`，不得用下载对象模拟 HEAD。
+- `read_range(key, offset=0, length=...)` 只读取指定范围；S3-compatible backend 必须发送服务端 `Range`，local backend 必须 seek 后有界读取，返回值不得超过 `length`。
+- S3-compatible client 必须固定使用 SigV4。PUT presign 的 `content_type` 与 `content_length` 必须进入签名参数；返回给调用方的显式 header 包含同一 `Content-Type`，浏览器生成的 `Content-Length` 必须与签名值一致。
+- PUT presign 的 `write_once` 默认值固定为 `false`，避免改变需要覆盖同一 key 的正式输出上传。业务显式选择 `true` 时，S3-compatible provider 必须签入 `IfNoneMatch="*"` 并返回 `If-None-Match: *`；对象已存在时 provider 的 precondition failure 必须原样暴露，不能回退为覆盖写。local backend 接受该参数以保持合同一致，但仍不支持 PUT presign。
+- `private_bucket` 必须是与公共 `bucket` 不同、未绑定公共域名的物理 bucket；`private_key_patterns` 匹配的 key 在所有读写/签名方法中都路由到该 bucket，且 `url()` 固定返回 `None`。缺失或同 bucket 配置属于安全错误，不能静默使用公共 bucket。
+- `write_once` 不覆盖“删除后重建”场景：上传授权仍有效时，业务必须保留 rejected/cancelled 对象及 tombstone，使 `If-None-Match: *` 持续拒绝第二次 PUT；只有 capability 失效并留出时钟偏差窗口后才能删除。
+- `open()` 是流式 handle 合同，不等于全量载入；需要文件头的调用方应优先使用 `read_range()`，不得通过无界 `read()` 实现探测。
+
+Foundation 不判断对象是否为真实图片，也不保存业务 upload intent。业务 owner 应把 `stat()` 的对象大小/元数据、`read_range()` 的 magic bytes 与自身一次性 intent 交叉校验，并在 provider 不可用或事实不一致时 fail closed。
 - `pz_foundation/host/*`
 
 ## Redis / Cache 设计原则
@@ -53,7 +67,7 @@
 
 同时，foundation 的 async cache facade 不负责把 redis 故障偷偷吞成 `0 / None / False`。请求期是否记录 error、继续使用当前状态、回退 DB 还是返回 `503`，由上层子包显式决定。
 
-`cache_service.read_snapshot()` 是请求期需要一次读取多个 cache 事实时的正式快照入口。它只负责把多个 Redis string key 合并为一次读取，并按调用方声明的 `json_keys` / `version_names` 返回当前快照；它不改变 miss 语义、不引入跨请求放行缓存，也不会在 backend 故障时替上层吞错。
+`cache_service.read_snapshot()` 是请求期需要一次读取多个 cache 事实时的正式快照入口，稳定公开面为 `CacheFacade.read_snapshot(json_keys=(), version_names=())`。它只负责把多个 Redis string key 合并为一次读取，并按调用方声明的 `json_keys` / `version_names` 返回当前快照；它不改变 miss 语义、不引入跨请求放行缓存，也不会在 backend 故障时替上层吞错。上层子包不得越过 facade 重新拼 Redis version key 或用循环 `get_version()` 代替一次快照读取。
 
 测试态 `RedisManager.for_testing()` 必须模拟“每个 manager 一个 Redis server”的语义：同一 manager 创建出的不同连接、不同事件循环连接、不同线程连接共享同一个 in-memory backend；`reset_connection` / `reset_all_redis_connections` 只重置连接对象，不 flush backend 数据；不同 manager 之间仍保持隔离。该 testing backend 必须覆盖 Redis key/value、集合、zset、stream、eval 以及 Pub/Sub 等已被正式 runtime 消费的能力，避免上层子包在测试中看到与真实 Redis 不一致的生命周期或跨进程语义。
 
@@ -122,6 +136,8 @@ Foundation capability 与基础设施探测结果只绑定到当前进程的 run
 
 Foundation infra 必须挂到正式 `RuntimePlan` lifecycle：Web、CLI、worker 与 Python API 在执行阶段都应先进入 runtime activate，再消费已绑定的 `SettingsSnapshot` / `settings_center.settings.pz_foundation` 初始化 DB、cache、settings operator 等基础设施。HTTP lifespan 只承担 ASGI 进程内的长驻后台探活与关闭协作，不再是 DB 初始化的唯一入口；CLI / programmatic runtime 不得为了 DB 连接重新读取 `.env`、`pz*.jsonc` 或包内默认模板。
 
+Host builder、路由物化和 HTTP lifecycle 必须绑定 `RuntimePlan.settings` 中同一个 `SettingsSnapshot`。启动期导入的 handler/provider 只能消费该快照，不得再次编译 settings；请求期继续复用同一快照，避免把配置编译带入在线热路径。
+
 程序化入口在已有 event loop 内运行时必须使用 `await runtime.activate_async()` / `await runtime.shutdown_async()`，保证 async lifecycle 与 DB 连接池绑定在调用方当前 loop 上；同步 `runtime.activate()` 只适用于没有正在运行 event loop 的调用栈。
 
 因此：
@@ -162,6 +178,10 @@ Foundation infra 必须挂到正式 `RuntimePlan` lifecycle：Web、CLI、worker
 
 `pz_foundation` 是 managed worker 运维命令的正式 owner。命令实现集中在 `pz_foundation.cli.workers`，底层进程发现、状态、停止与 supervisor 启动语义集中在 `pz_foundation.managed_workers`；其它包不应再维护第二套 worker 管理 CLI。
 
+根命令通过名称为 `workers` 的 `pz.root_cli` entry point 注册。根 dispatcher 只在 argv 第一段为 `workers` 时加载该 provider；`workers` 仍消费同一份正式 `RuntimePlan`，不得另建 WorkerPlan 或第二套 app 发现链。
+
+独立执行 `pz workers ...` 时可通过 `compile_runtime_plan(include_cli_manifest=False)` 跳过该命令不会消费的 app CLI 静态索引；这只是同一 RuntimePlan 编译器的正式裁剪参数，不改变 settings、app、extension、worker role 或其它运行时真相源。宿主已经提供 plan 时必须直接复用，不得重复编译。
+
 正式命令面如下：
 
 - `pz workers list [name ...]`：列出当前 `RuntimePlan` 中声明的 worker role 与副本状态。
@@ -204,6 +224,8 @@ CLI 与 JSON 状态必须透出 `worker_kind`，用于上层审计“基础设
 - 同一 manifest 的资源构建不允许嵌套重入；foundation 负责快速失败并暴露明确错误，而不是让进程在资源锁上自锁。
 - 跨线程与跨进程仍必须由 foundation 资源构建锁串行化，业务包、site UI、crawler 或站点运行时不应各自绕开或复制资源锁语义。
 
+静态资源投递配置的唯一真相源是 `settings_center.settings.pz_foundation.resources.delivery`：`cdn_base_url` 只接受与 `project.base_url` 同源的 HTTPS 根地址，`cdn_enabled_by_pz_env` 决定各环境是否使用它。develop/test 默认使用相对同源 URL，product 在配置有效同源 CDN 根地址后才输出绝对 URL；URL 拼接与版本参数由消费方通过公开 resolver 完成，不允许模板另读环境变量。跨源 CDN 需要额外 CSP、CORS 与字体加载合同，在这些合同形成前 resolver 必须拒绝跨源配置，不能暴露半套能力。
+
 ## 缓存控制策略真相源
 
 `settings_center.settings.pz_foundation.cache_control` 是全系统缓存控制策略参数的唯一通用真相源。
@@ -220,10 +242,13 @@ CLI 与 JSON 状态必须透出 `worker_kind`，用于上层审计“基础设
 正式边界：
 
 - `pz_foundation` 只拥有通用缓存控制参数：`enabled`、`ttl_seconds`、`max_entries`、`shared_invalidation_versions`。
-- 匿名公开 HTML 的 Cloudflare/CDN 缓存头由 `http.public_html_cdn` 唯一控制；`CacheControlMiddleware` 输出浏览器侧 `Cache-Control: public, max-age=0, must-revalidate`，并在 policy 开启时输出 `Cloudflare-CDN-Cache-Control: public, max-age=<ttl_seconds>`。
+- 公开 HTML 的 Cloudflare/CDN 缓存 TTL 由 `http.public_html_cdn` 唯一控制；但 policy 开启不等于任意 HTML 自动公开缓存。只有真正命中或成功写入公开 HTML 响应缓存的 owner，才能通过 `mark_public_html_edge_cache_eligible(response)` 显式 opt-in。
+- `CacheControlMiddleware` 是 HTML edge cache 的最终 fail-closed 安全门：只接受 `GET` / `HEAD` 的 2xx 响应，且请求不得带 `Authorization`，响应不得带 `Set-Cookie`、`Cache-Control: private/no-store` 或 `Vary: Cookie/Authorization`。普通 opt-in 请求仍不得带任何 `Cookie`；只有请求状态与内部 marker 同时声明 `request_cookie_independent` 的公开静态壳才允许携带 Cookie。全部条件成立时才输出浏览器侧 `Cache-Control: public, max-age=0, must-revalidate` 与 `Cloudflare-CDN-Cache-Control: public, max-age=<ttl_seconds>`；其余 HTML 统一 `no-store`。
+- opt-in 使用内部响应 header 传递，缓存资格不成立或存储失败时，响应 owner 通过 `clear_public_html_edge_cache_eligible(response)` 撤销标记。`CacheControlMiddleware` 在所有 HTTP 状态码和方法上都必须在最终响应中删除它，该 header 不属于外部协议。
 - JS/CSS、图片、字体、XML/JSON 等文件类型分类只从 `cache_control.http.file_extensions` 读取；对应 TTL 仍只从 `http.static.*` policies 读取。
-- 当 `http.public_html_cdn` 或全局 `runtime_enabled` 关闭时，公开 HTML 的 Cloudflare 头必须明确为 `Cloudflare-CDN-Cache-Control: no-store`，不能依赖 Cloudflare 面板或业务页面自己补规则。
-- 用户态 HTML 不属于匿名 CDN 缓存策略；`pz_site_essentials.HtmlCacheGuardMiddleware` 负责按用户态识别结果强制 `Cloudflare-CDN-Cache-Control: no-store` 与 `Vary: Cookie, Authorization`。
+- 带版本参数的静态资源同时输出浏览器与 Cloudflare 的一年 `public, max-age=31536000, immutable`（具体秒数仍取 policy），让重复访问直接复用 memory/disk cache，强制网络校验则由 CDN edge 响应；未版本化资源也同步输出对应 CDN TTL，但不得标记 immutable。
+- 当 `http.public_html_cdn` 或全局 `runtime_enabled` 关闭时，公开 HTML 的 Cloudflare 头必须明确为 `Cloudflare-CDN-Cache-Control: no-store`，不能依赖 Cloudflare 面板或业务页面自己补规则。未显式 opt-in 的 HTML 在 policy 开启时也同样 `no-store`。
+- 用户态 HTML 不属于公开静态壳策略；只有正文不包含用户、余额、订阅或 Cookie 派生事实，且这些能力由客户端动态岛恢复的页面才可声明静态壳。其它用户态 owner 仍负责输出正确的 `Vary` 与业务语义，Foundation 安全门另外以请求/响应头独立复核并在任一条件不成立时强制 `no-store`。
 - `pz_foundation` 不拥有 CMS/Blog/业务内容的事实真相，不定义业务 tag 语义，也不决定某篇文章更新后应失效哪些业务集合。
 - 业务 owner 在自身正式写链路中声明业务 tag 和失效事实；读取链路只按 policy id 消费 TTL、容量和共享版本开关。
 - `pz_site_ui` 的公开 HTML 响应缓存、模板上下文缓存，CMS 的读模型/推荐/站点地图缓存，均应消费该 policy registry；不得在业务子包里重复放置同类 TTL/容量/共享版本配置。
@@ -252,6 +277,16 @@ CLI 与 JSON 状态必须透出 `worker_kind`，用于上层审计“基础设
 
 foundation 的日志与 bot 通道配置必须走正式 app settings。
 
+### HTTP Request ID 与日志关联
+
+`pz_foundation` 是宿主 HTTP request correlation 与日志上下文的唯一 owner，正式规则如下：
+
+- 唯一 header 名为 `x-request-id`，最终值遵守 `pz_core.runtime.request_id` 的 16 位小写十六进制合同。
+- `RequestLoggingMiddleware` 必须作为 foundation 最外层通用中间件之一运行；合法入站值规范化后保留，缺失或非法值自动生成，并写入 ASGI `scope.state.request_id`、ContextVar 和响应 header。
+- logger formatter 固定输出 `request_id=<value>`。请求上下文外使用 `request_id=-`；请求内所有 `pz.*` 业务日志和访问日志使用同一个最终 ID。
+- `request_logging.exclude_paths` 只排除 header 明细，不能形成 correlation 日志盲区；只要 request logging 启用，每个 HTTP 请求仍写一条包含 ID、method、path、status、duration 的访问日志。
+- 业务包发起下游 HTTP 时只消费 `pz_foundation.public.with_request_id_headers`、`outbound_http_request_id` 或接入它们的正式 transport，不复制生成与校验逻辑。
+
 正式默认值真相源：
 
 - `pz_foundation/configs/default.jsonc`

{pz_cli-5.0.1 → pz_cli-5.0.2}/pz_contrib/pz_foundation/pz_foundation/docs//350/267/257/347/224/261/344/270/216URL/345/244/204/347/220/206/350/247/204/350/214/203.md

@@ -6,6 +6,7 @@
 
 - 路由声明真相仍在各 app 的 `<pkg>.urls` / `routes.py`；业务包只声明自己拥有的 canonical route。
 - 路由装配、排序、冲突检测、route manifest 与 host 级 redirect 归 `pz_foundation.routing` 统一处理。
+- 普通 `path(...)` handler 使用绝对 `module:callable` 引用，并统一由基础包 `ImportRef` 值对象校验和解析。RuntimePlan 只编译轻量路由结构并保留正式 `DeclaredUrlSpec`；Web 激活直接物化同一声明对象，不重新扫描 URL 模块，在 ready 前统一构建 FastAPI router；请求期不做首次导入。
 - 公开页面 path 规范化使用 `public_canonical_path(...)`。
 - 模板、导航、footer、CTA、语言切换等 href 生成使用 `public_canonical_href(...)`，或由 `pz_site_ui` 暴露到模板的 `canonical_public_href(...)`。
 - 子包不要手写 `/{lang}/...`、`/en/...`、尾斜杠补齐、默认语言去前缀、语言 alias casing 处理。

pz_cli-5.0.2/pz_contrib/pz_foundation/pz_foundation/edge_cache.py

@@ -0,0 +1,46 @@
+"""Internal response contract for public HTML edge caching."""
+
+from __future__ import annotations
+
+from typing import TypeVar
+
+from starlette.responses import Response
+
+
+PUBLIC_HTML_EDGE_CACHE_OPT_IN_HEADER = "x-pz-public-html-edge-cache"
+PUBLIC_HTML_STATIC_SHELL_SCOPE_STATE = "pz_public_html_static_shell"
+_PUBLIC_HTML_EDGE_CACHE_OPT_IN_VALUE = "1"
+_PUBLIC_HTML_EDGE_CACHE_STATIC_SHELL_VALUE = "static-shell-v1"
+_ResponseT = TypeVar("_ResponseT", bound=Response)
+
+
+def mark_public_html_edge_cache_eligible(
+    response: _ResponseT,
+    *,
+    request_cookie_independent: bool = False,
+) -> _ResponseT:
+    """Opt a response into the middleware's fail-closed public HTML checks."""
+
+    marker = (
+        _PUBLIC_HTML_EDGE_CACHE_STATIC_SHELL_VALUE
+        if request_cookie_independent
+        else _PUBLIC_HTML_EDGE_CACHE_OPT_IN_VALUE
+    )
+    response.headers[PUBLIC_HTML_EDGE_CACHE_OPT_IN_HEADER] = marker
+    return response
+
+
+def clear_public_html_edge_cache_eligible(response: _ResponseT) -> _ResponseT:
+    """Remove a stale or untrusted opt-in marker before returning a response."""
+
+    if PUBLIC_HTML_EDGE_CACHE_OPT_IN_HEADER in response.headers:
+        del response.headers[PUBLIC_HTML_EDGE_CACHE_OPT_IN_HEADER]
+    return response
+
+
+__all__ = [
+    "PUBLIC_HTML_EDGE_CACHE_OPT_IN_HEADER",
+    "PUBLIC_HTML_STATIC_SHELL_SCOPE_STATE",
+    "clear_public_html_edge_cache_eligible",
+    "mark_public_html_edge_cache_eligible",
+]