agentlinkops 0.6.11 → 0.6.13

package/cli/report.js

@@ -18,13 +18,15 @@
 // evidence reference that resolves to the observation itself. One dataset feeds both exports:
 // this HTML view for a human client, and `report --json` for an agent, so the two can never
 // disagree about what was observed.
+// v3 freezes activity separately from retained receipts. Older v2 datasets still render with
+// their original columns and wording; activity never changes an old observation's date/hash.
 import {indexRowsForUrl} from './index-observations.js';
 import {reconcileIndexObservations} from '../src/index-observation.js';
 import { createHash } from 'node:crypto';
-import { latestByEntry } from './mirror.js';
+import { projectPlacements } from './placement-projection.js';
 import { mirrorEvidenceReference } from '../src/evidence-reference.js';
 
-export const REPORT_VERSION = 2;
+export const REPORT_VERSION = 3;
 
 /** HTML-escape. Every value below is publisher or customer content and none of it is trusted. */
 export const escape = value => String(value ?? '')
@@ -35,6 +37,10 @@ const STATE_LABEL = Object.freeze({
   present: 'Present', absent: 'Not found', unknown: 'Could not check',
   source_unavailable: 'Page unavailable', unchecked: 'Never checked',
 });
+const CURRENT_STATE_LABEL = Object.freeze({
+  ...STATE_LABEL,
+  suspected_missing: 'Suspected missing', confirmed_missing: 'Confirmed missing',
+});
 
 /**
  * The frozen dataset a report renders.
@@ -42,12 +48,10 @@ const STATE_LABEL = Object.freeze({
  * Selection happens here and nowhere else, so a caller can hold this object, assert it, and know
  * the rendered document is a pure function of it.
  */
-export function freezeDataset(entries, observations, { asOf, title = 'Backlink report', includeNotes = false, includeRetired = false, indexObservations = [] } = {}) {
-  const latest = latestByEntry(observations);
-  const rows = entries
-    .filter(entry => includeRetired || entry.intent !== 'retired')
-    .map(entry => {
-      const row = latest.get(entry.id) ?? null;
+export function freezeDataset(entries, observations, { asOf, title = 'Backlink report', includeNotes = false, includeRetired = false, indexObservations = [], activityState = null } = {}) {
+  const rows = projectPlacements(entries.filter(entry => includeRetired || entry.intent !== 'retired'), observations, { state: activityState })
+    .map(projection => {
+      const { entry, row } = projection;
       const indexRows=indexRowsForUrl(indexObservations,entry.source);
       const origin = row?.source === 'cloud' ? 'cloud' : (row?.source ?? null);
       return {
@@ -57,6 +61,16 @@ export function freezeDataset(entries, observations, { asOf, title = 'Backlink r
         reason: row?.reason ?? null,
         occurrences: row?.occurrences ?? 0,
         checked_at: row?.checked_at ?? null,
+        current_state: projection.current_state,
+        uncertain: projection.uncertain,
+        activity: {
+          available: projection.activity_available,
+          identity_status: projection.identity_status,
+          latest_attempt: projection.latest_attempt,
+          last_successful_observation: projection.last_successful_observation,
+          last_link_verification: projection.last_link_verification,
+          first_present: projection.first_present,
+        },
         checked_by: row?.source ?? null,
         anchor: row?.result?.occurrences?.[0]?.anchor ?? null,
         rel: row?.result?.occurrences?.[0]?.rel ?? [],
@@ -105,10 +119,16 @@ export function freezeDataset(entries, observations, { asOf, title = 'Backlink r
     // Stated rather than implied. A report over a ledger nobody has checked is not a report about
     // links, and the reader should see that before the table.
     coverage: {
-      checked: rows.filter(row => row.checked_at).length,
-      never_checked: rows.filter(row => !row.checked_at).length,
+      checked: rows.filter(row => row.activity.latest_attempt).length,
+      never_checked: rows.filter(row => !row.activity.latest_attempt).length,
+      retained_receipt_entries: rows.filter(row => row.checked_at).length,
+      missing_receipt_entries: rows.filter(row => !row.checked_at).length,
       observed_from: dates[0] ?? null,
       observed_to: dates.at(-1) ?? null,
+      activity_entries: rows.filter(row => row.activity.available).length,
+      identity_unmatched_entries: rows.filter(row => row.activity.identity_status === 'not_matched').length,
+      denominator: includeRetired ? 'all_ledger_entries' : 'non_retired_ledger_entries',
+      known_present_after_unknown: rows.filter(row => row.current_state === 'present' && row.uncertain).length,
     },
   };
 }
@@ -149,6 +169,18 @@ export function renderReport(dataset, { brand = null } = {}) {
   const digest = createHash('sha256').update(JSON.stringify(dataset)).digest('hex');
   const card = (label, value) => `<div class="card"><b>${escape(value)}</b><span>${escape(label)}</span></div>`;
   const coverage = dataset.coverage;
+  const hasActivity = dataset.v >= 3;
+  const activityCell = row => {
+    const activity = row.activity ?? {};
+    const describe = (label, attempt) => `<div>${escape(label)}: ${attempt ? `${escape(attempt.state)} · ${escape(attempt.checked_at)}` : 'not retained'}</div>`
+      + (attempt ? `<div class="note">${escape(attempt.reason ?? 'reason not recorded')} · ${escape(attempt.method ?? 'method not recorded')}</div>`
+        + `<div class="ref">${escape(attempt.evidence_reference ?? 'no retained receipt reference')}</div>` : '');
+    return `<div>${escape(CURRENT_STATE_LABEL[row.current_state] ?? row.current_state ?? 'Unknown')}${row.uncertain ? ' · latest attempt inconclusive' : ''}</div>`
+      + describe('Latest attempt', activity.latest_attempt)
+      + describe('Last conclusive check', activity.last_successful_observation)
+      + describe('Last link verification', activity.last_link_verification)
+      + `<div class="note">Activity ${activity.available ? 'recorded' : 'not supplied or not retained'}; identity ${escape(activity.identity_status ?? 'not retained')}</div>`;
+  };
   // The receipt column. "hash not recorded" is stated rather than papered over: a local check
   // that never completed a fetch has no hash, and a cloud-synced row may carry its snapshot key
   // without a hash in an older event. Neither is a claim about the link.
@@ -164,10 +196,10 @@ export function renderReport(dataset, { brand = null } = {}) {
   const rows = dataset.rows.map(row => `<tr>
       <td class="url"><a href="${escape(row.source)}">${escape(row.source)}</a></td>
       <td class="url">${escape(row.target)}</td>
-      <td><span class="state ${escape(row.state)}">${escape(STATE_LABEL[row.state] ?? row.state)}</span></td>
+      <td><span class="state ${escape(row.state)}">${escape(hasActivity && !row.evidence && row.activity?.latest_attempt ? 'No retained observation' : (hasActivity ? CURRENT_STATE_LABEL : STATE_LABEL)[row.state] ?? row.state)}</span></td>
       <td>${row.anchor ? escape(row.anchor) : '<span class="note">&mdash;</span>'}${(row.rel ?? []).length ? `<div class="note">rel: ${escape(row.rel.join(' '))}</div>` : ''}</td>
       <td>${row.checked_at ? escape(row.checked_at.slice(0, 10)) : '<span class="note">never</span>'}</td>
-      <td>${evidenceCell(row)}</td>
+      <td>${evidenceCell(row)}</td>${hasActivity ? `\n      <td>${activityCell(row)}</td>` : ''}
       ${hasIndex?`<td>${(row.index_observations??[]).map(o=>`${escape(o.tier)} · ${escape(o.reason)}<div>${escape(o.checked_at)} · ${escape(o.backend)}</div><div class="ref">${escape(o.locator)}</div>`).join('<hr>')||'Not checked'}</td>`:''}
       ${dataset.include_notes ? `<td class="note">${escape(row.ref ?? '')}${row.note ? `<div>${escape(row.note)}</div>` : ''}</td>` : ''}
     </tr>`).join('\n');
@@ -188,21 +220,21 @@ export function renderReport(dataset, { brand = null } = {}) {
 <p class="sub">${brand ? `${escape(brand)} &middot; ` : ''}Prepared ${escape(dataset.as_of)}</p>
 <div class="cards">
 ${card('links in report', dataset.totals.entries)}
-${card('present', dataset.totals.present ?? 0)}
-${card('not found', dataset.totals.absent ?? 0)}
-${card('could not check', (dataset.totals.unknown ?? 0) + (dataset.totals.source_unavailable ?? 0))}
-${card('never checked', dataset.totals.unchecked ?? 0)}
+${card(hasActivity ? 'retained present' : 'present', dataset.totals.present ?? 0)}
+${card(hasActivity ? 'retained not found' : 'not found', dataset.totals.absent ?? 0)}
+${card(hasActivity ? 'retained could not check' : 'could not check', (dataset.totals.unknown ?? 0) + (dataset.totals.source_unavailable ?? 0))}
+${card('never checked', hasActivity ? coverage.never_checked : dataset.totals.unchecked ?? 0)}
 </div>
 <p class="caveat"><strong>What these dates mean.</strong> Every row shows the date that link was
 last observed, between ${escape(coverage.observed_from ?? 'n/a')} and ${escape(coverage.observed_to ?? 'n/a')}.
 The date at the top is when this document was prepared and does not make any observation newer
-than it is. ${coverage.never_checked ? `${coverage.never_checked} of ${dataset.totals.entries} links have never been checked and are listed as such.` : ''}</p>
+than it is. ${coverage.never_checked ? `${coverage.never_checked} of ${dataset.totals.entries} links have never been checked and are listed as such.` : ''}</p>${hasActivity ? '\n<p class="caveat"><strong>Activity and verification.</strong> The result and receipt date describe the retained observation. Activity lists later attempts and complete checks separately; an unchanged recheck can be newer than that receipt. An inconclusive attempt preserves the earlier verified state, and does not prove loss. A complete unavailable source is a conclusive source check, not a link verification. Missing activity is not inferred from a report preparation date.</p>' : ''}
 <p class="caveat"><strong>What a result means.</strong> &ldquo;Present&rdquo; means the link was in
 the observed HTML. &ldquo;Could not check&rdquo; is not the same as
 &ldquo;not found&rdquo;: it means the page could not be read, and no conclusion was drawn.
 Each receipt identifies the check method when it was recorded. A snapshot alone does not prove the link was visible on screen.</p>
 <table><thead><tr>
-<th>Source page</th><th>Target</th><th>Result</th><th>Anchor</th><th>Observed</th><th>Evidence</th>${hasIndex?'<th>Index evidence</th>':''}${dataset.include_notes ? '<th>Notes</th>' : ''}
+<th>Source page</th><th>Target</th><th>Result</th><th>Anchor</th><th>Observed</th><th>Evidence</th>${hasActivity ? '<th>Activity and verified state</th>' : ''}${hasIndex?'<th>Index evidence</th>':''}${dataset.include_notes ? '<th>Notes</th>' : ''}
 </tr></thead><tbody>
 ${rows}
 </tbody></table>
@@ -219,7 +251,7 @@ ${receiptRows}
 </tbody></table>` : ''}
 <footer>
 AgentLinkOps report v${dataset.v}. Dataset digest <code>${escape(digest)}</code> &mdash; the same
-ledger and observations always produce this digest. The same dataset exports as JSON
+ledger and observations${hasActivity ? ' and frozen activity' : ''} always produce this digest. The same dataset exports as JSON
 (<code>agentlinkops report --json</code>) and carries the same digest.
 ${dataset.include_notes ? 'Private notes are included in this document.' : 'Private notes and references are excluded.'}
 </footer>

package/cli/state.js

@@ -10,8 +10,9 @@
 // was this last confirmed" — is exactly what a small, rewritten map answers better.
 import { readFile, writeFile, mkdir, rename } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
+import { placementIdentity, attemptSummary, isConclusive, isLinkVerification, validTime } from './placement-projection.js';
 
-export const STATE_VERSION = 2;
+export const STATE_VERSION = 3;
 
 /**
  * Brings a state file forward without losing anything it already held.
@@ -58,49 +59,81 @@ export async function writeState(path, state) {
 }
 
 /** When each entry was last checked, whatever the answer was. */
-export function lastCheckedMap(state) {
-  return new Map(Object.entries(state.entries ?? {}).map(([id, record]) => [id, record.last_checked]));
+export function lastCheckedMap(state, entries = null) {
+  const identities = entries ? new Map(entries.map(entry => [entry.id, placementIdentity(entry)])) : null;
+  return new Map(Object.entries(state.entries ?? {}).filter(([id, record]) => !identities
+    || identities.get(id) && record.last_placement === identities.get(id)).map(([id, record]) => [id, record.last_checked]));
+}
+
+const methodOf = row => row.result?.evidence?.method ?? null;
+const eligible = (row, previous) => validTime(row.checked_at)
+  && (!validTime(previous?.last_checked) || Date.parse(row.checked_at) > Date.parse(previous.last_checked));
+const repeats = (row, previous) => previous
+  && previous.last_placement === placementIdentity(row)
+  && previous.last_state === row.state
+  && (previous.last_reason ?? null) === (row.reason ?? null)
+  && (previous.last_signature ?? null) === (row.result?.linkSignature ?? null)
+  && previous.last_complete === (row.complete === true)
+  && (previous.last_method ?? null) === methodOf(row)
+  && (previous.last_checker_version ?? null) === (row.checker_version ?? row.result?.evidence?.checkerVersion ?? null);
+
+function applyRow(previous, row) {
+  const identity = placementIdentity(row);
+  const samePlacement = previous?.last_placement === identity;
+  const attempt = attemptSummary(row, { retained: !repeats(row, previous) });
+  const knownPresent = isConclusive(attempt) && attempt.state === 'present';
+  const priorFirst = samePlacement && previous?.first_present_observation?.placement === identity
+    && isConclusive(previous.first_present_observation) && previous.first_present_observation.state === 'present'
+    ? previous.first_present_observation : null;
+  const firstPresent = priorFirst ?? (knownPresent ? attempt : null);
+  return {
+    ...previous,
+    last_checked: row.checked_at,
+    last_complete: row.complete === true,
+    last_placement: identity,
+    last_state: row.state,
+    last_reason: row.reason ?? null,
+    last_signature: row.result?.linkSignature ?? null,
+    last_method: methodOf(row),
+    last_checker_version: row.checker_version ?? row.result?.evidence?.checkerVersion ?? null,
+    checks: (previous?.checks ?? 0) + 1,
+    last_attempt: attempt,
+    last_successful_observation: isConclusive(attempt) ? attempt : samePlacement ? previous?.last_successful_observation ?? null : null,
+    last_link_verification: isLinkVerification(attempt) ? attempt : samePlacement ? previous?.last_link_verification ?? null : null,
+    first_present: firstPresent?.checked_at ?? null,
+    first_present_placement: firstPresent ? identity : null,
+    first_present_observation: firstPresent,
+    ...(samePlacement && previous?.first_present && !previous.first_present_observation
+      ? { legacy_first_present: previous.first_present } : {}),
+  };
 }
 
 /**
  * Splits a run's rows into the ones worth recording and the ones that repeat.
  *
- * A row is worth recording when it is the first for its entry, or when the state, the reason or
- * the link signature moved. The signature is in there deliberately: a link that is still present
- * but whose anchor or rel changed is a real event, and comparing only the state would miss it.
+ * A row is worth recording when it is the first for its placement, or when the state, reason,
+ * link signature, completeness or method moved. A link that is still present but whose anchor
+ * or rel changed is a real event, and comparing only the state would miss it.
  */
 export function selectChanged(rows, state) {
-  const changed = [], repeated = [];
+  const changed = [], repeated = [], ignored = [];
+  const entries = { ...(state.entries ?? {}) };
   for (const row of rows) {
-    const previous = state.entries?.[row.id];
-    const signature = row.result?.linkSignature ?? null;
-    const same = previous
-      && previous.last_state === row.state
-      && (previous.last_reason ?? null) === (row.reason ?? null)
-      && (previous.last_signature ?? null) === signature;
-    (same ? repeated : changed).push(row);
+    const previous = entries[row.id];
+    if (!eligible(row, previous)) { ignored.push(row); continue; }
+    (repeats(row, previous) ? repeated : changed).push(row);
+    entries[row.id] = applyRow(previous, row);
   }
-  return { changed, repeated };
+  return { changed, repeated, ignored };
 }
 
 /** Applies a run to the activity record. Every check counts, recorded or not. */
 export function applyRun(state, rows) {
   const entries = { ...(state.entries ?? {}) };
   for (const row of rows) {
-    const previous = entries[row.id] ?? { checks: 0 };
-    entries[row.id] = {
-      ...previous,
-      last_checked: row.checked_at,
-      last_complete: row.complete === true,
-      last_placement: row.result?.sourceUrl && row.result?.targetUrl ? JSON.stringify([row.result.sourceUrl, row.result.targetUrl, row.result.targetScope ?? 'exact']) : null,
-      last_state: row.state,
-      last_reason: row.reason ?? null,
-      last_signature: row.result?.linkSignature ?? null,
-      checks: (previous.checks ?? 0) + 1,
-      // The date a placement was first seen is worth keeping where nothing can compact it away.
-      first_present: previous.first_present ?? (row.state === 'present' ? row.checked_at : null),
-      first_present_placement: previous.first_present ? previous.first_present_placement ?? null : row.state === 'present' && row.result?.sourceUrl && row.result?.targetUrl ? JSON.stringify([row.result.sourceUrl, row.result.targetUrl, row.result.targetScope ?? 'exact']) : null,
-    };
+    const previous = entries[row.id];
+    if (!eligible(row, previous)) continue;
+    entries[row.id] = applyRow(previous, row);
   }
   return { ...state, v: STATE_VERSION, entries };
 }

package/cli/status.js

@@ -4,32 +4,28 @@
 // expectation, closes the laptop, and three weeks later an agent opens the repository and reads
 // this. So it answers in the order a person cares about, not the order the data is stored in:
 // what appeared, what was lost, what we cannot say, and what needs a decision.
-import { latestByEntry } from './mirror.js';
+import { projectPlacements } from './placement-projection.js';
 
 /** A ledger entry whose observations disagree with its declared intent. */
-export function disagreements(entries, observations) {
-  const latest = latestByEntry(observations);
+export function disagreements(entries, observations, { state = null } = {}) {
   const out = [];
-  for (const entry of entries) {
-    const row = latest.get(entry.id);
-    if (!row) { out.push({ entry, kind: 'never_checked' }); continue; }
+  for (const projection of projectPlacements(entries, observations, { state })) {
+    const { entry, row, latest_attempt: attempt } = projection;
+    const activity = { current_state: projection.current_state, uncertain: projection.uncertain,
+      latest_attempt: attempt, last_successful_observation: projection.last_successful_observation,
+      last_link_verification: projection.last_link_verification,
+      evidence_observed_at: projection.evidence_observed_at, identity_status: projection.identity_status };
+    if (!attempt) { out.push({ entry, kind: 'never_checked', activity }); continue; }
     if (entry.intent === 'expected') {
-      const hostedState = row.source === 'cloud' ? row.result?.watchState : null;
-      const confirmed = row.state === 'confirmed_missing'
-        || (row.state === 'absent' && hostedState === 'confirmed_missing');
-      const suspected = row.state === 'suspected_missing' || row.state === 'absent'
-        || (row.state === 'unknown' && hostedState === 'suspected_missing');
-      const missing = ['absent', 'suspected_missing', 'confirmed_missing'].includes(row.state);
-      // The change mirror omits repeated checks, so raw absence cannot prove confirmation.
-      if ((confirmed || suspected) && row.complete === true) {
-        out.push({ entry, row, kind: confirmed ? 'lost' : 'suspected_missing' });
-      } else if (missing || ['unknown', 'source_unavailable'].includes(row.state)) {
-        out.push({ entry, row, kind: 'cannot_say' });
+      if (projection.uncertain || attempt.state === 'source_unavailable') {
+        out.push({ entry, row, kind: 'cannot_say', activity });
+      } else if (['suspected_missing', 'confirmed_missing'].includes(projection.current_state)) {
+        out.push({ entry, row, kind: projection.current_state === 'confirmed_missing' ? 'lost' : 'suspected_missing', activity });
       }
     }
     // Nothing is promoted automatically: whether a link that appeared is one we now EXPECT is
     // a judgement about a relationship, not about HTML. So this proposes the edit and stops.
-    if (entry.intent === 'wanted' && row.state === 'present') out.push({ entry, row, kind: 'appeared', suggest: { intent: 'expected' } });
+    if (entry.intent === 'wanted' && !projection.uncertain && projection.current_state === 'present') out.push({ entry, row, kind: 'appeared', activity, suggest: { intent: 'expected' } });
   }
   return out;
 }

package/cli/sync.js

@@ -12,6 +12,24 @@ import { CloudError } from './client.js';
 
 const PUSH_BATCH = 100;
 
+function completeImportRows(result, expected) {
+  const record = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+  const text = value => typeof value === 'string' && value.trim().length > 0;
+  const refuse = () => { throw new CloudError('INVALID_IMPORT_RESPONSE', 502, null,
+    'The cloud returned an incomplete or invalid watch import result. Some watches may already have been stored. Inspect accessible watches and their local references before retrying sync; this request was not automatically replayed.'); };
+  if (!record(result) || !Array.isArray(result.rows) || result.rows.length !== expected) refuse();
+  const seen = new Set();
+  for (const row of result.rows) {
+    if (!record(row) || !Number.isInteger(row.index) || row.index < 0 || row.index >= expected || seen.has(row.index)) refuse();
+    seen.add(row.index);
+    const watch = Object.hasOwn(row, 'watch'), error = Object.hasOwn(row, 'error');
+    if (watch === error) refuse();
+    if (watch && (!record(row.watch) || !text(row.watch.id) || typeof row.watch.created !== 'boolean')) refuse();
+    if (error && (!record(row.error) || !text(row.error.code) || !text(row.error.message))) refuse();
+  }
+  return result.rows;
+}
+
 export function syncPlan(entries, state, { includeWanted = false, ledgerIds = null } = {}) {
   if (ledgerIds !== null && (!Array.isArray(ledgerIds) || ledgerIds.some(id => typeof id !== 'string') || ledgerIds.some(id => !entries.some(entry => entry.id === id))))
     throw new CloudError('INVALID_SYNC_SELECTION', 0);
@@ -38,12 +56,13 @@ export async function pushExpectations(client, entries, state, { projectId, onPr
   for (let index = 0; index < watched.length; index += PUSH_BATCH) {
     const batch = watched.slice(index, index + PUSH_BATCH);
     const result = await client.importWatches(projectId, batch.map(toWatchInput));
-    for (const row of result.rows ?? []) {
+    // Validate the complete acknowledgement before adopting any of this batch.
+    // Earlier POSTs may have committed; a malformed response never authorizes a replay.
+    for (const row of completeImportRows(result, batch.length)) {
       const entry = batch[row.index];
-      if (!entry) continue;
       if (row.error) { failed.push({ id: entry.id, code: row.error.code, message: row.error.message }); continue; }
       mapping[entry.id] = row.watch.id;
-      if (row.watch.created !== false) created.push(entry.id);
+      if (row.watch.created) created.push(entry.id);
     }
     onProgress?.(Math.min(index + PUSH_BATCH, watched.length), watched.length);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentlinkops",
-  "version": "0.6.11",
+  "version": "0.6.13",
   "description": "Backlink checks with dated evidence and portable results, optional repository ledgers, supplier-export imports and sync to AgentLinkOps.",
   "author": "AgentLinkOps (https://agentlinkops.com)",
   "license": "Apache-2.0",

package/shared/index-observation-contract.js

@@ -4,7 +4,7 @@ export const indexConfigureInput=z.object({projectId:id,enabled:z.boolean(),dail
 export const indexInspectInput=z.object({connectionId:id,watchId:id,idempotencyKey:z.string().regex(/^[\x21-\x7e]{1,128}$/)}).strict();
 export const indexHistoryInput=z.object({projectId:id,watchId:id,limit:z.number().int().min(1).max(100).optional(),beforeId:digest.optional()}).strict();
 export const indexReceiptInput=z.object({projectId:id,watchId:id,receiptId:digest}).strict();
-export const indexEventsInput=z.object({projectId:id,watchId:id,limit:z.number().int().min(1).max(100).optional()}).strict();
+export const indexEventsInput=z.object({projectId:id,watchId:id,limit:z.number().int().min(1).max(100).optional(),beforeId:digest.optional()}).strict();
 export const indexSettingsInput=z.object({projectId:id}).strict();
 export const indexSettingsResponse=z.object({projectId:id,enabled:z.boolean(),dailyLimit:z.number().int().positive(),retentionDays:z.number().int().positive(),cadenceSeconds:z.number().int().positive(),schedulingAvailable:z.boolean()}).passthrough();
 export const indexObservation=z.looseObject({id:digest,observationId:id,checkedAt:time,recordedAt:time,expiresAt:time,evidenceSha256:digest,eventId:digest.nullable(),ignored:z.string().nullable(),version:z.literal(1),url:z.url(),lane:z.enum(['gsc','licensed_site']),backend:z.string(),source_key:z.string(),tier:z.enum(['indexed','not_indexed','likely_indexed','not_found_in_site_query','unknown']),confidence:z.enum(['google_index_snapshot','search_result_sample','unknown']),reason:z.string(),live_page_test:z.literal(false),submission_requested:z.literal(false)});
@@ -13,4 +13,4 @@ export const indexInspectResponse=indexReceiptResponse.extend({replayed:z.boolea
 export const indexAttemptSummary=z.object({observedAt:time,latestAttempt:z.object({id:digest,admittedAt:time,status:z.enum(['in_progress','unsettled','completed']),receiptId:digest.nullable(),leaseExpiresAt:time.nullable()}).nullable(),unsettledCount:z.number().int().nonnegative()});
 export const indexWebsiteQuota=z.object({windowStart:time,observedAt:time,admitted:z.number().int().nonnegative(),limit:z.number().int().positive(),remaining:z.number().int().nonnegative()});
 export const indexHistoryResponse=z.object({observations:z.array(indexObservation),nextCursor:digest.nullable(),attemptSummary:indexAttemptSummary.optional(),websiteQuota:indexWebsiteQuota.optional()}).passthrough();
-export const indexEventsResponse=z.object({events:z.array(z.looseObject({id:digest,receiptId:digest,type:z.enum(['index.deindexed','index.reindexed']),createdAt:time,url:z.url(),source_key:z.string(),before:z.enum(['indexed','not_indexed']),after:z.enum(['indexed','not_indexed']),observation_ids:z.array(id)}))}).passthrough();
+export const indexEventsResponse=z.object({events:z.array(z.looseObject({id:digest,receiptId:digest,type:z.enum(['index.deindexed','index.reindexed']),createdAt:time,url:z.url(),source_key:z.string(),before:z.enum(['indexed','not_indexed']),after:z.enum(['indexed','not_indexed']),observation_ids:z.array(id)})),nextCursor:digest.nullable().optional(),hasMore:z.boolean().optional()}).passthrough();

package/shared/monitoring-chronology-export.js

@@ -0,0 +1,57 @@
+// Offline frozen chronology export. No hosted store, authentication, network or
+// collection dependency belongs in the customer's CLI export closure.
+const fail=(status,code,message)=>{throw Object.assign(new Error(message),{name:'ChronologyExportError',status,code});};
+const iso=value=>typeof value==='string'&&Number.isFinite(Date.parse(value))?new Date(value).toISOString():null;
+const validIdentity=value=>{
+ if(!value||typeof value!=='object'||Array.isArray(value))return false;
+ const id=v=>typeof v==='string'&&v.length>0&&v.length<=200&&!/[\s\x00-\x1f\x7f]/u.test(v);
+ const url=v=>{if(typeof v!=='string'||!v||v.length>4096)return false;try{const u=new URL(v);return ['http:','https:'].includes(u.protocol)&&!u.username&&!u.password;}catch{return false;}};
+ return ['workspaceId','projectId','watchId'].every(k=>id(value[k]))&&url(value.sourceUrl)&&url(value.targetUrl)
+  &&['exact','domain','subdomain','path'].includes(value.targetScope)&&(value.targetId===null||id(value.targetId))
+  &&(value.localReference===null||typeof value.localReference==='string'&&value.localReference.length<=2048)
+  &&value.matchBasis==='configured_target_url';
+};
+const compare=(a,b)=>a.sortAt>b.sortAt?-1:a.sortAt<b.sortAt?1:a.id>b.id?-1:a.id<b.id?1:0;
+const sha256=async value=>Array.from(new Uint8Array(await crypto.subtle.digest('SHA-256',new TextEncoder().encode(value))),b=>b.toString(16).padStart(2,'0')).join('');
+const baseItem=(stream,row,identity,observedAt,recordedAt,kind)=>({id:`${stream}:${row.id}`,rawId:row.id,stream,kind,identity,observedAt:iso(observedAt),recordedAt:iso(recordedAt),sortAt:iso(observedAt)??iso(recordedAt),state:null,reason:null,sourceKey:null,method:null,checkerVersion:null,evidence:{sha256:null,reference:null,expiresAt:null,availability:'not_checked'},data:{}});
+
+// Export only a supplied frozen dataset. This function never reads current DB
+// state or fills a missing origin with today's projection.
+export async function freezeChronology(pages,{localItems=[]}={}){
+ if(!Array.isArray(pages)||!pages.length||pages.length>10000||!Array.isArray(localItems)||localItems.length>10000)fail(400,'INVALID_CHRONOLOGY_EXPORT','Provide bounded chronology pages.');
+ const first=pages[0];if(!validIdentity(first?.identity)||iso(first?.asOf)!==first.asOf||!/^[a-f0-9]{64}$/.test(first?.snapshotId??''))fail(400,'INVALID_CHRONOLOGY_EXPORT','A frozen page requires an exact placement identity, watermark and snapshot digest.');
+ const byId=new Map();let continuous=first.pageCursor===null;
+ for(let i=0;i<pages.length;i++){
+  const page=pages[i];if(!page||page.schemaVersion!==1||page.snapshotId!==first.snapshotId||page.asOf!==first.asOf||JSON.stringify(page.identity)!==JSON.stringify(first.identity)||!Array.isArray(page.items))fail(400,'CHRONOLOGY_EXPORT_SCOPE_MISMATCH','Export pages must belong to one frozen placement read.');
+  if(typeof page.hasMore!=='boolean'||(page.hasMore?typeof page.nextCursor!=='string'||!page.nextCursor||page.nextCursor.length>12000:page.nextCursor!==null))fail(400,'INVALID_CHRONOLOGY_EXPORT','Each frozen page must declare whether another page exists with a consistent continuation cursor.');
+  if(i&&pages[i-1].nextCursor!==page.pageCursor)continuous=false;
+  for(const row of page.items){if(!row||JSON.stringify(row.identity)!==JSON.stringify(first.identity))fail(400,'CHRONOLOGY_EXPORT_SCOPE_MISMATCH','Every retained row must belong to this exact frozen placement.');const previous=byId.get(row.id);if(previous&&JSON.stringify(previous)!==JSON.stringify(row))fail(400,'CHRONOLOGY_EXPORT_CONFLICT','A frozen row changed between pages.');byId.set(row.id,row);}
+ }
+ for(const row of localItems){if(row.stream!=='local_submissions'||JSON.stringify(row.identity)!==JSON.stringify(first.identity)||!iso(row.sortAt)||row.sortAt>first.asOf)fail(400,'CHRONOLOGY_EXPORT_SCOPE_MISMATCH','Local submission context must match this placement and cutoff.');const previous=byId.get(row.id);if(previous&&JSON.stringify(previous)!==JSON.stringify(row))fail(400,'CHRONOLOGY_EXPORT_CONFLICT','A local receipt identity changed.');byId.set(row.id,row);}
+ const complete=continuous&&pages.at(-1).hasMore===false,coverage=JSON.parse(JSON.stringify(pages.at(-1).coverage));
+ if(localItems.length)coverage.local_submissions={status:'available',reason:'validated_local_reported_receipts',hasMore:false,providerAuthenticity:'not_established'};
+ const items=[...byId.values()].sort(compare),gaps=[];
+ for(const [stream,origin] of Object.entries(coverage)){
+  if(origin.status==='available'){const loaded=items.filter(row=>row.stream===stream);origin.loadedRange={newestAt:loaded[0]?.sortAt??null,oldestAt:loaded.at(-1)?.sortAt??null,itemCount:loaded.length};}
+  if(origin.status!=='available'||origin.compactedBefore||origin.retentionFloor>0)gaps.push({stream,reason:origin.reason,...(origin.compactedBefore?{compactedBefore:origin.compactedBefore}:{}),...(origin.retentionFloor>0?{retentionFloor:origin.retentionFloor}:{})});
+ }
+ if(!complete)gaps.push({stream:'pagination',reason:'partial_pagination'});
+ const data={schemaVersion:1,identity:first.identity,asOf:first.asOf,snapshotId:first.snapshotId,items,coverage,gaps,pagination:{complete,pageCount:pages.length,reason:complete?'all_loaded_pages':'partial_pagination',nextCursor:pages.at(-1).nextCursor??null},historyMeaning:first.historyMeaning};
+ const frozen=JSON.parse(JSON.stringify(data));return {...frozen,contentHash:await sha256(JSON.stringify(frozen))};
+}
+
+// This is an offline normalization boundary, not server ingestion, collection or
+// proof of provider authenticity. The hash uses the existing CLI receipt format.
+export async function normalizeLocalSubmissions(rows,identity){
+ if(!validIdentity(identity))fail(400,'INVALID_SUBMISSION_RECEIPT','An exact placement identity is required.');
+ if(!Array.isArray(rows)||rows.length>10000)fail(400,'INVALID_SUBMISSION_RECEIPT','Provide bounded local submission receipts.');
+ const fields=['v','id','project_id','url','channel','endpoint','submitted_at','http_status','evidence_sha256'],items=[],byId=new Map();
+ for(const row of rows){
+  if(!row||Object.keys(row).some(k=>!fields.includes(k))||fields.some(k=>!Object.hasOwn(row,k))||row.v!==1||!/^[\w-]{1,128}$/.test(row.id??'')||!/^[\w-]{1,128}$/.test(row.project_id??'')||row.channel!=='indexnow'||row.endpoint!=='https://api.indexnow.org/indexnow'||iso(row.submitted_at)!==row.submitted_at||row.http_status!==null&&(!Number.isInteger(row.http_status)||row.http_status<100||row.http_status>599))fail(400,'INVALID_SUBMISSION_RECEIPT','Use the existing validated local submission format.');
+  let url;try{url=new URL(row.url);}catch{fail(400,'INVALID_SUBMISSION_RECEIPT','The submission URL is invalid.');}if(url.href!==row.url||!['http:','https:'].includes(url.protocol)||url.username||url.password||url.hash)fail(400,'INVALID_SUBMISSION_RECEIPT','The submission URL must be exact HTTP(S).');
+  const body=Object.fromEntries(fields.filter(k=>k!=='evidence_sha256').map(k=>[k,row[k]]));if(await sha256(JSON.stringify(body))!==row.evidence_sha256)fail(400,'INVALID_SUBMISSION_RECEIPT','The local receipt hash does not match.');
+  const key=`${row.project_id}:${row.id}`,previous=byId.get(key);if(previous&&JSON.stringify(previous)!==JSON.stringify(row))fail(409,'SUBMISSION_IDENTITY_CONFLICT','A local submission ID has conflicting contents.');byId.set(key,row);if(previous||row.project_id!==identity.projectId||![identity.sourceUrl,identity.targetUrl].includes(row.url))continue;
+  const item=baseItem('local_submissions',{id:key},identity,null,null,'reported_submission');items.push({...item,sortAt:row.submitted_at,reason:row.http_status===200?'received':row.http_status===202?'key_validation_pending':row.http_status===null?'unknown':'failed',method:'reported_indexnow_http_response',evidence:{...item.evidence,sha256:row.evidence_sha256,availability:'local_receipt'},data:{...row,subject:row.url===identity.sourceUrl?'source':'target',reportedSubmissionAt:row.submitted_at,sortTimeMeaning:'reported_submission_time',retrievedAt:null,providerAuthenticity:'not_established',participantIndexingVerified:false,causationEstablished:false}});
+ }
+ return items.sort(compare);
+}

package/shared/monitoring-read-contract.js

@@ -0,0 +1,41 @@
+import {z} from 'zod';
+const id=z.string().min(1).max(200),time=z.string().datetime(),nullableTime=time.nullable(),count=z.number().int().nonnegative();
+export const chronologyStreams=['context','link_observations','target_observations','link_events','target_events','index_observations','index_events','local_submissions'];
+export const chronologyInput=z.object({watchId:id,limit:z.number().int().min(1).max(100).optional(),cursor:z.string().max(12000).optional(),streams:z.array(z.enum(chronologyStreams)).min(1).max(8).refine(values=>new Set(values).size===values.length).optional()}).strict();
+const identity=z.object({workspaceId:id,projectId:id,watchId:id,sourceUrl:z.url(),targetUrl:z.url(),targetScope:z.enum(['exact','domain','subdomain','path']),targetId:id.nullable(),localReference:z.string().nullable(),matchBasis:z.literal('configured_target_url')});
+export const chronologyResponse=z.object({schemaVersion:z.literal(1),identity,asOf:time,snapshotId:z.string().regex(/^[a-f0-9]{64}$/),items:z.array(z.looseObject({id:z.string(),rawId:z.string(),stream:z.enum(chronologyStreams),kind:z.string(),identity,observedAt:nullableTime,recordedAt:nullableTime,sortAt:time,state:z.string().nullable(),reason:z.string().nullable(),sourceKey:z.string().nullable(),method:z.string().nullable(),checkerVersion:z.string().nullable(),evidence:z.looseObject({sha256:z.string().nullable(),reference:z.string().nullable(),expiresAt:nullableTime,availability:z.string()}),data:z.record(z.string(),z.unknown())})),pageCursor:z.string().nullable(),nextCursor:z.string().nullable(),hasMore:z.boolean(),coverage:z.partialRecord(z.enum(chronologyStreams),z.looseObject({status:z.enum(['available','denied','unavailable']),reason:z.string()})),historyMeaning:z.string()}).passthrough();
+// Additive retained-data projection; absence preserves older backend responses.
+const nullableSeconds=z.number().nonnegative().nullable();
+const coverageProjection=z.object({
+ supplied:count,active:count,paused:count,recordedHeld:count,schedulingCandidates:count,busy:count,dueCandidates:count,
+ eligibility:z.object({status:z.literal('unavailable'),eligible:z.null(),reason:z.literal('admission_not_rechecked')}),
+ denominatorMeaning:z.string(),freshnessWindow:z.string(),cadenceSeconds:z.object({minimum:count.nullable(),maximum:count.nullable()}),
+ oldestOverdueAt:nullableTime,oldestOverdueAgeSeconds:nullableSeconds,nextScheduledAt:nullableTime,nextEligibleAt:z.null(),nextEligibleReason:z.literal('admission_not_rechecked'),
+ neverAttempted:count,neverConclusive:count,currentUnknown:count,unknownReasons:z.record(z.string(),count),freshConclusive:count,staleConclusive:count,
+ shares:z.object({currentUnknown:z.number().min(0).max(1).nullable(),neverAttempted:z.number().min(0).max(1).nullable(),freshConclusive:z.number().min(0).max(1).nullable()}),shareMeaning:z.string(),
+ freshRetainedLinkVerification:count.optional(),linkVerificationMeaning:z.string().optional(),reasonCounts:z.object({due:z.record(z.string(),count),deferred:z.record(z.string(),count),unavailable:z.record(z.string(),count).optional()})
+});
+const projectedJobs=z.object({
+ retained:count,queued:count,running:count,succeeded:count,failed:count,cancelled:count,everClaimed:count,claimAttempts:count,retryClaims:count,retryExhausted:count,expiredRunningLeases:count,
+ oldestQueuedAt:nullableTime,oldestQueuedAgeSeconds:nullableSeconds,oldestRunningAdmissionAt:nullableTime,oldestRunningAdmissionAgeSeconds:nullableSeconds,latestAdmissionAt:nullableTime,latestCompletionAt:nullableTime,
+ scopedRetainedDeadLetters:count,deadLetterMeaning:z.string(),admissionToTerminal:z.object({samples:count,minimumSeconds:nullableSeconds,maximumSeconds:nullableSeconds,meaning:z.string()}),
+ startedAt:z.null(),queueWaitSeconds:z.null(),providerLatencySeconds:z.null(),timingReason:z.literal('first_start_and_provider_timing_not_retained'),
+ dispatch:z.object({outstanding:count,deferred:count,expiredSendingLeases:count,nextDispatchAt:nullableTime,meaning:z.string()}),historyMeaning:z.string()
+});
+const projectedPlane=z.object({coverage:coverageProjection,jobs:projectedJobs});
+const indexProjection=z.discriminatedUnion('status',[
+ z.object({status:z.literal('denied'),reason:z.string()}).strict(),z.object({status:z.literal('unavailable'),reason:z.string()}).strict(),
+ z.object({status:z.literal('available'),reason:z.string(),suppliedSourceWatches:count,activeSourceWatches:count,
+  lanes:z.array(z.object({lane:z.enum(['gsc','licensed_site']),retainedStates:count,observedActiveWatches:count,neverObservedActiveWatches:count,currentUnknownStates:count,latestObservationAt:nullableTime,oldestObservationAt:nullableTime,oldestObservationAgeSeconds:nullableSeconds})).length(2),
+  schedule:z.discriminatedUnion('status',[z.object({status:z.literal('unavailable'),reason:z.literal('schema_unavailable')}),z.object({status:z.literal('available'),projectOptedIn:z.boolean(),inspectionEnabled:z.boolean(),schedulerEnabled:z.boolean(),cadenceSeconds:count.nullable(),dailyLimit:count.nullable(),nextProjectScanAt:nullableTime,propertyEligibleWatches:z.null(),propertyEligibilityReason:z.literal('current_source_property_grant_not_assessed'),eligibleWatches:z.null(),eligibilityReason:z.literal('admission_not_rechecked')})]),meaning:z.string()})
+]);
+export const monitoringAssuranceProjection=z.object({schemaVersion:z.literal(1),source:projectedPlane,target:projectedPlane,index:indexProjection,
+ serviceTickWindow:z.object({expectedTicks:z.null(),completedTicks:z.null(),availabilityShare:z.null(),reason:z.literal('tick_history_not_retained')}),
+ capacity:z.object({dueOpportunities:z.null(),missedOpportunities:z.null(),checksPerEligibleWatch:z.null(),reason:z.literal('bounded_roster_opportunity_history_not_retained')}),meaning:z.string()});
+export const assuranceInput=z.object({projectId:id}).strict();
+const metric=z.object({supplied:count,active:count,paused:count,neverAttempted:count,neverConclusive:count,due:count,overdue:count,currentUnknown:count,latestAttemptAt:nullableTime,oldestAttemptAt:nullableTime,oldestAttemptAgeSeconds:z.number().nonnegative().nullable(),latestConclusiveAt:nullableTime,oldestConclusiveAt:nullableTime,oldestConclusiveAgeSeconds:z.number().nonnegative().nullable()});
+export const assuranceResponse=z.object({schemaVersion:z.literal(1),workspaceId:id,projectId:id,asOf:time,source:metric,target:metric,monitoringProjection:monitoringAssuranceProjection.optional(),sourceLinkVerification:z.object({latestRetainedAt:nullableTime,oldestRetainedAt:nullableTime,observedWatches:count,meaning:z.string()}),sourceJobs:z.object({queued:count,running:count}),overdueReasons:z.record(z.string(),count),index:z.discriminatedUnion('status',[z.object({status:z.literal('available'),reason:z.string(),observedWatches:count,latestObservationAt:nullableTime,oldestObservationAt:nullableTime,oldestObservationAgeSeconds:z.number().nonnegative().nullable(),denominator:z.string()}),z.object({status:z.literal('denied'),reason:z.string()}),z.object({status:z.literal('unavailable'),reason:z.string()})]),serviceTicks:z.object({status:z.enum(['available','unavailable']),meaning:z.string(),items:z.array(z.object({plan:z.string(),latestAttemptAt:time,latestCompletionAt:nullableTime,latestSuccessAt:nullableTime,latestOutcome:z.enum(['running','succeeded','failed']),ageSeconds:z.number().nonnegative()}))}),assurance:z.object({elapsedSoak:z.literal('not_established'),backupRestore:z.literal('not_established'),externalDelivery:z.literal('not_established')}),denominator:z.string()}).passthrough();
+export const monitoringReadResponses={get_placement_chronology:chronologyResponse,get_monitoring_service_assurance:assuranceResponse};
+const at='2026-10-07T00:00:00.000Z',projectId='pr_example',workspaceId='ws_example';
+const emptyMetric={supplied:0,active:0,paused:0,neverAttempted:0,neverConclusive:0,due:0,overdue:0,currentUnknown:0,latestAttemptAt:null,oldestAttemptAt:null,oldestAttemptAgeSeconds:null,latestConclusiveAt:null,oldestConclusiveAt:null,oldestConclusiveAgeSeconds:null};
+export const monitoringReadExamples={get_placement_chronology:{schemaVersion:1,identity:{workspaceId,projectId,watchId:'watch_example',sourceUrl:'https://publisher.example.org/resource',targetUrl:'https://example.org/guide',targetScope:'exact',targetId:null,localReference:null,matchBasis:'configured_target_url'},asOf:at,snapshotId:'a'.repeat(64),items:[],pageCursor:null,nextCursor:null,hasMore:false,coverage:{context:{status:'available',reason:'recorded_declarations_only'},local_submissions:{status:'unavailable',reason:'local_only_not_hosted'}},historyMeaning:'Retained evidence only; gaps do not establish inactivity.'},get_monitoring_service_assurance:{schemaVersion:1,workspaceId,projectId,asOf:at,source:emptyMetric,target:emptyMetric,sourceLinkVerification:{latestRetainedAt:null,oldestRetainedAt:null,observedWatches:0,meaning:'Retained complete link receipts.'},sourceJobs:{queued:0,running:0},overdueReasons:{},index:{status:'unavailable',reason:'not_configured'},serviceTicks:{status:'unavailable',meaning:'Scheduler metadata, not customer coverage.',items:[]},assurance:{elapsedSoak:'not_established',backupRestore:'not_established',externalDelivery:'not_established'},denominator:'Supplied project records; zero is not an inventory of all backlinks.'}};