@joshuaswarren/openclaw-engram 9.0.29 → 9.0.30

package/README.md

@@ -34,7 +34,7 @@ AI agents forget everything between conversations. Engram fixes that.
 - **Objective-state recall** — Engram can now store normalized file, process, and tool outcomes and, when `objectiveStateRecallEnabled` is enabled, inject the most relevant objective-state snapshots back into recall context as a separate `Objective State` section.
 - **Causal trajectory graph foundation** — Engram can now persist typed `goal -> action -> observation -> outcome -> follow-up` chains when `causalTrajectoryMemoryEnabled` is enabled and, with `actionGraphRecallEnabled`, emit deterministic action-conditioned edges into the causal graph for later trajectory-aware retrieval.
 - **Causal trajectory recall** — Engram can now, when `causalTrajectoryRecallEnabled` is enabled, inject prompt-relevant causal chains back into recall context as a separate `Causal Trajectories` section with lightweight match explainability.
-- **Trust-zone store foundation** — Engram can now, when `trustZonesEnabled` is enabled, persist typed quarantine, working, and trusted records with provenance metadata into a dedicated trust-zone store for later promotion and defense slices.
+- **Trust-zone promotion path** — Engram can now, when `trustZonesEnabled` and `quarantinePromotionEnabled` are enabled, persist typed quarantine, working, and trusted records, plan explicit promotions, block direct `quarantine -> trusted` jumps, and require anchored provenance before promoting risky working records into `trusted`.
 - **Zero-config start** — Install, add an API key, restart. Engram works out of the box with sensible defaults and progressively unlocks advanced features as you enable them.
 
 ## Quick Start
@@ -160,6 +160,8 @@ openclaw engram benchmark-import <path>      # Import a validated benchmark pack
 openclaw engram benchmark-ci-gate            # Compare base vs candidate eval stores and fail on regressions
 openclaw engram objective-state-status       # Objective-state snapshot counts and latest stored snapshot
 openclaw engram causal-trajectory-status    # Causal-trajectory record counts and latest stored chain
+openclaw engram trust-zone-status           # Trust-zone record counts and latest stored record
+openclaw engram trust-zone-promote          # Dry-run or apply a trust-zone promotion with provenance enforcement
 openclaw engram conversation-index-health    # Conversation index status
 openclaw engram graph-health                 # Entity graph status
 openclaw engram tier-status                  # Hot/cold tier metrics
@@ -190,8 +192,8 @@ Key settings:
 | `causalTrajectoryStoreDir` | `{memoryDir}/state/causal-trajectories` | Root directory for causal-trajectory records |
 | `causalTrajectoryRecallEnabled` | `false` | Inject prompt-relevant causal trajectories into recall context |
 | `actionGraphRecallEnabled` | `false` | Write action-conditioned causal-stage edges from typed trajectory records into the causal graph |
-| `trustZonesEnabled` | `false` | Enable the trust-zone memory foundation for quarantine, working, and trusted records |
-| `quarantinePromotionEnabled` | `false` | Reserve future promotion flows from quarantine into higher-trust zones |
+| `trustZonesEnabled` | `false` | Enable the trust-zone memory foundation and operator-facing promotion path for quarantine, working, and trusted records |
+| `quarantinePromotionEnabled` | `false` | Allow explicit trust-zone promotions such as `quarantine -> working` and guarded `working -> trusted` |
 | `trustZoneStoreDir` | `{memoryDir}/state/trust-zones` | Root directory for trust-zone records |
 
 Full reference: [Config Reference](docs/config-reference.md)

package/dist/index.js

@@ -26294,6 +26294,129 @@ function validateTrustZoneRecord(raw) {
     metadata: validateMetadata3(raw.metadata)
   };
 }
+async function recordTrustZoneRecord(options) {
+  const rootDir = resolveTrustZoneStoreDir(options.memoryDir, options.trustZoneStoreDir);
+  const validated = validateTrustZoneRecord(options.record);
+  const day = recordStoreDay(validated.recordedAt);
+  const zoneDir = path53.join(rootDir, "zones", validated.zone, day);
+  const filePath = path53.join(zoneDir, `${validated.recordId}.json`);
+  await mkdir35(zoneDir, { recursive: true });
+  await writeFile32(filePath, JSON.stringify(validated, null, 2), "utf8");
+  return filePath;
+}
+function hasAnchoredProvenance(record) {
+  return Boolean(record.provenance.sourceId && record.provenance.evidenceHash);
+}
+function buildPromotionRecordId(sourceRecordId, targetZone, recordedAt) {
+  const suffix = recordedAt.replace(/[^0-9]/g, "").slice(0, 14);
+  return `${sourceRecordId}-${targetZone}-${suffix}`;
+}
+function dedupeStrings(values) {
+  const out = values.filter((value) => typeof value === "string" && value.length > 0);
+  if (out.length === 0) return void 0;
+  return [...new Set(out)];
+}
+function planTrustZonePromotion(options) {
+  const { record, targetZone } = options;
+  const reasons = [];
+  const provenanceAnchored = hasAnchoredProvenance(record);
+  if (record.zone === targetZone) {
+    reasons.push(`record is already in the ${targetZone} zone`);
+  }
+  if (record.zone === "trusted") {
+    reasons.push("trusted records are terminal and cannot be promoted again");
+  }
+  if (record.zone === "quarantine" && targetZone === "trusted") {
+    reasons.push("quarantine records must pass through working before trusted promotion");
+  }
+  if (record.zone === "working" && targetZone === "quarantine") {
+    reasons.push("working records cannot be demoted back into quarantine in this promotion path");
+  }
+  if (record.zone === "quarantine" && targetZone !== "working") {
+    reasons.push("quarantine promotions only support the working zone");
+  }
+  if (record.zone === "working" && targetZone !== "trusted") {
+    reasons.push("working promotions only support the trusted zone");
+  }
+  if (targetZone === "trusted" && ["tool_output", "web_content", "subagent_trace"].includes(record.provenance.sourceClass) && provenanceAnchored !== true) {
+    reasons.push("trusted promotion for external/tool-derived provenance requires both provenance.sourceId and provenance.evidenceHash");
+  }
+  return {
+    allowed: reasons.length === 0,
+    reasons,
+    sourceRecordId: record.recordId,
+    sourceZone: record.zone,
+    targetZone,
+    provenanceAnchored
+  };
+}
+async function findTrustZoneRecordById(options) {
+  const { records } = await readTrustZoneRecords(options);
+  records.sort((a, b) => b.recordedAt.localeCompare(a.recordedAt));
+  return records.find((record) => record.recordId === options.recordId) ?? null;
+}
+async function promoteTrustZoneRecord(options) {
+  if (options.enabled !== true) {
+    throw new Error("trust zone promotion requires trustZonesEnabled=true");
+  }
+  if (options.promotionEnabled !== true) {
+    throw new Error("trust zone promotion requires quarantinePromotionEnabled=true");
+  }
+  const sourceRecord = await findTrustZoneRecordById({
+    memoryDir: options.memoryDir,
+    trustZoneStoreDir: options.trustZoneStoreDir,
+    recordId: assertSafePathSegment(assertString2(options.sourceRecordId, "sourceRecordId"), "sourceRecordId")
+  });
+  if (!sourceRecord) {
+    throw new Error(`source trust-zone record not found: ${options.sourceRecordId}`);
+  }
+  const plan = planTrustZonePromotion({
+    record: sourceRecord,
+    targetZone: options.targetZone
+  });
+  if (!plan.allowed) {
+    throw new Error(`trust-zone promotion denied: ${plan.reasons.join("; ")}`);
+  }
+  const recordedAt = assertIsoRecordedAt(assertString2(options.recordedAt, "recordedAt"));
+  const promotionReason = assertString2(options.promotionReason, "promotionReason");
+  const nextRecord = {
+    schemaVersion: 1,
+    recordId: buildPromotionRecordId(sourceRecord.recordId, options.targetZone, recordedAt),
+    zone: options.targetZone,
+    recordedAt,
+    kind: sourceRecord.kind,
+    summary: optionalString(options.summary) ?? sourceRecord.summary,
+    provenance: sourceRecord.provenance,
+    promotedFromZone: sourceRecord.zone,
+    entityRefs: sourceRecord.entityRefs,
+    tags: dedupeStrings([...sourceRecord.tags ?? [], "promotion"]),
+    metadata: {
+      ...sourceRecord.metadata ?? {},
+      sourceRecordId: sourceRecord.recordId,
+      promotionReason
+    }
+  };
+  if (options.dryRun === true) {
+    return {
+      plan,
+      wroteRecord: false,
+      record: nextRecord,
+      sourceRecord
+    };
+  }
+  const filePath = await recordTrustZoneRecord({
+    memoryDir: options.memoryDir,
+    trustZoneStoreDir: options.trustZoneStoreDir,
+    record: nextRecord
+  });
+  return {
+    plan,
+    wroteRecord: true,
+    record: nextRecord,
+    filePath,
+    sourceRecord
+  };
+}
 async function readTrustZoneRecords(options) {
   const rootDir = resolveTrustZoneStoreDir(options.memoryDir, options.trustZoneStoreDir);
   const files = await listJsonFiles(path53.join(rootDir, "zones"));
@@ -26546,6 +26669,24 @@ async function runTrustZoneStatusCliCommand(options) {
     promotionEnabled: options.quarantinePromotionEnabled
   });
 }
+async function runTrustZonePromoteCliCommand(options) {
+  const result = await promoteTrustZoneRecord({
+    memoryDir: options.memoryDir,
+    trustZoneStoreDir: options.trustZoneStoreDir,
+    enabled: options.trustZonesEnabled,
+    promotionEnabled: options.quarantinePromotionEnabled,
+    sourceRecordId: options.sourceRecordId,
+    targetZone: options.targetZone,
+    recordedAt: options.recordedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+    promotionReason: options.promotionReason,
+    summary: options.summary,
+    dryRun: options.dryRun === true
+  });
+  return {
+    ...result,
+    dryRun: options.dryRun === true
+  };
+}
 async function runSessionCheckCliCommand(options) {
   return analyzeSessionIntegrity({ memoryDir: options.memoryDir });
 }
@@ -27714,6 +27855,23 @@ function registerCli(api, orchestrator) {
         console.log(JSON.stringify(status, null, 2));
         console.log("OK");
       });
+      cmd.command("trust-zone-promote").description("Dry-run or apply a trust-zone promotion with provenance enforcement").requiredOption("--record-id <recordId>", "Source trust-zone record id").requiredOption("--target-zone <targetZone>", "Promotion target zone (working|trusted)").requiredOption("--reason <reason>", "Human-readable promotion reason").option("--recorded-at <isoTimestamp>", "Promotion timestamp (defaults to now)").option("--summary <summary>", "Optional replacement summary for the promoted record").option("--dry-run", "Show the promotion plan without writing the promoted record").action(async (...args) => {
+        const options = args[0] ?? {};
+        const result = await runTrustZonePromoteCliCommand({
+          memoryDir: orchestrator.config.memoryDir,
+          trustZoneStoreDir: orchestrator.config.trustZoneStoreDir,
+          trustZonesEnabled: orchestrator.config.trustZonesEnabled,
+          quarantinePromotionEnabled: orchestrator.config.quarantinePromotionEnabled,
+          sourceRecordId: String(options.recordId ?? ""),
+          targetZone: String(options.targetZone ?? ""),
+          promotionReason: String(options.reason ?? ""),
+          recordedAt: typeof options.recordedAt === "string" ? options.recordedAt : void 0,
+          summary: typeof options.summary === "string" ? options.summary : void 0,
+          dryRun: options.dryRun === true
+        });
+        console.log(JSON.stringify(result, null, 2));
+        console.log("OK");
+      });
       cmd.command("conversation-index-health").description("Show conversation index backend health and index stats").action(async () => {
         const health = await runConversationIndexHealthCliCommand(orchestrator);
         console.log(JSON.stringify(health, null, 2));