@remnic/core 9.3.645 → 9.3.647

package/dist/session-transcript-migration.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/summarizer.js

@@ -1,9 +1,10 @@
 import {
   HourlySummarizer
-} from "./chunk-Y2XKJJEI.js";
+} from "./chunk-IMWFHBG2.js";
 import "./chunk-XJNBEDFE.js";
 import "./chunk-XZ4WBBB5.js";
 import "./chunk-H3HDXD3U.js";
+import "./chunk-S4DDLTPX.js";
 import "./chunk-A3BS64GV.js";
 import "./chunk-B5XMS73R.js";
 import "./chunk-7SI52C65.js";

package/dist/transcript.d.ts

@@ -26,13 +26,17 @@ declare class TranscriptManager {
     private static readonly CHARS_PER_TOKEN;
     constructor(config: PluginConfig);
     /**
-     * Parse a sessionKey to extract channel type and ID.
+     * Resolve the storage path pieces for a sessionKey via the shared
+     * {@link sessionStoragePaths} helper (issue #1496, rule #22).
      *
-     * SessionKey patterns:
-     *   - agent:<agent-id>:main → type="main", id="default"
-     *   - agent:<agent-id>:discord:channel:<channel-id> → type="discord", id="<channel-id>"
-     *   - agent:<agent-id>:cron:<job-id> → type="cron", id="<job-id>"
-     *   - agent:<agent-id>:slack:channel:<channel-id> → type="slack", id="<channel-id>"
+     * Legacy `agent:<id>:...` shapes keep their existing readable channel paths.
+     * Arbitrary / non-legacy keys (e.g. `pi-geek:abc123`) route to
+     * `transcripts/session/<hash>/YYYY-MM-DD.jsonl` from the FIRST write — they
+     * never start life in `other/default`. For those keys a list of
+     * read-back-only `readbackDirs` is returned so data written by older builds
+     * (under `other/default`, or under an old `parts.length >= 3` directory such
+     * as `baz/default`) stays discoverable until migrated. New writes never
+     * target read-back dirs. See `session-identity.ts`.
      *
      * @returns Object with raw channel identifiers and encoded storage path pieces.
      */
@@ -43,6 +47,7 @@ declare class TranscriptManager {
         channelId: string;
         alternateDir: string;
         legacyDir?: string;
+        readbackDirs: string[];
     };
     /**
      * Initialize the transcript manager by ensuring directories exist.
@@ -59,6 +64,7 @@ declare class TranscriptManager {
         file: string;
         alternateDir: string;
         legacyDir?: string;
+        readbackDirs: string[];
     };
     private selectStorageDirForWrite;
     private directorySessionStatus;
@@ -102,6 +108,12 @@ declare class TranscriptManager {
      * Read transcript entries for a date range.
      * Returns entries within the time range, optionally filtered by sessionKey.
      * Reads from all channel subdirectories in the hierarchical structure.
+     *
+     * The window is half-open `[start, end)`: the upper bound is exclusive so
+     * caller-specified ranges (explicit dates, analytics buckets) don't
+     * double-count at shared boundaries (CLAUDE.md rule #35 / AGENTS.md rule 23).
+     * readRecent's inclusive-of-now behavior is handled by readRecent itself
+     * extending its end, not by relaxing this bound.
      */
     readRange(startTime: string, endTime: string, sessionKey?: string): Promise<TranscriptEntry[]>;
     /**

package/dist/transcript.js

@@ -1,6 +1,7 @@
 import {
   TranscriptManager
-} from "./chunk-IHG27THY.js";
+} from "./chunk-XUGQQPGO.js";
+import "./chunk-S4DDLTPX.js";
 import "./chunk-KFY3SGN7.js";
 import "./chunk-FF4KLI5W.js";
 import "./chunk-2ODBA7MQ.js";

package/dist/transfer/backup.js

@@ -1,8 +1,8 @@
 import {
   backupMemoryDir
-} from "../chunk-BXLOS5AJ.js";
+} from "../chunk-OWHERGF2.js";
 import "../chunk-765K3SAT.js";
-import "../chunk-DQEMWVMT.js";
+import "../chunk-UVYI6VIX.js";
 import "../chunk-J4EB7DNW.js";
 import "../chunk-BJMBJZ2Y.js";
 import "../chunk-UKJAGEXH.js";

package/dist/transfer/capsule-export.js

@@ -1,9 +1,9 @@
 import {
   exportCapsule,
   isValidCapsuleSince
-} from "../chunk-VDX2J7OX.js";
+} from "../chunk-BUKK5SWA.js";
 import "../chunk-WEHSQBFR.js";
-import "../chunk-DQEMWVMT.js";
+import "../chunk-UVYI6VIX.js";
 import "../chunk-J4EB7DNW.js";
 import "../chunk-BJMBJZ2Y.js";
 import "../chunk-UKJAGEXH.js";

package/dist/transfer/capsule-import.js

@@ -1,9 +1,9 @@
 import {
   importCapsule
-} from "../chunk-DGNQRNLL.js";
+} from "../chunk-NT5TINK5.js";
 import "../chunk-ALEPI75L.js";
 import "../chunk-WEHSQBFR.js";
-import "../chunk-DQEMWVMT.js";
+import "../chunk-UVYI6VIX.js";
 import "../chunk-BJMBJZ2Y.js";
 import "../chunk-UKJAGEXH.js";
 import "../chunk-FP2373TW.js";

package/dist/transfer/import-sqlite.js

@@ -1,8 +1,8 @@
 import {
   importSqlite
-} from "../chunk-AGNBY3VG.js";
-import "../chunk-Z734BLO3.js";
+} from "../chunk-APJQ6UEA.js";
 import "../chunk-G4IAEX6D.js";
+import "../chunk-Z734BLO3.js";
 import "../chunk-6KYMPV2O.js";
 import "../chunk-GCGJW34D.js";
 import "../chunk-PZ5AY32C.js";

package/dist/transfer/types.d.ts

@@ -313,13 +313,13 @@ 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;
@@ -334,13 +334,13 @@ declare const CapsuleBlockSchema: z.ZodObject<{
         directAnswerEnabled: boolean;
     };
 }, {
-    schemaVersion: string;
     includes: {
         procedural: boolean;
         taxonomy: boolean;
         identityAnchors: boolean;
         peerProfiles: boolean;
     };
+    schemaVersion: string;
     id: string;
     description: string;
     version: string;
@@ -464,13 +464,13 @@ 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;
@@ -485,13 +485,13 @@ declare const ExportManifestV2Schema: z.ZodObject<{
             directAnswerEnabled: boolean;
         };
     }, {
-        schemaVersion: string;
         includes: {
             procedural: boolean;
             taxonomy: boolean;
             identityAnchors: boolean;
             peerProfiles: boolean;
         };
+        schemaVersion: string;
         id: string;
         description: string;
         version: string;
@@ -518,13 +518,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;
@@ -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,13 +683,13 @@ 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;
@@ -704,13 +704,13 @@ declare const ExportBundleV2Schema: z.ZodObject<{
                 directAnswerEnabled: boolean;
             };
         }, {
-            schemaVersion: string;
             includes: {
                 procedural: boolean;
                 taxonomy: boolean;
                 identityAnchors: boolean;
                 peerProfiles: boolean;
             };
+            schemaVersion: string;
             id: string;
             description: string;
             version: string;
@@ -737,13 +737,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;
@@ -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,13 +815,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;
@@ -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/package.json

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

package/src/cli.ts

@@ -202,6 +202,10 @@ import {
   type SessionRepairApplyResult,
   type SessionRepairPlan,
 } from "./session-integrity.js";
+import {
+  migrateSessionTranscripts,
+  planSessionTranscriptMigration,
+} from "./session-transcript-migration.js";
 import type { TierMigrationCycleSummary, TierMigrationStatusSnapshot } from "./recall-state.js";
 import {
   readRuntimePolicySnapshot as readPolicyRuntimeSnapshot,
@@ -8650,6 +8654,81 @@ export function registerCli(
           }
         });
 
+      // ── Sessions subcommand (issue #1496) ───────────────────────────────
+      const sessionsCmd = cmd
+        .command("sessions")
+        .description("Inspect and migrate session transcript storage");
+
+      sessionsCmd
+        .command("migrate-transcripts")
+        .description(
+          "Split conflated other/default transcripts into first-class session/<hash> dirs",
+        )
+        .option("--dry-run", "Report the migration plan without moving files (default)")
+        .option("--apply", "Apply the migration (move files; default is dry-run)")
+        .action(async (...args: unknown[]) => {
+          const options = (args[0] ?? {}) as Record<string, unknown>;
+          const dryRunFlag = options.dryRun === true;
+          const applyFlag = options.apply === true;
+
+          // Rule #51: reject contradictory flags rather than silently picking one.
+          if (dryRunFlag && applyFlag) {
+            console.error("Cannot pass both --dry-run and --apply. Choose one.");
+            process.exit(1);
+          }
+
+          // Safe default: dry-run when neither flag is given.
+          const apply = applyFlag;
+          const memoryDir = orchestrator.config.memoryDir;
+
+          if (!apply) {
+            const plan = await planSessionTranscriptMigration({ memoryDir });
+            console.log("=== Session Transcript Migration (DRY RUN) ===\n");
+            if (!dryRunFlag && !applyFlag) {
+              console.log("No flag given — defaulting to --dry-run. Pass --apply to migrate.\n");
+            }
+            console.log(`transcripts dir: ${plan.transcriptsDir}`);
+            console.log(`files to migrate: ${plan.files.length}`);
+            console.log(`distinct sessions: ${plan.distinctSessions}`);
+            console.log(`entries to move: ${plan.movedEntries}`);
+            if (plan.files.length > 0) {
+              console.log("\nPlanned splits:");
+              for (const file of plan.files) {
+                console.log(`- ${file.sourceRelPath}`);
+                for (const group of file.groups) {
+                  console.log(
+                    `    ${group.entryCount} entr${group.entryCount === 1 ? "y" : "ies"} → ${group.destDir} (${group.legacy ? "legacy" : "session"})`,
+                  );
+                }
+                if (file.unmovableLines > 0) {
+                  console.log(`    ${file.unmovableLines} unmovable line(s) retained in source`);
+                }
+              }
+            }
+            console.log("\nDRY RUN — no files changed.");
+            return;
+          }
+
+          const result = await migrateSessionTranscripts({ memoryDir, apply: true });
+          console.log("=== Session Transcript Migration (APPLY) ===\n");
+          console.log(`files rewritten: ${result.filesRewritten}`);
+          console.log(`files removed: ${result.filesRemoved}`);
+          console.log(`distinct sessions: ${result.plan.distinctSessions}`);
+          console.log(`entries moved: ${result.plan.movedEntries}`);
+          if (result.manifestPath) {
+            console.log(`manifest: ${result.manifestPath}`);
+          }
+          if (result.errors.length > 0) {
+            console.log("\nErrors:");
+            for (const err of result.errors) {
+              console.log(`- ${err}`);
+            }
+            process.exitCode = 1;
+            return;
+          }
+          console.log("\nOK");
+        });
+
       // Checkpoint command
       cmd
         .command("checkpoint")

package/src/index.ts

@@ -324,6 +324,24 @@ export { MeilisearchBackend } from "./search/meilisearch-backend.js";
 export { buildEntityRecallSection } from "./entity-retrieval.js";
 export { resolvePrincipal } from "./namespaces/principal.js";
 
+// ---------------------------------------------------------------------------
+// Session identity / transcript pathing (issue #1496)
+// ---------------------------------------------------------------------------
+
+// Shared, deterministic session-key → storage-path resolution. Exported so
+// downstream consumers (the @remnic/bench adapter + its tests, host adapters)
+// resolve transcript directories through the SAME layer the core writer uses
+// instead of hard-coding `other/default` (rule #20, #22, #26).
+export {
+  SESSION_CHANNEL_TYPE,
+  parseSessionIdentity,
+  sessionStoragePaths,
+  legacyParserReadbackDir,
+  type SessionIdentity,
+  type SessionStoragePaths,
+} from "./session-identity.js";
+export { storagePathHash } from "./storage-paths.js";
+
 // ---------------------------------------------------------------------------
 // Trust zones
 // ---------------------------------------------------------------------------

package/src/session-identity.test.ts

@@ -0,0 +1,130 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  LEGACY_FALLBACK_CHANNEL_ID,
+  LEGACY_FALLBACK_CHANNEL_TYPE,
+  SESSION_CHANNEL_TYPE,
+  legacyParserReadbackDir,
+  parseSessionIdentity,
+  sessionStoragePaths,
+} from "./session-identity.js";
+
+test("legacy agent:<id>:main keeps main/default channel identity", () => {
+  const id = parseSessionIdentity("agent:generalist:main");
+  assert.equal(id.legacy, true);
+  assert.equal(id.channelType, "main");
+  assert.equal(id.channelId, "default");
+  assert.equal(id.canonicalSessionKey, "agent:generalist:main");
+});
+
+test("legacy discord channel keeps discord/<channelId> identity", () => {
+  const id = parseSessionIdentity("agent:generalist:discord:channel:998877");
+  assert.equal(id.legacy, true);
+  assert.equal(id.channelType, "discord");
+  assert.equal(id.channelId, "998877");
+});
+
+test("legacy slack channel keeps slack/<channelId> identity", () => {
+  const id = parseSessionIdentity("agent:generalist:slack:channel:C12345");
+  assert.equal(id.legacy, true);
+  assert.equal(id.channelType, "slack");
+  assert.equal(id.channelId, "C12345");
+});
+
+test("legacy cron job keeps cron/<jobId> identity", () => {
+  const id = parseSessionIdentity("agent:generalist:cron:nightly-sync");
+  assert.equal(id.legacy, true);
+  assert.equal(id.channelType, "cron");
+  assert.equal(id.channelId, "nightly-sync");
+});
+
+test("arbitrary key becomes a first-class session/<hash> identity, never other/default", () => {
+  const id = parseSessionIdentity("pi-geek:abc123");
+  assert.equal(id.legacy, false);
+  assert.equal(id.channelType, SESSION_CHANNEL_TYPE);
+  assert.notEqual(id.channelType, LEGACY_FALLBACK_CHANNEL_TYPE);
+  assert.notEqual(id.channelId, LEGACY_FALLBACK_CHANNEL_ID);
+  assert.match(id.channelId, /^[0-9a-f]{16}$/);
+});
+
+test("distinct arbitrary keys get distinct, collision-resistant hashes", () => {
+  const geek = parseSessionIdentity("pi-geek:abc123");
+  const friend = parseSessionIdentity("pi-friend:def456");
+  assert.notEqual(geek.channelId, friend.channelId);
+});
+
+test("identity is deterministic for the same key", () => {
+  const a = parseSessionIdentity("pi-geek:abc123");
+  const b = parseSessionIdentity("pi-geek:abc123");
+  assert.deepEqual(a, b);
+});
+
+test("a bare token without the agent prefix is treated as arbitrary, not legacy", () => {
+  // "foo:bar:baz" must NOT be misread as channelType="baz".
+  const id = parseSessionIdentity("foo:bar:baz");
+  assert.equal(id.legacy, false);
+  assert.equal(id.channelType, SESSION_CHANNEL_TYPE);
+});
+
+test("empty session key resolves without throwing", () => {
+  const id = parseSessionIdentity("");
+  assert.equal(id.legacy, false);
+  assert.equal(id.channelType, SESSION_CHANNEL_TYPE);
+  assert.equal(typeof id.channelId, "string");
+});
+
+test("sessionStoragePaths routes arbitrary keys to session/<hash>", () => {
+  const paths = sessionStoragePaths("pi-geek:abc123");
+  assert.equal(paths.channelType, SESSION_CHANNEL_TYPE);
+  assert.match(paths.dir, /^session\/[0-9a-f]{16}$/);
+});
+
+test("sessionStoragePaths keeps legacy main at main/default", () => {
+  const paths = sessionStoragePaths("agent:generalist:main");
+  assert.equal(paths.dir, "main/default");
+});
+
+test("two arbitrary keys never share a storage dir", () => {
+  const a = sessionStoragePaths("pi-geek:abc123");
+  const b = sessionStoragePaths("pi-friend:def456");
+  assert.notEqual(a.dir, b.dir);
+  assert.notEqual(a.dir, "other/default");
+  assert.notEqual(b.dir, "other/default");
+});
+
+test("display label strips control characters and separators", () => {
+  const id = parseSessionIdentity("pi-geek:abc/123");
+  assert.ok(!id.displayLabel.includes("/"));
+  assert.ok(id.displayLabel.length > 0);
+});
+
+test("legacyParserReadbackDir reconstructs the OLD parser dir for >=3-part keys", () => {
+  // foo:bar:baz → channelType=baz, channelId=default
+  assert.equal(legacyParserReadbackDir("foo:bar:baz"), "baz/default");
+  // foo:bar:baz:qux → channelType=baz, channelId=qux
+  assert.equal(legacyParserReadbackDir("foo:bar:baz:qux"), "baz/qux");
+});
+
+test("legacyParserReadbackDir returns undefined for <3-part keys (old build used other/default)", () => {
+  assert.equal(legacyParserReadbackDir("pi-geek:abc123"), undefined);
+  assert.equal(legacyParserReadbackDir("bare"), undefined);
+  assert.equal(legacyParserReadbackDir(""), undefined);
+});
+
+test("readbackDirs for a >=3-part arbitrary key include other/default AND the old parser dir", () => {
+  const paths = sessionStoragePaths("foo:bar:baz");
+  assert.match(paths.dir, /^session\/[0-9a-f]{16}$/);
+  assert.ok(paths.readbackDirs.includes("other/default"));
+  assert.ok(paths.readbackDirs.includes("baz/default"));
+});
+
+test("readbackDirs for a 2-part arbitrary key include only other/default", () => {
+  const paths = sessionStoragePaths("pi-geek:abc123");
+  assert.deepEqual(paths.readbackDirs, ["other/default"]);
+});
+
+test("legacy agent:<id>:... keys expose no read-back dirs (their location never moved)", () => {
+  assert.deepEqual(sessionStoragePaths("agent:generalist:main").readbackDirs, []);
+  assert.deepEqual(sessionStoragePaths("agent:generalist:discord:channel:998877").readbackDirs, []);
+});