@remnic/core 9.3.518 → 9.3.520

package/dist/schemas.d.ts

@@ -7,13 +7,13 @@ declare const MemoryActionEligibilityContextSchema: z.ZodObject<{
     importance: z.ZodNumber;
     source: z.ZodEnum<["extraction", "consolidation", "replay", "manual", "unknown"]>;
 }, "strict", z.ZodTypeAny, {
-    source: "manual" | "extraction" | "consolidation" | "replay" | "unknown";
     confidence: number;
+    source: "unknown" | "manual" | "extraction" | "consolidation" | "replay";
     lifecycleState: "active" | "archived" | "candidate" | "validated" | "stale";
     importance: number;
 }, {
-    source: "manual" | "extraction" | "consolidation" | "replay" | "unknown";
     confidence: number;
+    source: "unknown" | "manual" | "extraction" | "consolidation" | "replay";
     lifecycleState: "active" | "archived" | "candidate" | "validated" | "stale";
     importance: number;
 }>;
@@ -149,10 +149,10 @@ declare const ExtractedFactSchema: z.ZodEffects<z.ZodObject<{
         observed_outcome?: string | null | undefined;
     }>>>;
 }, "strip", z.ZodTypeAny, {
-    tags: string[];
-    content: string;
     category: "fact" | "preference" | "correction" | "entity" | "decision" | "relationship" | "principle" | "commitment" | "moment" | "skill" | "rule" | "procedure" | "reasoning_trace";
+    content: string;
     confidence: number;
+    tags: string[];
     entityRef?: string | null | undefined;
     structuredAttributes?: Record<string, string> | null | undefined;
     promptedByQuestion?: string | null | undefined;
@@ -178,10 +178,10 @@ declare const ExtractedFactSchema: z.ZodEffects<z.ZodObject<{
         observed_outcome?: string | null | undefined;
     } | null | undefined;
 }, {
-    tags: string[];
-    content: string;
     category: "fact" | "preference" | "correction" | "entity" | "decision" | "relationship" | "principle" | "commitment" | "moment" | "skill" | "rule" | "procedure" | "reasoning_trace";
+    content: string;
     confidence: number;
+    tags: string[];
     entityRef?: string | null | undefined;
     structuredAttributes?: Record<string, string> | null | undefined;
     promptedByQuestion?: string | null | undefined;
@@ -207,10 +207,10 @@ declare const ExtractedFactSchema: z.ZodEffects<z.ZodObject<{
         observed_outcome?: string | null | undefined;
     } | null | undefined;
 }>, {
-    tags: string[];
-    content: string;
     category: "fact" | "preference" | "correction" | "entity" | "decision" | "relationship" | "principle" | "commitment" | "moment" | "skill" | "rule" | "procedure" | "reasoning_trace";
+    content: string;
     confidence: number;
+    tags: string[];
     entityRef?: string | null | undefined;
     structuredAttributes?: Record<string, string> | null | undefined;
     promptedByQuestion?: string | null | undefined;
@@ -236,10 +236,10 @@ declare const ExtractedFactSchema: z.ZodEffects<z.ZodObject<{
         observed_outcome?: string | null | undefined;
     } | null | undefined;
 }, {
-    tags: string[];
-    content: string;
     category: "fact" | "preference" | "correction" | "entity" | "decision" | "relationship" | "principle" | "commitment" | "moment" | "skill" | "rule" | "procedure" | "reasoning_trace";
+    content: string;
     confidence: number;
+    tags: string[];
     entityRef?: string | null | undefined;
     structuredAttributes?: Record<string, string> | null | undefined;
     promptedByQuestion?: string | null | undefined;
@@ -457,10 +457,10 @@ declare const ProactiveExtractionResultSchema: z.ZodObject<{
             observed_outcome?: string | null | undefined;
         }>>>;
     }, "strip", z.ZodTypeAny, {
-        tags: string[];
-        content: string;
         category: "fact" | "preference" | "correction" | "entity" | "decision" | "relationship" | "principle" | "commitment" | "moment" | "skill" | "rule" | "procedure" | "reasoning_trace";
+        content: string;
         confidence: number;
+        tags: string[];
         entityRef?: string | null | undefined;
         structuredAttributes?: Record<string, string> | null | undefined;
         promptedByQuestion?: string | null | undefined;
@@ -486,10 +486,10 @@ declare const ProactiveExtractionResultSchema: z.ZodObject<{
             observed_outcome?: string | null | undefined;
         } | null | undefined;
     }, {
-        tags: string[];
-        content: string;
         category: "fact" | "preference" | "correction" | "entity" | "decision" | "relationship" | "principle" | "commitment" | "moment" | "skill" | "rule" | "procedure" | "reasoning_trace";
+        content: string;
         confidence: number;
+        tags: string[];
         entityRef?: string | null | undefined;
         structuredAttributes?: Record<string, string> | null | undefined;
         promptedByQuestion?: string | null | undefined;
@@ -515,10 +515,10 @@ declare const ProactiveExtractionResultSchema: z.ZodObject<{
             observed_outcome?: string | null | undefined;
         } | null | undefined;
     }>, {
-        tags: string[];
-        content: string;
         category: "fact" | "preference" | "correction" | "entity" | "decision" | "relationship" | "principle" | "commitment" | "moment" | "skill" | "rule" | "procedure" | "reasoning_trace";
+        content: string;
         confidence: number;
+        tags: string[];
         entityRef?: string | null | undefined;
         structuredAttributes?: Record<string, string> | null | undefined;
         promptedByQuestion?: string | null | undefined;
@@ -544,10 +544,10 @@ declare const ProactiveExtractionResultSchema: z.ZodObject<{
             observed_outcome?: string | null | undefined;
         } | null | undefined;
     }, {
-        tags: string[];
-        content: string;
         category: "fact" | "preference" | "correction" | "entity" | "decision" | "relationship" | "principle" | "commitment" | "moment" | "skill" | "rule" | "procedure" | "reasoning_trace";
+        content: string;
         confidence: number;
+        tags: string[];
         entityRef?: string | null | undefined;
         structuredAttributes?: Record<string, string> | null | undefined;
         promptedByQuestion?: string | null | undefined;
@@ -631,10 +631,10 @@ declare const ProactiveExtractionResultSchema: z.ZodObject<{
     }>, "many">>>;
 }, "strip", z.ZodTypeAny, {
     facts: {
-        tags: string[];
-        content: string;
         category: "fact" | "preference" | "correction" | "entity" | "decision" | "relationship" | "principle" | "commitment" | "moment" | "skill" | "rule" | "procedure" | "reasoning_trace";
+        content: string;
         confidence: number;
+        tags: string[];
         entityRef?: string | null | undefined;
         structuredAttributes?: Record<string, string> | null | undefined;
         promptedByQuestion?: string | null | undefined;
@@ -680,10 +680,10 @@ declare const ProactiveExtractionResultSchema: z.ZodObject<{
     }[] | null | undefined;
 }, {
     facts: {
-        tags: string[];
-        content: string;
         category: "fact" | "preference" | "correction" | "entity" | "decision" | "relationship" | "principle" | "commitment" | "moment" | "skill" | "rule" | "procedure" | "reasoning_trace";
+        content: string;
         confidence: number;
+        tags: string[];
         entityRef?: string | null | undefined;
         structuredAttributes?: Record<string, string> | null | undefined;
         promptedByQuestion?: string | null | undefined;
@@ -825,10 +825,10 @@ declare const ExtractionResultSchema: z.ZodObject<{
             observed_outcome?: string | null | undefined;
         }>>>;
     }, "strip", z.ZodTypeAny, {
-        tags: string[];
-        content: string;
         category: "fact" | "preference" | "correction" | "entity" | "decision" | "relationship" | "principle" | "commitment" | "moment" | "skill" | "rule" | "procedure" | "reasoning_trace";
+        content: string;
         confidence: number;
+        tags: string[];
         entityRef?: string | null | undefined;
         structuredAttributes?: Record<string, string> | null | undefined;
         promptedByQuestion?: string | null | undefined;
@@ -854,10 +854,10 @@ declare const ExtractionResultSchema: z.ZodObject<{
             observed_outcome?: string | null | undefined;
         } | null | undefined;
     }, {
-        tags: string[];
-        content: string;
         category: "fact" | "preference" | "correction" | "entity" | "decision" | "relationship" | "principle" | "commitment" | "moment" | "skill" | "rule" | "procedure" | "reasoning_trace";
+        content: string;
         confidence: number;
+        tags: string[];
         entityRef?: string | null | undefined;
         structuredAttributes?: Record<string, string> | null | undefined;
         promptedByQuestion?: string | null | undefined;
@@ -883,10 +883,10 @@ declare const ExtractionResultSchema: z.ZodObject<{
             observed_outcome?: string | null | undefined;
         } | null | undefined;
     }>, {
-        tags: string[];
-        content: string;
         category: "fact" | "preference" | "correction" | "entity" | "decision" | "relationship" | "principle" | "commitment" | "moment" | "skill" | "rule" | "procedure" | "reasoning_trace";
+        content: string;
         confidence: number;
+        tags: string[];
         entityRef?: string | null | undefined;
         structuredAttributes?: Record<string, string> | null | undefined;
         promptedByQuestion?: string | null | undefined;
@@ -912,10 +912,10 @@ declare const ExtractionResultSchema: z.ZodObject<{
             observed_outcome?: string | null | undefined;
         } | null | undefined;
     }, {
-        tags: string[];
-        content: string;
         category: "fact" | "preference" | "correction" | "entity" | "decision" | "relationship" | "principle" | "commitment" | "moment" | "skill" | "rule" | "procedure" | "reasoning_trace";
+        content: string;
         confidence: number;
+        tags: string[];
         entityRef?: string | null | undefined;
         structuredAttributes?: Record<string, string> | null | undefined;
         promptedByQuestion?: string | null | undefined;
@@ -1013,10 +1013,10 @@ declare const ExtractionResultSchema: z.ZodObject<{
     }>, "many">>>;
 }, "strip", z.ZodTypeAny, {
     facts: {
-        tags: string[];
-        content: string;
         category: "fact" | "preference" | "correction" | "entity" | "decision" | "relationship" | "principle" | "commitment" | "moment" | "skill" | "rule" | "procedure" | "reasoning_trace";
+        content: string;
         confidence: number;
+        tags: string[];
         entityRef?: string | null | undefined;
         structuredAttributes?: Record<string, string> | null | undefined;
         promptedByQuestion?: string | null | undefined;
@@ -1068,10 +1068,10 @@ declare const ExtractionResultSchema: z.ZodObject<{
     identityReflection?: string | null | undefined;
 }, {
     facts: {
-        tags: string[];
-        content: string;
         category: "fact" | "preference" | "correction" | "entity" | "decision" | "relationship" | "principle" | "commitment" | "moment" | "skill" | "rule" | "procedure" | "reasoning_trace";
+        content: string;
         confidence: number;
+        tags: string[];
         entityRef?: string | null | undefined;
         structuredAttributes?: Record<string, string> | null | undefined;
         promptedByQuestion?: string | null | undefined;
@@ -1285,13 +1285,13 @@ declare const ContradictionVerificationSchema: z.ZodObject<{
     reasoning: z.ZodString;
     whichIsNewer: z.ZodEnum<["first", "second", "unclear"]>;
 }, "strip", z.ZodTypeAny, {
-    reasoning: string;
     confidence: number;
+    reasoning: string;
     isContradiction: boolean;
     whichIsNewer: "first" | "second" | "unclear";
 }, {
-    reasoning: string;
     confidence: number;
+    reasoning: string;
     isContradiction: boolean;
     whichIsNewer: "first" | "second" | "unclear";
 }>;
@@ -1386,8 +1386,8 @@ declare const BehaviorLoopAdjustmentSchema: z.ZodObject<{
     reason: z.ZodString;
     appliedAt: z.ZodString;
 }, "strip", z.ZodTypeAny, {
-    reason: string;
     confidence: number;
+    reason: string;
     parameter: string;
     previousValue: number;
     nextValue: number;
@@ -1395,8 +1395,8 @@ declare const BehaviorLoopAdjustmentSchema: z.ZodObject<{
     evidenceCount: number;
     appliedAt: string;
 }, {
-    reason: string;
     confidence: number;
+    reason: string;
     parameter: string;
     previousValue: number;
     nextValue: number;
@@ -1420,8 +1420,8 @@ declare const BehaviorLoopPolicyStateSchema: z.ZodObject<{
         reason: z.ZodString;
         appliedAt: z.ZodString;
     }, "strip", z.ZodTypeAny, {
-        reason: string;
         confidence: number;
+        reason: string;
         parameter: string;
         previousValue: number;
         nextValue: number;
@@ -1429,8 +1429,8 @@ declare const BehaviorLoopPolicyStateSchema: z.ZodObject<{
         evidenceCount: number;
         appliedAt: string;
     }, {
-        reason: string;
         confidence: number;
+        reason: string;
         parameter: string;
         previousValue: number;
         nextValue: number;
@@ -1447,8 +1447,8 @@ declare const BehaviorLoopPolicyStateSchema: z.ZodObject<{
     maxDeltaPerCycle: number;
     protectedParams: string[];
     adjustments: {
-        reason: string;
         confidence: number;
+        reason: string;
         parameter: string;
         previousValue: number;
         nextValue: number;
@@ -1464,8 +1464,8 @@ declare const BehaviorLoopPolicyStateSchema: z.ZodObject<{
     maxDeltaPerCycle: number;
     protectedParams: string[];
     adjustments: {
-        reason: string;
         confidence: number;
+        reason: string;
         parameter: string;
         previousValue: number;
         nextValue: number;

package/dist/shared-context/manager.d.ts

@@ -22,9 +22,9 @@ declare const SharedFeedbackEntrySchema: z.ZodObject<{
     agent: string;
     date: string;
     reason: string;
+    confidence?: number | undefined;
     workflow?: string | undefined;
     tags?: string[] | undefined;
-    confidence?: number | undefined;
     severity?: "low" | "medium" | "high" | undefined;
     outcome?: string | undefined;
     refs?: string[] | undefined;
@@ -36,9 +36,9 @@ declare const SharedFeedbackEntrySchema: z.ZodObject<{
     agent: string;
     date: string;
     reason: string;
+    confidence?: number | undefined;
     workflow?: string | undefined;
     tags?: string[] | undefined;
-    confidence?: number | undefined;
     severity?: "low" | "medium" | "high" | undefined;
     outcome?: string | undefined;
     refs?: string[] | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remnic/core",
-  "version": "9.3.518",
+  "version": "9.3.520",
   "description": "Framework-agnostic Remnic memory engine — orchestrator, storage, extraction, search, trust zones",
   "type": "module",
   "main": "dist/index.js",

package/src/binary-lifecycle/backend.ts

@@ -6,7 +6,7 @@
  * so swapping storage providers requires no pipeline changes.
  */
 
-import fs from "node:fs";
+import type { Stats } from "node:fs";
 import fsp from "node:fs/promises";
 import path from "node:path";
 import type { BinaryStorageBackendConfig } from "./types.js";
@@ -27,6 +27,8 @@ export interface BinaryStorageBackend {
   exists(remotePath: string): Promise<boolean>;
   /** Delete a file from the backend. */
   delete(remotePath: string): Promise<void>;
+  /** Return the user-resolvable markdown target for a stored backend path. */
+  getRedirectTarget?(remotePath: string): string;
 }
 
 // ---------------------------------------------------------------------------
@@ -45,10 +47,9 @@ export class FilesystemBackend implements BinaryStorageBackend {
   }
 
   private resolveRemotePath(remotePath: string): string {
-    if (path.isAbsolute(remotePath)) {
-      throw new Error(`FilesystemBackend remotePath must be relative: ${JSON.stringify(remotePath)}`);
-    }
-    const resolved = path.resolve(this.basePath, remotePath);
+    const resolved = path.isAbsolute(remotePath)
+      ? path.resolve(remotePath)
+      : path.resolve(this.basePath, remotePath);
     const relative = path.relative(this.basePath, resolved);
     if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
       throw new Error(`FilesystemBackend remotePath escapes basePath: ${JSON.stringify(remotePath)}`);
@@ -56,26 +57,169 @@ export class FilesystemBackend implements BinaryStorageBackend {
     return resolved;
   }
 
-  async upload(localPath: string, remotePath: string): Promise<string> {
+  private isInsideBase(candidate: string, realBase: string): boolean {
+    const relative = path.relative(realBase, candidate);
+    return relative === "" || (relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+  }
+
+  private async realBasePathIfExists(): Promise<string | null> {
+    try {
+      const stat = await fsp.lstat(this.basePath);
+      if (stat.isSymbolicLink()) {
+        throw new Error(`FilesystemBackend basePath must not be a symlink: ${this.basePath}`);
+      }
+      if (!stat.isDirectory()) {
+        throw new Error(`FilesystemBackend basePath must be a directory: ${this.basePath}`);
+      }
+      return await fsp.realpath(this.basePath);
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+        return null;
+      }
+      throw err;
+    }
+  }
+
+  private async ensureBaseDirectory(): Promise<string> {
+    await fsp.mkdir(this.basePath, { recursive: true });
+    const realBase = await this.realBasePathIfExists();
+    if (realBase === null) {
+      throw new Error(`FilesystemBackend failed to create basePath: ${this.basePath}`);
+    }
+    return realBase;
+  }
+
+  private async ensureSafeParentDirectory(dest: string): Promise<string> {
+    const realBase = await this.ensureBaseDirectory();
+    const destDir = path.dirname(dest);
+    const relativeDir = path.relative(this.basePath, destDir);
+    const segments = relativeDir === "" ? [] : relativeDir.split(path.sep);
+    let current = this.basePath;
+
+    for (const segment of segments) {
+      if (segment === "." || segment === "") continue;
+      current = path.join(current, segment);
+      try {
+        const stat = await fsp.lstat(current);
+        if (stat.isSymbolicLink()) {
+          throw new Error(`FilesystemBackend remotePath traverses symlink: ${current}`);
+        }
+        if (!stat.isDirectory()) {
+          throw new Error(`FilesystemBackend remotePath parent is not a directory: ${current}`);
+        }
+      } catch (err) {
+        if ((err as NodeJS.ErrnoException).code !== "ENOENT") {
+          throw err;
+        }
+        await fsp.mkdir(current);
+      }
+    }
+
+    const realParent = await fsp.realpath(destDir);
+    if (!this.isInsideBase(realParent, realBase)) {
+      throw new Error(`FilesystemBackend remotePath parent escapes basePath: ${dest}`);
+    }
+    return realBase;
+  }
+
+  private async resolveExistingRemotePath(remotePath: string): Promise<string | null> {
     const dest = this.resolveRemotePath(remotePath);
+    const realBase = await this.realBasePathIfExists();
+    if (realBase === null) {
+      return null;
+    }
+
     const destDir = path.dirname(dest);
-    await fsp.mkdir(destDir, { recursive: true });
-    await fsp.copyFile(localPath, dest);
+    const relativeDir = path.relative(this.basePath, destDir);
+    const segments = relativeDir === "" ? [] : relativeDir.split(path.sep);
+    let current = this.basePath;
+    for (const segment of segments) {
+      if (segment === "." || segment === "") continue;
+      current = path.join(current, segment);
+      let stat: Stats;
+      try {
+        stat = await fsp.lstat(current);
+      } catch (err) {
+        if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+          return null;
+        }
+        throw err;
+      }
+      if (stat.isSymbolicLink()) {
+        throw new Error(`FilesystemBackend remotePath traverses symlink: ${current}`);
+      }
+      if (!stat.isDirectory()) {
+        return null;
+      }
+    }
+
+    const realParent = await fsp.realpath(destDir).catch((err: NodeJS.ErrnoException) => {
+      if (err.code === "ENOENT") return null;
+      throw err;
+    });
+    if (realParent === null) {
+      return null;
+    }
+    if (!this.isInsideBase(realParent, realBase)) {
+      throw new Error(`FilesystemBackend remotePath parent escapes basePath: ${JSON.stringify(remotePath)}`);
+    }
+
+    try {
+      const stat = await fsp.lstat(dest);
+      if (stat.isSymbolicLink()) {
+        throw new Error(`FilesystemBackend remotePath points to symlink: ${dest}`);
+      }
+      if (!stat.isFile()) {
+        return null;
+      }
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+        return null;
+      }
+      throw err;
+    }
+
+    const realDest = await fsp.realpath(dest);
+    if (!this.isInsideBase(realDest, realBase)) {
+      throw new Error(`FilesystemBackend remotePath escapes basePath: ${JSON.stringify(remotePath)}`);
+    }
     return dest;
   }
 
-  async exists(remotePath: string): Promise<boolean> {
+  async upload(localPath: string, remotePath: string): Promise<string> {
+    if (path.isAbsolute(remotePath)) {
+      throw new Error(`FilesystemBackend upload remotePath must be relative: ${JSON.stringify(remotePath)}`);
+    }
     const dest = this.resolveRemotePath(remotePath);
+    const realBase = await this.ensureSafeParentDirectory(dest);
     try {
-      await fsp.access(dest, fs.constants.F_OK);
-      return true;
-    } catch {
-      return false;
+      const stat = await fsp.lstat(dest);
+      if (stat.isSymbolicLink()) {
+        throw new Error(`FilesystemBackend remotePath points to symlink: ${dest}`);
+      }
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== "ENOENT") {
+        throw err;
+      }
     }
+    await fsp.copyFile(localPath, dest);
+    const realDest = await fsp.realpath(dest);
+    if (!this.isInsideBase(realDest, realBase)) {
+      throw new Error(`FilesystemBackend remotePath escapes basePath: ${JSON.stringify(remotePath)}`);
+    }
+    return remotePath;
+  }
+
+  async exists(remotePath: string): Promise<boolean> {
+    const dest = await this.resolveExistingRemotePath(remotePath);
+    return dest !== null;
   }
 
   async delete(remotePath: string): Promise<void> {
-    const dest = this.resolveRemotePath(remotePath);
+    const dest = await this.resolveExistingRemotePath(remotePath);
+    if (dest === null) {
+      return;
+    }
     try {
       await fsp.unlink(dest);
     } catch (err: unknown) {
@@ -83,6 +227,10 @@ export class FilesystemBackend implements BinaryStorageBackend {
       if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
     }
   }
+
+  getRedirectTarget(remotePath: string): string {
+    return this.resolveRemotePath(remotePath);
+  }
 }
 
 // ---------------------------------------------------------------------------

package/src/binary-lifecycle/manifest.ts

@@ -24,25 +24,37 @@ export function manifestPath(memoryDir: string): string {
 
 /**
  * Read the manifest from disk. Returns a fresh empty manifest if the file
- * does not exist or contains invalid JSON (CLAUDE.md #18).
+ * does not exist. Existing invalid manifests fail closed so the pipeline does
+ * not overwrite state needed for safe cleanup.
  */
 export async function readManifest(memoryDir: string): Promise<BinaryLifecycleManifest> {
   const filePath = manifestPath(memoryDir);
+  let raw: string;
   try {
-    const raw = await fsp.readFile(filePath, "utf-8");
-    const parsed: unknown = JSON.parse(raw);
-    // CLAUDE.md #18: validate the parsed result is a non-null object.
-    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    raw = await fsp.readFile(filePath, "utf-8");
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") {
       return emptyManifest();
     }
-    const obj = parsed as Record<string, unknown>;
-    if (obj.version !== 1 || !Array.isArray(obj.assets)) {
-      return emptyManifest();
-    }
-    return parsed as BinaryLifecycleManifest;
-  } catch {
-    return emptyManifest();
+    throw new Error(`Failed to read binary lifecycle manifest at ${filePath}: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`Invalid binary lifecycle manifest JSON at ${filePath}: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  // CLAUDE.md #18: validate the parsed result is a non-null object.
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new Error(`Invalid binary lifecycle manifest shape at ${filePath}: expected object`);
+  }
+  const obj = parsed as Record<string, unknown>;
+  if (obj.version !== 1 || !Array.isArray(obj.assets)) {
+    throw new Error(`Invalid binary lifecycle manifest shape at ${filePath}: expected version 1 with assets array`);
   }
+  return parsed as BinaryLifecycleManifest;
 }
 
 /**