@potential-guide/task-protocol 0.0.0-stage → 0.1.0-rc.0

package/LICENSE

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

package/README.md

@@ -1,3 +1,85 @@
-# Temporary Holding Version
+# @potential-guide/task-protocol
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+## Task Bundle bytes and structure
+
+The Bundle protocol owns `taskBundleLimits`, `TaskBundleFileLimits`,
+`isTaskBundlePath`, `parseTaskBundleYaml`, and `readTaskBundle`.
+Limits preserve the 64 MiB total/per-file, 256-file, 512-path and 72 MiB CAR
+budgets. Paths are portable, relative, NFC-normalized names without traversal,
+reserved device names or ambiguous casing.
+`parseTaskBundleYaml` reads bounded UTF-8 JSON-subset YAML, without aliases,
+tags, duplicate keys or non-finite numbers; it also reads author build
+declarations before their own schema validation.
+`readTaskBundle` takes an already supplied `ReadonlyMap<string, Uint8Array>`
+and checks exact file inclusion, capacities, nonempty UTF-8 Worker bytes and
+offline Schema resources. It returns declaration, resolved schemas, bytes and
+file count without evaluating the Worker, reading a directory or fetching data.
+Both author tooling and Engine use this implementation independently of
+`artifact-files`. Filesystem safety and Node runtime eligibility remain caller
+responsibilities; Engine cache/hint/retention budgets are not protocol limits.
+Browser reference and presentation subpaths remain independent of this reader
+and its YAML/Schema implementation.
+
+Task Bundle 的引用为根 CID 字符串或 `{cid, hint}`：
+`parseBundleReference(reference)` 接受 CID 文本或对象 JSON，
+`formatBundleReference(bundle)` 保留其填写形状及有序 hint。
+两者复用 `validateBundleReference` 的 CID/HTTP(S) gateway 基址约束；
+hint 可为非空字符串或非空数组，不允许凭据、query、fragment、空项或非法 URI。
+Engine 另施加宿主 hint 数量预算，非法输入与容量超限明确区分。
+Request 原始表示参与幂等；内容判等与缓存使用 `bundleCid(reference)` 规范化根 CID。
+旧 URL/Digest 或 URL#Digest 引用明确拒绝，不做双轨转换。
+辅助函数同时从包根与浏览器安全的 `@potential-guide/task-protocol/bundle-reference`
+子入口导出；浏览器使用子入口，不引入 Node Schema 编译与摘要依赖。
+
+可信宿主资源声明采用 `resourceLifetime: "request"`，或提供独立
+`confirmResourceRelease(RunResourceContext)` 证明跨请求 owner/句柄已释放。
+上下文包含可信 workerGeneration；这些宿主函数不进入类型 Worker。
+失败 Result 与成功 Result 一样经纯 terminal 业务复验，不能改写或在恢复前放宽。
+
+通用 Task/完整 Run 的 JSON、schema、请求、事件、Store 与服务边界。
+
+Task Bundle/Worker 使用唯一 `taskSchemaUri` v1，包含独立诊断日志协议。
+项目尚未正式发布，v1 可原地演进；已移除的 Task v2 和未来未知 URL 明确拒绝，不做别名。
+TaskType 仅声明 type/version/inputSchema/resultSchema/messageSchema 和完整 run 入口；
+Host 用 RegisteredType 本地模块描述注册，不传动态函数对象给 Engine。
+
+matchPolicy / MatchPolicy 使用 starts-after-eligible、terminates-after-eligible 两值，after 包含等号。
+时间对应完整 Run 开始/实际退出，不对应业务 Execution；已开始但未终结的 Run
+可在可信源资格边界满足 terminates 条件。Stage 为 initial/running/stopping/stopped/completed/failed；
+stage、canceled、按当前 now 推导的时间标签互相独立，取消或终态不冻结后两者。
+Progress 另用 preparation/allocation/execution、可选有限 0–100 percent 与展示字符串。
+
+`aggregateTaskStatus(task, now)` 是纯展示聚合函数，`now` 必须显式传入 epoch 毫秒。
+输入仅需 `stage`、`canceled`、`eligibleAt`、`deadlineAt`，兼容 TaskSnapshot / TaskSummary。
+返回 `{ status, qualifiers }`，不含文案、颜色或 i18n；各 UI 自行映射。
+`status` 为 completed / failed / stopped / canceled / timedOut / stopping / running /
+pending（待生效）/ waiting（已生效、等待匹配）。
+优先保留运行结局，再判断取消、超时，之后保留 running / stopping，
+仅 initial 按生效边界区分 pending / waiting；已匹配运行不因时钟回拨显示待生效。
+终结后取消附加 `demandWithdrawn`；取消或超时但运行未终结附加 `runNotEnded`；
+其余 `qualifiers` 为空数组。这些标识不证明资源回收或结果是否按时产生。
+时间输入遵循协议 canonical UTC，截止不得早于生效时间；无效输入抛出 `TaskError`。
+聚合结果不存储，也不用于匹配、取消或回收决策。
+
+浏览器使用独立入口，避免加载服务端 schema / crypto：
+
+```ts
+import { aggregateTaskStatus } from "@potential-guide/task-protocol/presentation";
+
+const { status, qualifiers } = aggregateTaskStatus(task, now);
+```
+
+messageSchema 支持 boolean，false 是 Never，{} / true 不是 Never。
+messages 必选、Task 归属及确认与生命周期控制分离；checkpoint 是独立、按 resultSchema 验证的机器证据。
+公共服务消息操作使用 taskId/messageId、可信 Caller、持久化状态，不改 Input/deadline。
+
+Facts projection v5；Task 仅存受理/取消事实，匹配与状态按源前缀推导。
+新 submission 的 `bundleProtocol:"ipfs"` 区分当前受理记录与不支持的旧协议；
+即使新请求因非法引用而被拒绝，仍可跨重启读取其原始意图及持久拒绝结果。
+Task/Run Binding 保留原 inputSchema；实时共享与纯事实重放都使用该 Schema 编译的结构 Equals。
+历史分组的 equivalenceKey 与 Equals 共用投影和序列化，由绑定 Schema 与原 Input 重建，不落盘为匹配权威。
+允许但未声明的额外字段也参与比较，不能忽略其存在或取值差异。
+Request 幂等冲突检查仍比较完整原始 Request，不使用结构 Equals。
+全域源 revision、完整集合封装和 fromRevision 补读不使用每 Task 权威快照或绑定事务。
+旧版本明确拒绝，无隐式数据迁移或删除。
+完整协议与历史/取消/资源边界见 [Task Engine](../../docs/task-engine.md)。

package/dist/bundle-files.d.ts

@@ -0,0 +1,9 @@
+import { type TaskBundleFileLimits } from "./bundle-paths.js";
+/** Inspect supplied bytes only; filesystem, transport and runtime eligibility belong to callers. */
+export declare function readTaskBundle(files: ReadonlyMap<string, Uint8Array>, configuration?: Partial<TaskBundleFileLimits>): {
+    declaration: import("./bundle.js").TaskBundleDeclaration;
+    resolved: import("./bundle.js").ResolvedTaskBundle;
+    bytes: number;
+    files: number;
+};
+//# sourceMappingURL=bundle-files.d.ts.map

package/dist/bundle-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundle-files.d.ts","sourceRoot":"","sources":["../src/bundle-files.ts"],"names":[],"mappings":"AAMA,OAAO,EAAoB,KAAK,oBAAoB,EAAoB,MAAM,mBAAmB,CAAC;AAGlG,oGAAoG;AACpG,wBAAgB,cAAc,CAC5B,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,UAAU,CAAC,EACtC,aAAa,GAAE,OAAO,CAAC,oBAAoB,CAAM;;;;;EA6FlD"}

package/dist/bundle-files.js

@@ -0,0 +1,93 @@
+import { resolveBundleSchemas, validateTaskBundleFiles, parseTaskBundleYaml, validateTaskBundle, } from "./bundle.js";
+import { isTaskBundlePath, taskBundleLimits } from "./bundle-paths.js";
+import { fail, TaskError } from "./json.js";
+/** Inspect supplied bytes only; filesystem, transport and runtime eligibility belong to callers. */
+export function readTaskBundle(files, configuration = {}) {
+    const limits = {
+        bytes: taskBundleLimits.bytes,
+        fileBytes: taskBundleLimits.fileBytes,
+        files: taskBundleLimits.files,
+        paths: taskBundleLimits.paths,
+        ...configuration,
+    };
+    if (Object.values(limits).some((value) => !Number.isSafeInteger(value) || value <= 0))
+        fail("invalid_config", "Invalid Bundle file capacity.");
+    if (files.size > limits.files)
+        fail("capacity_exceeded", "Bundle file capacity exceeded.");
+    const seen = new Set();
+    const spellings = new Map();
+    const unsupportedPaths = [];
+    let bytes = 0;
+    for (const [path, content] of files) {
+        if (!isTaskBundlePath(path) || seen.has(path.toLowerCase()))
+            fail("invalid_bundle", "Unsafe or duplicate Bundle path.");
+        if (!["task.yaml", "worker.cjs"].includes(path) &&
+            !path.startsWith("schemas/") &&
+            !path.startsWith("resources/"))
+            unsupportedPaths.push(path);
+        seen.add(path.toLowerCase());
+        let prefix = "";
+        for (const part of path.split("/")) {
+            prefix = prefix ? `${prefix}/${part}` : part;
+            const folded = prefix.toLowerCase();
+            if (spellings.has(folded) && spellings.get(folded) !== prefix)
+                fail("invalid_bundle", "Ambiguous Bundle path casing.");
+            spellings.set(folded, prefix);
+        }
+        bytes += content.byteLength;
+        if (content.byteLength > limits.fileBytes ||
+            bytes > limits.bytes ||
+            spellings.size > limits.paths)
+            fail("capacity_exceeded", "Bundle tree capacity exceeded.");
+    }
+    for (const path of files.keys()) {
+        const parts = path.split("/");
+        parts.pop();
+        while (parts.length) {
+            if (files.has(parts.join("/")))
+                fail("invalid_bundle", "Bundle file is also a parent.");
+            parts.pop();
+        }
+    }
+    const yaml = files.get("task.yaml");
+    const worker = files.get("worker.cjs");
+    if (!yaml || !worker?.byteLength)
+        fail("invalid_bundle", "Bundle requires task.yaml and nonempty worker.cjs.");
+    const parsed = parseTaskBundleYaml(yaml);
+    if (unsupportedPaths.length &&
+        parsed !== null &&
+        typeof parsed === "object" &&
+        !Array.isArray(parsed) &&
+        Array.isArray(parsed.include)) {
+        const include = parsed.include;
+        const undeclared = unsupportedPaths.find((path) => !include.includes(path));
+        if (undeclared !== undefined)
+            fail("invalid_bundle", `Undeclared Bundle file: ${undeclared}.`);
+        fail("invalid_bundle", `Unsupported Bundle path: ${unsupportedPaths[0]}.`);
+    }
+    const declaration = validateTaskBundle(parsed);
+    validateTaskBundleFiles(declaration, files.keys());
+    const schemaFiles = [...files].filter(([path]) => path.startsWith("schemas/"));
+    let schemas;
+    try {
+        schemas = schemaFiles.map(([, content]) => {
+            const value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(content));
+            if (!value || typeof value !== "object" || Array.isArray(value))
+                fail("invalid_schema", "Shared Schema requires an absolute $id.");
+            return value;
+        });
+        new TextDecoder("utf-8", { fatal: true }).decode(worker);
+    }
+    catch (error) {
+        if (error instanceof TaskError)
+            throw error;
+        fail("invalid_bundle", "Invalid Bundle Worker or Schema JSON.");
+    }
+    return {
+        declaration,
+        resolved: resolveBundleSchemas(declaration, schemas, schemaFiles.map(([path]) => path)),
+        bytes,
+        files: files.size,
+    };
+}
+//# sourceMappingURL=bundle-files.js.map

package/dist/bundle-files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundle-files.js","sourceRoot":"","sources":["../src/bundle-files.ts"],"names":[],"mappings":"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"}

package/dist/bundle-paths.d.ts

@@ -0,0 +1,15 @@
+export interface TaskBundleFileLimits {
+    bytes: number;
+    fileBytes: number;
+    files: number;
+    paths: number;
+}
+export declare const taskBundleLimits: Readonly<{
+    bytes: number;
+    fileBytes: number;
+    files: 256;
+    paths: 512;
+    archiveBytes: number;
+}>;
+export declare function isTaskBundlePath(path: string): boolean;
+//# sourceMappingURL=bundle-paths.d.ts.map

package/dist/bundle-paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundle-paths.d.ts","sourceRoot":"","sources":["../src/bundle-paths.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED,eAAO,MAAM,gBAAgB;;;;;;EAM3B,CAAC;AAEH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAsBtD"}

package/dist/bundle-paths.js

@@ -0,0 +1,24 @@
+export const taskBundleLimits = Object.freeze({
+    bytes: 64 * 1024 * 1024,
+    fileBytes: 64 * 1024 * 1024,
+    files: 256,
+    paths: 512,
+    archiveBytes: 72 * 1024 * 1024,
+});
+export function isTaskBundlePath(path) {
+    const encoder = new TextEncoder();
+    return (encoder.encode(path).byteLength <= 1024 &&
+        path
+            .split("/")
+            .every((part) => !!part &&
+            part !== "." &&
+            part !== ".." &&
+            part === part.normalize("NFC") &&
+            encoder.encode(part).byteLength <= 255 &&
+            part.toLowerCase() !== "node_modules" &&
+            !/[\\:<>"|?*]/.test(part) &&
+            ![...part].some((character) => character.charCodeAt(0) < 32 || character.charCodeAt(0) === 127) &&
+            !/[. ]$/.test(part) &&
+            !/^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(part)));
+}
+//# sourceMappingURL=bundle-paths.js.map

package/dist/bundle-paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundle-paths.js","sourceRoot":"","sources":["../src/bundle-paths.ts"],"names":[],"mappings":"AAOA,MAAM,CAAC,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,CAAC;IAC5C,KAAK,EAAE,EAAE,GAAG,IAAI,GAAG,IAAI;IACvB,SAAS,EAAE,EAAE,GAAG,IAAI,GAAG,IAAI;IAC3B,KAAK,EAAE,GAAG;IACV,KAAK,EAAE,GAAG;IACV,YAAY,EAAE,EAAE,GAAG,IAAI,GAAG,IAAI;CAC/B,CAAC,CAAC;AAEH,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC;IAClC,OAAO,CACL,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,UAAU,IAAI,IAAI;QACvC,IAAI;aACD,KAAK,CAAC,GAAG,CAAC;aACV,KAAK,CACJ,CAAC,IAAI,EAAE,EAAE,CACP,CAAC,CAAC,IAAI;YACN,IAAI,KAAK,GAAG;YACZ,IAAI,KAAK,IAAI;YACb,IAAI,KAAK,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC;YAC9B,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,UAAU,IAAI,GAAG;YACtC,IAAI,CAAC,WAAW,EAAE,KAAK,cAAc;YACrC,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC;YACzB,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,IAAI,CACb,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,EAAE,IAAI,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,GAAG,CAC/E;YACD,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC;YACnB,CAAC,iDAAiD,CAAC,IAAI,CAAC,IAAI,CAAC,CAChE,CACJ,CAAC;AACJ,CAAC"}

package/dist/bundle-reference.d.ts

@@ -0,0 +1,9 @@
+export type BundleReference = string | {
+    cid: string;
+    hint: string | string[];
+};
+export declare function bundleCid(value: BundleReference): string;
+export declare function validateBundleReference(value: unknown, maxHints?: number): BundleReference;
+export declare function parseBundleReference(value: string): BundleReference;
+export declare function formatBundleReference(value: BundleReference): string;
+//# sourceMappingURL=bundle-reference.d.ts.map

package/dist/bundle-reference.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundle-reference.d.ts","sourceRoot":"","sources":["../src/bundle-reference.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;CAAE,CAAC;AAEhF,wBAAgB,SAAS,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAIxD;AAED,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,OAAO,EACd,QAAQ,SAA0B,GACjC,eAAe,CAgEjB;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,CAWnE;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAGpE"}

package/dist/bundle-reference.js

@@ -0,0 +1,82 @@
+import { CID } from "multiformats/cid";
+import { fail } from "./json.js";
+export function bundleCid(value) {
+    return CID.parse(typeof value === "string" ? value : value.cid)
+        .toV1()
+        .toString();
+}
+export function validateBundleReference(value, maxHints = Number.MAX_SAFE_INTEGER) {
+    const cid = typeof value === "string"
+        ? value
+        : value && typeof value === "object"
+            ? Object.getOwnPropertyDescriptor(value, "cid")?.value
+            : undefined;
+    if (typeof cid !== "string" || cid.length > 256)
+        fail("invalid_request", "A Bundle root CID is required.");
+    try {
+        const parsed = CID.parse(cid);
+        if (![0x70, 0x55].includes(parsed.code) || parsed.multihash.code !== 0x12)
+            fail("invalid_request", "Unsupported Bundle CID codec or hash.");
+    }
+    catch {
+        return fail("invalid_request", "Invalid Bundle root CID.");
+    }
+    if (typeof value === "string")
+        return value;
+    if (!value ||
+        typeof value !== "object" ||
+        Array.isArray(value) ||
+        Object.keys(value).sort().join(",") !== "cid,hint")
+        fail("invalid_request", "Bundle references are a CID or {cid,hint}.");
+    const ref = { cid, hint: Object.getOwnPropertyDescriptor(value, "hint")?.value };
+    const hints = typeof ref.hint === "string" ? [ref.hint] : ref.hint;
+    if (!Array.isArray(hints) || !hints.length)
+        fail("invalid_request", "Gateway hints must not be empty.");
+    if (hints.length > maxHints)
+        fail("capacity_exceeded", "Gateway hint capacity exceeded.");
+    for (const hint of hints) {
+        if (typeof hint !== "string" ||
+            !hint ||
+            hint.length > 4096 ||
+            [...hint].some((character) => character.charCodeAt(0) <= 32 || character.charCodeAt(0) === 127 || character === "\\"))
+            fail("invalid_request", "Invalid gateway hint.");
+        let uri;
+        try {
+            uri = new URL(hint);
+        }
+        catch {
+            return fail("invalid_request", "Invalid gateway base URI.");
+        }
+        if (!["https:", "http:"].includes(uri.protocol) ||
+            !/^https?:\/\/[^/]+/i.test(hint) ||
+            hint
+                .slice(hint.indexOf("://") + 3)
+                .split("/", 1)[0]
+                ?.includes("@") ||
+            uri.username ||
+            uri.password ||
+            hint.includes("?") ||
+            hint.includes("#"))
+            fail("invalid_request", "Gateway requires an HTTP(S) base URI without credentials/query/fragment.");
+    }
+    return { cid: ref.cid, hint: typeof ref.hint === "string" ? ref.hint : [...hints] };
+}
+export function parseBundleReference(value) {
+    if (typeof value !== "string")
+        fail("invalid_request", "A Bundle CID reference is required.");
+    let parsed = value;
+    if (value.trim().startsWith("{")) {
+        try {
+            parsed = JSON.parse(value);
+        }
+        catch {
+            return fail("invalid_request", "Invalid Bundle reference JSON.");
+        }
+    }
+    return validateBundleReference(parsed);
+}
+export function formatBundleReference(value) {
+    const ref = validateBundleReference(value);
+    return typeof ref === "string" ? ref : JSON.stringify(ref);
+}
+//# sourceMappingURL=bundle-reference.js.map

package/dist/bundle-reference.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundle-reference.js","sourceRoot":"","sources":["../src/bundle-reference.ts"],"names":[],"mappings":"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"}

package/dist/bundle.d.ts

@@ -0,0 +1,80 @@
+import { type Json, type JsonObject } from "./json.js";
+import { type InputSchema, type JsonSchema } from "./schema.js";
+import { taskSchemaUri } from "./task-schema-uri.js";
+export { taskSchemaUri } from "./task-schema-uri.js";
+export declare const taskBundleSchema: {
+    $id: string;
+    $comment: string;
+    type: string;
+    additionalProperties: boolean;
+    required: string[];
+    properties: {
+        $schema: {
+            const: string;
+        };
+        name: {
+            type: string;
+            minLength: number;
+            pattern: string;
+        };
+        runtime: {
+            type: string;
+            additionalProperties: boolean;
+            required: string[];
+            properties: {
+                type: {
+                    const: string;
+                };
+                minVersion: {
+                    type: string;
+                    pattern: string;
+                };
+            };
+        };
+        entry: {
+            const: string;
+        };
+        include: {
+            type: string;
+            minItems: number;
+            maxItems: 256;
+            uniqueItems: boolean;
+            items: {
+                type: string;
+                pattern: string;
+            };
+        };
+        inputSchema: {
+            type: string;
+        };
+        resultSchema: {
+            type: string[];
+        };
+        messageSchema: {
+            type: string[];
+        };
+    };
+};
+export * from "./bundle-reference.js";
+export interface TaskBundleDeclaration {
+    $schema: typeof taskSchemaUri;
+    name: string;
+    runtime: {
+        type: "node";
+        minVersion: string;
+    };
+    entry: "worker.cjs";
+    include: string[];
+    inputSchema: JsonObject;
+    resultSchema: JsonSchema;
+    messageSchema: JsonSchema;
+}
+export interface ResolvedTaskBundle extends Omit<TaskBundleDeclaration, "inputSchema"> {
+    inputSchema: InputSchema;
+}
+export declare function parseTaskBundleYaml(bytes: Uint8Array): Json;
+export declare function validateTaskBundle(value: unknown): TaskBundleDeclaration;
+export declare function validateTaskBundleFiles(declaration: TaskBundleDeclaration, paths: Iterable<string>): void;
+/** Resolve only supplied resources. No network loader or ambient Schema registry exists. */
+export declare function resolveBundleSchemas(declaration: TaskBundleDeclaration, resources: readonly JsonObject[], resourcePaths?: readonly string[]): ResolvedTaskBundle;
+//# sourceMappingURL=bundle.d.ts.map

package/dist/bundle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundle.d.ts","sourceRoot":"","sources":["../src/bundle.ts"],"names":[],"mappings":"AAGA,OAAO,EAAmB,KAAK,IAAI,EAAE,KAAK,UAAU,EAAmB,MAAM,WAAW,CAAC;AACzF,OAAO,EAGL,KAAK,WAAW,EAChB,KAAK,UAAU,EAChB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoD5B,CAAC;AACF,cAAc,uBAAuB,CAAC;AACtC,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,OAAO,aAAa,CAAC;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9C,KAAK,EAAE,YAAY,CAAC;IACpB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,WAAW,EAAE,UAAU,CAAC;IACxB,YAAY,EAAE,UAAU,CAAC;IACzB,aAAa,EAAE,UAAU,CAAC;CAC3B;AACD,MAAM,WAAW,kBAAmB,SAAQ,IAAI,CAAC,qBAAqB,EAAE,aAAa,CAAC;IACpF,WAAW,EAAE,WAAW,CAAC;CAC1B;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAgC3D;AACD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,qBAAqB,CAmCxE;AACD,wBAAgB,uBAAuB,CACrC,WAAW,EAAE,qBAAqB,EAClC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,GACtB,IAAI,CAUN;AAyBD,4FAA4F;AAC5F,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,qBAAqB,EAClC,SAAS,EAAE,SAAS,UAAU,EAAE,EAChC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,GAChC,kBAAkB,CAgLpB"}