@pulsemcp/air-core 0.0.42 → 0.1.1

package/README.md

@@ -24,8 +24,8 @@ const artifacts = await resolveArtifacts("~/.air/air.json");
 // Validate a JSON file against its AIR schema
 const result = validateJson(data, "skills");
 
-// Merge two artifact sets (later wins for matching IDs)
-const merged = mergeArtifacts(base, override);
+// Merge two artifact sets (additive union — duplicate qualified IDs throw)
+const merged = mergeArtifacts(base, overlay);
 ```
 
 ### With a Catalog Provider (remote URIs)

package/dist/config.d.ts

@@ -18,6 +18,11 @@ export interface ResolveOptions {
      * (e.g., `gitProtocol`). Providers ignore unknown keys.
      */
     providerOptions?: Record<string, unknown>;
+    /**
+     * Sink for non-fatal warnings (e.g. cross-scope shortname collisions, stale
+     * `exclude` entries). When omitted, core writes warnings to `console.warn`.
+     */
+    onWarning?: (message: string) => void;
 }
 /**
  * Merge air.json-level provider fields with runtime overrides and dispatch
@@ -34,28 +39,40 @@ export interface ResolveOptions {
 export declare function configureProviders(providers: CatalogProvider[], airConfig: AirConfig, providerOptions?: Record<string, unknown>): void;
 /**
  * Resolve all artifacts from an air.json file.
- * Each artifact property is an array of paths; files merge in order.
- * Remote URIs are delegated to the matching CatalogProvider.
  *
- * `catalogs` entries are expanded first via directory-walking discovery —
- * each catalog is resolved to a local directory (cloned by the relevant
- * provider for remote URIs) and walked up to `CATALOG_MAX_DEPTH` levels
- * for artifact index files. Files are identified by `$schema` (preferred)
- * or filename, and grouped by artifact type. Skip-listed directories
- * (node_modules, .git, dist, build, etc.) and entries matched by a
- * root-level `.gitignore` are not descended into. Explicit per-type
- * arrays layer on top of catalog-discovered indexes.
+ * Every artifact is canonically `@scope/id`:
+ *   - Catalog providers supply scope via `getScope(uri)` (e.g. the GitHub
+ *     provider returns `owner/repo`).
+ *   - Local catalogs and per-type arrays default to scope `local`.
+ *
+ * Composition is union-only: catalogs and per-type arrays *contribute*
+ * artifacts. The only way to remove an artifact is via `air.json#exclude`,
+ * which lists qualified IDs to drop from the resolved set. Two contributors
+ * producing the same qualified ID hard-fail; same shortname under different
+ * scopes warns and both qualified IDs appear in the result.
  *
- * All `path` fields in resolved entries are absolute paths,
- * making artifacts self-contained regardless of source location.
+ * Reference fields inside artifact bodies (skill.references, plugin.skills,
+ * root.default_skills, …) are canonicalized to qualified IDs at resolution
+ * time. References inside a catalog's own indexes resolve to that catalog's
+ * scope first; cross-catalog references must use the qualified form when
+ * the shortname is ambiguous.
+ *
+ * All `path` fields are absolute, making artifacts self-contained regardless
+ * of source location.
  */
 export declare function resolveArtifacts(airJsonPath: string, options?: ResolveOptions): Promise<ResolvedArtifacts>;
 /**
- * Merge two resolved artifact sets. Override wins for matching IDs.
- * Composite plugins are re-expanded after merging so that newly
- * added plugins that reference existing ones are fully resolved.
+ * Combine two resolved artifact sets by union. Inputs must already be
+ * qualified (`@scope/id`); a duplicate qualified ID across the two inputs
+ * is rejected with a clear diagnostic. Composite plugins are re-expanded
+ * after merging.
+ *
+ * `mergeArtifacts` is a low-level helper used to layer two pre-resolved
+ * sets — for example, an external orchestrator merging a parent session's
+ * artifacts with a subagent's. Most callers should compose at the air.json
+ * level (catalogs + exclude) instead.
  */
-export declare function mergeArtifacts(base: ResolvedArtifacts, override: ResolvedArtifacts): ResolvedArtifacts;
+export declare function mergeArtifacts(base: ResolvedArtifacts, overlay: ResolvedArtifacts): ResolvedArtifacts;
 /**
  * Recursively expand plugin references.
  *
@@ -66,12 +83,12 @@ export declare function mergeArtifacts(base: ResolvedArtifacts, override: Resolv
  * not a runtime concept.
  *
  * Semantics:
- * - Child plugins are expanded depth-first in declaration order
- * - Parent's direct declarations override children (later wins via dedup)
- * - Circular references are rejected with a clear error message
- * - Plugins without a `plugins` field are returned unchanged
- * - The `plugins` array on each entry is preserved as metadata (e.g., for
- *   UI display of the dependency graph) even though primitives are inlined
+ * - All IDs are already qualified (`@scope/id`) at this stage.
+ * - Child plugins are expanded depth-first in declaration order.
+ * - Parent's direct declarations come last (later wins via dedup).
+ * - Circular references are rejected with a clear error message.
+ * - Plugins without a `plugins` field are returned unchanged.
+ * - The `plugins` array on each entry is preserved as metadata.
  *
  * Returns a new ResolvedArtifacts object; the input is not mutated.
  */

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,SAAS,EACT,iBAAiB,EAOjB,eAAe,EAChB,MAAM,YAAY,CAAC;AAoGpB,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAG5D;AAED;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,CAM9C;AAED;;;GAGG;AACH,wBAAgB,cAAc,IAAI,MAAM,GAAG,IAAI,CAG9C;AAED,MAAM,WAAW,cAAc;IAC7B,2EAA2E;IAC3E,SAAS,CAAC,EAAE,eAAe,EAAE,CAAC;IAC9B;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC3C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,eAAe,EAAE,EAC5B,SAAS,EAAE,SAAS,EACpB,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACxC,IAAI,CAwBN;AAsOD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,iBAAiB,CAAC,CAkD5B;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,iBAAiB,EACvB,QAAQ,EAAE,iBAAiB,GAC1B,iBAAiB,CASnB;AAmBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,iBAAiB,GAAG,iBAAiB,CAiF7E;AAED,wBAAgB,cAAc,IAAI,iBAAiB,CASlD"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,SAAS,EACT,iBAAiB,EAOjB,eAAe,EAChB,MAAM,YAAY,CAAC;AAkNpB,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAG5D;AAED;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,CAM9C;AAED;;;GAGG;AACH,wBAAgB,cAAc,IAAI,MAAM,GAAG,IAAI,CAG9C;AAED,MAAM,WAAW,cAAc;IAC7B,2EAA2E;IAC3E,SAAS,CAAC,EAAE,eAAe,EAAE,CAAC;IAC9B;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C;;;OAGG;IACH,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACvC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,eAAe,EAAE,EAC5B,SAAS,EAAE,SAAS,EACpB,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACxC,IAAI,CAwBN;AAufD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,iBAAiB,CAAC,CAgF5B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,iBAAiB,EACvB,OAAO,EAAE,iBAAiB,GACzB,iBAAiB,CA2BnB;AAmBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,iBAAiB,GAAG,iBAAiB,CAiF7E;AAED,wBAAgB,cAAc,IAAI,iBAAiB,CASlD"}

package/dist/config.js

@@ -2,6 +2,7 @@ import { readFileSync, readdirSync, existsSync } from "fs";
 import { resolve, dirname } from "path";
 import ignore from "ignore";
 import { detectSchemaType, detectSchemaFromValue, } from "./schemas.js";
+import { deriveScope, qualifyId, parseQualifiedId, isQualified, resolveReference, } from "./scope.js";
 function loadJsonFile(filePath) {
     if (!existsSync(filePath)) {
         return {};
@@ -43,16 +44,13 @@ function resolveEntryPaths(entries, sourceDir) {
     return resolved;
 }
 /**
- * Load and merge entries from an array of index file paths.
- * Local paths are resolved relative to baseDir.
- * URI paths (with schemes) are delegated to the matching CatalogProvider.
- *
- * After loading, relative `path` fields in entries are resolved
- * to absolute paths, so downstream consumers don't need source directory context.
+ * Load every contribution for a single artifact type and return them as a
+ * flat list. Each contribution preserves the scope of the catalog it came
+ * from so qualification can happen during merging.
  */
-async function loadAndMerge(paths, baseDir, providers) {
-    let merged = {};
-    for (const p of paths) {
+async function loadContributions(paths, baseDir, providers) {
+    const contributions = [];
+    for (const { path: p, scope } of paths) {
         const scheme = getScheme(p);
         let data;
         let sourceDir;
@@ -73,9 +71,81 @@ async function loadAndMerge(paths, baseDir, providers) {
         }
         const entries = stripSchema(data);
         const resolved = resolveEntryPaths(entries, sourceDir);
-        merged = { ...merged, ...resolved };
+        contributions.push({ scope, source: p, entries: resolved });
+    }
+    return contributions;
+}
+/**
+ * Merge per-source contributions into a single `@scope/id`-keyed map.
+ *
+ * Composition rules:
+ *   - Every entry is qualified `@scope/id` using the contribution's scope.
+ *   - Two contributions producing the same qualified ID hard-fail with a
+ *     diagnostic that names both sources.
+ *   - Two contributions producing the same shortname under different scopes
+ *     both land in the map. Cross-scope shortname collisions are reported by
+ *     {@link warnCrossScopeShortnames} *after* `exclude` runs, so excluding
+ *     one of the colliding artifacts silences the warning.
+ *
+ * Returns the merged map plus a `sources` map that records which contribution
+ * each qualified ID came from — used later for the post-exclude warning pass.
+ */
+function mergeContributions(contributions, artifactType) {
+    const merged = {};
+    const sourceByQualified = new Map();
+    for (const contribution of contributions) {
+        for (const [shortname, entry] of Object.entries(contribution.entries)) {
+            if (isQualified(shortname)) {
+                throw new Error(`Artifact index entry must use a bare shortname; got qualified ID ` +
+                    `"${shortname}" in ${contribution.source}. Scopes are assigned by ` +
+                    `the catalog source, not by authors.`);
+            }
+            const qualified = qualifyId(contribution.scope, shortname);
+            const existingSource = sourceByQualified.get(qualified);
+            if (existingSource !== undefined) {
+                throw new Error(`Duplicate ${artifactType} ID "${qualified}" produced by both ` +
+                    `"${existingSource}" and "${contribution.source}". Two catalogs ` +
+                    `with the same scope contributed the same shortname; rename one ` +
+                    `or remove the duplicate from your air.json.`);
+            }
+            sourceByQualified.set(qualified, contribution.source);
+            merged[qualified] = entry;
+        }
+    }
+    return { merged, sources: sourceByQualified };
+}
+/**
+ * Emit one warning per shortname that survives `exclude` under more than one
+ * scope. Running this after {@link applyExclude} means excluding either side
+ * of the collision silences the warning.
+ */
+function warnCrossScopeShortnames(artifacts, sourcesByType, warnings) {
+    for (const type of ARTIFACT_TYPES) {
+        const pool = artifacts[type];
+        const sources = sourcesByType[type];
+        const scopesByShortname = new Map();
+        for (const qualified of Object.keys(pool)) {
+            const { scope, id: shortname } = parseQualifiedId(qualified);
+            const source = sources.get(qualified) ?? "(unknown source)";
+            let scopeMap = scopesByShortname.get(shortname);
+            if (!scopeMap) {
+                scopeMap = new Map();
+                scopesByShortname.set(shortname, scopeMap);
+            }
+            scopeMap.set(scope, source);
+        }
+        for (const [shortname, scopeMap] of scopesByShortname) {
+            if (scopeMap.size <= 1)
+                continue;
+            const scopeList = [...scopeMap.entries()]
+                .map(([scope, source]) => `@${scope} (from ${source})`)
+                .join(", ");
+            warnings.push(`Cross-scope shortname collision: ${type} "${shortname}" is ` +
+                `provided by ${scopeMap.size} scopes — ${scopeList}. Short references ` +
+                `to "${shortname}" without a scope are ambiguous; use the qualified ` +
+                `form "@scope/${shortname}" to disambiguate.`);
+        }
     }
-    return merged;
 }
 export function loadAirConfig(airJsonPath) {
     const content = readFileSync(airJsonPath, "utf-8");
@@ -205,9 +275,7 @@ function detectIndexType(absPath, filename) {
  * within `CATALOG_MAX_DEPTH` levels, skipping `CATALOG_SKIP_DIRS`, hidden
  * entries, and anything matched by a root-level `.gitignore` if present.
  *
- * Files are returned sorted by relative path (alphabetic, depth-naive) so
- * that "later wins" collision semantics within a single catalog are stable
- * across machines and filesystems.
+ * Files are returned sorted by relative path.
  */
 function discoverCatalogIndexes(catalogDir) {
     if (!existsSync(catalogDir))
@@ -288,88 +356,311 @@ async function resolveCatalogRoot(catalog, baseDir, providers) {
     return await provider.resolveCatalogDir(catalog);
 }
 /**
- * Expand every entry in `catalogs[]` into a per-type map of absolute index
- * file paths. Each catalog is resolved to a local directory and walked for
- * artifact index files (depth-capped, gitignore-aware, skip-listed).
- *
- * Within a single catalog, files of the same type discovered at multiple
- * locations are merged in sorted relPath order with later-wins semantics —
- * the downstream `loadAndMerge` consumes the returned arrays in order and
- * applies the same "later wins by ID" rule as everywhere else in AIR.
- *
- * Across catalogs, catalogs earlier in `catalogs[]` are processed first so
- * that later catalogs override earlier ones, matching the existing contract.
+ * Expand every entry in `catalogs[]` into per-type index file paths grouped
+ * by scope. Each catalog is resolved to a local directory and walked for
+ * artifact index files (depth-capped, gitignore-aware, skip-listed); the
+ * scope assigned to those files comes from the provider's `getScope(uri)`,
+ * or `local` for filesystem catalogs and providers without `getScope`.
  */
 async function expandAllCatalogs(catalogs, baseDir, providers) {
-    const result = {
-        skills: [],
-        references: [],
-        mcp: [],
-        plugins: [],
-        roots: [],
-        hooks: [],
-    };
+    const expansions = [];
     for (const catalog of catalogs) {
         const catalogDir = await resolveCatalogRoot(catalog, baseDir, providers);
         const discovered = discoverCatalogIndexes(catalogDir);
+        const scope = deriveScope(catalog, providers);
+        const paths = {
+            skills: [],
+            references: [],
+            mcp: [],
+            plugins: [],
+            roots: [],
+            hooks: [],
+        };
         for (const entry of discovered) {
-            result[entry.type].push(entry.absPath);
+            paths[entry.type].push(entry.absPath);
+        }
+        expansions.push({ scope, paths });
+    }
+    return expansions;
+}
+/**
+ * Canonicalize every reference field in an artifact body to its qualified
+ * form. References that fail to resolve (missing or ambiguous) populate
+ * `errors` so callers can fail composition with all problems at once.
+ *
+ * `fromScope` is the scope of the artifact that owns the reference — used
+ * to apply the intra-catalog rule (a short reference inside a catalog binds
+ * to that catalog's scope first).
+ */
+function canonicalizeReferences(artifacts, excluded, errors) {
+    const result = {
+        skills: { ...artifacts.skills },
+        references: { ...artifacts.references },
+        mcp: { ...artifacts.mcp },
+        plugins: { ...artifacts.plugins },
+        roots: { ...artifacts.roots },
+        hooks: { ...artifacts.hooks },
+    };
+    /**
+     * For a `missing` reference, decide whether the target was specifically
+     * dropped by `air.json#exclude`. Exact qualified-ID match wins; otherwise a
+     * short reference matches any excluded entry whose shortname matches `ref`.
+     * The list of matching excluded IDs is returned so the error can name them.
+     */
+    function excludedMatches(ref) {
+        if (isQualified(ref)) {
+            return excluded.has(ref) ? [ref] : [];
+        }
+        const matches = [];
+        for (const id of excluded) {
+            if (parseQualifiedId(id).id === ref)
+                matches.push(id);
+        }
+        return matches;
+    }
+    function resolveList(list, pool, fromScope, poolType, ownerLabel, field) {
+        if (!list)
+            return undefined;
+        const out = [];
+        for (const ref of list) {
+            const res = resolveReference(pool, ref, fromScope);
+            if (res.status === "ok") {
+                out.push(res.qualified);
+            }
+            else if (res.status === "missing") {
+                const matches = excludedMatches(ref);
+                if (matches.length > 0) {
+                    errors.push(`${ownerLabel}.${field} references ${poolType} "${ref}", ` +
+                        `which is removed by air.json#exclude (${matches.join(", ")}). ` +
+                        `Drop the exclude entry or also remove every artifact that ` +
+                        `references it.`);
+                }
+                else {
+                    errors.push(`${ownerLabel}.${field} references unknown ${poolType} "${ref}". ` +
+                        `Available qualified IDs: ${listIds(pool)}.`);
+                }
+            }
+            else {
+                errors.push(`${ownerLabel}.${field} reference "${ref}" is ambiguous across ` +
+                    `scopes — candidates: ${res.candidates.join(", ")}. ` +
+                    `Use the qualified form to disambiguate.`);
+            }
+        }
+        return out;
+    }
+    function processOwner(qualified, owner) {
+        const { scope } = parseQualifiedId(qualified);
+        const ownerLabel = qualified;
+        if (owner.kind === "skill" || owner.kind === "hook") {
+            const next = { ...owner.entry };
+            next.references = resolveList(next.references, result.references, scope, "reference", ownerLabel, "references");
+            if (owner.kind === "skill")
+                result.skills[qualified] = next;
+            else
+                result.hooks[qualified] = next;
+        }
+        else if (owner.kind === "plugin") {
+            const next = { ...owner.entry };
+            next.skills = resolveList(next.skills, result.skills, scope, "skill", ownerLabel, "skills");
+            next.mcp_servers = resolveList(next.mcp_servers, result.mcp, scope, "mcp", ownerLabel, "mcp_servers");
+            next.hooks = resolveList(next.hooks, result.hooks, scope, "hook", ownerLabel, "hooks");
+            next.plugins = resolveList(next.plugins, result.plugins, scope, "plugin", ownerLabel, "plugins");
+            result.plugins[qualified] = next;
         }
+        else {
+            const next = { ...owner.entry };
+            next.default_skills = resolveList(next.default_skills, result.skills, scope, "skill", ownerLabel, "default_skills");
+            next.default_mcp_servers = resolveList(next.default_mcp_servers, result.mcp, scope, "mcp", ownerLabel, "default_mcp_servers");
+            next.default_plugins = resolveList(next.default_plugins, result.plugins, scope, "plugin", ownerLabel, "default_plugins");
+            next.default_hooks = resolveList(next.default_hooks, result.hooks, scope, "hook", ownerLabel, "default_hooks");
+            next.default_subagent_roots = resolveList(next.default_subagent_roots, result.roots, scope, "root", ownerLabel, "default_subagent_roots");
+            result.roots[qualified] = next;
+        }
+    }
+    for (const [qualified, entry] of Object.entries(artifacts.skills)) {
+        processOwner(qualified, { kind: "skill", entry });
+    }
+    for (const [qualified, entry] of Object.entries(artifacts.hooks)) {
+        processOwner(qualified, { kind: "hook", entry });
+    }
+    for (const [qualified, entry] of Object.entries(artifacts.plugins)) {
+        processOwner(qualified, { kind: "plugin", entry });
+    }
+    for (const [qualified, entry] of Object.entries(artifacts.roots)) {
+        processOwner(qualified, { kind: "root", entry });
     }
     return result;
 }
+function listIds(pool) {
+    const keys = Object.keys(pool);
+    if (keys.length === 0)
+        return "(none)";
+    if (keys.length > 8) {
+        return `${keys.slice(0, 8).join(", ")}, … (${keys.length} total)`;
+    }
+    return keys.join(", ");
+}
+/**
+ * Apply `air.json#exclude` to a resolved artifact set. Excluded qualified IDs
+ * disappear from every artifact map; entries that don't match anything are
+ * surfaced as warnings so typos in `exclude` are visible to authors.
+ */
+function applyExclude(artifacts, exclude, warnings) {
+    if (exclude.length === 0) {
+        return { artifacts, excluded: new Set() };
+    }
+    const excludeSet = new Set();
+    for (const id of exclude) {
+        if (!isQualified(id)) {
+            throw new Error(`air.json "exclude" entries must be qualified IDs (@scope/id); got "${id}".`);
+        }
+        excludeSet.add(id);
+    }
+    const result = {
+        skills: {},
+        references: {},
+        mcp: {},
+        plugins: {},
+        roots: {},
+        hooks: {},
+    };
+    const seen = new Set();
+    for (const type of ARTIFACT_TYPES) {
+        const src = artifacts[type];
+        const dst = result[type];
+        for (const [id, entry] of Object.entries(src)) {
+            if (excludeSet.has(id)) {
+                seen.add(id);
+                continue;
+            }
+            dst[id] = entry;
+        }
+    }
+    for (const id of excludeSet) {
+        if (!seen.has(id)) {
+            warnings.push(`air.json "exclude" entry "${id}" did not match any resolved ` +
+                `artifact. Remove it or check for typos.`);
+        }
+    }
+    return { artifacts: result, excluded: excludeSet };
+}
 /**
  * Resolve all artifacts from an air.json file.
- * Each artifact property is an array of paths; files merge in order.
- * Remote URIs are delegated to the matching CatalogProvider.
  *
- * `catalogs` entries are expanded first via directory-walking discovery —
- * each catalog is resolved to a local directory (cloned by the relevant
- * provider for remote URIs) and walked up to `CATALOG_MAX_DEPTH` levels
- * for artifact index files. Files are identified by `$schema` (preferred)
- * or filename, and grouped by artifact type. Skip-listed directories
- * (node_modules, .git, dist, build, etc.) and entries matched by a
- * root-level `.gitignore` are not descended into. Explicit per-type
- * arrays layer on top of catalog-discovered indexes.
+ * Every artifact is canonically `@scope/id`:
+ *   - Catalog providers supply scope via `getScope(uri)` (e.g. the GitHub
+ *     provider returns `owner/repo`).
+ *   - Local catalogs and per-type arrays default to scope `local`.
+ *
+ * Composition is union-only: catalogs and per-type arrays *contribute*
+ * artifacts. The only way to remove an artifact is via `air.json#exclude`,
+ * which lists qualified IDs to drop from the resolved set. Two contributors
+ * producing the same qualified ID hard-fail; same shortname under different
+ * scopes warns and both qualified IDs appear in the result.
+ *
+ * Reference fields inside artifact bodies (skill.references, plugin.skills,
+ * root.default_skills, …) are canonicalized to qualified IDs at resolution
+ * time. References inside a catalog's own indexes resolve to that catalog's
+ * scope first; cross-catalog references must use the qualified form when
+ * the shortname is ambiguous.
  *
- * All `path` fields in resolved entries are absolute paths,
- * making artifacts self-contained regardless of source location.
+ * All `path` fields are absolute, making artifacts self-contained regardless
+ * of source location.
  */
 export async function resolveArtifacts(airJsonPath, options) {
     const airConfig = loadAirConfig(airJsonPath);
     const baseDir = dirname(resolve(airJsonPath));
     const providers = options?.providers || [];
     const catalogs = airConfig.catalogs || [];
+    const onWarning = options?.onWarning ?? ((msg) => console.warn(`warning: ${msg}`));
+    const warnings = [];
     // Configure providers with merged options: air.json fields are the base,
     // explicit providerOptions override them. Providers ignore unknown keys.
     configureProviders(providers, airConfig, options?.providerOptions);
-    const fromCatalogs = await expandAllCatalogs(catalogs, baseDir, providers);
-    function paths(type, explicit) {
-        return [...fromCatalogs[type], ...explicit];
+    const expansions = await expandAllCatalogs(catalogs, baseDir, providers);
+    function pathsFor(type) {
+        const list = [];
+        for (const expansion of expansions) {
+            for (const p of expansion.paths[type]) {
+                list.push({ path: p, scope: expansion.scope });
+            }
+        }
+        for (const p of airConfig[type] || []) {
+            // Per-type arrays default to LOCAL_SCOPE, but a provider URI in a
+            // per-type array still gets its provider scope so artifacts from
+            // different orgs/repos cannot collide under @local/<id>.
+            list.push({ path: p, scope: deriveScope(p, providers) });
+        }
+        return list;
+    }
+    const sourcesByType = {
+        skills: new Map(),
+        references: new Map(),
+        mcp: new Map(),
+        plugins: new Map(),
+        roots: new Map(),
+        hooks: new Map(),
+    };
+    async function load(type) {
+        const paths = pathsFor(type);
+        const contributions = await loadContributions(paths, baseDir, providers);
+        const { merged, sources } = mergeContributions(contributions, type);
+        sourcesByType[type] = sources;
+        return merged;
     }
     const resolved = {
-        skills: await loadAndMerge(paths("skills", airConfig.skills || []), baseDir, providers),
-        references: await loadAndMerge(paths("references", airConfig.references || []), baseDir, providers),
-        mcp: await loadAndMerge(paths("mcp", airConfig.mcp || []), baseDir, providers),
-        plugins: await loadAndMerge(paths("plugins", airConfig.plugins || []), baseDir, providers),
-        roots: await loadAndMerge(paths("roots", airConfig.roots || []), baseDir, providers),
-        hooks: await loadAndMerge(paths("hooks", airConfig.hooks || []), baseDir, providers),
+        skills: await load("skills"),
+        references: await load("references"),
+        mcp: await load("mcp"),
+        plugins: await load("plugins"),
+        roots: await load("roots"),
+        hooks: await load("hooks"),
     };
-    return expandPlugins(resolved);
+    // Apply exclude before reference canonicalization so dropped IDs cannot
+    // satisfy references and a clear "missing reference" error surfaces.
+    const { artifacts: filtered, excluded } = applyExclude(resolved, airConfig.exclude || [], warnings);
+    // Cross-scope shortname collisions are reported on the post-exclude pool, so
+    // excluding one side of the collision silences the warning automatically.
+    warnCrossScopeShortnames(filtered, sourcesByType, warnings);
+    const refErrors = [];
+    const canonical = canonicalizeReferences(filtered, excluded, refErrors);
+    if (refErrors.length > 0) {
+        throw new Error(`Reference resolution failed:\n  - ${refErrors.join("\n  - ")}`);
+    }
+    for (const w of warnings)
+        onWarning(w);
+    return expandPlugins(canonical);
 }
 /**
- * Merge two resolved artifact sets. Override wins for matching IDs.
- * Composite plugins are re-expanded after merging so that newly
- * added plugins that reference existing ones are fully resolved.
+ * Combine two resolved artifact sets by union. Inputs must already be
+ * qualified (`@scope/id`); a duplicate qualified ID across the two inputs
+ * is rejected with a clear diagnostic. Composite plugins are re-expanded
+ * after merging.
+ *
+ * `mergeArtifacts` is a low-level helper used to layer two pre-resolved
+ * sets — for example, an external orchestrator merging a parent session's
+ * artifacts with a subagent's. Most callers should compose at the air.json
+ * level (catalogs + exclude) instead.
  */
-export function mergeArtifacts(base, override) {
+export function mergeArtifacts(base, overlay) {
+    function unionOrThrow(a, b, label) {
+        const out = { ...a };
+        for (const [k, v] of Object.entries(b)) {
+            if (k in out) {
+                throw new Error(`mergeArtifacts: duplicate ${label} ID "${k}" in both base and overlay. ` +
+                    `Override is not supported — drop one source via air.json#exclude.`);
+            }
+            out[k] = v;
+        }
+        return out;
+    }
     return expandPlugins({
-        skills: { ...base.skills, ...override.skills },
-        references: { ...base.references, ...override.references },
-        mcp: { ...base.mcp, ...override.mcp },
-        plugins: { ...base.plugins, ...override.plugins },
-        roots: { ...base.roots, ...override.roots },
-        hooks: { ...base.hooks, ...override.hooks },
+        skills: unionOrThrow(base.skills, overlay.skills, "skill"),
+        references: unionOrThrow(base.references, overlay.references, "reference"),
+        mcp: unionOrThrow(base.mcp, overlay.mcp, "mcp"),
+        plugins: unionOrThrow(base.plugins, overlay.plugins, "plugin"),
+        roots: unionOrThrow(base.roots, overlay.roots, "root"),
+        hooks: unionOrThrow(base.hooks, overlay.hooks, "hook"),
     });
 }
 /**
@@ -398,12 +689,12 @@ function deduplicateIds(arr) {
  * not a runtime concept.
  *
  * Semantics:
- * - Child plugins are expanded depth-first in declaration order
- * - Parent's direct declarations override children (later wins via dedup)
- * - Circular references are rejected with a clear error message
- * - Plugins without a `plugins` field are returned unchanged
- * - The `plugins` array on each entry is preserved as metadata (e.g., for
- *   UI display of the dependency graph) even though primitives are inlined
+ * - All IDs are already qualified (`@scope/id`) at this stage.
+ * - Child plugins are expanded depth-first in declaration order.
+ * - Parent's direct declarations come last (later wins via dedup).
+ * - Circular references are rejected with a clear error message.
+ * - Plugins without a `plugins` field are returned unchanged.
+ * - The `plugins` array on each entry is preserved as metadata.
  *
  * Returns a new ResolvedArtifacts object; the input is not mutated.
  */