agentlinkops 0.5.0

package/cli/mix.js

@@ -0,0 +1,123 @@
+// `agentlinkops mix` — the referring-domain mix over the LOCAL ledger (DP-0003-T08/T09/T10).
+//
+// The cloud serves this report to a customer's agent (POST /v1/competitor-sets/:id/domain-mix,
+// get_domain_mix_report, the console panel). This command is the accountless local surface for
+// the same question over the same ledger the agent would supply as lanes: are our referring
+// domains generic padding, niche, or unlabelled — and how did that change since last run?
+//
+// The honesty rules are the library's, not re-stated here: class labels come only from the
+// row's own tags (never inferred from a domain's shape), ratios run over labelled domains
+// only, and a diff across different lanes or datasets refuses with the reason instead of
+// rendering index churn as link acquisition.
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { loadConfig } from './config.js';
+import { readLedger } from './ledger.js';
+import { buildDomainMixReport, diffDomainMixReports, renderDomainMixDiff } from '../src/competitors/domain-mix.js';
+
+const CLASS_LABELS = new Set(['generic', 'niche', 'outreach', 'webmcp']);
+
+const USAGE = `agentlinkops mix — the referring-domain mix over this ledger
+
+  agentlinkops mix [--lane-file FILE]… [--save FILE] [--against FILE] [--json]
+
+  Class labels are the row tags (generic, niche, outreach, webmcp); lanes split on the
+  row's src:<name> tag. Extra lanes (e.g. scripts/graph-domain-mix-lanes.mjs output) merge
+  in unchanged. --save writes the full report JSON; --against diffs the current mix against
+  a saved one in the watch format.`;
+
+/** One lane per row-source tag, exactly the fleet-run mapping: class from the row's own tags. */
+export function lanesFromEntries(entries) {
+  const byLane = new Map();
+  for (const entry of entries) {
+    const tags = entry.tags ?? [];
+    const klass = tags.find(tag => CLASS_LABELS.has(tag)) ?? null;
+    const srcTag = tags.find(tag => tag.startsWith('src:'));
+    const lane = srcTag ? srcTag.slice(4) : 'unattributed';
+    if (!byLane.has(lane)) byLane.set(lane, []);
+    byLane.get(lane).push({ source_url: entry.source, class: klass, added: entry.added ?? null });
+  }
+  return [...byLane.entries()].map(([lane, rows]) => ({ lane, rows })).sort((a, b) => a.lane < b.lane ? -1 : 1);
+}
+
+/** The one-line-per-lane human rendering. Numbers stay within their dataset, always. */
+export function renderMix(report, out) {
+  const m = report.metadata;
+  out(`referring-domain mix — lanes: ${m.lanes.length}, competitor side: ${m.competitor_side_state}`);
+  for (const lane of report.ours) {
+    const c = lane.classes;
+    const share = lane.generic_share_of_labelled === null ? 'no labelled domains' : `generic ${lane.generic_share_of_labelled} of labelled`;
+    out(`  ${lane.lane}: ${lane.referring_domains} domains — generic ${c.generic ?? 0}, niche ${c.niche ?? 0}, unlabelled ${c.unlabelled ?? 0} (${share}; label coverage ${lane.label_coverage})`);
+  }
+  for (const member of report.members) {
+    const c = member.classes;
+    out(`  ${member.member_id} (${member.member_role}, inventory coverage ${member.coverage}): ${member.referring_domains} domains — generic ${c.generic ?? 0}, niche ${c.niche ?? 0}, unlabelled ${c.unlabelled ?? 0}; our labels reach ${member.label_coverage}`);
+  }
+  out(`report ${m.report_hash}`);
+}
+
+const parseMixArgs = argv => {
+  const parsed = { 'lane-file': [], save: null, against: null, json: false, help: false, _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--json') parsed.json = true;
+    else if (arg === '--help') parsed.help = true;
+    else if (arg === '--save') parsed.save = argv[++i] ?? null;
+    else if (arg === '--against') parsed.against = argv[++i] ?? null;
+    else if (arg === '--lane-file') parsed['lane-file'].push(argv[++i] ?? null);
+    else if (arg.startsWith('--')) throw new Error(`unknown flag: ${arg}`);
+    else parsed._.push(arg);
+  }
+  return parsed;
+};
+
+export async function mixMain(argv = [], { cwd = process.cwd(), out = console.log, err = console.error } = {}) {
+  let args;
+  try { args = parseMixArgs(argv); } catch (error) { err(`${error.message}\n\n${USAGE}`); return 2; }
+  if (args.help || args._.length) { out(USAGE); return args.help ? 0 : 2; }
+
+  const config = await loadConfig({ cwd, root: cwd });
+  const { entries, problems, missing } = await readLedger(config.paths.ledger);
+  if (missing) { err('no ledger here — run `agentlinkops init` first'); return 2; }
+  if (problems.length) {
+    // Malformed lines are reported and excluded, never silently dropped.
+    err(`${problems.length} ledger line(s) could not be read and are excluded from the mix:`);
+    for (const problem of problems.slice(0, 10)) err(`  line ${problem.line}${problem.id ? ` (${problem.id})` : ''}: ${problem.reason}`);
+  }
+  const lanes = lanesFromEntries(entries);
+  for (const file of args['lane-file']) {
+    if (!file) { err('--lane-file needs a file'); return 2; }
+    const extra = JSON.parse(await readFile(file, 'utf8'));
+    if (!Array.isArray(extra)) { err(`${file}: a lane file is a JSON array of { lane, rows }`); return 2; }
+    lanes.push(...extra);
+  }
+  if (!lanes.length) {
+    // A confirmed absence, not a usage error: the ledger exists and names no rows we can
+    // split. Exit 1 says so with the reason instead of printing an empty report.
+    err('no labelled rows: the ledger is empty, or no row carries a class tag (generic, niche, outreach, webmcp)');
+    return 1;
+  }
+
+  let report;
+  try {
+    report = await buildDomainMixReport({ lanes });
+  } catch (error) {
+    err(`the mix could not be built: ${error.message}`);
+    return 2;
+  }
+
+  if (args.save) {
+    await mkdir(dirname(String(args.save)), { recursive: true });
+    await writeFile(String(args.save), `${JSON.stringify(report, null, 1)}\n`, 'utf8');
+    out(`saved report ${report.metadata.report_hash} to ${args.save}`);
+  }
+  if (args.against) {
+    const previous = JSON.parse(await readFile(String(args.against), 'utf8'));
+    const diff = diffDomainMixReports(previous, report);
+    if (!diff.comparable) out(`not comparable: ${diff.reason}`);
+    else renderDomainMixDiff(diff, out);
+  }
+  if (args.json) out(JSON.stringify(report, null, 1));
+  else if (!args.save && !args.against) renderMix(report, out);
+  return 0;
+}

package/cli/platforms.js

@@ -0,0 +1,161 @@
+// `agentlinkops platforms`: the per-platform visibility aggregate over verification results.
+//
+// A placement agent's first question about a self-serve platform is not "can I get a link"
+// but "will the link be VISIBLE" — in served HTML a crawler reads, or written by JavaScript
+// a crawler never runs, or flattened to plain text, or on a page that is noindexed. Those
+// four classes are exactly what the verifier already measures, page by page:
+//
+//   server-html        the link was found in the served HTML (state `present`, link_found)
+//   noindex            the page was read and carries a robots noindex (present or not)
+//   js-only            the page provably needs a browser (`possible_render_required`), or an
+//                      adjudication found the target only in script / in no served bytes
+//   mention-no-anchor  an adjudication found the target in markup but never as a link
+//
+// What the aggregate REFUSES to do matters as much: an `absent` on a rich page contributes
+// the observation but no class vote, because static HTML cannot tell "does not link to us"
+// from "links to us via JavaScript" — the T01 decision, kept. A platform with no observations
+// is unknown, and nothing about an absent platform is inferred.
+//
+// The aggregate is claim-free context: counts, classes and dates from real observations, with
+// their provenance, and no verdict. It can travel with candidate rows for exactly that reason.
+import { readFile } from 'node:fs/promises';
+
+export const PLATFORM_CLASSES = Object.freeze(['server-html', 'js-only', 'mention-no-anchor', 'noindex']);
+
+const normalizeHost = value => {
+  try { return new URL(value).hostname.replace(/^www\./u, ''); } catch { return null; }
+};
+
+/**
+ * One observation row -> one class vote, or none. The precedence is explicit:
+ * noindex beats server-html (a link on a noindexed page is present but not visible),
+ * and an absent/unknown page never votes js-only unless the verifier or an adjudication
+ * PROVED the browser dependency. An `absent` with complete evidence votes nothing.
+ */
+export function classifyObservation(row) {
+  const result = row.result ?? row;
+  const noindex = result.directives?.noindex ?? row.noindex ?? null;
+  if (result.state === 'present' || row.state === 'present') return noindex ? 'noindex' : 'server-html';
+  const reason = result.reason ?? row.reason;
+  if (reason === 'possible_render_required') return 'js-only';
+  return null;
+}
+
+/** A benchmark result row (scripts/verifier-benchmark.mjs shape) classifies the same way. */
+export function classifyBenchmarkRow(row) {
+  if (row.state === 'present') return row.noindex ? 'noindex' : 'server-html';
+  if (row.renderFixable) return 'js-only';
+  return null;
+}
+
+async function readJsonl(path) {
+  const text = await readFile(path, 'utf8');
+  return text.split('\n').filter(line => line.trim()).map(line => JSON.parse(line));
+}
+
+const dayOf = value => String(value ?? '').slice(0, 10);
+
+/**
+ * The aggregate. Sources are stated per platform, because "one adjudication last year" and
+ * "eleven checks this month" are different amounts of knowledge and the reader can tell.
+ */
+export async function platformAggregate({ observations = [], benchmark = [], seed = [] } = {}) {
+  const platforms = new Map();
+  const observe = (host, { klass, at, source }) => {
+    if (!host) return;
+    if (!platforms.has(host)) platforms.set(host, {
+      platform: host, observations: 0, classes: Object.fromEntries(PLATFORM_CLASSES.map(c => [c, 0])),
+      unclassified: 0, last_seen: null, sources: {},
+    });
+    const row = platforms.get(host);
+    row.observations++;
+    if (klass) row.classes[klass]++; else row.unclassified++;
+    if (!row.last_seen || dayOf(at) > dayOf(row.last_seen)) row.last_seen = dayOf(at);
+    row.sources[source] = (row.sources[source] ?? 0) + 1;
+  };
+
+  for (const path of observations) {
+    for (const row of await readJsonl(path)) {
+      observe(normalizeHost(row.result?.sourceUrl ?? row.source), {
+        klass: classifyObservation(row), at: row.checked_at, source: row.source === 'cloud' ? 'cloud-observation' : 'local-observation',
+      });
+    }
+  }
+  for (const path of benchmark) {
+    for (const row of await readJsonl(path)) {
+      observe(normalizeHost(row.sourceUrl), {
+        klass: classifyBenchmarkRow(row), at: row.checked_at, source: 'verifier-benchmark',
+      });
+    }
+  }
+  for (const path of seed) {
+    for (const row of await readJsonl(path)) {
+      observe(normalizeHost(`https://${row.platform}/`), {
+        klass: row.class, at: row.checked_at ?? row.last_seen, source: row.provenance,
+      });
+    }
+  }
+
+  const rows = [...platforms.values()].map(row => {
+    const votes = PLATFORM_CLASSES.map(klass => [klass, row.classes[klass]]).filter(([, n]) => n > 0);
+    votes.sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
+    // A majority needs MORE THAN HALF the classified votes; a tie is not a majority, and
+    // zero classified votes is unknown rather than a default.
+    const classified = votes.reduce((n, [, count]) => n + count, 0);
+    const majority = classified > 0 && votes[0][1] > classified / 2 ? votes[0][0] : null;
+    return { ...row, classified, majority_class: majority,
+      // "unknown" here means "no class evidence", never "checked and absent".
+      status: classified ? 'classified' : 'observed-unclassified' };
+  }).sort((a, b) => b.observations - a.observations || a.platform.localeCompare(b.platform));
+
+  return {
+    v: 1,
+    // No inference from absence: a platform NOT in `platforms` has never been observed,
+    // and the CLI prints exactly that when asked about one.
+    classes: PLATFORM_CLASSES, platforms: rows,
+    totals: {
+      platforms: rows.length,
+      classified: rows.filter(row => row.classified).length,
+      observed_unclassified: rows.filter(row => !row.classified).length,
+      observations: rows.reduce((n, row) => n + row.observations, 0),
+    },
+  };
+}
+
+/** Claim-free context for candidate rows: the platform's numbers, or an explicit unknown. */
+export function attachToCandidates(candidates, aggregate) {
+  const byHost = new Map(aggregate.platforms.map(row => [row.platform, row]));
+  return candidates.map(candidate => {
+    const host = normalizeHost(candidate.source_url ?? candidate.sourceUrl ?? '');
+    const row = host ? byHost.get(host) : null;
+    return {
+      ...candidate,
+      platform_context: row ? {
+        platform: row.platform, observations: row.observations, classified: row.classified,
+        majority_class: row.majority_class, classes: row.classes, last_seen: row.last_seen, sources: row.sources,
+        claim: 'counts_from_our_observations_only',
+      } : { platform: host, observations: 0, majority_class: null, claim: 'no_observations_unknown' },
+    };
+  });
+}
+
+export function renderPlatforms(aggregate, query, out = console.log) {
+  const rows = query
+    ? aggregate.platforms.filter(row => row.platform.includes(query.replace(/^www\./u, '')))
+    : aggregate.platforms;
+  if (query && !rows.length) {
+    out(`no observations for "${query}" — unknown. Nothing is inferred from absence; the platform may be excellent, unmeasured.`);
+    return 0;
+  }
+  out(`platform                 obs  class  majority-class     last-seen   sources`);
+  for (const row of rows.slice(0, query ? 50 : 40)) {
+    out(`${row.platform.padEnd(24)} ${String(row.observations).padStart(4)} ${String(row.classified).padStart(6)}  `
+      + `${(row.majority_class ?? '—').padEnd(16)} ${String(row.unclassified).padStart(3)}u  ${(row.last_seen ?? '').padEnd(10)} ${JSON.stringify(row.sources)}`);
+  }
+  const t = aggregate.totals;
+  out('');
+  out(`${t.platforms} platform(s), ${t.classified} with a class, ${t.observed_unclassified} observed without one, ${t.observations} observations total.`);
+  out('A platform absent from this list has never been observed by us; that is unknown, not a judgement.');
+  if (!query && rows.length > 40) out(`… and ${rows.length - 40} more (pass a HOST substring to filter)`);
+  return 0;
+}

package/cli/receipt-performance.js

@@ -0,0 +1,64 @@
+// Optional local context for a receipt report. Never edits the receipt or verification history.
+import { newestWinningRows, windowComparison, windowFromRange, assertComparable, pageWithinProperty } from '../src/context/gsc.js';
+import { landingPageContext } from '../src/context/ga4.js';
+
+const dayIn = (value, zone) => new Intl.DateTimeFormat('en-CA', { timeZone: zone, year: 'numeric', month: '2-digit', day: '2-digit' }).format(new Date(value));
+function window(value) {
+  for (const key of ['start', 'end']) {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(value?.[key] ?? '') || new Date(`${value[key]}T00:00:00Z`).toISOString().slice(0, 10) !== value[key]) throw new Error('performance windows require valid calendar dates');
+  }
+  return windowFromRange(value.start, value.end);
+}
+const sameWindow = (a, b) => a?.start === b.start && a?.end === b.end;
+const caveats = [
+  'Traffic and search changes are observations, not evidence that this action caused ranking or traffic lift.',
+  'Content edits, technical changes, other links, seasonality, search updates and measurement changes may explain differences; these alternatives have not been ruled out.',
+  'GSC calendar dates use America/Los_Angeles; GA4 retains its property timezone. The populations are separate and are not joined.',
+];
+
+export function attachReceiptPerformance(history, spec, { gscRows = [], ga4Rows = [], now = new Date().toISOString() } = {}) {
+  if (!spec || typeof spec.receipt_id !== 'string') throw new Error('performance requires receipt_id');
+  const selected = history.find(row => row.receipt.id === spec.receipt_id);
+  if (!selected) throw new Error('performance receipt_id not found');
+  const before = window(spec.before), after = window(spec.after);
+  assertComparable(before, after);
+  const actedDay = dayIn(selected.receipt.acted_at, 'America/Los_Angeles');
+  if (before.end >= actedDay || after.start <= actedDay || after.end >= dayIn(now, 'America/Los_Angeles')) throw new Error('performance windows must exclude the action day and unfinished days');
+  if (typeof spec.gsc_property !== 'string' || !pageWithinProperty(selected.receipt.target, spec.gsc_property)) throw new Error('performance requires a GSC property covering the receipt target');
+  if (spec.confounders != null && (!Array.isArray(spec.confounders) || spec.confounders.some(v => typeof v !== 'string' || !v.trim()))) throw new Error('confounders must be nonempty strings');
+  const page = selected.receipt.target;
+  const latest = newestWinningRows(gscRows);
+  const rows = latest.filter(row => row.kind === 'gsc.page' && row.page === page && row.property === spec.gsc_property
+    && row.type === (spec.search_type ?? 'web') && row.aggregationType === 'byPage' && JSON.stringify(row.dimensions) === '["page"]' && row.dataState === 'final');
+  const a = rows.find(row => sameWindow(row.window, after)), b = rows.find(row => sameWindow(row.window, before));
+  let search;
+  if (!a || !b) search = { state: 'missing_window', delta: null };
+  else if ([a, b].some(row => latest.some(marker => marker.kind === 'gsc.window' && marker.property === row.property
+    && marker.type === row.type && marker.aggregationType === row.aggregationType && marker.dataState === row.dataState
+    && JSON.stringify(marker.dimensions) === JSON.stringify(row.dimensions) && sameWindow(marker.window, row.window)
+    && (marker.fetched_at ?? '') > (row.fetched_at ?? '')))) search = { state: 'superseded_window', delta: null };
+  else if ([a, b].some(row => row.first_incomplete_date || row.incomplete || row.truncated)) search = { state: 'incomplete_window', delta: null };
+  else if ([a, b].some(row => ['clicks', 'impressions', 'position'].some(key => !Number.isFinite(row[key])))) search = { state: 'missing_metrics', delta: null };
+  else search = windowComparison({ rows: [a, b], windowA: after, windowB: before, property: spec.gsc_property, page });
+  search = { ...search, property: spec.gsc_property, page, timezone: 'America/Los_Angeles', before: b ?? null, after: a ?? null, delta_direction: 'after_minus_before' };
+  let business = { state: 'ga4_absent', before: null, after: null };
+  if (spec.ga4_property) {
+    const propertyRows = ga4Rows.filter(row => row.property === spec.ga4_property);
+    const read = wanted => ({ ...landingPageContext({ rows: propertyRows, page, window: wanted, connection: { property: spec.ga4_property, grant: 'unknown' } }),
+      provenance: propertyRows.filter(row => sameWindow(row.window, wanted)).map(row => ({ fetched_at: row.fetched_at ?? null, retrieved_by: row.retrieved_by ?? null })) });
+    business = { relation: 'side_by_side_not_joined', property: spec.ga4_property, before: read(before), after: read(after), delta: null };
+    const zones = [business.before.time_zone, business.after.time_zone];
+    const comparable = zones[0] && zones[0] === zones[1] && business.before.state === 'ok' && business.after.state === 'ok'
+      && before.end < dayIn(selected.receipt.acted_at, zones[0]) && after.start > dayIn(selected.receipt.acted_at, zones[0])
+      && after.end < dayIn(now, zones[0]) && business.before.currency_code === business.after.currency_code;
+    business.state = comparable ? 'dated_context' : 'not_comparable';
+  }
+  const performance_context = {
+    generated_at: now, receipt_id: selected.receipt.id, acted_at: selected.receipt.acted_at,
+    declared_at: selected.receipt.declared_at, verification_baseline: selected.receipt.baseline,
+    windows: { before, after, action_day_excluded: actedDay }, search, business,
+    confounders: { reported: spec.confounders ?? [], assessment: 'not_ruled_out' }, caveats,
+    attribution: 'not_established',
+  };
+  return history.map(row => row === selected ? { ...row, performance_context } : row);
+}

package/cli/receipts.js

@@ -0,0 +1,122 @@
+// Local claims, joined to existing facts by ledger id. No network and no cloud receipt.
+import { readFile, writeFile, mkdir, rename, unlink } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { normalizeEntry, readLedger } from './ledger.js';
+import { checkObservationKind } from '../src/verifier/observation-kind.js';
+import { readObservations } from './mirror.js';
+import { readState } from './state.js';
+
+const textAt = async path => readFile(path, 'utf8').catch(error => {
+  if (error.code === 'ENOENT') return ''; throw error;
+});
+const core = row => JSON.stringify([row.kind, row.source, row.target, row.scope ?? 'exact', row.acted_at]);
+const placement = row => JSON.stringify([row.source, row.target, row.scope ?? 'exact']);
+const date = value => typeof value === 'string' && /^\d{4}-\d\d-\d\dT.*(?:Z|[+-]\d\d:\d\d)$/.test(value) && Number.isFinite(Date.parse(value));
+
+export async function readReceipts(path) {
+  const rows = [], ids = new Set(), keys = new Set();
+  for (const [i, line] of (await textAt(path)).split('\n').entries()) {
+    if (!line.trim()) continue;
+    try {
+      const row = JSON.parse(line);
+      if (!/^ar_[a-z0-9]{4,32}$/.test(row.id) || !/^lk_[a-z0-9]{4,32}$/.test(row.ledger)
+        || !['internal', 'external'].includes(row.kind) || row.report?.state !== 'claimed'
+        || !date(row.acted_at) || !date(row.declared_at) || !('baseline' in row)
+        || !['human', 'agent'].includes(row.actor?.role)) throw new Error('invalid receipt claim');
+      normalizeEntry({ ...row, id: row.ledger, intent: row.intent_after ?? 'wanted' });
+      if (ids.has(row.id) || (row.idempotency && keys.has(row.idempotency))) throw new Error('duplicate receipt identity or idempotency key');
+      ids.add(row.id); if (row.idempotency) keys.add(row.idempotency);
+      rows.push(row);
+    } catch (error) { throw new Error(`receipts line ${i + 1}: ${error.message}`); }
+  }
+  return rows;
+}
+
+// A recoverable two-file append. A crash after the entry write cannot mint another identity.
+// Before/after comparisons refuse concurrent manual edits; recovery never overwrites them.
+async function finishTransaction(path, tx, afterWrite = async () => {}) {
+  for (const part of tx.parts) {
+    const held = await textAt(part.path);
+    if (held === part.after) continue;
+    if (held !== part.before) throw new Error(`receipt transaction conflict at ${part.path}; preserve edits and reconcile ${path}`);
+    await mkdir(dirname(part.path), { recursive: true });
+    const tmp = `${part.path}.${crypto.randomUUID()}.tmp`;
+    await writeFile(tmp, part.after, 'utf8');
+    await rename(tmp, part.path);
+    await afterWrite(part.path);
+  }
+  await unlink(path);
+}
+
+export async function writeReceipt(config, input, { now = new Date().toISOString(), afterWrite } = {}) {
+  await mkdir(config.dir, { recursive: true });
+  const lock = `${config.paths.ledger}.lock`;
+  let handle;
+  try { handle = await import('node:fs/promises').then(fs => fs.open(lock, 'wx')); }
+  catch (error) { if (error.code === 'EEXIST') throw new Error(`receipt writer locked: ${lock}; remove only after confirming its writer stopped`); throw error; }
+  const journal = join(config.dir, 'receipt-transaction.json');
+  try {
+    const pending = await textAt(journal);
+    if (pending) await finishTransaction(journal, JSON.parse(pending), afterWrite);
+    const ledger = await readLedger(config.paths.ledger);
+    if (ledger.missing || ledger.problems.length) throw new Error('receipt requires a valid existing ledger');
+    const receipts = await readReceipts(config.paths.receipts);
+    const proposed = input.intent_after ?? (input.kind === 'internal' ? 'expected' : 'wanted');
+    const entry = normalizeEntry({ source: input.source, target: input.target, scope: input.scope,
+      intent: proposed, expect: input.expect, ref: input.ref, tags: input.tags, note: input.note,
+      added: now.slice(0, 10) }, { assignId: true });
+    const kind = checkObservationKind({ kind: input.kind, sourceUrl: entry.source, targetUrl: entry.target }, config.project?.site);
+    if (!kind.valid) throw new Error(kind.reason);
+    if (!date(input.acted_at) || !date(now)) throw new Error('acted_at must be an ISO timestamp with timezone');
+    if (!['human', 'agent'].includes(input.actor?.role)) throw new Error('actor.role must be human or agent');
+    if (input.report && input.report.state !== 'claimed') throw new Error('report.state must remain claimed');
+    if (input.idempotency != null && (typeof input.idempotency !== 'string' || !input.idempotency.trim())) throw new Error('idempotency must be a nonempty string');
+    const replay = input.idempotency && receipts.find(row => row.idempotency === input.idempotency);
+    if (replay) {
+      if (core(replay) !== core(input)) throw new Error('idempotency key is bound to a different core claim');
+      return { receipt: replay, created: false };
+    }
+    const matches = ledger.entries.filter(row => placement(row) === placement(entry));
+    if (matches.length > 1) throw new Error('ambiguous placement: multiple ledger entries');
+    const existing = input.ledger ? ledger.entries.find(row => row.id === input.ledger) : matches[0];
+    if (input.ledger && (!existing || placement(existing) !== placement(entry))) throw new Error('ledger reference does not match receipt placement');
+    const linked = existing ?? entry;
+    const observations = await readObservations(config.paths.observations);
+    if (observations.problems.length) throw new Error('cannot pin baseline from malformed observations');
+    const state = await readState(config.paths.state);
+    const prior = observations.rows.filter(row => row.id === linked.id && row.result?.sourceUrl === entry.source && row.result?.targetUrl === entry.target && (row.result?.targetScope ?? 'exact') === entry.scope && Date.parse(row.checked_at) <= Date.parse(now))
+      .sort((a, b) => Date.parse(b.checked_at) - Date.parse(a.checked_at))[0];
+    let baseline = prior ? { checked_at: prior.checked_at, state: prior.state, reason: prior.reason ?? null, complete: prior.complete === true } : null;
+    const activity = state.entries?.[linked.id];
+    if (activity && activity.last_placement === placement(entry) && Date.parse(activity.last_checked) <= Date.parse(now) && (!baseline || Date.parse(activity.last_checked) > Date.parse(baseline.checked_at))) {
+      baseline = { checked_at: activity.last_checked, state: activity.last_state, reason: activity.last_reason ?? null,
+        complete: activity.last_complete ?? (prior?.state === activity.last_state && prior?.reason === activity.last_reason ? prior.complete === true : false) };
+    }
+    const receipt = { ...input, id: `ar_${crypto.randomUUID().replaceAll('-', '').slice(0, 16)}`,
+      source: entry.source, target: entry.target, scope: entry.scope, declared_at: now,
+      report: { ...input.report, state: 'claimed' }, baseline, ledger: linked.id, intent_after: proposed };
+    const parts = [];
+    for (const [path, row] of [[config.paths.ledger, existing ? null : entry], [config.paths.receipts, receipt]]) {
+      if (!row) continue;
+      const before = await textAt(path);
+      parts.push({ path, before, after: before + (before && !before.endsWith('\n') ? '\n' : '') + JSON.stringify(row) + '\n' });
+    }
+    await writeFile(journal, JSON.stringify({ parts }), { flag: 'wx' });
+    await finishTransaction(journal, { parts }, afterWrite);
+    return { receipt, created: true };
+  } finally { await handle.close(); await unlink(lock); }
+}
+
+export function receiptHistory(receipts, entries, observations, state) {
+  return receipts.map(receipt => {
+    const entry = entries.find(row => row.id === receipt.ledger);
+    const history = observations.filter(row => row.id === receipt.ledger).sort((a, b) => Date.parse(a.checked_at) - Date.parse(b.checked_at));
+    const activity = state.entries?.[receipt.ledger];
+    const firstPresent = [activity?.first_present_placement === placement(receipt) ? activity.first_present : null, ...history.filter(row => row.state === 'present' && row.complete && row.result?.sourceUrl === receipt.source && row.result?.targetUrl === receipt.target && (row.result?.targetScope ?? 'exact') === receipt.scope).map(row => row.checked_at)]
+      .filter(Boolean).sort((a, b) => Date.parse(a) - Date.parse(b))[0] ?? null;
+    return { receipt, entry_missing: !entry, placement_changed: !!entry && placement(entry) !== placement(receipt),
+      intent_proposal_differs: !!entry && entry.intent !== receipt.intent_after,
+      latest: history.at(-1) ?? null, first_present: firstPresent,
+      novelty: receipt.baseline?.state === 'present' || (firstPresent && Date.parse(firstPresent) < Date.parse(receipt.acted_at)) ? 'contradicted' : 'unproven', history };
+  });
+}

package/cli/report.js

@@ -0,0 +1,158 @@
+// `agentlinkops report`: one self-contained HTML file, reproducible from a frozen dataset.
+//
+// **Reproducible is the requirement, and it is the one that constrains the design.** The same
+// ledger and the same observations must produce byte-identical output, because a report a
+// customer sends to a client is a document they may have to produce again months later and
+// defend as unchanged. So: no clock read that is not an input, no random ids, stable ordering,
+// and a content digest printed in the footer so "identical" is checkable rather than claimed.
+//
+// **A report timestamp does not make its observations fresh.** Every row carries the date IT was
+// observed, and the header states the range, because the single most misleading thing a link
+// report can do is print today's date above a figure from March.
+//
+// Self-contained: no external stylesheet, font, script or image. That makes it openable offline
+// forever, printable to PDF from any browser, and incapable of telling anyone it was opened.
+import { createHash } from 'node:crypto';
+import { latestByEntry } from './mirror.js';
+
+export const REPORT_VERSION = 1;
+
+/** HTML-escape. Every value below is publisher or customer content and none of it is trusted. */
+export const escape = value => String(value ?? '')
+  .replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;')
+  .replaceAll('"', '&quot;').replaceAll("'", '&#39;');
+
+const STATE_LABEL = Object.freeze({
+  present: 'Present', absent: 'Not found', unknown: 'Could not check',
+  source_unavailable: 'Page unavailable', unchecked: 'Never checked',
+});
+
+/**
+ * The frozen dataset a report renders.
+ *
+ * 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 } = {}) {
+  const latest = latestByEntry(observations);
+  const rows = entries
+    .filter(entry => includeRetired || entry.intent !== 'retired')
+    .map(entry => {
+      const row = latest.get(entry.id) ?? null;
+      return {
+        id: entry.id, intent: entry.intent, source: entry.source, target: entry.target, scope: entry.scope,
+        expected_anchor: entry.expect?.anchor ?? null,
+        state: row?.state ?? 'unchecked',
+        reason: row?.reason ?? null,
+        occurrences: row?.occurrences ?? 0,
+        checked_at: row?.checked_at ?? null,
+        checked_by: row?.source ?? null,
+        anchor: row?.result?.occurrences?.[0]?.anchor ?? null,
+        rel: row?.result?.occurrences?.[0]?.rel ?? [],
+        // Opt-in, because a note can hold commercial context — what a placement cost, what a
+        // publisher said — and a report is the document most likely to be forwarded.
+        note: includeNotes ? (entry.note ?? null) : null,
+        ref: includeNotes ? (entry.ref ?? null) : null,
+      };
+    })
+    // Stable ordering, by state then id: byte-identical output needs a total order with no ties
+    // broken by insertion.
+    .sort((a, b) => (a.state === b.state ? (a.id < b.id ? -1 : 1) : (a.state < b.state ? -1 : 1)));
+
+  const dates = rows.map(row => row.checked_at).filter(Boolean).sort();
+  const counts = rows.reduce((acc, row) => { acc[row.state] = (acc[row.state] ?? 0) + 1; return acc; }, {});
+  return {
+    v: REPORT_VERSION, title, as_of: asOf, include_notes: includeNotes,
+    rows,
+    totals: { entries: rows.length, ...counts },
+    // 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,
+      observed_from: dates[0] ?? null,
+      observed_to: dates.at(-1) ?? null,
+    },
+  };
+}
+
+const STYLE = `
+:root{color-scheme:light}
+*{box-sizing:border-box}
+body{margin:0;padding:32px;font:14px/1.5 -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Helvetica,Arial,sans-serif;color:#1a1a1a;background:#fff}
+h1{font-size:22px;margin:0 0 4px}
+.sub{color:#555;margin:0 0 24px}
+.cards{display:flex;flex-wrap:wrap;gap:12px;margin:0 0 24px}
+.card{border:1px solid #ddd;border-radius:6px;padding:10px 14px;min-width:120px}
+.card b{display:block;font-size:20px}
+.card span{color:#555;font-size:12px}
+table{border-collapse:collapse;width:100%;font-size:13px}
+th,td{text-align:left;vertical-align:top;padding:8px 10px;border-bottom:1px solid #eee}
+th{background:#fafafa;border-bottom:1px solid #ddd;font-weight:600}
+td.url{word-break:break-all;max-width:340px}
+.state{display:inline-block;padding:1px 8px;border-radius:10px;font-size:12px;border:1px solid #ccc}
+.present{background:#eef7ee;border-color:#b6d7b6}
+.absent{background:#fdeeee;border-color:#e2b6b6}
+.unknown,.unchecked,.source_unavailable{background:#f6f6f6}
+.note{color:#555;font-size:12px}
+footer{margin-top:28px;padding-top:12px;border-top:1px solid #eee;color:#555;font-size:12px}
+.caveat{margin:18px 0;padding:10px 14px;border-left:3px solid #ddd;color:#444;font-size:13px}
+@media print{body{padding:0}th{background:#fff}tr{break-inside:avoid}.card{break-inside:avoid}}
+`.trim();
+
+/**
+ * Renders the frozen dataset. A pure function of its argument: same input, same bytes.
+ *
+ * The digest in the footer is over the DATASET rather than over the HTML, so it stays stable
+ * across a cosmetic change to this template while still changing the moment a figure does.
+ */
+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 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>${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>
+      ${dataset.include_notes ? `<td class="note">${escape(row.ref ?? '')}${row.note ? `<div>${escape(row.note)}</div>` : ''}</td>` : ''}
+    </tr>`).join('\n');
+
+  return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>${escape(dataset.title)}</title><style>${STYLE}</style></head>
+<body>
+<h1>${escape(dataset.title)}</h1>
+<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)}
+</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>
+<p class="caveat"><strong>What a result means.</strong> &ldquo;Present&rdquo; means the link was in
+the HTML the publisher served. &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.
+JavaScript execution and visual visibility were not checked.</p>
+<table><thead><tr>
+<th>Source page</th><th>Target</th><th>Result</th><th>Anchor</th><th>Observed</th>${dataset.include_notes ? '<th>Notes</th>' : ''}
+</tr></thead><tbody>
+${rows}
+</tbody></table>
+<footer>
+AgentLinkOps report v${dataset.v}. Dataset digest <code>${escape(digest)}</code> &mdash; the same
+ledger and observations always produce this digest.
+${dataset.include_notes ? 'Private notes are included in this document.' : 'Private notes and references are excluded.'}
+</footer>
+</body></html>
+`;
+}
+
+/** The digest a caller can compare without rendering. */
+export const datasetDigest = dataset => createHash('sha256').update(JSON.stringify(dataset)).digest('hex');