@aigne/afs-index 1.12.0-beta.5

package/dist/extraction/manager.mjs

@@ -0,0 +1,74 @@
+//#region src/extraction/manager.ts
+var ExtractorManager = class {
+	registrations = /* @__PURE__ */ new Map();
+	/**
+	* Register an extractor for a domain.
+	* @param domain - Domain name this extractor serves
+	* @param registration - Extractor configuration
+	*/
+	register(domain, registration) {
+		this.registrations.set(domain, registration);
+	}
+	/**
+	* Unregister an extractor for a domain.
+	*/
+	unregister(domain) {
+		this.registrations.delete(domain);
+	}
+	/**
+	* Find the first extractor whose scope matches the given path.
+	* @returns [domainName, registration] or undefined if no match
+	*/
+	findForPath(path) {
+		for (const [domain, reg] of this.registrations) if (path.startsWith(reg.scope)) return [domain, reg];
+	}
+	/**
+	* Dispatch extraction for a path using the matching extractor.
+	* Calls the extractor's AFS exec endpoint and returns the result.
+	*
+	* @returns ExtractionResult or null if no extractor matched or extraction failed
+	*/
+	async extract(path, root) {
+		const match = this.findForPath(path);
+		if (!match) return null;
+		const [domain, reg] = match;
+		if (!reg.extractor || !root.exec) return null;
+		try {
+			const execResult = await root.exec(reg.extractor, { path }, {});
+			if (!execResult.success || !execResult.data) return null;
+			const data = execResult.data;
+			return {
+				domain,
+				result: {
+					anchors: data.anchors ?? [],
+					summary: data.summary,
+					embedding: data.embedding
+				}
+			};
+		} catch {
+			return null;
+		}
+	}
+	/**
+	* List all registered extractors.
+	*/
+	list() {
+		return this.registrations;
+	}
+	/**
+	* Check if any extractors are registered.
+	*/
+	get hasRegistrations() {
+		return this.registrations.size > 0;
+	}
+	/**
+	* Clear all registrations.
+	*/
+	clear() {
+		this.registrations.clear();
+	}
+};
+
+//#endregion
+export { ExtractorManager };
+//# sourceMappingURL=manager.mjs.map

package/dist/extraction/manager.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.mjs","names":[],"sources":["../../src/extraction/manager.ts"],"sourcesContent":["/**\n * ExtractorManager — manages extractor registrations and dispatches extraction requests.\n *\n * Extractors are external AFS exec endpoints that accept a path and return\n * { anchors, summary, embedding? }. They are registered per-domain with a scope\n * that determines which write events they handle.\n */\nimport type { AFSRoot } from \"@aigne/afs\";\nimport type { Anchor, ExtractionResult, ExtractorRegistration } from \"../types.js\";\n\nexport class ExtractorManager {\n  private readonly registrations = new Map<string, ExtractorRegistration>();\n\n  /**\n   * Register an extractor for a domain.\n   * @param domain - Domain name this extractor serves\n   * @param registration - Extractor configuration\n   */\n  register(domain: string, registration: ExtractorRegistration): void {\n    this.registrations.set(domain, registration);\n  }\n\n  /**\n   * Unregister an extractor for a domain.\n   */\n  unregister(domain: string): void {\n    this.registrations.delete(domain);\n  }\n\n  /**\n   * Find the first extractor whose scope matches the given path.\n   * @returns [domainName, registration] or undefined if no match\n   */\n  findForPath(path: string): [string, ExtractorRegistration] | undefined {\n    for (const [domain, reg] of this.registrations) {\n      if (path.startsWith(reg.scope)) {\n        return [domain, reg];\n      }\n    }\n    return undefined;\n  }\n\n  /**\n   * Dispatch extraction for a path using the matching extractor.\n   * Calls the extractor's AFS exec endpoint and returns the result.\n   *\n   * @returns ExtractionResult or null if no extractor matched or extraction failed\n   */\n  async extract(\n    path: string,\n    root: AFSRoot,\n  ): Promise<{ domain: string; result: ExtractionResult } | null> {\n    const match = this.findForPath(path);\n    if (!match) return null;\n\n    const [domain, reg] = match;\n    if (!reg.extractor || !root.exec) return null;\n\n    try {\n      const execResult = await root.exec(reg.extractor, { path }, {});\n      if (!execResult.success || !execResult.data) return null;\n\n      const data = execResult.data as {\n        anchors?: Anchor[];\n        summary?: string;\n        embedding?: number[];\n      };\n      return {\n        domain,\n        result: {\n          anchors: (data.anchors as Anchor[]) ?? [],\n          summary: data.summary,\n          embedding: data.embedding,\n        },\n      };\n    } catch {\n      return null;\n    }\n  }\n\n  /**\n   * List all registered extractors.\n   */\n  list(): ReadonlyMap<string, ExtractorRegistration> {\n    return this.registrations;\n  }\n\n  /**\n   * Check if any extractors are registered.\n   */\n  get hasRegistrations(): boolean {\n    return this.registrations.size > 0;\n  }\n\n  /**\n   * Clear all registrations.\n   */\n  clear(): void {\n    this.registrations.clear();\n  }\n}\n"],"mappings":";AAUA,IAAa,mBAAb,MAA8B;CAC5B,AAAiB,gCAAgB,IAAI,KAAoC;;;;;;CAOzE,SAAS,QAAgB,cAA2C;AAClE,OAAK,cAAc,IAAI,QAAQ,aAAa;;;;;CAM9C,WAAW,QAAsB;AAC/B,OAAK,cAAc,OAAO,OAAO;;;;;;CAOnC,YAAY,MAA2D;AACrE,OAAK,MAAM,CAAC,QAAQ,QAAQ,KAAK,cAC/B,KAAI,KAAK,WAAW,IAAI,MAAM,CAC5B,QAAO,CAAC,QAAQ,IAAI;;;;;;;;CAY1B,MAAM,QACJ,MACA,MAC8D;EAC9D,MAAM,QAAQ,KAAK,YAAY,KAAK;AACpC,MAAI,CAAC,MAAO,QAAO;EAEnB,MAAM,CAAC,QAAQ,OAAO;AACtB,MAAI,CAAC,IAAI,aAAa,CAAC,KAAK,KAAM,QAAO;AAEzC,MAAI;GACF,MAAM,aAAa,MAAM,KAAK,KAAK,IAAI,WAAW,EAAE,MAAM,EAAE,EAAE,CAAC;AAC/D,OAAI,CAAC,WAAW,WAAW,CAAC,WAAW,KAAM,QAAO;GAEpD,MAAM,OAAO,WAAW;AAKxB,UAAO;IACL;IACA,QAAQ;KACN,SAAU,KAAK,WAAwB,EAAE;KACzC,SAAS,KAAK;KACd,WAAW,KAAK;KACjB;IACF;UACK;AACN,UAAO;;;;;;CAOX,OAAmD;AACjD,SAAO,KAAK;;;;;CAMd,IAAI,mBAA4B;AAC9B,SAAO,KAAK,cAAc,OAAO;;;;;CAMnC,QAAc;AACZ,OAAK,cAAc,OAAO"}

package/dist/extraction/path-anchors.cjs

@@ -0,0 +1,86 @@
+
+//#region src/extraction/path-anchors.ts
+/**
+* Path-derived topic anchor extractor.
+*
+* Promoted from the retrieval bench's hand-rolled helper after it
+* lifted the docs/ corpus from R@5=46.7% (FTS only) to R@5=100%
+* (with these anchors + text-embedding-3-small). The win came from
+* making path segments — already the strongest semantic signal in
+* any docs tree — directly addressable as topic anchors.
+*
+* Strategy:
+*
+*   1. Each `/`-delimited segment is added as a topic. Numeric ADR
+*      prefixes (`0001-`) and the `.md` extension get stripped.
+*      Example: `docs/adr/0001-afs-top-level-path-categories.md` →
+*      `docs`, `adr`, `afs-top-level-path-categories`.
+*
+*   2. Project-jargon prefixes (afs-, aup-, ash-, adr-, aigne-, did-,
+*      dev-) are also stripped to yield a second anchor without the
+*      prefix — `afs-top-level-path-categories` →
+*      `top-level-path-categories`. Lets queries that name the topic
+*      without the namespace prefix still match.
+*
+*   3. Trailing 3-4 grams of the stripped form. Specific enough
+*      ("aup-surface-family", "level-path-categories") to add real
+*      retrieval signal; long enough (≥8 chars) to not crowd out
+*      gold matches with generic words. Only trailing because the
+*      head of a slug usually IS the namespace prefix already
+*      captured above.
+*
+*   4. ADR ids surface as `ADR-0001` so questions that name an ADR
+*      pin the right doc deterministically.
+*
+*   5. The first H1 (when content provided) becomes a topic — long
+*      titles fall back to the first 80 chars to keep the lookup
+*      table compact.
+*
+* Sub-token expansion (1- and 2-grams) was tried earlier and hurt
+* R@1 because every doc shares short tokens like "afs" and "agent" —
+* the over-broad match crowded out specific gold hits.
+*/
+const JARGON_PREFIX = /^(afs|aup|ash|adr|aigne|did|dev)-/i;
+/**
+* Extract a single `topic`-typed anchor entry from an AFS path.
+*
+* Returns the canonical shape consumed by `AFSIndex.execIndex`:
+* `[{ type: "topic", values: string[], confidence: 1 }]`. Empty when
+* nothing useful surfaces (e.g. path was just `/` or all segments
+* were stop-words).
+*/
+function extractPathTopicAnchors(entryPath, options = {}) {
+	const topics = /* @__PURE__ */ new Set();
+	const cleanPath = entryPath.replace(/^\/+/, "");
+	for (const seg of cleanPath.split("/")) {
+		const stripped = seg.replace(/\.md$/, "").replace(/^\d+-/, "");
+		if (!stripped || stripped.toLowerCase() === "readme") continue;
+		topics.add(stripped);
+		const noPrefix = stripped.replace(JARGON_PREFIX, "");
+		if (noPrefix !== stripped && noPrefix.length > 0) topics.add(noPrefix);
+		const parts = stripped.toLowerCase().split("-").filter(Boolean);
+		if (parts.length >= 4) for (let n = 3; n <= 4; n++) for (let i = parts.length - n; i >= 0 && i >= parts.length - 4; i--) {
+			const gram = parts.slice(i, i + n).join("-");
+			if (gram.length >= 8) topics.add(gram);
+		}
+	}
+	const adrMatch = /\b(\d{4})-/.exec(cleanPath);
+	if (adrMatch) topics.add(`ADR-${adrMatch[1]}`);
+	if (options.content) {
+		const h1 = options.content.match(/^#\s+(.+)$/m);
+		if (h1) {
+			const title = h1[1].slice(0, 80).trim();
+			if (title) topics.add(title);
+		}
+	}
+	if (topics.size === 0) return [];
+	const cap = options.maxValues ?? 32;
+	return [{
+		type: "topic",
+		values: [...topics].slice(0, cap),
+		confidence: 1
+	}];
+}
+
+//#endregion
+exports.extractPathTopicAnchors = extractPathTopicAnchors;

package/dist/extraction/path-anchors.d.cts

@@ -0,0 +1,72 @@
+//#region src/extraction/path-anchors.d.ts
+/**
+ * Path-derived topic anchor extractor.
+ *
+ * Promoted from the retrieval bench's hand-rolled helper after it
+ * lifted the docs/ corpus from R@5=46.7% (FTS only) to R@5=100%
+ * (with these anchors + text-embedding-3-small). The win came from
+ * making path segments — already the strongest semantic signal in
+ * any docs tree — directly addressable as topic anchors.
+ *
+ * Strategy:
+ *
+ *   1. Each `/`-delimited segment is added as a topic. Numeric ADR
+ *      prefixes (`0001-`) and the `.md` extension get stripped.
+ *      Example: `docs/adr/0001-afs-top-level-path-categories.md` →
+ *      `docs`, `adr`, `afs-top-level-path-categories`.
+ *
+ *   2. Project-jargon prefixes (afs-, aup-, ash-, adr-, aigne-, did-,
+ *      dev-) are also stripped to yield a second anchor without the
+ *      prefix — `afs-top-level-path-categories` →
+ *      `top-level-path-categories`. Lets queries that name the topic
+ *      without the namespace prefix still match.
+ *
+ *   3. Trailing 3-4 grams of the stripped form. Specific enough
+ *      ("aup-surface-family", "level-path-categories") to add real
+ *      retrieval signal; long enough (≥8 chars) to not crowd out
+ *      gold matches with generic words. Only trailing because the
+ *      head of a slug usually IS the namespace prefix already
+ *      captured above.
+ *
+ *   4. ADR ids surface as `ADR-0001` so questions that name an ADR
+ *      pin the right doc deterministically.
+ *
+ *   5. The first H1 (when content provided) becomes a topic — long
+ *      titles fall back to the first 80 chars to keep the lookup
+ *      table compact.
+ *
+ * Sub-token expansion (1- and 2-grams) was tried earlier and hurt
+ * R@1 because every doc shares short tokens like "afs" and "agent" —
+ * the over-broad match crowded out specific gold hits.
+ */
+interface PathAnchorOptions {
+  /**
+   * Optional document body. When supplied, the first H1 line
+   * (`# Title`) becomes a topic. Truncated to 80 chars so a long
+   * title doesn't blow up the lookup table.
+   */
+  content?: string;
+  /**
+   * Maximum number of distinct anchor values to emit. Defaults to 32.
+   * The anchor backend stores one row per (entry_path, key), so a
+   * very high cap inflates `idx_anchor_key` without proportional recall
+   * gain. 32 was the sweet spot in the docs/ corpus bench.
+   */
+  maxValues?: number;
+}
+/**
+ * Extract a single `topic`-typed anchor entry from an AFS path.
+ *
+ * Returns the canonical shape consumed by `AFSIndex.execIndex`:
+ * `[{ type: "topic", values: string[], confidence: 1 }]`. Empty when
+ * nothing useful surfaces (e.g. path was just `/` or all segments
+ * were stop-words).
+ */
+declare function extractPathTopicAnchors(entryPath: string, options?: PathAnchorOptions): Array<{
+  type: "topic";
+  values: string[];
+  confidence: number;
+}>;
+//#endregion
+export { PathAnchorOptions, extractPathTopicAnchors };
+//# sourceMappingURL=path-anchors.d.cts.map

package/dist/extraction/path-anchors.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-anchors.d.cts","names":[],"sources":["../../src/extraction/path-anchors.ts"],"mappings":";;AA2CA;;;;;AAwBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UAxBiB,iBAAA;;;;;;EAMf,OAAA;;;;;;;EAOA,SAAA;AAAA;;;;;;;;;iBAWc,uBAAA,CACd,SAAA,UACA,OAAA,GAAS,iBAAA,GACR,KAAA;EAAQ,IAAA;EAAe,MAAA;EAAkB,UAAA;AAAA"}

package/dist/extraction/path-anchors.d.mts

@@ -0,0 +1,72 @@
+//#region src/extraction/path-anchors.d.ts
+/**
+ * Path-derived topic anchor extractor.
+ *
+ * Promoted from the retrieval bench's hand-rolled helper after it
+ * lifted the docs/ corpus from R@5=46.7% (FTS only) to R@5=100%
+ * (with these anchors + text-embedding-3-small). The win came from
+ * making path segments — already the strongest semantic signal in
+ * any docs tree — directly addressable as topic anchors.
+ *
+ * Strategy:
+ *
+ *   1. Each `/`-delimited segment is added as a topic. Numeric ADR
+ *      prefixes (`0001-`) and the `.md` extension get stripped.
+ *      Example: `docs/adr/0001-afs-top-level-path-categories.md` →
+ *      `docs`, `adr`, `afs-top-level-path-categories`.
+ *
+ *   2. Project-jargon prefixes (afs-, aup-, ash-, adr-, aigne-, did-,
+ *      dev-) are also stripped to yield a second anchor without the
+ *      prefix — `afs-top-level-path-categories` →
+ *      `top-level-path-categories`. Lets queries that name the topic
+ *      without the namespace prefix still match.
+ *
+ *   3. Trailing 3-4 grams of the stripped form. Specific enough
+ *      ("aup-surface-family", "level-path-categories") to add real
+ *      retrieval signal; long enough (≥8 chars) to not crowd out
+ *      gold matches with generic words. Only trailing because the
+ *      head of a slug usually IS the namespace prefix already
+ *      captured above.
+ *
+ *   4. ADR ids surface as `ADR-0001` so questions that name an ADR
+ *      pin the right doc deterministically.
+ *
+ *   5. The first H1 (when content provided) becomes a topic — long
+ *      titles fall back to the first 80 chars to keep the lookup
+ *      table compact.
+ *
+ * Sub-token expansion (1- and 2-grams) was tried earlier and hurt
+ * R@1 because every doc shares short tokens like "afs" and "agent" —
+ * the over-broad match crowded out specific gold hits.
+ */
+interface PathAnchorOptions {
+  /**
+   * Optional document body. When supplied, the first H1 line
+   * (`# Title`) becomes a topic. Truncated to 80 chars so a long
+   * title doesn't blow up the lookup table.
+   */
+  content?: string;
+  /**
+   * Maximum number of distinct anchor values to emit. Defaults to 32.
+   * The anchor backend stores one row per (entry_path, key), so a
+   * very high cap inflates `idx_anchor_key` without proportional recall
+   * gain. 32 was the sweet spot in the docs/ corpus bench.
+   */
+  maxValues?: number;
+}
+/**
+ * Extract a single `topic`-typed anchor entry from an AFS path.
+ *
+ * Returns the canonical shape consumed by `AFSIndex.execIndex`:
+ * `[{ type: "topic", values: string[], confidence: 1 }]`. Empty when
+ * nothing useful surfaces (e.g. path was just `/` or all segments
+ * were stop-words).
+ */
+declare function extractPathTopicAnchors(entryPath: string, options?: PathAnchorOptions): Array<{
+  type: "topic";
+  values: string[];
+  confidence: number;
+}>;
+//#endregion
+export { PathAnchorOptions, extractPathTopicAnchors };
+//# sourceMappingURL=path-anchors.d.mts.map

package/dist/extraction/path-anchors.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-anchors.d.mts","names":[],"sources":["../../src/extraction/path-anchors.ts"],"mappings":";;AA2CA;;;;;AAwBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UAxBiB,iBAAA;;;;;;EAMf,OAAA;;;;;;;EAOA,SAAA;AAAA;;;;;;;;;iBAWc,uBAAA,CACd,SAAA,UACA,OAAA,GAAS,iBAAA,GACR,KAAA;EAAQ,IAAA;EAAe,MAAA;EAAkB,UAAA;AAAA"}

package/dist/extraction/path-anchors.mjs

@@ -0,0 +1,86 @@
+//#region src/extraction/path-anchors.ts
+/**
+* Path-derived topic anchor extractor.
+*
+* Promoted from the retrieval bench's hand-rolled helper after it
+* lifted the docs/ corpus from R@5=46.7% (FTS only) to R@5=100%
+* (with these anchors + text-embedding-3-small). The win came from
+* making path segments — already the strongest semantic signal in
+* any docs tree — directly addressable as topic anchors.
+*
+* Strategy:
+*
+*   1. Each `/`-delimited segment is added as a topic. Numeric ADR
+*      prefixes (`0001-`) and the `.md` extension get stripped.
+*      Example: `docs/adr/0001-afs-top-level-path-categories.md` →
+*      `docs`, `adr`, `afs-top-level-path-categories`.
+*
+*   2. Project-jargon prefixes (afs-, aup-, ash-, adr-, aigne-, did-,
+*      dev-) are also stripped to yield a second anchor without the
+*      prefix — `afs-top-level-path-categories` →
+*      `top-level-path-categories`. Lets queries that name the topic
+*      without the namespace prefix still match.
+*
+*   3. Trailing 3-4 grams of the stripped form. Specific enough
+*      ("aup-surface-family", "level-path-categories") to add real
+*      retrieval signal; long enough (≥8 chars) to not crowd out
+*      gold matches with generic words. Only trailing because the
+*      head of a slug usually IS the namespace prefix already
+*      captured above.
+*
+*   4. ADR ids surface as `ADR-0001` so questions that name an ADR
+*      pin the right doc deterministically.
+*
+*   5. The first H1 (when content provided) becomes a topic — long
+*      titles fall back to the first 80 chars to keep the lookup
+*      table compact.
+*
+* Sub-token expansion (1- and 2-grams) was tried earlier and hurt
+* R@1 because every doc shares short tokens like "afs" and "agent" —
+* the over-broad match crowded out specific gold hits.
+*/
+const JARGON_PREFIX = /^(afs|aup|ash|adr|aigne|did|dev)-/i;
+/**
+* Extract a single `topic`-typed anchor entry from an AFS path.
+*
+* Returns the canonical shape consumed by `AFSIndex.execIndex`:
+* `[{ type: "topic", values: string[], confidence: 1 }]`. Empty when
+* nothing useful surfaces (e.g. path was just `/` or all segments
+* were stop-words).
+*/
+function extractPathTopicAnchors(entryPath, options = {}) {
+	const topics = /* @__PURE__ */ new Set();
+	const cleanPath = entryPath.replace(/^\/+/, "");
+	for (const seg of cleanPath.split("/")) {
+		const stripped = seg.replace(/\.md$/, "").replace(/^\d+-/, "");
+		if (!stripped || stripped.toLowerCase() === "readme") continue;
+		topics.add(stripped);
+		const noPrefix = stripped.replace(JARGON_PREFIX, "");
+		if (noPrefix !== stripped && noPrefix.length > 0) topics.add(noPrefix);
+		const parts = stripped.toLowerCase().split("-").filter(Boolean);
+		if (parts.length >= 4) for (let n = 3; n <= 4; n++) for (let i = parts.length - n; i >= 0 && i >= parts.length - 4; i--) {
+			const gram = parts.slice(i, i + n).join("-");
+			if (gram.length >= 8) topics.add(gram);
+		}
+	}
+	const adrMatch = /\b(\d{4})-/.exec(cleanPath);
+	if (adrMatch) topics.add(`ADR-${adrMatch[1]}`);
+	if (options.content) {
+		const h1 = options.content.match(/^#\s+(.+)$/m);
+		if (h1) {
+			const title = h1[1].slice(0, 80).trim();
+			if (title) topics.add(title);
+		}
+	}
+	if (topics.size === 0) return [];
+	const cap = options.maxValues ?? 32;
+	return [{
+		type: "topic",
+		values: [...topics].slice(0, cap),
+		confidence: 1
+	}];
+}
+
+//#endregion
+export { extractPathTopicAnchors };
+//# sourceMappingURL=path-anchors.mjs.map

package/dist/extraction/path-anchors.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-anchors.mjs","names":[],"sources":["../../src/extraction/path-anchors.ts"],"sourcesContent":["/**\n * Path-derived topic anchor extractor.\n *\n * Promoted from the retrieval bench's hand-rolled helper after it\n * lifted the docs/ corpus from R@5=46.7% (FTS only) to R@5=100%\n * (with these anchors + text-embedding-3-small). The win came from\n * making path segments — already the strongest semantic signal in\n * any docs tree — directly addressable as topic anchors.\n *\n * Strategy:\n *\n *   1. Each `/`-delimited segment is added as a topic. Numeric ADR\n *      prefixes (`0001-`) and the `.md` extension get stripped.\n *      Example: `docs/adr/0001-afs-top-level-path-categories.md` →\n *      `docs`, `adr`, `afs-top-level-path-categories`.\n *\n *   2. Project-jargon prefixes (afs-, aup-, ash-, adr-, aigne-, did-,\n *      dev-) are also stripped to yield a second anchor without the\n *      prefix — `afs-top-level-path-categories` →\n *      `top-level-path-categories`. Lets queries that name the topic\n *      without the namespace prefix still match.\n *\n *   3. Trailing 3-4 grams of the stripped form. Specific enough\n *      (\"aup-surface-family\", \"level-path-categories\") to add real\n *      retrieval signal; long enough (≥8 chars) to not crowd out\n *      gold matches with generic words. Only trailing because the\n *      head of a slug usually IS the namespace prefix already\n *      captured above.\n *\n *   4. ADR ids surface as `ADR-0001` so questions that name an ADR\n *      pin the right doc deterministically.\n *\n *   5. The first H1 (when content provided) becomes a topic — long\n *      titles fall back to the first 80 chars to keep the lookup\n *      table compact.\n *\n * Sub-token expansion (1- and 2-grams) was tried earlier and hurt\n * R@1 because every doc shares short tokens like \"afs\" and \"agent\" —\n * the over-broad match crowded out specific gold hits.\n */\n\nconst JARGON_PREFIX = /^(afs|aup|ash|adr|aigne|did|dev)-/i;\n\nexport interface PathAnchorOptions {\n  /**\n   * Optional document body. When supplied, the first H1 line\n   * (`# Title`) becomes a topic. Truncated to 80 chars so a long\n   * title doesn't blow up the lookup table.\n   */\n  content?: string;\n  /**\n   * Maximum number of distinct anchor values to emit. Defaults to 32.\n   * The anchor backend stores one row per (entry_path, key), so a\n   * very high cap inflates `idx_anchor_key` without proportional recall\n   * gain. 32 was the sweet spot in the docs/ corpus bench.\n   */\n  maxValues?: number;\n}\n\n/**\n * Extract a single `topic`-typed anchor entry from an AFS path.\n *\n * Returns the canonical shape consumed by `AFSIndex.execIndex`:\n * `[{ type: \"topic\", values: string[], confidence: 1 }]`. Empty when\n * nothing useful surfaces (e.g. path was just `/` or all segments\n * were stop-words).\n */\nexport function extractPathTopicAnchors(\n  entryPath: string,\n  options: PathAnchorOptions = {},\n): Array<{ type: \"topic\"; values: string[]; confidence: number }> {\n  const topics = new Set<string>();\n  const cleanPath = entryPath.replace(/^\\/+/, \"\");\n\n  for (const seg of cleanPath.split(\"/\")) {\n    const stripped = seg.replace(/\\.md$/, \"\").replace(/^\\d+-/, \"\");\n    if (!stripped || stripped.toLowerCase() === \"readme\") continue;\n\n    topics.add(stripped);\n\n    const noPrefix = stripped.replace(JARGON_PREFIX, \"\");\n    if (noPrefix !== stripped && noPrefix.length > 0) topics.add(noPrefix);\n\n    const parts = stripped.toLowerCase().split(\"-\").filter(Boolean);\n    if (parts.length >= 4) {\n      for (let n = 3; n <= 4; n++) {\n        for (let i = parts.length - n; i >= 0 && i >= parts.length - 4; i--) {\n          const gram = parts.slice(i, i + n).join(\"-\");\n          if (gram.length >= 8) topics.add(gram);\n        }\n      }\n    }\n  }\n\n  const adrMatch = /\\b(\\d{4})-/.exec(cleanPath);\n  if (adrMatch) topics.add(`ADR-${adrMatch[1]}`);\n\n  if (options.content) {\n    const h1 = options.content.match(/^#\\s+(.+)$/m);\n    if (h1) {\n      const title = h1[1]!.slice(0, 80).trim();\n      if (title) topics.add(title);\n    }\n  }\n\n  if (topics.size === 0) return [];\n\n  const cap = options.maxValues ?? 32;\n  return [\n    {\n      type: \"topic\",\n      values: [...topics].slice(0, cap),\n      confidence: 1,\n    },\n  ];\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyCA,MAAM,gBAAgB;;;;;;;;;AA0BtB,SAAgB,wBACd,WACA,UAA6B,EAAE,EACiC;CAChE,MAAM,yBAAS,IAAI,KAAa;CAChC,MAAM,YAAY,UAAU,QAAQ,QAAQ,GAAG;AAE/C,MAAK,MAAM,OAAO,UAAU,MAAM,IAAI,EAAE;EACtC,MAAM,WAAW,IAAI,QAAQ,SAAS,GAAG,CAAC,QAAQ,SAAS,GAAG;AAC9D,MAAI,CAAC,YAAY,SAAS,aAAa,KAAK,SAAU;AAEtD,SAAO,IAAI,SAAS;EAEpB,MAAM,WAAW,SAAS,QAAQ,eAAe,GAAG;AACpD,MAAI,aAAa,YAAY,SAAS,SAAS,EAAG,QAAO,IAAI,SAAS;EAEtE,MAAM,QAAQ,SAAS,aAAa,CAAC,MAAM,IAAI,CAAC,OAAO,QAAQ;AAC/D,MAAI,MAAM,UAAU,EAClB,MAAK,IAAI,IAAI,GAAG,KAAK,GAAG,IACtB,MAAK,IAAI,IAAI,MAAM,SAAS,GAAG,KAAK,KAAK,KAAK,MAAM,SAAS,GAAG,KAAK;GACnE,MAAM,OAAO,MAAM,MAAM,GAAG,IAAI,EAAE,CAAC,KAAK,IAAI;AAC5C,OAAI,KAAK,UAAU,EAAG,QAAO,IAAI,KAAK;;;CAM9C,MAAM,WAAW,aAAa,KAAK,UAAU;AAC7C,KAAI,SAAU,QAAO,IAAI,OAAO,SAAS,KAAK;AAE9C,KAAI,QAAQ,SAAS;EACnB,MAAM,KAAK,QAAQ,QAAQ,MAAM,cAAc;AAC/C,MAAI,IAAI;GACN,MAAM,QAAQ,GAAG,GAAI,MAAM,GAAG,GAAG,CAAC,MAAM;AACxC,OAAI,MAAO,QAAO,IAAI,MAAM;;;AAIhC,KAAI,OAAO,SAAS,EAAG,QAAO,EAAE;CAEhC,MAAM,MAAM,QAAQ,aAAa;AACjC,QAAO,CACL;EACE,MAAM;EACN,QAAQ,CAAC,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI;EACjC,YAAY;EACb,CACF"}

package/dist/follower-scheduler.cjs

@@ -0,0 +1,92 @@
+
+//#region src/follower-scheduler.ts
+function clampSpent(value, remaining) {
+	if (!Number.isFinite(value ?? 0) || (value ?? 0) <= 0) return 0;
+	return Math.min(value ?? 0, remaining);
+}
+/**
+* Fairly spend one index-follower tick across a selected scope set.
+*
+* Each scope receives a small bounded slice first; scopes that still report
+* `hasMore` are appended to the tail and can receive another slice only after
+* the other selected scopes had their chance. The helper is intentionally
+* storage/runtime-agnostic so Cloudflare and Node share the same starvation
+* semantics while keeping different budget sizes.
+*/
+async function runIndexFollowerRoundRobin(opts) {
+	let remainingProcessed = Math.max(0, opts.maxProcessed);
+	let remainingNoop = Math.max(0, opts.maxNoop);
+	let remainingScan = Math.max(0, opts.maxScan);
+	const perScopeMaxProcessed = Math.max(0, opts.perScopeMaxProcessed ?? 1);
+	const perScopeMaxNoop = Math.max(0, opts.perScopeMaxNoop ?? 2);
+	const perScopeMaxScan = Math.max(1, opts.perScopeMaxScan ?? 50);
+	const maxRuns = opts.maxRuns ?? opts.scopes.length + Math.ceil((remainingProcessed || 0) / Math.max(1, perScopeMaxProcessed || 1)) + Math.ceil((remainingNoop || 0) / Math.max(1, perScopeMaxNoop || 1)) + Math.ceil((remainingScan || 0) / Math.max(1, perScopeMaxScan));
+	const queue = [...opts.scopes];
+	const runs = [];
+	let indexedThisTick = 0;
+	let deletedThisTick = 0;
+	let noopedThisTick = 0;
+	let ackRaceThisTick = 0;
+	let stoppedBy = "drained";
+	let sawBudgetBlockedScope = false;
+	while (queue.length > 0) {
+		if (opts.shouldStop?.()) {
+			stoppedBy = "time";
+			break;
+		}
+		if (runs.length >= maxRuns) {
+			stoppedBy = "max_runs";
+			break;
+		}
+		if (remainingScan <= 0 || remainingProcessed <= 0 && remainingNoop <= 0) {
+			stoppedBy = "budget";
+			break;
+		}
+		const scope = queue.shift();
+		const limits = {
+			maxProcessed: Math.min(perScopeMaxProcessed, remainingProcessed),
+			maxNoop: Math.min(perScopeMaxNoop, remainingNoop),
+			maxScan: Math.min(perScopeMaxScan, remainingScan)
+		};
+		if (limits.maxScan <= 0 || limits.maxProcessed <= 0 && limits.maxNoop <= 0) {
+			stoppedBy = "budget";
+			break;
+		}
+		const result = await opts.runScope(scope, limits);
+		runs.push({
+			scope,
+			limits,
+			result
+		});
+		remainingProcessed -= clampSpent(result.processed, remainingProcessed);
+		remainingNoop -= clampSpent(result.noopProcessed, remainingNoop);
+		remainingScan -= clampSpent(result.scanned, remainingScan);
+		indexedThisTick += result.indexed;
+		deletedThisTick += result.deleted;
+		noopedThisTick += result.nooped;
+		if (result.ackRace) ackRaceThisTick++;
+		if (!result.advanced && result.hasMore && [
+			"processed_budget",
+			"noop_budget",
+			"scan_budget"
+		].includes(result.stopReason ?? "")) sawBudgetBlockedScope = true;
+		if (result.advanced && result.hasMore && !result.aborted && remainingScan > 0 && (remainingProcessed > 0 || remainingNoop > 0)) queue.push(scope);
+	}
+	return {
+		runs,
+		processedThisTick: opts.maxProcessed - remainingProcessed,
+		noopThisTick: opts.maxNoop - remainingNoop,
+		indexedThisTick,
+		deletedThisTick,
+		noopedThisTick,
+		scannedThisTick: opts.maxScan - remainingScan,
+		ackRaceThisTick,
+		stoppedBy: stoppedBy === "drained" && sawBudgetBlockedScope ? "budget" : stoppedBy,
+		remainingProcessed,
+		remainingNoop,
+		remainingScan
+	};
+}
+
+//#endregion
+exports.runIndexFollowerRoundRobin = runIndexFollowerRoundRobin;

package/dist/follower-scheduler.d.cts

@@ -0,0 +1,58 @@
+import { IndexFollowerBatchResult } from "./follower.cjs";
+
+//#region src/follower-scheduler.d.ts
+interface IndexFollowerRunLimits {
+  maxProcessed: number;
+  maxNoop: number;
+  maxScan: number;
+}
+interface IndexFollowerRoundRobinOptions<T> {
+  scopes: T[];
+  maxProcessed: number;
+  maxNoop: number;
+  maxScan: number;
+  perScopeMaxProcessed?: number;
+  perScopeMaxNoop?: number;
+  perScopeMaxScan?: number;
+  maxRuns?: number;
+  shouldStop?: () => boolean;
+  runScope: (scope: T, limits: IndexFollowerRunLimits) => Promise<IndexFollowerBatchResult>;
+}
+interface IndexFollowerRoundRobinRun<T> {
+  scope: T;
+  limits: IndexFollowerRunLimits;
+  result: IndexFollowerBatchResult;
+}
+interface IndexFollowerRoundRobinResult<T> {
+  runs: IndexFollowerRoundRobinRun<T>[];
+  processedThisTick: number;
+  noopThisTick: number;
+  indexedThisTick: number;
+  deletedThisTick: number;
+  noopedThisTick: number;
+  scannedThisTick: number;
+  /**
+   * Drain RUNS that lost the ack race-guard this tick (healthy concurrent-write
+   * churn, not failures). Counted per `runScope` call, so a single hot scope
+   * requeued within the tick can contribute more than once — this is a run
+   * occurrence count, not a distinct-scope count.
+   */
+  ackRaceThisTick: number;
+  stoppedBy: "drained" | "budget" | "max_runs" | "time";
+  remainingProcessed: number;
+  remainingNoop: number;
+  remainingScan: number;
+}
+/**
+ * Fairly spend one index-follower tick across a selected scope set.
+ *
+ * Each scope receives a small bounded slice first; scopes that still report
+ * `hasMore` are appended to the tail and can receive another slice only after
+ * the other selected scopes had their chance. The helper is intentionally
+ * storage/runtime-agnostic so Cloudflare and Node share the same starvation
+ * semantics while keeping different budget sizes.
+ */
+declare function runIndexFollowerRoundRobin<T>(opts: IndexFollowerRoundRobinOptions<T>): Promise<IndexFollowerRoundRobinResult<T>>;
+//#endregion
+export { IndexFollowerRoundRobinOptions, IndexFollowerRoundRobinResult, IndexFollowerRoundRobinRun, IndexFollowerRunLimits, runIndexFollowerRoundRobin };
+//# sourceMappingURL=follower-scheduler.d.cts.map

package/dist/follower-scheduler.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"follower-scheduler.d.cts","names":[],"sources":["../src/follower-scheduler.ts"],"mappings":";;;UAMiB,sBAAA;EACf,YAAA;EACA,OAAA;EACA,OAAA;AAAA;AAAA,UAGe,8BAAA;EACf,MAAA,EAAQ,CAAA;EACR,YAAA;EACA,OAAA;EACA,OAAA;EACA,oBAAA;EACA,eAAA;EACA,eAAA;EACA,OAAA;EACA,UAAA;EACA,QAAA,GAAW,KAAA,EAAO,CAAA,EAAG,MAAA,EAAQ,sBAAA,KAA2B,OAAA,CAAQ,wBAAA;AAAA;AAAA,UAGjD,0BAAA;EACf,KAAA,EAAO,CAAA;EACP,MAAA,EAAQ,sBAAA;EACR,MAAA,EAAQ,wBAAA;AAAA;AAAA,UAGO,6BAAA;EACf,IAAA,EAAM,0BAAA,CAA2B,CAAA;EACjC,iBAAA;EACA,YAAA;EACA,eAAA;EACA,eAAA;EACA,cAAA;EACA,eAAA;EAlBA;;;;;;EAyBA,eAAA;EACA,SAAA;EACA,kBAAA;EACA,aAAA;EACA,aAAA;AAAA;;;;;;;;;;iBAiBoB,0BAAA,GAAA,CACpB,IAAA,EAAM,8BAAA,CAA+B,CAAA,IACpC,OAAA,CAAQ,6BAAA,CAA8B,CAAA"}

package/dist/follower-scheduler.d.mts

@@ -0,0 +1,58 @@
+import { IndexFollowerBatchResult } from "./follower.mjs";
+
+//#region src/follower-scheduler.d.ts
+interface IndexFollowerRunLimits {
+  maxProcessed: number;
+  maxNoop: number;
+  maxScan: number;
+}
+interface IndexFollowerRoundRobinOptions<T> {
+  scopes: T[];
+  maxProcessed: number;
+  maxNoop: number;
+  maxScan: number;
+  perScopeMaxProcessed?: number;
+  perScopeMaxNoop?: number;
+  perScopeMaxScan?: number;
+  maxRuns?: number;
+  shouldStop?: () => boolean;
+  runScope: (scope: T, limits: IndexFollowerRunLimits) => Promise<IndexFollowerBatchResult>;
+}
+interface IndexFollowerRoundRobinRun<T> {
+  scope: T;
+  limits: IndexFollowerRunLimits;
+  result: IndexFollowerBatchResult;
+}
+interface IndexFollowerRoundRobinResult<T> {
+  runs: IndexFollowerRoundRobinRun<T>[];
+  processedThisTick: number;
+  noopThisTick: number;
+  indexedThisTick: number;
+  deletedThisTick: number;
+  noopedThisTick: number;
+  scannedThisTick: number;
+  /**
+   * Drain RUNS that lost the ack race-guard this tick (healthy concurrent-write
+   * churn, not failures). Counted per `runScope` call, so a single hot scope
+   * requeued within the tick can contribute more than once — this is a run
+   * occurrence count, not a distinct-scope count.
+   */
+  ackRaceThisTick: number;
+  stoppedBy: "drained" | "budget" | "max_runs" | "time";
+  remainingProcessed: number;
+  remainingNoop: number;
+  remainingScan: number;
+}
+/**
+ * Fairly spend one index-follower tick across a selected scope set.
+ *
+ * Each scope receives a small bounded slice first; scopes that still report
+ * `hasMore` are appended to the tail and can receive another slice only after
+ * the other selected scopes had their chance. The helper is intentionally
+ * storage/runtime-agnostic so Cloudflare and Node share the same starvation
+ * semantics while keeping different budget sizes.
+ */
+declare function runIndexFollowerRoundRobin<T>(opts: IndexFollowerRoundRobinOptions<T>): Promise<IndexFollowerRoundRobinResult<T>>;
+//#endregion
+export { IndexFollowerRoundRobinOptions, IndexFollowerRoundRobinResult, IndexFollowerRoundRobinRun, IndexFollowerRunLimits, runIndexFollowerRoundRobin };
+//# sourceMappingURL=follower-scheduler.d.mts.map

package/dist/follower-scheduler.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"follower-scheduler.d.mts","names":[],"sources":["../src/follower-scheduler.ts"],"mappings":";;;UAMiB,sBAAA;EACf,YAAA;EACA,OAAA;EACA,OAAA;AAAA;AAAA,UAGe,8BAAA;EACf,MAAA,EAAQ,CAAA;EACR,YAAA;EACA,OAAA;EACA,OAAA;EACA,oBAAA;EACA,eAAA;EACA,eAAA;EACA,OAAA;EACA,UAAA;EACA,QAAA,GAAW,KAAA,EAAO,CAAA,EAAG,MAAA,EAAQ,sBAAA,KAA2B,OAAA,CAAQ,wBAAA;AAAA;AAAA,UAGjD,0BAAA;EACf,KAAA,EAAO,CAAA;EACP,MAAA,EAAQ,sBAAA;EACR,MAAA,EAAQ,wBAAA;AAAA;AAAA,UAGO,6BAAA;EACf,IAAA,EAAM,0BAAA,CAA2B,CAAA;EACjC,iBAAA;EACA,YAAA;EACA,eAAA;EACA,eAAA;EACA,cAAA;EACA,eAAA;EAlBA;;;;;;EAyBA,eAAA;EACA,SAAA;EACA,kBAAA;EACA,aAAA;EACA,aAAA;AAAA;;;;;;;;;;iBAiBoB,0BAAA,GAAA,CACpB,IAAA,EAAM,8BAAA,CAA+B,CAAA,IACpC,OAAA,CAAQ,6BAAA,CAA8B,CAAA"}