@fenglimg/fabric-shared 2.1.0-rc.2 → 2.2.0-rc.3

package/dist/index.js

@@ -1,12 +1,4 @@
-import {
-  BOOTSTRAP_CANONICAL,
-  BOOTSTRAP_MARKER_BEGIN,
-  BOOTSTRAP_MARKER_END,
-  BOOTSTRAP_REGEX,
-  LEGACY_KB_MARKER_BEGIN,
-  LEGACY_KB_MARKER_END,
-  LEGACY_KB_REGEX
-} from "./chunk-MDWTGOAY.js";
+import "./chunk-LXNCAKJZ.js";
 import {
   PROTECTED_TOKENS,
   createTranslator,
@@ -16,7 +8,7 @@ import {
   normalizeLocale,
   resolveFabricLocale,
   zhCNMessages
-} from "./chunk-R2J7DAED.js";
+} from "./chunk-QSD4PN4W.js";
 import {
   FabExtractKnowledgeInputSchema,
   FabExtractKnowledgeInputShape,
@@ -64,8 +56,16 @@ import {
   recallInputSchema,
   recallOutputSchema,
   structuredWarningSchema
-} from "./chunk-WVPDH4BF.js";
-import "./chunk-LXNCAKJZ.js";
+} from "./chunk-355LUDLW.js";
+import {
+  BOOTSTRAP_CANONICAL,
+  BOOTSTRAP_MARKER_BEGIN,
+  BOOTSTRAP_MARKER_END,
+  BOOTSTRAP_REGEX,
+  LEGACY_KB_MARKER_BEGIN,
+  LEGACY_KB_MARKER_END,
+  LEGACY_KB_REGEX
+} from "./chunk-AFT7DB4P.js";
 
 // src/schemas/agents-meta.ts
 import { z } from "zod";
@@ -112,7 +112,15 @@ var ruleDescriptionSchema = z.object({
   //   relevance_scope → 'broad'   (always-surface, safe default)
   //   relevance_paths → []        (no path anchors)
   relevance_scope: z.enum(["narrow", "broad"]).default("broad"),
-  relevance_paths: z.array(z.string()).default([])
+  relevance_paths: z.array(z.string()).default([]),
+  // v2.2 H2-related (W1-T7): explicit graph edges to related KB entries by
+  // stable_id. Authored in frontmatter (`related: [KT-DEC-0001, KT-PIT-0002]`)
+  // or written by the fabric-connect skill (SK2); read by fab_recall's
+  // include_related packaging (MC1). Optional + default [] so the field is a
+  // pure additive — every pre-v2.2 entry parses unchanged. The schema is
+  // .strict(), so this MUST be declared or `related:` frontmatter would be
+  // rejected at parse time.
+  related: z.array(z.string()).default([]).optional()
 }).strict();
 var ruleDescriptionIndexItemSchema = z.object({
   stable_id: z.string(),
@@ -417,6 +425,7 @@ var mcpPayloadLimitsSchema = z6.object({
   hardBytes: z6.number().int().positive().optional()
 }).optional();
 var selectionTokenTtlMsSchema = z6.number().int().min(3e4).max(36e5);
+var planContextTopKSchema = z6.number().int().min(1).max(200);
 var fabricLanguageSchema = z6.enum([
   "match-existing",
   "zh-CN",
@@ -592,6 +601,30 @@ var fabricConfigSchema = z6.object({
   // high-contract-criticality projects. Other strategies (time-based,
   // token-budget) deferred to rc.35 per plan locked-decisions 2026-05-26.
   cite_evict_interval: z6.number().int().min(0).optional().default(0),
+  // v2.1 ⑤ cite-redesign (P5): recall-based cite-accounting hook config. The
+  // rc.34 cite_evict_interval turn-counter above is superseded by the
+  // PreToolUse(Edit/Write) recall-aware nudge in cite-policy-evict.cjs; the old
+  // key is retained for back-compat (inert now that the hook moved off
+  // UserPromptSubmit). `cite_recall_nudge` is the master switch (default true =
+  // ON); set false to silence the "改前先 fab_recall" nudge entirely (mirrors
+  // the cite_evict_interval=0 opt-out convention). `cite_recall_window_minutes`
+  // bounds how far back an in-session fab_recall counts as "informing" the edit
+  // (default 30; 0 = unbounded).
+  cite_recall_nudge: z6.boolean().optional().default(true),
+  cite_recall_window_minutes: z6.number().int().min(0).optional().default(30),
+  // F2: glob exemptions for the cite nudge (cite-policy-evict.cjs). Edit paths
+  // matching any glob skip the "改前先 fab_recall" nudge — meta/orchestration
+  // files (e.g. `.workflow/` scratchpads) are not source the cite policy
+  // governs. MERGED with the hook's built-in [".workflow/**"] default; an
+  // omitted/empty value keeps just that default. `*` = within a path segment,
+  // `**` = across segments.
+  cite_nudge_ignore_globs: z6.array(z6.string()).optional(),
+  // v2.1 ④ conflict-detection (P4): bm25 content-similarity threshold (0..1)
+  // for the knowledge-conflict lint (`fabric doctor --lint-conflicts`). A
+  // same-(type,layer) pair whose normalized bm25 similarity reaches this floor
+  // is surfaced as a candidate (possible duplicate OR conflict). Conservative
+  // default 0.5 — raise to reduce noise, lower to catch looser pairs.
+  conflict_lint_similarity_threshold: z6.number().min(0).max(1).optional().default(0.5),
   // v2.0.0-rc.22 Scope A T3: sliding-window retention (in days) for the
   // event ledger rotation primitive (`rotateEventLedgerIfNeeded`). Lines
   // whose `ts` is older than `now - fabric_event_retention_days * 86_400_000`
@@ -634,12 +667,32 @@ var fabricConfigSchema = z6.object({
   // TRUNCATION_THRESHOLD=12 grouped-render kicks in. Mirrors the rc.7 T7 +
   // archive_max_* pattern of externalizing previously-hardcoded thresholds.
   hint_broad_top_k: z6.number().int().min(1).max(50).optional().default(8),
+  // v2.2 HK2-degrade (W2-T2): char budget for the rendered SessionStart broad-menu
+  // body — the final rung of the degradation ladder after the hint_broad_top_k
+  // count slice. Once the rendered entry/group lines exceed this, the tail
+  // collapses to a single "N more omitted" marker so a large corpus cannot blow
+  // the agent's working memory. Default 2000 (~one screenful); 0 disables the
+  // budget. Read by knowledge-hint-broad.cjs via readConfigNumber. Range 0..20000.
+  hint_broad_budget_chars: z6.number().int().min(0).max(2e4).optional().default(2e3),
   // v2.0.0-rc.37 NEW-16: durable per-signal dismiss for the fabric-hint Stop
   // hook nudges. Any signal type listed here is suppressed at emit time across
   // all sessions (the session-scoped sibling lives in a .fabric/.cache sidecar
   // written on request). Mirrors the cite_evict_interval=0 opt-out convention —
   // a knob for an existing surface, not a new feature. Unknown types ignored.
   hint_dismiss_signals: z6.array(z6.enum(["archive", "review", "import", "maintenance"])).optional(),
+  // v2.1 ADJ-NEWN-4: user-override escape hatches for the two strong behavioral
+  // policies (cite-before-edit + self-archive). The strong policies can make an
+  // agent feel like a "stubborn parrot" (D2 user-in-control red line); these
+  // flags let a user durably turn either off via fabric-config.json (or the
+  // `fabric config` panel) without editing bootstrap/AGENTS.md. Default true
+  // preserves rc.x behavior (policies ON); set false to opt a project out.
+  // The bootstrap behavior layer references these so the AGENTS.md rules degrade
+  // from "MUST" to "optional" when disabled — a config knob for an existing
+  // surface, mirroring the cite_evict_interval=0 / hint_dismiss_signals opt-out
+  // convention, NOT a new feature. Wave3 J32 will quantify the friction these
+  // relieve; until then they ship as inert-safe opt-outs.
+  cite_policy_enabled: z6.boolean().optional().default(true),
+  self_archive_policy_enabled: z6.boolean().optional().default(true),
   // v2.0.0-rc.33 W2-1 (P0-9): TopK upper bound for the narrow PreToolUse hint
   // emitted by knowledge-hint-narrow.cjs. After filtering to entries whose
   // `relevance_scope === "narrow"` (rc.27 TASK-005 audit §2.5 fix), the hook
@@ -674,13 +727,25 @@ var fabricConfigSchema = z6.object({
   // 0..168 (one week).
   hint_narrow_cooldown_hours: z6.number().int().min(0).max(168).optional().default(0),
   // v2.0.0-rc.33 W4-B3 (T5 P2): per-maturity inactivity thresholds (days)
-  // driving orphan_demote. Hardcoded at stable=90/endorsed=30/draft=14 in
+  // driving orphan_demote. Hardcoded at proven=90/verified=30/draft=14 in
   // rc.32; chatty workspaces want them tighter, slow ones want them looser.
   // Each field optional; absent → defaults inside doctor.ts apply. Ranges
   // chosen so a typo can't accidentally disable the lint (min 1).
+  //
+  // v2.2 W3-T5 (F-MATURITY-ENDORSED): the canonical maturity enum is
+  // draft/verified/proven (KT-DEC-0005), but these threshold keys historically
+  // used the legacy stable/endorsed vocabulary — a config authored with the
+  // canonical names could never tune the proven/verified tiers. The canonical
+  // keys below are the preferred form; the legacy keys are retained for
+  // backward-compat (a config written before this fix keeps working). The
+  // loader maps stable→proven / endorsed→verified, canonical taking precedence.
+  orphan_demote_proven_days: z6.number().int().min(1).max(3650).optional(),
+  orphan_demote_verified_days: z6.number().int().min(1).max(3650).optional(),
+  orphan_demote_draft_days: z6.number().int().min(1).max(3650).optional(),
+  // Legacy aliases (deprecated; map to proven/verified). Kept so existing
+  // configs do not silently lose their tuning.
   orphan_demote_stable_days: z6.number().int().min(1).max(3650).optional(),
   orphan_demote_endorsed_days: z6.number().int().min(1).max(3650).optional(),
-  orphan_demote_draft_days: z6.number().int().min(1).max(3650).optional(),
   // v2.0.0-rc.33 W4-A3 (T4 P2): per-entry summary truncation length used by
   // knowledge-hint-{broad,narrow}.cjs. Hard-coded at 80 chars in rc.32 — too
   // short for entries with parameterized summaries (e.g. "Use bcrypt with
@@ -713,7 +778,49 @@ var fabricConfigSchema = z6.object({
   // so the server-side per-field reader can validate without re-running the
   // whole fabricConfigSchema on every plan_context call — that lets a corrupt
   // unrelated field stay isolated from the hot read path.
-  selection_token_ttl_ms: selectionTokenTtlMsSchema.optional()
+  selection_token_ttl_ms: selectionTokenTtlMsSchema.optional(),
+  // v2.2 A-INFRA-3 (W1-T3-TOPK): bound on `fab_plan_context` candidate count,
+  // applied after BM25 ranking. Absent → library default (24). See
+  // planContextTopKSchema for the range/calibration rationale.
+  plan_context_top_k: planContextTopKSchema.optional(),
+  // v2.2 C5-budget (W2-T3): layered retrieval budget profile. A single coherent
+  // strategy across the injection + MCP layers — `balanced` (default) reproduces
+  // the historical per-knob defaults exactly, `conservative` / `generous` scale
+  // the whole truncation chain (top_k + payload bytes + injection chars) down /
+  // up together. Per-field knobs (plan_context_top_k, mcpPayloadLimits.*,
+  // hint_broad_budget_chars) still override the profile when set. See
+  // retrieval-budget.ts (resolveRetrievalBudget) for the resolution order.
+  retrieval_budget_profile: z6.enum(["conservative", "balanced", "generous"]).optional(),
+  // v2.2 C2-vector (W2-T7): OPTIONAL dense-embedding semantic retrieval, layered
+  // as a recall supplement after BM25. Default OFF (`--no-embed` is the baseline);
+  // requires the operator to install the optional `fastembed` package — absent →
+  // text-only fallback. Never grows the default install footprint.
+  embed_enabled: z6.boolean().optional().default(false),
+  // Weight applied to the 0..1 cosine similarity before it joins the additive
+  // score. Capped at 49 — strictly BELOW BM25_WEIGHT (50) — so a perfect vector
+  // match (weight × 1) can never outscore a single strong BM25 term match. This
+  // ENFORCES the "vectors supplement, never override lexical relevance"
+  // invariant in the schema rather than leaving it to a comment (W2-REVIEW codex
+  // MED-4). Range 0..49; default 30.
+  embed_weight: z6.number().int().min(0).max(49).optional().default(30),
+  // v2.1 ③ vector-chinese-model (P3): which fastembed model to load. The prior
+  // code pinned fastembed's English default (bge-small-en-v1.5) — wrong for the
+  // Chinese-heavy zh-CN-hybrid KB. Values are the fastembed@2.x EmbeddingModel
+  // enum strings. Default `fast-bge-small-zh-v1.5` (BGESmallZH): light, fast,
+  // Chinese-capable (bm25 already covers English/code tokens; the vector term
+  // supplements Chinese semantics). `fast-multilingual-e5-large` (MLE5Large) is
+  // available for full multilingual recall at a ~1GB download + slower CPU cost.
+  // (V1 research: fastembed@2.1.0 has NO multilingual-e5-SMALL — the originally
+  // planned pin — so bge-small-zh is the light Chinese choice.)
+  embed_model: z6.enum([
+    "fast-bge-small-zh-v1.5",
+    "fast-multilingual-e5-large",
+    "fast-bge-small-en-v1.5",
+    "fast-bge-small-en",
+    "fast-bge-base-en-v1.5",
+    "fast-bge-base-en",
+    "fast-all-MiniLM-L6-v2"
+  ]).optional().default("fast-bge-small-zh-v1.5")
 });
 
 // src/schemas/fabric-config-introspect.ts
@@ -1226,9 +1333,23 @@ function hasScriptExtension(name) {
   const dot = name.lastIndexOf(".");
   return dot !== -1 && SCRIPT_EXTENSIONS.has(name.slice(dot).toLowerCase());
 }
-function findStoreExecutableViolations(absDir) {
+var STORE_SCAN_MAX_DEPTH = 32;
+var STORE_SCAN_MAX_ENTRIES = 1e5;
+function findStoreExecutableViolations(absDir, options = {}) {
+  const maxDepth = options.maxDepth ?? STORE_SCAN_MAX_DEPTH;
+  const maxEntries = options.maxEntries ?? STORE_SCAN_MAX_ENTRIES;
   const violations = [];
-  const walk = (dir, rel) => {
+  let entriesScanned = 0;
+  let bounded = false;
+  const walk = (dir, rel, depth) => {
+    if (bounded) {
+      return;
+    }
+    if (depth > maxDepth) {
+      violations.push(`<scan-bounded: depth > ${maxDepth} at ${rel === "" ? "." : rel}>`);
+      bounded = true;
+      return;
+    }
     let entries;
     try {
       entries = readdirSync(dir);
@@ -1236,9 +1357,18 @@ function findStoreExecutableViolations(absDir) {
       return;
     }
     for (const entry of entries) {
+      if (bounded) {
+        return;
+      }
       if (rel === "" && entry === ".git") {
         continue;
       }
+      entriesScanned += 1;
+      if (entriesScanned > maxEntries) {
+        violations.push(`<scan-bounded: entries > ${maxEntries}>`);
+        bounded = true;
+        return;
+      }
       const abs = join(dir, entry);
       const relPath = rel === "" ? entry : `${rel}/${entry}`;
       let stat;
@@ -1248,7 +1378,7 @@ function findStoreExecutableViolations(absDir) {
         continue;
       }
       if (stat.isDirectory()) {
-        walk(abs, relPath);
+        walk(abs, relPath, depth + 1);
         continue;
       }
       if ((stat.mode & 73) !== 0 || hasScriptExtension(entry)) {
@@ -1256,7 +1386,7 @@ function findStoreExecutableViolations(absDir) {
       }
     }
   };
-  walk(absDir, "");
+  walk(absDir, "", 0);
   return violations;
 }
 
@@ -1427,6 +1557,76 @@ function aggregatePendingAcrossStores(stores) {
   );
 }
 
+// src/store/global-config-io.ts
+import { existsSync as existsSync3, mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
+import { homedir } from "os";
+import { join as join3 } from "path";
+function resolveGlobalRoot() {
+  return join3(process.env.FABRIC_HOME ?? homedir(), ".fabric");
+}
+function globalConfigPath(globalRoot = resolveGlobalRoot()) {
+  return join3(globalRoot, "fabric-global.json");
+}
+function loadGlobalConfig(globalRoot = resolveGlobalRoot()) {
+  const path = globalConfigPath(globalRoot);
+  if (!existsSync3(path)) {
+    return null;
+  }
+  return globalConfigSchema.parse(JSON.parse(readFileSync2(path, "utf8")));
+}
+function saveGlobalConfig(config, globalRoot = resolveGlobalRoot()) {
+  const validated = globalConfigSchema.parse(config);
+  mkdirSync2(globalRoot, { recursive: true });
+  writeFileSync2(globalConfigPath(globalRoot), `${JSON.stringify(validated, null, 2)}
+`, "utf8");
+}
+
+// src/store/project-config-io.ts
+import { existsSync as existsSync4, mkdirSync as mkdirSync3, readFileSync as readFileSync3, writeFileSync as writeFileSync3 } from "fs";
+import { join as join4 } from "path";
+function projectConfigPath(projectRoot) {
+  return join4(projectRoot, ".fabric", "fabric-config.json");
+}
+function loadProjectConfig(projectRoot) {
+  const path = projectConfigPath(projectRoot);
+  if (!existsSync4(path)) {
+    return null;
+  }
+  return fabricConfigSchema.parse(JSON.parse(readFileSync3(path, "utf8")));
+}
+function saveProjectConfig(config, projectRoot) {
+  const validated = fabricConfigSchema.parse(config);
+  mkdirSync3(join4(projectRoot, ".fabric"), { recursive: true });
+  writeFileSync3(projectConfigPath(projectRoot), `${JSON.stringify(validated, null, 2)}
+`, "utf8");
+}
+
+// src/store/resolve-input.ts
+function buildStoreResolveInput(projectRoot, globalRoot = resolveGlobalRoot()) {
+  const global = loadGlobalConfig(globalRoot);
+  if (global === null) {
+    return null;
+  }
+  const project = loadProjectConfig(projectRoot);
+  return {
+    uid: global.uid,
+    mountedStores: global.stores.map((s) => ({
+      store_uuid: s.store_uuid,
+      alias: s.alias,
+      ...s.remote === void 0 ? {} : { remote: s.remote },
+      writable: s.writable ?? true,
+      personal: s.personal ?? false
+    })),
+    requiredStores: (project?.required_stores ?? []).map(
+      (r) => ({
+        id: r.id,
+        ...r.suggested_remote === void 0 ? {} : { suggested_remote: r.suggested_remote }
+      })
+    ),
+    ...project?.active_write_store === void 0 ? {} : { activeWriteAlias: project.active_write_store }
+  };
+}
+
 // src/store/secret-scan.ts
 var SECRET_RULES = [
   { rule: "aws-access-key-id", re: /\bAKIA[0-9A-Z]{16}\b/ },
@@ -1463,6 +1663,51 @@ function redactSecrets(content) {
   }
   return out;
 }
+function scrubRemoteUrl(remote) {
+  const httpStripped = remote.replace(/^(https?:\/\/)[^/@]+@/i, "$1");
+  if (httpStripped !== remote) {
+    return httpStripped;
+  }
+  return remote.replace(
+    /^([a-zA-Z][a-zA-Z0-9+.-]*:\/\/)[^/@]*:[^/@]*@/,
+    "$1"
+  );
+}
+
+// src/scanner/scan-recommendations.ts
+function buildScanRecommendations(input, t) {
+  const recs = [];
+  if (input.hasExistingFabric === false) {
+    recs.push(t("scan.rec.install"));
+  }
+  if (input.readmeOk === false) {
+    recs.push(t("scan.rec.readme"));
+  }
+  if (input.hasContributing === false) {
+    recs.push(t("scan.rec.contributing"));
+  }
+  switch (input.frameworkKind) {
+    case "cocos-creator":
+      recs.push(t("scan.rec.cocos.lifecycle"));
+      recs.push(t("scan.rec.cocos.human-protect"));
+      if (input.hasMeta === true) {
+        recs.push(t("scan.rec.cocos.meta-lock"));
+      }
+      break;
+    case "next":
+      recs.push(t("scan.rec.next"));
+      break;
+    case "vite":
+      recs.push(t("scan.rec.vite"));
+      break;
+    case "unknown":
+      recs.push(t("scan.rec.unknown"));
+      break;
+    default:
+      recs.push(t("scan.rec.generic", { kind: input.frameworkKind }));
+  }
+  return recs;
+}
 
 // src/store/cross-store-lint.ts
 function lintCrossStoreReferences(input) {
@@ -1602,10 +1847,24 @@ var resolvedBindingsSnapshotSchema = z14.object({
 }).strict();
 
 // src/store/bindings.ts
-import { existsSync as existsSync3, mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
-import { join as join3 } from "path";
+import { existsSync as existsSync5, mkdirSync as mkdirSync4, readFileSync as readFileSync4, writeFileSync as writeFileSync4 } from "fs";
+import { join as join5, resolve, sep } from "path";
+var SAFE_PROJECT_ID = /^[A-Za-z0-9._-]+$/;
+function assertSafeProjectId(projectId) {
+  if (!SAFE_PROJECT_ID.test(projectId) || projectId.includes("..")) {
+    throw new Error(
+      `bindingsSnapshotPath: refusing unsafe project_id ${JSON.stringify(projectId)} (must match ${SAFE_PROJECT_ID} and contain no "..")`
+    );
+  }
+}
 function bindingsSnapshotPath(globalRoot, projectId) {
-  return join3(globalRoot, GLOBAL_STATE_DIR, GLOBAL_BINDINGS_DIR, `${projectId}_resolved.json`);
+  assertSafeProjectId(projectId);
+  const bindingsDir = resolve(join5(globalRoot, GLOBAL_STATE_DIR, GLOBAL_BINDINGS_DIR));
+  const path = resolve(join5(bindingsDir, `${projectId}_resolved.json`));
+  if (path !== bindingsDir && !path.startsWith(bindingsDir + sep)) {
+    throw new Error(`bindingsSnapshotPath: resolved path escapes bindings dir for ${JSON.stringify(projectId)}`);
+  }
+  return path;
 }
 function writeBindingsSnapshot(options) {
   const resolver = createStoreResolver();
@@ -1619,18 +1878,18 @@ function writeBindingsSnapshot(options) {
     write_target: target
   });
   const path = bindingsSnapshotPath(options.globalRoot, options.projectId);
-  mkdirSync2(join3(path, ".."), { recursive: true });
-  writeFileSync2(path, `${JSON.stringify(snapshot, null, 2)}
+  mkdirSync4(join5(path, ".."), { recursive: true });
+  writeFileSync4(path, `${JSON.stringify(snapshot, null, 2)}
 `, "utf8");
   return snapshot;
 }
 function readBindingsSnapshot(globalRoot, projectId) {
   const path = bindingsSnapshotPath(globalRoot, projectId);
-  if (!existsSync3(path)) {
+  if (!existsSync5(path)) {
     return null;
   }
   try {
-    const parsed = resolvedBindingsSnapshotSchema.safeParse(JSON.parse(readFileSync2(path, "utf8")));
+    const parsed = resolvedBindingsSnapshotSchema.safeParse(JSON.parse(readFileSync4(path, "utf8")));
     return parsed.success ? parsed.data : null;
   } catch {
     return null;
@@ -1650,6 +1909,8 @@ function addMountedStore(config, store) {
       `alias '${store.alias}' already mounts store ${aliasClash.store_uuid}; choose another alias`
     );
   }
+  const sanitized = store.remote === void 0 ? store : { ...store, remote: scrubRemoteUrl(store.remote) };
+  store = sanitized;
   const existing = config.stores.find((s) => s.store_uuid === store.store_uuid);
   const stores = existing === void 0 ? [...config.stores, store] : config.stores.map((s) => s.store_uuid === store.store_uuid ? store : s);
   return { ...config, stores };
@@ -1665,7 +1926,8 @@ function detachMountedStore(config, alias) {
   };
 }
 function bindRequiredStore(required, entry) {
-  return required.some((r) => r.id === entry.id) ? required.map((r) => r.id === entry.id ? entry : r) : [...required, entry];
+  const safeEntry = entry.suggested_remote === void 0 ? entry : { ...entry, suggested_remote: scrubRemoteUrl(entry.suggested_remote) };
+  return required.some((r) => r.id === safeEntry.id) ? required.map((r) => r.id === safeEntry.id ? safeEntry : r) : [...required, safeEntry];
 }
 function explainStore(config, alias) {
   const store = findMountedStore(config, alias);
@@ -2318,6 +2580,15 @@ var assistantTurnObservedEventSchema = z18.object({
       skip_reason: z18.string().nullable()
     })
   ).default([]),
+  // lifecycle-refactor W3-T4 (§2 store 轴 / store-qualified 观测): per-cite store
+  // qualifier, index-aligned with cite_ids. Mirrors the cite-line-parser's
+  // `cite_stores` output (`<alias-or-uuid>:<id>` → the qualifier; a bare id →
+  // null). Persists the store provenance the parser already extracts so
+  // doctor --cite-coverage can break compliance down per store WITHOUT joining
+  // against the store registry. Additive `.optional()` (NOT `.default([])`) so
+  // existing inline event constructors stay valid without supplying it — pre-W3-T4
+  // events parse with the field absent and bucket under the project-local default.
+  cite_stores: z18.array(z18.string().nullable()).optional(),
   client: z18.enum(["cc", "codex", "cursor"]).optional(),
   turn_id: z18.string(),
   envelope_index: z18.number().int().nonnegative().optional(),
@@ -2372,6 +2643,117 @@ var sessionArchiveAttemptedEventSchema = z18.object({
   candidates_proposed: z18.number().int().nonnegative().default(0),
   knowledge_proposed_ids: z18.array(z18.string()).default([])
 });
+var hookSurfaceEmittedEventSchema = z18.object({
+  ...eventLedgerEnvelopeSchema,
+  event_type: z18.literal("hook_surface_emitted"),
+  hook_name: z18.string(),
+  client: z18.enum(["cc", "codex", "cursor"]),
+  target_channel: z18.string(),
+  rendered_ids: z18.array(z18.string()),
+  delivery_status: z18.enum(["delivered", "suppressed", "error"]),
+  suppression_reason: z18.string().optional()
+});
+var hookSignalEmittedEventSchema = z18.object({
+  ...eventLedgerEnvelopeSchema,
+  event_type: z18.literal("hook_signal_emitted"),
+  signal_type: z18.enum(["archive", "review", "maintenance", "other"]),
+  threshold: z18.number(),
+  actual_value: z18.number(),
+  fired: z18.boolean()
+});
+var mcpStdioTraceEventSchema = z18.object({
+  ...eventLedgerEnvelopeSchema,
+  event_type: z18.literal("mcp_stdio_trace"),
+  tool_name: z18.string(),
+  request_id: z18.string(),
+  duration_ms: z18.number().nonnegative(),
+  status: z18.enum(["ok", "error"]),
+  payload_bytes_in: z18.number().int().nonnegative(),
+  payload_bytes_out: z18.number().int().nonnegative(),
+  error_code: z18.string().optional()
+});
+var payloadGuardObservedEventSchema = z18.object({
+  ...eventLedgerEnvelopeSchema,
+  event_type: z18.literal("payload_guard_observed"),
+  tool_name: z18.string(),
+  path_count: z18.number().int().nonnegative(),
+  tokens_estimated: z18.number().int().nonnegative(),
+  truncated: z18.boolean(),
+  cap: z18.number().int().positive()
+});
+var skillInvocationStartedEventSchema = z18.object({
+  ...eventLedgerEnvelopeSchema,
+  event_type: z18.literal("skill_invocation_started"),
+  skill_name: z18.string(),
+  trigger_source: z18.enum(["user", "auto_invoke", "ai_self_trigger", "chained"]),
+  entry_point: z18.string()
+});
+var skillInvocationCompletedEventSchema = z18.object({
+  ...eventLedgerEnvelopeSchema,
+  event_type: z18.literal("skill_invocation_completed"),
+  skill_name: z18.string(),
+  trigger_source: z18.enum(["user", "auto_invoke", "ai_self_trigger", "chained"]),
+  entry_point: z18.string(),
+  outcome: z18.enum(["completed", "aborted", "error", "no_op"]),
+  elapsed_ms: z18.number().nonnegative().optional()
+});
+var skillPhaseTransitionEventSchema = z18.object({
+  ...eventLedgerEnvelopeSchema,
+  event_type: z18.literal("skill_phase_transition"),
+  skill_name: z18.string(),
+  phase: z18.string(),
+  status: z18.enum(["entered", "completed", "skipped", "failed"]),
+  checkpoint: z18.string().optional(),
+  elapsed_ms: z18.number().nonnegative().optional()
+});
+var skillTriggerCandidateEventSchema = z18.object({
+  ...eventLedgerEnvelopeSchema,
+  event_type: z18.literal("skill_trigger_candidate"),
+  skill_name: z18.string(),
+  trigger_source: z18.enum(["user", "auto_invoke", "ai_self_trigger", "chained"]),
+  signal: z18.string(),
+  invoked: z18.boolean()
+});
+var llmJudgeRunEventSchema = z18.object({
+  ...eventLedgerEnvelopeSchema,
+  event_type: z18.literal("llm_judge_run"),
+  prompt: z18.string(),
+  version: z18.string(),
+  model: z18.string(),
+  input_trace_id: z18.string(),
+  score: z18.number(),
+  rationale: z18.string()
+});
+var clientCapabilitySnapshotEventSchema = z18.object({
+  ...eventLedgerEnvelopeSchema,
+  event_type: z18.literal("client_capability_snapshot"),
+  client: z18.enum(["cc", "codex", "cursor"]),
+  capabilities: z18.array(z18.string()),
+  version: z18.string()
+});
+var sessionEndedEventSchema = z18.object({
+  ...eventLedgerEnvelopeSchema,
+  event_type: z18.literal("session_ended")
+});
+var fileMutatedEventSchema = z18.object({
+  ...eventLedgerEnvelopeSchema,
+  event_type: z18.literal("file_mutated"),
+  path: z18.string(),
+  tool_call_id: z18.string(),
+  tool_name: z18.string().optional(),
+  source_event_id: z18.string().optional(),
+  store_id: z18.string().optional()
+});
+var precompactObservedEventSchema = z18.object({
+  ...eventLedgerEnvelopeSchema,
+  event_type: z18.literal("precompact_observed")
+});
+var graphEdgeCandidateRequestedEventSchema = z18.object({
+  ...eventLedgerEnvelopeSchema,
+  event_type: z18.literal("graph_edge_candidate_requested"),
+  stable_id: z18.string(),
+  store: z18.string().optional()
+});
 var eventLedgerEventSchema = z18.discriminatedUnion("event_type", [
   knowledgeContextPlannedEventSchema,
   knowledgeSelectionEventSchema,
@@ -2453,8 +2835,88 @@ var eventLedgerEventSchema = z18.discriminatedUnion("event_type", [
   // fabric-archive skill at the end of every invocation. Drives Phase 0.0
   // cross-session digest, outcome-based rescan filter (skips user_dismissed),
   // covered_through_ts watermark, and `fabric doctor --archive-history`.
-  sessionArchiveAttemptedEventSchema
+  sessionArchiveAttemptedEventSchema,
+  // v2.1 GATE-INSTR (NEW-N-3): 9 interaction-axis instrumentation events.
+  hookSurfaceEmittedEventSchema,
+  hookSignalEmittedEventSchema,
+  mcpStdioTraceEventSchema,
+  payloadGuardObservedEventSchema,
+  skillInvocationStartedEventSchema,
+  skillInvocationCompletedEventSchema,
+  skillPhaseTransitionEventSchema,
+  skillTriggerCandidateEventSchema,
+  llmJudgeRunEventSchema,
+  clientCapabilitySnapshotEventSchema,
+  // lifecycle-refactor Wave 2 — dormant-hook activation markers.
+  sessionEndedEventSchema,
+  fileMutatedEventSchema,
+  precompactObservedEventSchema,
+  graphEdgeCandidateRequestedEventSchema
 ]);
+
+// src/text-tokenize.ts
+var CJK_CLASS = "\\u3400-\\u4dbf\\u4e00-\\u9fff\\uf900-\\ufaff\\u3040-\\u30ff\\uac00-\\ud7af";
+var RUN_RE = new RegExp(`[a-z0-9]+|[${CJK_CLASS}]+`, "gu");
+var CJK_FIRST_RE = new RegExp(`[${CJK_CLASS}]`, "u");
+function tokenize(text) {
+  if (text.length === 0) {
+    return [];
+  }
+  const tokens = [];
+  const lowered = text.toLowerCase();
+  RUN_RE.lastIndex = 0;
+  let match;
+  while ((match = RUN_RE.exec(lowered)) !== null) {
+    const run = match[0];
+    if (CJK_FIRST_RE.test(run[0])) {
+      if (run.length === 1) {
+        tokens.push(run);
+      } else {
+        for (let i = 0; i < run.length - 1; i += 1) {
+          tokens.push(run.slice(i, i + 2));
+        }
+      }
+    } else {
+      tokens.push(run);
+    }
+  }
+  return tokens;
+}
+
+// src/retrieval-budget.ts
+var PROFILES = {
+  conservative: {
+    topK: 12,
+    payloadWarnBytes: 8192,
+    payloadHardBytes: 32768,
+    injectionChars: 1e3
+  },
+  balanced: {
+    topK: 24,
+    payloadWarnBytes: 16384,
+    payloadHardBytes: 65536,
+    injectionChars: 2e3
+  },
+  generous: {
+    topK: 48,
+    payloadWarnBytes: 32768,
+    payloadHardBytes: 131072,
+    injectionChars: 4e3
+  }
+};
+var DEFAULT_RETRIEVAL_BUDGET_PROFILE = "balanced";
+function resolveRetrievalBudget(overrides) {
+  const base = PROFILES[overrides?.profile ?? DEFAULT_RETRIEVAL_BUDGET_PROFILE];
+  return {
+    topK: overrides?.topK ?? base.topK,
+    payloadWarnBytes: overrides?.payloadWarnBytes ?? base.payloadWarnBytes,
+    payloadHardBytes: overrides?.payloadHardBytes ?? base.payloadHardBytes,
+    injectionChars: overrides?.injectionChars ?? base.injectionChars
+  };
+}
+function retrievalBudgetProfile(profile) {
+  return PROFILES[profile];
+}
 export {
   AGENTS_META_IDENTITY_SOURCES,
   AGENTS_META_LAYERS,
@@ -2464,6 +2926,7 @@ export {
   BOOTSTRAP_MARKER_BEGIN,
   BOOTSTRAP_MARKER_END,
   BOOTSTRAP_REGEX,
+  DEFAULT_RETRIEVAL_BUDGET_PROFILE,
   FabExtractKnowledgeInputSchema,
   FabExtractKnowledgeInputShape,
   FabExtractKnowledgeOutputSchema,
@@ -2528,6 +2991,8 @@ export {
   bootstrapMarkerMigratedEventSchema,
   buildDebugBundle,
   buildFailureTrace,
+  buildScanRecommendations,
+  buildStoreResolveInput,
   candidateFileEntrySchema,
   citeContractMetricsSchema,
   citeContractPolicyActivatedEventSchema,
@@ -2536,6 +3001,7 @@ export {
   citePolicyActivatedEventSchema,
   claudeHookPathMigratedEventSchema,
   claudeSkillPathMigratedEventSchema,
+  clientCapabilitySnapshotEventSchema,
   clientPathsSchema,
   codexSkillPathMigratedEventSchema,
   createProjectRootResolver,
@@ -2564,6 +3030,7 @@ export {
   fabricConfigSchema,
   fabricEventSchema,
   fabricLanguageSchema,
+  fileMutatedEventSchema,
   findMountedStore,
   findStoreExecutableViolations,
   forensicAssertionCoverageSchema,
@@ -2580,10 +3047,14 @@ export {
   formatKnowledgeId,
   getPanelFieldByKey,
   getPanelFields,
+  globalConfigPath,
   globalConfigSchema,
   globalRefSchema,
+  graphEdgeCandidateRequestedEventSchema,
   hasSecrets,
   historyStateQuerySchema,
+  hookSignalEmittedEventSchema,
+  hookSurfaceEmittedEventSchema,
   humanLedgerEntrySchema,
   humanLockApproveRequestSchema,
   humanLockEntrySchema,
@@ -2637,12 +3108,16 @@ export {
   ledgerSourceSchema,
   lintCrossStoreReferences,
   listStoreKnowledge,
+  llmJudgeRunEventSchema,
+  loadGlobalConfig,
+  loadProjectConfig,
   localKnowledgeIdSchema,
   lockApprovedEventSchema,
   lockDriftEventSchema,
   mcpConfigMigratedEventSchema,
   mcpEventLedgerEventSchema,
   mcpPayloadLimitsSchema,
+  mcpStdioTraceEventSchema,
   metaReconciledEventSchema,
   metaReconciledOnStartupEventSchema,
   metaUpdatedEventSchema,
@@ -2658,12 +3133,16 @@ export {
   parseCiteLine,
   parseGlobalRef,
   parseKnowledgeId,
+  payloadGuardObservedEventSchema,
   pendingAutoArchivedEventSchema,
   planContextAnnotations,
   planContextHintNarrowEntrySchema,
   planContextHintOutputSchema,
   planContextInputSchema,
   planContextOutputSchema,
+  planContextTopKSchema,
+  precompactObservedEventSchema,
+  projectConfigPath,
   projectRootGoldenCaseSchema,
   projectRootGoldenFileSchema,
   projectRootResolutionSchema,
@@ -2685,16 +3164,27 @@ export {
   requiredStoreEntrySchema,
   resolveCandidates,
   resolveFabricLocale,
+  resolveGlobalRoot,
+  resolveRetrievalBudget,
   resolveStoreQualifiedId,
   resolvedBindingsSnapshotSchema,
+  retrievalBudgetProfile,
   ruleDescriptionIndexItemSchema,
   ruleDescriptionSchema,
+  saveGlobalConfig,
+  saveProjectConfig,
   scanForSecrets,
   scopeCoordinateSchema,
   scopeRoot,
+  scrubRemoteUrl,
   selectionTokenTtlMsSchema,
   serveLockClearedEventSchema,
   sessionArchiveAttemptedEventSchema,
+  sessionEndedEventSchema,
+  skillInvocationCompletedEventSchema,
+  skillInvocationStartedEventSchema,
+  skillPhaseTransitionEventSchema,
+  skillTriggerCandidateEventSchema,
   storeAwareEntrySchema,
   storeCountersSchema,
   storeIdentitySchema,
@@ -2706,6 +3196,7 @@ export {
   storeResolverWarningSchema,
   storeUuidSchema,
   structuredWarningSchema,
+  tokenize,
   uidSchema,
   withDerivedAgentsMetaNodeDefaults,
   writeBindingsSnapshot,