target-supabase-sdk 0.1.9 → 0.2.1

package/dist/chunks/word.interface-DLgRobKV.js

@@ -0,0 +1,1973 @@
+import { B as BaseValidator, e as createTarget, E as validateWithSchema, d as createLogger, A as updateTargetDetails, g as generateResponse, f as deleteTarget, i as getTarget, y as scanTargetList, h as getPossibleTarget, j as getTargetList, o as isOptimisticLockError, c as OPTIMISTIC_LOCK_FAILED_MESSAGE, O as OPTIMISTIC_LOCK_ERROR_CODE, s as logManager } from './create-logger-DyH3mZ8p.js';
+import { z } from 'zod';
+
+var CategoryIdea;
+(function (CategoryIdea) {
+    CategoryIdea["OPPORTUNITY"] = "opportunity";
+})(CategoryIdea || (CategoryIdea = {}));
+var Market;
+(function (Market) {
+    Market["NA"] = "NA";
+    Market["EU"] = "EU";
+    Market["JP"] = "JP";
+    Market["CN"] = "CN";
+    Market["TW"] = "TW";
+})(Market || (Market = {}));
+
+class PostLinkValidator extends BaseValidator {
+    requiredFields = ["name", "value", "category", "details"];
+    optionalFields = [];
+    constructor() {
+        super();
+        // Add custom
+        this.addCustomValidator((_val) => {
+            return true;
+        });
+    }
+}
+const postLinkCreate = async (payload) => {
+    return createTarget({
+        payload: payload,
+        validator: PostLinkValidator,
+        createFn: (validPayload) => {
+            const { name, value, category, details } = validPayload;
+            return {
+                name,
+                category,
+                value,
+                tagList: [],
+                details,
+            };
+        },
+    });
+};
+
+var CategoryLink;
+(function (CategoryLink) {
+    CategoryLink["LINK"] = "link";
+})(CategoryLink || (CategoryLink = {}));
+
+var NodeStatus;
+(function (NodeStatus) {
+    /** Registered, not yet in worker loop. */
+    NodeStatus["READY"] = "READY";
+    /** Worker main loop is running (accepts tasks until shutdown). */
+    NodeStatus["BUSY"] = "BUSY";
+    /** Heartbeat lost or voluntarily offline; considered unavailable by the scheduler. */
+    NodeStatus["LOST"] = "LOST";
+    /** TODO Gracefully draining: not accepting new tasks, waiting for in-flight tasks to complete. */
+    NodeStatus["DRAINING"] = "DRAINING";
+    /** TODO Disabled by an administrator; excluded from scheduling. */
+    NodeStatus["DISABLED"] = "DISABLED";
+})(NodeStatus || (NodeStatus = {}));
+var CategoryNode;
+(function (CategoryNode) {
+    CategoryNode["NODE"] = "node";
+})(CategoryNode || (CategoryNode = {}));
+
+const NODE_STATUS_FIELD = "details->>status";
+const LOG_TOPIC_NODE = "node";
+const nodeIdSchema$1 = z.string().trim().min(1);
+const traceIdSchema$2 = z.string().trim().min(1).optional();
+// ─── Zod schemas ─────────────────────────────────────────────────────────────
+const postRegisterNodeSchema = z.object({
+    traceId: traceIdSchema$2,
+});
+const patchNodeHeartBeatSchema = z.object({
+    nodeId: nodeIdSchema$1,
+    traceId: traceIdSchema$2,
+});
+const patchStopNodeSchema = z.object({
+    nodeId: nodeIdSchema$1,
+    traceId: traceIdSchema$2,
+});
+const patchChangeNodeStatusSchema = z.object({
+    nodeId: nodeIdSchema$1,
+    status: z.nativeEnum(NodeStatus),
+    /** When set, UPDATE only if current status matches (optimistic lock). */
+    fromStatus: z.nativeEnum(NodeStatus).optional(),
+    traceId: traceIdSchema$2,
+});
+// ─── Optimistic lock helpers ─────────────────────────────────────────────────
+function lockOnNodeStatus(status) {
+    return [{ field: NODE_STATUS_FIELD, operator: "eq", value: status }];
+}
+// ─── postRegisterNode ────────────────────────────────────────────────────────
+const postRegisterNode = validateWithSchema(postRegisterNodeSchema, "postRegisterNodeSchema")(async (payload) => {
+    return createTarget({
+        payload,
+        createFn: () => {
+            const details = {
+                manifestVersion: 0,
+                status: NodeStatus.READY,
+                lastHeartBeat: Date.now(),
+            };
+            return {
+                name: "",
+                category: CategoryNode.NODE,
+                value: "",
+                tagList: [],
+                details,
+            };
+        },
+    });
+});
+// ─── patchNodeHeartBeat ──────────────────────────────────────────────────────
+const patchNodeHeartBeat = validateWithSchema(patchNodeHeartBeatSchema, "patchNodeHeartBeatSchema")(async ({ nodeId }) => {
+    const lastHeartBeat = Date.now();
+    await updateTargetDetails({
+        id: nodeId,
+        updateFn: (details) => ({
+            ...details,
+            lastHeartBeat,
+        }),
+    });
+    return generateResponse.success(lastHeartBeat);
+});
+// ─── patchStopNode ───────────────────────────────────────────────────────────
+const patchStopNode = validateWithSchema(patchStopNodeSchema, "patchStopNodeSchema")(async ({ nodeId }) => {
+    const lastHeartBeat = Date.now();
+    // TODO 等待任務全部完成才下綫 應該先使用NodeStatus.DRAINING
+    await updateTargetDetails({
+        id: nodeId,
+        updateFn: (details) => ({
+            ...details,
+            lastHeartBeat,
+            status: NodeStatus.LOST,
+        }),
+    });
+    return generateResponse.success(lastHeartBeat);
+});
+// ─── patchChangeNodeStatus ───────────────────────────────────────────────────
+const patchChangeNodeStatus = validateWithSchema(patchChangeNodeStatusSchema, "patchChangeNodeStatusSchema")(async ({ nodeId, status, fromStatus, traceId }) => {
+    const logger = createLogger({ module: "patchChangeNodeStatus", traceId, labels: { nodeId } });
+    const data = await updateTargetDetails({
+        id: nodeId,
+        optimisticLockFilterList: fromStatus != null ? lockOnNodeStatus(fromStatus) : [],
+        updateFn: (details) => ({
+            ...details,
+            status,
+            lastHeartBeat: Date.now(),
+        }),
+    });
+    logger.info("节点状态更新成功", {
+        topic: LOG_TOPIC_NODE,
+        data: {
+            nodeId,
+            status,
+            fromStatus,
+        },
+    });
+    return generateResponse.success(data);
+});
+
+function isBusyWithHeartbeat(node) {
+    return node.details.status === NodeStatus.BUSY && typeof node.details.lastHeartBeat === "number";
+}
+/** Evaluate TaskNode liveness from a scanned node list (no I/O). */
+function evaluateBusyNodeLiveness(nodes, options) {
+    const now = options.now ?? Date.now();
+    const { staleMs, excludeNodeId, onlyFreshCandidates = false } = options;
+    const candidates = nodes.filter((node) => (excludeNodeId == null || node.id !== excludeNodeId) && isBusyWithHeartbeat(node));
+    const busyWorkerCount = candidates.length;
+    const freshCandidates = candidates.filter((node) => now - node.details.lastHeartBeat < staleMs);
+    const freshWorkerCount = freshCandidates.length;
+    const pool = onlyFreshCandidates ? freshCandidates : candidates;
+    const freshestNode = pool.reduce((best, node) => {
+        if (best == null) {
+            return node;
+        }
+        return node.details.lastHeartBeat > best.details.lastHeartBeat ? node : best;
+    }, null);
+    const ageMs = freshestNode == null ? Number.POSITIVE_INFINITY : now - freshestNode.details.lastHeartBeat;
+    const healthy = onlyFreshCandidates ? freshestNode != null : freshestNode != null && ageMs < staleMs;
+    return {
+        healthy,
+        staleMs,
+        busyWorkerCount,
+        freshWorkerCount,
+        freshest: freshestNode == null
+            ? null
+            : {
+                nodeId: freshestNode.id,
+                status: freshestNode.details.status,
+                lastHeartBeat: new Date(freshestNode.details.lastHeartBeat).toISOString(),
+                ageMs,
+            },
+    };
+}
+
+function resolveFetchUrl(input) {
+    if (typeof input === "string") {
+        return input;
+    }
+    if (input instanceof URL) {
+        return input.href;
+    }
+    return input.url;
+}
+function isHttpUrl(url) {
+    return url.startsWith("http://") || url.startsWith("https://");
+}
+
+function isLocalFilesystemPath(url) {
+    if (url.startsWith("file://")) {
+        return true;
+    }
+    return /^[a-zA-Z]:[\\/]/.test(url) || url.startsWith("\\\\") || url.startsWith("/");
+}
+/** Opaque chunk locator - not HTTP and not a local path (e.g. Telegram file_id). */
+function isOpaqueChunkUrl(url) {
+    return !isHttpUrl(url) && !isLocalFilesystemPath(url);
+}
+/** `provider:opaque` scheme (e.g. `telegram:BQACAg...`). */
+function parseProviderPrefixedUrl(url) {
+    const match = /^([a-z][a-z0-9_-]*):(.+)$/i.exec(url);
+    if (match == null) {
+        return null;
+    }
+    const provider = match[1].toLowerCase();
+    const locator = match[2].trim();
+    if (locator === "") {
+        return null;
+    }
+    if (provider === "http" || provider === "https" || provider === "file") {
+        return null;
+    }
+    return { provider, locator };
+}
+
+const resolvers = new Map();
+function registerChunkResolver(resolver) {
+    resolvers.set(resolver.provider, resolver);
+}
+/** Register a provider's chunk resolver (call when the provider module loads). */
+function registerProviderChunkResolver(module) {
+    if (module.resolveChunk == null) {
+        return;
+    }
+    const resolveChunk = module.resolveChunk;
+    registerChunkResolver({
+        provider: module.provider,
+        matches(url) {
+            const prefixed = parseProviderPrefixedUrl(url);
+            if (prefixed != null) {
+                return prefixed.provider === module.provider;
+            }
+            return module.matchesOpaqueUrl?.(url) === true;
+        },
+        resolve(locator) {
+            const prefixed = parseProviderPrefixedUrl(locator);
+            const opaque = prefixed?.provider === module.provider ? prefixed.locator : locator;
+            return resolveChunk(opaque);
+        },
+    });
+}
+async function resolveOpaqueUrl(url) {
+    const prefixed = parseProviderPrefixedUrl(url);
+    if (prefixed != null) {
+        const resolver = resolvers.get(prefixed.provider);
+        if (resolver == null) {
+            throw new Error(`No chunk resolver registered for provider: ${prefixed.provider}`);
+        }
+        return resolver.resolve(prefixed.locator);
+    }
+    const matches = [...resolvers.values()].filter((entry) => entry.matches(url));
+    if (matches.length === 1) {
+        return matches[0].resolve(url);
+    }
+    if (matches.length > 1) {
+        throw new Error(`Ambiguous chunk url (${url}); use provider-prefixed form e.g. telegram:${url.slice(0, 12)}…`);
+    }
+    const registered = [...resolvers.keys()].join(", ") || "(none)";
+    throw new Error(`No chunk resolver for opaque url (${url.slice(0, 24)}…). Registered: ${registered}`);
+}
+/**
+ * Patch global fetch so ParcelManager.reassemble can resolve opaque chunk locators.
+ * HTTP URLs use the original fetch (S3 presigned, etc.).
+ */
+function installChunkFetchRegistry() {
+    const originalFetch = globalThis.fetch.bind(globalThis);
+    globalThis.fetch = (async (input, init) => {
+        const url = resolveFetchUrl(input);
+        if (isHttpUrl(url)) {
+            return originalFetch(input, init);
+        }
+        if (isLocalFilesystemPath(url)) {
+            throw new Error(`Chunk fetch registry: local path not supported (${url}). ` +
+                "Use a local provider module or parcel-restore-local.");
+        }
+        const buffer = await resolveOpaqueUrl(url);
+        return new Response(buffer, { headers: { "Content-Type": "application/octet-stream" } });
+    });
+    return () => {
+        globalThis.fetch = originalFetch;
+    };
+}
+
+var CategoryParcel;
+(function (CategoryParcel) {
+    CategoryParcel["PARCEL"] = "parcel";
+})(CategoryParcel || (CategoryParcel = {}));
+var LifecycleStatus;
+(function (LifecycleStatus) {
+    LifecycleStatus["STORED"] = "STORED";
+    LifecycleStatus["SOFT_DELETED"] = "SOFT_DELETED";
+    LifecycleStatus["HARD_DELETED"] = "HARD_DELETED";
+})(LifecycleStatus || (LifecycleStatus = {}));
+
+const parcelIdSchema = z.string().trim().min(1);
+const chunkSchema = z.object({
+    index: z.number().int().nonnegative(),
+    size: z.number().int().nonnegative(),
+    checksum: z.string().trim().min(1),
+    url: z.string().trim().min(1),
+    provider: z.string().optional(),
+});
+const parcelCryptoSchema = z.object({
+    enabled: z.boolean(),
+    algorithm: z.string().optional(),
+    iv: z.string().optional(),
+    keyDerivation: z.string().optional(),
+    salt: z.string().optional(),
+    pbkdf2Iterations: z.number().int().positive().optional(),
+});
+const parcelDetailsSchema = z.object({
+    manifestVersion: z.number().int().nonnegative(),
+    chunkList: z.array(chunkSchema).min(1),
+    checksum: z.string().trim().min(1),
+    size: z.number().int().nonnegative(),
+    preview: z.string().optional(),
+    crypto: parcelCryptoSchema.optional(),
+});
+const postParcelSchema = z.object({
+    name: z.string().trim().min(1),
+    value: z.string().trim().min(1),
+    details: parcelDetailsSchema,
+    tagList: z.array(z.string()).optional().default([]),
+    extra: z.string().optional(),
+});
+const getParcelSchema = z.object({
+    id: parcelIdSchema,
+});
+const deleteParcelSchema = z.object({
+    id: parcelIdSchema,
+});
+const parcelCategoryFilter = {
+    field: "category",
+    operator: "eq",
+    value: CategoryParcel.PARCEL,
+};
+/** Persist a Parcel row (`category=parcel`) after chunks are uploaded via {@link ParcelManager.save}. */
+const postParcel = validateWithSchema(postParcelSchema, "postParcelSchema")(async ({ name, value, details, tagList, extra }) => {
+    return createTarget({
+        payload: { name, value, details, tagList, extra },
+        createFn: () => ({
+            name,
+            value,
+            category: CategoryParcel.PARCEL,
+            tagList,
+            extra,
+            details: details,
+        }),
+    });
+});
+/** Fetch a Parcel by id (`category=parcel`). */
+const getParcel = validateWithSchema(getParcelSchema, "getParcelSchema")(async ({ id }) => {
+    const result = await getTarget({
+        id,
+        filterList: [parcelCategoryFilter],
+    });
+    return {
+        ...result,
+        data: result.data,
+    };
+});
+/** Delete a Parcel row by id (`category=parcel`). Does not remove chunk blobs from storage providers. */
+const deleteParcel = validateWithSchema(deleteParcelSchema, "deleteParcelSchema")(async ({ id }) => {
+    return deleteTarget({
+        id,
+        filterList: [parcelCategoryFilter],
+    });
+});
+
+function getCrypto$1() {
+    if (typeof globalThis !== "undefined" && globalThis.crypto) {
+        return globalThis.crypto;
+    }
+    throw new Error("sha256Hex: crypto.subtle not available");
+}
+/** SHA-256 digest as lowercase hex (browser + Node Web Crypto). */
+async function sha256Hex(buffer) {
+    const crypto = getCrypto$1();
+    const hash = await crypto.subtle.digest("SHA-256", buffer);
+    return Array.from(new Uint8Array(hash))
+        .map((byte) => byte.toString(16).padStart(2, "0"))
+        .join("");
+}
+
+const MANIFEST_VERSION = 1;
+const DEFAULT_CHUNK_SIZE = 2 * 1024 * 1024; // 2MB - fallback for empty input only
+const MB = 1024 * 1024;
+/** Source files at or below this size use at most 2 chunks */
+const SMALL_FILE_MAX_BYTES = 50 * MB;
+/** Target per-chunk size for larger files */
+const PREFERRED_CHUNK_BYTES = 16 * MB;
+/** Cap chunk count for very large files */
+const MAX_CHUNK_COUNT = 64;
+const AES_GCM_ALGORITHM = "AES-GCM-256";
+const KEY_DERIVATION_PBKDF2 = "PBKDF2-SHA256";
+const PBKDF2_ITERATIONS = 100_000;
+const AES_GCM_IV_LENGTH = 12;
+const AES_GCM_TAG_LENGTH = 128;
+/** Auth tag bytes Web Crypto appends to AES-GCM ciphertext */
+const AES_GCM_AUTH_TAG_BYTES = AES_GCM_TAG_LENGTH / 8;
+/** @deprecated Legacy IV in Target.extra - read only for old parcels */
+const LEGACY_EXTRA_IV_KEY = "iv";
+function getCrypto() {
+    if (typeof globalThis !== "undefined" && globalThis.crypto)
+        return globalThis.crypto;
+    throw new Error("ParcelManager: crypto not available");
+}
+function bytesToBase64(bytes) {
+    return btoa(String.fromCharCode(...bytes));
+}
+function base64ToBytes(base64) {
+    return Uint8Array.from(atob(base64), (c) => c.charCodeAt(0));
+}
+async function encrypt(data, key, iv) {
+    const crypto = getCrypto();
+    return crypto.subtle.encrypt({ name: "AES-GCM", iv: new Uint8Array(iv), tagLength: AES_GCM_TAG_LENGTH }, key, data);
+}
+async function decrypt(data, key, iv) {
+    const crypto = getCrypto();
+    return crypto.subtle.decrypt({ name: "AES-GCM", iv: new Uint8Array(iv), tagLength: AES_GCM_TAG_LENGTH }, key, data);
+}
+function isDecryptAuthFailure(error) {
+    if (error instanceof DOMException && error.name === "OperationError") {
+        return true;
+    }
+    if (error instanceof Error) {
+        return /operation failed|operation-specific|decrypt|OperationError/i.test(error.message);
+    }
+    return false;
+}
+async function decryptPayload(data, key, iv, usedPassphrase) {
+    try {
+        return await decrypt(data, key, iv);
+    }
+    catch (error) {
+        if (isDecryptAuthFailure(error)) {
+            throw new Error(usedPassphrase
+                ? "ParcelManager.reassemble: 解密失败，口令错误或密文已损坏"
+                : "ParcelManager.reassemble: 解密失败，密钥错误或密文已损坏");
+        }
+        throw error;
+    }
+}
+async function generateKey() {
+    const crypto = getCrypto();
+    return crypto.subtle.generateKey({ name: "AES-GCM", length: 256 }, true, ["encrypt", "decrypt"]);
+}
+async function deriveKeyFromPassphrase(passphrase, salt, iterations) {
+    const crypto = getCrypto();
+    const keyMaterial = await crypto.subtle.importKey("raw", new TextEncoder().encode(passphrase), "PBKDF2", false, [
+        "deriveKey",
+    ]);
+    return crypto.subtle.deriveKey({
+        name: "PBKDF2",
+        salt: new Uint8Array(salt),
+        iterations,
+        hash: "SHA-256",
+    }, keyMaterial, { name: "AES-GCM", length: 256 }, false, ["encrypt", "decrypt"]);
+}
+function usesPassphraseDerivation(crypto) {
+    return crypto.keyDerivation === KEY_DERIVATION_PBKDF2;
+}
+async function resolveDecryptionKey(crypto, options) {
+    if (usesPassphraseDerivation(crypto)) {
+        if (options.passphrase == null || options.passphrase === "") {
+            throw new Error("ParcelManager.reassemble: 口令加密 Parcel 需要提供 passphrase");
+        }
+        if (crypto.salt == null || crypto.salt === "") {
+            throw new Error("ParcelManager.reassemble: 缺少 details.crypto.salt");
+        }
+        const iterations = crypto.pbkdf2Iterations ?? PBKDF2_ITERATIONS;
+        const salt = base64ToBytes(crypto.salt);
+        return deriveKeyFromPassphrase(options.passphrase, salt, iterations);
+    }
+    if (options.key != null) {
+        return options.key;
+    }
+    throw new Error("ParcelManager.reassemble: 加密 Parcel 需要提供 key");
+}
+async function buildChunkList(payload, chunkSize) {
+    const chunks = [];
+    const chunkList = [];
+    let offset = 0;
+    let index = 0;
+    while (offset < payload.byteLength) {
+        const end = Math.min(offset + chunkSize, payload.byteLength);
+        const chunkBuffer = payload.slice(offset, end);
+        const checksum = await sha256Hex(chunkBuffer);
+        chunks.push(chunkBuffer);
+        chunkList.push({
+            index,
+            size: chunkBuffer.byteLength,
+            checksum,
+            url: "",
+        });
+        offset = end;
+        index += 1;
+    }
+    return { chunks, chunkList };
+}
+/**
+ * Derive per-chunk byte size from the buffer that will be split.
+ *
+ * | Payload size | Policy |
+ * |--------------|--------|
+ * | ≤50 MB | At most **2** chunks (`ceil(size / 2)` per chunk) |
+ * | > 50 MB | Target ~16 MB per chunk; chunk count capped at **64** |
+ *
+ * For encrypted parcels, pass plaintext size + {@link AES_GCM_AUTH_TAG_BYTES}
+ * (GCM auth tag is appended before split).
+ *
+ * Explicit `chunkSize` in {@link CreateOptions} overrides this table.
+ */
+function resolveChunkSize(fileSize, override) {
+    if (override != null) {
+        if (!Number.isFinite(override) || override <= 0) {
+            throw new Error("ParcelManager.create: chunkSize must be a positive number");
+        }
+        return override;
+    }
+    if (fileSize <= 0) {
+        return DEFAULT_CHUNK_SIZE;
+    }
+    if (fileSize <= SMALL_FILE_MAX_BYTES) {
+        return Math.ceil(fileSize / 2);
+    }
+    const targetChunks = Math.min(MAX_CHUNK_COUNT, Math.max(2, Math.ceil(fileSize / PREFERRED_CHUNK_BYTES)));
+    return Math.ceil(fileSize / targetChunks);
+}
+function concatBuffers(buffers) {
+    const total = buffers.reduce((sum, buffer) => sum + buffer.byteLength, 0);
+    const merged = new Uint8Array(total);
+    let offset = 0;
+    for (const buffer of buffers) {
+        merged.set(new Uint8Array(buffer), offset);
+        offset += buffer.byteLength;
+    }
+    return merged.buffer;
+}
+function isEncryptionEnabled(details, parcelExtra) {
+    if (details.crypto != null) {
+        return details.crypto.enabled === true;
+    }
+    if (parcelExtra == null || parcelExtra.trim() === "") {
+        return false;
+    }
+    try {
+        const legacy = JSON.parse(parcelExtra);
+        return typeof legacy[LEGACY_EXTRA_IV_KEY] === "string";
+    }
+    catch {
+        return false;
+    }
+}
+function resolveCrypto(details, parcelExtra) {
+    if (details.crypto?.enabled === true) {
+        return details.crypto;
+    }
+    if (parcelExtra == null || parcelExtra.trim() === "") {
+        return null;
+    }
+    try {
+        const legacy = JSON.parse(parcelExtra);
+        const iv = legacy[LEGACY_EXTRA_IV_KEY];
+        if (typeof iv !== "string" || iv === "") {
+            return null;
+        }
+        return { enabled: true, algorithm: AES_GCM_ALGORITHM, iv };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Split a file into chunks. Default: plaintext shards; optional whole-file AES-GCM before split.
+ */
+async function create(file, options = {}) {
+    const encryptEnabled = options.encrypt === true;
+    const splitPayloadSize = encryptEnabled ? file.byteLength + AES_GCM_AUTH_TAG_BYTES : file.byteLength;
+    const chunkSize = resolveChunkSize(splitPayloadSize, options.chunkSize);
+    const plaintextChecksum = await sha256Hex(file);
+    if (!encryptEnabled) {
+        const { chunks, chunkList } = await buildChunkList(file, chunkSize);
+        return {
+            details: {
+                manifestVersion: MANIFEST_VERSION,
+                chunkList,
+                checksum: plaintextChecksum,
+                size: file.byteLength,
+            },
+            chunks,
+        };
+    }
+    if (options.passphrase != null && options.key != null) {
+        throw new Error("ParcelManager.create: passphrase 与 key 不能同時指定");
+    }
+    const cryptoApi = getCrypto();
+    const iv = cryptoApi.getRandomValues(new Uint8Array(AES_GCM_IV_LENGTH));
+    let key;
+    let generatedKey = false;
+    let cryptoMeta;
+    if (options.passphrase != null && options.passphrase !== "") {
+        const salt = cryptoApi.getRandomValues(new Uint8Array(16));
+        key = await deriveKeyFromPassphrase(options.passphrase, salt, PBKDF2_ITERATIONS);
+        cryptoMeta = {
+            enabled: true,
+            algorithm: AES_GCM_ALGORITHM,
+            iv: bytesToBase64(iv),
+            keyDerivation: KEY_DERIVATION_PBKDF2,
+            salt: bytesToBase64(salt),
+            pbkdf2Iterations: PBKDF2_ITERATIONS,
+        };
+    }
+    else if (options.key != null) {
+        key = options.key;
+        cryptoMeta = {
+            enabled: true,
+            algorithm: AES_GCM_ALGORITHM,
+            iv: bytesToBase64(iv),
+        };
+    }
+    else {
+        key = await generateKey();
+        generatedKey = true;
+        cryptoMeta = {
+            enabled: true,
+            algorithm: AES_GCM_ALGORITHM,
+            iv: bytesToBase64(iv),
+        };
+    }
+    const encrypted = await encrypt(file, key, iv);
+    const { chunks, chunkList } = await buildChunkList(encrypted, chunkSize);
+    const result = {
+        details: {
+            manifestVersion: MANIFEST_VERSION,
+            chunkList,
+            checksum: plaintextChecksum,
+            size: file.byteLength,
+            crypto: cryptoMeta,
+        },
+        chunks,
+    };
+    if (generatedKey) {
+        result.key = key;
+    }
+    return result;
+}
+/** Upload chunks round-robin across storage adapters */
+async function save(createResult, fileSystems, input) {
+    if (fileSystems.length === 0) {
+        throw new Error("ParcelManager.save: fileSystems 不能为空");
+    }
+    const { details, chunks } = createResult;
+    const chunkListWithUrls = [];
+    for (let i = 0; i < chunks.length; i++) {
+        const adapter = fileSystems[i % fileSystems.length];
+        const pathOrKey = `chunk-${i}-${details.checksum.slice(0, 8)}`;
+        const { url } = await adapter.upload(chunks[i], pathOrKey);
+        chunkListWithUrls.push({
+            ...details.chunkList[i],
+            url,
+            provider: adapter.provider,
+        });
+    }
+    return {
+        name: input.name,
+        value: input.value,
+        tagList: input.tagList ?? [],
+        category: CategoryParcel.PARCEL,
+        details: {
+            ...details,
+            chunkList: chunkListWithUrls,
+        },
+    };
+}
+async function downloadAndVerifyChunks(chunkList) {
+    const sortedChunks = [...chunkList].sort((a, b) => a.index - b.index);
+    const buffers = [];
+    for (const chunkMeta of sortedChunks) {
+        const res = await fetch(chunkMeta.url);
+        if (!res.ok) {
+            throw new Error(`ParcelManager.reassemble: 下载 chunk ${chunkMeta.index} 失败: ${res.status}`);
+        }
+        const chunkBuffer = await res.arrayBuffer();
+        const chunkChecksum = await sha256Hex(chunkBuffer);
+        if (chunkChecksum !== chunkMeta.checksum) {
+            throw new Error(`ParcelManager.reassemble: chunk ${chunkMeta.index} 校验失败 (checksum 不一致`);
+        }
+        buffers.push(chunkBuffer);
+    }
+    return buffers;
+}
+function verifyPlaintextSize(buffer, details) {
+    if (buffer.byteLength !== details.size) {
+        throw new Error(`ParcelManager.reassemble: 重组后大小与 details.size 不一致(${buffer.byteLength} !== ${details.size})`);
+    }
+}
+/**
+ * Fetch chunks from {@link Parcel.details.chunkList}, reassemble, optionally decrypt, verify checksum.
+ * Encrypted parcels: pass `{ passphrase }` for PBKDF2 parcels, or `{ key }` for raw-key parcels.
+ */
+async function reassemble(parcel, options = {}) {
+    const { details } = parcel;
+    const encrypted = isEncryptionEnabled(details, parcel.extra);
+    const buffers = await downloadAndVerifyChunks(details.chunkList);
+    const merged = concatBuffers(buffers);
+    if (!encrypted) {
+        verifyPlaintextSize(merged, details);
+        const fileChecksum = await sha256Hex(merged);
+        if (fileChecksum !== details.checksum) {
+            throw new Error("ParcelManager.reassemble: 重组后文件校验失败 (sha256 与 details.checksum 不一致)");
+        }
+        return merged;
+    }
+    const cryptoMeta = resolveCrypto(details, parcel.extra);
+    if (cryptoMeta?.iv == null || cryptoMeta.iv === "") {
+        throw new Error("ParcelManager.reassemble: 加密 Parcel 缺少 details.crypto.iv");
+    }
+    const iv = base64ToBytes(cryptoMeta.iv);
+    if (iv.length !== AES_GCM_IV_LENGTH) {
+        throw new Error("ParcelManager.reassemble: IV 长度无效");
+    }
+    const key = await resolveDecryptionKey(cryptoMeta, options);
+    const usedPassphrase = usesPassphraseDerivation(cryptoMeta);
+    const decrypted = await decryptPayload(merged, key, iv, usedPassphrase);
+    verifyPlaintextSize(decrypted, details);
+    const fileChecksum = await sha256Hex(decrypted);
+    if (fileChecksum !== details.checksum) {
+        throw new Error(usedPassphrase
+            ? "ParcelManager.reassemble: 解密后校验失败，口令错误或数据已损坏"
+            : "ParcelManager.reassemble: 解密后文件校验失败 (sha256 与 details.checksum 不一致)");
+    }
+    return decrypted;
+}
+const ParcelManager = {
+    create,
+    save,
+    reassemble,
+};
+
+function requireResponseData(response, label) {
+    if (response.data == null) {
+        const suffix = response.message != null ? ` (${response.message})` : "";
+        throw new Error(`${label}: no data${suffix}`);
+    }
+    return response.data;
+}
+/**
+ * One-shot publish: split (optional encrypt) → upload chunks → persist Parcel row.
+ * Orchestrates {@link ParcelManager} + {@link postParcel}.
+ */
+async function publishParcel(input) {
+    const { file, adapters, name, value, tagList = [], extra, createOptions } = input;
+    const createResult = await ParcelManager.create(file, createOptions ?? {});
+    const draft = await ParcelManager.save(createResult, adapters, { name, value, tagList });
+    const response = await postParcel({
+        name: draft.name,
+        value: draft.value,
+        details: draft.details,
+        tagList: draft.tagList ?? [],
+        extra,
+    });
+    return {
+        parcel: requireResponseData(response, "postParcel"),
+        key: createResult.key,
+    };
+}
+/**
+ * Reassemble file bytes from a {@link Parcel} (chunk URLs in details).
+ */
+async function restoreParcel(parcel, reassembleOptions) {
+    return ParcelManager.reassemble(parcel, reassembleOptions ?? {});
+}
+/**
+ * Fetch Parcel by id, then reassemble. Orchestrates {@link getParcel} + {@link restoreParcel}.
+ */
+async function restoreParcelById(input) {
+    const response = await getParcel({ id: input.id });
+    const parcel = requireResponseData(response, "getParcel");
+    const file = await restoreParcel(parcel, input.reassembleOptions);
+    return { parcel, file };
+}
+
+function createUploadTracker() {
+    const handles = [];
+    return {
+        handles,
+        push(handle) {
+            handles.push(handle);
+        },
+    };
+}
+
+/** In-process registry for {@link StorageProviderModule}; syncs chunk resolvers on register. */
+function createStorageProviderRegistry() {
+    const modules = new Map();
+    return {
+        register(module) {
+            modules.set(module.provider, module);
+            registerProviderChunkResolver(module);
+        },
+        get(provider) {
+            const found = modules.get(provider);
+            if (found == null) {
+                const available = [...modules.keys()].join(", ") || "(none)";
+                throw new Error(`Unknown storage provider: ${provider}. Registered: ${available}`);
+            }
+            return found;
+        },
+        has(provider) {
+            return modules.has(provider);
+        },
+        list() {
+            return [...modules.keys()];
+        },
+        async probeAll() {
+            const out = {};
+            for (const [name, module] of modules) {
+                if (module.probe == null) {
+                    out[name] = { ok: true, detail: { skipped: true } };
+                    continue;
+                }
+                out[name] = await module.probe();
+            }
+            return out;
+        },
+    };
+}
+
+var CategoryRepo;
+(function (CategoryRepo) {
+    /** Project */
+    CategoryRepo["REPO"] = "repo";
+})(CategoryRepo || (CategoryRepo = {}));
+/** `Repo.details.usage` for task worker remote discovery ({@link registerTasks}). */
+const TASK_REPO_USAGE = "task";
+
+const REPO_USAGE_FIELD = "details->>usage";
+const getScanRemoteRepoValuesSchema = z.object({
+    usage: z.string().trim().min(1),
+});
+/**
+ * Scan `Repo.value` keys for `category=repo` with matching `details.usage`.
+ * Returns `{ data: string[] }` on success; validation and DB failures use `{ error }` (never throws).
+ */
+const getScanRemoteRepoValues = async (payload) => {
+    try {
+        return await getScanRemoteRepoValuesValidated(payload);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return generateResponse.error(message);
+    }
+};
+const getScanRemoteRepoValuesValidated = validateWithSchema(getScanRemoteRepoValuesSchema, "getScanRemoteRepoValuesSchema")(async ({ usage }) => {
+    try {
+        const { data } = await scanTargetList({
+            category: CategoryRepo.REPO,
+            selectFields: "value",
+            orderBy: { field: "value", ascending: true },
+            filterList: [{ field: REPO_USAGE_FIELD, operator: "eq", value: usage }],
+        });
+        const values = (data ?? [])
+            .map((row) => row.value?.trim())
+            .filter((value) => value != null && value !== "");
+        return generateResponse.success([...new Set(values)]);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return generateResponse.error(message);
+    }
+});
+
+var ServiceLifecycleStatus;
+(function (ServiceLifecycleStatus) {
+    ServiceLifecycleStatus["ACTIVE"] = "ACTIVE";
+    ServiceLifecycleStatus["DEPRECATED"] = "DEPRECATED";
+    ServiceLifecycleStatus["SUNSET"] = "SUNSET";
+})(ServiceLifecycleStatus || (ServiceLifecycleStatus = {}));
+
+var CategoryService;
+(function (CategoryService) {
+    CategoryService["SERVICE"] = "service";
+})(CategoryService || (CategoryService = {}));
+var CategoryApi;
+(function (CategoryApi) {
+    CategoryApi["API"] = "api";
+})(CategoryApi || (CategoryApi = {}));
+var ApiMethod;
+(function (ApiMethod) {
+    ApiMethod["POST"] = "POST";
+    ApiMethod["GET"] = "GET";
+    ApiMethod["PUT"] = "PUT";
+    ApiMethod["DELETE"] = "DELETE";
+})(ApiMethod || (ApiMethod = {}));
+
+const targetIdSchema = z.string().trim().min(1);
+const enumMemberSchema = z.object({
+    key: z.string().trim().min(1),
+    value: z.string(),
+});
+const fieldPresenceSchema = z.object({
+    nullable: z.boolean(),
+    optional: z.boolean(),
+});
+const schemaDefinitionSchema = z.lazy(() => z.discriminatedUnion("type", [
+    fieldPresenceSchema.extend({
+        type: z.literal("string"),
+        min: z.number().optional(),
+        max: z.number().optional(),
+        regex: z.string().optional(),
+        default: z.string().optional(),
+    }),
+    fieldPresenceSchema.extend({
+        type: z.literal("number"),
+        min: z.number().optional(),
+        max: z.number().optional(),
+        default: z.number().optional(),
+    }),
+    fieldPresenceSchema.extend({
+        type: z.literal("boolean"),
+        default: z.boolean().optional(),
+    }),
+    fieldPresenceSchema.extend({
+        type: z.literal("unknown"),
+        default: z.unknown().optional(),
+    }),
+    fieldPresenceSchema.extend({
+        type: z.literal("enum"),
+        members: z.array(enumMemberSchema).min(1),
+        defaultKey: z.string().trim().min(1).optional(),
+    }),
+    fieldPresenceSchema.extend({
+        type: z.literal("object"),
+        fields: z.array(fieldDefinitionSchema),
+        default: z.record(z.unknown()).optional(),
+    }),
+    fieldPresenceSchema.extend({
+        type: z.literal("array"),
+        items: schemaDefinitionSchema,
+        min: z.number().int().nonnegative().optional(),
+        max: z.number().int().nonnegative().optional(),
+        default: z.unknown().optional(),
+    }),
+]));
+const fieldDefinitionSchema = z.intersection(z.object({ fieldName: z.string().trim().min(1) }), schemaDefinitionSchema);
+const serviceLifecycleSchema = z.object({
+    status: z.nativeEnum(ServiceLifecycleStatus),
+    activeSince: z.string().trim().min(1),
+    deprecatedAt: z.string().nullable(),
+    sunsetAt: z.string().nullable(),
+});
+const apiDetailsSchema = z.object({
+    method: z.nativeEnum(ApiMethod),
+    path: z.string().trim().min(1),
+    endpoint: z.string().trim().min(1),
+    request: z.object({
+        query: z.array(fieldDefinitionSchema),
+    }),
+    response: z.object({
+        "200": z.array(fieldDefinitionSchema),
+    }),
+    manifestVersion: z.number().int().nonnegative(),
+    lifecycle: serviceLifecycleSchema,
+});
+const serviceDetailsSchema = z.object({
+    manifestVersion: z.number().int().nonnegative(),
+    apiKeys: z.array(z.string().trim().min(1)),
+    dependencies: z.array(z.string().trim().min(1)).default([]),
+    lifecycle: serviceLifecycleSchema,
+});
+const postApiSchema = z.object({
+    name: z.string().trim().min(1),
+    value: z.string().trim().min(1),
+    details: apiDetailsSchema,
+    tagList: z.array(z.string()).optional().default([]),
+    extra: z.string().optional(),
+});
+const getApiSchema = z
+    .object({
+    id: targetIdSchema.optional(),
+    value: z.string().trim().min(1).optional(),
+})
+    .refine((payload) => {
+    const hasId = payload.id != null && payload.id !== "";
+    const hasValue = payload.value != null && payload.value !== "";
+    return hasId !== hasValue;
+}, { message: "Provide exactly one of id or value" });
+const getServiceSchema = z
+    .object({
+    id: targetIdSchema.optional(),
+    value: z.string().trim().min(1).optional(),
+    /** When set, filters `details.lifecycle.status` at query time. */
+    lifecycleStatus: z.nativeEnum(ServiceLifecycleStatus).optional(),
+})
+    .refine((payload) => {
+    const hasId = payload.id != null && payload.id !== "";
+    const hasValue = payload.value != null && payload.value !== "";
+    return hasId !== hasValue;
+}, { message: "Provide exactly one of id or value" });
+const postServiceSchema = z.object({
+    name: z.string().trim().min(1),
+    value: z.string().trim().min(1),
+    details: serviceDetailsSchema,
+    tagList: z.array(z.string()).optional().default([]),
+    extra: z.string().optional(),
+});
+const apiCategoryFilter = {
+    field: "category",
+    operator: "eq",
+    value: CategoryApi.API,
+};
+const serviceCategoryFilter = {
+    field: "category",
+    operator: "eq",
+    value: CategoryService.SERVICE,
+};
+const SERVICE_LIFECYCLE_STATUS_FIELD$1 = "details->lifecycle->>status";
+function buildServiceLookupFilters(payload) {
+    const filters = [serviceCategoryFilter];
+    if (payload.id != null && payload.id !== "") ;
+    else {
+        filters.push({ field: "value", operator: "eq", value: payload.value });
+    }
+    if (payload.lifecycleStatus != null) {
+        filters.push({
+            field: SERVICE_LIFECYCLE_STATUS_FIELD$1,
+            operator: "eq",
+            value: payload.lifecycleStatus,
+        });
+    }
+    return filters;
+}
+/** Register an Api contract row (`category=api`). */
+const postApi = validateWithSchema(postApiSchema, "postApiSchema")(async ({ name, value, details, tagList, extra }) => {
+    return createTarget({
+        payload: { name, value, details, tagList, extra },
+        createFn: () => ({
+            name,
+            value,
+            category: CategoryApi.API,
+            tagList,
+            extra,
+            details: details,
+        }),
+    });
+});
+/** Fetch an Api by id or by {@link Api.value} key (`category=api`). */
+const getApi = validateWithSchema(getApiSchema, "getApiSchema")(async (payload) => {
+    if (payload.id != null && payload.id !== "") {
+        const result = await getTarget({
+            id: payload.id,
+            filterList: [apiCategoryFilter],
+        });
+        return {
+            ...result,
+            data: result.data,
+        };
+    }
+    const result = await getPossibleTarget({
+        filterList: [apiCategoryFilter, { field: "value", operator: "eq", value: payload.value }],
+    });
+    if (result.data == null) {
+        return {
+            ...result,
+            data: undefined,
+        };
+    }
+    return {
+        ...result,
+        data: result.data,
+    };
+});
+/** Fetch a Service by id or by {@link Service.value} key (`category=service`). */
+const getService = validateWithSchema(getServiceSchema, "getServiceSchema")(async (payload) => {
+    const filterList = buildServiceLookupFilters(payload);
+    if (payload.id != null && payload.id !== "") {
+        const result = await getTarget({
+            id: payload.id,
+            filterList,
+        });
+        return {
+            ...result,
+            data: result.data,
+        };
+    }
+    const result = await getPossibleTarget({
+        filterList,
+    });
+    if (result.data == null) {
+        return {
+            ...result,
+            data: undefined,
+        };
+    }
+    return {
+        ...result,
+        data: result.data,
+    };
+});
+/** Register a Service catalog row (`category=service`). */
+const postService = validateWithSchema(postServiceSchema, "postServiceSchema")(async ({ name, value, details, tagList, extra }) => {
+    return createTarget({
+        payload: { name, value, details, tagList, extra },
+        createFn: () => ({
+            name,
+            value,
+            category: CategoryService.SERVICE,
+            tagList,
+            extra,
+            details: details,
+        }),
+    });
+});
+
+const DISCOVER_LIFECYCLE_STATUS = ServiceLifecycleStatus.ACTIVE;
+const SERVICE_LIFECYCLE_STATUS_FIELD = "details->lifecycle->>status";
+async function lookupServicePrimary(value) {
+    const response = await getService({ value, lifecycleStatus: DISCOVER_LIFECYCLE_STATUS });
+    return response.data ?? null;
+}
+async function lookupServiceByScan(value) {
+    const { data } = await scanTargetList({
+        category: CategoryService.SERVICE,
+        orderBy: { field: "value", ascending: true },
+        maxRows: 1,
+        filterList: [
+            { field: "value", operator: "eq", value },
+            {
+                field: SERVICE_LIFECYCLE_STATUS_FIELD,
+                operator: "eq",
+                value: DISCOVER_LIFECYCLE_STATUS,
+            },
+        ],
+    });
+    return data?.[0] ?? null;
+}
+async function resolveDiscoverFailureReason(value) {
+    const response = await getService({ value });
+    if (response.data == null) {
+        return "not-found";
+    }
+    return "not-available";
+}
+/**
+ * Discover a single service by {@link Service.value}.
+ * Only returns services with `lifecycle.status === ACTIVE` (filtered at query time).
+ *
+ * Lookup: primary `getService` → fallback `scanTargetList` by value.
+ */
+async function discoverService(input) {
+    const value = input.value.trim();
+    const logger = createLogger({
+        module: "discoverService",
+        traceId: input.traceId,
+        labels: { serviceValue: value },
+    });
+    if (value === "") {
+        const message = "discoverService: value must not be empty";
+        logger.warn(message, { topic: "service", data: { value: input.value } });
+        return generateResponse.error(message, undefined, "SERVICE_VALUE_REQUIRED");
+    }
+    try {
+        logger.info("开始发现服务", {
+            topic: "service",
+            data: { value, lifecycleStatus: DISCOVER_LIFECYCLE_STATUS },
+        });
+        let service = await lookupServicePrimary(value);
+        let source = "primary";
+        if (service == null) {
+            logger.warn("主路径未命中，尝试 catalog 扫描回退", {
+                topic: "service",
+                data: { value, step: "scan-fallback", lifecycleStatus: DISCOVER_LIFECYCLE_STATUS },
+            });
+            service = await lookupServiceByScan(value);
+            source = "scan";
+        }
+        if (service == null) {
+            const reason = await resolveDiscoverFailureReason(value);
+            if (reason === "not-available") {
+                const message = `Service ${value} is not available (lifecycle is not ACTIVE)`;
+                logger.warn("服务已注册但不可用", {
+                    topic: "service",
+                    data: { value, step: "not-available", lifecycleStatus: DISCOVER_LIFECYCLE_STATUS },
+                });
+                return generateResponse.error(message, undefined, "SERVICE_NOT_AVAILABLE");
+            }
+            const message = `Service not found: ${value}`;
+            logger.error("服务未发现", {
+                topic: "service",
+                data: { value, step: "not-found", tried: ["primary", "scan"] },
+            });
+            return generateResponse.error(message, undefined, "SERVICE_NOT_FOUND");
+        }
+        logger.info("服务发现成功", {
+            topic: "service",
+            data: {
+                value,
+                source,
+                serviceId: service.id,
+                lifecycleStatus: service.details.lifecycle.status,
+                apiKeyCount: service.details.apiKeys.length,
+                dependencyCount: service.details.dependencies.length,
+            },
+        });
+        return generateResponse.success(service);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        logger.error("服务发现失败", {
+            topic: "service",
+            data: { value, message },
+        });
+        let service = null;
+        try {
+            service = await lookupServiceByScan(value);
+        }
+        catch (fallbackError) {
+            const fallbackMessage = fallbackError instanceof Error ? fallbackError.message : String(fallbackError);
+            logger.error("扫描回退失败", {
+                topic: "service",
+                data: { value, message: fallbackMessage },
+            });
+            return generateResponse.error(message, undefined, "SERVICE_DISCOVER_FAILED");
+        }
+        if (service != null) {
+            logger.warn("主路径异常后扫描回退成功", {
+                topic: "service",
+                data: { value, serviceId: service.id, primaryError: message },
+            });
+            return generateResponse.success(service);
+        }
+        return generateResponse.error(message, undefined, "SERVICE_DISCOVER_FAILED");
+    }
+}
+
+const RETRYABLE_CAUSE_CODES = new Set([
+    "UND_ERR_CONNECT_TIMEOUT",
+    "UND_ERR_HEADERS_TIMEOUT",
+    "UND_ERR_BODY_TIMEOUT",
+    "UND_ERR_SOCKET",
+    "ECONNRESET",
+    "ECONNREFUSED",
+    "ENOTFOUND",
+    "ETIMEDOUT",
+    "EPIPE",
+    "EAI_AGAIN",
+]);
+function errorCause(error) {
+    if (error instanceof Error) {
+        return error.cause;
+    }
+    return undefined;
+}
+function classifyNetworkError(error) {
+    if (!(error instanceof Error)) {
+        return { kind: "unknown", retryable: false, code: "", detail: String(error) };
+    }
+    const cause = errorCause(error);
+    const code = cause?.code ?? "";
+    const causeMessage = cause?.message ?? "";
+    const message = error.message;
+    const tlsDisconnect = /TLS connection was established/i.test(causeMessage) ||
+        /secure TLS connection/i.test(causeMessage) ||
+        /socket disconnected before secure TLS/i.test(message) ||
+        /socket disconnected before secure TLS/i.test(causeMessage);
+    if (tlsDisconnect) {
+        return {
+            kind: "tls_disconnect",
+            retryable: true,
+            code,
+            detail: causeMessage || message,
+        };
+    }
+    if (code === "UND_ERR_CONNECT_TIMEOUT" || error.name === "TimeoutError" || error.name === "AbortError") {
+        return {
+            kind: error.name === "AbortError" ? "timeout" : "connect_timeout",
+            retryable: true,
+            code,
+            detail: causeMessage || message,
+        };
+    }
+    if (code === "ECONNREFUSED") {
+        return {
+            kind: "connection_refused",
+            retryable: true,
+            code,
+            detail: causeMessage || message,
+        };
+    }
+    if (code === "ENOTFOUND" || code === "EAI_AGAIN") {
+        return {
+            kind: "dns_error",
+            retryable: code === "EAI_AGAIN",
+            code,
+            detail: causeMessage || message,
+        };
+    }
+    if (code === "UND_ERR_SOCKET" ||
+        code === "ECONNRESET" ||
+        code === "EPIPE" ||
+        /socket disconnected/i.test(causeMessage) ||
+        /other side closed/i.test(causeMessage)) {
+        return {
+            kind: "socket_closed",
+            retryable: true,
+            code,
+            detail: causeMessage || message,
+        };
+    }
+    if (RETRYABLE_CAUSE_CODES.has(code)) {
+        return {
+            kind: "proxy_error",
+            retryable: true,
+            code,
+            detail: causeMessage || message,
+        };
+    }
+    return {
+        kind: "unknown",
+        retryable: false,
+        code,
+        detail: causeMessage ? `${message}: ${causeMessage}` : message,
+    };
+}
+function formatNetworkError(error, label, options = {}) {
+    const classified = classifyNetworkError(error);
+    const hint = options.hint ?? "";
+    switch (classified.kind) {
+        case "connect_timeout":
+            return `${label}: connect timeout${hint}`;
+        case "tls_disconnect":
+            return `${label}: TLS handshake dropped${hint}. Often transient through proxies — retries may succeed.`;
+        case "connection_refused":
+            return `${label}: connection refused — ${classified.detail}${hint}`;
+        case "dns_error":
+            return `${label}: DNS lookup failed (${classified.code}) — ${classified.detail}`;
+        case "socket_closed":
+            return (`${label}: connection closed mid-request (${classified.code || "socket"}) — ` +
+                `${classified.detail}${hint}`);
+        case "timeout":
+            return `${label}: request timeout — ${classified.detail}${hint}`;
+        case "proxy_error":
+            return `${label}: network/proxy error (${classified.code}) — ${classified.detail}${hint}`;
+        default:
+            return `${label}: ${classified.detail}${hint}`;
+    }
+}
+
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** Default HTTP statuses that trigger retry (429, 5xx). */
+function isRetryableHttpStatus(status) {
+    return status === 429 || status >= 500;
+}
+function requestHasBody(init) {
+    return init.body != null;
+}
+function backoffMs(retryBaseMs, attempt, response, maxBackoffMs) {
+    const retryAfter = response?.headers.get("Retry-After");
+    if (retryAfter != null) {
+        const seconds = Number(retryAfter);
+        if (Number.isFinite(seconds) && seconds > 0) {
+            const delayMs = seconds * 1000;
+            return maxBackoffMs != null ? Math.min(delayMs, maxBackoffMs) : delayMs;
+        }
+    }
+    let delayMs = retryBaseMs * 2 ** (attempt - 1);
+    if (maxBackoffMs != null) {
+        delayMs = Math.min(delayMs, maxBackoffMs);
+    }
+    return delayMs;
+}
+async function fetchOnce(url, init, timeoutMs, dispatcher) {
+    const options = {
+        ...init,
+        signal: AbortSignal.timeout(timeoutMs),
+    };
+    if (dispatcher != null) {
+        options.dispatcher = dispatcher;
+    }
+    return fetch(url, options);
+}
+async function fetchWithRetry(url, initOrFactory, options) {
+    const maxAttempts = options.maxAttempts ?? 1;
+    const retryBaseMs = options.retryBaseMs ?? 2_000;
+    const isRetryableStatus = options.isRetryableStatus ?? isRetryableHttpStatus;
+    const buildInit = typeof initOrFactory === "function" ? initOrFactory : () => initOrFactory;
+    if (maxAttempts > 1 && typeof initOrFactory !== "function" && requestHasBody(initOrFactory)) {
+        throw new Error(`${options.label}: retry requires an init factory when request body may be consumed`);
+    }
+    let lastError = null;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+            const response = await fetchOnce(url, buildInit(), options.timeoutMs, options.dispatcher);
+            if (!response.ok && isRetryableStatus(response.status) && attempt < maxAttempts) {
+                const delayMs = backoffMs(retryBaseMs, attempt, response, options.maxBackoffMs);
+                if (options.logger != null) {
+                    options.logger.warn("retrying after HTTP error", {
+                        topic: "fetch",
+                        data: {
+                            label: options.label,
+                            attempt,
+                            status: response.status,
+                            delayMs,
+                        },
+                    });
+                }
+                await sleep(delayMs);
+                continue;
+            }
+            if (attempt > 1 && options.logger != null) {
+                options.logger.info("request succeeded after retry", {
+                    topic: "fetch",
+                    data: { label: options.label, attempt },
+                });
+            }
+            return response;
+        }
+        catch (error) {
+            const classified = classifyNetworkError(error);
+            lastError = new Error(formatNetworkError(error, options.label, { hint: options.hint }));
+            if (classified.retryable && attempt < maxAttempts) {
+                const delayMs = backoffMs(retryBaseMs, attempt, undefined, options.maxBackoffMs);
+                if (options.logger != null) {
+                    options.logger.warn("retrying after network error", {
+                        topic: "fetch",
+                        data: {
+                            label: options.label,
+                            attempt,
+                            maxAttempts,
+                            kind: classified.kind,
+                            code: classified.code,
+                            delayMs,
+                        },
+                    });
+                }
+                await sleep(delayMs);
+                continue;
+            }
+            throw lastError;
+        }
+    }
+    throw lastError ?? new Error(`${options.label}: request failed`);
+}
+async function fetchBinaryWithRetry(url, init, options) {
+    const response = await fetchWithRetry(url, init, options);
+    if (!response.ok) {
+        throw new Error(`${options.label}: HTTP ${response.status}`);
+    }
+    return response.arrayBuffer();
+}
+
+function fileBaseName(raw) {
+    const normalized = raw.replace(/\\/g, "/");
+    const parts = normalized.split("/");
+    return parts.at(-1) ?? normalized;
+}
+/**
+ * Safe display / storage file name from a browser or filesystem path string.
+ * Strips directory segments and forbidden characters.
+ */
+function sanitizeFileName(raw, options = {}) {
+    const maxLength = options.maxLength ?? 200;
+    const base = fileBaseName(raw);
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: intentionally strip ASCII control chars (0x00–0x1f)
+    const cleaned = base.replace(/[\x00-\x1f<>:"/\\|?*]+/g, "_").trim();
+    if (cleaned === "" || cleaned === "." || cleaned === "..") {
+        if (options.fallback != null) {
+            return options.fallback.slice(0, maxLength);
+        }
+        throw new Error("Invalid file name");
+    }
+    return cleaned.slice(0, maxLength);
+}
+/** Parcel.name / value default — 200 char cap. */
+function sanitizeParcelFileName(raw) {
+    return sanitizeFileName(raw, { maxLength: 200 });
+}
+
+/**
+ * Normalize unknown catch / rejection values to {@link Error}.
+ *
+ * `catch` and Promise rejections are typed `unknown` because `throw` can be
+ * anything (string, number, plain object). Call sites that need `.message`,
+ * re-throw, or `instanceof Error` checks should normalize first.
+ */
+function toError(value) {
+    return value instanceof Error ? value : new Error(String(value));
+}
+/** Error message safe for log `context` fields (JSON-serializable). */
+function getErrorMessage(value) {
+    return toError(value).message;
+}
+
+/** Log topic for task domain (`topic` field on structured logs). */
+const LOG_TOPIC_TASK = "task";
+const CRITICAL_UNKNOWN_TASK_TRACE_ID = "CRITICAL_UNKNOWN_TASK_TRACE_ID";
+
+var CategoryTask;
+(function (CategoryTask) {
+    CategoryTask["TASK"] = "task";
+})(CategoryTask || (CategoryTask = {}));
+var TaskStatus;
+(function (TaskStatus) {
+    TaskStatus["OPEN"] = "OPEN";
+    TaskStatus["TODO"] = "TODO";
+    TaskStatus["DOING"] = "DOING";
+    TaskStatus["DONE"] = "DONE";
+    TaskStatus["CLOSED"] = "CLOSED";
+})(TaskStatus || (TaskStatus = {}));
+/** Named transitions for {@link patchChangeTaskStatus} — verb aligned with state machine edges */
+var TaskStatusAction;
+(function (TaskStatusAction) {
+    TaskStatusAction["PUBLISH"] = "publish";
+    TaskStatusAction["CLAIM"] = "claim";
+    TaskStatusAction["RESET"] = "reset";
+    TaskStatusAction["CANCEL"] = "cancel";
+    TaskStatusAction["CLOSE"] = "close";
+    TaskStatusAction["FINISH"] = "finish";
+})(TaskStatusAction || (TaskStatusAction = {}));
+var ResultCode;
+(function (ResultCode) {
+    ResultCode[ResultCode["SUCCESS"] = 1000] = "SUCCESS";
+    /** 3xxx 依赖 / 外部 */
+    ResultCode[ResultCode["PARAMS_NOT_VALID"] = 3001] = "PARAMS_NOT_VALID";
+    ResultCode[ResultCode["REPO_NOT_VALID"] = 3002] = "REPO_NOT_VALID";
+    /** 4xxx — 运行环境 */
+    ResultCode[ResultCode["TIMEOUT"] = 4001] = "TIMEOUT";
+    ResultCode[ResultCode["CANCELLED"] = 4002] = "CANCELLED";
+    ResultCode[ResultCode["NODE_UNAVAILABLE"] = 4003] = "NODE_UNAVAILABLE";
+    ResultCode[ResultCode["UNKNOWN_ERROR"] = 9999] = "UNKNOWN_ERROR";
+})(ResultCode || (ResultCode = {}));
+
+const TASK_STATUS_FIELD = "details->>status";
+const TASK_NODE_ID_FIELD = "details->>nodeId";
+// ─── State machine ───────────────────────────────────────────────────────────
+/**
+ * Task state machine (field: `details.status`)
+ *
+ * ```text
+ *   publish          claim (CLAIM / patchClaimTask)     finish
+ * OPEN ──────► TODO ──────────────────► DOING ─────────────► DONE
+ *   │                │ reset                  │ cancel           │ close
+ *   │                │                        └──────► TODO      │
+ *   └──────── reset ─┴──────────────────────── reset ────────────┘
+ *   |                                                            │
+ *   └──────────────────── close ─────────────────────────────────┘
+ *                                                               ▼
+ *                                                            CLOSED
+ * ```
+ *
+ * | TaskStatusAction | from              | to     | lock filters                   | caller        |
+ * |------------------|-------------------|--------|--------------------------------|---------------|
+ * | PUBLISH          | OPEN              | TODO   | status = OPEN                  | scheduler     |
+ * | CLAIM            | TODO              | DOING  | status = TODO                  | worker        |
+ * | RESET            | TODO              | OPEN   | status = TODO (no nodeId)      | admin         |
+ * | RESET            | DOING, DONE       | OPEN   | status ∈ {DOING,DONE} + nodeId | worker        |
+ * | CANCEL           | DOING             | TODO   | DOING + nodeId                 | worker        |
+ * | FINISH           | DOING             | DONE   | DOING + nodeId                 | worker        |
+ * | CLOSE            | OPEN, DONE        | CLOSED | status ∈ {OPEN, DONE}          | scheduler     |
+ *
+ * RESET: omit `nodeId` to reset from **TODO**; pass `nodeId` to reset from **DOING** or **DONE**.
+ *
+ * All public APIs validate input with Zod (`validateWithSchema`). Optimistic locks live in
+ * `optimisticLockFilterList` on UPDATE — see `.cursor/skills/optimistic-lock-update/SKILL.md`.
+ */
+// ─── Zod schemas ─────────────────────────────────────────────────────────────
+const taskIdSchema = z.string().trim().min(1);
+const nodeIdSchema = z.string().trim().min(1);
+/** Optional — orchestrator (e.g. TaskNode loop) passes its trace to correlate logs. */
+const traceIdSchema$1 = z.string().trim().min(1).optional();
+z.string().trim().min(1).nullable().optional();
+const patchChangeTaskStatusBaseSchema = {
+    id: taskIdSchema,
+    extra: z.string().optional(),
+    traceId: traceIdSchema$1,
+};
+/** Shared by CLAIM / CANCEL / FINISH — worker-side actions that require nodeId */
+const patchChangeTaskStatusNodeOwnedSchema = {
+    ...patchChangeTaskStatusBaseSchema,
+    nodeId: nodeIdSchema,
+};
+const patchChangeTaskStatusSchema = z.discriminatedUnion("action", [
+    z.object({
+        ...patchChangeTaskStatusBaseSchema,
+        action: z.literal(TaskStatusAction.PUBLISH),
+    }),
+    z.object({
+        ...patchChangeTaskStatusBaseSchema,
+        action: z.literal(TaskStatusAction.CLOSE),
+    }),
+    z.object({
+        ...patchChangeTaskStatusNodeOwnedSchema,
+        action: z.literal(TaskStatusAction.CLAIM),
+    }),
+    z.object({
+        ...patchChangeTaskStatusBaseSchema,
+        action: z.literal(TaskStatusAction.RESET),
+        nodeId: nodeIdSchema.optional(),
+    }),
+    z.object({
+        ...patchChangeTaskStatusNodeOwnedSchema,
+        action: z.literal(TaskStatusAction.CANCEL),
+    }),
+    z.object({
+        ...patchChangeTaskStatusNodeOwnedSchema,
+        action: z.literal(TaskStatusAction.FINISH),
+        cost: z.number().min(0),
+    }),
+]);
+const patchTaskProgressSchema = z.object({
+    id: taskIdSchema,
+    progress: z.number().min(0).max(100),
+    nodeId: nodeIdSchema,
+    traceId: traceIdSchema$1,
+});
+const patchClaimTaskSchema = z.object({
+    nodeId: nodeIdSchema,
+    availableTaskList: z.array(z.string()).min(1),
+    traceId: traceIdSchema$1,
+});
+// ─── Optimistic lock helpers ─────────────────────────────────────────────────
+function lockOnStatus(...allowed) {
+    if (allowed.length === 1) {
+        return [{ field: TASK_STATUS_FIELD, operator: "eq", value: allowed[0] }];
+    }
+    return [{ field: TASK_STATUS_FIELD, operator: "in", value: allowed }];
+}
+function lockOnOwnerNode(nodeId) {
+    return { field: TASK_NODE_ID_FIELD, operator: "eq", value: nodeId };
+}
+/** DOING row owned by `nodeId` — used by FINISH, CANCEL, patchTaskProgress */
+function lockOnDoingOwner(nodeId) {
+    return [...lockOnStatus(TaskStatus.DOING), lockOnOwnerNode(nodeId)];
+}
+/** TODO without nodeId; DOING/DONE with owner when nodeId is provided */
+function lockOnReset(nodeId) {
+    if (nodeId != null) {
+        return [...lockOnStatus(TaskStatus.DOING, TaskStatus.DONE), lockOnOwnerNode(nodeId)];
+    }
+    return lockOnStatus(TaskStatus.TODO);
+}
+function clearExecutionState() {
+    return { progress: 0, nodeId: null, result: undefined };
+}
+// ─── Internal transitions ────────────────────────────────────────────────────
+async function transitionTask({ id, optimisticLockFilterList, updateFn, updateExtraFn, }) {
+    return updateTargetDetails({
+        id,
+        optimisticLockFilterList,
+        updateFn,
+        updateExtraFn,
+    });
+}
+function logTaskTransition(logger, action, task, data) {
+    logger.debug("任務狀態遷移成功", {
+        topic: LOG_TOPIC_TASK,
+        data: {
+            action,
+            taskId: task.id,
+            taskValue: task.value,
+            status: task.details.status,
+            nodeId: task.details.nodeId,
+            ...data,
+        },
+    });
+}
+/** TODO → DOING — lock status only (no owner yet); used by CLAIM and {@link patchClaimTask} */
+async function claimTaskById({ taskId, nodeId, updateExtraFn, }) {
+    return transitionTask({
+        id: taskId,
+        optimisticLockFilterList: lockOnStatus(TaskStatus.TODO),
+        updateFn: (details) => ({
+            ...details,
+            status: TaskStatus.DOING,
+            nodeId,
+        }),
+        updateExtraFn,
+    });
+}
+// ─── patchChangeTaskStatus ───────────────────────────────────────────────────
+const patchChangeTaskStatus = validateWithSchema(patchChangeTaskStatusSchema, "patchChangeTaskStatusSchema")(async (params) => {
+    const logger = createLogger({ module: "patchChangeTaskStatus", traceId: params.traceId });
+    const { id, action, extra } = params;
+    const updateExtraFn = extra == null ? undefined : () => extra;
+    switch (action) {
+        case TaskStatusAction.PUBLISH: {
+            const data = await transitionTask({
+                id,
+                optimisticLockFilterList: lockOnStatus(TaskStatus.OPEN),
+                updateFn: (details) => ({
+                    ...details,
+                    ...clearExecutionState(),
+                    status: TaskStatus.TODO,
+                }),
+                updateExtraFn,
+            });
+            logTaskTransition(logger, action, data);
+            return generateResponse.success(data);
+        }
+        case TaskStatusAction.CLAIM: {
+            const { nodeId } = params;
+            const data = await claimTaskById({ taskId: id, nodeId, updateExtraFn });
+            logTaskTransition(logger, action, data);
+            return generateResponse.success(data);
+        }
+        case TaskStatusAction.RESET: {
+            const { nodeId } = params;
+            const data = await transitionTask({
+                id,
+                optimisticLockFilterList: lockOnReset(nodeId),
+                updateFn: (details) => ({
+                    ...details,
+                    ...clearExecutionState(),
+                    status: TaskStatus.OPEN,
+                }),
+                updateExtraFn,
+            });
+            logTaskTransition(logger, action, data, nodeId != null ? undefined : { resetFrom: "TODO" });
+            return generateResponse.success(data);
+        }
+        case TaskStatusAction.CANCEL: {
+            const { nodeId } = params;
+            const data = await transitionTask({
+                id,
+                optimisticLockFilterList: lockOnDoingOwner(nodeId),
+                updateFn: (details) => ({
+                    ...details,
+                    ...clearExecutionState(),
+                    status: TaskStatus.TODO,
+                }),
+                updateExtraFn,
+            });
+            logTaskTransition(logger, action, data);
+            return generateResponse.success(data);
+        }
+        case TaskStatusAction.CLOSE: {
+            const data = await transitionTask({
+                id,
+                optimisticLockFilterList: lockOnStatus(TaskStatus.OPEN, TaskStatus.DONE),
+                updateFn: (details) => ({
+                    ...details,
+                    status: TaskStatus.CLOSED,
+                }),
+                updateExtraFn,
+            });
+            logTaskTransition(logger, action, data);
+            return generateResponse.success(data);
+        }
+        case TaskStatusAction.FINISH: {
+            const { cost, nodeId } = params;
+            const data = await transitionTask({
+                id,
+                optimisticLockFilterList: lockOnDoingOwner(nodeId),
+                updateFn: (details) => ({
+                    ...details,
+                    progress: 100,
+                    status: TaskStatus.DONE,
+                    nodeId,
+                    result: {
+                        cost,
+                        code: ResultCode.SUCCESS,
+                    },
+                }),
+                updateExtraFn,
+            });
+            logTaskTransition(logger, action, data, { cost });
+            return generateResponse.success(data);
+        }
+        default: {
+            const _exhaustive = action;
+            const message = `[patchChangeTaskStatus] Unknown action: ${String(_exhaustive)}`;
+            logger.error(message, { topic: "task", data: { action: String(_exhaustive) } });
+            return generateResponse.error(message);
+        }
+    }
+});
+// ─── patchTaskProgress ───────────────────────────────────────────────────────
+/** Update progress on a DOING task; only the owning node may write (see `lockOnDoingOwner`). */
+const patchTaskProgress = validateWithSchema(patchTaskProgressSchema, "patchTaskProgressSchema")(async ({ id, progress, nodeId, traceId }) => {
+    const logger = createLogger({ module: "patchTaskProgress", traceId, labels: { nodeId } });
+    const data = await transitionTask({
+        id,
+        optimisticLockFilterList: lockOnDoingOwner(nodeId),
+        updateFn: (details) => ({
+            ...details,
+            progress,
+        }),
+    });
+    logTaskTransition(logger, "patchTaskProgress", data, { progress });
+    return generateResponse.success(data);
+});
+// ─── patchClaimTask ──────────────────────────────────────────────────────────
+/**
+ * Discover and claim one TODO task for this node.
+ *
+ * Flow: oldest TODO in `availableTaskList` (FIFO by `created_at`) → {@link claimTaskById}.
+ * Equivalent to `patchChangeTaskStatus({ id, action: CLAIM, nodeId })` when `id` is already known.
+ *
+ * Returns `data: null` when no TODO task matches.
+ * Optimistic lock conflicts return `{ error, code: OPTIMISTIC_LOCK_ERROR_CODE }` (not thrown).
+ */
+const patchClaimTask = validateWithSchema(patchClaimTaskSchema, "patchClaimTaskSchema")(async ({ nodeId, availableTaskList, traceId }) => {
+    const logger = createLogger({ module: "patchClaimTask", traceId, labels: { nodeId } });
+    let todoTask;
+    try {
+        const { data: taskCandidates } = await getTargetList({
+            category: CategoryTask.TASK,
+            filterList: [
+                { field: TASK_STATUS_FIELD, operator: "eq", value: TaskStatus.TODO },
+                { field: "value", operator: "in", value: availableTaskList },
+            ],
+            limit: 1,
+            orderBy: { field: "created_at", ascending: true },
+        });
+        const possibleTask = taskCandidates?.[0] ?? null;
+        if (possibleTask == null) {
+            return generateResponse.success(null);
+        }
+        todoTask = possibleTask;
+    }
+    catch (error) {
+        const message = getErrorMessage(error);
+        logger.error("獲取 TODO 任務失敗", { topic: LOG_TOPIC_TASK, data: { error: message, availableTaskList } });
+        return generateResponse.error(message);
+    }
+    const taskLogger = createLogger({
+        module: "patchClaimTask",
+        traceId,
+        traceParentId: todoTask.details.traceId,
+        labels: { nodeId },
+    });
+    try {
+        const data = await claimTaskById({ taskId: todoTask.id, nodeId });
+        logTaskTransition(taskLogger, "patchClaimTask", data);
+        return generateResponse.success(data);
+    }
+    catch (error) {
+        if (isOptimisticLockError(error)) {
+            taskLogger.debug("認領競爭失敗，任務已被其他節點認領", {
+                topic: LOG_TOPIC_TASK,
+                data: { taskId: todoTask.id, taskTypeKey: todoTask.value },
+            });
+            return generateResponse.error(OPTIMISTIC_LOCK_FAILED_MESSAGE, undefined, OPTIMISTIC_LOCK_ERROR_CODE);
+        }
+        const message = getErrorMessage(error);
+        taskLogger.error("認領任務失敗", {
+            topic: LOG_TOPIC_TASK,
+            data: { error: message, taskId: todoTask.id, taskTypeKey: todoTask.value },
+        });
+        return generateResponse.error(message);
+    }
+});
+
+const traceIdSchema = z.string().trim().min(1).optional();
+const traceParentIdSchema = z.string().trim().min(1).nullable().optional();
+/** Initial status for a new task — OPEN (draft) or TODO (claimable by workers). */
+const postTaskInitialStatusSchema = z
+    .union([z.literal(TaskStatus.OPEN), z.literal(TaskStatus.TODO)])
+    .optional()
+    .default(TaskStatus.TODO);
+const postTaskSchema = z.object({
+    name: z.string().trim().min(1),
+    /** Task type key — matches `task.value`, {@link patchClaimTask}, {@link Repo.value}, and local Repo registry. */
+    value: z.string().trim().min(1),
+    params: z.unknown(),
+    taskStatus: postTaskInitialStatusSchema,
+    tagList: z.array(z.string()).optional().default([]),
+    extra: z.string().optional(),
+    traceId: traceIdSchema,
+    traceParentId: traceParentIdSchema,
+});
+/** Shared DB insert for {@link postTask} and {@link postTaskWithValidation}. */
+async function createTaskRow({ name, value, params, taskStatus, tagList, extra, taskTraceId, traceParentId }, logger) {
+    const result = await createTarget({
+        payload: {
+            name,
+            value,
+            params,
+            taskStatus,
+            tagList,
+            extra,
+            traceId: taskTraceId,
+            traceParentId,
+        },
+        createFn: () => ({
+            name,
+            value,
+            category: CategoryTask.TASK,
+            tagList,
+            extra,
+            details: {
+                manifestVersion: 0,
+                status: taskStatus,
+                params,
+                progress: 0,
+                nodeId: null,
+                traceId: taskTraceId,
+            },
+        }),
+    });
+    logger.info("任務已創建", {
+        topic: "task",
+        data: {
+            taskId: result.data?.id,
+            taskTypeKey: value,
+            status: taskStatus,
+            traceId: taskTraceId,
+        },
+    });
+    return result;
+}
+/**
+ * Create a task row (scheduler / admin). **Browser and Node** — no Repo or params validation.
+ * Execution-time checks live in {@link TaskManager.prepareTask}.
+ */
+const postTask = validateWithSchema(postTaskSchema, "postTaskSchema")(async ({ name, value, params, taskStatus, tagList, extra, traceId, traceParentId }) => {
+    const taskTraceId = traceId?.trim() || logManager.generateTraceId();
+    const logger = createLogger({
+        module: "postTask",
+        traceId: taskTraceId,
+        traceParentId: traceParentId ?? null,
+    });
+    return createTaskRow({ name, value, params, taskStatus, tagList, extra, traceParentId, taskTraceId }, logger);
+});
+
+/** Count tasks of `taskType` grouped by each requested status. */
+function countTasksByType(tasks, taskType, statuses) {
+    const filtered = tasks.filter((task) => task.value === taskType);
+    const counts = {};
+    for (const status of statuses) {
+        counts[status] = filtered.filter((task) => task.details.status === status).length;
+    }
+    return counts;
+}
+/** Total tasks of `taskType` whose status is in `statuses`. */
+function summarizeTaskQueue(tasks, taskType, statuses) {
+    return tasks.filter((task) => task.value === taskType && statuses.includes(task.details.status)).length;
+}
+
+var CategoryWord;
+(function (CategoryWord) {
+    CategoryWord["WORD"] = "word";
+})(CategoryWord || (CategoryWord = {}));
+
+export { patchNodeHeartBeatSchema as $, ApiMethod as A, getParcelSchema as B, CategoryIdea as C, getScanRemoteRepoValues as D, getScanRemoteRepoValuesSchema as E, getService as F, getServiceSchema as G, installChunkFetchRegistry as H, isHttpUrl as I, isLocalFilesystemPath as J, isOpaqueChunkUrl as K, isRetryableHttpStatus as L, Market as M, NodeStatus as N, parcelDetailsSchema as O, ParcelManager as P, parseProviderPrefixedUrl as Q, ResultCode as R, ServiceLifecycleStatus as S, TASK_REPO_USAGE as T, patchChangeNodeStatus as U, patchChangeNodeStatusSchema as V, patchChangeTaskStatus as W, patchChangeTaskStatusSchema as X, patchClaimTask as Y, patchClaimTaskSchema as Z, patchNodeHeartBeat as _, CategoryLink as a, patchStopNode as a0, patchStopNodeSchema as a1, patchTaskProgress as a2, patchTaskProgressSchema as a3, postApi as a4, postApiSchema as a5, postLinkCreate as a6, postParcel as a7, postParcelSchema as a8, postRegisterNode as a9, postRegisterNodeSchema as aa, postService as ab, postServiceSchema as ac, postTask as ad, postTaskSchema as ae, publishParcel as af, registerProviderChunkResolver as ag, requestHasBody as ah, resolveFetchUrl as ai, restoreParcel as aj, restoreParcelById as ak, sanitizeFileName as al, sanitizeParcelFileName as am, schemaDefinitionSchema as an, serviceDetailsSchema as ao, serviceLifecycleSchema as ap, sha256Hex as aq, summarizeTaskQueue as ar, getErrorMessage as as, LOG_TOPIC_TASK as at, CRITICAL_UNKNOWN_TASK_TRACE_ID as au, toError as av, createTaskRow as aw, CategoryNode as b, CategoryParcel as c, CategoryRepo as d, CategoryService as e, CategoryTask as f, CategoryWord as g, PostLinkValidator as h, TaskStatus as i, TaskStatusAction as j, apiDetailsSchema as k, classifyNetworkError as l, countTasksByType as m, createStorageProviderRegistry as n, createUploadTracker as o, deleteParcel as p, deleteParcelSchema as q, discoverService as r, evaluateBusyNodeLiveness as s, fetchBinaryWithRetry as t, fetchWithRetry as u, fieldDefinitionSchema as v, formatNetworkError as w, getApi as x, getApiSchema as y, getParcel as z };
+//# sourceMappingURL=word.interface-DLgRobKV.js.map