Local file contracts

Use these contracts when another agent or script reads files produced by the local CLI. Configuration owns their locations. Preserve unknown ledger/state fields when editing older files.

Ledger rows

links.jsonl contains one JSON object per line. Blank lines are ignored. IDs are unique; malformed rows are reported with line numbers and excluded from reads. Mutations refuse malformed input.

Field	Contract
id	Required when reading; lk_ followed by 4 to 32 lowercase alphanumeric characters
intent	wanted, expected or retired
source, target	HTTP(S) URL strings
scope	exact, domain, subdomain or path; default exact
expect.anchor	Optional string, at most 1000 characters
expect.rel	Optional array of at most 20 relation tokens, each 1 to 40 letters/digits/underscore/hyphen; normalized to lowercase, deduplicated and sorted
cadence	daily, weekly, monthly or integer seconds from 3600 to 2592000; wanted defaults weekly, expected daily
ref	Optional string, at most 500 characters
origin.kind	manual, import, discovery_candidate, mention, citation, competitor or placement_run
origin.id, run_id, provider, observed_at, source_url	Optional lineage strings, each at most 500 characters
tags	Optional string array, deduplicated
added, note	Optional strings

Unknown top-level and origin fields are retained. Lineage stays local; a cloud localReference is bounded and cannot replace it.

Portable single-check artifact

check —source … —target … returns schema:"linktrail.local-check.v1", result_id, input, checked_at, observation and provenance. The ID is an lr_ SHA-256 digest of normalized input and observation. input has source, target and scope. provenance records execution:“local”, verifier:“linktrail-shared-verifier” and raw_html_included:false.

Observation field	Type and meaning
state	present, absent, unknown or source_unavailable
reason	String reason for the result
sourceUrl, finalUrl, targetUrl	Requested source, final source and target URL strings
targetScope	exact, domain, subdomain or path
httpStatus	Integer or null
checkedAt	Canonical ISO timestamp; equals artifact checked_at
occurrences	At most 1000 matching links
directives	meta array of name/content strings; xRobotsTag string array; noindex/nofollow booleans; indexingStatus string
redirects	Array of from/to URL strings and integer status
evidence	Capture metadata described below
robots, robotsHistory	Optional robots result and up to six robots results
sourceResponse	Optional url, integer httpStatus, nullable contentType (up to 128 characters), nullable retryAfterSeconds and boolean challenge
expectations	Optional nullable expectedAnchor, expectedRel, anchorMatches and relMatches; boolean satisfied
linkSignature	Optional string
warnings	Optional string array
retryAfterSeconds	Optional number

Each occurrence contains href, targetUrl, anchor and context strings; rel string array; visibility:“not_rendered”; and locator:null or an object with integer line, column and offset. A matching HTML link does not prove rendered visibility. Evidence requires method, checkerVersion, complete and fetchedAt (timestamp or null). Optional fields are bytes, nullable contentType/etag/lastModified, baseUrl, rendered, sha256, parseErrors and renderEligibility (required or comparison). Optional readiness contains requiresRender, nullable reason and possibleLoginWall, plus optional hasVisiblePassword, targetInScript, emptyAppRoot and emptyProfileRoot booleans. A robots result requires nullable allowed, reason, matchedRule and crawlDelaySeconds, plus nullable fetched. Optional fields are sourceUrl, robotsUrl, nullable httpStatus, productToken, up to five redirects and retryAfterSeconds. Nullable fields remain unknown when absent evidence cannot support a conclusion. Adoption validates the portable observation contract, matching source/target/scope, timestamp identity and result identity. Present requires complete evidence and matching occurrences. Absent requires complete evidence and no occurrences. Portable observations cannot include raw HTML, body or headers. The artifact size check is 512 KiB of serialized JSON characters. Use adopt-result to persist it.

Observation mirror and activity state

Observation rows contain id (ledger ID), checked_at, state, reason, occurrences (count), complete, checker_version, source, evidence_key and result. Result contains verifier metadata with raw HTML removed. Deduplication uses ledger ID, checked timestamp and source. Cloud projection rows can carry projection metadata in addition to these fields. The observation mirror records changes; state.json records repeated-check activity. State version 2 holds entries, cursors and cloud mappings. Source and destination cursors remain independent. Preserve unknown state fields and let the CLI own migration; changing a cursor can skip history.

Receipt input

receipt add accepts a claim object:

{
  "kind": "external",
  "source": "https://publisher.example.com/post",
  "target": "https://example.com/guide",
  "scope": "exact",
  "acted_at": "2026-09-13T12:00:00.000Z",
  "actor": {"role": "agent"},
  "report": {"state": "claimed"},
  "idempotency": "campaign-example-001"
}

The command supplies receipt ID, declared_at, baseline and ledger reference. actor.role is human or agent. acted_at needs a timezone. Optional ledger must identify a matching placement. Optional intent_after defaults to expected for internal and wanted for external claims. expect, ref, tags and note follow ledger rules. An idempotency replay reuses the original claim only when its placement, kind, scope and acted_at match. A claim remains claimed until independent observations can be read alongside it; receipt history reports that evidence without declaring causation.

Source contracts: cli/ledger.js, cli/local-result.js, cli/mirror.js, cli/state.js and cli/receipts.js.

Overview

Cloud operations

Repository tools

HTTP and events

Ledger rows

Portable single-check artifact

Observation mirror and activity state

Receipt input

​Ledger rows

​Portable single-check artifact

​Observation mirror and activity state

​Receipt input

Ledger rows

Portable single-check artifact

Observation mirror and activity state

Receipt input