@actiondock/core 2.7.0 → 2.8.0

package/dist/catalog/graph.js

@@ -0,0 +1,589 @@
+import { existsSync, readFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { ActionDockError, ACTION_PACKAGE_VERSION_CONFLICT, PACKAGE_NOT_FOUND, UNDECLARED_ACTION_DEPENDENCY, } from "../errors.js";
+import { computeManifestDigest, parseJsonWithoutDuplicates } from "../project/digest.js";
+import { loadLockfile } from "../project/lockfile.js";
+import { loadPlaybooks, loadProjectConfig } from "../project/loader.js";
+import { loadManifest, MANIFEST_FILE_NAME } from "../project/manifest.js";
+import { listLinkedPackages } from "../registry/registry.js";
+import { createPackageIdentity } from "../runtime/identity.js";
+import { parseSemVer } from "../utils/index.js";
+import { PackageDiscovery } from "./discovery.js";
+export { parseSemVer };
+/**
+ * 校验两个语义化版本范围是否兼容并能收敛为单一解析版本。
+ * 遵循设计规范：直接或传递版本范围无法收敛时拒绝并抛出 ACTION_PACKAGE_VERSION_CONFLICT。
+ */
+export function areVersionsCompatible(v1, v2) {
+    if (v1 === v2 || v1 === "*" || v2 === "*" || !v1 || !v2) {
+        return true;
+    }
+    const clean1 = v1.trim().replace(/^[\^~=]/, "");
+    const clean2 = v2.trim().replace(/^[\^~=]/, "");
+    const sem1 = parseSemVer(clean1);
+    const sem2 = parseSemVer(clean2);
+    if (!sem1 || !sem2) {
+        return v1 === v2;
+    }
+    if (sem1.major !== sem2.major) {
+        return false;
+    }
+    if (v1.startsWith("~") || v2.startsWith("~")) {
+        if (sem1.minor !== sem2.minor) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * 版本冲突错误。
+ */
+export class ActionPackageVersionConflictError extends ActionDockError {
+    packageId;
+    conflicts;
+    constructor(packageId, conflicts) {
+        const details = conflicts.map((c) => `'${c.requester}' 要求 '${c.rangeOrVersion}'`).join(", ");
+        super(ACTION_PACKAGE_VERSION_CONFLICT, `ACTION_PACKAGE_VERSION_CONFLICT: 逻辑包 '${packageId}' 存在不可收敛的版本冲突: ${details}`);
+        this.name = "ActionPackageVersionConflictError";
+        this.packageId = packageId;
+        this.conflicts = conflicts;
+        Object.setPrototypeOf(this, ActionPackageVersionConflictError.prototype);
+    }
+}
+/**
+ * 未声明依赖调用拦截错误。
+ */
+export class UndeclaredActionDependencyError extends ActionDockError {
+    targetRef;
+    caller;
+    constructor(targetRef, caller, reason) {
+        const msg = caller
+            ? `UNDECLARED_ACTION_DEPENDENCY: Action '${caller}' 未在 'uses' 中声明对 '${targetRef}' 的跨包依赖`
+            : `UNDECLARED_ACTION_DEPENDENCY: 根调用 Action '${targetRef}' 被拒绝: 目标包既非 actiondock.json 直接依赖，亦未被可见 Playbook 委托${reason ? ` (${reason})` : ""}`;
+        super(UNDECLARED_ACTION_DEPENDENCY, msg);
+        this.name = "UndeclaredActionDependencyError";
+        this.targetRef = targetRef;
+        this.caller = caller;
+        Object.setPrototypeOf(this, UndeclaredActionDependencyError.prototype);
+    }
+}
+/**
+ * 判定单一 uses 声明项是否命中目标 Action（跨包调用授权单一事实源）。
+ *
+ * 匹配语义（安全铁律，逐字不变）：
+ * - 完全限定名：`<targetPackageId>/<targetActionId>`；
+ * - 包级通配符：`<targetPackageId>/*`；
+ * - 裸包名：`<targetPackageId>`。
+ *
+ * DefaultPackageGraph.canCascadeCall 与 InvocationPolicy.checkUsesAuthorization
+ * 必须统一经由本谓词判定，禁止在调用点另建重复表达式分叉。
+ */
+export function isUsesDeclared(use, targetPackageId, targetActionId) {
+    return (use === `${targetPackageId}/${targetActionId}` ||
+        use === `${targetPackageId}/*` ||
+        use === targetPackageId);
+}
+/**
+ * 默认包依赖图实现。
+ */
+export class DefaultPackageGraph {
+    packages;
+    root;
+    visiblePlaybooks;
+    delegatedActions;
+    constructor(packages, root, visiblePlaybooks, delegatedActions) {
+        this.packages = packages;
+        this.root = root;
+        this.visiblePlaybooks = visiblePlaybooks ?? new Map();
+        this.delegatedActions = delegatedActions ?? new Set();
+    }
+    get rootPackageId() {
+        return this.root?.id;
+    }
+    get directDependencyIds() {
+        if (!this.root)
+            return new Set();
+        const rootNode = this.packages.get(this.root.id);
+        return rootNode ? rootNode.directDependencies : new Set();
+    }
+    get transitiveDependencyIds() {
+        if (!this.root)
+            return new Set();
+        const rootNode = this.packages.get(this.root.id);
+        return rootNode ? rootNode.transitiveDependencies : new Set();
+    }
+    getPackage(id) {
+        return this.packages.get(id);
+    }
+    getNode(id) {
+        return this.packages.get(id);
+    }
+    hasPackage(id) {
+        return this.packages.has(id);
+    }
+    canRootCall(targetPackageId, targetActionId) {
+        if (this.root && targetPackageId === this.root.id) {
+            return true;
+        }
+        if (this.directDependencyIds.has(targetPackageId)) {
+            return true;
+        }
+        const qualifiedRef = `${targetPackageId}/${targetActionId}`;
+        if (this.delegatedActions.has(qualifiedRef)) {
+            return true;
+        }
+        return false;
+    }
+    assertRootCallAllowed(targetPackageId, targetActionId) {
+        if (!this.canRootCall(targetPackageId, targetActionId)) {
+            throw new UndeclaredActionDependencyError(`${targetPackageId}/${targetActionId}`);
+        }
+    }
+    canCascadeCall(callerPackageId, callerActionId, targetPackageId, targetActionId) {
+        if (callerPackageId === targetPackageId) {
+            return true;
+        }
+        const callerPkg = this.packages.get(callerPackageId);
+        if (!callerPkg) {
+            return false;
+        }
+        const callerActionEntry = callerPkg.manifest.actions?.[callerActionId];
+        const usesList = callerActionEntry?.uses || [];
+        return usesList.some((u) => isUsesDeclared(u, targetPackageId, targetActionId));
+    }
+    assertCascadeCallAllowed(callerPackageId, callerActionId, targetPackageId, targetActionId) {
+        if (!this.canCascadeCall(callerPackageId, callerActionId, targetPackageId, targetActionId)) {
+            throw new UndeclaredActionDependencyError(`${targetPackageId}/${targetActionId}`, `${callerPackageId}/${callerActionId}`);
+        }
+    }
+}
+/**
+ * 构建包节点公共字段（单一事实源：模式 A/B/C 共用，避免节点构造字面量三处拷贝）。
+ */
+function createPackageNodeFields(params) {
+    const digest = computeManifestDigest(params.manifest);
+    const identity = params.identity ??
+        createPackageIdentity({
+            id: params.id,
+            instanceId: `${params.id}:${params.root}`,
+            generation: params.generation ?? "",
+        });
+    return {
+        identity,
+        packageId: params.id,
+        root: params.root,
+        manifest: params.manifest,
+        manifestDigest: digest,
+        version: params.manifest.version || "0.1.0",
+        npmPackage: params.npmPackage,
+        directDependencies: new Set(),
+        transitiveDependencies: new Set(),
+        isDirect: params.isDirect,
+        isRoot: params.isRoot,
+    };
+}
+/**
+ * 从各包清单的 dependencies 中补全直接依赖边（仅计入图中已存在的包）。
+ */
+function linkDirectDependencies(nodes) {
+    for (const node of nodes.values()) {
+        if (node.manifest.dependencies && typeof node.manifest.dependencies === "object") {
+            for (const depId of Object.keys(node.manifest.dependencies)) {
+                if (nodes.has(depId)) {
+                    node.directDependencies.add(depId);
+                }
+            }
+        }
+    }
+}
+/**
+ * 以 BFS 计算每个节点的传递依赖闭包（单一事实源，自带环防护）。
+ */
+function computeTransitiveDependencies(nodes) {
+    for (const node of nodes.values()) {
+        const q = Array.from(node.directDependencies);
+        const visited = new Set(node.directDependencies);
+        while (q.length > 0) {
+            const curr = q.shift();
+            node.transitiveDependencies.add(curr);
+            const depNode = nodes.get(curr);
+            if (depNode) {
+                for (const next of depNode.directDependencies) {
+                    if (next !== node.identity.id && !visited.has(next)) {
+                        visited.add(next);
+                        q.push(next);
+                    }
+                }
+            }
+        }
+    }
+}
+/**
+ * 聚合根包与其直接依赖包的可见 Playbook 及委托点名的 Action（单一事实源）。
+ */
+function collectVisiblePlaybooks(rootNode, nodes) {
+    const visiblePlaybooks = new Map();
+    const delegatedActions = new Set();
+    if (rootNode && rootNode.root && existsSync(rootNode.root)) {
+        try {
+            const rootPbs = loadPlaybooks(rootNode.root, undefined, rootNode.manifest);
+            for (const [id, pb] of rootPbs.entries()) {
+                visiblePlaybooks.set(id, pb);
+                visiblePlaybooks.set(`${rootNode.packageId}/${id}`, pb);
+            }
+        }
+        catch {
+            // 忽略根包 Playbook 加载异常
+        }
+        for (const depId of rootNode.directDependencies) {
+            if (depId === rootNode.packageId)
+                continue;
+            const depNode = nodes.get(depId);
+            if (depNode && depNode.root && existsSync(depNode.root)) {
+                try {
+                    const depPbs = loadPlaybooks(depNode.root, undefined, depNode.manifest);
+                    for (const [id, pb] of depPbs.entries()) {
+                        visiblePlaybooks.set(`${depId}/${id}`, pb);
+                    }
+                }
+                catch {
+                    // 忽略依赖包 Playbook 加载异常
+                }
+            }
+        }
+    }
+    for (const pb of visiblePlaybooks.values()) {
+        if (Array.isArray(pb.actions)) {
+            for (const actRef of pb.actions) {
+                if (typeof actRef === "string" && actRef.trim()) {
+                    delegatedActions.add(actRef.trim());
+                }
+            }
+        }
+    }
+    return { visiblePlaybooks, delegatedActions };
+}
+/**
+ * 包依赖拓扑图构建器 PackageGraphBuilder。
+ * 输入发现的包集合或工程根目录，统一实施版本冲突检测、lockfile 校验与拓扑图构建。
+ */
+export class PackageGraphBuilder {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    /**
+     * 同步构建包依赖拓扑图（模式 A：显式包集合）。
+     */
+    buildFromPackages(nodes, generation) {
+        for (const pkg of this.options.packages) {
+            const fields = createPackageNodeFields({
+                id: pkg.id,
+                root: pkg.root,
+                manifest: pkg.manifest,
+                npmPackage: pkg.id,
+                isDirect: Boolean(pkg.isCurrentProject),
+                isRoot: Boolean(pkg.isCurrentProject),
+                identity: pkg.identity,
+                generation,
+            });
+            nodes.set(pkg.id, fields);
+        }
+        let rootIdentity;
+        if (this.options.root) {
+            if (nodes.has(this.options.root)) {
+                rootIdentity = nodes.get(this.options.root).identity;
+            }
+            else {
+                const absRoot = resolve(this.options.root);
+                for (const node of nodes.values()) {
+                    if (resolve(node.root) === absRoot) {
+                        rootIdentity = node.identity;
+                        break;
+                    }
+                }
+            }
+        }
+        if (!rootIdentity) {
+            for (const node of nodes.values()) {
+                if (node.isRoot) {
+                    rootIdentity = node.identity;
+                    break;
+                }
+            }
+        }
+        if (rootIdentity) {
+            const rootNode = nodes.get(rootIdentity.id);
+            if (rootNode) {
+                rootNode.isRoot = true;
+                rootNode.isDirect = true;
+            }
+        }
+        linkDirectDependencies(nodes);
+        computeTransitiveDependencies(nodes);
+        const effectiveRootNode = rootIdentity ? nodes.get(rootIdentity.id) : undefined;
+        const { visiblePlaybooks, delegatedActions } = collectVisiblePlaybooks(effectiveRootNode, nodes);
+        return new DefaultPackageGraph(nodes, rootIdentity, visiblePlaybooks, delegatedActions);
+    }
+    /**
+     * 同步构建包依赖拓扑图（模式 C：全局包发现）。
+     */
+    buildFromGlobalDiscovery(nodes, generation) {
+        const discOpts = {
+            ...this.options.discoveryOptions,
+            customHome: this.options.discoveryOptions?.customHome ?? this.options.customHome,
+            scanLinkedPackages: this.options.discoveryOptions?.scanLinkedPackages ?? this.options.allowDevLinks ?? true,
+        };
+        const discovered = new PackageDiscovery(discOpts).discoverSync();
+        for (const pkg of discovered) {
+            const fields = createPackageNodeFields({
+                id: pkg.id,
+                root: pkg.root,
+                manifest: pkg.manifest,
+                npmPackage: pkg.id,
+                isDirect: Boolean(pkg.isCurrentProject),
+                isRoot: Boolean(pkg.isCurrentProject),
+                generation,
+            });
+            nodes.set(pkg.id, fields);
+        }
+        return new DefaultPackageGraph(nodes);
+    }
+    /**
+     * 同步构建包依赖拓扑图。
+     */
+    buildSync() {
+        const projectRoot = this.options.projectRoot || this.options.root;
+        const absProjectRoot = projectRoot ? resolve(projectRoot) : undefined;
+        const generation = this.options.generationId || crypto.randomUUID();
+        const nodes = new Map();
+        // 模式 A：显式包集合模式（由 Host.rebuildGraphAndCatalog 或测试直接传入已发现包）
+        if (this.options.packages) {
+            return this.buildFromPackages(nodes, generation);
+        }
+        // 模式 B：单工程或根目录依赖解析闭包构建
+        if (absProjectRoot) {
+            let rootManifest = this.options.manifest;
+            if (!rootManifest && existsSync(absProjectRoot)) {
+                try {
+                    rootManifest = loadManifest(absProjectRoot) || loadProjectConfig(absProjectRoot);
+                }
+                catch {
+                    // 忽略清单加载异常
+                }
+            }
+            if (!rootManifest) {
+                rootManifest = {
+                    id: basename(absProjectRoot),
+                    version: "0.1.0",
+                };
+            }
+            const rootPackageId = rootManifest.id;
+            const rootIdentity = createPackageIdentity({
+                id: rootPackageId,
+                instanceId: `${rootPackageId}:${absProjectRoot}`,
+                generation,
+            });
+            const rootNode = {
+                ...createPackageNodeFields({
+                    id: rootPackageId,
+                    root: absProjectRoot,
+                    manifest: rootManifest,
+                    npmPackage: rootPackageId,
+                    isDirect: true,
+                    isRoot: true,
+                    identity: rootIdentity,
+                }),
+            };
+            nodes.set(rootPackageId, rootNode);
+            const lockfile = this.options.lockfile ?? loadLockfile(absProjectRoot);
+            const devLinkMap = new Map();
+            const scanLinked = Boolean(this.options.discoveryOptions?.scanLinkedPackages ?? this.options.allowDevLinks);
+            if (scanLinked) {
+                try {
+                    const linked = listLinkedPackages(this.options.customHome);
+                    for (const entry of linked) {
+                        if (existsSync(entry.path)) {
+                            devLinkMap.set(entry.id, entry.path);
+                        }
+                    }
+                }
+                catch {
+                    // 忽略扫描外部链接包异常
+                }
+            }
+            const versionRequirements = new Map();
+            function recordRequirement(pkgId, requester, rangeOrVersion) {
+                const existing = versionRequirements.get(pkgId) || [];
+                for (const req of existing) {
+                    if (!areVersionsCompatible(req.rangeOrVersion, rangeOrVersion)) {
+                        throw new ActionPackageVersionConflictError(pkgId, [
+                            req,
+                            { requester, rangeOrVersion },
+                        ]);
+                    }
+                }
+                existing.push({ requester, rangeOrVersion });
+                versionRequirements.set(pkgId, existing);
+            }
+            const queue = [];
+            for (const [depId, spec] of Object.entries(rootManifest.dependencies || {})) {
+                rootNode.directDependencies.add(depId);
+                recordRequirement(depId, rootPackageId, spec);
+                queue.push({
+                    pkgId: depId,
+                    requester: rootPackageId,
+                    rangeOrSpec: spec,
+                    isDirect: true,
+                });
+            }
+            const packageRootsRecord = this.options.packageRoots && !Array.isArray(this.options.packageRoots)
+                ? this.options.packageRoots
+                : undefined;
+            while (queue.length > 0) {
+                const item = queue.shift();
+                if (nodes.has(item.pkgId)) {
+                    const existingNode = nodes.get(item.pkgId);
+                    const pkgVer = existingNode.version || existingNode.manifest.version || "0.1.0";
+                    const reqs = versionRequirements.get(item.pkgId) || [];
+                    for (const req of reqs) {
+                        if (!areVersionsCompatible(req.rangeOrVersion, pkgVer)) {
+                            throw new ActionPackageVersionConflictError(item.pkgId, [
+                                req,
+                                { requester: item.pkgId, rangeOrVersion: pkgVer },
+                            ]);
+                        }
+                    }
+                    continue;
+                }
+                let pkgDir = null;
+                const locked = lockfile?.packages?.[item.pkgId];
+                if (packageRootsRecord?.[item.pkgId]) {
+                    pkgDir = packageRootsRecord[item.pkgId];
+                }
+                else if (devLinkMap.has(item.pkgId)) {
+                    pkgDir = devLinkMap.get(item.pkgId);
+                }
+                else {
+                    const candidateNames = [];
+                    if (locked?.npmPackage) {
+                        candidateNames.push(locked.npmPackage);
+                    }
+                    candidateNames.push(item.rangeOrSpec);
+                    candidateNames.push(item.pkgId);
+                    let cur = absProjectRoot;
+                    while (true) {
+                        for (const candName of candidateNames) {
+                            const candPath = join(cur, "node_modules", candName);
+                            if (existsSync(candPath) && existsSync(join(candPath, MANIFEST_FILE_NAME))) {
+                                pkgDir = candPath;
+                                break;
+                            }
+                        }
+                        if (pkgDir)
+                            break;
+                        const parent = dirname(cur);
+                        if (parent === cur)
+                            break;
+                        cur = parent;
+                    }
+                }
+                if (!pkgDir || !existsSync(pkgDir)) {
+                    throw new ActionDockError(PACKAGE_NOT_FOUND, `PACKAGE_NOT_FOUND: Package '${item.pkgId}' required by '${item.requester}' is not installed in ${absProjectRoot}. Please run 'ad add ${item.rangeOrSpec}'.`);
+                }
+                const manifestPath = join(pkgDir, MANIFEST_FILE_NAME);
+                if (!existsSync(manifestPath)) {
+                    throw new Error(`Action package '${item.pkgId}' at '${pkgDir}' misses required manifest 'actiondock.json'`);
+                }
+                let manifestRaw;
+                try {
+                    manifestRaw = readFileSync(manifestPath, "utf-8");
+                }
+                catch (err) {
+                    throw new Error(`Failed to read manifest for '${item.pkgId}': ${err.message}`);
+                }
+                const depManifest = parseJsonWithoutDuplicates(manifestRaw);
+                const actualDigest = computeManifestDigest(depManifest);
+                if (locked?.manifestDigest && locked.manifestDigest !== actualDigest) {
+                    throw new Error(`Manifest digest mismatch for package '${item.pkgId}': expected '${locked.manifestDigest}', got '${actualDigest}'. Re-resolution required.`);
+                }
+                const pkgVersion = depManifest.version || locked?.version || "0.1.0";
+                const reqs = versionRequirements.get(item.pkgId) || [];
+                for (const req of reqs) {
+                    if (!areVersionsCompatible(req.rangeOrVersion, pkgVersion)) {
+                        throw new ActionPackageVersionConflictError(item.pkgId, [
+                            req,
+                            { requester: item.pkgId, rangeOrVersion: pkgVersion },
+                        ]);
+                    }
+                }
+                const identity = createPackageIdentity({
+                    id: item.pkgId,
+                    instanceId: `${item.pkgId}:${pkgDir}`,
+                    generation,
+                });
+                const newNode = {
+                    ...createPackageNodeFields({
+                        id: item.pkgId,
+                        root: pkgDir,
+                        manifest: depManifest,
+                        npmPackage: locked?.npmPackage || item.rangeOrSpec,
+                        isDirect: item.isDirect,
+                        isRoot: false,
+                        identity,
+                    }),
+                };
+                nodes.set(item.pkgId, newNode);
+                for (const [subDepId, subSpec] of Object.entries(depManifest.dependencies || {})) {
+                    recordRequirement(subDepId, item.pkgId, subSpec);
+                    if (!nodes.has(subDepId)) {
+                        queue.push({
+                            pkgId: subDepId,
+                            requester: item.pkgId,
+                            rangeOrSpec: subSpec,
+                            isDirect: false,
+                        });
+                    }
+                }
+            }
+            if (scanLinked) {
+                for (const [devPkgId, devPkgDir] of devLinkMap.entries()) {
+                    if (devPkgId !== rootPackageId && !nodes.has(devPkgId) && existsSync(devPkgDir)) {
+                        const manifestPath = join(devPkgDir, MANIFEST_FILE_NAME);
+                        if (!existsSync(manifestPath))
+                            continue;
+                        try {
+                            const manifestRaw = readFileSync(manifestPath, "utf-8");
+                            const devManifest = parseJsonWithoutDuplicates(manifestRaw);
+                            nodes.set(devPkgId, createPackageNodeFields({
+                                id: devPkgId,
+                                root: devPkgDir,
+                                manifest: devManifest,
+                                npmPackage: devPkgId,
+                                isDirect: true,
+                                isRoot: false,
+                                generation,
+                            }));
+                            rootNode.directDependencies.add(devPkgId);
+                        }
+                        catch {
+                            // 忽略解析失败的链接包
+                        }
+                    }
+                }
+            }
+            linkDirectDependencies(nodes);
+            computeTransitiveDependencies(nodes);
+            const { visiblePlaybooks, delegatedActions } = collectVisiblePlaybooks(rootNode, nodes);
+            return new DefaultPackageGraph(nodes, rootIdentity, visiblePlaybooks, delegatedActions);
+        }
+        // 模式 C：全局包发现构建
+        return this.buildFromGlobalDiscovery(nodes, generation);
+    }
+    /**
+     * 异步构建包依赖拓扑图。
+     */
+    async build() {
+        return this.buildSync();
+    }
+}

package/dist/catalog/index.d.ts

@@ -1,5 +1,5 @@
-export * from "./action-index.js";
-export * from "./action-resolver.js";
-export * from "./location-registry.js";
-export * from "./package-catalog.js";
-export * from "./types.js";
+export * from "./action-catalog.js";
+export * from "./discovery.js";
+export * from "./graph.js";
+export * from "./resolve-action.js";
+export * from "./resolve-playbook.js";

package/dist/catalog/index.js

@@ -1,5 +1,5 @@
-export * from "./action-index.js";
-export * from "./action-resolver.js";
-export * from "./location-registry.js";
-export * from "./package-catalog.js";
-export * from "./types.js";
+export * from "./action-catalog.js";
+export * from "./discovery.js";
+export * from "./graph.js";
+export * from "./resolve-action.js";
+export * from "./resolve-playbook.js";

package/dist/catalog/resolve-action.d.ts

@@ -0,0 +1,43 @@
+import type { ActionContract, ActionRef, ResolvedActionRef } from "@actiondock/sdk";
+import type { PackageIdentity } from "../runtime/identity.js";
+import type { ActionCatalog } from "./action-catalog.js";
+import type { PackageGraph } from "./graph.js";
+/**
+ * ActionRef 解析上下文。
+ */
+export interface ResolveActionContext {
+    /** 当前调用方包身份或包标识（可选） */
+    caller?: PackageIdentity | string;
+    /** 包拓扑图单一事实源 */
+    graph: PackageGraph;
+    /** 动作目录索引单一事实源 */
+    catalog: ActionCatalog;
+}
+/**
+ * Action 解析最终结果。
+ */
+export interface ResolvedAction {
+    /** 规范化解析引用值对象 */
+    readonly ref: ResolvedActionRef;
+    /** 目标包身份标识值对象 */
+    readonly package: PackageIdentity;
+    /** 动作入口文件相对路径 */
+    readonly entry: string;
+    /** 动作契约元数据规范 */
+    readonly contract: ActionContract;
+}
+/**
+ * 规范化解析动作引用字符串或对象为 ActionRef。
+ * 铁律：ActionRef 解析只有一个事实源。
+ */
+export declare function parseActionRef(ref: ActionRef | string): ActionRef;
+/**
+ * 纯领域动作解析函数 resolveAction。
+ * 铁律：ActionRef 解析只有一个事实源，禁止各模块各自编写短名匹配或启发式搜索。
+ *
+ * 解析次序：
+ * 1. 显式包限定标识符精确查找目标包与动作
+ * 2. 裸标识符优先查找 caller 调用者所在包
+ * 3. 裸标识符全局搜索：单命中返回、多命中抛出歧义异常、零命中抛出未找到异常
+ */
+export declare function resolveAction(ref: ActionRef | string, context: ResolveActionContext): ResolvedAction;