Activity ${activity.available ? 'recorded' : 'not supplied or not retained'}; identity ${escape(activity.identity_status ?? 'not retained')}
`;
+ };
// 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 => `
What these dates mean. 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.` : ''}
+than it is. ${coverage.never_checked ? `${coverage.never_checked} of ${dataset.totals.entries} links have never been checked and are listed as such.` : ''}${hasActivity ? '\n
Activity and verification. 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.
' : ''}
What a result means. “Present” means the link was in
the observed HTML. “Could not check” is not the same as
“not found”: 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.
-
Source page
Target
Result
Anchor
Observed
Evidence
${hasIndex?'
Index evidence
':''}${dataset.include_notes ? '
Notes
' : ''}
+
Source page
Target
Result
Anchor
Observed
Evidence
${hasActivity ? '
Activity and verified state
' : ''}${hasIndex?'
Index evidence
':''}${dataset.include_notes ? '
Notes
' : ''}
${rows}
@@ -219,7 +251,7 @@ ${receiptRows}
` : ''}
diff --git a/cli/state.js b/cli/state.js
index e3e6098..c71de1d 100644
--- a/cli/state.js
+++ b/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 };
}
diff --git a/cli/status.js b/cli/status.js
index 83e7308..94ee5ea 100644
--- a/cli/status.js
+++ b/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;
}
diff --git a/package-lock.json b/package-lock.json
index 3eae9c3..335658c 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "agentlinkops",
- "version": "0.6.12",
+ "version": "0.6.13",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "agentlinkops",
- "version": "0.6.12",
+ "version": "0.6.13",
"license": "Apache-2.0",
"dependencies": {
"@modelcontextprotocol/client": "2.2.0",
diff --git a/package.json b/package.json
index cd065c4..2d36f6f 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "agentlinkops",
- "version": "0.6.12",
+ "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",
diff --git a/shared/index-observation-contract.js b/shared/index-observation-contract.js
index 429466f..f06672f 100644
--- a/shared/index-observation-contract.js
+++ b/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();
diff --git a/shared/monitoring-chronology-export.js b/shared/monitoring-chronology-export.js
new file mode 100644
index 0000000..d85daf5
--- /dev/null
+++ b/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.sortAtb.id?-1:a.idArray.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;i12000: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);
+}
diff --git a/shared/monitoring-read-contract.js b/shared/monitoring-read-contract.js
new file mode 100644
index 0000000..310a1d9
--- /dev/null
+++ b/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.'}};
diff --git a/shared/response-contract.js b/shared/response-contract.js
index b3bdf40..6d9e7e2 100644
--- a/shared/response-contract.js
+++ b/shared/response-contract.js
@@ -1,3 +1,4 @@
+import {chronologyResponse,assuranceResponse} from './monitoring-read-contract.js';
import {lifecycleOutput} from './lifecycle-contract.js';
import {searchConnectionsResponse,searchRowsResponse,searchSyncResponse,searchPropertiesResponse,searchStartResponse,searchConnection,searchImportResponse} from './search-connection-contract.js';
import {z} from 'zod';
@@ -55,6 +56,8 @@ export function restResponseContract(path,method='GET') {
if(/^\/v1\/search-connections\/[^/]+\/disconnect$/.test(pathname)&&method==='POST')return z.object({disconnected:z.literal(true),retainedRows:z.literal(true)});
if(/^\/v1\/search-connections\/[^/]+$/.test(pathname)&&method==='DELETE')return z.object({forgotten:z.literal(true)});
if(method!=='GET')return objectResponse;
+ if(/^\/v1\/watches\/[^/]+\/chronology$/.test(pathname))return chronologyResponse;
+ if(/^\/v1\/projects\/[^/]+\/monitoring-assurance$/.test(pathname))return assuranceResponse;
if(/^\/v1\/(?:watches|targets)\/[^/]+\/history$/.test(pathname))return historyResponse;
if(/^\/v1\/watches\/[^/]+$/.test(pathname))return watchResponse;
if(/^\/v1\/targets\/[^/]+$/.test(pathname))return targetResponse;
diff --git a/skills/agentlinkops-connect/references/agentlinkops.md b/skills/agentlinkops-connect/references/agentlinkops.md
index cce2c08..e7a2218 100644
--- a/skills/agentlinkops-connect/references/agentlinkops.md
+++ b/skills/agentlinkops-connect/references/agentlinkops.md
@@ -9,7 +9,7 @@ records. This page is the complete agent reference: the same text prints from
full once per session, then use `describe` (or `exec describe` on MCP) for any command's exact schema.
-Pack version 0.6.12. 139 commands in 15 toolsets.
+Pack version 0.6.13. 147 commands in 16 toolsets.
## Install and connect (once per machine)
@@ -269,18 +269,19 @@ The human-readable version is
## Tool reference
-139 commands in 15 toolsets, generated from `src/tool-registry.js` (`npm run generate:tools`). Core on every view: `get_workspace`, `list_projects`, `list_link_watches`, `monitor_link`, `list_events`. The index verbs list the rest by name; `describe` is the source of truth for input schemas. Admission-gated today: prepare_domain_baseline, start_domain_baseline, request_competitor_inventory, request_domain_overview, discover_backlinks; these refuse before any persistence.
+147 commands in 16 toolsets, generated from `src/tool-registry.js` (`npm run generate:tools`). Core on every view: `get_workspace`, `list_projects`, `list_link_watches`, `monitor_link`, `list_events`. The index verbs list the rest by name; `describe` is the source of truth for input schemas. Admission-gated today: prepare_domain_baseline, start_domain_baseline, request_competitor_inventory, request_domain_overview, discover_backlinks; these refuse before any persistence.
| Toolset | Commands | What it covers |
| --- | --- | --- |
| `monitoring` | 17 | Watch earned links and destination URLs: create, list, update, import, export, recheck. |
| `evidence` | 17 | What a check observed: histories, snapshots, change feeds, check jobs, published contacts. |
| `rank` | 5 | Synthetic DataForSEO rank schedules and dated history; hosted collection disabled. |
+| `licensed` | 6 | Licensed source-search evidence and charge custody; operator admission required. |
| `discovery` | 16 | Import candidate rows, read stored runs, verify selected candidates, enroll them. |
| `baseline` | 7 | Scoped backlink baselines; supplier admission disabled. |
| `library` | 3 | Read and export the coverage-stated opportunity library. |
| `competitors` | 17 | Competitor sets, dated inventories, scheduled refresh, gap and domain-mix reports. |
-| `reports` | 7 | Profile, anchor and report summaries over the tracked dataset. |
+| `reports` | 9 | Placement chronology, service assurance and backlink reports. |
| `workspace` | 16 | Workspace, projects, usage, members, invitations, scratch-resource cleanup. |
| `notifications` | 6 | Email notification preferences, previews, tests and deliveries. |
| `webhooks` | 6 | Webhook endpoints, state, secrets and delivery records. |
diff --git a/src/tool-views.js b/src/tool-views.js
index 323d1ca..bdf356e 100644
--- a/src/tool-views.js
+++ b/src/tool-views.js
@@ -3,7 +3,7 @@
// script, the MCP router, the CLI index and the generators all read the same definitions.
// Rules: docs/technical/AGENT-SURFACE-CONTRACT.md (DP-0036).
-export const TOOLSETS = ['monitoring','evidence','rank','discovery','baseline','library','competitors','reports','workspace','notifications','webhooks','admission','disavow','lifecycle','digests'];
+export const TOOLSETS = ['monitoring','evidence','rank','licensed','discovery','baseline','library','competitors','reports','workspace','notifications','webhooks','admission','disavow','lifecycle','digests'];
// One line per toolset: what the group is for. Printed by the site brief, the REST index and the
// catalog snapshot so the same wording reaches every client; a toolset without a summary is a
@@ -16,11 +16,12 @@ export const TOOLSET_SUMMARIES = {
monitoring: 'Watch earned links and destination URLs: create, list, update, import, export, recheck.',
evidence: 'What a check observed: histories, snapshots, change feeds, check jobs, published contacts.',
rank: 'Synthetic DataForSEO rank schedules and dated history; hosted collection disabled.',
+ licensed: 'Licensed source-search evidence and charge custody; operator admission required.',
discovery: 'Import candidate rows, read stored runs, verify selected candidates, enroll them.',
baseline: 'Scoped backlink baselines; supplier admission disabled.',
library: 'Read and export the coverage-stated opportunity library.',
competitors: 'Competitor sets, dated inventories, scheduled refresh, gap and domain-mix reports.',
- reports: 'Profile, anchor and report summaries over the tracked dataset.',
+ reports: 'Placement chronology, service assurance and backlink reports.',
workspace: 'Workspace, projects, usage, members, invitations, scratch-resource cleanup.',
notifications: 'Email notification preferences, previews, tests and deliveries.',
webhooks: 'Webhook endpoints, state, secrets and delivery records.',
@@ -57,10 +58,10 @@ export function oneLiner(description, max = 60) {
}
// entries: [{ name, description, toolset, tier, readOnly }]. Grouped, one line per command.
-export function manifestText(entries, { max = 36 } = {}) {
+export function manifestText(entries, { max = 28 } = {}) {
const groups = new Map(TOOLSETS.map(t => [t, []]));
for (const entry of entries) (groups.get(entry.toolset) ?? groups.set(entry.toolset, []).get(entry.toolset)).push(entry);
- const lines = ['Commands by toolset (name: what it does). On /mcp use exec: `exec search `, `exec describe `, `exec call `; the CLI mirrors the verbs as `agentlinkops tools | describe | call`.'];
+ const lines = ['Commands by toolset. MCP: `exec search `, `exec describe `, `exec call `. CLI: `agentlinkops tools | describe | call`. Licensed supplier calls require operator admission.'];
for (const [toolset, members] of groups) {
if (!members.length) continue;
lines.push(`\n${toolset}:`);
diff --git a/test/cli-check.test.js b/test/cli-check.test.js
index 388bab6..82f2083 100644
--- a/test/cli-check.test.js
+++ b/test/cli-check.test.js
@@ -166,7 +166,7 @@ test('the ledger maps to a watch, and a corrected URL keeps its history', () =>
test('status proposes a promotion and refuses to make it', async () => {
const entries = [normalizeEntry({ id: 'lk_pitched1', intent: 'wanted', source: SOURCE, target: TARGET })];
- const rows = [observationRow('lk_pitched1', { state: 'present', reason: 'link_found', checkedAt: '2026-09-14T09:00:00.000Z', occurrences: [{}], evidence: { complete: true } })];
+ const rows = [observationRow('lk_pitched1', { sourceUrl: SOURCE, targetUrl: TARGET, state: 'present', reason: 'link_found', checkedAt: '2026-09-14T09:00:00.000Z', occurrences: [{}], evidence: { complete: true } })];
const found = disagreements(entries, rows);
assert.equal(found.length, 1);
assert.equal(found[0].kind, 'appeared');
@@ -242,7 +242,7 @@ test('check is due-driven, so running it twice does not refetch the web', () =>
test('a repeated answer is activity, not a new observation', () => {
const at = day => `2026-09-${String(day).padStart(2, '0')}T00:00:00.000Z`;
- const present = day => observationRow('lk_stable01', { state: 'present', reason: 'link_found', checkedAt: at(day), occurrences: [{}], linkSignature: 'sig1', evidence: { complete: true } });
+ const present = day => observationRow('lk_stable01', { sourceUrl: SOURCE, targetUrl: TARGET, targetScope: 'exact', state: 'present', reason: 'link_found', checkedAt: at(day), occurrences: [{}], linkSignature: 'sig1', evidence: { complete: true } });
let state = { v: 1, entries: {} };
let split = selectChanged([present(1)], state);
@@ -259,11 +259,12 @@ test('a repeated answer is activity, not a new observation', () => {
// A link still present whose anchor or rel changed IS an event. Comparing only the state
// would file it as more of the same.
- const changedAnchor = observationRow('lk_stable01', { state: 'present', reason: 'link_found', checkedAt: at(4), occurrences: [{}], linkSignature: 'sig2', evidence: { complete: true } });
+ const changedAnchor = observationRow('lk_stable01', { sourceUrl: SOURCE, targetUrl: TARGET, targetScope: 'exact', state: 'present', reason: 'link_found', checkedAt: at(4), occurrences: [{}], linkSignature: 'sig2', evidence: { complete: true } });
assert.equal(selectChanged([changedAnchor], state).changed.length, 1);
});
test('init, add, fmt and check work end to end from the command line', async t => {
+ t.mock.method(globalThis, 'fetch', () => assert.fail('a matching not-due placement must not fetch'));
const space = await workspace(t);
let result = await run(space.dir, ['add', '--source', SOURCE, '--target', TARGET, '--intent', 'expected', '--anchor', 'guide', '--ref', 'q3/1']);
assert.equal(result.code, 0);
@@ -286,7 +287,7 @@ test('init, add, fmt and check work end to end from the command line', async t =
// A ledger with nothing due says so rather than silently doing nothing. Due-ness comes from
// state.json, so a recorded observation alone does not make an entry not-due.
- const row = observationRow(id, { state: 'present', reason: 'link_found', checkedAt: new Date().toISOString(), occurrences: [{}], evidence: { complete: true } });
+ const row = observationRow(id, { sourceUrl: SOURCE, targetUrl: TARGET, targetScope: 'exact', state: 'present', reason: 'link_found', checkedAt: new Date().toISOString(), occurrences: [{}], evidence: { complete: true } });
await writeFile(space.observations, `${JSON.stringify(row)}\n`, 'utf8');
await writeFile(join(space.dir, '.agentlinkops/state.json'), `${JSON.stringify(applyRun({ v: 1, entries: {} }, [row]), null, 1)}\n`, 'utf8');
result = await run(space.dir, ['check']);
@@ -310,7 +311,7 @@ test('check --json keeps stdout empty when there are no observations due and pre
const space = await workspace(t);
const fetchMock = t.mock.method(globalThis, 'fetch', () => assert.fail('an empty check must not fetch'));
const entry = normalizeEntry({ id: 'lk_jsonempty', intent: 'expected', source: SOURCE, target: TARGET });
- const row = observationRow(entry.id, { state: 'present', reason: 'link_found', checkedAt: new Date().toISOString(), occurrences: [{}], evidence: { complete: true } });
+ const row = observationRow(entry.id, { sourceUrl: SOURCE, targetUrl: TARGET, targetScope: 'exact', state: 'present', reason: 'link_found', checkedAt: new Date().toISOString(), occurrences: [{}], evidence: { complete: true } });
const scenarios = [
{ name: 'empty ledger', entries: [], args: [], count: 0 },
{ name: 'not due', entries: [entry], args: [], count: 1 },
diff --git a/test/cli-chronology.test.js b/test/cli-chronology.test.js
new file mode 100644
index 0000000..b6830ba
--- /dev/null
+++ b/test/cli-chronology.test.js
@@ -0,0 +1,76 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {mkdtemp,writeFile,readFile,rm} from 'node:fs/promises';
+import {tmpdir} from 'node:os';
+import {join} from 'node:path';
+import {chronologyMain} from '../cli/chronology.js';
+const page={schemaVersion:1,identity:{workspaceId:'ws',projectId:'pr',watchId:'watch',sourceUrl:'https://publisher.example/page',targetUrl:'https://example.org/',targetScope:'exact',targetId:null,localReference:null,matchBasis:'configured_target_url'},asOf:'2026-10-07T00:00:00.000Z',snapshotId:'a'.repeat(64),items:[],pageCursor:null,nextCursor:'next',hasMore:true,coverage:{context:{status:'available',reason:'retained_rows_only',hasMore:false},link_events:{status:'denied',reason:'insufficient_scope'}},historyMeaning:'Retained records only.'};
+test('offline export is deterministic, explicit about partial paging and has no network or ledger dependency',async t=>{
+ const dir=await mkdtemp(join(tmpdir(),'alo-chronology-'));t.after(()=>rm(dir,{recursive:true,force:true}));await writeFile(join(dir,'pages.json'),JSON.stringify([page]));
+ const args={_:['chronology','export'],tag:[],pages:'pages.json',out:'export.json'};
+ await chronologyMain(args,{cwd:dir,out:()=>{},fetchImpl:()=>{throw Error('unexpected network');}});
+ const first=await readFile(join(dir,'export.json'),'utf8');await chronologyMain({...args,out:'export2.json'},{cwd:dir,out:()=>{}});assert.equal(await readFile(join(dir,'export2.json'),'utf8'),first);
+ await assert.rejects(chronologyMain(args,{cwd:dir,out:()=>{}}),{code:'EEXIST'});assert.equal(await readFile(join(dir,'export.json'),'utf8'),first);
+ const input=await readFile(join(dir,'pages.json'),'utf8');await assert.rejects(chronologyMain({...args,out:'pages.json'},{cwd:dir,out:()=>{}}),{code:'EEXIST'});assert.equal(await readFile(join(dir,'pages.json'),'utf8'),input);
+ const data=JSON.parse(first);assert.equal(data.pagination.complete,false);assert.equal(data.pagination.reason,'partial_pagination');assert.equal(data.coverage.link_events.status,'denied');assert.match(data.contentHash,/^[a-f0-9]{64}$/);
+});
+test('offline export refuses mixed placement snapshots before writing output',async t=>{
+ const dir=await mkdtemp(join(tmpdir(),'alo-chronology-'));t.after(()=>rm(dir,{recursive:true,force:true}));await writeFile(join(dir,'pages.json'),JSON.stringify([page,{...page,identity:{...page.identity,watchId:'other'}}]));
+ await assert.rejects(chronologyMain({_:['chronology','export'],tag:[],pages:'pages.json',out:'export.json'},{cwd:dir,out:()=>{}}),{code:'CHRONOLOGY_EXPORT_SCOPE_MISMATCH'});
+ await assert.rejects(readFile(join(dir,'export.json')),{code:'ENOENT'});
+});
+
+test('offline export refuses absent or malformed placement identity before writing output',async t=>{
+ const dir=await mkdtemp(join(tmpdir(),'alo-chronology-'));t.after(()=>rm(dir,{recursive:true,force:true}));
+ const malformed=[undefined,null,{}, {...page.identity,projectId:''},{...page.identity,targetScope:'any'},{...page.identity,sourceUrl:'file:///tmp/source'},{...page.identity,matchBasis:undefined}];
+ for(const identity of malformed){
+ await writeFile(join(dir,'pages.json'),JSON.stringify({...page,identity}));
+ await assert.rejects(chronologyMain({_:['chronology','export'],tag:[],pages:'pages.json',out:'export.json'},{cwd:dir,out:()=>{}}),{code:'INVALID_CHRONOLOGY_EXPORT'});
+ await assert.rejects(readFile(join(dir,'export.json')),{code:'ENOENT'});
+ }
+});
+
+test('new export path works on the checkout filesystem and refuses replacement',async t=>{
+ const dir=await mkdtemp(new URL('../.chronology-export-',import.meta.url).pathname);t.after(()=>rm(dir,{recursive:true,force:true}));
+ await writeFile(join(dir,'pages.json'),JSON.stringify([page]));
+ const args={_:['chronology','export'],tag:[],pages:'pages.json',out:'export.json'};
+ await chronologyMain(args,{cwd:dir,out:()=>{}});const first=await readFile(join(dir,'export.json'),'utf8');
+ assert.match(JSON.parse(first).contentHash,/^[a-f0-9]{64}$/);
+ await assert.rejects(chronologyMain(args,{cwd:dir,out:()=>{}}),{code:'EEXIST'});assert.equal(await readFile(join(dir,'export.json'),'utf8'),first);
+});
+
+test('offline export rejects malformed terminal and continuation metadata without output or a new file',async t=>{
+ const dir=await mkdtemp(join(tmpdir(),'alo-chronology-'));t.after(()=>rm(dir,{recursive:true,force:true}));
+ const last={...page,pageCursor:page.nextCursor,nextCursor:null,hasMore:false};
+ const malformed=[
+ {hasMore:false,nextCursor:'older'},
+ {hasMore:true,nextCursor:null},
+ {hasMore:true,nextCursor:''},
+ {hasMore:true,nextCursor:'x'.repeat(12001)},
+ {hasMore:true,nextCursor:42},
+ {hasMore:'false',nextCursor:null},
+ {hasMore:undefined,nextCursor:null},
+ {hasMore:false,nextCursor:undefined},
+ ];
+ for(const pagination of malformed)for(const pages of [[{...page,...pagination}],[page,{...last,...pagination}]])for(const destination of [{out:'export.json'},{}]){
+ const input=JSON.stringify(pages),output=[];await writeFile(join(dir,'pages.json'),input);
+ await assert.rejects(chronologyMain({_:['chronology','export'],tag:[],pages:'pages.json',...destination},{cwd:dir,out:value=>output.push(value),fetchImpl:()=>assert.fail('offline export must not fetch')}),{code:'INVALID_CHRONOLOGY_EXPORT'});
+ assert.deepEqual(output,[]);await assert.rejects(readFile(join(dir,'export.json')),{code:'ENOENT'});
+ assert.equal(await readFile(join(dir,'pages.json'),'utf8'),input);
+ }
+});
+
+test('offline continuation-only export remains partial and a legacy terminal page needs no invented readAt',async t=>{
+ const dir=await mkdtemp(join(tmpdir(),'alo-chronology-'));t.after(()=>rm(dir,{recursive:true,force:true}));
+ const terminal={...page,pageCursor:'previous',nextCursor:null,hasMore:false};
+ await writeFile(join(dir,'pages.json'),JSON.stringify([terminal]));
+ await chronologyMain({_:['chronology','export'],tag:[],pages:'pages.json',out:'continuation.json'},{cwd:dir,out:()=>{},fetchImpl:()=>assert.fail('offline export must not fetch')});
+ const partial=JSON.parse(await readFile(join(dir,'continuation.json'),'utf8'));
+ assert.equal(partial.pagination.complete,false);assert.equal(partial.pagination.nextCursor,null);assert.equal(partial.pagination.pageCount,1);
+ assert.ok(partial.gaps.some(g=>g.stream==='pagination'&&g.reason==='partial_pagination'));
+ assert.equal('readAt' in partial,false);assert.equal(partial.asOf,page.asOf);
+ await writeFile(join(dir,'pages.json'),JSON.stringify([{...terminal,pageCursor:null}]));
+ await chronologyMain({_:['chronology','export'],tag:[],pages:'pages.json',out:'complete.json'},{cwd:dir,out:()=>{},fetchImpl:()=>assert.fail('offline export must not fetch')});
+ const complete=JSON.parse(await readFile(join(dir,'complete.json'),'utf8'));
+ assert.equal(complete.pagination.complete,true);assert.equal(complete.pagination.nextCursor,null);assert.equal('readAt' in complete,false);
+});
diff --git a/test/cli-client-resilience.test.js b/test/cli-client-resilience.test.js
index da32e86..5895ea9 100644
--- a/test/cli-client-resilience.test.js
+++ b/test/cli-client-resilience.test.js
@@ -11,14 +11,14 @@ const unavailable=(status,headers={})=>Response.json({error:{code:status===429?'
{status,headers:{'X-Request-ID':`req-${status}`,...headers}});
const client=(fetchImpl,options={})=>createClient({origin:ORIGIN,token:TOKEN,fetchImpl,...options});
-test('the REST client sends the 0.6.12 release User-Agent', async () => {
+test('the REST client sends the 0.6.13 release User-Agent', async () => {
const requests = [];
const result = await client(async (url, init) => {
const request = new Request(url, init);
requests.push(request);
assert.equal(request.url, ORIGIN + '/v1/watches');
assert.equal(request.method, 'GET');
- assert.equal(request.headers.get('user-agent'), 'agentlinkops-cli/0.6.12');
+ assert.equal(request.headers.get('user-agent'), 'agentlinkops-cli/0.6.13');
assert.equal(request.headers.get('authorization'), 'Bearer ' + TOKEN);
return page();
}).listWatches();
diff --git a/test/cli-doctor-writer.test.js b/test/cli-doctor-writer.test.js
index 537b0dd..5b75015 100644
--- a/test/cli-doctor-writer.test.js
+++ b/test/cli-doctor-writer.test.js
@@ -9,7 +9,7 @@ import {join} from 'node:path';
if (typeof mock.module === 'function') mock.module('../cli/native-lock.js', {namedExports: {nativeLock: async () => ({acquire: () => true})}});
const {doctorMain} = await import('../cli/doctor.js');
const {acquireSyncLock} = await import('../cli/sync-lock.js');
-const {writeState} = await import('../cli/state.js');
+const {writeState, STATE_VERSION} = await import('../cli/state.js');
const {main} = await import('../cli/main.js');
async function ledger(t) {
@@ -19,7 +19,7 @@ async function ledger(t) {
await writeFile(join(dir, 'links.jsonl'), JSON.stringify({id: 'lk_sameid01', intent: 'expected', source: 'https://publisher.example/a', target: 'https://customer.example/b'}) + '\n');
await writeFile(join(dir, 'config.json'), JSON.stringify({cloud: {origin: 'https://api.example'}}));
const statePath = join(dir, 'state.json');
- const before = {v: 2, entries: {}, watches: {lk_sameid01: 'old'}, cursors: {events: 'old-source', target_events: 'old-target'}, custom: {site: cwd}};
+ const before = {v: STATE_VERSION, entries: {}, watches: {lk_sameid01: 'old'}, cursors: {events: 'old-source', target_events: 'old-target'}, custom: {site: cwd}};
await writeState(statePath, before);
return {cwd, dir, statePath, before};
}
diff --git a/test/cli-fleet.test.js b/test/cli-fleet.test.js
index 8d4960e..d833153 100644
--- a/test/cli-fleet.test.js
+++ b/test/cli-fleet.test.js
@@ -13,10 +13,10 @@ async function scratch(t) {
}
const entry = (id, intent, source) => `${JSON.stringify({ id, intent, source, target: 'https://me.example/', scope: 'domain' })}\n`;
-const observation = (id, state, checked_at = '2026-09-11T05:00:00.000Z') => `${JSON.stringify({
+const observation = (id, state, checked_at = '2026-09-11T05:00:00.000Z', sourceUrl = `https://${id}.example/x`) => `${JSON.stringify({
id, checked_at, state, reason: state === 'present' ? 'link_found' : 'no_matching_link_in_complete_html',
occurrences: state === 'present' ? 1 : 0, complete: true, checker_version: '1', source: 'local', evidence_key: null,
- result: { state, reason: 'x', sourceUrl: `https://${id}.example/x`, directives: { noindex: false } },
+ result: { state, reason: 'x', sourceUrl, targetUrl: 'https://me.example/', targetScope: 'domain', directives: { noindex: false } },
})}\n`;
test('fleet summarises each project on its own and never merges intent', async t => {
@@ -27,7 +27,7 @@ test('fleet summarises each project on its own and never merges intent', async t
// merely wanted in another. Two files, two ids, and the summary must report both.
await writeFile(join(dir, 'a', 'links.jsonl'), entry('lk_expected1', 'expected', 'https://platform.example/a') + entry('lk_wantedaa', 'wanted', 'https://other.example/'));
await writeFile(join(dir, 'b', 'links.jsonl'), entry('lk_wantedbb', 'wanted', 'https://platform.example/b'));
- await writeFile(join(dir, 'a', 'observations.jsonl'), observation('lk_expected1', 'present'));
+ await writeFile(join(dir, 'a', 'observations.jsonl'), observation('lk_expected1', 'present', undefined, 'https://platform.example/a'));
const summary = await fleetSummary(
[{ name: 'a', ledger: join(dir, 'a', 'links.jsonl') }, { name: 'b', ledger: join(dir, 'b', 'links.jsonl') }],
diff --git a/test/cli-freshness-surface.test.js b/test/cli-freshness-surface.test.js
new file mode 100644
index 0000000..577f8c7
--- /dev/null
+++ b/test/cli-freshness-surface.test.js
@@ -0,0 +1,83 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {mkdtemp, mkdir, readFile, readdir, rm, writeFile} from 'node:fs/promises';
+import {tmpdir} from 'node:os';
+import {join} from 'node:path';
+import {main} from '../cli/main.js';
+import {normalizeEntry,serializeLedger} from '../cli/ledger.js';
+import {observationRow} from '../cli/mirror.js';
+import {applyRun} from '../cli/state.js';
+
+const at=minutes=>new Date(Date.parse('2026-10-07T00:00:00.000Z')+minutes*60_000).toISOString();
+const entry=id=>normalizeEntry({id,intent:'expected',source:`https://publisher.example/${id}`,target:'https://customer.example/guide',scope:'exact'});
+const row=(entry,state,minutes)=>observationRow(entry.id,{sourceUrl:entry.source,targetUrl:entry.target,targetScope:entry.scope,state,checkedAt:at(minutes),
+ reason:state==='unknown'?'source_http_403':state==='present'?'link_found':'no_matching_link_in_complete_html',
+ occurrences:state==='present'?[{targetUrl:entry.target,anchor:'Guide',rel:[]}]:[],linkSignature:state==='present'?'stable-present':null,
+ evidence:{complete:state!=='unknown',method:'http_html',checkerVersion:'fixture-1',sha256:'a'.repeat(64)}});
+const invoke=async(cwd,argv)=>{
+ const out=[],err=[];
+ const code=await main(argv,{cwd,env:{},out:value=>out.push(String(value)),err:value=>err.push(String(value)),fetchImpl:()=>assert.fail('local freshness reads must not fetch')});
+ return {code,out:out.join('\n'),err:err.join('\n')};
+};
+async function bytes(dir){
+ const found={};
+ const visit=async(path=dir,prefix='')=>{
+ for(const item of (await readdir(path,{withFileTypes:true})).sort((a,b)=>a.nameb.name?1:0)){
+ const absolute=join(path,item.name),relative=prefix+item.name;
+ if(item.isDirectory())await visit(absolute,relative+'/');else found[relative]=(await readFile(absolute)).toString('base64');
+ }
+ };
+ await visit();return found;
+}
+async function workspace(t,entries,observations,state){
+ const cwd=await mkdtemp(join(tmpdir(),'alo-freshness-surface-'));t.after(()=>rm(cwd,{recursive:true,force:true}));
+ const dir=join(cwd,'.agentlinkops');await mkdir(dir);
+ const paths={ledger:join(dir,'links.jsonl'),observations:join(dir,'observations.jsonl'),state:join(dir,'state.json')};
+ await writeFile(paths.ledger,serializeLedger(entries));await writeFile(paths.observations,observations.map(value=>JSON.stringify(value)).join('\n')+'\n');
+ await writeFile(paths.state,JSON.stringify(state)+'\n');return {cwd,paths};
+}
+
+test('actual status --all joins latest activity while legacy array, receipt dates and customer bytes stay stable',async t=>{
+ t.mock.method(globalThis,'fetch',()=>assert.fail('status/report/fleet never fetch'));
+ const healthy=entry('lk_healthy01'),blocked=entry('lk_blocked01'),corrected=entry('lk_corrected1'),missing=entry('lk_missing01');
+ const retained=[row(healthy,'present',0),row(blocked,'present',0),row(blocked,'unknown',100),row(corrected,'present',0),row(missing,'absent',40)];
+ const activity=applyRun({v:2,entries:{},cursors:{events:'source-keep',target_events:'target-keep'},doctor:{keep:true},future:{keep:['custom']}},
+ [row(healthy,'present',0),row(healthy,'present',50),row(blocked,'present',0),row(blocked,'present',50),row(blocked,'unknown',100),row(corrected,'present',0),row(missing,'absent',40),row(missing,'absent',90)]);
+ activity.entries[healthy.id].futureEntry={keep:17};
+ const f=await workspace(t,[healthy,blocked,{...corrected,scope:'domain'},missing],retained,activity),before=await bytes(f.cwd);
+ const legacy=await invoke(f.cwd,['status','--json']);assert.equal(legacy.code,0);assert.equal(legacy.err,'');
+ const disagreements=JSON.parse(legacy.out);assert.equal(Array.isArray(disagreements),true);
+ assert.deepEqual(disagreements.map(item=>[item.entry.id,item.kind]),[[blocked.id,'cannot_say'],[corrected.id,'never_checked'],[missing.id,'suspected_missing']]);
+ const all=await invoke(f.cwd,['status','--all','--json']);assert.equal(all.code,0);assert.equal(all.err,'');
+ const result=JSON.parse(all.out);assert.deepEqual(result.disagreements,disagreements);assert.equal(result.placements.length,4);
+ const healthyView=result.placements.find(item=>item.id===healthy.id),blockedView=result.placements.find(item=>item.id===blocked.id),correctedView=result.placements.find(item=>item.id===corrected.id);
+ assert.equal(healthyView.current_state,'present');assert.equal(healthyView.latest_attempt.checked_at,at(50));assert.equal(healthyView.evidence_observed_at,at(0));
+ assert.equal(healthyView.last_link_verification.evidence_reference,null);
+ assert.equal(blockedView.current_state,'present');assert.equal(blockedView.uncertain,true);assert.equal(blockedView.latest_attempt.checked_at,at(100));
+ assert.equal(blockedView.latest_attempt.reason,'source_http_403');assert.equal(blockedView.last_successful_observation.checked_at,at(50));
+ assert.equal(correctedView.current_state,'unchecked');assert.equal(correctedView.identity_status,'not_matched');assert.equal(correctedView.latest_attempt,null);
+ assert.equal((await invoke(f.cwd,['status','--all','--json'])).out,all.out,'the read has no current-time input or mutation');
+ const human=await invoke(f.cwd,['status','--all']);assert.equal(human.code,0);assert.match(human.out,/Latest attempt: 2026-10-07T01:40:00\.000Z \(source_http_403\)/);
+ assert.ok(human.out.includes(`${healthy.id}: latest attempt ${at(50)}; last conclusive ${at(50)}; last link verification ${at(50)}`));
+ const report=await invoke(f.cwd,['report','--json','--as-of','2026-10-07']);assert.equal(report.code,0);
+ const dataset=JSON.parse(report.out),reportHealthy=dataset.rows.find(item=>item.id===healthy.id),reportBlocked=dataset.rows.find(item=>item.id===blocked.id);
+ assert.equal(reportHealthy.checked_at,at(0));assert.deepEqual(reportHealthy.activity.latest_attempt,healthyView.latest_attempt);
+ assert.equal(reportBlocked.state,'unknown');assert.equal(reportBlocked.current_state,'present');assert.equal(dataset.coverage.identity_unmatched_entries,1);
+ const fleet=await invoke(f.cwd,['fleet','--project',`isolated=${f.paths.ledger}`,'--observations-of',`isolated=${f.paths.observations}`,'--state-of',`isolated=${f.paths.state}`,'--json']);
+ assert.equal(fleet.code,0);const project=JSON.parse(fleet.out).projects[0];assert.equal(project.last_attempt_at,at(100));assert.equal(project.last_link_verification_at,at(90));
+ assert.equal(project.uncertain_entries,1);assert.equal(project.coverage.identity_unmatched_entries,1);
+ assert.deepEqual(await bytes(f.cwd),before,'all read surfaces preserve ledger, mirror, activity, cursors and unknown keys byte-for-byte');
+});
+
+test('actual main distinguishes state-only checks from unavailable receipts without inventing a locator',async t=>{
+ t.mock.method(globalThis,'fetch',()=>assert.fail('state-only reads never fetch'));
+ const selected=entry('lk_stateonly1'),state=applyRun({v:2,entries:{},cursors:{events:'keep',target_events:'keep-too'}},[row(selected,'present',50)]);
+ const f=await workspace(t,[selected],[],state),before=await bytes(f.cwd);
+ const status=await invoke(f.cwd,['status','--all','--json']);assert.equal(status.code,0);const value=JSON.parse(status.out);
+ assert.deepEqual(value.disagreements,[]);assert.equal(value.placements[0].latest_attempt.checked_at,at(50));
+ assert.equal(value.placements[0].evidence_observed_at,null);assert.equal(value.placements[0].last_link_verification.evidence_reference,null);
+ const report=await invoke(f.cwd,['report','--json','--as-of','2026-10-07']),dataset=JSON.parse(report.out);
+ assert.equal(report.code,0);assert.equal(dataset.rows[0].evidence,null);assert.equal(dataset.rows[0].current_state,'present');
+ assert.equal(dataset.coverage.checked,1);assert.equal(dataset.coverage.never_checked,0);assert.equal(dataset.coverage.retained_receipt_entries,0);
+ assert.deepEqual(await bytes(f.cwd),before);
+});
diff --git a/test/cli-freshness.test.js b/test/cli-freshness.test.js
new file mode 100644
index 0000000..2a3e4d2
--- /dev/null
+++ b/test/cli-freshness.test.js
@@ -0,0 +1,215 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { applyRun, selectChanged, lastCheckedMap, upgradeState, STATE_VERSION } from '../cli/state.js';
+import { observationRow, compactionPlan } from '../cli/mirror.js';
+import { placementIdentity, projectPlacement } from '../cli/placement-projection.js';
+import { disagreements } from '../cli/status.js';
+import { freezeDataset, renderReport, datasetDigest } from '../cli/report.js';
+import { fleetSummary } from '../cli/fleet.js';
+
+const entry = { id: 'lk_fresh001', intent: 'expected', source: 'https://publisher.example/a', target: 'https://customer.example/', scope: 'exact', cadence: 'daily' };
+const at = minutes => new Date(Date.parse('2026-10-07T00:00:00.000Z') + minutes * 60_000).toISOString();
+const row = (state, minutes, changes = {}) => observationRow(entry.id, {
+ sourceUrl: entry.source, targetUrl: entry.target, targetScope: entry.scope, state,
+ reason: state === 'unknown' ? 'timeout' : state === 'present' ? 'link_found' : state,
+ checkedAt: at(minutes), linkSignature: state === 'present' ? 'present-signature' : null,
+ occurrences: state === 'present' ? [{ anchor: 'Guide', rel: [], targetUrl: entry.target }] : [],
+ evidence: { complete: state !== 'unknown', sha256: String(minutes).padStart(64, '0'), method: 'http_html', checkerVersion: '1' }, ...changes,
+});
+const empty = () => ({ v: 2, entries: {}, cursors: { events: 'source-cursor', target_events: 'target-cursor' }, future: { keep: true } });
+
+test('the existing frozen v2 report still renders byte-for-byte identically', async () => {
+ const fixture = JSON.parse(await readFile(new URL('./fixtures/report-v2-snapshot.json', import.meta.url), 'utf8'));
+ assert.equal(fixture.dataset.v, 2);
+ assert.equal(createHash('sha256').update(renderReport(fixture.dataset)).digest('hex'), fixture.html_sha256);
+});
+
+test('unchanged success advances activity without manufacturing a retained receipt or change', () => {
+ const original = row('present', 0), unchanged = row('present', 50);
+ const before = applyRun(empty(), [original]);
+ const selected = selectChanged([unchanged], before);
+ assert.equal(selected.changed.length, 0);
+ assert.equal(selected.repeated.length, 1);
+ const state = applyRun(before, [unchanged]);
+ const view = projectPlacement(entry, [original], { state });
+ assert.equal(view.evidence_observed_at, at(0));
+ assert.equal(view.last_successful_observation.checked_at, at(50));
+ assert.equal(view.last_link_verification.checked_at, at(50));
+ assert.equal(view.last_link_verification.evidence_reference, null, 'an omitted receipt cannot be located');
+ assert.equal(view.last_link_verification.content_hash, unchanged.result.evidence.sha256);
+ const dataset = freezeDataset([entry], [original], { asOf: '2026-10-07', activityState: state });
+ assert.equal(dataset.rows[0].checked_at, at(0));
+ assert.equal(dataset.rows[0].evidence.content_hash, original.result.evidence.sha256);
+ assert.equal(dataset.rows[0].activity.latest_attempt.checked_at, at(50));
+ assert.equal(renderReport(dataset), renderReport(JSON.parse(JSON.stringify(dataset))));
+ assert.notEqual(datasetDigest(dataset), datasetDigest(freezeDataset([entry], [original], { asOf: '2026-10-07', activityState: before })));
+});
+
+test('blocked attempts retain the last conclusive observation and verified link alongside unknown reason/date', () => {
+ const original = row('present', 0), unchanged = row('present', 50);
+ for (const reason of ['source_http_403', 'timeout', 'robots_disallowed', 'access_challenge']) {
+ const blocked = row('unknown', 100, { reason });
+ const state = applyRun(applyRun(empty(), [original, unchanged]), [blocked]);
+ const view = projectPlacement(entry, [original, blocked], { state });
+ assert.equal(view.current_state, 'present');
+ assert.equal(view.uncertain, true);
+ assert.equal(view.latest_attempt.reason, reason);
+ assert.equal(view.latest_attempt.checked_at, at(100));
+ assert.equal(view.last_successful_observation.checked_at, at(50));
+ assert.equal(view.last_link_verification.state, 'present');
+ const mismatch = disagreements([entry], [original, blocked], { state })[0];
+ assert.equal(mismatch.kind, 'cannot_say');
+ assert.equal(mismatch.activity.last_link_verification.checked_at, at(50));
+ const report = freezeDataset([entry], [original, blocked], { asOf: '2026-10-07', activityState: state });
+ assert.equal(report.rows[0].state, 'unknown', 'raw retained receipt is never rewritten');
+ assert.equal(report.rows[0].current_state, 'present');
+ assert.match(renderReport(report), /latest attempt inconclusive/);
+ }
+});
+
+test('source unavailable advances conclusive freshness but cannot replace link verification or prove loss', () => {
+ const original = row('present', 0), unavailable = row('source_unavailable', 100, { httpStatus: 410 });
+ const state = applyRun(empty(), [original, unavailable]);
+ const view = projectPlacement(entry, [original, unavailable], { state });
+ assert.equal(view.current_state, 'source_unavailable');
+ assert.equal(view.last_successful_observation.checked_at, at(100));
+ assert.equal(view.last_link_verification.checked_at, at(0));
+ assert.equal(disagreements([entry], [original, unavailable], { state })[0].kind, 'cannot_say');
+});
+
+test('identity-bound activity without a retained receipt proves a check, without inventing receipt evidence', () => {
+ const state = applyRun(empty(), [row('present', 50)]);
+ const dataset = freezeDataset([entry], [], { asOf: '2026-10-07', activityState: state });
+ assert.equal(dataset.rows[0].state, 'unchecked', 'the raw receipt field remains empty');
+ assert.equal(dataset.rows[0].evidence, null);
+ assert.equal(dataset.rows[0].current_state, 'present');
+ assert.equal(dataset.rows[0].activity.latest_attempt.evidence_reference, null);
+ assert.equal(dataset.rows[0].activity.last_link_verification.evidence_reference, null);
+ assert.equal(dataset.coverage.checked, 1);
+ assert.equal(dataset.coverage.never_checked, 0);
+ assert.equal(dataset.coverage.retained_receipt_entries, 0);
+ assert.match(renderReport(dataset), /No retained observation/);
+});
+
+test('raw local absence stays suspected after repeats; authoritative hosted confirmation survives compaction', () => {
+ const first = row('absent', 1), repeated = row('absent', 40);
+ const local = applyRun(empty(), [first, repeated]);
+ assert.equal(disagreements([entry], [first], { state: local })[0].kind, 'suspected_missing');
+ assert.equal(projectPlacement(entry, [first], { state: local }).first_present, null);
+ const present = row('present', 0);
+ const confirmed = { ...row('absent', 60, { watchState: 'confirmed_missing', checkState: 'absent' }), source: 'cloud' };
+ const history = compactionPlan([present, first, confirmed]).keep;
+ assert.equal(disagreements([entry], history)[0].kind, 'lost');
+ const blocked = row('unknown', 100);
+ assert.equal(projectPlacement(entry, [...history, blocked]).current_state, 'confirmed_missing');
+ assert.equal(disagreements([entry], [...history, blocked])[0].kind, 'cannot_say');
+ assert.equal(disagreements([entry], [...history, row('absent', 110)])[0].kind, 'suspected_missing',
+ 'a newer independent local absence does not inherit the old hosted confirmation');
+ assert.equal(projectPlacement(entry, [...history, row('present', 120)]).current_state, 'present');
+});
+
+test('duplicate, out-of-order and invalid timestamps do not regress activity or increment checks', () => {
+ const recent = row('present', 50);
+ const state = applyRun(empty(), [recent]);
+ const retry = [recent, row('unknown', 40), { ...row('absent', 60), checked_at: 'invalid' }];
+ assert.deepEqual(applyRun(state, retry), state);
+ const selected = selectChanged(retry, state);
+ assert.equal(selected.changed.length, 0);
+ assert.equal(selected.repeated.length, 0);
+ assert.equal(selected.ignored.length, 3);
+ assert.deepEqual(state.cursors, empty().cursors);
+ assert.deepEqual(state.future, { keep: true });
+});
+
+test('equal-time retained receipt selection is deterministic and matches its projected evidence', () => {
+ const present = row('present', 50), absent = row('absent', 50, { evidence: present.result.evidence });
+ const forward = freezeDataset([entry], [present, absent], { asOf: '2026-10-07' });
+ const reverse = freezeDataset([entry], [absent, present], { asOf: '2026-10-07' });
+ assert.deepEqual(forward, reverse);
+ assert.equal(forward.rows[0].state, forward.rows[0].activity.latest_attempt.state);
+ const otherAnchor = structuredClone(present);
+ otherAnchor.result.occurrences[0].anchor = 'Different';
+ assert.deepEqual(freezeDataset([entry], [present, otherAnchor], { asOf: '2026-10-07' }),
+ freezeDataset([entry], [otherAnchor, present], { asOf: '2026-10-07' }));
+ const malformed = { id: entry.id, intent: 'expected' };
+ assert.equal(projectPlacement(malformed, [{ ...present, result: {} }]).latest_attempt, null);
+});
+
+test('source, target and scope corrections cannot inherit activity, presence or cadence from the same ledger id', () => {
+ const original = row('present', 0);
+ const old = applyRun(empty(), [original]);
+ old.entries[entry.id].futureEntry = { keep: true };
+ for (const correction of [{ source: 'https://publisher.example/b' }, { target: 'https://customer.example/new' }, { scope: 'domain' }]) {
+ const corrected = { ...entry, ...correction };
+ assert.equal(lastCheckedMap(old, [corrected]).has(entry.id), false);
+ const unbound = projectPlacement(corrected, [original], { state: old });
+ assert.equal(unbound.current_state, 'unchecked');
+ assert.equal(unbound.first_present, null);
+ const blocked = row('unknown', 50, { sourceUrl: corrected.source, targetUrl: corrected.target, targetScope: corrected.scope });
+ assert.equal(selectChanged([blocked], old).changed.length, 1);
+ const updated = applyRun(old, [blocked]);
+ const activity = updated.entries[entry.id];
+ assert.equal(activity.last_placement, placementIdentity(corrected));
+ assert.equal(activity.first_present, null);
+ assert.equal(activity.last_successful_observation, null);
+ assert.equal(activity.last_link_verification, null);
+ assert.deepEqual(activity.futureEntry, { keep: true });
+ }
+});
+
+test('legacy migration preserves unknown keys, cursors and truthful missing last-success provenance', () => {
+ const original = row('present', 0);
+ const legacy = { ...empty(), entries: { [entry.id]: { last_checked: at(100), last_state: 'unknown', last_complete: false, last_placement: placementIdentity(entry), future: 'keep' } } };
+ const migrated = upgradeState(legacy);
+ assert.equal(migrated.v, STATE_VERSION);
+ assert.equal(migrated.entries[entry.id].future, 'keep');
+ const view = projectPlacement(entry, [original], { state: migrated });
+ assert.equal(view.latest_attempt.checked_at, at(100));
+ assert.equal(view.last_successful_observation.checked_at, at(0), 'unretained prior rechecks cannot be reconstructed');
+ assert.equal(view.last_successful_observation.method, 'http_html');
+ const completeLegacy = structuredClone(migrated);
+ Object.assign(completeLegacy.entries[entry.id], { last_state: 'present', last_complete: true });
+ const fresh = projectPlacement(entry, [original], { state: completeLegacy });
+ assert.equal(fresh.last_successful_observation.checked_at, at(100));
+ assert.equal(fresh.last_successful_observation.method, null);
+ assert.equal(fresh.last_successful_observation.evidence_reference, null);
+});
+
+test('method and completeness changes are retained even when link signature is unchanged', () => {
+ const original = row('present', 0);
+ const state = applyRun(empty(), [original]);
+ const browser = row('present', 50, { evidence: { complete: true, method: 'browser_html', checkerVersion: '1', sha256: 'b'.repeat(64) } });
+ assert.equal(selectChanged([browser], state).changed.length, 1);
+ const incomplete = row('present', 50, { evidence: { complete: false, method: 'http_html', checkerVersion: '1' } });
+ assert.equal(selectChanged([incomplete], state).changed.length, 1);
+ assert.equal(projectPlacement(entry, [original], { state: applyRun(state, [incomplete]) }).uncertain, true);
+});
+
+test('fleet reads explicit per-project activity and keeps scope/denominators separate', async t => {
+ const dir = await mkdtemp(join(tmpdir(), 'alo-freshness-'));
+ t.after(() => rm(dir, { recursive: true, force: true }));
+ const original = row('present', 0);
+ const projects = [], observationsOf = {}, statesOf = {};
+ for (const [name, minutes] of [['a', 50], ['b', 90]]) {
+ const ledger = join(dir, `${name}-links.jsonl`);
+ await writeFile(ledger, JSON.stringify(entry) + '\n' + JSON.stringify({ ...entry, id: 'lk_retired1', intent: 'retired' }) + '\n');
+ observationsOf[name] = join(dir, `${name}-observations.jsonl`);
+ await writeFile(observationsOf[name], JSON.stringify(original) + '\n' + JSON.stringify({ ...original, id: 'lk_retired1' }) + '\n');
+ statesOf[name] = join(dir, `${name}-state.json`);
+ await writeFile(statesOf[name], JSON.stringify(applyRun(empty(), [original, row('present', minutes)])));
+ projects.push({ name, ledger });
+ }
+ const summary = await fleetSummary(projects, { observationsOf, statesOf });
+ assert.equal(summary.projects[0].last_attempt_at, at(50));
+ assert.equal(summary.projects[1].last_attempt_at, at(90));
+ assert.equal(summary.projects[0].last_observation, at(0));
+ assert.equal(summary.totals.earned, 2);
+ assert.equal(summary.totals.never_checked, 0, 'retired history does not make a negative active denominator');
+ const noActivity = await fleetSummary(projects, { observationsOf });
+ assert.equal(noActivity.projects[0].activity_available, false);
+ assert.equal(noActivity.projects[0].coverage.activity_input, 'not_supplied');
+});
diff --git a/test/cli-loss-evidence.test.js b/test/cli-loss-evidence.test.js
index 32c7ab9..e7f8478 100644
--- a/test/cli-loss-evidence.test.js
+++ b/test/cli-loss-evidence.test.js
@@ -17,7 +17,7 @@ import { verifyLink } from '../src/verifier/index.js';
const entry = normalizeEntry({ id: 'lk_evidence01', intent: 'expected', source: SOURCE, target: TARGET });
const timestamp = index => new Date(Date.UTC(2026, 8, 30, 0, index)).toISOString();
function observation(state, complete = true, index = 0, source = 'local') {
- return observationRow(entry.id, { state, checkedAt: timestamp(index), reason: `fixture_${state}`,
+ return observationRow(entry.id, { sourceUrl: SOURCE, targetUrl: TARGET, targetScope: 'exact', state, checkedAt: timestamp(index), reason: `fixture_${state}`,
occurrences: state === 'present' ? [{}] : [], evidence: { complete, checkerVersion: 'fixture_v1' } }, { source });
}
function hosted(state, uncertain = false) {
@@ -104,7 +104,7 @@ test('real status retains hosted confirmed-missing evidence but refuses incomple
const f = await workspace(t, [observation('confirmed_missing', true, 0, 'cloud')]);
const confirmed = await invoke(f.dir, ['status', '--json']);
assert.equal(JSON.parse(confirmed.out)[0].kind, 'lost');
- assert.match((await invoke(f.dir, ['status'])).out, /\bLOST \(1\)/);
+ assert.match((await invoke(f.dir, ['status'])).out, /confirmed missing \(1\)/);
await writeObservations(f.mirror, [observation('confirmed_missing', false, 1, 'cloud')]);
const before = await bytes(f.dir), incomplete = await invoke(f.dir, ['status', '--json']);
assert.equal(JSON.parse(incomplete.out)[0].kind, 'cannot_say');
@@ -165,7 +165,7 @@ test('actual hosted snapshot normalization preserves confirmed watch state throu
const status = await invoke(f.dir, ['status', '--json']), human = await invoke(f.dir, ['status']);
const found = JSON.parse(status.out)[0];
assert.equal(found.kind, 'lost'); assert.equal(found.row.state, 'absent');
- assert.equal(found.row.result.watchState, 'confirmed_missing'); assert.match(human.out, /\bLOST \(1\)/);
+ assert.equal(found.row.result.watchState, 'confirmed_missing'); assert.match(human.out, /confirmed missing \(1\)/);
assert.deepEqual(await bytes(f.dir), before);
});
diff --git a/test/fixtures/report-v2-snapshot.json b/test/fixtures/report-v2-snapshot.json
new file mode 100644
index 0000000..9bdc663
--- /dev/null
+++ b/test/fixtures/report-v2-snapshot.json
@@ -0,0 +1,48 @@
+{
+ "dataset": {
+ "v": 2,
+ "title": "Backlink report",
+ "as_of": "2026-09-11",
+ "include_notes": false,
+ "rows": [
+ {
+ "id": "lk_legacy01",
+ "intent": "expected",
+ "source": "https://publisher.example/a",
+ "target": "https://customer.example/",
+ "scope": "exact",
+ "expected_anchor": null,
+ "state": "present",
+ "reason": "link_found",
+ "occurrences": 0,
+ "checked_at": "2026-09-10T00:00:00.000Z",
+ "checked_by": "local",
+ "anchor": null,
+ "rel": [],
+ "evidence": {
+ "observed_at": "2026-09-10T00:00:00.000Z",
+ "content_hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+ "snapshot_key": null,
+ "origin": "local",
+ "checker_version": null,
+ "method": "static_html",
+ "hosted_observation_id": null,
+ "locator": "agentlinkops:evidence/1/link/mirror/lk_legacy01/local/2026-09-10T00%3A00%3A00.000Z"
+ },
+ "note": null,
+ "ref": null
+ }
+ ],
+ "totals": {
+ "entries": 1,
+ "present": 1
+ },
+ "coverage": {
+ "checked": 1,
+ "never_checked": 0,
+ "observed_from": "2026-09-10T00:00:00.000Z",
+ "observed_to": "2026-09-10T00:00:00.000Z"
+ }
+ },
+ "html_sha256": "e969ed266d8c0f643a05618ccc0ff26573d0355792e5273daa1e3f9b7e4db988"
+}