claude-memory-layer 1.0.46 → 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"
@@ -11046,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);
@@ -11076,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,
@@ -11094,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,
@@ -11113,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,
@@ -11133,10 +11138,26 @@ 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");
     }
@@ -11222,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,
@@ -11276,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);
@@ -17286,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 = {
@@ -20201,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) {
@@ -20217,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;
@@ -20297,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;
@@ -20427,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;
       }
@@ -20577,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;
@@ -20785,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;
@@ -21034,6 +22080,9 @@ export {
   RetrievalResultTypeSchema,
   Retriever,
   RuleBasedPerspectiveObservationExtractor,
+  SOURCE_CAPTURE_MODES,
+  SOURCE_PRIVACY_CLASSES,
+  SOURCE_TRANSFORMATION_KINDS,
   SQLiteEventStore,
   SearchIndexItemSchema,
   SessionActorRepository,
@@ -21049,6 +22098,7 @@ export {
   SharedStoreConfigSchema,
   SharedTroubleshootingEntrySchema,
   SharedVectorStore,
+  SourceContractValidationError,
   SummaryDeriver,
   SyncWorker,
   TaskActionProjector,
@@ -21079,6 +22129,7 @@ export {
   VectorWorkerV2,
   WorkingSetItemSchema,
   actionIdForTaskEntity,
+  assertSourceAdapterContract,
   backfillPerspectiveSessionActors,
   buildMemoryActorId,
   createCodexSessionHistoryImporter,
@@ -21106,9 +22157,14 @@ export {
   createSharedPromoter,
   createSharedStore,
   createSharedVectorStore,
+  createSourceRef,
   createSummaryDeriver,
   createVectorWorker,
   createVectorWorkerV2,
+  defineSourceAdapter,
+  defineSourceSchema,
+  defineSourceTransformation,
+  defineSourceTransformations,
   deriveCodexSessionIdFromFileName,
   detectContextContentType,
   emptyRetentionAuditReport,
@@ -21132,8 +22188,13 @@ export {
   isKnownBenignTransformersWarning,
   isMissingTransformersDependencyError,
   isSameCanonicalKey,
+  isSourceCaptureMode,
+  isSourcePrivacyClass,
+  isSourceTransformationKind,
   listCodexSessionFilesRecursive,
   loadSessionRegistry,
+  looksLikeLocalAbsolutePath,
+  looksLikePrivacySensitiveSourceValue,
   makeArtifactKey,
   makeCanonicalKey,
   makeDedupeKey,
@@ -21169,6 +22230,13 @@ export {
   toDisclosureResultId,
   toSQLiteTimestamp,
   validateCodexSessions,
+  validateSourceAdapterCapabilities,
+  validateSourceAdapterContract,
+  validateSourceAdapterIdentity,
+  validateSourceRef,
+  validateSourceSchema,
+  validateSourceTransformationDeclaration,
+  validateSourceTransformationDeclarations,
   withSuppressedKnownTransformersWarnings,
   writeGovernanceAuditEntry
 };