@kbediako/codex-orchestrator 0.1.37 → 0.2.0

package/dist/orchestrator/src/cli/run/source0.js

@@ -0,0 +1,690 @@
+import { readFile, stat } from 'node:fs/promises';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { buildContextObject } from '../rlm/context.js';
+import { isoTimestamp } from '../utils/time.js';
+const RUN_SOURCE0_SCHEMA_VERSION = 1;
+const RUN_MEMORY_OBSERVABILITY_SCHEMA_VERSION = 1;
+const RUN_SOURCE0_CONTEXT_KIND = 'context_object';
+const RUN_SOURCE0_PAYLOAD_KIND = 'run_source_0';
+const RUN_SOURCE0_CHUNK_TARGET_BYTES = 65_536;
+const RUN_SOURCE0_CHUNK_OVERLAP_BYTES = 4_096;
+const RUN_MEMORY_REPAIR_DETAIL_MARKER = 'memory-repair:';
+const INVALID_INHERITED_SOURCE0_OBJECT_ID = 'sha256:invalid-inherited-source0-descriptor';
+const INVALID_INHERITED_SOURCE0_CHUNK_ID = 'invalid';
+const SANITIZED_REJECTED_CANDIDATE_PATH_PREFIX = 'invalid-source0';
+const WINDOWS_DRIVE_ABSOLUTE_PATH_RE = /^[A-Za-z]:[\\/]/u;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function readNonEmptyString(value) {
+    if (typeof value !== 'string') {
+        return null;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+function readInteger(value) {
+    if (typeof value === 'number' && Number.isInteger(value)) {
+        return value;
+    }
+    return null;
+}
+function readRunSource0Lineage(value) {
+    if (!isRecord(value)) {
+        return null;
+    }
+    const runId = readNonEmptyString(value.run_id);
+    const taskId = readNonEmptyString(value.task_id);
+    const manifestPath = readNonEmptyString(value.manifest_path);
+    if (!runId || !taskId || !manifestPath) {
+        return null;
+    }
+    return {
+        run_id: runId,
+        task_id: taskId,
+        manifest_path: manifestPath
+    };
+}
+function readSource0Candidate(input) {
+    if (!isRecord(input)) {
+        return null;
+    }
+    if (isRecord(input.memory) && isRecord(input.memory.source_0)) {
+        return input.memory.source_0;
+    }
+    return input;
+}
+function readManifestSource0Value(input) {
+    if (!isRecord(input) ||
+        !isRecord(input.memory) ||
+        !Object.prototype.hasOwnProperty.call(input.memory, 'source_0')) {
+        return undefined;
+    }
+    return input.memory.source_0;
+}
+function buildRunSource0Payload(params) {
+    const promptPacks = Array.isArray(params.manifest.prompt_packs) ? params.manifest.prompt_packs : [];
+    const manifestPath = join(params.manifest.artifact_root, 'manifest.json');
+    return {
+        schema_version: RUN_SOURCE0_SCHEMA_VERSION,
+        kind: RUN_SOURCE0_PAYLOAD_KIND,
+        generated_at: params.manifest.updated_at,
+        run_contract: {
+            task_id: params.manifest.task_id,
+            run_id: params.manifest.run_id,
+            parent_run_id: params.manifest.parent_run_id ?? null,
+            pipeline_id: params.manifest.pipeline_id,
+            pipeline_title: params.manifest.pipeline_title
+        },
+        artifacts: {
+            manifest_path: manifestPath,
+            artifact_root: params.manifest.artifact_root,
+            log_path: params.manifest.log_path,
+            workspace_path: params.manifest.workspace_path ?? null
+        },
+        issue: {
+            provider: params.manifest.issue_provider ?? null,
+            id: params.manifest.issue_id ?? null,
+            identifier: params.manifest.issue_identifier ?? null,
+            updated_at: params.manifest.issue_updated_at ?? null
+        },
+        instructions: {
+            hash: params.manifest.instructions_hash ?? null,
+            sources: [...params.manifest.instructions_sources],
+            prompt_packs: promptPacks.map((pack) => ({
+                id: pack.id,
+                domain: pack.domain,
+                stamp: pack.stamp,
+                source_count: Array.isArray(pack.sources) ? pack.sources.length : 0,
+                experience_count: Array.isArray(pack.experiences) ? pack.experiences.length : 0
+            }))
+        }
+    };
+}
+function buildRunMemoryProvenanceDescriptor(descriptor) {
+    return {
+        pointer: descriptor.pointer,
+        object_id: descriptor.object_id,
+        dir_path: descriptor.dir_path,
+        index_path: descriptor.index_path,
+        source_path: descriptor.source_path,
+        created_at: descriptor.created_at,
+        origin: descriptor.origin,
+        inherited_from: descriptor.inherited_from
+    };
+}
+function buildRunMemorySelectedDescriptor(params) {
+    return {
+        selection: params.selection,
+        ...buildRunMemoryProvenanceDescriptor(params.descriptor)
+    };
+}
+function buildRunMemoryRejectedCandidate(params) {
+    const descriptor = buildRunMemoryProvenanceDescriptor(params.descriptor);
+    return {
+        ...descriptor,
+        dir_path: sanitizeRejectedCandidatePath(descriptor.dir_path, 'dir_path'),
+        index_path: sanitizeRejectedCandidatePath(descriptor.index_path, 'index_path'),
+        source_path: sanitizeRejectedCandidatePath(descriptor.source_path, 'source_path'),
+        reason: params.reason,
+        detail: params.detail
+    };
+}
+function sanitizeRejectedCandidatePath(candidate, field) {
+    const trimmed = candidate.trim();
+    const normalizedCandidate = trimmed.replaceAll('\\', '/');
+    if (trimmed.length === 0 ||
+        normalizedCandidate === '.' ||
+        hasInvalidPathCharacters(normalizedCandidate) ||
+        normalizedCandidate.startsWith('/') ||
+        isAbsolute(trimmed) ||
+        WINDOWS_DRIVE_ABSOLUTE_PATH_RE.test(trimmed) ||
+        normalizedCandidate.split('/').some((segment) => segment === '..')) {
+        return `${SANITIZED_REJECTED_CANDIDATE_PATH_PREFIX}/${field}`;
+    }
+    return normalizedCandidate;
+}
+function buildMalformedInheritedSource0Descriptor(params) {
+    const candidate = isRecord(params.candidate) ? params.candidate : {};
+    const fallbackDir = join(dirname(params.fallbackOrigin.manifest_path), 'memory', 'source-0');
+    const objectId = readNonEmptyString(candidate.object_id) ?? INVALID_INHERITED_SOURCE0_OBJECT_ID;
+    return {
+        schema_version: RUN_SOURCE0_SCHEMA_VERSION,
+        kind: RUN_SOURCE0_CONTEXT_KIND,
+        object_id: objectId,
+        pointer: readNonEmptyString(candidate.pointer) ??
+            buildRunSource0Pointer(objectId, INVALID_INHERITED_SOURCE0_CHUNK_ID),
+        dir_path: readNonEmptyString(candidate.dir_path) ?? fallbackDir,
+        index_path: readNonEmptyString(candidate.index_path) ?? join(fallbackDir, 'index.json'),
+        source_path: readNonEmptyString(candidate.source_path) ?? join(fallbackDir, 'source.txt'),
+        byte_length: readInteger(candidate.byte_length) ?? 0,
+        chunk_count: Math.max(1, readInteger(candidate.chunk_count) ?? 1),
+        created_at: readNonEmptyString(candidate.created_at) ?? params.fallbackCreatedAt,
+        origin: readRunSource0Lineage(candidate.origin) ?? params.fallbackOrigin,
+        inherited_from: candidate.inherited_from === null
+            ? null
+            : readRunSource0Lineage(candidate.inherited_from)
+    };
+}
+function buildRunSource0Pointer(objectId, chunkId) {
+    return `ctx:${objectId}#chunk:${chunkId}`;
+}
+function buildRunMemoryRediscovery(params) {
+    return {
+        from_pointer: params.rejected.descriptor.pointer,
+        from_object_id: params.rejected.descriptor.object_id,
+        to_pointer: params.selected.pointer,
+        to_object_id: params.selected.object_id,
+        reason: params.rejected.reason
+    };
+}
+function readAcceptedManualRepairEvents(manifest) {
+    return manifest.resume_events
+        .filter((event) => event.outcome === 'accepted' &&
+        event.reason === 'manual-resume' &&
+        typeof event.detail === 'string' &&
+        event.detail.trim().toLowerCase().startsWith(RUN_MEMORY_REPAIR_DETAIL_MARKER))
+        .map((event) => ({
+        timestamp: event.timestamp,
+        actor: event.actor,
+        reason: event.reason,
+        outcome: 'accepted',
+        detail: event.detail ?? null
+    }));
+}
+function resolveResumeLatencyMs(recordedAt, manualRepairs) {
+    const latestRepair = manualRepairs.at(-1);
+    if (!latestRepair) {
+        return null;
+    }
+    const recordedAtMs = Date.parse(recordedAt);
+    const repairAtMs = Date.parse(latestRepair.timestamp);
+    if (Number.isNaN(recordedAtMs) || Number.isNaN(repairAtMs)) {
+        return null;
+    }
+    return Math.max(0, recordedAtMs - repairAtMs);
+}
+function readRepeatedFailureStreak(manifest) {
+    const streak = manifest?.memory?.observability?.counters?.repeated_failure_streak;
+    return typeof streak === 'number' && Number.isInteger(streak) && streak >= 0 ? streak : 0;
+}
+function applyRunMemoryManualRepairState(observability, manifest, recordedAt) {
+    const manualRepairs = readAcceptedManualRepairEvents(manifest);
+    observability.recorded_at = recordedAt;
+    observability.manual_repairs = manualRepairs;
+    observability.counters.manual_repair_count = manualRepairs.length;
+    observability.counters.resume_latency_ms = resolveResumeLatencyMs(recordedAt, manualRepairs);
+}
+function buildRunMemoryObservability(params) {
+    const rejectedCandidates = params.rejectedCandidates.map((candidate) => buildRunMemoryRejectedCandidate(candidate));
+    const rediscoveredMemory = params.selection === 'fresh_rebuild' && params.rejectedCandidates[0]
+        ? buildRunMemoryRediscovery({
+            rejected: params.rejectedCandidates[0],
+            selected: params.selected
+        })
+        : null;
+    const observability = {
+        schema_version: RUN_MEMORY_OBSERVABILITY_SCHEMA_VERSION,
+        recorded_at: params.recordedAt,
+        selected_memory: buildRunMemorySelectedDescriptor({
+            descriptor: params.selected,
+            selection: params.selection
+        }),
+        rejected_candidates: rejectedCandidates,
+        rediscovered_memory: rediscoveredMemory,
+        manual_repairs: [],
+        counters: {
+            contradiction_count: params.rejectedCandidates.filter((candidate) => candidate.reason === 'provenance_contradiction').length,
+            rediscovery_count: rediscoveredMemory ? 1 : 0,
+            resume_latency_ms: null,
+            manual_repair_count: 0,
+            repeated_failure_streak: params.repeatedFailureStreak,
+            retrieval_hits: params.selection === 'inherited_reuse' ? 1 : 0,
+            retrieval_misses: params.rejectedCandidates.length > 0 ? 1 : 0
+        }
+    };
+    applyRunMemoryManualRepairState(observability, params.manifest, params.recordedAt);
+    return observability;
+}
+async function assessInheritedRunSource0Candidate(params) {
+    try {
+        resolveRunSource0Paths(params.repoRoot, params.descriptor);
+    }
+    catch (error) {
+        return {
+            descriptor: params.descriptor,
+            reason: 'provenance_contradiction',
+            detail: error?.message ?? 'invalid inherited source_0 descriptor paths'
+        };
+    }
+    const hasArtifacts = await hasRunSource0Artifacts(params.repoRoot, params.descriptor);
+    if (!hasArtifacts) {
+        return {
+            descriptor: params.descriptor,
+            reason: 'missing_artifacts',
+            detail: 'inherited source_0 artifacts are missing'
+        };
+    }
+    try {
+        const payload = await readRunSource0Payload(params.repoRoot, params.descriptor);
+        if (!payload) {
+            return {
+                descriptor: params.descriptor,
+                reason: 'provenance_contradiction',
+                detail: 'inherited source_0 payload is invalid'
+            };
+        }
+        if (payload.run_contract.run_id !== params.descriptor.origin.run_id) {
+            return {
+                descriptor: params.descriptor,
+                reason: 'provenance_contradiction',
+                detail: 'inherited source_0 payload run_id does not match descriptor origin'
+            };
+        }
+        if (payload.run_contract.task_id !== params.descriptor.origin.task_id) {
+            return {
+                descriptor: params.descriptor,
+                reason: 'provenance_contradiction',
+                detail: 'inherited source_0 payload task_id does not match descriptor origin'
+            };
+        }
+        if (payload.artifacts.manifest_path !== params.descriptor.origin.manifest_path) {
+            return {
+                descriptor: params.descriptor,
+                reason: 'provenance_contradiction',
+                detail: 'inherited source_0 payload manifest_path does not match descriptor origin'
+            };
+        }
+        const inheritedPaths = resolveRunSource0Paths(params.repoRoot, params.descriptor);
+        const contextObject = await buildContextObject({
+            source: { type: 'dir', value: inheritedPaths.dirPath },
+            targetDir: inheritedPaths.dirPath,
+            chunking: {
+                targetBytes: RUN_SOURCE0_CHUNK_TARGET_BYTES,
+                overlapBytes: RUN_SOURCE0_CHUNK_OVERLAP_BYTES,
+                strategy: 'byte'
+            }
+        });
+        validateRunSource0DescriptorAgainstArtifacts({
+            repoRoot: params.repoRoot,
+            descriptor: params.descriptor,
+            contextObject
+        });
+    }
+    catch (error) {
+        return {
+            descriptor: params.descriptor,
+            reason: 'provenance_contradiction',
+            detail: error?.message ?? 'failed to read inherited source_0 payload'
+        };
+    }
+    return null;
+}
+export function readRunSource0Descriptor(input) {
+    const candidate = readSource0Candidate(input);
+    if (!candidate) {
+        return null;
+    }
+    const schemaVersion = readInteger(candidate.schema_version);
+    const kind = readNonEmptyString(candidate.kind);
+    const objectId = readNonEmptyString(candidate.object_id);
+    const pointer = readNonEmptyString(candidate.pointer);
+    const dirPath = readNonEmptyString(candidate.dir_path);
+    const indexPath = readNonEmptyString(candidate.index_path);
+    const sourcePath = readNonEmptyString(candidate.source_path);
+    const byteLength = readInteger(candidate.byte_length);
+    const chunkCount = readInteger(candidate.chunk_count);
+    const createdAt = readNonEmptyString(candidate.created_at);
+    const origin = readRunSource0Lineage(candidate.origin);
+    const inheritedFrom = candidate.inherited_from === null ? null : readRunSource0Lineage(candidate.inherited_from);
+    if (schemaVersion === null ||
+        schemaVersion < 1 ||
+        kind !== RUN_SOURCE0_CONTEXT_KIND ||
+        !objectId ||
+        !pointer ||
+        !dirPath ||
+        !indexPath ||
+        !sourcePath ||
+        byteLength === null ||
+        byteLength < 0 ||
+        chunkCount === null ||
+        chunkCount < 1 ||
+        !createdAt ||
+        !origin ||
+        candidate.inherited_from === undefined ||
+        (candidate.inherited_from !== null && inheritedFrom === null)) {
+        return null;
+    }
+    return {
+        schema_version: schemaVersion,
+        kind: RUN_SOURCE0_CONTEXT_KIND,
+        object_id: objectId,
+        pointer,
+        dir_path: dirPath,
+        index_path: indexPath,
+        source_path: sourcePath,
+        byte_length: byteLength,
+        chunk_count: chunkCount,
+        created_at: createdAt,
+        origin,
+        inherited_from: inheritedFrom
+    };
+}
+export function resolveRunSource0Paths(repoRoot, descriptor) {
+    const resolvedRepoRoot = resolve(repoRoot);
+    return {
+        dirPath: resolveRepoRelativeSource0Path(resolvedRepoRoot, descriptor.dir_path, 'dir_path'),
+        indexPath: resolveRepoRelativeSource0Path(resolvedRepoRoot, descriptor.index_path, 'index_path'),
+        sourcePath: resolveRepoRelativeSource0Path(resolvedRepoRoot, descriptor.source_path, 'source_path')
+    };
+}
+function resolveRepoRelativeSource0Path(repoRoot, candidate, field) {
+    const normalizedCandidate = candidate.replaceAll('\\', '/');
+    if (isAbsolute(candidate) ||
+        WINDOWS_DRIVE_ABSOLUTE_PATH_RE.test(candidate) ||
+        normalizedCandidate.startsWith('/')) {
+        throw new Error(`source_0 ${field} must be repo-relative`);
+    }
+    if (hasInvalidPathCharacters(normalizedCandidate)) {
+        throw new Error(`source_0 ${field} must not contain control characters or line separators`);
+    }
+    if (normalizedCandidate.split('/').some((segment) => segment === '..')) {
+        throw new Error(`source_0 ${field} must not traverse outside the repo root`);
+    }
+    const resolvedPath = resolve(repoRoot, candidate);
+    const relativePath = relative(repoRoot, resolvedPath);
+    if (!relativePath ||
+        relativePath === '.' ||
+        isAbsolute(relativePath) ||
+        WINDOWS_DRIVE_ABSOLUTE_PATH_RE.test(relativePath) ||
+        relativePath.split(/[\\/]+/u).some((segment) => segment === '..')) {
+        throw new Error(`source_0 ${field} escapes the repo root`);
+    }
+    return resolvedPath;
+}
+function hasInvalidPathCharacters(value) {
+    return Array.from(value).some((character) => {
+        const codePoint = character.codePointAt(0) ?? 0;
+        return (codePoint < 0x20 ||
+            codePoint === 0x7f ||
+            codePoint === 0x2028 ||
+            codePoint === 0x2029);
+    });
+}
+export function buildRunSource0PromptLines(descriptor) {
+    if (!descriptor) {
+        return [];
+    }
+    const lines = [
+        'Shared source 0 anchor:',
+        `- Pointer: \`${descriptor.pointer}\``,
+        `- Object id: \`${descriptor.object_id}\``,
+        `- Context dir: \`${descriptor.dir_path}\``,
+        `- Source payload: \`${descriptor.source_path}\``,
+        `- Origin: run=\`${descriptor.origin.run_id}\`, task=\`${descriptor.origin.task_id}\`, manifest=\`${descriptor.origin.manifest_path}\``
+    ];
+    if (descriptor.inherited_from) {
+        lines.push(`- Inherited from: run=\`${descriptor.inherited_from.run_id}\`, task=\`${descriptor.inherited_from.task_id}\`, manifest=\`${descriptor.inherited_from.manifest_path}\``);
+    }
+    return lines;
+}
+export async function readRunSource0Payload(repoRoot, descriptor) {
+    const raw = await readFile(resolveRunSource0Paths(repoRoot, descriptor).sourcePath, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (!isRecord(parsed)) {
+        return null;
+    }
+    if (readInteger(parsed.schema_version) !== RUN_SOURCE0_SCHEMA_VERSION) {
+        return null;
+    }
+    if (readNonEmptyString(parsed.kind) !== RUN_SOURCE0_PAYLOAD_KIND) {
+        return null;
+    }
+    return parsed;
+}
+export async function hasRunSource0Artifacts(repoRoot, descriptor) {
+    try {
+        const paths = resolveRunSource0Paths(repoRoot, descriptor);
+        const [dirInfo, indexInfo, sourceInfo] = await Promise.all([
+            stat(paths.dirPath),
+            stat(paths.indexPath),
+            stat(paths.sourcePath)
+        ]);
+        return dirInfo.isDirectory() && indexInfo.isFile() && sourceInfo.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function buildRunSource0Descriptor(params) {
+    const firstChunk = params.contextObject.index.chunks[0];
+    if (!firstChunk) {
+        throw new Error('source_0 context object must contain at least one chunk');
+    }
+    return {
+        schema_version: RUN_SOURCE0_SCHEMA_VERSION,
+        kind: RUN_SOURCE0_CONTEXT_KIND,
+        object_id: params.contextObject.index.object_id,
+        pointer: buildRunSource0Pointer(params.contextObject.index.object_id, firstChunk.id),
+        dir_path: relative(params.repoRoot, params.runDir),
+        index_path: relative(params.repoRoot, params.contextObject.indexPath),
+        source_path: relative(params.repoRoot, params.contextObject.sourcePath),
+        byte_length: params.contextObject.index.source.byte_length,
+        chunk_count: params.contextObject.index.chunks.length,
+        created_at: params.contextObject.index.created_at,
+        origin: params.origin,
+        inherited_from: params.inheritedFrom
+    };
+}
+function validateRunSource0DescriptorAgainstArtifacts(params) {
+    const firstChunk = params.contextObject.index.chunks[0];
+    if (!firstChunk) {
+        throw new Error('source_0 context object must contain at least one chunk');
+    }
+    const expectedPointer = buildRunSource0Pointer(params.contextObject.index.object_id, firstChunk.id);
+    const expectedDirPath = relative(params.repoRoot, params.contextObject.dir);
+    const expectedIndexPath = relative(params.repoRoot, params.contextObject.indexPath);
+    const expectedSourcePath = relative(params.repoRoot, params.contextObject.sourcePath);
+    if (params.descriptor.object_id !== params.contextObject.index.object_id) {
+        throw new Error('inherited source_0 descriptor object_id does not match artifacts');
+    }
+    if (params.descriptor.pointer !== expectedPointer) {
+        throw new Error('inherited source_0 descriptor pointer does not match artifacts');
+    }
+    if (params.descriptor.dir_path !== expectedDirPath) {
+        throw new Error('inherited source_0 descriptor dir_path does not match artifacts');
+    }
+    if (params.descriptor.index_path !== expectedIndexPath) {
+        throw new Error('inherited source_0 descriptor index_path does not match artifacts');
+    }
+    if (params.descriptor.source_path !== expectedSourcePath) {
+        throw new Error('inherited source_0 descriptor source_path does not match artifacts');
+    }
+    if (params.descriptor.byte_length !== params.contextObject.index.source.byte_length) {
+        throw new Error('inherited source_0 descriptor byte_length does not match artifacts');
+    }
+    if (params.descriptor.chunk_count !== params.contextObject.index.chunks.length) {
+        throw new Error('inherited source_0 descriptor chunk_count does not match artifacts');
+    }
+    if (params.descriptor.created_at !== params.contextObject.index.created_at) {
+        throw new Error('inherited source_0 descriptor created_at does not match artifacts');
+    }
+}
+function buildCurrentRunLineage(manifest) {
+    return {
+        run_id: manifest.run_id,
+        task_id: manifest.task_id,
+        manifest_path: join(manifest.artifact_root, 'manifest.json')
+    };
+}
+async function materializeFreshRunSource0(params) {
+    const payload = buildRunSource0Payload({
+        manifest: params.manifest
+    });
+    const contextObject = await buildContextObject({
+        source: {
+            type: 'text',
+            value: `${JSON.stringify(payload, null, 2)}\n`
+        },
+        targetDir: params.targetDir,
+        chunking: {
+            targetBytes: RUN_SOURCE0_CHUNK_TARGET_BYTES,
+            overlapBytes: RUN_SOURCE0_CHUNK_OVERLAP_BYTES,
+            strategy: 'byte'
+        }
+    });
+    return {
+        source_0: buildRunSource0Descriptor({
+            repoRoot: params.env.repoRoot,
+            runDir: params.targetDir,
+            contextObject,
+            origin: buildCurrentRunLineage(params.manifest),
+            inheritedFrom: params.inheritedFrom
+        })
+    };
+}
+export async function materializeRunSource0(params) {
+    const targetDir = join(params.paths.runDir, 'memory', 'source-0');
+    const inheritedSource0Value = params.inheritedFrom
+        ? readManifestSource0Value(params.inheritedFrom.manifest)
+        : undefined;
+    const inheritedDescriptor = params.inheritedFrom
+        ? readRunSource0Descriptor(params.inheritedFrom.manifest)
+        : null;
+    const inheritedLineage = params.inheritedFrom
+        ? buildCurrentRunLineage(params.inheritedFrom.manifest)
+        : null;
+    const recordedAt = isoTimestamp();
+    if (params.inheritedFrom &&
+        inheritedLineage &&
+        inheritedSource0Value !== undefined &&
+        !inheritedDescriptor) {
+        const fresh = await materializeFreshRunSource0({
+            env: params.env,
+            paths: params.paths,
+            manifest: params.manifest,
+            targetDir,
+            inheritedFrom: inheritedLineage
+        });
+        return {
+            source_0: fresh.source_0,
+            observability: buildRunMemoryObservability({
+                manifest: params.manifest,
+                recordedAt,
+                selected: fresh.source_0,
+                selection: 'fresh_rebuild',
+                rejectedCandidates: [
+                    {
+                        descriptor: buildMalformedInheritedSource0Descriptor({
+                            candidate: inheritedSource0Value,
+                            fallbackOrigin: inheritedLineage,
+                            fallbackCreatedAt: params.inheritedFrom.manifest.updated_at
+                        }),
+                        reason: 'provenance_contradiction',
+                        detail: 'inherited source_0 descriptor is invalid'
+                    }
+                ],
+                repeatedFailureStreak: readRepeatedFailureStreak(params.inheritedFrom.manifest) + 1
+            })
+        };
+    }
+    if (inheritedDescriptor) {
+        let rejectedCandidate = await assessInheritedRunSource0Candidate({
+            repoRoot: params.env.repoRoot,
+            descriptor: inheritedDescriptor
+        });
+        if (!rejectedCandidate) {
+            try {
+                const inheritedPaths = resolveRunSource0Paths(params.env.repoRoot, inheritedDescriptor);
+                const contextObject = await buildContextObject({
+                    source: { type: 'dir', value: inheritedPaths.dirPath },
+                    targetDir,
+                    chunking: {
+                        targetBytes: RUN_SOURCE0_CHUNK_TARGET_BYTES,
+                        overlapBytes: RUN_SOURCE0_CHUNK_OVERLAP_BYTES,
+                        strategy: 'byte'
+                    }
+                });
+                const source0 = buildRunSource0Descriptor({
+                    repoRoot: params.env.repoRoot,
+                    runDir: targetDir,
+                    contextObject,
+                    origin: inheritedDescriptor.origin,
+                    inheritedFrom: inheritedLineage
+                });
+                return {
+                    source_0: source0,
+                    observability: buildRunMemoryObservability({
+                        manifest: params.manifest,
+                        recordedAt,
+                        selected: source0,
+                        selection: 'inherited_reuse',
+                        rejectedCandidates: [],
+                        repeatedFailureStreak: 0
+                    })
+                };
+            }
+            catch (error) {
+                rejectedCandidate = {
+                    descriptor: inheritedDescriptor,
+                    reason: 'provenance_contradiction',
+                    detail: error?.message ?? 'failed to materialize inherited source_0 context'
+                };
+            }
+        }
+        const fresh = await materializeFreshRunSource0({
+            env: params.env,
+            paths: params.paths,
+            manifest: params.manifest,
+            targetDir,
+            inheritedFrom: inheritedLineage
+        });
+        return {
+            source_0: fresh.source_0,
+            observability: buildRunMemoryObservability({
+                manifest: params.manifest,
+                recordedAt,
+                selected: fresh.source_0,
+                selection: 'fresh_rebuild',
+                rejectedCandidates: [rejectedCandidate],
+                repeatedFailureStreak: readRepeatedFailureStreak(params.inheritedFrom?.manifest) + 1
+            })
+        };
+    }
+    const fresh = await materializeFreshRunSource0({
+        env: params.env,
+        paths: params.paths,
+        manifest: params.manifest,
+        targetDir,
+        inheritedFrom: null
+    });
+    return {
+        source_0: fresh.source_0,
+        observability: buildRunMemoryObservability({
+            manifest: params.manifest,
+            recordedAt,
+            selected: fresh.source_0,
+            selection: 'root',
+            rejectedCandidates: [],
+            repeatedFailureStreak: 0
+        })
+    };
+}
+export function refreshRunMemoryObservability(manifest, recordedAt = isoTimestamp()) {
+    const observability = manifest.memory?.observability;
+    if (!observability) {
+        return false;
+    }
+    applyRunMemoryManualRepairState(observability, manifest, recordedAt);
+    return true;
+}
+export function buildRunMemoryObservabilityMetrics(observability) {
+    if (!observability) {
+        return undefined;
+    }
+    return {
+        recorded_at: observability.recorded_at,
+        selected_memory: observability.selected_memory,
+        counters: observability.counters
+    };
+}