@pisell/private-materials 6.12.168 → 6.12.169

package/es/components/HDLKiosk/{contracts → app/contracts}/config.js

@@ -1,4 +1,4 @@
-//#region src/components/HDLKiosk/contracts/config.ts
+//#region src/components/HDLKiosk/app/contracts/config.ts
 const ALL_ENTRY_MODES = Object.freeze([
 	"quick",
 	"barcode",

package/es/components/HDLKiosk/app/manifest.js

@@ -1,9 +1,5 @@
-import { defineKioskApplication } from "../kernel/application/defineApplication.js";
-import { createOperationRegistry } from "./operations/types.js";
-import { barcodeConsumeOperation } from "./operations/barcode.js";
-import { cartRemoveLineOperation, cartUpdateQuantityOperation } from "./operations/cart.js";
-import { checkoutOpenOperation, checkoutPrepareOperation } from "./operations/checkout.js";
-import { sessionEnsureOperation, sessionResetOperation } from "./operations/session.js";
+import { defineApplication, defineTrigger } from "../kernel/application/defineApplication.js";
+import { barcodeConsumeOperation, cartRemoveLineOperation, cartUpdateQuantityOperation, checkoutOpenOperation, checkoutPrepareOperation, sessionEnsureOperation, sessionResetOperation } from "./operations.js";
 import { hdlKioskSlices } from "../slices/index.js";
 import { barcodeWorkflow } from "./workflow/barcode.js";
 import { quickOrderWorkflow } from "./workflow/quick.js";
@@ -15,7 +11,7 @@ import { scaleWorkflow } from "./workflow/scale.js";
 * session/device 等不归属于具体 Slice 的 Operation，并绑定三条 Workflow。
 * 边界：Runtime 只消费 Manifest，不再分别创建 Activity/Operation/Workflow 注册表。
 */
-const hdlKioskApplication = defineKioskApplication({
+const hdlKioskApplication = defineApplication({
 	id: "hdl-kiosk",
 	slices: hdlKioskSlices,
 	workflows: {
@@ -23,6 +19,13 @@ const hdlKioskApplication = defineKioskApplication({
 		barcode: barcodeWorkflow,
 		scale: scaleWorkflow
 	},
+	triggers: [defineTrigger({
+		id: "onScan",
+		mode: "automatic"
+	}), defineTrigger({
+		id: "onWeight",
+		mode: "automatic"
+	})],
 	operations: [
 		sessionEnsureOperation,
 		sessionResetOperation,
@@ -33,8 +36,5 @@ const hdlKioskApplication = defineKioskApplication({
 		checkoutPrepareOperation
 	]
 });
-function createHDLKioskOperationRegistry() {
-	return createOperationRegistry([...hdlKioskApplication.operations.values()]);
-}
 //#endregion
-export { createHDLKioskOperationRegistry, hdlKioskApplication };
+export { hdlKioskApplication };

package/es/components/HDLKiosk/app/operations.js

@@ -0,0 +1,92 @@
+import { defineKernelOperationContract } from "../kernel/operations/types.js";
+//#region src/components/HDLKiosk/app/operations.ts
+function defineOperationContract(contract) {
+	return defineKernelOperationContract(contract);
+}
+const identitySyncOperation = defineOperationContract({
+	id: "identity.sync",
+	conflictScope: "customer",
+	timeoutMs: 15e3,
+	retry: "explicit-user"
+});
+const productRemovePrimaryProductOperation = defineOperationContract({
+	id: "product.removePrimaryProduct",
+	conflictScope: "cart",
+	timeoutMs: 15e3,
+	retry: "explicit-user"
+});
+const productSyncPrimaryWeightedProductOperation = defineOperationContract({
+	id: "product.syncPrimaryWeightedProduct",
+	conflictScope: "cart",
+	retry: "explicit-user"
+});
+const barcodeConsumeOperation = defineOperationContract({
+	id: "barcode.consume",
+	conflictScope: "cart",
+	retry: "explicit-user"
+});
+const cartAddProductOperation = defineOperationContract({
+	id: "cart.addProduct",
+	conflictScope: "cart",
+	retry: "explicit-user"
+});
+const cartUpdateQuantityOperation = defineOperationContract({
+	id: "cart.updateQuantity",
+	conflictScope: "cart",
+	timeoutMs: 15e3,
+	retry: "explicit-user"
+});
+const cartRemoveLineOperation = defineOperationContract({
+	id: "cart.removeLine",
+	conflictScope: "cart",
+	timeoutMs: 15e3,
+	retry: "explicit-user"
+});
+const setFulfillmentOperation = defineOperationContract({
+	id: "fulfillment.set",
+	conflictScope: "cart",
+	timeoutMs: 2e4,
+	retry: "explicit-user"
+});
+const sessionEnsureOperation = defineOperationContract({
+	id: "session.ensure",
+	conflictScope: "session",
+	timeoutMs: 15e3,
+	retry: "explicit-user"
+});
+const sessionResetOperation = defineOperationContract({
+	id: "session.reset",
+	tags: ["session-reset"],
+	conflictScope: "session",
+	timeoutMs: 15e3,
+	retry: "never"
+});
+const checkoutPrepareOperation = defineOperationContract({
+	id: "checkout.prepare",
+	conflictScope: "checkout",
+	timeoutMs: 2e4,
+	retry: "explicit-user"
+});
+const checkoutOpenOperation = defineOperationContract({
+	id: "checkout.open",
+	tags: ["checkout-dispatch"],
+	conflictScope: "checkout",
+	timeoutMs: 12e4,
+	retry: "never"
+});
+const checkoutPayEftposOperation = defineOperationContract({
+	id: "checkout.payEftpos",
+	tags: ["checkout-dispatch"],
+	conflictScope: "checkout",
+	timeoutMs: 12e4,
+	retry: "never"
+});
+const checkoutRequestStaffPaymentApprovalOperation = defineOperationContract({
+	id: "checkout.requestStaffPaymentApproval",
+	tags: ["checkout-authorization"],
+	conflictScope: "checkout",
+	timeoutMs: 2e4,
+	retry: "explicit-user"
+});
+//#endregion
+export { barcodeConsumeOperation, cartAddProductOperation, cartRemoveLineOperation, cartUpdateQuantityOperation, checkoutOpenOperation, checkoutPayEftposOperation, checkoutPrepareOperation, checkoutRequestStaffPaymentApprovalOperation, identitySyncOperation, productRemovePrimaryProductOperation, productSyncPrimaryWeightedProductOperation, sessionEnsureOperation, sessionResetOperation, setFulfillmentOperation };

package/es/components/HDLKiosk/app/workflow/barcode.js

@@ -7,14 +7,18 @@ import { primaryProductPromptSlice } from "../../slices/primaryProductPrompt/sli
 //#region src/components/HDLKiosk/app/workflow/barcode.ts
 /**
 * 文件角色：声明 Barcode 入口的有序业务步骤。
-* 运行机制：Workflow 从 Catalog 开始；首码在 Session readyForCommands 后由全局 Scanner
-* Controller 消费。Catalog 完成补充购物后进入独立的主商品询问 Modal，需要时进入
+* 运行机制：onScan Trigger 创建并发布 Session，再在 readyForCommands 后消费首码。
+* Workflow 从 Catalog 开始，完成补充购物后进入独立的主商品询问 Modal，需要时进入
 * Customization；无论选择或拒绝，最终都直接进入 Fulfillment。
 * 边界：设备扫码属于 Session 输入，不是可前进/后退的 Activity；支付 prepare 由支付
 * Operation 在 dispatch 前统一保证，不绑定 Catalog transition。
 */
 const barcodeWorkflow = defineWorkflow({
 	id: "hdl.barcode",
+	start: {
+		trigger: "onScan",
+		channel: "product"
+	},
 	steps: [
 		catalogSlice,
 		{
@@ -28,7 +32,7 @@ const barcodeWorkflow = defineWorkflow({
 		paymentMethodSlice,
 		{
 			slice: paymentCompletedSlice,
-			end: "success"
+			isTerminal: true
 		}
 	]
 });

package/es/components/HDLKiosk/app/workflow/index.js

@@ -0,0 +1,16 @@
+import "./barcode.js";
+import "./quick.js";
+import "./scale.js";
+import "./registry.js";
+import "./predicates.js";
+import "./navigationGuards.js";
+import "./policy.js";
+//#region src/components/HDLKiosk/app/workflow/index.ts
+/** 允许注册到本应用的内建 Workflow ID。 */
+const HDL_WORKFLOW_IDS = Object.freeze([
+	"hdl.quick",
+	"hdl.barcode",
+	"hdl.scale"
+]);
+//#endregion
+export { HDL_WORKFLOW_IDS };

package/es/components/HDLKiosk/app/workflow/predicates.js

@@ -20,4 +20,4 @@ function createPredicateRegistry(overrides = {}) {
 }
 const defaultPredicateRegistry = createPredicateRegistry();
 //#endregion
-export { defaultPredicateRegistry };
+export { createPredicateRegistry, defaultPredicateRegistry };

package/es/components/HDLKiosk/app/workflow/quick.js

@@ -23,7 +23,7 @@ const quickOrderWorkflow = defineWorkflow({
 		paymentMethodSlice,
 		{
 			slice: paymentCompletedSlice,
-			end: "success"
+			isTerminal: true
 		}
 	]
 });

package/es/components/HDLKiosk/app/workflow/registry.js

@@ -1,4 +1,4 @@
-import { createApplicationActivityRegistry, normalizeKioskWorkflow } from "../../kernel/application/defineApplication.js";
+import { createApplicationActivityRegistry, normalizeApplicationWorkflow } from "../../kernel/application/defineApplication.js";
 import { hdlKioskApplication } from "../manifest.js";
 //#region src/components/HDLKiosk/app/workflow/registry.ts
 const manifestRegistry = createApplicationActivityRegistry(hdlKioskApplication);
@@ -10,9 +10,9 @@ const defaultActivityRegistry = Object.freeze({
 	accepts: (id, intent) => manifestRegistry.require(id).intents.some((availableIntent) => availableIntent === intent)
 });
 const BUILT_IN_WORKFLOW_DEFINITIONS = Object.freeze({
-	quick: normalizeKioskWorkflow(hdlKioskApplication.workflows.quick),
-	barcode: normalizeKioskWorkflow(hdlKioskApplication.workflows.barcode),
-	scale: normalizeKioskWorkflow(hdlKioskApplication.workflows.scale)
+	quick: normalizeApplicationWorkflow(hdlKioskApplication.workflows.quick),
+	barcode: normalizeApplicationWorkflow(hdlKioskApplication.workflows.barcode),
+	scale: normalizeApplicationWorkflow(hdlKioskApplication.workflows.scale)
 });
 function getBuiltInWorkflowDefinition(entry) {
 	return BUILT_IN_WORKFLOW_DEFINITIONS[entry];

package/es/components/HDLKiosk/app/workflow/scale.js

@@ -13,6 +13,10 @@ import { paymentCompletedSlice, paymentMethodSlice } from "../../slices/payment/
 */
 const scaleWorkflow = defineWorkflow({
 	id: "hdl.scale",
+	start: {
+		trigger: "onWeight",
+		channel: "weighing-product"
+	},
 	steps: [
 		customizationSlice,
 		catalogSlice,
@@ -20,7 +24,7 @@ const scaleWorkflow = defineWorkflow({
 		paymentMethodSlice,
 		{
 			slice: paymentCompletedSlice,
-			end: "success"
+			isTerminal: true
 		}
 	]
 });

package/es/components/HDLKiosk/docs/00-/346/226/207/344/273/266/345/257/274/350/210/252.md

@@ -1,199 +1,136 @@
 # HDLKiosk 文件导航
 
-本文按当前代码事实说明目录职责。第一次接触 HDLKiosk 时，先看本页，再看《01-核心运行机制》和目标业务 Slice。
+本文按当前代码事实说明所有权和依赖边界。详细运行模型见《01-核心运行机制》和《08-无头 Application Runtime 重构设计》。
 
-## 1. 主调用方向
+## 1. 固定依赖方向
 
 ```text
-HDLKiosk Root
-  → app/manifest + app/workflow
-  → runtime session/controllers
-  → kernel workflow actor + operation coordinator
-  → slices slice/view
-  → components shell/overlay/common
-  → contracts host ports
-  → BigSale template adapter
+kernel ← app ← runtime ← ui
+           ↑              ↑
+         slices ───────────┘
 ```
 
-依赖方向只能由上层装配指向稳定协议或下层能力。`kernel` 不认识 HDLKiosk、React、BigSale；`slices` 不直接调用 Host；`components` 不拥有流程跳转。
+- `kernel/` 是通用基础包，不认识 HDLKiosk、Host、商品、设备或 React。
+- `app/` 是 HDLKiosk 业务 Application，只包含协议、流程和静态策略，可脱离 UI。
+- `runtime/` 绑定 Host Port、Operation Handler 和 Trigger Adapter，产出可执行 Runtime。
+- `slices/` 按 feature 并置协议定义和 React View；`app` 只允许读取其 `slice.ts` 协议出口。
+- `ui/` 是 Runtime 的可选 React 适配层；`components/` 只保留跨 Slice 的共享视觉组件。
 
-## 2. 当前顶层结构
+`architectureBoundary.test.ts` 会阻止 `app → runtime/UI` 和 `runtime → React/UI` 的反向依赖。
 
-```text
-HDLKiosk/
-├── app/          # 应用清单、流程、共享 Operation 入口、Entry 与节点渲染装配
-├── slices/       # 纵向业务切片
-├── components/   # 跨切片共享 UI 与样式
-├── runtime/      # React 生命周期、会话与 Actor 连接层
-├── contracts/    # Host、订单、设备、流程和 Operation 协议
-├── kernel/       # 与商家无关的 Workflow/Application/Operation 内核
-├── devices/      # 扫码、称重入口治理与 Scale Runtime
-├── testing/      # FakeHost、fixture 和测试工具
-├── docs/         # 常驻设计与维护文档
-├── types.ts      # 公共 Props、Action、ViewModel 与 Slice View Context
-├── utils.ts      # 跨 Slice 纯方法与安全错误呈现
-├── index.tsx     # 独立物料根组件
-├── index.less    # 全局样式聚合
-├── locales.ts    # 文案
-└── product.ts    # 标准 ProductData 的轻量读取辅助
-```
-
-顶层目录只表达稳定职责，业务能力、共享组件、流程和副作用分别从 `slices`、`components` 与 `app` 进入。
-
-## 3. `app/`：一套 Kiosk 如何被装配
-
-| 文件/目录 | 角色 |
-| --- | --- |
-| `manifest.ts` | 唯一应用清单；收集 Slice 提供的 Activity/Operation，并绑定三条 Workflow |
-| `constants.ts` | `HDL_WORKFLOW_IDS` 等应用常量 |
-| `events.ts` | HDLKiosk Activity Intent 与 Back Navigation 的强类型事件联合 |
-| `operations.ts` | 共享 Operation 的唯一公共导入入口 |
-| `operations/` | `operations.ts` 背后的私有实现、Coordinator 策略和测试；外部代码不要逐文件跨层引用 |
-| `views.ts` | 应用层 Activity → React View 的完整同步注册表；不进入 Slice/Workflow/Kernel |
-| `workflow/quick.ts` | Quick 的有序 Activity 列表与特殊转移 |
-| `workflow/barcode.ts` | Barcode 的有序 Activity 列表与特殊转移 |
-| `workflow/scale.ts` | Scale 的有序 Activity 列表与特殊转移 |
-| `workflow/registry.ts` | 从 Manifest 派生 Activity Registry，并提供内置流程查询 |
-| `workflow/predicates.ts` | HDLKiosk 本地 Predicate Registry |
-| `workflow/policy.ts` | 支付门禁等商家应用策略校验；结构编译仍属于 Kernel |
-| `ScreenRenderer.tsx` | 按当前 Activity 从 `views.ts` 取 View；处理 modal base 叠加和缺失 View 的阻断呈现 |
-| `entry/model.ts` | 派生 Workflow 之外三个入口的可用性和展示模型 |
-| `entry/Screen/` | Workflow 之外的三个入口页面 |
-
-`compileWorkflowDefinition` 没有独立包装文件。会话启动处直接调用 Kernel 的 `compileWorkflowStructure`，随后执行 HDLKiosk policy 校验；测试在自身消费处声明小型 helper。
-
-## 4. `slices/`：纵向业务能力
-
-每个 Slice 把一个业务能力的定义和私有界面放在同一处：
+## 2. 顶层结构
 
 ```text
-slices/<name>/
-├── slice.ts         # 唯一导出的 defineSlice 结果：Activity、Screen、effect
-├── operation.ts     # 仅该 Slice 使用的业务副作用；没有则不创建
-├── view.tsx         # 本 Slice 的 ViewModel 派生与组件装配
-├── Screen|Dialog/   # 私有 UI 与样式
-└── model.ts         # 仅本 Slice 使用的纯模型；按需存在
+HDLKiosk/
+├── kernel/          # 通用 Application、Workflow 和 Operation 原语
+├── app/             # HDLKiosk Contracts、Manifest、Workflow、Operation Contract
+├── slices/          # 各 Activity 的协议定义、View、Screen 和局部模型
+├── runtime/         # Host Binding、设备入口、Trigger、Operation、Session Factory
+├── ui/              # React Entry、Controller、Renderer 和 Runtime hooks
+├── components/      # 跨 Slice 共享的 common/shell/overlay UI
+├── testing/         # FakeHost、fixture 和测试辅助
+├── docs/
+├── types.ts         # React 展示层公共类型
+├── utils.ts         # 跨 View 纯方法
+├── index.tsx
+└── index.less
 ```
 
-当前 Slice：`identity`、`fulfillment`、`customization`、`catalog`、`primaryProductPrompt`、`paymentMethod`、`paymentCompleted`。`primaryProductPrompt` 是以 Catalog 为 base 的 Modal；`paymentCompleted` 是支付成功终态，与 `paymentMethod` 共用 Checkout Screen/View。
-
-- `slices/index.ts` 只汇总各目录导出的 `defineSlice` 结果，并统一约束 `screen.id` 必须是 HDLKiosk `ScreenId`；
-- 每个 `slice.ts` 只通过 `screen: { id }` 声明页面类别；实际 View 在 `app/views.ts` 中按 Activity 单独、完整地注册，使用同步本地组件引用；
-- Slice 专属 Operation 与 Slice 同置，例如 `identity/operation.ts`；
-- Cart、Checkout、Session、Barcode 等跨 Slice Operation 从 `app/operations.ts` 导入。
-
-`Slice` 是作者侧唯一业务能力概念：`defineSlice` 定义能力，`application.slices` 收集能力，Workflow 的 `slice` 字段引用能力；运行期再编译为 Activity Contract。
-
-命名关系必须保持单向：Slice `id` 是业务 Activity；`screen.id` 是页面类别；`app/views.ts` 按 Activity 注册实际 UI。`catalog` 负责商品浏览，`primaryProductPrompt` 负责主商品询问；Prompt 以 Modal 覆盖 Actor Surface 中当前实际 Page，不引用固定背景 Step。支付派发和店员支付授权是 `paymentMethod` 页面内 Command，不创建流程 Intent。
-
-## 5. `components/`：共享展示能力
+## 3. 各层所有权
 
-| 位置 | 角色 |
-| --- | --- |
-| `shell/` | Header、BottomBarHost、FloatingBar、会员区、订单摘要和错误边界 |
-| `overlays/` | CartDrawer、统一 `HDLKioskModal`、主动结束订单确认 |
-| `common/` | SkuOptionsSelection 适配、BlockingNotice 等跨 Slice 控件 |
+### `kernel/`：通用基础包
 
-业务私有 Screen/Dialog 和 ViewModel 留在对应 Slice。公共类型统一位于根 `types.ts`，跨 Slice 的金额、购物车和错误映射等纯方法位于根 `utils.ts`。`BlockingNotice` 是所有缺失 View、reset 失败和阻断状态共用的 fail-closed 表面。
+| 位置           | 职责                                                                            |
+| -------------- | ------------------------------------------------------------------------------- |
+| `application/` | `defineSlice`、`defineApplication`、Trigger 路由、Admission 和 Session Registry |
+| `workflow/`    | Compiler、Actor、Transition 原语                                                |
+| `operations/`  | 排队、冲突域、timeout 和 epoch 原语                                             |
 
-## 6. `runtime/`：会话与 React 生命周期
+`kernel/application` 是可提取的通用 API，不是 HDLKiosk 业务 App。
 
-| 文件 | 角色 |
-| --- | --- |
-| `createWorkflowSession.ts` | 读取内置 Definition，直接编译、校验并创建 Actor/Coordinator |
-| `HDLKioskWorkflowView.tsx` | 活跃会话的 React 组合层；连接 Shell、Renderer 和 Controllers |
-| `domainTransitionRunner.ts` | 将 Actor 的 exit effect 交给 Operation Coordinator |
-| `workflowContext.ts` | 只归并经过 Activity Intent 成功提交的流程上下文 |
-| `workflowLifecycle.ts` | Actor blocked/finished 的 Host 遥测与生命周期钩子 |
-| `useHostSnapshot.ts` | 订阅 Host Projection |
-| `useWorkflowSnapshot.ts` | 订阅 Actor Snapshot |
+### `app/`：HDLKiosk 业务 Application
 
-### Controllers
+| 位置            | 职责                                                   |
+| --------------- | ------------------------------------------------------ |
+| `manifest.ts`   | 产出 `hdlKioskApplication` Definition                  |
+| `contracts/`    | Application 与 Host/Runtime 之间的稳定业务端口         |
+| `operations.ts` | Operation ID、输入输出、冲突域和重试语义；不含 Handler |
+| `workflow/`     | Quick、Barcode、Scale 拓扑与业务策略                   |
 
-| Controller | 角色 |
-| --- | --- |
-| `useHDLKioskSessionController` | 创建/销毁会话、入口互斥、session epoch，以及 `returnToEntry(reason?)` 安全清单接口 |
-| `useHDLKioskDeviceController` | 顶层注册 scanner/scale 输入，只有当前入口状态允许时才消费 |
-| `useHDLKioskCustomerController` | Shell 中途登录、身份同步与重新报价 |
-| `useHDLKioskScreenData` | 按当前 Activity 加载 Catalog 或主称重商品，离开后丢弃迟到结果 |
+Activity、Command、Intent、Surface 和 Exit Effect 协议位于平级的
+`slices/*/slice.ts`。协议与 UI 同 feature 并置，但 Application 不能导入其中的 React 文件。
 
-当前没有 Idle Controller 或 idle warning UI。Payment 成功态使用旧版 `PaymentResultToastV2` 页面展示，10 秒后通过 `returnToEntry` 自动执行验证式 `session.reset`。
+`app/` 不可导入 Host 实现、设备订阅、Runtime Handler 或 React。
 
-BigSale 专用 H5 登录实现位于 `bigSale/templates/HDLKiosk/auth/`。独立物料只暴露 Identity 认证 UI 插槽；Login2/Register2、PisellOS 模块注册和认证客户暂存均不进入 Slice 或 Kernel。
+### `runtime/`：具体依赖与无头运行时
 
-## 7. `kernel/`：可提取的通用内核
+| 位置               | 职责                                                                       |
+| ------------------ | -------------------------------------------------------------------------- |
+| `createRuntime.ts` | 将 Application Definition 和 Host 组合为可执行 Runtime                     |
+| `triggers.ts`      | 直接订阅 Scanner/Scale Port，提交 Trigger Occurrence                       |
+| `devices/`         | Scanner/Scale Ingress、去重和无 UI Scale Store                             |
+| `operations/`      | 购物车、支付、身份、履约和会话的 Host Handler                              |
+| `session/`         | Session Factory、Actor、Coordinator、Context、Projection 和 Lifecycle 组合 |
 
-| 位置 | 角色 |
-| --- | --- |
-| `application/` | `defineSlice`、`defineKioskApplication`、Slice 收集和 authoring normalization |
-| `workflow/compiler.ts` | 编译有序 Step 数组，校验 ID、Intent、可达性、modal base 和有界循环 |
-| `workflow/actor.ts` | 单会话串行状态机，拒绝迟到 Activity/Step 事件 |
-| `workflow/transition.ts` | advance/stay/blocked 等转移结果原语 |
-| `operations/coordinator.ts` | 通用排队、去重、timeout、dispose 和 epoch 协调 |
-| `operations/registry.ts` | 与业务无关的 Operation 注册表 |
-
-Kernel 只能依赖自身类型。它不包含 HDLKiosk Activity ID、支付语义、React 或 BigSale。
-
-## 8. `app/operations.ts` 与 Operation 私有实现
-
-公共消费统一写成：
+纯 JavaScript 可直接运行：
 
 ```ts
-import {
-  cartAddProductOperation,
-  checkoutOpenOperation,
-  createOperationCoordinator,
-} from '../../app/operations';
+const runtime = createHDLKioskApplicationRuntime(host, { config });
+runtime.subscribe(() => consume(runtime.getSnapshot()));
+runtime.activate();
+const quick = await runtime.start('quick');
 ```
 
-内部实现位于 `app/operations/`：
-
-- `cart.ts` / `cartConsistency.ts`：购物车写入与写后一致性；
-- `checkout.ts` / `checkoutSafety.ts` / `checkoutRequirements.ts`：prepare、支付派发和支付前事实门禁；
-- `barcode.ts`：消费标准化扫码输入；
-- `session.ts`：ensure 与验证式 reset；
-- `coordinator.ts`：把 Kernel Coordinator 绑定到 HDLKiosk Host、冲突矩阵和支付冻结；
-- `errors.ts` / `types.ts`：业务错误和 Kernel 类型绑定。
-
-履约方式由通用 `checkout.prepare` 在支付派发前写入和验证，不绑定具体 Screen 事件。
-
-## 9. `contracts/` 与 BigSale Adapter
-
-`contracts/` 是独立物料和宿主的边界：
+### `ui/` 与 `components/`：可选 React 消费层
 
-- `host.ts`：Host 总入口和 capabilities；
-- `sales.ts`：标准 ProductData、OS 加购流、购物车、客户、履约、支付和 Projection；
-- `devices.ts`：scanner/scale port；
-- `workflow*.ts`：Activity、Definition、Predicate 和 Navigation Guard 协议；
-- `operations.ts`：允许请求的 Operation ID 与输入映射；
-- `results.ts` / `errors.ts` / `telemetry.ts`：结果、错误与观测。
+| 位置                                             | 职责                                                           |
+| ------------------------------------------------ | -------------------------------------------------------------- |
+| `ui/controllers/useHDLKioskSessionController.ts` | 创建 Runtime、用 `useSyncExternalStore` 投影 snapshot          |
+| `ui/controllers/useHDLKioskActionDispatcher.ts`  | 将 UI Intent/Navigation/Command 适配到当前 Session             |
+| `ui/controllers/useHDLKioskExitController.ts`    | 处理 Exit Navigation 确认与验证式 returnToEntry                |
+| `runtime/devices/scannerSessionRouter.ts`        | 唯一持有 Scanner；统一路由 Entry、启动中和 Flow 扫码           |
+| `runtime/devices/scannerSessionPort.ts`          | 将当前 Workflow Session 的可写策略与扫码 Command 适配给 Router |
+| `ui/controllers/useHDLKioskDeviceController.ts`  | 仅投影秤连接状态，不启动 Workflow                              |
+| `ui/views.ts` / `ui/ScreenRenderer.tsx`          | Activity → View 注册和渲染                                     |
+| `ui/entry/`                                      | Workflow 外手动入口 UI                                         |
+| `slices/<name>/`                                 | 同一 feature 内的 `slice.ts` 协议与 View/Screen/Dialog         |
+| `components/`                                    | 跨 feature 的 common、shell 和 overlays                        |
 
-BigSale 兼容层位于 `components/bigSale/templates/HDLKiosk/adapter/`。它负责读取 BigSale/OS Context、调用 SalesSDK writer、注册设备插件并归一化 Host Projection；Core、Slice 和组件不能反向 import 兼容层。
+Slice 协议和 UI 分层，但保持相同 feature 名字和局部目录形状，降低定义与展示间的定位成本。
 
-## 10. `devices/`：持续监听、按状态消费
+## 4. Trigger 所有权
 
-- `scannerIngress.ts`：标准化、稳定事件 ID、TTL 去重；
-- `scaleIngress.ts`：有效重量、时效与重复读数治理；
-- `entryArbiter.ts`：Quick/Barcode/Scale 竞争时只允许一个入口获胜；
-- `scale/runtime.ts`：HDLKiosk 生命周期内共享秤快照，Entry 和 Customization 读取同一来源。
-
-监听可以常驻，消费由当前应用/Activity 状态决定。
-
-## 11. 常见修改定位
-
-| 需求 | 首要位置 | 同步检查 |
-| --- | --- | --- |
-| 调整三条流程顺序 | `app/workflow/*.ts` | Definition/Actor 测试、03 文档 |
-| 新增业务能力 | `slices/<name>/slice.ts` + `view.tsx` | `slices/index.ts`、Workflow |
-| 新增 Slice 私有写入 | `slices/<name>/operation.ts` | Slice exit effect、Host contract、测试 |
-| 新增跨 Slice 写入 | `app/operations/` + `app/operations.ts` | Manifest、OperationInputMap、Coordinator 测试 |
-| 修改 Slice 私有展示投影 | `slices/<name>/view.tsx` | 只信 Sales Projection，不本地报价 |
-| 修改跨 Slice 购物车/金额映射 | 根 `utils.ts` | 根 `types.ts`、使用这些方法的 Slice View |
-| 修改共享 BottomBar/Modal | `components/shell` 或 `components/overlays` | z-index、portal、各 Slice 局部样式 |
-| 修改扫码/称重入口 | `devices/` + Device Controller | event ID、入口互斥、session epoch |
-| 修改回首页 | Session Controller 的 `returnToEntry` | reset receipt、支付安全、epoch |
-| 修改 BigSale/OS 对接 | BigSale `adapter/` | capabilities、Projection、FakeHost |
-
-## 12. 文件头注释
+```text
+Host device event
+  → runtime/triggers.ts
+  → Kernel Runtime occurrence
+  → trigger + channel 唯一匹配 Workflow
+  → Admission / idempotency
+  → Session Factory
+  → Session Registry started event
+  → React 或纯 JS 消费者
+```
 
-业务、运行时和适配层文件应在顶部简述三件事：文件角色、运行机制、边界。纯样式、测试和简单 barrel 文件不强制。注释解释“为何存在”，不复述函数名，也不记录历史迁移过程。
+- Quick 未声明 `start`，因此默认 manual。
+- Barcode/Scale 只能由 automatic Trigger 启动，手动调用 Workflow Handle 会被拒绝。
+- 当前一个 automatic Trigger 只能绑定一个 Workflow，重复绑定 fail-closed。
+- Channel 由 Runtime Adapter 赋予，不要求物理秤事件自带 Channel。
+- 流程内扫码是 Session Command，不再进入 Workflow 启动 API。
+- 当前不实现多 Workflow 广播和嵌套调用；`parentSessionId` 只保留因果关联字段。
+
+## 5. 常见修改定位
+
+| 需求                 | 首要位置                                                   |
+| -------------------- | ---------------------------------------------------------- |
+| 调整流程顺序         | `app/workflow/*.ts`                                        |
+| 新增 Activity 协议   | `slices/<name>/slice.ts`                                   |
+| 新增 Activity UI     | `slices/<name>/` + `ui/views.ts`                           |
+| 新增 Operation 协议  | `app/operations.ts` + Slice effect/command                 |
+| 实现 Operation       | `runtime/operations/registry.ts` + 对应 Handler            |
+| 新增自动入口         | `app/manifest.ts` + Workflow start + `runtime/triggers.ts` |
+| 修改 React 消费方式  | `ui/`                                                      |
+| 修改 BigSale/OS 对接 | `components/bigSale/templates/HDLKiosk/adapter/`           |
+
+## 6. 文件头注释
+
+业务、运行时和适配层文件应说明文件角色、运行机制和边界。注释记录当前设计事实，不记录迁移历史。