@iowarp/clio-coder 0.3.3 → 0.3.6

package/src/domains/evidence/types.ts

@@ -3,6 +3,7 @@ import type { RunPersonaOverride, RunPipelineProvenance, RunReceiptAutonomyEnfor
 import type { EvalCommandPhase, EvalFailureClass, EvalRunRecord } from "../eval/index.js";
 import type { ProtectedArtifact } from "../safety/protected-artifacts.js";
 import type { RunEscalationCounts } from "./provenance.js";
+import type { CanonicalTrustStatus } from "./trust-status.js";
 
 export const EVIDENCE_VERSION = 1;
 
@@ -131,13 +132,38 @@ export interface EvidenceBuildResult {
 	directory: string;
 	overview: EvidenceOverview;
 	findings: EvidenceFinding[];
+	trustStatus: EvidenceTrustStatusFile;
 }
 
 export interface EvidenceInspectable {
 	overview: EvidenceOverview;
 	findings: EvidenceFinding[];
+	trustStatus: EvidenceTrustStatusView;
 }
 
+export interface EvidenceRunTrustStatus {
+	runId: string;
+	status: CanonicalTrustStatus;
+}
+
+/** Canonical per-run projection persisted by current evidence builders. */
+export interface EvidenceTrustStatusFile {
+	version: 1;
+	evidenceId: string;
+	projection: "canonical";
+	runs: EvidenceRunTrustStatus[];
+}
+
+/** Explicit compatibility result for a bundle built before the projection existed. */
+export interface HistoricalEvidenceTrustStatus {
+	version: 1;
+	evidenceId: string;
+	projection: "historical_format";
+	runs: [];
+}
+
+export type EvidenceTrustStatusView = EvidenceTrustStatusFile | HistoricalEvidenceTrustStatus;
+
 export interface EvidenceRunSource {
 	envelope: RunEnvelope;
 	receipt: RunReceipt | null;

package/src/domains/memory/index.ts

@@ -6,6 +6,20 @@ export {
 	rejectMemoryRecord,
 	selectApprovedMemory,
 } from "./operations.js";
+export {
+	applyScopeIdentity,
+	MEMORY_PROMOTION_SCOPES,
+	type MemoryPromotionScope,
+	type MemoryPromotionSource,
+	type MemoryPromotionSourceRedaction,
+	type MemoryScopeSelection,
+	memoryAgentIdentity,
+	memoryRecordFromPromotion,
+	memoryRuntimeIdentity,
+	memoryScopeIdentityKey,
+	proposeMemoryPromotion,
+	validateMemoryScopeSelection,
+} from "./promotion.js";
 export {
 	buildMemoryPromptSection,
 	MEMORY_PROMPT_DEFAULT_MAX_ITEMS,
@@ -46,7 +60,9 @@ export {
 	type TaskMemorySnapshot,
 } from "./task-bank.js";
 export {
+	type LegacyTaskMemoryHandoffSnapshot,
 	parseTaskMemoryHandoffSnapshot,
+	type ReviewedTaskMemoryHandoffSnapshot,
 	readNewestTaskMemoryHandoff,
 	renderTaskMemoryHandoffSnapshot,
 	renderTaskMemoryHandoffSource,
@@ -57,9 +73,11 @@ export {
 	type TaskMemoryHandoffArtifact,
 	type TaskMemoryHandoffEntry,
 	type TaskMemoryHandoffOffer,
+	type TaskMemoryHandoffRedaction,
 	type TaskMemoryHandoffSeedOutcome,
 	type TaskMemoryHandoffSeedResult,
 	type TaskMemoryHandoffSnapshot,
+	type TaskMemoryHandoffSourceProvenance,
 	taskMemoryHandoffSeedOffer,
 	taskMemoryHandoffSnapshot,
 } from "./task-memory-handoff.js";
@@ -112,12 +130,16 @@ export {
 	taskMemoryTracePath,
 } from "./task-memory-trace.js";
 export type {
+	MemoryAgentIdentity,
+	MemoryPromotionRedaction,
 	MemoryProposalResult,
 	MemoryPruneResult,
 	MemoryRecord,
+	MemoryRecordProvenance,
 	MemoryRecordValidationResult,
 	MemoryRepositoryIdentity,
 	MemoryRetrievalOptions,
+	MemoryRuntimeIdentity,
 	MemoryScope,
 	MemoryStatus,
 	MemoryStoreFile,

package/src/domains/memory/operations.ts

@@ -2,7 +2,13 @@ import { isAbsolute } from "node:path";
 import { canonicalizeExistingPath } from "../../core/path-canonical.js";
 import { ceilChars } from "../session/context-accounting.js";
 import { pruneStaleMemoryRecords, sortMemoryRecords, updateMemoryRecord } from "./store.js";
-import type { MemoryRecord, MemoryRepositoryIdentity, MemoryRetrievalOptions } from "./types.js";
+import type {
+	MemoryAgentIdentity,
+	MemoryRecord,
+	MemoryRepositoryIdentity,
+	MemoryRetrievalOptions,
+	MemoryRuntimeIdentity,
+} from "./types.js";
 
 export async function approveMemoryRecord(
 	dataDir: string,
@@ -31,12 +37,16 @@ export function selectApprovedMemory(
 	if (options.tokenBudget <= 0) return [];
 	const allowedScopes = options.scopes === undefined ? null : new Set(options.scopes);
 	const activeRepository = canonicalActiveRepository(options.activeRepository);
+	const activeRuntime = validActiveNamedIdentity(options.activeRuntime, "runtime");
+	const activeAgent = validActiveNamedIdentity(options.activeAgent, "agent");
 	const candidates = sortMemoryRecords(records)
 		.filter((record) => record.approved)
 		.filter((record) => record.evidenceRefs.length > 0)
 		.filter((record) => record.regressions === undefined || record.regressions.length === 0)
 		.filter((record) => allowedScopes === null || allowedScopes.has(record.scope))
 		.filter((record) => repositoryApplies(record, activeRepository))
+		.filter((record) => runtimeApplies(record, activeRuntime))
+		.filter((record) => agentApplies(record, activeAgent))
 		.sort(compareRetrievalPriority);
 	const selected: MemoryRecord[] = [];
 	let spent = 0;
@@ -55,6 +65,8 @@ export function estimateMemoryTokens(record: MemoryRecord): number {
 		record.key,
 		record.lesson,
 		...(record.repository === undefined ? [] : [record.repository.kind, record.repository.key]),
+		...(record.runtime === undefined ? [] : [record.runtime.kind, record.runtime.key]),
+		...(record.agent === undefined ? [] : [record.agent.kind, record.agent.key]),
 		...record.evidenceRefs,
 		...record.appliesWhen,
 		...record.avoidWhen,
@@ -80,6 +92,21 @@ function cloneRecord(record: MemoryRecord): MemoryRecord {
 	if (record.regressions !== undefined) next.regressions = [...record.regressions];
 	if (record.rejectedAt !== undefined) next.rejectedAt = record.rejectedAt;
 	if (record.repository !== undefined) next.repository = { ...record.repository };
+	if (record.runtime !== undefined) next.runtime = { ...record.runtime };
+	if (record.agent !== undefined) next.agent = { ...record.agent };
+	if (record.provenance !== undefined) {
+		next.provenance = {
+			...record.provenance,
+			...(record.provenance.redaction === undefined
+				? {}
+				: {
+						redaction: {
+							...record.provenance.redaction,
+							sourceFields: [...record.provenance.redaction.sourceFields],
+						},
+					}),
+		};
+	}
 	return next;
 }
 
@@ -115,6 +142,36 @@ function repositoryApplies(record: MemoryRecord, activeRepository: MemoryReposit
 	return record.repository.kind === activeRepository.kind && record.repository.key === activeRepository.key;
 }
 
+function runtimeApplies(record: MemoryRecord, activeRuntime: MemoryRuntimeIdentity | null): boolean {
+	if (record.scope !== "runtime") return true;
+	if (activeRuntime === null || record.runtime === undefined) return false;
+	return record.runtime.kind === activeRuntime.kind && record.runtime.key === activeRuntime.key;
+}
+
+function agentApplies(record: MemoryRecord, activeAgent: MemoryAgentIdentity | null): boolean {
+	if (record.scope !== "agent") return true;
+	if (activeAgent === null || record.agent === undefined) return false;
+	return record.agent.kind === activeAgent.kind && record.agent.key === activeAgent.key;
+}
+
+function validActiveNamedIdentity<T extends "runtime" | "agent">(
+	identity: { kind: T; key: string } | null | undefined,
+	kind: T,
+): { kind: T; key: string } | null {
+	if (
+		identity === null ||
+		identity === undefined ||
+		identity.kind !== kind ||
+		identity.key.length === 0 ||
+		identity.key.length > 256 ||
+		identity.key.trim() !== identity.key ||
+		/[\0\r\n\t ]/u.test(identity.key)
+	) {
+		return null;
+	}
+	return { kind, key: identity.key };
+}
+
 function isUsableAbsoluteRepositoryPath(value: string): boolean {
 	return value.length > 0 && !/[\0\r\n]/u.test(value) && isAbsolute(value);
 }

package/src/domains/memory/promotion.ts

@@ -0,0 +1,281 @@
+import { createHash } from "node:crypto";
+import { createRedactionTally, redactSecretsText } from "../evidence/redact.js";
+import { canonicalMemoryRepositoryIdentity } from "./operations.js";
+import { loadMemoryRecords, upsertMemoryRecord } from "./store.js";
+import type { TaskMemoryEntry, TaskMemoryRenderableClass } from "./task-bank.js";
+import type {
+	MemoryAgentIdentity,
+	MemoryProposalResult,
+	MemoryRecord,
+	MemoryRepositoryIdentity,
+	MemoryRuntimeIdentity,
+} from "./types.js";
+import { validateMemoryRecord } from "./validate.js";
+
+export const MEMORY_PROMOTION_SCOPES = ["repo", "global", "runtime", "agent"] as const;
+export type MemoryPromotionScope = (typeof MEMORY_PROMOTION_SCOPES)[number];
+
+export type MemoryScopeSelection =
+	| { scope: "repo"; repository: MemoryRepositoryIdentity }
+	| { scope: "global"; acknowledgeGlobal: true }
+	| { scope: "runtime"; runtime: MemoryRuntimeIdentity }
+	| { scope: "agent"; agent: MemoryAgentIdentity };
+
+export interface MemoryPromotionSourceRedaction {
+	replacementCount: number;
+	sourceFields: ReadonlyArray<string>;
+}
+
+export interface MemoryPromotionSource {
+	kind: "task-bank-entry" | "handoff-snapshot";
+	sessionId: string;
+	evidenceRefs: ReadonlyArray<string>;
+	entry: TaskMemoryEntry;
+	runtimeIds?: ReadonlyArray<string>;
+	agentIds?: ReadonlyArray<string>;
+	redaction?: MemoryPromotionSourceRedaction;
+}
+
+interface ScopeSourceIdentities {
+	runtimeIds?: ReadonlyArray<string>;
+	agentIds?: ReadonlyArray<string>;
+}
+
+/**
+ * Validate an operator-selected scope without inferring or widening it.
+ * Runtime and agent scopes must name identities carried by the source.
+ */
+export function validateMemoryScopeSelection(
+	selection: MemoryScopeSelection,
+	source: ScopeSourceIdentities,
+): MemoryScopeSelection {
+	switch (selection.scope) {
+		case "repo": {
+			const repository = canonicalMemoryRepositoryIdentity(selection.repository.key);
+			if (
+				selection.repository.kind !== "canonical-path" ||
+				repository === null ||
+				repository.key !== selection.repository.key
+			) {
+				throw new Error("repo scope requires an existing canonical absolute repository identity");
+			}
+			return { scope: "repo", repository };
+		}
+		case "global":
+			if (selection.acknowledgeGlobal !== true) {
+				throw new Error("global scope requires a separate operator acknowledgement");
+			}
+			return selection;
+		case "runtime": {
+			const runtime = normalizeNamedIdentity(selection.runtime, "runtime");
+			if (!(source.runtimeIds ?? []).includes(runtime.key)) {
+				throw new Error(`runtime identity '${runtime.key}' does not match the promotion source`);
+			}
+			return { scope: "runtime", runtime };
+		}
+		case "agent": {
+			const agent = normalizeNamedIdentity(selection.agent, "agent");
+			if (!(source.agentIds ?? []).includes(agent.key)) {
+				throw new Error(`agent identity '${agent.key}' does not match the promotion source`);
+			}
+			return { scope: "agent", agent };
+		}
+	}
+}
+
+export function memoryRuntimeIdentity(key: string): MemoryRuntimeIdentity {
+	return normalizeNamedIdentity({ kind: "runtime", key }, "runtime");
+}
+
+export function memoryAgentIdentity(key: string): MemoryAgentIdentity {
+	return normalizeNamedIdentity({ kind: "agent", key }, "agent");
+}
+
+/** Create one reviewable proposal from a selected non-private task-bank entry. */
+export async function proposeMemoryPromotion(
+	dataDir: string,
+	source: MemoryPromotionSource,
+	selection: MemoryScopeSelection,
+	now: Date = new Date(),
+): Promise<MemoryProposalResult> {
+	validatePromotionSource(source);
+	const validatedScope = validateMemoryScopeSelection(selection, {
+		runtimeIds: source.runtimeIds ?? [],
+		agentIds: source.agentIds ?? [],
+	});
+	const record = memoryRecordFromPromotion(source, validatedScope, now);
+	const existing = (await loadMemoryRecords(dataDir)).find((candidate) => candidate.id === record.id);
+	if (existing !== undefined) return { record: existing, created: false };
+	await upsertMemoryRecord(dataDir, record);
+	return { record, created: true };
+}
+
+export function memoryRecordFromPromotion(
+	source: MemoryPromotionSource,
+	selection: MemoryScopeSelection,
+	now: Date = new Date(),
+): MemoryRecord {
+	validatePromotionSource(source);
+	const entryKind = source.entry.kind;
+	if (entryKind === "status") throw new Error("private task-memory status cannot be promoted");
+	const validatedScope = validateMemoryScopeSelection(selection, {
+		runtimeIds: source.runtimeIds ?? [],
+		agentIds: source.agentIds ?? [],
+	});
+	const tally = createRedactionTally();
+	const lesson = redactPromotionText(source.entry.content, tally).replace(/\s+/gu, " ").trim();
+	const sourceFields = new Set(source.redaction?.sourceFields ?? []);
+	if (lesson !== source.entry.content) sourceFields.add("content");
+	const replacementCount = (source.redaction?.replacementCount ?? 0) + tally.count;
+	const scopeKey = memoryScopeIdentityKey(validatedScope);
+	const record: MemoryRecord = {
+		id: promotedMemoryId({
+			sourceKind: source.kind,
+			sessionId: source.sessionId,
+			entryId: source.entry.id,
+			entryKind,
+			evidenceRefs: uniqueStrings(source.evidenceRefs),
+			lesson,
+			scopeKey,
+		}),
+		scope: validatedScope.scope,
+		key: `promotion:${source.kind}:${source.sessionId}:${source.entry.id}`,
+		lesson,
+		evidenceRefs: uniqueStrings(source.evidenceRefs),
+		appliesWhen: scopeApplicability(validatedScope),
+		avoidWhen: [],
+		confidence: 0.6,
+		createdAt: now.toISOString(),
+		approved: false,
+		provenance: {
+			sourceKind: source.kind,
+			sourceSessionId: source.sessionId,
+			sourceEntryId: source.entry.id,
+			sourceEntryKind: entryKind,
+			sourceEntryCreatedAt: source.entry.createdAt,
+			sourceEntryLastTouchedAt: source.entry.lastTouchedAt,
+			redaction: {
+				appliedBeforePersistence: true,
+				replacementCount,
+				sourceFields: [...sourceFields].sort(compareStrings),
+			},
+		},
+	};
+	applyScopeIdentity(record, validatedScope);
+	const validated = validateMemoryRecord(record);
+	if (!validated.valid) {
+		throw new Error(
+			`promoted memory record invalid: ${validated.issues.map((issue) => `${issue.path}: ${issue.message}`).join("; ")}`,
+		);
+	}
+	return validated.record;
+}
+
+export function applyScopeIdentity(record: MemoryRecord, selection: MemoryScopeSelection): void {
+	if (selection.scope === "repo") record.repository = { ...selection.repository };
+	if (selection.scope === "runtime") record.runtime = { ...selection.runtime };
+	if (selection.scope === "agent") record.agent = { ...selection.agent };
+}
+
+export function memoryScopeIdentityKey(selection: MemoryScopeSelection): string {
+	switch (selection.scope) {
+		case "repo":
+			return `repo:${selection.repository.kind}:${selection.repository.key}`;
+		case "global":
+			return "global:acknowledged";
+		case "runtime":
+			return `runtime:${selection.runtime.key}`;
+		case "agent":
+			return `agent:${selection.agent.key}`;
+	}
+}
+
+function validatePromotionSource(source: MemoryPromotionSource): void {
+	if (!validSourceValue(source.sessionId)) throw new Error("promotion requires a valid source session id");
+	if (source.evidenceRefs.length === 0 || source.evidenceRefs.some((value) => !validSourceValue(value))) {
+		throw new Error("promotion requires at least one valid source evidence ref");
+	}
+	if (source.entry.kind === "status") throw new Error("private task-memory status cannot be promoted");
+	if (source.entry.kind !== "knowledge" && source.entry.kind !== "procedural") {
+		throw new Error("promotion requires a knowledge or procedural task-memory entry");
+	}
+	if (!validSourceValue(source.entry.id) || source.entry.content.trim().length === 0) {
+		throw new Error("promotion requires a valid task-memory entry");
+	}
+	for (const runtimeId of source.runtimeIds ?? []) memoryRuntimeIdentity(runtimeId);
+	for (const agentId of source.agentIds ?? []) memoryAgentIdentity(agentId);
+	if (source.redaction !== undefined) {
+		if (!Number.isInteger(source.redaction.replacementCount) || source.redaction.replacementCount < 0) {
+			throw new Error("promotion source redaction count must be a non-negative integer");
+		}
+		if (source.redaction.sourceFields.some((field) => !validSourceValue(field))) {
+			throw new Error("promotion source redaction fields must be valid non-empty strings");
+		}
+	}
+}
+
+function normalizeNamedIdentity<T extends "runtime" | "agent">(
+	identity: { kind: T; key: string },
+	kind: T,
+): { kind: T; key: string } {
+	if (identity.kind !== kind || !validNamedIdentityKey(identity.key)) {
+		throw new Error(`${kind} scope requires a valid ${kind} identity`);
+	}
+	return { kind, key: identity.key };
+}
+
+function validNamedIdentityKey(value: string): boolean {
+	return value.length > 0 && value.length <= 256 && value.trim() === value && !/[\0\r\n\t ]/u.test(value);
+}
+
+function validSourceValue(value: string): boolean {
+	return value.length > 0 && value.length <= 1_024 && value.trim() === value && !/[\0\r\n]/u.test(value);
+}
+
+function scopeApplicability(selection: MemoryScopeSelection): string[] {
+	switch (selection.scope) {
+		case "repo":
+			return [`repository:${selection.repository.kind}:${selection.repository.key}`];
+		case "global":
+			return [];
+		case "runtime":
+			return [`runtime:${selection.runtime.key}`];
+		case "agent":
+			return [`agent:${selection.agent.key}`];
+	}
+}
+
+function promotedMemoryId(value: {
+	sourceKind: MemoryPromotionSource["kind"];
+	sessionId: string;
+	entryId: string;
+	entryKind: TaskMemoryRenderableClass;
+	evidenceRefs: string[];
+	lesson: string;
+	scopeKey: string;
+}): string {
+	const digest = createHash("sha256").update(JSON.stringify(value), "utf8").digest("hex").slice(0, 16);
+	return `mem-${digest}`;
+}
+
+function uniqueStrings(values: ReadonlyArray<string>): string[] {
+	return [...new Set(values)].sort(compareStrings);
+}
+
+function redactPromotionText(text: string, tally: ReturnType<typeof createRedactionTally>): string {
+	const markers: string[] = [];
+	const masked = text.replace(/\[redacted:[a-z-]+\]/gu, (marker) => {
+		const token = `\uE000${String.fromCharCode(0xe100 + markers.length)}`;
+		markers.push(marker);
+		return token;
+	});
+	let redacted = redactSecretsText(masked, tally);
+	for (let index = 0; index < markers.length; index += 1) {
+		redacted = redacted.replaceAll(`\uE000${String.fromCharCode(0xe100 + index)}`, markers[index] ?? "");
+	}
+	return redacted;
+}
+
+function compareStrings(left: string, right: string): number {
+	return left < right ? -1 : left > right ? 1 : 0;
+}

package/src/domains/memory/prompt-section.ts

@@ -1,5 +1,11 @@
 import { estimateMemoryTokens, selectApprovedMemory } from "./operations.js";
-import type { MemoryRecord, MemoryRepositoryIdentity, MemoryScope } from "./types.js";
+import type {
+	MemoryAgentIdentity,
+	MemoryRecord,
+	MemoryRepositoryIdentity,
+	MemoryRuntimeIdentity,
+	MemoryScope,
+} from "./types.js";
 
 export const MEMORY_PROMPT_DEFAULT_TOKEN_BUDGET = 400;
 export const MEMORY_PROMPT_DEFAULT_MAX_ITEMS = 5;
@@ -20,6 +26,10 @@ export interface MemoryPromptOptions {
 	maxItems?: number;
 	/** Missing or unknown identity leaves global memory eligible but excludes repo memory. */
 	activeRepository?: MemoryRepositoryIdentity | null;
+	/** Missing or unknown identity excludes runtime-scoped memory. */
+	activeRuntime?: MemoryRuntimeIdentity | null;
+	/** Missing or unknown identity excludes agent-scoped memory. */
+	activeAgent?: MemoryAgentIdentity | null;
 }
 
 /**
@@ -40,6 +50,8 @@ export function selectMemoryForPrompt(
 		scopes,
 		tokenBudget,
 		activeRepository: options.activeRepository ?? null,
+		activeRuntime: options.activeRuntime ?? null,
+		activeAgent: options.activeAgent ?? null,
 	});
 	return selected.slice(0, maxItems);
 }
@@ -67,11 +79,19 @@ export function renderMemoryPromptSection(records: ReadonlyArray<MemoryRecord>):
 }
 
 function renderApplicability(record: MemoryRecord): string {
-	if (record.scope !== "repo") return `scope=${record.scope}`;
-	if (record.repository !== undefined) {
-		return `scope=repo, repository=${JSON.stringify(`${record.repository.kind}:${record.repository.key}`)}`;
+	if (record.scope === "repo") {
+		if (record.repository !== undefined) {
+			return `scope=repo, repository=${JSON.stringify(`${record.repository.kind}:${record.repository.key}`)}`;
+		}
+		return "scope=repo, repository=unknown";
 	}
-	return "scope=repo, repository=unknown";
+	if (record.scope === "runtime") {
+		return `scope=runtime, runtime=${JSON.stringify(record.runtime?.key ?? "unknown")}`;
+	}
+	if (record.scope === "agent") {
+		return `scope=agent, agent=${JSON.stringify(record.agent?.key ?? "unknown")}`;
+	}
+	return `scope=${record.scope}`;
 }
 
 /** Convenience for callers that want a single end-to-end build step. */

package/src/domains/memory/proposal.ts

@@ -2,8 +2,15 @@ import { createHash } from "node:crypto";
 import type { EvidenceFinding, EvidenceOverview, EvidenceTag } from "../evidence/index.js";
 import { inspectEvidence } from "../evidence/index.js";
 import { canonicalMemoryRepositoryIdentity } from "./operations.js";
+import {
+	applyScopeIdentity,
+	type MemoryScopeSelection,
+	memoryScopeIdentityKey,
+	validateMemoryScopeSelection,
+} from "./promotion.js";
 import { loadMemoryRecords, upsertMemoryRecord } from "./store.js";
 import type { MemoryProposalResult, MemoryRecord, MemoryRepositoryIdentity, MemoryScope } from "./types.js";
+import { validateMemoryRecord } from "./validate.js";
 
 const LESSON_MAX_CHARS = 240;
 const APPLY_MAX_CHARS = 160;
@@ -23,12 +30,16 @@ const TAG_PRIORITY = [
 	"unknown",
 ] as const satisfies ReadonlyArray<EvidenceTag>;
 
-export async function proposeMemoryFromEvidence(dataDir: string, evidenceId: string): Promise<MemoryProposalResult> {
+export async function proposeMemoryFromEvidence(
+	dataDir: string,
+	evidenceId: string,
+	selection?: MemoryScopeSelection,
+): Promise<MemoryProposalResult> {
 	const evidence = await inspectEvidence(dataDir, evidenceId);
-	const existing = (await loadMemoryRecords(dataDir)).find((record) => record.id === memoryIdFromEvidence(evidenceId));
+	const record = memoryRecordFromEvidence(evidence.overview, evidence.findings, selection);
+	const existing = (await loadMemoryRecords(dataDir)).find((candidate) => candidate.id === record.id);
 	if (existing !== undefined) return { record: existing, created: false };
 
-	const record = memoryRecordFromEvidence(evidence.overview, evidence.findings);
 	await upsertMemoryRecord(dataDir, record);
 	return { record, created: true };
 }
@@ -41,13 +52,24 @@ export function memoryIdFromEvidence(evidenceId: string): string {
 export function memoryRecordFromEvidence(
 	overview: EvidenceOverview,
 	findings: ReadonlyArray<EvidenceFinding>,
+	selection?: MemoryScopeSelection,
 ): MemoryRecord {
 	const tags = overview.tags;
 	const primaryTag = primaryEvidenceTag(tags);
 	const repository = inferRepository(overview);
-	const scope = inferScope(overview, repository);
+	const validatedSelection =
+		selection === undefined
+			? undefined
+			: validateMemoryScopeSelection(selection, {
+					runtimeIds: overview.runtimeIds,
+					agentIds: overview.agentIds,
+				});
+	const scope = validatedSelection?.scope ?? inferScope(overview, repository);
 	const record: MemoryRecord = {
-		id: memoryIdFromEvidence(overview.evidenceId),
+		id:
+			validatedSelection === undefined
+				? memoryIdFromEvidence(overview.evidenceId)
+				: memoryIdFromEvidenceScope(overview.evidenceId, memoryScopeIdentityKey(validatedSelection)),
 		scope,
 		key: `evidence:${overview.evidenceId}`,
 		lesson: truncateText(buildLesson(overview, findings, primaryTag), LESSON_MAX_CHARS),
@@ -57,9 +79,31 @@ export function memoryRecordFromEvidence(
 		confidence: confidenceForEvidence(overview, findings),
 		createdAt: overview.generatedAt,
 		approved: false,
+		provenance: {
+			sourceKind: "evidence",
+			evidenceId: overview.evidenceId,
+			...(overview.sessionId === null ? {} : { sourceSessionId: overview.sessionId }),
+		},
 	};
-	if (scope === "repo" && repository !== null) record.repository = repository;
-	return record;
+	if (validatedSelection !== undefined) applyScopeIdentity(record, validatedSelection);
+	else if (scope === "repo" && repository !== null) record.repository = repository;
+	else if (scope === "runtime" && overview.runtimeIds[0] !== undefined) {
+		record.runtime = { kind: "runtime", key: overview.runtimeIds[0] };
+	} else if (scope === "agent" && overview.agentIds[0] !== undefined) {
+		record.agent = { kind: "agent", key: overview.agentIds[0] };
+	}
+	const validated = validateMemoryRecord(record);
+	if (!validated.valid) {
+		throw new Error(
+			`evidence memory record invalid: ${validated.issues.map((issue) => `${issue.path}: ${issue.message}`).join("; ")}`,
+		);
+	}
+	return validated.record;
+}
+
+function memoryIdFromEvidenceScope(evidenceId: string, scopeKey: string): string {
+	const digest = createHash("sha256").update(`${evidenceId}\n${scopeKey}`, "utf8").digest("hex").slice(0, 16);
+	return `mem-${digest}`;
 }
 
 /**

package/src/domains/memory/task-bank.ts

@@ -37,8 +37,9 @@ export interface SaveTaskMemoryOptions {
 }
 
 /**
- * Per-session execution memory. This deliberately has no durable store or
- * approval flow: it is authoritative working state for one active task.
+ * Per-session execution memory. The bank stays transient and authoritative
+ * for one active task. Selected non-private entries can enter the separate
+ * durable store only through the reviewed promotion service.
  */
 export class TaskMemoryBank {
 	readonly #knowledgeCap: number;