agentlinkops 0.6.11 → 0.6.13

package/cli/chronology.js

@@ -0,0 +1,39 @@
+import {readFile,writeFile,mkdir,copyFile,unlink} from 'node:fs/promises';
+import {constants} from 'node:fs';
+import {dirname,resolve} from 'node:path';
+import {loadConfig,ConfigError} from './config.js';
+import {cloudConnection} from './connection.js';
+import {createClient} from './client.js';
+import {freezeChronology,normalizeLocalSubmissions} from '../shared/monitoring-chronology-export.js';
+const help='agentlinkops chronology pull --watch-id ID [--limit 50] [--cursor TOKEN] [--all] [--out NEW_FILE] | export --pages FILE [--submissions FILE] [--out NEW_FILE]';
+async function output(value,args,{cwd,out}){
+ const text=JSON.stringify(value,null,2)+'\n';
+ if(!args.out){out(text.trimEnd());return;}
+ if(typeof args.out!=='string'||!args.out.trim())throw new ConfigError('--out requires a file');
+ const path=resolve(cwd,args.out),temp=`${path}.${crypto.randomUUID()}.tmp`;
+ await mkdir(dirname(path),{recursive:true});
+ try{await writeFile(temp,text,{flag:'wx',mode:0o600});await copyFile(temp,path,constants.COPYFILE_EXCL);}finally{await unlink(temp).catch(e=>{if(e.code!=='ENOENT')throw e;});}
+ out(`wrote ${path}`);
+}
+export async function chronologyMain(args,{cwd=process.cwd(),env=process.env,fetchImpl=globalThis.fetch,out=console.log}={}){
+ const command=args._[1],allowed=new Set(['_','tag','watch-id','limit','cursor','all','out','pages','submissions']);
+ if(args._.length!==2||args.tag?.length||Object.keys(args).some(key=>!allowed.has(key)))throw new ConfigError(help);
+ if(command==='export'){
+  if(typeof args.pages!=='string'||args['watch-id']!==undefined||args.limit!==undefined||args.cursor!==undefined||args.all!==undefined)throw new ConfigError(help);
+  const input=JSON.parse(await readFile(resolve(cwd,args.pages),'utf8')),pages=Array.isArray(input)?input:[input];
+  const localItems=args.submissions?await normalizeLocalSubmissions(JSON.parse(await readFile(resolve(cwd,args.submissions),'utf8')),pages[0]?.identity):[];
+  await output(await freezeChronology(pages,{localItems}),args,{cwd,out});return 0;
+ }
+ if(command!=='pull'||typeof args['watch-id']!=='string'||args.pages!==undefined||args.submissions!==undefined||args.all!==undefined&&args.all!==true)throw new ConfigError(help);
+ const limit=Number(args.limit??50);if(!Number.isInteger(limit)||limit<1||limit>100||args.cursor===true)throw new ConfigError(help);
+ const config=await loadConfig({cwd}),connection=cloudConnection(config,env);
+ if(!connection.projectId)throw new ConfigError('Connect this project before reading hosted chronology.');
+ const client=createClient({...connection,fetchImpl}),pages=[];let cursor=args.cursor;
+ do{
+  const page=await client.callCommand('get_placement_chronology',{watchId:args['watch-id'],limit,...(cursor?{cursor}: {})});
+  if(page.identity?.projectId!==connection.projectId||page.identity?.watchId!==args['watch-id']||connection.workspaceId&&page.identity?.workspaceId!==connection.workspaceId)throw new ConfigError('Chronology identity does not match the connected project and selected watch.');
+  pages.push(page);cursor=page.nextCursor;
+  if(pages.length===100&&args.all&&cursor)throw new ConfigError('Chronology exceeds the 100-page read bound. Pull explicit pages and export their qualified partial dataset.');
+ }while(args.all&&cursor);
+ await output(args.all?await freezeChronology(pages):pages[0],args,{cwd,out});return 0;
+}

package/cli/client.js

@@ -5,7 +5,7 @@ export {CloudError} from './cloud-error.js';
 // A small HTTP client for the cloud. Scoped keys only; no human session ever reaches here.
 // DP-0036-T13: the CLI names itself so the usage counters can tell it from other REST callers.
 // The version follows the plugin manifests; bump it with them.
-export const CLI_VERSION = '0.6.11';
+export const CLI_VERSION = '0.6.13';
 export const CLI_USER_AGENT = `agentlinkops-cli/${CLI_VERSION}`;
 const MAX_ATTEMPTS = 3;
 const MAX_RETRY_WAIT_MS = 5_000;

package/cli/fleet.js

@@ -6,54 +6,62 @@
 // and a summary that deduplicated them would silently pick one. So every number below is
 // per project, the only cross-project arithmetic is a sum of counts, and the output says so.
 //
-// "Earned" follows the ledger contract, not a status column: an entry is earned when its
-// latest OBSERVATION says present. A project with no observation file has earned nothing and
-// is reported as never checked rather than as zero links.
+// "Earned" follows known conclusive presence; a later inconclusive attempt is disclosed
+// separately. Activity is supplied explicitly per project, never discovered in another repo.
 import { readLedger } from './ledger.js';
-import { readObservations, latestByEntry } from './mirror.js';
+import { readObservations } from './mirror.js';
+import { readState } from './state.js';
+import { projectPlacements } from './placement-projection.js';
 
 const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
 
 /** One project's row. Everything is computed inside the project; nothing crosses the boundary. */
-export async function fleetProject(name, ledgerPath, observationsPath) {
+export async function fleetProject(name, ledgerPath, observationsPath, statePath = null) {
   const ledger = await readLedger(ledgerPath);
   if (ledger.missing) { const error = new Error(`no ledger at ${ledgerPath}`); error.code = 'NO_LEDGER'; throw error; }
   const byIntent = { wanted: 0, expected: 0, retired: 0 };
   for (const entry of ledger.entries) byIntent[entry.intent] = (byIntent[entry.intent] ?? 0) + 1;
 
   const { rows } = observationsPath ? await readObservations(observationsPath) : { rows: [] };
-  const latest = latestByEntry(rows);
-  let earned = 0, observed = 0;
-  for (const [id, row] of latest) {
-    if (!ledger.entries.some(entry => entry.id === id)) continue; // observations from another ledger's ids
-    observed++;
-    if (row.state === 'present') earned++;
-  }
-  const lastCheck = rows.length ? rows.map(row => row.checked_at).sort().at(-1) : null;
+  const state = statePath ? await readState(statePath) : null;
+  const eligible = ledger.entries.filter(entry => entry.intent !== 'retired');
+  const projected = projectPlacements(eligible, rows, { state });
+  const observed = projected.filter(item => item.latest_attempt).length;
+  const earned = projected.filter(item => item.current_state === 'present').length;
+  const newest = values => values.filter(Boolean).sort((a, b) => Date.parse(a) - Date.parse(b)).at(-1) ?? null;
   return {
     project: name, ledger: ledgerPath,
     entries: ledger.entries.length, ...byIntent,
     problems: ledger.problems.length,
     observed_entries: observed, earned,
-    never_checked: ledger.entries.filter(entry => entry.intent !== 'retired').length - observed,
-    last_observation: lastCheck,
+    never_checked: eligible.length - observed,
+    last_observation: newest(projected.map(item => item.evidence_observed_at)),
+    last_attempt_at: newest(projected.map(item => item.latest_attempt?.checked_at)),
+    last_success_at: newest(projected.map(item => item.last_successful_observation?.checked_at)),
+    last_link_verification_at: newest(projected.map(item => item.last_link_verification?.checked_at)),
+    uncertain_entries: projected.filter(item => item.uncertain).length,
+    activity_available: projected.some(item => item.activity_available),
+    activity_entries: projected.filter(item => item.activity_available).length,
+    coverage: { denominator: 'non_retired_ledger_entries', eligible_entries: eligible.length,
+      identity_unmatched_entries: projected.filter(item => item.identity_status === 'not_matched').length,
+      activity_input: statePath ? 'explicit_state_file' : 'not_supplied' },
     // Due volume, the same arithmetic the dogfood records use to price a fleet.
     implied_weekly_checks: byIntent.wanted + byIntent.expected * 7,
   };
 }
 
 /** Summons the fleet. Same numbers per project, one sum of counts, no merged intent. */
-export async function fleetSummary(projects, { observationsOf = {} } = {}) {
+export async function fleetSummary(projects, { observationsOf = {}, statesOf = {} } = {}) {
   const rows = [];
-  for (const { name, ledger } of projects) rows.push(await fleetProject(name, ledger, observationsOf[name] ?? null));
+  for (const { name, ledger } of projects) rows.push(await fleetProject(name, ledger, observationsOf[name] ?? null, statesOf[name] ?? null));
   const totals = rows.reduce((acc, row) => {
-    for (const key of ['entries', 'wanted', 'expected', 'retired', 'earned', 'observed_entries', 'never_checked', 'implied_weekly_checks']) {
+    for (const key of ['entries', 'wanted', 'expected', 'retired', 'earned', 'observed_entries', 'never_checked', 'uncertain_entries', 'activity_entries', 'implied_weekly_checks']) {
       acc[key] = (acc[key] ?? 0) + row[key];
     }
     return acc;
   }, {});
   return {
-    v: 1, projects: rows, totals,
+    v: 2, projects: rows, totals,
     // The sum answers "how big is the operation". It is not a merged view: the same platform
     // counted in two projects is two intents, and only a human can say which one they meant.
     intent_merged_across_repos: false,
@@ -75,6 +83,9 @@ export function renderFleet(summary, out = console.log) {
     + `${String(t.never_checked).padStart(13)}  (sum of counts)`);
   out('');
   out(`implied weekly check volume across the fleet: ${t.implied_weekly_checks}`);
+  for (const row of summary.projects) {
+    out(`${row.project}: latest attempt ${row.last_attempt_at ?? 'not recorded'}; last conclusive check ${row.last_success_at ?? 'not recorded'}; last link verification ${row.last_link_verification_at ?? 'not recorded'}; activity ${row.activity_available ? `${row.activity_entries} entr(ies)` : 'not available'}; uncertain ${row.uncertain_entries}`);
+  }
   if (summary.projects.some(row => row.problems)) {
     out(`ledger problems: ${summary.projects.map(row => `${row.project}=${row.problems}`).filter(s => !s.endsWith('=0')).join(', ')}`);
   }

package/cli/main.js

@@ -1,3 +1,5 @@
+import {projectPlacements} from './placement-projection.js';
+import {chronologyMain} from './chronology.js';
 import { acquireSyncLock } from './sync-lock.js';
 import {lifecycleMain} from './lifecycle.js';
 import {admissionMain} from './admission.js';
@@ -52,6 +54,8 @@ const USAGE = `agentlinkops — a backlink ledger that lives in your repository
                 [--mode local|hosted|external]  read-only setup plan; no account required
   agentlinkops add --source URL --target URL [--intent wanted|expected] [--scope …]
                 [--anchor TEXT] [--rel a,b] [--ref TEXT] [--tag t --tag t] [--note TEXT]
+  agentlinkops chronology pull --watch-id ID [--limit N] [--cursor TOKEN] [--all] [--out FILE]
+  agentlinkops chronology export --pages FILE [--submissions FILE] [--out FILE]
   agentlinkops index pull --watch-id ID [--limit N] [--before ID]
   agentlinkops lifecycle get|update|clear|renew|report
   agentlinkops admission list|add|update|remove|evaluate|reevaluate|receipt --project ID
@@ -63,7 +67,7 @@ const USAGE = `agentlinkops — a backlink ledger that lives in your repository
   agentlinkops import FILE --target DOMAIN [--from SUPPLIER] [--map source=COL,target=COL]
                 [--exact-url] [--no-subdomains] [--generated-at ISO] [--json]
   agentlinkops adopt CRM.sqlite [--scope exact|domain] [--write]
-  agentlinkops fleet --project NAME=LEDGER [--project …] [--observations-of NAME=FILE] [--json]
+  agentlinkops fleet --project NAME=LEDGER [--project …] [--observations-of NAME=FILE] [--state-of NAME=FILE] [--json]
   agentlinkops platforms [HOST] [--observations FILE]… [--benchmark FILE]… [--seed FILE]…
                 [--for-candidates FILE] [--json]
   agentlinkops context COMMAND…               first-party search context and site profile
@@ -100,7 +104,7 @@ const USAGE = `agentlinkops — a backlink ledger that lives in your repository
   agentlinkops adopt-result FILE [--intent wanted|expected]  save result to local ledger
   agentlinkops receipt add --file CLAIM.json   project.site declares public site hosts
   agentlinkops receipt history [--performance FILE.json]  claims, history and optional dated context
-  agentlinkops status [--json]
+  agentlinkops status [--all] [--json]
   agentlinkops diff [--json]
   agentlinkops report [--out FILE] [--title T] [--brand B] [--as-of ISO]
                 [--include-notes] [--include-retired] [--digest-only] [--json]
@@ -122,7 +126,7 @@ evidence · 2 usage, configuration or ledger error. Unknown is nonfailing by def
 Names: \`linktrail\` still runs this CLI, LINKTRAIL_* variables are still read, and an existing
 .linktrail/ directory is still used, each with a one-line notice, until the DP-0029 cutover.`;
 
-const parseArgs = argv => parseArguments(argv,["tag", "project", "observations-of", "observations", "benchmark", "seed"],{tag:[]});
+const parseArgs = argv => parseArguments(argv,["tag", "project", "observations-of", "state-of", "observations", "benchmark", "seed"],{tag:[]});
 
 const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
 
@@ -154,6 +158,7 @@ export async function main(argv = process.argv.slice(2), { cwd = process.cwd(),
     if (command === 'lifecycle') return await lifecycleMain(args,{cwd,env,fetchImpl,out,err});
     if (command === 'admission') { const config=await loadConfig({cwd}); return await admissionMain(argv.slice(1),{client:createClient({...cloudConnection(config,env),fetchImpl}),out,err}); }
     if (command === 'disavow') return await disavowMain(args,{cwd,env,fetchImpl,out});
+    if (command === 'chronology') return await chronologyMain(args,{cwd,env,fetchImpl,out});
     if (command === 'index') return await indexMain(args,{cwd,env,fetchImpl,out});
     if (command === 'setup') return await setupPlanMain(argv, { cwd, out });
     if (command === 'tools' || command === 'describe' || command === 'schema' || command === 'call') return await commandsMain(argv, { cwd, out, err, env, fetchImpl });
@@ -306,7 +311,15 @@ export async function main(argv = process.argv.slice(2), { cwd = process.cwd(),
         if (!name || !path) throw new ConfigError(`--observations-of expects NAME=FILE, got "${value}"`);
         observationsOf[name] = path;
       }
-      const summary = await fleetSummary(pairs, { observationsOf });
+      const statesOf = {};
+      for (const value of [].concat(args['state-of'] ?? [])) {
+        const separator = String(value).indexOf('=');
+        const name = String(value).slice(0, separator), path = String(value).slice(separator + 1);
+        if (separator < 1 || !path || !pairs.some(project => project.name === name)) throw new ConfigError('--state-of expects a declared NAME=FILE');
+        if (Object.hasOwn(statesOf, name)) throw new ConfigError(`Duplicate state input for ${name}`);
+        statesOf[name] = path;
+      }
+      const summary = await fleetSummary(pairs, { observationsOf, statesOf });
       if (args.json) { out(JSON.stringify(summary, null, 1)); return 0; }
       return renderFleet(summary, out);
     }
@@ -392,6 +405,7 @@ export async function main(argv = process.argv.slice(2), { cwd = process.cwd(),
       // so it is unchanged by a cosmetic edit to the template and changes the moment a figure does.
       const asOf = args['as-of'] === true ? null : (args['as-of'] ?? null);
       const dataset = freezeDataset(ledger.entries, observations.rows, {
+        activityState: await readState(config.paths.state),
         asOf: asOf ?? new Date().toISOString().slice(0, 10),
         title: args.title === true ? 'Backlink report' : (args.title ?? 'Backlink report'),
         includeNotes: args['include-notes'] === true,
@@ -500,24 +514,29 @@ export async function main(argv = process.argv.slice(2), { cwd = process.cwd(),
     }
 
     if (command === 'status' || command === 'diff') {
-      const found = command === 'status' ? disagreements(ledger.entries, observations.rows) : transitions(observations.rows);
-      if (args.json) { out(JSON.stringify(found, null, 1)); return 0; }
+      const activityState = command === 'status' ? await readState(config.paths.state) : null;
+      const found = command === 'status' ? disagreements(ledger.entries, observations.rows, { state: activityState }) : transitions(observations.rows);
+      const activity = command === 'status' && args.all ? projectPlacements(ledger.entries, observations.rows, { state: activityState }).map(({ entry, row, ...facts }) => ({ id: entry.id, source: entry.source, target: entry.target, scope: entry.scope, ...facts })) : null;
+      if (args.json) { out(JSON.stringify(activity ? { disagreements: found, placements: activity } : found, null, 1)); return 0; }
       reportProblems(ledger.problems, 'ledger line(s)', out);
       if (command === 'diff') {
         if (!found.length) out('no state changes recorded');
         for (const change of found.slice(0, 100)) out(`  ${change.at.slice(0, 10)}  ${change.from} -> ${change.to}  ${change.id}`);
         return 0;
       }
-      const groups = { appeared: 'appeared', lost: 'LOST', suspected_missing: 'suspected missing', cannot_say: 'cannot say', never_checked: 'never checked' };
+      const groups = { appeared: 'appeared', lost: 'confirmed missing', suspected_missing: 'suspected missing', cannot_say: 'cannot say', never_checked: 'never checked' };
       for (const [kind, label] of Object.entries(groups)) {
         const rows = found.filter(item => item.kind === kind);
         if (!rows.length) continue;
         out(`\n${label} (${rows.length})`);
         for (const item of rows.slice(0, 50)) {
           out(`  ${item.entry.id}  ${item.entry.source}${item.row ? `  [${item.row.reason}]` : ''}`);
+          out(`    Latest attempt: ${item.activity?.latest_attempt?.checked_at ?? 'not retained'} (${item.activity?.latest_attempt?.reason ?? 'unknown'})`);
+          out(`    Last conclusive: ${item.activity?.last_successful_observation?.checked_at ?? 'not retained'}; last link verification: ${item.activity?.last_link_verification?.checked_at ?? 'not retained'}`);
         }
       }
       if (!found.length) out('intent and observations agree on every entry');
+      if (activity) for (const item of activity) out(`  ${item.id}: latest attempt ${item.latest_attempt?.checked_at ?? 'not retained'}; last conclusive ${item.last_successful_observation?.checked_at ?? 'not retained'}; last link verification ${item.last_link_verification?.checked_at ?? 'not retained'}`);
       return 0;
     }
 
@@ -590,7 +609,7 @@ export async function main(argv = process.argv.slice(2), { cwd = process.cwd(),
       if (ledger.problems.length) { reportProblems(ledger.problems, 'ledger line(s)', err); return 2; }
       const state = await readState(config.paths.state);
       const selected = selectEntries(ledger.entries, { filter: args.filter === true ? null : args.filter });
-      const entries = args.all ? selected : dueEntries(selected, lastCheckedMap(state));
+      const entries = args.all ? selected : dueEntries(selected, lastCheckedMap(state, selected));
       if (!entries.length) { (args.json ? err : out)(`nothing due (${plural(selected.length, 'entry', 'entries')} in scope; pass --all to recheck)`); return 0; }
       if (!args.json) err(`checking ${plural(entries.length, 'entry', 'entries')}…`);
       const rows = await runCheck(entries, {
@@ -625,6 +644,13 @@ export async function main(argv = process.argv.slice(2), { cwd = process.cwd(),
       err(JSON.stringify({error: {code: error.code, status: error.status, next: 'Keep this project ledger and its history. Resolve authorized read access for the configured project, then retry agentlinkops sync --pull-only --recover-cursors. Do not broaden grants or replay remote writes.'}}));
       return 2;
     }
+    if (command === 'sync' && error instanceof CloudError && error.status === 0 &&
+        ['CLOUD_TIMEOUT', 'CLOUD_NETWORK_ERROR'].includes(error.code)) {
+      // A local transport failure cannot establish whether a write committed.
+      // Print trusted recovery guidance, never attached exception/server text.
+      err(`agentlinkops: ${error.code}\nThe request outcome is unknown. Check the operation result before sending it again. Keep this project ledger and its history. Inspect accessible watches and their local references with agentlinkops sync --pull-only --recover-cursors. Do not broaden grants or replay remote writes.`);
+      return 2;
+    }
     err(`agentlinkops: ${error?.message ?? error}`);
     return 2;
   } finally {

package/cli/mcp-client.js

@@ -62,7 +62,7 @@ function retryDelay(error, attempt, now) {
 
 async function sdkClient({url, token, workspaceId, fetchImpl}) {
   const {Client, StreamableHTTPClientTransport} = await import('@modelcontextprotocol/client');
-  const client = new Client({name: 'agentlinkops-cli', version: '0.6.11'});
+  const client = new Client({name: 'agentlinkops-cli', version: '0.6.13'});
   const destination = new URL(url);
   const transport = new StreamableHTTPClientTransport(destination, {
     authProvider: {token: async () => token},
@@ -71,7 +71,7 @@ async function sdkClient({url, token, workspaceId, fetchImpl}) {
       if (target.href !== destination.href) fail('OAUTH_TOKEN_DESTINATION_MISMATCH');
       const headers = new Headers(init.headers ?? (input instanceof Request ? input.headers : undefined));
       if (workspaceId) headers.set('X-Workspace-ID', workspaceId);
-      headers.set('User-Agent', 'agentlinkops-cli/0.6.11');
+      headers.set('User-Agent', 'agentlinkops-cli/0.6.13');
       const response = await fetchImpl(input, {...init, headers, redirect: 'error', signal: AbortSignal.timeout(30000)});
       if (response.redirected || response.status >= 300 && response.status < 400
         || response.url && response.url !== destination.href) fail('OAUTH_TOKEN_DESTINATION_MISMATCH');

package/cli/placement-projection.js

@@ -0,0 +1,106 @@
+// One identity-bound projection for local activity and retained observations. A change-only
+// mirror is not a complete probe log, so local absence remains provisional. Hosted watch
+// state is carried independently from the raw check; this module never confirms loss.
+import { mirrorEvidenceReference } from '../src/evidence-reference.js';
+
+const conclusive = new Set(['present', 'absent', 'source_unavailable']);
+const watchStates = new Set(['present', 'suspected_missing', 'confirmed_missing', 'source_unavailable']);
+export const validTime = value => typeof value === 'string' && Number.isFinite(Date.parse(value));
+
+export function placementIdentity(value) {
+  const record = value?.result ?? value;
+  const source = record?.sourceUrl ?? record?.source_url ?? record?.source;
+  const target = record?.targetUrl ?? record?.target_url ?? record?.target;
+  const scope = record?.targetScope ?? record?.target_scope ?? record?.scope ?? 'exact';
+  return typeof source === 'string' && typeof target === 'string'
+    ? JSON.stringify([source, target, scope]) : null;
+}
+
+export function attemptSummary(row, { retained = false } = {}) {
+  if (!validTime(row?.checked_at)) return null;
+  const cloud = row.source === 'cloud';
+  const rawState = cloud && conclusive.has(row.result?.checkState) ? row.result.checkState
+    : ['suspected_missing', 'confirmed_missing'].includes(row.state) ? 'absent' : row.state;
+  const method = row.result?.evidence?.method ?? null;
+  return {
+    checked_at: row.checked_at, placement: placementIdentity(row),
+    state: rawState, reason: row.reason ?? null, complete: row.complete === true,
+    origin: row.source ?? 'local',
+    watch_state: cloud && watchStates.has(row.result?.watchState) ? row.result.watchState
+      : ['suspected_missing', 'confirmed_missing'].includes(row.state) ? row.state : null,
+    link_signature: row.result?.linkSignature ?? null,
+    method, checker_version: row.checker_version ?? row.result?.evidence?.checkerVersion ?? null,
+    content_hash: row.result?.evidence?.sha256 ?? null,
+    evidence_reference: retained ? mirrorEvidenceReference({ entryId: row.id, checkedAt: row.checked_at, origin: row.source ?? 'local' }) : null,
+    retained,
+  };
+}
+
+export const isConclusive = attempt => attempt?.complete === true && conclusive.has(attempt.state);
+export const isLinkVerification = attempt => isConclusive(attempt) && ['present', 'absent'].includes(attempt.state);
+
+// Equal timestamps never qualify another probe. Stable tie-breaking makes frozen exports
+// independent of input ordering; an activity summary cannot replace a richer retained receipt.
+const compareText = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+function latest(items) {
+  return items.filter(item => item && validTime(item.checked_at)).sort((a, b) =>
+    Date.parse(b.checked_at) - Date.parse(a.checked_at)
+      || Number(b.retained === true) - Number(a.retained === true)
+      || compareText(JSON.stringify(a), JSON.stringify(b)))[0] ?? null;
+}
+
+function activityAttempt(record, identity) {
+  if (record?.last_placement !== identity) return null;
+  if (record.last_attempt?.placement === identity && record.last_attempt.checked_at === record.last_checked
+    && validTime(record.last_attempt.checked_at)) return record.last_attempt;
+  // Legacy activity can prove its last conclusive time, but cannot invent a method/hash or
+  // reconstruct the overwritten successful check after a later unknown attempt.
+  if (!validTime(record.last_checked)) return null;
+  return { checked_at: record.last_checked, placement: identity, state: record.last_state ?? 'unknown',
+    reason: record.last_reason ?? null, complete: record.last_complete === true, origin: 'local',
+    watch_state: null, link_signature: record.last_signature ?? null, method: null,
+    checker_version: null, content_hash: null, evidence_reference: null, retained: false };
+}
+
+export function projectPlacement(entry, observations, { state = null } = {}) {
+  const identity = placementIdentity(entry);
+  const history = identity ? observations.filter(row => row.id === entry.id && placementIdentity(row) === identity && validTime(row.checked_at)) : [];
+  const attempts = history.map(row => attemptSummary(row, { retained: true }));
+  const record = state?.entries?.[entry.id];
+  const locate = item => item?.retained === true && !attempts.some(receipt => receipt.checked_at === item.checked_at
+    && receipt.origin === item.origin && receipt.content_hash === item.content_hash)
+    ? { ...item, retained: false, evidence_reference: null } : item;
+  const activity = locate(identity ? activityAttempt(record, identity) : null);
+  const saved = key => locate(identity && record?.last_placement === identity && record[key]?.placement === identity ? record[key] : null);
+  const latestAttempt = latest([...attempts, activity]);
+  const savedSuccess = saved('last_successful_observation'), savedLink = saved('last_link_verification');
+  const lastSuccessful = latest([...attempts.filter(isConclusive), isConclusive(savedSuccess) ? savedSuccess : null, isConclusive(activity) ? activity : null]);
+  const lastLink = latest([...attempts.filter(isLinkVerification), isLinkVerification(savedLink) ? savedLink : null, isLinkVerification(activity) ? activity : null]);
+  const retained = latest(attempts);
+  const row = retained ? history.filter(item => JSON.stringify(attemptSummary(item, { retained: true })) === JSON.stringify(retained))
+    .sort((a, b) => compareText(JSON.stringify(a), JSON.stringify(b)))[0] ?? null : null;
+  const firstDates = attempts.filter(item => isConclusive(item) && item.state === 'present').map(item => item.checked_at);
+  const first = saved('first_present_observation');
+  if (isConclusive(first) && first.state === 'present' && validTime(first.checked_at)) firstDates.push(first.checked_at);
+  const firstPresent = firstDates.sort((a, b) => Date.parse(a) - Date.parse(b))[0] ?? null;
+  const current = latestAttempt?.watch_state ?? lastSuccessful?.watch_state ?? (lastSuccessful?.state === 'absent' ? 'suspected_missing'
+    : lastSuccessful?.state ?? (latestAttempt ? 'unknown' : 'unchecked'));
+  return {
+    entry, row, placement: identity, current_state: current,
+    uncertain: !!latestAttempt && !isConclusive(latestAttempt),
+    latest_attempt: latestAttempt, last_successful_observation: lastSuccessful,
+    last_link_verification: lastLink, first_present: firstPresent,
+    evidence_observed_at: retained?.checked_at ?? null,
+    activity_available: activity !== null,
+    identity_status: history.length || activity ? 'matched' : observations.some(item => item.id === entry.id) || record ? 'not_matched' : 'not_observed',
+  };
+}
+
+export function projectPlacements(entries, observations, options = {}) {
+  const byId = new Map();
+  for (const row of observations) {
+    if (!byId.has(row.id)) byId.set(row.id, []);
+    byId.get(row.id).push(row);
+  }
+  return entries.map(entry => projectPlacement(entry, byId.get(entry.id) ?? [], options));
+}