@jacfrost/autopm 0.0.1

package/src/autopm/memory/canonicalize.js

@@ -0,0 +1,697 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import {
+  AUTOPM_MEMORY_SCHEMA_VERSION,
+  memoryDiagnostic,
+  validateSourceEnvelope,
+} from './contracts.js';
+import {
+  isSecretLikeMemoryPropertyName,
+  redactMemoryText,
+  redactMemoryTextWithStats,
+  redactMemoryValue,
+  redactMemoryValueWithStats,
+} from './redaction.js';
+import {
+  PRODUCT_CONTEXT_INDEX_PATH,
+  PRODUCT_CONTEXT_INTRO_PATH,
+} from '../product-context.js';
+import {
+  VENTURE_SIGNAL_DIR,
+} from '../../venture-signal/contracts.js';
+
+export const AUTOPM_MEMORY_CANONICALIZER_VERSION = 1;
+
+export const LOCAL_MEMORY_SOURCE_TYPES = Object.freeze([
+  'autopm_artifact',
+  'venture_signal_artifact',
+  'repo_doc',
+  'session_summary',
+  'task_summary',
+  'manual_note',
+  'local_markdown',
+  'local_text',
+  'local_json',
+]);
+
+const DEFAULT_LIMITS = Object.freeze({
+  maxBytes: 256 * 1024,
+  maxJsonFields: 160,
+});
+
+const SUPPORTED_EXTENSIONS = new Set(['.md', '.markdown', '.txt', '.json']);
+const TEXT_EXTENSIONS = new Set(['.md', '.markdown', '.txt']);
+const JSON_EXTENSION = '.json';
+const UNSAFE_PATH_SEGMENTS = new Set(['.git', '.gsd', 'node_modules', 'dist', 'build', 'coverage', '.cache', '.next', 'tmp', 'vendor']);
+const SECRET_BEARING_BASENAME_PATTERN = /(?:^|[._-])(?:env|secret|secrets|credential|credentials|password|passwd|private-key|private_key)(?:$|[._-])/i;
+const SECRET_LABEL_PATTERN = /("?)([A-Z0-9_]*(?:TOKEN|SECRET|PASSWORD|PASSWD|API[-_]?KEY|AUTHORIZATION|CREDENTIAL|PRIVATE[-_]?KEY|CLIENT[-_]?SECRET)[A-Z0-9_]*)("?)(\s*[:=]\s*)("?)\[REDACTED\]("?)/gi;
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function sha256Hex(value) {
+  return crypto.createHash('sha256').update(String(value), 'utf8').digest('hex');
+}
+
+function shortHash(value, length = 16) {
+  return sha256Hex(value).slice(0, length);
+}
+
+function byteLength(value) {
+  return Buffer.byteLength(String(value), 'utf8');
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function uniqueStrings(values) {
+  return [...new Set(values.filter((value) => typeof value === 'string' && value.length > 0))];
+}
+
+function posixRelative(from, to) {
+  const relative = path.relative(from, to).replaceAll(path.sep, '/');
+  return relative === '' ? '.' : relative;
+}
+
+function pathSegments(relativePath) {
+  return String(relativePath).split('/').filter(Boolean);
+}
+
+function sanitizeRedactedTextForMemory(text) {
+  return String(text ?? '').replace(SECRET_LABEL_PATTERN, (_match, openKeyQuote, _key, closeKeyQuote, separator, openValueQuote, closeValueQuote) => {
+    const quotedKey = openKeyQuote || closeKeyQuote ? '"redactedField"' : 'redactedField';
+    return `${quotedKey}${separator}${openValueQuote}[REDACTED]${closeValueQuote}`;
+  });
+}
+
+function redactTextForCanonicalMarkdown(value, diagnosticPath = '$.content') {
+  const redacted = redactMemoryTextWithStats(value, { path: diagnosticPath });
+  return {
+    ...redacted,
+    value: sanitizeRedactedTextForMemory(redacted.value),
+  };
+}
+
+function safeTitle(value, fallback = 'Local memory source') {
+  const redacted = redactMemoryText(String(value ?? fallback)).trim().replace(/\s+/g, ' ');
+  const sanitized = sanitizeRedactedTextForMemory(redacted).replace(/[\r\n]/g, ' ').trim();
+  return sanitized.length > 0 ? sanitized.slice(0, 240) : fallback;
+}
+
+function canonicalizeNewlines(value) {
+  return String(value ?? '').replace(/\r\n?/g, '\n');
+}
+
+function stripTrailingWhitespace(value) {
+  return canonicalizeNewlines(value)
+    .split('\n')
+    .map((line) => line.replace(/[\t ]+$/g, ''))
+    .join('\n')
+    .replace(/\n{4,}/g, '\n\n\n')
+    .trim();
+}
+
+function markdownFenceFor(uri, fallback = 'text') {
+  const extension = path.extname(uri).toLowerCase();
+  if (extension === '.json') return 'json';
+  if (extension === '.md' || extension === '.markdown') return 'markdown';
+  return fallback;
+}
+
+function lineCount(value) {
+  if (String(value ?? '').length === 0) return 0;
+  return canonicalizeNewlines(value).split('\n').length;
+}
+
+function firstMarkdownHeading(value) {
+  const heading = canonicalizeNewlines(value)
+    .split('\n')
+    .map((line) => line.match(/^#\s+(.+)$/)?.[1]?.trim())
+    .find((line) => typeof line === 'string' && line.length > 0);
+  return heading ?? null;
+}
+
+function sourceTypeConfig(type, relativePath) {
+  switch (type) {
+    case 'autopm_artifact':
+      return { memoryKind: 'product_context', trustClass: 'local_autopm_runtime_state', titlePrefix: 'AutoPM artifact' };
+    case 'venture_signal_artifact':
+      return { memoryKind: 'external', trustClass: 'local_venture_signal_evidence', titlePrefix: 'Venture Signal artifact' };
+    case 'repo_doc':
+      return { memoryKind: 'filesystem', trustClass: 'project_documentation', titlePrefix: 'Repository document' };
+    case 'session_summary':
+      return { memoryKind: 'filesystem', trustClass: 'session_summary', titlePrefix: 'Session summary' };
+    case 'task_summary':
+      return { memoryKind: 'filesystem', trustClass: 'task_summary', titlePrefix: 'Task summary' };
+    case 'manual_note':
+      return { memoryKind: 'manual', trustClass: 'operator_authored_note', titlePrefix: 'Manual note' };
+    case 'local_json':
+      return { memoryKind: 'filesystem', trustClass: 'local_json_file', titlePrefix: 'Local JSON' };
+    case 'local_text':
+      return { memoryKind: 'filesystem', trustClass: 'local_text_file', titlePrefix: 'Local text' };
+    case 'local_markdown':
+    default:
+      return {
+        memoryKind: relativePath.startsWith('.autopm/wiki/') ? 'wiki' : 'filesystem',
+        trustClass: relativePath.startsWith('.autopm/wiki/') ? 'wiki_note' : 'local_markdown_file',
+        titlePrefix: 'Local Markdown',
+      };
+  }
+}
+
+export function detectLocalMemorySourceType(relativePath) {
+  const normalized = String(relativePath ?? '').replaceAll('\\', '/').replace(/^\.\//, '');
+  const base = path.posix.basename(normalized);
+  const extension = path.posix.extname(normalized).toLowerCase();
+
+  if (
+    normalized === PRODUCT_CONTEXT_INDEX_PATH
+    || normalized === PRODUCT_CONTEXT_INTRO_PATH
+    || normalized.startsWith('.autopm/product-context/product-')
+    || normalized === '.autopm/product-context/connectors.json'
+    || normalized === '.autopm/objective/current.json'
+    || normalized === '.autopm/runtime/status.json'
+    || normalized.startsWith('.autopm/actions/proposals/')
+  ) return 'autopm_artifact';
+
+  if (normalized.startsWith(VENTURE_SIGNAL_DIR)) return 'venture_signal_artifact';
+
+  if (normalized.startsWith('.autopm/wiki/notes/')) return 'manual_note';
+  if (/^(?:README|AGENTS|CLAUDE|CONTRIBUTING|PROJECT|PRODUCT)(?:\.md|\.txt)$/i.test(base) || normalized.startsWith('docs/')) return 'repo_doc';
+  if (/^(?:T\d+|S\d+|M\d+)-SUMMARY\.md$/i.test(base)) return base.startsWith('T') ? 'task_summary' : 'session_summary';
+  if (/session[-_. ]?summary/i.test(base)) return 'session_summary';
+  if (/task[-_. ]?summary/i.test(base)) return 'task_summary';
+  if (extension === JSON_EXTENSION) return 'local_json';
+  if (extension === '.txt') return 'local_text';
+  return 'local_markdown';
+}
+
+function diagnostic({ severity = 'error', code, message, path: diagnosticPath = '$', details = {} }) {
+  return memoryDiagnostic({ severity, code, message, path: diagnosticPath, details });
+}
+
+function failure({ code, message, details = {}, artifactPathsRead = [], generatedAt = nowIso(), diagnosticPath = '$.path' }) {
+  const errors = [diagnostic({ code, message, path: diagnosticPath, details })];
+  return Object.freeze({
+    ok: false,
+    status: 'error',
+    generatedAt,
+    source: null,
+    markdown: '',
+    normalizedMarkdown: '',
+    metadata: null,
+    provenance: null,
+    artifactPathsRead: uniqueStrings(artifactPathsRead),
+    diagnostics: errors,
+    warnings: Object.freeze([]),
+    errors: Object.freeze(errors),
+    warningCodes: Object.freeze([]),
+    errorCodes: Object.freeze([code]),
+    redactionCount: 0,
+  });
+}
+
+function resolveLocalPath({ projectRoot, sourcePath, generatedAt }) {
+  let root;
+  try {
+    root = fs.realpathSync.native(path.resolve(projectRoot ?? process.cwd()));
+  } catch (error) {
+    return { error: failure({ code: 'AUTOPM_MEMORY_CANONICALIZE_ROOT_MISSING', message: 'Project root does not exist.', generatedAt, details: { reason: error instanceof Error ? error.message : String(error) } }) };
+  }
+
+  if (typeof sourcePath !== 'string' || sourcePath.trim().length === 0) {
+    return { error: failure({ code: 'AUTOPM_MEMORY_CANONICALIZE_PATH_REQUIRED', message: 'A local source path is required.', generatedAt }) };
+  }
+
+  const trimmed = sourcePath.trim();
+  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(trimmed)) {
+    return { error: failure({ code: 'AUTOPM_MEMORY_CANONICALIZE_PATH_UNSAFE', message: 'Local memory canonicalization only accepts filesystem paths.', generatedAt, details: { path: trimmed } }) };
+  }
+  if (trimmed.includes('\0') || trimmed.includes('\\') || trimmed.includes(':')) {
+    return { error: failure({ code: 'AUTOPM_MEMORY_CANONICALIZE_PATH_UNSAFE', message: 'Source path must be POSIX-style and cannot contain NUL bytes, backslashes, or colons.', generatedAt, details: { path: trimmed } }) };
+  }
+
+  const suppliedSegments = pathSegments(trimmed.replaceAll(path.sep, '/'));
+  if (suppliedSegments.includes('..')) {
+    return { error: failure({ code: 'AUTOPM_MEMORY_CANONICALIZE_PATH_TRAVERSAL', message: 'Source path must not contain traversal segments.', generatedAt, details: { path: trimmed } }) };
+  }
+  const suppliedUnsafeSegment = suppliedSegments.find((segment) => UNSAFE_PATH_SEGMENTS.has(segment));
+  if (suppliedUnsafeSegment) {
+    return { error: failure({ code: 'AUTOPM_MEMORY_CANONICALIZE_PATH_UNSAFE', message: 'Local source path is inside a blocked runtime or dependency directory.', generatedAt, details: { path: trimmed, segment: suppliedUnsafeSegment } }) };
+  }
+  const suppliedBasename = path.posix.basename(trimmed.replaceAll(path.sep, '/'));
+  if (SECRET_BEARING_BASENAME_PATTERN.test(suppliedBasename)) {
+    return { error: failure({ code: 'AUTOPM_MEMORY_CANONICALIZE_PATH_SECRET_UNSAFE', message: 'Local source path appears secret-bearing and will not be ingested.', generatedAt, details: { path: trimmed } }) };
+  }
+
+  const absolutePath = path.resolve(root, trimmed);
+  if (!fs.existsSync(absolutePath)) {
+    return { error: failure({ code: 'AUTOPM_MEMORY_CANONICALIZE_PATH_MISSING', message: 'Local source path does not exist.', generatedAt, details: { path: trimmed } }) };
+  }
+
+  let realPath;
+  try {
+    realPath = fs.realpathSync.native(absolutePath);
+  } catch (error) {
+    return { error: failure({ code: 'AUTOPM_MEMORY_CANONICALIZE_PATH_UNREADABLE', message: 'Local source path cannot be resolved.', generatedAt, details: { path: trimmed, reason: error instanceof Error ? error.message : String(error) } }) };
+  }
+
+  const relativePath = posixRelative(root, realPath);
+  if (relativePath === '.' || relativePath.startsWith('..') || path.isAbsolute(relativePath)) {
+    return { error: failure({ code: 'AUTOPM_MEMORY_CANONICALIZE_PATH_TRAVERSAL', message: 'Local source path escapes the project root.', generatedAt, details: { path: trimmed } }) };
+  }
+
+  const segments = pathSegments(relativePath);
+  const unsafeSegment = segments.find((segment) => UNSAFE_PATH_SEGMENTS.has(segment));
+  if (unsafeSegment) {
+    return { error: failure({ code: 'AUTOPM_MEMORY_CANONICALIZE_PATH_UNSAFE', message: 'Local source path is inside a blocked runtime or dependency directory.', generatedAt, details: { path: relativePath, segment: unsafeSegment } }) };
+  }
+
+  const base = path.posix.basename(relativePath);
+  if (SECRET_BEARING_BASENAME_PATTERN.test(base)) {
+    return { error: failure({ code: 'AUTOPM_MEMORY_CANONICALIZE_PATH_SECRET_UNSAFE', message: 'Local source path appears secret-bearing and will not be ingested.', generatedAt, details: { path: relativePath } }) };
+  }
+
+  const extension = path.posix.extname(relativePath).toLowerCase();
+  if (!SUPPORTED_EXTENSIONS.has(extension)) {
+    return { error: failure({ code: 'AUTOPM_MEMORY_CANONICALIZE_EXTENSION_UNSUPPORTED', message: 'Only Markdown, text, and JSON local sources are supported.', generatedAt, details: { path: relativePath, extension } }) };
+  }
+
+  let stat;
+  try {
+    stat = fs.statSync(realPath);
+  } catch (error) {
+    return { error: failure({ code: 'AUTOPM_MEMORY_CANONICALIZE_STAT_FAILED', message: 'Local source path cannot be inspected.', generatedAt, details: { path: relativePath, reason: error instanceof Error ? error.message : String(error) } }) };
+  }
+  if (!stat.isFile()) {
+    return { error: failure({ code: 'AUTOPM_MEMORY_CANONICALIZE_NOT_FILE', message: 'Local source path must be a file.', generatedAt, details: { path: relativePath } }) };
+  }
+
+  return { root, path: realPath, relativePath, extension, stat };
+}
+
+function readBoundedUtf8File({ filePath, relativePath, stat, limits, generatedAt }) {
+  const bytesToRead = Math.min(stat.size, limits.maxBytes);
+  let buffer;
+  try {
+    const fd = fs.openSync(filePath, 'r');
+    try {
+      buffer = Buffer.alloc(bytesToRead);
+      const read = fs.readSync(fd, buffer, 0, bytesToRead, 0);
+      buffer = buffer.subarray(0, read);
+    } finally {
+      fs.closeSync(fd);
+    }
+  } catch (error) {
+    return { error: failure({ code: 'AUTOPM_MEMORY_CANONICALIZE_READ_FAILED', message: 'Local source file could not be read.', generatedAt, artifactPathsRead: [relativePath], details: { path: relativePath, reason: error instanceof Error ? error.message : String(error) } }) };
+  }
+
+  if (buffer.includes(0)) {
+    return { error: failure({ code: 'AUTOPM_MEMORY_CANONICALIZE_BINARY_UNSAFE', message: 'Binary-looking local source was rejected.', generatedAt, artifactPathsRead: [relativePath], details: { path: relativePath } }) };
+  }
+
+  return {
+    text: buffer.toString('utf8'),
+    bytesRead: buffer.length,
+    truncated: stat.size > buffer.length,
+  };
+}
+
+function normalizeSourceType(sourceType, relativePath) {
+  if (sourceType === undefined || sourceType === null || sourceType === 'auto') return detectLocalMemorySourceType(relativePath);
+  if (LOCAL_MEMORY_SOURCE_TYPES.includes(sourceType)) return sourceType;
+  return null;
+}
+
+function cleanSecretPropertyNames(value, state = { index: 0 }) {
+  if (Array.isArray(value)) return value.map((item) => cleanSecretPropertyNames(item, state));
+  if (!isPlainObject(value)) return value;
+
+  const output = {};
+  for (const [key, child] of Object.entries(value)) {
+    let outputKey = key;
+    if (isSecretLikeMemoryPropertyName(key)) {
+      state.index += 1;
+      outputKey = `redactedField${String(state.index).padStart(3, '0')}`;
+    }
+    output[outputKey] = cleanSecretPropertyNames(child, state);
+  }
+  return output;
+}
+
+function flattenJsonFields(value, prefix = '$', output = []) {
+  if (output.length >= DEFAULT_LIMITS.maxJsonFields) return output;
+  if (Array.isArray(value)) {
+    value.slice(0, 50).forEach((item, index) => flattenJsonFields(item, `${prefix}[${index}]`, output));
+    return output;
+  }
+  if (isPlainObject(value)) {
+    for (const [key, child] of Object.entries(value)) {
+      if (output.length >= DEFAULT_LIMITS.maxJsonFields) break;
+      const safeKey = /^[A-Za-z_][A-Za-z0-9_]*$/.test(key) ? key : JSON.stringify(key);
+      flattenJsonFields(child, `${prefix}.${safeKey}`, output);
+    }
+    return output;
+  }
+  output.push({ fieldPath: prefix, valueType: value === null ? 'null' : typeof value });
+  return output;
+}
+
+function formatJsonFieldSummary(fields) {
+  if (fields.length === 0) return '_No scalar JSON fields._';
+  return fields.map((field) => `- \`${field.fieldPath}\` (${field.valueType})`).join('\n');
+}
+
+function composeHeader({ title, relativePath, sourceType, memoryKind, trustClass, contentHash, redactionCount }) {
+  return [
+    `# ${title}`,
+    '',
+    `> Source: \`${relativePath}\``,
+    `> Local source type: \`${sourceType}\``,
+    `> Memory source kind: \`${memoryKind}\``,
+    `> Trust class: \`${trustClass}\``,
+    `> Content hash: \`${contentHash}\``,
+    `> Redactions: ${redactionCount}`,
+    '',
+  ].join('\n');
+}
+
+function composeTextMarkdown({ rawText, relativePath, sourceType, config, contentHash, redactionCount }) {
+  const normalizedBody = stripTrailingWhitespace(rawText);
+  const title = safeTitle(firstMarkdownHeading(normalizedBody) ?? `${config.titlePrefix}: ${path.posix.basename(relativePath)}`);
+  const header = composeHeader({
+    title,
+    relativePath,
+    sourceType,
+    memoryKind: config.memoryKind,
+    trustClass: config.trustClass,
+    contentHash,
+    redactionCount,
+  });
+  const body = normalizedBody.length > 0 ? normalizedBody : '_Empty source after normalization._';
+  return {
+    title,
+    markdown: `${header}${body}\n`,
+    provenance: {
+      type: 'line-range',
+      lineRanges: [{
+        path: relativePath,
+        startLine: 1,
+        endLine: Math.max(1, lineCount(rawText)),
+        markdownSection: 'body',
+      }],
+    },
+  };
+}
+
+function composeJsonMarkdown({ value, relativePath, sourceType, config, contentHash, redactionCount }) {
+  const scrubbed = cleanSecretPropertyNames(value);
+  const fields = flattenJsonFields(scrubbed).slice(0, DEFAULT_LIMITS.maxJsonFields);
+  const serialized = `${JSON.stringify(scrubbed, null, 2)}\n`;
+  const title = safeTitle(`${config.titlePrefix}: ${path.posix.basename(relativePath)}`);
+  const header = composeHeader({
+    title,
+    relativePath,
+    sourceType,
+    memoryKind: config.memoryKind,
+    trustClass: config.trustClass,
+    contentHash,
+    redactionCount,
+  });
+  const markdown = [
+    header.trimEnd(),
+    '',
+    '## JSON Field Inventory',
+    '',
+    formatJsonFieldSummary(fields),
+    '',
+    '## Redacted JSON Body',
+    '',
+    '```json',
+    serialized.trimEnd(),
+    '```',
+    '',
+  ].join('\n');
+  return {
+    title,
+    markdown,
+    provenance: {
+      type: 'field-path',
+      fields: fields.map((field, index) => ({ ...field, ordinal: index })),
+    },
+  };
+}
+
+function safeMetadata(value) {
+  return redactMemoryValue(value);
+}
+
+function sanitizeDiagnosticPath(diagnosticPath) {
+  return String(diagnosticPath ?? '$')
+    .split('.')
+    .map((segment) => isSecretLikeMemoryPropertyName(segment) ? 'redactedField' : segment)
+    .join('.');
+}
+
+function sanitizeDiagnosticDetails(value) {
+  if (Array.isArray(value)) return value.map((item) => sanitizeDiagnosticDetails(item));
+  if (!isPlainObject(value)) {
+    return typeof value === 'string' && isSecretLikeMemoryPropertyName(value) ? 'redactedField' : value;
+  }
+  const output = {};
+  for (const [key, child] of Object.entries(value)) {
+    output[key] = sanitizeDiagnosticDetails(child);
+  }
+  return output;
+}
+
+function warningDiagnostic(code, message, details = {}) {
+  return diagnostic({ severity: 'warning', code, message, details });
+}
+
+export function canonicalizeLocalMemorySource({
+  projectRoot = process.cwd(),
+  path: sourcePath,
+  relativePath,
+  sourceType = 'auto',
+  discoveredAt = nowIso(),
+  limits = {},
+} = {}) {
+  const generatedAt = discoveredAt;
+  const requestedPath = sourcePath ?? relativePath;
+  const effectiveLimits = { ...DEFAULT_LIMITS, ...limits };
+  const resolved = resolveLocalPath({ projectRoot, sourcePath: requestedPath, generatedAt });
+  if (resolved.error) return resolved.error;
+
+  const { path: filePath, relativePath: safeRelativePath, extension, stat } = resolved;
+  const normalizedSourceType = normalizeSourceType(sourceType, safeRelativePath);
+  if (!normalizedSourceType) {
+    return failure({
+      code: 'AUTOPM_MEMORY_CANONICALIZE_TYPE_UNSUPPORTED',
+      message: 'Unsupported local memory source type.',
+      generatedAt,
+      details: { sourceType, path: safeRelativePath },
+    });
+  }
+
+  const read = readBoundedUtf8File({ filePath, relativePath: safeRelativePath, stat, limits: effectiveLimits, generatedAt });
+  if (read.error) return read.error;
+
+  const warnings = [];
+  if (read.truncated) {
+    warnings.push(warningDiagnostic('AUTOPM_MEMORY_CANONICALIZE_FILE_TRUNCATED', 'Local source was truncated by canonicalization byte limits.', {
+      path: safeRelativePath,
+      size: stat.size,
+      bytesRead: read.bytesRead,
+    }));
+  }
+
+  const config = sourceTypeConfig(normalizedSourceType, safeRelativePath);
+  const artifactPathsRead = [safeRelativePath];
+  let redactedText;
+  let markdownParts;
+  let redactionCount = 0;
+  let redactionWarnings = [];
+
+  if (extension === JSON_EXTENSION || normalizedSourceType === 'local_json') {
+    const redactedValue = redactMemoryValueWithStats(read.text, { path: '$.sourceText' });
+    redactionCount += redactedValue.redactionCount;
+    redactionWarnings.push(...redactedValue.findings);
+    let parsed;
+    try {
+      parsed = JSON.parse(redactedValue.value);
+    } catch (error) {
+      return failure({
+        code: 'AUTOPM_MEMORY_CANONICALIZE_JSON_MALFORMED',
+        message: 'JSON local source could not be parsed after redaction.',
+        generatedAt,
+        artifactPathsRead,
+        diagnosticPath: '$.sourceText',
+        details: { path: safeRelativePath, reason: error instanceof Error ? error.message : String(error) },
+      });
+    }
+    const scrubbedValue = redactMemoryValueWithStats(parsed, { path: '$.sourceJson' });
+    redactionCount += scrubbedValue.redactionCount;
+    redactionWarnings.push(...scrubbedValue.findings);
+    const contentHash = sha256Hex(JSON.stringify(scrubbedValue.value));
+    markdownParts = composeJsonMarkdown({
+      value: scrubbedValue.value,
+      relativePath: safeRelativePath,
+      sourceType: normalizedSourceType,
+      config,
+      contentHash,
+      redactionCount,
+    });
+    redactedText = JSON.stringify(scrubbedValue.value, null, 2);
+  } else if (TEXT_EXTENSIONS.has(extension)) {
+    const redacted = redactTextForCanonicalMarkdown(read.text, '$.sourceText');
+    redactionCount += redacted.redactionCount;
+    redactionWarnings.push(...redacted.findings);
+    redactedText = redacted.value;
+    const contentHash = sha256Hex(stripTrailingWhitespace(redactedText));
+    markdownParts = composeTextMarkdown({
+      rawText: redactedText,
+      relativePath: safeRelativePath,
+      sourceType: normalizedSourceType,
+      config,
+      contentHash,
+      redactionCount,
+    });
+  } else {
+    return failure({
+      code: 'AUTOPM_MEMORY_CANONICALIZE_EXTENSION_UNSUPPORTED',
+      message: 'Unsupported local memory source extension.',
+      generatedAt,
+      details: { path: safeRelativePath, extension },
+    });
+  }
+
+  const normalizedMarkdown = stripTrailingWhitespace(markdownParts.markdown) + '\n';
+  const markdownContentHash = sha256Hex(normalizedMarkdown);
+  const sourceId = `source-${shortHash(`${safeRelativePath}\n${markdownContentHash}`, 24)}`;
+  const redactionDiagnostics = redactionWarnings.map((finding) => diagnostic({
+    severity: 'warning',
+    code: finding.code,
+    message: finding.message,
+    path: sanitizeDiagnosticPath(finding.path),
+    details: sanitizeDiagnosticDetails(finding.details),
+  }));
+  const diagnostics = [...warnings, ...redactionDiagnostics];
+  const warningCodes = uniqueStrings(diagnostics.filter((item) => item.severity === 'warning').map((item) => item.code));
+
+  const metadata = safeMetadata({
+    canonicalizer: 'autopm-local-memory-source',
+    canonicalizerVersion: AUTOPM_MEMORY_CANONICALIZER_VERSION,
+    sourceType: normalizedSourceType,
+    sourceKind: normalizedSourceType,
+    trustClass: config.trustClass,
+    contentHash: markdownContentHash,
+    sourceContentHash: sha256Hex(stripTrailingWhitespace(redactedText)),
+    byteLength: read.bytesRead,
+    originalByteLength: stat.size,
+    truncated: read.truncated,
+    lineCount: lineCount(redactedText),
+    mediaType: extension === JSON_EXTENSION ? 'application/json' : 'text/markdown',
+    artifactPathsRead,
+    provenance: markdownParts.provenance,
+    redactionCount,
+    warningCodes,
+    errorCodes: [],
+  });
+
+  const source = {
+    schemaVersion: AUTOPM_MEMORY_SCHEMA_VERSION,
+    recordType: 'source',
+    sourceId,
+    kind: config.memoryKind,
+    status: 'active',
+    title: markdownParts.title,
+    uri: safeRelativePath,
+    discoveredAt: generatedAt,
+    updatedAt: null,
+    metadata,
+    diagnostics,
+  };
+
+  const validation = validateSourceEnvelope(source);
+  if (!validation.ok) {
+    const schemaErrors = validation.errors.map((error) => diagnostic({
+      severity: 'error',
+      code: error.code,
+      message: error.message,
+      path: error.path,
+      details: error.details,
+    }));
+    return Object.freeze({
+      ok: false,
+      status: 'error',
+      generatedAt,
+      source: null,
+      markdown: '',
+      normalizedMarkdown: '',
+      metadata,
+      provenance: markdownParts.provenance,
+      artifactPathsRead,
+      diagnostics: schemaErrors,
+      warnings: Object.freeze([]),
+      errors: Object.freeze(schemaErrors),
+      warningCodes: Object.freeze([]),
+      errorCodes: Object.freeze(uniqueStrings(schemaErrors.map((error) => error.code))),
+      redactionCount,
+    });
+  }
+
+  return Object.freeze({
+    ok: true,
+    status: warnings.length > 0 || redactionDiagnostics.length > 0 ? 'warn' : 'ok',
+    generatedAt,
+    source,
+    markdown: normalizedMarkdown,
+    normalizedMarkdown,
+    metadata,
+    provenance: markdownParts.provenance,
+    artifactPathsRead: Object.freeze(artifactPathsRead),
+    diagnostics: Object.freeze(diagnostics),
+    warnings: Object.freeze(diagnostics.filter((item) => item.severity === 'warning')),
+    errors: Object.freeze([]),
+    warningCodes: Object.freeze(warningCodes),
+    errorCodes: Object.freeze([]),
+    redactionCount,
+  });
+}
+
+export function canonicalizeLocalMemorySources({ sources = [], ...options } = {}) {
+  if (!Array.isArray(sources)) {
+    return Object.freeze({
+      ok: false,
+      status: 'error',
+      results: Object.freeze([]),
+      diagnostics: Object.freeze([diagnostic({ code: 'AUTOPM_MEMORY_CANONICALIZE_SOURCES_INVALID', message: 'sources must be an array.' })]),
+      artifactPathsRead: Object.freeze([]),
+      warningCodes: Object.freeze([]),
+      errorCodes: Object.freeze(['AUTOPM_MEMORY_CANONICALIZE_SOURCES_INVALID']),
+    });
+  }
+
+  const results = sources.map((source) => canonicalizeLocalMemorySource({ ...options, ...(typeof source === 'string' ? { path: source } : source) }));
+  const diagnostics = results.flatMap((result) => result.diagnostics);
+  return Object.freeze({
+    ok: results.every((result) => result.ok),
+    status: results.some((result) => !result.ok) ? 'error' : results.some((result) => result.status === 'warn') ? 'warn' : 'ok',
+    results: Object.freeze(results),
+    diagnostics: Object.freeze(diagnostics),
+    artifactPathsRead: Object.freeze(uniqueStrings(results.flatMap((result) => result.artifactPathsRead))),
+    warningCodes: Object.freeze(uniqueStrings(results.flatMap((result) => result.warningCodes))),
+    errorCodes: Object.freeze(uniqueStrings(results.flatMap((result) => result.errorCodes))),
+  });
+}
+
+export function localMemorySourceTitleForPath(relativePath) {
+  const type = detectLocalMemorySourceType(relativePath);
+  const config = sourceTypeConfig(type, String(relativePath ?? ''));
+  return safeTitle(`${config.titlePrefix}: ${path.posix.basename(String(relativePath ?? 'source'))}`);
+}