@agentproto/corpus 0.1.0-alpha.3 → 0.1.0

package/dist/{chunk-3P23OX5X.mjs → chunk-JV6VRZ6U.mjs}

@@ -89,5 +89,5 @@ async function resolveKnowledge(opts) {
 }
 
 export { REFINED_KIND_SCHEMA, isRefinedKind, resolveKnowledge };
-//# sourceMappingURL=chunk-3P23OX5X.mjs.map
-//# sourceMappingURL=chunk-3P23OX5X.mjs.map
+//# sourceMappingURL=chunk-JV6VRZ6U.mjs.map
+//# sourceMappingURL=chunk-JV6VRZ6U.mjs.map

package/dist/chunk-JV6VRZ6U.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/distill/types.ts","../src/knowledge/resolve.ts"],"names":["z"],"mappings":";;;;;;;;AAgBO,IAAM,mBAAA,GAAsB,EAAE,IAAA,CAAK;AAAA,EACxC,WAAA;AAAA,EACA,SAAA;AAAA,EACA,UAAA;AAAA,EACA,SAAA;AAAA,EACA;AACF,CAAC;AAKM,SAAS,cAAc,KAAA,EAAsC;AAClE,EAAA,OAAO,mBAAA,CAAoB,SAAA,CAAU,KAAK,CAAA,CAAE,OAAA;AAC9C;ACNA,IAAM,iBAAA,GAAoBA,EACvB,MAAA,CAAO;AAAA,EACN,QAAQA,CAAAA,CAAE,MAAA,GAAS,QAAA,EAAS,CAAE,MAAM,MAAS,CAAA;AAAA,EAC7C,MAAMA,CAAAA,CAAE,MAAA,GAAS,QAAA,EAAS,CAAE,MAAM,MAAS,CAAA;AAAA,EAC3C,MAAMA,CAAAA,CAAE,MAAA,GAAS,QAAA,EAAS,CAAE,MAAM,MAAS,CAAA;AAAA,EAC3C,OAAOA,CAAAA,CAAE,MAAA,GAAS,QAAA,EAAS,CAAE,MAAM,MAAS,CAAA;AAAA,EAC5C,OAAA,EAASA,CAAAA,CAAE,KAAA,CAAMA,CAAAA,CAAE,MAAA,EAAQ,CAAA,CAAE,QAAA,EAAS,CAAE,KAAA,CAAM,MAAS,CAAA;AAAA,EACvD,YAAYA,CAAAA,CAAE,MAAA,GAAS,QAAA,EAAS,CAAE,MAAM,MAAS,CAAA;AAAA,EACjD,IAAA,EAAMA,CAAAA,CAAE,KAAA,CAAMA,CAAAA,CAAE,MAAA,EAAQ,CAAA,CAAE,QAAA,EAAS,CAAE,KAAA,CAAM,MAAS,CAAA;AAAA,EACpD,QAAA,EAAUA,EACP,MAAA,CAAO;AAAA,IACN,MAAA,EAAQA,EACL,MAAA,CAAO;AAAA,MACN,QAAQA,CAAAA,CAAE,MAAA,GAAS,QAAA,EAAS,CAAE,MAAM,MAAS,CAAA;AAAA,MAC7C,QAAQA,CAAAA,CAAE,MAAA,GAAS,QAAA,EAAS,CAAE,MAAM,MAAS,CAAA;AAAA;AAAA;AAAA,MAG7C,aAAaA,CAAAA,CACV,KAAA;AAAA,QACCA,EACG,MAAA,CAAO;AAAA,UACN,EAAA,EAAIA,EAAE,MAAA,EAAO;AAAA,UACb,KAAKA,CAAAA,CAAE,MAAA,GAAS,QAAA,EAAS,CAAE,MAAM,MAAS,CAAA;AAAA,UAC1C,OAAOA,CAAAA,CAAE,MAAA,GAAS,QAAA,EAAS,CAAE,MAAM,MAAS,CAAA;AAAA,UAC5C,WAAWA,CAAAA,CAAE,MAAA,GAAS,QAAA,EAAS,CAAE,MAAM,MAAS,CAAA;AAAA,UAChD,UAAUA,CAAAA,CAAE,MAAA,GAAS,QAAA,EAAS,CAAE,MAAM,MAAS;AAAA,SAChD,EACA,KAAA;AAAM,OACX,CACC,QAAA,EAAS,CACT,KAAA,CAAM,MAAS;AAAA,KACnB,CAAA,CACA,KAAA,GACA,QAAA,EAAS,CACT,MAAM,MAAS;AAAA,GACnB,CAAA,CACA,KAAA,GACA,QAAA,EAAS,CACT,MAAM,MAAS;AACpB,CAAC,EACA,KAAA,EAAM;AA6CT,eAAsB,iBACpB,IAAA,EACmC;AACnC,EAAA,MAAM,EAAE,EAAA,EAAI,KAAA,EAAO,aAAA,EAAc,GAAI,IAAA;AACrC,EAAA,MAAM,QAAA,GAAW,IAAI,GAAA,CAAA,CAAK,KAAA,CAAM,IAAA,IAAQ,EAAC,EAAG,GAAA,CAAI,CAAA,CAAA,KAAK,CAAA,CAAE,WAAA,EAAa,CAAC,CAAA;AACrE,EAAA,MAAM,YAAY,KAAA,CAAM,KAAA,GAAQ,IAAI,GAAA,CAAI,KAAA,CAAM,KAAK,CAAA,GAAI,IAAA;AAEvD,EAAA,IAAI,IAAA;AACJ,EAAA,IAAI;AACF,IAAA,IAAA,GAAO,MAAM,EAAA,CAAG,IAAA,CAAK,SAAS,CAAA;AAAA,EAChC,CAAA,CAAA,MAAQ;AACN,IAAA,OAAO,EAAC;AAAA,EACV;AAEA,EAAA,MAAM,OAAwB,EAAC;AAC/B,EAAA,KAAA,MAAW,OAAO,IAAA,EAAM;AACtB,IAAA,IAAI,CAAC,GAAA,CAAI,QAAA,CAAS,KAAK,CAAA,EAAG;AAG1B,IAAA,MAAM,IAAA,GAAO,WAAW,GAAG,CAAA,CAAA;AAC3B,IAAA,IAAI,MAAA;AACJ,IAAA,IAAI;AACF,MAAA,MAAA,GAAS,MAAA,CAAO,MAAM,EAAA,CAAG,QAAA,CAAS,IAAI,CAAC,CAAA;AAAA,IACzC,CAAA,CAAA,MAAQ;AACN,MAAA;AAAA,IACF;AACA,IAAA,MAAM,EAAA,GAAK,iBAAA,CAAkB,KAAA,CAAM,MAAA,CAAO,IAAI,CAAA;AAC9C,IAAA,IAAI,EAAA,CAAG,WAAW,oBAAA,EAAsB;AAKxC,IAAA,IAAI,EAAA,CAAG,QAAA,EAAU,MAAA,EAAQ,MAAA,KAAW,UAAA,EAAY;AAEhD,IAAA,MAAM,IAAA,GAAO,GAAG,IAAA,IAAQ,EAAA;AACxB,IAAA,IAAI,SAAA,IAAa,EAAE,aAAA,CAAc,IAAI,KAAK,SAAA,CAAU,GAAA,CAAI,IAAI,CAAA,CAAA,EAAI;AAEhE,IAAA,MAAM,IAAA,GAAO,EAAA,CAAG,IAAA,IAAQ,EAAC;AACzB,IAAA,IAAI,QAAA,CAAS,IAAA,GAAO,CAAA,IAAK,CAAC,IAAA,CAAK,IAAA,CAAK,CAAA,CAAA,KAAK,QAAA,CAAS,GAAA,CAAI,CAAA,CAAE,WAAA,EAAa,CAAC,CAAA,EAAG;AAEzE,IAAA,MAAM,MAAA,GAAS,EAAA,CAAG,QAAA,EAAU,MAAA,EAAQ,MAAA;AACpC,IAAA,IAAI,iBAAiB,MAAA,IAAU,CAAC,aAAA,CAAc,GAAA,CAAI,MAAM,CAAA,EAAG;AAE3D,IAAA,IAAA,CAAK,IAAA,CAAK;AAAA,MACR,IAAA,EAAM,GAAG,IAAA,IAAQ,IAAA;AAAA,MACjB,IAAA;AAAA,MACA,KAAA,EAAO,GAAG,KAAA,IAAS,EAAA;AAAA,MACnB,IAAA,EAAM,MAAA,CAAO,OAAA,CAAQ,IAAA,EAAK;AAAA,MAC1B,OAAA,EAAS,EAAA,CAAG,OAAA,IAAW,EAAC;AAAA,MACxB,GAAI,EAAA,CAAG,QAAA,EAAU,MAAA,EAAQ,WAAA,GACrB,EAAE,UAAA,EAAY,EAAA,CAAG,QAAA,CAAS,MAAA,CAAO,WAAA,EAAY,GAC7C,EAAC;AAAA,MACL,UAAA,EAAY,GAAG,UAAA,IAAc,CAAA;AAAA,MAC7B,IAAA;AAAA,MACA,GAAI,MAAA,GAAS,EAAE,MAAA,KAAW,EAAC;AAAA,MAC3B;AAAA,KACD,CAAA;AAAA,EACH;AAEA,EAAA,IAAA,CAAK,KAAK,CAAC,CAAA,EAAG,MAAM,CAAA,CAAE,UAAA,GAAa,EAAE,UAAU,CAAA;AAC/C,EAAA,OAAO,KAAA,CAAM,eAAe,MAAA,GAAY,IAAA,CAAK,MAAM,CAAA,EAAG,KAAA,CAAM,UAAU,CAAA,GAAI,IAAA;AAC5E","file":"chunk-JV6VRZ6U.mjs","sourcesContent":["/**\n * Distill — raw source → refined knowledge entries (the KNOWLEDGE layer).\n *\n * The \"simple mode\": no graph engine. A refined entry is just an AIP-10\n * `knowledge.entry/v1` markdown file whose `sources: [<id>]` frontmatter\n * IS the `derivedFrom` provenance edge. The filesystem refs ARE the graph;\n * a graph engine (mind-graph / gbrain) is an optional index added later.\n *\n * The kit owns the contract + the runner (what to write, where, with what\n * provenance). The LLM that actually extracts insights is an injected\n * `DistillPort` — host-supplied (Claude/OpenAI), so the kit stays pure.\n */\n\nimport { z } from \"zod\"\n\n/** Generic AIP-10 refined kinds — NOT domain-specific. */\nexport const REFINED_KIND_SCHEMA = z.enum([\n  \"principle\",\n  \"pattern\",\n  \"critique\",\n  \"summary\",\n  \"example\",\n])\n\nexport type RefinedKind = z.infer<typeof REFINED_KIND_SCHEMA>\n\n/** Runtime guard — narrows an untyped value to RefinedKind without a cast. */\nexport function isRefinedKind(value: unknown): value is RefinedKind {\n  return REFINED_KIND_SCHEMA.safeParse(value).success\n}\n\nexport interface DistilledItem {\n  readonly kind: RefinedKind\n  readonly title: string\n  /** The refined insight, markdown. Self-contained, not a quote dump. */\n  readonly body: string\n  /** 0–1 model confidence. */\n  readonly confidence?: number\n  readonly tags?: readonly string[]\n}\n\nexport interface DistillInput {\n  readonly title: string\n  readonly body: string\n  readonly tags?: readonly string[]\n  /** Hint for the kinds worth extracting (e.g. only principles). */\n  readonly kinds?: readonly RefinedKind[]\n  /**\n   * Lens instruction — an extra \"what to look for under this aspect\" directive\n   * prepended to the base distill prompt. When set, distillation reads the\n   * source THROUGH a lens (e.g. \"extract marketing decisions and positioning\")\n   * instead of the generic durable-insight pass. See {@link Lens}.\n   */\n  readonly instruction?: string\n}\n\n/**\n * The LLM boundary. Given a raw source, return refined items. Injected by\n * the host (corpus-cli `AnthropicDistiller`, a Guilde operator, …) so the\n * kit takes no model dependency.\n */\nexport interface DistillPort {\n  distill(input: DistillInput): Promise<readonly DistilledItem[]>\n}\n","/**\n * resolveKnowledge — the `knowledge:` binding resolver (KNOWLEDGE→SKILL link).\n *\n * Filesystem-first: a skill's binding (`{ tags, kinds }`) is resolved against\n * the refined `entries/**​/*.md` on disk — no graph engine. Returns the\n * matching refined entries (with their `sources:` provenance), filtered by the\n * caller's access scope so an operator never sees knowledge above its clearance.\n *\n * A graph engine (mind-graph / gbrain) can later replace this scan with\n * traversal/activation behind the SAME signature — the binding contract is stable.\n */\n\nimport matter from \"gray-matter\"\nimport { z } from \"zod\"\nimport type { FsPort } from \"../ports/fs.port.js\"\nimport { isRefinedKind, type RefinedKind } from \"../distill/types.js\"\n\n/**\n * Lenient zod view of an AIP-10 entry's frontmatter. Every field `.catch`es to\n * undefined so a malformed value degrades gracefully (the entry is still\n * parsed, the bad field is simply absent) — matching the previous defensive\n * hand-narrowing, but typed and cast-free.\n */\nconst ENTRY_FRONTMATTER = z\n  .object({\n    schema: z.string().optional().catch(undefined),\n    slug: z.string().optional().catch(undefined),\n    kind: z.string().optional().catch(undefined),\n    title: z.string().optional().catch(undefined),\n    sources: z.array(z.string()).optional().catch(undefined),\n    confidence: z.number().optional().catch(undefined),\n    tags: z.array(z.string()).optional().catch(undefined),\n    metadata: z\n      .object({\n        corpus: z\n          .object({\n            access: z.string().optional().catch(undefined),\n            status: z.string().optional().catch(undefined),\n            // Resolved provenance written at promote time — the origins this\n            // entry was distilled from, so a recall can cite the real source.\n            source_refs: z\n              .array(\n                z\n                  .object({\n                    id: z.string(),\n                    url: z.string().optional().catch(undefined),\n                    title: z.string().optional().catch(undefined),\n                    authority: z.string().optional().catch(undefined),\n                    language: z.string().optional().catch(undefined),\n                  })\n                  .loose()\n              )\n              .optional()\n              .catch(undefined),\n          })\n          .loose()\n          .optional()\n          .catch(undefined),\n      })\n      .loose()\n      .optional()\n      .catch(undefined),\n  })\n  .loose()\n\nexport interface CorpusEntryQuery {\n  /** Match entries sharing ANY of these tags. Empty/absent = no tag filter. */\n  readonly tags?: readonly string[]\n  /** Restrict to these refined kinds. Empty/absent = all kinds. */\n  readonly kinds?: readonly RefinedKind[]\n  /** Cap results (highest-confidence first). */\n  readonly maxResults?: number\n}\n\n/** A resolved origin an entry was distilled from (id + where to find it). */\nexport interface SourceRef {\n  readonly id: string\n  readonly url?: string\n  readonly title?: string\n  readonly authority?: string\n  readonly language?: string\n}\n\nexport interface ResolvedEntry {\n  readonly slug: string\n  readonly kind: string\n  readonly title: string\n  readonly body: string\n  /** Provenance — the raw source ids this entry was derived from. */\n  readonly sources: readonly string[]\n  /** Resolved provenance — id + url + title for each source, when available. */\n  readonly sourceRefs?: readonly SourceRef[]\n  readonly confidence: number\n  readonly tags: readonly string[]\n  readonly access?: string\n  readonly path: string\n}\n\nexport interface ResolveKnowledgeOptions {\n  readonly fs: FsPort\n  readonly query: CorpusEntryQuery\n  /**\n   * Access scopes the caller (operator) is cleared for. An entry passes if it\n   * has no access (public) or its access ∈ this set. Omit = no access filter.\n   */\n  readonly allowedAccess?: ReadonlySet<string>\n}\n\nexport async function resolveKnowledge(\n  opts: ResolveKnowledgeOptions\n): Promise<readonly ResolvedEntry[]> {\n  const { fs, query, allowedAccess } = opts\n  const wantTags = new Set((query.tags ?? []).map(t => t.toLowerCase()))\n  const wantKinds = query.kinds ? new Set(query.kinds) : null\n\n  let rels: readonly string[]\n  try {\n    rels = await fs.walk(\"entries\")\n  } catch {\n    return []\n  }\n\n  const hits: ResolvedEntry[] = []\n  for (const rel of rels) {\n    if (!rel.endsWith(\".md\")) continue\n    // `walk(\"entries\")` yields paths relative to the entries/ dir; readFile\n    // resolves against the workspace root, so re-prefix.\n    const path = `entries/${rel}`\n    let parsed\n    try {\n      parsed = matter(await fs.readFile(path))\n    } catch {\n      continue\n    }\n    const fm = ENTRY_FRONTMATTER.parse(parsed.data)\n    if (fm.schema !== \"knowledge.entry/v1\") continue\n\n    // Tombstone: a guild disables a pack entry by shadowing it (same path) with\n    // status \"archived\". Filtered here so the overlaid archived entry hides the\n    // pack's. Absent/active = shown — only an explicit archive subtracts.\n    if (fm.metadata?.corpus?.status === \"archived\") continue\n\n    const kind = fm.kind ?? \"\"\n    if (wantKinds && !(isRefinedKind(kind) && wantKinds.has(kind))) continue\n\n    const tags = fm.tags ?? []\n    if (wantTags.size > 0 && !tags.some(t => wantTags.has(t.toLowerCase()))) continue\n\n    const access = fm.metadata?.corpus?.access\n    if (allowedAccess && access && !allowedAccess.has(access)) continue\n\n    hits.push({\n      slug: fm.slug ?? path,\n      kind,\n      title: fm.title ?? \"\",\n      body: parsed.content.trim(),\n      sources: fm.sources ?? [],\n      ...(fm.metadata?.corpus?.source_refs\n        ? { sourceRefs: fm.metadata.corpus.source_refs }\n        : {}),\n      confidence: fm.confidence ?? 0,\n      tags,\n      ...(access ? { access } : {}),\n      path,\n    })\n  }\n\n  hits.sort((a, b) => b.confidence - a.confidence)\n  return query.maxResults !== undefined ? hits.slice(0, query.maxResults) : hits\n}\n"]}

package/dist/{chunk-UPX26MYH.mjs → chunk-WF5KGEL6.mjs}

@@ -9,6 +9,7 @@ var CandidatesSidecar = class {
   constructor(opts) {
     this.opts = opts;
   }
+  opts;
   /**
    * Load every row from disk. Returns an empty list if the file
    * doesn't exist (a fresh corpus has no candidates yet).
@@ -89,6 +90,8 @@ var SidecarDuplicateError = class extends Error {
     this.id = id;
     this.name = "SidecarDuplicateError";
   }
+  path;
+  id;
 };
 var SidecarNotFoundError = class extends Error {
   constructor(path, id) {
@@ -97,8 +100,10 @@ var SidecarNotFoundError = class extends Error {
     this.id = id;
     this.name = "SidecarNotFoundError";
   }
+  path;
+  id;
 };
 
 export { CandidatesSidecar, SidecarDuplicateError, SidecarNotFoundError };
-//# sourceMappingURL=chunk-UPX26MYH.mjs.map
-//# sourceMappingURL=chunk-UPX26MYH.mjs.map
+//# sourceMappingURL=chunk-WF5KGEL6.mjs.map
+//# sourceMappingURL=chunk-WF5KGEL6.mjs.map

package/dist/chunk-WF5KGEL6.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/workspace/sidecar.ts"],"names":["yamlParse","yamlStringify"],"mappings":"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","file":"chunk-WF5KGEL6.mjs","sourcesContent":["/**\n * CandidatesSidecar — accessor for `collections/<name>/_candidates.yaml`.\n *\n * The plan calls out lazy materialization (so-so #6): the\n * \"discovered\" state has high volume and short lifespan; AIP-18 ITEM\n * files only materialize when a candidate transitions to `analyzed`.\n * Until then, candidates live in a YAML sidecar keyed by id.\n *\n * Sidecar shape:\n *   candidates:\n *     - id: <slug>\n *       status: discovered   # may also be transitioning (rare)\n *       sourceUrl: ...       # collection-specific fields are free-form\n *       contentHash: ...\n *       discoveredAt: ISO\n *       discoveredBy: ws://operators/<slug>\n *\n * The accessor enforces:\n *   - id uniqueness within the file\n *   - atomic full-file writes (no partial sidecar)\n *   - status transition discipline (a row stays here only while\n *     `status === \"discovered\"`; transitions out remove the row and\n *     return the data so the caller can materialize ITEM.md)\n */\n\nimport { parse as yamlParse, stringify as yamlStringify } from \"yaml\"\nimport type { FsPort } from \"../ports/fs.port.js\"\n\nexport interface CandidateRow {\n  readonly id: string\n  readonly status: \"discovered\" | string\n  /** Open-ended — collection schema's `fields` defines what's allowed. */\n  readonly [key: string]: unknown\n}\n\ninterface SidecarShape {\n  readonly candidates: readonly CandidateRow[]\n}\n\nexport interface CandidatesSidecarOptions {\n  readonly fs: FsPort\n  /** Workspace-relative path of the sidecar file. */\n  readonly path: string\n}\n\nexport class CandidatesSidecar {\n  constructor(private readonly opts: CandidatesSidecarOptions) {}\n\n  /**\n   * Load every row from disk. Returns an empty list if the file\n   * doesn't exist (a fresh corpus has no candidates yet).\n   */\n  async load(): Promise<readonly CandidateRow[]> {\n    if (!(await this.opts.fs.exists(this.opts.path))) return []\n    const content = await this.opts.fs.readFile(this.opts.path)\n    if (!content.trim()) return []\n    const parsed = yamlParse(content) as Partial<SidecarShape> | null\n    if (!parsed || !Array.isArray(parsed.candidates)) return []\n    return parsed.candidates as readonly CandidateRow[]\n  }\n\n  /**\n   * Append a new candidate. Refuses if `id` already exists — sidecar\n   * keys are unique. Returns the full updated list.\n   */\n  async append(row: CandidateRow): Promise<readonly CandidateRow[]> {\n    const existing = await this.load()\n    if (existing.some((r) => r.id === row.id)) {\n      throw new SidecarDuplicateError(this.opts.path, row.id)\n    }\n    const next = [...existing, row]\n    await this.write(next)\n    return next\n  }\n\n  /**\n   * Mutate one row in-place. Throws if not found.\n   */\n  async update(\n    id: string,\n    patch: Readonly<Record<string, unknown>>\n  ): Promise<CandidateRow> {\n    const existing = await this.load()\n    let updated: CandidateRow | null = null\n    const next = existing.map((r) => {\n      if (r.id !== id) return r\n      updated = { ...r, ...patch, id: r.id } as CandidateRow\n      return updated\n    })\n    if (!updated) throw new SidecarNotFoundError(this.opts.path, id)\n    await this.write(next)\n    return updated\n  }\n\n  /**\n   * Remove a row by id. Returns the removed row so the caller can\n   * materialize an ITEM.md from its fields. Throws if not found.\n   *\n   * Use this when a candidate transitions out of `discovered`: pull\n   * it from the sidecar, write the ITEM.md, append an event.\n   */\n  async take(id: string): Promise<CandidateRow> {\n    const existing = await this.load()\n    const idx = existing.findIndex((r) => r.id === id)\n    if (idx === -1) throw new SidecarNotFoundError(this.opts.path, id)\n    const removed = existing[idx]!\n    const next = [...existing.slice(0, idx), ...existing.slice(idx + 1)]\n    await this.write(next)\n    return removed\n  }\n\n  /**\n   * Whole-file replace. Used in tests and by the indexer for\n   * bulk migrations. Prefer append/update/take for normal flow.\n   */\n  async write(candidates: readonly CandidateRow[]): Promise<void> {\n    const shape: SidecarShape = { candidates }\n    const content = yamlStringify(shape, {\n      // Stable output: sort keys alphabetically across rows for\n      // greppable diffs. Each row's id key is preserved by the\n      // stringifier; the rest is dictionary order.\n      sortMapEntries: false,\n    })\n    await this.opts.fs.writeFile(this.opts.path, content)\n  }\n}\n\nexport class SidecarDuplicateError extends Error {\n  constructor(\n    readonly path: string,\n    readonly id: string\n  ) {\n    super(\n      `SidecarDuplicateError: candidate id \"${id}\" already exists in ${path}`\n    )\n    this.name = \"SidecarDuplicateError\"\n  }\n}\n\nexport class SidecarNotFoundError extends Error {\n  constructor(\n    readonly path: string,\n    readonly id: string\n  ) {\n    super(`SidecarNotFoundError: candidate id \"${id}\" not in ${path}`)\n    this.name = \"SidecarNotFoundError\"\n  }\n}\n"]}

package/dist/index.d.ts

@@ -892,6 +892,13 @@ interface DistillInput {
     readonly tags?: readonly string[];
     /** Hint for the kinds worth extracting (e.g. only principles). */
     readonly kinds?: readonly RefinedKind[];
+    /**
+     * Lens instruction — an extra "what to look for under this aspect" directive
+     * prepended to the base distill prompt. When set, distillation reads the
+     * source THROUGH a lens (e.g. "extract marketing decisions and positioning")
+     * instead of the generic durable-insight pass. See {@link Lens}.
+     */
+    readonly instruction?: string;
 }
 /**
  * The LLM boundary. Given a raw source, return refined items. Injected by
@@ -921,6 +928,19 @@ interface DistillSource {
     /** Access scope inherited by every entry distilled from this source. */
     readonly access?: string;
     readonly domain?: string;
+    /**
+     * Lens instruction threaded to the distiller (what to extract under the
+     * lens's aspect). See {@link Lens}.
+     */
+    readonly instruction?: string;
+    /** Lens kind restriction — the distiller may emit only these kinds. */
+    readonly kinds?: readonly RefinedKind[];
+    /**
+     * Lens aspect — stamped on every produced entry as the faceted tag
+     * `aspect:<aspect>` (preserved verbatim past the topic-tag sanitizer, since
+     * `aspect:` is an AIP-10 facet, not a plain tag).
+     */
+    readonly aspect?: string;
 }
 interface DistillRunReport {
     readonly sourceId: string;
@@ -1097,6 +1117,227 @@ interface DistillRegistry {
 }
 declare function createDistillRegistry(): DistillRegistry;
 
+/**
+ * DistillIndex — the persistent ledger of "what was distilled, when, by which
+ * engine" for one corpus. A sidecar YAML at `_distill-index.yaml` under the
+ * corpus root, keyed by the raw source's provenance id (the same id that lands
+ * in each refined entry's `sources:` backlink).
+ *
+ * Why a ledger when `scanDistilledSourceIds` already derives "done" from the
+ * entries themselves? Because the entry scan answers only a boolean ("has this
+ * source any entry?") and loses the *cadence*: when it ran, with which engine,
+ * how many entries it produced, the source's content hash at the time. The
+ * ledger records that, so:
+ *   - a run can skip by content hash (re-distill only when the source changed),
+ *   - the corpus carries an auditable, git-diffable distillation history,
+ *   - cost/coverage is queryable without re-reading every entry.
+ *
+ * Same shape + discipline as {@link CandidatesSidecar}: whole-file atomic
+ * writes via FsPort, empty list for a fresh corpus, upsert (not append-only)
+ * keyed by `sourceId` because a source legitimately re-distills.
+ *
+ * Pure: consumes FsPort only, no node:fs / no clock (the caller stamps the time).
+ */
+
+/** Default corpus-relative location of the ledger. */
+declare const DISTILL_INDEX_PATH: "_distill-index.yaml";
+/** One distillation record — keyed by `(sourceId, lensId)`. */
+interface DistillIndexRecord {
+    /** Raw source provenance id (matches the entries' `sources:` backlink). */
+    readonly sourceId: string;
+    /**
+     * Lens id this run distilled under, when a lens was applied. Part of the key:
+     * the same source distilled under "diary" and "marketing" is two rows with
+     * independent cadence. Absent (undefined) = the generic, lens-less pass.
+     */
+    readonly lensId?: string;
+    /** Human title of the source at distill time (for greppable diffs). */
+    readonly title?: string;
+    /** ISO-8601 instant the distillation ran. */
+    readonly distilledAt: string;
+    /** Engine label that produced the entries (e.g. "claude-code", "anthropic-api"). */
+    readonly engine?: string;
+    /** Source content hash at distill time — lets a re-run skip unchanged sources. */
+    readonly contentHash?: string;
+    /** How many refined entries this run wrote. */
+    readonly entryCount: number;
+    /** Workspace-relative paths of the entries written this run. */
+    readonly entryPaths?: readonly string[];
+}
+interface DistillIndexOptions {
+    readonly fs: FsPort;
+    /** Workspace-relative path of the ledger. Defaults to {@link DISTILL_INDEX_PATH}. */
+    readonly path?: string;
+}
+declare class DistillIndex {
+    private readonly fs;
+    private readonly path;
+    constructor(opts: DistillIndexOptions);
+    /** Every record on disk. Empty for a fresh corpus (no file yet). */
+    load(): Promise<readonly DistillIndexRecord[]>;
+    /**
+     * The record for a `(sourceId, lensId)` pair, or null if never distilled.
+     * `lensId` undefined matches the generic lens-less row (back-compat).
+     */
+    get(sourceId: string, lensId?: string): Promise<DistillIndexRecord | null>;
+    /**
+     * True if the `(source, lens)` pair was distilled with a matching content
+     * hash (when given). Each lens has independent cadence over the same source.
+     */
+    isDistilled(sourceId: string, contentHash?: string, lensId?: string): Promise<boolean>;
+    /**
+     * Upsert a record by `(sourceId, lensId)`. Re-distilling overwrites that
+     * pair's row (cadence is "latest run wins") while leaving the same source's
+     * other lens rows untouched; a new pair appends. Returns the full list.
+     */
+    record(row: DistillIndexRecord): Promise<readonly DistillIndexRecord[]>;
+    /** Whole-file replace. Prefer {@link record} for normal flow. */
+    write(runs: readonly DistillIndexRecord[]): Promise<void>;
+}
+
+/**
+ * Lens — a named projection over the shared source pool.
+ *
+ * Sources are captured once (conversations / files / web → immutable `sources/`).
+ * A Lens decides *what to extract from them* and *how that extraction lives over
+ * time*. The same material read under two lenses produces two independent entry
+ * sets (a "diary" lens and a "marketing" lens over the same conversations), each
+ * tagged with its `aspect:` facet and ledgered independently by `(source, lens)`.
+ *
+ * A Lens is the {@link DistillDescriptor} pattern generalized: descriptors vary
+ * the *source* (guild-sources vs guild-web); a Lens varies the *projection* over
+ * a shared source set. Registering a lens is the whole of "add an aspect".
+ *
+ * Two modes — the heart of the design:
+ *   - `log`       extraction, append-only. The atoms ARE the artifact; never
+ *                 rebuilt. A conversation diary, a changelog, a research journal.
+ *   - `synthesis` re-derived living artifact. Atoms are supersedes-aware, and a
+ *                 consolidated doc at `synthesisPath` is rolled up from the
+ *                 current (non-superseded) atoms — rebuilt when a new decision
+ *                 lands. Marketing knowledge, a positioning doc.
+ *
+ * Pure data: no behavior. The distill core reads a Lens to set the instruction,
+ * constrain kinds, and stamp the `aspect:` tag; synthesis (P2) reads `mode` +
+ * `synthesisPath` to drive the report engine.
+ *
+ * Design: projects/guilde/docs/KNOWLEDGE-LENS-DESIGN.md
+ */
+
+/** How a lens's extraction lives over time. See module doc. */
+type LensMode = "log" | "synthesis";
+/**
+ * Which sources feed a lens. P1 ships the universal `"all"`; richer selection
+ * (by tag / channel / provenance prefix) lands with the per-guild setting in P3.
+ */
+type SourceSelector = {
+    readonly kind: "all";
+} | {
+    readonly kind: "tag";
+    readonly tag: string;
+} | {
+    readonly kind: "prefix";
+    readonly prefix: string;
+};
+/** A named, time-aware projection over the shared source pool. */
+interface Lens {
+    /** Stable id, e.g. "marketing" | "diary" | "sales". Also the ledger lens key. */
+    readonly id: string;
+    /** Human label. */
+    readonly label: string;
+    /**
+     * Extraction instruction handed to the distiller — "what to look for under
+     * this aspect". Prepended to the base distill prompt (see {@link DistillInput}).
+     */
+    readonly prompt: string;
+    /**
+     * Faceted aspect value. Stamped on every entry this lens produces as the tag
+     * `aspect:<aspect>` (a graph-knowledge facet → the query key for the lens).
+     * Defaults to {@link Lens.id} when omitted at construction (see {@link lensAspect}).
+     */
+    readonly aspect?: string;
+    /** Which RefinedKinds the lens may emit (orthogonal to aspect). */
+    readonly kinds?: readonly RefinedKind[];
+    /** How the lens lives over time. */
+    readonly mode: LensMode;
+    /** Which sources feed it. Defaults to `{ kind: "all" }`. */
+    readonly sourceSelector?: SourceSelector;
+    /** For `mode:"synthesis"` — where the consolidated artifact is (re)written. */
+    readonly synthesisPath?: string;
+}
+/** The aspect value for a lens — explicit `aspect`, else the lens id. */
+declare function lensAspect(lens: Lens): string;
+/** The faceted tag stamped on a lens's entries: `aspect:<value>`. */
+declare function lensAspectTag(lens: Lens): string;
+
+/**
+ * distillFromImporter — the importer → distill core, shared by every entrypoint.
+ *
+ * This is the kind-agnostic engine the conversation/web/source pipelines all
+ * ride on: take a configured IMPORTER, stream its sources, and run the DISTILLER
+ * over each — writing refined AIP-10 entries via {@link DistillRunner} and
+ * (optionally) recording each unit in the {@link DistillIndex} ledger.
+ *
+ * It owns NO source selection: the caller hands it an already-prepared importer
+ * `config` (which refs/urls/paths to pull). That keeps two very different
+ * entrypoints on ONE core:
+ *   - cron `runDistill(descriptor, scope)` — resolves the guild target + the
+ *     binding's fresh-ref `prepare`, then calls this.
+ *   - standalone CLI / runtime tool — points an FsPort at any corpus folder and
+ *     a transcript/local-files importer at any input, then calls this.
+ *
+ * Idempotent: {@link DistillRunner} skips an entry slug that already exists, and
+ * when a `index` ledger is supplied the caller can pre-skip sources by content
+ * hash (re-distill only on change). Pure — consumes FsPort + ClockPort + an
+ * injected DistillPort, no HTTP / no child process.
+ */
+
+/** Aggregate of one importer → distill pass (no descriptor/scope coupling). */
+interface DistillCoreReport {
+    /** Sources the importer yielded this run. */
+    unitsConsidered: number;
+    /** Units that produced ≥1 new entry. */
+    unitsDistilled: number;
+    entriesWritten: number;
+    /** Entry slugs skipped because an identical title already existed. */
+    skipped: number;
+    /** Sources skipped because the ledger shows an unchanged prior distillation. */
+    unchanged: number;
+}
+interface DistillFromImporterOptions {
+    readonly fs: FsPort;
+    readonly clock: ClockPort;
+    readonly distiller: DistillPort;
+    /** The configured importer (ConversationImporter, LocalFilesImporter, …). */
+    readonly importer: CorpusImporter;
+    /** Stable importer id — passed through as the enumerate target's importerId. */
+    readonly importerId: string;
+    /** Importer-native, already-prepared config (`{refs}`, `{urls}`, `{rootPath}`…). */
+    readonly config: Readonly<Record<string, unknown>>;
+    /** Entry path layout; defaults to the runner's "dated". */
+    readonly layout?: EntryLayout;
+    /**
+     * Provenance id from an imported source — the value written into each entry's
+     * `sources:` backlink AND the ledger key. Defaults to the importer's slug.
+     */
+    readonly provenanceId?: (imported: ImportedSource) => string;
+    /**
+     * Optional ledger. When set, each distilled unit is recorded (sourceId,
+     * timestamp, engine, content hash, entry count) AND a source whose ledger row
+     * already matches its content hash is skipped before the LLM is called.
+     */
+    readonly index?: DistillIndex;
+    /** Engine label written into the ledger (e.g. "claude-code"). */
+    readonly engine?: string;
+    /**
+     * Optional lens — read every source THROUGH this aspect: its `prompt` is
+     * threaded to the distiller, its `kinds` constrain output, its `aspect:` tag
+     * is stamped on every entry, and the ledger keys by `(source, lens.id)` so
+     * this lens's cadence is independent of any other over the same sources.
+     */
+    readonly lens?: Lens;
+}
+declare function distillFromImporter(opts: DistillFromImporterOptions): Promise<DistillCoreReport>;
+
 /**
  * runDistill — the generic distill pass for one (descriptor × scope).
  *
@@ -1111,18 +1352,112 @@ declare function createDistillRegistry(): DistillRegistry;
  * slug that already exists — so a daily re-run only adds fresh material.
  */
 
-interface DistillReport {
+interface DistillReport extends DistillCoreReport {
     readonly descriptorId: string;
     readonly scopeId: string;
-    /** Sources the importer yielded this run. */
-    unitsConsidered: number;
-    /** Units that produced ≥1 new entry. */
-    unitsDistilled: number;
-    entriesWritten: number;
-    /** Entry slugs skipped because an identical title already existed. */
-    skipped: number;
 }
-declare function runDistill<S extends DistillScope>(descriptor: DistillDescriptor<S>, scope: S): Promise<DistillReport>;
+interface RunDistillOptions {
+    /** Optional ledger — records every distilled unit (what/when/engine). */
+    readonly index?: DistillIndex;
+    /** Engine label written into the ledger. */
+    readonly engine?: string;
+    /** Optional lens — distill the descriptor's sources THROUGH this aspect. */
+    readonly lens?: Lens;
+}
+declare function runDistill<S extends DistillScope>(descriptor: DistillDescriptor<S>, scope: S, opts?: RunDistillOptions): Promise<DistillReport>;
+
+/**
+ * synthesizeLens — the `mode:"synthesis"` half of the Lens contract.
+ *
+ * Where a `log` lens just accumulates atoms (the diary), a `synthesis` lens
+ * rolls the CURRENT atoms of its aspect into one consolidated, living artifact —
+ * rebuilt whenever a new decision lands. "Marketing knowledge" is the canonical
+ * case: a new decision can REVERSE a prior one, so the consolidated view must be
+ * re-derived from the current (non-superseded) atom set, not just appended to.
+ *
+ * "Current" = entries tagged `aspect:<lens>` that are NOT superseded by another
+ * entry and are NOT the prior synthesis artifact itself (`role:synthesis`). The
+ * artifact is pure derived state: an AIP-10 entry at `synthesisPath`, rewritten
+ * each run, queryable + graph-projected like any other entry (open-Q2 lean from
+ * KNOWLEDGE-LENS-DESIGN.md). Excluding `role:synthesis` from the atom read keeps
+ * the rebuild from feeding on its own output.
+ *
+ * Pure: consumes FsPort + ClockPort + an injected SynthesisPort (the LLM that
+ * consolidates). The model boundary mirrors {@link DistillPort}.
+ */
+
+/** Tag marking the consolidated artifact so the rebuild never reads it as an atom. */
+declare const SYNTHESIS_ROLE_TAG: "role:synthesis";
+/** One current atom handed to the synthesizer. */
+interface SynthesisAtom {
+    readonly slug: string;
+    readonly title: string;
+    readonly body: string;
+}
+interface SynthesisInput {
+    readonly aspect: string;
+    readonly label: string;
+    /** The current (non-superseded) atoms of the aspect, highest-confidence first. */
+    readonly atoms: readonly SynthesisAtom[];
+}
+/**
+ * The LLM boundary for synthesis — given the current atoms of an aspect, return
+ * the consolidated artifact body (markdown). Host-supplied, so the kit stays
+ * model-free (same discipline as {@link DistillPort}).
+ */
+interface SynthesisPort {
+    synthesize(input: SynthesisInput): Promise<string>;
+}
+interface SynthesizeLensOptions {
+    readonly fs: FsPort;
+    readonly clock: ClockPort;
+    readonly synthesizer: SynthesisPort;
+    readonly lens: Lens;
+}
+interface SynthesizeLensReport {
+    readonly lensId: string;
+    readonly aspect: string;
+    /** Entries tagged with the aspect (before the superseded/role filter). */
+    readonly atomsConsidered: number;
+    /** Atoms that fed the synthesis (current view). */
+    readonly atomsUsed: number;
+    /** Whether an artifact was (re)written — false when there are no current atoms. */
+    readonly wrote: boolean;
+    /** Workspace-relative path of the artifact, when written. */
+    readonly path?: string;
+}
+/**
+ * The current atoms of a lens's aspect: tagged `aspect:<lens>`, not archived,
+ * not the synthesis artifact, and not superseded by any other entry. Sorted
+ * highest-confidence first (the order handed to the synthesizer).
+ */
+declare function currentLensAtoms(fs: FsPort, lens: Lens): Promise<readonly SynthesisAtom[]>;
+/** Default artifact location for a lens with no explicit `synthesisPath`. */
+declare function defaultSynthesisPath(lens: Lens): string;
+interface LensStaleness {
+    /** True when the artifact does not reflect the current atom set. */
+    readonly stale: boolean;
+    /** "missing" (no artifact yet) | "drifted" (atom set changed) | "fresh". */
+    readonly reason: "missing" | "drifted" | "fresh";
+    /** Current (non-superseded) atom count. */
+    readonly atomCount: number;
+}
+/**
+ * Whether a synthesis lens's artifact is stale — timestamp-free, deterministic:
+ * the artifact records the atom slugs it consolidated in its `sources:`. If the
+ * CURRENT atom set differs (a new decision added/superseded an atom), the
+ * artifact has drifted and should be rebuilt. No artifact yet ⇒ stale when
+ * atoms exist. This is the "mark-stale-on-new-atom" surface (P4).
+ */
+declare function lensSynthesisStale(fs: FsPort, lens: Lens): Promise<LensStaleness>;
+/**
+ * Re-derive a synthesis lens's consolidated artifact from its current atoms and
+ * write it (overwrite — derived state) as an AIP-10 entry tagged with the aspect
+ * and `role:synthesis`. No-op (wrote:false) when the lens has no current atoms.
+ */
+declare function synthesizeLens(opts: SynthesizeLensOptions): Promise<SynthesizeLensReport>;
+/** Build the synthesis prompt — the model-agnostic core (mirrors buildDistillPrompt). */
+declare function buildSynthesisPrompt(input: SynthesisInput): string;
 
 /**
  * ClaudeDistiller — a `DistillPort` backed by Claude over the Messages API.
@@ -2196,12 +2531,39 @@ interface PushChunksInput {
     readonly uri?: string;
     readonly chunks: readonly WriterChunk[];
     readonly entryMetadata?: Readonly<Record<string, unknown>>;
+    /**
+     * The entry's full parsed frontmatter. Vector engines ignore it; a
+     * graph-projection writer reads the relation arrays the flattened
+     * `entryMetadata` drops (`links` / `supersedes` / `contradicts`) to build
+     * entry↔entry edges. Optional — absence just means no graph projection.
+     */
+    readonly entryFrontmatter?: Readonly<Record<string, unknown>>;
+}
+/**
+ * A `knowledge.source/v1` doc to project. Sources never chunk into a vector
+ * engine, so they have their own port method (not `pushChunks`). A graph
+ * writer projects the full source frontmatter (title / authority /
+ * content_hash / …) into a real Source node; a vector writer no-ops.
+ */
+interface PushSourceInput {
+    readonly sourceId: string;
+    readonly sourcePath: string;
+    readonly title?: string;
+    /** The source's full parsed frontmatter (`knowledge.source/v1`). */
+    readonly sourceFrontmatter: Readonly<Record<string, unknown>>;
 }
 interface WriterPort {
     pushChunks(input: PushChunksInput): Promise<readonly string[]>;
     removeEntry(entrySlug: string): Promise<{
         removed: number;
     }>;
+    /**
+     * Project a source doc. Optional — vector-only writers omit it (sources
+     * aren't searchable chunks); a graph-projection writer implements it so
+     * Source nodes carry full frontmatter, not just the stub id the
+     * entry→source `DERIVED_FROM` path leaves behind.
+     */
+    pushSource?(input: PushSourceInput): Promise<void>;
 }
 
 /**
@@ -2233,6 +2595,7 @@ interface IndexReport {
     readonly removed: number;
     readonly skipped: number;
     readonly chunkCount: number;
+    readonly sourcesPushed: number;
 }
 declare class CorpusIndexer {
     private readonly opts;
@@ -2912,4 +3275,4 @@ declare class PlaybookEvaluator {
 declare const SPEC_NAME: "agentcorpus/v1";
 declare const SPEC_VERSION: "0.1.0-alpha";
 
-export { ANY_REF, type AccessCaller, type AccessClassification, type AccessContext, type AccessDecision, type AccessModesMap, type ActivateResult, type AggregateOptions, type AggregateResult, type AipSchemaBundle, type AipSchemaKey, type ArchiveResult, type AttachmentAsset, type AttachmentDeclaration, type Attestation, type AttestationKind, type AutoPromoteConfig, type AutoPromoteRequirements, type AxisDefinition, type AxisRegistry, type BatchReport, type BuildOverlayOptions, type CalibrationOptions, type CandidateForGate, type CandidateRow, type CandidateStatus, CandidatesSidecar, type CandidatesSidecarOptions, type Capability, type CapabilityCaller, type CapabilityDecision, type CapabilityRule, type ChunkerOptions, ClaudeDistiller, type ClaudeDistillerOptions, ClockPort, type ConversationDoc, ConversationImporter, type ConversationImporterOptions, type ConversationSourcePort, type ConversationThreadRef, type ConversationTurn, type ConversationWindowSource, type CorpusAccessSpec, type CorpusEntryQuery, type CorpusEvent, CorpusEventEmitter, type CorpusEventEmitterOptions, type CorpusEventKind, type CorpusImporter, CorpusIndexer, type CorpusIndexerOptions, CorpusLinter, type CorpusLinterOptions, type CorpusPreset, type CorpusPresetBootstrapContext, CorpusPromoter, CorpusValidator, type CorpusValidatorOptions, CorpusVersionConflictError, CorpusWorkspaceReader, type CorpusWorkspaceReaderOptions, type CorpusWorkspaceSnapshot, CorpusWorkspaceWriter, type CorpusWorkspaceWriterOptions, type CustomLintRunner, DEFAULT_TRANSITIONS, type Dimensions, type DistillBinding, type DistillDescriptor, type DistillInput, type DistillPort, type DistillRegistry, type DistillReport, type DistillRunReport, DistillRunner, type DistillRunnerOptions, type DistillScope, type DistillSource, type DistillTarget, type DistilledItem, EMPTY_SELECTOR, type EntryLayout, type EvalCase, EvalContextPort, EvalRubricPort, EvaluatorPort, FetcherPort, type FileKind, FsLockHandle, FsPort, FsStat, type GateFailure, type GateResult, IdentityPort, IllegalPlaybookTransitionError, IllegalTransitionError, type ImportedSource, ImporterRunner, type ImporterRunnerOptions, type ImporterTarget, type IndexReport, type KbListLike, type KbMigrationConfig, KbMigrationImporter, type KbSourceLike, type LanguageFilter, type LayerMode, type LayerProvider, type LayerRef, type LayerShadow, type LintIssue, type LintReport, LocalFilesImporter, type LocalFilesImporterOptions, type MarkdownDoc, type MatchAttachmentsOptions, type MatchOptions, MemFs, type ModelDistillerOptions, OperatorOverlayResolver, OverlayFs, type OverlayFsOptions, type ParsedFile, type Playbook, type PlaybookBatchOptions, type PlaybookBatchResult, type PlaybookCorpusMeta, PlaybookEvaluator, type PlaybookEvaluatorOptions, type PlaybookKind, PlaybookLifecycle, type PlaybookLifecycleOptions, PlaybookNotFoundError, type PlaybookQuery, PlaybookRegistry, type PlaybookRegistryOptions, type PlaybookStatus, type PlaybookTarget, type PlaybookTargetKind, type PromoteContext, type PromoteOptions, PromoteRejectedError, type PromoteResult, type PushChunksInput, REFINED_KIND_SCHEMA, ReadOnlyFs, type RefinedKind, type RenderedOverlays, type ResolutionContext, type ResolveContext, type ResolveKnowledgeOptions, type ResolveLanguageFilterInput, type ResolveResult, type ResolvedEntry, type ResolvedOverlay, type ReviewerCalibration, type ReviewerScore, ReviewerTrackRecord, type ReviewerTrackRecordOptions, SPEC_NAME, SPEC_VERSION, type Selector, type SelectorTerm, SidecarDuplicateError, SidecarNotFoundError, type SinkItem, type SinkPort, type SinkPushResult, type SlugifyOptions, type SourceRef, type StackEntry, type StackRefPartition, type StackResolution, StackResolver, type StackSkip, type SyncReport, SyncRunner, type SyncRunnerOptions, type TrackRecordEntry, type TransitionCheck, type ValidationIssue, type ValidationResult, WELL_KNOWN_AXES, WHITEOUT_SUFFIX, WebImporter, type WebImporterOptions, type WriterChunk, type WriterPort, 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, modelDistiller, 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 };
+export { ANY_REF, type AccessCaller, type AccessClassification, type AccessContext, type AccessDecision, type AccessModesMap, type ActivateResult, type AggregateOptions, type AggregateResult, type AipSchemaBundle, type AipSchemaKey, type ArchiveResult, type AttachmentAsset, type AttachmentDeclaration, type Attestation, type AttestationKind, type AutoPromoteConfig, type AutoPromoteRequirements, type AxisDefinition, type AxisRegistry, type BatchReport, type BuildOverlayOptions, type CalibrationOptions, type CandidateForGate, type CandidateRow, type CandidateStatus, CandidatesSidecar, type CandidatesSidecarOptions, type Capability, type CapabilityCaller, type CapabilityDecision, type CapabilityRule, type ChunkerOptions, ClaudeDistiller, type ClaudeDistillerOptions, ClockPort, type ConversationDoc, ConversationImporter, type ConversationImporterOptions, type ConversationSourcePort, type ConversationThreadRef, type ConversationTurn, type ConversationWindowSource, type CorpusAccessSpec, type CorpusEntryQuery, type CorpusEvent, CorpusEventEmitter, type CorpusEventEmitterOptions, type CorpusEventKind, type CorpusImporter, CorpusIndexer, type CorpusIndexerOptions, CorpusLinter, type CorpusLinterOptions, type CorpusPreset, type CorpusPresetBootstrapContext, CorpusPromoter, CorpusValidator, type CorpusValidatorOptions, CorpusVersionConflictError, CorpusWorkspaceReader, type CorpusWorkspaceReaderOptions, type CorpusWorkspaceSnapshot, CorpusWorkspaceWriter, type CorpusWorkspaceWriterOptions, type CustomLintRunner, DEFAULT_TRANSITIONS, DISTILL_INDEX_PATH, type Dimensions, type DistillBinding, type DistillCoreReport, type DistillDescriptor, type DistillFromImporterOptions, DistillIndex, type DistillIndexOptions, type DistillIndexRecord, type DistillInput, type DistillPort, type DistillRegistry, type DistillReport, type DistillRunReport, DistillRunner, type DistillRunnerOptions, type DistillScope, type DistillSource, type DistillTarget, type DistilledItem, EMPTY_SELECTOR, type EntryLayout, type EvalCase, EvalContextPort, EvalRubricPort, EvaluatorPort, FetcherPort, type FileKind, FsLockHandle, FsPort, FsStat, type GateFailure, type GateResult, IdentityPort, IllegalPlaybookTransitionError, IllegalTransitionError, type ImportedSource, ImporterRunner, type ImporterRunnerOptions, type ImporterTarget, type IndexReport, type KbListLike, type KbMigrationConfig, KbMigrationImporter, type KbSourceLike, type LanguageFilter, type LayerMode, type LayerProvider, type LayerRef, type LayerShadow, type Lens, type LensMode, type LensStaleness, type LintIssue, type LintReport, LocalFilesImporter, type LocalFilesImporterOptions, type MarkdownDoc, type MatchAttachmentsOptions, type MatchOptions, MemFs, type ModelDistillerOptions, OperatorOverlayResolver, OverlayFs, type OverlayFsOptions, type ParsedFile, type Playbook, type PlaybookBatchOptions, type PlaybookBatchResult, type PlaybookCorpusMeta, PlaybookEvaluator, type PlaybookEvaluatorOptions, type PlaybookKind, PlaybookLifecycle, type PlaybookLifecycleOptions, PlaybookNotFoundError, type PlaybookQuery, PlaybookRegistry, type PlaybookRegistryOptions, type PlaybookStatus, type PlaybookTarget, type PlaybookTargetKind, type PromoteContext, type PromoteOptions, PromoteRejectedError, type PromoteResult, type PushChunksInput, type PushSourceInput, REFINED_KIND_SCHEMA, ReadOnlyFs, type RefinedKind, type RenderedOverlays, type ResolutionContext, type ResolveContext, type ResolveKnowledgeOptions, type ResolveLanguageFilterInput, type ResolveResult, type ResolvedEntry, type ResolvedOverlay, type ReviewerCalibration, type ReviewerScore, ReviewerTrackRecord, type ReviewerTrackRecordOptions, type RunDistillOptions, SPEC_NAME, SPEC_VERSION, SYNTHESIS_ROLE_TAG, type Selector, type SelectorTerm, SidecarDuplicateError, SidecarNotFoundError, type SinkItem, type SinkPort, type SinkPushResult, type SlugifyOptions, type SourceRef, type SourceSelector, type StackEntry, type StackRefPartition, type StackResolution, StackResolver, type StackSkip, type SyncReport, SyncRunner, type SyncRunnerOptions, type SynthesisAtom, type SynthesisInput, type SynthesisPort, type SynthesizeLensOptions, type SynthesizeLensReport, type TrackRecordEntry, type TransitionCheck, type ValidationIssue, type ValidationResult, WELL_KNOWN_AXES, WHITEOUT_SUFFIX, WebImporter, type WebImporterOptions, type WriterChunk, type WriterPort, aggregateReviewerScores, appendAttestation, assertTransition, buildDistillPrompt, buildOverlayFromStack, buildSynthesisPrompt, canTransition, capabilityAxis, chunkText, compileLegacyPlaybookBinding, computeReviewerCalibration, createAxisRegistry, createDistillRegistry, currentLensAtoms, defaultSynthesisPath, distillFromImporter, enumerateWindowRefs, evaluateAccess, evaluateCapability, evaluateGate, extractAutoPromoteConfig, flattenPackRefs, identityAxis, isEmptySelector, isEntrySlug, isRefinedKind, isSourceSlug, lensAspect, lensAspectTag, lensSynthesisStale, makeAttestation, matchAttachmentRefs, matchAttachments, matchesLanguageFilter, matchesSelector, modelDistiller, normalizeLanguageTag, parseItems, parseSelectorFrontmatter, parseWindowRef, partitionStackRefs, pearsonCorrelation, positionAxis, prefixedRefNormalizer, readAccessModes, readAccessSpec, readAttestations, readEntryLanguage, readOperatorLocale, readWorkspaceDefaultLanguage, renderOverlays, resolveKnowledge, resolveLanguageFilter, roleAxis, runDistill, scanDistilledSourceIds, slugify, synthesizeLens, transitionGraphFromCollection, uniqueSlug, windowRef, windowSlug };