apsimo 1.3.0__py3-none-any.whl

apsimo/turns/reported_workers.py

@@ -0,0 +1,196 @@
+"""Optional local heartbeat reports, separate from canonical executions."""
+import json
+import hashlib
+import math
+import os
+from pathlib import Path
+import time
+
+
+def _text(value, maximum=128):
+    return (isinstance(value, str) and 0 < len(value) <= maximum
+            and not any(ord(char) < 32 for char in value))
+
+
+def _number(value):
+    try:
+        return type(value) in (int, float) and math.isfinite(value) and value >= 0
+    except OverflowError:
+        return False
+
+
+def work_snapshot(value, *, now=None):
+    """Bounded metadata from an explicitly enrolled producer, never authority.
+
+    Producers may attach this snapshot to an existing process heartbeat. The
+    public reader knows no private ledger schema, recipients or machine paths.
+    """
+    if value is None:
+        return None
+    if not isinstance(value, dict) or value.get('schema') != 'ColonyWorkSnapshotV1':
+        return {'schema': 'ColonyWorkSnapshotV1', 'available': False, 'reason': 'unsupported_work_snapshot', 'complete': False}
+    if type(value.get('available')) is not bool or not _number(value.get('observed_at')):
+        return {'schema': 'ColonyWorkSnapshotV1', 'available': False, 'reason': 'invalid_work_snapshot', 'complete': False}
+    now = time.time() if now is None else now
+    age = now - value['observed_at']
+    result = {'schema': 'ColonyWorkSnapshotV1', 'available': value['available'], 'complete': False, 'observed_at': value['observed_at'],
+              'freshness': 'recent' if 0 <= age <= 120 else 'stale' if age > 120 else 'unknown',
+              'items': [], 'truncated': bool(value.get('truncated')), 'partial': bool(value.get('partial'))}
+    for key in ('total', 'pending_total', 'terminal_total', 'unmatched_provider_total'):
+        if type(value.get(key)) is int and value[key] >= 0:
+            result[key] = value[key]
+    for key in ('reason', 'coverage'):
+        if _text(value.get(key), 200):
+            result[key] = value[key]
+    statuses = value.get('source_status')
+    if isinstance(statuses, dict):
+        result['source_status'] = {key: state for key, state in list(statuses.items())[:8]
+            if _text(key, 32) and state in {'observed', 'unavailable', 'partial', 'not_observed'}}
+    states = value.get('state_counts')
+    if isinstance(states, dict):
+        result['state_counts'] = {key: n for key, n in list(states.items())[:12]
+            if _text(key, 48) and type(n) is int and n >= 0}
+    rows = value.get('items', [])
+    if not isinstance(rows, list):
+        return {'schema': 'ColonyWorkSnapshotV1', 'available': False, 'reason': 'invalid_work_snapshot', 'complete': False}
+    result['truncated'] |= len(rows) > 4
+    for row in rows[:4]:
+        if not isinstance(row, dict):
+            result['partial'] = True
+            continue
+        item = {'liveness': 'record_only'}
+        for key in ('delivery_id', 'intent_id', 'request_key', 'attempt_id', 'state', 'record_kind',
+                    'provider_state', 'observation_state'):
+            if _text(row.get(key), 256 if key.endswith('_id') or key == 'request_key' else 64):
+                item[key] = row[key]
+        if not item.get('delivery_id') or not item.get('state'):
+            result['partial'] = True
+            continue
+        for key in ('updated_at', 'provider_updated_at'):
+            if _number(row.get(key)):
+                item[key] = row[key]
+        if type(row.get('transport_observation_pending')) is bool:
+            item['transport_observation_pending'] = row['transport_observation_pending']
+        digest = row.get('evidence_sha256')
+        if isinstance(digest, str) and len(digest) == 64 and all(c in '0123456789abcdef' for c in digest):
+            item['evidence_sha256'] = digest
+        result['items'].append(item)
+    return result
+
+
+def work_details(value, *, now=None):
+    """Project declared work metadata; never follow references or verify effects.
+
+    These optional fields extend existing heartbeat producers. Bad optional
+    values do not hide the underlying legacy state or make a task terminal.
+    The same projection is used for automatic request context.
+    """
+    result = {}
+    snapshot = work_snapshot(value.get('work_snapshot'), now=now)
+    if snapshot is not None:
+        result['work_snapshot'] = snapshot
+    for key in ('task_id', 'parent_task_id', 'worker_id', 'kind'):
+        if _text(value.get(key)):
+            result[key] = value[key]
+    for key in ('started_at', 'finished_at'):
+        if _number(value.get(key)):
+            result[key] = value[key]
+    if type(value.get('exit_code')) is int and -(2**31) <= value['exit_code'] < 2**31:
+        result['exit_code'] = value['exit_code']
+    progress = value.get('progress')
+    if isinstance(progress, list):
+        selected = []
+        for row in progress[:4]:
+            if (not isinstance(row, dict) or not _number(row.get('completed'))
+                    or not _number(row.get('observed_at')) or not _text(row.get('unit'), 32)
+                    or not _text(row.get('source'), 128)):
+                continue
+            item = {key: row[key] for key in ('completed', 'unit', 'source', 'observed_at')}
+            if 'total' in row:
+                if not _number(row['total']) or row['total'] < row['completed']:
+                    continue
+                item['total'] = row['total']
+            selected.append(item)
+        if selected:
+            result['progress'] = selected
+    references = value.get('result_refs')
+    if isinstance(references, list):
+        selected = []
+        for row in references[:4]:
+            if (not isinstance(row, dict) or not _text(row.get('kind'), 64)
+                    or not _text(row.get('reference'), 512)):
+                continue
+            item = {key: row[key] for key in ('kind', 'reference')}
+            digest = row.get('sha256')
+            if isinstance(digest, str) and len(digest) == 64 and all(c in '0123456789abcdef' for c in digest):
+                item['sha256'] = digest
+            if _number(row.get('observed_at')):
+                item['observed_at'] = row['observed_at']
+            # The producer describes its check; the reader does not endorse it.
+            if _text(row.get('verification'), 160):
+                item['verification'] = row['verification']
+            selected.append(item)
+        if selected:
+            result['result_refs'] = selected
+    return result
+
+
+def reported_worker_view(*, limit=8, now=None):
+    configured = os.environ.get('COLONY_WORKER_STATUS_PATHS', '').strip()
+    if not configured:
+        return None
+    view = {'source':'configured_local_heartbeats', 'available':False,
+            'items':[], 'complete':False,
+            'coverage':'reported worker state only; no execution or effect verification'}
+    try:
+        paths = json.loads(configured)
+        if (len(configured)>8192 or not isinstance(paths,dict)
+                or not all(isinstance(label,str) and label and isinstance(path,str) and path
+                           for label,path in paths.items())):
+            raise ValueError('Invalid heartbeat mapping')
+    except (ValueError,TypeError):
+        return {**view,'reason':'invalid_status_configuration'}
+    now = time.time() if now is None else now
+    bounded = max(1,min(int(limit),8))
+    items = []
+    for label,filename in list(paths.items())[:bounded]:
+        item = {'label':label[:128], 'available':False, 'liveness':'unverified'}
+        try:
+            path = Path(filename).expanduser()
+            if not path.is_file():
+                raise ValueError('Heartbeat unavailable')
+            with path.open('rb') as stream:
+                raw = stream.read(16385)
+            value = json.loads(raw)
+            if len(raw)>16384 or not isinstance(value,dict):
+                raise ValueError('Invalid heartbeat')
+            updated = value.get('updated_at')
+            state = value.get('state')
+            if isinstance(state, dict) and 'work_snapshot' in state:
+                value = {**value, 'work_snapshot': state['work_snapshot']}
+                state = 'reported_ready' if value.get('ready') is True else 'reported_unready'
+            if (not isinstance(state,str) or not state or len(state)>64
+                    or isinstance(updated,bool) or not isinstance(updated,(int,float))
+                    or not math.isfinite(updated)):
+                raise ValueError('Invalid heartbeat fields')
+            age = now-updated
+            item.update(available=True,state=state,updated_at=updated,
+                age_seconds=round(age,1) if age>=0 else None,
+                freshness='recent' if 0<=age<=120 else 'stale' if age>120 else 'unknown',
+                status_sha256=hashlib.sha256(raw).hexdigest())
+            for key in ('detail_code','release_commit'):
+                if isinstance(value.get(key),str):
+                    item[key] = value[key][:128]
+            item.update(work_details(value, now=now))
+            if 'task_id' in item:
+                finished = item.get('finished_at')
+                terminal = (finished is not None and finished <= updated
+                            and finished >= item.get('started_at', 0)
+                            and state in {'exited', 'completed', 'failed', 'interrupted', 'cancelled'})
+                item['record_kind'] = 'terminal_report' if terminal else 'progress_report'
+        except (OSError,ValueError,TypeError):
+            item['reason'] = 'heartbeat_unavailable'
+        items.append(item)
+    partial = any(not item.get('available') or item.get('work_snapshot', {}).get('available') is False
+                  or item.get('work_snapshot', {}).get('partial') for item in items)
+    return {**view,'available':True,'items':items,'truncated':len(paths)>bounded, 'partial': partial}

apsimo/turns/source_annotations.py

@@ -0,0 +1,283 @@
+"""Attributed source corrections in the existing source ledger and recall packet."""
+from contextlib import closing
+from datetime import datetime, timezone
+import hashlib
+import json
+import re
+import sqlite3
+
+
+def initialize(conn):
+    # No correction text is duplicated here. These references survive erasure
+    # so deleting an annotation cannot silently revive its unqualified source.
+    conn.execute('''CREATE TABLE IF NOT EXISTS source_annotations (
+        annotation_source_id TEXT PRIMARY KEY, target_source_id TEXT NOT NULL,
+        target_version TEXT NOT NULL, target_message_hashes_json TEXT NOT NULL,
+        request_sha256 TEXT NOT NULL)''')
+    conn.execute('CREATE INDEX IF NOT EXISTS source_annotation_target ON source_annotations(target_source_id)')
+
+
+def append(ledger, *, contact_id, session_id, annotation_id, source_id, source_version,
+           excerpt, correction, author_principal):
+    from .idempotency import canonical_turn_digest, source_message_hash, SourceErased
+    from .audio import source_text
+    for value, maximum in ((contact_id, 256), (session_id, 256), (annotation_id, 128),
+                           (source_id, 256), (excerpt, 4096), (correction, 4096),
+                           (author_principal, 256)):
+        if not isinstance(value, str) or not value.strip() or len(value) > maximum:
+            raise ValueError('invalid_source_annotation')
+    if not isinstance(source_version, str) or not re.fullmatch('[0-9a-f]{64}', source_version):
+        raise ValueError('invalid_source_annotation')
+    identity = [contact_id, author_principal, annotation_id]
+    annotation_source = 'source-annotation:' + canonical_turn_digest(identity)
+    target = {'source_id': source_id, 'source_version': source_version}
+    request_digest = canonical_turn_digest([identity, session_id, target, excerpt, correction])
+    with closing(ledger._connect()) as conn, conn:
+        conn.execute('BEGIN IMMEDIATE')
+        prior = conn.execute('SELECT * FROM source_annotations WHERE annotation_source_id=?',
+                             (annotation_source,)).fetchone()
+        if prior and prior['request_sha256'] != request_digest:
+            raise ValueError('annotation_id_conflict')
+        if conn.execute('SELECT 1 FROM source_erasures WHERE turn_id=?', (annotation_source,)).fetchone():
+            raise SourceErased('source_erased')
+        row = conn.execute('''SELECT * FROM turn_sources WHERE turn_id=? AND contact_id=?
+            AND (scope='person' OR session_id=?)''', (source_id, contact_id, session_id)).fetchone()
+        if row is None:
+            raise ValueError('source_not_found')
+        messages = json.loads(row['messages_json'])
+        if canonical_turn_digest(messages) != source_version:
+            raise ValueError('source_version_mismatch')
+        matched = [source_message_hash(row['session_id'], m) for m in messages
+                   if excerpt in source_text(m.get('content'))]
+        if not matched:
+            raise ValueError('source_excerpt_mismatch')
+        if prior:
+            stored = conn.execute('SELECT messages_json FROM turn_sources WHERE turn_id=?',
+                                  (annotation_source,)).fetchone()
+            if stored is None:
+                raise SourceErased('source_erased')
+            annotation_messages = json.loads(stored['messages_json'])
+        else:
+            at = datetime.now(timezone.utc).isoformat()
+            content = {'target': target, 'excerpt': excerpt, 'correction': correction,
+                       'author_principal': author_principal, 'recorded_at': at,
+                       'state': 'attributed_correction'}
+            annotation_messages = [{'role': 'assistant', 'content': json.dumps(content, ensure_ascii=False),
+                                    '_supplied_sources': [target]}]
+            # The dedicated method owns authorship, source and relation in one
+            # transaction. Ordinary turn metadata cannot create a correction.
+            ledger._validate_dependencies(conn, annotation_source, contact_id, session_id, annotation_messages)
+            digest = canonical_turn_digest({'messages': annotation_messages, 'contact_id': contact_id,
+                'session_id': session_id, 'scope': row['scope'], 'occurred_at': at})
+            try:
+                conn.execute('''INSERT INTO turn_sources
+                    (turn_id,content_sha256,contact_id,session_id,scope,messages_json,occurred_at)
+                    VALUES (?,?,?,?,?,?,?)''', (annotation_source, digest, contact_id, session_id,
+                        row['scope'], json.dumps(annotation_messages, ensure_ascii=True, sort_keys=True,
+                                                 separators=(',', ':')), at))
+            except sqlite3.IntegrityError as exc:
+                raise ValueError('annotation_id_conflict') from exc
+            ledger._index_messages(conn, annotation_source, annotation_messages)
+            from .source_vectors import enqueue
+            enqueue(conn, annotation_source)
+            conn.execute('INSERT INTO source_annotations VALUES (?,?,?,?,?)',
+                (annotation_source, source_id, source_version, json.dumps(matched), request_digest))
+        return {'accepted': True, 'created': prior is None, 'source_id': annotation_source,
+                'source_version': canonical_turn_digest(annotation_messages), 'target': target}
+
+
+def source_ids(row):
+    ids = list(row.get('source_turn_ids') or [])
+    if row.get('source_turn_id'):
+        ids.append(row['source_turn_id'])
+    uri = str(row.get('source_uri') or '')
+    if uri.startswith('turn:'):
+        ids.append(uri[5:])
+    return list(dict.fromkeys(ids))
+
+
+def expand(ledger, candidates, *, contact_id, session_id, covered=()):
+    """Bundle exact revision corrections before ranking and character packing.
+
+    A source-backed belief/conflict bundle and a derived answer are subject to
+    the same rule as direct lexical/semantic excerpts. All discovered notes
+    remain attributed evidence; the newest note does not automatically win.
+    """
+    from .idempotency import canonical_turn_digest, source_message_hash
+    from .audio import source_text
+    result = []
+    with closing(ledger._connect()) as conn:
+        cached = {}
+
+        def source(identifier):
+            if identifier not in cached:
+                row = conn.execute('''SELECT * FROM turn_sources WHERE turn_id=? AND contact_id=?
+                    AND (scope='person' OR session_id=?)''', (identifier, contact_id, session_id)).fetchone()
+                cached[identifier] = dict(row) if row else None
+                if row:
+                    cached[identifier]['messages'] = json.loads(row['messages_json'])
+            return cached[identifier]
+
+        def candidate_hashes(candidate, identifier):
+            # Assertion bundles carry canonical claim membership, not a JSON
+            # string to reinterpret. Semantic excerpts already have one hash.
+            if '_source_message_hashes' in candidate:
+                return set(candidate['_source_message_hashes'].get(identifier, []))
+            if candidate.get('source_message_hash'):
+                return {candidate['source_message_hash']}
+            if candidate.get('kind') == 'source_quote' or candidate.get('source_turn_id'):
+                row = source(identifier)
+                text, role = candidate.get('content'), candidate.get('role')
+                return {source_message_hash(row['session_id'], message) for message in row['messages']
+                        if (not role or message.get('role') == role)
+                        and isinstance(text, str) and text
+                        and text in source_text(message.get('content'))} if row else set()
+            # Older graph summaries and supplied parent references attest a
+            # whole source version. Do not invent finer ancestry from prose.
+            return None
+
+        for original in candidates:
+            ids = source_ids(original)
+            pending = [(identifier, candidate_hashes(original, identifier)) for identifier in ids]
+            visited, notes = {}, {}
+            unavailable = False
+            while pending:
+                identifier, selected_hashes = pending.pop()
+                row = source(identifier)
+                if row is None:
+                    continue
+                version = canonical_turn_digest(row['messages'])
+                hashes = {source_message_hash(row['session_id'], m) for m in row['messages']}
+                selected_hashes = hashes if selected_hashes is None else hashes.intersection(selected_hashes)
+                selected_hashes -= visited.get(identifier, set())
+                if not selected_hashes:
+                    continue
+                visited.setdefault(identifier, set()).update(selected_hashes)
+                for relation in conn.execute('SELECT * FROM source_annotations WHERE target_source_id=?', (identifier,)):
+                    # A partial erase can change the source revision while
+                    # retaining the annotated message. Its removed correction
+                    # still fences that message; unrelated survivors remain.
+                    same_version = relation['target_version'] == version
+                    retained_message = selected_hashes.intersection(json.loads(relation['target_message_hashes_json']))
+                    if not retained_message:
+                        continue
+                    annotation = source(relation['annotation_source_id'])
+                    if annotation is None or not same_version:
+                        unavailable = True
+                        break
+                    data = json.loads(annotation['messages'][0]['content'])
+                    notes[relation['annotation_source_id']] = data
+                    pending.append((relation['annotation_source_id'], None))
+                if unavailable:
+                    break
+                own_annotation = conn.execute('SELECT * FROM source_annotations WHERE annotation_source_id=?',
+                                              (identifier,)).fetchone()
+                for message in row['messages']:
+                    if (message.get('role') == 'assistant'
+                            and source_message_hash(row['session_id'], message) in selected_hashes):
+                        for ref in message.get('_supplied_sources', []):
+                            parent = source(ref['source_id'])
+                            if parent and canonical_turn_digest(parent['messages']) == ref['source_version']:
+                                # Dedicated annotations have exact target message
+                                # membership. Their own source link must not widen
+                                # a selected excerpt back to all sibling messages.
+                                target_hashes = (set(json.loads(own_annotation['target_message_hashes_json']))
+                                    if own_annotation and own_annotation['target_source_id'] == ref['source_id']
+                                    and own_annotation['target_version'] == ref['source_version'] else None)
+                                pending.append((ref['source_id'], target_hashes))
+            if unavailable:
+                continue
+            if not notes:
+                # An empty correction set is also a selection-time snapshot.
+                # A first note can arrive while ranking awaits; preserve exact
+                # message membership so a sibling's note does not hide this row.
+                row = dict(original)
+                if visited:
+                    row['_annotation_source_refs'] = [{'source_id': identifier,
+                        'source_version': canonical_turn_digest(source(identifier)['messages'])}
+                        for identifier in visited]
+                    row['_annotation_ids'] = ()
+                    row['_annotation_message_hashes'] = {identifier: sorted(hashes)
+                        for identifier, hashes in visited.items()}
+                result.append(row)
+                continue
+            row = dict(original)
+            if (original.get('kind') == 'belief'
+                    or 'kind' not in original and not original.get('source_turn_id')):
+                row['_recall_memory_id'] = original.get('_recall_memory_id', original['id'])
+            # If the annotation itself matched the query, show its exact
+            # target excerpt first instead of presenting an orphan note.
+            if len(ids) == 1 and ids[0] in notes:
+                note = notes[ids[0]]
+                original_evidence = {'source': note['target'], 'quote': note['excerpt']}
+                row['_annotation_only'] = True
+            else:
+                original_evidence = {'source_ids': ids, 'content': str(original.get('content') or '')}
+            corrections = [dict(data, source_id=identifier) for identifier, data in sorted(
+                notes.items(), key=lambda pair: (pair[1]['recorded_at'], pair[0]))]
+            row.update(content=json.dumps({'original': original_evidence, 'corrections': corrections,
+                'interpretation': 'Read the original in light of these attributed corrections; conflicting corrections remain unresolved.'},
+                ensure_ascii=False), atomic_evidence=True, epistemic_state='correction_evidence',
+                source_turn_ids=list(dict.fromkeys(ids + sorted(visited) + list(notes))))
+            row['_annotation_source_refs'] = [{'source_id': identifier,
+                'source_version': canonical_turn_digest(source(identifier)['messages'])}
+                for identifier in row['source_turn_ids'] if source(identifier)]
+            row['_annotation_ids'] = tuple(sorted(notes))
+            row['_annotation_message_hashes'] = {identifier: sorted(hashes) for identifier, hashes in visited.items()}
+            row['ranking_text'] = '\n'.join(
+                'Attributed correction (not independently verified):\n' + note['correction']
+                for note in corrections) + '\nOriginal evidence:\n' + str(
+                    original.get('ranking_text') or original.get('content') or '')
+            row['id'] = 'annotated:' + hashlib.sha256(json.dumps([original['id'], list(notes)], sort_keys=True).encode()).hexdigest()
+            result.append(row)
+    # A lexical/semantic annotation hit adds no evidence when an original
+    # excerpt already carries the same complete correction set. Preserve all
+    # distinct original excerpts; this is not content or semantic merging.
+    seen = {row['_annotation_ids'] for row in [*covered, *result]
+            if row.get('_annotation_ids') and not row.get('_annotation_only')}
+    retained = []
+    for row in result:
+        if row.get('_annotation_only'):
+            if row['_annotation_ids'] in seen:
+                continue
+            seen.add(row['_annotation_ids'])
+        retained.append(row)
+    return retained
+
+
+def inputs_unannotated(ledger, refs):
+    """Check exact input membership, including retained withdrawn annotations.
+
+    Callers separately validate source ownership. This small current read also
+    serves the existing native freshness round trip; it adds no revision store.
+    """
+    membership = {}
+    for ref in refs:
+        membership.setdefault(ref['source_id'], set()).add(ref['input_message_hash'])
+    if not membership:
+        return True
+    with closing(ledger._connect()) as conn:
+        rows = conn.execute('SELECT target_source_id,target_message_hashes_json '
+            'FROM source_annotations WHERE target_source_id IN ('
+            + ','.join('?' for _ in membership) + ')', list(membership))
+        return not any(membership[row[0]].intersection(json.loads(row[1])) for row in rows)
+
+
+def current_candidates(ledger, candidates, *, contact_id, session_id):
+    """Do not publish stale evidence after a correction changes during ranking."""
+    required = [ref for row in candidates for ref in row.get('_annotation_source_refs', [])]
+    if not required:
+        return candidates
+    current = {r['source_id']: r['source_version'] for r in ledger.source_references(
+        [r['source_id'] for r in required], contact_id=contact_id, session_id=session_id)}
+    notes = {}
+    with closing(ledger._connect()) as conn:
+        for identifier, version in current.items():
+            notes[identifier] = {row[0]: set(json.loads(row[1])) for row in conn.execute('''SELECT annotation_source_id,target_message_hashes_json
+                FROM source_annotations WHERE target_source_id=? AND target_version=?''', (identifier, version))}
+    return [row for row in candidates if all(current.get(ref['source_id']) == ref['source_version']
+            for ref in row.get('_annotation_source_refs', [])) and (
+                not row.get('_annotation_source_refs') or set(row['_annotation_ids']) == set().union(
+                    *({identifier for identifier, hashes in notes.get(ref['source_id'], {}).items()
+                       if hashes.intersection(row['_annotation_message_hashes'].get(ref['source_id'], []))}
+                      for ref in row['_annotation_source_refs'])))]

apsimo/turns/source_attribution.py

@@ -0,0 +1,154 @@
+"""Explicit participant corrections without rewriting or erasing source text.
+
+The host authorizes the exact old/new people and selected sources. This module
+owns the source transaction; contact handles live in their existing store and
+are reconciled separately using the same operation ID. No source is inferred
+from a name, similarity, session or contact-wide history sweep.
+"""
+from contextlib import closing
+from datetime import datetime, timezone
+import hashlib
+import json
+
+
+def initialize(conn):
+    conn.execute('''CREATE TABLE IF NOT EXISTS source_attribution_operations (
+        operation_id TEXT PRIMARY KEY,request_sha256 TEXT NOT NULL,
+        result_json TEXT NOT NULL,recorded_at TEXT NOT NULL)''')
+    conn.execute('''CREATE TABLE IF NOT EXISTS source_attribution_revisions (
+        operation_id TEXT NOT NULL,source_id TEXT NOT NULL,old_contact_id TEXT NOT NULL,
+        contact_id TEXT NOT NULL,original_digest TEXT NOT NULL,source_version TEXT NOT NULL,
+        PRIMARY KEY(operation_id,source_id))''')
+    conn.execute('CREATE INDEX IF NOT EXISTS attribution_source ON source_attribution_revisions(source_id)')
+    conn.execute('''CREATE TABLE IF NOT EXISTS source_attribution_invalidations (
+        source_id TEXT NOT NULL,corrected_source_id TEXT NOT NULL,operation_id TEXT NOT NULL,
+        PRIMARY KEY(source_id,corrected_source_id,operation_id))''')
+
+
+def correct(ledger, *, operation_id, performed_by, old_contact_id, contact_id,
+            source_ids, evidence_refs):
+    """Correct an explicit source set and invalidate derived interpretations.
+
+    The original ingest digest, messages, media links, session and timestamps
+    remain unchanged. Changing the participant invalidates cached source views
+    and their current projections; it does not adopt old judgments for a new
+    person. Returned refs let other stores purge their own source projections.
+    """
+    from apsimo.contacts.identity_links import _refs, _json
+    from .idempotency import canonical_turn_digest, SourceErased
+    selected, evidence = _refs(source_ids), _refs(evidence_refs)
+    if not selected or not evidence or old_contact_id == contact_id:
+        raise ValueError('invalid_source_attribution')
+    for value in (operation_id, performed_by, old_contact_id, contact_id):
+        if not isinstance(value, str) or not value.strip() or len(value) > 256:
+            raise ValueError('invalid_source_attribution')
+    request_hash = hashlib.sha256(_json([performed_by, old_contact_id, contact_id, selected, evidence]).encode()).hexdigest()
+    with closing(ledger._connect()) as conn, conn:
+        conn.execute('BEGIN IMMEDIATE')
+        initialize(conn)
+        prior = conn.execute('SELECT * FROM source_attribution_operations WHERE operation_id=?', (operation_id,)).fetchone()
+        if prior:
+            if prior['request_sha256'] != request_hash:
+                raise ValueError('source_attribution_operation_conflict')
+            return json.loads(prior['result_json'])
+        rows = []
+        for sid in selected:
+            if conn.execute('SELECT 1 FROM source_erasures WHERE turn_id=?', (sid,)).fetchone():
+                raise SourceErased('source_erased')
+            row = conn.execute("SELECT * FROM turn_sources WHERE turn_id=? AND contact_id=? AND scope='person'",
+                               (sid, old_contact_id)).fetchone()
+            if row is None:
+                raise ValueError('source_attribution_preimage_changed')
+            rows.append(row)
+        # Discover source-linked descendant answers for invalidation, not silent
+        # reassignment. Their original prose remains historical source evidence.
+        descendants = set()
+        pending = set(selected)
+        candidates = conn.execute("SELECT turn_id,messages_json FROM turn_sources WHERE contact_id=?", (old_contact_id,)).fetchall()
+        while pending:
+            found = set()
+            for row in candidates:
+                if row['turn_id'] in selected or row['turn_id'] in descendants:
+                    continue
+                if any(ref.get('source_id') in pending for message in json.loads(row['messages_json'])
+                       for ref in message.get('_supplied_sources', [])):
+                    found.add(row['turn_id'])
+            descendants.update(found)
+            pending = found
+        affected = sorted(set(selected) | descendants)
+        for sid in descendants:
+            # Existing projection invalidation table owns graph/ToM cleanup.
+            for original in selected:
+                conn.execute('INSERT OR IGNORE INTO source_projection_erasures VALUES (?,?)', (sid, original))
+                conn.execute('INSERT OR IGNORE INTO source_attribution_invalidations VALUES (?,?,?)',
+                             (sid, original, operation_id))
+        from apsimo.beliefs.source_projection import erase_removed as erase_claims, enqueue
+        from apsimo.self_model.perspective import erase_removed as erase_preferences
+        from apsimo.self_model.judgments import erase_removed as erase_judgments
+        from .source_vectors import enqueue as enqueue_vectors
+        for row in rows:
+            sid = row['turn_id']
+            messages = json.loads(row['messages_json'])
+            prior_job = conn.execute('SELECT timezone FROM source_claim_jobs WHERE turn_id=?', (sid,)).fetchone()
+            conn.execute('INSERT INTO source_attribution_revisions VALUES (?,?,?,?,?,?)',
+                (operation_id, sid, old_contact_id, contact_id, row['content_sha256'], canonical_turn_digest(messages)))
+            # Revoke claim-worker leases before changing their input attribution.
+            erase_claims(conn, sid, row['session_id'], [])
+            erase_preferences(conn, sid, row['session_id'], [])
+            erase_judgments(conn, sid, row['session_id'], [])
+            conn.execute('UPDATE turn_sources SET contact_id=? WHERE turn_id=?', (contact_id, sid))
+            conn.execute('UPDATE turn_ingestion SET response_json=NULL,error=NULL WHERE turn_id=?', (sid,))
+            # Preserve admission and timezone. Reviewed source-only imports
+            # must not start learning merely because their identity was fixed.
+            if prior_job:
+                enqueue(conn, sid, messages, scope=row['scope'], timezone_name=prior_job['timezone'])
+            enqueue_vectors(conn, sid)
+        for sid in descendants:
+            row = conn.execute('SELECT session_id FROM turn_sources WHERE turn_id=?', (sid,)).fetchone()
+            if row:
+                conn.execute('UPDATE turn_ingestion SET response_json=NULL,error=NULL WHERE turn_id=?', (sid,))
+                erase_claims(conn, sid, row['session_id'], [])
+                erase_preferences(conn, sid, row['session_id'], [])
+                erase_judgments(conn, sid, row['session_id'], [])
+        try:
+            from apsimo.self_model.appraisals import invalidate_source_attribution
+        except ModuleNotFoundError as exc:
+            if exc.name != 'apsimo.self_model.appraisals':
+                raise
+        else:
+            invalidate_source_attribution(conn, affected, old_contact_id, contact_id)
+        result = {'schema': 'SourceAttributionCorrectionV1', 'operation_id': operation_id,
+            'old_contact_id': old_contact_id, 'contact_id': contact_id,
+            'source_ids': selected, 'affected_source_ids': affected,
+            'invalidated_source_ids': sorted(descendants), 'evidence_refs': evidence,
+            'recorded_at': datetime.now(timezone.utc).isoformat(), 'performed_by': performed_by,
+            'authority_granted': False, 'source_text_preserved': True}
+        conn.execute('INSERT INTO source_attribution_operations VALUES (?,?,?,?)',
+                     (operation_id, request_hash, _json(result), result['recorded_at']))
+        return result
+
+
+def history(ledger, *, source_id, contact_id):
+    """Correction provenance only for the source's currently authorized person."""
+    with closing(ledger._connect()) as conn:
+        if not conn.execute('SELECT 1 FROM sqlite_master WHERE name=?', ('source_attribution_revisions',)).fetchone():
+            return []
+        if not conn.execute('SELECT 1 FROM turn_sources WHERE turn_id=? AND contact_id=?', (source_id, contact_id)).fetchone():
+            return []
+        rows = conn.execute('''SELECT r.*,o.recorded_at FROM source_attribution_revisions r
+            JOIN source_attribution_operations o USING(operation_id) WHERE r.source_id=?
+            ORDER BY o.recorded_at,r.operation_id''', (source_id,)).fetchall()
+        return [dict(row) for row in rows]
+
+
+def is_invalidated(conn, source_id):
+    if not conn.execute("SELECT 1 FROM sqlite_master WHERE name='source_attribution_invalidations'").fetchone():
+        return False
+    return bool(conn.execute('SELECT 1 FROM source_attribution_invalidations WHERE source_id=? LIMIT 1',
+                             (source_id,)).fetchone())
+
+
+def visible_hits(ledger, hits):
+    """Drop stale derived-answer copies, never the corrected direct evidence."""
+    with closing(ledger._connect()) as conn:
+        return [hit for hit in hits if not is_invalidated(conn, hit.get('turn_id') or hit.get('source_turn_id'))]