@stalfh233/omc-cli 0.0.0-stage → 0.4.10

package/dist/workflow-support.js

@@ -0,0 +1,99 @@
+import { ENDPOINTS } from "./endpoints.js";
+import { wireCall } from "./wire.js";
+/**
+ * Shared workflow RUNTIME endpoint knowledge (ticket 21): merges the two
+ * parallel protocol implementations that used to live inside the runtime-data
+ * and workflow lanes, mirroring form-support / rule-support. Design-time
+ * workflow authoring (template read/write/publish) stays in the workflow
+ * lane — this module owns only:
+ *
+ * - GET /runtime/workflow/search_workitems — the caller's pending todos
+ *   (server injects userId); WorkItemSearchVO.filterWorkflowInstanceId is a
+ *   NOT-equal exclusion (BizWorkitemServiceImpl.toSearchWorkItemsCriterion:
+ *   400-402), so exact instance matching is client-side and that server
+ *   field is never sent.
+ * - GET /runtime/workflow/getBizObjectByWfInstanceId — in-flight bizObject
+ *   identity (BizObjectCreatedModel.id/schemaCode).
+ * - GET /runtime/form/getReplayToken — replay token the isStartWf branches
+ *   verify server-side (AbstractFormRuntimeController.verifyReplay, else
+ *   100005).
+ *
+ * Deliberately NOT here (grilled seam, ticket 21): status polling (form/load
+ * readback semantics — runtime-data), formType branching, submit payload
+ * assembly, and the two-phase draft orchestration.
+ */
+/** Tolerant string decode for wire fields (empty/non-string → null). */
+export function wireString(value) {
+    return typeof value === "string" && value ? value : null;
+}
+/**
+ * Decode the `PageVO<WorkItemVO>` payload of search_workitems:
+ * `{ totalPages, totalElements, content }` serialized directly; a `page`/`data`
+ * wrapper is tolerated for resilience. The single decoder for both lanes
+ * (ticket 21: the two per-lane extract* twins merged into one).
+ */
+export function decodeWorkItemPage(value) {
+    const root = value && typeof value === "object" ? value : {};
+    const candidate = root.page && typeof root.page === "object" ? root.page : root;
+    const content = Array.isArray(candidate.content)
+        ? candidate.content.filter((row) => !!row && typeof row === "object")
+        : [];
+    return {
+        total: typeof candidate.totalElements === "number" ? candidate.totalElements : 0,
+        totalPages: typeof candidate.totalPages === "number" ? candidate.totalPages : 0,
+        content,
+    };
+}
+/**
+ * Discover the caller's pending work items on the evidenced endpoint and
+ * apply the client-side exact instance filter when requested. Returns the
+ * page-level totals plus the (filtered) content rows.
+ */
+export async function searchWorkItems(session, filter = {}) {
+    const query = {
+        page: String(filter.page ?? 0),
+        size: String(filter.size ?? 200),
+    };
+    if (filter.workflowCode)
+        query.workflowCode = filter.workflowCode;
+    if (filter.schemaCode)
+        query.schemaCode = filter.schemaCode;
+    const page = decodeWorkItemPage((await wireCall(session, { path: ENDPOINTS.workflowSearchWorkItems, query })).data);
+    const items = filter.instanceId
+        ? page.content.filter((item) => wireString(item.instanceId) === filter.instanceId)
+        : page.content;
+    return { total: page.total, totalPages: page.totalPages, items };
+}
+/**
+ * Resolve the in-flight bizObject identity for a workflow instance.
+ * Authoritative source: getBizObjectByWfInstanceId → BizObjectCreatedModel
+ * .id/.schemaCode. Best-effort by design: a failed lookup leaves the
+ * identity null and never throws — a resolution failure must not drop the
+ * todo it belongs to.
+ */
+export async function resolveBizObjectIdByInstance(session, instanceId) {
+    try {
+        const object = await wireCall(session, {
+            path: ENDPOINTS.workflowGetBizObjectByWfInstanceId,
+            query: { workflowInstanceId: instanceId },
+        });
+        const data = (object.data ?? {});
+        return {
+            bizObjectId: wireString(data.id) ?? wireString(data.objectId),
+            schemaCode: wireString(data.schemaCode),
+        };
+    }
+    catch {
+        return { bizObjectId: null, schemaCode: null };
+    }
+}
+/**
+ * Fetch a replay token from GET /runtime/form/getReplayToken. Returns
+ * undefined when the face yields no usable string — callers then omit the
+ * key entirely (a token-less request must not carry an empty value).
+ */
+export async function getReplayToken(session) {
+    const token = await wireCall(session, { path: ENDPOINTS.runtimeFormReplayToken, query: {} });
+    return typeof token.data === "string" && token.data ? token.data : undefined;
+}
+//# sourceMappingURL=workflow-support.js.map

package/dist/write-lease.js

@@ -0,0 +1,26 @@
+/**
+ * Per-environment write lease: concurrent write operations must serialize.
+ * A write acquires the lease; a second concurrent write waits (bounded) for
+ * the first to complete rather than interleaving. Enforced across the whole
+ * CLI process, keyed by environment name.
+ */
+export class WriteLeaseQueue {
+    chains = new Map();
+    active = new Map();
+    run(environment, operationId, operation) {
+        const previous = this.chains.get(environment) ?? Promise.resolve();
+        const result = previous.then(operation, operation);
+        this.chains.set(environment, result.then(() => undefined, () => undefined));
+        this.active.set(environment, operationId);
+        const clear = () => {
+            if (this.active.get(environment) === operationId)
+                this.active.delete(environment);
+        };
+        result.then(clear, clear);
+        return result;
+    }
+    holder(environment) {
+        return this.active.get(environment);
+    }
+}
+//# sourceMappingURL=write-lease.js.map

package/dist/write-lock.js

@@ -0,0 +1,109 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import lockfile from "proper-lockfile";
+function locksRoot() {
+    return join(resolve(process.env.OMC_CONFIG_HOME ?? join(process.cwd(), ".omc")), "locks");
+}
+function lockTarget(environment) {
+    const encoded = environment.replace(/[^a-zA-Z0-9_-]/g, (char) => [...char].map((c) => `-${c.charCodeAt(0).toString(16)}`).join(""));
+    return join(locksRoot(), encoded);
+}
+function ownerFile(environment) {
+    return `${lockTarget(environment)}.lock.owner.json`;
+}
+function readOwner(environment) {
+    try {
+        return JSON.parse(readFileSync(ownerFile(environment), "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function writeOwner(environment) {
+    const owner = { pid: process.pid, startedAt: new Date().toISOString(), command: process.argv.slice(0, 4).join(" ") };
+    try {
+        writeFileSync(ownerFile(environment), JSON.stringify(owner, null, 2) + "\n", { mode: 0o600 });
+    }
+    catch {
+        // metadata only: the filesystem lock itself remains authoritative
+    }
+}
+function clearOwner(environment) {
+    try {
+        rmSync(ownerFile(environment), { force: true });
+    }
+    catch {
+        // metadata only
+    }
+}
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+function breakStaleLock(environment) {
+    rmSync(`${lockTarget(environment)}.lock`, { recursive: true, force: true });
+    clearOwner(environment);
+}
+async function tryAcquire(environment) {
+    mkdirSync(locksRoot(), { recursive: true });
+    try {
+        const release = await lockfile.lock(lockTarget(environment), { retries: 0, realpath: false, stale: 30_000 });
+        writeOwner(environment);
+        return {
+            held: true,
+            release: async () => {
+                clearOwner(environment);
+                try {
+                    await release();
+                }
+                catch {
+                    // already released or broken by a stale recovery
+                }
+            },
+        };
+    }
+    catch (error) {
+        const code = error.code;
+        if (code !== "ELOCKED")
+            throw error;
+        const owner = readOwner(environment);
+        if (owner && Number.isInteger(owner.pid) && !pidAlive(owner.pid)) {
+            breakStaleLock(environment);
+            return tryAcquire(environment);
+        }
+        const lockDir = `${lockTarget(environment)}.lock`;
+        const ownerDead = owner !== null && Number.isInteger(owner.pid) && !pidAlive(owner.pid);
+        return {
+            held: false,
+            reason: "conflict",
+            owner,
+            recovery: [
+                `another process holds the write lock for environment ${environment}`,
+                owner ? `owner pid=${owner.pid} started=${owner.startedAt} command=${owner.command}` : "owner metadata missing (the holder predates lock metadata or crashed while acquiring)",
+                `lock path: ${lockDir}`,
+                ...(ownerDead
+                    ? ["owner pid is NOT alive → this is a STALE lock; re-running the same command now recovers automatically (or delete the lock path above)"]
+                    : ["the holder is alive → wait for it to finish, then retry (retryable:true); do NOT delete the lock path while the holder runs"]),
+                `to force recovery when the owner is dead: rm -rf "${lockDir}" then retry`,
+            ],
+        };
+    }
+}
+export async function acquireWriteLock(environment) {
+    return tryAcquire(environment);
+}
+export function lockOwner(environment) {
+    return readOwner(environment);
+}
+export function staleLockPresent(environment) {
+    if (!existsSync(`${lockTarget(environment)}.lock`))
+        return false;
+    const owner = readOwner(environment);
+    return owner !== null && Number.isInteger(owner.pid) && !pidAlive(owner.pid);
+}
+//# sourceMappingURL=write-lock.js.map

package/dist/write.js

@@ -0,0 +1,176 @@
+import { z } from "zod";
+import { randomUUID } from "node:crypto";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+/** Parse a JSON string for the dry-lint; unparseable input returns undefined so the shape validators report it. */
+function parseJsonOrUndefined(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+import { admitGovernedWrite } from "./governed-execution.js";
+import { writeSummary } from "./human-summary.js";
+import { planFor } from "./plan.js";
+import { isUncertainWireError, sha256, wireErrorKind, writeArtifact } from "./support.js";
+import { capabilityArg, confirmProductionArg, environmentArg, WRITE_PROTOCOL } from "./args.js";
+import { plannableArgsRaw } from "./plan.js";
+import { defineTool, ToolRefusalError } from "./tool-types.js";
+import { assertFieldFamilyAllowed } from "./field-families.js";
+import { validateBusinessCode } from "./code-rules.js";
+import { validateFormLayout } from "./form-layout.js";
+import { prepareRuleGraph, validateRuleNodeGraph } from "./lanes/rule-graph.js";
+import { WireError } from "./wire.js";
+/**
+ * The shared governed write pipeline and the low-level write registration
+ * factory every lane adapter uses.
+ */
+/**
+ * Shared governed write pipeline: coverage gate → environment write permission
+ * → session → version-family gate (fail closed without evidence) → production
+ * confirmation → write lease → execute with authoritative readback.
+ */
+async function governedWrite(ctx, tool, args, execute, dryRunPayload) {
+    const requestFingerprint = args.requestId ? sha256({ requestId: args.requestId, args: plannableArgsRaw(args) }) : undefined;
+    // The shared admission owns the gate sequence; this face only supplies its
+    // plan and its dry-run / replay payload shapes.
+    const outcome = await admitGovernedWrite(ctx, {
+        environment: args.environment,
+        confirmProduction: args.confirmProduction,
+        dryRun: args.dryRun,
+        capability: args.capability,
+        coverage: { lane: args.capability ?? tool.lane, scope: tool.scope ?? "" },
+        plan: (session) => planFor(ctx, args.environment, tool.name, args),
+        // A face may supply a session-aware dry-run projection (e.g. model.delete's
+        // reference scan) so the preview carries facts that only live reads can
+        // establish — never a second write path.
+        dryRunResult: dryRunPayload ? (plan, session) => dryRunPayload(session, args).then((payload) => ({ status: "dry-run", wouldChange: true, plan, idempotency: idempotencyDeclaration(tool.name), ...payload, ...(args.requestId ? { requestId: args.requestId } : {}) })) : (plan) => ({ status: "dry-run", wouldChange: true, plan, idempotency: idempotencyDeclaration(tool.name), ...(args.requestId ? { requestId: args.requestId } : {}) }),
+        replay: (plan) => (requestFingerprint ? findCompleted(ctx.artifactsDir, args.requestId, tool.name, plan.environment, requestFingerprint) : undefined),
+    });
+    if (outcome.kind === "settled")
+        return outcome.result;
+    const { session, plan, productionConfirmed } = outcome.admission;
+    return ctx.lease.run(session.environmentName, `${tool.name}:${randomUUID().slice(0, 8)}`, async () => {
+        let executed;
+        try {
+            executed = await execute(session);
+        }
+        catch (error) {
+            if (isUncertainWireError(error))
+                return {
+                    status: "uncertain",
+                    frozen: true,
+                    reason: `wire-transport:${wireErrorKind(error)}`,
+                    detail: error.message,
+                    message: "write outcome cannot be established; frozen — re-discover before retrying; never assume success",
+                };
+            if (error instanceof ToolRefusalError)
+                throw error;
+            if (error instanceof WireError)
+                return { status: "refused", blocker: `wire-${error.kind}`, errcode: error.errcode, message: error.message, ...(error.diagnostic ? { diagnostic: error.diagnostic } : {}) };
+            throw error;
+        }
+        const { performed, readback } = executed;
+        // Every production write echoes the explicit acknowledgement into the audit
+        // trail, so the record can always answer "was this a confirmed production
+        // write?".
+        const artifact = {
+            tool: tool.name,
+            ...(args.requestId ? { requestId: args.requestId, requestFingerprint } : {}),
+            environment: session.environmentName,
+            environmentFingerprint: session.environmentFingerprint(),
+            performed,
+            readback,
+            ...(productionConfirmed ? { productionConfirmed: true } : {}),
+            deliveryState: "DELIVERED",
+            recordedAt: new Date().toISOString(),
+        };
+        const artifactRef = writeArtifact(ctx, `${tool.name}-${randomUUID().slice(0, 8)}.json`, artifact);
+        return { status: "ok", deliveryState: "DELIVERED", performed, readback, ...(args.requestId ? { requestId: args.requestId, idempotency: idempotencyDeclaration(tool.name) } : {}), ...(productionConfirmed ? { productionConfirmed: true } : {}), summary: writeSummary(tool.name, args, { performed, readback }, "done"), detailFile: artifactRef.detailFile, detailSha256: artifactRef.detailSha256, artifactFingerprint: artifactRef.detailSha256 };
+    });
+}
+function idempotencyDeclaration(tool) {
+    if (tool.includes("delete"))
+        return { key: "requestId", replay: "completed", duplicate: "already-absent-no-op" };
+    if (tool.includes("publish"))
+        return { key: "requestId", replay: "completed", duplicate: "already-published-no-op" };
+    if (tool.includes("import"))
+        return { key: "requestId", replay: "completed", duplicate: "same-request-replay-no-op" };
+    return { key: "requestId", replay: "completed", duplicate: "same-request-replay-no-op" };
+}
+function findCompleted(root, requestId, tool, environment, requestFingerprint) {
+    if (!existsSync(root))
+        return undefined;
+    for (const name of readdirSync(root)) {
+        if (!name.endsWith(".json"))
+            continue;
+        try {
+            const artifact = JSON.parse(readFileSync(join(root, name), "utf8"));
+            if (artifact.deliveryState === "DELIVERED" && artifact.requestId === requestId && artifact.tool === tool && artifact.environment === environment && artifact.requestFingerprint === requestFingerprint)
+                return { status: "ok", deliveryState: "DELIVERED", replay: "already-completed", requestId, idempotency: idempotencyDeclaration(tool), performed: artifact.performed, readback: artifact.readback };
+        }
+        catch { }
+    }
+    return undefined;
+}
+/** Low-level write registration factory: shared by every lane adapter. */
+export function writeTool(tools, name, lane, scope, description, inputSchema, execute, preflight, dryRunPayload) {
+    const rawExecute = execute;
+    const semanticGate = (args) => {
+        if (name === "field.create")
+            assertFieldFamilyAllowed(args);
+        // CFG-naming: reject an invalid business code BEFORE the write permission
+        // gate and any wire call (length / style / reserved system codes).
+        if (name === "model.create" || name === "field.create") {
+            const violations = validateBusinessCode(String(args.code ?? ""), { kind: name === "model.create" ? "model" : "field" });
+            if (violations.length > 0)
+                throw new ToolRefusalError({ status: "refused", blocker: "business-code-invalid", message: "code 未过出门前校验；按 validation 修正（长度/风格/保留字）", validation: violations });
+        }
+        // CFG-form-layout: a supplied draft layout must satisfy the platform's
+        // span/row/coverage invariants before it reaches the environment.
+        if (name === "form.draft" && typeof args.draftViewJson === "string" && typeof args.draftAttributesJson === "string") {
+            const violations = validateFormLayout(parseJsonOrUndefined(args.draftViewJson), parseJsonOrUndefined(args.draftAttributesJson));
+            if (violations.length > 0)
+                throw new ToolRefusalError({ status: "refused", blocker: "form-layout-invalid", message: "表单布局未过出门前校验；按 validation 修正（span 白名单/行宽≤24/整行独占/控件覆盖率）", validation: violations });
+        }
+        if (name === "rule.save") {
+            // Pre-flight dry lint (ticket 14): refuse a mis-shaped node graph
+            // BEFORE the write permission gate and before any wire call. CFG-02/CFG-26: lint
+            // the SAME normalized graph the executor will send (prepareRuleGraph) —
+            // linting the raw args would refuse a graph the executor normalizes and
+            // would wave through the shapes it does not touch.
+            const ruleCode = String(args.ruleCode ?? "");
+            const prepared = prepareRuleGraph(ruleCode, (args.nodeGraph ?? {}), args.customTrigger, typeof args.schemaCode === "string" ? args.schemaCode : undefined);
+            const blockers = [...prepared.warnings, ...validateRuleNodeGraph(prepared.graph, ruleCode, typeof args.schemaCode === "string" ? args.schemaCode : undefined)];
+            // Ticket 113: warning-severity findings ride the payload but never gate.
+            if (blockers.some((blocker) => blocker.severity !== "warning"))
+                throw new ToolRefusalError({ status: "refused", blocker: "rule-graph-validation-failed", message: "nodeGraph 未过出门前校验（dry lint）；按 validation 逐项修正，校验器不猜不改", validation: blockers });
+        }
+        // Optional per-tool semantic gate: refuse before the write permission gate
+        // and before any wire call, independent of input-schema validation.
+        if (preflight)
+            preflight(args);
+    };
+    tools.push({
+        ...defineTool({
+            name,
+            layer: "low",
+            kind: "write",
+            lane,
+            scope,
+            description: `${description} ${WRITE_PROTOCOL}`,
+            inputSchema: { environment: environmentArg, capability: capabilityArg, confirmProduction: confirmProductionArg, requestId: z.string().min(1).optional(), dryRun: z.boolean().optional(), ...inputSchema },
+            handler: async (ctx, args, self) => {
+                semanticGate(args);
+                return governedWrite(ctx, self, args, (session) => rawExecute(session, args), dryRunPayload);
+            },
+        }),
+        // Ticket 46: the batch entry drives the SAME executor/gates, so a batch
+        // step can never bypass its lane's readback or semantic refusal.
+        writeExecute: rawExecute,
+        writePreflight: semanticGate,
+    });
+}
+//# sourceMappingURL=write.js.map

package/dist/zip.js

@@ -0,0 +1,156 @@
+import { inflateRawSync } from "node:zlib";
+/**
+ * Ticket 106 — a minimal, dependency-free ZIP reader/writer for the bizservice
+ * IE package face.
+ *
+ * The platform export answers a ZIP with manifest.json + version.md
+ * (BizServiceIEController.java:124-138). Java's ZipOutputStream typically
+ * writes local headers with zeroed sizes plus a trailing data descriptor
+ * (general-purpose bit 3), so the READER resolves entries through the central
+ * directory (whose sizes/CRCs are authoritative) and only uses each local
+ * header to locate the data offset. The WRITER emits stored (method 0)
+ * entries — real zips for fake routes and tests; the platform reader accepts
+ * both stored and deflated entries.
+ */
+const EOCD_SIGNATURE = 0x06054b50;
+const CENTRAL_SIGNATURE = 0x02014b50;
+const LOCAL_SIGNATURE = 0x04034b50;
+const EOCD_SCAN_LIMIT = 65_557; // fixed EOCD (22) + max comment (65_535)
+export class ZipFormatError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ZipFormatError";
+    }
+}
+/** CRC-32 (IEEE 802.3), table-driven. */
+const CRC_TABLE = (() => {
+    const table = new Array(256);
+    for (let n = 0; n < 256; n += 1) {
+        let c = n;
+        for (let k = 0; k < 8; k += 1)
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        table[n] = c >>> 0;
+    }
+    return table;
+})();
+function crc32(buffer) {
+    let crc = 0xffffffff;
+    for (const byte of buffer)
+        crc = CRC_TABLE[(crc ^ byte) & 0xff] ^ (crc >>> 8);
+    return (crc ^ 0xffffffff) >>> 0;
+}
+/** Locate the End Of Central Directory record; returns its byte offset. */
+function locateEocd(buffer) {
+    const start = Math.max(0, buffer.length - EOCD_SCAN_LIMIT);
+    for (let offset = buffer.length - 22; offset >= start; offset -= 1) {
+        if (buffer.readUInt32LE(offset) === EOCD_SIGNATURE) {
+            const commentLength = buffer.readUInt16LE(offset + 20);
+            if (offset + 22 + commentLength === buffer.length)
+                return offset;
+        }
+    }
+    throw new ZipFormatError("no end-of-central-directory record found");
+}
+/** Read every central-directory entry as name → decompressed Buffer. */
+export function readZipEntries(buffer) {
+    const eocd = locateEocd(buffer);
+    const entryCount = buffer.readUInt16LE(eocd + 10);
+    let cursor = buffer.readUInt32LE(eocd + 16);
+    const entries = new Map();
+    for (let index = 0; index < entryCount; index += 1) {
+        if (cursor + 46 > buffer.length || buffer.readUInt32LE(cursor) !== CENTRAL_SIGNATURE)
+            throw new ZipFormatError(`central directory entry ${index} is malformed`);
+        const method = buffer.readUInt16LE(cursor + 10);
+        const compressedSize = buffer.readUInt32LE(cursor + 20);
+        const nameLength = buffer.readUInt16LE(cursor + 28);
+        const extraLength = buffer.readUInt16LE(cursor + 30);
+        const commentLength = buffer.readUInt16LE(cursor + 32);
+        const localOffset = buffer.readUInt32LE(cursor + 42);
+        const name = buffer.subarray(cursor + 46, cursor + 46 + nameLength).toString("utf8");
+        // The local header carries its OWN name/extra lengths (they may differ
+        // from the central copies); the data starts right after them.
+        if (localOffset + 30 > buffer.length || buffer.readUInt32LE(localOffset) !== LOCAL_SIGNATURE)
+            throw new ZipFormatError(`local header for "${name}" is malformed`);
+        const localNameLength = buffer.readUInt16LE(localOffset + 26);
+        const localExtraLength = buffer.readUInt16LE(localOffset + 28);
+        const dataStart = localOffset + 30 + localNameLength + localExtraLength;
+        const data = buffer.subarray(dataStart, dataStart + compressedSize);
+        if (method === 0)
+            entries.set(name, Buffer.from(data));
+        else if (method === 8)
+            entries.set(name, inflateRawSync(data));
+        else
+            throw new ZipFormatError(`entry "${name}" uses unsupported compression method ${method}`);
+        cursor += 46 + nameLength + extraLength + commentLength;
+    }
+    return entries;
+}
+/** Build a stored-entry ZIP (method 0, UTF-8 names flagged via bit 11). */
+export function buildZip(files) {
+    const chunks = [];
+    const central = [];
+    let offset = 0;
+    for (const file of files) {
+        const nameBytes = Buffer.from(file.name, "utf8");
+        const crc = crc32(file.data);
+        const local = Buffer.alloc(30);
+        local.writeUInt32LE(LOCAL_SIGNATURE, 0);
+        local.writeUInt16LE(0x0800, 6); // UTF-8 name flag
+        local.writeUInt16LE(0, 8); // stored
+        local.writeUInt16LE(0, 10); // time
+        local.writeUInt16LE(0x2100, 12); // date (1996-01-01, deterministic)
+        local.writeUInt32LE(crc, 14);
+        local.writeUInt32LE(file.data.length, 18);
+        local.writeUInt32LE(file.data.length, 22);
+        local.writeUInt16LE(nameBytes.length, 26);
+        local.writeUInt16LE(0, 28);
+        chunks.push(local, nameBytes, file.data);
+        const entry = Buffer.alloc(46);
+        entry.writeUInt32LE(CENTRAL_SIGNATURE, 0);
+        entry.writeUInt16LE(0x031e, 4); // made by UNIX/ZIP 3.0
+        entry.writeUInt16LE(0x0014, 6); // extract by DOS/ZIP 2.0
+        entry.writeUInt16LE(0x0800, 8);
+        entry.writeUInt16LE(0, 10);
+        entry.writeUInt16LE(0, 12);
+        entry.writeUInt16LE(0x2100, 14);
+        entry.writeUInt32LE(crc, 16);
+        entry.writeUInt32LE(file.data.length, 20);
+        entry.writeUInt32LE(file.data.length, 24);
+        entry.writeUInt16LE(nameBytes.length, 28);
+        entry.writeUInt16LE(0, 30);
+        entry.writeUInt16LE(0, 32);
+        entry.writeUInt16LE(0, 34);
+        entry.writeUInt16LE(0, 36);
+        entry.writeUInt32LE(0, 38);
+        entry.writeUInt32LE(offset, 42);
+        central.push(entry, nameBytes);
+        offset += 30 + nameBytes.length + file.data.length;
+    }
+    const centralBuffer = Buffer.concat(central);
+    const eocd = Buffer.alloc(22);
+    eocd.writeUInt32LE(EOCD_SIGNATURE, 0);
+    eocd.writeUInt16LE(0, 4);
+    eocd.writeUInt16LE(0, 6);
+    eocd.writeUInt16LE(files.length, 8);
+    eocd.writeUInt16LE(files.length, 10);
+    eocd.writeUInt32LE(centralBuffer.length, 12);
+    eocd.writeUInt32LE(offset, 16);
+    eocd.writeUInt16LE(0, 20);
+    return Buffer.concat([...chunks, centralBuffer, eocd]);
+}
+/**
+ * Resolve an entry by BASENAME: the platform export compresses the staging
+ * DIRECTORY, so entries carry a `bizService-<uuid>/` prefix
+ * (live 2026-09-15: bizService-59d72d4a…/manifest.json).
+ */
+export function zipEntryByBasename(entries, basename) {
+    const direct = entries.get(basename);
+    if (direct !== undefined)
+        return direct;
+    const suffix = `/${basename}`;
+    for (const [name, data] of entries)
+        if (name.endsWith(suffix))
+            return data;
+    return undefined;
+}
+//# sourceMappingURL=zip.js.map

package/docs/tool-surface-map.md

@@ -0,0 +1,42 @@
+# Tool Surface ↔ Coverage Manifest Correspondence
+
+Baseline: `coverage/m1-coverage-manifest-v1.json` (39 items, M1, 8.6-only).
+Every `executable` and `partial` item maps to at least one tool below;
+`blocked` / `static-only` / `unsupported` items are hard boundaries —
+requesting them refuses with the manifest citation (red-team tested).
+
+Methodology (how to operate the tools) is read with `omc help <topic>` — see
+`skills/`. The tool surface is the "what"; those topics are the "how".
+
+| # | Manifest item (lane) | Status | Tools that carry it |
+|---|---|---|---|
+| 1 | W1-list-view | partial | `listview.create`, `listview.delete` (forced defaults, header readback, exact absence) |
+| 3 | W5-S26-aggregation | partial | `field.create` with formula/EXPRESSION scope (same-model AGGREGATION semantics documented in the manifest entry; no separate wire face was live-proven) |
+| 10 | W7-S29-greenfield | executable | `workflow.create`, `workflow.delete` |
+| 11 | W7-S29-residual-OQs | partial | surfaced by `coverage.manifest` + `get_status` (residual OQs are documented unknowns — no tool may claim past them) |
+| 12 | S25-rule-lifecycle | executable | `rule.enable`, `rule.disable`, `rule.delete` (invoke via enable + effect readback) |
+| 12a | B1-businessrule | executable | `rule.list` (latest runtime versions with full business-field projection; agent filters client-side) |
+| 13 | S32-business-integration | executable | `service.register`, `service.get`, `service.delete` (RESTFUL face) |
+| 15 | M2-runtime-data (data-entry projection) | partial | `data.load` (projection boundary: `form/load` authoritative) |
+| 15a | M2-runtime-data (query/list) | executable | `data.list` (simplified filters -> queryCondition, pagination, field projection) |
+| 21 | field-families | executable | `field.create`, `field.publish`, `field.delete`, `field.list` |
+| 22 | field-families (numeric-logical/date-time) | partial | same field tools, family types constrained to the proven set |
+| 23 | model-management | executable | `model.create`, `model.update` (app-tree NODE rename patch: bizSchemaCode/id/name/parentId required, modelType refused — fixed at create), `model.setSummary`, `model.delete`, `model.deleteMany` (publish aspect = model-scoped publication via `field.publish`/`form.publish`, exactly the proven ladder; no separate model-publish wire call exists) |
+| 24 | form-publish-chain | executable | `form.draft`, `form.publish`, `form.get` (draft-first, explicit publishedHtmlJson, control-level layout readback) |
+| 25 | B1-businessrule | executable | `rule.save` (dead-state + B1.2 CRUD/conditional node graphs) |
+| 26 | C-workflow-template | executable | `workflow.create` (minimal template lifecycle) |
+| 27 | online-js (composer) | executable | `onlinejs.compose` (platform skeleton preserved, canonical customScript element with array attrs, publish + SHA-256 readback). The design-time 在线开发 face (`/api/api/programming` JAVA source) is authored via 二开扩展包 and exposes no CLI tool |
+| 28 | M2-runtime-data (write/readback) | executable | `data.save`, `data.load`, `data.delete`, `data.list` |
+| 29 | B2-registration | executable | `service.register` (+ method), `service.get`, `service.delete` |
+| 30 | environment-governance | executable | `discover_environment`, `environment.fingerprint`, `doctor`, `get_status` |
+| 31 | e2e-delivery | executable | the governed chain itself: write tools (DELIVERED + artifact) → read tools (VERIFIED) → delete tools with exact-absence proof (CLEANED) |
+| 32 | app-management | executable | `app.list`, `app.create`, `app.delete` (design-time application package lifecycle; production writes permanently refused) |
+
+High-level orchestrations compose the same lanes under one token:
+`configure_model` (23+21+24), `configure_form` (24), `configure_rule`
+(25+12), `discover_environment` (30).
+
+Blocked/static-only/unsupported boundaries (no tools, enforced by refusal):
+W2-permissions, W5-S26-cross-model, W6-S27-* (nested child tables, relation
+linkage, child-to-child), W6-S28-*, S32-custom-extension, boundary-unsupported
+(inline backend coding, app publish/environment release, OCR/ELECTRONIC_SIGN).