@actiondock/core 2.7.0 → 2.8.0

package/dist/input/advice.js

@@ -1,4 +1,4 @@
-import { isFlatPathPropertyName, isForbiddenActionInputPropertyName, } from "./flat-predicates.js";
+import { isFlatSafePropertyName, isFlatPathPropertyName, isForbiddenActionInputPropertyName, } from "./flat-predicates.js";
 const RECOGNIZED_SCHEMA_TYPES = new Set([
     "object",
     "array",
@@ -54,6 +54,93 @@ function createMalformedAdvice(message) {
         fields: [],
     };
 }
+/**
+ * 构造无字段可用、推荐 full-json 的 ok 状态报告骨架（absent / any 语义共用单一事实源）。
+ * 字段顺序与既有契约保持一致，禁止调整键序。
+ */
+function createNonFlatOkAdvice(schemaState) {
+    return {
+        version: 1,
+        analysisMode: "declared-properties-only",
+        analysisStatus: "ok",
+        schemaState,
+        inputFeasibility: "possible-or-unknown",
+        flatAvailable: false,
+        requiredSatisfiable: null,
+        flatCandidate: false,
+        schemaRecommendedMode: "full-json",
+        fields: [],
+    };
+}
+/**
+ * 校验 schema 节点的 type 关键字结构合法性（根级与属性级重复逻辑的单一事实源）。
+ *
+ * 判定规则：
+ * - 字符串型 type 必须属于 RECOGNIZED_SCHEMA_TYPES；
+ * - 数组型 type 不得为空、元素必须是受认可字符串且不得重复；
+ * - 其余形态（数字、对象等）非法。
+ *
+ * @param type 待校验的 type 关键字值
+ * @returns 非法时返回结构化原因，合法时返回 undefined
+ */
+function validateTypeKeyword(type) {
+    if (typeof type === "string") {
+        if (!RECOGNIZED_SCHEMA_TYPES.has(type)) {
+            return { code: "UNRECOGNIZED_TYPE", value: type };
+        }
+        return undefined;
+    }
+    if (Array.isArray(type)) {
+        if (type.length === 0) {
+            return { code: "EMPTY_TYPE_ARRAY" };
+        }
+        const seen = new Set();
+        for (const t of type) {
+            if (typeof t !== "string" || !RECOGNIZED_SCHEMA_TYPES.has(t)) {
+                return { code: "UNRECOGNIZED_TYPE_IN_ARRAY", value: String(t) };
+            }
+            if (seen.has(t)) {
+                return { code: "DUPLICATE_TYPE", value: t };
+            }
+            seen.add(t);
+        }
+        return undefined;
+    }
+    return { code: "NOT_STRING_OR_ARRAY" };
+}
+/**
+ * 依 TypeKeywordIssue 构造根级 type 关键字 malformed 消息（措辞与历史实现逐字节一致）。
+ */
+function formatRootTypeKeywordMessage(issue) {
+    switch (issue.code) {
+        case "UNRECOGNIZED_TYPE":
+            return `Unrecognized type keyword: '${issue.value}'`;
+        case "UNRECOGNIZED_TYPE_IN_ARRAY":
+            return `Unrecognized type in type array: '${issue.value}'`;
+        case "EMPTY_TYPE_ARRAY":
+            return "Type array must not be empty";
+        case "DUPLICATE_TYPE":
+            return `Duplicate type in type array: '${issue.value}'`;
+        case "NOT_STRING_OR_ARRAY":
+            return "Type keyword must be a string or array of strings";
+    }
+}
+/**
+ * 依 TypeKeywordIssue 构造属性级 type 关键字 malformed 消息（措辞与历史实现逐字节一致）。
+ */
+function formatPropertyTypeKeywordMessage(issue, propKey) {
+    switch (issue.code) {
+        case "UNRECOGNIZED_TYPE":
+        case "UNRECOGNIZED_TYPE_IN_ARRAY":
+            return `Unrecognized type '${issue.value}' in property '${propKey}'`;
+        case "EMPTY_TYPE_ARRAY":
+            return `Type array in property '${propKey}' must not be empty`;
+        case "DUPLICATE_TYPE":
+            return `Duplicate type '${issue.value}' in property '${propKey}'`;
+        case "NOT_STRING_OR_ARRAY":
+            return `Type in property '${propKey}' must be string or array of strings`;
+    }
+}
 /**
  * 依据 inputSchema 构造 v1 版本的 Action 输入编码顾问报告（机器契约）。
  *
@@ -64,18 +151,7 @@ export function buildCliInputAdviceV1(schema) {
     // 1. Schema Sanity 阶段（Section 44）
     // 1.1 根形状检查（Section 44.1）
     if (schema === undefined) {
-        return {
-            version: 1,
-            analysisMode: "declared-properties-only",
-            analysisStatus: "ok",
-            schemaState: "absent",
-            inputFeasibility: "possible-or-unknown",
-            flatAvailable: false,
-            requiredSatisfiable: null,
-            flatCandidate: false,
-            schemaRecommendedMode: "full-json",
-            fields: [],
-        };
+        return createNonFlatOkAdvice("absent");
     }
     if (typeof schema === "boolean") {
         if (schema === false) {
@@ -93,18 +169,7 @@ export function buildCliInputAdviceV1(schema) {
                 fields: [],
             };
         }
-        return {
-            version: 1,
-            analysisMode: "declared-properties-only",
-            analysisStatus: "ok",
-            schemaState: "any",
-            inputFeasibility: "possible-or-unknown",
-            flatAvailable: false,
-            requiredSatisfiable: null,
-            flatCandidate: false,
-            schemaRecommendedMode: "full-json",
-            fields: [],
-        };
+        return createNonFlatOkAdvice("any");
     }
     if (!isPlainObject(schema)) {
         return {
@@ -124,30 +189,11 @@ export function buildCliInputAdviceV1(schema) {
     }
     const s = schema;
     // 1.2 关键字形状检查（Section 44.2）
-    // 检查 type
+    // 检查 type（结构校验单一事实源，根级消息模板独立持有）
     if (s.type !== undefined) {
-        if (typeof s.type === "string") {
-            if (!RECOGNIZED_SCHEMA_TYPES.has(s.type)) {
-                return createMalformedAdvice(`Unrecognized type keyword: '${s.type}'`);
-            }
-        }
-        else if (Array.isArray(s.type)) {
-            if (s.type.length === 0) {
-                return createMalformedAdvice("Type array must not be empty");
-            }
-            const seen = new Set();
-            for (const t of s.type) {
-                if (typeof t !== "string" || !RECOGNIZED_SCHEMA_TYPES.has(t)) {
-                    return createMalformedAdvice(`Unrecognized type in type array: '${String(t)}'`);
-                }
-                if (seen.has(t)) {
-                    return createMalformedAdvice(`Duplicate type in type array: '${t}'`);
-                }
-                seen.add(t);
-            }
-        }
-        else {
-            return createMalformedAdvice("Type keyword must be a string or array of strings");
+        const issue = validateTypeKeyword(s.type);
+        if (issue) {
+            return createMalformedAdvice(formatRootTypeKeywordMessage(issue));
         }
     }
     // 检查 properties
@@ -161,28 +207,9 @@ export function buildCliInputAdviceV1(schema) {
             }
             if (isPlainObject(propVal)) {
                 if (propVal.type !== undefined) {
-                    if (typeof propVal.type === "string") {
-                        if (!RECOGNIZED_SCHEMA_TYPES.has(propVal.type)) {
-                            return createMalformedAdvice(`Unrecognized type '${propVal.type}' in property '${propKey}'`);
-                        }
-                    }
-                    else if (Array.isArray(propVal.type)) {
-                        if (propVal.type.length === 0) {
-                            return createMalformedAdvice(`Type array in property '${propKey}' must not be empty`);
-                        }
-                        const seen = new Set();
-                        for (const t of propVal.type) {
-                            if (typeof t !== "string" || !RECOGNIZED_SCHEMA_TYPES.has(t)) {
-                                return createMalformedAdvice(`Unrecognized type '${String(t)}' in property '${propKey}'`);
-                            }
-                            if (seen.has(t)) {
-                                return createMalformedAdvice(`Duplicate type '${t}' in property '${propKey}'`);
-                            }
-                            seen.add(t);
-                        }
-                    }
-                    else {
-                        return createMalformedAdvice(`Type in property '${propKey}' must be string or array of strings`);
+                    const issue = validateTypeKeyword(propVal.type);
+                    if (issue) {
+                        return createMalformedAdvice(formatPropertyTypeKeywordMessage(issue, propKey));
                     }
                 }
                 if (propVal.enum !== undefined) {
@@ -280,18 +307,7 @@ export function buildCliInputAdviceV1(schema) {
     }
     // 2. 语义分类阶段（Section 45）
     if (Object.keys(s).length === 0) {
-        return {
-            version: 1,
-            analysisMode: "declared-properties-only",
-            analysisStatus: "ok",
-            schemaState: "any",
-            inputFeasibility: "possible-or-unknown",
-            flatAvailable: false,
-            requiredSatisfiable: null,
-            flatCandidate: false,
-            schemaRecommendedMode: "full-json",
-            fields: [],
-        };
+        return createNonFlatOkAdvice("any");
     }
     const hasComplexKeyword = isTupleItems ||
         COMPLEX_KEYWORDS.some((kw) => s[kw] !== undefined);
@@ -413,83 +429,37 @@ export function buildCliInputAdviceV1(schema) {
         // enum/const 绝不改变 operator 选择，仅显式单一 schema.type 决定 operator。
         // 无显式 type 时不推断类型，推荐 full-json，flatSafe: false。
         if (typeof propType === "string") {
-            if (propType === "string") {
-                fields.push({
-                    path: key,
-                    inputAllowed: true,
-                    flatSafe: true,
-                    required: isReq,
-                    type: "string",
-                    operator: "=",
-                    encoding: "string",
-                    assignmentTemplate: `${key}=TEXT`,
-                    ...(desc ? { description: desc } : {}),
-                });
-            }
-            else if (propType === "number" || propType === "integer") {
-                fields.push({
-                    path: key,
-                    inputAllowed: true,
-                    flatSafe: true,
-                    required: isReq,
-                    type: propType,
-                    operator: ":=",
-                    encoding: "json-number",
-                    assignmentTemplate: `${key}:=NUMBER`,
-                    ...(desc ? { description: desc } : {}),
-                });
-            }
-            else if (propType === "boolean") {
-                fields.push({
-                    path: key,
-                    inputAllowed: true,
-                    flatSafe: true,
-                    required: isReq,
-                    type: "boolean",
-                    operator: ":=",
-                    encoding: "json-boolean",
-                    assignmentTemplate: `${key}:=BOOLEAN`,
-                    ...(desc ? { description: desc } : {}),
-                });
-            }
-            else if (propType === "null") {
-                fields.push({
-                    path: key,
-                    inputAllowed: true,
-                    flatSafe: true,
-                    required: isReq,
-                    type: "null",
-                    operator: ":=",
-                    encoding: "json-null",
-                    assignmentTemplate: `${key}:=null`,
-                    ...(desc ? { description: desc } : {}),
-                });
-            }
-            else if (propType === "array") {
-                fields.push({
-                    path: key,
-                    inputAllowed: true,
-                    flatSafe: true,
-                    required: isReq,
-                    type: "array",
-                    operator: ":=",
+            // Flat-safe 显式单一类型的编码参数表（string/number/integer/boolean/null/array/object）。
+            // 各分支仅在 type、encoding、assignmentTemplate 与 hint 上差异，结构完全一致。
+            const flatSafeTypeTable = {
+                string: { encoding: "string", assignmentTemplate: `${key}=TEXT` },
+                number: { encoding: "json-number", assignmentTemplate: `${key}:=NUMBER` },
+                integer: { encoding: "json-number", assignmentTemplate: `${key}:=NUMBER` },
+                boolean: { encoding: "json-boolean", assignmentTemplate: `${key}:=BOOLEAN` },
+                null: { encoding: "json-null", assignmentTemplate: `${key}:=null` },
+                array: {
                     encoding: "json-array",
                     assignmentTemplate: `${key}:=JSON`,
                     hint: "建议使用 --input-file 或标准输入传递数组结构",
-                    ...(desc ? { description: desc } : {}),
-                });
-            }
-            else if (propType === "object") {
+                },
+                object: {
+                    encoding: "json-object",
+                    assignmentTemplate: `${key}:=JSON`,
+                    hint: "大型结构建议使用 --input-file",
+                },
+            };
+            const flatSafeEntry = flatSafeTypeTable[propType];
+            if (flatSafeEntry) {
                 fields.push({
                     path: key,
                     inputAllowed: true,
                     flatSafe: true,
                     required: isReq,
-                    type: "object",
-                    operator: ":=",
-                    encoding: "json-object",
-                    assignmentTemplate: `${key}:=JSON`,
-                    hint: "大型结构建议使用 --input-file",
+                    type: propType,
+                    operator: propType === "string" ? "=" : ":=",
+                    encoding: flatSafeEntry.encoding,
+                    assignmentTemplate: flatSafeEntry.assignmentTemplate,
+                    ...(flatSafeEntry.hint ? { hint: flatSafeEntry.hint } : {}),
                     ...(desc ? { description: desc } : {}),
                 });
             }
@@ -599,13 +569,31 @@ export function buildCliInputAdviceV1(schema) {
         fields,
     };
 }
-export const FLAT_SAFE_KEY_REGEX = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+/**
+ * 扁平编码通用指引文案。
+ * 属性名安全判定统一引用 flat-predicates 的单一事实源（含禁止属性排除），
+ * 禁止在本文件另建独立正则分叉。
+ */
 export const FLAT_ENCODING_GUIDELINES = [
     "字符串: path=TEXT",
     "JSON 标量与结构: path:=JSON (例如 count:=1, enabled:=true)",
     "数组元素: path.INDEX=... (例如 items.0=first)",
     "提示: 复杂嵌套或大段文本建议使用 --input 或 --input-file",
 ];
+/**
+ * 构造无扁平能力、无字段明细的空结果建议报告（各降级早退分支共用单一事实源）。
+ * 键序与既有契约保持一致，禁止调整。
+ */
+function createEmptyFlatAdvice(notes) {
+    return {
+        flatSupported: false,
+        hasFlatFields: false,
+        fields: [],
+        requiredTemplates: [],
+        optionalTemplates: [],
+        notes,
+    };
+}
 /**
  * 依据 inputSchema 构造统一的 Action 输入编码建议。
  *
@@ -615,62 +603,27 @@ export const FLAT_ENCODING_GUIDELINES = [
 export function buildActionInputAdvice(schema) {
     if (typeof schema === "boolean") {
         if (schema === false) {
-            return {
-                flatSupported: false,
-                hasFlatFields: false,
-                fields: [],
-                requiredTemplates: [],
-                optionalTemplates: [],
-                notes: ["布尔模式 false：拒绝所有输入，任何调用参数均判定为非法"],
-            };
+            return createEmptyFlatAdvice(["布尔模式 false：拒绝所有输入，任何调用参数均判定为非法"]);
         }
-        return {
-            flatSupported: false,
-            hasFlatFields: false,
-            fields: [],
-            requiredTemplates: [],
-            optionalTemplates: [],
-            notes: [
-                "布尔模式 true：接受任意合法 JSON 输入；调用时无需指定必填参数，非对象根输入请使用 --input-file 或 --input",
-            ],
-        };
+        return createEmptyFlatAdvice([
+            "布尔模式 true：接受任意合法 JSON 输入；调用时无需指定必填参数，非对象根输入请使用 --input-file 或 --input",
+        ]);
     }
     if (!schema || typeof schema !== "object") {
-        return {
-            flatSupported: false,
-            hasFlatFields: false,
-            fields: [],
-            requiredTemplates: [],
-            optionalTemplates: [],
-            notes: ["根模式未声明输入字段，直接调用或使用 --input-file / --input '{}'"],
-        };
+        return createEmptyFlatAdvice(["根模式未声明输入字段，直接调用或使用 --input-file / --input '{}'"]);
     }
     const s = schema;
     // 校验根模式是否为 object 类型
     if (s.type !== undefined && s.type !== "object") {
-        return {
-            flatSupported: false,
-            hasFlatFields: false,
-            fields: [],
-            requiredTemplates: [],
-            optionalTemplates: [],
-            notes: [
-                `根模式类型为 '${s.type}'，不支持扁平赋值，建议使用 --input-file 或 --input`,
-            ],
-        };
+        return createEmptyFlatAdvice([
+            `根模式类型为 '${s.type}'，不支持扁平赋值，建议使用 --input-file 或 --input`,
+        ]);
     }
     const properties = (s.properties || {});
     const required = Array.isArray(s.required) ? s.required : [];
     const propKeys = Object.keys(properties);
     if (propKeys.length === 0) {
-        return {
-            flatSupported: false,
-            hasFlatFields: false,
-            fields: [],
-            requiredTemplates: [],
-            optionalTemplates: [],
-            notes: ["根模式无声明属性，不支持扁平赋值，建议使用 --input-file 或 --input '{}'"],
-        };
+        return createEmptyFlatAdvice(["根模式无声明属性，不支持扁平赋值，建议使用 --input-file 或 --input '{}'"]);
     }
     const fields = [];
     const requiredTemplates = [];
@@ -680,10 +633,21 @@ export function buildActionInputAdvice(schema) {
         const prop = properties[key] || {};
         const typeStr = prop.type ? String(prop.type) : "any";
         const isReq = required.includes(key);
-        const isFlatSafe = FLAT_SAFE_KEY_REGEX.test(key);
+        const isFlatSafe = isFlatSafePropertyName(key);
         let assignmentTemplate;
         let hint;
         if (isFlatSafe) {
+            // 数组元素标量类型到扁平元素赋值模板的参数表（共用同一守卫与拼接规则）。
+            // 命中时模板形态为 `${key}.0<operator><占位符>`，未命中回退数组整体 JSON 模板。
+            const itemsTypeTemplates = {
+                string: `${key}.0=TEXT`,
+                number: `${key}.0:=NUMBER`,
+                integer: `${key}.0:=NUMBER`,
+                boolean: `${key}.0:=BOOLEAN`,
+            };
+            const itemsTemplate = prop.type === "array" && prop.items && typeof prop.items === "object"
+                ? itemsTypeTemplates[prop.items.type]
+                : undefined;
             if (prop.type === "string") {
                 assignmentTemplate = `${key}=TEXT`;
             }
@@ -693,23 +657,8 @@ export function buildActionInputAdvice(schema) {
             else if (prop.type === "boolean") {
                 assignmentTemplate = `${key}:=BOOLEAN`;
             }
-            else if (prop.type === "array" &&
-                prop.items &&
-                typeof prop.items === "object" &&
-                prop.items.type === "string") {
-                assignmentTemplate = `${key}.0=TEXT`;
-            }
-            else if (prop.type === "array" &&
-                prop.items &&
-                typeof prop.items === "object" &&
-                (prop.items.type === "number" || prop.items.type === "integer")) {
-                assignmentTemplate = `${key}.0:=NUMBER`;
-            }
-            else if (prop.type === "array" &&
-                prop.items &&
-                typeof prop.items === "object" &&
-                prop.items.type === "boolean") {
-                assignmentTemplate = `${key}.0:=BOOLEAN`;
+            else if (itemsTemplate) {
+                assignmentTemplate = itemsTemplate;
             }
             else if (prop.type === "array") {
                 assignmentTemplate = `${key}:=JSON`;

package/dist/input/describe.d.ts

@@ -1,4 +1,4 @@
-import type { ActionSpec } from "../app/types.js";
+import type { ActionSpec } from "../package/types.js";
 /**
  * 字段级异常明细。
  */

package/dist/input/flat-errors.d.ts

@@ -1,5 +1,5 @@
-import { INVALID_JSON, INVALID_JSON_LITERAL, INVALID_FLAT_ARGUMENT, INPUT_PATH_CONFLICT, FLAT_INPUT_LIMIT_EXCEEDED, INPUT_LIMIT_EXCEEDED, INPUT_POLICY_VIOLATION, INPUT_CONFLICT, INPUT_FILE_NOT_FOUND, INPUT_FILE_READ_FAILED, INPUT_NOT_JSON, INPUT_VALIDATION_FAILED } from "../errors.js";
-export { INVALID_JSON, INVALID_JSON_LITERAL, INVALID_FLAT_ARGUMENT, INPUT_PATH_CONFLICT, FLAT_INPUT_LIMIT_EXCEEDED, INPUT_LIMIT_EXCEEDED, INPUT_POLICY_VIOLATION, INPUT_CONFLICT, INPUT_FILE_NOT_FOUND, INPUT_FILE_READ_FAILED, INPUT_NOT_JSON, INPUT_VALIDATION_FAILED, };
+import { ActionDockError, type ErrorCode } from "../errors.js";
+export { INVALID_JSON, INVALID_JSON_LITERAL, INVALID_FLAT_ARGUMENT, INPUT_PATH_CONFLICT, FLAT_INPUT_LIMIT_EXCEEDED, INPUT_LIMIT_EXCEEDED, INPUT_POLICY_VIOLATION, INPUT_CONFLICT, INPUT_FILE_NOT_FOUND, INPUT_FILE_READ_FAILED, INPUT_NOT_JSON, INPUT_VALIDATION_FAILED, } from "../errors.js";
 /** 输入大小或深度超出限制的根因类型 */
 export type InputLimitExceededReason = "MAX_INPUT_BYTES" | "MAX_JSON_DEPTH" | string;
 /** 扁平入参安全阈值超限的根因类型 */
@@ -19,16 +19,15 @@ export type InputValidationSource = "flat-json-literal" | "flat-materialized" |
 /**
  * 输入领域通用结构化异常类。
  */
-export declare class InputError extends Error {
-    readonly code: string;
+export declare class InputError extends ActionDockError {
     readonly details?: Record<string, unknown> | string[];
-    constructor(code: string, message: string, details?: Record<string, unknown> | string[]);
+    constructor(code: ErrorCode, message: string, details?: Record<string, unknown> | string[]);
 }
 /**
  * 扁平输入结构化异常类（继承 InputError 保持既有捕获兼容）。
  */
 export declare class FlatInputError extends InputError {
-    constructor(code: string, message: string, details?: Record<string, unknown>);
+    constructor(code: ErrorCode, message: string, details?: Record<string, unknown>);
 }
 /**
  * 构造 INVALID_JSON 异常（用于完整 JSON 文档解析失败）。

package/dist/input/flat-errors.js

@@ -1,15 +1,15 @@
-import { INVALID_JSON, INVALID_JSON_LITERAL, INVALID_FLAT_ARGUMENT, INPUT_PATH_CONFLICT, FLAT_INPUT_LIMIT_EXCEEDED, INPUT_LIMIT_EXCEEDED, INPUT_POLICY_VIOLATION, INPUT_CONFLICT, INPUT_FILE_NOT_FOUND, INPUT_FILE_READ_FAILED, INPUT_NOT_JSON, INPUT_VALIDATION_FAILED, } from "../errors.js";
-export { INVALID_JSON, INVALID_JSON_LITERAL, INVALID_FLAT_ARGUMENT, INPUT_PATH_CONFLICT, FLAT_INPUT_LIMIT_EXCEEDED, INPUT_LIMIT_EXCEEDED, INPUT_POLICY_VIOLATION, INPUT_CONFLICT, INPUT_FILE_NOT_FOUND, INPUT_FILE_READ_FAILED, INPUT_NOT_JSON, INPUT_VALIDATION_FAILED, };
+import { ActionDockError, INVALID_JSON, INVALID_JSON_LITERAL, INVALID_FLAT_ARGUMENT, INPUT_PATH_CONFLICT, FLAT_INPUT_LIMIT_EXCEEDED, INPUT_LIMIT_EXCEEDED, INPUT_POLICY_VIOLATION, INPUT_CONFLICT, INPUT_FILE_NOT_FOUND, INPUT_FILE_READ_FAILED, } from "../errors.js";
+// 错误码常量对外转引单一事实源：仅保留工厂函数实际引用的导入绑定，
+// 对外输出统一经由本条 export-from 语句完成，不再另列本地重导出清单。
+export { INVALID_JSON, INVALID_JSON_LITERAL, INVALID_FLAT_ARGUMENT, INPUT_PATH_CONFLICT, FLAT_INPUT_LIMIT_EXCEEDED, INPUT_LIMIT_EXCEEDED, INPUT_POLICY_VIOLATION, INPUT_CONFLICT, INPUT_FILE_NOT_FOUND, INPUT_FILE_READ_FAILED, INPUT_NOT_JSON, INPUT_VALIDATION_FAILED, } from "../errors.js";
 /**
  * 输入领域通用结构化异常类。
  */
-export class InputError extends Error {
-    code;
+export class InputError extends ActionDockError {
     details;
     constructor(code, message, details) {
-        super(message);
+        super(code, message, details);
         this.name = "InputError";
-        this.code = code;
         this.details = details;
         Object.setPrototypeOf(this, InputError.prototype);
     }

package/dist/input/flat-materializer.js

@@ -64,6 +64,44 @@ function materializeNode(node) {
  */
 export function materializeFlatInput(assignments, options) {
     const root = createNode("", NodeState.OBJECT);
+    /**
+     * 叶子赋值四态推进（字符串段与数字段共用单一事实源）。
+     * - UNSET：置为 VALUE 并写入值；
+     * - VALUE：重复赋值，抛 DUPLICATE_ASSIGNMENT；
+     * - OBJECT/ARRAY：值写入既有容器，抛 LEAF_CONTAINER_CONFLICT。
+     */
+    const assignLeaf = (child, currentPathStr, operator, value, valueLength) => {
+        if (child.state === NodeState.UNSET) {
+            child.state = NodeState.VALUE;
+            child.value = value;
+        }
+        else if (child.state === NodeState.VALUE) {
+            throw inputPathConflict(`Duplicate assignment to leaf path "${currentPathStr}"`, { path: currentPathStr, operator, valueLength, reason: "DUPLICATE_ASSIGNMENT" });
+        }
+        else {
+            throw inputPathConflict(`Path conflict at "${currentPathStr}": cannot assign value to existing container (${child.state.toLowerCase()})`, { path: currentPathStr, operator, valueLength, reason: "LEAF_CONTAINER_CONFLICT" });
+        }
+    };
+    /**
+     * 容器下钻三态推进（字符串段与数字段共用单一事实源）。
+     * - UNSET：按下一路径段形态初始化为 OBJECT 或 ARRAY；
+     * - VALUE：穿透既有值节点，抛 LEAF_CONTAINER_CONFLICT；
+     * - 容器形态与期望不符：抛 OBJECT_ARRAY_CONFLICT。
+     * 错误消息中下一访问段的措辞由 accessNoun 提供（字符串段为 property，数字段为 index/property）。
+     */
+    const descend = (child, currentPathStr, nextSeg, operator, valueLength, accessNoun) => {
+        const nextExpectedState = typeof nextSeg === "number" ? NodeState.ARRAY : NodeState.OBJECT;
+        if (child.state === NodeState.UNSET) {
+            child.state = nextExpectedState;
+        }
+        else if (child.state === NodeState.VALUE) {
+            throw inputPathConflict(`Path conflict at "${currentPathStr}": cannot access ${accessNoun} "${nextSeg}" on existing value`, { path: currentPathStr, operator, valueLength, reason: "LEAF_CONTAINER_CONFLICT" });
+        }
+        else if (child.state !== nextExpectedState) {
+            throw inputPathConflict(`Path conflict at "${currentPathStr}": expected ${nextExpectedState.toLowerCase()} but found ${child.state.toLowerCase()}`, { path: currentPathStr, operator, valueLength, reason: "OBJECT_ARRAY_CONFLICT" });
+        }
+        return child;
+    };
     for (const assignment of assignments) {
         const { path, value, operator, rawValue } = assignment;
         const valueLength = Buffer.byteLength(rawValue, "utf8");
@@ -90,30 +128,10 @@ export function materializeFlatInput(assignments, options) {
                     current.objectChildren[seg] = child;
                 }
                 if (isLast) {
-                    if (child.state === NodeState.UNSET) {
-                        child.state = NodeState.VALUE;
-                        child.value = value;
-                    }
-                    else if (child.state === NodeState.VALUE) {
-                        throw inputPathConflict(`Duplicate assignment to leaf path "${currentPathStr}"`, { path: currentPathStr, operator, valueLength, reason: "DUPLICATE_ASSIGNMENT" });
-                    }
-                    else {
-                        throw inputPathConflict(`Path conflict at "${currentPathStr}": cannot assign value to existing container (${child.state.toLowerCase()})`, { path: currentPathStr, operator, valueLength, reason: "LEAF_CONTAINER_CONFLICT" });
-                    }
+                    assignLeaf(child, currentPathStr, operator, value, valueLength);
                 }
                 else {
-                    const nextSeg = path[i + 1];
-                    const nextExpectedState = typeof nextSeg === "number" ? NodeState.ARRAY : NodeState.OBJECT;
-                    if (child.state === NodeState.UNSET) {
-                        child.state = nextExpectedState;
-                    }
-                    else if (child.state === NodeState.VALUE) {
-                        throw inputPathConflict(`Path conflict at "${currentPathStr}": cannot access property "${nextSeg}" on existing value`, { path: currentPathStr, operator, valueLength, reason: "LEAF_CONTAINER_CONFLICT" });
-                    }
-                    else if (child.state !== nextExpectedState) {
-                        throw inputPathConflict(`Path conflict at "${currentPathStr}": expected ${nextExpectedState.toLowerCase()} but found ${child.state.toLowerCase()}`, { path: currentPathStr, operator, valueLength, reason: "OBJECT_ARRAY_CONFLICT" });
-                    }
-                    current = child;
+                    current = descend(child, currentPathStr, path[i + 1], operator, valueLength, "property");
                 }
             }
             else {
@@ -132,30 +150,10 @@ export function materializeFlatInput(assignments, options) {
                     current.arrayChildren.set(seg, child);
                 }
                 if (isLast) {
-                    if (child.state === NodeState.UNSET) {
-                        child.state = NodeState.VALUE;
-                        child.value = value;
-                    }
-                    else if (child.state === NodeState.VALUE) {
-                        throw inputPathConflict(`Duplicate assignment to leaf path "${currentPathStr}"`, { path: currentPathStr, operator, valueLength, reason: "DUPLICATE_ASSIGNMENT" });
-                    }
-                    else {
-                        throw inputPathConflict(`Path conflict at "${currentPathStr}": cannot assign value to existing container (${child.state.toLowerCase()})`, { path: currentPathStr, operator, valueLength, reason: "LEAF_CONTAINER_CONFLICT" });
-                    }
+                    assignLeaf(child, currentPathStr, operator, value, valueLength);
                 }
                 else {
-                    const nextSeg = path[i + 1];
-                    const nextExpectedState = typeof nextSeg === "number" ? NodeState.ARRAY : NodeState.OBJECT;
-                    if (child.state === NodeState.UNSET) {
-                        child.state = nextExpectedState;
-                    }
-                    else if (child.state === NodeState.VALUE) {
-                        throw inputPathConflict(`Path conflict at "${currentPathStr}": cannot access index/property "${nextSeg}" on existing value`, { path: currentPathStr, operator, valueLength, reason: "LEAF_CONTAINER_CONFLICT" });
-                    }
-                    else if (child.state !== nextExpectedState) {
-                        throw inputPathConflict(`Path conflict at "${currentPathStr}": expected ${nextExpectedState.toLowerCase()} but found ${child.state.toLowerCase()}`, { path: currentPathStr, operator, valueLength, reason: "OBJECT_ARRAY_CONFLICT" });
-                    }
-                    current = child;
+                    current = descend(child, currentPathStr, path[i + 1], operator, valueLength, "index/property");
                 }
             }
         }

package/dist/invocation/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./types.js";
+export * from "./policy.js";

package/dist/invocation/index.js

@@ -0,0 +1,2 @@
+export * from "./types.js";
+export * from "./policy.js";