@danielsimonjr/memoryjs 1.9.0 → 1.15.0

package/dist/cli/index.js

@@ -495,7 +495,7 @@ var init_indexes = __esm({
 });
 
 // src/utils/errors.ts
-var KnowledgeGraphError, EntityNotFoundError, RelationNotFoundError, ValidationError, CycleDetectedError, InvalidImportanceError, FileOperationError, InsufficientEntitiesError, RefConflictError, LowEntropyContentError, OperationCancelledError;
+var KnowledgeGraphError, EntityNotFoundError, RelationNotFoundError, ValidationError, CycleDetectedError, InvalidImportanceError, FileOperationError, InsufficientEntitiesError, RefConflictError, VersionConflictError, LowEntropyContentError, OperationCancelledError;
 var init_errors = __esm({
   "src/utils/errors.ts"() {
     "use strict";
@@ -662,6 +662,31 @@ ${this.suggestions.map((s) => `  - ${s}`).join("\n")}`;
         this.name = "RefConflictError";
       }
     };
+    VersionConflictError = class extends KnowledgeGraphError {
+      entityName;
+      expected;
+      actual;
+      conflictingAgentId;
+      constructor(entityName, expected, actual, conflictingAgentId) {
+        super(
+          `Version conflict on entity '${entityName}': expected v${expected}, found v${actual}`,
+          "VERSION_CONFLICT",
+          {
+            context: { entityName, expected, actual, conflictingAgentId },
+            suggestions: [
+              "Re-fetch the entity to get the current version",
+              "Reconcile your changes with the live state",
+              "Retry the update with the new expectedVersion"
+            ]
+          }
+        );
+        this.name = "VersionConflictError";
+        this.entityName = entityName;
+        this.expected = expected;
+        this.actual = actual;
+        this.conflictingAgentId = conflictingAgentId;
+      }
+    };
     LowEntropyContentError = class extends Error {
       /** Stable error code for programmatic handling */
       code = "LOW_ENTROPY_CONTENT";
@@ -1006,7 +1031,8 @@ var init_schemas = __esm({
       lastModified: isoDateSchema.optional(),
       tags: z.array(tagSchema).optional(),
       importance: importanceSchema.optional(),
-      parentId: entityNameSchema.optional()
+      parentId: entityNameSchema.optional(),
+      contentHash: z.string().length(64).optional()
     }).strict();
     CreateEntitySchema = z.object({
       name: entityNameSchema,
@@ -1018,12 +1044,26 @@ var init_schemas = __esm({
       projectId: z.string().optional(),
       createdAt: isoDateSchema.optional(),
       lastModified: isoDateSchema.optional(),
+      // v1.6.0: Freshness
+      ttl: z.number().optional(),
+      confidence: z.number().min(0).max(1).optional(),
       // v1.8.0: Memory versioning fields
       version: z.number().int().positive().optional(),
       parentEntityName: z.string().optional(),
       rootEntityName: z.string().optional(),
       isLatest: z.boolean().optional(),
-      supersededBy: z.string().optional()
+      supersededBy: z.string().optional(),
+      // v1.11.0: Memory Engine dedup
+      contentHash: z.string().length(64).optional(),
+      // η.4.4: Bitemporal validity
+      validFrom: z.string().optional(),
+      validUntil: z.string().optional(),
+      observationMeta: z.array(z.object({
+        content: z.string(),
+        validFrom: z.string().optional(),
+        validUntil: z.string().optional(),
+        recordedAt: z.string().optional()
+      })).optional()
     }).strict();
     UpdateEntitySchema = z.object({
       entityType: entityTypeSchema.optional(),
@@ -1033,7 +1073,21 @@ var init_schemas = __esm({
       parentId: entityNameSchema.optional(),
       // v1.8.0: Memory versioning fields
       isLatest: z.boolean().optional(),
-      supersededBy: z.string().optional()
+      supersededBy: z.string().optional(),
+      rootEntityName: entityNameSchema.optional(),
+      parentEntityName: entityNameSchema.optional(),
+      version: z.number().int().min(1).optional(),
+      // v1.11.0: Memory Engine dedup
+      contentHash: z.string().length(64).optional(),
+      // η.4.4: Temporal Versioning expansion
+      validFrom: z.string().optional(),
+      validUntil: z.string().optional(),
+      observationMeta: z.array(z.object({
+        content: z.string(),
+        validFrom: z.string().optional(),
+        validUntil: z.string().optional(),
+        recordedAt: z.string().optional()
+      })).optional()
     }).strict();
     RelationSchema = z.object({
       from: entityNameSchema,
@@ -1107,7 +1161,18 @@ var init_schemas = __esm({
       entityType: entityTypeSchema.optional()
     }).strict();
     ImportFormatSchema = z.enum(["json", "csv", "graphml"]);
-    ExtendedExportFormatSchema = z.enum(["json", "csv", "graphml", "gexf", "dot", "markdown", "mermaid"]);
+    ExtendedExportFormatSchema = z.enum([
+      "json",
+      "csv",
+      "graphml",
+      "gexf",
+      "dot",
+      "markdown",
+      "mermaid",
+      "turtle",
+      "rdf-xml",
+      "json-ld"
+    ]);
     MergeStrategySchema = z.enum(["replace", "skip", "merge", "fail"]);
     ExportFilterSchema = z.object({
       startDate: isoDateSchema.optional(),
@@ -1251,17 +1316,20 @@ function escapeCsvFormula(field) {
   }
   return str;
 }
-function validateFilePath(filePath, baseDir = process.cwd(), confineToBase = false) {
-  const normalized = path2.normalize(filePath);
-  const absolute = path2.isAbsolute(normalized) ? normalized : path2.join(baseDir, normalized);
-  const finalNormalized = path2.normalize(absolute);
-  const segments = finalNormalized.split(path2.sep);
-  if (segments.includes("..")) {
+function validateFilePath(filePath, baseDir = process.cwd(), confineToBase = true) {
+  if (filePath.split(/[/\\]/).includes("..")) {
     throw new FileOperationError(
       `Path traversal detected in file path: ${filePath}`,
       filePath
     );
   }
+  const finalNormalized = path2.resolve(baseDir, filePath);
+  if (finalNormalized.split(path2.sep).includes("..")) {
+    throw new FileOperationError(
+      `Path traversal detected in file path after resolution: ${filePath}`,
+      filePath
+    );
+  }
   if (confineToBase) {
     const resolvedBase = path2.resolve(baseDir) + path2.sep;
     if (!finalNormalized.startsWith(resolvedBase) && finalNormalized !== resolvedBase.slice(0, -1)) {
@@ -1831,7 +1899,7 @@ var init_StreamingExporter = __esm({
        * @throws {FileOperationError} If path traversal is detected
        */
       constructor(filePath) {
-        this.validatedFilePath = validateFilePath(filePath);
+        this.validatedFilePath = validateFilePath(filePath, void 0, false);
       }
       /**
        * Get the validated file path.
@@ -2434,7 +2502,26 @@ var init_EntityManager = __esm({
        * }
        * ```
        */
-      async updateEntity(name, updates) {
+      /**
+       * Update an entity with optional optimistic-concurrency-control (η.5.5.c).
+       *
+       * Pass `options.expectedVersion` to enforce OCC: the caller asserts the
+       * live entity has a specific `version`. If it differs (because another
+       * agent / consolidation pass / contradiction-resolution incremented it
+       * since the caller fetched), `VersionConflictError` is thrown with the
+       * expected and actual versions. Omit `expectedVersion` for legacy
+       * last-write-wins semantics (the default — backwards-compat).
+       *
+       * On a successful OCC-guarded write, `version` is auto-incremented:
+       * `(entity.version ?? 1) + 1`. This makes OCC composable with the
+       * existing v1.8.0 supersession-driven version increments.
+       *
+       * **Caveat**: a `ConsolidationScheduler` running in the background can
+       * increment `version` between caller fetch and update, producing
+       * spurious conflicts. Don't cache `expectedVersion` across scheduler
+       * cycles — fetch immediately before writing.
+       */
+      async updateEntity(name, updates, options) {
         const validation = UpdateEntitySchema.safeParse(updates);
         if (!validation.success) {
           const errors = validation.error.issues.map((e) => `${e.path.join(".")}: ${e.message}`);
@@ -2447,8 +2534,17 @@ var init_EntityManager = __esm({
           if (!entity) {
             throw new EntityNotFoundError(name);
           }
+          if (options?.expectedVersion !== void 0) {
+            const liveVersion = entity.version ?? 1;
+            if (liveVersion !== options.expectedVersion) {
+              throw new VersionConflictError(name, options.expectedVersion, liveVersion);
+            }
+          }
           Object.assign(entity, sanitizeObject(updates));
           entity.lastModified = (/* @__PURE__ */ new Date()).toISOString();
+          if (options?.expectedVersion !== void 0) {
+            entity.version = (entity.version ?? 1) + 1;
+          }
           await this.storage.saveGraph(graph);
           return entity;
         } finally {
@@ -2708,6 +2804,85 @@ var init_EntityManager = __esm({
           release();
         }
       }
+      // ==================== η.4.4: Temporal Versioning ====================
+      //
+      // Mirrors the v1.9.0 RelationManager surface (invalidateRelation /
+      // queryAsOf / timeline) for entities. Orthogonal to v1.8.0 supersession
+      // (`version`/`supersededBy`): supersession answers "which version is
+      // current?", temporal validity answers "was the entity true at time T?".
+      // An entity may be superseded but still valid at a past asOf date, and
+      // vice versa.
+      /**
+       * Mark an entity as no longer valid by setting `validUntil`. Idempotent:
+       * a second call updates the existing `validUntil`. Does not delete the
+       * entity — `entityAsOf` still returns it for past asOf timestamps.
+       *
+       * @param name - The entity to invalidate
+       * @param ended - ISO 8601 timestamp; defaults to current time
+       * @throws {EntityNotFoundError} If no entity exists with the given name
+       */
+      async invalidateEntity(name, ended) {
+        const release = await this.storage.graphMutex.acquire();
+        try {
+          const graph = await this.storage.getGraphForMutation();
+          const entity = graph.entities.find((e) => e.name === name);
+          if (!entity) throw new EntityNotFoundError(name);
+          entity.validUntil = ended ?? (/* @__PURE__ */ new Date()).toISOString();
+          entity.lastModified = (/* @__PURE__ */ new Date()).toISOString();
+          await this.storage.saveGraph(graph);
+        } finally {
+          release();
+        }
+      }
+      /**
+       * Return the entity at a given point in time, or null if it didn't exist
+       * (or was already invalidated) then. An entity is valid at `asOf` when:
+       * - `validFrom` is undefined OR `validFrom` <= asOf
+       * - `validUntil` is undefined OR `validUntil` >= asOf
+       *
+       * @param name - The entity name
+       * @param asOf - ISO 8601 date string
+       * @throws {ValidationError} If `asOf` is not an ISO 8601 date string
+       */
+      async entityAsOf(name, asOf) {
+        if (!/^\d{4}-\d{2}-\d{2}/.test(asOf)) {
+          throw new ValidationError(`asOf must be an ISO 8601 date string, got: '${asOf}'`, []);
+        }
+        const graph = await this.storage.loadGraph();
+        const entity = graph.entities.find((e) => e.name === name);
+        if (!entity) return null;
+        const vf = entity.validFrom;
+        const vu = entity.validUntil;
+        if (vf && vf > asOf) return null;
+        if (vu && vu < asOf) return null;
+        return entity;
+      }
+      /**
+       * Return all temporal versions of an entity in chronological order
+       * (by `validFrom`, with unbounded entities last). When `name` matches
+       * a member of a v1.8.0 supersession chain, returns the full chain
+       * sorted by `validFrom`. Otherwise returns just the named entity (or []).
+       *
+       * @param name - Any entity name in the chain
+       */
+      async entityTimeline(name) {
+        const graph = await this.storage.loadGraph();
+        const entity = graph.entities.find((e) => e.name === name);
+        if (!entity) return [];
+        const rootName = entity.rootEntityName ?? entity.name;
+        const chain = graph.entities.filter(
+          (e) => (e.rootEntityName ?? e.name) === rootName
+        );
+        chain.sort((a, b) => {
+          const aFrom = a.validFrom ?? "";
+          const bFrom = b.validFrom ?? "";
+          if (!aFrom && !bFrom) return 0;
+          if (!aFrom) return 1;
+          if (!bFrom) return -1;
+          return aFrom.localeCompare(bFrom);
+        });
+        return chain;
+      }
     };
   }
 });
@@ -2752,10 +2927,177 @@ var init_IOManager = __esm({
             return this.exportAsMarkdown(graph);
           case "mermaid":
             return this.exportAsMermaid(graph);
+          case "turtle":
+            return this.exportAsTurtle(graph);
+          case "rdf-xml":
+            return this.exportAsRdfXml(graph);
+          case "json-ld":
+            return this.exportAsJsonLd(graph);
           default:
             throw new Error(`Unsupported export format: ${format}`);
         }
       }
+      // -------- η.5.4 Standards Compliance — RDF / Turtle / JSON-LD --------
+      /** IRI for an entity resource. Format: `urn:memoryjs:entity:<percent-encoded-name>`. */
+      entityIri(name) {
+        return `urn:memoryjs:entity:${encodeURIComponent(name)}`;
+      }
+      /** IRI for a relation predicate. Format: `urn:memoryjs:rel:<percent-encoded-type>`. */
+      relationIri(type) {
+        return `urn:memoryjs:rel:${encodeURIComponent(type)}`;
+      }
+      /**
+       * Escape a string for a Turtle `STRING_LITERAL_QUOTE` per W3C Turtle 1.1.
+       * - Named ECHAR escapes for `\\ " \n \r \t \b \f`
+       * - Other C0 control chars (forbidden unescaped in `"..."`) as `\uXXXX`
+       */
+      turtleEscape(s) {
+        return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n").replace(/\r/g, "\\r").replace(/\t/g, "\\t").replace(/\x08/g, "\\b").replace(/\x0c/g, "\\f").replace(
+          /[\x00-\x07\x0B\x0E-\x1F]/g,
+          (c) => `\\u${c.charCodeAt(0).toString(16).toUpperCase().padStart(4, "0")}`
+        );
+      }
+      /**
+       * Test whether a string is a valid XML 1.0 NCName — ASCII subset,
+       * sufficient because `relationIri()` percent-encodes everything else.
+       * RDF/XML requires this for property-element predicate names.
+       */
+      isValidNCName(s) {
+        return /^[A-Za-z_][A-Za-z0-9_\-.]*$/.test(s);
+      }
+      /**
+       * Export as Turtle (W3C RDF 1.1).
+       * - entity → `urn:memoryjs:entity:<name>` resource
+       * - entityType → `rdf:type` with `urn:memoryjs:type:<type>` IRI
+       * - observations → `rdfs:comment` literals
+       * - tags → `dcterms:subject` literals
+       * - createdAt → `dcterms:created` literal
+       * - relation → `<from> <urn:memoryjs:rel:<type>> <to>` triple
+       */
+      exportAsTurtle(graph) {
+        const lines = [];
+        lines.push("@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .");
+        lines.push("@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .");
+        lines.push("@prefix dcterms: <http://purl.org/dc/terms/> .");
+        lines.push("");
+        for (const entity of graph.entities) {
+          const subject = `<${this.entityIri(entity.name)}>`;
+          lines.push(`${subject} a <urn:memoryjs:type:${encodeURIComponent(entity.entityType)}> ;`);
+          lines.push(`  rdfs:label "${this.turtleEscape(entity.name)}" ;`);
+          for (const obs of entity.observations) {
+            lines.push(`  rdfs:comment "${this.turtleEscape(obs)}" ;`);
+          }
+          for (const tag of entity.tags ?? []) {
+            lines.push(`  dcterms:subject "${this.turtleEscape(tag)}" ;`);
+          }
+          if (entity.createdAt) {
+            lines.push(`  dcterms:created "${this.turtleEscape(entity.createdAt)}" ;`);
+          }
+          const last = lines.length - 1;
+          lines[last] = lines[last].replace(/ ;$/, " .");
+        }
+        if (graph.entities.length > 0) lines.push("");
+        for (const relation of graph.relations) {
+          const subject = `<${this.entityIri(relation.from)}>`;
+          const predicate = `<${this.relationIri(relation.relationType)}>`;
+          const object = `<${this.entityIri(relation.to)}>`;
+          lines.push(`${subject} ${predicate} ${object} .`);
+        }
+        return lines.join("\n");
+      }
+      /**
+       * Export as RDF/XML (W3C RDF 1.1 XML serialization).
+       * - Same triple set as Turtle, in XML form
+       * - NCName-valid relation types → property-element under `mjsRel:`
+       * - Otherwise → asserted `mjsRel:link` triple plus `rdf:Statement` reification preserving the original predicate IRI
+       */
+      exportAsRdfXml(graph) {
+        const xmlEscape = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+        const lines = [];
+        lines.push('<?xml version="1.0" encoding="UTF-8"?>');
+        lines.push("<rdf:RDF");
+        lines.push('  xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"');
+        lines.push('  xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#"');
+        lines.push('  xmlns:dcterms="http://purl.org/dc/terms/"');
+        lines.push('  xmlns:mjsRel="urn:memoryjs:rel:">');
+        for (const entity of graph.entities) {
+          lines.push(`  <rdf:Description rdf:about="${xmlEscape(this.entityIri(entity.name))}">`);
+          lines.push(`    <rdf:type rdf:resource="urn:memoryjs:type:${xmlEscape(encodeURIComponent(entity.entityType))}"/>`);
+          lines.push(`    <rdfs:label>${xmlEscape(entity.name)}</rdfs:label>`);
+          for (const obs of entity.observations) {
+            lines.push(`    <rdfs:comment>${xmlEscape(obs)}</rdfs:comment>`);
+          }
+          for (const tag of entity.tags ?? []) {
+            lines.push(`    <dcterms:subject>${xmlEscape(tag)}</dcterms:subject>`);
+          }
+          lines.push("  </rdf:Description>");
+        }
+        for (const relation of graph.relations) {
+          const fromIri = xmlEscape(this.entityIri(relation.from));
+          const toIri = xmlEscape(this.entityIri(relation.to));
+          if (this.isValidNCName(relation.relationType)) {
+            lines.push(`  <rdf:Description rdf:about="${fromIri}">`);
+            lines.push(`    <mjsRel:${xmlEscape(relation.relationType)} rdf:resource="${toIri}"/>`);
+            lines.push("  </rdf:Description>");
+            continue;
+          }
+          const predIri = xmlEscape(this.relationIri(relation.relationType));
+          lines.push(`  <rdf:Description rdf:about="${fromIri}">`);
+          lines.push(`    <mjsRel:link rdf:resource="${toIri}"/>`);
+          lines.push("  </rdf:Description>");
+          lines.push("  <rdf:Description>");
+          lines.push('    <rdf:type rdf:resource="http://www.w3.org/1999/02/22-rdf-syntax-ns#Statement"/>');
+          lines.push(`    <rdf:subject rdf:resource="${fromIri}"/>`);
+          lines.push(`    <rdf:predicate rdf:resource="${predIri}"/>`);
+          lines.push(`    <rdf:object rdf:resource="${toIri}"/>`);
+          lines.push("  </rdf:Description>");
+        }
+        lines.push("</rdf:RDF>");
+        return lines.join("\n");
+      }
+      /**
+       * Export as JSON-LD (JSON for Linking Data).
+       * - `@context` maps memoryjs schema to RDFS + DCTerms vocabularies
+       * - observations/tags use `@container: @set` so each value becomes its own triple (matches Turtle/RDF-XML), not an `rdf:List`
+       * - any JSON-LD parser yields the same RDF graph as the Turtle export
+       */
+      exportAsJsonLd(graph) {
+        const context = {
+          "@vocab": "urn:memoryjs:",
+          rdfs: "http://www.w3.org/2000/01/rdf-schema#",
+          dcterms: "http://purl.org/dc/terms/",
+          name: "rdfs:label",
+          entityType: "@type",
+          observations: { "@id": "rdfs:comment", "@container": "@set" },
+          tags: { "@id": "dcterms:subject", "@container": "@set" },
+          createdAt: "dcterms:created",
+          lastModified: "dcterms:modified",
+          from: { "@id": "urn:memoryjs:rel:from", "@type": "@id" },
+          to: { "@id": "urn:memoryjs:rel:to", "@type": "@id" },
+          relationType: "urn:memoryjs:rel:type"
+        };
+        const doc = {
+          "@context": context,
+          "@graph": [
+            ...graph.entities.map((entity) => ({
+              "@id": this.entityIri(entity.name),
+              name: entity.name,
+              entityType: `urn:memoryjs:type:${encodeURIComponent(entity.entityType)}`,
+              observations: entity.observations,
+              ...entity.tags && entity.tags.length > 0 ? { tags: entity.tags } : {},
+              ...entity.createdAt ? { createdAt: entity.createdAt } : {},
+              ...entity.lastModified ? { lastModified: entity.lastModified } : {}
+            })),
+            ...graph.relations.map((relation) => ({
+              "@id": `urn:memoryjs:relation:${encodeURIComponent(relation.from)}:${encodeURIComponent(relation.relationType)}:${encodeURIComponent(relation.to)}`,
+              from: this.entityIri(relation.from),
+              to: this.entityIri(relation.to),
+              relationType: relation.relationType
+            }))
+          ]
+        };
+        return JSON.stringify(doc, null, 2);
+      }
       /** Export graph with optional brotli compression. */
       async exportGraphWithCompression(graph, format, options) {
         const shouldStream = options?.streaming || options?.outputPath && graph.entities.length >= STREAMING_CONFIG.STREAMING_THRESHOLD;
@@ -2797,7 +3139,7 @@ var init_IOManager = __esm({
       }
       /** Stream export to a file for large graphs. */
       async streamExport(format, graph, options) {
-        const validatedOutputPath = validateFilePath(options.outputPath);
+        const validatedOutputPath = validateFilePath(options.outputPath, void 0, false);
         const exporter = new StreamingExporter(validatedOutputPath);
         let result;
         switch (format) {
@@ -3568,7 +3910,10 @@ var init_IOManager = __esm({
       async restoreFromBackup(backupPath) {
         try {
           validateFilePath(backupPath, this.backupDir, true);
-          await fs.access(backupPath);
+          const stat = await fs.lstat(backupPath);
+          if (stat.isSymbolicLink()) {
+            throw new FileOperationError("Symbolic links are not allowed for backup restore", backupPath);
+          }
           const isCompressed = hasBrotliExtension(backupPath);
           const backupBuffer = await fs.readFile(backupPath);
           let backupContent;
@@ -3598,7 +3943,8 @@ var init_IOManager = __esm({
           validateFilePath(backupPath, this.backupDir, true);
           await fs.unlink(backupPath);
           try {
-            const metaPath = join(dirname(backupPath), `${backupPath.split(/[/\\]/).pop()}.meta.json`);
+            const baseName = backupPath.split(/[/\\]/).pop() ?? "";
+            const metaPath = join(this.backupDir, `${baseName}.meta.json`);
             validateFilePath(metaPath, this.backupDir, true);
             await fs.unlink(metaPath);
           } catch {
@@ -3649,10 +3995,10 @@ var init_IOManager = __esm({
           skippedDuplicates: 0,
           entityNames: []
         };
-        const { createHash } = await import("crypto");
+        const { createHash: createHash2 } = await import("crypto");
         const graph = await this.storage.loadGraph();
         const existingObsSet = new Set(
-          graph.entities.map((e) => createHash("sha256").update(e.observations.join("\n")).digest("hex"))
+          graph.entities.map((e) => createHash2("sha256").update(e.observations.join("\n")).digest("hex"))
         );
         const { EntityManager: EntityManager2 } = await Promise.resolve().then(() => (init_EntityManager(), EntityManager_exports));
         const em = new EntityManager2(this.storage);
@@ -3663,7 +4009,7 @@ var init_IOManager = __esm({
             const chunk = chunks[i];
             const entityName = `${source}-${String(i + 1).padStart(3, "0")}`;
             const observations = chunk.map((m) => `[${m.role}] ${m.content}`);
-            const obsKey = createHash("sha256").update(observations.join("\n")).digest("hex");
+            const obsKey = createHash2("sha256").update(observations.join("\n")).digest("hex");
             if (existingObsSet.has(obsKey)) {
               result.skippedDuplicates++;
               continue;
@@ -3741,19 +4087,24 @@ var init_IOManager = __esm({
           /^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}/m
         ];
         let rawSessions = [content];
+        const MAX_SPLIT_LENGTH = 10 * 1024 * 1024;
+        const splitContent = content.length > MAX_SPLIT_LENGTH ? content.slice(0, MAX_SPLIT_LENGTH) : content;
         for (const delimiter of delimiters) {
-          const globalDelimiter = new RegExp(delimiter.source, delimiter.flags.includes("g") ? delimiter.flags : delimiter.flags + "g");
-          if (globalDelimiter.test(content)) {
-            const lookaheadDelimiter = new RegExp(`(?=${delimiter.source})`, delimiter.flags.replace("g", "").replace("m", "") + "m");
-            const parts = content.split(lookaheadDelimiter);
+          const flags = delimiter.flags.includes("g") ? delimiter.flags : delimiter.flags + "g";
+          const globalDelimiter = new RegExp(delimiter.source, flags);
+          if (globalDelimiter.test(splitContent)) {
+            const lookaheadFlags = delimiter.flags.replace(/[gm]/g, "") + "m";
+            const lookaheadDelimiter = new RegExp(`(?=${delimiter.source})`, lookaheadFlags);
+            const parts = splitContent.split(lookaheadDelimiter);
+            const MAX_PARTS = 1e4;
             if (parts.length > 1) {
-              rawSessions = parts;
+              rawSessions = parts.slice(0, MAX_PARTS);
               break;
             }
-            const splitDelimiter = new RegExp(delimiter.source, delimiter.flags.includes("g") ? delimiter.flags : delimiter.flags + "g");
-            const splitParts = content.split(splitDelimiter);
+            const splitDelimiter = new RegExp(delimiter.source, flags);
+            const splitParts = splitContent.split(splitDelimiter);
             if (splitParts.length > 1) {
-              rawSessions = splitParts;
+              rawSessions = splitParts.slice(0, MAX_PARTS);
               break;
             }
           }
@@ -4606,8 +4957,15 @@ var init_GraphEventEmitter = __esm({
 
 // src/core/GraphStorage.ts
 import { promises as fs2 } from "fs";
+import { randomBytes } from "crypto";
 import { Mutex } from "async-mutex";
-var GraphStorage;
+function copyOptionalPersistedFields(src, dst) {
+  for (const field of OPTIONAL_PERSISTED_ENTITY_FIELDS) {
+    const v = src[field];
+    if (v !== void 0) dst[field] = v;
+  }
+}
+var OPTIONAL_PERSISTED_ENTITY_FIELDS, GraphStorage;
 var init_GraphStorage = __esm({
   "src/core/GraphStorage.ts"() {
     "use strict";
@@ -4617,6 +4975,60 @@ var init_GraphStorage = __esm({
     init_utils();
     init_TransactionManager();
     init_GraphEventEmitter();
+    OPTIONAL_PERSISTED_ENTITY_FIELDS = [
+      // Core Entity (types/types.ts)
+      "tags",
+      "importance",
+      "parentId",
+      "projectId",
+      "version",
+      "parentEntityName",
+      "rootEntityName",
+      "isLatest",
+      "supersededBy",
+      "contentHash",
+      "ttl",
+      "confidence",
+      // η.4.4 temporal versioning expansion
+      "validFrom",
+      "validUntil",
+      "observationMeta",
+      // AgentEntity extension (types/agent-memory.ts)
+      "memoryType",
+      "sessionId",
+      "conversationId",
+      "taskId",
+      "expiresAt",
+      "isWorkingMemory",
+      "promotedAt",
+      "promotedFrom",
+      "markedForPromotion",
+      "accessCount",
+      "lastAccessedAt",
+      "accessPattern",
+      "confirmationCount",
+      "decayRate",
+      "agentId",
+      "visibility",
+      "source",
+      // SessionEntity extension (types/agent-memory.ts)
+      "startedAt",
+      "endedAt",
+      "status",
+      "goalDescription",
+      "taskType",
+      "userIntent",
+      "memoryCount",
+      "consolidatedCount",
+      "previousSessionId",
+      "relatedSessionIds",
+      "outcome",
+      "failureCauses",
+      // ArtifactEntity extension (types/artifact.ts)
+      "artifactType",
+      "toolName",
+      "shortId"
+    ];
     GraphStorage = class {
       /**
        * Mutex for thread-safe access to storage operations.
@@ -4687,7 +5099,7 @@ var init_GraphStorage = __esm({
        * @throws {FileOperationError} If path traversal is detected
        */
       constructor(memoryFilePath) {
-        this.memoryFilePath = validateFilePath(memoryFilePath);
+        this.memoryFilePath = validateFilePath(memoryFilePath, void 0, false);
       }
       // ==================== Phase 10 Sprint 2: Event Emitter Access ====================
       /**
@@ -4713,6 +5125,25 @@ var init_GraphStorage = __esm({
       get events() {
         return this.eventEmitter;
       }
+      /**
+       * Synchronous access to the in-memory cached graph. Returns `null` if the
+       * cache is not yet warm — in which case consumers should call
+       * `loadGraph()` once to populate it and then use this accessor on
+       * subsequent reads.
+       *
+       * Intended for integrations that need a synchronous read path backed by
+       * `GraphStorage`'s already-materialized cache (e.g., the `ObservableDataModel`
+       * adapter consumed by JSON-UI's `DataProvider`, which must supply a
+       * synchronous `snapshot()` to React's `useSyncExternalStore`). Most
+       * callers should prefer `loadGraph()`, which lazy-loads on first call.
+       *
+       * The returned reference is the live cache object — do NOT mutate it.
+       * Use `loadGraph()` for a defensive read or `getGraphForMutation()` for
+       * a mutable copy.
+       */
+      get cachedGraph() {
+        return this.cache;
+      }
       // ==================== Durable File Operations ====================
       /**
        * Write content to file with fsync for durability.
@@ -4720,7 +5151,7 @@ var init_GraphStorage = __esm({
        * @param content - Content to write
        */
       async durableWriteFile(content) {
-        const tmpPath = `${this.memoryFilePath}.tmp.${process.pid}`;
+        const tmpPath = `${this.memoryFilePath}.tmp.${process.pid}.${randomBytes(6).toString("hex")}`;
         const fd = await fs2.open(tmpPath, "w");
         try {
           await fd.write(content);
@@ -4913,15 +5344,7 @@ var init_GraphStorage = __esm({
             createdAt: entity.createdAt,
             lastModified: entity.lastModified
           };
-          if (entity.tags !== void 0) entityData.tags = entity.tags;
-          if (entity.importance !== void 0) entityData.importance = entity.importance;
-          if (entity.parentId !== void 0) entityData.parentId = entity.parentId;
-          if (entity.projectId !== void 0) entityData.projectId = entity.projectId;
-          if (entity.version !== void 0) entityData.version = entity.version;
-          if (entity.parentEntityName !== void 0) entityData.parentEntityName = entity.parentEntityName;
-          if (entity.rootEntityName !== void 0) entityData.rootEntityName = entity.rootEntityName;
-          if (entity.isLatest !== void 0) entityData.isLatest = entity.isLatest;
-          if (entity.supersededBy !== void 0) entityData.supersededBy = entity.supersededBy;
+          copyOptionalPersistedFields(entity, entityData);
           const line = JSON.stringify(entityData);
           try {
             const stat = await fs2.stat(this.memoryFilePath);
@@ -5035,15 +5458,7 @@ var init_GraphStorage = __esm({
               createdAt: e.createdAt,
               lastModified: e.lastModified
             };
-            if (e.tags !== void 0) entityData.tags = e.tags;
-            if (e.importance !== void 0) entityData.importance = e.importance;
-            if (e.parentId !== void 0) entityData.parentId = e.parentId;
-            if (e.projectId !== void 0) entityData.projectId = e.projectId;
-            if (e.version !== void 0) entityData.version = e.version;
-            if (e.parentEntityName !== void 0) entityData.parentEntityName = e.parentEntityName;
-            if (e.rootEntityName !== void 0) entityData.rootEntityName = e.rootEntityName;
-            if (e.isLatest !== void 0) entityData.isLatest = e.isLatest;
-            if (e.supersededBy !== void 0) entityData.supersededBy = e.supersededBy;
+            copyOptionalPersistedFields(e, entityData);
             return JSON.stringify(entityData);
           }),
           // Serialize relations with metadata (Phase 1 Sprint 5)
@@ -5121,15 +5536,7 @@ var init_GraphStorage = __esm({
             createdAt: updatedEntity.createdAt,
             lastModified: updatedEntity.lastModified
           };
-          if (updatedEntity.tags !== void 0) entityData.tags = updatedEntity.tags;
-          if (updatedEntity.importance !== void 0) entityData.importance = updatedEntity.importance;
-          if (updatedEntity.parentId !== void 0) entityData.parentId = updatedEntity.parentId;
-          if (updatedEntity.projectId !== void 0) entityData.projectId = updatedEntity.projectId;
-          if (updatedEntity.version !== void 0) entityData.version = updatedEntity.version;
-          if (updatedEntity.parentEntityName !== void 0) entityData.parentEntityName = updatedEntity.parentEntityName;
-          if (updatedEntity.rootEntityName !== void 0) entityData.rootEntityName = updatedEntity.rootEntityName;
-          if (updatedEntity.isLatest !== void 0) entityData.isLatest = updatedEntity.isLatest;
-          if (updatedEntity.supersededBy !== void 0) entityData.supersededBy = updatedEntity.supersededBy;
+          copyOptionalPersistedFields(updatedEntity, entityData);
           const line = JSON.stringify(entityData);
           try {
             const stat = await fs2.stat(this.memoryFilePath);
@@ -5370,7 +5777,7 @@ var init_SQLiteStorage = __esm({
     init_searchCache();
     init_indexes();
     init_utils();
-    SQLiteStorage = class {
+    SQLiteStorage = class _SQLiteStorage {
       /**
        * Mutex for thread-safe access to storage operations.
        * Prevents concurrent writes from corrupting the cache.
@@ -5424,7 +5831,7 @@ var init_SQLiteStorage = __esm({
        * @throws {FileOperationError} If path traversal is detected
        */
       constructor(dbFilePath) {
-        this.validatedDbFilePath = validateFilePath(dbFilePath);
+        this.validatedDbFilePath = validateFilePath(dbFilePath, void 0, false);
       }
       /**
        * Initialize the database connection and schema.
@@ -5458,7 +5865,9 @@ var init_SQLiteStorage = __esm({
         parentEntityName TEXT,
         rootEntityName TEXT,
         isLatest INTEGER DEFAULT 1,
-        supersededBy TEXT
+        supersededBy TEXT,
+        contentHash TEXT,
+        agentMetadata TEXT
       )
     `);
         this.db.exec(`
@@ -5568,8 +5977,87 @@ var init_SQLiteStorage = __esm({
         if (!columnNames.has("supersededBy")) {
           this.db.exec("ALTER TABLE entities ADD COLUMN supersededBy TEXT");
         }
+        if (!columnNames.has("contentHash")) {
+          this.db.exec("ALTER TABLE entities ADD COLUMN contentHash TEXT");
+        }
+        if (!columnNames.has("agentMetadata")) {
+          this.db.exec("ALTER TABLE entities ADD COLUMN agentMetadata TEXT");
+        }
         this.db.exec(`CREATE INDEX IF NOT EXISTS idx_entities_projectId ON entities(projectId)`);
         this.db.exec(`CREATE INDEX IF NOT EXISTS idx_entities_isLatest ON entities(isLatest)`);
+        this.db.exec(`CREATE INDEX IF NOT EXISTS idx_entities_content_hash ON entities(contentHash)`);
+      }
+      /**
+       * Fields that round-trip through the `agentMetadata` JSON blob column.
+       * Native columns (importance, projectId, version, contentHash, etc.) are
+       * stored separately for SQL-side queryability. Everything else lives in
+       * the blob to avoid schema-migration drift as the type system evolves.
+       * Mirrors `OPTIONAL_PERSISTED_ENTITY_FIELDS` in GraphStorage.ts minus
+       * the fields that already have native columns.
+       */
+      static EXTENSION_FIELDS = [
+        // Core Entity (not in native columns)
+        "ttl",
+        "confidence",
+        // η.4.4 temporal versioning expansion
+        "validFrom",
+        "validUntil",
+        "observationMeta",
+        // AgentEntity (types/agent-memory.ts)
+        "memoryType",
+        "sessionId",
+        "conversationId",
+        "taskId",
+        "expiresAt",
+        "isWorkingMemory",
+        "promotedAt",
+        "promotedFrom",
+        "markedForPromotion",
+        "accessCount",
+        "lastAccessedAt",
+        "accessPattern",
+        "confirmationCount",
+        "decayRate",
+        "agentId",
+        "visibility",
+        "source",
+        // SessionEntity (types/agent-memory.ts)
+        "startedAt",
+        "endedAt",
+        "status",
+        "goalDescription",
+        "taskType",
+        "userIntent",
+        "memoryCount",
+        "consolidatedCount",
+        "previousSessionId",
+        "relatedSessionIds",
+        "outcome",
+        "failureCauses",
+        // ArtifactEntity (types/artifact.ts)
+        "artifactType",
+        "toolName",
+        "shortId"
+      ];
+      /** Build the JSON blob payload for the `agentMetadata` column. */
+      serializeExtensionFields(entity) {
+        const src = entity;
+        const out = {};
+        for (const field of _SQLiteStorage.EXTENSION_FIELDS) {
+          const v = src[field];
+          if (v !== void 0) out[field] = v;
+        }
+        return Object.keys(out).length === 0 ? null : JSON.stringify(out);
+      }
+      /** Inverse of `serializeExtensionFields`. Tolerant of malformed JSON. */
+      parseExtensionFields(blob) {
+        if (!blob) return {};
+        try {
+          const parsed = JSON.parse(blob);
+          return parsed && typeof parsed === "object" ? parsed : {};
+        } catch {
+          return {};
+        }
       }
       /**
        * Load all data from SQLite into memory cache.
@@ -5596,11 +6084,23 @@ var init_SQLiteStorage = __esm({
        * Convert a database row to an Entity object.
        */
       rowToEntity(row) {
+        let observations;
+        let tags;
+        try {
+          observations = JSON.parse(row.observations);
+        } catch {
+          observations = [];
+        }
+        try {
+          tags = row.tags ? JSON.parse(row.tags) : void 0;
+        } catch {
+          tags = void 0;
+        }
         const entity = {
           name: row.name,
           entityType: row.entityType,
-          observations: JSON.parse(row.observations),
-          tags: row.tags ? JSON.parse(row.tags) : void 0,
+          observations,
+          tags,
           importance: row.importance ?? void 0,
           parentId: row.parentId ?? void 0,
           createdAt: row.createdAt,
@@ -5612,6 +6112,9 @@ var init_SQLiteStorage = __esm({
         if (row.rootEntityName != null) entity.rootEntityName = row.rootEntityName;
         if (row.isLatest != null) entity.isLatest = row.isLatest === 1;
         if (row.supersededBy != null) entity.supersededBy = row.supersededBy;
+        if (row.contentHash != null) entity.contentHash = row.contentHash;
+        const ext = this.parseExtensionFields(row.agentMetadata ?? null);
+        Object.assign(entity, ext);
         return entity;
       }
       /**
@@ -5628,8 +6131,18 @@ var init_SQLiteStorage = __esm({
         };
         if (row.weight !== null) relation.weight = row.weight;
         if (row.confidence !== null) relation.confidence = row.confidence;
-        if (row.properties !== null) relation.properties = JSON.parse(row.properties);
-        if (row.metadata !== null) relation.metadata = JSON.parse(row.metadata);
+        if (row.properties !== null) {
+          try {
+            relation.properties = JSON.parse(row.properties);
+          } catch {
+          }
+        }
+        if (row.metadata !== null) {
+          try {
+            relation.metadata = JSON.parse(row.metadata);
+          } catch {
+          }
+        }
         return relation;
       }
       /**
@@ -5710,8 +6223,8 @@ var init_SQLiteStorage = __esm({
             this.db.exec("DELETE FROM relations");
             this.db.exec("DELETE FROM entities");
             const entityStmt = this.db.prepare(`
-          INSERT INTO entities (name, entityType, observations, tags, importance, parentId, createdAt, lastModified, projectId, version, parentEntityName, rootEntityName, isLatest, supersededBy)
-          VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+          INSERT INTO entities (name, entityType, observations, tags, importance, parentId, createdAt, lastModified, projectId, version, parentEntityName, rootEntityName, isLatest, supersededBy, contentHash, agentMetadata)
+          VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
         `);
             for (const entity of graph.entities) {
               entityStmt.run(
@@ -5728,7 +6241,9 @@ var init_SQLiteStorage = __esm({
                 entity.parentEntityName ?? null,
                 entity.rootEntityName ?? null,
                 entity.isLatest === false ? 0 : 1,
-                entity.supersededBy ?? null
+                entity.supersededBy ?? null,
+                entity.contentHash ?? null,
+                this.serializeExtensionFields(entity)
               );
             }
             const relationStmt = this.db.prepare(`
@@ -5776,8 +6291,8 @@ var init_SQLiteStorage = __esm({
         return this.mutex.runExclusive(async () => {
           if (!this.db) throw new Error("Database not initialized");
           const stmt = this.db.prepare(`
-        INSERT OR REPLACE INTO entities (name, entityType, observations, tags, importance, parentId, createdAt, lastModified, projectId, version, parentEntityName, rootEntityName, isLatest, supersededBy)
-        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        INSERT OR REPLACE INTO entities (name, entityType, observations, tags, importance, parentId, createdAt, lastModified, projectId, version, parentEntityName, rootEntityName, isLatest, supersededBy, contentHash, agentMetadata)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
       `);
           stmt.run(
             entity.name,
@@ -5793,7 +6308,9 @@ var init_SQLiteStorage = __esm({
             entity.parentEntityName ?? null,
             entity.rootEntityName ?? null,
             entity.isLatest === false ? 0 : 1,
-            entity.supersededBy ?? null
+            entity.supersededBy ?? null,
+            entity.contentHash ?? null,
+            this.serializeExtensionFields(entity)
           );
           const existingIndex = this.cache.entities.findIndex((e) => e.name === entity.name);
           if (existingIndex >= 0) {
@@ -5882,7 +6399,9 @@ var init_SQLiteStorage = __esm({
           parentEntityName = ?,
           rootEntityName = ?,
           isLatest = ?,
-          supersededBy = ?
+          supersededBy = ?,
+          contentHash = ?,
+          agentMetadata = ?
         WHERE name = ?
       `);
           stmt.run(
@@ -5898,6 +6417,8 @@ var init_SQLiteStorage = __esm({
             entity.rootEntityName ?? null,
             entity.isLatest === false ? 0 : 1,
             entity.supersededBy ?? null,
+            entity.contentHash ?? null,
+            this.serializeExtensionFields(entity),
             entityName
           );
           this.nameIndex.add(entity);
@@ -6697,6 +7218,12 @@ var init_ObservationManager = __esm({
       contradictionDetector;
       linkedEntityManager;
       _autoLinker;
+      /** Lazy provider for the validator — invoking it constructs / fetches
+       * the MemoryValidator. Stored as a thunk so unconditional wiring at
+       * `ManagerContext` construction time costs nothing until the validator
+       * is actually needed (i.e., MEMORY_VALIDATE_ON_STORE flips on AND an
+       * observation gets added). */
+      memoryValidatorProvider;
       /**
        * Enable contradiction detection on addObservations.
        * When a new observation is detected as contradicting an existing one,
@@ -6712,6 +7239,37 @@ var init_ObservationManager = __esm({
       setAutoLinker(autoLinker) {
         this._autoLinker = autoLinker;
       }
+      /**
+       * Wire a `MemoryValidator` provider for the optional pre-storage
+       * validation hook (Phase δ.1, T31). The argument is a thunk so the
+       * validator can be lazy-constructed only when actually needed —
+       * `ManagerContext` wires this unconditionally at construction time so
+       * runtime toggling of `MEMORY_VALIDATE_ON_STORE` works in both
+       * directions, but the validator object itself isn't built until the
+       * first observation is added with the flag on.
+       *
+       * Behaviour when flag is on:
+       * - `duplicate-observation` → blocking; observation skipped with a
+       *   `console.warn`.
+       * - `semantic-contradiction` → ADVISORY; if a `ContradictionDetector`
+       *   is also wired (the v1.8.0 supersede branch), that branch handles
+       *   the case downstream and creates a proper version chain. Filtering
+       *   it here would silently disable supersede semantics.
+       * - `low-confidence` → ADVISORY only.
+       *
+       * Default off — preserves backwards-compat for existing callers.
+       *
+       * Overload: accepts either a validator instance (eager) or a thunk
+       * (lazy). Pass the instance for tests where a stub is convenient;
+       * pass the thunk for production wiring through `ManagerContext`.
+       */
+      setMemoryValidator(validatorOrProvider) {
+        if (typeof validatorOrProvider === "function") {
+          this.memoryValidatorProvider = validatorOrProvider;
+        } else {
+          this.memoryValidatorProvider = () => validatorOrProvider;
+        }
+      }
       /**
        * Resolve deduplication options from explicit parameter and environment variable.
        *
@@ -6780,7 +7338,31 @@ var init_ObservationManager = __esm({
           if (!entity) {
             throw new EntityNotFoundError(o.entityName);
           }
-          const nonExactDuplicates = o.contents.filter((content) => !entity.observations.includes(content));
+          let nonExactDuplicates = o.contents.filter((content) => !entity.observations.includes(content));
+          if (this.memoryValidatorProvider && process.env.MEMORY_VALIDATE_ON_STORE === "true") {
+            const validator = this.memoryValidatorProvider();
+            const passed = [];
+            for (const content of nonExactDuplicates) {
+              const result = await validator.validateConsistency(content, entity);
+              const blockingDup = result.issues.some((i) => i.kind === "duplicate-observation");
+              if (!blockingDup) {
+                passed.push(content);
+                if (!result.isValid) {
+                  const advisories = result.issues.filter((i) => i.kind !== "duplicate-observation").map((i) => i.kind);
+                  if (advisories.length > 0) {
+                    console.warn(
+                      `[ObservationManager] Validator advisory for "${o.entityName}": ${advisories.join(", ")}. ` + (this.contradictionDetector ? "Semantic-contradiction findings will be handled by the v1.8.0 supersede branch." : "No contradiction-detector wired; advisory only.")
+                    );
+                  }
+                }
+              } else {
+                console.warn(
+                  `[ObservationManager] Skipping duplicate observation on entity "${o.entityName}". Suggestions: ${result.suggestions.join("; ")}`
+                );
+              }
+            }
+            nonExactDuplicates = passed;
+          }
           if (nonExactDuplicates.length > 0) {
             if (this.contradictionDetector && this.linkedEntityManager) {
               const contradictions = await this.contradictionDetector.detect(
@@ -6936,6 +7518,74 @@ var init_ObservationManager = __esm({
           await this.storage.saveGraph(graph);
         }
       }
+      // ==================== η.4.4: Temporal Validity ====================
+      //
+      // Per-observation temporal validity via the parallel `observationMeta[]`
+      // array on Entity. Mirrors the entity-level `validFrom`/`validUntil` shape
+      // but indexed by observation content (not array position) so re-ordering
+      // observations doesn't disturb validity windows.
+      /**
+       * Mark a specific observation as no longer valid by setting its
+       * `validUntil`. Creates the parallel `observationMeta[]` entry if absent
+       * (preserves backwards-compat for entities that don't use the bitemporal
+       * axis). Idempotent: a second call updates the existing `validUntil`.
+       *
+       * @throws {EntityNotFoundError} If no entity exists with the given name
+       * @throws {ValidationError} If the observation isn't found on the entity
+       */
+      async invalidateObservation(entityName, content, ended) {
+        const release = await this.storage.graphMutex.acquire();
+        try {
+          const graph = await this.storage.getGraphForMutation();
+          const entity = graph.entities.find((e) => e.name === entityName);
+          if (!entity) throw new EntityNotFoundError(entityName);
+          if (!entity.observations.includes(content)) {
+            throw new ValidationError(
+              `Observation not found on entity '${entityName}'`,
+              [`content: ${JSON.stringify(content).slice(0, 80)}`]
+            );
+          }
+          const ts = ended ?? (/* @__PURE__ */ new Date()).toISOString();
+          if (!entity.observationMeta) entity.observationMeta = [];
+          const existing = entity.observationMeta.find((m) => m.content === content);
+          if (existing) {
+            existing.validUntil = ts;
+          } else {
+            entity.observationMeta.push({ content, validUntil: ts });
+          }
+          entity.lastModified = (/* @__PURE__ */ new Date()).toISOString();
+          await this.storage.saveGraph(graph);
+        } finally {
+          release();
+        }
+      }
+      /**
+       * Return observations valid at a given point in time. An observation
+       * with no meta entry is treated as unbounded (always valid). With a meta
+       * entry, validity rules mirror `EntityManager.entityAsOf`:
+       * - `validFrom` undefined OR `validFrom` <= asOf
+       * - `validUntil` undefined OR `validUntil` >= asOf
+       *
+       * @throws {ValidationError} If `asOf` is not an ISO 8601 date string
+       */
+      async observationsAsOf(entityName, asOf) {
+        if (!/^\d{4}-\d{2}-\d{2}/.test(asOf)) {
+          throw new ValidationError(`asOf must be an ISO 8601 date string, got: '${asOf}'`, []);
+        }
+        const graph = await this.storage.loadGraph();
+        const entity = graph.entities.find((e) => e.name === entityName);
+        if (!entity) return [];
+        const metaByContent = new Map(
+          (entity.observationMeta ?? []).map((m) => [m.content, m])
+        );
+        return entity.observations.filter((obs) => {
+          const meta = metaByContent.get(obs);
+          if (!meta) return true;
+          if (meta.validFrom && meta.validFrom > asOf) return false;
+          if (meta.validUntil && meta.validUntil < asOf) return false;
+          return true;
+        });
+      }
     };
   }
 });
@@ -9619,7 +10269,14 @@ var init_SavedSearchManager = __esm({
         try {
           const data = await fs4.readFile(this.savedSearchesFilePath, "utf-8");
           const lines = data.split("\n").filter((line) => line.trim() !== "");
-          return lines.map((line) => JSON.parse(line));
+          const searches = [];
+          for (const line of lines) {
+            try {
+              searches.push(JSON.parse(line));
+            } catch {
+            }
+          }
+          return searches;
         } catch (error) {
           if (error instanceof Error && "code" in error && error.code === "ENOENT") {
             return [];
@@ -12013,7 +12670,14 @@ var init_TagManager = __esm({
         try {
           const data = await fs5.readFile(this.tagAliasesFilePath, "utf-8");
           const lines = data.split("\n").filter((line) => line.trim() !== "");
-          return lines.map((line) => JSON.parse(line));
+          const aliases = [];
+          for (const line of lines) {
+            try {
+              aliases.push(JSON.parse(line));
+            } catch {
+            }
+          }
+          return aliases;
         } catch (error) {
           if (error instanceof Error && "code" in error && error.code === "ENOENT") {
             return [];
@@ -13247,6 +13911,7 @@ var init_AutoLinker = __esm({
         });
         candidates.sort((a, b) => b.name.length - a.name.length);
         for (const entity of candidates) {
+          if (entity.name.length > 500) continue;
           const escapedName = escapeRegExp(entity.name);
           const flags = opts.caseSensitive ? "" : "i";
           const pattern2 = new RegExp(`\\b${escapedName}\\b`, flags);
@@ -13557,6 +14222,7 @@ var init_FactExtractor = __esm({
 
 // src/core/TransitionLedger.ts
 import { promises as fs7 } from "fs";
+import { randomBytes as randomBytes2 } from "crypto";
 import * as path4 from "path";
 var TransitionLedger;
 var init_TransitionLedger = __esm({
@@ -13591,7 +14257,7 @@ var init_TransitionLedger = __esm({
       async append(event) {
         const fullEvent = {
           ...event,
-          id: `txn_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+          id: `txn_${Date.now()}_${randomBytes2(4).toString("hex")}`,
           timestamp: (/* @__PURE__ */ new Date()).toISOString()
         };
         this.events.push(fullEvent);
@@ -13757,12 +14423,7 @@ var init_TransitionLedger = __esm({
               entityId: event.entity.name,
               field: "entity",
               from: null,
-              to: {
-                entityType: event.entity.entityType,
-                observations: event.entity.observations,
-                tags: event.entity.tags,
-                importance: event.entity.importance
-              }
+              to: this.mapEntityState(event.entity)
             });
           })
         );
@@ -13786,12 +14447,7 @@ var init_TransitionLedger = __esm({
             handleAppend({
               entityId: event.entityName,
               field: "entity",
-              from: event.entity ? {
-                entityType: event.entity.entityType,
-                observations: event.entity.observations,
-                tags: event.entity.tags,
-                importance: event.entity.importance
-              } : null,
+              from: event.entity ? this.mapEntityState(event.entity) : null,
               to: null
             });
           })
@@ -13849,6 +14505,18 @@ var init_TransitionLedger = __esm({
         };
       }
       // ==================== Private Helpers ====================
+      /**
+       * Map entity state to a consistent audit format.
+       * Extracts only the core data fields to avoid metadata noise.
+       */
+      mapEntityState(entity) {
+        return {
+          entityType: entity.entityType,
+          observations: entity.observations,
+          tags: entity.tags,
+          importance: entity.importance
+        };
+      }
       /**
        * Deep equality check for transition values.
        * Handles primitives, arrays, and plain objects.
@@ -14354,6 +15022,9 @@ var init_FreshnessManager = __esm({
 });
 
 // src/agent/DecayEngine.ts
+function tokenize3(text) {
+  return new Set(tokenize2(text));
+}
 var DecayEngine;
 var init_DecayEngine = __esm({
   "src/agent/DecayEngine.ts"() {
@@ -14361,6 +15032,7 @@ var init_DecayEngine = __esm({
     init_esm_shims();
     init_agent_memory();
     init_FreshnessManager();
+    init_textSimilarity();
     DecayEngine = class {
       storage;
       accessTracker;
@@ -14369,15 +15041,20 @@ var init_DecayEngine = __esm({
       constructor(storage, accessTracker, config = {}) {
         this.storage = storage;
         this.accessTracker = accessTracker;
+        const halfLifeHours = config.halfLifeHours ?? 168;
         this.config = {
-          halfLifeHours: config.halfLifeHours ?? 168,
-          // 1 week
+          halfLifeHours,
           importanceModulation: config.importanceModulation ?? true,
           accessModulation: config.accessModulation ?? true,
           minImportance: config.minImportance ?? 0.1,
           ttlExpiredDecayMultiplier: config.ttlExpiredDecayMultiplier ?? 3,
           confidenceDecayRate: config.confidenceDecayRate ?? 1e-3,
-          applyConfidenceToImportance: config.applyConfidenceToImportance ?? false
+          applyConfidenceToImportance: config.applyConfidenceToImportance ?? false,
+          // PRD MEM-01: derive decayRate from halfLifeHours when not given.
+          decayRate: config.decayRate ?? Math.LN2 / (halfLifeHours * 3600),
+          freshnessCoefficient: config.freshnessCoefficient ?? 0.01,
+          relevanceWeight: config.relevanceWeight ?? 0.35,
+          minImportanceThreshold: config.minImportanceThreshold ?? 0.1
         };
         this.freshnessManager = new FreshnessManager(storage, {
           defaultHalfLifeHours: this.config.halfLifeHours
@@ -14518,6 +15195,58 @@ var init_DecayEngine = __esm({
       getFreshnessManager() {
         return this.freshnessManager;
       }
+      // ==================== PRD-aligned Effective Importance (v1.12.0) ====================
+      /**
+       * Calculate effective importance using the Context Engine PRD formula.
+       *
+       * Distinct from `calculateEffectiveImportance` (legacy formula preserved
+       * for `DecayScheduler`, `SearchManager`, `SemanticForget`, etc.).
+       *
+       * Formula:
+       * ```
+       * effective = importance × recency × freshness + relevance_boost
+       *   recency         = e^(−decayRate × age_seconds)
+       *   freshness       = e^(−freshnessCoefficient × seconds_since_last_access)
+       *   relevance_boost = (|query_tokens ∩ turn_tokens| / |query_tokens|) × relevanceWeight
+       * ```
+       *
+       * `importance` is auto-scaled from memoryjs's `[0, 10]` range to PRD's
+       * `[1.0, 3.0]` range via `prd_importance = 1.0 + (memoryjs_importance / 10.0) * 2.0`.
+       *
+       * @param entity         AgentEntity to score.
+       * @param queryContext   Optional query string. When provided, enables the
+       *                       relevance-boost term via token overlap.
+       * @param now            Optional clock override (test injection). Defaults to `Date.now()`.
+       * @returns              Float in `[0, ∞)`. Callers filter via `minImportanceThreshold`.
+       */
+      calculatePrdEffectiveImportance(entity, queryContext, now = Date.now()) {
+        const memoryjsScale = entity.importance ?? 5;
+        const prdImportance = 1 + memoryjsScale / 10 * 2;
+        const createdAtMs = entity.createdAt ? new Date(entity.createdAt).getTime() : now;
+        const ageSeconds = Math.max(0, (now - createdAtMs) / 1e3);
+        const recency = Math.exp(-this.config.decayRate * ageSeconds);
+        const lastAccessMs = entity.lastAccessedAt ? new Date(entity.lastAccessedAt).getTime() : createdAtMs;
+        const sinceAccessSeconds = Math.max(0, (now - lastAccessMs) / 1e3);
+        const freshness = Math.exp(-this.config.freshnessCoefficient * sinceAccessSeconds);
+        let relevanceBoost = 0;
+        if (queryContext && queryContext.length > 0) {
+          const queryTokens = tokenize3(queryContext);
+          if (queryTokens.size > 0) {
+            const turnText = (entity.observations ?? []).join(" ");
+            const turnTokens = tokenize3(turnText);
+            let intersection = 0;
+            for (const t of queryTokens) {
+              if (turnTokens.has(t)) intersection += 1;
+            }
+            relevanceBoost = intersection / queryTokens.size * this.config.relevanceWeight;
+          }
+        }
+        return prdImportance * recency * freshness + relevanceBoost;
+      }
+      /** Read-only accessor for the configured PRD `min_importance_threshold`. */
+      get prdMinImportanceThreshold() {
+        return this.config.minImportanceThreshold;
+      }
       // ==================== Decayed Memory Queries ====================
       /**
        * Get memories that have decayed below threshold.
@@ -15136,16 +15865,14 @@ var init_SummarizationService = __esm({
        * @returns Array of summaries (one per group)
        */
       async summarizeGroups(groups) {
-        const summaries = [];
-        for (const group of groups) {
-          if (group.length === 1) {
-            summaries.push(group[0]);
-          } else {
-            const summary = await this.summarize(group);
-            summaries.push(summary);
-          }
-        }
-        return summaries;
+        return Promise.all(
+          groups.map((group) => {
+            if (group.length === 1) {
+              return group[0];
+            }
+            return this.summarize(group);
+          })
+        );
       }
       // ==================== Configuration Access ====================
       /**
@@ -15984,7 +16711,7 @@ var init_ContextWindowManager = __esm({
     init_esm_shims();
     init_agent_memory();
     init_ContextProfileManager();
-    ContextWindowManager = class {
+    ContextWindowManager = class _ContextWindowManager {
       storage;
       salienceEngine;
       config;
@@ -16751,39 +17478,279 @@ var init_ContextWindowManager = __esm({
             console.error("[ContextWindowManager.wakeUp] L1 entity loading failed:", err);
           }
         }
+        if (options.compress && l1) {
+          try {
+            const level = typeof options.compress === "string" ? options.compress : "medium";
+            const compressResult = this.compressForContext(l1, { level });
+            if (compressResult.stats.savedTokens > 0) {
+              l1 = compressResult.compressed;
+            }
+          } catch (err) {
+            console.error("[ContextWindowManager.wakeUp] Compression failed, using uncompressed:", err);
+          }
+        }
         const totalTokens = this.estimateStringTokens(l0) + this.estimateStringTokens(l1);
         return { l0, l1, totalTokens, entityCount };
       }
-    };
-  }
-});
-
-// src/agent/MemoryFormatter.ts
-var MemoryFormatter;
-var init_MemoryFormatter = __esm({
-  "src/agent/MemoryFormatter.ts"() {
-    "use strict";
-    init_esm_shims();
-    MemoryFormatter = class {
-      config;
-      defaultPromptTemplate;
-      constructor(config = {}) {
-        this.config = {
-          defaultMaxTokens: config.defaultMaxTokens ?? 2e3,
-          tokenMultiplier: config.tokenMultiplier ?? 1.3,
-          includeTimestamps: config.includeTimestamps ?? true,
-          includeSalience: config.includeSalience ?? false,
-          includeMemoryType: config.includeMemoryType ?? true,
-          promptTemplate: config.promptTemplate ?? ""
+      // ==================== Context Compression ====================
+      /** Unicode abbreviation map for aggressive-level compression (code keywords). */
+      static COMMON_PATTERNS = {
+        "function ": "\u0192 ",
+        "return ": "\u0280 ",
+        "const ": "\u1D04 ",
+        "export ": "\u1D07 ",
+        "import ": "\u026A ",
+        "interface ": "\u026A\u0274\u1D1B ",
+        "class ": "\u1D04\u029Fs ",
+        "async ": "\u1D00 ",
+        "await ": "\u1D00\u1D21 ",
+        "undefined": "\u1D1C\u0274\u1D05",
+        "null": "\u0274\u1D1C\u029F",
+        "true": "\u1D1B",
+        "false": "\uA730",
+        "```typescript": "```ts",
+        "```javascript": "```js",
+        "## ": "\u2E2B ",
+        "### ": "\u2E2C ",
+        "#### ": "\u2E2D ",
+        '"description"': '"desc"',
+        '"dependencies"': '"deps"',
+        '"devDependencies"': '"devDeps"',
+        '"repository"': '"repo"',
+        '"homepage"': '"home"',
+        '"keywords"': '"keys"',
+        '"license"': '"lic"',
+        '"version"': '"ver"',
+        '"required"': '"req"',
+        '"optional"': '"opt"',
+        '"default"': '"def"',
+        '"example"': '"ex"',
+        '"properties"': '"props"',
+        '"additionalProperties"': '"addProps"',
+        "node_modules/": "nm/",
+        "src/": "s/",
+        "dist/": "d/",
+        "test/": "t/",
+        "tests/": "t/",
+        ".typescript": ".ts",
+        ".javascript": ".js"
+      };
+      /**
+       * Compress text for token-efficient context loading.
+       * Finds repeated substrings, replaces with paragraph-sign codes, generates a legend.
+       * Inspired by the CTON compress-for-context tool.
+       */
+      compressForContext(text, options) {
+        const level = options?.level ?? "medium";
+        let compressed = text;
+        const legend = {};
+        if (level !== "light") {
+          compressed = compressed.replace(/[ \t]+/g, " ");
+          compressed = compressed.replace(/\n{3,}/g, "\n\n");
+        }
+        if (level === "aggressive") {
+          const patternResult = this.applyCommonPatterns(compressed);
+          compressed = patternResult.text;
+          Object.assign(legend, patternResult.legend);
+        }
+        const minLength2 = level === "light" ? 8 : level === "medium" ? 6 : 5;
+        const minOccurrences = level === "light" ? 4 : 3;
+        const maxSubstrings = level === "light" ? 20 : level === "medium" ? 30 : 36;
+        const substrings = this.findRepeatedSubstrings(compressed, minLength2, minOccurrences, maxSubstrings);
+        if (substrings.length > 0) {
+          const totalSavings = substrings.reduce((sum, s) => sum + s.savings, 0);
+          if (totalSavings > 5) {
+            const result = this.applySubstringCompression(compressed, substrings);
+            Object.assign(legend, result.legend);
+            compressed = result.compressed;
+          }
+        }
+        if (Object.keys(legend).length > 0) {
+          const legendStr = "=== Legend ===\n" + Object.entries(legend).map(([a, f]) => `${a} = ${f}`).join("\n") + "\n=============\n\n";
+          compressed = legendStr + compressed;
+        }
+        const originalTokens = this.estimateStringTokens(text);
+        const hasLegend = Object.keys(legend).length > 0;
+        const compressedTokens = hasLegend ? this.estimateStringTokens(compressed) : originalTokens;
+        const savedTokens = Math.max(0, originalTokens - compressedTokens);
+        return {
+          compressed: hasLegend ? compressed : text,
+          legend,
+          stats: {
+            originalTokens,
+            compressedTokens,
+            savedTokens,
+            savedPercent: originalTokens > 0 ? Math.round(savedTokens / originalTokens * 100) : 0
+          }
         };
-        this.defaultPromptTemplate = `## {name} ({type})
-{observations}
-{metadata}`;
       }
-      // ==================== Prompt Format ====================
       /**
-       * Format memories as text for LLM prompts.
-       *
+       * Compress entities for context loading. Formats entities as compact text,
+       * then applies compression. Sorted by importance descending.
+       */
+      compressEntitiesForContext(entities, options) {
+        const sorted = [...entities].filter((e) => e.entityType !== "profile" && e.entityType !== "diary").sort((a, b) => (b.importance ?? 0) - (a.importance ?? 0));
+        const lines = [];
+        let tokenCount = 0;
+        let entityCount = 0;
+        const maxTokens = options?.maxTokens ?? Infinity;
+        for (const e of sorted) {
+          const obs = e.observations?.slice(0, 3).join("; ") ?? "";
+          const line = `[${e.entityType}] ${e.name}: ${obs}`;
+          const lineTokens = this.estimateStringTokens(line);
+          if (tokenCount + lineTokens > maxTokens) break;
+          lines.push(line);
+          tokenCount += lineTokens;
+          entityCount++;
+        }
+        const raw = lines.join("\n");
+        const result = this.compressForContext(raw, { level: options?.level });
+        return { ...result, entityCount };
+      }
+      // ==================== Compression Helpers ====================
+      /**
+       * Find repeated substrings and calculate compression potential.
+       * Returns substrings sorted by net savings (highest first).
+       * @internal
+       */
+      findRepeatedSubstrings(text, minLength2, minOccurrences, maxSubstrings = 36) {
+        if (text.length < minLength2 * 2) return [];
+        const substringCounts = /* @__PURE__ */ new Map();
+        const MAX_MAP_SIZE = 1e4;
+        const tokens = text.split(/(\s+|[{}()\[\]<>:;,."'`|=])/);
+        outer: for (let n = 1; n <= 6; n++) {
+          for (let i = 0; i <= tokens.length - n; i++) {
+            const ngram = tokens.slice(i, i + n).join("");
+            if (ngram.length < minLength2 || ngram.length > 50) continue;
+            if (/^\s*$/.test(ngram)) continue;
+            if ((ngram.match(/\s/g) || []).length > ngram.length * 0.5) continue;
+            const opens = (ngram.match(/[{(\[<]/g) || []).length;
+            const closes = (ngram.match(/[})\]>]/g) || []).length;
+            if (opens !== closes) continue;
+            substringCounts.set(ngram, (substringCounts.get(ngram) || 0) + 1);
+            if (substringCounts.size >= MAX_MAP_SIZE) break outer;
+          }
+        }
+        const pathRe = /[a-zA-Z0-9_\-./]+\/[a-zA-Z0-9_\-./]+/g;
+        let pathMatch;
+        while ((pathMatch = pathRe.exec(text)) !== null) {
+          const p = pathMatch[0];
+          if (p.length >= minLength2 && substringCounts.size < MAX_MAP_SIZE) {
+            substringCounts.set(p, (substringCounts.get(p) || 0) + 1);
+          }
+        }
+        const candidates = [];
+        for (const [substring, _mapCount] of substringCounts.entries()) {
+          const actualCount = text.split(substring).length - 1;
+          if (actualCount >= minOccurrences) {
+            const abbrevLength = 2;
+            const legendCost = abbrevLength + substring.length + 4;
+            const savingsPerOccurrence = substring.length - abbrevLength;
+            const netSavings = savingsPerOccurrence * actualCount - legendCost;
+            if (netSavings > 5) {
+              candidates.push({ substring, count: actualCount, savings: netSavings });
+            }
+          }
+        }
+        candidates.sort((a, b) => b.savings - a.savings);
+        const selected = [];
+        const usedSubstrings = [];
+        for (const candidate of candidates) {
+          let isTooSimilar = false;
+          const candidateTrimmed = candidate.substring.trim();
+          if (candidateTrimmed.length < 3) continue;
+          for (const used of usedSubstrings) {
+            const usedTrimmed = used.trim();
+            if (used.includes(candidate.substring) || candidate.substring.includes(used)) {
+              isTooSimilar = true;
+              break;
+            }
+            if (candidateTrimmed === usedTrimmed || candidateTrimmed.includes(usedTrimmed) || usedTrimmed.includes(candidateTrimmed)) {
+              isTooSimilar = true;
+              break;
+            }
+            const shorter = candidateTrimmed.length < usedTrimmed.length ? candidateTrimmed : usedTrimmed;
+            const longer = candidateTrimmed.length >= usedTrimmed.length ? candidateTrimmed : usedTrimmed;
+            if (longer.includes(shorter.slice(0, Math.floor(shorter.length * 0.7)))) {
+              isTooSimilar = true;
+              break;
+            }
+          }
+          if (!isTooSimilar) {
+            selected.push(candidate);
+            usedSubstrings.push(candidate.substring);
+            if (selected.length >= maxSubstrings) break;
+          }
+        }
+        return selected;
+      }
+      /**
+       * Apply substring replacements to text.
+       * Applies replacements in savings-descending order (as returned by findRepeatedSubstrings).
+       * @internal
+       */
+      applySubstringCompression(text, substrings) {
+        const legend = {};
+        let compressed = text;
+        substrings.forEach((item, index) => {
+          const abbrev = `\xA7${index.toString(36)}`;
+          legend[abbrev] = item.substring;
+          compressed = compressed.split(item.substring).join(abbrev);
+        });
+        return { compressed, legend };
+      }
+      /**
+       * Apply COMMON_PATTERNS unicode abbreviations (aggressive level only).
+       * @internal
+       */
+      applyCommonPatterns(text) {
+        let result = text;
+        const legend = {};
+        for (const [pattern2, replacement] of Object.entries(_ContextWindowManager.COMMON_PATTERNS)) {
+          try {
+            if (!result.includes(pattern2)) continue;
+            const count = result.split(pattern2).length - 1;
+            const savings = (pattern2.length - replacement.length) * count;
+            if (savings > pattern2.length + replacement.length + 5) {
+              legend[replacement] = pattern2;
+              result = result.split(pattern2).join(replacement);
+            }
+          } catch {
+            continue;
+          }
+        }
+        return { text: result, legend };
+      }
+    };
+  }
+});
+
+// src/agent/MemoryFormatter.ts
+var MemoryFormatter;
+var init_MemoryFormatter = __esm({
+  "src/agent/MemoryFormatter.ts"() {
+    "use strict";
+    init_esm_shims();
+    MemoryFormatter = class {
+      config;
+      defaultPromptTemplate;
+      constructor(config = {}) {
+        this.config = {
+          defaultMaxTokens: config.defaultMaxTokens ?? 2e3,
+          tokenMultiplier: config.tokenMultiplier ?? 1.3,
+          includeTimestamps: config.includeTimestamps ?? true,
+          includeSalience: config.includeSalience ?? false,
+          includeMemoryType: config.includeMemoryType ?? true,
+          promptTemplate: config.promptTemplate ?? ""
+        };
+        this.defaultPromptTemplate = `## {name} ({type})
+{observations}
+{metadata}`;
+      }
+      // ==================== Prompt Format ====================
+      /**
+       * Format memories as text for LLM prompts.
+       *
        * @param memories - Memories to format
        * @param options - Formatting options
        * @returns Formatted text string
@@ -17711,6 +18678,7 @@ var init_WorkingMemoryManager = __esm({
 });
 
 // src/agent/SessionManager.ts
+import { randomBytes as randomBytes3 } from "crypto";
 var SessionManager;
 var init_SessionManager = __esm({
   "src/agent/SessionManager.ts"() {
@@ -17744,7 +18712,7 @@ var init_SessionManager = __esm({
        */
       generateSessionId() {
         const timestamp = Date.now();
-        const random = Math.random().toString(36).substring(2, 8);
+        const random = randomBytes3(4).toString("hex");
         return `session_${timestamp}_${random}`;
       }
       // ==================== Session Creation ====================
@@ -18166,6 +19134,7 @@ var init_SessionManager = __esm({
 });
 
 // src/agent/EpisodicMemoryManager.ts
+import { randomBytes as randomBytes4 } from "crypto";
 var EpisodicRelations, EpisodicMemoryManager;
 var init_EpisodicMemoryManager = __esm({
   "src/agent/EpisodicMemoryManager.ts"() {
@@ -18205,7 +19174,7 @@ var init_EpisodicMemoryManager = __esm({
       async createEpisode(content, options) {
         const now = (/* @__PURE__ */ new Date()).toISOString();
         const timestamp = Date.now();
-        const name = `episode_${timestamp}_${Math.random().toString(36).slice(2, 8)}`;
+        const name = `episode_${timestamp}_${randomBytes4(4).toString("hex")}`;
         const entity = {
           name,
           entityType: options?.entityType ?? "episode",
@@ -20044,35 +21013,41 @@ var init_VisibilityResolver = __esm({
        * @param requestingAgentId - ID of the agent requesting access
        * @param requestingMeta    - Metadata for the requesting agent (undefined = unregistered)
        * @param ownerMeta         - Metadata for the owning agent (undefined = unknown owner)
+       * @param now               - Override for the current time (ISO 8601). Defaults
+       *                            to `new Date().toISOString()`. Useful for tests
+       *                            and for evaluating access at a hypothetical time.
        * @returns True if access is permitted
        */
-      canAccess(memory, requestingAgentId, requestingMeta, ownerMeta) {
+      canAccess(memory, requestingAgentId, requestingMeta, ownerMeta, now) {
+        const currentTime = now ?? (/* @__PURE__ */ new Date()).toISOString();
+        if (memory.visibleFrom && memory.visibleFrom > currentTime) return false;
+        if (memory.visibleUntil && memory.visibleUntil < currentTime) return false;
         if (memory.agentId === requestingAgentId) {
           return true;
         }
         const visibility = memory.visibility ?? "private";
+        let levelGrant = false;
         if (visibility === "public") {
-          return true;
-        }
-        if (!requestingMeta) {
+          levelGrant = true;
+        } else if (!requestingMeta) {
           return false;
-        }
-        if (visibility === "shared") {
-          return true;
-        }
-        if (visibility === "org") {
+        } else if (visibility === "shared") {
+          levelGrant = true;
+        } else if (visibility === "org") {
           const requesterOrg = requestingMeta.groupMembership?.org;
           const ownerOrg = ownerMeta?.groupMembership?.org;
-          if (!requesterOrg || !ownerOrg) return false;
-          return requesterOrg === ownerOrg;
-        }
-        if (visibility === "team") {
+          levelGrant = !!requesterOrg && !!ownerOrg && requesterOrg === ownerOrg;
+        } else if (visibility === "team") {
           const requesterTeams = requestingMeta.groupMembership?.teams ?? [];
           const ownerTeams = ownerMeta?.groupMembership?.teams ?? [];
-          if (requesterTeams.length === 0 || ownerTeams.length === 0) return false;
-          return requesterTeams.some((t) => ownerTeams.includes(t));
+          levelGrant = requesterTeams.length > 0 && ownerTeams.length > 0 && requesterTeams.some((t) => ownerTeams.includes(t));
         }
-        return false;
+        if (!levelGrant) return false;
+        if (memory.allowedRoles && memory.allowedRoles.length > 0) {
+          const role = requestingMeta?.role;
+          if (!role || !memory.allowedRoles.includes(role)) return false;
+        }
+        return true;
       }
     };
   }
@@ -21119,6 +22094,7 @@ var init_SessionCheckpoint = __esm({
 });
 
 // src/agent/WorkThreadManager.ts
+import { randomBytes as randomBytes5 } from "crypto";
 var VALID_TRANSITIONS, CHILD_OF_RELATION, BLOCKED_BY_RELATION, WORK_THREAD_ENTITY_TYPE, WorkThreadManager;
 var init_WorkThreadManager = __esm({
   "src/agent/WorkThreadManager.ts"() {
@@ -21192,7 +22168,7 @@ var init_WorkThreadManager = __esm({
           throw new Error(`Priority must be between 0 and 10, got ${options.priority}`);
         }
         const now = (/* @__PURE__ */ new Date()).toISOString();
-        const id = `thread_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+        const id = `thread_${Date.now()}_${randomBytes5(4).toString("hex")}`;
         const thread = {
           id,
           title,
@@ -22920,8 +23896,9 @@ var init_artifact = __esm({
 });
 
 // src/agent/ArtifactManager.ts
+import { randomBytes as randomBytes6 } from "crypto";
 function generateShortId() {
-  return Math.floor(Math.random() * 65535).toString(16).padStart(4, "0");
+  return randomBytes6(2).toString("hex");
 }
 function formatDateUTC(date) {
   const y = date.getUTCFullYear();
@@ -23707,152 +24684,2289 @@ var init_SemanticForget = __esm({
   }
 });
 
-// src/core/ManagerContext.ts
-import path5 from "path";
-var ManagerContext;
-var init_ManagerContext = __esm({
-  "src/core/ManagerContext.ts"() {
+// src/agent/MemoryEngine.ts
+import { EventEmitter as EventEmitter6 } from "events";
+import { createHash } from "crypto";
+function stripRolePrefix(text) {
+  return text.replace(ROLE_PREFIX_RE, "");
+}
+function longestCommonPrefix(a, b) {
+  const max2 = Math.min(a.length, b.length);
+  let i = 0;
+  while (i < max2 && a[i] === b[i]) i += 1;
+  return a.slice(0, i);
+}
+function tokeniseForDedup(text) {
+  return new Set(
+    text.toLowerCase().replace(/[^\p{L}\p{N}\s]/gu, " ").split(/\s+/).filter((t) => t.length > 0)
+  );
+}
+function hasStoreEmbedding(storage) {
+  return typeof storage?.storeEmbedding === "function";
+}
+var ROLE_PREFIX_RE, MemoryEngine;
+var init_MemoryEngine = __esm({
+  "src/agent/MemoryEngine.ts"() {
     "use strict";
     init_esm_shims();
-    init_StorageFactory();
-    init_EntityManager();
-    init_RelationManager();
-    init_ObservationManager();
-    init_HierarchyManager();
-    init_GraphTraversal();
-    init_SearchManager();
-    init_RankedSearch();
-    init_LLMQueryPlanner();
-    init_LLMSearchExecutor();
-    init_search();
-    init_IOManager();
-    init_TagManager();
-    init_AnalyticsManager();
-    init_CompressionManager();
-    init_ArchiveManager();
-    init_AutoLinker();
-    init_FactExtractor();
-    init_TransitionLedger();
-    init_AccessTracker();
-    init_DecayEngine();
-    init_DecayScheduler();
-    init_ConsolidationScheduler();
-    init_SalienceEngine();
-    init_ContextWindowManager();
-    init_MemoryFormatter();
-    init_AgentMemoryManager();
-    init_ArtifactManager();
-    init_DreamEngine();
-    init_RefIndex();
-    init_ObserverPipeline();
-    init_constants();
-    init_utils();
-    init_ContradictionDetector();
-    init_SemanticForget();
-    ManagerContext = class {
-      // Type as GraphStorage for manager compatibility; actual instance may be SQLiteStorage
-      // which implements the same interface via duck typing
-      storage;
-      defaultProjectId;
-      savedSearchesFilePath;
-      tagAliasesFilePath;
-      refIndexFilePath;
-      _observerPipeline;
-      // ==================== LAZY-INITIALIZED CORE MANAGERS ====================
-      _entityManager;
-      _relationManager;
-      _observationManager;
-      _hierarchyManager;
-      _graphTraversal;
-      _searchManager;
-      _rankedSearch;
-      _ioManager;
-      _tagManager;
-      _analyticsManager;
-      _compressionManager;
-      _archiveManager;
-      _autoLinker;
-      _factExtractor;
-      _transitionLedger;
-      _semanticSearch;
-      _accessTracker;
-      _decayEngine;
-      _decayScheduler;
-      _salienceEngine;
-      _contextWindowManager;
-      _memoryFormatter;
-      _agentMemory;
-      _refIndex;
-      _artifactManager;
-      _consolidationScheduler;
-      _dreamEngine;
-      _llmQueryPlanner;
-      _llmSearchExecutor;
-      _semanticForget;
-      constructor(pathOrOptions) {
-        const opts = typeof pathOrOptions === "string" ? { storagePath: pathOrOptions } : pathOrOptions;
-        this.defaultProjectId = opts.defaultProjectId;
-        const validatedPath = validateFilePath(opts.storagePath);
-        const dir = path5.dirname(validatedPath);
-        const basename2 = path5.basename(validatedPath, path5.extname(validatedPath));
-        this.savedSearchesFilePath = path5.join(dir, `${basename2}-saved-searches.jsonl`);
-        this.tagAliasesFilePath = path5.join(dir, `${basename2}-tag-aliases.jsonl`);
-        this.refIndexFilePath = path5.join(dir, `${basename2}-ref-index.jsonl`);
-        this.storage = createStorageFromPath(validatedPath);
-        if (opts.enableContradictionDetection) {
-          this.initContradictionDetection(opts.contradictionThreshold);
+    ROLE_PREFIX_RE = /^\[role=[a-z]+\]\s*/i;
+    MemoryEngine = class {
+      events = new EventEmitter6();
+      /** Dependencies bundle — populated in constructor, consumed in T5–T10. */
+      deps;
+      /** Resolved config — populated in constructor, consumed in T5–T10. */
+      cfg;
+      constructor(storage, entityManager, episodicMemory, workingMemory, importanceScorer, semanticSearch, embeddingService, config = {}) {
+        if (config.semanticDedupEnabled && !semanticSearch) {
+          throw new TypeError(
+            "MemoryEngine: semanticDedupEnabled=true requires a SemanticSearch instance"
+          );
         }
+        this.deps = {
+          storage,
+          entityManager,
+          episodicMemory,
+          workingMemory,
+          importanceScorer,
+          semanticSearch,
+          embeddingService
+        };
+        this.cfg = {
+          jaccardThreshold: config.jaccardThreshold ?? 0.72,
+          prefixOverlapThreshold: config.prefixOverlapThreshold ?? 0.5,
+          dedupScanWindow: config.dedupScanWindow ?? 200,
+          maxTurnsPerSession: config.maxTurnsPerSession ?? 1e3,
+          semanticDedupEnabled: config.semanticDedupEnabled ?? false,
+          semanticThreshold: config.semanticThreshold ?? 0.92,
+          recentTurnsForImportance: config.recentTurnsForImportance ?? 10
+        };
       }
-      /**
-       * Wire ContradictionDetector to ObservationManager if a semantic search
-       * embedding provider is available. Silently degrades when none is configured.
-       * @internal
-       */
-      initContradictionDetection(threshold) {
-        try {
-          const ss = this.semanticSearch;
-          if (!ss) {
-            console.warn(
-              "[ManagerContext] Contradiction detection requested but no embedding provider is configured. Set MEMORY_EMBEDDING_PROVIDER to enable it."
-            );
-            return;
+      async addTurn(content, options) {
+        const dup = await this.checkDuplicate(content, options.sessionId);
+        if (dup.isDuplicate && dup.match) {
+          this.events.emit("memoryEngine:duplicateDetected", {
+            existingEntity: dup.match,
+            attemptedContent: content,
+            sessionId: options.sessionId,
+            tier: dup.tier
+          });
+          return {
+            entity: dup.match,
+            duplicateDetected: true,
+            duplicateOf: dup.match.name,
+            duplicateTier: dup.tier,
+            importanceScore: dup.match.importance ?? 0
+          };
+        }
+        let importance;
+        if (typeof options.importance === "number") {
+          importance = options.importance;
+        } else {
+          const recentTurns = options.recentTurns ?? await this.loadRecentTurnsForImportance(options.sessionId);
+          importance = this.deps.importanceScorer.score(content, {
+            queryContext: options.queryContext,
+            recentTurns
+          });
+        }
+        const observation = `[role=${options.role}] ${content}`;
+        const entity = await this.deps.episodicMemory.createEpisode(observation, {
+          sessionId: options.sessionId,
+          agentId: options.agentId,
+          importance
+        });
+        const hash = this.computeContentHash(content);
+        await this.deps.storage.updateEntity(entity.name, { contentHash: hash });
+        const enriched = { ...entity, contentHash: hash };
+        if (this.deps.embeddingService && hasStoreEmbedding(this.deps.storage)) {
+          try {
+            const vector = await this.deps.embeddingService.embed(content);
+            const model = this.deps.embeddingService.getModelName?.() ?? "unknown";
+            this.deps.storage.storeEmbedding(entity.name, vector, model);
+          } catch {
           }
-          const detector = new ContradictionDetector(ss, threshold ?? 0.85);
-          this.observationManager.setContradictionDetector(detector, this.entityManager);
-        } catch (err) {
-          console.warn(
-            "[ManagerContext] Could not initialise contradiction detection:",
-            err instanceof Error ? err.message : String(err)
-          );
         }
+        this.events.emit("memoryEngine:turnAdded", {
+          entity: enriched,
+          sessionId: options.sessionId,
+          role: options.role,
+          importance
+        });
+        return { entity: enriched, duplicateDetected: false, importanceScore: importance };
       }
-      // ==================== LAZY ACCESSORS (agent memory + semantic) ====================
-      /** EntityManager - Entity CRUD and tag operations */
-      get entityManager() {
-        return this._entityManager ??= new EntityManager(
-          this.storage,
-          { defaultProjectId: this.defaultProjectId }
+      async loadRecentTurnsForImportance(sessionId) {
+        const recent = await this.getRecentSessionEntities(
+          sessionId,
+          this.cfg.recentTurnsForImportance
         );
+        return recent.map((e) => stripRolePrefix(e.observations[0] ?? ""));
       }
-      /** RelationManager - Relation CRUD */
-      get relationManager() {
-        return this._relationManager ??= new RelationManager(this.storage);
-      }
-      /** ObservationManager - Observation CRUD */
-      get observationManager() {
-        return this._observationManager ??= new ObservationManager(this.storage);
+      async getSessionTurns(sessionId, options = {}) {
+        const graph = await this.deps.storage.loadGraph();
+        let turns = graph.entities.filter(
+          (e) => e.sessionId === sessionId
+        );
+        turns.sort((a, b) => {
+          const aT = a.createdAt ? new Date(a.createdAt).getTime() : 0;
+          const bT = b.createdAt ? new Date(b.createdAt).getTime() : 0;
+          return aT - bT;
+        });
+        if (options.role) {
+          const prefix = `[role=${options.role}]`;
+          turns = turns.filter((e) => (e.observations[0] ?? "").startsWith(prefix));
+        }
+        if (typeof options.limit === "number") {
+          turns = turns.slice(0, options.limit);
+        }
+        return turns;
+      }
+      async checkDuplicate(content, sessionId) {
+        if (this.cfg.semanticDedupEnabled && this.deps.semanticSearch) {
+          const ts = await this.checkTierSemantic(content, sessionId);
+          if (ts.isDuplicate) return ts;
+        }
+        const t1 = await this.checkTierExact(content, sessionId);
+        if (t1.isDuplicate) return t1;
+        const recent = await this.getRecentSessionEntities(sessionId, this.cfg.dedupScanWindow);
+        const t2 = this.checkTierPrefix(content, recent);
+        if (t2.isDuplicate) return t2;
+        const t3 = this.checkTierJaccard(content, recent);
+        if (t3.isDuplicate) return t3;
+        return { isDuplicate: false };
+      }
+      async checkTierSemantic(content, sessionId) {
+        if (!this.deps.semanticSearch) return { isDuplicate: false };
+        const graph = await this.deps.storage.loadGraph();
+        const results = await this.deps.semanticSearch.search(graph, content, 5, this.cfg.semanticThreshold);
+        for (const hit of results) {
+          if (hit.similarity < this.cfg.semanticThreshold) continue;
+          const candidate = hit.entity;
+          if (candidate.sessionId === sessionId) {
+            return { isDuplicate: true, match: candidate, tier: "semantic" };
+          }
+        }
+        return { isDuplicate: false };
+      }
+      computeContentHash(content) {
+        return createHash("sha256").update(content).digest("hex");
+      }
+      async checkTierExact(content, sessionId) {
+        const hash = this.computeContentHash(content);
+        const graph = await this.deps.storage.loadGraph();
+        const candidates = graph.entities.filter(
+          (e) => e.contentHash === hash
+        );
+        const match = candidates.find((e) => e.sessionId === sessionId);
+        if (match) return { isDuplicate: true, match, tier: "exact" };
+        return { isDuplicate: false };
+      }
+      async getRecentSessionEntities(sessionId, windowSize) {
+        const graph = await this.deps.storage.loadGraph();
+        const sessionEntities = graph.entities.filter(
+          (e) => e.sessionId === sessionId
+        );
+        sessionEntities.sort((a, b) => {
+          const aT = a.createdAt ? new Date(a.createdAt).getTime() : 0;
+          const bT = b.createdAt ? new Date(b.createdAt).getTime() : 0;
+          return bT - aT;
+        });
+        return sessionEntities.slice(0, windowSize);
+      }
+      checkTierPrefix(content, candidates) {
+        for (const candidate of candidates) {
+          const candidateContent = stripRolePrefix(candidate.observations[0] ?? "");
+          const shared = longestCommonPrefix(content, candidateContent);
+          const ratio = shared.length / Math.max(content.length, candidateContent.length);
+          if (ratio >= this.cfg.prefixOverlapThreshold) {
+            return { isDuplicate: true, match: candidate, tier: "prefix" };
+          }
+        }
+        return { isDuplicate: false };
+      }
+      checkTierJaccard(content, candidates) {
+        const contentTokens = tokeniseForDedup(content);
+        if (contentTokens.size === 0) return { isDuplicate: false };
+        for (const candidate of candidates) {
+          const candidateContent = stripRolePrefix(candidate.observations[0] ?? "");
+          const candidateTokens = tokeniseForDedup(candidateContent);
+          if (candidateTokens.size === 0) continue;
+          let intersection = 0;
+          for (const token of contentTokens) {
+            if (candidateTokens.has(token)) intersection += 1;
+          }
+          const union = contentTokens.size + candidateTokens.size - intersection;
+          const jaccard3 = union === 0 ? 0 : intersection / union;
+          if (jaccard3 >= this.cfg.jaccardThreshold) {
+            return { isDuplicate: true, match: candidate, tier: "jaccard" };
+          }
+        }
+        return { isDuplicate: false };
+      }
+      async deleteSession(sessionId) {
+        const turns = await this.getSessionTurns(sessionId);
+        if (turns.length === 0) return { deleted: 0 };
+        const names = turns.map((t) => t.name);
+        await this.deps.entityManager.deleteEntities(names);
+        this.events.emit("memoryEngine:sessionDeleted", {
+          sessionId,
+          deletedCount: names.length
+        });
+        return { deleted: names.length };
       }
-      /** HierarchyManager - Entity hierarchy operations */
-      get hierarchyManager() {
-        return this._hierarchyManager ??= new HierarchyManager(this.storage);
+      async listSessions() {
+        const graph = await this.deps.storage.loadGraph();
+        const sessions = /* @__PURE__ */ new Set();
+        for (const e of graph.entities) {
+          const s = e.sessionId;
+          if (s) sessions.add(s);
+        }
+        return Array.from(sessions);
       }
-      /** GraphTraversal - Phase 4 Sprint 6-8: Graph traversal algorithms */
-      get graphTraversal() {
-        return this._graphTraversal ??= new GraphTraversal(this.storage);
+    };
+  }
+});
+
+// src/agent/ImportanceScorer.ts
+function tokenise(text) {
+  return new Set(
+    text.toLowerCase().replace(/[^\p{L}\p{N}\s]/gu, " ").split(/\s+/).filter((t) => t.length > 0)
+  );
+}
+function countIntersection(a, b) {
+  let count = 0;
+  for (const token of a) {
+    if (b.has(token)) count += 1;
+  }
+  return count;
+}
+var ImportanceScorer;
+var init_ImportanceScorer = __esm({
+  "src/agent/ImportanceScorer.ts"() {
+    "use strict";
+    init_esm_shims();
+    ImportanceScorer = class {
+      domainKeywords;
+      lengthWeight;
+      keywordWeight;
+      overlapWeight;
+      constructor(config = {}) {
+        this.domainKeywords = config.domainKeywords ?? /* @__PURE__ */ new Set();
+        this.lengthWeight = config.lengthWeight ?? 0.3;
+        this.keywordWeight = config.keywordWeight ?? 0.4;
+        this.overlapWeight = config.overlapWeight ?? 0.3;
+      }
+      /**
+       * Score new content at creation time.
+       *
+       * PRD MEM-02: "Auto-importance scoring evaluates: content length
+       * (log-scaled), domain keyword presence, query token overlap with
+       * recent turns" (PRD §8 line 409).
+       *
+       * Returns integer in [0, 10] (memoryjs scale). PRD's narrower [1.0, 3.0]
+       * range is out of scope here; the Decay Extensions spec owns the mapping.
+       */
+      score(content, options = {}) {
+        if (content.length === 0) return 0;
+        const contentTokens = tokenise(content);
+        const lengthSignal = Math.min(1, Math.log10(content.length) / 4);
+        const keywordSignal = this.domainKeywords.size > 0 ? countIntersection(contentTokens, this.domainKeywords) / this.domainKeywords.size : 0;
+        const overlapCorpus = [];
+        if (options.queryContext) overlapCorpus.push(options.queryContext);
+        if (options.recentTurns) overlapCorpus.push(...options.recentTurns);
+        let overlapSignal;
+        if (overlapCorpus.length === 0) {
+          overlapSignal = 0.5;
+        } else {
+          const corpusTokens = tokenise(overlapCorpus.join(" "));
+          overlapSignal = contentTokens.size > 0 ? countIntersection(contentTokens, corpusTokens) / contentTokens.size : 0;
+        }
+        const raw = this.lengthWeight * lengthSignal + this.keywordWeight * keywordSignal + this.overlapWeight * overlapSignal;
+        return Math.max(0, Math.min(10, Math.round(raw * 10)));
       }
-      /** SearchManager - All search operations */
-      get searchManager() {
-        return this._searchManager ??= new SearchManager(this.storage, this.savedSearchesFilePath);
+    };
+  }
+});
+
+// src/agent/InMemoryBackend.ts
+function turnToEntity(turn) {
+  const prd = turn.importance;
+  const memoryjsImportance = Math.max(0, Math.min(10, (prd - 1) * 5));
+  return {
+    name: turn.id,
+    entityType: "memory_turn",
+    observations: [turn.content],
+    createdAt: turn.createdAt,
+    lastModified: turn.createdAt,
+    lastAccessedAt: turn.lastAccessedAt,
+    importance: memoryjsImportance,
+    memoryType: "episodic",
+    accessCount: turn.accessCount ?? 0,
+    confidence: 1,
+    confirmationCount: 0,
+    visibility: "private",
+    sessionId: turn.sessionId
+  };
+}
+var InMemoryBackend;
+var init_InMemoryBackend = __esm({
+  "src/agent/InMemoryBackend.ts"() {
+    "use strict";
+    init_esm_shims();
+    InMemoryBackend = class {
+      constructor(decayEngine) {
+        this.decayEngine = decayEngine;
+      }
+      /** Per-session FIFO ordered list of turns. */
+      turns = /* @__PURE__ */ new Map();
+      async add(turn) {
+        const list = this.turns.get(turn.sessionId) ?? [];
+        if (list.some((existing) => existing.content === turn.content)) {
+          return;
+        }
+        list.push(turn);
+        this.turns.set(turn.sessionId, list);
+      }
+      async get_weighted(query, sessionId, options) {
+        const list = this.turns.get(sessionId);
+        if (!list || list.length === 0) return [];
+        const threshold = options?.threshold ?? this.decayEngine.prdMinImportanceThreshold;
+        const limit = options?.limit ?? 10;
+        const scored = list.map((turn) => {
+          const synthetic = turnToEntity(turn);
+          const score = this.decayEngine.calculatePrdEffectiveImportance(
+            synthetic,
+            query
+          );
+          return { turn, score };
+        });
+        return scored.filter((wt) => wt.score >= threshold).sort((a, b) => b.score - a.score).slice(0, limit);
+      }
+      async delete_session(sessionId) {
+        this.turns.delete(sessionId);
+      }
+      async list_sessions() {
+        return Array.from(this.turns.keys());
+      }
+    };
+  }
+});
+
+// src/agent/SQLiteBackend.ts
+function entityToTurn(entity) {
+  const observation = entity.observations?.[0] ?? "";
+  const m = observation.match(/^\[role=([a-z]+)\]\s*(.*)$/i);
+  const role = m?.[1]?.toLowerCase() ?? "user";
+  const content = m?.[2] ?? observation;
+  const memoryjsImportance = entity.importance ?? 5;
+  const prdImportance = 1 + memoryjsImportance / 10 * 2;
+  return {
+    id: entity.name,
+    sessionId: entity.sessionId ?? "",
+    content,
+    role,
+    importance: prdImportance,
+    createdAt: entity.createdAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+    lastAccessedAt: entity.lastAccessedAt,
+    accessCount: entity.accessCount,
+    embedding: void 0,
+    // not exposed via getSessionTurns; future read-path enhancement
+    metadata: void 0
+    // see the metadata-round-trip caveat in the contract test
+  };
+}
+var SQLiteBackend;
+var init_SQLiteBackend = __esm({
+  "src/agent/SQLiteBackend.ts"() {
+    "use strict";
+    init_esm_shims();
+    SQLiteBackend = class {
+      constructor(memoryEngine, decayEngine, options = {}) {
+        this.memoryEngine = memoryEngine;
+        this.decayEngine = decayEngine;
+        this.options = {
+          dedupOnAdd: options.dedupOnAdd ?? true,
+          preserveCallerIds: options.preserveCallerIds ?? false
+        };
+      }
+      options;
+      async add(turn) {
+        if (!this.options.dedupOnAdd) {
+          throw new Error(
+            "SQLiteBackend: dedupOnAdd=false bypass path is not implemented yet. See docs/superpowers/specs/2026-04-16-memory-engine-decay-extensions-design.md"
+          );
+        }
+        const memoryjsImportance = Math.max(0, Math.min(10, (turn.importance - 1) * 5));
+        const result = await this.memoryEngine.addTurn(turn.content, {
+          sessionId: turn.sessionId,
+          role: turn.role,
+          importance: memoryjsImportance
+        });
+        if (this.options.preserveCallerIds && !result.duplicateDetected && turn.id !== result.entity.name) {
+          throw new Error(
+            "SQLiteBackend: preserveCallerIds=true requires storage.renameEntity which is not implemented yet. Default false; see \u03B2.3 spec notes."
+          );
+        }
+      }
+      async get_weighted(query, sessionId, options) {
+        const turns = await this.memoryEngine.getSessionTurns(sessionId);
+        if (turns.length === 0) return [];
+        const threshold = options?.threshold ?? this.decayEngine.prdMinImportanceThreshold;
+        const limit = options?.limit ?? 10;
+        const scored = turns.map((entity) => {
+          const score = this.decayEngine.calculatePrdEffectiveImportance(entity, query);
+          return { turn: entityToTurn(entity), score };
+        });
+        return scored.filter((wt) => wt.score >= threshold).sort((a, b) => b.score - a.score).slice(0, limit);
+      }
+      async delete_session(sessionId) {
+        await this.memoryEngine.deleteSession(sessionId);
+      }
+      async list_sessions() {
+        return await this.memoryEngine.listSessions();
+      }
+    };
+  }
+});
+
+// src/agent/MemoryValidator.ts
+function rawToTyped(c) {
+  const sev = c.similarity >= 0.95 ? "high" : c.similarity >= 0.85 ? "medium" : "low";
+  return {
+    observation1: c.existingObservation,
+    observation2: c.newObservation,
+    conflictType: "factual",
+    severity: sev
+  };
+}
+var MemoryValidator;
+var init_MemoryValidator = __esm({
+  "src/agent/MemoryValidator.ts"() {
+    "use strict";
+    init_esm_shims();
+    MemoryValidator = class {
+      contradictionDetector;
+      lowConfidenceThreshold;
+      constructor(contradictionDetector, config = {}) {
+        this.contradictionDetector = contradictionDetector;
+        this.lowConfidenceThreshold = config.lowConfidenceThreshold ?? 0.4;
+      }
+      /**
+       * Check a new observation against an entity's existing knowledge.
+       * Composite: runs the contradiction detector, plus duplicate detection,
+       * plus low-confidence flag if the entity itself looks unreliable.
+       */
+      async validateConsistency(newObservation, existing) {
+        const issues = [];
+        const suggestions = [];
+        if (existing.observations.includes(newObservation)) {
+          issues.push({
+            kind: "duplicate-observation",
+            message: "Identical observation already present on this entity.",
+            observation: newObservation
+          });
+          suggestions.push("Drop the duplicate; existing observation is unchanged.");
+        }
+        const contradictions = await this.contradictionDetector.detect(existing, [newObservation]);
+        for (const c of contradictions) {
+          issues.push({
+            kind: "semantic-contradiction",
+            message: `New observation semantically contradicts existing observation (similarity ${c.similarity.toFixed(2)}).`,
+            observation: newObservation
+          });
+          suggestions.push(
+            "Either supersede the existing observation (use ContradictionDetector.supersede) or reject the new one."
+          );
+        }
+        const reliability = this.calculateReliability(existing);
+        if (reliability < this.lowConfidenceThreshold) {
+          issues.push({
+            kind: "low-confidence",
+            message: `Entity reliability ${reliability.toFixed(2)} is below threshold ${this.lowConfidenceThreshold}.`
+          });
+        }
+        return {
+          isValid: issues.filter((i) => i.kind !== "low-confidence").length === 0,
+          confidence: 1 - 0.2 * issues.length,
+          // rough confidence drop per issue
+          issues,
+          suggestions
+        };
+      }
+      /**
+       * Detect contradictions within an entity's own observation set.
+       * Delegates to `ContradictionDetector.detect` against a synthetic
+       * "new observations" set (every observation paired against the rest).
+       *
+       * Per ROADMAP §3B.1 spec, returns the extended Contradiction shape
+       * (with `conflictType` + `severity`) — these are derived heuristically
+       * from similarity score because the underlying detector is similarity-
+       * only.
+       */
+      async detectContradictions(entity) {
+        if (entity.observations.length < 2) return [];
+        const raw = await this.contradictionDetector.detect(entity, entity.observations);
+        const out = [];
+        const seen = /* @__PURE__ */ new Set();
+        for (const c of raw) {
+          const key = [c.existingObservation, c.newObservation].sort().join("||");
+          if (seen.has(key)) continue;
+          seen.add(key);
+          out.push(rawToTyped(c));
+        }
+        return out;
+      }
+      /**
+       * Apply feedback to repair an entity by appending a corrective
+       * observation prefixed with `[repair]`. Returns the repaired entity
+       * — does NOT persist. Caller decides via
+       * `EntityManager.updateEntity` or supersede semantics.
+       *
+       * For full `ConflictResolver`-driven repair against a competing
+       * memory, see `repairWithResolver`.
+       */
+      async repairMemory(entity, feedback) {
+        return {
+          ...entity,
+          observations: [...entity.observations, `[repair] ${feedback}`],
+          lastModified: (/* @__PURE__ */ new Date()).toISOString()
+        };
+      }
+      /**
+       * Repair an entity by delegating to a `ConflictResolver`. Constructs
+       * the minimal `ConflictInfo` from a `Contradiction` finding so callers
+       * don't have to hand-build it. Closes the loop spec'd in ROADMAP §3B.1
+       * for `repairMemory` integration.
+       *
+       * @param entity         Primary memory being repaired (must be `AgentEntity`).
+       * @param competing      Competing memory to resolve against.
+       * @param contradiction  Optional similarity score / context. Severity
+       *                       is mapped onto `detectionMethod = 'similarity'`.
+       * @param resolver       The `ConflictResolver` instance.
+       * @param agents         Optional agent-metadata registry (used by the
+       *                       `trusted_agent` strategy). Empty Map is fine
+       *                       for the strategies that don't need it.
+       * @returns The resolved memory per the resolver's verdict.
+       *
+       * Throws when neither input is an `AgentEntity` (resolver requires the
+       * extension fields), or when the resolver itself throws (e.g., no
+       * conflicting memories found — should not happen given we provide both).
+       */
+      async repairWithResolver(entity, competing, resolver, options = {}) {
+        const sim = options.contradiction?.similarity ?? 0.85;
+        const detectionMethod = options.detectionMethod ?? "similarity";
+        const agents = options.agents ?? /* @__PURE__ */ new Map();
+        let suggestedStrategy;
+        if (options.strategy) {
+          suggestedStrategy = options.strategy;
+        } else {
+          const aTs = entity.lastModified ? Date.parse(entity.lastModified) : 0;
+          const bTs = competing.lastModified ? Date.parse(competing.lastModified) : 0;
+          const ageDeltaSeconds = Math.abs(aTs - bTs) / 1e3;
+          suggestedStrategy = ageDeltaSeconds > 60 * 60 * 24 ? "most_recent" : "highest_confidence";
+        }
+        const result = resolver.resolveConflict(
+          {
+            primaryMemory: entity.name,
+            conflictingMemories: [competing.name],
+            detectionMethod,
+            similarityScore: sim,
+            suggestedStrategy,
+            detectedAt: (/* @__PURE__ */ new Date()).toISOString()
+          },
+          [entity, competing],
+          agents
+        );
+        return result.resolvedMemory;
+      }
+      /**
+       * Validate temporal consistency of observations carrying ISO-8601
+       * timestamps. Looks for either explicit `[T=ISO]` prefixes or
+       * `createdAt`-style metadata. Returns `isValid: false` when any
+       * adjacent pair is out of order.
+       *
+       * Synchronous (no I/O); the spec method is sync.
+       */
+      validateTemporalOrder(observations) {
+        const issues = [];
+        const stamped = [];
+        for (let i = 0; i < observations.length; i += 1) {
+          const m = observations[i].match(/\[T=([^\]]+)\]/);
+          if (m) {
+            const ts = Date.parse(m[1]);
+            if (Number.isFinite(ts)) {
+              stamped.push({ idx: i, ts, obs: observations[i] });
+            }
+          }
+        }
+        for (let i = 1; i < stamped.length; i += 1) {
+          if (stamped[i].ts < stamped[i - 1].ts) {
+            issues.push({
+              kind: "temporal-disorder",
+              message: `Observation at index ${stamped[i].idx} has earlier timestamp than index ${stamped[i - 1].idx}.`,
+              observation: stamped[i].obs
+            });
+          }
+        }
+        return {
+          isValid: issues.length === 0,
+          confidence: stamped.length >= 2 ? 0.9 : 0.5,
+          // less confident with sparse stamps
+          issues,
+          suggestions: issues.length > 0 ? ["Re-sort observations by parsed timestamp."] : []
+        };
+      }
+      /**
+       * Reliability score in `[0, 1]`. Composite of:
+       * - the entity's own `confidence` field (default 0.5 when absent),
+       * - confirmation count (asymptotic — diminishing returns past 5),
+       * - inverse decay from creation time (older = slightly less reliable
+       *   absent reinforcement; very gentle, doesn't dominate).
+       *
+       * Read-only; does not persist anything to the entity.
+       */
+      calculateReliability(entity) {
+        const ag = entity;
+        const conf = ag.confidence ?? 0.5;
+        const confirmations = ag.confirmationCount ?? 0;
+        const confFactor = confirmations === 0 ? 0 : 1 - 1 / (1 + confirmations / 5);
+        const created = entity.createdAt ? Date.parse(entity.createdAt) : Date.now();
+        const ageDays = Math.max(0, (Date.now() - created) / (1e3 * 60 * 60 * 24));
+        const agePenalty = Math.min(0.3, ageDays / 300);
+        return Math.max(0, Math.min(1, conf * 0.6 + confFactor * 0.3 - agePenalty * 0.1));
+      }
+    };
+  }
+});
+
+// src/agent/TrajectoryCompressor.ts
+function tokenize4(text) {
+  return new Set(
+    text.toLowerCase().replace(/[^a-z0-9\s]/g, "").split(/\s+/).filter((t) => t.length > 0)
+  );
+}
+function jaccard(a, b) {
+  if (a.size === 0 && b.size === 0) return 0;
+  let inter = 0;
+  for (const t of a) if (b.has(t)) inter += 1;
+  return inter / (a.size + b.size - inter);
+}
+function pickTop3(observations) {
+  if (observations.length <= 3) return observations;
+  const tokens = observations.map(tokenize4);
+  const scores = tokens.map((set, i) => {
+    let overlap = 0;
+    for (let j = 0; j < tokens.length; j += 1) {
+      if (i !== j) {
+        for (const t of set) if (tokens[j].has(t)) overlap += 1;
+      }
+    }
+    return { idx: i, score: overlap };
+  });
+  scores.sort((a, b) => b.score - a.score);
+  return scores.slice(0, 3).map((s) => observations[s.idx]);
+}
+var TrajectoryCompressor;
+var init_TrajectoryCompressor = __esm({
+  "src/agent/TrajectoryCompressor.ts"() {
+    "use strict";
+    init_esm_shims();
+    TrajectoryCompressor = class {
+      contextWindow;
+      redundancyThreshold;
+      constructor(contextWindow, config = {}) {
+        this.contextWindow = contextWindow;
+        this.redundancyThreshold = config.redundancyThreshold ?? 0.7;
+      }
+      /**
+       * Compress an observation sequence into a CompressedMemory.
+       * Strategy: keep observations whose tokens overlap heavily with the
+       * majority (these are the "core" facts), drop low-overlap outliers.
+       * Length-truncate the summary at `maxLength`. No LLM dependency yet —
+       * pluggable later via a summarizer config option.
+       */
+      async distill(observations, options = {}) {
+        const preserveTemporalOrder = options.preserveTemporalOrder ?? true;
+        const maxLength2 = options.maxLength ?? 2e3;
+        void options.preserveEntities;
+        const originalCount = observations.length;
+        if (originalCount === 0) {
+          return {
+            summary: "",
+            keyFacts: [],
+            originalCount: 0,
+            compressionRatio: 0,
+            preservedDetails: [],
+            discardedDetails: []
+          };
+        }
+        const tokenSets = observations.map((o) => tokenize4(o));
+        const scores = tokenSets.map((set, i) => {
+          let overlap = 0;
+          for (let j = 0; j < tokenSets.length; j += 1) {
+            if (i === j) continue;
+            for (const t of set) if (tokenSets[j].has(t)) overlap += 1;
+          }
+          return { idx: i, score: overlap, obs: observations[i] };
+        });
+        const threshold = options.importanceThreshold ?? 0;
+        const kept = scores.filter((s) => s.score >= threshold);
+        const dropped = scores.filter((s) => s.score < threshold);
+        if (preserveTemporalOrder) kept.sort((a, b) => a.idx - b.idx);
+        else kept.sort((a, b) => b.score - a.score);
+        const keyFacts = kept.slice(0, Math.min(kept.length, 10)).map((s) => s.obs);
+        let summary = keyFacts.join(" ");
+        if (summary.length > maxLength2) summary = summary.slice(0, maxLength2).trimEnd() + "\u2026";
+        const totalLength = observations.join(" ").length || 1;
+        return {
+          summary,
+          keyFacts,
+          originalCount,
+          compressionRatio: summary.length / totalLength,
+          preservedDetails: kept.map((s) => s.obs),
+          discardedDetails: dropped.map((s) => s.obs)
+        };
+      }
+      /**
+       * Produce a coarsened view of a set of entities at one of three
+       * granularities. `fine` returns the entities unchanged; `medium`
+       * trims observations to the top-3 most overlap-y per entity;
+       * `coarse` distills each entity's observations into a single summary.
+       */
+      async abstractAtLevel(memories, granularity) {
+        if (granularity === "fine") return memories;
+        const out = [];
+        for (const e of memories) {
+          if (granularity === "medium") {
+            const top3 = pickTop3(e.observations);
+            out.push({ ...e, observations: top3 });
+          } else {
+            const distilled = await this.distill(e.observations, { maxLength: 200 });
+            out.push({ ...e, observations: [distilled.summary] });
+          }
+        }
+        return out;
+      }
+      /**
+       * Compress a working-memory text blob to fit within `maxTokens`.
+       * Delegates to `ContextWindowManager.compressForContext` and chooses
+       * the compression level based on how aggressively we need to shrink.
+       * The `working` parameter is intentionally typed `string` here — the
+       * spec talks about `WorkingMemory` but in practice the compressor
+       * operates on serialized text.
+       */
+      async foldContext(working, maxTokens) {
+        const estTokens = Math.ceil(working.length / 4);
+        if (estTokens <= maxTokens) return working;
+        const ratio = estTokens / maxTokens;
+        const level = ratio > 2 ? "aggressive" : ratio > 1.3 ? "medium" : "light";
+        const result = this.contextWindow.compressForContext(working, { level });
+        return result.compressed;
+      }
+      /**
+       * Identify groups of entities whose observation sets are largely
+       * duplicates. Pairs entities whose union-of-observations Jaccard
+       * exceeds the configured threshold. O(n²) pairwise; suitable for
+       * graphs up to ~1k entities — beyond that, a candidate-blocking
+       * pass on tags/projectId would be the natural extension.
+       *
+       * Algorithmic caveat (greedy single-link): an entity is absorbed
+       * into the FIRST seed it overlaps with above threshold; results
+       * therefore depend on input ordering when an entity would qualify
+       * for multiple seeds. For correctness-critical clustering, use
+       * union-find or complete-link clustering instead.
+       */
+      async findRedundancies(entities) {
+        const groups = [];
+        const visited = /* @__PURE__ */ new Set();
+        for (let i = 0; i < entities.length; i += 1) {
+          if (visited.has(entities[i].name)) continue;
+          const cluster = [entities[i]];
+          const sims = [];
+          visited.add(entities[i].name);
+          for (let j = i + 1; j < entities.length; j += 1) {
+            if (visited.has(entities[j].name)) continue;
+            const sim = jaccard(
+              new Set(entities[i].observations.flatMap((o) => Array.from(tokenize4(o)))),
+              new Set(entities[j].observations.flatMap((o) => Array.from(tokenize4(o))))
+            );
+            if (sim >= this.redundancyThreshold) {
+              cluster.push(entities[j]);
+              sims.push(sim);
+              visited.add(entities[j].name);
+            }
+          }
+          if (cluster.length > 1) {
+            const avg = sims.reduce((a, b) => a + b, 0) / sims.length;
+            groups.push({
+              entities: cluster,
+              canonicalName: cluster[0].name,
+              avgSimilarity: avg
+            });
+          }
+        }
+        return groups;
+      }
+      /**
+       * Collapse a redundancy group into a single canonical entity per
+       * strategy. Doesn't persist — caller is responsible for the actual
+       * `EntityManager.deleteEntities(...)` + `createEntity(merged)` dance
+       * if they want the change durable.
+       */
+      async mergeRedundant(group, strategy) {
+        if (group.entities.length === 0) {
+          throw new Error("TrajectoryCompressor.mergeRedundant: empty group");
+        }
+        let canonical;
+        switch (strategy) {
+          case "keep-newest":
+            canonical = group.entities.reduce((acc, e) => {
+              const epoch = "1970-01-01T00:00:00Z";
+              const accT = Date.parse(acc.lastModified ?? acc.createdAt ?? epoch);
+              const eT = Date.parse(e.lastModified ?? e.createdAt ?? epoch);
+              return Number.isFinite(eT) && eT > (Number.isFinite(accT) ? accT : 0) ? e : acc;
+            });
+            break;
+          case "keep-most-confident":
+            canonical = group.entities.reduce((acc, e) => {
+              const ac = acc.confidence ?? 0;
+              const ec = e.confidence ?? 0;
+              return ec > ac ? e : acc;
+            });
+            break;
+          case "union-observations": {
+            const head = group.entities[0];
+            const allObs = /* @__PURE__ */ new Set();
+            for (const e of group.entities) for (const o of e.observations) allObs.add(o);
+            canonical = { ...head, observations: Array.from(allObs) };
+            break;
+          }
+        }
+        return canonical;
+      }
+    };
+  }
+});
+
+// src/agent/ExperienceExtractor.ts
+function tokenize5(text) {
+  return new Set(
+    text.toLowerCase().replace(/[^a-z0-9\s]/g, "").split(/\s+/).filter((t) => t.length > 2)
+  );
+}
+function countTokens(texts) {
+  const out = /* @__PURE__ */ new Map();
+  for (const text of texts) {
+    for (const tok of tokenize5(text)) {
+      out.set(tok, (out.get(tok) ?? 0) + 1);
+    }
+  }
+  return out;
+}
+function jaccard2(a, b) {
+  if (a.size === 0 && b.size === 0) return 0;
+  let inter = 0;
+  for (const t of a) if (b.has(t)) inter += 1;
+  return inter / (a.size + b.size - inter);
+}
+function trajectoryTokens(t, method) {
+  if (method === "structural") {
+    return new Set(t.actions.map((a) => a.name));
+  }
+  const all2 = /* @__PURE__ */ new Set();
+  for (const o of t.observations) for (const tok of tokenize5(o)) all2.add(tok);
+  return all2;
+}
+function extractField(t, field) {
+  if (field === "outcome") return t.outcome;
+  return t.context[field];
+}
+var ExperienceExtractor;
+var init_ExperienceExtractor = __esm({
+  "src/agent/ExperienceExtractor.ts"() {
+    "use strict";
+    init_esm_shims();
+    ExperienceExtractor = class {
+      patternDetector;
+      minPatternOccurrences;
+      similarityThreshold;
+      constructor(patternDetector, config = {}) {
+        this.patternDetector = patternDetector;
+        this.minPatternOccurrences = config.minPatternOccurrences ?? 2;
+        this.similarityThreshold = config.similarityThreshold ?? 0.6;
+      }
+      /**
+       * Derive rules from contrastive pairs. Strategy: tokens appearing
+       * disproportionately in successes (vs. failures) become condition
+       * antecedents; the next action after the distinguishing token
+       * becomes the rule's recommended action.
+       *
+       * Lightweight — no embeddings or LLMs. Suitable for the "what does
+       * the agent do differently when it succeeds" question at scale.
+       */
+      async extractFromContrastivePairs(success, failure) {
+        if (success.length === 0 || failure.length === 0) return [];
+        const successTokens = countTokens(success.flatMap((t) => t.observations));
+        const failureTokens = countTokens(failure.flatMap((t) => t.observations));
+        const rules = [];
+        for (const [tok, sCount] of successTokens.entries()) {
+          const fCount = failureTokens.get(tok) ?? 0;
+          if (sCount >= 2 && sCount >= 2 * fCount) {
+            const actionCounts = /* @__PURE__ */ new Map();
+            for (const t of success) {
+              if (t.observations.some((o) => o.toLowerCase().includes(tok))) {
+                for (const a of t.actions) {
+                  actionCounts.set(a.name, (actionCounts.get(a.name) ?? 0) + 1);
+                }
+              }
+            }
+            const topAction = Array.from(actionCounts.entries()).sort((a, b) => b[1] - a[1])[0]?.[0] ?? "unknown";
+            rules.push({
+              condition: `observation contains "${tok}"`,
+              action: topAction,
+              confidence: sCount / (sCount + fCount + 1),
+              supportCount: sCount,
+              contraCount: fCount
+            });
+          }
+        }
+        return rules.sort((a, b) => b.confidence - a.confidence).slice(0, 10);
+      }
+      /**
+       * Abstract a pattern across trajectories' observations. Delegates
+       * to `PatternDetector.detectPatterns` and lifts the result onto
+       * the spec's `HeuristicGuideline` shape with trajectory provenance.
+       *
+       * `similarityThreshold` is currently unused by the underlying
+       * `detectPatterns` (it operates on token-template equality, not
+       * similarity); kept in the signature for spec compliance and future
+       * use when an embedding-based variant lands.
+       */
+      async abstractPattern(trajectories, similarityThreshold) {
+        void similarityThreshold;
+        const allObs = trajectories.flatMap((t) => t.observations);
+        const patterns = this.patternDetector.detectPatterns(
+          allObs,
+          this.minPatternOccurrences
+        );
+        if (patterns.length === 0) {
+          return { pattern: "", variables: [], occurrences: 0, sourceTrajectoryIds: [] };
+        }
+        const top = patterns.sort((a, b) => b.occurrences - a.occurrences)[0];
+        const sourceIds = /* @__PURE__ */ new Set();
+        const variableValues = new Set(top.variables);
+        for (const t of trajectories) {
+          for (const o of t.observations) {
+            if (Array.from(variableValues).some((v) => o.includes(v))) {
+              sourceIds.add(t.id);
+              break;
+            }
+          }
+        }
+        return {
+          pattern: top.pattern,
+          variables: top.variables ?? [],
+          occurrences: top.occurrences,
+          sourceTrajectoryIds: Array.from(sourceIds)
+        };
+      }
+      /**
+       * Learn the decision boundary for a binary outcome split. Currently
+       * supports `outcome` field (success vs. failure); other field names
+       * fall back to the `Outcome` lookup. Returns the most-distinguishing
+       * tokens per side.
+       */
+      async learnDecisionBoundary(trajectories, outcomeField) {
+        const positive = trajectories.filter(
+          (t) => extractField(t, outcomeField) === "success"
+        );
+        const negative = trajectories.filter(
+          (t) => extractField(t, outcomeField) === "failure"
+        );
+        const posTokens = countTokens(positive.flatMap((t) => t.observations));
+        const negTokens = countTokens(negative.flatMap((t) => t.observations));
+        const presence = [];
+        const absence = [];
+        for (const [tok, p] of posTokens) {
+          const n = negTokens.get(tok) ?? 0;
+          if (p >= 2 && p >= 2 * n) presence.push(tok);
+        }
+        for (const [tok, n] of negTokens) {
+          const p = posTokens.get(tok) ?? 0;
+          if (n >= 2 && n >= 2 * p) absence.push(tok);
+        }
+        const total = positive.length + negative.length;
+        return {
+          presenceTokens: presence.slice(0, 10),
+          absenceTokens: absence.slice(0, 10),
+          outcomeIfPresent: "success",
+          outcomeIfAbsent: "failure",
+          confidence: total === 0 ? 0 : Math.min(positive.length, negative.length) / total
+        };
+      }
+      /**
+       * Cluster trajectories by the chosen method. Lightweight: no
+       * embeddings — `semantic` and `structural` both use token-Jaccard
+       * with different normalization; `outcome` simply groups by the
+       * `Outcome` value.
+       *
+       * Algorithmic caveat (greedy single-link for semantic/structural):
+       * a trajectory is absorbed into the FIRST seed it overlaps with
+       * above the configured similarity threshold, regardless of whether
+       * a later seed would match more strongly. Results therefore depend
+       * on input ordering, and "chain" clusters (A↔B, B↔C, but A↔C far
+       * apart) can form under low thresholds. The `cohesion` field on
+       * each `TrajectoryCluster` surfaces this — downstream
+       * `synthesizeExperience` already passes cohesion through to
+       * `Experience.confidence`. For higher-quality clustering, a
+       * complete-link or union-find variant would be the natural
+       * extension.
+       */
+      async clusterTrajectories(trajectories, method) {
+        if (trajectories.length === 0) return [];
+        if (method === "outcome") {
+          const groups = /* @__PURE__ */ new Map();
+          for (const t of trajectories) {
+            const arr = groups.get(t.outcome) ?? [];
+            arr.push(t);
+            groups.set(t.outcome, arr);
+          }
+          return Array.from(groups.entries()).map(([outcome, ts], i) => ({
+            id: `cluster-outcome-${i}-${outcome}`,
+            method: "outcome",
+            trajectories: ts,
+            cohesion: 1
+            // outcome equality = perfect cohesion by definition
+          }));
+        }
+        const clusters = [];
+        const sims = [];
+        const visited = /* @__PURE__ */ new Set();
+        for (const t of trajectories) {
+          if (visited.has(t.id)) continue;
+          const cluster = [t];
+          const cSims = [];
+          visited.add(t.id);
+          const tTokens = trajectoryTokens(t, method);
+          for (const u of trajectories) {
+            if (visited.has(u.id)) continue;
+            const sim = jaccard2(tTokens, trajectoryTokens(u, method));
+            if (sim >= this.similarityThreshold) {
+              cluster.push(u);
+              cSims.push(sim);
+              visited.add(u.id);
+            }
+          }
+          clusters.push(cluster);
+          sims.push(cSims);
+        }
+        return clusters.map((cluster, i) => ({
+          id: `cluster-${method}-${i}`,
+          method,
+          trajectories: cluster,
+          cohesion: sims[i].length === 0 ? 1 : sims[i].reduce((a, b) => a + b, 0) / sims[i].length
+        }));
+      }
+      /**
+       * Synthesize a transferable `Experience` from a cluster. Picks the
+       * `type` heuristically (procedure if cluster is action-heavy;
+       * heuristic otherwise) and uses the most-common-pattern across the
+       * cluster as the experience content.
+       */
+      async synthesizeExperience(cluster) {
+        const id = `exp-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        const obs = cluster.trajectories.flatMap((t) => t.observations);
+        const actionCount = cluster.trajectories.reduce((acc, t) => acc + t.actions.length, 0);
+        const type = actionCount > cluster.trajectories.length * 2 ? "procedure" : "heuristic";
+        const patterns = this.patternDetector.detectPatterns(obs, 2);
+        const content = patterns[0]?.pattern ?? obs[0] ?? "";
+        const counts = countTokens(obs);
+        const applicability = Array.from(counts.entries()).sort((a, b) => b[1] - a[1]).slice(0, 5).map(([t]) => t);
+        return {
+          id,
+          type,
+          content,
+          applicability,
+          confidence: cluster.cohesion,
+          sourceTrajectories: cluster.trajectories.map((t) => t.id),
+          createdAt: (/* @__PURE__ */ new Date()).toISOString()
+        };
+      }
+    };
+  }
+});
+
+// src/agent/procedural/ProcedureStore.ts
+function encodeObservations(procedure) {
+  const observations = [];
+  if (procedure.description && procedure.description.trim() !== "") {
+    observations.push(procedure.description);
+  }
+  observations.push(`${STEPS_PREFIX}${JSON.stringify(procedure.steps)}`);
+  observations.push(
+    `${META_PREFIX}${JSON.stringify({
+      triggers: procedure.triggers ?? [],
+      successRate: procedure.successRate ?? 0,
+      executionCount: procedure.executionCount ?? 0
+    })}`
+  );
+  return observations;
+}
+function decodeProcedure(id, observations) {
+  let steps = [];
+  let triggers = [];
+  let successRate = 0;
+  let executionCount = 0;
+  const descriptionLines = [];
+  for (const obs of observations) {
+    if (obs.startsWith(STEPS_PREFIX)) {
+      try {
+        const parsed = JSON.parse(obs.slice(STEPS_PREFIX.length));
+        if (Array.isArray(parsed)) steps = parsed;
+      } catch {
+      }
+    } else if (obs.startsWith(META_PREFIX)) {
+      try {
+        const parsed = JSON.parse(obs.slice(META_PREFIX.length));
+        triggers = parsed.triggers ?? [];
+        successRate = parsed.successRate ?? 0;
+        executionCount = parsed.executionCount ?? 0;
+      } catch {
+      }
+    } else {
+      descriptionLines.push(obs);
+    }
+  }
+  return {
+    id,
+    name: id,
+    description: descriptionLines.join("\n"),
+    steps,
+    triggers,
+    successRate,
+    executionCount
+  };
+}
+var STEPS_PREFIX, META_PREFIX, PROCEDURE_ENTITY_TYPE, ProcedureStore;
+var init_ProcedureStore = __esm({
+  "src/agent/procedural/ProcedureStore.ts"() {
+    "use strict";
+    init_esm_shims();
+    STEPS_PREFIX = "[procedure-steps]:";
+    META_PREFIX = "[procedure-meta]:";
+    PROCEDURE_ENTITY_TYPE = "procedure";
+    ProcedureStore = class {
+      constructor(entityManager) {
+        this.entityManager = entityManager;
+      }
+      /**
+       * Persist a new procedure. The entity name = `procedure.id`. Steps and
+       * metadata are encoded as JSON observations alongside any caller-supplied
+       * description observation. Idempotent on duplicate id (relies on
+       * `EntityManager.createEntities` semantics).
+       */
+      async save(procedure) {
+        const observations = encodeObservations(procedure);
+        await this.entityManager.createEntities([
+          {
+            name: procedure.id,
+            entityType: PROCEDURE_ENTITY_TYPE,
+            observations,
+            tags: ["procedure", ...procedure.triggers ?? []]
+          }
+        ]);
+      }
+      /**
+       * Load a procedure by id, or null if not found. Tolerant of partial
+       * encodings — steps default to `[]`, meta to zeroed fields.
+       */
+      async load(id) {
+        const entity = await this.entityManager.getEntity(id);
+        if (!entity || entity.entityType !== PROCEDURE_ENTITY_TYPE) return null;
+        return decodeProcedure(id, entity.observations);
+      }
+      /**
+       * Replace an existing procedure's steps + metadata. Throws if the
+       * entity doesn't exist or isn't a procedure.
+       */
+      async update(procedure) {
+        await this.entityManager.updateEntity(procedure.id, {
+          observations: encodeObservations(procedure),
+          tags: ["procedure", ...procedure.triggers ?? []]
+        });
+      }
+    };
+  }
+});
+
+// src/agent/procedural/StepSequencer.ts
+var StepSequencer;
+var init_StepSequencer = __esm({
+  "src/agent/procedural/StepSequencer.ts"() {
+    "use strict";
+    init_esm_shims();
+    StepSequencer = class {
+      constructor(procedure) {
+        this.procedure = procedure;
+      }
+      cursor = 0;
+      /** When set, all `current()` / `next()` calls return this fallback chain
+       *  instead of the main steps until cleared. */
+      activeFallback = null;
+      /** Steps in 1-indexed order. Read-only. */
+      get steps() {
+        return this.procedure.steps;
+      }
+      /** Index of the next step to execute (0-based). Public for tests. */
+      get cursorIndex() {
+        return this.cursor;
+      }
+      /** Whether all main-track steps have been consumed. Fallbacks may still run. */
+      isComplete() {
+        return this.activeFallback === null && this.cursor >= this.procedure.steps.length;
+      }
+      /** Return the step about to execute, or null if exhausted. */
+      current() {
+        if (this.activeFallback) return this.activeFallback;
+        return this.procedure.steps[this.cursor] ?? null;
+      }
+      /**
+       * Advance the cursor and return the new current step (or null when
+       * complete). Clears any active fallback — fallbacks are single-step
+       * by design; deeper branching needs a nested fallback in the step's
+       * `fallback.fallback`.
+       */
+      next() {
+        if (this.activeFallback) {
+          this.activeFallback = null;
+          this.cursor++;
+          return this.current();
+        }
+        this.cursor++;
+        return this.current();
+      }
+      /**
+       * Switch to the current step's `fallback` chain. The next `current()`
+       * call will return the fallback's first step. Throws if the current
+       * step has no fallback (caller should test before invoking).
+       */
+      branchToFallback() {
+        const step = this.current();
+        if (!step?.fallback) {
+          throw new Error(`Step ${step?.order ?? "?"} has no fallback`);
+        }
+        this.activeFallback = step.fallback;
+      }
+      /** Reset the cursor and clear any fallback — start over. */
+      reset() {
+        this.cursor = 0;
+        this.activeFallback = null;
+      }
+    };
+  }
+});
+
+// src/agent/procedural/ProcedureManager.ts
+import { randomUUID as randomUUID2 } from "crypto";
+function tokenize6(s) {
+  return new Set(
+    s.toLowerCase().split(/[^a-z0-9]+/g).filter((t) => t.length >= 2)
+  );
+}
+function clamp01(x) {
+  return Math.max(0, Math.min(1, x));
+}
+var ProcedureManager;
+var init_ProcedureManager = __esm({
+  "src/agent/procedural/ProcedureManager.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_ProcedureStore();
+    init_StepSequencer();
+    ProcedureManager = class {
+      store;
+      successRateAlpha;
+      constructor(entityManager, config = {}) {
+        this.store = new ProcedureStore(entityManager);
+        this.successRateAlpha = config.successRateAlpha ?? 0.2;
+      }
+      /**
+       * Persist a new procedure. Auto-generates `id` (and falls back to it
+       * for `name`) when caller omits them. Throws if the id collides — the
+       * caller should `getProcedure` first if upsert semantics are needed.
+       */
+      async addProcedure(input) {
+        if (!input.steps) {
+          throw new Error("addProcedure: steps[] is required");
+        }
+        const id = input.id ?? `proc-${randomUUID2()}`;
+        const procedure = {
+          id,
+          name: input.name ?? id,
+          description: input.description ?? "",
+          steps: input.steps,
+          triggers: input.triggers ?? [],
+          successRate: input.successRate ?? 0,
+          executionCount: input.executionCount ?? 0,
+          createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+          lastModified: (/* @__PURE__ */ new Date()).toISOString()
+        };
+        await this.store.save(procedure);
+        return procedure;
+      }
+      /** Load by id, or null. */
+      async getProcedure(id) {
+        return this.store.load(id);
+      }
+      /**
+       * Stateless lookup of a specific step by 1-indexed `stepOrder`. Returns
+       * null when the procedure has no such step.
+       */
+      async getStep(procedureId, stepOrder) {
+        const proc = await this.getProcedure(procedureId);
+        if (!proc) return null;
+        return proc.steps.find((s) => s.order === stepOrder) ?? null;
+      }
+      /**
+       * Look up the step that follows `currentOrder`. Returns null when at
+       * the end of the procedure or the procedure does not exist.
+       */
+      async getNextStep(procedureId, currentOrder) {
+        const proc = await this.getProcedure(procedureId);
+        if (!proc) return null;
+        const idx = proc.steps.findIndex((s) => s.order === currentOrder);
+        if (idx < 0 || idx + 1 >= proc.steps.length) return null;
+        return proc.steps[idx + 1];
+      }
+      /**
+       * Open a fresh `StepSequencer` for the named procedure. Returns null
+       * when the procedure doesn't exist. Multiple sequencers per procedure
+       * are independent — no shared cursor state.
+       */
+      async openSequencer(procedureId) {
+        const proc = await this.getProcedure(procedureId);
+        if (!proc) return null;
+        return new StepSequencer(proc);
+      }
+      /**
+       * Token-overlap match: scores each procedure by Jaccard-like overlap
+       * between the lowercased context tokens and the union of (`name`,
+       * `triggers`). Returns matches in score order, descending. `threshold`
+       * filters out matches below the cutoff (default 0.0 — return all).
+       */
+      async matchProcedure(contextDescription, candidates, threshold = 0) {
+        const ctxTokens = tokenize6(contextDescription);
+        if (ctxTokens.size === 0) return [];
+        const matches = [];
+        for (const procedure of candidates) {
+          const procTokens = /* @__PURE__ */ new Set();
+          for (const t of tokenize6(procedure.name)) procTokens.add(t);
+          for (const trig of procedure.triggers ?? []) {
+            for (const t of tokenize6(trig)) procTokens.add(t);
+          }
+          if (procTokens.size === 0) continue;
+          const intersection = /* @__PURE__ */ new Set();
+          for (const t of ctxTokens) if (procTokens.has(t)) intersection.add(t);
+          const union = /* @__PURE__ */ new Set([...ctxTokens, ...procTokens]);
+          const score = intersection.size / union.size;
+          if (score >= threshold) matches.push({ procedure, score });
+        }
+        matches.sort((a, b) => b.score - a.score);
+        return matches;
+      }
+      /**
+       * Apply caller feedback: increment `executionCount` and update
+       * `successRate` via EWMA. Persists the updated procedure. Returns
+       * the updated record. Throws if procedure does not exist.
+       */
+      async refineProcedure(procedureId, feedback) {
+        const proc = await this.getProcedure(procedureId);
+        if (!proc) {
+          throw new Error(`Procedure '${procedureId}' not found`);
+        }
+        const previousRate = proc.successRate ?? 0;
+        const observation = feedback.succeeded ? 1 : 0;
+        const baseline = (proc.executionCount ?? 0) === 0 ? 0.5 : previousRate;
+        const newRate = baseline + this.successRateAlpha * (observation - baseline);
+        const updated = {
+          ...proc,
+          successRate: clamp01(newRate),
+          executionCount: (proc.executionCount ?? 0) + 1,
+          lastModified: feedback.recordedAt ?? (/* @__PURE__ */ new Date()).toISOString()
+        };
+        await this.store.update(updated);
+        return updated;
+      }
+    };
+  }
+});
+
+// src/agent/causal/CausalReasoner.ts
+function chainScore(relations) {
+  let score = 1;
+  for (const r of relations) {
+    const meta = r.metadata;
+    const strength = typeof meta?.causalStrength === "number" ? meta.causalStrength : 1;
+    score *= strength;
+  }
+  return score;
+}
+var DEFAULT_CAUSAL_RELATION_TYPES, CausalReasoner;
+var init_CausalReasoner = __esm({
+  "src/agent/causal/CausalReasoner.ts"() {
+    "use strict";
+    init_esm_shims();
+    DEFAULT_CAUSAL_RELATION_TYPES = [
+      "causes",
+      "enables",
+      "prevents",
+      "precedes",
+      "correlates"
+    ];
+    CausalReasoner = class {
+      constructor(traversal, config = {}) {
+        this.traversal = traversal;
+        this.causalTypes = config.causalTypes ?? DEFAULT_CAUSAL_RELATION_TYPES;
+        this.maxDepth = config.maxDepth ?? 6;
+      }
+      causalTypes;
+      maxDepth;
+      /**
+       * Find all causal chains ending at `effectEntityName`. Searches for
+       * paths from any node to `effectEntityName` along causal edges. In
+       * practice we delegate to `findAllPaths` per candidate cause; for
+       * unbounded discovery the caller should layer their own seed selection.
+       *
+       * Returns an empty array when no causal chain reaches the target. Each
+       * chain's `score` is the product of `causalStrength` annotations on
+       * its relations (defaults to 1 per edge when missing).
+       */
+      async findCauses(effectEntityName, candidateCauses, maxDepth) {
+        const depth = maxDepth ?? this.maxDepth;
+        const chains = [];
+        for (const cause of candidateCauses) {
+          const paths = await this.traversal.findAllPaths(cause, effectEntityName, depth, {
+            relationTypes: this.causalTypes
+          });
+          for (const p of paths) {
+            chains.push({
+              path: p.path,
+              relations: p.relations,
+              score: chainScore(p.relations),
+              length: p.relations.length
+            });
+          }
+        }
+        chains.sort((a, b) => b.score - a.score);
+        return chains;
+      }
+      /**
+       * Find all causal chains starting at `causeEntityName` and reaching
+       * any of `candidateEffects`. Symmetric counterpart to `findCauses`.
+       */
+      async findEffects(causeEntityName, candidateEffects, maxDepth) {
+        const depth = maxDepth ?? this.maxDepth;
+        const chains = [];
+        for (const effect of candidateEffects) {
+          const paths = await this.traversal.findAllPaths(causeEntityName, effect, depth, {
+            relationTypes: this.causalTypes
+          });
+          for (const p of paths) {
+            chains.push({
+              path: p.path,
+              relations: p.relations,
+              score: chainScore(p.relations),
+              length: p.relations.length
+            });
+          }
+        }
+        chains.sort((a, b) => b.score - a.score);
+        return chains;
+      }
+      /**
+       * Counterfactual: "what changes if we remove edge `(removeFrom →
+       * removeTo)` and ask whether `predict` is still reachable from
+       * `seed`?" Returns chains from `seed` to `predict` that DO NOT use
+       * the removed edge. Compare against the unfiltered `findEffects`
+       * result to see which chains the removal kills.
+       *
+       * Pure: does not mutate the underlying graph or storage.
+       */
+      async counterfactual(scenario) {
+        const depth = scenario.maxDepth ?? this.maxDepth;
+        const paths = await this.traversal.findAllPaths(
+          scenario.seed,
+          scenario.predict,
+          depth,
+          { relationTypes: this.causalTypes }
+        );
+        const surviving = paths.filter(
+          (p) => !p.relations.some(
+            (r) => r.from === scenario.removeFrom && r.to === scenario.removeTo
+          )
+        );
+        return surviving.map((p) => ({
+          path: p.path,
+          relations: p.relations,
+          score: chainScore(p.relations),
+          length: p.relations.length
+        }));
+      }
+      /**
+       * Detect cycles in the causal subgraph rooted at `seed`. Returns each
+       * cycle as a list of entity names (with the repeating node at both
+       * ends) plus the edges that close the loop.
+       *
+       * **Caveat**: treats `prevents` as a directed causal edge, NOT as a
+       * negation. A `prevents`→`enables`→`prevents` triangle WILL show up
+       * as a cycle. Document explicitly so callers don't misinterpret.
+       *
+       * Cycle detection here is a depth-bounded DFS rather than full Tarjan
+       * SCC — sufficient for sparse causal graphs at hop counts ≤ 6, but
+       * may double-report cycles that share edges. Filter by `cycle[0]`
+       * sort-then-stringify if exact dedup is needed.
+       */
+      detectCycles(seed, maxDepth) {
+        const depth = maxDepth ?? this.maxDepth;
+        const cycles = [];
+        const path6 = [];
+        const relations = [];
+        const inPath = /* @__PURE__ */ new Set();
+        const dfs = (node, d) => {
+          if (d > depth) return;
+          inPath.add(node);
+          path6.push(node);
+          const neighbors = this.traversal.getNeighborsWithRelations(node, {
+            relationTypes: this.causalTypes,
+            direction: "outgoing"
+          });
+          for (const { neighbor, relation } of neighbors) {
+            if (inPath.has(neighbor)) {
+              const idx = path6.indexOf(neighbor);
+              if (idx >= 0) {
+                cycles.push({
+                  cycle: [...path6.slice(idx), neighbor],
+                  relations: [...relations.slice(idx), relation]
+                });
+              }
+            } else {
+              relations.push(relation);
+              dfs(neighbor, d + 1);
+              relations.pop();
+            }
+          }
+          inPath.delete(node);
+          path6.pop();
+        };
+        dfs(seed, 0);
+        return cycles;
+      }
+    };
+  }
+});
+
+// src/agent/rbac/PermissionMatrix.ts
+function permissionsForRole(role, resourceType, matrix = DEFAULT_PERMISSION_MATRIX, overrides) {
+  const overrideMatrix = overrides?.get(resourceType);
+  if (overrideMatrix?.has(role)) {
+    return overrideMatrix.get(role);
+  }
+  return matrix.get(role) ?? [];
+}
+var DEFAULT_PERMISSION_MATRIX;
+var init_PermissionMatrix = __esm({
+  "src/agent/rbac/PermissionMatrix.ts"() {
+    "use strict";
+    init_esm_shims();
+    DEFAULT_PERMISSION_MATRIX = /* @__PURE__ */ new Map([
+      ["reader", ["read"]],
+      ["writer", ["read", "write"]],
+      ["admin", ["read", "write", "delete"]],
+      ["owner", ["read", "write", "delete", "manage"]]
+    ]);
+  }
+});
+
+// src/agent/rbac/RbacMiddleware.ts
+var RbacMiddleware;
+var init_RbacMiddleware = __esm({
+  "src/agent/rbac/RbacMiddleware.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_PermissionMatrix();
+    RbacMiddleware = class {
+      constructor(store, options) {
+        this.store = store;
+        this.matrix = options?.matrix ?? DEFAULT_PERMISSION_MATRIX;
+        this.overrides = options?.overrides;
+        this.defaultRole = options?.defaultRole === void 0 && options !== void 0 ? options.defaultRole : options?.defaultRole ?? "reader";
+      }
+      matrix;
+      overrides;
+      defaultRole;
+      checkPermission(agentId, action, resourceType, resourceName, now) {
+        const active = this.store.listActive(agentId, now);
+        const applicable = active.filter((a) => this.matchesResource(a, resourceType, resourceName));
+        if (applicable.length === 0) {
+          if (!this.defaultRole) return false;
+          const granted = permissionsForRole(this.defaultRole, resourceType, this.matrix, this.overrides);
+          return granted.includes(action);
+        }
+        return applicable.some((a) => {
+          const granted = permissionsForRole(a.role, resourceType, this.matrix, this.overrides);
+          return granted.includes(action);
+        });
+      }
+      matchesResource(assignment, resourceType, resourceName) {
+        if (assignment.resourceType !== void 0 && assignment.resourceType !== resourceType) {
+          return false;
+        }
+        if (assignment.scope) {
+          if (!resourceName) return false;
+          if (!resourceName.startsWith(assignment.scope)) return false;
+        }
+        return true;
+      }
+    };
+  }
+});
+
+// src/agent/rbac/RoleAssignmentStore.ts
+import { promises as fs9 } from "fs";
+var RoleAssignmentStore;
+var init_RoleAssignmentStore = __esm({
+  "src/agent/rbac/RoleAssignmentStore.ts"() {
+    "use strict";
+    init_esm_shims();
+    RoleAssignmentStore = class {
+      assignments = /* @__PURE__ */ new Map();
+      persistencePath;
+      constructor(options) {
+        this.persistencePath = options?.persistencePath;
+      }
+      /**
+       * Replay the JSONL persistence file (if configured) into the in-memory
+       * map. Idempotent — safe to call multiple times. No-op when no path
+       * is set or the file does not exist.
+       */
+      async hydrate() {
+        if (!this.persistencePath) return;
+        let content;
+        try {
+          content = await fs9.readFile(this.persistencePath, "utf-8");
+        } catch (e) {
+          if (e.code === "ENOENT") return;
+          throw e;
+        }
+        this.assignments.clear();
+        for (const line of content.split("\n")) {
+          if (!line.trim()) continue;
+          try {
+            const rec = JSON.parse(line);
+            if (rec.op === "assign") {
+              this.applyAssign(rec.assignment);
+            } else {
+              this.applyRevoke(rec.agentId, rec.role, rec.resourceType);
+            }
+          } catch {
+          }
+        }
+      }
+      /**
+       * Add an assignment. Multiple grants per agent are allowed (e.g. one
+       * agent may be a `reader` for entities and a `writer` for relations).
+       * Persists if configured.
+       */
+      async assign(assignment) {
+        this.applyAssign(assignment);
+        await this.persist({ op: "assign", assignment, ts: (/* @__PURE__ */ new Date()).toISOString() });
+      }
+      /**
+       * Remove a specific assignment. Matching is by `agentId + role +
+       * resourceType` (the resourceType match is exact, including undefined).
+       */
+      async revoke(agentId, role, resourceType) {
+        this.applyRevoke(agentId, role, resourceType);
+        await this.persist({ op: "revoke", agentId, role, resourceType, ts: (/* @__PURE__ */ new Date()).toISOString() });
+      }
+      /** All assignments for the given agent (active and inactive). */
+      list(agentId) {
+        return this.assignments.get(agentId)?.slice() ?? [];
+      }
+      /**
+       * Active assignments for the given agent at the supplied time. Default
+       * is current time. An assignment is active when `validFrom <= now <=
+       * validUntil` (with absent bounds treated as unbounded).
+       */
+      listActive(agentId, now) {
+        const ts = now ?? (/* @__PURE__ */ new Date()).toISOString();
+        return this.list(agentId).filter((a) => {
+          if (a.validFrom && a.validFrom > ts) return false;
+          if (a.validUntil && a.validUntil < ts) return false;
+          return true;
+        });
+      }
+      // -------- Internal --------
+      applyAssign(assignment) {
+        const list = this.assignments.get(assignment.agentId) ?? [];
+        list.push(assignment);
+        this.assignments.set(assignment.agentId, list);
+      }
+      applyRevoke(agentId, role, resourceType) {
+        const list = this.assignments.get(agentId);
+        if (!list) return;
+        const filtered = list.filter(
+          (a) => !(a.role === role && a.resourceType === resourceType)
+        );
+        if (filtered.length === 0) {
+          this.assignments.delete(agentId);
+        } else {
+          this.assignments.set(agentId, filtered);
+        }
+      }
+      async persist(record) {
+        if (!this.persistencePath) return;
+        const line = JSON.stringify(record) + "\n";
+        await fs9.appendFile(this.persistencePath, line, "utf-8");
+      }
+    };
+  }
+});
+
+// src/agent/world/WorldStateSnapshot.ts
+function diffFields(before, after) {
+  const out = [];
+  if (before.entityType !== after.entityType) out.push("entityType");
+  if (before.importance !== after.importance) out.push("importance");
+  if (before.confidence !== after.confidence) out.push("confidence");
+  if (before.observationCount !== after.observationCount) out.push("observationCount");
+  if (!sameStringSet(before.tags, after.tags)) out.push("tags");
+  if (before.lastModified !== after.lastModified) out.push("lastModified");
+  return out;
+}
+function sameStringSet(a, b) {
+  if (a.length !== b.length) return false;
+  const setA = new Set(a);
+  for (const x of b) if (!setA.has(x)) return false;
+  return true;
+}
+var WorldStateSnapshot;
+var init_WorldStateSnapshot = __esm({
+  "src/agent/world/WorldStateSnapshot.ts"() {
+    "use strict";
+    init_esm_shims();
+    WorldStateSnapshot = class _WorldStateSnapshot {
+      /** ISO 8601 timestamp this snapshot was taken. */
+      takenAt;
+      /** Map keyed by entity name. */
+      entitiesByName;
+      constructor(entities, takenAt) {
+        this.takenAt = takenAt ?? (/* @__PURE__ */ new Date()).toISOString();
+        const m = /* @__PURE__ */ new Map();
+        for (const e of entities) m.set(e.name, e);
+        this.entitiesByName = m;
+      }
+      /** Number of entities in the snapshot. */
+      get size() {
+        return this.entitiesByName.size;
+      }
+      /** All entities, in insertion order. */
+      entities() {
+        return [...this.entitiesByName.values()];
+      }
+      /**
+       * Pure: compute the diff to a `next` snapshot. Returns added /
+       * removed / modified breakdown. An entity counts as "modified" when
+       * any of `importance`, `confidence`, `observationCount`, `tags`, or
+       * `lastModified` differs.
+       */
+      diffTo(next) {
+        const removed = [];
+        const added = [];
+        const modified = [];
+        for (const [name, before] of this.entitiesByName) {
+          const after = next.entitiesByName.get(name);
+          if (!after) {
+            removed.push(before);
+            continue;
+          }
+          const fields = diffFields(before, after);
+          if (fields.length > 0) {
+            modified.push({ name, before, after, fields });
+          }
+        }
+        for (const [name, after] of next.entitiesByName) {
+          if (!this.entitiesByName.has(name)) added.push(after);
+        }
+        return { removed, added, modified };
+      }
+      /** JSON-serializable form. */
+      toJSON() {
+        return { takenAt: this.takenAt, entities: [...this.entities()] };
+      }
+      /** Reconstruct from `toJSON()` output. */
+      static fromJSON(json) {
+        return new _WorldStateSnapshot(json.entities, json.takenAt);
+      }
+    };
+  }
+});
+
+// src/agent/world/WorldModelManager.ts
+var WorldModelManager;
+var init_WorldModelManager = __esm({
+  "src/agent/world/WorldModelManager.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_WorldStateSnapshot();
+    WorldModelManager = class {
+      constructor(entityManager, causalReasoner, memoryValidator, options = {}) {
+        this.entityManager = entityManager;
+        this.causalReasoner = causalReasoner;
+        this.memoryValidator = memoryValidator;
+        this.maxSnapshotSize = options.maxSnapshotSize ?? 1e3;
+      }
+      maxSnapshotSize;
+      /**
+       * Build a fresh snapshot from the live graph. Loads ALL entities (capped
+       * at `maxSnapshotSize`) and reduces each to a `WorldStateEntity`. Pure
+       * reads; safe to call concurrently.
+       *
+       * For graphs larger than the cap, entities are sorted by `importance`
+       * descending and truncated — high-importance entities preferred.
+       */
+      async getCurrentState() {
+        const graph = await this.entityManager["storage"].loadGraph();
+        let entities = graph.entities;
+        if (entities.length > this.maxSnapshotSize) {
+          entities = [...entities].sort((a, b) => (b.importance ?? 0) - (a.importance ?? 0)).slice(0, this.maxSnapshotSize);
+        }
+        const snapshotEntities = entities.map((e) => ({
+          name: e.name,
+          entityType: e.entityType,
+          importance: e.importance,
+          confidence: e.confidence,
+          observationCount: e.observations.length,
+          tags: [...e.tags ?? []],
+          lastModified: e.lastModified
+        }));
+        return new WorldStateSnapshot(snapshotEntities);
+      }
+      /**
+       * Validate a candidate observation against the named entity's current
+       * state. Delegates to `MemoryValidator.validateConsistency` when one
+       * was wired at construction; returns a deferred result with a `null`
+       * `issues` array when no validator is available — callers should treat
+       * `valid: undefined` as "not checked" rather than "passed".
+       */
+      async validateFact(observation, entityName) {
+        if (!this.memoryValidator) return null;
+        const entity = await this.entityManager.getEntity(entityName);
+        if (!entity) return null;
+        return this.memoryValidator.validateConsistency(observation, entity);
+      }
+      /**
+       * Predict downstream effects of an action by walking the causal
+       * subgraph from `actionEntity` to each candidate effect. Returns
+       * empty when no causal reasoner was wired or no chain reaches any
+       * candidate.
+       */
+      async predictOutcome(actionEntity, candidateEffects) {
+        if (!this.causalReasoner) return [];
+        return this.causalReasoner.findEffects(actionEntity, candidateEffects);
+      }
+      /**
+       * Pure: diff two snapshots. Direct passthrough to
+       * `WorldStateSnapshot.diffTo` — exposed here so callers can use the
+       * world-model facade for both snapshotting and change detection.
+       */
+      detectStateChange(before, after) {
+        return before.diffTo(after);
+      }
+    };
+  }
+});
+
+// src/agent/retrieval/QueryRewriter.ts
+function tokenize7(s) {
+  return s.toLowerCase().split(/[^a-z0-9]+/g).filter((t) => t.length >= 3 && !STOPWORDS3.has(t));
+}
+var STOPWORDS3, QueryRewriter;
+var init_QueryRewriter = __esm({
+  "src/agent/retrieval/QueryRewriter.ts"() {
+    "use strict";
+    init_esm_shims();
+    STOPWORDS3 = /* @__PURE__ */ new Set([
+      "the",
+      "a",
+      "an",
+      "of",
+      "and",
+      "or",
+      "but",
+      "is",
+      "are",
+      "was",
+      "were",
+      "be",
+      "been",
+      "being",
+      "have",
+      "has",
+      "had",
+      "do",
+      "does",
+      "did",
+      "will",
+      "would",
+      "could",
+      "should",
+      "may",
+      "might",
+      "must",
+      "shall",
+      "can",
+      "to",
+      "for",
+      "with",
+      "on",
+      "in",
+      "at",
+      "by",
+      "from",
+      "up",
+      "about",
+      "as",
+      "this",
+      "that",
+      "these",
+      "those",
+      "i",
+      "you",
+      "he",
+      "she",
+      "it",
+      "we",
+      "they",
+      "his",
+      "her",
+      "its",
+      "our",
+      "their",
+      "me",
+      "him",
+      "them",
+      "us",
+      "my",
+      "your"
+    ]);
+    QueryRewriter = class {
+      /**
+       * Expand `query` with the top-`expansionLimit` co-occurring tokens
+       * from `snippets`. Tokens already present in the query (case-
+       * insensitive) and stopwords are excluded.
+       */
+      rewrite(query, snippets, expansionLimit = 3) {
+        const queryTokens = new Set(tokenize7(query));
+        const counts = /* @__PURE__ */ new Map();
+        for (const s of snippets) {
+          const seen = /* @__PURE__ */ new Set();
+          for (const t of tokenize7(s)) {
+            if (queryTokens.has(t)) continue;
+            if (seen.has(t)) continue;
+            seen.add(t);
+            counts.set(t, (counts.get(t) ?? 0) + 1);
+          }
+        }
+        const top = [...counts.entries()].sort((a, b) => b[1] - a[1]).slice(0, expansionLimit).map(([t]) => t);
+        if (top.length === 0) {
+          return { query, expansionTokens: [] };
+        }
+        return {
+          query: `${query} ${top.join(" ")}`,
+          expansionTokens: top
+        };
+      }
+    };
+  }
+});
+
+// src/agent/retrieval/ActiveRetrievalController.ts
+var ActiveRetrievalController;
+var init_ActiveRetrievalController = __esm({
+  "src/agent/retrieval/ActiveRetrievalController.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_QueryRewriter();
+    ActiveRetrievalController = class {
+      constructor(rankedSearch, config = {}) {
+        this.rankedSearch = rankedSearch;
+        this.maxRounds = config.maxRounds ?? 3;
+        this.minCoverage = config.minCoverage ?? 0.6;
+        this.resultsPerRound = config.resultsPerRound ?? 10;
+        this.costThreshold = config.costThreshold ?? 1e3;
+        this.expansionLimit = config.expansionLimit ?? 3;
+      }
+      rewriter = new QueryRewriter();
+      maxRounds;
+      minCoverage;
+      resultsPerRound;
+      costThreshold;
+      expansionLimit;
+      /**
+       * Decide whether retrieval is worth the cost. Currently a simple
+       * heuristic: tokens(query) × resultsPerRound × maxRounds × constant.
+       * Returns `retrieve: false` when estimated cost > budget OR query is
+       * empty.
+       */
+      shouldRetrieve(context) {
+        const tokens = context.query.trim().split(/\s+/).filter(Boolean);
+        if (tokens.length === 0) {
+          return { retrieve: false, estimatedCost: 0, reason: "Empty query" };
+        }
+        const estimatedCost = tokens.length * 5 + this.resultsPerRound * this.maxRounds * 50;
+        const budget = context.budgetTokens ?? this.costThreshold;
+        if (estimatedCost > budget) {
+          return {
+            retrieve: false,
+            estimatedCost,
+            reason: `Estimated cost ${estimatedCost} exceeds budget ${budget}`
+          };
+        }
+        return {
+          retrieve: true,
+          estimatedCost,
+          reason: "Cost within budget"
+        };
+      }
+      /**
+       * Run up to `maxRounds` of (search → score coverage → rewrite). Stops
+       * early when coverage hits `minCoverage` or no expansion tokens are
+       * available. Returns the highest-coverage round's results plus the
+       * full per-round trace.
+       */
+      async adaptiveRetrieve(context) {
+        const rounds = [];
+        let currentQuery = context.query;
+        let bestRound = null;
+        for (let i = 0; i < this.maxRounds; i++) {
+          const results = await this.rankedSearch.searchNodesRanked(
+            currentQuery,
+            void 0,
+            void 0,
+            void 0,
+            this.resultsPerRound
+          );
+          const coverage = this.estimateCoverage(results);
+          const round = {
+            query: currentQuery,
+            results,
+            coverage,
+            expansionTokens: i === 0 ? [] : rounds[i - 1].expansionTokens ?? []
+          };
+          rounds.push(round);
+          if (!bestRound || coverage > bestRound.coverage) bestRound = round;
+          if (coverage >= this.minCoverage) break;
+          if (results.length === 0) break;
+          const snippets = results.flatMap((r) => r.entity.observations).slice(0, 20);
+          const rewrite = this.rewriter.rewrite(currentQuery, snippets, this.expansionLimit);
+          if (rewrite.expansionTokens.length === 0) break;
+          currentQuery = rewrite.query;
+          rounds[rounds.length - 1].expansionTokens = rewrite.expansionTokens;
+        }
+        return {
+          bestResults: bestRound?.results ?? [],
+          bestCoverage: bestRound?.coverage ?? 0,
+          rounds
+        };
+      }
+      /**
+       * Quick coverage estimate: average of the top-3 results' scores,
+       * clamped to [0, 1]. Empty results → 0. Score normalization assumes
+       * `RankedSearch` returns BM25-ish positive numbers; we cap at 1.0 to
+       * keep the threshold comparison meaningful.
+       */
+      estimateCoverage(results) {
+        if (results.length === 0) return 0;
+        const top = results.slice(0, 3);
+        const avg = top.reduce((acc, r) => acc + (r.score ?? 0), 0) / top.length;
+        return Math.min(1, Math.max(0, avg));
+      }
+    };
+  }
+});
+
+// src/core/ManagerContext.ts
+import path5 from "path";
+var ManagerContext;
+var init_ManagerContext = __esm({
+  "src/core/ManagerContext.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_StorageFactory();
+    init_EntityManager();
+    init_RelationManager();
+    init_ObservationManager();
+    init_HierarchyManager();
+    init_GraphTraversal();
+    init_SearchManager();
+    init_RankedSearch();
+    init_LLMQueryPlanner();
+    init_LLMSearchExecutor();
+    init_search();
+    init_IOManager();
+    init_TagManager();
+    init_AnalyticsManager();
+    init_CompressionManager();
+    init_ArchiveManager();
+    init_AutoLinker();
+    init_FactExtractor();
+    init_TransitionLedger();
+    init_AccessTracker();
+    init_DecayEngine();
+    init_DecayScheduler();
+    init_ConsolidationScheduler();
+    init_SalienceEngine();
+    init_ContextWindowManager();
+    init_MemoryFormatter();
+    init_AgentMemoryManager();
+    init_ArtifactManager();
+    init_DreamEngine();
+    init_RefIndex();
+    init_ObserverPipeline();
+    init_constants();
+    init_utils();
+    init_ContradictionDetector();
+    init_SemanticForget();
+    init_MemoryEngine();
+    init_ImportanceScorer();
+    init_InMemoryBackend();
+    init_SQLiteBackend();
+    init_MemoryValidator();
+    init_TrajectoryCompressor();
+    init_ExperienceExtractor();
+    init_PatternDetector();
+    init_ProcedureManager();
+    init_CausalReasoner();
+    init_RbacMiddleware();
+    init_RoleAssignmentStore();
+    init_WorldModelManager();
+    init_ActiveRetrievalController();
+    ManagerContext = class {
+      // Type as GraphStorage for manager compatibility; actual instance may be SQLiteStorage
+      // which implements the same interface via duck typing
+      storage;
+      defaultProjectId;
+      savedSearchesFilePath;
+      tagAliasesFilePath;
+      refIndexFilePath;
+      _observerPipeline;
+      // ==================== LAZY-INITIALIZED CORE MANAGERS ====================
+      _entityManager;
+      _relationManager;
+      _observationManager;
+      _hierarchyManager;
+      _graphTraversal;
+      _searchManager;
+      _rankedSearch;
+      _ioManager;
+      _tagManager;
+      _analyticsManager;
+      _compressionManager;
+      _archiveManager;
+      _autoLinker;
+      _factExtractor;
+      _transitionLedger;
+      _semanticSearch;
+      _memoryEngine;
+      _memoryBackend;
+      _memoryValidator;
+      _trajectoryCompressor;
+      _experienceExtractor;
+      _patternDetector;
+      _procedureManager;
+      _causalReasoner;
+      _rbacMiddleware;
+      _roleAssignmentStore;
+      _worldModelManager;
+      _activeRetrieval;
+      _accessTracker;
+      _decayEngine;
+      _decayScheduler;
+      _salienceEngine;
+      _contextWindowManager;
+      _memoryFormatter;
+      _agentMemory;
+      _refIndex;
+      _artifactManager;
+      _consolidationScheduler;
+      _dreamEngine;
+      _llmQueryPlanner;
+      _llmSearchExecutor;
+      _semanticForget;
+      constructor(pathOrOptions) {
+        const opts = typeof pathOrOptions === "string" ? { storagePath: pathOrOptions } : pathOrOptions;
+        this.defaultProjectId = opts.defaultProjectId;
+        const validatedPath = validateFilePath(opts.storagePath, void 0, false);
+        const dir = path5.dirname(validatedPath);
+        const basename2 = path5.basename(validatedPath, path5.extname(validatedPath));
+        this.savedSearchesFilePath = path5.join(dir, `${basename2}-saved-searches.jsonl`);
+        this.tagAliasesFilePath = path5.join(dir, `${basename2}-tag-aliases.jsonl`);
+        this.refIndexFilePath = path5.join(dir, `${basename2}-ref-index.jsonl`);
+        this.storage = createStorageFromPath(validatedPath);
+        if (opts.enableContradictionDetection) {
+          this.initContradictionDetection(opts.contradictionThreshold);
+        }
+        this.observationManager.setMemoryValidator(() => this.memoryValidator);
+      }
+      /**
+       * Wire ContradictionDetector to ObservationManager if a semantic search
+       * embedding provider is available. Silently degrades when none is configured.
+       * @internal
+       */
+      initContradictionDetection(threshold) {
+        try {
+          const ss = this.semanticSearch;
+          if (!ss) {
+            console.warn(
+              "[ManagerContext] Contradiction detection requested but no embedding provider is configured. Set MEMORY_EMBEDDING_PROVIDER to enable it."
+            );
+            return;
+          }
+          const detector = new ContradictionDetector(ss, threshold ?? 0.85);
+          this.observationManager.setContradictionDetector(detector, this.entityManager);
+        } catch (err) {
+          console.warn(
+            "[ManagerContext] Could not initialise contradiction detection:",
+            err instanceof Error ? err.message : String(err)
+          );
+        }
+      }
+      // ==================== LAZY ACCESSORS (agent memory + semantic) ====================
+      /** EntityManager - Entity CRUD and tag operations */
+      get entityManager() {
+        return this._entityManager ??= new EntityManager(
+          this.storage,
+          { defaultProjectId: this.defaultProjectId }
+        );
+      }
+      /** RelationManager - Relation CRUD */
+      get relationManager() {
+        return this._relationManager ??= new RelationManager(this.storage);
+      }
+      /** ObservationManager - Observation CRUD */
+      get observationManager() {
+        return this._observationManager ??= new ObservationManager(this.storage);
+      }
+      /** HierarchyManager - Entity hierarchy operations */
+      get hierarchyManager() {
+        return this._hierarchyManager ??= new HierarchyManager(this.storage);
+      }
+      /** GraphTraversal - Phase 4 Sprint 6-8: Graph traversal algorithms */
+      get graphTraversal() {
+        return this._graphTraversal ??= new GraphTraversal(this.storage);
+      }
+      /** SearchManager - All search operations */
+      get searchManager() {
+        return this._searchManager ??= new SearchManager(this.storage, this.savedSearchesFilePath);
       }
       /** RankedSearch - TF-IDF/BM25 ranked search */
       get rankedSearch() {
@@ -23918,6 +27032,203 @@ var init_ManagerContext = __esm({
         }
         return this._semanticSearch;
       }
+      /**
+       * MemoryEngine — turn-aware conversation memory facade composing over
+       * EpisodicMemoryManager + WorkingMemoryManager + ImportanceScorer.
+       * Lazy: instantiated on first access. Reads MEMORY_ENGINE_* env vars
+       * for dedup thresholds, scan window, and scorer weights.
+       */
+      get memoryEngine() {
+        if (!this._memoryEngine) {
+          const agent = this.agentMemory();
+          const importanceScorer = new ImportanceScorer({
+            lengthWeight: this.getEnvNumber("MEMORY_ENGINE_LENGTH_WEIGHT", 0.3),
+            keywordWeight: this.getEnvNumber("MEMORY_ENGINE_KEYWORD_WEIGHT", 0.4),
+            overlapWeight: this.getEnvNumber("MEMORY_ENGINE_OVERLAP_WEIGHT", 0.3)
+          });
+          const semanticSearch = this.semanticSearch ?? null;
+          const embeddingService = semanticSearch?.getEmbeddingService() ?? null;
+          this._memoryEngine = new MemoryEngine(
+            this.storage,
+            this.entityManager,
+            agent.episodicMemory,
+            agent.workingMemory,
+            importanceScorer,
+            semanticSearch,
+            embeddingService,
+            {
+              jaccardThreshold: this.getEnvNumber("MEMORY_ENGINE_JACCARD_THRESHOLD", 0.72),
+              prefixOverlapThreshold: this.getEnvNumber("MEMORY_ENGINE_PREFIX_OVERLAP", 0.5),
+              dedupScanWindow: Math.trunc(
+                this.getEnvNumber("MEMORY_ENGINE_DEDUP_SCAN_WINDOW", 200)
+              ),
+              maxTurnsPerSession: Math.trunc(
+                this.getEnvNumber("MEMORY_ENGINE_MAX_TURNS_PER_SESSION", 1e3)
+              ),
+              semanticDedupEnabled: this.getEnvBool("MEMORY_ENGINE_SEMANTIC_DEDUP", false),
+              semanticThreshold: this.getEnvNumber("MEMORY_ENGINE_SEMANTIC_THRESHOLD", 0.92),
+              recentTurnsForImportance: Math.trunc(
+                this.getEnvNumber("MEMORY_ENGINE_RECENT_TURNS", 10)
+              )
+            }
+          );
+        }
+        return this._memoryEngine;
+      }
+      /**
+       * IMemoryBackend (PRD MEM-04) — agent-memory-flavored backend.
+       *
+       * Selection by `MEMORY_BACKEND` env var:
+       *   - `sqlite` (default when storage is SQLite OR var unset on JSONL)
+       *   - `in-memory` (ephemeral; no persistence)
+       *   - future: `postgres`, `vector` (Phase γ)
+       *
+       * Both adapters wrap `ctx.memoryEngine` + `ctx.decayEngine` so they
+       * inherit the four-tier dedup chain and PRD effective-importance
+       * scoring respectively. Lazy-initialized; cached.
+       */
+      get memoryBackend() {
+        if (!this._memoryBackend) {
+          const choice = (process.env.MEMORY_BACKEND ?? "sqlite").toLowerCase();
+          switch (choice) {
+            case "in-memory":
+            case "inmemory":
+            case "memory":
+              this._memoryBackend = new InMemoryBackend(this.decayEngine);
+              break;
+            case "sqlite":
+            default:
+              this._memoryBackend = new SQLiteBackend(this.memoryEngine, this.decayEngine);
+              break;
+          }
+        }
+        return this._memoryBackend;
+      }
+      /**
+       * MemoryValidator (ROADMAP §3B.1, Phase δ.1) — reflection-stage
+       * service that prevents hallucinations and logical errors from
+       * contaminating memory through self-critique before storage.
+       * Wraps `ContradictionDetector`. Lazy-initialized.
+       *
+       * Construction needs `ContradictionDetector(SemanticSearch, threshold)`.
+       * If no semantic-search backend is configured, a no-op detector is
+       * synthesized so MemoryValidator's other methods still work — the
+       * detection method just returns no contradictions.
+       */
+      get memoryValidator() {
+        if (!this._memoryValidator) {
+          const ss = this.semanticSearch;
+          const detector = ss ? new ContradictionDetector(ss, 0.85) : new ContradictionDetector(
+            { calculateSimilarity: async () => 0 },
+            0.85
+          );
+          this._memoryValidator = new MemoryValidator(detector);
+        }
+        return this._memoryValidator;
+      }
+      /**
+       * TrajectoryCompressor (ROADMAP §3B.2, Phase δ.2) — reflection-stage
+       * service that distills verbose interaction histories into compact,
+       * reusable representations. Wraps `compressForContext`. Lazy.
+       */
+      get trajectoryCompressor() {
+        if (!this._trajectoryCompressor) {
+          this._trajectoryCompressor = new TrajectoryCompressor(this.contextWindowManager);
+        }
+        return this._trajectoryCompressor;
+      }
+      /**
+       * ExperienceExtractor (ROADMAP §3B.3, Phase δ.3) — experience-stage
+       * service that abstracts universal patterns from trajectory clusters
+       * for zero-shot transfer. Wraps `PatternDetector`. Lazy.
+       */
+      get experienceExtractor() {
+        if (!this._experienceExtractor) {
+          this._experienceExtractor = new ExperienceExtractor(this.patternDetector);
+        }
+        return this._experienceExtractor;
+      }
+      /** Lazy `PatternDetector` instance — backs `experienceExtractor`
+       * but also exposed directly for callers that want pattern detection
+       * without the full Experience-stage wrapper. */
+      get patternDetector() {
+        if (!this._patternDetector) {
+          this._patternDetector = new PatternDetector();
+        }
+        return this._patternDetector;
+      }
+      /**
+       * `ProcedureManager` (3B.4) — first-class executable procedures.
+       * Lazy. Composes `EntityManager` (persists procedures as
+       * `entityType: 'procedure'`).
+       */
+      get procedureManager() {
+        if (!this._procedureManager) {
+          this._procedureManager = new ProcedureManager(this.entityManager);
+        }
+        return this._procedureManager;
+      }
+      /**
+       * `CausalReasoner` (3B.6) — symbolic forward / backward / counter-
+       * factual inference over the causal subgraph. Wraps `GraphTraversal`.
+       * Lazy.
+       */
+      get causalReasoner() {
+        if (!this._causalReasoner) {
+          this._causalReasoner = new CausalReasoner(this.graphTraversal);
+        }
+        return this._causalReasoner;
+      }
+      /**
+       * `RoleAssignmentStore` (η.6.1) — registry of role grants per agent.
+       * Lazy. In-memory only by default; configure persistence via the
+       * direct constructor if a JSONL sidecar is wanted.
+       */
+      get roleAssignmentStore() {
+        if (!this._roleAssignmentStore) {
+          this._roleAssignmentStore = new RoleAssignmentStore();
+        }
+        return this._roleAssignmentStore;
+      }
+      /**
+       * `RbacMiddleware` (η.6.1) — `RbacPolicy` impl. Backed by the lazy
+       * `roleAssignmentStore`. Lazy.
+       */
+      get rbacMiddleware() {
+        if (!this._rbacMiddleware) {
+          this._rbacMiddleware = new RbacMiddleware(this.roleAssignmentStore);
+        }
+        return this._rbacMiddleware;
+      }
+      /**
+       * `WorldModelManager` (3B.7) — orchestrator that composes
+       * `causalReasoner`, `memoryValidator`, and `entityManager` into a
+       * single facade for `getCurrentState` / `validateFact` /
+       * `predictOutcome` / `detectStateChange`. Lazy. Causal and validator
+       * dependencies are passed through; methods that need them gracefully
+       * return null/empty when they're not configured.
+       */
+      get worldModelManager() {
+        if (!this._worldModelManager) {
+          this._worldModelManager = new WorldModelManager(
+            this.entityManager,
+            this.causalReasoner,
+            this.memoryValidator
+          );
+        }
+        return this._worldModelManager;
+      }
+      /**
+       * `ActiveRetrievalController` (3B.5) — adaptive query-rewriting loop
+       * over `RankedSearch`. Lazy. Pure symbolic expansion (no LLM); for
+       * LLM-driven decomposition use `ctx.llmQueryPlanner`.
+       */
+      get activeRetrieval() {
+        if (!this._activeRetrieval) {
+          this._activeRetrieval = new ActiveRetrievalController(this.rankedSearch);
+        }
+        return this._activeRetrieval;
+      }
       /**
        * TransitionLedger - Append-only audit trail for state changes.
        * Returns null if not enabled via MEMORY_TRANSITION_LEDGER env var.
@@ -23980,11 +27291,25 @@ var init_ManagerContext = __esm({
             halfLifeHours: this.getEnvNumber("MEMORY_DECAY_HALF_LIFE_HOURS", 168),
             minImportance: this.getEnvNumber("MEMORY_DECAY_MIN_IMPORTANCE", 0.1),
             importanceModulation: this.getEnvBool("MEMORY_DECAY_IMPORTANCE_MOD", true),
-            accessModulation: this.getEnvBool("MEMORY_DECAY_ACCESS_MOD", true)
+            accessModulation: this.getEnvBool("MEMORY_DECAY_ACCESS_MOD", true),
+            // PRD MEM-01 (v1.12.0). decayRate is auto-derived from halfLifeHours
+            // when env-var unset (NaN check avoids overriding the auto-derive).
+            decayRate: this.envNumberOrUndefined("MEMORY_PRD_DECAY_RATE"),
+            freshnessCoefficient: this.getEnvNumber("MEMORY_PRD_FRESHNESS_COEFFICIENT", 0.01),
+            relevanceWeight: this.getEnvNumber("MEMORY_PRD_RELEVANCE_WEIGHT", 0.35),
+            minImportanceThreshold: this.getEnvNumber("MEMORY_PRD_MIN_IMPORTANCE_THRESHOLD", 0.1)
           });
         }
         return this._decayEngine;
       }
+      /** Returns env-var as number, or undefined when unset (lets the
+       *  default-derive logic in DecayEngine kick in for `decayRate`). */
+      envNumberOrUndefined(name) {
+        const raw = process.env[name];
+        if (raw === void 0 || raw === "") return void 0;
+        const n = Number(raw);
+        return Number.isFinite(n) ? n : void 0;
+      }
       /**
        * DecayScheduler - Scheduled decay and forget operations.
        * Returns undefined if auto-decay is not enabled (MEMORY_AUTO_DECAY).
@@ -24145,6 +27470,10 @@ var init_ManagerContext = __esm({
       agentMemory(config) {
         if (!this._agentMemory || config) {
           this._agentMemory = new AgentMemoryManager(this.storage, config);
+          this._memoryEngine = void 0;
+          this._memoryBackend = void 0;
+          this._consolidationScheduler = void 0;
+          this._dreamEngine = void 0;
         }
         return this._agentMemory;
       }
@@ -24427,7 +27756,7 @@ Path (${pathResult.length} hops): ${pathResult.path.join(" -> ")}`);
       break;
     }
     case "export": {
-      const validFormats = ["json", "csv", "graphml", "gexf", "dot", "markdown", "mermaid"];
+      const validFormats = ["json", "csv", "graphml", "gexf", "dot", "markdown", "mermaid", "turtle", "rdf-xml", "json-ld"];
       const fmt = args[0] || "json";
       if (!validFormats.includes(fmt)) {
         console.log(chalk2.yellow(`Invalid format: ${fmt}. Use: ${validFormats.join(", ")}`));
@@ -24501,14 +27830,11 @@ var defaultOptions = {
   verbose: false
 };
 function parseGlobalOptions(opts) {
-  const format = opts.format;
-  if (format && !["json", "table", "csv"].includes(format)) {
-    console.error(`Invalid format: ${format}. Use json, table, or csv.`);
-    process.exit(1);
-  }
+  const rawFormat = opts.outputFormat;
+  const format = rawFormat && ["json", "table", "csv"].includes(rawFormat) ? rawFormat : defaultOptions.format;
   return {
     storage: opts.storage || defaultOptions.storage,
-    format: format || defaultOptions.format,
+    format,
     quiet: Boolean(opts.quiet),
     verbose: Boolean(opts.verbose)
   };
@@ -25365,8 +28691,9 @@ init_esm_shims();
 import { readFileSync as readFileSync2, writeFileSync } from "fs";
 import { resolve as resolve2 } from "path";
 import { Option } from "commander";
+init_entityUtils();
 var IMPORT_FORMATS = ["json", "csv", "graphml"];
-var EXPORT_FORMATS = ["json", "csv", "graphml", "gexf", "dot", "markdown", "mermaid"];
+var EXPORT_FORMATS = ["json", "csv", "graphml", "gexf", "dot", "markdown", "mermaid", "turtle", "rdf-xml", "json-ld"];
 function registerIOCommands(program2) {
   program2.command("import <file>").description("Import data from file").addOption(
     new Option("-f, --format <format>", "File format").choices([...IMPORT_FORMATS]).default("json")
@@ -25375,7 +28702,7 @@ function registerIOCommands(program2) {
     const logger2 = createLogger(options);
     const ctx = createContext(options);
     try {
-      const resolvedPath = resolve2(file);
+      const resolvedPath = validateFilePath(resolve2(file), void 0, false);
       const data = readFileSync2(resolvedPath, "utf-8");
       const result = await ctx.ioManager.importGraph(
         opts.format,
@@ -25397,7 +28724,7 @@ function registerIOCommands(program2) {
     const logger2 = createLogger(options);
     const ctx = createContext(options);
     try {
-      const resolvedPath = resolve2(file);
+      const resolvedPath = validateFilePath(resolve2(file), void 0, false);
       const graph = await ctx.storage.loadGraph();
       const data = ctx.ioManager.exportGraph(
         graph,
@@ -25568,7 +28895,7 @@ function getVersion() {
 }
 var program = new Command2();
 program.name("memory").description("MemoryJS - Knowledge Graph CLI").version(getVersion(), "-v, --version", "Output the current version");
-program.option("-s, --storage <path>", "Path to storage file", "./memory.jsonl").option("-f, --format <type>", "Output format (json|table|csv)", "json").option("-q, --quiet", "Suppress non-essential output").option("--verbose", "Enable verbose/debug output");
+program.option("-s, --storage <path>", "Path to storage file", "./memory.jsonl").option("--output-format <type>", "Console output format (json|table|csv)", "json").option("-q, --quiet", "Suppress non-essential output").option("--verbose", "Enable verbose/debug output");
 registerCommands(program);
 program.parse();
 //# sourceMappingURL=index.js.map