omc-core 0.0.0-stage → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oh-My-CpAgent contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,13 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# omc-core
+
+OMC（Oh-My-CpAgent）配置能力族的共享内核：能力契约、治理原语（审批协议、受控执行器、
+写租约）、CloudPivot wire 解码器，以及字段/模型/表单的契约阶梯。
+
+硬性保证：
+
+- **零 DSH 依赖。** `omc-core` 从不 import `@deepseek-ai/dsh-*`。由
+  `scripts/check-zero-dsh.mjs` 强制（已接入 CI；违反即为红色）。
+- **宿主无关**：没有宿主插件、没有 profile shell、没有安装 shell——那些属于宿主包
+  （`oh-my-cpagents` 根包、DSH 层）。
+
+本包是 `omc-cli` 的共享运行时依赖，也会与 `omc-cli` 使用相同版本发布到 GitLab npm Package Registry。使用方通常直接安装 `omc-cli`，npm 会自动解析 `omc-core`。

package/dist/application-discovery.js

@@ -0,0 +1,107 @@
+import { createHash } from "node:crypto";
+import { DatabaseSync } from "node:sqlite";
+import { mkdirSync } from "node:fs";
+import { dirname as pathDirname } from "node:path";
+export async function discoverApplicationModelFieldForms(catalog, adapter, credentials) {
+    const capabilityId = "capabilityId" in adapter ? adapter.capabilityId : undefined;
+    if (!capabilityId)
+        throw new Error("Discovery adapter must identify its catalog capability.");
+    const capability = catalog.get(capabilityId);
+    assertExecutableDiscoveryCapability(capability);
+    const discovery = await adapter.discover(credentials);
+    const bindings = discovery.models.map((model) => toBinding(discovery, model));
+    return { discovery, bindings, baselineFingerprint: fingerprint({ discovery, bindings }) };
+}
+export class ResourceCodeReservations {
+    db;
+    constructor(databasePath) {
+        mkdirSync(pathDirname(databasePath), { recursive: true });
+        this.db = new DatabaseSync(databasePath);
+        this.db.exec("CREATE TABLE IF NOT EXISTS resource_code_reservation (resource_type TEXT NOT NULL, code TEXT NOT NULL, owner TEXT NOT NULL, PRIMARY KEY (resource_type, code))");
+    }
+    reserve(discovery, plans, owner) {
+        if (!plans.length)
+            throw new Error("At least one resource code must be planned.");
+        if (!owner.trim())
+            throw new Error("Reservation owner is required.");
+        const discovered = discoveredCodes(discovery);
+        const requested = flattenPlans(plans);
+        const duplicate = requested.find((resource) => discovered.has(key(resource.type, resource.code)));
+        if (duplicate)
+            throw new Error(`Planned ${duplicate.type} code collides with discovered resource: ${duplicate.code}.`);
+        const seen = new Set();
+        for (const resource of requested) {
+            const identity = key(resource.type, resource.code);
+            if (seen.has(identity))
+                throw new Error(`Duplicate planned ${resource.type} code: ${resource.code}.`);
+            seen.add(identity);
+        }
+        this.db.exec("BEGIN IMMEDIATE");
+        try {
+            for (const resource of requested) {
+                try {
+                    this.db.prepare("INSERT INTO resource_code_reservation (resource_type, code, owner) VALUES (?, ?, ?)").run(resource.type, resource.code, owner.trim());
+                }
+                catch {
+                    throw new Error(`Planned ${resource.type} code is already reserved: ${resource.code}.`);
+                }
+            }
+            this.db.exec("COMMIT");
+        }
+        catch (error) {
+            this.db.exec("ROLLBACK");
+            throw error;
+        }
+    }
+    reservations() {
+        return this.db.prepare("SELECT resource_type, code, owner FROM resource_code_reservation ORDER BY resource_type, code").all()
+            .map((row) => ({ type: String(row.resource_type), code: String(row.code), owner: String(row.owner) }));
+    }
+}
+function assertExecutableDiscoveryCapability(capability) {
+    if (capability.status !== "executable" || capability.promotionStatus !== "promoted" || capability.freeze.blocked) {
+        throw new Error(`Capability is not an executable discovery adapter: ${capability.id}.`);
+    }
+}
+function toBinding(discovery, model) {
+    const application = discovery.applications.find((candidate) => candidate.code === model.applicationCode);
+    if (!application)
+        throw new Error(`Read-back model references an undiscovered application: ${model.applicationCode}.`);
+    const fields = [...model.fields.draft, ...model.fields.published];
+    const fieldCodes = {};
+    for (const field of fields) {
+        if (fieldCodes[field.code] && fieldCodes[field.code].type !== field.type)
+            throw new Error(`Read-back field has conflicting types: ${field.code}.`);
+        fieldCodes[field.code] = { id: field.id, type: field.type, published: field.published || fieldCodes[field.code]?.published === true };
+    }
+    if (model.defaultForm.binding.modelCode !== model.schemaCode)
+        throw new Error(`Read-back form is not bound to model: ${model.schemaCode}.`);
+    return { applicationCode: application.code, modelCode: model.schemaCode, modelId: model.id, formCode: model.defaultForm.sheetCode, formId: model.defaultForm.id, fieldCodes, formBinding: model.defaultForm.binding };
+}
+function discoveredCodes(discovery) {
+    const codes = new Set();
+    for (const application of discovery.applications)
+        codes.add(key("application", application.code));
+    for (const model of discovery.models) {
+        codes.add(key("model", model.schemaCode));
+        codes.add(key("form", model.defaultForm.sheetCode));
+        for (const field of [...model.fields.draft, ...model.fields.published])
+            codes.add(key("field", field.code));
+    }
+    return codes;
+}
+function flattenPlans(plans) {
+    return plans.flatMap((plan) => [
+        ...(plan.applicationCode ? [{ type: "application", code: plan.applicationCode }] : []),
+        ...(plan.modelCode ? [{ type: "model", code: plan.modelCode }] : []),
+        ...(plan.formCode ? [{ type: "form", code: plan.formCode }] : []),
+        ...(plan.fieldCodes ?? []).map((code) => ({ type: "field", code })),
+    ]).map((resource) => {
+        if (!resource.code.trim())
+            throw new Error(`Planned ${resource.type} code is required.`);
+        return { ...resource, code: resource.code.trim() };
+    });
+}
+function key(type, code) { return `${type}:${code}`; }
+function fingerprint(value) { return createHash("sha256").update(JSON.stringify(value)).digest("hex"); }
+//# sourceMappingURL=application-discovery.js.map

package/dist/approval-frame-readability.js

@@ -0,0 +1,317 @@
+// Host-owned human-readable approval summary blocks (Ticket 15).
+//
+// Iron rules (series spec, .scratch/omc-approval-readability/spec.md):
+// 1. The summary block is DERIVED from the immutable plan/package by the
+//    Host. Every line is composed from a fixed per-capability registry plus
+//    grammar-validated resource identities taken from the validated approval
+//    or package — there is no free-text parameter, so model-authored phrasing
+//    can never enter an approval frame.
+// 2. The block is APPENDED after the byte-identical machine prefix; every
+//    established runner keeps matching `reason.startsWith(reasonPrefix)`.
+// 3. A rendered block that diverges from the immutable identities/scope is
+//    rejected: `verifyApprovalFrameHumanBlock` re-derives the block and
+//    fails any frame that does not end with exactly that block, and
+//    `assertApprovalFrameHumanBlock` gates the DSH approval request itself.
+import { activeFieldFamily, fieldFamilyMembers } from "./families/registry.js";
+/** Resource identity grammar: code-like segments only — never prose. */
+const IDENTITY_PATTERN = /^[A-Za-z0-9_][A-Za-z0-9_:/-]{0,191}$/;
+const SCOPE_PATTERN = /^[A-Za-z0-9_][A-Za-z0-9_:/+-]{0,191}$/;
+const TEST_FIXTURE_RUN = "测试夹具运行,资源将按已批准契约分级清理";
+const TEST_FIXTURE_CLEANUP_RUN = "测试夹具运行,清理以权威精确缺失回读收尾";
+// Ticket 25: the ladder's family rungs derive their Chinese prose and the
+// family-field identity labels from the ACTIVE registry family (src/families
+// /<family>.ts) — never a per-rung literal — and the field stages are
+// VARIADIC in the family-field identity slots (one schema + one code per
+// registered member), so the identity-count gate and label rendering scale
+// with the active member enumeration.
+const FAMILY_PLAN = activeFieldFamily().planRow;
+const FAMILY_MEMBER_COUNT = activeFieldFamily().members.length;
+const CAPABILITY_SPECS = {
+    "bootstrap-model-create": {
+        change: "在 test 应用默认分组下创建清单所列 LIST 业务模型,每模型一步(序列化模型创建 + 权威 GET 回读),随后按已批准清理契约收尾",
+        boundary: "仅创建模型并回读验证;绝不 app publish、绝不 Environment release、绝不运行期业务数据变更",
+        runIdentity: TEST_FIXTURE_RUN,
+        identityLabels: ["模型"],
+        variadicIdentities: true,
+    },
+    "ticket02-model-create": {
+        change: "在 test 应用既有分组下创建一个序列化 LIST 模型(单步)并以权威 GET 回读确认,随后执行已批准的模型物理删除清理步",
+        boundary: "仅模型创建与回读;绝不 app publish、绝不 Environment release;写入仅经唯一配置写者租约执行",
+        runIdentity: TEST_FIXTURE_RUN,
+        identityLabels: ["模型"],
+    },
+    "ticket08-model-create": {
+        change: "创建一个序列化 LIST 测试夹具模型(单步;权威回读与行为验证;清理需另行单独审批)",
+        boundary: "仅创建测试夹具模型;绝不 app publish、绝不 Environment release;写入仅经唯一 Forge 配置写者租约执行",
+        runIdentity: TEST_FIXTURE_RUN,
+        identityLabels: ["夹具模型"],
+    },
+    "ticket08-model-cleanup": {
+        change: "物理删除本运行持有的测试夹具模型(单步;任务历史 END + 精确缺失回读)",
+        boundary: "仅删除归属明确的夹具模型;不确定结果立即停止、保留并上报,绝不盲试重放",
+        runIdentity: TEST_FIXTURE_CLEANUP_RUN,
+        identityLabels: ["夹具模型"],
+    },
+    "ticket08-orphan-cleanup": {
+        change: "经归属采纳预检后,物理删除遗留的本主机域测试夹具模型(单步;任务历史 END + 精确缺失回读)",
+        boundary: "仅删除采纳确认归属的遗留夹具模型;不确定结果立即停止、保留并上报",
+        runIdentity: TEST_FIXTURE_CLEANUP_RUN,
+        identityLabels: ["采纳夹具模型"],
+    },
+    "ticket09-field-create": {
+        change: `在夹具模型上创建${FAMILY_PLAN.familyShortLabel}族${FAMILY_MEMBER_COUNT}个类型化草稿字段(${[FAMILY_PLAN.fieldCreateQualifiers[0], FAMILY_PLAN.fieldCreateQualifiers[1] ?? ""].filter(Boolean).join("、")};逐字段草态/发布态两权威回读)`,
+        boundary: "仅草稿族字段创建;绝不 app publish、绝不 Environment release;清理分两段另行单独审批",
+        runIdentity: TEST_FIXTURE_RUN,
+        identityLabels: ["夹具模型", "族草稿字段"],
+        variadicIdentities: true,
+        identityCount: FAMILY_MEMBER_COUNT + 1,
+    },
+    "ticket09-field-cleanup": {
+        change: `强制删除本运行持有的${FAMILY_MEMBER_COUNT}个草稿族字段(逐字段;草态精确缺失回读)`,
+        boundary: "仅删除归属明确的草稿族字段;不确定结果停止、保留并上报",
+        runIdentity: TEST_FIXTURE_CLEANUP_RUN,
+        identityLabels: ["夹具模型", "族草稿字段"],
+        variadicIdentities: true,
+        identityCount: FAMILY_MEMBER_COUNT + 1,
+    },
+    "ticket10-field-publish": {
+        change: `一次模型级数据项发布夹具模型上${FAMILY_PLAN.familyShortLabel}族${FAMILY_MEMBER_COUNT}个字段(草态/发布态两权威回读与逐成员行为验证)`,
+        boundary: "仅模型级族字段发布;绝不 app publish、绝不表单发布、绝不 Environment release",
+        runIdentity: TEST_FIXTURE_RUN,
+        identityLabels: ["夹具模型", "族字段"],
+        variadicIdentities: true,
+        identityCount: FAMILY_MEMBER_COUNT + 1,
+    },
+    "ticket10-field-cleanup": {
+        change: `删除本运行持有的${FAMILY_MEMBER_COUNT}个已发布族字段(逐字段先探测 force_delete;确定性拒绝时按声明的模型级联契约收尾;两态精确缺失回读)`,
+        boundary: "仅处置归属明确的已发布族字段;不确定结果停止、保留并上报",
+        runIdentity: TEST_FIXTURE_CLEANUP_RUN,
+        identityLabels: ["夹具模型", "族字段"],
+        variadicIdentities: true,
+        identityCount: FAMILY_MEMBER_COUNT + 1,
+    },
+    "ticket11-form-draft": {
+        change: `保存夹具模型默认表单草稿(单步;空布局时组合设计器标准脚手架;绑定${FAMILY_MEMBER_COUNT}个族类型化控件,选项只写 visible 与总是只读布尔;发布态保持不变)`,
+        boundary: "仅草稿保存;绝不表单发布、绝不 app publish、绝不 Environment release",
+        runIdentity: TEST_FIXTURE_RUN,
+        identityLabels: ["夹具模型", "默认表单", "族控件字段"],
+        variadicIdentities: true,
+        identityCount: FAMILY_MEMBER_COUNT + 2,
+    },
+    "ticket20-data-rule": {
+        change: `经设计器原生规则面创建一条无条件必填规则行(单步;dataRuleType=4,选项 {requiredFormula:true,functionType:true},绑定${FAMILY_PLAN.ruleTargetLabel};规则列表权威回读解码)`,
+        boundary: "仅必填规则行创建;绝不只读/显示条件规则、绝不表单发布、绝不 app publish、绝不 Environment release",
+        runIdentity: TEST_FIXTURE_RUN,
+        identityLabels: ["夹具模型", "规则演示字段"],
+    },
+    "ticket12-form-publish": {
+        change: `发布夹具模型默认表单(模型级表单发布;${FAMILY_MEMBER_COUNT}个类型化控件随发布侧解码;发布历史解码;此前记录的表单一致性滞后在此了结)`,
+        boundary: "仅模型级默认表单发布;绝不 app publish、绝不 Environment release",
+        runIdentity: TEST_FIXTURE_RUN,
+        identityLabels: ["夹具模型", "默认表单", "族控件字段"],
+        variadicIdentities: true,
+        identityCount: FAMILY_MEMBER_COUNT + 2,
+    },
+};
+/** Validates that every identity/scope entry is code-like — model-authored phrasing is rejected. */
+function assertCodeLike(value, pattern, label) {
+    if (typeof value !== "string" || !pattern.test(value))
+        throw new Error(`Approval human-readable summary ${label} is not a valid immutable code reference: ${String(value).slice(0, 80)}`);
+}
+function validateHumanBlockInput(input) {
+    const spec = CAPABILITY_SPECS[input.capability];
+    if (!spec)
+        throw new Error(`Approval human-readable summary has no Host-owned capability registry entry for ${String(input.capability)}.`);
+    if (input.kind !== "delivery-plan" && input.kind !== "environment-change")
+        throw new Error("Approval human-readable summary requires the frame kind.");
+    const identityCount = spec.identityCount ?? spec.identityLabels.length;
+    if (!Array.isArray(input.identities) || (spec.identityCount !== undefined ? input.identities.length !== identityCount : spec.variadicIdentities ? input.identities.length < identityCount : input.identities.length !== identityCount))
+        throw new Error(`Approval human-readable summary requires ${spec.identityCount !== undefined ? "exactly " : spec.variadicIdentities ? "at least " : "exactly "}${identityCount} resource identit${identityCount === 1 ? "y" : "ies"} for ${input.capability}.`);
+    input.identities.forEach((identity) => assertCodeLike(identity, IDENTITY_PATTERN, "resource identity"));
+    if (!Array.isArray(input.scope) || !input.scope.length)
+        throw new Error("Approval human-readable summary requires the exact approved operation scope.");
+    input.scope.forEach((scope) => assertCodeLike(scope, SCOPE_PATTERN, "operation scope"));
+    if (/(password|token|cookie|client[_-]?secret|authorization|api[_-]?key|private[_-]?key|bearer\s|-----begin|raw[_-]?(request|response|log))/i.test([...input.identities, ...input.scope].join(" ")))
+        throw new Error("Approval human-readable summary identities contain prohibited sensitive data.");
+    return spec;
+}
+/** Renders the four-line human-readable block from the registry + validated identities/scope. */
+export function renderApprovalHumanBlock(input) {
+    const spec = validateHumanBlockInput(input);
+    const identities = input.identities.map((identity, index) => `${spec.identityLabels[Math.min(index, spec.identityLabels.length - 1)]} ${identity}`).join(" / ");
+    return [
+        `  变更内容:${spec.change}`,
+        `  边界承诺:${spec.boundary}`,
+        `  运行身份:${spec.runIdentity}`,
+        `  资源身份:${identities}(操作范围 ${input.scope.join(", ")})`,
+    ].join("\n");
+}
+/** Appends the human-readable block after the byte-identical machine prefix. */
+export function appendApprovalHumanBlock(machinePrefix, input) {
+    if (typeof machinePrefix !== "string" || !machinePrefix || machinePrefix.includes("\n"))
+        throw new Error("Approval machine prefix must be the single unchanged machine line.");
+    return `${machinePrefix}\n${renderApprovalHumanBlock(input)}`;
+}
+// ---------------------------------------------------------------------------
+// Ticket 17 (issue 03) — the single master approval frame, format polish.
+//
+// Grill decisions of 2026-09-05: the conversational plan-of-record carries
+// the entire reading budget (the omc_master_plan_compose tool output), so the
+// master frame is reduced to exactly THREE host-derived lines (summary /
+// impact+boundary / anchor+guidance) with the machine prefix line DELETED —
+// the master frame is a new contract with no archived-replay obligation, and
+// the binding is structural (the approve tool call plus the plan hash sealed
+// in the master plan record), never the displayed text. The 8-hex anchor
+// prefix stays on line three for human cross-checking against the plan
+// receipt. The same iron rules carry over: the frame is composed only from
+// the fixed registry below plus grammar-validated enumeration input taken
+// from the immutable master plan record — there is no free-text parameter,
+// so model-authored phrasing can never enter the master frame; a rendered
+// frame that diverges from the record is rejected before the human is asked.
+// The legacy per-package four-line 变更内容 blocks above stay byte-identical.
+// ---------------------------------------------------------------------------
+/** Compact per-stage chain titles for the master frame's line-one summary (fixed text). */
+const MASTER_STAGE_SUMMARY_TITLES = {
+    "ticket08-model-create": "模型",
+    "ticket09-field-create": `字段(${activeFieldFamily().planRow.familyShortLabel})`,
+    "ticket10-field-publish": "发布",
+    "ticket11-form-draft": "草稿",
+    "ticket20-data-rule": "规则(必填)",
+    "ticket12-form-publish": "发布表单",
+};
+function validateMasterHumanBlockInput(input) {
+    if (!Array.isArray(input.stages) || input.stages.length !== 6)
+        throw new Error("Master approval human-readable summary requires the six enumerated chain stages.");
+    input.stages.forEach((stage, index) => {
+        if (!MASTER_STAGE_SUMMARY_TITLES[stage.capability])
+            throw new Error(`Master approval human-readable summary stage ${index + 1} has no Host-owned registry entry for ${String(stage.capability)}.`);
+        if (input.stages.slice(0, index).some((prior) => MASTER_STAGE_SUMMARY_TITLES[prior.capability] === MASTER_STAGE_SUMMARY_TITLES[stage.capability]))
+            throw new Error("Master approval human-readable summary stages must be the six distinct enumerated capabilities.");
+        // Ticket 25 family rung: identity cardinality is exact per capability:
+        // model=1, field/rule=1+N/2, and form=2+N. This keeps the three-line
+        // summary bound to the immutable plan instead of accepting arbitrary
+        // extra resources under a loose upper bound.
+        const expectedIdentityCount = stage.capability === "ticket08-model-create" ? 1
+            : stage.capability === "ticket09-field-create" || stage.capability === "ticket09-field-cleanup" || stage.capability === "ticket10-field-publish" || stage.capability === "ticket10-field-cleanup" ? fieldFamilyMembers().length + 1
+                : stage.capability === "ticket11-form-draft" || stage.capability === "ticket12-form-publish" ? fieldFamilyMembers().length + 2
+                    : stage.capability === "ticket20-data-rule" ? 2
+                        : undefined;
+        if (!Array.isArray(stage.identities) || expectedIdentityCount === undefined || stage.identities.length !== expectedIdentityCount)
+            throw new Error(`Master approval human-readable summary stage ${index + 1} requires exactly ${expectedIdentityCount ?? "the registered"} resource identities.`);
+        stage.identities.forEach((identity) => assertCodeLike(identity, IDENTITY_PATTERN, "master resource identity"));
+        if (typeof stage.scope !== "string" || !SCOPE_PATTERN.test(stage.scope))
+            throw new Error(`Master approval human-readable summary stage ${index + 1} requires the exact operation scope.`);
+    });
+    // The master plan always declares exactly the two staged cleanups
+    // (composeMasterPlan pins them); any other count is a foreign shape.
+    if (input.cleanupCount !== 2)
+        throw new Error("Master approval human-readable summary requires the two declared staged cleanups.");
+    for (const value of [input.environment, input.application, input.folderId, input.testRunId])
+        assertCodeLike(value, IDENTITY_PATTERN, "master impact reference");
+    if (typeof input.folderName !== "string" || !input.folderName.trim())
+        throw new Error("Master approval human-readable summary requires the folder name.");
+    // Display names are the only free-form-ish text on the approval surface;
+    // line breaks or control characters could forge the frame structure.
+    if (/[\n\r\t\u0000-\u001f]/.test(input.folderName))
+        throw new Error("Master approval human-readable summary folder name must be single-line text.");
+    if (!/^[a-f0-9]{64}$/i.test(input.anchorHash))
+        throw new Error("Master approval human-readable summary requires the 64-hex plan anchor hash.");
+    if (/(password|token|cookie|client[_-]?secret|authorization|api[_-]?key|private[_-]?key|bearer\s|-----begin|raw[_-]?(request|response|log))/i.test([input.testRunId, input.folderName, ...input.stages.flatMap((stage) => [...stage.identities, stage.scope])].join(" ")))
+        throw new Error("Master approval human-readable summary contains prohibited sensitive data.");
+}
+/** Renders the exactly-three-line master frame: summary / impact+boundary / anchor+guidance. */
+export function renderMasterApprovalFrame(input) {
+    validateMasterHumanBlockInput(input);
+    const chain = [...input.stages.map((stage) => MASTER_STAGE_SUMMARY_TITLES[stage.capability]), "分级清理"];
+    return [
+        `批准执行 ${input.stages.length + input.cleanupCount} 步交付:${chain.join("→")}`,
+        `影响:${input.environment} 环境·${input.folderName} · 绝不 app publish / Environment release`,
+        `锚点 ${input.anchorHash.slice(0, 8)} · 完整方案见上方对话 · 逐步结果将在对话内汇报`,
+    ].join("\n");
+}
+/**
+ * Re-derives the exactly-three-line frame from the immutable enumeration
+ * input and fails any frame that diverges from it — the complete mismatch
+ * gate (the binding itself is structural: the approve tool call plus the
+ * plan hash sealed in the master plan record).
+ */
+export function verifyMasterApprovalFrameHumanBlock(frame, input) {
+    if (typeof frame !== "string" || !frame)
+        throw new Error("Approval frame is required.");
+    if (frame !== renderMasterApprovalFrame(input))
+        throw new Error("Master approval frame human-readable summary diverges from the immutable master plan enumeration.");
+}
+/**
+ * Master approval-request structural gate: the frame must be exactly the
+ * three Host-rendered lines (summary / impact+boundary / anchor+guidance) —
+ * no machine prefix, no fourth line, no injected block — and must carry the
+ * 8-hex anchor prefix for human cross-check. The byte-exact re-derivation
+ * against the record (verifyMasterApprovalFrameHumanBlock) remains the
+ * complete mismatch gate.
+ */
+export function assertMasterApprovalFrameHumanBlock(frame) {
+    if (typeof frame !== "string" || !frame)
+        throw new Error("Approval frame is required.");
+    const lines = frame.split("\n");
+    if (lines.length !== 3)
+        throw new Error("Master approval frame is not the exactly-three-line contract.");
+    if (!/^批准执行 [0-9]+ 步交付:.+→分级清理$/.test(lines[0]))
+        throw new Error("Master approval frame summary line is not Host-rendered.");
+    if (!lines[1].startsWith("影响:") || !lines[1].includes("绝不 app publish") || !lines[1].includes("Environment release"))
+        throw new Error("Master approval frame impact line is not Host-rendered.");
+    if (!/^锚点 [a-f0-9]{8} · 完整方案见上方对话 · 逐步结果将在对话内汇报$/.test(lines[2]))
+        throw new Error("Master approval frame anchor line is not Host-rendered.");
+    if (/(password|token|cookie|client[_-]?secret|authorization|api[_-]?key|private[_-]?key|bearer\s|-----begin|raw[_-]?(request|response|log))/i.test(frame))
+        throw new Error("Master approval frame human-readable summary contains prohibited sensitive data.");
+}
+/** Read-only access to a capability's Host-owned registry spec (shared with the conversational plan renderer). */
+export function approvalHumanCapabilitySpec(capability) {
+    const spec = CAPABILITY_SPECS[capability];
+    if (!spec)
+        throw new Error(`Approval human-readable summary has no Host-owned capability registry entry for ${String(capability)}.`);
+    return { change: spec.change, boundary: spec.boundary, runIdentity: spec.runIdentity };
+}
+function humanBlockStart(frame) {
+    return frame.indexOf("\n  变更内容:");
+}
+/** Re-derives the block from the immutable input and fails any frame that diverges from it. */
+export function verifyApprovalFrameHumanBlock(frame, input) {
+    if (typeof frame !== "string" || !frame)
+        throw new Error("Approval frame is required.");
+    const block = renderApprovalHumanBlock(input);
+    const start = humanBlockStart(frame);
+    if (start < 0 || frame.slice(start + 1) !== block || frame.split(block).length !== 2)
+        throw new Error("Approval frame human-readable summary diverges from the immutable package/plan identities and scope.");
+}
+/**
+ * Approval-request gate: the frame must carry exactly one well-formed
+ * human-readable block at its end, and every resource identity code in the
+ * block must also appear in the machine prefix — which the Host derives from
+ * the same validated immutable approval/package binding — so a summary
+ * rendered from any other package is rejected before the human is asked.
+ */
+export function assertApprovalFrameHumanBlock(frame) {
+    if (typeof frame !== "string" || !frame)
+        throw new Error("Approval frame is required.");
+    const blockStart = humanBlockStart(frame);
+    if (blockStart < 0)
+        throw new Error("Approval frame is missing the Host-generated human-readable summary block.");
+    const machinePrefix = frame.slice(0, blockStart);
+    const block = frame.slice(blockStart + 1);
+    if (!machinePrefix || machinePrefix.includes("\n  变更内容:"))
+        throw new Error("Approval frame machine prefix is malformed.");
+    const lines = block.split("\n");
+    if (lines.length !== 4 || !lines[0].startsWith("  变更内容:") || !lines[1].startsWith("  边界承诺:") || !lines[2].startsWith("  运行身份:") || !lines[3].startsWith("  资源身份:") || !lines[3].endsWith(")"))
+        throw new Error("Approval frame human-readable summary block is not the Host-rendered four-line contract.");
+    if (/(password|token|cookie|client[_-]?secret|authorization|api[_-]?key|private[_-]?key|bearer\s|-----begin|raw[_-]?(request|response|log))/i.test(block))
+        throw new Error("Approval frame human-readable summary contains prohibited sensitive data.");
+    const identityLine = lines[3].slice("  资源身份:".length, lines[3].indexOf("(操作范围"));
+    for (const identity of identityLine.split(" / ")) {
+        const code = identity.slice(identity.lastIndexOf(" ") + 1);
+        if (!IDENTITY_PATTERN.test(code))
+            throw new Error(`Approval frame human-readable summary carries a non-code resource identity: ${code.slice(0, 80)}`);
+        if (!machinePrefix.includes(code))
+            throw new Error(`Approval frame human-readable summary identity ${code} diverges from the machine prefix binding.`);
+    }
+}
+//# sourceMappingURL=approval-frame-readability.js.map

package/dist/approval-protocol.js

@@ -0,0 +1,143 @@
+import { createHash, createHmac, randomUUID, timingSafeEqual } from "node:crypto";
+import { mkdirSync } from "node:fs";
+import { DatabaseSync } from "node:sqlite";
+import { dirname } from "node:path";
+export class ApprovalProtocol {
+    db;
+    key;
+    constructor(databasePath, key) {
+        mkdirSync(dirname(databasePath), { recursive: true });
+        this.key = Buffer.isBuffer(key) ? key : Buffer.from(key, "base64");
+        if (this.key.length !== 32)
+            throw new Error("Approval protocol integrity key must be exactly 32 bytes.");
+        this.db = new DatabaseSync(databasePath);
+        this.db.exec(`CREATE TABLE IF NOT EXISTS approval_protocol (
+      transaction_id TEXT PRIMARY KEY, kind TEXT NOT NULL, opaque_id TEXT NOT NULL,
+      expected_json TEXT NOT NULL, intent_hash TEXT NOT NULL, status TEXT NOT NULL,
+      completed_boundaries_json TEXT NOT NULL, record_hash TEXT NOT NULL, integrity_mac TEXT NOT NULL,
+      UNIQUE(kind, opaque_id)
+    )`);
+        for (const column of ["prompt_issued INTEGER NOT NULL DEFAULT 0", "approval_outcome TEXT"]) {
+            try {
+                this.db.exec(`ALTER TABLE approval_protocol ADD COLUMN ${column}`);
+            }
+            catch { /* already present */ }
+        }
+    }
+    begin(kind, opaqueId, expected) {
+        if (!opaqueId)
+            throw new Error("Approval protocol requires an opaque ID.");
+        const existing = this.load(kind, opaqueId);
+        const intentHash = sha256({ kind, opaqueId, expected });
+        if (existing) {
+            if (existing.status === "operator-reconcile")
+                throw new Error("Approval protocol is blocked for operator reconcile.");
+            if (existing.intentHash !== intentHash)
+                throw new Error("Approval protocol intent diverges from the authenticated approval frame; operator reconcile is required.");
+            return existing;
+        }
+        const value = { transactionId: randomUUID(), kind, opaqueId, expected, intentHash, status: "pending", completedBoundaries: [], promptIssued: false };
+        this.save(value);
+        return value;
+    }
+    get(kind, opaqueId) { return this.load(kind, opaqueId); }
+    claimPrompt(intent) {
+        const current = this.authenticate(intent);
+        if (current.promptIssued)
+            return { intent: current, claimed: false };
+        const next = { ...current, promptIssued: true };
+        const recordHash = sha256(next);
+        const mac = hmac(recordHash, this.key);
+        const result = this.db.prepare(`UPDATE approval_protocol
+      SET prompt_issued = 1, record_hash = ?, integrity_mac = ?
+      WHERE transaction_id = ? AND kind = ? AND opaque_id = ? AND intent_hash = ? AND prompt_issued = 0`)
+            .run(recordHash, mac, current.transactionId, current.kind, current.opaqueId, current.intentHash);
+        if (Number(result.changes) !== 1) {
+            const latest = this.authenticate(intent);
+            return { intent: latest, claimed: false };
+        }
+        return { intent: next, claimed: true };
+    }
+    recordOutcome(intent, outcome) {
+        if (!outcome)
+            throw new Error("Approval protocol outcome is required.");
+        const current = this.authenticate(intent);
+        if (!current.promptIssued)
+            throw new Error("Approval protocol prompt was not issued.");
+        if (current.approvalOutcome && current.approvalOutcome !== outcome)
+            throw new Error("Approval protocol approval outcome diverges; operator reconcile is required.");
+        if (current.approvalOutcome === outcome)
+            return current;
+        const next = { ...current, approvalOutcome: outcome };
+        this.save(next);
+        return next;
+    }
+    markBoundary(intent, boundary) {
+        const current = this.load(intent.kind, intent.opaqueId);
+        if (!current || current.transactionId !== intent.transactionId || current.intentHash !== intent.intentHash)
+            throw new Error("Approval protocol transaction authentication failed; operator reconcile is required.");
+        if (current.status === "operator-reconcile")
+            throw new Error("Approval protocol is blocked for operator reconcile.");
+        if (current.completedBoundaries.includes(boundary))
+            return current;
+        const completedBoundaries = [...current.completedBoundaries, boundary];
+        const next = { ...current, completedBoundaries, status: completedBoundaries.length === 3 ? "complete" : "pending" };
+        this.save(next);
+        return next;
+    }
+    failClosed(intent, reason) {
+        const current = this.load(intent.kind, intent.opaqueId);
+        if (current && current.transactionId === intent.transactionId && current.intentHash === intent.intentHash)
+            this.save({ ...current, status: "operator-reconcile" });
+        throw new Error(`Approval protocol requires operator reconcile: ${reason}`);
+    }
+    abandon(intent) {
+        const current = this.load(intent.kind, intent.opaqueId);
+        if (!current || current.transactionId !== intent.transactionId || current.intentHash !== intent.intentHash || current.completedBoundaries.length)
+            throw new Error("Approval protocol transaction cannot be abandoned.");
+        this.db.prepare("DELETE FROM approval_protocol WHERE transaction_id = ?").run(intent.transactionId);
+    }
+    renew(intent, expected) {
+        const current = this.authenticate(intent);
+        if (current.kind !== "execution-approval" || current.completedBoundaries.length < 2 || current.approvalOutcome !== "allowed-once")
+            throw new Error("Approval protocol execution intent cannot be renewed before authoritative reconciliation.");
+        this.db.prepare("DELETE FROM approval_protocol WHERE transaction_id = ?").run(current.transactionId);
+        return this.begin(current.kind, current.opaqueId, expected);
+    }
+    load(kind, opaqueId) {
+        const row = this.db.prepare("SELECT * FROM approval_protocol WHERE kind = ? AND opaque_id = ?").get(kind, opaqueId);
+        if (!row)
+            return undefined;
+        const value = { transactionId: String(row.transaction_id), kind: String(row.kind), opaqueId: String(row.opaque_id), expected: JSON.parse(String(row.expected_json)), intentHash: String(row.intent_hash), status: String(row.status), completedBoundaries: JSON.parse(String(row.completed_boundaries_json)), promptIssued: Number(row.prompt_issued) === 1, ...(row.approval_outcome ? { approvalOutcome: String(row.approval_outcome) } : {}) };
+        const recordHash = sha256(value);
+        const legacyRecordHash = sha256({ transactionId: value.transactionId, kind: value.kind, opaqueId: value.opaqueId, expected: value.expected, intentHash: value.intentHash, status: value.status, completedBoundaries: value.completedBoundaries });
+        const storedHash = String(row.record_hash);
+        const validRecord = storedHash === recordHash || (storedHash === legacyRecordHash && !value.promptIssued && value.approvalOutcome === undefined);
+        if (!validRecord || !sameMac(String(row.integrity_mac), hmac(storedHash, this.key)) || value.intentHash !== sha256({ kind: value.kind, opaqueId: value.opaqueId, expected: value.expected }))
+            throw new Error("Approval protocol record authentication is invalid; operator reconcile is required.");
+        return value;
+    }
+    save(value) {
+        const recordHash = sha256(value);
+        const mac = hmac(recordHash, this.key);
+        this.db.prepare(`INSERT INTO approval_protocol (transaction_id, kind, opaque_id, expected_json, intent_hash, status, completed_boundaries_json, prompt_issued, approval_outcome, record_hash, integrity_mac)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?) ON CONFLICT(transaction_id) DO UPDATE SET status = excluded.status, completed_boundaries_json = excluded.completed_boundaries_json, prompt_issued = excluded.prompt_issued, approval_outcome = excluded.approval_outcome, record_hash = excluded.record_hash, integrity_mac = excluded.integrity_mac`)
+            .run(value.transactionId, value.kind, value.opaqueId, canonical(value.expected), value.intentHash, value.status, canonical(value.completedBoundaries), value.promptIssued ? 1 : 0, value.approvalOutcome ?? null, recordHash, mac);
+    }
+    authenticate(intent) {
+        const current = this.load(intent.kind, intent.opaqueId);
+        if (!current || current.transactionId !== intent.transactionId || current.intentHash !== intent.intentHash)
+            throw new Error("Approval protocol transaction authentication failed; operator reconcile is required.");
+        if (current.status === "operator-reconcile")
+            throw new Error("Approval protocol is blocked for operator reconcile.");
+        return current;
+    }
+}
+function sha256(value) { return createHash("sha256").update(canonical(value)).digest("hex"); }
+function hmac(value, key) { return createHmac("sha256", key).update(value).digest("hex"); }
+function sameMac(actual, expected) { const a = Buffer.from(actual, "hex"); const b = Buffer.from(expected, "hex"); return a.length === b.length && timingSafeEqual(a, b); }
+function canonical(value) { return JSON.stringify(sort(value)); }
+function sort(value) { if (Array.isArray(value))
+    return value.map(sort); if (value && typeof value === "object")
+    return Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([key, item]) => [key, sort(item)])); return value; }
+//# sourceMappingURL=approval-protocol.js.map