apsimo 1.3.0__py3-none-any.whl

apsimo/self_model/runtime_forecasts.py

@@ -0,0 +1,296 @@
+"""Prospective native task turnaround learning, without quality claims.
+
+Attachment is the prediction origin, so turnaround includes queue delay. Native
+run elapsed time is retained separately. Hermes' ledger cannot attest which
+processor actually served a request; configured overrides are not substituted.
+"""
+from contextlib import closing
+from datetime import datetime, timezone
+import hashlib
+import json
+import logging
+import math
+import time
+
+from apsimo import get_state_dir
+from apsimo.turns import get_turn_idempotency_ledger
+from apsimo.turns.idempotency import SourceErased
+from .expectations import expectations_enabled
+
+logger = logging.getLogger(__name__)
+VERSION = 'native-task-forecast-v1'
+DECISION_VERSION = 'native-task-inspection-shadow-v1'
+
+
+def _digest(value):
+    return hashlib.sha256(json.dumps(value, sort_keys=True, separators=(',', ':')).encode()).hexdigest()
+
+
+def _identity(native):
+    return {key: native[key] for key in ('source_home_id', 'native_board', 'native_task_id')}
+
+
+def _reference(source_id):
+    return 'receipt:'+source_id
+
+
+def _current(ledger, references, versions, owner):
+    ids = [r.removeprefix('receipt:') for r in references]
+    current = {r['source_id']:r['source_version'] for r in ledger.source_references(
+        ids, contact_id=owner, session_id='')}
+    if not all(current.get(identifier) == versions.get(_reference(identifier))
+               and not ledger.is_projection_erased(identifier) for identifier in ids):
+        return False
+    with closing(ledger._connect()) as db:
+        for identifier in ids:
+            if db.execute('SELECT 1 FROM source_annotations WHERE target_source_id=? LIMIT 1', (identifier,)).fetchone():
+                return False
+    return True
+
+
+def _retain(ledger, *, source_id, owner, native, facts, occurred_at, dependencies=None):
+    # First observation survives replay. Native configuration can change later;
+    # never rebind an old receipt to whichever model is configured today.
+    with closing(ledger._connect()) as db:
+        exists = db.execute('SELECT 1 FROM turn_sources WHERE turn_id=?', (source_id,)).fetchone()
+    if not exists:
+        ledger.record_source(source_id, contact_id=owner,
+            session_id='native-runtime:'+native['native_task_id'],
+            occurred_at=datetime.fromtimestamp(occurred_at, timezone.utc).isoformat(),
+            messages=[{'role':'assistant', '_native_runtime_observation':VERSION, '_native_forecast_facts':facts,
+                **({'_supplied_sources': [{'source_id': r.removeprefix('receipt:'), 'source_version': v}
+                                         for r, v in dependencies.items()]} if dependencies else {}),
+                'content':'Runtime-owned task forecast/lifecycle observation. This is not an owner statement, '
+                          'successful output evaluation, or permission for any action.\n'+json.dumps(facts, sort_keys=True)}],
+            derive_claims=False)
+    refs = ledger.source_references([source_id], contact_id=owner, session_id='')
+    if not refs or ledger.is_projection_erased(source_id):
+        raise SourceErased('runtime forecast evidence unavailable')
+    with closing(ledger._connect()) as db:
+        message = json.loads(db.execute('SELECT messages_json FROM turn_sources WHERE turn_id=?', (source_id,)).fetchone()[0])[0]
+    if message.get('_native_runtime_observation') != VERSION or message.get('_native_forecast_facts', {}).get('identity') != _identity(native):
+        raise ValueError('runtime forecast source binding conflict')
+    return {_reference(source_id):refs[0]['source_version']}, message['_native_forecast_facts']
+
+
+def _outcome_facts(ledger, outcome):
+    if ledger is None or outcome is None:
+        return {}
+    with closing(ledger._connect()) as db:
+        row = db.execute('SELECT messages_json FROM turn_sources WHERE turn_id=?',
+                         (outcome['receipt_ref'].removeprefix('receipt:'),)).fetchone()
+    facts = json.loads(row[0])[0].get('_native_forecast_facts', {}) if row else {}
+    return facts if facts.get('version') == VERSION and facts.get('kind') == 'duration_outcome' else {}
+
+
+def _comparable(configuration, outcome_facts):
+    observed = outcome_facts.get('processor_observation') or {}
+    return bool(configuration and observed.get('configuration') == configuration
+                and observed.get('complete_observed_pairs') and observed.get('served_model'))
+
+
+def _parts(review, native, state, owner):
+    from apsimo.api.routers import host
+    engine = host._expectations
+    if engine is None or not expectations_enabled():
+        return None
+    selection = (review.get('native_work') or {}).get('outcome_learning') or {}
+    if selection.get('version') != 'native-runtime-observation-v1':
+        return None
+    identity = _identity(native)
+    forecast_id = 'native-task:'+_digest(identity)
+    ledger = get_turn_idempotency_ledger(get_state_dir())
+    return engine.store, ledger, selection, identity, forecast_id
+
+
+def attach(review, native, state, owner):
+    """Called after a verified prospective blocked task binding, before promote."""
+    parts = _parts(review, native, state, owner)
+    if parts is None:
+        return {'status':'disabled_or_unselected'}
+    store, ledger, selection, identity, fid = parts
+    existing = store.forecast_history(fid)['forecasts']
+    if existing:
+        return {'status':'existing', 'forecast_id':fid, 'horizon':existing[0]['horizon']}
+    if state['status'] != 'blocked' or state['attempt_count'] != 0:
+        return {'status':'not_prospective'}
+    bound = datetime.fromisoformat(selection['bound_at']).timestamp()
+    # Task/run timestamps have one-second precision. The no-runs binding above
+    # establishes ordering within that second; retain the precise bound too.
+    origin = math.floor(bound)
+    now = time.time()
+    config = state['forecast_configuration']
+    budget = config.get('runtime_budget_seconds')
+    prior = float(budget) if isinstance(budget, (int, float)) and budget > 0 else 480.
+    cohort = 'native-review:'+review['review']['action']
+    def current(prediction, outcome):
+        return (_current(ledger, prediction.evidence_refs, prediction.detail['source_versions'], owner)
+                and _current(ledger, outcome['evidence_refs'], outcome['source_versions'], owner)
+                and prediction.detail['model_provenance']['capabilities'] == config
+                and _comparable(config, _outcome_facts(ledger, outcome)))
+    estimate = store.estimate_duration(domain='task_duration',cohort=cohort,
+        subject_person_id=owner,viewer_scope='owner',prior_seconds=prior,
+        now=now,evidence_is_current=current)
+    horizon = origin + estimate['seconds']
+    if horizon <= now:
+        return {'status':'binding_too_old_for_prospective_forecast'}
+    source_id = 'native-forecast-binding:'+_digest(identity)
+    versions, retained = _retain(ledger,source_id=source_id,owner=owner,native=native,occurred_at=bound,
+        facts={'version':VERSION,'kind':'prospective_binding','identity':identity,
+               'bound_at':selection['bound_at'],'configuration':config,
+               'registered_action':review['review']['action'],
+               'estimate':estimate,'measurement':'attachment_to_terminal_turnaround'})
+    # Recovery after source capture uses the retained original estimate, not
+    # a later improved estimate presented as the earlier prediction.
+    estimate = retained['estimate']
+    horizon = origin + estimate['seconds']
+    config = retained['configuration']
+    prediction = store.issue_forecast(forecast_id=fid,subject='task:'+native['native_task_id'],
+        domain='task_duration',expectation='The accepted native review completes within its turnaround estimate',
+        confidence=estimate['confidence'],horizon=horizon,origin_at=origin,issued_at=origin,
+        evidence_refs=list(versions),source_versions=versions,source_kind='task_receipt',
+        cohort=cohort,method=estimate['method'],
+        model_provenance={'requested_role':'native_default_worker','served_model':None,
+                          'model_revision':None,'capabilities':config,'fallback':None},
+        subject_person_id=owner,viewer_scope='owner',shareability='owner_private',
+        conditions={'measurement':'attachment_to_terminal_turnaround','timestamp_precision_seconds':1,
+                    'bound_at':selection['bound_at'],'estimate':estimate})
+    return {'status':'issued','forecast_id':fid,'horizon':prediction.horizon,'estimate':estimate}
+
+
+def observe(review, native, state, owner):
+    """Readback settles duration only. Pauses/failures are explicit censoring."""
+    parts = _parts(review, native, state, owner)
+    if parts is None:
+        return {'status':'disabled_or_unselected'}
+    store, ledger, selection, identity, fid = parts
+    history = store.forecast_history(fid)
+    if not history['forecasts']:
+        return {'status':'no_prospective_forecast'}
+    prediction = history['forecasts'][0]
+    observed = state.get('duration_observation')
+    if not observed or not isinstance(observed.get('ended_at'), (int,float)):
+        return {'status':'pending','forecast_id':fid}
+    ended = observed['ended_at']
+    if ended < math.floor(datetime.fromisoformat(selection['bound_at']).timestamp()) or ended > time.time():
+        return {'status':'unqualified_native_time'}
+    source_id = 'native-forecast-outcome:'+_digest({**identity,'native_run_id':state.get('native_run_id'),
+        'outcome':observed['outcome'],'ended_at':ended})
+    receipt = _reference(source_id)
+    if any(o['receipt_ref'] == receipt for o in history['outcomes']):
+        return {'status':'observed','forecast_id':fid,'receipt_ref':receipt}
+    valid = _current(ledger,prediction['evidence_refs'],prediction['detail']['source_versions'],owner)
+    paused = any(o['reason'] == 'paused' for o in history['outcomes'])
+    complete = state['status'] == 'done' and state.get('completed_run') and valid and not paused
+    reason = '' if complete else 'source_retracted' if not valid else 'paused' if paused or (state['status']=='blocked' and not state.get('gave_up')) else 'cancelled' if state['status'] in {'archived','cancelled'} else 'unavailable'
+    from .runtime_models import summarize
+    processor = summarize(ledger, owner, native, state.get('native_run_id'))
+    versions, retained = _retain(ledger,source_id=source_id,owner=owner,native=native,occurred_at=ended,
+        dependencies=processor['source_versions'],
+        facts={'version':VERSION,'kind':'duration_outcome','identity':identity,
+               'native_run_id':state.get('native_run_id'),'observation':observed,
+               'processor_observation':processor,
+               'native_status':state['status'],'forecast_id':fid,
+               'turnaround_seconds':ended-prediction['detail']['origin_at'],
+               'measurement':'attachment_to_terminal_turnaround','quality_evaluated':False})
+    versions = {**versions, **retained.get('processor_observation', {}).get('source_versions', {})}
+    result = store.record_forecast_outcome(forecast_id=fid,receipt_ref=receipt,
+        evidence_refs=list(versions),source_versions=versions,source_kind='task_receipt',
+        observed_at=ended,subject_person_id=owner,viewer_scope='owner',shareability='owner_private',
+        status='observed' if complete else 'censored',value=True if complete else None,
+        reason=reason,previous_revision=len(history['outcomes']))
+    return {'status':'observed','forecast_id':fid,'outcome_status':result['status'],
+            'receipt_ref':receipt,'quality_evaluated':False}
+
+
+def project(review, native, state, owner, *, now=None):
+    """Project one existing forecast on a normal work read, without side effects.
+
+    The original horizon, not a revised or recomputed estimate, supplies the
+    shadow inspection decision. No suggestion, polling, retry or notification
+    is enabled by this projection, even when its forecast has many samples.
+    """
+    parts = _parts(review, native, state, owner)
+    if parts is None:
+        return {'status':'disabled_or_unselected'}
+    store, ledger, _, _, fid = parts
+    history = store.forecast_history(fid)
+    if not history['forecasts']:
+        return {'status':'no_prospective_forecast'}
+    prediction = history['forecasts'][0]
+    detail = prediction['detail']
+    if (prediction['subject_person_id'] != owner or prediction['viewer_scope'] != 'owner'
+            or not _current(ledger,prediction['evidence_refs'],detail['source_versions'],owner)):
+        return {'status':'source_unavailable'}
+    stamp = time.time() if now is None else float(now)
+    if not math.isfinite(stamp) or stamp < detail['origin_at']:
+        return {'status':'unqualified_observation_time'}
+    estimate = detail['conditions']['estimate']
+    prior_horizon = detail['origin_at'] + estimate['prior_seconds']
+    recorded_configuration = detail['model_provenance']['capabilities']
+    same_conditions = bool(recorded_configuration) and state.get('forecast_configuration') == recorded_configuration
+    status = state.get('status')
+    active = status in {'ready','running'}
+    latest = history['outcomes'][-1] if history['outcomes'] else None
+    outcome_facts = _outcome_facts(ledger, latest)
+    processor = outcome_facts.get('processor_observation') or {}
+    if latest:
+        # Later profile/task edits do not rewrite the conditions witnessed by
+        # the terminal receipt. Original future processor fields stay unknown.
+        same_conditions = bool(recorded_configuration) and recorded_configuration == processor.get('configuration')
+    outcome_current = latest is None or _current(ledger,latest['evidence_refs'],latest['source_versions'],owner)
+    if not outcome_current:
+        decision = prior_decision = 'source_unavailable'
+    elif latest and latest['status'] == 'censored':
+        decision = prior_decision = 'censored'
+    elif not active:
+        decision = prior_decision = 'terminal' if status in {'done','archived','cancelled'} else 'not_running'
+    elif not same_conditions:
+        decision = prior_decision = 'conditions_unknown_or_changed'
+    else:
+        decision = 'inspect_recorded_state' if stamp >= prediction['horizon'] else 'continue_waiting'
+        prior_decision = 'inspect_recorded_state' if stamp >= prior_horizon else 'continue_waiting'
+    result = {'status':'shadow','version':DECISION_VERSION,
+        'decision_id':'native-inspection:'+_digest({'forecast_id':fid,'horizon':prediction['horizon']}),
+        'forecast_id':fid,'original_revision':prediction['detail']['revision'],
+        'original_horizon':prediction['horizon'],'prior_horizon':prior_horizon,
+        'observed_at':stamp,'native_status':status,'decision':decision,
+        'prior_decision':prior_decision,'changed_from_prior':decision != prior_decision,
+        'sample_n':estimate['sample_n'],'uncertain':estimate['uncertain'],
+        'configuration_matches':same_conditions,
+        'conditions_comparable':bool(outcome_current and latest and latest['status'] == 'observed'
+                                     and _comparable(recorded_configuration, outcome_facts)),
+        'served_model':processor.get('served_model'),
+        'original_served_model':detail['model_provenance']['served_model'],
+        'processor_observation':processor,
+        'evidence_refs':prediction['evidence_refs'],'source_versions':detail['source_versions'],
+        'suggestion_enabled':False,'quality_evaluated':False,
+        'enable_criteria':{'cohort_must_be_closed':True,'minimum_comparable_terminal_receipts':10,
+            'lower_mean_absolute_error':True,'no_more_premature_inspections':True,
+            'no_greater_mean_inspection_lateness':True}}
+    if latest and latest['status'] == 'observed' and latest['value'] is True and outcome_current:
+        ended = latest['observed_at']
+        result['comparison'] = {
+            'conditions_comparable':result['conditions_comparable'],
+            'observed_response_model':processor.get('served_model'),
+            'receipt_ref':latest['receipt_ref'],'outcome_source_versions':latest['source_versions'],
+            'turnaround_seconds':ended-detail['origin_at'],
+            'forecast_absolute_error_seconds':abs(ended-prediction['horizon']),
+            'prior_absolute_error_seconds':abs(ended-prior_horizon),
+            'forecast_premature_inspection':prediction['horizon'] < ended,
+            'prior_premature_inspection':prior_horizon < ended,
+            'forecast_inspection_lateness_seconds':max(0.,prediction['horizon']-ended),
+            'prior_inspection_lateness_seconds':max(0.,prior_horizon-ended),
+            'counterfactual_horizon_comparison':True,'projection_added_status_calls':0}
+    return result
+
+
+def safe(operation, review, native, state, owner):
+    """A forecast observer failure is visible but cannot stall accepted work."""
+    try:
+        return operation(review,native,state,owner)
+    except SourceErased:
+        return {'status':'source_unavailable'}
+    except Exception as error:
+        logger.warning('Native task forecast observer unavailable: %s', type(error).__name__)
+        return {'status':'unavailable','error_type':type(error).__name__}

apsimo/self_model/runtime_models.py

@@ -0,0 +1,67 @@
+"""Canonical, prospective native request metadata; no transcript classifier."""
+from contextlib import closing
+import json
+import time
+
+from .runtime_forecasts import VERSION, _current, _digest, _identity, _retain
+
+
+def _prefix(native, run_id):
+    return 'native-model:'+_digest({**_identity(native), 'native_run_id': run_id})+':'
+
+
+def retain(ledger, owner, native, state, value):
+    """The API caller already verified the active native run and claim lock."""
+    request = {key: value.get(key) for key in
+               ('api_request_id', 'phase', 'requested_model', 'provider', 'response_model')}
+    if request['phase'] != 'response':
+        request['response_model'] = None
+    source_id = _prefix(native, native['native_run_id'])+_digest([request['api_request_id'], request['phase']])
+    versions, retained = _retain(ledger, source_id=source_id, owner=owner, native=native,
+        occurred_at=time.time(), facts={'version': VERSION, 'kind': 'model_request',
+            'identity': _identity(native), 'native_run_id': native['native_run_id'],
+            'request': request, 'configuration': state['forecast_configuration']})
+    if retained['request'] != request:
+        raise ValueError('native_model_observation_conflict')
+    return {'accepted': True, 'evidence_refs': list(versions),
+            'identity_basis': 'provider_reported_response_model_not_weight_attestation'}
+
+
+def summarize(ledger, owner, native, run_id):
+    """Pair observed starts/ends; missing, erased and mixed remain explicit."""
+    prefix = _prefix(native, run_id)
+    with closing(ledger._connect()) as db:
+        rows = db.execute('SELECT turn_id,messages_json FROM turn_sources WHERE contact_id=? '
+                          'AND substr(turn_id,1,?)=? ORDER BY turn_id LIMIT 257',
+                          (owner, len(prefix), prefix)).fetchall()
+        erased = db.execute('SELECT 1 FROM source_erasures WHERE substr(turn_id,1,?)=? LIMIT 1',
+                            (len(prefix), prefix)).fetchone()
+    refs = ledger.source_references([r['turn_id'] for r in rows], contact_id=owner, session_id='')
+    versions = {'receipt:'+r['source_id']: r['source_version'] for r in refs}
+    valid = bool(rows) and len(refs) == len(rows) and len(rows) <= 256 and not erased and _current(ledger, list(versions), versions, owner)
+    requests, configurations, models, requested = {}, [], set(), set()
+    for row in rows:
+        facts = json.loads(row['messages_json'])[0].get('_native_forecast_facts', {})
+        if (facts.get('version') != VERSION or facts.get('kind') != 'model_request'
+                or facts.get('identity') != _identity(native) or facts.get('native_run_id') != run_id):
+            valid = False
+            continue
+        request = facts['request']
+        requests.setdefault(request['api_request_id'], {})[request['phase']] = request
+        configurations.append(facts['configuration'])
+        if request.get('requested_model'):
+            requested.add(request['requested_model'])
+        if request['phase'] == 'response' and request.get('response_model'):
+            models.add(request['response_model'])
+    complete = valid and all(set(v) in ({'start', 'response'}, {'start', 'error'}) for v in requests.values())
+    missing_model = any('response' in v and not v['response'].get('response_model') for v in requests.values())
+    same_configuration = bool(configurations) and all(c == configurations[0] for c in configurations)
+    return {'basis': 'provider_reported_response_model_not_weight_attestation',
+        'coverage': 'registered native review API requests only; auxiliary and uninstrumented calls unknown',
+        'request_count': len(requests), 'complete_observed_pairs': bool(complete),
+        'response_models': sorted(models), 'requested_models': sorted(requested),
+        'served_model': next(iter(models)) if complete and not missing_model and len(models) == 1 else None,
+        'model_state': 'unknown' if not complete or missing_model or not models else 'mixed' if len(models) > 1 else 'observed',
+        'configuration': configurations[0] if same_configuration else None,
+        'configuration_state': 'observed' if same_configuration and complete else 'unknown_or_changed',
+        'evidence_refs': list(versions), 'source_versions': versions}

apsimo/self_model/settlement.py

@@ -0,0 +1,207 @@
+"""Source settlement: resolving a concern settles what the concern points at.
+
+A concern raised from a durable source (an overdue commitment, an anomaly, a
+stale goal) carries that source in its ``sources`` list as ``"<kind>:<id>"``.
+Resolving only the concern leaves the source open, and whatever ingests that
+source re-raises the concern on the next tick — the owner's resolve silently
+undone minutes later. The registry maps a source kind to a settle callback so
+every surface (owner deck, agent tool, MCP, API) closes the whole chain with
+one call.
+
+Deployment-agnostic: the server wires settlers for whatever stores it runs;
+unknown source kinds are skipped, and one failing settler never blocks the
+others.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import threading
+from typing import Any, Callable, Dict, List, Mapping, Optional
+
+logger = logging.getLogger(__name__)
+
+Settler = Callable[..., Optional[Dict[str, Any]]]
+
+_SETTLERS: Dict[str, Settler] = {}
+_RETRY_SAFE: set[str] = set()
+_REGISTRY_LOCK = threading.RLock()
+
+
+class SettlementRetryUnsafe(ValueError):
+    """One or more sources lack an exact operation-bound retry contract."""
+
+    def __init__(self, sources: List[str]) -> None:
+        super().__init__("cascade recovery requires retry-safe source settlers")
+        self.sources = list(sources)
+
+
+class _SettlementOperationUnverified(ValueError):
+    settlement_error_code = "operation_unverified"
+
+
+def source_operation_id(operation_root: str, source: str) -> str:
+    """Derive the stable per-intent/per-source idempotency identity."""
+
+    root = str(operation_root or "").strip()
+    ref = str(source or "").strip()
+    if not root or not ref:
+        raise ValueError("source settlement operation identity is incomplete")
+    digest = hashlib.sha256(f"{root}\0{ref}".encode("utf-8")).hexdigest()
+    return f"concern-source-operation:{digest}"
+
+
+def register_settler(
+    kind: str,
+    fn: Settler,
+    *,
+    retry_safe: bool = False,
+) -> None:
+    """Register the settle callback for a source kind (e.g. "commitment").
+
+    Retry-safe callbacks additionally receive a stable ``operation_id`` and
+    must bind it together with outcome, note, and resolver to the durable
+    transition.  Their detail must attest those exact fields.  This is a
+    stronger contract than merely returning the same terminal state twice.
+    """
+    if type(retry_safe) is not bool:
+        raise ValueError("settler retry_safe must be boolean")
+    with _REGISTRY_LOCK:
+        _SETTLERS[kind] = fn
+        if retry_safe:
+            _RETRY_SAFE.add(kind)
+        else:
+            _RETRY_SAFE.discard(kind)
+
+
+def registered_kinds() -> List[str]:
+    with _REGISTRY_LOCK:
+        return sorted(_SETTLERS)
+
+
+def _settle_sources(
+    sources: List[str],
+    *,
+    callbacks: Mapping[str, Settler],
+    retry_safe_kinds: set[str],
+    outcome: str,
+    note: str,
+    resolved_by: str,
+    operation_root: Optional[str],
+) -> List[Dict[str, Any]]:
+    results: List[Dict[str, Any]] = []
+    for src in sources:
+        kind, _, source_id = str(src).partition(":")
+        fn = callbacks.get(kind)
+        if fn is None or not source_id:
+            continue
+        entry: Dict[str, Any] = {"source": src, "settled": False}
+        operation_id = None
+        try:
+            kwargs: Dict[str, Any] = {
+                "outcome": outcome,
+                "note": note,
+                "resolved_by": resolved_by,
+            }
+            if operation_root is not None and kind in retry_safe_kinds:
+                operation_id = source_operation_id(operation_root, src)
+                kwargs["operation_id"] = operation_id
+            detail = fn(source_id, **kwargs)
+            if detail is not None:
+                if operation_id is not None:
+                    note_digest = hashlib.sha256(note.encode("utf-8")).hexdigest()
+                    if not isinstance(detail, Mapping) or any((
+                        detail.get("operation_id") != operation_id,
+                        detail.get("outcome") != outcome,
+                        detail.get("note_digest") != note_digest,
+                        detail.get("resolved_by") != resolved_by,
+                    )):
+                        raise _SettlementOperationUnverified(
+                            "retry-safe settler did not attest the bound operation"
+                        )
+                entry["settled"] = True
+                if isinstance(detail, Mapping):
+                    entry.update({
+                        key: value for key, value in detail.items()
+                        if key not in {
+                            "source", "settled", "error", "error_digest",
+                        }
+                    })
+        except Exception as exc:
+            logger.warning("settler for %s failed (%s)", src, type(exc).__name__)
+            error_code = getattr(exc, "settlement_error_code", "settler_error")
+            if error_code not in {
+                "operation_conflict", "operation_unverified", "settler_error",
+            }:
+                error_code = "settler_error"
+            entry["error"] = error_code
+            entry["error_digest"] = hashlib.sha256(
+                str(exc).encode("utf-8", errors="replace")
+            ).hexdigest()
+        results.append(entry)
+    return results
+
+
+def settle_sources(
+    sources: Optional[List[str]],
+    *,
+    outcome: str = "done",
+    note: str = "",
+    resolved_by: str = "owner",
+    operation_root: Optional[str] = None,
+) -> List[Dict[str, Any]]:
+    """Settle every recognized source reference. Returns one entry per source
+    that had a registered settler, with ``settled`` and any settler detail."""
+    with _REGISTRY_LOCK:
+        callbacks = dict(_SETTLERS)
+        retry_safe_kinds = set(_RETRY_SAFE)
+    return _settle_sources(
+        list(sources or []),
+        callbacks=callbacks,
+        retry_safe_kinds=retry_safe_kinds,
+        outcome=outcome,
+        note=note,
+        resolved_by=resolved_by,
+        operation_root=operation_root,
+    )
+
+
+def retry_safe_settle_sources(
+    sources: Optional[List[str]],
+    *,
+    operation_root: str,
+    outcome: str = "done",
+    note: str = "",
+    resolved_by: str = "owner",
+) -> List[Dict[str, Any]]:
+    """Explicitly retry only sources with exact operation-bound semantics.
+
+    The complete source set is validated before the first callback.  Unknown,
+    malformed, or merely state-idempotent settlers are rejected together and
+    remain pending for explicit reconciliation.
+    """
+
+    refs = list(sources or [])
+    unsafe: List[str] = []
+    with _REGISTRY_LOCK:
+        callbacks = dict(_SETTLERS)
+        retry_safe_kinds = set(_RETRY_SAFE)
+    for src in refs:
+        kind, separator, source_id = str(src).partition(":")
+        if (
+            not separator or not source_id or kind not in callbacks
+            or kind not in retry_safe_kinds
+        ):
+            unsafe.append(str(src))
+    if unsafe:
+        raise SettlementRetryUnsafe(unsafe)
+    return _settle_sources(
+        refs,
+        callbacks=callbacks,
+        retry_safe_kinds=retry_safe_kinds,
+        outcome=outcome,
+        note=note,
+        resolved_by=resolved_by,
+        operation_root=operation_root,
+    )