memorix 1.2.1 → 1.2.3

package/src/memory/observations.ts

@@ -8,7 +8,16 @@
  * and in the Orama search index (for full-text + vector search).
  */
 
-import type { Observation, ObservationType, ObservationStatus, MemorixDocument, ProgressInfo } from '../types.js';
+import type {
+  Observation,
+  ObservationAdmissionState,
+  ObservationReader,
+  ObservationVisibility,
+  ObservationType,
+  ObservationStatus,
+  MemorixDocument,
+  ProgressInfo,
+} from '../types.js';
 import { TOPIC_KEY_FAMILIES } from '../types.js';
 import {
   insertObservation,
@@ -25,13 +34,15 @@ import {
   makeOramaObservationId,
   getLastSearchMode,
   searchObservations,
+  updateObservationMetadata,
 } from '../store/orama-store.js';
 import { getObservationStore, initObservationStore } from '../store/obs-store.js';
 import { countTextTokens } from '../compact/token-budget.js';
 import { extractEntities, enrichConcepts } from './entity-extractor.js';
 import { getEmbeddingProvider, isEmbeddingExplicitlyDisabled } from '../embedding/provider.js';
 import { sanitizeCredentials } from './secret-filter.js';
-import { enqueueClaimDerivation } from '../runtime/lifecycle.js';
+import { enqueueClaimDerivation, enqueueObservationQualification } from '../runtime/lifecycle.js';
+import { canManageObservation, resolveObservationVisibility } from './visibility.js';
 
 /** In-memory observation list (loaded from persistence on init) */
 let observations: Observation[] = [];
@@ -137,6 +148,20 @@ function queueClaimDerivation(observation: Observation): void {
   }
 }
 
+function queueObservationQualification(observation: Observation): void {
+  const dataDir = projectDir;
+  if (!dataDir || observation.admissionState !== 'candidate') return;
+  try {
+    enqueueObservationQualification({
+      dataDir,
+      projectId: observation.projectId,
+      source: 'automatic-capture:' + observation.id,
+    });
+  } catch {
+    // Candidate evidence remains available for a later qualification scan.
+  }
+}
+
 function isVectorCompatibleWithCurrentIndex(embedding: number[] | null): boolean {
   if (!embedding) return false;
   const vectorDimensions = getVectorDimensions();
@@ -253,7 +278,13 @@ export async function storeObservation(input: {
   relatedEntities?: string[];
   sourceDetail?: 'explicit' | 'hook' | 'git-ingest';
   valueCategory?: 'core' | 'contextual' | 'ephemeral';
+  admissionState?: ObservationAdmissionState;
+  admissionReason?: string;
+  visibility?: ObservationVisibility;
+  sharedWithAgentIds?: string[];
   createdByAgentId?: string;
+  /** Optional caller-bound write scope for topic-key upserts. */
+  visibilityReader?: ObservationReader;
 }): Promise<{ observation: Observation; upserted: boolean }> {
   const now = new Date().toISOString();
 
@@ -273,6 +304,9 @@ export async function storeObservation(input: {
       o => o.topicKey === input.topicKey && o.projectId === input.projectId,
     );
     if (existing) {
+      if (input.visibilityReader && !canManageObservation(existing, input.visibilityReader)) {
+        throw new Error('Cannot update a memory outside this session\'s write scope.');
+      }
       return { observation: await upsertObservation(existing, input, now), upserted: true };
     }
   }
@@ -320,6 +354,9 @@ export async function storeObservation(input: {
         if (input.topicKey) {
           const diskExisting = await tx.findByTopicKey(input.projectId, input.topicKey);
           if (diskExisting) {
+            if (input.visibilityReader && !canManageObservation(diskExisting, input.visibilityReader)) {
+              throw new Error('Cannot update a memory outside this session\'s write scope.');
+            }
             // Switch to upsert path — update the existing observation after this
             // short transaction has released its lock.
             upsertedInsideLock = true;
@@ -355,6 +392,10 @@ export async function storeObservation(input: {
           relatedEntities: input.relatedEntities,
           sourceDetail: input.sourceDetail,
           valueCategory: input.valueCategory,
+          admissionState: input.admissionState,
+          admissionReason: input.admissionReason ? sanitizeCredentials(input.admissionReason) : undefined,
+          visibility: input.visibility ?? 'project',
+          sharedWithAgentIds: input.sharedWithAgentIds,
           createdByAgentId: input.createdByAgentId,
           // Predict the generation that atomic() will commit after this callback.
           // bumpGeneration() runs after fn(tx) returns, incrementing by 1.
@@ -409,6 +450,10 @@ export async function storeObservation(input: {
         relatedEntities: input.relatedEntities,
         sourceDetail: input.sourceDetail,
         valueCategory: input.valueCategory,
+        admissionState: input.admissionState,
+        admissionReason: input.admissionReason ? sanitizeCredentials(input.admissionReason) : undefined,
+        visibility: input.visibility ?? 'project',
+        sharedWithAgentIds: input.sharedWithAgentIds,
         createdByAgentId: input.createdByAgentId,
         writeGeneration: 0,
       };
@@ -435,6 +480,11 @@ export async function storeObservation(input: {
       source: input.source ?? 'agent',
       sourceDetail: input.sourceDetail ?? '',
       valueCategory: input.valueCategory ?? '',
+      admissionState: input.admissionState ?? '',
+      admissionReason: input.admissionReason ? sanitizeCredentials(input.admissionReason) : '',
+      visibility: input.visibility ?? 'project',
+      createdByAgentId: input.createdByAgentId ?? '',
+      sharedWithAgentIds: JSON.stringify(input.sharedWithAgentIds ?? []),
     };
 
     await insertObservation(doc);
@@ -448,7 +498,10 @@ export async function storeObservation(input: {
   }
 
   await bindObservationCodeRefsBestEffort(observation);
-  queueClaimDerivation(observation);
+  queueObservationQualification(observation);
+  if (resolveObservationVisibility(observation) === 'project') {
+    queueClaimDerivation(observation);
+  }
 
   // Generate embedding async (fire-and-forget) — never blocks MCP response
   // Track in vectorMissingIds until embedding is successfully written.
@@ -518,6 +571,10 @@ async function upsertObservation(
     progress?: ProgressInfo;
     sourceDetail?: 'explicit' | 'hook' | 'git-ingest';
     valueCategory?: 'core' | 'contextual' | 'ephemeral';
+    admissionState?: ObservationAdmissionState;
+    admissionReason?: string;
+    visibility?: ObservationVisibility;
+    sharedWithAgentIds?: string[];
   },
   now: string,
 ): Promise<Observation> {
@@ -556,6 +613,10 @@ async function upsertObservation(
   if (input.progress) existing.progress = input.progress;
   if (input.sourceDetail !== undefined) existing.sourceDetail = input.sourceDetail;
   if (input.valueCategory !== undefined) existing.valueCategory = input.valueCategory;
+  if (input.admissionState !== undefined) existing.admissionState = input.admissionState;
+  if (input.admissionReason !== undefined) existing.admissionReason = sanitizeCredentials(input.admissionReason);
+  if (input.visibility !== undefined) existing.visibility = input.visibility;
+  if (input.sharedWithAgentIds !== undefined) existing.sharedWithAgentIds = input.sharedWithAgentIds;
 
   // Re-index in Orama WITHOUT embedding first (non-blocking)
   const doc: MemorixDocument = {
@@ -577,6 +638,11 @@ async function upsertObservation(
     source: existing.source ?? 'agent',
     sourceDetail: existing.sourceDetail ?? '',
     valueCategory: existing.valueCategory ?? '',
+    admissionState: existing.admissionState ?? '',
+    admissionReason: existing.admissionReason ?? '',
+    visibility: existing.visibility ?? 'project',
+    createdByAgentId: existing.createdByAgentId ?? '',
+    sharedWithAgentIds: JSON.stringify(existing.sharedWithAgentIds ?? []),
   };
 
   // Remove old doc and insert updated one (with retry for concurrent upsert race)
@@ -603,7 +669,10 @@ async function upsertObservation(
   }
 
   await bindObservationCodeRefsBestEffort(existing);
-  queueClaimDerivation(existing);
+  queueObservationQualification(existing);
+  if (resolveObservationVisibility(existing) === 'project') {
+    queueClaimDerivation(existing);
+  }
 
   // Generate embedding async (fire-and-forget) — never blocks MCP response
   const searchableText = [input.title, input.narrative, ...(input.facts ?? [])].join(' ');
@@ -651,6 +720,79 @@ export function getObservation(id: number, projectId?: string): Observation | un
   return observations.find((o) => o.id === id && (projectId ? o.projectId === projectId : true));
 }
 
+/**
+ * Promote or demote an automatic observation without changing its content.
+ * The expected-state guard keeps concurrent maintenance workers from
+ * resurrecting an observation that another writer has already changed.
+ */
+export async function updateObservationAdmission(input: {
+  observationId: number;
+  projectId?: string;
+  expectedState?: ObservationAdmissionState;
+  admissionState: ObservationAdmissionState;
+  admissionReason: string;
+  visibility?: ObservationVisibility;
+}): Promise<Observation | undefined> {
+  await ensureFreshObservations();
+  const cached = observations.find((observation) =>
+    observation.id === input.observationId &&
+    (!input.projectId || observation.projectId === input.projectId),
+  );
+  if (!cached) return undefined;
+
+  const now = new Date().toISOString();
+  const admissionReason = sanitizeCredentials(input.admissionReason).slice(0, 240);
+  const apply = (current: Observation): Observation | undefined => {
+    if (input.projectId && current.projectId !== input.projectId) return undefined;
+    if (input.expectedState && current.admissionState !== input.expectedState) return undefined;
+    return {
+      ...current,
+      admissionState: input.admissionState,
+      admissionReason,
+      ...(input.visibility !== undefined ? { visibility: input.visibility } : {}),
+      updatedAt: now,
+    };
+  };
+
+  let updated: Observation | undefined;
+  if (projectDir) {
+    const store = getObservationStore();
+    await store.atomic(async (tx) => {
+      const current = await tx.getById(input.observationId);
+      if (!current) return;
+      const next = apply(current);
+      if (!next) return;
+      await tx.update(next);
+      updated = next;
+    });
+  } else {
+    updated = apply(cached);
+  }
+
+  if (!updated) return undefined;
+  observations = observations.map((observation) =>
+    observation.id === updated!.id && observation.projectId === updated!.projectId
+      ? updated!
+      : observation,
+  );
+
+  try {
+    await updateObservationMetadata(updated.projectId, updated.id, {
+      admissionState: updated.admissionState,
+      admissionReason: updated.admissionReason,
+      ...(updated.visibility !== undefined ? { visibility: updated.visibility } : {}),
+    });
+  } catch {
+    // SQLite is canonical. The next index hydration repairs a missed update.
+  }
+
+  if (updated.admissionState === 'qualified' && resolveObservationVisibility(updated) === 'project') {
+    queueClaimDerivation(updated);
+  }
+
+  return updated;
+}
+
 /**
  * Resolve observations — mark them as resolved (completed/no longer active).
  * This prevents resolved memories from appearing in default search results.
@@ -701,6 +843,11 @@ export async function resolveObservations(
         source: obs.source ?? 'agent',
         sourceDetail: obs.sourceDetail ?? '',
         valueCategory: obs.valueCategory ?? '',
+        admissionState: obs.admissionState ?? '',
+        admissionReason: obs.admissionReason ?? '',
+        visibility: obs.visibility ?? 'project',
+        createdByAgentId: obs.createdByAgentId ?? '',
+        sharedWithAgentIds: JSON.stringify(obs.sharedWithAgentIds ?? []),
       };
       await insertObservation(doc);
       // Async embedding update (fire-and-forget)
@@ -904,6 +1051,11 @@ export async function reindexObservations(): Promise<number> {
         source: obs.source ?? 'agent',
         sourceDetail: obs.sourceDetail ?? '',
         valueCategory: obs.valueCategory ?? '',
+        admissionState: obs.admissionState ?? '',
+        admissionReason: obs.admissionReason ?? '',
+        visibility: obs.visibility ?? 'project',
+        createdByAgentId: obs.createdByAgentId ?? '',
+        sharedWithAgentIds: JSON.stringify(obs.sharedWithAgentIds ?? []),
         ...(compatibleEmbedding ? { embedding: compatibleEmbedding } : {}),
       };
       await insertObservation(doc);
@@ -1028,6 +1180,7 @@ export async function probeSearchIndex(projectId: string): Promise<string> {
   await searchObservations({
     query: 'semantic memory retrieval status',
     projectId,
+    reader: { projectId },
     limit: 1,
     status: 'all',
     trackAccess: false,
@@ -1114,6 +1267,11 @@ export async function backfillVectorEmbeddings(options: {
             source: obs.source ?? 'agent',
             sourceDetail: obs.sourceDetail ?? '',
             valueCategory: obs.valueCategory ?? '',
+            admissionState: obs.admissionState ?? '',
+            admissionReason: obs.admissionReason ?? '',
+            visibility: obs.visibility ?? 'project',
+            createdByAgentId: obs.createdByAgentId ?? '',
+            sharedWithAgentIds: JSON.stringify(obs.sharedWithAgentIds ?? []),
             embedding,
           };
           await insertObservation(doc);

package/src/memory/quality-audit.ts

@@ -137,6 +137,8 @@ export function auditMemoryQuality(
       source: obs.source ?? 'agent',
       sourceDetail: obs.sourceDetail ?? '',
       valueCategory: obs.valueCategory ?? '',
+      admissionState: obs.admissionState ?? '',
+      admissionReason: obs.admissionReason ?? '',
     }, options.referenceTime) !== 'active')
     .map((obs) => makeEntry(obs, 'Outside active retention zone'));
 

package/src/memory/retention.ts

@@ -15,8 +15,9 @@
  * retention period but are no longer permanently immune — they decay normally.
  */
 
-import type { MemorixDocument, Observation } from '../types.js';
+import type { MemorixDocument, Observation, ObservationReader } from '../types.js';
 import { getObservationStore } from '../store/obs-store.js';
+import { canManageObservation } from './visibility.js';
 
 // ── Importance → Retention Period mapping ────────────────────────────
 
@@ -113,6 +114,10 @@ export function isImmune(doc: MemorixDocument): boolean {
   // Probe observations are operational heartbeats -- never immune, regardless of valueCategory or access.
   if (doc.type === 'probe') return false;
 
+  // A candidate has not earned durable status. Never let an automatic core
+  // classification turn unqualified capture into permanently retained memory.
+  if (doc.admissionState === 'candidate' || doc.admissionState === 'ephemeral') return false;
+
   // formation-classified core memories are immune regardless of type
   if (doc.valueCategory === 'core') return true;
 
@@ -135,6 +140,11 @@ export function getImmunityReason(doc: MemorixDocument): string | null {
   // Probe observations are never immune
   if (doc.type === 'probe') return null;
 
+  // Automatic traces and candidates have not earned durable status. Keep the
+  // explanation aligned with isImmune() even when an earlier classifier gave
+  // a candidate the core value category.
+  if (doc.admissionState === 'candidate' || doc.admissionState === 'ephemeral') return null;
+
   if (doc.valueCategory === 'core') return 'core valueCategory (formation-classified)';
   const importance = getImportanceLevel(doc);
   if (importance === 'critical') return 'critical importance';
@@ -369,6 +379,8 @@ export interface ArchiveExpiredBatchOptions {
   limit?: number;
   referenceTime?: Date;
   accessMap?: Map<number, { accessCount: number; lastAccessedAt: string }>;
+  /** Omit only for trusted background maintenance. */
+  reader?: ObservationReader;
 }
 
 export interface ArchiveExpiredBatchResult {
@@ -401,6 +413,8 @@ function toRetentionDocument(
     source: obs.source ?? 'agent',
     sourceDetail: obs.sourceDetail ?? '',
     valueCategory: obs.valueCategory ?? '',
+    admissionState: obs.admissionState ?? '',
+    admissionReason: obs.admissionReason ?? '',
   };
 }
 
@@ -423,6 +437,7 @@ export async function archiveExpiredBatch(
   const hasMore = page.length > limit;
   const scanned = hasMore ? page.slice(0, limit) : page;
   const candidateIds = scanned
+    .filter((observation) => !options.reader || canManageObservation(observation, options.reader))
     .filter((observation) => getRetentionZone(
       toRetentionDocument(observation, options.accessMap),
       options.referenceTime,
@@ -461,6 +476,7 @@ export async function archiveExpired(
   referenceTime?: Date,
   accessMap?: Map<number, { accessCount: number; lastAccessedAt: string }>,
   projectId?: string,
+  reader?: ObservationReader,
 ): Promise<{ archived: number; remaining: number }> {
   const store = getObservationStore();
   if (projectId) {
@@ -472,12 +488,16 @@ export async function archiveExpired(
         afterId,
         referenceTime,
         accessMap,
+        reader,
       });
       archived += batch.archived;
       afterId = batch.nextCursor;
     } while (afterId !== undefined);
 
-    const remaining = await store.countByProject(projectId, { status: 'active' });
+    const remainingObservations = await store.loadByProject(projectId, { status: 'active' });
+    const remaining = reader
+      ? remainingObservations.filter((observation) => canManageObservation(observation, reader)).length
+      : remainingObservations.length;
     return { archived, remaining };
   }
 

package/src/memory/session.ts

@@ -11,13 +11,15 @@
  * - Cross-agent session awareness (all agents share session data)
  */
 
-import type { Observation, Session } from '../types.js';
+import type { Observation, ObservationReader, Session } from '../types.js';
+import { isEligibleForAutomaticDelivery } from './admission.js';
 import { classifyLayer } from './disclosure-policy.js';
 import { resolveAliases } from '../project/aliases.js';
 import { getObservationStore } from '../store/obs-store.js';
 import { getSessionStore } from '../store/session-store.js';
 import { KnowledgeGraphManager } from './graph.js';
 import { redactCredentials, sanitizeCredentials } from './secret-filter.js';
+import { canReadObservation } from './visibility.js';
 
 const PRIORITY_TYPES = new Set(['gotcha', 'decision', 'problem-solution', 'trade-off', 'discovery']);
 const TYPE_EMOJI: Record<string, string> = {
@@ -241,7 +243,7 @@ export function scoreObservationForSessionContext(obs: Observation, projectToken
 export async function startSession(
   projectDir: string,
   projectId: string,
-  opts?: { sessionId?: string; agent?: string },
+  opts?: { sessionId?: string; agent?: string; reader?: ObservationReader },
 ): Promise<{ session: Session; previousContext: string }> {
   const sessionId = opts?.sessionId || generateSessionId();
   const now = new Date().toISOString();
@@ -255,7 +257,7 @@ export async function startSession(
   };
 
   // Load previous context before creating new session
-  const previousContext = await getSessionContext(projectDir, projectId);
+  const previousContext = await getSessionContext(projectDir, projectId, 3, opts?.reader);
 
   // Atomic rollover: complete all active sessions for this project's aliases
   // and insert the new session in a single SQLite transaction.
@@ -305,17 +307,31 @@ export async function endSession(
  *   Key Memories   — durable explicit working context (L2)
  *   Session History— orientation log
  *   L3 Evidence    — pointers to git-memory and hook traces (on-demand)
+ *
+ * When a reader is supplied, automatic observation delivery follows that
+ * identity's visibility boundary. Omit it only for trusted maintenance paths.
  */
 export async function getSessionContext(
   projectDir: string,
   projectId: string,
   limit: number = 3,
+  reader?: ObservationReader,
 ): Promise<string> {
   const aliasSet = await resolveProjectIds(projectId);
   const [sessions, allObs] = await Promise.all([
     loadAliasSessions(aliasSet),
     loadAliasActiveObservations(aliasSet),
   ]);
+  const readableObs = reader
+    ? allObs.filter((observation) => {
+        // Aliases represent one project across moved/renamed worktrees. Preserve
+        // that project equivalence while still enforcing the caller's identity.
+        const observationReader = reader.projectId && aliasSet.has(observation.projectId)
+          ? { ...reader, projectId: observation.projectId }
+          : reader;
+        return canReadObservation(observation, observationReader);
+      })
+    : allObs;
   /** Check if a session summary contains noise/system-self content */
   const isNoisySummary = (summary: string | undefined): boolean => {
     if (!summary) return false;
@@ -328,7 +344,7 @@ export async function getSessionContext(
     .sort((a, b) => new Date(b.endedAt || b.startedAt).getTime() - new Date(a.endedAt || a.startedAt).getTime())
     .slice(0, limit);
 
-  if (projectSessions.length === 0 && allObs.length === 0) {
+  if (projectSessions.length === 0 && readableObs.length === 0) {
     return '';
   }
 
@@ -336,7 +352,7 @@ export async function getSessionContext(
   const projectTokens = tokenizeProjectId(projectId);
 
   // ── Partition project observations by disclosure layer ─────────────
-  const projectObs = allObs
+  const projectObs = readableObs
     .filter((obs) => !isNoiseObservation(obs) && !isSystemSelfObservation(obs));
 
   // L2: durable working context (explicit/undefined/core), priority types only
@@ -369,13 +385,15 @@ export async function getSessionContext(
 
   // L1: recent hook activity signals (titles only, most recent first)
   const l1HookObs = projectObs
-    .filter((obs) => classifyLayer(obs) === 'L1')
+    .filter((obs) => isEligibleForAutomaticDelivery(obs) && classifyLayer(obs) === 'L1')
     .sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime())
     .slice(0, 3);
 
   // L3: git-ingest evidence count (pointer only, not injected)
   const l3GitCount = projectObs.filter((obs) => classifyLayer(obs) === 'L3').length;
-  const totalHookCount = projectObs.filter((obs) => classifyLayer(obs) === 'L1').length;
+  const totalHookCount = projectObs
+    .filter((obs) => isEligibleForAutomaticDelivery(obs) && classifyLayer(obs) === 'L1')
+    .length;
 
   // Active entities: unique entity names from top-scored L2 memories.
   // Surfaced in L1 Routing as next-hop search guidance — not working context.
@@ -389,11 +407,11 @@ export async function getSessionContext(
   // Active entities enrich the section when it is shown but do not open it alone.
   const hasL1Content = l1HookObs.length > 0 || l3GitCount > 0;
   if (hasL1Content) {
-    // Graph neighbor routing hint: 1-hop neighbors of activeEntities from the
-    // knowledge graph. Routing only — no query expansion, no rerank, no 2-hop
-    // traversal. Silently skipped if graph is absent, empty, or throws.
+    // Graph relations do not yet carry observation visibility metadata, so an
+    // agent-facing reader must not use them as an indirect disclosure channel.
+    // Trusted maintenance paths retain the existing routing hint.
     let graphNeighbors: string[] = [];
-    if (activeEntities.length > 0) {
+    if (!reader && activeEntities.length > 0) {
       try {
         const graphMgr = new KnowledgeGraphManager(projectDir);
         await graphMgr.init();

package/src/memory/visibility.ts

@@ -0,0 +1,80 @@
+import type { ObservationReader, ObservationVisibility } from '../types.js';
+
+/** Minimal common shape shared by persisted observations and Orama documents. */
+export interface VisibilityRecord {
+  projectId: string;
+  visibility?: ObservationVisibility | string;
+  createdByAgentId?: string;
+  sharedWithAgentIds?: string[] | string;
+}
+
+/**
+ * Pre-control-plane records were intentionally project-shared. Preserve that
+ * behavior so an upgrade does not make a user's historical memory disappear.
+ */
+export function resolveObservationVisibility(record: Pick<VisibilityRecord, 'visibility'>): ObservationVisibility {
+  switch (record.visibility) {
+    case 'personal':
+    case 'team':
+    case 'project':
+      return record.visibility;
+    default:
+      return 'project';
+  }
+}
+
+function sharedAgentIds(record: VisibilityRecord): string[] {
+  if (Array.isArray(record.sharedWithAgentIds)) return record.sharedWithAgentIds;
+  if (typeof record.sharedWithAgentIds !== 'string' || !record.sharedWithAgentIds) return [];
+  try {
+    const parsed = JSON.parse(record.sharedWithAgentIds);
+    return Array.isArray(parsed) ? parsed.filter((id): id is string => typeof id === 'string') : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * The policy is intentionally fail-closed for personal and team scopes. A
+ * missing actor never turns a private record into a project-wide result.
+ * `undefined` is reserved for trusted internal maintenance, not MCP delivery.
+ */
+export function canReadObservation(record: VisibilityRecord, reader?: ObservationReader): boolean {
+  if (!reader) return true;
+
+  const sameProject = reader.projectId === record.projectId;
+  const visibility = resolveObservationVisibility(record);
+  // An explicit global search may inspect project-visible facts across projects,
+  // but it never gains a team or personal scope without a bound project.
+  if (visibility === 'project') return !reader.projectId || sameProject;
+  if (!sameProject || !reader.agentId) return false;
+
+  if (visibility === 'team') return reader.isTeamMember === true;
+  return record.createdByAgentId === reader.agentId || sharedAgentIds(record).includes(reader.agentId);
+}
+
+/**
+ * Reading a targeted handoff does not grant the recipient permission to alter
+ * it. Project evidence is jointly maintainable; personal records stay owned by
+ * their creator; team records require an active team member.
+ */
+export function canManageObservation(record: VisibilityRecord, reader?: ObservationReader): boolean {
+  if (!reader) return true;
+  if (!reader.projectId || reader.projectId !== record.projectId) return false;
+
+  switch (resolveObservationVisibility(record)) {
+    case 'project':
+      return true;
+    case 'team':
+      return reader.isTeamMember === true;
+    case 'personal':
+      return Boolean(reader.agentId && record.createdByAgentId === reader.agentId);
+  }
+}
+
+export function filterReadableObservations<T extends VisibilityRecord>(
+  observations: readonly T[],
+  reader?: ObservationReader,
+): T[] {
+  return reader ? observations.filter((observation) => canReadObservation(observation, reader)) : [...observations];
+}