@jacfrost/autopm 0.0.1

package/src/venture-signal/runner.js

@@ -0,0 +1,1685 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import { runCollectorIntake } from './collector.js';
+import {
+  ANALYST_STAGE,
+  COLLECTOR_STAGE,
+  NORMALIZER_STAGE,
+  SKEPTIC_STAGE,
+  VENTURE_SIGNAL_LATEST_PATH,
+  analystDiagnosticsPath,
+  analystRunDirectoryPath,
+  analystRunSummaryPath,
+  analystTrendScoresPath,
+  collectorDiagnosticsPath,
+  collectorRunDirectoryPath,
+  collectorRunSummaryPath,
+  normalizeVentureArtifactPath,
+  normalizeVentureRunId,
+  normalizerAliasesPath,
+  normalizerCompaniesPath,
+  normalizerDiagnosticsIndexPath,
+  normalizerDiagnosticsPath,
+  normalizerInvestorsPath,
+  normalizerRunDirectoryPath,
+  normalizerRunSummaryPath,
+  normalizerSignalsPath,
+  normalizerTaxonomyMappingsPath,
+  normalizerTrendsPath,
+  pmWriterAlertCandidatesPath,
+  pmWriterDailyRadarMarkdownPath,
+  pmWriterDailyRadarPath,
+  pmWriterDiagnosticsPath,
+  pmWriterMvpExperimentsPath,
+  pmWriterRecommendationsPath,
+  pmWriterRunDirectoryPath,
+  pmWriterRunSummaryPath,
+  pmWriterSectorMemoMarkdownPath,
+  pmWriterSectorMemoPath,
+  skepticChallengesPath,
+  skepticDiagnosticsPath,
+  skepticRunDirectoryPath,
+  skepticRunSummaryPath,
+} from './contracts.js';
+import { normalizeCollectorBatch } from './normalizer.js';
+import {
+  renderDailyRadarMarkdown,
+  renderSectorMemoMarkdown,
+  writePmWriterOutputs,
+} from './pm-writer.js';
+import { analyzeNormalizedTrends } from './signal-analyst.js';
+import { reviewScoredTrends } from './skeptic.js';
+import {
+  ANALYST_ROLE,
+  ANALYST_STATUS_VALUES,
+  COLLECTOR_ROLE,
+  LATEST_STATUS_VALUES,
+  NORMALIZER_ROLE,
+  NORMALIZER_STATUS_VALUES,
+  PM_WRITER_ROLE,
+  PM_WRITER_STAGE,
+  PM_WRITER_STATUS_VALUES,
+  SECRET_LOOKING_PATTERN,
+  SKEPTIC_ROLE,
+  SKEPTIC_STATUS_VALUES,
+  dailyRadarSchema,
+  pmWriterDiagnosticsArtifactSchema,
+  pmWriterRunSummarySchema,
+  sectorMemoSchema,
+} from './schemas.js';
+
+const PROMOTABLE_COLLECTOR_STATUSES = new Set(['ok', 'warn']);
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function jsonClone(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+function schemaTypeMatches(expected, value) {
+  const values = Array.isArray(expected) ? expected : [expected];
+  return values.some((type) => {
+    if (type === 'array') return Array.isArray(value);
+    if (type === 'integer') return Number.isInteger(value);
+    if (type === 'number') return typeof value === 'number' && Number.isFinite(value);
+    if (type === 'null') return value === null;
+    if (type === 'object') return value !== null && typeof value === 'object' && !Array.isArray(value);
+    return typeof value === type;
+  });
+}
+
+function validateJsonSchema(schema, value, schemaPath = '$') {
+  const errors = [];
+
+  if (schema.anyOf) {
+    const matching = schema.anyOf.some((candidate) => validateJsonSchema(candidate, value, schemaPath).length === 0);
+    if (!matching) errors.push(`${schemaPath} did not match anyOf`);
+    return errors;
+  }
+
+  if (schema.allOf) {
+    for (const candidate of schema.allOf) errors.push(...validateJsonSchema(candidate, value, schemaPath));
+  }
+
+  if (schema.not && validateJsonSchema(schema.not, value, schemaPath).length === 0) {
+    errors.push(`${schemaPath} matched forbidden schema`);
+  }
+
+  if (schema.type && !schemaTypeMatches(schema.type, value)) {
+    errors.push(`${schemaPath} expected ${JSON.stringify(schema.type)} got ${Array.isArray(value) ? 'array' : value === null ? 'null' : typeof value}`);
+    return errors;
+  }
+
+  if (Object.hasOwn(schema, 'const') && value !== schema.const) {
+    errors.push(`${schemaPath} expected const ${JSON.stringify(schema.const)} got ${JSON.stringify(value)}`);
+  }
+
+  if (schema.enum && !schema.enum.includes(value)) {
+    errors.push(`${schemaPath} expected one of ${JSON.stringify(schema.enum)} got ${JSON.stringify(value)}`);
+  }
+
+  if (typeof value === 'string') {
+    if (schema.minLength !== undefined && value.length < schema.minLength) errors.push(`${schemaPath} shorter than ${schema.minLength}`);
+    if (schema.pattern && !new RegExp(schema.pattern).test(value)) errors.push(`${schemaPath} did not match ${schema.pattern}`);
+    if (schema.format === 'date-time' && Number.isNaN(Date.parse(value))) errors.push(`${schemaPath} expected date-time`);
+  }
+
+  if (typeof value === 'number') {
+    if (schema.minimum !== undefined && value < schema.minimum) errors.push(`${schemaPath} below minimum ${schema.minimum}`);
+    if (schema.maximum !== undefined && value > schema.maximum) errors.push(`${schemaPath} above maximum ${schema.maximum}`);
+  }
+
+  if (Array.isArray(value)) {
+    if (schema.minItems !== undefined && value.length < schema.minItems) errors.push(`${schemaPath} expected at least ${schema.minItems} items`);
+    if (schema.items) value.forEach((item, index) => errors.push(...validateJsonSchema(schema.items, item, `${schemaPath}[${index}]`)));
+  }
+
+  if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+    const properties = schema.properties ?? {};
+    for (const key of schema.required ?? []) {
+      if (!Object.hasOwn(value, key)) errors.push(`${schemaPath}.${key} is required`);
+    }
+    if (schema.additionalProperties === false) {
+      for (const key of Object.keys(value)) {
+        if (!Object.hasOwn(properties, key)) errors.push(`${schemaPath}.${key} is not allowed`);
+      }
+    }
+    for (const [key, childSchema] of Object.entries(properties)) {
+      if (Object.hasOwn(value, key)) errors.push(...validateJsonSchema(childSchema, value[key], `${schemaPath}.${key}`));
+    }
+  }
+
+  return errors;
+}
+
+function assertSchemaValid(schema, value, label) {
+  const errors = validateJsonSchema(schema, value);
+  if (errors.length > 0) {
+    throw new TypeError(`Invalid ${label}: ${errors.slice(0, 5).join('; ')}.`);
+  }
+}
+
+function assertSafeDestination(rootDir, relativeArtifactPath) {
+  const normalizedArtifactPath = normalizeVentureArtifactPath(relativeArtifactPath);
+  const root = path.resolve(rootDir);
+  const destination = path.resolve(root, normalizedArtifactPath);
+
+  if (destination !== root && !destination.startsWith(`${root}${path.sep}`)) {
+    throw new TypeError(`Invalid venture signal artifact destination: ${JSON.stringify(relativeArtifactPath)}.`);
+  }
+
+  return { normalizedArtifactPath, destination };
+}
+
+function assertCollectorIdentity(artifact, runId, label, { requireRunId = true } = {}) {
+  if (!isPlainObject(artifact)) {
+    throw new TypeError(`Invalid ${label}: expected an object.`);
+  }
+  if (requireRunId && artifact.runId !== runId) {
+    throw new TypeError(`Invalid ${label}: runId must be ${runId}.`);
+  }
+  if (!requireRunId && Object.hasOwn(artifact, 'runId') && artifact.runId !== runId) {
+    throw new TypeError(`Invalid ${label}: runId must be ${runId} when present.`);
+  }
+  if (artifact.role !== COLLECTOR_ROLE || artifact.stage !== COLLECTOR_STAGE) {
+    throw new TypeError(`Invalid ${label}: role and stage must be Collector.`);
+  }
+}
+
+function assertNormalizerIdentity(artifact, runId, label, { requireRunId = true } = {}) {
+  if (!isPlainObject(artifact)) {
+    throw new TypeError(`Invalid ${label}: expected an object.`);
+  }
+  if (requireRunId && artifact.runId !== runId) {
+    throw new TypeError(`Invalid ${label}: runId must be ${runId}.`);
+  }
+  if (!requireRunId && Object.hasOwn(artifact, 'runId') && artifact.runId !== runId) {
+    throw new TypeError(`Invalid ${label}: runId must be ${runId} when present.`);
+  }
+  if (artifact.role !== NORMALIZER_ROLE || artifact.stage !== NORMALIZER_STAGE) {
+    throw new TypeError(`Invalid ${label}: role and stage must be Normalizer.`);
+  }
+}
+
+function assertPathBelongsToRun(runId, artifactPath) {
+  const normalizedArtifactPath = normalizeVentureArtifactPath(artifactPath);
+  if (normalizedArtifactPath === VENTURE_SIGNAL_LATEST_PATH) return normalizedArtifactPath;
+
+  const runDirectory = collectorRunDirectoryPath(runId);
+  if (!normalizedArtifactPath.startsWith(runDirectory)) {
+    throw new TypeError(`Invalid Collector artifact path for run ${runId}: ${JSON.stringify(artifactPath)}.`);
+  }
+
+  return normalizedArtifactPath;
+}
+
+function assertNormalizerPathBelongsToRun(runId, artifactPath) {
+  const normalizedArtifactPath = normalizeVentureArtifactPath(artifactPath);
+  if (normalizedArtifactPath === VENTURE_SIGNAL_LATEST_PATH) return normalizedArtifactPath;
+
+  const runDirectory = normalizerRunDirectoryPath(runId);
+  if (!normalizedArtifactPath.startsWith(runDirectory)) {
+    throw new TypeError(`Invalid Normalizer artifact path for run ${runId}: ${JSON.stringify(artifactPath)}.`);
+  }
+
+  return normalizedArtifactPath;
+}
+
+function assertArtifactMapEntry(runId, relativePath, artifact) {
+  const normalizedPath = assertPathBelongsToRun(runId, relativePath);
+
+  if (!isPlainObject(artifact)) {
+    throw new TypeError(`Invalid Collector artifact at ${normalizedPath}: expected a JSON object.`);
+  }
+
+  if (normalizedPath !== VENTURE_SIGNAL_LATEST_PATH) {
+    assertCollectorIdentity(artifact, runId, `Collector artifact at ${normalizedPath}`, { requireRunId: false });
+  }
+
+  if (typeof artifact.artifactPath === 'string' && artifact.artifactPath !== normalizedPath) {
+    throw new TypeError(`Invalid Collector artifact at ${normalizedPath}: artifactPath does not match file path.`);
+  }
+
+  return normalizedPath;
+}
+
+function assertLatestArtifact(runId, latest, summary) {
+  if (!isPlainObject(latest)) {
+    throw new TypeError('Invalid latest artifact: expected an object.');
+  }
+
+  assertCollectorIdentity(latest, runId, 'latest artifact');
+
+  if (latest.latestPath !== VENTURE_SIGNAL_LATEST_PATH) {
+    throw new TypeError('Invalid latest artifact: latestPath must be the stable Venture Signal latest path.');
+  }
+  if (!LATEST_STATUS_VALUES.includes(latest.status)) {
+    throw new TypeError(`Invalid latest artifact: status ${JSON.stringify(latest.status)} is not promotable.`);
+  }
+  if (latest.summaryPath !== collectorRunSummaryPath(runId)) {
+    throw new TypeError('Invalid latest artifact: summaryPath must point at this Collector run summary.');
+  }
+  if (latest.diagnosticsPath !== collectorDiagnosticsPath(runId)) {
+    throw new TypeError('Invalid latest artifact: diagnosticsPath must point at this Collector run diagnostics.');
+  }
+  if (!isPlainObject(latest.promotion) || latest.promotion.status !== 'promoted') {
+    throw new TypeError('Invalid latest artifact: promotion must be promoted.');
+  }
+  if (summary.status === 'error') {
+    throw new TypeError('Invalid latest artifact: error Collector runs cannot be promoted.');
+  }
+}
+
+function validateCollectorRunForPersistence(result) {
+  if (!isPlainObject(result) || !(result.files instanceof Map)) {
+    throw new TypeError('Collector result with a files Map is required.');
+  }
+
+  const runId = normalizeVentureRunId(result.runId);
+  const summary = result.summary;
+  const diagnosticsArtifact = result.diagnosticsArtifact;
+
+  assertCollectorIdentity(summary, runId, 'Collector run summary');
+  assertCollectorIdentity(diagnosticsArtifact, runId, 'Collector diagnostics artifact');
+
+  if (!PROMOTABLE_COLLECTOR_STATUSES.has(summary.status) && summary.status !== 'error') {
+    throw new TypeError(`Invalid Collector run status: ${JSON.stringify(summary.status)}.`);
+  }
+  if (result.status !== summary.status) {
+    throw new TypeError('Invalid Collector result: top-level status must match summary status.');
+  }
+  if (summary.artifacts?.summary !== collectorRunSummaryPath(runId)) {
+    throw new TypeError('Invalid Collector run summary: summary artifact path is not exact.');
+  }
+  if (summary.artifacts?.diagnostics !== collectorDiagnosticsPath(runId)) {
+    throw new TypeError('Invalid Collector run summary: diagnostics artifact path is not exact.');
+  }
+  if (diagnosticsArtifact.artifactPath !== collectorDiagnosticsPath(runId)) {
+    throw new TypeError('Invalid Collector diagnostics artifact: artifactPath is not exact.');
+  }
+  if (!result.files.has(collectorRunSummaryPath(runId))) {
+    throw new TypeError('Invalid Collector result: summary file is missing from artifact map.');
+  }
+  if (!result.files.has(collectorDiagnosticsPath(runId))) {
+    throw new TypeError('Invalid Collector result: diagnostics file is missing from artifact map.');
+  }
+
+  const normalizedFiles = new Map();
+  for (const [relativePath, artifact] of result.files.entries()) {
+    const normalizedPath = assertArtifactMapEntry(runId, relativePath, artifact);
+    normalizedFiles.set(normalizedPath, artifact);
+  }
+
+  const promotable = PROMOTABLE_COLLECTOR_STATUSES.has(summary.status);
+  const latestFromFiles = normalizedFiles.get(VENTURE_SIGNAL_LATEST_PATH);
+
+  if (promotable) {
+    if (!result.latest || !latestFromFiles) {
+      throw new TypeError('Invalid Collector result: promotable runs must include a latest artifact.');
+    }
+    assertLatestArtifact(runId, result.latest, summary);
+    assertLatestArtifact(runId, latestFromFiles, summary);
+  } else if (result.latest || latestFromFiles || summary.artifacts?.latest !== null) {
+    throw new TypeError('Invalid Collector result: non-promotable runs must not include a latest artifact.');
+  }
+
+  return {
+    runId,
+    summary,
+    diagnosticsArtifact,
+    files: normalizedFiles,
+    promotable,
+    latest: promotable ? latestFromFiles : null,
+  };
+}
+
+function assertNormalizerArtifactMapEntry(runId, relativePath, artifact) {
+  const normalizedPath = assertNormalizerPathBelongsToRun(runId, relativePath);
+
+  if (!isPlainObject(artifact)) {
+    throw new TypeError(`Invalid Normalizer artifact at ${normalizedPath}: expected a JSON object.`);
+  }
+
+  assertNormalizerIdentity(artifact, runId, `Normalizer artifact at ${normalizedPath}`, { requireRunId: false });
+
+  if (typeof artifact.artifactPath === 'string' && artifact.artifactPath !== normalizedPath) {
+    throw new TypeError(`Invalid Normalizer artifact at ${normalizedPath}: artifactPath does not match file path.`);
+  }
+
+  return normalizedPath;
+}
+
+function assertExactNormalizerArtifactPath(artifact, expectedPath, label) {
+  if (!isPlainObject(artifact)) {
+    throw new TypeError(`Invalid ${label}: expected a JSON object.`);
+  }
+  if (artifact.artifactPath !== expectedPath) {
+    throw new TypeError(`Invalid ${label}: artifactPath must be ${expectedPath}.`);
+  }
+}
+
+function assertNormalizerSummaryPaths(runId, summary) {
+  if (summary.artifacts?.summary !== normalizerRunSummaryPath(runId)) {
+    throw new TypeError('Invalid Normalizer run summary: summary artifact path is not exact.');
+  }
+  if (summary.artifacts?.diagnostics !== normalizerDiagnosticsPath(runId)) {
+    throw new TypeError('Invalid Normalizer run summary: diagnostics artifact path is not exact.');
+  }
+  if (summary.artifacts?.aliases !== normalizerAliasesPath(runId)) {
+    throw new TypeError('Invalid Normalizer run summary: aliases artifact path is not exact.');
+  }
+  if (summary.artifacts?.taxonomyMappings !== normalizerTaxonomyMappingsPath(runId)) {
+    throw new TypeError('Invalid Normalizer run summary: taxonomy mappings artifact path is not exact.');
+  }
+}
+
+function validateNormalizerRunForPersistence(result, collectorValidation = null) {
+  if (!isPlainObject(result) || !(result.files instanceof Map)) {
+    throw new TypeError('Normalizer result with a files Map is required.');
+  }
+
+  const runId = normalizeVentureRunId(result.runId);
+  const summary = result.summary;
+  const diagnosticsArtifact = result.diagnosticsArtifact;
+  const aliasesArtifact = result.aliasesArtifact;
+  const taxonomyMappingsArtifact = result.taxonomyMappingsArtifact;
+
+  assertNormalizerIdentity(summary, runId, 'Normalizer run summary');
+  assertNormalizerIdentity(diagnosticsArtifact, runId, 'Normalizer diagnostics artifact');
+  assertNormalizerIdentity(aliasesArtifact, runId, 'Normalizer aliases artifact');
+  assertNormalizerIdentity(taxonomyMappingsArtifact, runId, 'Normalizer taxonomy mappings artifact');
+
+  if (!NORMALIZER_STATUS_VALUES.includes(summary.status)) {
+    throw new TypeError(`Invalid Normalizer run status: ${JSON.stringify(summary.status)}.`);
+  }
+  if (result.status !== summary.status) {
+    throw new TypeError('Invalid Normalizer result: top-level status must match summary status.');
+  }
+
+  assertNormalizerSummaryPaths(runId, summary);
+  assertExactNormalizerArtifactPath(diagnosticsArtifact, normalizerDiagnosticsPath(runId), 'Normalizer diagnostics artifact');
+  assertExactNormalizerArtifactPath(aliasesArtifact, normalizerAliasesPath(runId), 'Normalizer aliases artifact');
+  assertExactNormalizerArtifactPath(taxonomyMappingsArtifact, normalizerTaxonomyMappingsPath(runId), 'Normalizer taxonomy mappings artifact');
+
+  if (!result.files.has(normalizerRunSummaryPath(runId))) {
+    throw new TypeError('Invalid Normalizer result: summary file is missing from artifact map.');
+  }
+  if (!result.files.has(normalizerDiagnosticsPath(runId))) {
+    throw new TypeError('Invalid Normalizer result: diagnostics file is missing from artifact map.');
+  }
+  if (!result.files.has(normalizerAliasesPath(runId))) {
+    throw new TypeError('Invalid Normalizer result: aliases file is missing from artifact map.');
+  }
+  if (!result.files.has(normalizerTaxonomyMappingsPath(runId))) {
+    throw new TypeError('Invalid Normalizer result: taxonomy mappings file is missing from artifact map.');
+  }
+
+  if (collectorValidation) {
+    if (summary.sourceBatch?.collectorRunId !== collectorValidation.runId) {
+      throw new TypeError('Invalid Normalizer run summary: collectorRunId must match the validated Collector run.');
+    }
+    if (summary.sourceBatch?.collectorSummaryPath !== collectorRunSummaryPath(collectorValidation.runId)) {
+      throw new TypeError('Invalid Normalizer run summary: collector summary path must match the validated Collector run.');
+    }
+    if (summary.sourceBatch?.collectorDiagnosticsPath !== collectorDiagnosticsPath(collectorValidation.runId)) {
+      throw new TypeError('Invalid Normalizer run summary: collector diagnostics path must match the validated Collector run.');
+    }
+  }
+
+  const normalizedFiles = new Map();
+  for (const [relativePath, artifact] of result.files.entries()) {
+    const normalizedPath = assertNormalizerArtifactMapEntry(runId, relativePath, artifact);
+    normalizedFiles.set(normalizedPath, artifact);
+  }
+
+  const companies = Array.isArray(result.companies) ? result.companies : [];
+  const investors = Array.isArray(result.investors) ? result.investors : [];
+  const marketTrends = Array.isArray(result.marketTrends) ? result.marketTrends : [];
+  const signals = Array.isArray(result.signals) ? result.signals : [];
+
+  for (const [label, records] of [
+    ['company', companies],
+    ['investor', investors],
+    ['market trend', marketTrends],
+    ['signal', signals],
+  ]) {
+    for (const record of records) {
+      assertNormalizerIdentity(record, runId, `Normalizer ${label}`, { requireRunId: false });
+      if (typeof record.artifactPath !== 'string' || !normalizedFiles.has(record.artifactPath)) {
+        throw new TypeError(`Invalid Normalizer ${label}: artifactPath must be present in the files Map.`);
+      }
+    }
+  }
+
+  const aggregatePaths = [
+    normalizerCompaniesPath(runId),
+    normalizerInvestorsPath(runId),
+    normalizerTrendsPath(runId),
+    normalizerSignalsPath(runId),
+    normalizerDiagnosticsIndexPath(runId),
+  ];
+  const canPromoteLatest = result.promotable !== false && summary.status !== 'error' && collectorValidation?.promotable === true;
+  const written = [...new Set([...(summary.artifacts?.written ?? []), ...aggregatePaths])].sort();
+  const summaryForPersistence = {
+    ...jsonClone(summary),
+    artifacts: {
+      ...jsonClone(summary.artifacts),
+      latest: canPromoteLatest ? VENTURE_SIGNAL_LATEST_PATH : null,
+      written: canPromoteLatest ? [...new Set([...written, VENTURE_SIGNAL_LATEST_PATH])].sort() : written,
+    },
+  };
+  normalizedFiles.set(normalizerRunSummaryPath(runId), summaryForPersistence);
+
+  return {
+    runId,
+    summary: summaryForPersistence,
+    diagnosticsArtifact,
+    aliasesArtifact,
+    taxonomyMappingsArtifact,
+    files: normalizedFiles,
+    companies,
+    investors,
+    marketTrends,
+    signals,
+    promotable: result.promotable !== false && summary.status !== 'error',
+    aggregateArtifacts: createNormalizerAggregateArtifacts({
+      runId,
+      summary: summaryForPersistence,
+      diagnosticsArtifact,
+      companies,
+      investors,
+      marketTrends,
+      signals,
+    }),
+  };
+}
+
+function createNormalizerAggregateArtifacts({ runId, summary, diagnosticsArtifact, companies, investors, marketTrends, signals }) {
+  const generatedAt = summary.completedAt;
+  const base = { schemaVersion: summary.schemaVersion, runId, role: NORMALIZER_ROLE, stage: NORMALIZER_STAGE, generatedAt };
+  return new Map([
+    [normalizerCompaniesPath(runId), { ...base, artifactPath: normalizerCompaniesPath(runId), companies: jsonClone(companies) }],
+    [normalizerInvestorsPath(runId), { ...base, artifactPath: normalizerInvestorsPath(runId), investors: jsonClone(investors) }],
+    [normalizerTrendsPath(runId), { ...base, artifactPath: normalizerTrendsPath(runId), trends: jsonClone(marketTrends) }],
+    [normalizerSignalsPath(runId), { ...base, artifactPath: normalizerSignalsPath(runId), signals: jsonClone(signals) }],
+    [normalizerDiagnosticsIndexPath(runId), {
+      ...base,
+      artifactPath: normalizerDiagnosticsIndexPath(runId),
+      diagnostics: jsonClone(diagnosticsArtifact.diagnostics ?? []),
+    }],
+  ]);
+}
+
+function createNormalizerLatestArtifact(collectorValidation, normalizerValidation) {
+  const collectorLatest = collectorValidation.latest;
+  const collectorSummary = collectorValidation.summary;
+  const normalizerSummary = normalizerValidation.summary;
+  return {
+    schemaVersion: normalizerSummary.schemaVersion,
+    latestPath: VENTURE_SIGNAL_LATEST_PATH,
+    runId: normalizerValidation.runId,
+    role: NORMALIZER_ROLE,
+    stage: NORMALIZER_STAGE,
+    status: normalizerSummary.status,
+    updatedAt: normalizerSummary.completedAt,
+    summaryPath: normalizerRunSummaryPath(normalizerValidation.runId),
+    diagnosticsPath: normalizerDiagnosticsPath(normalizerValidation.runId),
+    collectorSummaryPath: collectorRunSummaryPath(collectorValidation.runId),
+    collectorDiagnosticsPath: collectorDiagnosticsPath(collectorValidation.runId),
+    sourceCounts: jsonClone(collectorLatest?.sourceCounts ?? {
+      collected: collectorSummary.sourceCounts?.collected ?? 0,
+      failed: collectorSummary.sourceCounts?.failed ?? 0,
+      skippedOptional: collectorSummary.sourceCounts?.skippedOptional ?? 0,
+      rejectedPaid: collectorSummary.sourceCounts?.rejectedPaid ?? 0,
+    }),
+    freshness: jsonClone(collectorLatest?.freshness ?? {
+      status: 'unknown',
+      observedAt: collectorSummary.completedAt,
+      sourcePublishedAt: null,
+      reason: 'Normalizer latest promotion inherited Collector freshness metadata from the validated run summary.',
+    }),
+    stageStatuses: {
+      collector: collectorSummary.status,
+      normalizer: normalizerSummary.status,
+    },
+    normalizerCounts: jsonClone(normalizerSummary.counts),
+    promotion: {
+      status: 'promoted',
+      reason: 'Validated Collector and Normalizer artifacts were written before latest promotion.',
+    },
+  };
+}
+
+const SECRET_LOOKING_REGEX = new RegExp(SECRET_LOOKING_PATTERN);
+
+function uniqueSortedStrings(values) {
+  return [...new Set(values
+    .filter((value) => typeof value === 'string' && value.trim() !== '')
+    .map((value) => value.trim()))]
+    .sort((a, b) => a.localeCompare(b, 'en', { sensitivity: 'base' }));
+}
+
+function combinedStatus(statuses) {
+  if (statuses.includes('error')) return 'error';
+  if (statuses.includes('warn')) return 'warn';
+  return 'ok';
+}
+
+function assertNoSecretLookingDiagnostics(artifact, label) {
+  const diagnostics = Array.isArray(artifact?.diagnostics) ? artifact.diagnostics : [];
+  for (const diagnostic of diagnostics) {
+    for (const value of [diagnostic?.message, diagnostic?.details?.reason]) {
+      if (typeof value !== 'string') continue;
+      if (SECRET_LOOKING_REGEX.test(value)) {
+        SECRET_LOOKING_REGEX.lastIndex = 0;
+        throw new TypeError(`Invalid ${label}: diagnostics must be redacted before persistence.`);
+      }
+      SECRET_LOOKING_REGEX.lastIndex = 0;
+    }
+  }
+}
+
+function assertAnalysisIdentity(artifact, runId, label, role, stage, { requireRunId = true } = {}) {
+  if (!isPlainObject(artifact)) {
+    throw new TypeError(`Invalid ${label}: expected an object.`);
+  }
+  if (requireRunId && artifact.runId !== runId) {
+    throw new TypeError(`Invalid ${label}: runId must be ${runId}.`);
+  }
+  if (!requireRunId && Object.hasOwn(artifact, 'runId') && artifact.runId !== runId) {
+    throw new TypeError(`Invalid ${label}: runId must be ${runId} when present.`);
+  }
+  if (artifact.role !== role || artifact.stage !== stage) {
+    throw new TypeError(`Invalid ${label}: role and stage must be ${role}/${stage}.`);
+  }
+}
+
+function assertAnalysisPathBelongsToRun(runId, artifactPath, stage, label) {
+  const normalizedPath = normalizeVentureArtifactPath(artifactPath);
+  const runDirectory = stage === ANALYST_STAGE ? analystRunDirectoryPath(runId) : skepticRunDirectoryPath(runId);
+  if (!normalizedPath.startsWith(runDirectory)) {
+    throw new TypeError(`Invalid ${label} artifact path for run ${runId}: ${JSON.stringify(artifactPath)}.`);
+  }
+  return normalizedPath;
+}
+
+function assertAnalysisArtifactMapEntry(runId, relativePath, artifact, stage, role, label) {
+  const normalizedPath = assertAnalysisPathBelongsToRun(runId, relativePath, stage, label);
+
+  if (!isPlainObject(artifact)) {
+    throw new TypeError(`Invalid ${label} artifact at ${normalizedPath}: expected a JSON object.`);
+  }
+
+  assertAnalysisIdentity(artifact, runId, `${label} artifact at ${normalizedPath}`, role, stage, { requireRunId: false });
+
+  if (typeof artifact.artifactPath === 'string' && artifact.artifactPath !== normalizedPath) {
+    throw new TypeError(`Invalid ${label} artifact at ${normalizedPath}: artifactPath does not match file path.`);
+  }
+
+  return normalizedPath;
+}
+
+function assertExactArtifactPath(artifact, expectedPath, label) {
+  if (!isPlainObject(artifact)) {
+    throw new TypeError(`Invalid ${label}: expected a JSON object.`);
+  }
+  if (artifact.artifactPath !== expectedPath) {
+    throw new TypeError(`Invalid ${label}: artifactPath must be ${expectedPath}.`);
+  }
+}
+
+function assertAnalysisRunIdMatchesPrior(runId, priorRunId, label) {
+  if (runId !== priorRunId) {
+    throw new TypeError(`Invalid ${label}: runId must match validated prior stage run ${priorRunId}.`);
+  }
+}
+
+function validateAnalystRunForPersistence(result, normalizerValidation = null) {
+  if (!isPlainObject(result) || !(result.files instanceof Map)) {
+    throw new TypeError('Analyst result with a files Map is required.');
+  }
+
+  const runId = normalizeVentureRunId(result.runId);
+  if (normalizerValidation) assertAnalysisRunIdMatchesPrior(runId, normalizerValidation.runId, 'Analyst result');
+
+  const summary = result.summary;
+  const diagnosticsArtifact = result.diagnosticsArtifact;
+  const trendScoresArtifact = result.trendScoresArtifact;
+
+  assertAnalysisIdentity(summary, runId, 'Analyst run summary', ANALYST_ROLE, ANALYST_STAGE);
+  assertAnalysisIdentity(diagnosticsArtifact, runId, 'Analyst diagnostics artifact', ANALYST_ROLE, ANALYST_STAGE);
+  assertAnalysisIdentity(trendScoresArtifact, runId, 'Analyst trend-scores artifact', ANALYST_ROLE, ANALYST_STAGE);
+
+  if (!ANALYST_STATUS_VALUES.includes(summary.status)) {
+    throw new TypeError(`Invalid Analyst run status: ${JSON.stringify(summary.status)}.`);
+  }
+  if (result.status !== summary.status) {
+    throw new TypeError('Invalid Analyst result: top-level status must match summary status.');
+  }
+  if (summary.artifacts?.summary !== analystRunSummaryPath(runId)) {
+    throw new TypeError('Invalid Analyst run summary: summary artifact path is not exact.');
+  }
+  if (summary.artifacts?.diagnostics !== analystDiagnosticsPath(runId)) {
+    throw new TypeError('Invalid Analyst run summary: diagnostics artifact path is not exact.');
+  }
+  if (summary.artifacts?.trendScores !== analystTrendScoresPath(runId)) {
+    throw new TypeError('Invalid Analyst run summary: trend-scores artifact path is not exact.');
+  }
+  if (normalizerValidation) {
+    if (summary.artifacts?.normalizerSummary !== normalizerRunSummaryPath(normalizerValidation.runId)) {
+      throw new TypeError('Invalid Analyst run summary: normalizer summary path must match the validated Normalizer run.');
+    }
+    if (summary.artifacts?.normalizerDiagnostics !== normalizerDiagnosticsPath(normalizerValidation.runId)) {
+      throw new TypeError('Invalid Analyst run summary: normalizer diagnostics path must match the validated Normalizer run.');
+    }
+  }
+
+  assertExactArtifactPath(diagnosticsArtifact, analystDiagnosticsPath(runId), 'Analyst diagnostics artifact');
+  assertExactArtifactPath(trendScoresArtifact, analystTrendScoresPath(runId), 'Analyst trend-scores artifact');
+  assertNoSecretLookingDiagnostics(diagnosticsArtifact, 'Analyst diagnostics artifact');
+  assertNoSecretLookingDiagnostics(summary, 'Analyst run summary');
+
+  if (!result.files.has(analystRunSummaryPath(runId))) {
+    throw new TypeError('Invalid Analyst result: summary file is missing from artifact map.');
+  }
+  if (!result.files.has(analystDiagnosticsPath(runId))) {
+    throw new TypeError('Invalid Analyst result: diagnostics file is missing from artifact map.');
+  }
+  if (!result.files.has(analystTrendScoresPath(runId))) {
+    throw new TypeError('Invalid Analyst result: trend-scores file is missing from artifact map.');
+  }
+
+  const normalizedFiles = new Map();
+  for (const [relativePath, artifact] of result.files.entries()) {
+    const normalizedPath = assertAnalysisArtifactMapEntry(runId, relativePath, artifact, ANALYST_STAGE, ANALYST_ROLE, 'Analyst');
+    normalizedFiles.set(normalizedPath, artifact);
+  }
+
+  const trendScores = Array.isArray(result.trendScores) ? result.trendScores : [];
+  for (const trendScore of trendScores) {
+    assertAnalysisIdentity(trendScore, runId, 'Analyst trend score', ANALYST_ROLE, ANALYST_STAGE);
+    if (typeof trendScore.artifactPath !== 'string' || !normalizedFiles.has(trendScore.artifactPath)) {
+      throw new TypeError('Invalid Analyst trend score: artifactPath must be present in the files Map.');
+    }
+  }
+
+  return {
+    runId,
+    summary,
+    diagnosticsArtifact,
+    trendScoresArtifact,
+    files: normalizedFiles,
+    trendScores,
+    diagnostics: Array.isArray(result.diagnostics) ? result.diagnostics : [],
+    promotable: result.status !== 'error' && summary.status !== 'error' && trendScores.length > 0,
+  };
+}
+
+function validateSkepticRunForPersistence(result, analystValidation = null) {
+  if (!isPlainObject(result) || !(result.files instanceof Map)) {
+    throw new TypeError('Skeptic result with a files Map is required.');
+  }
+
+  const runId = normalizeVentureRunId(result.runId);
+  if (analystValidation) assertAnalysisRunIdMatchesPrior(runId, analystValidation.runId, 'Skeptic result');
+
+  const summary = result.summary;
+  const diagnosticsArtifact = result.diagnosticsArtifact;
+  const challengesArtifact = result.challengesArtifact;
+
+  assertAnalysisIdentity(result, runId, 'Skeptic result', SKEPTIC_ROLE, SKEPTIC_STAGE);
+  assertAnalysisIdentity(summary, runId, 'Skeptic review summary', ANALYST_ROLE, ANALYST_STAGE);
+  assertAnalysisIdentity(diagnosticsArtifact, runId, 'Skeptic diagnostics artifact', SKEPTIC_ROLE, SKEPTIC_STAGE);
+  assertAnalysisIdentity(challengesArtifact, runId, 'Skeptic challenged-claims artifact', SKEPTIC_ROLE, SKEPTIC_STAGE);
+
+  if (!SKEPTIC_STATUS_VALUES.includes(result.status) || !SKEPTIC_STATUS_VALUES.includes(summary.stageStatuses?.skeptic)) {
+    throw new TypeError(`Invalid Skeptic run status: ${JSON.stringify(result.status)}.`);
+  }
+  if (result.status !== summary.stageStatuses?.skeptic) {
+    throw new TypeError('Invalid Skeptic result: top-level status must match summary skeptic stage status.');
+  }
+  if (summary.artifacts?.skepticSummary !== skepticRunSummaryPath(runId)) {
+    throw new TypeError('Invalid Skeptic review summary: summary artifact path is not exact.');
+  }
+  if (summary.artifacts?.skepticDiagnostics !== skepticDiagnosticsPath(runId)) {
+    throw new TypeError('Invalid Skeptic review summary: diagnostics artifact path is not exact.');
+  }
+  if (analystValidation) {
+    if (summary.stageStatuses?.analyst !== analystValidation.summary.status) {
+      throw new TypeError('Invalid Skeptic review summary: analyst stage status must match the validated Analyst result.');
+    }
+    if (summary.artifacts?.analystSummary !== analystRunSummaryPath(analystValidation.runId)) {
+      throw new TypeError('Invalid Skeptic review summary: analyst summary path must match the validated Analyst run.');
+    }
+    if (summary.artifacts?.analystDiagnostics !== analystDiagnosticsPath(analystValidation.runId)) {
+      throw new TypeError('Invalid Skeptic review summary: analyst diagnostics path must match the validated Analyst run.');
+    }
+  }
+
+  assertExactArtifactPath(diagnosticsArtifact, skepticDiagnosticsPath(runId), 'Skeptic diagnostics artifact');
+  assertExactArtifactPath(challengesArtifact, skepticChallengesPath(runId), 'Skeptic challenged-claims artifact');
+  assertNoSecretLookingDiagnostics(diagnosticsArtifact, 'Skeptic diagnostics artifact');
+
+  if (!result.files.has(skepticRunSummaryPath(runId))) {
+    throw new TypeError('Invalid Skeptic result: review summary file is missing from artifact map.');
+  }
+  if (!result.files.has(skepticDiagnosticsPath(runId))) {
+    throw new TypeError('Invalid Skeptic result: diagnostics file is missing from artifact map.');
+  }
+  if (!result.files.has(skepticChallengesPath(runId))) {
+    throw new TypeError('Invalid Skeptic result: challenged-claims file is missing from artifact map.');
+  }
+
+  const normalizedFiles = new Map();
+  for (const [relativePath, artifact] of result.files.entries()) {
+    const normalizedPath = assertAnalysisPathBelongsToRun(runId, relativePath, SKEPTIC_STAGE, 'Skeptic');
+    if (!isPlainObject(artifact)) {
+      throw new TypeError(`Invalid Skeptic artifact at ${normalizedPath}: expected a JSON object.`);
+    }
+    if (normalizedPath === skepticRunSummaryPath(runId)) {
+      assertAnalysisIdentity(artifact, runId, `Skeptic artifact at ${normalizedPath}`, ANALYST_ROLE, ANALYST_STAGE, { requireRunId: false });
+    } else {
+      assertAnalysisIdentity(artifact, runId, `Skeptic artifact at ${normalizedPath}`, SKEPTIC_ROLE, SKEPTIC_STAGE, { requireRunId: false });
+    }
+    if (typeof artifact.artifactPath === 'string' && artifact.artifactPath !== normalizedPath) {
+      throw new TypeError(`Invalid Skeptic artifact at ${normalizedPath}: artifactPath does not match file path.`);
+    }
+    normalizedFiles.set(normalizedPath, artifact);
+  }
+
+  const challenges = Array.isArray(result.skepticChallenges) ? result.skepticChallenges : [];
+  for (const challenge of challenges) {
+    assertAnalysisIdentity(challenge, runId, 'Skeptic challenge', SKEPTIC_ROLE, SKEPTIC_STAGE);
+    if (typeof challenge.artifactPath !== 'string' || !normalizedFiles.has(challenge.artifactPath)) {
+      throw new TypeError('Invalid Skeptic challenge: artifactPath must be present in the files Map.');
+    }
+  }
+
+  return {
+    runId,
+    summary,
+    diagnosticsArtifact,
+    challengesArtifact,
+    files: normalizedFiles,
+    challenges,
+    diagnostics: Array.isArray(result.diagnostics) ? result.diagnostics : [],
+    confidenceAdjustments: Array.isArray(result.confidenceAdjustments) ? result.confidenceAdjustments : [],
+    promotable: result.status !== 'error' && summary.stageStatuses?.skeptic !== 'error' && Array.isArray(summary.trendScores) && summary.trendScores.length > 0,
+  };
+}
+
+export function analysisAnalystDiagnosticsPath(runId) {
+  return `${analystRunDirectoryPath(runId)}diagnostics.json`;
+}
+
+export function analysisSkepticReviewPath(runId) {
+  return `${skepticRunDirectoryPath(runId)}review.json`;
+}
+
+export function analysisSkepticChallengedClaimsPath(runId) {
+  return `${skepticRunDirectoryPath(runId)}challenged-claims.json`;
+}
+
+export function analysisSkepticDiagnosticsPath(runId) {
+  return `${skepticRunDirectoryPath(runId)}diagnostics.json`;
+}
+
+function replaceWrittenArtifacts(written, replacements) {
+  return uniqueSortedStrings((written ?? []).map((artifactPath) => replacements.get(artifactPath) ?? artifactPath));
+}
+
+function createPersistedAnalystArtifacts(analystValidation, stageStatuses) {
+  const runId = analystValidation.runId;
+  const diagnosticsPath = analysisAnalystDiagnosticsPath(runId);
+  const replacements = new Map([[analystDiagnosticsPath(runId), diagnosticsPath]]);
+  const summary = {
+    ...jsonClone(analystValidation.summary),
+    stageStatuses: jsonClone(stageStatuses),
+    artifacts: {
+      ...jsonClone(analystValidation.summary.artifacts),
+      diagnostics: diagnosticsPath,
+      written: replaceWrittenArtifacts(analystValidation.summary.artifacts?.written, replacements),
+    },
+  };
+  const diagnosticsArtifact = {
+    ...jsonClone(analystValidation.diagnosticsArtifact),
+    artifactPath: diagnosticsPath,
+  };
+  const files = new Map();
+  files.set(analystRunSummaryPath(runId), summary);
+  files.set(diagnosticsPath, diagnosticsArtifact);
+  for (const [relativePath, artifact] of analystValidation.files.entries()) {
+    if (relativePath === analystRunSummaryPath(runId) || relativePath === analystDiagnosticsPath(runId)) continue;
+    files.set(relativePath, artifact);
+  }
+  return { summary, diagnosticsArtifact, files };
+}
+
+function createPersistedSkepticArtifacts(skepticValidation, stageStatuses) {
+  const runId = skepticValidation.runId;
+  const reviewPath = analysisSkepticReviewPath(runId);
+  const diagnosticsPath = analysisSkepticDiagnosticsPath(runId);
+  const challengedClaimsPath = analysisSkepticChallengedClaimsPath(runId);
+  const replacements = new Map([
+    [skepticRunSummaryPath(runId), reviewPath],
+    [skepticDiagnosticsPath(runId), diagnosticsPath],
+    [skepticChallengesPath(runId), challengedClaimsPath],
+  ]);
+  const summary = {
+    ...jsonClone(skepticValidation.summary),
+    stageStatuses: jsonClone(stageStatuses),
+    artifacts: {
+      ...jsonClone(skepticValidation.summary.artifacts),
+      skepticSummary: reviewPath,
+      skepticDiagnostics: diagnosticsPath,
+      written: replaceWrittenArtifacts(skepticValidation.summary.artifacts?.written, replacements),
+    },
+  };
+  const diagnosticsArtifact = {
+    ...jsonClone(skepticValidation.diagnosticsArtifact),
+    artifactPath: diagnosticsPath,
+  };
+  const challengedClaimsArtifact = {
+    ...jsonClone(skepticValidation.challengesArtifact),
+    artifactPath: challengedClaimsPath,
+  };
+  const files = new Map();
+  files.set(reviewPath, summary);
+  files.set(diagnosticsPath, diagnosticsArtifact);
+  files.set(challengedClaimsPath, challengedClaimsArtifact);
+  for (const [relativePath, artifact] of skepticValidation.files.entries()) {
+    if ([skepticRunSummaryPath(runId), skepticDiagnosticsPath(runId), skepticChallengesPath(runId)].includes(relativePath)) continue;
+    files.set(relativePath, artifact);
+  }
+  return { summary, diagnosticsArtifact, challengedClaimsArtifact, files };
+}
+
+function createAnalysisLatestArtifact({ collectorValidation, normalizerValidation, analystValidation, skepticValidation, analystArtifacts, skepticArtifacts, stageStatuses }) {
+  const collectorSummary = collectorValidation.summary;
+  const collectorLatest = collectorValidation.latest;
+  const status = combinedStatus(Object.values(stageStatuses));
+  return {
+    schemaVersion: skepticArtifacts.summary.schemaVersion,
+    latestPath: VENTURE_SIGNAL_LATEST_PATH,
+    runId: skepticValidation.runId,
+    role: SKEPTIC_ROLE,
+    stage: SKEPTIC_STAGE,
+    status,
+    updatedAt: skepticArtifacts.summary.completedAt,
+    summaryPath: analysisSkepticReviewPath(skepticValidation.runId),
+    diagnosticsPath: analysisSkepticDiagnosticsPath(skepticValidation.runId),
+    collectorSummaryPath: collectorRunSummaryPath(collectorValidation.runId),
+    collectorDiagnosticsPath: collectorDiagnosticsPath(collectorValidation.runId),
+    normalizerSummaryPath: normalizerRunSummaryPath(normalizerValidation.runId),
+    normalizerDiagnosticsPath: normalizerDiagnosticsPath(normalizerValidation.runId),
+    analystSummaryPath: analystRunSummaryPath(analystValidation.runId),
+    analystDiagnosticsPath: analysisAnalystDiagnosticsPath(analystValidation.runId),
+    analystTrendScoresPath: analystTrendScoresPath(analystValidation.runId),
+    skepticReviewPath: analysisSkepticReviewPath(skepticValidation.runId),
+    skepticChallengedClaimsPath: analysisSkepticChallengedClaimsPath(skepticValidation.runId),
+    skepticDiagnosticsPath: analysisSkepticDiagnosticsPath(skepticValidation.runId),
+    sourceCounts: jsonClone(collectorLatest?.sourceCounts ?? {
+      collected: collectorSummary.sourceCounts?.collected ?? 0,
+      failed: collectorSummary.sourceCounts?.failed ?? 0,
+      skippedOptional: collectorSummary.sourceCounts?.skippedOptional ?? 0,
+      rejectedPaid: collectorSummary.sourceCounts?.rejectedPaid ?? 0,
+    }),
+    freshness: jsonClone(collectorLatest?.freshness ?? {
+      status: 'unknown',
+      observedAt: collectorSummary.completedAt,
+      sourcePublishedAt: null,
+      reason: 'Analysis latest promotion inherited Collector freshness metadata from the validated run summary.',
+    }),
+    stageStatuses: jsonClone(stageStatuses),
+    normalizerCounts: jsonClone(normalizerValidation.summary.counts),
+    analysisCounts: jsonClone(analystArtifacts.summary.counts),
+    skepticCounts: {
+      challengedClaims: skepticValidation.challenges.length,
+      confidenceAdjustments: skepticValidation.confidenceAdjustments.length,
+      diagnostics: skepticValidation.diagnostics.length,
+    },
+    promotion: {
+      status: 'promoted',
+      reason: 'Validated Collector, Normalizer, Analyst, and Skeptic artifacts were written before analysis latest promotion.',
+    },
+  };
+}
+
+async function writeJsonArtifact(rootDir, relativePath, artifact) {
+  const { normalizedArtifactPath, destination } = assertSafeDestination(rootDir, relativePath);
+  await mkdir(path.dirname(destination), { recursive: true });
+  await writeFile(destination, `${JSON.stringify(artifact, null, 2)}\n`, 'utf8');
+  return normalizedArtifactPath;
+}
+
+async function writeTextArtifact(rootDir, relativePath, text) {
+  const { normalizedArtifactPath, destination } = assertSafeDestination(rootDir, relativePath);
+  if (typeof text !== 'string' || text.trim() === '') {
+    throw new TypeError(`Invalid text artifact at ${normalizedArtifactPath}: expected non-empty text.`);
+  }
+  await mkdir(path.dirname(destination), { recursive: true });
+  await writeFile(destination, text.endsWith('\n') ? text : `${text}\n`, 'utf8');
+  return normalizedArtifactPath;
+}
+
+export function isPromotableCollectorStatus(status) {
+  return PROMOTABLE_COLLECTOR_STATUSES.has(status);
+}
+
+export async function persistCollectorRun(result, { rootDir = process.cwd() } = {}) {
+  const validation = validateCollectorRunForPersistence(result);
+  const written = [];
+
+  for (const [relativePath, artifact] of validation.files.entries()) {
+    if (relativePath === VENTURE_SIGNAL_LATEST_PATH) continue;
+    written.push(await writeJsonArtifact(rootDir, relativePath, artifact));
+  }
+
+  let latestPromoted = false;
+  if (validation.promotable && validation.latest) {
+    written.push(await writeJsonArtifact(rootDir, VENTURE_SIGNAL_LATEST_PATH, validation.latest));
+    latestPromoted = true;
+  }
+
+  return {
+    runId: validation.runId,
+    role: COLLECTOR_ROLE,
+    stage: COLLECTOR_STAGE,
+    status: validation.summary.status,
+    summaryPath: collectorRunSummaryPath(validation.runId),
+    diagnosticsPath: collectorDiagnosticsPath(validation.runId),
+    latestPath: latestPromoted ? VENTURE_SIGNAL_LATEST_PATH : null,
+    latestPromoted,
+    previousLatestPreserved: !latestPromoted,
+    written,
+    summary: jsonClone(validation.summary),
+    diagnostics: jsonClone(validation.diagnosticsArtifact.diagnostics ?? []),
+  };
+}
+
+export async function persistNormalizerRun(result, { rootDir = process.cwd(), collectorResult = null } = {}) {
+  const collectorValidation = collectorResult ? validateCollectorRunForPersistence(collectorResult) : null;
+  const validation = validateNormalizerRunForPersistence(result, collectorValidation);
+  const written = [];
+
+  if (collectorValidation) {
+    for (const [relativePath, artifact] of collectorValidation.files.entries()) {
+      if (relativePath === VENTURE_SIGNAL_LATEST_PATH) continue;
+      written.push(await writeJsonArtifact(rootDir, relativePath, artifact));
+    }
+  }
+
+  for (const [relativePath, artifact] of validation.files.entries()) {
+    written.push(await writeJsonArtifact(rootDir, relativePath, artifact));
+  }
+
+  for (const [relativePath, artifact] of validation.aggregateArtifacts.entries()) {
+    written.push(await writeJsonArtifact(rootDir, relativePath, artifact));
+  }
+
+  let latestPromoted = false;
+  if (validation.promotable && collectorValidation?.promotable) {
+    const latest = createNormalizerLatestArtifact(collectorValidation, validation);
+    written.push(await writeJsonArtifact(rootDir, VENTURE_SIGNAL_LATEST_PATH, latest));
+    latestPromoted = true;
+  }
+
+  return {
+    runId: validation.runId,
+    role: NORMALIZER_ROLE,
+    stage: NORMALIZER_STAGE,
+    status: validation.summary.status,
+    stageStatuses: {
+      collector: collectorValidation?.summary.status ?? null,
+      normalizer: validation.summary.status,
+    },
+    summaryPath: normalizerRunSummaryPath(validation.runId),
+    diagnosticsPath: normalizerDiagnosticsPath(validation.runId),
+    aggregatePaths: {
+      companies: normalizerCompaniesPath(validation.runId),
+      investors: normalizerInvestorsPath(validation.runId),
+      trends: normalizerTrendsPath(validation.runId),
+      signals: normalizerSignalsPath(validation.runId),
+      diagnostics: normalizerDiagnosticsIndexPath(validation.runId),
+    },
+    latestPath: latestPromoted ? VENTURE_SIGNAL_LATEST_PATH : null,
+    latestPromoted,
+    previousLatestPreserved: !latestPromoted,
+    written,
+    summary: jsonClone(validation.summary),
+    diagnostics: jsonClone(validation.diagnosticsArtifact.diagnostics ?? []),
+  };
+}
+
+export async function persistAnalysisRun(result, { rootDir = process.cwd() } = {}) {
+  if (!isPlainObject(result)) {
+    throw new TypeError('Analysis persistence requires Collector, Normalizer, Analyst, and Skeptic results.');
+  }
+
+  const collectorValidation = validateCollectorRunForPersistence(result.collectorResult);
+  const normalizerValidation = validateNormalizerRunForPersistence(result.normalizerResult, collectorValidation);
+  const analystValidation = validateAnalystRunForPersistence(result.analystResult, normalizerValidation);
+  const skepticValidation = validateSkepticRunForPersistence(result.skepticResult, analystValidation);
+  const stageStatuses = {
+    collector: collectorValidation.summary.status,
+    normalizer: normalizerValidation.summary.status,
+    analyst: analystValidation.summary.status,
+    skeptic: skepticValidation.summary.stageStatuses.skeptic,
+  };
+  const analystArtifacts = createPersistedAnalystArtifacts(analystValidation, stageStatuses);
+  const skepticArtifacts = createPersistedSkepticArtifacts(skepticValidation, stageStatuses);
+  const status = combinedStatus(Object.values(stageStatuses));
+  const written = [];
+
+  for (const [relativePath, artifact] of collectorValidation.files.entries()) {
+    if (relativePath === VENTURE_SIGNAL_LATEST_PATH) continue;
+    written.push(await writeJsonArtifact(rootDir, relativePath, artifact));
+  }
+
+  for (const [relativePath, artifact] of normalizerValidation.files.entries()) {
+    written.push(await writeJsonArtifact(rootDir, relativePath, artifact));
+  }
+
+  for (const [relativePath, artifact] of normalizerValidation.aggregateArtifacts.entries()) {
+    written.push(await writeJsonArtifact(rootDir, relativePath, artifact));
+  }
+
+  for (const [relativePath, artifact] of analystArtifacts.files.entries()) {
+    written.push(await writeJsonArtifact(rootDir, relativePath, artifact));
+  }
+
+  for (const [relativePath, artifact] of skepticArtifacts.files.entries()) {
+    written.push(await writeJsonArtifact(rootDir, relativePath, artifact));
+  }
+
+  let latestPromoted = false;
+  if (
+    collectorValidation.promotable
+    && normalizerValidation.promotable
+    && analystValidation.promotable
+    && skepticValidation.promotable
+    && status !== 'error'
+  ) {
+    const latest = createAnalysisLatestArtifact({
+      collectorValidation,
+      normalizerValidation,
+      analystValidation,
+      skepticValidation,
+      analystArtifacts,
+      skepticArtifacts,
+      stageStatuses,
+    });
+    written.push(await writeJsonArtifact(rootDir, VENTURE_SIGNAL_LATEST_PATH, latest));
+    latestPromoted = true;
+  }
+
+  return {
+    runId: skepticValidation.runId,
+    role: SKEPTIC_ROLE,
+    stage: SKEPTIC_STAGE,
+    status,
+    stageStatuses,
+    summaryPath: analysisSkepticReviewPath(skepticValidation.runId),
+    diagnosticsPath: analysisSkepticDiagnosticsPath(skepticValidation.runId),
+    analystPaths: {
+      summary: analystRunSummaryPath(analystValidation.runId),
+      diagnostics: analysisAnalystDiagnosticsPath(analystValidation.runId),
+      trendScores: analystTrendScoresPath(analystValidation.runId),
+      trendScoreArtifacts: jsonClone(analystArtifacts.summary.artifacts.trendScoreArtifacts ?? []),
+    },
+    skepticPaths: {
+      review: analysisSkepticReviewPath(skepticValidation.runId),
+      challengedClaims: analysisSkepticChallengedClaimsPath(skepticValidation.runId),
+      diagnostics: analysisSkepticDiagnosticsPath(skepticValidation.runId),
+      challengeArtifacts: jsonClone(skepticValidation.challenges.map((challenge) => challenge.artifactPath)),
+    },
+    latestPath: latestPromoted ? VENTURE_SIGNAL_LATEST_PATH : null,
+    latestPromoted,
+    previousLatestPreserved: !latestPromoted,
+    written,
+    summary: jsonClone(skepticArtifacts.summary),
+    analystSummary: jsonClone(analystArtifacts.summary),
+    analystDiagnostics: jsonClone(analystArtifacts.diagnosticsArtifact.diagnostics ?? []),
+    skepticDiagnostics: jsonClone(skepticArtifacts.diagnosticsArtifact.diagnostics ?? []),
+    challengedClaims: jsonClone(skepticValidation.challenges),
+    confidenceAdjustments: jsonClone(skepticValidation.confidenceAdjustments),
+  };
+}
+
+
+function assertPmWriterIdentity(artifact, runId, label, { requireRunId = true } = {}) {
+  if (!isPlainObject(artifact)) {
+    throw new TypeError(`Invalid ${label}: expected an object.`);
+  }
+  if (requireRunId && artifact.runId !== runId) {
+    throw new TypeError(`Invalid ${label}: runId must be ${runId}.`);
+  }
+  if (!requireRunId && Object.hasOwn(artifact, 'runId') && artifact.runId !== runId) {
+    throw new TypeError(`Invalid ${label}: runId must be ${runId} when present.`);
+  }
+  if (artifact.role !== PM_WRITER_ROLE || artifact.stage !== PM_WRITER_STAGE) {
+    throw new TypeError(`Invalid ${label}: role and stage must be PM Writer.`);
+  }
+}
+
+function assertPmWriterPathBelongsToRun(runId, artifactPath, label) {
+  const normalizedPath = normalizeVentureArtifactPath(artifactPath);
+  const runDirectory = pmWriterRunDirectoryPath(runId);
+  if (!normalizedPath.startsWith(runDirectory)) {
+    throw new TypeError(`Invalid ${label} artifact path for run ${runId}: ${JSON.stringify(artifactPath)}.`);
+  }
+  return normalizedPath;
+}
+
+function assertPmWriterArtifactMapEntry(runId, relativePath, artifact) {
+  const normalizedPath = assertPmWriterPathBelongsToRun(runId, relativePath, 'PM Writer');
+
+  if (!isPlainObject(artifact)) {
+    throw new TypeError(`Invalid PM Writer artifact at ${normalizedPath}: expected a JSON object.`);
+  }
+
+  assertPmWriterIdentity(artifact, runId, `PM Writer artifact at ${normalizedPath}`, { requireRunId: false });
+
+  if (typeof artifact.artifactPath === 'string' && artifact.artifactPath !== normalizedPath) {
+    throw new TypeError(`Invalid PM Writer artifact at ${normalizedPath}: artifactPath does not match file path.`);
+  }
+
+  return normalizedPath;
+}
+
+function createPmWriterTracePathSet(analysisValidation) {
+  if (!analysisValidation) return null;
+  const tracePaths = new Set();
+  for (const map of [
+    analysisValidation.collectorValidation.files,
+    analysisValidation.normalizerValidation.files,
+    analysisValidation.normalizerValidation.aggregateArtifacts,
+    analysisValidation.analystValidation.files,
+    analysisValidation.skepticValidation.files,
+    analysisValidation.analystArtifacts.files,
+    analysisValidation.skepticArtifacts.files,
+  ]) {
+    for (const relativePath of map.keys()) tracePaths.add(relativePath);
+  }
+  return tracePaths;
+}
+
+function assertPmWriterTraceLinks({ dailyRadar, sectorMemos, tracePaths }) {
+  if (!tracePaths) return;
+
+  const recommendationGroups = [
+    dailyRadar.recommendations ?? [],
+    ...sectorMemos.map((memo) => memo.recommendations ?? []),
+  ];
+  for (const recommendations of recommendationGroups) {
+    for (const recommendation of recommendations) {
+      for (const evidenceRef of recommendation.evidenceRefs ?? []) {
+        if (typeof evidenceRef?.signalPath !== 'string' || !tracePaths.has(evidenceRef.signalPath)) {
+          throw new TypeError(`Invalid PM Writer result: broken PM Writer evidence trace link ${JSON.stringify(evidenceRef?.signalPath)}.`);
+        }
+      }
+      for (const skepticRef of recommendation.skepticRefs ?? []) {
+        if (typeof skepticRef?.challengePath !== 'string' || !tracePaths.has(skepticRef.challengePath)) {
+          throw new TypeError(`Invalid PM Writer result: broken PM Writer Skeptic trace link ${JSON.stringify(skepticRef?.challengePath)}.`);
+        }
+      }
+    }
+  }
+
+  for (const alert of dailyRadar.alertCandidates ?? []) {
+    for (const evidenceRef of alert.evidenceRefs ?? []) {
+      if (typeof evidenceRef?.signalPath !== 'string' || !tracePaths.has(evidenceRef.signalPath)) {
+        throw new TypeError(`Invalid PM Writer result: broken PM Writer evidence trace link ${JSON.stringify(evidenceRef?.signalPath)}.`);
+      }
+    }
+    for (const skepticRef of alert.skepticRefs ?? []) {
+      if (typeof skepticRef?.challengePath !== 'string' || !tracePaths.has(skepticRef.challengePath)) {
+        throw new TypeError(`Invalid PM Writer result: broken PM Writer Skeptic trace link ${JSON.stringify(skepticRef?.challengePath)}.`);
+      }
+    }
+  }
+}
+
+function assertPmWriterMarkdownPairs(result, validation) {
+  if (!isPlainObject(result.markdown)) {
+    throw new TypeError('Invalid PM Writer result: Markdown render outputs are required.');
+  }
+  const dailyRadarMarkdown = result.markdown.dailyRadar;
+  if (dailyRadarMarkdown !== renderDailyRadarMarkdown(validation.dailyRadar)) {
+    throw new TypeError('Invalid PM Writer result: Daily radar Markdown must match the validated JSON artifact.');
+  }
+  if (!(result.markdown.sectorMemos instanceof Map)) {
+    throw new TypeError('Invalid PM Writer result: sector memo Markdown outputs must be a Map.');
+  }
+  for (const memo of validation.sectorMemos) {
+    const memoMarkdown = result.markdown.sectorMemos.get(memo.marketTrendId);
+    if (memoMarkdown !== renderSectorMemoMarkdown(memo)) {
+      throw new TypeError(`Invalid PM Writer result: Sector memo Markdown must match the validated JSON artifact for ${memo.marketTrendId}.`);
+    }
+  }
+}
+
+function assertPmWriterStageStatuses(summary, dailyRadar, sectorMemos, expectedStageStatuses) {
+  const traces = [dailyRadar.roleStageTrace, ...sectorMemos.map((memo) => memo.roleStageTrace)];
+  for (const trace of traces) {
+    if (!isPlainObject(trace?.stageStatuses)) {
+      throw new TypeError('Invalid PM Writer result: role-stage trace stage statuses are required.');
+    }
+    if (trace.stageStatuses.pmWriter !== summary.status) {
+      throw new TypeError('Invalid PM Writer result: PM Writer trace status must match the run summary status.');
+    }
+    if (expectedStageStatuses) {
+      for (const [stage, status] of Object.entries(expectedStageStatuses)) {
+        if (trace.stageStatuses[stage] !== status) {
+          throw new TypeError(`Invalid PM Writer result: ${stage} stage status must match the validated prior stage.`);
+        }
+      }
+    }
+  }
+}
+
+function validatePmWriterRunForPersistence(result, analysisValidation = null) {
+  if (!isPlainObject(result) || !(result.files instanceof Map)) {
+    throw new TypeError('PM Writer result with a files Map is required.');
+  }
+
+  const runId = normalizeVentureRunId(result.runId);
+  if (analysisValidation) assertAnalysisRunIdMatchesPrior(runId, analysisValidation.skepticValidation.runId, 'PM Writer result');
+
+  const summary = result.summary;
+  const diagnosticsArtifact = result.diagnosticsArtifact;
+  const dailyRadar = result.dailyRadar;
+  const recommendationsArtifact = result.recommendationsArtifact;
+  const alertCandidatesArtifact = result.alertCandidatesArtifact;
+  const mvpExperimentsArtifact = result.mvpExperimentsArtifact;
+  const sectorMemos = Array.isArray(result.sectorMemos) ? result.sectorMemos : [];
+
+  assertPmWriterIdentity(summary, runId, 'PM Writer run summary');
+  assertPmWriterIdentity(diagnosticsArtifact, runId, 'PM Writer diagnostics artifact');
+  assertPmWriterIdentity(dailyRadar, runId, 'PM Writer daily radar');
+  assertPmWriterIdentity(recommendationsArtifact, runId, 'PM Writer recommendations artifact');
+  assertPmWriterIdentity(alertCandidatesArtifact, runId, 'PM Writer alert candidates artifact');
+  assertPmWriterIdentity(mvpExperimentsArtifact, runId, 'PM Writer MVP experiments artifact');
+  for (const memo of sectorMemos) assertPmWriterIdentity(memo, runId, `PM Writer sector memo ${memo?.marketTrendId ?? ''}`);
+
+  if (!PM_WRITER_STATUS_VALUES.includes(summary.status)) {
+    throw new TypeError(`Invalid PM Writer run status: ${JSON.stringify(summary.status)}.`);
+  }
+  if (result.status !== summary.status) {
+    throw new TypeError('Invalid PM Writer result: top-level status must match summary status.');
+  }
+  if (summary.status === 'error') {
+    throw new TypeError('Invalid PM Writer result: error runs are not promotable.');
+  }
+  if (summary.artifacts?.summary !== pmWriterRunSummaryPath(runId)) {
+    throw new TypeError('Invalid PM Writer run summary: summary artifact path is not exact.');
+  }
+  if (summary.artifacts?.diagnostics !== pmWriterDiagnosticsPath(runId)) {
+    throw new TypeError('Invalid PM Writer run summary: diagnostics artifact path is not exact.');
+  }
+  if (summary.artifacts?.dailyRadar !== pmWriterDailyRadarPath(runId)) {
+    throw new TypeError('Invalid PM Writer run summary: daily radar artifact path is not exact.');
+  }
+  if (summary.artifacts?.recommendations !== pmWriterRecommendationsPath(runId)) {
+    throw new TypeError('Invalid PM Writer run summary: recommendations artifact path is not exact.');
+  }
+  if (summary.artifacts?.alertCandidates !== pmWriterAlertCandidatesPath(runId)) {
+    throw new TypeError('Invalid PM Writer run summary: alert candidates artifact path is not exact.');
+  }
+  if (summary.artifacts?.mvpExperiments !== pmWriterMvpExperimentsPath(runId)) {
+    throw new TypeError('Invalid PM Writer run summary: MVP experiments artifact path is not exact.');
+  }
+
+  assertExactArtifactPath(diagnosticsArtifact, pmWriterDiagnosticsPath(runId), 'PM Writer diagnostics artifact');
+  assertExactArtifactPath(dailyRadar, pmWriterDailyRadarPath(runId), 'PM Writer daily radar');
+  assertExactArtifactPath(recommendationsArtifact, pmWriterRecommendationsPath(runId), 'PM Writer recommendations artifact');
+  assertExactArtifactPath(alertCandidatesArtifact, pmWriterAlertCandidatesPath(runId), 'PM Writer alert candidates artifact');
+  assertExactArtifactPath(mvpExperimentsArtifact, pmWriterMvpExperimentsPath(runId), 'PM Writer MVP experiments artifact');
+  for (const memo of sectorMemos) {
+    assertExactArtifactPath(memo, pmWriterSectorMemoPath(runId, memo.marketTrendId), `PM Writer sector memo ${memo.marketTrendId}`);
+  }
+  assertNoSecretLookingDiagnostics(diagnosticsArtifact, 'PM Writer diagnostics artifact');
+  assertNoSecretLookingDiagnostics(summary, 'PM Writer run summary');
+  assertSchemaValid(pmWriterRunSummarySchema, summary, 'PM Writer run summary');
+  assertSchemaValid(pmWriterDiagnosticsArtifactSchema, diagnosticsArtifact, 'PM Writer diagnostics artifact');
+  assertSchemaValid(dailyRadarSchema, dailyRadar, 'PM Writer daily radar');
+  for (const memo of sectorMemos) assertSchemaValid(sectorMemoSchema, memo, `PM Writer sector memo ${memo.marketTrendId}`);
+
+  for (const expectedPath of [
+    pmWriterRunSummaryPath(runId),
+    pmWriterDiagnosticsPath(runId),
+    pmWriterDailyRadarPath(runId),
+    pmWriterRecommendationsPath(runId),
+    pmWriterAlertCandidatesPath(runId),
+    pmWriterMvpExperimentsPath(runId),
+    ...sectorMemos.map((memo) => pmWriterSectorMemoPath(runId, memo.marketTrendId)),
+  ]) {
+    if (!result.files.has(expectedPath)) {
+      throw new TypeError(`Invalid PM Writer result: ${expectedPath} is missing from artifact map.`);
+    }
+  }
+
+  const markdownPaths = [
+    pmWriterDailyRadarMarkdownPath(runId),
+    ...sectorMemos.map((memo) => pmWriterSectorMemoMarkdownPath(runId, memo.marketTrendId)),
+  ];
+  const summaryForPersistence = {
+    ...jsonClone(summary),
+    artifacts: {
+      ...jsonClone(summary.artifacts),
+      written: uniqueSortedStrings([...(summary.artifacts?.written ?? []), ...markdownPaths]),
+    },
+  };
+
+  const normalizedFiles = new Map();
+  for (const [relativePath, artifact] of result.files.entries()) {
+    const normalizedPath = assertPmWriterArtifactMapEntry(runId, relativePath, artifact);
+    normalizedFiles.set(normalizedPath, normalizedPath === pmWriterRunSummaryPath(runId) ? summaryForPersistence : artifact);
+  }
+
+  const expectedStageStatuses = analysisValidation ? {
+    collector: analysisValidation.collectorValidation.summary.status,
+    normalizer: analysisValidation.normalizerValidation.summary.status,
+    analyst: analysisValidation.analystValidation.summary.status,
+    skeptic: analysisValidation.skepticValidation.summary.stageStatuses.skeptic,
+    pmWriter: summary.status,
+  } : null;
+  assertPmWriterStageStatuses(summary, dailyRadar, sectorMemos, expectedStageStatuses);
+  const validation = {
+    runId,
+    summary: summaryForPersistence,
+    diagnosticsArtifact,
+    dailyRadar,
+    recommendationsArtifact,
+    alertCandidatesArtifact,
+    mvpExperimentsArtifact,
+    sectorMemos,
+    files: normalizedFiles,
+    markdown: {
+      dailyRadar: result.markdown?.dailyRadar,
+      sectorMemos: result.markdown?.sectorMemos,
+    },
+    status: summary.status,
+    stageStatuses: expectedStageStatuses ?? dailyRadar.roleStageTrace.stageStatuses,
+    promotable: summary.status !== 'error',
+  };
+  assertPmWriterMarkdownPairs(result, validation);
+  assertPmWriterTraceLinks({ dailyRadar, sectorMemos, tracePaths: createPmWriterTracePathSet(analysisValidation) });
+
+  return validation;
+}
+
+function createPmWriterLatestArtifact({ collectorValidation, normalizerValidation, writerValidation, writerPaths }) {
+  const collectorSummary = collectorValidation.summary;
+  const collectorLatest = collectorValidation.latest;
+  return {
+    schemaVersion: writerValidation.summary.schemaVersion,
+    latestPath: VENTURE_SIGNAL_LATEST_PATH,
+    runId: writerValidation.runId,
+    role: PM_WRITER_ROLE,
+    stage: PM_WRITER_STAGE,
+    status: combinedStatus(Object.values(writerValidation.stageStatuses)),
+    updatedAt: writerValidation.summary.completedAt,
+    summaryPath: pmWriterRunSummaryPath(writerValidation.runId),
+    diagnosticsPath: pmWriterDiagnosticsPath(writerValidation.runId),
+    dailyRadarPath: pmWriterDailyRadarPath(writerValidation.runId),
+    collectorSummaryPath: collectorRunSummaryPath(collectorValidation.runId),
+    collectorDiagnosticsPath: collectorDiagnosticsPath(collectorValidation.runId),
+    normalizerSummaryPath: normalizerRunSummaryPath(normalizerValidation.runId),
+    normalizerDiagnosticsPath: normalizerDiagnosticsPath(normalizerValidation.runId),
+    writerPaths: jsonClone(writerPaths),
+    sourceCounts: jsonClone(collectorLatest?.sourceCounts ?? {
+      collected: collectorSummary.sourceCounts?.collected ?? 0,
+      failed: collectorSummary.sourceCounts?.failed ?? 0,
+      skippedOptional: collectorSummary.sourceCounts?.skippedOptional ?? 0,
+      rejectedPaid: collectorSummary.sourceCounts?.rejectedPaid ?? 0,
+    }),
+    freshness: jsonClone(collectorLatest?.freshness ?? {
+      status: 'unknown',
+      observedAt: collectorSummary.completedAt,
+      sourcePublishedAt: null,
+      reason: 'PM Writer latest promotion inherited Collector freshness metadata from the validated run summary.',
+    }),
+    stageStatuses: jsonClone(writerValidation.stageStatuses),
+    writerCounts: jsonClone(writerValidation.summary.counts),
+    writerDiagnostics: {
+      count: writerValidation.diagnosticsArtifact.diagnostics.length,
+      warningCount: writerValidation.diagnosticsArtifact.diagnostics.filter((entry) => entry.status === 'warn' || entry.severity === 'warning').length,
+    },
+    promotion: {
+      status: 'promoted',
+      reason: 'Validated Collector, Normalizer, Analyst, Skeptic, and PM Writer artifacts were written before writer latest promotion.',
+    },
+  };
+}
+
+function createPmWriterInput({ runId, now, collectorResult, normalizerResult, analystResult, skepticResult }) {
+  return {
+    runId,
+    now,
+    collectorStatus: collectorResult.summary.status,
+    normalizerStatus: normalizerResult.summary.status,
+    analystStatus: analystResult.summary.status,
+    skepticStatus: skepticResult.status,
+    trendScores: analystResult.trendScores,
+    skepticChallenges: skepticResult.skepticChallenges,
+    summary: {
+      ...jsonClone(skepticResult.summary),
+      artifacts: {
+        ...jsonClone(skepticResult.summary.artifacts),
+        analystDiagnostics: analysisAnalystDiagnosticsPath(runId),
+        skepticSummary: analysisSkepticReviewPath(runId),
+        skepticDiagnostics: analysisSkepticDiagnosticsPath(runId),
+        skepticChallenges: analysisSkepticChallengedClaimsPath(runId),
+      },
+    },
+  };
+}
+
+export async function persistPmWriterRun(result, { rootDir = process.cwd() } = {}) {
+  if (!isPlainObject(result)) {
+    throw new TypeError('PM Writer persistence requires Collector, Normalizer, Analyst, Skeptic, and PM Writer results.');
+  }
+
+  const collectorValidation = validateCollectorRunForPersistence(result.collectorResult);
+  const normalizerValidation = validateNormalizerRunForPersistence(result.normalizerResult, collectorValidation);
+  const analystValidation = validateAnalystRunForPersistence(result.analystResult, normalizerValidation);
+  const skepticValidation = validateSkepticRunForPersistence(result.skepticResult, analystValidation);
+  const stageStatusesWithoutWriter = {
+    collector: collectorValidation.summary.status,
+    normalizer: normalizerValidation.summary.status,
+    analyst: analystValidation.summary.status,
+    skeptic: skepticValidation.summary.stageStatuses.skeptic,
+  };
+  const analystArtifacts = createPersistedAnalystArtifacts(analystValidation, stageStatusesWithoutWriter);
+  const skepticArtifacts = createPersistedSkepticArtifacts(skepticValidation, stageStatusesWithoutWriter);
+  const writerValidation = validatePmWriterRunForPersistence(result.pmWriterResult, {
+    collectorValidation,
+    normalizerValidation,
+    analystValidation,
+    skepticValidation,
+    analystArtifacts,
+    skepticArtifacts,
+  });
+  const selectedMemo = writerValidation.sectorMemos[0] ?? null;
+  const writerPaths = {
+    summary: pmWriterRunSummaryPath(writerValidation.runId),
+    diagnostics: pmWriterDiagnosticsPath(writerValidation.runId),
+    dailyRadarJson: pmWriterDailyRadarPath(writerValidation.runId),
+    dailyRadarMarkdown: pmWriterDailyRadarMarkdownPath(writerValidation.runId),
+    sectorMemoJson: selectedMemo ? pmWriterSectorMemoPath(writerValidation.runId, selectedMemo.marketTrendId) : null,
+    sectorMemoMarkdown: selectedMemo ? pmWriterSectorMemoMarkdownPath(writerValidation.runId, selectedMemo.marketTrendId) : null,
+    recommendationsJson: pmWriterRecommendationsPath(writerValidation.runId),
+    alertsJson: pmWriterAlertCandidatesPath(writerValidation.runId),
+    mvpExperimentsJson: pmWriterMvpExperimentsPath(writerValidation.runId),
+  };
+  const written = [];
+
+  for (const [relativePath, artifact] of collectorValidation.files.entries()) {
+    if (relativePath === VENTURE_SIGNAL_LATEST_PATH) continue;
+    written.push(await writeJsonArtifact(rootDir, relativePath, artifact));
+  }
+
+  for (const [relativePath, artifact] of normalizerValidation.files.entries()) {
+    written.push(await writeJsonArtifact(rootDir, relativePath, artifact));
+  }
+
+  for (const [relativePath, artifact] of normalizerValidation.aggregateArtifacts.entries()) {
+    written.push(await writeJsonArtifact(rootDir, relativePath, artifact));
+  }
+
+  for (const [relativePath, artifact] of analystArtifacts.files.entries()) {
+    written.push(await writeJsonArtifact(rootDir, relativePath, artifact));
+  }
+
+  for (const [relativePath, artifact] of skepticArtifacts.files.entries()) {
+    written.push(await writeJsonArtifact(rootDir, relativePath, artifact));
+  }
+
+  for (const [relativePath, artifact] of writerValidation.files.entries()) {
+    written.push(await writeJsonArtifact(rootDir, relativePath, artifact));
+  }
+  written.push(await writeTextArtifact(rootDir, pmWriterDailyRadarMarkdownPath(writerValidation.runId), writerValidation.markdown.dailyRadar));
+  for (const memo of writerValidation.sectorMemos) {
+    written.push(await writeTextArtifact(
+      rootDir,
+      pmWriterSectorMemoMarkdownPath(writerValidation.runId, memo.marketTrendId),
+      writerValidation.markdown.sectorMemos.get(memo.marketTrendId),
+    ));
+  }
+
+  let latestPromoted = false;
+  if (
+    collectorValidation.promotable
+    && normalizerValidation.promotable
+    && analystValidation.promotable
+    && skepticValidation.promotable
+    && writerValidation.promotable
+    && combinedStatus(Object.values(writerValidation.stageStatuses)) !== 'error'
+  ) {
+    const latest = createPmWriterLatestArtifact({
+      collectorValidation,
+      normalizerValidation,
+      writerValidation,
+      writerPaths,
+    });
+    written.push(await writeJsonArtifact(rootDir, VENTURE_SIGNAL_LATEST_PATH, latest));
+    latestPromoted = true;
+  }
+
+  return {
+    runId: writerValidation.runId,
+    role: PM_WRITER_ROLE,
+    stage: PM_WRITER_STAGE,
+    status: writerValidation.status,
+    stageStatuses: writerValidation.stageStatuses,
+    summaryPath: pmWriterRunSummaryPath(writerValidation.runId),
+    diagnosticsPath: pmWriterDiagnosticsPath(writerValidation.runId),
+    writerPaths,
+    selectedMemoMarketTrendId: selectedMemo?.marketTrendId ?? null,
+    latestPath: latestPromoted ? VENTURE_SIGNAL_LATEST_PATH : null,
+    latestPromoted,
+    previousLatestPreserved: !latestPromoted,
+    written,
+    summary: jsonClone(writerValidation.summary),
+    dailyRadar: jsonClone(writerValidation.dailyRadar),
+    sectorMemos: jsonClone(writerValidation.sectorMemos),
+    alertCandidates: jsonClone(writerValidation.alertCandidatesArtifact.alertCandidates ?? []),
+    diagnostics: jsonClone(writerValidation.diagnosticsArtifact.diagnostics ?? []),
+  };
+}
+
+export async function runVentureSignalWriter(options = {}) {
+  const runId = normalizeVentureRunId(options.runId ?? `writer-${Date.now()}`);
+  const now = options.now;
+  const collectorResult = runCollectorIntake({ ...options, runId });
+  const normalizerResult = normalizeCollectorBatch(normalizerInputFromCollectorResult(collectorResult, {
+    runId,
+    now,
+  }), { runId, now });
+  const analystResult = analyzeNormalizedTrends({
+    runId,
+    now,
+    marketTrends: normalizerResult.marketTrends,
+    signals: normalizerResult.signals,
+    normalizerSummaryPath: normalizerRunSummaryPath(runId),
+    normalizerDiagnosticsPath: normalizerDiagnosticsPath(runId),
+  }, { runId, now });
+  const skepticResult = reviewScoredTrends(analystResult, { runId, now });
+  const pmWriterResult = writePmWriterOutputs(createPmWriterInput({
+    runId,
+    now,
+    collectorResult,
+    normalizerResult,
+    analystResult,
+    skepticResult,
+  }), { runId, now });
+  return persistPmWriterRun({ collectorResult, normalizerResult, analystResult, skepticResult, pmWriterResult }, {
+    rootDir: options.rootDir ?? process.cwd(),
+  });
+}
+
+export const runWriter = runVentureSignalWriter;
+export const runPmWriterArtifacts = runVentureSignalWriter;
+
+function normalizerInputFromCollectorResult(collectorResult, { runId, now }) {
+  return {
+    runId,
+    collectorRunId: collectorResult.runId,
+    now,
+    sourceBatch: {
+      collectorRunId: collectorResult.runId,
+      collectorSummaryPath: collectorRunSummaryPath(collectorResult.runId),
+      collectorDiagnosticsPath: collectorDiagnosticsPath(collectorResult.runId),
+    },
+    sourceItemsArtifacts: collectorResult.sourceItemsArtifacts,
+  };
+}
+
+export async function runVentureSignalNormalizer(options = {}) {
+  const runId = normalizeVentureRunId(options.runId ?? `normalizer-${Date.now()}`);
+  const collectorResult = runCollectorIntake({ ...options, runId });
+  const normalizerResult = normalizeCollectorBatch(normalizerInputFromCollectorResult(collectorResult, {
+    runId,
+    now: options.now,
+  }), { runId, now: options.now });
+  return persistNormalizerRun(normalizerResult, {
+    rootDir: options.rootDir ?? process.cwd(),
+    collectorResult,
+  });
+}
+
+export async function runVentureSignalAnalysis(options = {}) {
+  const runId = normalizeVentureRunId(options.runId ?? `analysis-${Date.now()}`);
+  const now = options.now;
+  const collectorResult = runCollectorIntake({ ...options, runId });
+  const normalizerResult = normalizeCollectorBatch(normalizerInputFromCollectorResult(collectorResult, {
+    runId,
+    now,
+  }), { runId, now });
+  const analystResult = analyzeNormalizedTrends({
+    runId,
+    now,
+    marketTrends: normalizerResult.marketTrends,
+    signals: normalizerResult.signals,
+    normalizerSummaryPath: normalizerRunSummaryPath(runId),
+    normalizerDiagnosticsPath: normalizerDiagnosticsPath(runId),
+  }, { runId, now });
+  const skepticResult = reviewScoredTrends(analystResult, { runId, now });
+  return persistAnalysisRun({ collectorResult, normalizerResult, analystResult, skepticResult }, {
+    rootDir: options.rootDir ?? process.cwd(),
+  });
+}
+
+export async function runVentureSignalCollector(options = {}) {
+  const runId = normalizeVentureRunId(options.runId ?? `collector-${Date.now()}`);
+  const result = runCollectorIntake({ ...options, runId });
+  return persistCollectorRun(result, { rootDir: options.rootDir ?? process.cwd() });
+}
+
+export const runCollector = runVentureSignalCollector;
+export const runNormalizer = runVentureSignalNormalizer;
+export const runAnalysis = runVentureSignalAnalysis;