@skaile/workspaces 0.22.0-beta.0 → 0.22.0-beta.2

package/dist/{chunk-TKOLD2O7.js → chunk-LDYPQVRU.js}

@@ -1,10 +1,13 @@
-import { scanDirectory, fromMcpServerMd } from './chunk-WIR34WMU.js';
-import { parseAssetRef } from './chunk-X5Y4EGZB.js';
-import { mkdirSync, existsSync, readFileSync, writeFileSync, lstatSync, symlinkSync, rmSync, readdirSync } from 'fs';
+import { scanDirectory, parseFrontmatter, fromMcpServerMd } from './chunk-NQL3T75I.js';
+import { parseAssetRef } from './chunk-VUCPJBAG.js';
+import { mkdirSync, existsSync, readFileSync, writeFileSync, lstatSync, symlinkSync, rmSync, readdirSync, statSync } from 'fs';
 import { homedir } from 'os';
-import { join, resolve, parse as parse$1, dirname } from 'path';
+import { join, resolve, relative, parse as parse$1, dirname } from 'path';
 import { parse, stringify } from 'yaml';
 import { spawnSync } from 'child_process';
+import semver from 'semver';
+import { createHash } from 'crypto';
+import fg from 'fast-glob';
 
 function getGlobalCacheDir() {
   return process.env.SKAILE_CACHE_DIR ?? join(homedir(), ".skaile", "repos");
@@ -117,9 +120,14 @@ function ensureRepo(decl, name, reposDir, opts) {
   if (decl.path) {
     const projectDir = opts?.projectDir ?? resolve(reposDir, "..");
     const resolved = resolve(projectDir, decl.path);
-    if (!existsSync(resolved)) {
+    if (existsSync(resolved)) return resolved;
+    if (!decl.url) {
       throw new Error(`Local repository path not found: ${decl.path} (resolved: ${resolved})`);
     }
+    if (!cloneRepo(decl.url, decl.branch ?? "main", resolved)) {
+      throw new Error(`Failed to clone ${decl.url} into ${resolved}`);
+    }
+    if (opts?.pin) checkoutPin(resolved, opts.pin);
     return resolved;
   }
   if (decl.url) {
@@ -157,13 +165,25 @@ function ensureRepo(decl, name, reposDir, opts) {
   }
   throw new Error(`Repository "${name}" has neither url nor path`);
 }
+function repoSlugFromGitRemote(rootDir) {
+  const r = spawnSync("git", ["-C", rootDir, "config", "--get", "remote.origin.url"], {
+    encoding: "utf8",
+    stdio: "pipe",
+    env: GIT_ENV
+  });
+  if (r.status !== 0) return void 0;
+  const m = /github\.com[/:]([^/]+)\/([^/]+?)(?:\.git)?\/?$/.exec(r.stdout.trim());
+  return m ? `${m[1]}/${m[2]}` : void 0;
+}
 function scanRepo(repoDir, repoName) {
-  return scanDirectory(repoDir, repoName);
+  const repo = repoSlugFromGitRemote(repoDir);
+  const entries = scanDirectory(repoDir, repoName);
+  return repo ? entries.map((e) => ({ ...e, repo })) : entries;
 }
 function resolveAsset(ref, repositories, reposDir, opts) {
   let repoNames;
-  if (ref.repository) {
-    repoNames = [ref.repository];
+  if (ref.publisher) {
+    repoNames = [ref.publisher];
   } else if (opts?.preferRepo && opts.preferRepo in repositories) {
     const rest = Object.keys(repositories).filter((n) => n !== opts.preferRepo);
     repoNames = [opts.preferRepo, ...rest];
@@ -199,67 +219,149 @@ function resolveRepoDir(decl, name, reposDir, projectDir) {
   if (existsSync(join(globalDest, ".git"))) return globalDest;
   return null;
 }
-function resolveAll(deps, repositories, reposDir, opts) {
+var CanonicalRefConflictError = class extends Error {
+  constructor(ref, candidates, depChain) {
+    super(
+      [
+        `error: divergent sha256 for ${ref}`,
+        "",
+        "  pulled in via:",
+        ...depChain.map((s, i) => `    ${" ".repeat(i * 2)}${s}`),
+        "",
+        "  candidates:",
+        ...candidates.map(
+          (c) => `    ${c.sourceUrl} @ ${c.commit.slice(0, 8)}
+      sha256: ${c.sha256}`
+        ),
+        "",
+        "resolve by:",
+        "  1. removing one source from skaile.yaml,",
+        "  2. configuring a store and using its canonical digest, or",
+        "  3. adding to overrides: (with a non-empty reason:)"
+      ].join("\n")
+    );
+    this.ref = ref;
+    this.candidates = candidates;
+    this.depChain = depChain;
+    this.name = "CanonicalRefConflictError";
+  }
+  ref;
+  candidates;
+  depChain;
+};
+var SHA_PIN_RE = /^[0-9a-f]{40}$/i;
+async function resolveAll(deps, opts) {
   const resolved = [];
   const seen = /* @__PURE__ */ new Set();
   const missing = [];
   const resolvedBy = /* @__PURE__ */ new Map();
-  function visit(refStr, parent, parentRepo) {
+  const overridesApplied = /* @__PURE__ */ new Set();
+  const overridesByRef = new Map(opts.overrides.map((o) => [o.ref, o]));
+  async function visit(refStr, parent, depChain) {
     const ref = parseAssetRef(refStr);
-    const key = `${ref.kind}:${ref.name}`;
+    if (!ref.publisher) throw new Error(`dep "${refStr}" missing publisher`);
+    const key = `${ref.publisher}/${ref.kind}:${ref.name}`;
     if (seen.has(key)) return;
     seen.add(key);
-    const preferRepo = ref.repository ?? parentRepo;
-    const entry = resolveAsset(ref, repositories, reposDir, {
-      ...opts,
-      preferRepo
-    });
-    if (!entry) {
+    const sourceCandidates = opts.provenanceIndex.get(key) ?? [];
+    const storeCandidates = [];
+    if (opts.stores.length > 0 && opts.storeFetcher) {
+      const candidateVersions = enumerateVersionsForPin(
+        ref.pin,
+        sourceCandidates.map((c) => c.version)
+      );
+      for (const store of opts.stores) {
+        for (const v of candidateVersions) {
+          if (!v) continue;
+          const m = await opts.storeFetcher.getInstallManifest(
+            store.url,
+            `${ref.publisher}/${ref.kind}:${ref.name}@${v}`
+          );
+          if (m) {
+            storeCandidates.push({
+              publisher: ref.publisher,
+              kind: ref.kind,
+              name: ref.name,
+              version: v,
+              sourceUrl: m.sourceUrl,
+              commit: m.commit,
+              files: m.files,
+              sha256: m.sha256
+            });
+          }
+        }
+      }
+    }
+    const all = [...sourceCandidates, ...storeCandidates];
+    if (all.length === 0) {
       missing.push(refStr);
       return;
     }
-    resolvedBy.set(key, parent);
-    const entryRepo = entry.repository;
-    for (const req of entry.requires) {
-      visit(`${req.kind}:${req.name}`, key, entryRepo);
+    const filtered = all.filter((c) => matchPin(ref.pin, c.version));
+    if (filtered.length === 0) {
+      missing.push(refStr);
+      return;
     }
-    for (const dep of entry.dependencies) {
-      visit(dep, key, entryRepo);
+    const versions = Array.from(new Set(filtered.map((c) => c.version)));
+    const best = versions.sort((a, b) => semver.rcompare(coerceVersion(a), coerceVersion(b)))[0];
+    const finalists = filtered.filter((c) => c.version === best);
+    const canonicalRef = `${ref.publisher}/${ref.kind}:${ref.name}@${best}`;
+    const uniqueShas = Array.from(new Set(finalists.map((c) => c.sha256)));
+    let chosen;
+    if (uniqueShas.length > 1) {
+      const override = overridesByRef.get(canonicalRef);
+      if (!override) {
+        throw new CanonicalRefConflictError(canonicalRef, finalists, [...depChain, refStr]);
+      }
+      const pick = finalists.find((c) => c.sourceUrl === override.source);
+      if (!pick) {
+        throw new Error(
+          `override for ${canonicalRef} points at ${override.source}, which is not among the resolved candidates`
+        );
+      }
+      chosen = pick;
+      overridesApplied.add(canonicalRef);
+    } else {
+      chosen = [...finalists].sort((a, b) => a.sourceUrl.localeCompare(b.sourceUrl))[0];
+    }
+    if (opts.storeFetcher && opts.stores.length > 0 && sourceCandidates.some((c) => c.version === best) && storeCandidates.some((c) => c.version === best)) {
+      for (const store of opts.stores) {
+        const d = await opts.storeFetcher.getCanonicalDigest(store.url, canonicalRef);
+        if (d && d.sha256 !== chosen.sha256) {
+          throw new CanonicalRefConflictError(
+            canonicalRef,
+            [...finalists, { ...chosen, sourceUrl: store.url, sha256: d.sha256 }],
+            [...depChain, refStr]
+          );
+        }
+      }
     }
-    resolved.push(entry);
+    resolved.push(chosen);
+    resolvedBy.set(key, parent);
   }
   for (const dep of deps) {
-    visit(dep, "direct");
+    await visit(dep, "direct", []);
   }
-  const collisions = detectCollisions(resolved, repositories, reposDir, opts?.projectDir);
-  return { resolved, missing, resolvedBy, collisions };
+  return { resolved, missing, resolvedBy, overridesApplied };
 }
-function detectCollisions(resolved, repositories, reposDir, projectDir) {
-  const repoNames = Object.keys(repositories);
-  if (repoNames.length < 2) return [];
-  const repoEntries = /* @__PURE__ */ new Map();
-  for (const repoName of repoNames) {
-    const decl = repositories[repoName];
-    if (!decl) continue;
-    const repoDir = resolveRepoDir(decl, repoName, reposDir, projectDir);
-    if (!repoDir || !existsSync(repoDir)) continue;
-    repoEntries.set(repoName, scanRepo(repoDir, repoName));
-  }
-  const collisions = [];
-  for (const entry of resolved) {
-    const key = `${entry.kind}:${entry.name}`;
-    const shadowedIn = [];
-    for (const [repoName, entries] of repoEntries) {
-      if (repoName === entry.repository) continue;
-      if (entries.some((e) => e.kind === entry.kind && e.name === entry.name)) {
-        shadowedIn.push(repoName);
-      }
-    }
-    if (shadowedIn.length > 0 && entry.repository) {
-      collisions.push({ key, resolvedFrom: entry.repository, shadowedIn });
-    }
+function coerceVersion(v) {
+  return semver.valid(v) ? v : semver.coerce(v)?.version ?? "0.0.0";
+}
+function matchPin(pin, version) {
+  if (!pin) return true;
+  if (SHA_PIN_RE.test(pin)) {
+    return version === `0.0.0-sha.${pin.slice(0, 7)}`;
   }
-  return collisions;
+  if (version.startsWith("0.0.0-sha.")) {
+    return version === pin;
+  }
+  if (!semver.valid(version)) return version === pin;
+  return semver.satisfies(version, pin, { includePrerelease: false });
+}
+function enumerateVersionsForPin(pin, sourceVersionsHint) {
+  if (!pin) return sourceVersionsHint.length > 0 ? sourceVersionsHint : [];
+  if (semver.valid(pin)) return [pin];
+  return sourceVersionsHint;
 }
 function checkRepoStatus(decl, name, reposDir, projectDir) {
   if (projectDir) {
@@ -320,8 +422,185 @@ function checkRepoStatus(decl, name, reposDir, projectDir) {
   base.upToDate = base.behind === 0;
   return base;
 }
+function fileSha256(p) {
+  return createHash("sha256").update(readFileSync(p)).digest("hex");
+}
+function compositeSha256(files) {
+  const lines = files.slice().sort((a, b) => a.path.localeCompare(b.path)).map((f) => `${f.path}:${f.sha256}
+`).join("");
+  return createHash("sha256").update(lines).digest("hex");
+}
+function publisherFromGithubUrl(url) {
+  const m = url.match(/github\.com[/:]([^/]+)\/[^/]+/);
+  return m?.[1];
+}
+function syntheticVersion(commit) {
+  return `0.0.0-sha.${commit.slice(0, 7)}`;
+}
+var KIND_DIRS = [
+  { dir: "skills", kind: "skill", mdName: "SKILL.md" },
+  { dir: "agents", kind: "agent", mdName: "AGENT.md" },
+  { dir: "bundles", kind: "bundle", mdName: "BUNDLE.md" },
+  { dir: "mcp-servers", kind: "mcp-server", mdName: "MCP.md" },
+  { dir: "connectors", kind: "connector", mdName: "CONNECTOR.md" },
+  { dir: "prompts", kind: "prompt", mdName: "PROMPT.md" },
+  { dir: "contracts", kind: "contract", mdName: "CONTRACT.md" }
+];
+var MD_FILE_BY_KIND = Object.fromEntries(
+  KIND_DIRS.map((k) => [k.kind, k.mdName])
+);
+function buildProvenanceIndex(clones, _opts) {
+  const index = /* @__PURE__ */ new Map();
+  for (const clone of clones) walkOne(clone, index);
+  return index;
+}
+function walkOne(clone, index) {
+  const yamlPath = join(clone.localPath, "skaile.yaml");
+  if (existsSync(yamlPath)) {
+    walkWithManifest(clone, yamlPath, index);
+  } else {
+    walkFilenameConvention(clone, index);
+  }
+}
+function walkWithManifest(clone, yamlPath, index) {
+  const raw = parse(readFileSync(yamlPath, "utf8")) ?? {};
+  const publisher = typeof raw.publisher === "string" && raw.publisher.length > 0 ? raw.publisher : publisherFromGithubUrl(clone.sourceUrl);
+  if (!publisher) {
+    throw new Error(
+      `${clone.sourceUrl}: publisher must be declared in skaile.yaml (non-GitHub source URL \u2014 auto-derivation not available).`
+    );
+  }
+  const sourceVersion = (typeof raw.version === "string" ? raw.version : void 0) ?? (clone.tag ? clone.tag.replace(/^v/, "") : void 0) ?? syntheticVersion(clone.commit);
+  const assets = Array.isArray(raw.assets) ? raw.assets : [];
+  if (assets.length === 0) {
+    walkFilenameConvention(clone, index, publisher, sourceVersion);
+    return;
+  }
+  for (const a of assets) {
+    const assetPublisher = a.publisher ?? publisher;
+    const version = a.version ?? sourceVersion;
+    const files = expandAssetFiles(clone.localPath, a);
+    verifyNameMatch(clone.localPath, files, a.name, a.kind);
+    const metadata = readMetadata(clone.localPath, files, a.kind);
+    const candidate = {
+      publisher: assetPublisher,
+      kind: a.kind,
+      name: a.name,
+      version,
+      sourceUrl: clone.sourceUrl,
+      commit: clone.commit,
+      files,
+      sha256: compositeSha256(files),
+      metadata
+    };
+    push(index, `${assetPublisher}/${a.kind}:${a.name}`, candidate);
+  }
+}
+function expandAssetFiles(repoRoot, a) {
+  const out = [];
+  if (a.root) {
+    walkDirRecursive(join(repoRoot, a.root), repoRoot, out);
+  }
+  if (a.files) {
+    const matches = fg.sync(a.files, { cwd: repoRoot, onlyFiles: true, dot: false });
+    for (const rel of matches) {
+      out.push({ path: rel, sha256: fileSha256(join(repoRoot, rel)) });
+    }
+  }
+  const seen = /* @__PURE__ */ new Set();
+  return out.filter((f) => seen.has(f.path) ? false : (seen.add(f.path), true));
+}
+function walkDirRecursive(abs, root, out) {
+  if (!existsSync(abs)) return;
+  for (const entry of readdirSync(abs, { withFileTypes: true })) {
+    if (entry.name === ".git" || entry.name === "node_modules") continue;
+    const childAbs = join(abs, entry.name);
+    if (entry.isDirectory()) {
+      walkDirRecursive(childAbs, root, out);
+    } else if (entry.isFile()) {
+      out.push({ path: relative(root, childAbs), sha256: fileSha256(childAbs) });
+    }
+  }
+}
+function walkFilenameConvention(clone, index, publisherOverride, versionOverride) {
+  const publisher = publisherOverride ?? publisherFromGithubUrl(clone.sourceUrl);
+  if (!publisher) {
+    throw new Error(
+      `${clone.sourceUrl}: publisher must be declared in skaile.yaml (non-GitHub source URL).`
+    );
+  }
+  const version = versionOverride ?? (clone.tag ? clone.tag.replace(/^v/, "") : void 0) ?? syntheticVersion(clone.commit);
+  for (const { dir, kind, mdName } of KIND_DIRS) {
+    const base = join(clone.localPath, dir);
+    if (!existsSync(base) || !statSync(base).isDirectory()) continue;
+    for (const entry of readdirSync(base, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const assetDir = join(base, entry.name);
+      if (!existsSync(join(assetDir, mdName))) continue;
+      const files = [];
+      walkDirRecursive(assetDir, clone.localPath, files);
+      const metadata = readMetadata(clone.localPath, files, kind);
+      const candidate = {
+        publisher,
+        kind,
+        name: entry.name,
+        version,
+        sourceUrl: clone.sourceUrl,
+        commit: clone.commit,
+        files,
+        sha256: compositeSha256(files),
+        metadata
+      };
+      push(index, `${publisher}/${kind}:${entry.name}`, candidate);
+    }
+  }
+}
+function verifyNameMatch(repoRoot, files, expectedName, kind) {
+  const mdName = MD_FILE_BY_KIND[kind];
+  if (!mdName) return;
+  const md = files.find((f) => f.path.endsWith(mdName));
+  if (!md) return;
+  const { data } = parseFrontmatter(readFileSync(join(repoRoot, md.path), "utf8"));
+  const declared = typeof data.name === "string" ? data.name : void 0;
+  if (declared && declared !== expectedName) {
+    throw new Error(
+      `name mismatch: ${mdName} says "${declared}", skaile.yaml says "${expectedName}" \u2014 index-time hard error.`
+    );
+  }
+}
+function readMetadata(repoRoot, files, kind) {
+  if (kind !== "mcp-server") return void 0;
+  const mcpMd = files.find((f) => f.path.endsWith("MCP.md"));
+  if (!mcpMd) return void 0;
+  const { data } = parseFrontmatter(readFileSync(join(repoRoot, mcpMd.path), "utf8"));
+  return data;
+}
+function push(index, key, candidate) {
+  const arr = index.get(key) ?? [];
+  arr.push(candidate);
+  index.set(key, arr);
+}
 
 // core/src/workspace-config.ts
+var DEFAULT_RECIPE_ATTR = "default";
+function validateAssetRecipeFlake(flake) {
+  if (typeof flake !== "string" || flake.length === 0) {
+    throw new Error("AssetRecipe.flake must be a non-empty string");
+  }
+  if (flake.length > 500) {
+    throw new Error(`AssetRecipe.flake too long (${flake.length} chars, max 500)`);
+  }
+  if (flake === ".") return;
+  const ALLOWED_SCHEME = /^(github:|git\+https:\/\/|git\+ssh:\/\/|path:\/)/;
+  if (!ALLOWED_SCHEME.test(flake)) {
+    throw new Error(
+      `AssetRecipe.flake "${flake}" has an unsupported source. Allowed: "." or a flake URL (github:, git+https://, git+ssh://, path:/).`
+    );
+  }
+  if (/[\s`$;|&<>(){}#\n\r]/.test(flake)) {
+    throw new Error(`AssetRecipe.flake "${flake}" contains forbidden characters.`);
+  }
+}
 function validateAssetRecipeAttr(attr) {
   if (typeof attr !== "string" || attr.length === 0) {
     throw new Error("AssetRecipe.attr must be a non-empty string");
@@ -401,13 +680,20 @@ function listSkWorkspaceConfigs(dir) {
 function resolveSkWorkspaceConfig(projectDir, opts) {
   const name = opts?.name ?? SK_WORKSPACE_DEFAULT_NAME;
   const configs = [];
+  const assertNoLegacyKey = (file) => {
+    const d = file?.diagnostics?.find((x) => x.code === "legacy_key_rejected");
+    if (d) throw new Error(d.message);
+  };
   const userConfig = loadSkWorkspaceConfig(join(homedir(), ".skaile"), name);
+  assertNoLegacyKey(userConfig);
   if (userConfig) configs.push(userConfig.config);
   if (opts?.appDir) {
     const appConfig = loadSkWorkspaceConfig(opts.appDir, name);
+    assertNoLegacyKey(appConfig);
     if (appConfig) configs.push(appConfig.config);
   }
   const projectConfig = loadSkWorkspaceConfig(projectDir, name);
+  assertNoLegacyKey(projectConfig);
   if (projectConfig) configs.push(projectConfig.config);
   if (configs.length > 0) return configs.reduce(mergeSkWorkspaceConfigs);
   return {};
@@ -443,10 +729,12 @@ function mergeSkWorkspaceConfigs(base, overlay) {
     },
     // startup: overlay wins (project-level only)
     startup: overlay.startup ?? base.startup,
-    // ai_resources: dedupe by source name — overlay entry wins for same name
-    ai_resources: dedupeByKey(
-      [...base.ai_resources ?? [], ...overlay.ai_resources ?? []],
-      "name"
+    // publication half — scalars: overlay wins when defined; assets: by kind+name
+    publisher: overlay.publisher ?? base.publisher,
+    version: overlay.version ?? base.version,
+    assets: dedupeByKey(
+      [...base.assets ?? [], ...overlay.assets ?? []],
+      (a) => `${a.kind}:${a.name}`
     ),
     // mounts: by id — overlay wins
     mounts: mergeById(base.mounts ?? [], overlay.mounts ?? []),
@@ -511,14 +799,14 @@ function mergeSkWorkspaceConfigs(base, overlay) {
     secrets: overlay.secrets ?? base.secrets,
     // telemetry: overlay wins entirely (raw pass-through)
     telemetry: overlay.telemetry ?? base.telemetry,
-    // repositories: always empty in merged output; the schema no longer
-    // accepts this key. The internal install pipeline builds its own map
-    // from `ai_resources[]` entries.
-    repositories: {},
     // dependencies: concatenate and dedupe
     dependencies: dedupe([...base.dependencies ?? [], ...overlay.dependencies ?? []]),
-    // sources: dedupe by name — overlay entry wins for the same name
-    sources: dedupeByKey([...base.sources ?? [], ...overlay.sources ?? []], "name"),
+    // sources: dedupe by url — overlay entry wins for the same url
+    sources: dedupeByKey([...base.sources ?? [], ...overlay.sources ?? []], "url"),
+    // stores: dedupe by url — overlay wins
+    stores: dedupeByKey([...base.stores ?? [], ...overlay.stores ?? []], "url"),
+    // overrides: dedupe by ref — overlay wins
+    overrides: dedupeByKey([...base.overrides ?? [], ...overlay.overrides ?? []], "ref"),
     // plugins: concatenate + dedupe (like dependencies)
     plugins: dedupe([...base.plugins ?? [], ...overlay.plugins ?? []]),
     // deploy: overlay wins entirely (scalar-like selection)
@@ -600,46 +888,75 @@ function normalizeConfigInternal(raw) {
   if (Array.isArray(raw.startup)) {
     config.startup = raw.startup;
   }
-  let aiResRaw;
-  let aiResKey;
-  if (raw.ai_resources !== void 0) {
-    aiResRaw = raw.ai_resources;
-    aiResKey = "ai_resources";
-  } else if (raw.aiResources !== void 0) {
-    aiResRaw = raw.aiResources;
-    aiResKey = "aiResources";
-  }
-  if (aiResKey === "aiResources") {
-    diagnostics.push({
-      code: "legacy_key_camelcase",
-      severity: "warning",
-      message: 'Non-canonical key "aiResources" \u2014 use "ai_resources".',
-      path: "aiResources"
-    });
+  if (raw.repositories !== void 0) {
+    throw new Error(
+      "skaile.yaml: unknown top-level key `repositories:`. The schema changed in @skaile/workspaces 4.x \u2014 see docs/concepts/manifest-schema.md, or ask your AI assistant to apply the `migrate-skaile-manifest` skill."
+    );
   }
-  if (Array.isArray(aiResRaw)) {
-    config.ai_resources = aiResRaw;
-  } else if (aiResRaw && typeof aiResRaw === "object") {
-    diagnostics.push({
-      code: "legacy_ai_resources_object",
-      severity: "warning",
-      message: "Legacy ai_resources object form ({sources, requires}) \u2014 use an array of {name, path, dependencies}.",
-      path: aiResKey
-    });
-    const old = aiResRaw;
-    const sources = Array.isArray(old.sources) ? old.sources : [];
-    const requires = Array.isArray(old.requires) ? old.requires.filter(Boolean) : [];
-    const autoDeploy = Boolean(old.auto_deploy ?? false);
-    config.ai_resources = sources.map((s, i) => {
-      const entry = {
-        name: String(s.name ?? ""),
-        path: String(s.path ?? s.url ?? "")
-      };
-      if (s.branch) entry.branch = String(s.branch);
-      if (autoDeploy) entry.auto_deploy = true;
-      if (i === 0 && requires.length > 0) entry.dependencies = requires;
-      return entry;
-    });
+  if (raw.ai_resources !== void 0 || raw.aiResources !== void 0) {
+    throw new Error(
+      "skaile.yaml: unknown top-level key `ai_resources:`. The schema changed in @skaile/workspaces 4.x \u2014 see docs/concepts/manifest-schema.md, or ask your AI assistant to apply the `migrate-skaile-manifest` skill."
+    );
+  }
+  if (typeof raw.publisher === "string" && raw.publisher.length > 0) {
+    config.publisher = raw.publisher;
+  }
+  if (typeof raw.version === "string" && raw.version.length > 0) {
+    config.version = raw.version;
+  }
+  if (Array.isArray(raw.assets)) {
+    const entries = [];
+    for (const item of raw.assets) {
+      if (!item || typeof item !== "object" || Array.isArray(item)) continue;
+      const a = item;
+      const kind = typeof a.kind === "string" ? a.kind : "";
+      const name = typeof a.name === "string" ? a.name : "";
+      if (!kind || !name) continue;
+      const entry = { kind, name };
+      if (typeof a.root === "string") entry.root = a.root;
+      if (Array.isArray(a.files)) {
+        entry.files = a.files.filter(
+          (f) => typeof f === "string"
+        );
+      }
+      if (typeof a.version === "string") entry.version = a.version;
+      if (typeof a.publisher === "string") entry.publisher = a.publisher;
+      entries.push(entry);
+    }
+    if (entries.length > 0) config.assets = entries;
+  }
+  if (Array.isArray(raw.stores)) {
+    const entries = [];
+    for (const item of raw.stores) {
+      if (!item || typeof item !== "object" || Array.isArray(item)) continue;
+      const s = item;
+      const url = typeof s.url === "string" ? s.url : "";
+      if (!url) continue;
+      entries.push({ url });
+    }
+    if (entries.length > 0) config.stores = entries;
+  }
+  if (Array.isArray(raw.overrides)) {
+    const entries = [];
+    for (const item of raw.overrides) {
+      if (!item || typeof item !== "object" || Array.isArray(item)) continue;
+      const o = item;
+      const ref = typeof o.ref === "string" ? o.ref : "";
+      const source = typeof o.source === "string" ? o.source : "";
+      if (!ref || !source) continue;
+      if (typeof o.reason !== "string") {
+        throw new Error(
+          `skaile.yaml: overrides[] entry for ${ref}: reason is required and must be a non-empty string.`
+        );
+      }
+      if (o.reason.trim().length === 0) {
+        throw new Error(
+          `skaile.yaml: overrides[] entry for ${ref}: reason must not be empty.`
+        );
+      }
+      entries.push({ ref, source, reason: o.reason });
+    }
+    if (entries.length > 0) config.overrides = entries;
   }
   if (Array.isArray(raw.mounts)) {
     config.mounts = raw.mounts;
@@ -678,13 +995,12 @@ function normalizeConfigInternal(raw) {
   if (Array.isArray(raw.sources)) {
     const entries = [];
     for (const item of raw.sources) {
-      if (!item || typeof item !== "object") continue;
+      if (!item || typeof item !== "object" || Array.isArray(item)) continue;
       const s = item;
-      const name = typeof s.name === "string" ? s.name : "";
       const url = typeof s.url === "string" ? s.url : "";
-      if (!name || !url) continue;
-      const entry = { name, url };
-      if (typeof s.branch === "string" && s.branch.length > 0) entry.branch = s.branch;
+      if (!url) continue;
+      const entry = { url };
+      if (typeof s.pin === "string" && s.pin.length > 0) entry.pin = s.pin;
       entries.push(entry);
     }
     if (entries.length > 0) config.sources = entries;
@@ -722,7 +1038,21 @@ function decodeSkaileYaml(text) {
       ]
     };
   }
-  const result = normalizeConfigInternal(parsed);
+  let result;
+  try {
+    result = normalizeConfigInternal(parsed);
+  } catch (err) {
+    return {
+      config: {},
+      diagnostics: [
+        {
+          code: "legacy_key_rejected",
+          severity: "error",
+          message: err instanceof Error ? err.message : String(err)
+        }
+      ]
+    };
+  }
   validateConfigValues(result.config, result.diagnostics);
   return result;
 }
@@ -764,12 +1094,16 @@ function validateConfigValues(config, diagnostics) {
 var CANONICAL_KEY_ORDER = [
   "name",
   "description",
+  "publisher",
+  "version",
+  "assets",
   "agent_config",
   "dependencies",
   "plugins",
   "sources",
+  "stores",
+  "overrides",
   "startup",
-  "ai_resources",
   "connectors",
   "mcp_servers",
   "deploy",
@@ -779,8 +1113,7 @@ var CANONICAL_KEY_ORDER = [
   "secrets",
   "telemetry",
   "compaction",
-  "patches",
-  "repositories"
+  "patches"
 ];
 var CONFIG_KEY_TO_YAML = {
   agent_config: "agent-config"
@@ -814,10 +1147,11 @@ function dedupe(arr) {
   return [...new Set(arr)];
 }
 function dedupeByKey(arr, key) {
+  const keyOf = typeof key === "function" ? key : (item) => String(item[key] ?? "");
   const seen = /* @__PURE__ */ new Set();
   const result = [];
   for (let i = arr.length - 1; i >= 0; i--) {
-    const val = String(arr[i][key] ?? "");
+    const val = keyOf(arr[i]);
     if (!seen.has(val)) {
       seen.add(val);
       result.unshift(arr[i]);
@@ -854,13 +1188,22 @@ function mcpDeclFromCatalogEntry(entry) {
   if (entry.description) decl.description = entry.description;
   if (m.recipe && typeof m.recipe === "object" && !Array.isArray(m.recipe)) {
     const r = m.recipe;
-    if (typeof r.attr === "string") {
+    const hasFlake = typeof r.flake === "string";
+    const rawAttr = typeof r.attr === "string" ? r.attr : void 0;
+    const effectiveAttr = rawAttr ?? (hasFlake ? DEFAULT_RECIPE_ATTR : void 0);
+    if (effectiveAttr !== void 0) {
       try {
-        validateAssetRecipeAttr(r.attr);
-        decl.recipe = { attr: r.attr };
+        validateAssetRecipeAttr(effectiveAttr);
+        if (hasFlake) {
+          validateAssetRecipeFlake(r.flake);
+          decl.recipe = { attr: effectiveAttr, flake: r.flake };
+          if (typeof r.publisher === "string") decl.recipe.publisher = r.publisher;
+        } else {
+          decl.recipe = { attr: effectiveAttr };
+        }
       } catch (err) {
         console.warn(
-          `[workspace-config] mcpDeclFromCatalogEntry: invalid recipe.attr for entry "${entry.name}": ${err instanceof Error ? err.message : String(err)}`
+          `[workspace-config] mcpDeclFromCatalogEntry: invalid recipe for entry "${entry.name}": ${err instanceof Error ? err.message : String(err)}`
         );
       }
     }
@@ -932,33 +1275,49 @@ function loadMaterializedMcpDeclarations(projectDir) {
   }
   return result;
 }
+function sourceSlug(url) {
+  return url.replace(/\.git$/, "").split(/[/:]/).pop() ?? "source";
+}
+function buildSourceClones(sources) {
+  const home = process.env.SKAILE_HOME ?? join(homedir(), ".skaile");
+  const sourcesDir = join(home, "sources");
+  const clones = [];
+  for (const s of sources) {
+    const localPath = join(sourcesDir, sourceSlug(s.url));
+    if (!existsSync(localPath)) continue;
+    const commit = getRepoCommit(localPath) ?? "0".repeat(40);
+    clones.push({ localPath, sourceUrl: s.url, commit, tag: s.pin });
+  }
+  return clones;
+}
+function catalogEntryFromCandidate(c) {
+  const md = c.metadata ?? {};
+  return {
+    name: c.name,
+    kind: c.kind,
+    description: typeof md.description === "string" ? md.description : "",
+    source: c.files[0]?.path ?? "",
+    publisher: c.publisher,
+    version: c.version,
+    requires: [],
+    dependencies: [],
+    metadata: c.metadata
+  };
+}
 function loadMcpServerDeclarations(projectDir) {
   const config = resolveSkWorkspaceConfig(projectDir);
   const explicit = config.mcp_servers ?? [];
   const materialized = loadMaterializedMcpDeclarations(projectDir);
   const mcpRefStrings = [];
   for (const dep of config.dependencies ?? []) {
-    const ref = parseAssetRef(dep);
-    if (ref.kind === "mcp-server") mcpRefStrings.push(dep);
-  }
-  for (const res of config.ai_resources ?? []) {
-    for (const dep of res.dependencies ?? []) {
+    try {
       const ref = parseAssetRef(dep);
       if (ref.kind === "mcp-server") mcpRefStrings.push(dep);
+    } catch {
     }
   }
-  const repositories = config.repositories ?? {};
-  const allRepos = { ...repositories };
-  for (const res of config.ai_resources ?? []) {
-    if (res.name && res.path && !(res.name in allRepos)) {
-      allRepos[res.name] = {
-        url: res.path.startsWith("/") ? void 0 : res.path,
-        path: res.path.startsWith("/") ? res.path : void 0,
-        branch: res.branch
-      };
-    }
-  }
-  const reposDir = getGlobalCacheDir();
+  const sources = config.sources ?? [];
+  const provenanceIndex = sources.length > 0 ? buildProvenanceIndex(buildSourceClones(sources)) : /* @__PURE__ */ new Map();
   const byId = /* @__PURE__ */ new Map();
   const order = [];
   const upsert = (decl) => {
@@ -972,12 +1331,29 @@ function loadMcpServerDeclarations(projectDir) {
   };
   const seen = /* @__PURE__ */ new Set();
   for (const refStr of mcpRefStrings) {
-    const ref = parseAssetRef(refStr);
+    let ref;
+    try {
+      ref = parseAssetRef(refStr);
+    } catch {
+      continue;
+    }
     if (seen.has(ref.name)) continue;
     seen.add(ref.name);
-    const entry = resolveAsset(ref, allRepos, reposDir, { projectDir });
-    if (!entry) continue;
-    const catalogDecl = mcpDeclFromCatalogEntry(entry);
+    let candidates;
+    if (ref.publisher) {
+      candidates = provenanceIndex.get(`${ref.publisher}/${ref.kind}:${ref.name}`);
+    }
+    if (!candidates) {
+      for (const [key, arr] of provenanceIndex) {
+        if (key.endsWith(`/${ref.kind}:${ref.name}`)) {
+          candidates = arr;
+          break;
+        }
+      }
+    }
+    const candidate = candidates?.[0];
+    if (!candidate) continue;
+    const catalogDecl = mcpDeclFromCatalogEntry(catalogEntryFromCandidate(candidate));
     if (!catalogDecl) continue;
     upsert(catalogDecl);
   }
@@ -1011,16 +1387,11 @@ function resolveAgentDir(projectDir) {
     return join(aiAssetsDir, relPath);
   }
   if (definition.startsWith("agent:")) {
-    const ref = parseAssetRef(definition);
-    const repositories = config.repositories ?? {};
-    const reposDir = getGlobalCacheDir();
-    const entry = resolveAsset(ref, repositories, reposDir, { projectDir });
-    if (!entry) return void 0;
-    return dirname(entry.source);
+    return void 0;
   }
   return resolve(projectDir, definition);
 }
 
-export { COMPACTION_DEFAULTS, SKAILE_YAML_DEFAULT, SKAILE_YAML_SUFFIX, SK_WORKSPACE_DEFAULT_NAME, SK_WORKSPACE_SUFFIX, checkRepoStatus, checkoutPin, cloneRepo, decodeSkaileYaml, encodeSkaileYaml, ensureRepo, findWorkspaceRoot, getGlobalCacheDir, getRepoCommit, isWorkspaceConfigFilename, linkRepo, listSkWorkspaceConfigs, loadMcpServerDeclarations, loadSkWorkspaceConfig, mergeSkWorkspaceConfigs, normalizeConfig, pullRepo, readLinks, resolveAgentDir, resolveAll, resolveAsset, resolveSkWorkspaceConfig, saveSkWorkspaceConfig, scanRepo, unlinkRepo, validateAssetRecipeAttr, workspaceConfigFilename, workspaceNameFromFilename, writeLinks };
-//# sourceMappingURL=chunk-TKOLD2O7.js.map
-//# sourceMappingURL=chunk-TKOLD2O7.js.map
+export { COMPACTION_DEFAULTS, CanonicalRefConflictError, DEFAULT_RECIPE_ATTR, SKAILE_YAML_DEFAULT, SKAILE_YAML_SUFFIX, SK_WORKSPACE_DEFAULT_NAME, SK_WORKSPACE_SUFFIX, buildProvenanceIndex, checkRepoStatus, checkoutPin, cloneRepo, decodeSkaileYaml, encodeSkaileYaml, ensureRepo, findWorkspaceRoot, getGlobalCacheDir, getRepoCommit, isWorkspaceConfigFilename, linkRepo, listSkWorkspaceConfigs, loadMcpServerDeclarations, loadSkWorkspaceConfig, mergeSkWorkspaceConfigs, normalizeConfig, pullRepo, readLinks, resolveAgentDir, resolveAll, resolveAsset, resolveSkWorkspaceConfig, saveSkWorkspaceConfig, scanRepo, unlinkRepo, validateAssetRecipeAttr, validateAssetRecipeFlake, workspaceConfigFilename, workspaceNameFromFilename, writeLinks };
+//# sourceMappingURL=chunk-LDYPQVRU.js.map
+//# sourceMappingURL=chunk-LDYPQVRU.js.map