@remnic/core 9.65.3 → 9.65.4

package/src/connectors/materialize-skills.ts

@@ -0,0 +1,127 @@
+/**
+ * materialize-skills.ts — the `skills/` section of the Codex materializer
+ * (issue #2369).
+ *
+ * Extracted from codex-materialize.ts (which sits at its structural LOC cap)
+ * so the skill staging / commit / prune rules live in one small module. Format
+ * and slug rules stay in the host-agnostic `procedural/skill-projection.ts`;
+ * this module only decides what lands on disk.
+ *
+ * Ownership rule: Remnic removes ONLY the slugs a previous run recorded in the
+ * sentinel's `projected_skills`. A skill folder a user (or another tool)
+ * created is never in that list, so it is never a removal candidate.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { renderSkillBundle, SKILL_FILE_NAME, type SkillBundle } from "../procedural/skill-projection.js";
+import { isValidSkillSlug } from "../skills-registry.js";
+import { ensureSafeManagedSubdir } from "./materialize-paths.js";
+
+/** Sub-directory for projected procedural skill bundles. */
+export const SKILLS_SUBDIR = "skills";
+
+export interface SkillFile {
+  slug: string;
+  body: string;
+}
+
+export interface SkillPlan {
+  /** False when the caller omitted `skills` — leave `skills/` untouched. */
+  supplied: boolean;
+  /** Bundles to write, deduplicated on slug. */
+  files: SkillFile[];
+  /** Previously projected slugs this run no longer projects. */
+  retiredSlugs: string[];
+}
+
+/**
+ * Decide what this run writes and removes. `undefined` bundles mean "not our
+ * business this run"; an empty array is authoritative and retires everything
+ * previously projected.
+ */
+export function planSkillFiles(
+  bundles: SkillBundle[] | undefined,
+  previouslyProjectedSlugs: readonly string[],
+): SkillPlan {
+  const files: SkillFile[] = [];
+  const seen = new Set<string>();
+  for (const bundle of bundles ?? []) {
+    // Invalid or duplicate slugs are dropped so two bundles can never target
+    // one folder and leave the second rename with no source (§37).
+    if (!isValidSkillSlug(bundle.slug) || seen.has(bundle.slug)) continue;
+    seen.add(bundle.slug);
+    files.push({ slug: bundle.slug, body: renderSkillBundle(bundle) });
+  }
+  const previous = previouslyProjectedSlugs.filter((slug) => isValidSkillSlug(slug));
+  return {
+    supplied: bundles !== undefined,
+    files,
+    retiredSlugs: bundles === undefined ? [] : previous.filter((slug) => !seen.has(slug)),
+  };
+}
+
+/** Absolute path of a projected bundle's SKILL.md under `memoriesDir`. */
+export function skillFilePath(memoriesDir: string, slug: string): string {
+  return path.join(memoriesDir, SKILLS_SUBDIR, slug, SKILL_FILE_NAME);
+}
+
+/** Relative path recorded in `MaterializeResult.filesWritten`. */
+export function skillFileRelPath(slug: string): string {
+  return path.join(SKILLS_SUBDIR, slug, SKILL_FILE_NAME);
+}
+
+/**
+ * True when no retired folder is still on disk. Guards the idempotent
+ * early-return: a hash match is only a safe no-op if the removals also landed.
+ */
+export function retiredSkillsAlreadyRemoved(memoriesDir: string, retiredSlugs: readonly string[]): boolean {
+  return retiredSlugs.every((slug) => !fs.existsSync(path.join(memoriesDir, SKILLS_SUBDIR, slug)));
+}
+
+/** Render bundles into the per-run staging directory. */
+export function stageSkillFiles(tmpDir: string, files: readonly SkillFile[]): void {
+  for (const file of files) {
+    const stagedDir = path.join(tmpDir, SKILLS_SUBDIR, file.slug);
+    fs.mkdirSync(stagedDir, { recursive: true });
+    fs.writeFileSync(path.join(stagedDir, SKILL_FILE_NAME), file.body);
+  }
+}
+
+/**
+ * Remove retired folders, then rename each staged SKILL.md into place. Per-file
+ * renames (never directory renames) so an existing folder cannot cause
+ * ENOTEMPTY and so Codex never observes a half-written file.
+ */
+export function commitSkillFiles(memoriesDir: string, tmpDir: string, plan: SkillPlan): void {
+  if (!plan.supplied) return;
+  if (plan.files.length === 0 && plan.retiredSlugs.length === 0) return;
+
+  const skillsDir = ensureSafeManagedSubdir(memoriesDir, path.join(memoriesDir, SKILLS_SUBDIR), SKILLS_SUBDIR);
+  for (const slug of plan.retiredSlugs) {
+    const retiredDir = path.join(skillsDir, slug);
+    try {
+      // Never follow a symlink out of the managed tree while pruning.
+      if (fs.lstatSync(retiredDir).isSymbolicLink()) continue;
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") continue;
+      throw err;
+    }
+    try {
+      fs.rmSync(retiredDir, { recursive: true, force: true });
+    } catch (err) {
+      throw new Error(
+        `codex-materialize: failed to remove retired skill ${slug}: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
+  for (const file of plan.files) {
+    const destDir = path.join(skillsDir, file.slug);
+    fs.mkdirSync(destDir, { recursive: true });
+    fs.renameSync(
+      path.join(tmpDir, SKILLS_SUBDIR, file.slug, SKILL_FILE_NAME),
+      path.join(destDir, SKILL_FILE_NAME),
+    );
+  }
+}

package/src/index.ts

@@ -219,17 +219,12 @@ export {
 } from "./procedural/procedure-types.js";
 
 // Procedural stats surface (issue #567 PR 5/5).
-export {
-  computeProcedureStats,
-  formatProcedureStatsText,
-} from "./procedural/procedure-stats.js";
-export type {
-  ProcedureStatsReport,
-  ProcedureStatusCounts,
-  ProcedureStatsConfigSnapshot,
-  ProcedureStatsRecent,
-} from "./procedural/procedure-stats.js";
+export { computeProcedureStats, formatProcedureStatsText } from "./procedural/procedure-stats.js";
+export type { ProcedureStatsReport, ProcedureStatusCounts, ProcedureStatsConfigSnapshot, ProcedureStatsRecent } from "./procedural/procedure-stats.js";
 export { runProcedureLibraryMaintenance, type ProcedureLibraryMaintenanceReport, type ProcedureMaintenanceAction, type ProcedureMaintenanceActionKind, type ProcedureMaintenanceReasonCode, type ProcedureMaintenanceEvidence, type ProcedureMaintenanceMarker } from "./procedural/library-maintenance.js";
+// Portable procedural skill bundles (issue #2369).
+export { parseSkillProjectionConfig, projectProceduresToSkills, renderSkillBundle, parseSkillBundle, sanitizeSkillSlug, SKILL_FILE_NAME, type SkillBundle, type SkillProjectionConfig, type ParsedSkillBundle } from "./procedural/skill-projection.js";
+export { exportSkillBundles, readSkillBundlesFromDir, persistImportedSkills, type ExportSkillsResult, type ImportSkillsResult, type ReadSkillBundle } from "./procedural/skill-io.js";
 export * from "./preferences/index.js";
 // ---------------------------------------------------------------------------
 // Direct-answer retrieval tier (issue #518)

package/src/procedural/skill-io.test.ts

@@ -0,0 +1,190 @@
+/**
+ * Skill bundle export / import I/O (issue #2369).
+ *
+ * Covers the acceptance matrix:
+ *   - export → import into a FRESH memory dir reproduces the procedure steps
+ *     with import provenance;
+ *   - imported procedures land as `pending_review`, never active;
+ *   - a bundle carrying `scripts/` imports the SKILL.md text only and flags
+ *     `hasUnimportedResources`;
+ *   - symlinked bundle dirs / SKILL.md files and escaping entries are skipped
+ *     with a reason instead of being walked.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import os from "node:os";
+import path from "node:path";
+import { mkdir, mkdtemp, rm, symlink, writeFile } from "node:fs/promises";
+
+import { StorageManager } from "../storage.js";
+import { stripAttributesSuffix } from "../structured-attributes.js";
+import { buildProcedurePersistBody, parseProcedureStepsFromBody } from "./procedure-types.js";
+import { exportSkillBundles, persistImportedSkills, readSkillBundlesFromDir } from "./skill-io.js";
+import { projectProceduresToSkills, SKILL_FILE_NAME } from "./skill-projection.js";
+import type { MemoryFile } from "../types.js";
+
+const STEPS = [
+  { order: 1, intent: "Read the failing output." },
+  { order: 2, intent: "Fix the smallest cause.", expectedOutcome: "The suite passes." },
+];
+
+function makeProcedure(id: string, title: string): MemoryFile {
+  return {
+    path: `procedures/2026-08-18/${id}.md`,
+    content: buildProcedurePersistBody(title, STEPS),
+    frontmatter: {
+      id,
+      category: "procedure",
+      created: "2026-08-18T00:00:00.000Z",
+      updated: "2026-08-18T00:00:00.000Z",
+      source: "procedure-miner",
+      confidence: 0.8,
+      confidenceTier: "implied",
+      tags: [],
+    } as MemoryFile["frontmatter"],
+  };
+}
+
+async function tempDir(prefix: string): Promise<string> {
+  return mkdtemp(path.join(os.tmpdir(), prefix));
+}
+
+test("export then import into a fresh memory dir reproduces the steps as pending_review", async () => {
+  const outDir = await tempDir("remnic-skill-export-");
+  const memoryDir = await tempDir("remnic-skill-memory-");
+  try {
+    const source = makeProcedure("procedure-1", "Fix a failing test");
+    const written = await exportSkillBundles({
+      bundles: projectProceduresToSkills([source]),
+      outDir,
+    });
+    assert.deepEqual(written.slugs, ["fix-a-failing-test"]);
+
+    const read = await readSkillBundlesFromDir(outDir);
+    assert.equal(read.bundles.length, 1);
+    assert.equal(read.bundles[0].hasUnimportedResources, false);
+
+    const storage = new StorageManager(memoryDir);
+    const result = await persistImportedSkills({ storage, bundles: read.bundles });
+    assert.equal(result.imported.length, 1);
+    assert.equal(result.imported[0].steps, 2);
+    assert.deepEqual(result.rejected, []);
+
+    const memories = await storage.readAllMemories();
+    const imported = memories.filter((m) => m.frontmatter.category === "procedure");
+    assert.equal(imported.length, 1);
+    assert.equal(imported[0].frontmatter.status, "pending_review");
+    assert.equal(imported[0].frontmatter.source, "skill-import");
+    assert.equal(imported[0].frontmatter.structuredAttributes?.skill_slug, "fix-a-failing-test");
+    assert.equal(imported[0].frontmatter.structuredAttributes?.skill_origin_memory_id, "procedure-1");
+    assert.equal(imported[0].frontmatter.structuredAttributes?.hasUnimportedResources, undefined);
+
+    // storage.writeMemory appends a "[Attributes: ...]" footer to any memory
+    // carrying structuredAttributes; it is machine provenance, not a step.
+    assert.deepEqual(
+      parseProcedureStepsFromBody(stripAttributesSuffix(imported[0].content)),
+      parseProcedureStepsFromBody(source.content),
+    );
+  } finally {
+    await rm(outDir, { recursive: true, force: true });
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("a bundle with scripts/ imports text only and flags hasUnimportedResources", async () => {
+  const dir = await tempDir("remnic-skill-scripts-");
+  const memoryDir = await tempDir("remnic-skill-memory-");
+  try {
+    const bundleDir = path.join(dir, "risky-skill");
+    await mkdir(path.join(bundleDir, "scripts"), { recursive: true });
+    await writeFile(
+      path.join(bundleDir, SKILL_FILE_NAME),
+      ["---", "name: risky-skill", "description: Do the risky thing", "---", "", "Do the risky thing", "", "## Step 1", "", "Run the checklist.", ""].join("\n"),
+    );
+    await writeFile(path.join(bundleDir, "scripts", "install.sh"), "#!/bin/sh\necho nope\n");
+
+    const read = await readSkillBundlesFromDir(dir);
+    assert.equal(read.bundles.length, 1);
+    assert.equal(read.bundles[0].hasUnimportedResources, true);
+    assert.equal(read.bundles[0].steps?.length, 1);
+    assert.ok(!read.bundles[0].body.includes("echo nope"));
+
+    const storage = new StorageManager(memoryDir);
+    await persistImportedSkills({ storage, bundles: read.bundles });
+    const imported = (await storage.readAllMemories()).filter((m) => m.frontmatter.category === "procedure");
+    assert.equal(imported.length, 1);
+    assert.equal(imported[0].frontmatter.structuredAttributes?.hasUnimportedResources, "true");
+    assert.equal(imported[0].frontmatter.status, "pending_review");
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("a step-less body is stored verbatim", async () => {
+  const dir = await tempDir("remnic-skill-prose-");
+  const memoryDir = await tempDir("remnic-skill-memory-");
+  try {
+    const bundleDir = path.join(dir, "prose-skill");
+    await mkdir(bundleDir, { recursive: true });
+    await writeFile(path.join(bundleDir, SKILL_FILE_NAME), "---\nname: prose-skill\n---\n\nJust prose guidance.\n");
+
+    const read = await readSkillBundlesFromDir(dir);
+    assert.equal(read.bundles[0].steps, null);
+
+    const storage = new StorageManager(memoryDir);
+    await persistImportedSkills({ storage, bundles: read.bundles });
+    const imported = (await storage.readAllMemories()).filter((m) => m.frontmatter.category === "procedure");
+    assert.match(imported[0].content, /Just prose guidance\./);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("symlinked bundles and escaping entries are skipped with a reason", async () => {
+  const dir = await tempDir("remnic-skill-symlink-");
+  const outside = await tempDir("remnic-skill-outside-");
+  try {
+    const real = path.join(dir, "real-skill");
+    await mkdir(real, { recursive: true });
+    await writeFile(path.join(real, SKILL_FILE_NAME), "---\nname: real-skill\n---\n\nReal body\n");
+
+    // A symlinked bundle directory pointing outside the import root.
+    await mkdir(path.join(outside, "evil"), { recursive: true });
+    await writeFile(path.join(outside, "evil", SKILL_FILE_NAME), "---\nname: evil\n---\n\nEscaped body\n");
+    await symlink(path.join(outside, "evil"), path.join(dir, "linked-skill"), "dir");
+
+    // A bundle whose SKILL.md is itself a symlink.
+    const linkedFile = path.join(dir, "linked-file-skill");
+    await mkdir(linkedFile, { recursive: true });
+    await symlink(path.join(outside, "evil", SKILL_FILE_NAME), path.join(linkedFile, SKILL_FILE_NAME), "file");
+
+    // A directory with no SKILL.md at all.
+    await mkdir(path.join(dir, "empty-skill"), { recursive: true });
+
+    const read = await readSkillBundlesFromDir(dir);
+    assert.deepEqual(read.bundles.map((b) => b.slug), ["real-skill"]);
+    const reasons = new Map(read.skipped.map((s) => [s.entry, s.reason]));
+    assert.equal(reasons.get("linked-skill"), "symlink");
+    assert.match(reasons.get("linked-file-skill") ?? "", /not a regular file/);
+    assert.match(reasons.get("empty-skill") ?? "", /no SKILL\.md/);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+    await rm(outside, { recursive: true, force: true });
+  }
+});
+
+test("a symlinked import root is refused outright", async () => {
+  const dir = await tempDir("remnic-skill-root-");
+  const linkParent = await tempDir("remnic-skill-link-");
+  try {
+    const link = path.join(linkParent, "linked-root");
+    await symlink(dir, link, "dir");
+    await assert.rejects(() => readSkillBundlesFromDir(link), /symlinked directory/);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+    await rm(linkParent, { recursive: true, force: true });
+  }
+});

package/src/procedural/skill-io.ts

@@ -0,0 +1,220 @@
+/**
+ * skill-io.ts — filesystem export / import for procedural skill bundles
+ * (issue #2369).
+ *
+ * Export writes `<dir>/<slug>/SKILL.md` and never deletes anything it did not
+ * just render. Import walks every `<dir>/<slug>/SKILL.md`, rejects symlinks and any entry that
+ * resolves outside the requested root, and persists `pending_review` procedure
+ * memories through the sealed-envelope write path.
+ *
+ * Import is INERT: bundle resources (`scripts/`, binaries, extra files) are
+ * never read, copied, or executed. Their presence is recorded as
+ * `hasUnimportedResources` so a reviewer can act on it.
+ */
+
+import { lstat, mkdir, readdir, readFile, realpath, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import { log } from "../logger.js";
+import type { StorageManager } from "../storage.js";
+import { pathIsInside } from "../utils/path-containment.js";
+import { composeMemoryEnvelope } from "../write-envelope.js";
+import { buildProcedurePersistBody } from "./procedure-types.js";
+import {
+  parseSkillBundle,
+  renderSkillBundle,
+  sanitizeSkillSlug,
+  SKILL_FILE_NAME,
+  SKILL_IMPORT_SOURCE,
+  type ParsedSkillBundle,
+  type SkillBundle,
+} from "./skill-projection.js";
+
+export interface ExportSkillsResult {
+  outDir: string;
+  /** Slugs written this run, in projection order. */
+  slugs: string[];
+}
+
+/** Write bundles as `<outDir>/<slug>/SKILL.md`. Creates directories as needed. */
+export async function exportSkillBundles(options: {
+  bundles: readonly SkillBundle[];
+  outDir: string;
+}): Promise<ExportSkillsResult> {
+  const outDir = path.resolve(options.outDir);
+  await mkdir(outDir, { recursive: true });
+  const slugs: string[] = [];
+  for (const bundle of options.bundles) {
+    const dir = path.join(outDir, bundle.slug);
+    if (!pathIsInside(outDir, dir)) {
+      throw new Error(`skill export: refusing to write outside ${outDir} (slug ${bundle.slug})`);
+    }
+    try {
+      const existing = await lstat(dir);
+      if (existing.isSymbolicLink()) {
+        throw new Error(`skill export: refusing to write through symlink ${dir}`);
+      }
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
+    }
+    await mkdir(dir, { recursive: true });
+    const skillPath = path.join(dir, SKILL_FILE_NAME);
+    try {
+      const existingSkill = await lstat(skillPath);
+      if (existingSkill.isSymbolicLink()) {
+        throw new Error(`skill export: refusing to write through symlink ${skillPath}`);
+      }
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
+    }
+    await writeFile(skillPath, renderSkillBundle(bundle), "utf-8");
+    slugs.push(bundle.slug);
+  }
+  return { outDir, slugs };
+}
+
+/** One bundle read off disk, plus the resource flag the reviewer needs. */
+export interface ReadSkillBundle extends ParsedSkillBundle {
+  /** True when the bundle directory holds anything besides SKILL.md. */
+  hasUnimportedResources: boolean;
+}
+
+export interface ReadSkillBundlesResult {
+  bundles: ReadSkillBundle[];
+  /** Entries that were not importable, with the reason (never silent). */
+  skipped: Array<{ entry: string; reason: string }>;
+}
+
+/**
+ * Read every `<dir>/*​/SKILL.md` bundle. Symlinked roots, symlinked bundle
+ * directories, symlinked SKILL.md files, and anything resolving outside `dir`
+ * are skipped with a reason (Review Prevention Checklist §3, §10).
+ */
+export async function readSkillBundlesFromDir(dir: string): Promise<ReadSkillBundlesResult> {
+  const root = path.resolve(dir);
+  const rootStat = await lstat(root);
+  if (rootStat.isSymbolicLink()) {
+    throw new Error(`skill import: refusing to walk symlinked directory ${root}`);
+  }
+  if (!rootStat.isDirectory()) {
+    throw new Error(`skill import: ${root} is not a directory`);
+  }
+  const rootReal = await realpath(root);
+
+  const bundles: ReadSkillBundle[] = [];
+  const skipped: Array<{ entry: string; reason: string }> = [];
+  const entries = await readdir(root, { withFileTypes: true });
+  // Stable order — readdir order is not guaranteed (§6).
+  entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+
+  for (const entry of entries) {
+    try {
+      if (entry.isSymbolicLink()) {
+        skipped.push({ entry: entry.name, reason: "symlink" });
+        continue;
+      }
+      if (!entry.isDirectory()) continue;
+      const bundleDir = path.join(root, entry.name);
+      const bundleReal = await realpath(bundleDir);
+      if (!pathIsInside(rootReal, bundleReal)) {
+        skipped.push({ entry: entry.name, reason: "resolves outside the import root" });
+        continue;
+      }
+      const skillPath = path.join(bundleDir, SKILL_FILE_NAME);
+      let skillStat;
+      try {
+        skillStat = await lstat(skillPath);
+      } catch {
+        skipped.push({ entry: entry.name, reason: `no ${SKILL_FILE_NAME}` });
+        continue;
+      }
+      if (skillStat.isSymbolicLink() || !skillStat.isFile()) {
+        skipped.push({ entry: entry.name, reason: `${SKILL_FILE_NAME} is not a regular file` });
+        continue;
+      }
+      const parsed = parseSkillBundle(await readFile(skillPath, "utf-8"), sanitizeSkillSlug(entry.name));
+      if (!parsed) {
+        skipped.push({ entry: entry.name, reason: "empty body" });
+        continue;
+      }
+      const siblings = await readdir(bundleDir);
+      bundles.push({
+        ...parsed,
+        hasUnimportedResources: siblings.some((name) => name !== SKILL_FILE_NAME),
+      });
+    } catch (err) {
+      skipped.push({
+        entry: entry.name,
+        reason: `unreadable: ${err instanceof Error ? err.message : String(err)}`,
+      });
+    }
+  }
+
+  return { bundles, skipped };
+}
+
+export interface ImportedSkillRecord {
+  slug: string;
+  memoryId: string;
+  steps: number;
+  hasUnimportedResources: boolean;
+}
+
+export interface ImportSkillsResult {
+  imported: ImportedSkillRecord[];
+  /** Bundles that were read but not persisted (e.g. tombstone-blocked). */
+  rejected: Array<{ slug: string; reason: string }>;
+}
+
+/**
+ * Persist read bundles as `pending_review` procedure memories.
+ *
+ * `pending_review` is unconditional: imported procedures never auto-promote,
+ * regardless of `procedural.autoPromoteOccurrences`. Recall already excludes
+ * non-active procedures, so review is the promotion checkpoint.
+ */
+export async function persistImportedSkills(options: {
+  storage: StorageManager;
+  bundles: readonly ReadSkillBundle[];
+}): Promise<ImportSkillsResult> {
+  const imported: ImportedSkillRecord[] = [];
+  const rejected: Array<{ slug: string; reason: string }> = [];
+
+  for (const bundle of options.bundles) {
+    const title = (bundle.description ?? bundle.name ?? bundle.slug).trim() || bundle.slug;
+    const content = bundle.steps ? buildProcedurePersistBody(title, bundle.steps) : bundle.body;
+    const envelope = composeMemoryEnvelope(
+      {
+        content,
+        category: "procedure",
+        tags: ["skill-import", "procedure"],
+        structuredAttributes: {
+          skill_slug: bundle.slug,
+          // Basename only — never an operator's absolute path.
+          skill_source: `${bundle.slug}/${SKILL_FILE_NAME}`,
+          ...(bundle.provenance.memoryId ? { skill_origin_memory_id: bundle.provenance.memoryId } : {}),
+          ...(bundle.hasUnimportedResources ? { hasUnimportedResources: "true" } : {}),
+        },
+      },
+      { source: SKILL_IMPORT_SOURCE },
+      // Machine-generated / externally authored input — salvage, warn on drops.
+      { salvage: true },
+    );
+    if (envelope.salvageNotes.length > 0) {
+      log.warn(`skill-import write salvaged invalid fields: ${envelope.salvageNotes.join("; ")}`);
+    }
+    const written = await options.storage.writeSealedMemory(envelope, { status: "pending_review" });
+    if (written.tombstoneBlocked) {
+      rejected.push({ slug: bundle.slug, reason: "blocked by a tombstone; left for review" });
+      continue;
+    }
+    imported.push({
+      slug: bundle.slug,
+      memoryId: written.id,
+      steps: bundle.steps?.length ?? 0,
+      hasUnimportedResources: bundle.hasUnimportedResources,
+    });
+  }
+
+  return { imported, rejected };
+}