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

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-7TZ2PMVH.js";
 import {
   FabExtractKnowledgeInputSchema,
   FabExtractKnowledgeInputShape,
@@ -64,8 +56,16 @@ import {
   recallInputSchema,
   recallOutputSchema,
   structuredWarningSchema
-} from "./chunk-WVPDH4BF.js";
-import "./chunk-LXNCAKJZ.js";
+} from "./chunk-JEXTOQVV.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-TX2XZ7AW.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",
@@ -634,12 +643,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
@@ -713,7 +742,31 @@ 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)
 });
 
 // src/schemas/fabric-config-introspect.ts
@@ -1226,9 +1279,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 +1303,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 +1324,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 +1332,7 @@ function findStoreExecutableViolations(absDir) {
       }
     }
   };
-  walk(absDir, "");
+  walk(absDir, "", 0);
   return violations;
 }
 
@@ -1463,6 +1539,47 @@ function redactSecrets(content) {
   }
   return out;
 }
+function scrubRemoteUrl(remote) {
+  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) {
@@ -1650,6 +1767,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 +1784,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);
@@ -2372,6 +2492,94 @@ 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 eventLedgerEventSchema = z18.discriminatedUnion("event_type", [
   knowledgeContextPlannedEventSchema,
   knowledgeSelectionEventSchema,
@@ -2453,8 +2661,83 @@ 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
 ]);
+
+// 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 +2747,7 @@ export {
   BOOTSTRAP_MARKER_BEGIN,
   BOOTSTRAP_MARKER_END,
   BOOTSTRAP_REGEX,
+  DEFAULT_RETRIEVAL_BUDGET_PROFILE,
   FabExtractKnowledgeInputSchema,
   FabExtractKnowledgeInputShape,
   FabExtractKnowledgeOutputSchema,
@@ -2528,6 +2812,7 @@ export {
   bootstrapMarkerMigratedEventSchema,
   buildDebugBundle,
   buildFailureTrace,
+  buildScanRecommendations,
   candidateFileEntrySchema,
   citeContractMetricsSchema,
   citeContractPolicyActivatedEventSchema,
@@ -2536,6 +2821,7 @@ export {
   citePolicyActivatedEventSchema,
   claudeHookPathMigratedEventSchema,
   claudeSkillPathMigratedEventSchema,
+  clientCapabilitySnapshotEventSchema,
   clientPathsSchema,
   codexSkillPathMigratedEventSchema,
   createProjectRootResolver,
@@ -2584,6 +2870,8 @@ export {
   globalRefSchema,
   hasSecrets,
   historyStateQuerySchema,
+  hookSignalEmittedEventSchema,
+  hookSurfaceEmittedEventSchema,
   humanLedgerEntrySchema,
   humanLockApproveRequestSchema,
   humanLockEntrySchema,
@@ -2637,12 +2925,14 @@ export {
   ledgerSourceSchema,
   lintCrossStoreReferences,
   listStoreKnowledge,
+  llmJudgeRunEventSchema,
   localKnowledgeIdSchema,
   lockApprovedEventSchema,
   lockDriftEventSchema,
   mcpConfigMigratedEventSchema,
   mcpEventLedgerEventSchema,
   mcpPayloadLimitsSchema,
+  mcpStdioTraceEventSchema,
   metaReconciledEventSchema,
   metaReconciledOnStartupEventSchema,
   metaUpdatedEventSchema,
@@ -2658,12 +2948,14 @@ export {
   parseCiteLine,
   parseGlobalRef,
   parseKnowledgeId,
+  payloadGuardObservedEventSchema,
   pendingAutoArchivedEventSchema,
   planContextAnnotations,
   planContextHintNarrowEntrySchema,
   planContextHintOutputSchema,
   planContextInputSchema,
   planContextOutputSchema,
+  planContextTopKSchema,
   projectRootGoldenCaseSchema,
   projectRootGoldenFileSchema,
   projectRootResolutionSchema,
@@ -2685,16 +2977,23 @@ export {
   requiredStoreEntrySchema,
   resolveCandidates,
   resolveFabricLocale,
+  resolveRetrievalBudget,
   resolveStoreQualifiedId,
   resolvedBindingsSnapshotSchema,
+  retrievalBudgetProfile,
   ruleDescriptionIndexItemSchema,
   ruleDescriptionSchema,
   scanForSecrets,
   scopeCoordinateSchema,
   scopeRoot,
+  scrubRemoteUrl,
   selectionTokenTtlMsSchema,
   serveLockClearedEventSchema,
   sessionArchiveAttemptedEventSchema,
+  skillInvocationCompletedEventSchema,
+  skillInvocationStartedEventSchema,
+  skillPhaseTransitionEventSchema,
+  skillTriggerCandidateEventSchema,
   storeAwareEntrySchema,
   storeCountersSchema,
   storeIdentitySchema,
@@ -2706,6 +3005,7 @@ export {
   storeResolverWarningSchema,
   storeUuidSchema,
   structuredWarningSchema,
+  tokenize,
   uidSchema,
   withDerivedAgentsMetaNodeDefaults,
   writeBindingsSnapshot,

package/dist/node/atomic-write.d.ts

@@ -6,6 +6,31 @@ interface AtomicWriteJsonOptions extends AtomicWriteOptions {
 }
 declare function atomicWriteText(path: string, content: string, opts?: AtomicWriteOptions): Promise<void>;
 declare function atomicWriteJson(path: string, value: unknown, opts?: AtomicWriteJsonOptions): Promise<void>;
+interface FileLockOptions {
+    /** A held lock older than this (ms, by lock-file mtime) is presumed stale —
+     * left by a crashed holder — and reclaimed. Default 10s. */
+    staleMs?: number;
+    /** Poll interval (ms) between acquire attempts while contended. Default 20ms. */
+    retryDelayMs?: number;
+    /** Give up acquiring after this long (ms) and throw. Default 10s. */
+    maxWaitMs?: number;
+}
+/**
+ * Run `fn` while holding a cross-process advisory lock at `lockPath`.
+ *
+ * Unlike the hook-side `appendLockedLine` (which DROPS on contention, fine for
+ * best-effort telemetry), this WAITS for the lock — the critical section it
+ * guards (e.g. a read-modify-write of a shared counter file) must not be
+ * skipped. The lock is a `wx` (O_CREAT|O_EXCL) lock file, so acquisition is
+ * atomic across processes; a crashed holder leaves the file behind, so any
+ * holder older than `staleMs` is reclaimed. The lock is always released in a
+ * `finally`, even if `fn` throws.
+ *
+ * Scope: cross-process AND in-process. Two concurrent callers on the same
+ * `lockPath` (same process or not) serialize, because both race the same
+ * O_EXCL create.
+ */
+declare function withFileLock<T>(lockPath: string, fn: () => Promise<T>, opts?: FileLockOptions): Promise<T>;
 interface LedgerWriteQueue {
     append(path: string, line: string): Promise<void>;
     /**
@@ -27,4 +52,4 @@ interface LedgerWriteQueue {
 }
 declare function createLedgerWriteQueue(): LedgerWriteQueue;
 
-export { type AtomicWriteJsonOptions, type AtomicWriteOptions, type LedgerWriteQueue, atomicWriteJson, atomicWriteText, createLedgerWriteQueue };
+export { type AtomicWriteJsonOptions, type AtomicWriteOptions, type FileLockOptions, type LedgerWriteQueue, atomicWriteJson, atomicWriteText, createLedgerWriteQueue, withFileLock };

package/dist/node/atomic-write.js

@@ -1,5 +1,6 @@
 // src/node/atomic-write.ts
-import { appendFile, open, rename, unlink, writeFile } from "fs/promises";
+import { appendFile, mkdir, open, rename, stat, unlink, writeFile } from "fs/promises";
+import { dirname } from "path";
 function makeTmpSuffix() {
   const rand = Math.floor(Math.random() * 65535).toString(16).padStart(4, "0");
   return `.${process.pid}.${Date.now()}.${rand}.tmp`;
@@ -32,6 +33,47 @@ async function atomicWriteJson(path, value, opts) {
   const content = JSON.stringify(value, null, indent) + "\n";
   await atomicWriteText(path, content, { fsync: opts?.fsync });
 }
+function isErrnoException(err) {
+  return err instanceof Error && typeof err.code === "string";
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function withFileLock(lockPath, fn, opts = {}) {
+  const staleMs = opts.staleMs ?? 1e4;
+  const retryDelayMs = opts.retryDelayMs ?? 20;
+  const maxWaitMs = opts.maxWaitMs ?? 1e4;
+  await mkdir(dirname(lockPath), { recursive: true });
+  const start = Date.now();
+  for (; ; ) {
+    let handle;
+    try {
+      handle = await open(lockPath, "wx");
+    } catch (err) {
+      if (!isErrnoException(err) || err.code !== "EEXIST") throw err;
+      try {
+        const st = await stat(lockPath);
+        if (Date.now() - st.mtimeMs > staleMs) {
+          await unlink(lockPath).catch(() => void 0);
+          continue;
+        }
+      } catch {
+        continue;
+      }
+      if (Date.now() - start > maxWaitMs) {
+        throw new Error(`withFileLock: timed out acquiring ${lockPath} after ${maxWaitMs}ms`);
+      }
+      await sleep(retryDelayMs);
+      continue;
+    }
+    try {
+      await handle.close();
+      return await fn();
+    } finally {
+      await unlink(lockPath).catch(() => void 0);
+    }
+  }
+}
 function createLedgerWriteQueue() {
   const chains = /* @__PURE__ */ new Map();
   async function doAppend(path, line) {
@@ -65,5 +107,6 @@ function createLedgerWriteQueue() {
 export {
   atomicWriteJson,
   atomicWriteText,
-  createLedgerWriteQueue
+  createLedgerWriteQueue,
+  withFileLock
 };

package/dist/node/mcp-payload-guard.d.ts

@@ -14,5 +14,36 @@ interface PayloadGuardResult {
 declare const PAYLOAD_LIMIT_DEFAULT_WARN_BYTES = 16384;
 declare const PAYLOAD_LIMIT_DEFAULT_HARD_BYTES = 65536;
 declare function enforcePayloadLimit(serializedPayload: string, opts?: PayloadGuardOptions): PayloadGuardResult;
+interface PayloadBudgetTrimResult<T> {
+    /** The retained head of `items` (the ranked tail was dropped to fit). */
+    items: T[];
+    /** How many trailing items were dropped to fit the hard budget. */
+    dropped: number;
+    /** Serialized byte size of the envelope built from the retained items. */
+    bytes: number;
+    /**
+     * True when even `minKeep` items still overflow the hard budget — the caller
+     * must surface this (a single oversized entry) rather than assume it fit.
+     */
+    overBudget: boolean;
+}
+/**
+ * v2.2 MC4-payload-budget (W1-T4): the byte-budget tail of the unified
+ * truncation chain (CJK → BM25 → top_k → payload). Rather than hard-throwing
+ * when a response overflows the hard limit, callers trim the LEAST-relevant
+ * items off the tail of an already-ranked list until the serialized envelope
+ * fits — turning a 413 crash into graceful degradation.
+ *
+ * `serialize` builds the FULL response envelope from a candidate slice (so the
+ * byte count includes warnings / metadata, not just the list). Trimming drops
+ * from the END, which is correct ONLY when the list is pre-ranked best-first
+ * (plan_context sorts by BM25 before calling this). `minKeep` (default 1)
+ * guarantees a non-empty result even under a pathological oversized head; in
+ * that case `overBudget` is returned true so the caller can warn instead of
+ * silently shipping an over-limit payload.
+ */
+declare function trimToPayloadBudget<T>(items: T[], serialize: (items: T[]) => string, opts?: PayloadGuardOptions & {
+    minKeep?: number;
+}): PayloadBudgetTrimResult<T>;
 
-export { PAYLOAD_LIMIT_DEFAULT_HARD_BYTES, PAYLOAD_LIMIT_DEFAULT_WARN_BYTES, type PayloadGuardOptions, type PayloadGuardResult, enforcePayloadLimit };
+export { PAYLOAD_LIMIT_DEFAULT_HARD_BYTES, PAYLOAD_LIMIT_DEFAULT_WARN_BYTES, type PayloadBudgetTrimResult, type PayloadGuardOptions, type PayloadGuardResult, enforcePayloadLimit, trimToPayloadBudget };