@remnic/core 9.3.678 → 9.3.680

package/dist/schemas.d.ts

@@ -275,12 +275,12 @@ declare const EntityMentionSchema: z.ZodObject<{
         title: z.ZodString;
         facts: z.ZodArray<z.ZodString, "many">;
     }, "strip", z.ZodTypeAny, {
-        key: string;
         title: string;
+        key: string;
         facts: string[];
     }, {
-        key: string;
         title: string;
+        key: string;
         facts: string[];
     }>, "many">>>;
 }, "strip", z.ZodTypeAny, {
@@ -288,8 +288,8 @@ declare const EntityMentionSchema: z.ZodObject<{
     name: string;
     facts: string[];
     structuredSections?: {
-        key: string;
         title: string;
+        key: string;
         facts: string[];
     }[] | null | undefined;
     promptedByQuestion?: string | null | undefined;
@@ -298,8 +298,8 @@ declare const EntityMentionSchema: z.ZodObject<{
     name: string;
     facts: string[];
     structuredSections?: {
-        key: string;
         title: string;
+        key: string;
         facts: string[];
     }[] | null | undefined;
     promptedByQuestion?: string | null | undefined;
@@ -584,12 +584,12 @@ declare const ProactiveExtractionResultSchema: z.ZodObject<{
             title: z.ZodString;
             facts: z.ZodArray<z.ZodString, "many">;
         }, "strip", z.ZodTypeAny, {
-            key: string;
             title: string;
+            key: string;
             facts: string[];
         }, {
-            key: string;
             title: string;
+            key: string;
             facts: string[];
         }>, "many">>>;
     }, "strip", z.ZodTypeAny, {
@@ -597,8 +597,8 @@ declare const ProactiveExtractionResultSchema: z.ZodObject<{
         name: string;
         facts: string[];
         structuredSections?: {
-            key: string;
             title: string;
+            key: string;
             facts: string[];
         }[] | null | undefined;
         promptedByQuestion?: string | null | undefined;
@@ -607,8 +607,8 @@ declare const ProactiveExtractionResultSchema: z.ZodObject<{
         name: string;
         facts: string[];
         structuredSections?: {
-            key: string;
             title: string;
+            key: string;
             facts: string[];
         }[] | null | undefined;
         promptedByQuestion?: string | null | undefined;
@@ -665,8 +665,8 @@ declare const ProactiveExtractionResultSchema: z.ZodObject<{
         name: string;
         facts: string[];
         structuredSections?: {
-            key: string;
             title: string;
+            key: string;
             facts: string[];
         }[] | null | undefined;
         promptedByQuestion?: string | null | undefined;
@@ -714,8 +714,8 @@ declare const ProactiveExtractionResultSchema: z.ZodObject<{
         name: string;
         facts: string[];
         structuredSections?: {
-            key: string;
             title: string;
+            key: string;
             facts: string[];
         }[] | null | undefined;
         promptedByQuestion?: string | null | undefined;
@@ -952,12 +952,12 @@ declare const ExtractionResultSchema: z.ZodObject<{
             title: z.ZodString;
             facts: z.ZodArray<z.ZodString, "many">;
         }, "strip", z.ZodTypeAny, {
-            key: string;
             title: string;
+            key: string;
             facts: string[];
         }, {
-            key: string;
             title: string;
+            key: string;
             facts: string[];
         }>, "many">>>;
     }, "strip", z.ZodTypeAny, {
@@ -965,8 +965,8 @@ declare const ExtractionResultSchema: z.ZodObject<{
         name: string;
         facts: string[];
         structuredSections?: {
-            key: string;
             title: string;
+            key: string;
             facts: string[];
         }[] | null | undefined;
         promptedByQuestion?: string | null | undefined;
@@ -975,8 +975,8 @@ declare const ExtractionResultSchema: z.ZodObject<{
         name: string;
         facts: string[];
         structuredSections?: {
-            key: string;
             title: string;
+            key: string;
             facts: string[];
         }[] | null | undefined;
         promptedByQuestion?: string | null | undefined;
@@ -1047,8 +1047,8 @@ declare const ExtractionResultSchema: z.ZodObject<{
         name: string;
         facts: string[];
         structuredSections?: {
-            key: string;
             title: string;
+            key: string;
             facts: string[];
         }[] | null | undefined;
         promptedByQuestion?: string | null | undefined;
@@ -1102,8 +1102,8 @@ declare const ExtractionResultSchema: z.ZodObject<{
         name: string;
         facts: string[];
         structuredSections?: {
-            key: string;
             title: string;
+            key: string;
             facts: string[];
         }[] | null | undefined;
         promptedByQuestion?: string | null | undefined;
@@ -1172,12 +1172,12 @@ declare const ConsolidationResultSchema: z.ZodObject<{
             title: z.ZodString;
             facts: z.ZodArray<z.ZodString, "many">;
         }, "strip", z.ZodTypeAny, {
-            key: string;
             title: string;
+            key: string;
             facts: string[];
         }, {
-            key: string;
             title: string;
+            key: string;
             facts: string[];
         }>, "many">>>;
     }, "strip", z.ZodTypeAny, {
@@ -1185,8 +1185,8 @@ declare const ConsolidationResultSchema: z.ZodObject<{
         name: string;
         facts: string[];
         structuredSections?: {
-            key: string;
             title: string;
+            key: string;
             facts: string[];
         }[] | null | undefined;
         promptedByQuestion?: string | null | undefined;
@@ -1195,8 +1195,8 @@ declare const ConsolidationResultSchema: z.ZodObject<{
         name: string;
         facts: string[];
         structuredSections?: {
-            key: string;
             title: string;
+            key: string;
             facts: string[];
         }[] | null | undefined;
         promptedByQuestion?: string | null | undefined;
@@ -1215,8 +1215,8 @@ declare const ConsolidationResultSchema: z.ZodObject<{
         name: string;
         facts: string[];
         structuredSections?: {
-            key: string;
             title: string;
+            key: string;
             facts: string[];
         }[] | null | undefined;
         promptedByQuestion?: string | null | undefined;
@@ -1235,8 +1235,8 @@ declare const ConsolidationResultSchema: z.ZodObject<{
         name: string;
         facts: string[];
         structuredSections?: {
-            key: string;
             title: string;
+            key: string;
             facts: string[];
         }[] | null | undefined;
         promptedByQuestion?: string | null | undefined;

package/dist/transfer/backup.js

@@ -1,8 +1,8 @@
 import {
   backupMemoryDir
-} from "../chunk-2NLLXCJG.js";
+} from "../chunk-BXLOS5AJ.js";
 import "../chunk-765K3SAT.js";
-import "../chunk-X7Y7WX73.js";
+import "../chunk-DQEMWVMT.js";
 import "../chunk-J4EB7DNW.js";
 import "../chunk-UI3NYK34.js";
 import "../chunk-GCGJW34D.js";

package/dist/transfer/capsule-export.js

@@ -1,9 +1,9 @@
 import {
   exportCapsule,
   isValidCapsuleSince
-} from "../chunk-KQAFEZQX.js";
+} from "../chunk-VDX2J7OX.js";
 import "../chunk-WEHSQBFR.js";
-import "../chunk-X7Y7WX73.js";
+import "../chunk-DQEMWVMT.js";
 import "../chunk-J4EB7DNW.js";
 import "../chunk-UI3NYK34.js";
 import "../chunk-GCGJW34D.js";

package/dist/transfer/capsule-import.js

@@ -1,9 +1,9 @@
 import {
   importCapsule
-} from "../chunk-ARV3AUOM.js";
+} from "../chunk-DL6H3D7S.js";
 import "../chunk-VF4XKTX3.js";
 import "../chunk-WEHSQBFR.js";
-import "../chunk-X7Y7WX73.js";
+import "../chunk-DQEMWVMT.js";
 import "../chunk-GCGJW34D.js";
 import "../chunk-BJMBJZ2Y.js";
 import "../chunk-UKJAGEXH.js";

package/dist/transfer/types.d.ts

@@ -313,34 +313,34 @@ declare const CapsuleBlockSchema: z.ZodObject<{
         peerProfiles: boolean;
     }>;
 }, "strip", z.ZodTypeAny, {
+    schemaVersion: string;
     includes: {
         procedural: boolean;
         taxonomy: boolean;
         identityAnchors: boolean;
         peerProfiles: boolean;
     };
-    schemaVersion: string;
     id: string;
     description: string;
     version: string;
+    parentCapsule: string | null;
     parent: {
         version: string;
         capsuleId: string;
         forkRoot: string;
     } | null;
-    parentCapsule: string | null;
     retrievalPolicy: {
         tierWeights: Record<string, number>;
         directAnswerEnabled: boolean;
     };
 }, {
+    schemaVersion: string;
     includes: {
         procedural: boolean;
         taxonomy: boolean;
         identityAnchors: boolean;
         peerProfiles: boolean;
     };
-    schemaVersion: string;
     id: string;
     description: string;
     version: string;
@@ -464,34 +464,34 @@ declare const ExportManifestV2Schema: z.ZodObject<{
             peerProfiles: boolean;
         }>;
     }, "strip", z.ZodTypeAny, {
+        schemaVersion: string;
         includes: {
             procedural: boolean;
             taxonomy: boolean;
             identityAnchors: boolean;
             peerProfiles: boolean;
         };
-        schemaVersion: string;
         id: string;
         description: string;
         version: string;
+        parentCapsule: string | null;
         parent: {
             version: string;
             capsuleId: string;
             forkRoot: string;
         } | null;
-        parentCapsule: string | null;
         retrievalPolicy: {
             tierWeights: Record<string, number>;
             directAnswerEnabled: boolean;
         };
     }, {
+        schemaVersion: string;
         includes: {
             procedural: boolean;
             taxonomy: boolean;
             identityAnchors: boolean;
             peerProfiles: boolean;
         };
-        schemaVersion: string;
         id: string;
         description: string;
         version: string;
@@ -518,22 +518,22 @@ declare const ExportManifestV2Schema: z.ZodObject<{
     pluginVersion: string;
     includesTranscripts: boolean;
     capsule: {
+        schemaVersion: string;
         includes: {
             procedural: boolean;
             taxonomy: boolean;
             identityAnchors: boolean;
             peerProfiles: boolean;
         };
-        schemaVersion: string;
         id: string;
         description: string;
         version: string;
+        parentCapsule: string | null;
         parent: {
             version: string;
             capsuleId: string;
             forkRoot: string;
         } | null;
-        parentCapsule: string | null;
         retrievalPolicy: {
             tierWeights: Record<string, number>;
             directAnswerEnabled: boolean;
@@ -551,13 +551,13 @@ declare const ExportManifestV2Schema: z.ZodObject<{
     pluginVersion: string;
     includesTranscripts: boolean;
     capsule: {
+        schemaVersion: string;
         includes: {
             procedural: boolean;
             taxonomy: boolean;
             identityAnchors: boolean;
             peerProfiles: boolean;
         };
-        schemaVersion: string;
         id: string;
         description: string;
         version: string;
@@ -683,34 +683,34 @@ declare const ExportBundleV2Schema: z.ZodObject<{
                 peerProfiles: boolean;
             }>;
         }, "strip", z.ZodTypeAny, {
+            schemaVersion: string;
             includes: {
                 procedural: boolean;
                 taxonomy: boolean;
                 identityAnchors: boolean;
                 peerProfiles: boolean;
             };
-            schemaVersion: string;
             id: string;
             description: string;
             version: string;
+            parentCapsule: string | null;
             parent: {
                 version: string;
                 capsuleId: string;
                 forkRoot: string;
             } | null;
-            parentCapsule: string | null;
             retrievalPolicy: {
                 tierWeights: Record<string, number>;
                 directAnswerEnabled: boolean;
             };
         }, {
+            schemaVersion: string;
             includes: {
                 procedural: boolean;
                 taxonomy: boolean;
                 identityAnchors: boolean;
                 peerProfiles: boolean;
             };
-            schemaVersion: string;
             id: string;
             description: string;
             version: string;
@@ -737,22 +737,22 @@ declare const ExportBundleV2Schema: z.ZodObject<{
         pluginVersion: string;
         includesTranscripts: boolean;
         capsule: {
+            schemaVersion: string;
             includes: {
                 procedural: boolean;
                 taxonomy: boolean;
                 identityAnchors: boolean;
                 peerProfiles: boolean;
             };
-            schemaVersion: string;
             id: string;
             description: string;
             version: string;
+            parentCapsule: string | null;
             parent: {
                 version: string;
                 capsuleId: string;
                 forkRoot: string;
             } | null;
-            parentCapsule: string | null;
             retrievalPolicy: {
                 tierWeights: Record<string, number>;
                 directAnswerEnabled: boolean;
@@ -770,13 +770,13 @@ declare const ExportBundleV2Schema: z.ZodObject<{
         pluginVersion: string;
         includesTranscripts: boolean;
         capsule: {
+            schemaVersion: string;
             includes: {
                 procedural: boolean;
                 taxonomy: boolean;
                 identityAnchors: boolean;
                 peerProfiles: boolean;
             };
-            schemaVersion: string;
             id: string;
             description: string;
             version: string;
@@ -815,22 +815,22 @@ declare const ExportBundleV2Schema: z.ZodObject<{
         pluginVersion: string;
         includesTranscripts: boolean;
         capsule: {
+            schemaVersion: string;
             includes: {
                 procedural: boolean;
                 taxonomy: boolean;
                 identityAnchors: boolean;
                 peerProfiles: boolean;
             };
-            schemaVersion: string;
             id: string;
             description: string;
             version: string;
+            parentCapsule: string | null;
             parent: {
                 version: string;
                 capsuleId: string;
                 forkRoot: string;
             } | null;
-            parentCapsule: string | null;
             retrievalPolicy: {
                 tierWeights: Record<string, number>;
                 directAnswerEnabled: boolean;
@@ -854,13 +854,13 @@ declare const ExportBundleV2Schema: z.ZodObject<{
         pluginVersion: string;
         includesTranscripts: boolean;
         capsule: {
+            schemaVersion: string;
             includes: {
                 procedural: boolean;
                 taxonomy: boolean;
                 identityAnchors: boolean;
                 peerProfiles: boolean;
             };
-            schemaVersion: string;
             id: string;
             description: string;
             version: string;

package/dist/utils/serialize-mutations.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Instance-scoped keyed serializer. Holds the per-key chain map so that all
+ * tasks queued under the same key on the SAME serializer run strictly in order.
+ *
+ * The map is instance-scoped (not module-level) so tests can construct a fresh
+ * serializer per case and avoid cross-test contamination, and so adopters that
+ * want isolation (e.g. one serializer per storage root) can have it. The free
+ * {@link serializeMutations} export delegates to a single shared default
+ * instance for callers that want process-wide serialization.
+ */
+declare class MutationSerializer {
+    private readonly chains;
+    /**
+     * Run `task` strictly after every other task already queued under `key` on
+     * this serializer has settled.
+     *
+     * Rejection recovery (rule #40, mirroring the catalog's `queueCritical`):
+     * if a prior task rejects, later tasks STILL RUN, while the rejecting task's
+     * error is surfaced to ITS OWN caller. Concretely, the recovered tail is
+     * `run.then(noop, noop)` — never a bare `.then(fn)`, which would let one
+     * failure kill every queued task behind it.
+     *
+     * No unbounded growth: when a chain's last task settles and no newer task
+     * chained onto it, its entry is deleted (the storage router's
+     * `inFlightResolved` marker-then-clear discipline).
+     */
+    serialize<T>(key: string, task: () => Promise<T>): Promise<T>;
+    /**
+     * Test-only: the number of keys with a not-yet-cleaned chain. Used to assert
+     * the no-unbounded-growth invariant. Not part of the public contract.
+     */
+    pendingKeysForTest(): number;
+}
+/**
+ * Free-function entry point (issue #1524 signature). Serializes `task` against
+ * every other task queued under `key` across the whole process, via a shared
+ * default {@link MutationSerializer}. For isolated/testable serialization,
+ * construct a `MutationSerializer` directly.
+ */
+declare function serializeMutations<T>(key: string, task: () => Promise<T>): Promise<T>;
+/** Options for {@link withHeldFileLock}. */
+interface HeldFileLockOptions {
+    /**
+     * A lock whose mtime is older than this (in ms) is treated as a crashed
+     * holder and broken. Required — there is no safe default, since the right
+     * value depends on how long the guarded critical section can legitimately
+     * run.
+     */
+    readonly staleMs: number;
+    /**
+     * Bounded acquisition: give up trying to acquire a busy lock after this long
+     * (ms) and invoke `task(false)` best-effort WITHOUT holding the lock, rather
+     * than blocking forever or crashing the primary op. Default 5000ms (matches
+     * the namespace catalog's `REBUILD_LOCK_MAX_WAIT_MS`).
+     */
+    readonly maxWaitMs?: number;
+    /**
+     * Poll interval (ms) while waiting for a busy lock to clear. Default 50ms.
+     */
+    readonly pollMs?: number;
+    /**
+     * While WE hold the lock, refresh its mtime on this cadence (ms) so a
+     * legitimately long task is not mistaken for a crashed holder and broken out
+     * from under. Default `floor(staleMs / 3)` (at least 100ms), mirroring the
+     * catalog heartbeat ratio. Must be comfortably below `staleMs`.
+     */
+    readonly heartbeatMs?: number;
+    /**
+     * Test seam (NG7Bg, #1506 round 28): fires AFTER a lock is judged stale and
+     * BEFORE the re-verify + unlink, simulating a replacement lock being created
+     * in the race window. No-op in production.
+     */
+    readonly onBeforeBreakStaleUnlinkForTest?: () => Promise<void> | void;
+    /**
+     * Test seam (codex P2): fires AFTER the release rename moves the lock to a
+     * trash path and BEFORE the ownership re-verify/restore — simulating a third
+     * contender acquiring the (now-empty) lockPath in the race window. No-op in
+     * production. Used to prove the pre-check prevents the rename entirely.
+     */
+    readonly onAfterReleaseRenameForTest?: () => Promise<void> | void;
+    /**
+     * Best-effort hook for non-fatal lock warnings (heartbeat refresh failure,
+     * release-time ownership check failure). Never throws into the caller. If
+     * omitted, warnings are swallowed (the lock is advisory; release/heartbeat
+     * failures must never crash the guarded op).
+     */
+    readonly onLockWarning?: (message: string, err: unknown) => void;
+}
+/**
+ * Run `task` under an exclusive on-disk lock at `lockPath`.
+ *
+ * Cross-process mutex via `open(lockPath, "wx")` (atomic exclusive create).
+ * While held, a heartbeat timer refreshes the lock's mtime so a legitimately
+ * long task is not mistaken for a crashed holder and broken out from under. A
+ * lock older than `opts.staleMs` is treated as stale and broken — but
+ * REPLACEMENT-SAFE (NG7Bg): we capture the stale lock's identity (full content
+ * line: `<pid> <owner-uuid> <iso>`) when judging it stale, then RE-READ and
+ * RE-STAT immediately before `unlink`, deleting only if byte-identical AND
+ * still stale. A replacement lock created in the window has a different owner
+ * id / timestamp, so its content differs and is left untouched.
+ *
+ * `task` receives `acquired: boolean` — `true` when we hold the lock, `false`
+ * when acquisition timed out (best-effort). The signature takes
+ * `(acquired) => Promise<T>` rather than the issue's sketched `() => Promise<T>`
+ * so this can be the SINGLE lock home (issue: "do NOT leave two lock
+ * implementations; pick one home"): the catalog's touch path needs to DROP on
+ * timeout, which requires knowing whether the lock was acquired. A caller that
+ * ignores the flag is still assignable (`() => Promise<T>` ⊆
+ * `(acquired: boolean) => Promise<T>` in TypeScript).
+ *
+ * Release is ownership-checked: we only `unlink` a lock whose content still
+ * identifies THIS acquirer (same owner id), so a replacement created after we
+ * stopped heartbeating is never destroyed — mirroring the catalog's
+ * `rebuildLockHeldBySelf`.
+ *
+ * ADOPTION NOTE: lock only the brief final read-merge-write window, never a
+ * long scan — a scan-length lock makes concurrent writers time out and
+ * silently drop work (catalog round 5, codex/cursor P2).
+ */
+declare function withHeldFileLock<T>(lockPath: string, opts: HeldFileLockOptions, task: (acquired: boolean) => Promise<T>): Promise<T>;
+
+export { type HeldFileLockOptions, MutationSerializer, serializeMutations, withHeldFileLock };