@agentproto/corpus 0.1.0-alpha.1

package/dist/index.mjs

@@ -0,0 +1,3380 @@
+export { systemClock } from './chunk-KYX2DTEH.mjs';
+import { CandidatesSidecar } from './chunk-UPX26MYH.mjs';
+export { CandidatesSidecar, SidecarDuplicateError, SidecarNotFoundError } from './chunk-UPX26MYH.mjs';
+import matter from 'gray-matter';
+import { createHash } from 'crypto';
+import { z } from 'zod';
+import { parse, stringify } from 'yaml';
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+import { createRegistry } from '@agentproto/registry';
+
+/**
+ * @agentproto/corpus v0.1.0-alpha
+ * Composition of AIP-10/12/18/9/15/41 — autonomous knowledge-improvement kit.
+ */
+
+// src/util/slug.ts
+var SOURCE_SLUG = /^[a-z0-9][a-z0-9-]*$/;
+var ENTRY_SLUG = /^[a-z][a-z0-9-]*[a-z0-9]$/;
+function slugify(input, opts = {}) {
+  const maxLen = opts.maxLen ?? 96;
+  const fallback = opts.fallback ?? "item";
+  let s = input.toLowerCase().normalize("NFD").replace(/[̀-ͯ]/g, "");
+  if (opts.stripScheme) s = s.replace(/^https?:\/\//, "");
+  s = s.replace(/[^a-z0-9]+/g, "-").replace(/-{2,}/g, "-").slice(0, maxLen).replace(/^-+|-+$/g, "");
+  if (opts.leadingLetter && s && !/^[a-z]/.test(s)) {
+    s = `e-${s}`.slice(0, maxLen).replace(/-+$/g, "");
+  }
+  return s.length >= 2 ? s : fallback;
+}
+function uniqueSlug(base, seen, maxLen = 96) {
+  let slug = base;
+  let n = 2;
+  while (seen.has(slug)) {
+    slug = `${base}-${n++}`.slice(0, maxLen).replace(/-+$/g, "");
+  }
+  seen.add(slug);
+  return slug;
+}
+function isSourceSlug(s) {
+  return SOURCE_SLUG.test(s) && s.length >= 2 && s.length <= 96;
+}
+function isEntrySlug(s) {
+  return ENTRY_SLUG.test(s) && s.length >= 2 && s.length <= 96;
+}
+
+// src/util/language.ts
+var NAME_TO_CODE = {
+  english: "en",
+  french: "fr",
+  spanish: "es",
+  german: "de",
+  italian: "it",
+  portuguese: "pt",
+  dutch: "nl",
+  russian: "ru",
+  japanese: "ja",
+  korean: "ko",
+  chinese: "zh",
+  arabic: "ar",
+  hindi: "hi",
+  turkish: "tr",
+  polish: "pl",
+  swedish: "sv",
+  norwegian: "no",
+  danish: "da",
+  finnish: "fi",
+  greek: "el",
+  hebrew: "he",
+  thai: "th",
+  vietnamese: "vi",
+  indonesian: "id",
+  ukrainian: "uk"
+};
+function normalizeLanguageTag(raw) {
+  if (!raw) return void 0;
+  const v = raw.trim().toLowerCase();
+  if (!v) return void 0;
+  const named = NAME_TO_CODE[v];
+  if (named) return named;
+  const parts = v.split(/[-_]/);
+  const primary = parts[0];
+  if (!primary || !/^[a-z]{2}$/.test(primary)) return void 0;
+  const region = parts.slice(1).find((p) => /^[a-z]{2}$/.test(p));
+  return region ? `${primary}-${region.toUpperCase()}` : primary;
+}
+
+// src/lifecycle/attestations.ts
+function appendAttestation(frontmatter, attestation) {
+  const metaIn = frontmatter.metadata ?? {};
+  const corpusIn = metaIn.corpus ?? {};
+  const existing = corpusIn.attestations ?? [];
+  const last = existing[existing.length - 1];
+  if (last && last.kind === attestation.kind && last.identity === attestation.identity && last.at === attestation.at) {
+    return { ...frontmatter };
+  }
+  return {
+    ...frontmatter,
+    metadata: {
+      ...metaIn,
+      corpus: {
+        ...corpusIn,
+        attestations: [...existing, attestation]
+      }
+    }
+  };
+}
+function readAttestations(frontmatter) {
+  const meta = frontmatter.metadata;
+  const list = meta?.corpus?.attestations;
+  if (!Array.isArray(list)) return [];
+  return Object.freeze(list);
+}
+function makeAttestation(input) {
+  return Object.freeze({
+    kind: input.kind,
+    identity: input.identity,
+    at: input.at,
+    ...input.model ? { model: input.model } : {},
+    ...input.promptHash ? { promptHash: input.promptHash } : {},
+    ...input.note ? { note: input.note } : {}
+  });
+}
+
+// src/access/policy.ts
+var DEFAULT_CLASSIFICATION = "internal";
+function evaluateAccess(spec, caller, context = {}) {
+  const classification = spec?.classification ?? DEFAULT_CLASSIFICATION;
+  if (spec) {
+    if (matchesAllowed("roles", spec.allowedRoles, caller))
+      return permit(`allowedRoles match`, classification);
+    if (matchesAllowed("operators", spec.allowedOperators, caller))
+      return permit(`allowedOperators match`, classification);
+    if (matchesAllowed("users", spec.allowedUsers, caller))
+      return permit(`allowedUsers match`, classification);
+    if (matchesAllowed("guilds", spec.allowedGuilds, caller))
+      return permit(`allowedGuilds match`, classification);
+    if (matchesAllowed("orgs", spec.allowedOrgs, caller))
+      return permit(`allowedOrgs match`, classification);
+  }
+  switch (classification) {
+    case "public":
+      return {
+        permitted: true,
+        reason: "classification=public",
+        redactBytes: false
+      };
+    case "internal": {
+      if (!context.homeGuild) {
+        return {
+          permitted: false,
+          reason: "classification=internal but no homeGuild context \u2014 fail-closed",
+          redactBytes: false
+        };
+      }
+      const expected = `ws://guilds/${context.homeGuild}`;
+      const inHomeGuild = caller.identityTree.includes(expected);
+      return {
+        permitted: inHomeGuild,
+        reason: inHomeGuild ? `classification=internal + caller in ${expected}` : `classification=internal but caller not in ${expected}`,
+        redactBytes: false
+      };
+    }
+    case "restricted":
+      return {
+        permitted: false,
+        reason: "classification=restricted \u2014 caller not in any allowed list (roles/operators/users/guilds/orgs)",
+        redactBytes: false
+      };
+    case "secret":
+      return {
+        permitted: false,
+        reason: "classification=secret \u2014 caller not in any allowed list; bytes redacted",
+        redactBytes: true
+      };
+    default: {
+      return {
+        permitted: false,
+        reason: `unknown classification "${String(classification)}" \u2014 fail-closed`,
+        redactBytes: true
+      };
+    }
+  }
+}
+function permit(reason, classification) {
+  return {
+    permitted: true,
+    reason: `${reason} (classification=${classification})`,
+    redactBytes: false
+  };
+}
+function matchesAllowed(kind, list, caller) {
+  if (!list || list.length === 0) return false;
+  const prefix = `ws://${kind}/`;
+  for (const ref of list) {
+    const expanded = ref.startsWith("ws://") ? ref : prefix + ref;
+    if (caller.identityTree.includes(expanded)) return true;
+    if (expanded === `${prefix}*`) {
+      if (caller.identityTree.some((r) => r.startsWith(prefix))) return true;
+    }
+  }
+  return false;
+}
+function readAccessSpec(frontmatter) {
+  const meta = frontmatter.metadata;
+  const access = meta?.corpus?.access;
+  if (!access || typeof access !== "object") return void 0;
+  return access;
+}
+
+// src/access/capability.ts
+var DEFAULT_RULES = Object.freeze({
+  "read": { allowedRoles: ["*"] },
+  "cite": { allowedRoles: ["*"] },
+  "flag-learning": {
+    allowedRoles: ["*"],
+    rateLimit: { perOperator: 20, window: "24h" }
+  },
+  "curate": { allowedRoles: ["corpus-curator", "admin"] },
+  "promote": { allowedRoles: ["corpus-curator", "admin"] },
+  "activate-playbook": {
+    allowedRoles: ["corpus-curator", "admin"],
+    requireApproval: true
+  },
+  "admin-reindex": { allowedRoles: ["admin"] },
+  "bypass-default-filters": {
+    allowedRoles: ["corpus-curator", "admin"],
+    audit: true
+  }
+});
+function evaluateCapability(capability, accessModes, caller) {
+  const rule = accessModes?.[capability] ?? DEFAULT_RULES[capability];
+  if (!rule) {
+    return {
+      permitted: false,
+      reason: `unknown capability "${capability}"`,
+      requireApproval: false,
+      audit: true
+    };
+  }
+  const permitted = matchesRoles(rule.allowedRoles, caller.identityTree);
+  return {
+    permitted,
+    reason: permitted ? `caller identity matches allowedRoles for "${capability}"` : `caller identity does NOT match allowedRoles for "${capability}"`,
+    rateLimit: rule.rateLimit,
+    requireApproval: !!rule.requireApproval,
+    audit: !!rule.audit
+  };
+}
+function matchesRoles(allowed, identityTree) {
+  if (allowed.includes("*")) return true;
+  for (const role of allowed) {
+    const expanded = role.startsWith("ws://") ? role : `ws://roles/${role}`;
+    if (identityTree.includes(expanded)) return true;
+  }
+  return false;
+}
+function readAccessModes(workspaceFrontmatter) {
+  const meta = workspaceFrontmatter.metadata;
+  const am = meta?.corpus?.accessModes;
+  if (!am || typeof am !== "object") return void 0;
+  return am;
+}
+
+// src/access/language.ts
+function resolveLanguageFilter(input) {
+  const set = /* @__PURE__ */ new Set();
+  if (input.callerLocale) addExpansions(set, input.callerLocale);
+  if (input.workspaceDefaultLanguage)
+    addExpansions(set, input.workspaceDefaultLanguage);
+  return Object.freeze({
+    allowedLanguages: set,
+    // If a workspace default exists, entries without an explicit
+    // language inherit it → pass-through. If neither caller nor
+    // workspace declares one, the filter is effectively off (everyone
+    // surfaces; the helper isn't called for cross-language scoping).
+    allowUnspecified: set.size === 0 ? true : input.workspaceDefaultLanguage != null
+  });
+}
+function matchesLanguageFilter(entryLanguage, filter) {
+  if (filter.allowedLanguages.size === 0) return true;
+  if (!entryLanguage) return filter.allowUnspecified;
+  const lower = entryLanguage.toLowerCase();
+  if (filter.allowedLanguages.has(lower)) return true;
+  const baseLang = lower.split("-")[0];
+  if (baseLang && filter.allowedLanguages.has(baseLang)) return true;
+  for (const allowed of filter.allowedLanguages) {
+    if (lower.startsWith(allowed + "-")) return true;
+  }
+  return false;
+}
+function addExpansions(set, locale) {
+  const lower = locale.toLowerCase();
+  set.add(lower);
+  const base = lower.split("-")[0];
+  if (base) set.add(base);
+}
+function readOperatorLocale(operatorFrontmatter) {
+  const meta = operatorFrontmatter.metadata;
+  const l = meta?.corpus?.locale;
+  return typeof l === "string" ? l : void 0;
+}
+function readWorkspaceDefaultLanguage(workspaceFrontmatter) {
+  const meta = workspaceFrontmatter.metadata;
+  const def = meta?.corpus?.languages?.default;
+  return typeof def === "string" ? def : void 0;
+}
+function readEntryLanguage(frontmatter) {
+  const top = frontmatter.language;
+  if (typeof top === "string") return top;
+  const meta = frontmatter.metadata;
+  const corp = meta?.corpus?.language;
+  return typeof corp === "string" ? corp : void 0;
+}
+
+// src/events/emitter.ts
+var CorpusEventEmitter = class {
+  constructor(opts) {
+    this.opts = opts;
+  }
+  /**
+   * Emit one event. Returns the event as written (including the
+   * ISO timestamp and actor resolved at emit time). The .md log file
+   * is created on first append if missing.
+   */
+  async emit(kind, payload) {
+    const identity = await this.opts.identity.resolve();
+    const event = {
+      kind,
+      at: this.opts.clock.now().toISOString(),
+      actor: identity.principal,
+      payload
+    };
+    const logPath = joinPath(this.opts.workspaceRoot, "_log.md");
+    const line = formatLine(event) + "\n";
+    if (!await this.opts.fs.exists(logPath)) {
+      await this.opts.fs.writeFile(
+        logPath,
+        "# Corpus activity log\n\nAppend-only AIP-10 log of corpus state transitions. Each line:\n`- <iso>  <kind>  by <actor>  payload=<json>`\n\n"
+      );
+    }
+    await this.opts.fs.appendFile(logPath, line);
+    return event;
+  }
+};
+function formatLine(event) {
+  const payload = JSON.stringify(event.payload, [...Object.keys(event.payload).sort()]);
+  return `- ${event.at}  ${event.kind}  by ${event.actor}  payload=${payload}`;
+}
+function joinPath(a, b) {
+  if (!a) return b;
+  return a.endsWith("/") ? a + b : a + "/" + b;
+}
+var CorpusWorkspaceReader = class {
+  constructor(opts) {
+    this.opts = opts;
+  }
+  /**
+   * Scan the workspace rooted at `root` and return a typed snapshot.
+   * `root` is workspace-relative (the host resolves to a backing
+   * storage); commonly "" for the workspace root itself.
+   */
+  async read(root) {
+    const files = await this.opts.fs.walk(root);
+    const mdFiles = files.filter((p) => p.endsWith(".md"));
+    const buckets = {
+      "knowledge-workspace": [],
+      "knowledge-source": [],
+      "knowledge-entry": [],
+      "collection-schema": [],
+      "collection-item": [],
+      "playbook": [],
+      "operator": [],
+      "workflow": [],
+      "routine": [],
+      "unknown": []
+    };
+    for (const path of mdFiles) {
+      const content = await this.opts.fs.readFile(path);
+      const parsed = matter(content);
+      const file = {
+        // Workspace-relative path. The walk returns paths anchored at
+        // the host's storage root (which already includes `root` for
+        // non-empty workspaces — see GuildWorkspaceFsAdapter.walk),
+        // so we strip `root` here to match the documented contract
+        // ("paths returned are workspace-relative"). Without this,
+        // call sites that re-join `workspacePath + file.path` (the
+        // playbook lifecycle, the evaluator, the promoter's CAS write)
+        // double-prefix the path and the next read/CAS misses,
+        // surfacing as CorpusVersionConflictError.
+        path: stripRoot(path, root),
+        kind: classify(path, root),
+        frontmatter: parsed.data ?? {},
+        body: parsed.content,
+        versionToken: sha256(content)
+      };
+      buckets[file.kind].push(file);
+    }
+    return {
+      root,
+      workspace: buckets["knowledge-workspace"][0] ?? null,
+      sources: freeze(buckets["knowledge-source"]),
+      entries: freeze(buckets["knowledge-entry"]),
+      collections: freeze(buckets["collection-schema"]),
+      collectionItems: freeze(buckets["collection-item"]),
+      playbooks: freeze(buckets["playbook"]),
+      operators: freeze(buckets["operator"]),
+      workflows: freeze(buckets["workflow"]),
+      routines: freeze(buckets["routine"]),
+      unknown: freeze(buckets["unknown"])
+    };
+  }
+};
+function classify(path, root) {
+  const rel = stripRoot(path, root);
+  const segs = rel.split("/").filter(Boolean);
+  const fname = segs[segs.length - 1] ?? "";
+  if (segs.length === 1 && fname === "KNOWLEDGE.md") return "knowledge-workspace";
+  const top = segs[0];
+  switch (top) {
+    case "sources":
+      return "knowledge-source";
+    case "entries":
+      return "knowledge-entry";
+    case "collections":
+      if (fname === "COLLECTION.md") return "collection-schema";
+      if (fname === "ITEM.md" || /^[a-z0-9][a-z0-9-]*\.md$/.test(fname))
+        return "collection-item";
+      return "unknown";
+    case "playbooks":
+      if (fname === "PLAYBOOK.md") return "playbook";
+      return "unknown";
+    case "operators":
+      if (fname === "OPERATOR.md") return "operator";
+      return "unknown";
+    case "workflows":
+      if (fname === "WORKFLOW.md") return "workflow";
+      return "unknown";
+    case "routines":
+      if (fname === "ROUTINE.md") return "routine";
+      return "unknown";
+    default:
+      return "unknown";
+  }
+}
+function stripRoot(path, root) {
+  if (!root) return path;
+  const prefix = root.endsWith("/") ? root : root + "/";
+  return path.startsWith(prefix) ? path.slice(prefix.length) : path;
+}
+function sha256(content) {
+  return "sha256:" + createHash("sha256").update(content).digest("hex");
+}
+function freeze(arr) {
+  return Object.freeze([...arr]);
+}
+var CorpusVersionConflictError = class extends Error {
+  constructor(path, expected, actual) {
+    super(
+      `CorpusVersionConflictError: ${path} versionToken mismatch \u2014 expected ${expected}, found ${actual}. Re-read the file and retry with the fresh token.`
+    );
+    this.path = path;
+    this.expected = expected;
+    this.actual = actual;
+    this.name = "CorpusVersionConflictError";
+  }
+};
+var CorpusWorkspaceWriter = class _CorpusWorkspaceWriter {
+  constructor(opts) {
+    this.opts = opts;
+  }
+  /**
+   * Compute the versionToken for raw file content. Exposed so the
+   * caller can stage a write and pass the same hash function used
+   * inside the writer.
+   */
+  static versionTokenOf(content) {
+    return "sha256:" + createHash("sha256").update(content).digest("hex");
+  }
+  /**
+   * Atomic write with optimistic concurrency check.
+   *
+   *   - expected === undefined → unconditional overwrite (use sparingly)
+   *   - expected === null      → create-only (refuses if exists)
+   *   - expected === string    → CAS check (refuses if current hash differs)
+   *
+   * Returns the new versionToken on success.
+   */
+  async writeFile(path, content, expected) {
+    if (expected === null) {
+      if (await this.opts.fs.exists(path)) {
+        throw new CorpusVersionConflictError(path, "<must-not-exist>", "<exists>");
+      }
+    } else if (typeof expected === "string") {
+      const existing = await this.opts.fs.exists(path);
+      if (!existing) {
+        throw new CorpusVersionConflictError(path, expected, "<missing>");
+      }
+      const current = await this.opts.fs.readFile(path);
+      const actual = _CorpusWorkspaceWriter.versionTokenOf(current);
+      if (actual !== expected) {
+        throw new CorpusVersionConflictError(path, expected, actual);
+      }
+    }
+    await this.opts.fs.writeFile(path, content);
+    return _CorpusWorkspaceWriter.versionTokenOf(content);
+  }
+  /**
+   * Serialize a markdown doc (frontmatter + body) and write atomically.
+   * Frontmatter keys are stringified in a stable order so version
+   * tokens are deterministic across emitter rebuilds.
+   */
+  async writeMarkdown(path, doc, expected) {
+    const content = serializeMarkdown(doc);
+    return this.writeFile(path, content, expected);
+  }
+  /**
+   * Run `fn` while holding a workspace-scoped lock. Used for
+   * multi-file transactions (promote entry + update _index.md + log
+   * append). The lock path is host-specific; we default to
+   * `_log.md` because it's the file every transaction touches.
+   *
+   * `lockPath` is workspace-relative.
+   */
+  async transaction(lockPath, fn) {
+    let handle = null;
+    try {
+      handle = await this.opts.fs.lock(lockPath);
+      return await fn();
+    } finally {
+      if (handle) await handle.release();
+    }
+  }
+};
+function serializeMarkdown(doc) {
+  return matter.stringify(doc.body.startsWith("\n") ? doc.body : "\n" + doc.body, doc.frontmatter);
+}
+
+// src/importers/runner.ts
+var SIDECAR_PATH = "collections/corpus-candidate/_candidates.yaml";
+var ImporterRunner = class {
+  constructor(opts) {
+    this.opts = opts;
+  }
+  /**
+   * Run a single importer batch end-to-end.
+   *
+   *   1. Pre-load existing source content_hashes for dedup.
+   *   2. For each source the importer yields:
+   *      a. Skip if hash already exists in the workspace.
+   *      b. Otherwise write AIP-10 source frontmatter + body to
+   *         `sources/<importerId>/<batchId>/<slug>.md`.
+   *      c. Append candidate row to `_candidates.yaml`.
+   *   3. Emit `corpus.candidate.discovered` per archived source.
+   *
+   * Atomic per-source (each source archived + candidate written
+   * inside one writer.transaction).
+   */
+  async run(importer, target) {
+    const fs = this.opts.fs;
+    const writer = new CorpusWorkspaceWriter({ fs });
+    const reader = new CorpusWorkspaceReader({ fs });
+    const sidecar = new CandidatesSidecar({
+      fs,
+      path: joinPath2(this.opts.workspacePath, SIDECAR_PATH)
+    });
+    const emitter = new CorpusEventEmitter({
+      fs,
+      clock: this.opts.clock,
+      identity: this.opts.identity,
+      workspaceRoot: this.opts.workspacePath
+    });
+    const batchId = target.batchId ?? this.opts.clock.now().toISOString().slice(0, 10);
+    const archiveDirSegment = `sources/${target.importerId}/${batchId}`;
+    const snapshot = await reader.read(this.opts.workspacePath);
+    const existingHashes = /* @__PURE__ */ new Set();
+    for (const file of snapshot.sources) {
+      const h = file.frontmatter.content_hash;
+      if (typeof h === "string") existingHashes.add(h);
+    }
+    const archivedSlugs = [];
+    const duplicateSlugs = [];
+    const candidateIds = [];
+    const warnings = [];
+    for await (const source of importer.enumerate(target)) {
+      if (!isSourceSlug(source.slug)) {
+        warnings.push(`source skipped \u2014 invalid slug "${source.slug}"`);
+        continue;
+      }
+      if (existingHashes.has(source.contentHash)) {
+        duplicateSlugs.push(source.slug);
+        continue;
+      }
+      existingHashes.add(source.contentHash);
+      const sourcePath = joinPath2(
+        this.opts.workspacePath,
+        `${archiveDirSegment}/${source.slug}.md`
+      );
+      const sourceContent = serializeSource(source, archiveDirSegment, this.opts.clock);
+      try {
+        await writer.writeFile(sourcePath, sourceContent, null);
+      } catch (err) {
+        warnings.push(
+          `source "${source.slug}" \u2014 slug collision in ${archiveDirSegment} (${err instanceof Error ? err.message : "unknown"}); skipped`
+        );
+        continue;
+      }
+      archivedSlugs.push(source.slug);
+      const toCandidate = this.opts.runner?.toCandidate ?? defaultToCandidate;
+      const sourceId = source.slug;
+      const row = toCandidate(source, sourceId);
+      try {
+        await sidecar.append(row);
+        candidateIds.push(row.id);
+      } catch (err) {
+        warnings.push(
+          `candidate "${row.id}" \u2014 sidecar append failed (${err instanceof Error ? err.message : "unknown"})`
+        );
+      }
+      await emitter.emit("corpus.candidate.discovered", {
+        id: row.id,
+        importerId: target.importerId,
+        batchId,
+        contentHash: source.contentHash,
+        provenanceKind: `imported-from-${target.importerId}`
+      }).catch(() => void 0);
+    }
+    return Object.freeze({
+      importerId: target.importerId,
+      batchId,
+      archivedSlugs: Object.freeze(archivedSlugs),
+      duplicateSlugs: Object.freeze(duplicateSlugs),
+      candidateIds: Object.freeze(candidateIds),
+      warnings: Object.freeze(warnings)
+    });
+  }
+};
+function defaultToCandidate(s, sourceId) {
+  return {
+    id: sourceId,
+    status: "discovered",
+    corpusKind: "example",
+    sourcePath: void 0,
+    // filled in by archiver via path mapping
+    sourceUrl: s.originalUrl,
+    contentHash: s.contentHash,
+    title: s.title,
+    summary: void 0,
+    discoveredAt: (/* @__PURE__ */ new Date()).toISOString(),
+    discoveredBy: "ws://operators/importer-runner",
+    provenanceKind: "imported"
+  };
+}
+function serializeSource(source, archiveDirSegment, clock) {
+  const fm = {
+    schema: "knowledge.source/v1",
+    id: source.slug,
+    path: `${archiveDirSegment}/${source.slug}.md`,
+    title: source.title,
+    captured_at: clock.now().toISOString(),
+    content_hash: source.contentHash,
+    authority: source.authority ?? "secondary"
+  };
+  if (source.language) fm.language = source.language;
+  if (source.tags && source.tags.length > 0) fm.tags = source.tags;
+  if (source.originalUrl || source.corpusMetadata) {
+    fm.metadata = {
+      corpus: {
+        ...source.originalUrl ? { originalUrl: source.originalUrl } : {},
+        ...source.corpusMetadata ?? {}
+      }
+    };
+  }
+  return matter.stringify(
+    source.body.startsWith("\n") ? source.body : "\n" + source.body,
+    fm
+  );
+}
+function joinPath2(a, b) {
+  if (!a) return b;
+  return a.endsWith("/") ? a + b : a + "/" + b;
+}
+var LocalFilesImporter = class {
+  constructor(opts) {
+    this.opts = opts;
+  }
+  id = "local-files";
+  label = "Local Files";
+  async *enumerate(target) {
+    const config = parseConfig(target.config);
+    const exts = new Set(config.extensions ?? [".md"]);
+    const maxFiles = config.maxFiles ?? 1e3;
+    const paths = await this.opts.fs.walk(config.rootPath);
+    let yielded = 0;
+    for (const p of paths) {
+      if (yielded >= maxFiles) break;
+      const ext = pickExt(p);
+      if (!exts.has(ext)) continue;
+      const body = await this.opts.fs.readFile(p);
+      const slug = makeSlug(p, config.rootPath);
+      const contentHash = sha2562(body);
+      const title = readTitleFromBody(body, slug);
+      yield {
+        slug,
+        title,
+        contentHash,
+        body,
+        authority: "secondary",
+        ...config.language ? { language: config.language } : {},
+        ...config.tags && config.tags.length > 0 ? { tags: config.tags } : {},
+        corpusMetadata: {
+          importerSourcePath: p,
+          importerRoot: config.rootPath
+        }
+      };
+      yielded++;
+    }
+  }
+};
+function parseConfig(raw) {
+  if (typeof raw.rootPath !== "string") {
+    throw new Error(
+      `LocalFilesImporter: config.rootPath is required (string)`
+    );
+  }
+  const cfg = {
+    rootPath: raw.rootPath,
+    extensions: Array.isArray(raw.extensions) ? raw.extensions.filter(
+      (x) => typeof x === "string"
+    ) : void 0,
+    maxFiles: typeof raw.maxFiles === "number" ? raw.maxFiles : void 0,
+    tags: Array.isArray(raw.tags) ? raw.tags.filter(
+      (x) => typeof x === "string"
+    ) : void 0,
+    language: typeof raw.language === "string" ? raw.language : void 0
+  };
+  return cfg;
+}
+function pickExt(path) {
+  const i = path.lastIndexOf(".");
+  if (i < 0) return "";
+  return path.slice(i).toLowerCase();
+}
+function makeSlug(path, rootPath) {
+  const rel = path.startsWith(rootPath) ? path.slice(rootPath.length) : path;
+  const stripped = rel.replace(/^\/+/, "").replace(/\.[^.]+$/, "");
+  return slugify(stripped, { fallback: "source" });
+}
+function readTitleFromBody(body, fallback) {
+  const m = body.match(/^\s*#\s+(.+)$/m);
+  if (m && m[1]) return m[1].trim().slice(0, 200);
+  return fallback;
+}
+function sha2562(content) {
+  return "sha256:" + createHash("sha256").update(content).digest("hex");
+}
+var KbMigrationImporter = class {
+  id = "kb-migration";
+  label = "Migrate from existing KB";
+  async *enumerate(target) {
+    const config = parseKbMigrationConfig(target.config);
+    const sources = await config.provider.listSources();
+    const max = config.maxSources ?? sources.length;
+    let yielded = 0;
+    for (const s of sources) {
+      if (yielded >= max) break;
+      const body = config.fetchBody ? await config.fetchBody(s.id) : `(Migrated from KB ${config.sourceKbId}, source id=${s.id}. Body fetcher not configured \u2014 archive contains metadata only.)`;
+      const slug = slugifyKbSource(s.id, config.sourceKbId);
+      yield {
+        slug,
+        title: s.title ?? s.id,
+        contentHash: hashKbSource(s, body),
+        body,
+        originalUrl: typeof s.uri === "string" ? s.uri : void 0,
+        authority: "secondary",
+        corpusMetadata: {
+          provenanceKind: "imported-from-kb",
+          sourceKbId: config.sourceKbId,
+          sourceKbSourceId: s.id,
+          sourceKbBytes: s.bytes,
+          sourceKbKind: s.kind,
+          // Carry the original KB's metadata through verbatim so
+          // curators can see what was lost in translation.
+          sourceKbMetadata: s.metadata
+        }
+      };
+      yielded++;
+    }
+  }
+};
+function parseKbMigrationConfig(raw) {
+  const sourceKbId = raw.sourceKbId;
+  const provider = raw.provider;
+  if (typeof sourceKbId !== "string") {
+    throw new Error("KbMigrationImporter: config.sourceKbId required (string)");
+  }
+  if (!provider || typeof provider !== "object" || typeof provider.listSources !== "function") {
+    throw new Error(
+      "KbMigrationImporter: config.provider required (must implement listSources)"
+    );
+  }
+  return {
+    sourceKbId,
+    provider,
+    fetchBody: typeof raw.fetchBody === "function" ? raw.fetchBody : void 0,
+    maxSources: typeof raw.maxSources === "number" ? raw.maxSources : void 0
+  };
+}
+function slugifyKbSource(id, kbId) {
+  const combined = `${kbId}-${id}`;
+  const slug = combined.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").replace(/-{2,}/g, "-").slice(0, 96);
+  return slug || "migrated-source";
+}
+function hashKbSource(s, body) {
+  return "sha256:" + createHash("sha256").update(`${s.id}|${s.bytes}|${body}`).digest("hex");
+}
+var WebImporter = class {
+  constructor(opts) {
+    this.opts = opts;
+  }
+  id = "web";
+  label = "Web (URLs)";
+  async *enumerate(target) {
+    const config = parseConfig2(target.config);
+    const maxUrls = config.maxUrls ?? 1e3;
+    const seenSlugs = /* @__PURE__ */ new Set();
+    let yielded = 0;
+    for (const url of config.urls) {
+      if (yielded >= maxUrls) break;
+      let fetched;
+      try {
+        fetched = await this.opts.fetcher.fetch(url);
+      } catch {
+        continue;
+      }
+      if (!fetched || !fetched.text.trim()) continue;
+      const slug = uniqueSlug(
+        slugify(fetched.title, { fallback: "" }) || slugify(url, { stripScheme: true, fallback: "source" }),
+        seenSlugs
+      );
+      const language = normalizeLanguageTag(fetched.language ?? config.language);
+      yield {
+        slug,
+        title: fetched.title.slice(0, 200) || slug,
+        contentHash: sha2563(fetched.text),
+        body: fetched.text,
+        originalUrl: url,
+        authority: "secondary",
+        ...language ? { language } : {},
+        ...config.tags && config.tags.length > 0 ? { tags: config.tags } : {},
+        corpusMetadata: {
+          importerSourceUrl: url,
+          fetchKind: fetched.kind,
+          ...fetched.via ? { fetchedVia: fetched.via } : {}
+        }
+      };
+      yielded++;
+    }
+  }
+};
+function parseConfig2(raw) {
+  const rawUrls = raw.urls;
+  if (!Array.isArray(rawUrls) || rawUrls.length === 0) {
+    throw new Error("WebImporter: config.urls is required (non-empty string[])");
+  }
+  const urls = rawUrls.filter(
+    (x) => typeof x === "string" && x.length > 0
+  );
+  if (urls.length === 0) {
+    throw new Error("WebImporter: config.urls contained no usable strings");
+  }
+  const rawTags = raw.tags;
+  return {
+    urls,
+    maxUrls: typeof raw.maxUrls === "number" ? raw.maxUrls : void 0,
+    tags: Array.isArray(rawTags) ? rawTags.filter((x) => typeof x === "string") : void 0,
+    language: typeof raw.language === "string" ? raw.language : void 0
+  };
+}
+function sha2563(content) {
+  return "sha256:" + createHash("sha256").update(content).digest("hex");
+}
+var ConversationImporter = class {
+  constructor(opts) {
+    this.opts = opts;
+  }
+  id = "conversation";
+  label = "Conversation";
+  async *enumerate(target) {
+    const config = parseConfig3(target.config);
+    const maxRefs = config.maxRefs ?? 1e3;
+    const seenSlugs = /* @__PURE__ */ new Set();
+    let yielded = 0;
+    for (const ref of config.refs) {
+      if (yielded >= maxRefs) break;
+      let doc;
+      try {
+        doc = await this.opts.source.fetchConversation(ref);
+      } catch {
+        continue;
+      }
+      if (!doc || doc.turns.length === 0) continue;
+      const body = renderTranscript(doc.turns);
+      if (!body) continue;
+      const slug = uniqueSlug(
+        slugify(doc.id, { fallback: "" }) || slugify(doc.title ?? "conversation", { fallback: "conversation" }),
+        seenSlugs
+      );
+      const language = normalizeLanguageTag(doc.language ?? config.language);
+      const stamps = doc.turns.map((t) => t.at).filter((a) => typeof a === "string" && a.length > 0).sort();
+      yield {
+        slug,
+        title: (doc.title ?? `Conversation ${doc.id}`).slice(0, 200),
+        contentHash: sha2564(body),
+        body,
+        authority: config.authority ?? "secondary",
+        ...language ? { language } : {},
+        ...config.tags && config.tags.length > 0 ? { tags: config.tags } : {},
+        corpusMetadata: {
+          conversationRef: ref,
+          conversationId: doc.id,
+          sourceKind: "conversation",
+          turnCount: countTurns(doc.turns),
+          ...stamps.length ? { firstTurnAt: stamps[0], lastTurnAt: stamps[stamps.length - 1] } : {}
+        }
+      };
+      yielded++;
+    }
+  }
+};
+function parseConfig3(raw) {
+  const rawRefs = raw.refs;
+  if (!Array.isArray(rawRefs) || rawRefs.length === 0) {
+    throw new Error(
+      "ConversationImporter: config.refs is required (non-empty string[])"
+    );
+  }
+  const refs = rawRefs.filter(
+    (x) => typeof x === "string" && x.length > 0
+  );
+  if (refs.length === 0) {
+    throw new Error(
+      "ConversationImporter: config.refs contained no usable strings"
+    );
+  }
+  const rawTags = raw.tags;
+  return {
+    refs,
+    maxRefs: typeof raw.maxRefs === "number" ? raw.maxRefs : void 0,
+    tags: Array.isArray(rawTags) ? rawTags.filter((x) => typeof x === "string") : void 0,
+    language: typeof raw.language === "string" ? raw.language : void 0,
+    authority: isAuthority(raw.authority) ? raw.authority : void 0
+  };
+}
+function isAuthority(v) {
+  return v === "primary" || v === "secondary" || v === "rumour";
+}
+function renderTranscript(turns) {
+  const blocks = [];
+  for (const turn of turns) {
+    const text = turn.text.trim();
+    if (!text) continue;
+    blocks.push(`${labelRole(turn.role)}: ${text}`);
+  }
+  return blocks.join("\n\n");
+}
+function countTurns(turns) {
+  let n = 0;
+  for (const t of turns) if (t.text.trim()) n++;
+  return n;
+}
+function labelRole(role) {
+  const r = role.trim();
+  if (!r) return "Speaker";
+  return r.charAt(0).toUpperCase() + r.slice(1);
+}
+function sha2564(content) {
+  return "sha256:" + createHash("sha256").update(content).digest("hex");
+}
+var ENTRY_SLUG_OPTS = { leadingLetter: true, fallback: "entry", maxLen: 80 };
+var KIND_DIR = {
+  principle: "principles",
+  pattern: "patterns",
+  critique: "critiques",
+  summary: "summaries",
+  example: "examples"
+};
+var DistillRunner = class {
+  constructor(opts) {
+    this.opts = opts;
+  }
+  async run(source) {
+    const items = await this.opts.distiller.distill({
+      title: source.title,
+      body: source.body,
+      ...source.tags ? { tags: source.tags } : {}
+    });
+    const year = this.opts.clock.now().getUTCFullYear();
+    const flat = this.opts.layout === "flat";
+    const seen = /* @__PURE__ */ new Set();
+    const entryPaths = [];
+    const skipped = [];
+    for (const item of items) {
+      if (!item.title.trim() || !item.body.trim()) continue;
+      const slug = uniqueSlug(slugify(item.title, ENTRY_SLUG_OPTS), seen, 80);
+      const dir = KIND_DIR[item.kind];
+      const path = flat ? `entries/${dir}/${slug}.md` : `entries/${dir}/${year}/${slug}.md`;
+      if (await this.opts.fs.exists(path)) {
+        skipped.push(slug);
+        continue;
+      }
+      await this.opts.fs.writeFile(path, serializeEntry(item, slug, source, this.opts.clock));
+      entryPaths.push(path);
+    }
+    return { sourceId: source.id, entryPaths, skipped };
+  }
+};
+function serializeEntry(item, slug, source, clock) {
+  const now = clock.now().toISOString();
+  const fm = {
+    schema: "knowledge.entry/v1",
+    slug,
+    kind: item.kind,
+    title: item.title,
+    updated_at: now,
+    sources: [source.id],
+    // ← derivedFrom / provenance edge
+    confidence: typeof item.confidence === "number" ? item.confidence : 0.7,
+    tags: dedupeTags(item.tags, source.tags),
+    metadata: {
+      corpus: {
+        status: "active",
+        ...source.domain ? { domain: source.domain } : {},
+        // access inherited from the source — propagates up the chain so a
+        // refined insight is never more visible than its evidence.
+        ...source.access ? { access: source.access } : {},
+        promotionMode: "auto-distill",
+        promotedAt: now
+      }
+    }
+  };
+  const body = item.body.trim();
+  return matter.stringify(body.startsWith("\n") ? body : "\n" + body, fm);
+}
+function dedupeTags(a, b) {
+  const out = /* @__PURE__ */ new Set();
+  for (const raw of [...a ?? [], ...b ?? []]) {
+    const t = sanitizeTag(raw);
+    if (t) out.add(t);
+  }
+  return [...out];
+}
+function sanitizeTag(raw) {
+  const t = raw.toLowerCase().normalize("NFD").replace(/[̀-ͯ]/g, "").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").replace(/-{2,}/g, "-");
+  return /^[a-z][a-z0-9-]*$/.test(t) ? t : null;
+}
+var REFINED_KIND_SCHEMA = z.enum([
+  "principle",
+  "pattern",
+  "critique",
+  "summary",
+  "example"
+]);
+function isRefinedKind(value) {
+  return REFINED_KIND_SCHEMA.safeParse(value).success;
+}
+var DISTILLED_ITEM = z.object({
+  kind: REFINED_KIND_SCHEMA,
+  title: z.string(),
+  body: z.string(),
+  confidence: z.number().optional(),
+  tags: z.array(z.string()).optional()
+}).loose();
+function buildDistillPrompt(input, maxItems) {
+  return `You distill a raw source (a video transcript or article) into REFINED, reusable knowledge for an AI operator. Extract the durable insights \u2014 not a summary of the video, but the transferable lessons.
+
+Return a JSON array (max ${maxItems} items). Each item:
+{ "kind": one of "principle" | "pattern" | "critique" | "summary" | "example",
+  "title": short imperative/declarative title,
+  "body": 2-5 sentences, SELF-CONTAINED (no "the speaker says"), the actual insight,
+  "confidence": 0-1, "tags": [short topic tags] }
+
+Guidance:
+- "principle": a durable rule of thumb. "pattern": a repeatable technique/sequence.
+  "critique": a common mistake / anti-pattern. "summary": a compact overview.
+  "example": a concrete worked instance worth remembering.
+- Drop filler, calls-to-action, tangents. Keep only what an operator could ACT on later.
+- Write every title and body in ENGLISH, even when the source is in another language. Translate the insight; do not copy the source language.
+
+SOURCE TITLE: ${input.title}
+${input.tags?.length ? `TAGS: ${input.tags.join(", ")}
+` : ""}SOURCE BODY:
+${input.body.slice(0, 24e3)}
+
+Return ONLY the JSON array, no prose.`;
+}
+function parseItems(text) {
+  const start = text.indexOf("[");
+  const end = text.lastIndexOf("]");
+  if (start < 0 || end <= start) return [];
+  let raw;
+  try {
+    raw = JSON.parse(text.slice(start, end + 1));
+  } catch {
+    return [];
+  }
+  if (!Array.isArray(raw)) return [];
+  const out = [];
+  for (const r of raw) {
+    const item = DISTILLED_ITEM.safeParse(r);
+    if (!item.success) continue;
+    const { kind, title, body, confidence, tags } = item.data;
+    out.push({
+      kind,
+      title,
+      body,
+      ...typeof confidence === "number" ? { confidence } : {},
+      ...tags ? { tags } : {}
+    });
+  }
+  return out;
+}
+var ENTRY_SOURCES = z.object({ sources: z.array(z.string()).optional().catch(void 0) }).loose();
+async function scanDistilledSourceIds(fs) {
+  const ids = /* @__PURE__ */ new Set();
+  let rels;
+  try {
+    rels = await fs.walk("entries");
+  } catch {
+    return ids;
+  }
+  for (const rel of rels) {
+    if (!rel.endsWith(".md")) continue;
+    const path = rel.startsWith("entries/") ? rel : `entries/${rel}`;
+    try {
+      const fm = ENTRY_SOURCES.parse(matter(await fs.readFile(path)).data);
+      if (fm.sources) for (const s of fm.sources) ids.add(s);
+    } catch {
+    }
+  }
+  return ids;
+}
+
+// src/distill/registry.ts
+function createDistillRegistry() {
+  const descriptors = /* @__PURE__ */ new Map();
+  return {
+    register(descriptor) {
+      if (descriptors.has(descriptor.id)) {
+        throw new Error(`Distill descriptor "${descriptor.id}" is already registered`);
+      }
+      descriptors.set(descriptor.id, descriptor);
+    },
+    has(id) {
+      return descriptors.has(id);
+    },
+    resolve(id) {
+      const descriptor = descriptors.get(id);
+      if (!descriptor) {
+        throw new Error(
+          `Distill descriptor "${id}" is not registered. Registered: ${[...descriptors.keys()].join(", ") || "(none)"}`
+        );
+      }
+      return descriptor;
+    },
+    list() {
+      return [...descriptors.values()];
+    }
+  };
+}
+
+// src/distill/run.ts
+async function runDistill(descriptor, scope) {
+  const report = {
+    descriptorId: descriptor.id,
+    scopeId: scope.id,
+    unitsConsidered: 0,
+    unitsDistilled: 0,
+    entriesWritten: 0,
+    skipped: 0
+  };
+  const target = await descriptor.target(scope);
+  const distilled = await scanDistilledSourceIds(target.fs);
+  const binding = descriptor.bind(scope, target);
+  const config = await binding.prepare(distilled);
+  if (!config) return report;
+  const runner = new DistillRunner({
+    fs: target.fs,
+    clock: target.clock,
+    distiller: descriptor.distiller(scope)
+  });
+  for await (const imported of binding.importer.enumerate({
+    importerId: descriptor.id,
+    config
+  })) {
+    report.unitsConsidered++;
+    const source = {
+      id: binding.provenanceId(imported),
+      title: imported.title,
+      body: imported.body,
+      ...imported.tags ? { tags: imported.tags } : {}
+    };
+    try {
+      const r = await runner.run(source);
+      if (r.entryPaths.length > 0) report.unitsDistilled++;
+      report.entriesWritten += r.entryPaths.length;
+      report.skipped += r.skipped.length;
+    } catch {
+    }
+  }
+  return report;
+}
+var ANTHROPIC_RESPONSE = z.object({
+  content: z.array(
+    z.object({ type: z.string(), text: z.string().optional() }).loose()
+  ).optional()
+}).loose();
+var ClaudeDistiller = class {
+  apiKey;
+  model;
+  baseUrl;
+  maxItems;
+  constructor(opts) {
+    this.apiKey = opts.apiKey;
+    this.model = opts.model ?? "claude-sonnet-4-6";
+    this.baseUrl = (opts.baseUrl ?? "https://api.anthropic.com/v1").replace(
+      /\/+$/,
+      ""
+    );
+    this.maxItems = opts.maxItems ?? 8;
+  }
+  async distill(input) {
+    const prompt = buildDistillPrompt(input, this.maxItems);
+    const res = await fetch(`${this.baseUrl}/messages`, {
+      method: "POST",
+      headers: {
+        "x-api-key": this.apiKey,
+        "anthropic-version": "2023-06-01",
+        "content-type": "application/json"
+      },
+      body: JSON.stringify({
+        model: this.model,
+        max_tokens: 4096,
+        messages: [{ role: "user", content: prompt }]
+      })
+    });
+    if (!res.ok) {
+      throw new Error(
+        `Claude distill ${res.status}: ${(await res.text()).slice(0, 200)}`
+      );
+    }
+    const parsed = ANTHROPIC_RESPONSE.safeParse(await res.json());
+    const text = parsed.success ? (parsed.data.content ?? []).find((c) => c.type === "text")?.text ?? "" : "";
+    return parseItems(text);
+  }
+};
+
+// src/distill/windows.ts
+var WINDOW_SEP = "::";
+function windowRef(threadId, day) {
+  return `${threadId}${WINDOW_SEP}${day}`;
+}
+function parseWindowRef(ref) {
+  const i = ref.indexOf(WINDOW_SEP);
+  if (i < 0) return null;
+  const threadId = ref.slice(0, i);
+  const day = ref.slice(i + WINDOW_SEP.length);
+  return threadId && day ? { threadId, day } : null;
+}
+function windowSlug(threadId, day) {
+  return `${threadId}-${day}`;
+}
+async function enumerateWindowRefs(source, distilled) {
+  const refs = [];
+  for (const thread of await source.listThreads()) {
+    const threadId = thread.threadId ?? thread.id;
+    if (!threadId) continue;
+    for (const day of await source.listWindows(threadId)) {
+      if (distilled.has(windowSlug(threadId, day))) continue;
+      refs.push(windowRef(threadId, day));
+    }
+  }
+  return refs;
+}
+var ENTRY_FRONTMATTER = z.object({
+  schema: z.string().optional().catch(void 0),
+  slug: z.string().optional().catch(void 0),
+  kind: z.string().optional().catch(void 0),
+  title: z.string().optional().catch(void 0),
+  sources: z.array(z.string()).optional().catch(void 0),
+  confidence: z.number().optional().catch(void 0),
+  tags: z.array(z.string()).optional().catch(void 0),
+  metadata: z.object({
+    corpus: z.object({
+      access: z.string().optional().catch(void 0),
+      status: z.string().optional().catch(void 0),
+      // Resolved provenance written at promote time — the origins this
+      // entry was distilled from, so a recall can cite the real source.
+      source_refs: z.array(
+        z.object({
+          id: z.string(),
+          url: z.string().optional().catch(void 0),
+          title: z.string().optional().catch(void 0),
+          authority: z.string().optional().catch(void 0),
+          language: z.string().optional().catch(void 0)
+        }).loose()
+      ).optional().catch(void 0)
+    }).loose().optional().catch(void 0)
+  }).loose().optional().catch(void 0)
+}).loose();
+async function resolveKnowledge(opts) {
+  const { fs, query, allowedAccess } = opts;
+  const wantTags = new Set((query.tags ?? []).map((t) => t.toLowerCase()));
+  const wantKinds = query.kinds ? new Set(query.kinds) : null;
+  let rels;
+  try {
+    rels = await fs.walk("entries");
+  } catch {
+    return [];
+  }
+  const hits = [];
+  for (const rel of rels) {
+    if (!rel.endsWith(".md")) continue;
+    const path = `entries/${rel}`;
+    let parsed;
+    try {
+      parsed = matter(await fs.readFile(path));
+    } catch {
+      continue;
+    }
+    const fm = ENTRY_FRONTMATTER.parse(parsed.data);
+    if (fm.schema !== "knowledge.entry/v1") continue;
+    if (fm.metadata?.corpus?.status === "archived") continue;
+    const kind = fm.kind ?? "";
+    if (wantKinds && !(isRefinedKind(kind) && wantKinds.has(kind))) continue;
+    const tags = fm.tags ?? [];
+    if (wantTags.size > 0 && !tags.some((t) => wantTags.has(t.toLowerCase()))) continue;
+    const access = fm.metadata?.corpus?.access;
+    if (allowedAccess && access && !allowedAccess.has(access)) continue;
+    hits.push({
+      slug: fm.slug ?? path,
+      kind,
+      title: fm.title ?? "",
+      body: parsed.content.trim(),
+      sources: fm.sources ?? [],
+      ...fm.metadata?.corpus?.source_refs ? { sourceRefs: fm.metadata.corpus.source_refs } : {},
+      confidence: fm.confidence ?? 0,
+      tags,
+      ...access ? { access } : {},
+      path
+    });
+  }
+  hits.sort((a, b) => b.confidence - a.confidence);
+  return query.maxResults !== void 0 ? hits.slice(0, query.maxResults) : hits;
+}
+
+// src/knowledge/overlay-fs.ts
+var WHITEOUT_SUFFIX = ".whiteout";
+var isMarker = (p) => p.endsWith(WHITEOUT_SUFFIX);
+var baseOf = (markerPath) => markerPath.slice(0, -WHITEOUT_SUFFIX.length);
+var OverlayFs = class {
+  /** Layers ordered highest-precedence first. */
+  layers;
+  whiteout;
+  writableIndex;
+  constructor(layers, options = {}) {
+    if (layers.length === 0) {
+      throw new Error("OverlayFs requires at least one layer");
+    }
+    this.layers = layers;
+    this.whiteout = options.whiteout ?? false;
+    const w = options.writableLayer ?? 0;
+    if (w < 0 || w >= layers.length) {
+      throw new Error(
+        `OverlayFs: writableLayer ${w} out of range [0, ${layers.length - 1}]`
+      );
+    }
+    this.writableIndex = w;
+  }
+  /**
+   * Top-down resolution for a single path: the first layer that declares
+   * either the real entry OR its whiteout marker decides. Within one
+   * layer a real entry wins over a stale marker. Returns null when no
+   * layer declares the path, and `{ removed: true }` when the winning
+   * layer tombstones it.
+   */
+  async resolvePath(path) {
+    const marker = path + WHITEOUT_SUFFIX;
+    for (const layer of this.layers) {
+      if (await layer.exists(path)) return { layer };
+      if (await layer.exists(marker)) return { removed: true };
+    }
+    return null;
+  }
+  async exists(path) {
+    if (!this.whiteout) {
+      for (const layer of this.layers) {
+        if (await layer.exists(path)) return true;
+      }
+      return false;
+    }
+    if (isMarker(path)) return false;
+    const r = await this.resolvePath(path);
+    return r !== null && !("removed" in r);
+  }
+  async readFile(path) {
+    if (this.whiteout && !isMarker(path)) {
+      const r = await this.resolvePath(path);
+      if (r && "layer" in r) return await r.layer.readFile(path);
+      return await this.layers[0].readFile(path);
+    }
+    for (const layer of this.layers) {
+      if (await layer.exists(path)) return await layer.readFile(path);
+    }
+    return await this.layers[0].readFile(path);
+  }
+  async stat(path) {
+    if (this.whiteout && !isMarker(path)) {
+      const r = await this.resolvePath(path);
+      if (r && "layer" in r) return await r.layer.stat(path);
+      return null;
+    }
+    if (this.whiteout && isMarker(path)) return null;
+    for (const layer of this.layers) {
+      const s = await layer.stat(path);
+      if (s) return s;
+    }
+    return null;
+  }
+  async readdir(path) {
+    if (!this.whiteout) {
+      const seen = /* @__PURE__ */ new Set();
+      for (const layer of this.layers) {
+        let names;
+        try {
+          names = await layer.readdir(path);
+        } catch {
+          continue;
+        }
+        for (const n of names) seen.add(n);
+      }
+      return [...seen];
+    }
+    return this.unionWhiteoutAware((layer) => layer.readdir(path));
+  }
+  async walk(path) {
+    if (!this.whiteout) {
+      const seen = /* @__PURE__ */ new Set();
+      for (const layer of this.layers) {
+        const rels = await layer.walk(path);
+        for (const rel of rels) seen.add(rel);
+      }
+      return [...seen];
+    }
+    return this.unionWhiteoutAware((layer) => layer.walk(path));
+  }
+  /**
+   * Union the entries each layer reports for a path (basenames for
+   * readdir, relative paths for walk), resolving whiteouts top-down: the
+   * first layer (highest precedence) that declares an entry or its marker
+   * wins. Real entries win over markers within the same layer; marker
+   * files are stripped from the result.
+   */
+  async unionWhiteoutAware(list) {
+    const decided = /* @__PURE__ */ new Map();
+    for (const layer of this.layers) {
+      let entries;
+      try {
+        entries = await list(layer);
+      } catch {
+        continue;
+      }
+      const reals = entries.filter((e) => !isMarker(e));
+      const markerBases = entries.filter(isMarker).map(baseOf);
+      for (const r of reals) if (!decided.has(r)) decided.set(r, "present");
+      for (const b of markerBases) if (!decided.has(b)) decided.set(b, "removed");
+    }
+    const out = [];
+    for (const [name, state] of decided) {
+      if (state === "present") out.push(name);
+    }
+    return out;
+  }
+  // ── mutations target the writable layer only ────────────────────────
+  async writeFile(path, content) {
+    return await this.layers[this.writableIndex].writeFile(path, content);
+  }
+  async appendFile(path, content) {
+    return await this.layers[this.writableIndex].appendFile(path, content);
+  }
+  async lock(path) {
+    return await this.layers[this.writableIndex].lock(path);
+  }
+};
+var ReadOnlyFs = class {
+  constructor(inner) {
+    this.inner = inner;
+  }
+  exists(path) {
+    return this.inner.exists(path);
+  }
+  readFile(path) {
+    return this.inner.readFile(path);
+  }
+  stat(path) {
+    return this.inner.stat(path);
+  }
+  readdir(path) {
+    return this.inner.readdir(path);
+  }
+  walk(path) {
+    return this.inner.walk(path);
+  }
+  async writeFile(path, _content) {
+    throw new Error(`ReadOnlyFs: refusing to write "${path}" \u2014 packs are immutable`);
+  }
+  async appendFile(path, _content) {
+    throw new Error(`ReadOnlyFs: refusing to append "${path}" \u2014 packs are immutable`);
+  }
+  async lock(path) {
+    throw new Error(`ReadOnlyFs: refusing to lock "${path}" \u2014 packs are immutable`);
+  }
+};
+
+// src/knowledge/mem-fs.ts
+var MemFs = class {
+  files;
+  constructor(files) {
+    this.files = { ...files };
+  }
+  async exists(path) {
+    return path in this.files;
+  }
+  async readFile(path) {
+    const content = this.files[path];
+    if (content === void 0) throw new Error(`MemFs: ENOENT ${path}`);
+    return content;
+  }
+  async writeFile(path, content) {
+    this.files[path] = content;
+  }
+  async appendFile(path, content) {
+    this.files[path] = (this.files[path] ?? "") + content;
+  }
+  async readdir(path) {
+    const prefix = path.endsWith("/") ? path : `${path}/`;
+    const names = /* @__PURE__ */ new Set();
+    for (const key of Object.keys(this.files)) {
+      if (key.startsWith(prefix)) names.add(key.slice(prefix.length).split("/")[0]);
+    }
+    return [...names];
+  }
+  async walk(path) {
+    const prefix = path.endsWith("/") ? path : `${path}/`;
+    return Object.keys(this.files).filter((key) => key.startsWith(prefix)).map((key) => key.slice(prefix.length));
+  }
+  async stat(path) {
+    const content = this.files[path];
+    return content === void 0 ? null : { kind: "file", bytes: content.length };
+  }
+  async lock() {
+    return { release: async () => {
+    } };
+  }
+};
+var DEFAULT_SHADOW_TRAFFIC_PCT = 0.1;
+function deterministicBucket(token, salt) {
+  const h = createHash("sha256").update(`${token}|${salt}`).digest();
+  return h.readUInt32BE(0) / 4294967296;
+}
+function sampleShadow(token, salt, pct = DEFAULT_SHADOW_TRAFFIC_PCT) {
+  if (!token) return false;
+  if (pct <= 0) return false;
+  if (pct >= 1) return true;
+  return deterministicBucket(token, salt) < pct;
+}
+
+// src/stack/resolver.ts
+var StackResolver = class {
+  constructor(registry) {
+    this.registry = registry;
+  }
+  async resolve(ctx) {
+    const providers = [...this.registry.list()].sort((a, b) => a.band - b.band);
+    const entries = [];
+    const skipped = [];
+    for (const p of providers) {
+      let shadowSampled = false;
+      if (p.shadow) {
+        shadowSampled = sampleShadow(ctx.conversationId, p.id, p.shadow.pct);
+        if (!shadowSampled) {
+          skipped.push({
+            providerId: p.id,
+            dimension: p.dimension,
+            reason: "shadow-not-sampled"
+          });
+          continue;
+        }
+      }
+      const refs = await p.resolve(ctx);
+      if (refs.length === 0) {
+        skipped.push({
+          providerId: p.id,
+          dimension: p.dimension,
+          reason: "empty"
+        });
+        continue;
+      }
+      entries.push({
+        providerId: p.id,
+        band: p.band,
+        mode: p.mode,
+        dimension: p.dimension,
+        refs,
+        shadowSampled
+      });
+    }
+    return Object.freeze({
+      entries: Object.freeze(entries),
+      skipped: Object.freeze(skipped)
+    });
+  }
+};
+
+// src/stack/mount.ts
+function buildOverlayFromStack(opts) {
+  const { guildFs, stack, loadFs } = opts;
+  const constraintFs = [];
+  const lensFs = [];
+  for (const entry of stack.entries) {
+    const target = entry.mode === "constraint" ? constraintFs : lensFs;
+    for (const ref of entry.refs) {
+      const fs = loadFs(ref);
+      if (fs) target.push(entry.mode === "constraint" ? new ReadOnlyFs(fs) : fs);
+    }
+  }
+  if (constraintFs.length === 0 && lensFs.length === 0) return guildFs;
+  const layers = [...constraintFs, guildFs, ...lensFs];
+  return new OverlayFs(layers, {
+    whiteout: true,
+    writableLayer: constraintFs.length
+    // index of guildFs
+  });
+}
+function flattenPackRefs(stack) {
+  const out = [];
+  for (const entry of stack.entries) {
+    for (const ref of entry.refs) {
+      if (ref.kind && ref.kind !== "pack") continue;
+      if (!out.includes(ref.ref)) out.push(ref.ref);
+    }
+  }
+  return out;
+}
+function partitionStackRefs(stack) {
+  const lens = [];
+  const constraint = [];
+  for (const entry of stack.entries) {
+    const target = entry.mode === "constraint" ? constraint : lens;
+    for (const ref of entry.refs) {
+      if (ref.kind && ref.kind !== "pack") continue;
+      if (!target.includes(ref.ref)) target.push(ref.ref);
+    }
+  }
+  return { lens, constraint };
+}
+
+// src/sink/runner.ts
+var SyncRunner = class {
+  constructor(opts) {
+    this.opts = opts;
+  }
+  async run() {
+    const scheme = this.opts.uriScheme ?? "corpus";
+    const throttle = this.opts.throttleMs ?? 0;
+    const sleep = this.opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const entries = await resolveKnowledge({
+      fs: this.opts.fs,
+      query: this.opts.select ?? {}
+    });
+    const results = [];
+    let pushed = 0;
+    let skipped = 0;
+    let failed = 0;
+    for (let i = 0; i < entries.length; i++) {
+      const e = entries[i];
+      if (i > 0 && throttle > 0) await sleep(throttle);
+      const item = {
+        slug: e.slug,
+        kind: e.kind,
+        title: e.title,
+        body: e.body,
+        sources: e.sources,
+        tags: e.tags,
+        confidence: e.confidence,
+        ...e.access ? { access: e.access } : {},
+        uri: `${scheme}://${e.slug}`
+      };
+      let res;
+      try {
+        res = await this.opts.sink.push(item);
+      } catch (err) {
+        res = { uri: item.uri, ok: false, error: err instanceof Error ? err.message : String(err) };
+      }
+      results.push(res);
+      if (res.skipped) skipped++;
+      else if (res.ok) pushed++;
+      else failed++;
+    }
+    return { pushed, skipped, failed, results };
+  }
+};
+
+// src/calibration/aggregate.ts
+var DEFAULT_DISAGREEMENT_THRESHOLD = 1.5;
+function aggregateReviewerScores(reviews, opts = {}) {
+  if (reviews.length === 0) {
+    return Object.freeze({
+      aggregate: 0,
+      spread: 0,
+      disagreement: false,
+      sampleSize: 0,
+      breakdown: Object.freeze([])
+    });
+  }
+  const threshold = opts.disagreementThreshold ?? DEFAULT_DISAGREEMENT_THRESHOLD;
+  const weighted = opts.weighted !== false;
+  const breakdown = reviews.map((r) => ({
+    reviewerIdentity: r.reviewerIdentity,
+    score: r.score,
+    weight: typeof r.weight === "number" && r.weight > 0 ? r.weight : 1
+  }));
+  const scores = breakdown.map((b) => b.score);
+  const min = Math.min(...scores);
+  const max = Math.max(...scores);
+  const spread = max - min;
+  const aggregate = weighted ? weightedMedian(breakdown) : plainMedian(scores);
+  return Object.freeze({
+    aggregate,
+    spread,
+    disagreement: spread > threshold,
+    sampleSize: reviews.length,
+    breakdown: Object.freeze(breakdown)
+  });
+}
+function plainMedian(values) {
+  const sorted = [...values].sort((a, b) => a - b);
+  const mid = Math.floor(sorted.length / 2);
+  if (sorted.length % 2 === 0) {
+    return (sorted[mid - 1] + sorted[mid]) / 2;
+  }
+  return sorted[mid];
+}
+function weightedMedian(items) {
+  const sorted = [...items].sort((a, b) => a.score - b.score);
+  const totalWeight = sorted.reduce((acc2, it) => acc2 + it.weight, 0);
+  if (totalWeight === 0) return plainMedian(items.map((i) => i.score));
+  const half = totalWeight / 2;
+  let acc = 0;
+  for (let i = 0; i < sorted.length; i++) {
+    acc += sorted[i].weight;
+    if (acc >= half) {
+      if (acc === half && i + 1 < sorted.length) {
+        return (sorted[i].score + sorted[i + 1].score) / 2;
+      }
+      return sorted[i].score;
+    }
+  }
+  return sorted[sorted.length - 1].score;
+}
+var DEFAULT_PATH = "_calibration/reviewer-track-record.yaml";
+var ReviewerTrackRecord = class {
+  constructor(opts) {
+    this.opts = opts;
+    this.path = opts.path ?? DEFAULT_PATH;
+  }
+  path;
+  /** Load the full record. Empty when the file doesn't exist yet. */
+  async load() {
+    if (!await this.opts.fs.exists(this.path)) return {};
+    const content = await this.opts.fs.readFile(this.path);
+    if (!content.trim()) return {};
+    const parsed = parse(content);
+    if (!parsed || typeof parsed.reviewers !== "object") return {};
+    return Object.freeze(parsed.reviewers);
+  }
+  /** Append one entry under a reviewer's identity. */
+  async append(reviewerIdentity, entry) {
+    const existing = await this.load();
+    const current = existing[reviewerIdentity] ?? [];
+    const next = {
+      reviewers: {
+        ...existing,
+        [reviewerIdentity]: [...current, entry]
+      }
+    };
+    const content = stringify(next);
+    await this.opts.fs.writeFile(this.path, content);
+  }
+  /**
+   * Read all entries for a reviewer in the last N days. Used by the
+   * calibration routine to compute correlation on a rolling window.
+   */
+  async window(reviewerIdentity, days, now) {
+    const all = await this.load();
+    const slice = all[reviewerIdentity] ?? [];
+    const cutoffMs = now.getTime() - days * 864e5;
+    return slice.filter((e) => Date.parse(e.at) >= cutoffMs);
+  }
+  /** Reviewer identities present in the record. */
+  async listReviewers() {
+    const all = await this.load();
+    return Object.keys(all);
+  }
+};
+
+// src/calibration/correlation.ts
+var DEFAULT_MIN_SAMPLE = 10;
+var DEFAULT_CALIBRATED_THRESHOLD = 0.4;
+function pearsonCorrelation(xs, ys) {
+  if (xs.length !== ys.length) {
+    throw new Error(
+      `pearsonCorrelation: array length mismatch (xs=${xs.length}, ys=${ys.length})`
+    );
+  }
+  const n = xs.length;
+  if (n < 2) return Number.NaN;
+  let sumX = 0;
+  let sumY = 0;
+  for (let i = 0; i < n; i++) {
+    sumX += xs[i];
+    sumY += ys[i];
+  }
+  const meanX = sumX / n;
+  const meanY = sumY / n;
+  let cov = 0;
+  let varX = 0;
+  let varY = 0;
+  for (let i = 0; i < n; i++) {
+    const dx = xs[i] - meanX;
+    const dy = ys[i] - meanY;
+    cov += dx * dy;
+    varX += dx * dx;
+    varY += dy * dy;
+  }
+  if (varX === 0 || varY === 0) return Number.NaN;
+  return cov / Math.sqrt(varX * varY);
+}
+function computeReviewerCalibration(reviewerIdentity, entries, opts = {}) {
+  const minSample = opts.minSampleSize ?? DEFAULT_MIN_SAMPLE;
+  const threshold = opts.calibratedThreshold ?? DEFAULT_CALIBRATED_THRESHOLD;
+  const utilityRows = entries.filter(
+    (e) => typeof e.observedUtility === "number"
+  );
+  const liftRows = entries.filter((e) => typeof e.observedLift === "number");
+  if (Math.max(utilityRows.length, liftRows.length) < minSample) {
+    return Object.freeze({
+      reviewerIdentity,
+      sampleSize: Math.max(utilityRows.length, liftRows.length),
+      correlationUtility: Number.NaN,
+      correlationLift: Number.NaN,
+      isCalibrated: false,
+      suggestedWeight: 1,
+      // neutral — no penalty for insufficient data
+      status: "insufficient-sample"
+    });
+  }
+  const corrUtil = utilityRows.length >= minSample ? pearsonCorrelation(
+    utilityRows.map((e) => e.qualityScore),
+    utilityRows.map((e) => e.observedUtility)
+  ) : Number.NaN;
+  const corrLift = liftRows.length >= minSample ? pearsonCorrelation(
+    liftRows.map((e) => e.qualityScore),
+    liftRows.map((e) => e.observedLift)
+  ) : Number.NaN;
+  const available = [corrUtil, corrLift].filter((x) => !Number.isNaN(x));
+  if (available.length === 0) {
+    return Object.freeze({
+      reviewerIdentity,
+      sampleSize: entries.length,
+      correlationUtility: corrUtil,
+      correlationLift: corrLift,
+      isCalibrated: false,
+      suggestedWeight: 0.3,
+      // de-weight but not zero
+      status: "no-variance"
+    });
+  }
+  const composite = available.reduce((a, b) => a + b, 0) / available.length;
+  let weight;
+  let isCalibrated;
+  if (composite >= threshold) {
+    isCalibrated = true;
+    weight = 0.7 + 0.3 * ((composite - threshold) / (1 - threshold));
+  } else {
+    isCalibrated = false;
+    weight = Math.max(
+      0,
+      0.7 * ((composite + 1) / (threshold + 1))
+    );
+  }
+  return Object.freeze({
+    reviewerIdentity,
+    sampleSize: entries.length,
+    correlationUtility: corrUtil,
+    correlationLift: corrLift,
+    isCalibrated,
+    suggestedWeight: Math.max(0, Math.min(1, weight)),
+    status: isCalibrated ? "calibrated" : "miscalibrated"
+  });
+}
+var FILE_KIND_TO_SCHEMA = {
+  "knowledge-workspace": "knowledge",
+  "knowledge-source": "knowledge",
+  "knowledge-entry": "knowledge",
+  "collection-schema": "collection",
+  "collection-item": "collection",
+  "playbook": "playbook",
+  "operator": "operator",
+  "workflow": "workflow",
+  "routine": "routine"
+};
+var CorpusValidator = class {
+  validators;
+  constructor(opts) {
+    const ajv = new Ajv2020({
+      strict: false,
+      allErrors: true,
+      allowUnionTypes: true
+    });
+    addFormats(ajv);
+    for (const ext of opts.bundle.externals ?? []) {
+      const id = ext.$id;
+      if (id && !ajv.getSchema(id)) ajv.addSchema(ext);
+    }
+    const validators = {};
+    for (const key of Object.keys(opts.bundle.schemas)) {
+      validators[key] = ajv.compile(opts.bundle.schemas[key]);
+    }
+    this.validators = validators;
+  }
+  /**
+   * Validate a single parsed file. Returns issues + a valid flag.
+   * Unknown FileKind ("unknown" bucket) is reported as a single info
+   * issue — the file exists but doesn't fit AIP conventions.
+   */
+  validateFile(file) {
+    if (file.kind === "unknown") {
+      return {
+        valid: false,
+        issues: [
+          {
+            path: file.path,
+            instancePath: "/",
+            message: "file location does not match any AIP convention; expected under sources/, entries/, collections/, playbooks/, operators/, workflows/, or routines/",
+            severity: "info"
+          }
+        ]
+      };
+    }
+    const schemaKey = FILE_KIND_TO_SCHEMA[file.kind];
+    if (!schemaKey) {
+      return {
+        valid: true,
+        issues: []
+      };
+    }
+    const validator = this.validators[schemaKey];
+    const ok = validator(file.frontmatter);
+    if (ok) return { valid: true, issues: [] };
+    const issues = (validator.errors ?? []).map((e) => ({
+      path: file.path,
+      instancePath: e.instancePath || "/",
+      message: `${e.message}${e.params && Object.keys(e.params).length > 0 ? ` (${JSON.stringify(e.params)})` : ""}`,
+      severity: "error"
+    }));
+    return { valid: false, issues };
+  }
+  /**
+   * Validate every file in a workspace snapshot. Returns a flat list
+   * of issues across all files plus a `valid` flag that's true only
+   * if zero error-severity issues exist.
+   */
+  validateWorkspace(snapshot) {
+    const all = [];
+    const buckets = [
+      snapshot.workspace ? [snapshot.workspace] : [],
+      snapshot.sources,
+      snapshot.entries,
+      snapshot.collections,
+      snapshot.collectionItems,
+      snapshot.playbooks,
+      snapshot.operators,
+      snapshot.workflows,
+      snapshot.routines,
+      snapshot.unknown
+    ];
+    for (const bucket of buckets) {
+      for (const file of bucket) {
+        all.push(...this.validateFile(file).issues);
+      }
+    }
+    return {
+      valid: all.every((i) => i.severity !== "error"),
+      issues: Object.freeze(all)
+    };
+  }
+};
+
+// src/validate/linter.ts
+var CorpusLinter = class {
+  constructor(opts) {
+    this.opts = opts;
+  }
+  lint(snapshot) {
+    const decls = extractLintDeclarations(snapshot);
+    const issues = [];
+    for (const decl of decls) {
+      switch (decl.kind) {
+        case "require-source":
+          issues.push(...this.lintRequireSource(decl, snapshot));
+          break;
+        case "min-confidence":
+          issues.push(...this.lintMinConfidence(decl, snapshot));
+          break;
+        case "max-age":
+          issues.push(...this.lintMaxAge(decl, snapshot));
+          break;
+        case "broken-ref":
+          issues.push(...this.lintBrokenRef(decl, snapshot));
+          break;
+        case "orphan":
+          issues.push(...this.lintOrphan(decl, snapshot));
+          break;
+        case "custom": {
+          const runner = this.opts.customRunners?.[decl.id];
+          if (runner) issues.push(...runner(decl, snapshot));
+          break;
+        }
+      }
+    }
+    return reportFrom(issues);
+  }
+  // ── Lint implementations ────────────────────────────────────────────
+  lintRequireSource(decl, snapshot) {
+    const out = [];
+    for (const entry of snapshot.entries) {
+      if (!matchesAppliesTo(entry, decl.appliesTo)) continue;
+      const sources = entry.frontmatter.sources ?? [];
+      if (sources.length === 0) {
+        out.push({
+          lintId: decl.id,
+          path: entry.path,
+          message: `entry has no sources[] (kind=${entry.frontmatter.kind ?? "?"})`,
+          severity: decl.severity
+        });
+      }
+    }
+    return out;
+  }
+  lintMinConfidence(decl, snapshot) {
+    const min = numberParam(decl, "min", 0.5);
+    const out = [];
+    for (const entry of snapshot.entries) {
+      if (!matchesAppliesTo(entry, decl.appliesTo)) continue;
+      const c = entry.frontmatter.confidence;
+      if (typeof c === "number" && c < min) {
+        out.push({
+          lintId: decl.id,
+          path: entry.path,
+          message: `confidence ${c} < min ${min}`,
+          severity: decl.severity
+        });
+      }
+    }
+    return out;
+  }
+  lintMaxAge(decl, snapshot) {
+    const days = numberParam(decl, "days", 365);
+    const cutoffMs = this.opts.clock.nowMs() - days * 864e5;
+    const out = [];
+    for (const entry of snapshot.entries) {
+      if (!matchesAppliesTo(entry, decl.appliesTo)) continue;
+      const updated = entry.frontmatter.updated_at;
+      if (typeof updated !== "string") continue;
+      const t = Date.parse(updated);
+      if (Number.isNaN(t)) continue;
+      if (t < cutoffMs) {
+        out.push({
+          lintId: decl.id,
+          path: entry.path,
+          message: `updated_at ${updated} older than ${days}d`,
+          severity: decl.severity
+        });
+      }
+    }
+    return out;
+  }
+  lintBrokenRef(decl, snapshot) {
+    const sourceIds = /* @__PURE__ */ new Set();
+    for (const s of snapshot.sources) {
+      const id = s.frontmatter.id;
+      if (typeof id === "string") sourceIds.add(id);
+    }
+    const entrySlugs = /* @__PURE__ */ new Set();
+    for (const e of snapshot.entries) {
+      const slug = e.frontmatter.slug;
+      if (typeof slug === "string") entrySlugs.add(slug);
+    }
+    const out = [];
+    for (const entry of snapshot.entries) {
+      if (!matchesAppliesTo(entry, decl.appliesTo)) continue;
+      const sources = entry.frontmatter.sources ?? [];
+      for (const s of sources) {
+        if (typeof s === "string" && !sourceIds.has(s)) {
+          out.push({
+            lintId: decl.id,
+            path: entry.path,
+            message: `unresolved source ref: ${s}`,
+            severity: decl.severity
+          });
+        }
+      }
+      for (const field of ["supersedes", "contradicts", "links"]) {
+        const refs = entry.frontmatter[field] ?? [];
+        for (const r of refs) {
+          if (typeof r === "string" && !entrySlugs.has(r)) {
+            out.push({
+              lintId: decl.id,
+              path: entry.path,
+              message: `unresolved ${field} ref: ${r}`,
+              severity: decl.severity
+            });
+          }
+        }
+      }
+    }
+    return out;
+  }
+  lintOrphan(decl, snapshot) {
+    const incoming = /* @__PURE__ */ new Set();
+    for (const e of snapshot.entries) {
+      for (const field of ["supersedes", "contradicts", "links"]) {
+        const refs = e.frontmatter[field] ?? [];
+        for (const r of refs) {
+          if (typeof r === "string") incoming.add(r);
+        }
+      }
+    }
+    const out = [];
+    for (const entry of snapshot.entries) {
+      if (!matchesAppliesTo(entry, decl.appliesTo)) continue;
+      const slug = entry.frontmatter.slug;
+      if (typeof slug !== "string") continue;
+      if (!incoming.has(slug)) {
+        out.push({
+          lintId: decl.id,
+          path: entry.path,
+          message: `entry has no incoming references (orphan)`,
+          severity: decl.severity
+        });
+      }
+    }
+    return out;
+  }
+};
+function extractLintDeclarations(snapshot) {
+  if (!snapshot.workspace) return [];
+  const raw = snapshot.workspace.frontmatter.lints ?? [];
+  const decls = [];
+  for (const r of raw) {
+    if (!isLintDeclaration(r)) continue;
+    decls.push(r);
+  }
+  return decls;
+}
+function isLintDeclaration(x) {
+  if (typeof x !== "object" || x === null) return false;
+  const o = x;
+  return typeof o.id === "string" && typeof o.kind === "string" && typeof o.appliesTo === "string" && typeof o.severity === "string";
+}
+function matchesAppliesTo(entry, appliesTo) {
+  if (appliesTo === "*") return true;
+  const kind = entry.frontmatter.kind;
+  if (typeof kind !== "string") return false;
+  return appliesTo.toLowerCase() === kind.toLowerCase();
+}
+function numberParam(decl, key, fallback) {
+  const params = decl.params ?? {};
+  const v = params[key];
+  return typeof v === "number" ? v : fallback;
+}
+function reportFrom(issues) {
+  let errorCount = 0;
+  let warnCount = 0;
+  let infoCount = 0;
+  for (const i of issues) {
+    if (i.severity === "error") errorCount++;
+    else if (i.severity === "warn") warnCount++;
+    else infoCount++;
+  }
+  return {
+    issues: Object.freeze([...issues]),
+    errorCount,
+    warnCount,
+    infoCount
+  };
+}
+
+// src/lifecycle/candidate.ts
+var DEFAULT_TRANSITIONS = Object.freeze({
+  discovered: ["analyzed", "rejected"],
+  analyzed: ["approved", "rejected", "needs-work"],
+  "needs-work": ["analyzed", "rejected"],
+  approved: [],
+  rejected: []
+});
+function canTransition(from, to, graph = DEFAULT_TRANSITIONS) {
+  if (from === to) {
+    return { allowed: false, reason: "same-status (no-op)" };
+  }
+  const allowedTargets = graph[from] ?? [];
+  if (allowedTargets.length === 0) {
+    return {
+      allowed: false,
+      reason: `"${from}" is terminal \u2014 no outgoing transitions`
+    };
+  }
+  if (!allowedTargets.includes(to)) {
+    return {
+      allowed: false,
+      reason: `"${from}" cannot transition to "${to}". Allowed: ${allowedTargets.join(", ")}`
+    };
+  }
+  return { allowed: true };
+}
+function transitionGraphFromCollection(fm) {
+  const statuses = fm.statuses ?? [];
+  const graph = {};
+  for (const s of statuses) {
+    if (typeof s !== "object" || s === null) continue;
+    const o = s;
+    if (typeof o.id !== "string") continue;
+    if (o.terminal === true) {
+      graph[o.id] = [];
+      continue;
+    }
+    if (Array.isArray(o.transitionsTo)) {
+      graph[o.id] = o.transitionsTo.filter(
+        (x) => typeof x === "string"
+      );
+    }
+  }
+  return Object.keys(graph).length > 0 ? Object.freeze(graph) : DEFAULT_TRANSITIONS;
+}
+var IllegalTransitionError = class extends Error {
+  constructor(from, to, reason) {
+    super(
+      `IllegalTransitionError: ${from} \u2192 ${to} is not allowed (${reason})`
+    );
+    this.from = from;
+    this.to = to;
+    this.reason = reason;
+    this.name = "IllegalTransitionError";
+  }
+};
+function assertTransition(from, to, graph) {
+  const check = canTransition(from, to, graph);
+  if (!check.allowed) {
+    throw new IllegalTransitionError(from, to, check.reason ?? "no reason");
+  }
+}
+
+// src/lifecycle/gate.ts
+function extractAutoPromoteConfig(snapshot) {
+  const ws = snapshot.workspace;
+  if (!ws) return { enabled: false };
+  const corpus = ws.frontmatter.metadata?.corpus;
+  if (!corpus?.autoPromote) return { enabled: false };
+  return corpus.autoPromote;
+}
+function evaluateGate(candidate, config) {
+  if (!config.enabled) {
+    return { passed: false, failures: [], disabled: true };
+  }
+  const requires = config.requires ?? {};
+  const failures = [];
+  const flat = candidate.frontmatter;
+  const corpusMeta = flat.metadata?.corpus ?? {};
+  const get = (key) => {
+    if (corpusMeta[key] !== void 0) return corpusMeta[key];
+    if (flat[key] !== void 0) return flat[key];
+    return void 0;
+  };
+  if (requires.qualityScore) {
+    const q = get("qualityScore");
+    if (typeof q !== "number") {
+      failures.push({
+        rule: "qualityScore",
+        message: "qualityScore is missing (required by autoPromote)"
+      });
+    } else {
+      if (requires.qualityScore.min !== void 0 && q < requires.qualityScore.min) {
+        failures.push({
+          rule: "qualityScore",
+          message: `qualityScore ${q} < min ${requires.qualityScore.min}`
+        });
+      }
+      if (requires.qualityScore.max !== void 0 && q > requires.qualityScore.max) {
+        failures.push({
+          rule: "qualityScore",
+          message: `qualityScore ${q} > max ${requires.qualityScore.max}`
+        });
+      }
+    }
+  }
+  if (requires.riskScore) {
+    const r = get("riskScore");
+    if (typeof r !== "number") {
+      failures.push({
+        rule: "riskScore",
+        message: "riskScore is missing (required by autoPromote)"
+      });
+    } else {
+      if (requires.riskScore.min !== void 0 && r < requires.riskScore.min) {
+        failures.push({
+          rule: "riskScore",
+          message: `riskScore ${r} < min ${requires.riskScore.min}`
+        });
+      }
+      if (requires.riskScore.max !== void 0 && r > requires.riskScore.max) {
+        failures.push({
+          rule: "riskScore",
+          message: `riskScore ${r} > max ${requires.riskScore.max}`
+        });
+      }
+    }
+  }
+  if (requires.hasArchiveHash) {
+    const h = get("contentHash") ?? get("content_hash");
+    if (typeof h !== "string" || !/^(sha256|sha512|blake3):/.test(h)) {
+      failures.push({
+        rule: "hasArchiveHash",
+        message: "candidate has no archive-grade content_hash"
+      });
+    }
+  }
+  if (requires.requiredFields && requires.requiredFields.length > 0) {
+    const analysis = candidate.analysis ?? {};
+    const body = candidate.body;
+    for (const field of requires.requiredFields) {
+      const inAnalysis = analysis[field];
+      const inBody = body.includes(`## ${humanize(field)}`) || body.includes(`## ${field}`);
+      if ((typeof inAnalysis !== "string" || inAnalysis.trim().length === 0) && !inBody) {
+        failures.push({
+          rule: "requiredFields",
+          message: `candidate is missing required field "${field}" (not in analysis.${field} nor in body section "## ${humanize(field)}")`
+        });
+      }
+    }
+  }
+  if (requires.notRestricted) {
+    const access = corpusMeta.access;
+    const cls = access?.classification;
+    if (cls === "restricted" || cls === "secret") {
+      failures.push({
+        rule: "notRestricted",
+        message: `candidate access.classification is "${cls}" \u2014 fails notRestricted gate`
+      });
+    }
+  }
+  return {
+    passed: failures.length === 0,
+    failures: Object.freeze(failures),
+    disabled: false
+  };
+}
+function humanize(field) {
+  const spaced = field.replace(/_/g, " ").replace(/([a-z])([A-Z])/g, "$1 $2").toLowerCase();
+  return spaced.charAt(0).toUpperCase() + spaced.slice(1);
+}
+
+// src/lifecycle/promote.ts
+var PromoteRejectedError = class extends Error {
+  constructor(entrySlug, failures) {
+    super(
+      `PromoteRejectedError: ${entrySlug} failed auto-promote gate \u2014 ${failures.map((f) => `[${f.rule}] ${f.message}`).join(" / ")}`
+    );
+    this.entrySlug = entrySlug;
+    this.failures = failures;
+    this.name = "PromoteRejectedError";
+  }
+};
+var CorpusPromoter = class {
+  constructor(ctx) {
+    this.ctx = ctx;
+  }
+  async promote(opts) {
+    const reader = new CorpusWorkspaceReader({ fs: this.ctx.fs });
+    const writer = new CorpusWorkspaceWriter({ fs: this.ctx.fs });
+    const emitter = new CorpusEventEmitter({
+      fs: this.ctx.fs,
+      clock: this.ctx.clock,
+      identity: this.ctx.identity,
+      workspaceRoot: opts.workspacePath
+    });
+    const lockPath = joinPath3(opts.workspacePath, "_log.md");
+    return await writer.transaction(lockPath, async () => {
+      const snapshot = await reader.read(opts.workspacePath);
+      let gatePassed = false;
+      let bypassed = false;
+      if (opts.bypassGate) {
+        bypassed = true;
+      } else {
+        const config = extractAutoPromoteConfig(snapshot);
+        const result = evaluateGate(
+          {
+            frontmatter: opts.frontmatter,
+            body: opts.body
+          },
+          config
+        );
+        gatePassed = result.passed;
+        if (!result.passed && !result.disabled) {
+          throw new PromoteRejectedError(opts.entrySlug, result.failures);
+        }
+        if (result.disabled) bypassed = true;
+      }
+      const existing = snapshot.entries.find(
+        (e) => e.frontmatter.slug === opts.entrySlug
+      );
+      const targetPath = existing?.path ?? opts.entryPath;
+      const expectedToken = existing?.versionToken ?? null;
+      const identity = await this.ctx.identity.resolve();
+      const attestedFm = appendAttestation(
+        opts.frontmatter,
+        makeAttestation({
+          kind: "promoted",
+          identity: identity.principal,
+          at: this.ctx.clock.now().toISOString(),
+          note: bypassed ? `bypassed=true${gatePassed ? "" : " (gate not consulted)"}` : `gatePassed=${gatePassed}`
+        })
+      );
+      const doc = {
+        frontmatter: attestedFm,
+        body: opts.body
+      };
+      const entryAbsPath = joinPath3(opts.workspacePath, targetPath);
+      const entryVersionToken = await writer.writeMarkdown(
+        entryAbsPath,
+        doc,
+        expectedToken
+      );
+      const freshSnapshot = await reader.read(opts.workspacePath);
+      const indexResult = await this.ctx.indexer.syncEntry(
+        freshSnapshot,
+        opts.entrySlug
+      );
+      await regenIndexFile({
+        fs: this.ctx.fs,
+        workspacePath: opts.workspacePath,
+        snapshot: freshSnapshot,
+        clock: this.ctx.clock
+      });
+      if (opts.candidateId && opts.candidateSidecarPath) {
+        const { CandidatesSidecar: CandidatesSidecar2 } = await import('./sidecar-TTWQD5R3.mjs');
+        const sidecar = new CandidatesSidecar2({
+          fs: this.ctx.fs,
+          path: joinPath3(opts.workspacePath, opts.candidateSidecarPath)
+        });
+        try {
+          await sidecar.take(opts.candidateId);
+        } catch {
+        }
+      }
+      await emitter.emit("corpus.entry.promoted", {
+        slug: opts.entrySlug,
+        kind: opts.entryKind,
+        entryPath: targetPath,
+        candidateId: opts.candidateId,
+        bypassed,
+        gatePassed,
+        chunkCount: indexResult.chunkCount
+      });
+      return {
+        entryPath: targetPath,
+        entryVersionToken,
+        chunkCount: indexResult.chunkCount,
+        gatePassed,
+        bypassed
+      };
+    });
+  }
+};
+async function regenIndexFile(input) {
+  const lines = [];
+  lines.push("# Corpus index");
+  lines.push("");
+  lines.push(
+    `Generated ${input.clock.now().toISOString()} \u2014 ${input.snapshot.entries.length} entries.`
+  );
+  lines.push("");
+  const byKind = /* @__PURE__ */ new Map();
+  for (const entry of input.snapshot.entries) {
+    const k = String(entry.frontmatter.kind ?? "unknown");
+    const bucket = byKind.get(k) ?? [];
+    bucket.push(entry);
+    byKind.set(k, bucket);
+  }
+  for (const [kind, entries] of [...byKind].sort(
+    ([a], [b]) => a.localeCompare(b)
+  )) {
+    lines.push(`## ${kind} (${entries.length})`);
+    lines.push("");
+    for (const e of entries.sort(
+      (a, b) => String(a.frontmatter.slug).localeCompare(String(b.frontmatter.slug))
+    )) {
+      const slug = e.frontmatter.slug;
+      const title = e.frontmatter.title ?? slug;
+      const corpus = e.frontmatter.metadata?.corpus;
+      const q = corpus?.qualityScore;
+      const s = corpus?.status ?? "active";
+      const meta = [];
+      if (s !== "active") meta.push(`status=${s}`);
+      if (typeof q === "number") meta.push(`q=${q.toFixed(1)}`);
+      const suffix = meta.length > 0 ? `  _(${meta.join(", ")})_` : "";
+      lines.push(`- [[${slug}]] \u2014 ${title}${suffix}`);
+    }
+    lines.push("");
+  }
+  const content = lines.join("\n");
+  await input.fs.writeFile(
+    joinPath3(input.workspacePath, "_index.md"),
+    content
+  );
+}
+function joinPath3(a, b) {
+  if (!a) return b;
+  return a.endsWith("/") ? a + b : a + "/" + b;
+}
+
+// src/index/chunker.ts
+var DEFAULT_TARGET = 1500;
+var DEFAULT_OVERLAP = 150;
+var DEFAULT_MAX_BYTES = 64 * 1024;
+function chunkText(text, opts = {}) {
+  const target = opts.targetChars ?? DEFAULT_TARGET;
+  const overlap = opts.overlapChars ?? DEFAULT_OVERLAP;
+  const maxBytes = opts.maxBytes ?? DEFAULT_MAX_BYTES;
+  if (overlap >= target) {
+    throw new Error("chunkText: overlap must be < target");
+  }
+  const trimmed = text.trim();
+  if (trimmed.length === 0) return [];
+  if (byteLength(trimmed) <= maxBytes && trimmed.length <= target) {
+    return [trimmed];
+  }
+  const chunks = [];
+  let cursor = 0;
+  while (cursor < trimmed.length) {
+    let end = Math.min(cursor + target, trimmed.length);
+    let slice = trimmed.slice(cursor, end);
+    while (byteLength(slice) > maxBytes && slice.length > 1) {
+      end = cursor + Math.floor((end - cursor) * 0.9);
+      slice = trimmed.slice(cursor, end);
+    }
+    chunks.push(slice);
+    if (end >= trimmed.length) break;
+    cursor = end - overlap;
+    if (cursor < 0) cursor = 0;
+  }
+  return chunks;
+}
+function byteLength(s) {
+  return new TextEncoder().encode(s).length;
+}
+
+// src/index/indexer.ts
+var CorpusIndexer = class {
+  constructor(opts) {
+    this.opts = opts;
+  }
+  /**
+   * Re-sync every active entry. Used at boot (cold-install) and by
+   * the admin `corpus reindex` command for drift recovery.
+   */
+  async reindex(snapshot) {
+    let pushed = 0;
+    let removed = 0;
+    let skipped = 0;
+    let chunkCount = 0;
+    for (const entry of snapshot.entries) {
+      const status = readStatus(entry);
+      if (status === "active") {
+        const n = await this.pushEntry(entry);
+        pushed++;
+        chunkCount += n;
+      } else if (status === "deprecated" || status === "archived") {
+        const slug = entry.frontmatter.slug;
+        if (typeof slug === "string") {
+          const r = await this.opts.writer.removeEntry(slug);
+          removed += r.removed > 0 ? 1 : 0;
+        }
+      } else {
+        skipped++;
+      }
+    }
+    return { pushed, removed, skipped, chunkCount };
+  }
+  /**
+   * Re-sync a single entry by slug. The lifecycle's `promote`
+   * workflow calls this immediately after writing the entry file.
+   */
+  async syncEntry(snapshot, slug) {
+    const entry = snapshot.entries.find((e) => e.frontmatter.slug === slug);
+    if (!entry) {
+      await this.opts.writer.removeEntry(slug);
+      return { chunkCount: 0 };
+    }
+    const status = readStatus(entry);
+    if (status !== "active") {
+      await this.opts.writer.removeEntry(slug);
+      return { chunkCount: 0 };
+    }
+    await this.opts.writer.removeEntry(slug);
+    const n = await this.pushEntry(entry);
+    return { chunkCount: n };
+  }
+  /** Drop one entry from the backing engine (deprecation, GDPR erase). */
+  async removeEntry(slug) {
+    await this.opts.writer.removeEntry(slug);
+  }
+  // ── Internal ─────────────────────────────────────────────────────
+  async pushEntry(entry) {
+    const slug = entry.frontmatter.slug;
+    if (typeof slug !== "string") return 0;
+    const chunks = chunkText(entry.body, this.opts.chunker).map((text) => ({
+      text
+    }));
+    const corpus = readCorpusMetadata(entry);
+    await this.opts.writer.pushChunks({
+      entrySlug: slug,
+      entryPath: entry.path,
+      title: typeof entry.frontmatter.title === "string" ? entry.frontmatter.title : void 0,
+      chunks,
+      // Forward the corpus-namespaced metadata so the engine adapter
+      // can hydrate hits without re-reading the file.
+      entryMetadata: {
+        kind: entry.frontmatter.kind,
+        sources: entry.frontmatter.sources,
+        confidence: entry.frontmatter.confidence,
+        tags: entry.frontmatter.tags,
+        ...corpus
+      }
+    });
+    return chunks.length;
+  }
+};
+function readStatus(entry) {
+  const corpus = entry.frontmatter.metadata?.corpus;
+  const s = corpus?.status;
+  return typeof s === "string" ? s : "active";
+}
+function readCorpusMetadata(entry) {
+  const corpus = entry.frontmatter.metadata?.corpus;
+  return corpus ?? {};
+}
+var ANY_REF = "*";
+function prefixedRefNormalizer(singular, plural) {
+  const bare = `${singular}/`;
+  const ws = `ws://${plural}/`;
+  return (ref) => {
+    const stripped = ref.startsWith(bare) ? ref.slice(bare.length) : ref.startsWith(ws) ? ref.slice(ws.length) : ref;
+    return stripped === "*" ? ANY_REF : stripped;
+  };
+}
+var SLUG_RE = /^[a-z][a-z0-9-]*[a-z0-9]$/;
+function slugValidator(ref) {
+  if (ref === ANY_REF) return null;
+  return SLUG_RE.test(ref) ? null : `not a slug (lowercase, digits, dashes): "${ref}"`;
+}
+var identityAxis = {
+  id: "identity",
+  aip: 9,
+  description: "The subject's own slug \u2014 targets one specific operator.",
+  normalizeRef: prefixedRefNormalizer("operator", "operators"),
+  validateRef: slugValidator
+};
+var roleAxis = {
+  id: "role",
+  aip: 47,
+  description: "The AIP-47 catalog role (job) the subject fulfils \u2014 targets every operator in the role.",
+  normalizeRef: prefixedRefNormalizer("role", "roles"),
+  validateRef: slugValidator
+};
+var positionAxis = {
+  id: "position",
+  aip: 6,
+  description: "The host-assigned seat label (slugified) \u2014 targets the one operator holding the seat. See AIP-47 \xA7Role vs Position vs Access role.",
+  normalizeRef: prefixedRefNormalizer("position", "positions"),
+  validateRef: slugValidator
+};
+var capabilityAxis = {
+  id: "capability",
+  aip: 9,
+  description: "A capability slug the subject carries.",
+  normalizeRef: prefixedRefNormalizer("capability", "capabilities"),
+  validateRef: slugValidator
+};
+var WELL_KNOWN_AXES = Object.freeze([
+  identityAxis,
+  roleAxis,
+  positionAxis,
+  capabilityAxis
+]);
+function createAxisRegistry(extra = []) {
+  const registry = createRegistry({
+    family: "binding-axis",
+    keyBy: (axis) => axis.id
+  });
+  for (const axis of WELL_KNOWN_AXES) registry.register(axis);
+  for (const axis of extra) registry.register(axis);
+  return registry;
+}
+
+// src/binding/selector.ts
+var EMPTY_SELECTOR = Object.freeze({});
+function isEmptySelector(selector) {
+  return !selector.allOf?.length && !selector.anyOf?.length;
+}
+function matchesSelector(selector, dimensions, options = {}) {
+  if (isEmptySelector(selector)) return false;
+  const { allOf, anyOf } = selector;
+  if (allOf?.length) {
+    for (const term of allOf) {
+      if (!termMatches(term, dimensions, options)) return false;
+    }
+  }
+  if (anyOf?.length) {
+    return anyOf.some((term) => termMatches(term, dimensions, options));
+  }
+  return true;
+}
+function termMatches(term, dimensions, options) {
+  const raw = dimensions[term.axis];
+  if (raw === void 0) return false;
+  const values = typeof raw === "string" ? [raw] : raw;
+  if (values.length === 0) return false;
+  const axis = options.axes?.get(term.axis);
+  for (const ref of term.anyOf) {
+    const normalized = normalizeRef(ref, axis);
+    if (normalized === ANY_REF) return true;
+    if (values.includes(normalized)) return true;
+  }
+  return false;
+}
+function normalizeRef(ref, axis) {
+  return axis?.normalizeRef ? axis.normalizeRef(ref) : ref;
+}
+
+// src/binding/parse.ts
+function parseSelectorFrontmatter(raw) {
+  if (!isPlainObject(raw)) return null;
+  if ("allOf" in raw || "anyOf" in raw) {
+    const allOf2 = readTermList(raw.allOf);
+    const anyOf = readTermList(raw.anyOf);
+    if (allOf2 === null || anyOf === null) return null;
+    if (!allOf2.length && !anyOf.length) return null;
+    return Object.freeze({
+      ...allOf2.length ? { allOf: allOf2 } : {},
+      ...anyOf.length ? { anyOf } : {}
+    });
+  }
+  const allOf = [];
+  for (const [axis, value] of Object.entries(raw)) {
+    const refs = readRefs(value);
+    if (refs === null) return null;
+    allOf.push(Object.freeze({ axis, anyOf: refs }));
+  }
+  if (!allOf.length) return null;
+  return Object.freeze({ allOf: Object.freeze(allOf) });
+}
+function readTermList(raw) {
+  if (raw === void 0) return [];
+  if (!Array.isArray(raw)) return null;
+  const out = [];
+  for (const entry of raw) {
+    if (!isPlainObject(entry)) return null;
+    const axis = entry.axis;
+    if (typeof axis !== "string" || !axis.length) return null;
+    const refs = readRefs(entry.anyOf);
+    if (refs === null || !refs.length) return null;
+    out.push(Object.freeze({ axis, anyOf: refs }));
+  }
+  return Object.freeze(out);
+}
+function readRefs(value) {
+  if (typeof value === "string") {
+    return value.length ? Object.freeze([value]) : null;
+  }
+  if (Array.isArray(value)) {
+    const refs = value;
+    if (!refs.length) return null;
+    if (!refs.every((r) => typeof r === "string" && r.length > 0))
+      return null;
+    return Object.freeze([...refs]);
+  }
+  return null;
+}
+function isPlainObject(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+// src/binding/legacy.ts
+var normalizeOperatorRef = identityAxis.normalizeRef;
+var normalizeRoleRef = roleAxis.normalizeRef;
+var normalizeSkillRef = prefixedRefNormalizer("skill", "skills");
+var normalizeRuntimeRef = prefixedRefNormalizer("runtime", "runtimes");
+function compileLegacyPlaybookBinding(targets, bindsOperator) {
+  const identity = /* @__PURE__ */ new Set();
+  const role = /* @__PURE__ */ new Set();
+  const skill = /* @__PURE__ */ new Set();
+  const runtime = /* @__PURE__ */ new Set();
+  if (bindsOperator) {
+    identity.add(normalizeOperatorRef(bindsOperator));
+    role.add(normalizeRoleRef(bindsOperator));
+  }
+  for (const target of targets) {
+    switch (target.kind) {
+      case "operator":
+        identity.add(normalizeOperatorRef(target.ref));
+        role.add(normalizeRoleRef(target.ref));
+        break;
+      case "role":
+        role.add(normalizeRoleRef(target.ref));
+        break;
+      case "skill":
+        skill.add(normalizeSkillRef(target.ref));
+        break;
+      case "runtime":
+        runtime.add(normalizeRuntimeRef(target.ref));
+        break;
+    }
+  }
+  const anyOf = [];
+  pushTerm(anyOf, identityAxis.id, identity);
+  pushTerm(anyOf, roleAxis.id, role);
+  pushTerm(anyOf, "skill", skill);
+  pushTerm(anyOf, "runtime", runtime);
+  if (!anyOf.length) return Object.freeze({});
+  return Object.freeze({ anyOf: Object.freeze(anyOf) });
+}
+function pushTerm(out, axis, refs) {
+  if (!refs.size) return;
+  out.push(Object.freeze({ axis, anyOf: Object.freeze([...refs]) }));
+}
+
+// src/binding/attachment.ts
+function matchAttachments(declarations, dimensions, options = {}) {
+  return declarations.filter(
+    (d) => matchesSelector(d.selector, dimensions, { axes: options.axes })
+  );
+}
+function matchAttachmentRefs(declarations, kind, dimensions, options = {}) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const d of matchAttachments(declarations, dimensions, options)) {
+    if (d.asset.kind === kind) seen.add(d.asset.ref);
+  }
+  return [...seen];
+}
+
+// src/playbooks/registry.ts
+var PlaybookRegistry = class {
+  bySlug;
+  all;
+  constructor(opts) {
+    const parsed = [];
+    for (const file of opts.snapshot.playbooks) {
+      const playbook = parsePlaybook(file);
+      if (playbook) parsed.push(playbook);
+    }
+    parsed.sort((a, b) => b.priority - a.priority);
+    this.all = Object.freeze(parsed);
+    const map = /* @__PURE__ */ new Map();
+    for (const p of parsed) map.set(p.slug, p);
+    this.bySlug = map;
+  }
+  list() {
+    return this.all;
+  }
+  bySlugOrNull(slug) {
+    return this.bySlug.get(slug) ?? null;
+  }
+  listBy(query = {}) {
+    return this.all.filter((p) => matches(p, query));
+  }
+};
+function parsePlaybook(file) {
+  const fm = file.frontmatter;
+  const slug = typeof fm.slug === "string" ? fm.slug : null;
+  const title = typeof fm.title === "string" ? fm.title : null;
+  if (!slug || !title) return null;
+  const status = readStatus2(fm);
+  const kind = fm.kind === "block-replacement" ? "block-replacement" : "overlay";
+  const priority = typeof fm.priority === "number" ? fm.priority : 100;
+  const bindsOperator = typeof fm.binds_operator === "string" ? fm.binds_operator : void 0;
+  const targets = readTargets(fm);
+  const supersedes = readStringArray(fm.supersedes);
+  const corpus = readCorpusMeta(fm);
+  const explicitSelector = parseSelectorFrontmatter(fm.selector);
+  const selector = explicitSelector ?? compileLegacyPlaybookBinding(targets, bindsOperator);
+  const selectorSource = explicitSelector ? "selector" : "legacy";
+  return Object.freeze({
+    path: file.path,
+    slug,
+    title,
+    status,
+    kind,
+    priority,
+    targets,
+    bindsOperator,
+    selector,
+    selectorSource,
+    supersedes,
+    body: file.body,
+    corpus,
+    versionToken: file.versionToken,
+    file
+  });
+}
+function readStatus2(fm) {
+  const s = fm.status;
+  if (s === "active" || s === "shadow" || s === "archived") return s;
+  return "shadow";
+}
+function readTargets(fm) {
+  const raw = fm.targets;
+  if (!Array.isArray(raw)) return [];
+  const out = [];
+  for (const t of raw) {
+    if (typeof t !== "object" || t === null) continue;
+    const o = t;
+    if (typeof o.ref !== "string" || o.kind !== "operator" && o.kind !== "role" && o.kind !== "skill" && o.kind !== "runtime")
+      continue;
+    out.push({ kind: o.kind, ref: o.ref });
+  }
+  return Object.freeze(out);
+}
+function readStringArray(v) {
+  if (!Array.isArray(v)) return [];
+  return Object.freeze(
+    v.filter((x) => typeof x === "string")
+  );
+}
+function readCorpusMeta(fm) {
+  const meta = fm.metadata?.corpus;
+  if (!meta || typeof meta !== "object") return {};
+  return Object.freeze(meta);
+}
+var AXES = createAxisRegistry();
+function matches(p, q) {
+  if (q.status !== void 0) {
+    const wanted = Array.isArray(q.status) ? q.status : [q.status];
+    if (!wanted.includes(p.status)) return false;
+  }
+  if (q.kind !== void 0 && p.kind !== q.kind) return false;
+  if (q.dimensions !== void 0) {
+    return matchesSelector(p.selector, q.dimensions, { axes: AXES });
+  }
+  if (q.forOperatorSlug !== void 0) {
+    const slugs = Array.isArray(q.forOperatorSlug) ? q.forOperatorSlug : [q.forOperatorSlug];
+    return matchesSelector(
+      p.selector,
+      { identity: slugs, role: slugs },
+      { axes: AXES }
+    );
+  }
+  if (q.operatorRef !== void 0) {
+    return p.targets.some(
+      (t) => t.kind === "operator" && t.ref === q.operatorRef
+    );
+  }
+  return true;
+}
+
+// src/playbooks/resolver.ts
+var OperatorOverlayResolver = class {
+  constructor(registry) {
+    this.registry = registry;
+  }
+  resolve(ctx) {
+    const slugs = ctx.roleSlug ? [ctx.operatorSlug, ctx.roleSlug] : [ctx.operatorSlug];
+    const candidates = this.registry.listBy({
+      ...ctx.dimensions ? { dimensions: ctx.dimensions } : { forOperatorSlug: slugs },
+      status: ["active", "shadow"]
+    });
+    const overlays = [];
+    for (const p of candidates) {
+      if (p.status === "archived") continue;
+      const shadowSampled = p.status === "shadow" ? sampleShadow2(ctx, p) : false;
+      if (p.status === "shadow" && !shadowSampled) continue;
+      overlays.push({
+        playbookSlug: p.slug,
+        status: p.status,
+        kind: p.kind,
+        priority: p.priority,
+        body: p.body,
+        playbookPath: p.path,
+        shadowSampled
+      });
+    }
+    return Object.freeze({
+      operatorSlug: ctx.operatorSlug,
+      overlays: Object.freeze(overlays)
+    });
+  }
+};
+function sampleShadow2(ctx, p) {
+  const pct = typeof p.corpus.shadowTrafficPct === "number" ? p.corpus.shadowTrafficPct : DEFAULT_SHADOW_TRAFFIC_PCT;
+  return sampleShadow(ctx.conversationId, p.slug, pct);
+}
+function renderOverlays(result) {
+  const overlays = result.overlays.filter((o) => o.kind === "overlay");
+  const replacements = result.overlays.filter((o) => o.kind === "block-replacement").map((o) => ({ playbookSlug: o.playbookSlug, body: o.body }));
+  return Object.freeze({
+    appendBlock: overlays.map((o) => o.body.trim()).join("\n\n---\n\n"),
+    replacements: Object.freeze(replacements)
+  });
+}
+var PlaybookNotFoundError = class extends Error {
+  constructor(slug) {
+    super(`PlaybookNotFoundError: no playbook found with slug "${slug}"`);
+    this.slug = slug;
+    this.name = "PlaybookNotFoundError";
+  }
+};
+var IllegalPlaybookTransitionError = class extends Error {
+  constructor(slug, from, to) {
+    super(
+      `IllegalPlaybookTransitionError: ${slug}: ${from} \u2192 ${to} is not allowed`
+    );
+    this.slug = slug;
+    this.from = from;
+    this.to = to;
+    this.name = "IllegalPlaybookTransitionError";
+  }
+};
+var PlaybookLifecycle = class {
+  constructor(opts) {
+    this.opts = opts;
+  }
+  /**
+   * Transition `slug` from shadow → active. Cascades through
+   * `supersedes[]`: any currently-active playbook listed there is
+   * archived (with `archiveReason: superseded-by-<slug>`) in the
+   * same lock-guarded transaction.
+   */
+  async activate(slug) {
+    const writer = new CorpusWorkspaceWriter({ fs: this.opts.fs });
+    const lockPath = joinPath4(this.opts.workspacePath, "_log.md");
+    return await writer.transaction(lockPath, async () => {
+      const playbook = await this.loadOne(slug);
+      assertTransition2(playbook.status, "active", slug);
+      const supersededSlugs = [];
+      const reg = await this.loadRegistry();
+      const identity = await this.opts.identity.resolve();
+      for (const supersededSlug of playbook.supersedes) {
+        const prev = reg.bySlugOrNull(supersededSlug);
+        if (!prev || prev.status !== "active") continue;
+        const att = this.attestation(
+          "archived",
+          identity.principal,
+          `superseded-by-${slug}`
+        );
+        await this.writeWith(
+          prev,
+          (fm) => appendAttestation(
+            patchStatus(fm, "archived", {
+              archiveReason: `superseded-by-${slug}`,
+              archivedAt: att.at
+            }),
+            att
+          )
+        );
+        await this.emitter().emit("playbook.archived", {
+          slug: prev.slug,
+          archiveReason: `superseded-by-${slug}`
+        });
+        supersededSlugs.push(prev.slug);
+      }
+      const activateAtt = this.attestation(
+        "activated",
+        identity.principal,
+        `from=${playbook.status}`
+      );
+      const newToken = await this.writeWith(
+        playbook,
+        (fm) => appendAttestation(
+          patchStatus(fm, "active", { activatedAt: activateAtt.at }),
+          activateAtt
+        )
+      );
+      await this.emitter().emit("playbook.activated", {
+        slug,
+        previousStatus: playbook.status,
+        supersededSlugs
+      });
+      return {
+        slug,
+        previousStatus: playbook.status,
+        versionToken: newToken,
+        supersededSlugs: Object.freeze(supersededSlugs)
+      };
+    });
+  }
+  /**
+   * Transition `slug` → archived. Skip-no-op if already archived.
+   */
+  async archive(slug, reason) {
+    const writer = new CorpusWorkspaceWriter({ fs: this.opts.fs });
+    const lockPath = joinPath4(this.opts.workspacePath, "_log.md");
+    return await writer.transaction(lockPath, async () => {
+      const playbook = await this.loadOne(slug);
+      if (playbook.status === "archived") {
+        return {
+          slug,
+          previousStatus: "archived",
+          versionToken: playbook.versionToken
+        };
+      }
+      assertTransition2(playbook.status, "archived", slug);
+      const identity = await this.opts.identity.resolve();
+      const att = this.attestation("archived", identity.principal, reason);
+      const newToken = await this.writeWith(
+        playbook,
+        (fm) => appendAttestation(
+          patchStatus(fm, "archived", {
+            archiveReason: reason,
+            archivedAt: att.at
+          }),
+          att
+        )
+      );
+      await this.emitter().emit("playbook.archived", {
+        slug,
+        previousStatus: playbook.status,
+        archiveReason: reason
+      });
+      return {
+        slug,
+        previousStatus: playbook.status,
+        versionToken: newToken
+      };
+    });
+  }
+  // ── Internal ─────────────────────────────────────────────────────
+  async loadOne(slug) {
+    const reg = await this.loadRegistry();
+    const p = reg.bySlugOrNull(slug);
+    if (!p) throw new PlaybookNotFoundError(slug);
+    return p;
+  }
+  async loadRegistry() {
+    const reader = new CorpusWorkspaceReader({ fs: this.opts.fs });
+    const snapshot = await reader.read(this.opts.workspacePath);
+    return new PlaybookRegistry({ snapshot });
+  }
+  async writeWith(playbook, patch) {
+    const writer = new CorpusWorkspaceWriter({ fs: this.opts.fs });
+    const nextFm = patch({ ...playbook.file.frontmatter });
+    const nextContent = matter.stringify(
+      playbook.body.startsWith("\n") ? playbook.body : "\n" + playbook.body,
+      nextFm
+    );
+    return await writer.writeFile(
+      joinPath4(this.opts.workspacePath, playbook.path),
+      nextContent,
+      playbook.versionToken
+    );
+  }
+  /** Build a transition attestation from current clock + given identity. */
+  attestation(kind, identity, note) {
+    return makeAttestation({
+      kind,
+      identity,
+      at: this.opts.clock.now().toISOString(),
+      ...note ? { note } : {}
+    });
+  }
+  emitter() {
+    return new CorpusEventEmitter({
+      fs: this.opts.fs,
+      clock: this.opts.clock,
+      identity: this.opts.identity,
+      workspaceRoot: this.opts.workspacePath
+    });
+  }
+};
+function assertTransition2(from, to, slug) {
+  const allowed = {
+    shadow: ["active", "archived"],
+    active: ["archived"],
+    archived: []
+  };
+  if (!allowed[from].includes(to)) {
+    throw new IllegalPlaybookTransitionError(slug, from, to);
+  }
+}
+function patchStatus(fm, newStatus, extraCorpusMeta) {
+  const metaIn = fm.metadata ?? {};
+  const corpusIn = metaIn.corpus ?? {};
+  return {
+    ...fm,
+    status: newStatus,
+    metadata: {
+      ...metaIn,
+      corpus: {
+        ...corpusIn,
+        ...extraCorpusMeta
+      }
+    }
+  };
+}
+function joinPath4(a, b) {
+  if (!a) return b;
+  return a.endsWith("/") ? a + b : a + "/" + b;
+}
+var PlaybookEvaluator = class {
+  constructor(opts) {
+    this.opts = opts;
+  }
+  /**
+   * Run an eval batch against a single playbook. For each case:
+   *   1. Score shadow.response against rubric → shadowScore
+   *   2. Score baseline.response against rubric → baselineScore
+   *   3. shadow "wins" if shadowScore >= baselineScore
+   * Aggregate: winRateVsBaseline = wins / n.
+   *
+   * On completion: writes shadowMetrics back to the PLAYBOOK.md (CAS),
+   * emits a `corpus.playbook.evaluated` event (held outside the formal
+   * AIP-41 taxonomy until the spec adopts it).
+   */
+  async runBatch(playbookSlug, batch) {
+    const playbook = await this.loadPlaybook(playbookSlug);
+    const perCase = [];
+    let wins = 0;
+    let shadowSum = 0;
+    let baselineSum = 0;
+    for (const c of batch.cases) {
+      const shadowResult = await this.opts.evaluator.evaluate({
+        rubric: batch.rubric,
+        prompt: c.prompt,
+        response: c.shadowResponse,
+        context: {
+          ...batch.contextOverrides ?? {},
+          arm: "shadow",
+          appliedPlaybooks: [playbookSlug]
+        }
+      });
+      const baselineResult = await this.opts.evaluator.evaluate({
+        rubric: batch.rubric,
+        prompt: c.prompt,
+        response: c.baselineResponse,
+        context: {
+          ...batch.contextOverrides ?? {},
+          arm: "baseline",
+          appliedPlaybooks: []
+        }
+      });
+      const winnerArm = shadowResult.score > baselineResult.score ? "shadow" : shadowResult.score < baselineResult.score ? "baseline" : "tie";
+      if (winnerArm === "shadow") wins++;
+      shadowSum += shadowResult.score;
+      baselineSum += baselineResult.score;
+      perCase.push({
+        id: c.id,
+        shadowScore: shadowResult.score,
+        baselineScore: baselineResult.score,
+        winnerArm
+      });
+    }
+    const sampleSize = batch.cases.length;
+    const winRate = sampleSize > 0 ? wins / sampleSize : 0;
+    const auto = playbook.corpus.autoPromote ?? {};
+    const gteOK = typeof auto.threshold?.gte === "number" ? winRate >= auto.threshold.gte : false;
+    const sizeOK = typeof auto.minSampleSize === "number" ? sampleSize >= auto.minSampleSize : sampleSize > 0;
+    const readyForActivation = !!auto.enabled && gteOK && sizeOK;
+    await this.persistMetrics(playbook, {
+      sampleSize,
+      winRateVsBaseline: winRate,
+      lastEvaluatedAt: this.opts.clock.now().toISOString()
+    });
+    await this.appendCustomEvent("playbook.shadow.evaluated", {
+      slug: playbook.slug,
+      sampleSize,
+      winRateVsBaseline: winRate,
+      readyForActivation
+    });
+    return Object.freeze({
+      playbookSlug: playbook.slug,
+      sampleSize,
+      winRateVsBaseline: winRate,
+      shadowAvgScore: sampleSize > 0 ? shadowSum / sampleSize : 0,
+      baselineAvgScore: sampleSize > 0 ? baselineSum / sampleSize : 0,
+      readyForActivation,
+      perCase: Object.freeze(perCase)
+    });
+  }
+  // ── Internal ─────────────────────────────────────────────────────
+  async loadPlaybook(slug) {
+    const reader = new CorpusWorkspaceReader({ fs: this.opts.fs });
+    const snapshot = await reader.read(this.opts.workspacePath);
+    const reg = new PlaybookRegistry({ snapshot });
+    const p = reg.bySlugOrNull(slug);
+    if (!p) throw new PlaybookNotFoundError(slug);
+    return p;
+  }
+  async persistMetrics(playbook, metrics) {
+    const writer = new CorpusWorkspaceWriter({ fs: this.opts.fs });
+    const identity = await this.opts.identity.resolve();
+    let fm = { ...playbook.file.frontmatter };
+    const metaIn = fm.metadata ?? {};
+    const corpusIn = metaIn.corpus ?? {};
+    fm.metadata = {
+      ...metaIn,
+      corpus: {
+        ...corpusIn,
+        shadowMetrics: metrics
+      }
+    };
+    fm = appendAttestation(
+      fm,
+      makeAttestation({
+        kind: "evaluated",
+        identity: identity.principal,
+        at: metrics.lastEvaluatedAt,
+        note: `n=${metrics.sampleSize} winRate=${metrics.winRateVsBaseline.toFixed(3)}`
+      })
+    );
+    const content = matter.stringify(
+      playbook.body.startsWith("\n") ? playbook.body : "\n" + playbook.body,
+      fm
+    );
+    await writer.writeFile(
+      joinPath5(this.opts.workspacePath, playbook.path),
+      content,
+      playbook.versionToken
+    );
+  }
+  async appendCustomEvent(customKind, payload) {
+    const identity = await this.opts.identity.resolve();
+    const line = `- ${this.opts.clock.now().toISOString()}  ${customKind}  by ${identity.principal}  payload=${JSON.stringify(payload, [...Object.keys(payload).sort()])}
+`;
+    const logPath = joinPath5(this.opts.workspacePath, "_log.md");
+    if (!await this.opts.fs.exists(logPath)) {
+      new CorpusEventEmitter({
+        fs: this.opts.fs,
+        clock: this.opts.clock,
+        identity: this.opts.identity,
+        workspaceRoot: this.opts.workspacePath
+      });
+      await this.opts.fs.writeFile(
+        logPath,
+        "# Corpus activity log\n\nAppend-only AIP-10 log of corpus state transitions. Each line:\n`- <iso>  <kind>  by <actor>  payload=<json>`\n\n"
+      );
+    }
+    await this.opts.fs.appendFile(logPath, line);
+  }
+};
+function joinPath5(a, b) {
+  if (!a) return b;
+  return a.endsWith("/") ? a + b : a + "/" + b;
+}
+
+// src/index.ts
+var SPEC_NAME = "agentcorpus/v1";
+var SPEC_VERSION = "0.1.0-alpha";
+
+export { ANY_REF, ClaudeDistiller, ConversationImporter, CorpusEventEmitter, CorpusIndexer, CorpusLinter, CorpusPromoter, CorpusValidator, CorpusVersionConflictError, CorpusWorkspaceReader, CorpusWorkspaceWriter, DEFAULT_TRANSITIONS, DistillRunner, EMPTY_SELECTOR, IllegalPlaybookTransitionError, IllegalTransitionError, ImporterRunner, KbMigrationImporter, LocalFilesImporter, MemFs, OperatorOverlayResolver, OverlayFs, PlaybookEvaluator, PlaybookLifecycle, PlaybookNotFoundError, PlaybookRegistry, PromoteRejectedError, REFINED_KIND_SCHEMA, ReadOnlyFs, ReviewerTrackRecord, SPEC_NAME, SPEC_VERSION, StackResolver, SyncRunner, WELL_KNOWN_AXES, WHITEOUT_SUFFIX, WebImporter, aggregateReviewerScores, appendAttestation, assertTransition, buildDistillPrompt, buildOverlayFromStack, canTransition, capabilityAxis, chunkText, compileLegacyPlaybookBinding, computeReviewerCalibration, createAxisRegistry, createDistillRegistry, enumerateWindowRefs, evaluateAccess, evaluateCapability, evaluateGate, extractAutoPromoteConfig, flattenPackRefs, identityAxis, isEmptySelector, isEntrySlug, isRefinedKind, isSourceSlug, makeAttestation, matchAttachmentRefs, matchAttachments, matchesLanguageFilter, matchesSelector, normalizeLanguageTag, parseItems, parseSelectorFrontmatter, parseWindowRef, partitionStackRefs, pearsonCorrelation, positionAxis, prefixedRefNormalizer, readAccessModes, readAccessSpec, readAttestations, readEntryLanguage, readOperatorLocale, readWorkspaceDefaultLanguage, renderOverlays, resolveKnowledge, resolveLanguageFilter, roleAxis, runDistill, scanDistilledSourceIds, slugify, transitionGraphFromCollection, uniqueSlug, windowRef, windowSlug };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map