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

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,7 @@
 // src/node/atomic-write.ts
-import { appendFile, open, rename, unlink, writeFile } from "fs/promises";
+import { appendFile, mkdir, open, readFile, rename, stat, unlink, writeFile } from "fs/promises";
+import { dirname } from "path";
+import { randomUUID } from "crypto";
 function makeTmpSuffix() {
   const rand = Math.floor(Math.random() * 65535).toString(16).padStart(4, "0");
   return `.${process.pid}.${Date.now()}.${rand}.tmp`;
@@ -32,6 +34,61 @@ 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 token = `${process.pid}.${randomUUID()}`;
+  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) {
+          const staleToken = await readFile(lockPath, "utf8").catch(() => null);
+          if (staleToken !== null) {
+            await unlinkIfToken(lockPath, staleToken);
+          }
+          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.writeFile(token, "utf8");
+      await handle.close();
+      return await fn();
+    } finally {
+      await unlinkIfToken(lockPath, token);
+    }
+  }
+}
+async function unlinkIfToken(lockPath, expected) {
+  try {
+    const current = await readFile(lockPath, "utf8");
+    if (current === expected) {
+      await unlink(lockPath).catch(() => void 0);
+    }
+  } catch {
+  }
+}
 function createLedgerWriteQueue() {
   const chains = /* @__PURE__ */ new Map();
   async function doAppend(path, line) {
@@ -65,5 +122,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 };

package/dist/node/mcp-payload-guard.js

@@ -1,6 +1,6 @@
 import {
   MCPError
-} from "../chunk-3SZRB42B.js";
+} from "../chunk-VW5QGPIN.js";
 
 // src/node/mcp-payload-guard.ts
 var McpPayloadTooLargeError = class extends MCPError {
@@ -37,8 +37,22 @@ function enforcePayloadLimit(serializedPayload, opts) {
   }
   return { bytes };
 }
+function trimToPayloadBudget(items, serialize, opts) {
+  const hardAt = opts?.hardBytes ?? DEFAULT_HARD;
+  const minKeep = Math.max(0, opts?.minKeep ?? 1);
+  let kept = items;
+  let bytes = Buffer.byteLength(serialize(kept), "utf8");
+  let dropped = 0;
+  while (bytes > hardAt && kept.length > minKeep) {
+    kept = kept.slice(0, -1);
+    dropped += 1;
+    bytes = Buffer.byteLength(serialize(kept), "utf8");
+  }
+  return { items: kept, dropped, bytes, overBudget: bytes > hardAt };
+}
 export {
   PAYLOAD_LIMIT_DEFAULT_HARD_BYTES,
   PAYLOAD_LIMIT_DEFAULT_WARN_BYTES,
-  enforcePayloadLimit
+  enforcePayloadLimit,
+  trimToPayloadBudget
 };