claude-memory-layer 1.0.45 → 1.0.47

package/dist/index.js

@@ -2622,6 +2622,7 @@ var VectorOutbox = class {
 // src/core/retrieval-debug-lanes.ts
 var RETRIEVAL_DEBUG_LANE_NAMES = [
   "raw_event",
+  "session_event",
   "session_summary",
   "graph_path",
   "facet_match"
@@ -10662,6 +10663,18 @@ var COMMAND_ARTIFACT_PATTERNS = [
   /<local-command-stdout>[\s\S]*?<\/local-command-stdout>/i,
   /<local-command-stderr>[\s\S]*?<\/local-command-stderr>/i
 ];
+var LOW_SIGNAL_CONTEXT_PATTERNS = [
+  /<environment_context\b[\s\S]*<\/environment_context>/i,
+  /<turn_aborted>/i,
+  /^#\s*AGENTS\.md\s+instructions\b[\s\S]*<INSTRUCTIONS>/i,
+  /^\s*(?:understood[,\s.]*)?(?:stopping|stopped|pausing|paused)\s+here\b[\s\S]{0,180}\blet\s+me\s+know\s+when\s+you(?:'d|\s+would)?\s+like\s+to\s+continue\b/i,
+  /^\s*\[?CONTEXT\s+COMPACTION\s*[—-]\s*REFERENCE\s+ONLY\]?\b[\s\S]{0,600}\b(?:earlier\s+turns\s+were\s+compacted|handoff\s+from\s+a\s+previous\s+context\s+window|active\s+task)\b/i,
+  /^\s*Summary\s+generation\s+was\s+unavailable\.\s*\d+\s+message\(s\)\s+were\s+removed\s+to\s+free\s+context\s+space\b/i,
+  /^\s*---\s*END\s+OF\s+CONTEXT\s+SUMMARY\b/i,
+  /^\s*\[Your\s+active\s+task\s+list\s+was\s+preserved\s+across\s+context\s+compression\]/i,
+  /^➜\s+\S+\s+git:\([^)]*\)\s+/i,
+  /^\$\s+\S+/i
+];
 var CONTINUATION_QUERY_PATTERNS = [
   /^\s*(?:continue|resume|next|what(?:'s| is)? next|next\s+(?:step|task|action)|recommended\s+(?:next\s+)?(?:step|task|action)|what should (?:we|i) do next)\??\s*$/i,
   /^\s*(?:응\s*)?(?:이어서(?:\s*진행(?:해줘)?)?|계속(?:\s*해줘)?|다음\s*(?:단계|작업|추천\s*작업|추천|할\s*일)?(?:은|는)?(?:\s*(?:뭐야|진행(?:해줘)?))?\??|남은\s*(?:추가(?:로)?\s*)?(?:(?:할\s*만한\s*)?(?:작업|일)|할\s*일)?(?:은|는)?\s*(?:있어|있나|있나요|뭐야)\??|추천\s*작업(?:은|는)?(?:\s*뭐야)?\??|진행해줘)\s*$/i
@@ -10673,7 +10686,7 @@ var SHORT_REPAIR_FOLLOW_UP_PATTERNS = [
 var CURRENT_STATE_QUERY_PATTERNS = [
   /\bcurrent\b.*\b(?:state|status|deployment|blocker|pr|pull request)\b/i,
   /\b(?:still|as current|current)\b.*\b(?:unresolved|open|pending|not completed)\b/i,
-  /\b(?:old|obsolete|stale|resolved|already resolved)\b.*\b(?:current|still|unresolved|open|state|status)\b/i,
+  /\b(?:old|obsolete|stale|resolved|already resolved)\b.*\b(?:current|still|unresolved|open|status)\b/i,
   /(?:현재|아직|이전|오래된|해결된).*(?:상태|미해결|열린|블로커|PR|풀리퀘스트)/i
 ];
 var STALE_CONTENT_PATTERNS = [
@@ -10819,6 +10832,21 @@ function isCommandArtifactQuery(query) {
   if (normalized.includes("command-name") || normalized.includes("command-message")) return true;
   return COMMAND_ARTIFACT_PATTERNS.some((pattern) => pattern.test(trimmed));
 }
+function isCommandArtifactContent(content) {
+  const trimmed = content.trim();
+  if (!trimmed) return false;
+  const normalized = trimmed.toLowerCase();
+  if (normalized.includes("local-command-stdout") || normalized.includes("local-command-stderr")) return true;
+  if (normalized.includes("command-name") || normalized.includes("command-message")) return true;
+  return COMMAND_ARTIFACT_PATTERNS.some((pattern) => pattern.test(trimmed));
+}
+function isLowSignalContextContent(content) {
+  const trimmed = content.trim();
+  if (!trimmed) return true;
+  if (isCommandArtifactContent(trimmed)) return true;
+  if (LOW_SIGNAL_CONTEXT_PATTERNS.some((pattern) => pattern.test(trimmed))) return true;
+  return false;
+}
 function isGenericContinuationQuery(query) {
   const trimmed = query.trim();
   if (!trimmed) return false;
@@ -10836,6 +10864,16 @@ function isShortRepairFollowUpQuery(query) {
   if (tokens.length > 8) return false;
   return SHORT_REPAIR_FOLLOW_UP_PATTERNS.some((pattern) => pattern.test(trimmed));
 }
+function isLowConfidenceContextFallbackQuery(query) {
+  const trimmed = query.trim();
+  if (!trimmed) return false;
+  if (isGenericContinuationQuery(trimmed) || isShortRepairFollowUpQuery(trimmed)) return true;
+  const terms = new Set(tokenizeQualityText(trimmed));
+  if ((terms.has("compacted") || terms.has("compaction")) && terms.has("handoff")) return false;
+  const hasContinuationRecall = /^(?:continue|resume)\b/i.test(trimmed) && (terms.has("work") || terms.has("step") || terms.has("task") || terms.has("last") || terms.has("completed"));
+  const hasValidationGateRecall = terms.has("validation") && (terms.has("gate") || terms.has("check")) && (terms.has("run") || terms.has("before") || terms.has("commit") || terms.has("committing") || terms.has("change"));
+  return hasContinuationRecall || hasValidationGateRecall;
+}
 function isCurrentStateQuery(query) {
   const trimmed = query.trim();
   if (!trimmed) return false;
@@ -11009,6 +11047,7 @@ var Retriever = class {
   }
   async retrieve(query, options = {}) {
     const opts = { ...DEFAULT_OPTIONS, ...options };
+    const retrievalMode = options.retrievalMode ?? ((options.strategy ?? DEFAULT_OPTIONS.strategy) === "auto" ? "session-event-hybrid" : "event");
     const sessionFilter = opts.scope?.sessionId ?? opts.sessionId;
     const fallbackTrace = [];
     const qualityQuery = buildRetrievalQualityQuery(query);
@@ -11039,6 +11078,7 @@ var Retriever = class {
       decayPolicy: opts.decayPolicy,
       intentRewrite: opts.intentRewrite === true,
       graphHop: opts.graphHop,
+      retrievalMode,
       projectScopeMode: opts.projectScopeMode,
       projectHash: opts.projectHash,
       allowedProjectHashes: opts.allowedProjectHashes,
@@ -11057,6 +11097,7 @@ var Retriever = class {
         rerankWeights: opts.rerankWeights,
         decayPolicy: opts.decayPolicy,
         graphHop: opts.graphHop,
+        retrievalMode,
         projectScopeMode: opts.projectScopeMode,
         projectHash: opts.projectHash,
         allowedProjectHashes: opts.allowedProjectHashes,
@@ -11076,6 +11117,7 @@ var Retriever = class {
         rerankWeights: opts.rerankWeights,
         decayPolicy: opts.decayPolicy,
         graphHop: opts.graphHop,
+        retrievalMode,
         projectScopeMode: opts.projectScopeMode,
         projectHash: opts.projectHash,
         allowedProjectHashes: opts.allowedProjectHashes,
@@ -11096,14 +11138,37 @@ var Retriever = class {
         query,
         minScore: opts.minScore
       });
+      const expandedSummary = retrievalMode === "session-event-hybrid" ? await this.expandSessionEventHybrid(filteredSummary, {
+        query: qualityQuery,
+        currentStateQuery: query,
+        limit: opts.topK * 4
+      }) : filteredSummary;
+      const scopedExpandedSummary = retrievalMode === "session-event-hybrid" ? await this.applyScopeFilters(expandedSummary, {
+        scope: opts.scope,
+        projectScopeMode: opts.projectScopeMode,
+        projectHash: opts.projectHash,
+        allowedProjectHashes: opts.allowedProjectHashes,
+        facets: opts.facets
+      }) : expandedSummary;
+      const finalSummary = retrievalMode === "session-event-hybrid" ? this.applyQualityFilters(scopedExpandedSummary, {
+        query,
+        minScore: opts.minScore
+      }) : scopedExpandedSummary;
       current = {
-        results: filteredSummary,
-        candidateResults: filteredSummary,
-        matchResult: this.matcher.matchSearchResults(filteredSummary, () => 0)
+        results: finalSummary,
+        candidateResults: finalSummary,
+        matchResult: this.matcher.matchSearchResults(finalSummary, () => 0)
       };
       fallbackTrace.push("fallback:summary");
     }
-    const memories = await this.enrichResults(current.results.slice(0, opts.topK), opts);
+    const selectedResults = current.results.slice(0, opts.topK).filter((result2) => {
+      if (current.matchResult.confidence !== "none") return true;
+      if (isLowConfidenceContextFallbackQuery(query)) {
+        return (result2.semanticScore ?? result2.score) >= 0.5 || result2.score >= 0.5;
+      }
+      return (result2.semanticScore ?? result2.score) >= 0.62 || result2.score >= 0.62;
+    });
+    const memories = await this.enrichResults(selectedResults, opts, query);
     const context = this.buildContext(memories, opts.maxTokens);
     return {
       memories,
@@ -11111,7 +11176,7 @@ var Retriever = class {
       totalTokens: this.estimateTokens(context),
       context,
       fallbackTrace,
-      selectedDebug: current.results.slice(0, opts.topK).map((r) => this.debugDetailForResult(r)),
+      selectedDebug: selectedResults.map((r) => this.debugDetailForResult(r)),
       candidateDebug: (current.candidateResults || []).slice(0, Math.max(opts.topK * 3, 20)).map((r) => this.debugDetailForResult(r)),
       rawQueryText: current.queryRewriteKind ? query : void 0,
       effectiveQueryText: current.effectiveQueryText,
@@ -11178,13 +11243,18 @@ var Retriever = class {
         initialResults = this.mergeResults(initialResults, rewrittenResults, input.topK * 3);
       }
     }
-    const expandedResults = input.graphHop?.enabled === false ? initialResults : await this.expandGraphHops(initialResults, {
+    const graphExpandedResults = input.graphHop?.enabled === false ? initialResults : await this.expandGraphHops(initialResults, {
       query,
       queryGraphEnabled: this.queryGraphExpansionEnabled,
       maxHops: clampGraphHops(input.graphHop?.maxHops ?? 1),
       hopPenalty: Math.max(0, input.graphHop?.hopPenalty ?? 0.08),
       limit: input.topK * 4
     });
+    const expandedResults = input.retrievalMode === "session-event-hybrid" ? await this.expandSessionEventHybrid(graphExpandedResults, {
+      query: rerankQuery,
+      currentStateQuery: query,
+      limit: input.topK * 4
+    }) : graphExpandedResults;
     const rerankedResults = input.rerankWithKeyword ? this.rerankByKeywordOverlap(expandedResults, rerankQuery, input.rerankWeights, input.decayPolicy) : expandedResults;
     const filtered = await this.applyScopeFilters(rerankedResults, {
       scope: input.scope,
@@ -11206,6 +11276,7 @@ var Retriever = class {
     if (isCurrentStateQuery(options.query)) {
       filtered = filtered.filter((result2) => !isStaleOrSupersededContent(result2.content));
     }
+    filtered = filtered.filter((result2) => !isLowSignalContextContent(result2.content));
     filtered = filtered.filter(
       (result2) => this.isGraphPathResult(result2) || hasDiscriminativeTermOverlap(options.query, result2.content)
     );
@@ -11231,6 +11302,47 @@ var Retriever = class {
     }
     return [...byId.values()].sort((a, b) => b.score - a.score).slice(0, limit);
   }
+  async expandSessionEventHybrid(seeds, opts) {
+    if (seeds.length === 0 || opts.limit <= seeds.length) return seeds;
+    const queryTokens = this.tokenize(opts.query);
+    if (queryTokens.length === 0) return seeds;
+    const byId = /* @__PURE__ */ new Map();
+    for (const seed of seeds) byId.set(seed.eventId, seed);
+    const bestSeedBySession = /* @__PURE__ */ new Map();
+    for (const seed of [...seeds].sort((a, b) => b.score - a.score || compareStable(a.eventId, b.eventId))) {
+      if (!seed.sessionId || bestSeedBySession.has(seed.sessionId)) continue;
+      bestSeedBySession.set(seed.sessionId, seed);
+    }
+    const suppressStaleState = isCurrentStateQuery(opts.currentStateQuery);
+    for (const [sessionId, seed] of bestSeedBySession) {
+      const sessionEvents = await this.eventStore.getSessionEvents(sessionId);
+      for (const event of [...sessionEvents].sort((a, b) => a.timestamp.getTime() - b.timestamp.getTime())) {
+        if (byId.has(event.id)) continue;
+        if (isLowSignalContextContent(event.content)) continue;
+        if (suppressStaleState && isStaleOrSupersededContent(event.content)) continue;
+        const lexicalScore = this.keywordOverlap(queryTokens, this.tokenize(event.content));
+        if (lexicalScore <= 0) continue;
+        if (shouldApplyTechnicalGuard(opts.query) && !hasTechnicalTermOverlap(opts.query, event.content)) continue;
+        const score = Math.min(0.95, Math.max(0.35, seed.score * 0.72 + lexicalScore * 0.28));
+        const row = withRetrievalLane({
+          id: `session-event-${seed.eventId}-${event.id}`,
+          eventId: event.id,
+          content: event.content,
+          score,
+          sessionId: event.sessionId,
+          eventType: event.eventType,
+          timestamp: event.timestamp.toISOString(),
+          semanticScore: seed.semanticScore ?? seed.score,
+          lexicalScore,
+          recencyScore: seed.recencyScore
+        }, { lane: "session_event", reason: `same_session:${seed.eventId}`, score });
+        byId.set(row.eventId, row);
+        if (byId.size >= opts.limit) break;
+      }
+      if (byId.size >= opts.limit) break;
+    }
+    return [...byId.values()].sort((a, b) => b.score - a.score || compareStable(a.eventId, b.eventId)).slice(0, opts.limit);
+  }
   async expandGraphHops(seeds, opts) {
     const byId = /* @__PURE__ */ new Map();
     for (const s of seeds) byId.set(s.eventId, s);
@@ -11546,7 +11658,7 @@ var Retriever = class {
   async retrieveRecent(limit = 100) {
     return this.eventStore.getRecentEvents(limit);
   }
-  async enrichResults(results, options) {
+  async enrichResults(results, options, query) {
     const memories = [];
     for (const result2 of results) {
       const event = await this.eventStore.getEvent(result2.eventId);
@@ -11556,13 +11668,13 @@ var Retriever = class {
       }
       let sessionContext;
       if (options.includeSessionContext) {
-        sessionContext = await this.getSessionContext(event.sessionId, event.id);
+        sessionContext = await this.getSessionContext(event.sessionId, event.id, query);
       }
       memories.push({ event, score: result2.score, sessionContext });
     }
     return memories;
   }
-  async getSessionContext(sessionId, eventId) {
+  async getSessionContext(sessionId, eventId, query) {
     const sessionEvents = await this.eventStore.getSessionEvents(sessionId);
     const eventIndex = sessionEvents.findIndex((e) => e.id === eventId);
     if (eventIndex === -1) return void 0;
@@ -11570,7 +11682,9 @@ var Retriever = class {
     const end = Math.min(sessionEvents.length, eventIndex + 2);
     const contextEvents = sessionEvents.slice(start, end);
     if (contextEvents.length <= 1) return void 0;
-    return contextEvents.filter((e) => e.id !== eventId).map((e) => `[${e.eventType}]: ${e.content.slice(0, 200)}...`).join("\n");
+    const suppressStaleState = isCurrentStateQuery(query);
+    const contextLines = contextEvents.filter((e) => e.id !== eventId).filter((e) => !isLowSignalContextContent(e.content)).filter((e) => !(suppressStaleState && isStaleOrSupersededContent(e.content))).map((e) => `[${e.eventType}]: ${e.content.slice(0, 200)}...`);
+    return contextLines.length > 0 ? contextLines.join("\n") : void 0;
   }
   buildUnifiedContext(projectResult, sharedMemories) {
     let context = projectResult.context;
@@ -17118,12 +17232,13 @@ var productValidationMatrix = [
     requirements: [
       "Expose an agent-ready project context pack that combines relevant retrieval results with recent project timeline.",
       "Support projectPath scoping so Hermes, Codex, and Claude Code can share the same project memory backend.",
-      "Keep output compact and citation-oriented so agents can follow up with source-ref or timeline tools."
+      "Keep output compact and citation-oriented so agents can follow up with source-ref or timeline tools.",
+      "Document MCP-only context-pack budget controls (`maxChars`, approximate `maxTokens`, and `compression: off|safe|aggressive`) and make the CLI/API parity boundary explicit."
     ],
     evidence: [
-      { kind: "test", ref: "tests/extensions/mcp-context-tools.test.ts", note: "Asserts context-pack output, projectPath routing, compact relevant memory citations, and recent timeline inclusion." },
-      { kind: "source", ref: "src/extensions/mcp/handlers.ts", note: "mem-context-pack handler formats relevant memories plus session summaries." },
-      { kind: "source", ref: "src/extensions/mcp/tools.ts", note: "MCP tool schema advertises projectPath, topK, recentLimit, and sessionLimit options." }
+      { kind: "test", ref: "tests/extensions/mcp-context-tools.test.ts", note: "Asserts context-pack output, projectPath routing, compact relevant memory citations, sourceRef preservation, maxChars/maxTokens budget enforcement, compression modes, and recent timeline inclusion." },
+      { kind: "source", ref: "src/extensions/mcp/handlers.ts", note: "mem-context-pack handler formats relevant memories plus session summaries and validates MCP-only budget/compression arguments before storage access." },
+      { kind: "source", ref: "src/extensions/mcp/tools.ts", note: "MCP tool schema advertises projectPath, topK, recentLimit, sessionLimit, maxChars, maxTokens, and compression options; CLI/API parity is documented as MCP-only for context-pack generation." }
     ]
   },
   {
@@ -17238,6 +17353,985 @@ function renderProductValidationMatrixMarkdown(matrix = productValidationMatrix)
 `;
 }
 
+// src/core/source/source-schema.ts
+var SOURCE_PRIVACY_CLASSES = Object.freeze(["public", "internal", "confidential", "restricted"]);
+var SOURCE_CAPTURE_MODES = Object.freeze(["snapshot", "append-only-log", "stream", "metadata-only", "history_import"]);
+var SourceContractValidationError = class extends Error {
+  violations;
+  constructor(violations) {
+    super(`Source contract validation failed: ${violations.map((violation2) => violation2.code).join(", ")}`);
+    this.name = "SourceContractValidationError";
+    this.violations = violations;
+  }
+};
+function isSourcePrivacyClass(value) {
+  return isOneOf(SOURCE_PRIVACY_CLASSES, value);
+}
+function isSourceCaptureMode(value) {
+  return isOneOf(SOURCE_CAPTURE_MODES, value);
+}
+function defineSourceSchema(schema) {
+  const prepared = prepareSourceSchema(schema);
+  if (prepared.violations.length > 0 || !prepared.record) {
+    throw new SourceContractValidationError(prepared.violations);
+  }
+  return Object.freeze(freezeSourceSchemaDeclaration(prepared.record));
+}
+function validateSourceSchema(schema, path12 = "source") {
+  return prepareSourceSchema(schema, path12).violations;
+}
+function prepareSourceSchema(schema, path12 = "source") {
+  const snapshot = snapshotAllowedRecordFields(schema, ["id", "version", "privacyClass", "captureMode", "description", "metadataSchema"], {
+    path: path12,
+    requiredCode: "source.required",
+    requiredMessage: "Source schema declaration is required.",
+    unknownCode: "source.unknown_field",
+    unknownMessage: "Source schema declaration contains unsupported fields.",
+    accessorCode: "source.accessor_field",
+    accessorMessage: "Source schema declaration fields must be data properties."
+  });
+  if (!snapshot.record) return snapshot;
+  return {
+    record: snapshot.record,
+    violations: validateSourceSchemaRecord(snapshot.record, path12, snapshot.violations)
+  };
+}
+function validateSourceSchemaRecord(schema, path12, initialViolations) {
+  const violations = [...initialViolations];
+  const id = getOwnField(schema, "id");
+  const version = getOwnField(schema, "version");
+  const privacyClass = getOwnField(schema, "privacyClass");
+  const captureMode = getOwnField(schema, "captureMode");
+  const description = getOwnField(schema, "description");
+  const metadataSchema = getOwnField(schema, "metadataSchema");
+  if (!hasText(id)) {
+    violations.push(violation("source.id.required", `${path12}.id`, "Source schema id must be non-empty."));
+  } else {
+    if (!isStableContractIdentifier(id)) {
+      violations.push(violation("source.id.unstable", `${path12}.id`, "Source schema id must be stable and must not include a local absolute path."));
+    }
+    if (looksLikePrivacySensitiveSourceValue(id)) {
+      violations.push(violation("source.id.privacy_sensitive", `${path12}.id`, "Source schema id must not leak local state handles or credential-shaped values."));
+    }
+  }
+  if (!hasText(version)) {
+    violations.push(violation("source.version.required", `${path12}.version`, "Source schema version must be non-empty."));
+  } else if (looksLikePrivacySensitiveSourceValue(version)) {
+    violations.push(violation("source.version.privacy_sensitive", `${path12}.version`, "Source schema version must not leak local state handles or credential-shaped values."));
+  }
+  if (!isSourcePrivacyClass(privacyClass)) {
+    violations.push(violation("source.privacyClass.invalid", `${path12}.privacyClass`, "Source schema privacyClass must be one of the bounded source privacy classes."));
+  }
+  if (!isSourceCaptureMode(captureMode)) {
+    violations.push(violation("source.captureMode.invalid", `${path12}.captureMode`, "Source schema captureMode must be one of the bounded source capture modes."));
+  }
+  if (description !== void 0 && typeof description !== "string") {
+    violations.push(violation("source.description.invalid", `${path12}.description`, "Source schema description must be a string when present."));
+  } else if (hasText(description) && looksLikePrivacySensitiveSourceValue(description)) {
+    violations.push(violation("source.description.privacy_sensitive", `${path12}.description`, "Source schema description must not leak local state handles or credential-shaped values."));
+  }
+  if (metadataSchema !== void 0 && typeof metadataSchema !== "string") {
+    violations.push(violation("source.metadataSchema.invalid", `${path12}.metadataSchema`, "Source schema metadataSchema must be a string when present."));
+  } else if (hasText(metadataSchema) && looksLikePrivacySensitiveSourceValue(metadataSchema)) {
+    violations.push(violation("source.metadataSchema.privacy_sensitive", `${path12}.metadataSchema`, "Source schema metadataSchema must not leak local state handles or credential-shaped values."));
+  }
+  return violations;
+}
+function freezeSourceSchemaDeclaration(schema) {
+  const id = getOwnField(schema, "id");
+  const version = getOwnField(schema, "version");
+  const privacyClass = getOwnField(schema, "privacyClass");
+  const captureMode = getOwnField(schema, "captureMode");
+  const ownDescription = getOwnField(schema, "description");
+  const ownMetadataSchema = getOwnField(schema, "metadataSchema");
+  const defined = {
+    id,
+    version,
+    privacyClass,
+    captureMode
+  };
+  if (ownDescription !== void 0) defined.description = ownDescription;
+  if (ownMetadataSchema !== void 0) defined.metadataSchema = ownMetadataSchema;
+  return defined;
+}
+function hasText(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+function isArrayForSourceSnapshot(value) {
+  try {
+    return Array.isArray(value);
+  } catch {
+    return false;
+  }
+}
+function isRecord6(value) {
+  return typeof value === "object" && value !== null && !isArrayForSourceSnapshot(value);
+}
+function hasOwnField(record, key) {
+  return Object.prototype.hasOwnProperty.call(record, key);
+}
+function getOwnField(record, key) {
+  try {
+    const descriptor = Object.getOwnPropertyDescriptor(record, key);
+    return descriptor && "value" in descriptor ? descriptor.value : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function safeOwnKeysForSourceSnapshot(value, path12, code, message) {
+  try {
+    return { keys: Reflect.ownKeys(value), violations: [] };
+  } catch {
+    return { keys: [], violations: [violation(code, path12, message)] };
+  }
+}
+function safeGetOwnPropertyDescriptorForSourceSnapshot(value, key, path12, code, message) {
+  try {
+    return { descriptor: Object.getOwnPropertyDescriptor(value, key), violations: [] };
+  } catch {
+    return { violations: [violation(code, path12, message)] };
+  }
+}
+function safeReadOwnDataPropertyForSourceSnapshot(value, key, descriptor, path12, code, message) {
+  if (!("value" in descriptor)) {
+    return { violations: [violation(code, path12, message)] };
+  }
+  try {
+    const readValue = Reflect.get(value, key, value);
+    if (!Object.is(readValue, descriptor.value)) {
+      return { violations: [violation(code, path12, message)] };
+    }
+    return { value: descriptor.value, violations: [] };
+  } catch {
+    return { violations: [violation(code, path12, message)] };
+  }
+}
+function snapshotAllowedRecordFields(value, allowedFields, options) {
+  if (!isRecord6(value)) {
+    return {
+      record: void 0,
+      violations: [violation(options.requiredCode, options.path, options.requiredMessage)]
+    };
+  }
+  const allowed = new Set(allowedFields);
+  const record = /* @__PURE__ */ Object.create(null);
+  const keySnapshot = safeOwnKeysForSourceSnapshot(value, options.path, options.accessorCode, options.accessorMessage);
+  const violations = [...keySnapshot.violations];
+  for (const key of keySnapshot.keys) {
+    if (typeof key !== "string" || !allowed.has(key)) {
+      violations.push(violation(options.unknownCode, options.path, options.unknownMessage));
+      continue;
+    }
+    const descriptorSnapshot = safeGetOwnPropertyDescriptorForSourceSnapshot(value, key, `${options.path}.${key}`, options.accessorCode, options.accessorMessage);
+    violations.push(...descriptorSnapshot.violations);
+    const descriptor = descriptorSnapshot.descriptor;
+    if (!descriptor || !("value" in descriptor)) {
+      violations.push(violation(options.accessorCode, `${options.path}.${key}`, options.accessorMessage));
+      continue;
+    }
+    const readSnapshot = safeReadOwnDataPropertyForSourceSnapshot(value, key, descriptor, `${options.path}.${key}`, options.accessorCode, options.accessorMessage);
+    violations.push(...readSnapshot.violations);
+    if (readSnapshot.violations.length > 0) continue;
+    record[key] = readSnapshot.value;
+  }
+  return { record, violations };
+}
+function isStableContractIdentifier(value) {
+  if (!hasText(value)) return false;
+  if (looksLikeLocalAbsolutePath(value)) return false;
+  return /^[A-Za-z0-9][A-Za-z0-9._:@-]*$/.test(value);
+}
+function looksLikeLocalAbsolutePath(value) {
+  const trimmed = value.trim();
+  if (trimmed.length === 0) return false;
+  return sourceValueVariants(trimmed).some((candidate) => {
+    const normalized = candidate.replace(/\\/g, "/");
+    return /^file:\/*/i.test(normalized) || /[A-Za-z]:\//.test(normalized) || normalized.startsWith("/") || /(?:^|[^A-Za-z0-9])file:\/*/i.test(normalized) || /(?:^|[^A-Za-z0-9])\/(?!\/)/.test(normalized) || /(?:^|[^A-Za-z0-9])(?:Users|home|root|tmp|var|data)(?:\/|$)/.test(normalized) || /(?:^|\/(?:\/*))(?:Users|home|root|tmp|var|data)(?:\/|$)/.test(normalized) || /(?:^|[^A-Za-z0-9])\\\\/.test(candidate);
+  });
+}
+function looksLikePrivacySensitiveSourceValue(value, fieldName = "") {
+  if (typeof value !== "string") return false;
+  const trimmed = value.trim();
+  if (trimmed.length === 0) return false;
+  return sourceValueVariants(trimmed).some((candidate) => {
+    const normalized = candidate.replace(/\\/g, "/");
+    return looksLikeLocalAbsolutePath(candidate) || /(?:^|[\s:=,;|()[\]{}<>"'`])~(?:\/|$)/.test(normalized) || /(?:^|\/)\.hermes(?:\/|$)/i.test(normalized) || /(?:^|[^A-Za-z0-9])state\.db(?:$|[^A-Za-z0-9])/i.test(normalized) || looksLikeCredentialAssignment(candidate) || looksLikeBareCredentialToken(candidate) || looksLikeCredentialFieldValue(fieldName, candidate) || /\bBearer\s+(?!\[?redacted\]?(?:$|[\s&;,|()[\]{}<>"'`]))[A-Za-z0-9._~+/=-]{3,}/i.test(candidate) || /(?:^|[\s:=,;|()[\]{}<>"'`])[a-z][a-z0-9+.-]*:\/\/[^\s/@:]+:[^\s/@]+@/i.test(candidate) || /(?:^|[\s:=,;|()[\]{}<>"'`])[a-z][a-z0-9+.-]*:\/\/:[^\s/@]+@/i.test(candidate);
+  });
+}
+function violation(code, path12, message) {
+  return { code, path: path12, message };
+}
+function looksLikeCredentialAssignment(value) {
+  return /(?:^|[^A-Za-z0-9_-])(?:api[_-]?key|access[_-]?token|auth[_-]?token|client[_-]?secret|secret|password|passwd|authorization|token)\s*[:=]\s*(?!(?:Bearer\s+)?\[?redacted\]?(?:$|[\s&;,|()[\]{}<>"'`]))(?:Bearer\s+)?[^\s&;,|]{3,}/i.test(value);
+}
+function looksLikeBareCredentialToken(value) {
+  if (/^\[?redacted\]?$/i.test(value.trim())) return false;
+  const tokenBoundary = "(?:^|[^A-Za-z0-9_-])";
+  const tokenEnd = "(?:$|[^A-Za-z0-9_-])";
+  return [
+    new RegExp(`${tokenBoundary}sk[-_][A-Za-z0-9][A-Za-z0-9_-]{2,}${tokenEnd}`),
+    new RegExp(`${tokenBoundary}gh[a-z]_[A-Za-z0-9_]{3,}${tokenEnd}`),
+    new RegExp(`${tokenBoundary}github_pat_[A-Za-z0-9_]{3,}${tokenEnd}`),
+    new RegExp(`${tokenBoundary}xox[abprs]-[A-Za-z0-9-]{3,}${tokenEnd}`),
+    new RegExp(`${tokenBoundary}hf_[A-Za-z0-9]{3,}${tokenEnd}`),
+    new RegExp(`${tokenBoundary}glpat-[A-Za-z0-9_-]{3,}${tokenEnd}`),
+    new RegExp(`${tokenBoundary}(?:AKIA|ASIA)[A-Z0-9]{8,}${tokenEnd}`),
+    new RegExp(`${tokenBoundary}AIza[A-Za-z0-9_-]{3,}${tokenEnd}`),
+    new RegExp(`${tokenBoundary}eyJ[A-Za-z0-9_-]*.[A-Za-z0-9_-]{3,}.[A-Za-z0-9_-]{3,}${tokenEnd}`)
+  ].some((pattern) => pattern.test(value));
+}
+function sourceValueVariants(value) {
+  const variants = /* @__PURE__ */ new Set([value]);
+  let current = value;
+  for (let attempt = 0; attempt < 5 && current.includes("%"); attempt += 1) {
+    const decoded = decodePercentEncodedBestEffort(current);
+    if (decoded === current) break;
+    variants.add(decoded);
+    current = decoded;
+  }
+  return [...variants];
+}
+function decodePercentEncodedBestEffort(value) {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value.replace(/%[0-9A-Fa-f]{2}/g, (match) => String.fromCharCode(Number.parseInt(match.slice(1), 16)));
+  }
+}
+function looksLikeCredentialFieldValue(fieldName, value) {
+  return /^(?:api[_-]?key|access[_-]?token|auth[_-]?token|client[_-]?secret|secret|password|passwd|authorization|token)$/i.test(fieldName.trim()) && !/^\[?redacted\]?$/i.test(value.trim());
+}
+function isOneOf(values, value) {
+  return typeof value === "string" && values.includes(value);
+}
+
+// src/core/source/source-ref.ts
+function createSourceRef(ref) {
+  const prepared = prepareSourceRef(ref);
+  if (prepared.violations.length > 0 || !prepared.record) {
+    throw new SourceContractValidationError(prepared.violations);
+  }
+  const kind = getOwnField(prepared.record, "kind");
+  const stableId = getOwnField(prepared.record, "stableId");
+  const publicHandle = getOwnField(prepared.record, "publicHandle");
+  const evidenceHandle = getOwnField(prepared.record, "evidenceHandle");
+  const privacyClass = getOwnField(prepared.record, "privacyClass");
+  const captureMode = getOwnField(prepared.record, "captureMode");
+  return Object.freeze({
+    kind,
+    stableId,
+    publicHandle,
+    ...evidenceHandle !== void 0 ? { evidenceHandle } : {},
+    privacyClass,
+    captureMode,
+    ...prepared.metadata !== void 0 ? { metadata: prepared.metadata } : {}
+  });
+}
+function validateSourceRef(ref, path12 = "sourceRef") {
+  return prepareSourceRef(ref, path12).violations;
+}
+function prepareSourceRef(ref, path12 = "sourceRef") {
+  const snapshot = snapshotAllowedRecordFields(ref, ["kind", "stableId", "publicHandle", "evidenceHandle", "privacyClass", "captureMode", "metadata"], {
+    path: path12,
+    requiredCode: "sourceRef.required",
+    requiredMessage: "Source ref is required.",
+    unknownCode: "sourceRef.unknown_field",
+    unknownMessage: "Source ref contains unsupported fields.",
+    accessorCode: "sourceRef.accessor_field",
+    accessorMessage: "Source ref fields must be data properties."
+  });
+  if (!snapshot.record) {
+    return { violations: snapshot.violations };
+  }
+  const violations = [...snapshot.violations];
+  const kind = getOwnField(snapshot.record, "kind");
+  const stableId = getOwnField(snapshot.record, "stableId");
+  const publicHandle = getOwnField(snapshot.record, "publicHandle");
+  const evidenceHandle = getOwnField(snapshot.record, "evidenceHandle");
+  const privacyClass = getOwnField(snapshot.record, "privacyClass");
+  const captureMode = getOwnField(snapshot.record, "captureMode");
+  const metadata = getOwnField(snapshot.record, "metadata");
+  if (!hasText(kind)) {
+    violations.push(violation("sourceRef.kind.required", `${path12}.kind`, "Source ref kind must be non-empty."));
+  } else if (looksLikePrivacySensitiveSourceValue(kind)) {
+    violations.push(violation("sourceRef.kind.privacy_sensitive", `${path12}.kind`, "Source ref kind must not leak local state handles or credential-shaped values."));
+  }
+  if (!hasText(stableId)) {
+    violations.push(violation("sourceRef.stableId.required", `${path12}.stableId`, "Source ref stableId must be non-empty."));
+  } else {
+    if (looksLikeLocalAbsolutePath(stableId)) {
+      violations.push(violation("sourceRef.stableId.absolute_local_path", `${path12}.stableId`, "Source ref stableId must not be a local absolute path."));
+    }
+    if (looksLikePrivacySensitiveSourceValue(stableId)) {
+      violations.push(violation("sourceRef.stableId.privacy_sensitive", `${path12}.stableId`, "Source ref stableId must not leak local state handles or credential-shaped values."));
+    }
+  }
+  validatePublicHandle(publicHandle, `${path12}.publicHandle`, violations);
+  validateEvidenceHandle(evidenceHandle, `${path12}.evidenceHandle`, violations);
+  if (!isSourcePrivacyClass(privacyClass)) {
+    violations.push(violation("sourceRef.privacyClass.invalid", `${path12}.privacyClass`, "Source ref privacyClass must be one of the bounded source privacy classes."));
+  }
+  if (!isSourceCaptureMode(captureMode)) {
+    violations.push(violation("sourceRef.captureMode.invalid", `${path12}.captureMode`, "Source ref captureMode must be one of the bounded source capture modes."));
+  }
+  const metadataSnapshot = snapshotSourceRefMetadata(metadata, `${path12}.metadata`);
+  violations.push(...metadataSnapshot.violations);
+  return {
+    record: snapshot.record,
+    metadata: metadataSnapshot.record,
+    violations
+  };
+}
+function validatePublicHandle(value, path12, violations) {
+  if (!hasText(value)) {
+    violations.push(violation("sourceRef.publicHandle.required", path12, "Source ref publicHandle must be non-empty."));
+    return;
+  }
+  if (looksLikeLocalAbsolutePath(value)) {
+    violations.push(violation("sourceRef.publicHandle.absolute_local_path", path12, "Source ref publicHandle must not leak a local absolute path."));
+  }
+  if (looksLikePrivacySensitiveSourceValue(value)) {
+    violations.push(violation("sourceRef.publicHandle.privacy_sensitive", path12, "Source ref publicHandle must not leak local state handles or credential-shaped values."));
+  }
+}
+function validateEvidenceHandle(value, path12, violations) {
+  if (value === void 0) return;
+  if (!hasText(value)) {
+    violations.push(violation("sourceRef.evidenceHandle.invalid", path12, "Source ref evidenceHandle must be a non-empty string when present."));
+    return;
+  }
+  if (looksLikeLocalAbsolutePath(value)) {
+    violations.push(violation("sourceRef.evidenceHandle.absolute_local_path", path12, "Source ref evidenceHandle must not leak a local absolute path."));
+  }
+  if (looksLikePrivacySensitiveSourceValue(value)) {
+    violations.push(violation("sourceRef.evidenceHandle.privacy_sensitive", path12, "Source ref evidenceHandle must not leak local state handles or credential-shaped values."));
+  }
+}
+function snapshotSourceRefMetadata(metadata, path12) {
+  if (metadata === void 0) return { violations: [] };
+  if (!isRecord6(metadata)) {
+    return {
+      violations: [violation("sourceRef.metadata.invalid", path12, "Source ref metadata must be an object when present.")]
+    };
+  }
+  const snapshot = /* @__PURE__ */ Object.create(null);
+  const keySnapshot = safeOwnKeysForSourceSnapshot(metadata, path12, "sourceRef.metadata.accessor_field", "Source ref metadata values must be data properties.");
+  const violations = [...keySnapshot.violations];
+  keySnapshot.keys.forEach((key, index) => {
+    if (typeof key !== "string") {
+      const valuePath2 = `${path12}.[symbol-${index}]`;
+      violations.push(violation("sourceRef.metadata.invalid_key", valuePath2, "Source ref metadata keys must be strings."));
+      const descriptorSnapshot2 = safeGetOwnPropertyDescriptorForSourceSnapshot(metadata, key, valuePath2, "sourceRef.metadata.accessor_field", "Source ref metadata values must be data properties.");
+      violations.push(...descriptorSnapshot2.violations);
+      const descriptor2 = descriptorSnapshot2.descriptor;
+      if (!descriptor2 || !("value" in descriptor2)) {
+        violations.push(violation("sourceRef.metadata.accessor_field", valuePath2, "Source ref metadata values must be data properties."));
+        return;
+      }
+      const readSnapshot2 = safeReadOwnDataPropertyForSourceSnapshot(metadata, key, descriptor2, valuePath2, "sourceRef.metadata.accessor_field", "Source ref metadata values must be data properties.");
+      violations.push(...readSnapshot2.violations);
+      if (readSnapshot2.violations.length > 0) return;
+      validateMetadataValue(readSnapshot2.value, valuePath2, propertyKeyDescription(key), violations);
+      return;
+    }
+    const valuePath = metadataEntryPath(path12, key, index);
+    if (looksLikePrivacySensitiveSourceValue(key)) {
+      violations.push(violation("sourceRef.metadata.privacy_sensitive", valuePath, "Source ref metadata keys must not leak local state handles or credential-shaped values."));
+    }
+    const descriptorSnapshot = safeGetOwnPropertyDescriptorForSourceSnapshot(metadata, key, valuePath, "sourceRef.metadata.accessor_field", "Source ref metadata values must be data properties.");
+    violations.push(...descriptorSnapshot.violations);
+    const descriptor = descriptorSnapshot.descriptor;
+    if (!descriptor || !("value" in descriptor)) {
+      violations.push(violation("sourceRef.metadata.accessor_field", valuePath, "Source ref metadata values must be data properties."));
+      return;
+    }
+    const readSnapshot = safeReadOwnDataPropertyForSourceSnapshot(metadata, key, descriptor, valuePath, "sourceRef.metadata.accessor_field", "Source ref metadata values must be data properties.");
+    violations.push(...readSnapshot.violations);
+    if (readSnapshot.violations.length > 0) return;
+    validateMetadataValue(readSnapshot.value, valuePath, key, violations);
+    if (isSourceRefMetadataValue(readSnapshot.value)) {
+      snapshot[key] = readSnapshot.value;
+    }
+  });
+  return { record: Object.freeze(snapshot), violations };
+}
+function isSourceRefMetadataValue(value) {
+  return value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+}
+function validateMetadataValue(value, valuePath, key, violations) {
+  if (value === null) return;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      violations.push(violation("sourceRef.metadata.invalid_value", valuePath, "Source ref metadata numbers must be finite."));
+    }
+    if (looksLikePrivacySensitiveSourceValue(String(value), key)) {
+      violations.push(violation("sourceRef.metadata.privacy_sensitive", valuePath, "Source ref metadata must not leak local state handles or credential-shaped values."));
+    }
+    return;
+  }
+  if (typeof value === "boolean") {
+    if (looksLikePrivacySensitiveSourceValue(String(value), key)) {
+      violations.push(violation("sourceRef.metadata.privacy_sensitive", valuePath, "Source ref metadata must not leak local state handles or credential-shaped values."));
+    }
+    return;
+  }
+  if (typeof value === "string") {
+    if (looksLikePrivacySensitiveSourceValue(value, key)) {
+      violations.push(violation("sourceRef.metadata.privacy_sensitive", valuePath, "Source ref metadata must not leak local state handles or credential-shaped values."));
+    }
+    return;
+  }
+  violations.push(violation("sourceRef.metadata.invalid_value", valuePath, "Source ref metadata values must be scalar strings, finite numbers, booleans, or null."));
+}
+function propertyKeyDescription(key) {
+  return typeof key === "symbol" ? String(key.description ?? "") : "";
+}
+function metadataEntryPath(path12, key, index) {
+  if (looksLikePrivacySensitiveSourceValue(key)) {
+    return `${path12}.[redacted-key-${index}]`;
+  }
+  const sanitizedKey = key.replace(/[^A-Za-z0-9._:-]+/g, "_").slice(0, 64);
+  return sanitizedKey ? `${path12}.${sanitizedKey}` : `${path12}.${index}`;
+}
+
+// src/core/source/source-transformations.ts
+var MAX_SOURCE_TRANSFORMATION_DECLARATIONS = 1e3;
+var SOURCE_TRANSFORMATION_KINDS = Object.freeze(["extract", "normalize", "privacy-filter", "map", "enrich"]);
+function isSourceTransformationKind(value) {
+  return typeof value === "string" && SOURCE_TRANSFORMATION_KINDS.includes(value);
+}
+function defineSourceTransformation(transformation) {
+  const prepared = prepareSourceTransformationDeclaration(transformation);
+  if (prepared.violations.length > 0 || !prepared.record) {
+    throw new SourceContractValidationError(prepared.violations);
+  }
+  return Object.freeze(freezeSourceTransformationDeclaration(prepared.record));
+}
+function defineSourceTransformations(transformations) {
+  const prepared = prepareSourceTransformationDeclarations(transformations, "transformations");
+  if (prepared.violations.length > 0) {
+    throw new SourceContractValidationError(prepared.violations);
+  }
+  return Object.freeze(prepared.records.map((transformation) => Object.freeze(freezeSourceTransformationDeclaration(transformation))));
+}
+function validateSourceTransformationDeclarations(transformations, path12 = "transformations") {
+  return prepareSourceTransformationDeclarations(transformations, path12).violations;
+}
+function prepareSourceTransformationDeclarations(transformations, path12) {
+  const snapshot = snapshotSourceTransformationArray(transformations, path12);
+  const violations = [...snapshot.violations];
+  const records = [];
+  for (let index = 0; index < snapshot.items.length; index += 1) {
+    const prepared = prepareSourceTransformationDeclaration(snapshot.items[index], `${path12}.${index}`);
+    violations.push(...prepared.violations);
+    if (prepared.record) records[index] = prepared.record;
+  }
+  const seenIds = /* @__PURE__ */ new Set();
+  for (const transformation of records) {
+    if (!isRecord6(transformation)) continue;
+    const id = getOwnField(transformation, "id");
+    if (!hasText(id)) continue;
+    if (seenIds.has(id)) {
+      violations.push(violation("transformation.id.duplicate", path12, "Duplicate transformation id."));
+    }
+    seenIds.add(id);
+  }
+  return { records, violations };
+}
+function snapshotSourceTransformationArray(transformations, path12) {
+  if (!isArrayForSourceSnapshot(transformations)) {
+    return {
+      items: [],
+      violations: [violation("transformations.required", path12, "At least one source transformation declaration is required.")]
+    };
+  }
+  const lengthDescriptorSnapshot = safeGetOwnPropertyDescriptorForSourceSnapshot(
+    transformations,
+    "length",
+    path12,
+    "transformations.length.invalid",
+    "Source transformation declarations must expose a stable bounded array length."
+  );
+  if (lengthDescriptorSnapshot.violations.length > 0) {
+    return { items: [], violations: lengthDescriptorSnapshot.violations };
+  }
+  const lengthDescriptor = lengthDescriptorSnapshot.descriptor;
+  if (!lengthDescriptor || !("value" in lengthDescriptor)) {
+    return {
+      items: [],
+      violations: [violation("transformations.length.invalid", path12, "Source transformation declarations must expose a stable bounded array length.")]
+    };
+  }
+  const lengthReadSnapshot = safeReadOwnDataPropertyForSourceSnapshot(
+    transformations,
+    "length",
+    lengthDescriptor,
+    path12,
+    "transformations.length.invalid",
+    "Source transformation declarations must expose a stable bounded array length."
+  );
+  if (lengthReadSnapshot.violations.length > 0) {
+    return { items: [], violations: lengthReadSnapshot.violations };
+  }
+  const length = lengthReadSnapshot.value;
+  if (typeof length !== "number" || !Number.isSafeInteger(length) || length < 0 || length > MAX_SOURCE_TRANSFORMATION_DECLARATIONS) {
+    return {
+      items: [],
+      violations: [violation("transformations.length.invalid", path12, "Source transformation declarations must expose a stable bounded array length.")]
+    };
+  }
+  if (length === 0) {
+    return {
+      items: [],
+      violations: [violation("transformations.required", path12, "At least one source transformation declaration is required.")]
+    };
+  }
+  const items = new Array(length);
+  const violations = [];
+  for (let index = 0; index < length; index += 1) {
+    const itemPath = `${path12}.${index}`;
+    const descriptorSnapshot = safeGetOwnPropertyDescriptorForSourceSnapshot(
+      transformations,
+      String(index),
+      itemPath,
+      "transformations.accessor_field",
+      "Source transformation declaration array entries must be data properties."
+    );
+    violations.push(...descriptorSnapshot.violations);
+    const descriptor = descriptorSnapshot.descriptor;
+    if (!descriptor) {
+      violations.push(violation("transformations.missing_index", itemPath, "Source transformation declarations must be a dense array."));
+      continue;
+    }
+    if (!("value" in descriptor)) {
+      violations.push(violation("transformations.accessor_field", itemPath, "Source transformation declaration array entries must be data properties."));
+      continue;
+    }
+    const readSnapshot = safeReadOwnDataPropertyForSourceSnapshot(
+      transformations,
+      String(index),
+      descriptor,
+      itemPath,
+      "transformations.accessor_field",
+      "Source transformation declaration array entries must be data properties."
+    );
+    violations.push(...readSnapshot.violations);
+    if (readSnapshot.violations.length > 0) continue;
+    items[index] = readSnapshot.value;
+  }
+  return { items, violations };
+}
+function validateSourceTransformationDeclaration(transformation, path12 = "transformation") {
+  return prepareSourceTransformationDeclaration(transformation, path12).violations;
+}
+function prepareSourceTransformationDeclaration(transformation, path12 = "transformation") {
+  const snapshot = snapshotAllowedRecordFields(transformation, ["id", "version", "kind", "inputSchema", "outputSchema", "deterministic", "description"], {
+    path: path12,
+    requiredCode: "transformation.required",
+    requiredMessage: "Source transformation declaration is required.",
+    unknownCode: "transformation.unknown_field",
+    unknownMessage: "Source transformation declaration contains unsupported fields.",
+    accessorCode: "transformation.accessor_field",
+    accessorMessage: "Source transformation declaration fields must be data properties."
+  });
+  if (!snapshot.record) return { violations: snapshot.violations };
+  const violations = [...snapshot.violations];
+  const id = getOwnField(snapshot.record, "id");
+  const version = getOwnField(snapshot.record, "version");
+  const kind = getOwnField(snapshot.record, "kind");
+  const inputSchema = getOwnField(snapshot.record, "inputSchema");
+  const outputSchema = getOwnField(snapshot.record, "outputSchema");
+  const deterministic = getOwnField(snapshot.record, "deterministic");
+  const description = getOwnField(snapshot.record, "description");
+  if (!hasText(id)) {
+    violations.push(violation("transformation.id.required", `${path12}.id`, "Source transformation id must be non-empty."));
+  } else {
+    if (!isStableContractIdentifier(id)) {
+      violations.push(violation("transformation.id.unstable", `${path12}.id`, "Source transformation id must be stable and must not include a local absolute path."));
+    }
+    if (looksLikePrivacySensitiveSourceValue(id)) {
+      violations.push(violation("transformation.id.privacy_sensitive", `${path12}.id`, "Source transformation id must not leak local state handles or credential-shaped values."));
+    }
+  }
+  if (!hasText(version)) {
+    violations.push(violation("transformation.version.required", `${path12}.version`, "Source transformation version must be non-empty."));
+  } else if (looksLikePrivacySensitiveSourceValue(version)) {
+    violations.push(violation("transformation.version.privacy_sensitive", `${path12}.version`, "Source transformation version must not leak local state handles or credential-shaped values."));
+  }
+  if (!isSourceTransformationKind(kind)) {
+    violations.push(violation("transformation.kind.invalid", `${path12}.kind`, "Source transformation kind must be one of the bounded source transformation kinds."));
+  }
+  if (!hasText(inputSchema)) {
+    violations.push(violation("transformation.inputSchema.required", `${path12}.inputSchema`, "Source transformation inputSchema must be non-empty."));
+  } else if (looksLikePrivacySensitiveSourceValue(inputSchema)) {
+    violations.push(violation("transformation.inputSchema.privacy_sensitive", `${path12}.inputSchema`, "Source transformation inputSchema must not leak local state handles or credential-shaped values."));
+  }
+  if (!hasText(outputSchema)) {
+    violations.push(violation("transformation.outputSchema.required", `${path12}.outputSchema`, "Source transformation outputSchema must be non-empty."));
+  } else if (looksLikePrivacySensitiveSourceValue(outputSchema)) {
+    violations.push(violation("transformation.outputSchema.privacy_sensitive", `${path12}.outputSchema`, "Source transformation outputSchema must not leak local state handles or credential-shaped values."));
+  }
+  if (deterministic !== void 0 && typeof deterministic !== "boolean") {
+    violations.push(violation("transformation.deterministic.invalid", `${path12}.deterministic`, "Source transformation deterministic must be a boolean when present."));
+  }
+  if (description !== void 0 && typeof description !== "string") {
+    violations.push(violation("transformation.description.invalid", `${path12}.description`, "Source transformation description must be a string when present."));
+  } else if (hasText(description) && looksLikePrivacySensitiveSourceValue(description)) {
+    violations.push(violation("transformation.description.privacy_sensitive", `${path12}.description`, "Source transformation description must not leak local state handles or credential-shaped values."));
+  }
+  return { record: snapshot.record, violations };
+}
+function freezeSourceTransformationDeclaration(transformation) {
+  const id = getOwnField(transformation, "id");
+  const version = getOwnField(transformation, "version");
+  const kind = getOwnField(transformation, "kind");
+  const inputSchema = getOwnField(transformation, "inputSchema");
+  const outputSchema = getOwnField(transformation, "outputSchema");
+  const deterministic = getOwnField(transformation, "deterministic");
+  const description = getOwnField(transformation, "description");
+  const defined = {
+    id,
+    version,
+    kind,
+    inputSchema,
+    outputSchema
+  };
+  if (deterministic !== void 0) defined.deterministic = deterministic;
+  if (description !== void 0) defined.description = description;
+  return defined;
+}
+
+// src/core/source/source-adapter.ts
+function validateSourceAdapterIdentity(identity, path12 = "identity") {
+  return prepareSourceAdapterIdentity(identity, path12).violations;
+}
+function prepareSourceAdapterIdentity(identity, path12 = "identity") {
+  const snapshot = snapshotAllowedRecordFields(identity, ["id", "version", "displayName"], {
+    path: path12,
+    requiredCode: "identity.required",
+    requiredMessage: "Source adapter identity is required.",
+    unknownCode: "identity.unknown_field",
+    unknownMessage: "Source adapter contract object contains unsupported fields.",
+    accessorCode: "identity.accessor_field",
+    accessorMessage: "Source adapter identity fields must be data properties."
+  });
+  if (!snapshot.record) return { violations: snapshot.violations };
+  const violations = [...snapshot.violations];
+  const id = getOwnField(snapshot.record, "id");
+  const version = getOwnField(snapshot.record, "version");
+  const displayName = getOwnField(snapshot.record, "displayName");
+  if (!hasText(id)) {
+    violations.push(violation("identity.id.required", `${path12}.id`, "Source adapter identity id must be non-empty."));
+  } else {
+    if (!isStableContractIdentifier(id)) {
+      violations.push(violation("identity.id.unstable", `${path12}.id`, "Source adapter identity id must be stable and must not include a local absolute path."));
+    }
+    if (looksLikePrivacySensitiveSourceValue(id)) {
+      violations.push(violation("identity.id.privacy_sensitive", `${path12}.id`, "Source adapter identity id must not leak local state handles or credential-shaped values."));
+    }
+  }
+  if (!hasText(version)) {
+    violations.push(violation("identity.version.required", `${path12}.version`, "Source adapter identity version must be non-empty."));
+  } else if (looksLikePrivacySensitiveSourceValue(version)) {
+    violations.push(violation("identity.version.privacy_sensitive", `${path12}.version`, "Source adapter identity version must not leak local state handles or credential-shaped values."));
+  }
+  if (displayName !== void 0 && typeof displayName !== "string") {
+    violations.push(violation("identity.displayName.invalid", `${path12}.displayName`, "Source adapter displayName must be a string when present."));
+  } else if (hasText(displayName) && looksLikePrivacySensitiveSourceValue(displayName)) {
+    violations.push(violation("identity.displayName.privacy_sensitive", `${path12}.displayName`, "Source adapter displayName must not leak local state handles or credential-shaped values."));
+  }
+  return { record: snapshot.record, violations };
+}
+function freezeSourceAdapterIdentity(identity) {
+  const id = getOwnField(identity, "id");
+  const version = getOwnField(identity, "version");
+  const displayName = getOwnField(identity, "displayName");
+  const defined = {
+    id,
+    version
+  };
+  if (displayName !== void 0) defined.displayName = displayName;
+  return Object.freeze(defined);
+}
+function validateSourceAdapterCapabilities(capabilities, path12 = "capabilities") {
+  return prepareSourceAdapterCapabilities(capabilities, path12).violations;
+}
+function prepareSourceAdapterCapabilities(capabilities, path12 = "capabilities") {
+  if (!isRecord6(capabilities)) {
+    return {
+      violations: [violation("capabilities.required", path12, "Source adapter capabilities with currentnessStrategy are required.")]
+    };
+  }
+  const record = /* @__PURE__ */ Object.create(null);
+  const keySnapshot = safeOwnKeysForSourceSnapshot(capabilities, path12, "capabilities.accessor_field", "Source adapter capability fields must be data properties.");
+  const violations = [...keySnapshot.violations];
+  keySnapshot.keys.forEach((key, index) => {
+    if (typeof key !== "string") {
+      const valuePath2 = `${path12}.[symbol-${index}]`;
+      violations.push(violation("capabilities.invalid_key", valuePath2, "Source adapter capability keys must be strings."));
+      const descriptorSnapshot2 = safeGetOwnPropertyDescriptorForSourceSnapshot(capabilities, key, valuePath2, "capabilities.accessor_field", "Source adapter capability fields must be data properties.");
+      violations.push(...descriptorSnapshot2.violations);
+      const descriptor2 = descriptorSnapshot2.descriptor;
+      if (!descriptor2 || !("value" in descriptor2)) {
+        violations.push(violation("capabilities.accessor_field", valuePath2, "Source adapter capability fields must be data properties."));
+        return;
+      }
+      const readSnapshot2 = safeReadOwnDataPropertyForSourceSnapshot(capabilities, key, descriptor2, valuePath2, "capabilities.accessor_field", "Source adapter capability fields must be data properties.");
+      violations.push(...readSnapshot2.violations);
+      if (readSnapshot2.violations.length > 0) return;
+      validateCapabilityValue(propertyKeyDescription2(key), readSnapshot2.value, valuePath2, violations);
+      return;
+    }
+    const valuePath = capabilityEntryPath(path12, key, index);
+    const descriptorSnapshot = safeGetOwnPropertyDescriptorForSourceSnapshot(capabilities, key, valuePath, "capabilities.accessor_field", "Source adapter capability fields must be data properties.");
+    violations.push(...descriptorSnapshot.violations);
+    const descriptor = descriptorSnapshot.descriptor;
+    if (!descriptor || !("value" in descriptor)) {
+      violations.push(violation("capabilities.accessor_field", valuePath, "Source adapter capability fields must be data properties."));
+      return;
+    }
+    const readSnapshot = safeReadOwnDataPropertyForSourceSnapshot(capabilities, key, descriptor, valuePath, "capabilities.accessor_field", "Source adapter capability fields must be data properties.");
+    violations.push(...readSnapshot.violations);
+    if (readSnapshot.violations.length > 0) return;
+    record[key] = readSnapshot.value;
+    validateCapabilityValue(key, readSnapshot.value, valuePath, violations);
+  });
+  const currentnessStrategy = getOwnField(record, "currentnessStrategy");
+  if (!hasOwnField(record, "currentnessStrategy") || !hasText(currentnessStrategy)) {
+    violations.push(violation("capabilities.currentnessStrategy.required", `${path12}.currentnessStrategy`, "Source adapter capabilities must declare a deterministic currentnessStrategy."));
+  } else if (!isStableContractIdentifier(currentnessStrategy)) {
+    violations.push(violation("capabilities.currentnessStrategy.unstable", `${path12}.currentnessStrategy`, "Source adapter currentnessStrategy must be stable and must not include a local absolute path."));
+  }
+  return { record, violations };
+}
+function freezeSourceAdapterCapabilities(capabilities) {
+  const keySnapshot = safeOwnKeysForSourceSnapshot(capabilities, "capabilities", "capabilities.accessor_field", "Source adapter capability fields must be data properties.");
+  const safeEntries = [];
+  keySnapshot.keys.forEach((key) => {
+    if (typeof key !== "string") return;
+    const descriptorSnapshot = safeGetOwnPropertyDescriptorForSourceSnapshot(capabilities, key, `capabilities.${key}`, "capabilities.accessor_field", "Source adapter capability fields must be data properties.");
+    const descriptor = descriptorSnapshot.descriptor;
+    if (descriptor && "value" in descriptor) safeEntries.push([key, descriptor.value]);
+  });
+  return Object.freeze(Object.fromEntries(safeEntries));
+}
+function propertyKeyDescription2(key) {
+  return typeof key === "symbol" ? String(key.description ?? "") : "";
+}
+function capabilityEntryPath(path12, key, index) {
+  if (looksLikePrivacySensitiveSourceValue(key)) {
+    return `${path12}.[redacted-key-${index}]`;
+  }
+  const sanitizedKey = key.replace(/[^A-Za-z0-9._:-]+/g, "_").slice(0, 64);
+  return sanitizedKey ? `${path12}.${sanitizedKey}` : `${path12}.${index}`;
+}
+function validateCapabilityValue(key, value, path12, violations) {
+  if (looksLikePrivacySensitiveSourceValue(key)) {
+    violations.push(violation("capabilities.privacy_sensitive", path12, "Source adapter capability keys must not leak local state handles or credential-shaped values."));
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      violations.push(violation("capabilities.invalid_value", path12, "Source adapter capability numbers must be finite."));
+    }
+    if (looksLikePrivacySensitiveSourceValue(String(value), key)) {
+      violations.push(violation("capabilities.privacy_sensitive", path12, "Source adapter capability values must not leak local state handles or credential-shaped values."));
+    }
+    return;
+  }
+  if (typeof value === "boolean") return;
+  if (typeof value === "string") {
+    if (looksLikePrivacySensitiveSourceValue(value, key)) {
+      violations.push(violation("capabilities.privacy_sensitive", path12, "Source adapter capability values must not leak local state handles or credential-shaped values."));
+    }
+    return;
+  }
+  violations.push(violation("capabilities.invalid_value", path12, "Source adapter capability values must be scalar strings, finite numbers, or booleans."));
+}
+
+// src/core/source/source-adapter-contract-suite.ts
+var MAX_SAMPLE_SOURCE_REFS = 1e3;
+function validateSourceAdapterContract(adapter, path12 = "adapter") {
+  return prepareSourceAdapterContract(adapter, path12).violations;
+}
+function assertSourceAdapterContract(adapter) {
+  return defineSourceAdapter(adapter);
+}
+function defineSourceAdapter(adapter) {
+  const prepared = prepareSourceAdapterContract(adapter);
+  if (prepared.violations.length > 0 || !prepared.contract) {
+    throw new SourceContractValidationError(prepared.violations);
+  }
+  return Object.freeze(prepared.contract);
+}
+function prepareSourceAdapterContract(adapter, path12 = "adapter") {
+  const snapshot = snapshotAllowedRecordFields(adapter, ["identity", "source", "transformations", "sampleSourceRefs", "capabilities"], {
+    path: path12,
+    requiredCode: "adapter.required",
+    requiredMessage: "Source adapter contract is required.",
+    unknownCode: "adapter.unknown_field",
+    unknownMessage: "Source adapter contract contains unsupported fields.",
+    accessorCode: "adapter.accessor_field",
+    accessorMessage: "Source adapter contract fields must be data properties."
+  });
+  if (!snapshot.record) return { violations: snapshot.violations };
+  const violations = [...snapshot.violations];
+  const identityInput = getOwnField(snapshot.record, "identity");
+  const sourceInput = getOwnField(snapshot.record, "source");
+  const transformationsInput = getOwnField(snapshot.record, "transformations");
+  const capabilitiesInput = getOwnField(snapshot.record, "capabilities");
+  const sampleSourceRefsInput = getOwnField(snapshot.record, "sampleSourceRefs");
+  const identityPrepared = prepareSourceAdapterIdentity(identityInput, `${path12}.identity`);
+  violations.push(...identityPrepared.violations);
+  const sourcePrepared = defineSafeResult(
+    () => defineSourceSchema(sourceInput),
+    "source",
+    `${path12}.source`,
+    "source.validation_error",
+    "Source schema validation failed unexpectedly."
+  );
+  violations.push(...sourcePrepared.violations);
+  const transformationsPrepared = defineSafeResult(
+    () => defineSourceTransformations(transformationsInput),
+    "transformations",
+    `${path12}.transformations`,
+    "transformations.validation_error",
+    "Source transformation validation failed unexpectedly."
+  );
+  violations.push(...transformationsPrepared.violations);
+  const capabilitiesPrepared = prepareSourceAdapterCapabilities(capabilitiesInput, `${path12}.capabilities`);
+  violations.push(...capabilitiesPrepared.violations);
+  const sampleSourceRefsPrepared = defineSampleSourceRefs(sampleSourceRefsInput, `${path12}.sampleSourceRefs`);
+  violations.push(...sampleSourceRefsPrepared.violations);
+  if (violations.length > 0 || !identityPrepared.record || !sourcePrepared.value || !transformationsPrepared.value || !capabilitiesPrepared.record) {
+    return { violations };
+  }
+  const contract = {
+    identity: freezeSourceAdapterIdentity(identityPrepared.record),
+    source: sourcePrepared.value,
+    transformations: transformationsPrepared.value,
+    sampleSourceRefs: sampleSourceRefsPrepared.value,
+    capabilities: freezeSourceAdapterCapabilities(capabilitiesPrepared.record)
+  };
+  return { contract, violations };
+}
+function defineSampleSourceRefs(sampleSourceRefs, path12) {
+  if (sampleSourceRefs === void 0) return { violations: [] };
+  if (!isArrayForSourceSnapshot(sampleSourceRefs)) {
+    return {
+      violations: [violation("sampleSourceRefs.invalid", path12, "sampleSourceRefs must be an array when present.")]
+    };
+  }
+  const snapshot = snapshotSampleSourceRefArray(sampleSourceRefs, path12);
+  const violations = [...snapshot.violations];
+  const refs = [];
+  for (let index = 0; index < snapshot.items.length; index += 1) {
+    const defined = defineSafeResult(
+      () => createSourceRef(snapshot.items[index]),
+      "sourceRef",
+      `${path12}.${index}`,
+      "sampleSourceRefs.validation_error",
+      "Sample source ref validation failed unexpectedly."
+    );
+    violations.push(...defined.violations);
+    if (defined.value) refs[index] = defined.value;
+  }
+  return {
+    value: violations.length === 0 ? Object.freeze(refs) : void 0,
+    violations
+  };
+}
+function snapshotSampleSourceRefArray(sampleSourceRefs, path12) {
+  const lengthDescriptorSnapshot = safeGetOwnPropertyDescriptorForSourceSnapshot(
+    sampleSourceRefs,
+    "length",
+    path12,
+    "sampleSourceRefs.length.invalid",
+    "sampleSourceRefs must expose a stable bounded array length."
+  );
+  if (lengthDescriptorSnapshot.violations.length > 0) {
+    return { items: [], violations: lengthDescriptorSnapshot.violations };
+  }
+  const lengthDescriptor = lengthDescriptorSnapshot.descriptor;
+  if (!lengthDescriptor || !("value" in lengthDescriptor)) {
+    return {
+      items: [],
+      violations: [violation("sampleSourceRefs.length.invalid", path12, "sampleSourceRefs must expose a stable bounded array length.")]
+    };
+  }
+  const lengthReadSnapshot = safeReadOwnDataPropertyForSourceSnapshot(
+    sampleSourceRefs,
+    "length",
+    lengthDescriptor,
+    path12,
+    "sampleSourceRefs.length.invalid",
+    "sampleSourceRefs must expose a stable bounded array length."
+  );
+  if (lengthReadSnapshot.violations.length > 0) {
+    return { items: [], violations: lengthReadSnapshot.violations };
+  }
+  const length = lengthReadSnapshot.value;
+  if (typeof length !== "number" || !Number.isSafeInteger(length) || length < 0 || length > MAX_SAMPLE_SOURCE_REFS) {
+    return {
+      items: [],
+      violations: [violation("sampleSourceRefs.length.invalid", path12, "sampleSourceRefs must expose a stable bounded array length.")]
+    };
+  }
+  const items = new Array(length);
+  const violations = [];
+  for (let index = 0; index < length; index += 1) {
+    const itemPath = `${path12}.${index}`;
+    const descriptorSnapshot = safeGetOwnPropertyDescriptorForSourceSnapshot(
+      sampleSourceRefs,
+      String(index),
+      itemPath,
+      "sampleSourceRefs.accessor_field",
+      "sampleSourceRefs array entries must be data properties."
+    );
+    violations.push(...descriptorSnapshot.violations);
+    const descriptor = descriptorSnapshot.descriptor;
+    if (!descriptor) {
+      violations.push(violation("sampleSourceRefs.missing_index", itemPath, "sampleSourceRefs must be a dense array."));
+      continue;
+    }
+    if (!("value" in descriptor)) {
+      violations.push(violation("sampleSourceRefs.accessor_field", itemPath, "sampleSourceRefs array entries must be data properties."));
+      continue;
+    }
+    const readSnapshot = safeReadOwnDataPropertyForSourceSnapshot(
+      sampleSourceRefs,
+      String(index),
+      descriptor,
+      itemPath,
+      "sampleSourceRefs.accessor_field",
+      "sampleSourceRefs array entries must be data properties."
+    );
+    violations.push(...readSnapshot.violations);
+    if (readSnapshot.violations.length > 0) continue;
+    items[index] = readSnapshot.value;
+  }
+  return { items, violations };
+}
+function defineSafeResult(define, sourcePathPrefix, targetPathPrefix, fallbackCode, fallbackMessage) {
+  try {
+    return { value: define(), violations: [] };
+  } catch (error) {
+    if (error instanceof SourceContractValidationError) {
+      return {
+        violations: error.violations.map((violationItem) => ({
+          ...violationItem,
+          path: remapPathPrefix(violationItem.path, sourcePathPrefix, targetPathPrefix)
+        }))
+      };
+    }
+    return { violations: [violation(fallbackCode, targetPathPrefix, fallbackMessage)] };
+  }
+}
+function remapPathPrefix(path12, sourcePathPrefix, targetPathPrefix) {
+  if (path12 === sourcePathPrefix) return targetPathPrefix;
+  if (path12.startsWith(`${sourcePathPrefix}.`)) return `${targetPathPrefix}${path12.slice(sourcePathPrefix.length)}`;
+  return path12;
+}
+
 // src/core/evidence-aligner.ts
 import { createHash as createHash8 } from "crypto";
 var DEFAULT_OPTIONS2 = {
@@ -17696,10 +18790,11 @@ var ContextCompressor = class {
   compress(content, options) {
     const source = safeLabel(options.source) || "unknown";
     const mode = options.mode;
+    const sourceRef = safeSourceRef(options.sourceRef ?? sourceRefFromMetadata(options.metadata ?? {}));
     const contentType = detectContextContentType(content, options.metadata ?? {});
     const originalLines = nonEmptyLines(content).length;
     if (mode === "off") {
-      return result(content, {
+      return withSourceRefHint(result(content, {
         mode,
         source,
         contentType,
@@ -17708,21 +18803,21 @@ var ContextCompressor = class {
         originalLines,
         omittedLines: 0,
         signalCount: 0
-      });
+      }), sourceRef);
     }
     if (contentType === "log") {
-      return this.compressLog(content, mode, source, contentType);
+      return withSourceRefHint(this.compressLog(content, mode, source, contentType), sourceRef);
     }
     if (contentType === "markdown") {
-      return this.compressMarkdown(content, mode, source, contentType);
+      return withSourceRefHint(this.compressMarkdown(content, mode, source, contentType), sourceRef);
     }
     if (contentType === "diff") {
-      return this.compressDiff(content, mode, source, contentType);
+      return withSourceRefHint(this.compressDiff(content, mode, source, contentType), sourceRef);
     }
     if (contentType === "code") {
-      return this.compressCode(content, mode, source, contentType);
+      return withSourceRefHint(this.compressCode(content, mode, source, contentType), sourceRef);
     }
-    return this.compressPlain(content, mode, source, contentType);
+    return withSourceRefHint(this.compressPlain(content, mode, source, contentType), sourceRef);
   }
   compressLog(content, mode, source, contentType) {
     const lines = nonEmptyLines(content);
@@ -17860,11 +18955,15 @@ function summarizeCompressionTelemetry(metadata) {
   const totalOriginalChars = metadata.reduce((sum, item) => sum + item.originalChars, 0);
   const totalCompressedChars = metadata.reduce((sum, item) => sum + item.compressedChars, 0);
   const totalSavedChars = metadata.reduce((sum, item) => sum + item.savedChars, 0);
+  const totalOmittedLines = metadata.reduce((sum, item) => sum + item.omittedLines, 0);
+  const sourceRefsPreserved = metadata.filter((item) => item.sourceRefPreserved).length;
   return {
     totalItems: metadata.length,
     totalOriginalChars,
     totalCompressedChars,
     totalSavedChars,
+    totalOmittedLines,
+    sourceRefsPreserved,
     bySource: summarizeBy(metadata, "source"),
     byStrategy: summarizeBy(metadata, "strategy")
   };
@@ -17878,12 +18977,16 @@ function summarizeBy(metadata, key) {
       items: 0,
       originalChars: 0,
       compressedChars: 0,
-      savedChars: 0
+      savedChars: 0,
+      omittedLines: 0,
+      sourceRefsPreserved: 0
     };
     existing.items += 1;
     existing.originalChars += item.originalChars;
     existing.compressedChars += item.compressedChars;
     existing.savedChars += item.savedChars;
+    existing.omittedLines += item.omittedLines;
+    if (item.sourceRefPreserved) existing.sourceRefsPreserved += 1;
     groups.set(groupKey, existing);
   }
   return Array.from(groups.values()).sort((a, b) => String(a[key] ?? "").localeCompare(String(b[key] ?? "")));
@@ -17898,7 +19001,8 @@ function result(text, base) {
       ...base,
       compressedChars,
       savedChars,
-      compressionRatio
+      compressionRatio,
+      sourceRefPreserved: false
     }
   };
 }
@@ -17947,6 +19051,65 @@ function safeLabel(value) {
   const cleaned = value.replace(/[^A-Za-z0-9_.:-]+/g, "_").replace(/^_+|_+$/g, "").slice(0, 80);
   return cleaned || void 0;
 }
+function sourceRefFromMetadata(metadata) {
+  const explicit = firstString(metadata, ["sourceRef", "source_ref", "sourceReference", "source_reference"]);
+  if (explicit) return explicit;
+  const citation = firstString(metadata, ["citationId", "citation_id", "memoryCitationId", "memory_citation_id"]);
+  if (citation) return citation.startsWith("mem:") ? citation : `mem:${citation}`;
+  const eventId = firstString(metadata, ["eventId", "event_id"]);
+  if (eventId) return eventId.startsWith("event:") ? eventId : `event:${eventId}`;
+  return void 0;
+}
+function firstString(metadata, keys) {
+  for (const key of keys) {
+    const value = metadata[key];
+    if (typeof value === "string" && value.trim().length > 0) return value.trim();
+  }
+  return void 0;
+}
+function safeSourceRef(value) {
+  if (!value) return void 0;
+  const normalized = value.trim().replace(/^\[?(mem|event):/i, (_, prefix) => `${prefix.toLowerCase()}:`).replace(/\]?$/g, "");
+  if (!normalized || /(?:password|secret|api[_-]?key|token|bearer)/i.test(normalized)) return void 0;
+  const cleaned = normalized.replace(/[^A-Za-z0-9_.:-]+/g, "_").replace(/^_+|_+$/g, "").slice(0, 140);
+  return cleaned || void 0;
+}
+function withSourceRefHint(compression, sourceRef) {
+  if (!sourceRef) return compression;
+  if (compression.metadata.mode === "off" || compression.metadata.strategy === "none") {
+    return {
+      text: compression.text,
+      metadata: {
+        ...compression.metadata,
+        sourceRef,
+        sourceRefPreserved: false
+      }
+    };
+  }
+  const hint = `sourceRef=${sourceRef} expand=mem-source-ref`;
+  const text = compression.text.includes(hint) ? compression.text : addSourceRefHint(compression.text, hint);
+  const compressedChars = text.length;
+  const savedChars = Math.max(0, compression.metadata.originalChars - compressedChars);
+  const compressionRatio = compression.metadata.originalChars > 0 ? compressedChars / compression.metadata.originalChars : 1;
+  return {
+    text,
+    metadata: {
+      ...compression.metadata,
+      sourceRef,
+      sourceRefPreserved: text.includes(`sourceRef=${sourceRef}`) && text.includes("expand=mem-source-ref"),
+      compressedChars,
+      savedChars,
+      compressionRatio
+    }
+  };
+}
+function addSourceRefHint(text, hint) {
+  if (text.startsWith("[compressed ")) {
+    return text.replace(/^\[([^\]]+)\]/, `[$1; ${hint}]`);
+  }
+  return `[${hint}]
+${text}`;
+}
 
 // src/core/task/task-matcher.ts
 var DEFAULT_CONFIG7 = {
@@ -20084,7 +21247,7 @@ import * as os7 from "os";
 import * as readline from "readline";
 import { createHash as createHash9, randomUUID as randomUUID26 } from "crypto";
 var CODEX_VALIDATION_DEFAULT_MAX_CONTENT_CHARS = 1e4;
-function isRecord6(value) {
+function isRecord7(value) {
   return typeof value === "object" && value !== null;
 }
 function normalizeMaybeRealpath(p) {
@@ -20100,7 +21263,7 @@ function extractCodexContentText(content, maxContentChars = CODEX_VALIDATION_DEF
     if (content.length > 0) texts.push(content);
   } else if (Array.isArray(content)) {
     for (const block of content) {
-      if (!isRecord6(block)) continue;
+      if (!isRecord7(block)) continue;
       const b = block;
       const t = typeof b.type === "string" ? b.type : "";
       if (t !== "input_text" && t !== "output_text" && t !== "text") continue;
@@ -20180,7 +21343,7 @@ async function readCodexSessionMeta(filePath) {
       try {
         const obj = JSON.parse(line);
         if (obj.type !== "session_meta") continue;
-        if (!isRecord6(obj.payload)) break;
+        if (!isRecord7(obj.payload)) break;
         const payload = obj.payload;
         const sessionId = typeof payload.id === "string" ? payload.id : null;
         const cwd = typeof payload.cwd === "string" ? payload.cwd : null;
@@ -20310,7 +21473,7 @@ async function normalizeCodexSessionFile(filePath, options = {}) {
         continue;
       }
       if (entry.type === "session_meta") continue;
-      if (entry.type !== "response_item" || !isRecord6(entry.payload)) {
+      if (entry.type !== "response_item" || !isRecord7(entry.payload)) {
         summary.skippedUnsupportedRecords += 1;
         continue;
       }
@@ -20460,7 +21623,7 @@ var CodexSessionHistoryImporter = class {
         try {
           const obj = JSON.parse(line);
           if (obj.type !== "session_meta") continue;
-          if (!isRecord6(obj.payload)) break;
+          if (!isRecord7(obj.payload)) break;
           const payload = obj.payload;
           const sessionId = typeof payload.id === "string" ? payload.id : null;
           const cwd = typeof payload.cwd === "string" ? payload.cwd : null;
@@ -20668,7 +21831,7 @@ var CodexSessionHistoryImporter = class {
         try {
           const entry = JSON.parse(line);
           result2.totalMessages++;
-          if (entry.type === "response_item" && isRecord6(entry.payload)) {
+          if (entry.type === "response_item" && isRecord7(entry.payload)) {
             const payload = entry.payload;
             if (payload.type !== "message") continue;
             const role = typeof payload.role === "string" ? payload.role : null;
@@ -20917,6 +22080,9 @@ export {
   RetrievalResultTypeSchema,
   Retriever,
   RuleBasedPerspectiveObservationExtractor,
+  SOURCE_CAPTURE_MODES,
+  SOURCE_PRIVACY_CLASSES,
+  SOURCE_TRANSFORMATION_KINDS,
   SQLiteEventStore,
   SearchIndexItemSchema,
   SessionActorRepository,
@@ -20932,6 +22098,7 @@ export {
   SharedStoreConfigSchema,
   SharedTroubleshootingEntrySchema,
   SharedVectorStore,
+  SourceContractValidationError,
   SummaryDeriver,
   SyncWorker,
   TaskActionProjector,
@@ -20962,6 +22129,7 @@ export {
   VectorWorkerV2,
   WorkingSetItemSchema,
   actionIdForTaskEntity,
+  assertSourceAdapterContract,
   backfillPerspectiveSessionActors,
   buildMemoryActorId,
   createCodexSessionHistoryImporter,
@@ -20989,9 +22157,14 @@ export {
   createSharedPromoter,
   createSharedStore,
   createSharedVectorStore,
+  createSourceRef,
   createSummaryDeriver,
   createVectorWorker,
   createVectorWorkerV2,
+  defineSourceAdapter,
+  defineSourceSchema,
+  defineSourceTransformation,
+  defineSourceTransformations,
   deriveCodexSessionIdFromFileName,
   detectContextContentType,
   emptyRetentionAuditReport,
@@ -21015,8 +22188,13 @@ export {
   isKnownBenignTransformersWarning,
   isMissingTransformersDependencyError,
   isSameCanonicalKey,
+  isSourceCaptureMode,
+  isSourcePrivacyClass,
+  isSourceTransformationKind,
   listCodexSessionFilesRecursive,
   loadSessionRegistry,
+  looksLikeLocalAbsolutePath,
+  looksLikePrivacySensitiveSourceValue,
   makeArtifactKey,
   makeCanonicalKey,
   makeDedupeKey,
@@ -21052,6 +22230,13 @@ export {
   toDisclosureResultId,
   toSQLiteTimestamp,
   validateCodexSessions,
+  validateSourceAdapterCapabilities,
+  validateSourceAdapterContract,
+  validateSourceAdapterIdentity,
+  validateSourceRef,
+  validateSourceSchema,
+  validateSourceTransformationDeclaration,
+  validateSourceTransformationDeclarations,
   withSuppressedKnownTransformersWarnings,
   writeGovernanceAuditEntry
 };