pomaster 0.1.0 → 0.2.0

package/catalog/archetypes/archetype.runtime.environment_parity.json

@@ -0,0 +1,178 @@
+{
+  "id": "RUNTIME_ARCHETYPE.ENVIRONMENT_PARITY",
+  "kind": "archetype",
+  "layer": "ARCHETYPE",
+  "title_zh": "环境一致性原型",
+  "summary_zh": "六维环境比对原型（PRD §215 逐字）：Runtime Version/Config/Feature Flag/DB Schema/Dependency/External Integration 逐维比对期望态与实际态，产出结构化 ENVIRONMENT_DRIFT（差异项 + severity + ignore_rules）；与 Perception 的 Wrong Runtime Instance 机制直接结合。",
+  "semantic": {
+    "responsibility": "把『环境之间是否一致』从印象问题标准化为逐维比对：每维声明事实源与比对方式，差异以结构化漂移产物承载（差异项、严重度、忽略规则三件齐备），而非散落在人脑与聊天记录",
+    "when_to_use": "多环境部署（PRD §215 五环境 LOCAL/DEV/TEST/STAGING/PRODUCTION）需要回答『dev 过而 production 挂』类问题时；环境迁移/复制部署/升级前需要预检漂移时",
+    "when_not_to_use": "单环境本地开发（无第二环境可比）；运行中服务的遥测观测（走观测语义绑定模式的信号面）；代码版本管理本身（版本比对只是六维之一）"
+  },
+  "composition": {
+    "requires": [],
+    "optional": [],
+    "incompatible": []
+  },
+  "defaults": {
+    "comparison_dimensions": {
+      "runtime_version": {
+        "source": "部署视图/镜像 tag；OTel 资源属性（service.version、deployment.id）",
+        "status": "verified",
+        "wording_anchors": [
+          "service.version"
+        ],
+        "note": "deployment.id/name/status 为 Development 级词形（非稳定锚，允许变更——research 2026-09-03 实抓）"
+      },
+      "config": {
+        "source": "应用 profile 分层（Spring profiles：spring.profiles.active/default/include/group + spring.config.activate.on-profile）+ k8s 分层渲染（kustomize base/overlays，template-free）+ 比对命令（kubectl diff：live vs would-be applied，恒输出 YAML，退出码 0=无差异/1=有差异/>1=出错）",
+        "status": "verified",
+        "wording_anchors": [
+          "spring.profiles.active",
+          "spring.profiles.group",
+          "spring.config.activate.on-profile",
+          "kustomize base/overlays",
+          "kubectl diff"
+        ],
+        "note": "配置项本体承载为 PRD 自有词形（Config Key/Default/Environment Override，§73）；OTel 无配置维度标准词形"
+      },
+      "feature_flag": {
+        "source": "OpenFeature（vendor-agnostic 标准层，CNCF incubating 现状，One SDK any backend）+ OTel 旗标求值属性族（全部 Release Candidate）",
+        "status": "verified",
+        "wording_anchors": [
+          "feature_flag.key",
+          "feature_flag.provider.name",
+          "feature_flag.result.value",
+          "feature_flag.result.reason"
+        ],
+        "note": "生命周期卫生项（rollout 完成未删 Flag/无 Owner/永久实验——§74）是 POMaster 增值层非外部标准复制品：引用 OpenFeature 只声明求值语义锚，Owner/Expiry 保持 self-defined"
+      },
+      "db_schema": {
+        "source": "迁移工具 drift 检测（Liquibase：diff 比对单库当前态 vs 上一态、diff-changelog 比对两个目标库并可生成 missing changesets 回填、Drift Report 人可读可接 CI/CD；Drift Report 为 Liquibase Secure 商业版功能，diff/diff-changelog 在 Community 分册）",
+        "status": "verified",
+        "wording_anchors": [
+          "diff",
+          "diff-changelog",
+          "Drift Report"
+        ],
+        "note": "Flyway 侧未核实，禁写入（research Caveats 明示）"
+      },
+      "dependency": {
+        "source": "self-defined——无单点主流工具（research 2026-09-03 如实裁定）；12factor 只给原则：backing service 禁 dev/production 异构（resist the urge to use different backing services——即使适配器理论上抹平差异也会造成 dev/staging 过而 production 挂的细微不兼容）",
+        "status": "self-defined",
+        "wording_anchors": [],
+        "note": "禁伪造『业界标准做法』引用（research 差异表 §215 行裁定）"
+      },
+      "external_integration": {
+        "source": "self-defined——无单点主流工具（research 2026-09-03 如实裁定）",
+        "status": "self-defined",
+        "wording_anchors": [],
+        "note": "调用侧韧性/错误映射语义归 ARCHETYPE.BACKEND.EXTERNAL_INTEGRATION（八要素），本维只管跨环境一致性"
+      }
+    },
+    "environment_name": {
+      "wording": "deployment.environment.name",
+      "level": "Stable",
+      "well_known_values": [
+        "development",
+        "production",
+        "staging",
+        "test"
+      ],
+      "prd_environment_mapping": {
+        "LOCAL": "development",
+        "DEV": "development",
+        "TEST": "test",
+        "STAGING": "staging",
+        "PRODUCTION": "production"
+      },
+      "mapping_note": "PRD 五环境词形保留为主键（差异表 §215 行裁定）；OTel 无 LOCAL/DEV——LOCAL/DEV 归并 development 或用 custom value（OTel 明文允许：otherwise, a custom value MAY be used）；TEST↔test 直接映射；环境值不参与 service 唯一性约束（service.name=frontend 在 production 与 staging 仍视为同一 service——semconv 脚注逐字语义）"
+    },
+    "drift_output": {
+      "name": "ENVIRONMENT_DRIFT",
+      "binding": "与 Perception 的 Wrong Runtime Instance 机制直接结合（PRD §215 逐字）",
+      "shape": "期望态（Git/manifest/would-be applied/changelog）vs 实际态（live/DB）的持续或即时比对 + 结构化差异输出 + 退出码/状态机（kubectl diff 退出码 0/1、Argo CD OutOfSync 状态、Liquibase Drift Report 三者同构——research 跨工具归纳）",
+      "fields": [
+        "dimension",
+        "expected",
+        "actual",
+        "severity",
+        "ignore_rules"
+      ],
+      "severity": {
+        "levels": [
+          "CRITICAL",
+          "MAJOR",
+          "MINOR"
+        ],
+        "rule": "每条差异项必须带严重度：CRITICAL=影响正确性/安全（如 production 缺失 DB Schema 迁移）；MAJOR=行为不一致（如 Flag 求值结果漂移、Config 覆盖缺失）；MINOR=呈现性差异；严重度缺失的差异项不得静默入账",
+        "note": "分级词形为 POMaster 自有（self-defined）——业界工具给退出码/状态不给分级，分级是门禁消费所需增量"
+      },
+      "ignore_rules": {
+        "forms": [
+          "field_path（对照 Argo CD jsonPointers / jqPathExpressions）",
+          "manager（对照 Argo CD managedFieldsManagers）",
+          "value_pattern（随机值类——randAlphaNum 型模板函数每次生成不同值）"
+        ],
+        "noise_sources": [
+          "controller/mutating webhook 改写对象",
+          "HPA 重排 spec.metrics",
+          "随机模板函数每次生成不同值",
+          "manifest 含 K8s 未知字段"
+        ],
+        "rule": "忽略规则必须显式登记（字段路径 + 理由）；未登记的忽略禁静默——漂移噪声治理是漂移检测的必要组成（Argo CD 实证：应用可在成功 Sync 后立即 OutOfSync，无 ignoreDifferences 则门禁因误报被关掉——research 题 2 关键结论）"
+      }
+    }
+  },
+  "deprecated_wording_note": "旧词形 deployment.environment 已废弃（Deprecated：Replaced by deployment.environment.name——semconv registry 部署属性族 2026-09-03 实抓）；本物料全文以新词形 deployment.environment.name 为准，旧词形仅在本注记出现作改名映射锚（读到旧词形按新词形归一并记 drift 事件；semconv 当前有 schema 变换 moratorium 警告——勿做自动 schema 变换依赖）",
+  "constraints": [
+    "六维中 Dependency 与 External Integration 两维如实标注 self-defined（无单点主流工具）——禁伪造『业界标准做法』引用",
+    "环境名只写新词形 deployment.environment.name；旧词形仅限 deprecated 注记（集成 spec 正则闸 deployment\\.environment(?!\\.name)）",
+    "四维实锚事实源引用与版本位以 x-research-anchors provenance 为准——物料正文不硬编码工具版本号（工具版本随 release 漂移，语义锚不随）"
+  ],
+  "x-research-anchors": {
+    "note": "六维比对语义为 PRD §215 逐字；六维事实源锚（Spring profiles/kustomize/kubectl diff/Argo CD ignoreDifferences/OpenFeature/Liquibase drift）与 Dependency/External Integration 两维 self-defined 裁定均出自 runtime-references.md 题 2（2026-09-03 官方站点实抓）；deployment.environment.name 词形与 well-known 四值出自 semconv deployment 属性族同日实抓；severity+ignore_rules 内置为 research 题 2 落点建议采纳",
+    "sources": [
+      {
+        "url": ".trellis/tasks/09-02-vnext-prd-v06-governed-substrate/research/runtime-references.md 题 2",
+        "fetched": "2026-09-03"
+      },
+      {
+        "url": "https://12factor.net/dev-prod-parity",
+        "fetched": "2026-09-03"
+      },
+      {
+        "url": "https://docs.spring.io/spring-boot/reference/features/profiles.html",
+        "fetched": "2026-09-03"
+      },
+      {
+        "url": "https://raw.githubusercontent.com/kubernetes-sigs/kustomize/master/README.md",
+        "fetched": "2026-09-03"
+      },
+      {
+        "url": "https://kubernetes.io/docs/reference/kubectl/generated/kubectl_diff/",
+        "fetched": "2026-09-03"
+      },
+      {
+        "url": "https://argo-cd.readthedocs.io/en/stable/user-guide/diffing/",
+        "fetched": "2026-09-03"
+      },
+      {
+        "url": "https://openfeature.dev/",
+        "fetched": "2026-09-03"
+      },
+      {
+        "url": "https://docs.liquibase.com/secure/user-guide-5-2-2/what-is-drift-detection",
+        "fetched": "2026-09-03"
+      },
+      {
+        "url": "https://opentelemetry.io/docs/specs/semconv/registry/attributes/deployment/",
+        "fetched": "2026-09-03"
+      },
+      {
+        "url": "doc/POMaster-vNext-PRD-v0.6-Governed-Engineering-System.md §215",
+        "fetched": "2026-09-03"
+      }
+    ]
+  }
+}

package/catalog/archetypes/archetype.runtime.observability_binding.json

@@ -0,0 +1,93 @@
+{
+  "id": "RUNTIME_ARCHETYPE.OBSERVABILITY_BINDING",
+  "kind": "archetype",
+  "layer": "PATTERN",
+  "title_zh": "观测语义绑定模式",
+  "summary_zh": "观测语义绑定模式（PRD §85/§86/§102-§103）：OTel 是 Runtime Sensor Provider，POMaster 不替代 APM 只建立语义 Binding——信号对象、资源身份词形、按域成熟度三面绑定到 Runtime Graph，遥测本体留在 OTel/APM 侧。",
+  "semantic": {
+    "responsibility": "把 POMaster 对象系与 OTel 语义约定的对应关系单点化：每条绑定声明词形锚与成熟度档位（Stable/Release Candidate/Development/Mixed），禁把不同域当成统一标准引用——绑定是语义映射不是复制",
+    "when_to_use": "需要把 Runtime Graph/Deployment View 与遥测信号对齐时（§72 Version→service.version 一类映射）；§103 Runtime Sensor（SENSOR.OTEL.TRACE/SENSOR.OTEL.METRIC 词形锚）的语义消费面",
+    "when_not_to_use": "自建 APM/自研语义约定（OTel 是 Provider，POMaster 不复制其语义）；具体后端查询语句与仪表盘配置（APM 侧自有面）；采集器部署与采样策略运维（OTel Collector 自有面）"
+  },
+  "composition": {
+    "requires": [],
+    "optional": [],
+    "incompatible": []
+  },
+  "defaults": {
+    "signals": {
+      "bound": [
+        "traces",
+        "metrics",
+        "logs",
+        "profiles"
+      ],
+      "wording_source": "OTLP 四信号（Collector component-stability 文档明文列 profiles；OTel spec 侧有 Profiles Mappings/Pprof Profiles Data Format 章节——research 题 1 实抓）",
+      "gap_note": "PRD §85 信号对象清单（Trace/Metric/Log Event/Correlation ID/Span/Alert/Dashboard/SLO）漏 profiles——差异注记如实落位，Profile 对象待对象系增补（不私扩）"
+    },
+    "domain_status": {
+      "http": "Mixed",
+      "rpc": "Release Candidate",
+      "database": "Mixed",
+      "messaging": "Development",
+      "service": "Stable（实体 service/service.namespace/service.instance——§86 Service/Service Instance 映射经实体族成立）",
+      "service_instance": "Stable（service.instance.id 与 service.namespace,service.name 组成全局唯一三元组）",
+      "rule": "逐域附 Status 禁当统一标准——PRD §86 六个映射域成熟度不齐（research 2026-09-03 逐域 index.md 自述实抓：HTTP Mixed/Database Mixed/RPC Release Candidate/Messaging Development/FaaS Development）"
+    },
+    "resource_identity": {
+      "service.name": "Stable——逻辑服务名；未指定时 SDK 回落 unknown_service:<进程名>；水平扩缩全实例 MUST 同值",
+      "service.version": "Stable——服务组件版本串（格式不定义：2.0.0 或 git SHA 皆可）",
+      "deployment.environment.name": "Stable——部署环境名（well-known 值 development/production/staging/test）；不参与 service 唯一性约束",
+      "service.namespace": "Stable——命名空间（namespace 内 name 唯一）",
+      "service.instance.id": "Stable——全局唯一三元组成员；Collector 无法无歧义确定实例时不应代设（如按 pod.name 生成大概率错）"
+    },
+    "maturity_anchor": "semconv ≥ 现行版语义（禁硬编码版本号——semconv 月级发版，版本位入 x-research-anchors provenance；语义判卷以 registry attributes/entities 的 index.md 机器视图为准，/llms.txt 总索引可直接消费）",
+    "binding_form": "词形锚 + 成熟度档位 + 消费位三件式：每条绑定声明 OTel 词形、其 Status、以及 POMaster 侧消费对象（Runtime Graph 节点/Deployment View 字段）"
+  },
+  "binding_rule": "OTel 是 Runtime Sensor Provider：POMaster 只建立语义 Binding，不复制 APM（PRD §85 逐字：POMaster 不替代 APM，只建立语义 Binding。）——semconv 只定义属性/命名契约，观测本体（采集/存储/查询/告警）留在 OTel/APM 侧（研究题 1 差异表：与 OTel 定位一致，无冲突）",
+  "deprecated_wording_note": "resource 词形改名锚：deployment.environment（旧词形）已废弃（Deprecated：Replaced by deployment.environment.name——semconv deployment 属性族 2026-09-03 实抓）；本物料全文以新词形为准，旧词形仅在本注记出现",
+  "collector_status": "Collector 双版本线 v1.66.0/v0.160.0（2026-09-02 release，高频发版；组件标 1.x 要求至少一个 signal stable——traces/metrics/logs/profiles 各自独立稳定级，Development/Alpha/Beta/Stable/Deprecated/Unmaintained 阶梯）；代码基基于 OTLP protocol v1.10.0（Stable）构建——版本位随 provenance 更新，禁硬编码进 defaults",
+  "constraints": [
+    "§103 SENSOR.OTEL.TRACE/SENSOR.OTEL.METRIC 为 Runtime Sensor 词形锚（登记面）——本物料是语义 Binding 不登记 sensor 本体：OTel 无既有探测器/availability_probe 键可引，登记即假绿（『禁止空壳仪式』§10；真实 implementation 另批走 vocab/传感器 PR）",
+    "Config Hash/Migration Version/Traffic/Health 无 OTel 标准词形（research 差异表 §72 行）——Deployment View 后四项为 POMaster 自有词形（self-defined），禁误挂 semconv 锚",
+    "schema 变换引用须带 moratorium 意识（官方 Warning：暂停依赖 schema 变换实现遥测稳定性）——改名类变更以 schema 文件描述并发布，但消费面不做自动变换依赖；改名映射是单向注记不是自动变换（旧词形→新词形，见 deprecated 注记）",
+    "semconv 稳定性契约只保证属性 key/实体引用/span name 与 kind/metric name 与 unit/well-known 既有值——属性值本身、span links、metric description 不在保证范围（versioning-and-stability 官方原文语义）"
+  ],
+  "x-research-anchors": {
+    "note": "四信号（traces/metrics/logs/profiles）/逐域 Status/resource 词形与稳定级/Collector 双版本线均出自 runtime-references.md 题 1（2026-09-03 opentelemetry.io 官方文档 + GitHub API 实抓）；semconv 文档站与仓库 latest release 当时版本位 1.44.0（2026-08-04 发布）、Collector 当时 v0.160.0（2026-09-02 发布）记录于本注记作 provenance——按研究裁定禁入 defaults 硬编码（月级发版）；『POMaster 不替代 APM 只建立语义 Binding』为 PRD §85 逐字，与 OTel 定位无冲突（差异表 §85 行）",
+    "sources": [
+      {
+        "url": ".trellis/tasks/09-02-vnext-prd-v06-governed-substrate/research/runtime-references.md 题 1",
+        "fetched": "2026-09-03"
+      },
+      {
+        "url": "https://opentelemetry.io/docs/specs/semconv/",
+        "fetched": "2026-09-03"
+      },
+      {
+        "url": "https://opentelemetry.io/docs/specs/otel/document-status/",
+        "fetched": "2026-09-03"
+      },
+      {
+        "url": "https://opentelemetry.io/docs/specs/otel/versioning-and-stability/",
+        "fetched": "2026-09-03"
+      },
+      {
+        "url": "https://opentelemetry.io/docs/specs/semconv/registry/attributes/service/index.md",
+        "fetched": "2026-09-03"
+      },
+      {
+        "url": "https://opentelemetry.io/docs/specs/semconv/registry/attributes/deployment/",
+        "fetched": "2026-09-03"
+      },
+      {
+        "url": "https://raw.githubusercontent.com/open-telemetry/opentelemetry-collector/main/docs/component-stability.md",
+        "fetched": "2026-09-03"
+      },
+      {
+        "url": "doc/POMaster-vNext-PRD-v0.6-Governed-Engineering-System.md §85/§86/§102/§103",
+        "fetched": "2026-09-03"
+      }
+    ]
+  }
+}

package/catalog/archetypes/archetype.state.async_command.json

@@ -0,0 +1,63 @@
+{
+  "id": "STATE_ARCHETYPE.ASYNC_COMMAND",
+  "kind": "archetype",
+  "layer": "PATTERN",
+  "title_zh": "异步命令状态机",
+  "summary_zh": "以 XState v5 六概念（state/event/transition/guard/actor/input/output）承载的异步命令原型：命令参数经 input 进入，状态经 guarded transition 确定性转移，final state 产出 output；非法组合经 transition contract 显式声明（实现侧绑定 state.can() 守卫位）。",
+  "semantic": {
+    "responsibility": "把一次异步命令（提交/保存/执行）建模为显式状态机：idle/running/done|error 转移全部声明在案，guard 纯同步布尔",
+    "when_to_use": "命令的合法状态转移需要显式契约时（非法组合必须可表达为「未声明的 transition 不存在」）；多步骤异步编排（invoke/spawn actor）",
+    "when_not_to_use": "远端取数缓存语义（STATE_ARCHETYPE.SERVER_QUERY）；无需显式转移契约的局部加载布尔"
+  },
+  "composition": {
+    "requires": [],
+    "optional": [],
+    "incompatible": []
+  },
+  "defaults": {
+    "vocabulary": [
+      "state",
+      "event",
+      "transition",
+      "guard",
+      "actor",
+      "input",
+      "output"
+    ],
+    "guard_nature": "pure_synchronous_boolean",
+    "guard_style": "serialized_named",
+    "transition_determinism": true,
+    "unmatched_event": "ignored_state_unchanged",
+    "output_semantics": "final_state_only"
+  },
+  "forbidden": [
+    "在 output 语义位放中途产物（output 仅到达 final state 时存在）",
+    "直接改 context（immutable，仅 assign 更新）",
+    "断言未匹配事件会运行时报错（XState v5 现实是静默忽略+state.can() 为 false——非法组合的表达位是 transition contract 声明与 can() 守卫位）"
+  ],
+  "x-research-anchors": {
+    "note": "【待 Owner 裁定·差异表 #7】PRD「Illegal Transition 必须可表达」在 XState v5（npm 5.32.6）无对应词形：未匹配/未启用事件=「no enabled transition → state does not change」静默忽略，state.can() 显式守卫为唯一查询位。本物料落 PRD 语义意图（非法组合经 transition contract 显式声明）+实现绑定注记 can() 守卫位；是否以治理层概念保留 Illegal Transition 词形待裁定。六概念词形与 guard 序列化命名推荐（reusability+visualization）均为 stately.ai 官方文档 2026-09-03 实抓",
+    "sources": [
+      {
+        "url": "https://stately.ai/docs/transitions",
+        "fetched": "2026-09-03"
+      },
+      {
+        "url": "https://stately.ai/docs/guards",
+        "fetched": "2026-09-03"
+      },
+      {
+        "url": "https://stately.ai/docs/input",
+        "fetched": "2026-09-03"
+      },
+      {
+        "url": "https://stately.ai/docs/output",
+        "fetched": "2026-09-03"
+      },
+      {
+        "url": "https://registry.npmjs.org/xstate",
+        "fetched": "2026-09-03"
+      }
+    ]
+  }
+}

package/catalog/archetypes/archetype.state.background_refresh.json

@@ -0,0 +1,45 @@
+{
+  "id": "STATE_ARCHETYPE.BACKGROUND_REFRESH",
+  "kind": "archetype",
+  "layer": "PATTERN",
+  "title_zh": "后台刷新状态",
+  "summary_zh": "stale-while-revalidate 后台刷新原型（TanStack v5 默认档）：staleTime 0 缓存即换，挂载/窗口聚焦/断线重连三触发自动 refetch；invalidateQueries 标 stale 并对渲染中查询后台补捞。",
+  "semantic": {
+    "responsibility": "远端缓存的过期判定与自动补捞触发面（mount/window_focus/reconnect 三触发+语义化 invalidation）",
+    "when_to_use": "STATE_ARCHETYPE.SERVER_QUERY 承载的远端资源的默认保鲜策略——mutation 后语义化 invalidation（前缀匹配 query key）也在本原型表达",
+    "when_not_to_use": "永不刷新的静态参照表（staleTime:'static'——invalidateQueries 对其无效）；仅一次性取数"
+  },
+  "composition": {
+    "requires": [],
+    "optional": [
+      "STATE_ARCHETYPE.SERVER_QUERY"
+    ],
+    "incompatible": []
+  },
+  "defaults": {
+    "refetch_on": [
+      "mount",
+      "window_focus",
+      "reconnect"
+    ],
+    "refetch_on_window_focus": true,
+    "invalidate_overrides_staleTime": true,
+    "invalidate_semantics": "标 stale+渲染中才后台 refetch（前缀匹配/exact:true/predicate）"
+  },
+  "forbidden": [
+    "假设 invalidateQueries 必发即时请求（仅标记 stale，正在渲染才后台 refetch）"
+  ],
+  "x-research-anchors": {
+    "note": "三触发默认与 invalidateQueries「覆盖 staleTime+渲染中才 refetch」语义为 TanStack Query v5 important-defaults/query-invalidation 官方文档 2026-09-03 实抓；与 SERVER_QUERY 经 composition.optional 互链（批次 2 组合链边）",
+    "sources": [
+      {
+        "url": "https://tanstack.com/query/latest/docs/framework/react/guides/important-defaults.md",
+        "fetched": "2026-09-03"
+      },
+      {
+        "url": "https://tanstack.com/query/latest/docs/framework/react/guides/query-invalidation.md",
+        "fetched": "2026-09-03"
+      }
+    ]
+  }
+}

package/catalog/archetypes/archetype.state.form_edit.json

@@ -0,0 +1,45 @@
+{
+  "id": "STATE_ARCHETYPE.FORM_EDIT",
+  "kind": "archetype",
+  "layer": "PATTERN",
+  "title_zh": "表单编辑草稿状态",
+  "summary_zh": "未保存表单草稿的本地编辑状态原型：字段值、校验状态与脏标记归表单容器持有，不进全局 Store 也不写 URL；校验状态词形按 AntD Form validateStatus 四值锚定。",
+  "semantic": {
+    "responsibility": "持有未提交草稿的字段值/校验结果/脏标记，提交成功后交出所有权",
+    "when_to_use": "未保存表单草稿（v0.6.1 §17 判定行「未保存表单草稿 → FORM」）——编辑抽屉/对话框内草稿、多字段录入面",
+    "when_not_to_use": "已提交数据的远端缓存（STATE_ARCHETYPE.SERVER_QUERY）；可分享筛选（STATE_ARCHETYPE.URL_FILTER）"
+  },
+  "composition": {
+    "requires": [],
+    "optional": [],
+    "incompatible": []
+  },
+  "defaults": {
+    "ownership": "form_container_local",
+    "validation_status_words": [
+      "success",
+      "warning",
+      "error",
+      "validating"
+    ],
+    "validation_status_source": "AntD Form validateStatus 官方四值（external-design-references.md 2026-09-02 正文明抓）",
+    "dirty_tracking": "pristine/dirty 二态起点"
+  },
+  "forbidden": [
+    "草稿直写全局 Store（v0.6.1 §17「禁止默认全部放全局 Store」的表单形态）",
+    "校验状态自造第五词形（success/warning/error/validating 四值闭包外）"
+  ],
+  "x-research-anchors": {
+    "note": "校验状态四值 success/warning/error/validating 为 AntD Form API 正文明抓（external-design-references.md 对应锚，2026-09-02）；§17 判定行与禁全局 Store 语义为 PRD 事实源（2026-09-03 对照 frontend-state-references.md 差异表 #3 无冲突确认）",
+    "sources": [
+      {
+        "url": "https://ant.design/components/form",
+        "fetched": "2026-09-02"
+      },
+      {
+        "url": "doc/POMaster-vNext-PRD-v0.6.1-Engineering-Substrate-Archetype-Catalog.md §17",
+        "fetched": "2026-09-03"
+      }
+    ]
+  }
+}

package/catalog/archetypes/archetype.state.optimistic_mutation.json

@@ -0,0 +1,48 @@
+{
+  "id": "STATE_ARCHETYPE.OPTIMISTIC_MUTATION",
+  "kind": "archetype",
+  "layer": "PATTERN",
+  "title_zh": "乐观更新 mutation",
+  "summary_zh": "写操作的乐观更新原型（TanStack Query v5 官方链序实抓）：onMutate 取消在飞 refetch→快照→乐观写入→返回快照；onError 回滚；onSettled 无条件 invalidate 并保持 pending 至 refetch 完成。",
+  "semantic": {
+    "responsibility": "把「先显示后确认」的写路径标准化为五步链序，rollback 与补捞（invalidate）不靠手写自觉",
+    "when_to_use": "多处联动感知写结果的 cache 路线（§17「远端资源」判定的写侧）；单处展示的临时项走 variables/isPending 的 UI 路线（免 rollback）——官方「When to use what」决策规则",
+    "when_not_to_use": "非远端同步的本地草稿（STATE_ARCHETYPE.FORM_EDIT）；无并发覆盖风险的低频写（直接 invalidate 亦可）"
+  },
+  "composition": {
+    "requires": [],
+    "optional": [],
+    "incompatible": []
+  },
+  "defaults": {
+    "sequence": [
+      "cancel_inflight_refetch",
+      "snapshot",
+      "optimistic_write",
+      "on_error_rollback",
+      "on_settled_invalidate"
+    ],
+    "sequence_note": "cancelQueries→getQueryData 快照→setQueryData→onError 回滚→onSettled 无条件 invalidateQueries（return promise 保持 pending 至 refetch 完成）——官方链序原样",
+    "invalidate_on_settled": true,
+    "await_invalidation": true,
+    "dual_route_note": "官方两路线：单处展示用 variables/isPending 的 UI 路线（无需 rollback）；多处联动用 cache 路线（本链序）"
+  },
+  "forbidden": [
+    "跳过 cancelQueries 直接写缓存（在飞 refetch 会覆盖乐观值）",
+    "只在 onError invalidate 而 onSettled 缺失（成功路径漏 refetch）",
+    "rollback 后不 invalidate"
+  ],
+  "x-research-anchors": {
+    "note": "五步链序与「onSettled 无条件 invalidate+return promise 保持 pending」为 TanStack Query v5 optimistic-updates/mutations 官方文档 2026-09-03 实抓（现行回调签名带 context 尾参）",
+    "sources": [
+      {
+        "url": "https://tanstack.com/query/latest/docs/framework/react/guides/optimistic-updates.md",
+        "fetched": "2026-09-03"
+      },
+      {
+        "url": "https://tanstack.com/query/latest/docs/framework/react/guides/mutations.md",
+        "fetched": "2026-09-03"
+      }
+    ]
+  }
+}

package/catalog/archetypes/archetype.state.selection.json

@@ -0,0 +1,35 @@
+{
+  "id": "STATE_ARCHETYPE.SELECTION",
+  "kind": "archetype",
+  "layer": "PATTERN",
+  "title_zh": "临时选中状态",
+  "summary_zh": "临时展开/选中类本地交互状态原型：生命周期限于当前视图实例，刷新即失、不入 URL、不进全局 Store——最便宜的所有权归最近持有者。",
+  "semantic": {
+    "responsibility": "持有视图实例私有的瞬时交互态（行选中/展开/焦点/tab 内高亮）",
+    "when_to_use": "临时展开/选中（v0.6.1 §17 判定行「临时展开/选中 → LOCAL_UI」）——组件本地 useState 即默认落点",
+    "when_not_to_use": "刷新后需保留的状态（升 STATE_ARCHETYPE.URL_FILTER 或 SERVER_QUERY）；跨页面会话（DOMAIN/SESSION 所有权，§17 判定行「跨页面业务 Session」）；「禁止默认全部放全局 Store」对本态最严格"
+  },
+  "composition": {
+    "requires": [],
+    "optional": [],
+    "incompatible": []
+  },
+  "defaults": {
+    "ownership": "component_local",
+    "persist_scope": "none",
+    "restore_on_refresh": false
+  },
+  "forbidden": [
+    "把临时选中提升进全局 Store（§17 禁默认全部放全局 Store）",
+    "把可分享筛选降格为本地位（应升 STATE_ARCHETYPE.URL_FILTER）"
+  ],
+  "x-research-anchors": {
+    "note": "所有权判定锚 PRD §17 State Ownership Resolver 判定表（2026-09-03 对照 frontend-state-references.md 差异表 #2/#3 无冲突确认）",
+    "sources": [
+      {
+        "url": "doc/POMaster-vNext-PRD-v0.6.1-Engineering-Substrate-Archetype-Catalog.md §17",
+        "fetched": "2026-09-03"
+      }
+    ]
+  }
+}

package/catalog/archetypes/archetype.state.server_query.json

@@ -0,0 +1,60 @@
+{
+  "id": "STATE_ARCHETYPE.SERVER_QUERY",
+  "kind": "archetype",
+  "layer": "PATTERN",
+  "title_zh": "服务端查询状态",
+  "summary_zh": "远端资源的异步取数状态原型（TanStack Query v5 词形锚定）：数据轴 status 与网络轴 fetchStatus 双轴分离，isPending/isFetching/isLoading 三词形语义各司其职，缓存与后台刷新默认档开箱即用。",
+  "semantic": {
+    "responsibility": "持有远端取数的缓存、去重与刷新生命周期（stale-while-revalidate），把「有没有数据」与「请求是否进行中」表达为两个正交词轴",
+    "when_to_use": "状态的所有权在远端：数据持久化在服务端、经异步 API 获取、可能被他人改动而过期（v0.6.1 §17 判定行「远端资源 → SERVER_QUERY」）——列表/详情/报表取数面默认归位",
+    "when_not_to_use": "可分享/可收藏筛选（STATE_ARCHETYPE.URL_FILTER）；未保存表单草稿（STATE_ARCHETYPE.FORM_EDIT）；纯本地交互态（STATE_ARCHETYPE.SELECTION）"
+  },
+  "composition": {
+    "requires": [],
+    "optional": [],
+    "incompatible": []
+  },
+  "defaults": {
+    "word_form_distinction": {
+      "isPending": "数据轴 status==='pending'——尚无任何数据（不等于请求进行中）",
+      "isFetching": "网络轴 fetchStatus==='fetching'——queryFn 正在抓取（含后台 refetch，任何 status 下可为 true）",
+      "isLoading": "isPending && isFetching——仅「无数据且在抓取」的首次加载词形（v4 isInitialLoading 改名，v5 现行口径）"
+    },
+    "status_axis": [
+      "pending",
+      "error",
+      "success"
+    ],
+    "fetch_status_axis": [
+      "fetching",
+      "paused",
+      "idle"
+    ],
+    "staleTime": 0,
+    "gcTime": "5min",
+    "retry": 3,
+    "structural_sharing": true
+  },
+  "forbidden": [
+    "单一扁平 loading 布尔同时表达数据有无与请求进行中（v5 拆分双轴）",
+    "v4 旧词形：status:'loading' / cacheTime / isInitialLoading",
+    "把 isPending 当「请求中」用（应表达为尚无数据）"
+  ],
+  "x-research-anchors": {
+    "note": "TanStack Query v5（npm 5.102.8）双轴模型与 Important Defaults（staleTime 0/gcTime 5min/retry 3/structural sharing）为官网 .md 文档实抓；isPending≠isFetching≠isLoading 三词形区分是 v4→v5 breaking 官方口径（2026-09-03 实抓）",
+    "sources": [
+      {
+        "url": "https://tanstack.com/query/latest/docs/framework/react/guides/queries.md",
+        "fetched": "2026-09-03"
+      },
+      {
+        "url": "https://tanstack.com/query/latest/docs/framework/react/guides/important-defaults.md",
+        "fetched": "2026-09-03"
+      },
+      {
+        "url": "https://tanstack.com/query/latest/docs/framework/react/guides/migrating-to-v5.md",
+        "fetched": "2026-09-03"
+      }
+    ]
+  }
+}

package/catalog/archetypes/archetype.state.url_filter.json

@@ -0,0 +1,47 @@
+{
+  "id": "STATE_ARCHETYPE.URL_FILTER",
+  "kind": "archetype",
+  "layer": "PATTERN",
+  "title_zh": "URL 筛选状态",
+  "summary_zh": "以 URL 查询串为事实源的筛选状态原型（nuqs 2.10.1：「the URL is the source of truth」）：筛选/分页/排序/tab 定位写入 URL 后天然可分享、可收藏、刷新保留、回退保留。",
+  "semantic": {
+    "responsibility": "把「可分享/可收藏/刷新保留/回退保留」四触发条件的筛选状态所有权交给 URL，序列化规则单点",
+    "when_to_use": "状态需要通过 URL 分享、收藏、刷新后保留或浏览器回退保留时（v0.6.1 §17 判定行「可分享/可收藏的筛选条件 → URL」）——列表筛选、分页、排序、tab 定位是典型",
+    "when_not_to_use": "大对象/不可序列化状态；临时展开/选中（STATE_ARCHETYPE.SELECTION）；高维筛选全量入参会参数爆炸（只放分享者视角关键参数）"
+  },
+  "composition": {
+    "requires": [],
+    "optional": [],
+    "incompatible": []
+  },
+  "defaults": {
+    "source_of_truth": "URL is the source of truth（nuqs 自我定位）",
+    "serialization": "search_params_string",
+    "read_only_view_client": true,
+    "replace_history_for_typed_input": true,
+    "push_history_for_discrete_changes": true,
+    "dual_surface_note": "Next.js App Router 双端形态：Client 侧 useSearchParams 只读同步（prerendered 路由须包 Suspense 边界）；Server 侧 Page searchParams prop 为 Promise 异步形态（v15 起，同步访问已标记将废弃）"
+  },
+  "forbidden": [
+    "Server Component 直接调 useSearchParams（Next.js 明确不支持）",
+    "prerendered 路由无 Suspense 边界使用 client searchParams hook",
+    "绕过序列化规则自造查询串格式（有 nuqs/框架 adapter 时应引用）"
+  ],
+  "x-research-anchors": {
+    "note": "nuqs npm latest 2.10.1 与 GitHub README「the URL is the source of truth」实抓；Next.js 16.3.4 文档 useSearchParams 只读 client 形态与 Page searchParams Promise 双端形态实抓（2026-09-03）",
+    "sources": [
+      {
+        "url": "https://registry.npmjs.org/nuqs",
+        "fetched": "2026-09-03"
+      },
+      {
+        "url": "https://nextjs.org/docs/app/api-reference/functions/use-search-params.md",
+        "fetched": "2026-09-03"
+      },
+      {
+        "url": "https://nextjs.org/docs/app/api-reference/file-conventions/page.md",
+        "fetched": "2026-09-03"
+      }
+    ]
+  }
+}