@kontourai/lookout 0.3.1 → 0.3.3

package/README.md

@@ -10,6 +10,52 @@ package. It does **not** implement acquisition or extraction, author trust-layer
 records, project to Surface, review claims, notify, crawl, or schedule.
 Operational failures are returned as typed results.
 
+## Quick start
+
+Register one source in a JSON file (defaults to `<cwd>/lookout.sources.json`;
+see [Registry](#registry) for every field):
+
+```json
+{
+  "version": 1,
+  "sources": [
+    {
+      "id": "example-home",
+      "kind": "web-page",
+      "url": "https://example.com/",
+      "targetSchema": [{ "path": "title", "type": "string", "required": true }],
+      "cadenceHint": "daily",
+      "renderPolicy": "never"
+    }
+  ]
+}
+```
+
+Then check it with the CLI:
+
+```bash
+lookout check example-home --registry ./lookout.sources.json
+```
+
+The first run has nothing to compare against, so it persists a baseline
+snapshot and reports `changed`/`initial`:
+
+```json
+{"sourceId":"example-home","sourceUrl":"https://example.com/","checkedAt":"2026-07-20T14:12:48.248Z","warnings":[],"kind":"changed","priorSnapshotRef":null,"currentSnapshotRef":"forage-snapshot:example-home?...","changeBasis":"initial"}
+```
+
+Run the same command again and, if the source hasn't changed, Forage's
+conditional request returns `304` with zero body transfer — no re-download,
+just confirmation:
+
+```json
+{"sourceId":"example-home","sourceUrl":"https://example.com/","checkedAt":"2026-07-20T14:12:53.089Z","warnings":[],"kind":"unchanged-304","snapshotRef":"forage-snapshot:example-home?..."}
+```
+
+Exit code is `0` for both runs — a per-source result, even a fetch failure, is
+not a CLI failure. See [CLI](#cli) for the full exit-code contract and
+[Check results](#check-results) for what each `kind` means.
+
 ## Why it's different
 
 The naive way to answer "did it change?" is to re-crawl the source and diff the
@@ -22,7 +68,7 @@ as "no change"). Lookout is the opposite on all three:
 | Cost | full re-download every check | **conditional `304`** — often no download at all |
 | Signal | raw bytes (ads/timestamps = "changed") | **proposal-identity diff** — "a *new entity appeared*" vs "a byte moved" |
 | Honesty | a crash or false-`304` silently reads as "unchanged" | **typed results, never throws**; Forage scopes validators to the exact prior resource and Lookout verifies the returned capture identity |
-| Output | your problem to shape | **neutral, typed drift** — events already Hachure-evidence-shaped, ready for a consumer to lift into a trust bundle |
+| Output | your problem to shape | **neutral, typed drift** — events already [Hachure](https://github.com/hachure-org/spec)-evidence-shaped (the open, product-neutral trust-record spec Surface's TrustBundle implements), ready for a consumer to lift into a trust bundle |
 
 So the point isn't "diffing" — it's *cheap + honest + semantic + review-ready*
 change detection, so a periodic re-check surfaces **only the real delta** (this
@@ -288,6 +334,46 @@ The existing `createCheckRunner` and `createDriftEmitter` entrypoints remain
 available. Use `createDriftEmitter` when the caller wants deterministic
 proposal-diff events with its own identity callbacks.
 
+## Route semantic transitions to review
+
+`buildSemanticReviewWork` turns one genuine prior/current proposal transition
+into structurally Survey-compatible `ReviewItem` resources without adding a
+runtime dependency on a review product. The caller supplies entity/field
+identity callbacks and claim meaning; Lookout supplies deterministic transition
+and item identities.
+
+```ts
+const work = buildSemanticReviewWork({
+  prior,
+  current,
+  observationIdentity: { prior: priorId, current: currentId },
+  schema: source.targetSchema,
+  selectEntities,
+  entityIdentity,
+  proposalsFor,
+  fieldIdentity,
+  claimTarget(change) {
+    return describeClaim(change);
+  },
+});
+```
+
+Added, removed, moved, provenance-changed, and value-changed proposals become distinct work items.
+New coverage or exact-provenance gaps are also reviewable. Each available side
+retains its exact snapshot reference, observation time, locator, excerpt, and
+extractor. An absent side is explicit and anchored to the corresponding
+observation snapshot, so a removal remains reviewable even when the new
+extraction emits no value. Identical proposal sets produce no semantic work;
+replaying the same pair of observation identities produces byte-identical
+resources.
+
+Review resolution, escalation, persistence, and authority policy stay with the
+consumer. Evidence excerpts and caller-supplied claim targets can contain
+sensitive data; apply retention, redaction, and access controls before storing
+or forwarding review work. Only compact typed identities cross the producer
+metadata boundary; no provider messages, native diagnostics, or raw responses
+are copied.
+
 ## Non-goals
 
 Acquisition and extraction implementations, Surface projection, notifications,

package/dist/src/drift-emission.js

@@ -16,6 +16,8 @@ function normalizeDiff(value) {
             removedProposalOccurrences: sorted(value.facts.removedProposalOccurrences),
             provenanceChanges: sorted(value.facts.provenanceChanges),
             removedEntities: [...value.facts.removedEntities].sort(),
+            addedProposalEvidence: sorted(value.facts.addedProposalEvidence ?? []),
+            removedProposalEvidence: sorted(value.facts.removedProposalEvidence ?? []),
         },
     };
 }

package/dist/src/index.d.ts

@@ -24,3 +24,5 @@ export { checkSchemaCoverage } from "./coverage.js";
 export type { SchemaCoverageGap, SchemaCoverageResult } from "./coverage.js";
 export { createObserveExtractDiff } from "./observe-extract-diff.js";
 export type { ObserveExtractAcquisition, ObserveExtractAttempt, ObserveExtractDiff, ObserveExtractDiffOptions, ObserveExtractError, ObserveExtractErrorKind, ObserveExtractExtraction, ObserveExtractExtractionInput, ObserveExtractObservation, ObserveExtractObservationIdentity, ObserveExtractOutcome, ObserveExtractProviderFailure, ObserveExtractRecorder, ObserveExtractResult, ObserveExtractSource, ObserveExtractSourceSnapshot, } from "./observe-extract-diff.js";
+export { buildSemanticReviewWork, semanticReviewApiVersion } from "./semantic-review-work.js";
+export type { BuildSemanticReviewWorkInput, SemanticClaimTarget, SemanticObservationIdentity, SemanticReviewCandidate, SemanticReviewChange, SemanticReviewItem, SemanticReviewKind, SemanticReviewWork, } from "./semantic-review-work.js";

package/dist/src/index.js

@@ -10,3 +10,4 @@ export { createObservationStore } from "./observation-store.js";
 export { createDriftEmitter } from "./drift-emission.js";
 export { checkSchemaCoverage } from "./coverage.js";
 export { createObserveExtractDiff } from "./observe-extract-diff.js";
+export { buildSemanticReviewWork, semanticReviewApiVersion } from "./semantic-review-work.js";

package/dist/src/proposal-diff.d.ts

@@ -62,6 +62,10 @@ export interface ProposalSetFacts {
     readonly removedProposalOccurrences: readonly ExtractionProposal[];
     readonly provenanceChanges: readonly ProvenanceChangeFact[];
     readonly removedEntities: readonly string[];
+    /** Exact observation-anchored evidence for every added proposal occurrence. */
+    readonly addedProposalEvidence?: readonly ProposalEvidence[];
+    /** Exact observation-anchored evidence for every removed proposal occurrence. */
+    readonly removedProposalEvidence?: readonly ProposalEvidence[];
 }
 export interface ProposalSetDiff {
     readonly events: readonly ProposalDiffEvent[];

package/dist/src/proposal-diff.js

@@ -73,6 +73,26 @@ function changeKind(prior, current) {
     const sameCategory = (prior === null ? "null" : typeof prior) === (current === null ? "null" : typeof current);
     return { ok: true, value: sameCategory ? "value-updated" : "value-replaced" };
 }
+function semanticFieldOrder(items, fieldIdentity) {
+    const groups = new Map();
+    for (const [index, item] of items.entries()) {
+        const fieldKey = identity("fieldIdentity", () => fieldIdentity(item));
+        if (!fieldKey.ok)
+            return fieldKey;
+        let encoded;
+        try {
+            encoded = canonicalValueKey({ value: item.proposal.candidateValue, provenance: item.proposal.provenance });
+        }
+        catch (cause) {
+            return { ok: false, error: { kind: "unsupported-value", message: "Proposal semantic content could not be inspected", path: "$", cause } };
+        }
+        if (!encoded.ok)
+            return encoded;
+        groups.set(fieldKey.value, [...(groups.get(fieldKey.value) ?? []), { item, key: encoded.key, index }]);
+    }
+    const ordered = [...groups.values()].flatMap((group) => group.sort((left, right) => left.key.localeCompare(right.key) || left.index - right.index));
+    return { ok: true, value: ordered.map(({ item }) => item) };
+}
 export function diffProposalSets(input) {
     if (input.prior.sourceId !== input.current.sourceId) {
         return {
@@ -97,6 +117,8 @@ export function diffProposalSets(input) {
     const removedProposalOccurrences = [];
     const provenanceChanges = [];
     const removedEntities = [];
+    const addedProposalEvidence = [];
+    const removedProposalEvidence = [];
     for (const pair of entities.value.retained) {
         const entityKeyResult = identity("entityIdentity", () => input.entityIdentity(pair.prior));
         if (!entityKeyResult.ok)
@@ -116,9 +138,25 @@ export function diffProposalSets(input) {
         retainedProposalOccurrences.push(...occurrences.value.retained);
         addedProposalOccurrences.push(...occurrences.value.additions);
         removedProposalOccurrences.push(...occurrences.value.removals);
-        const priorFields = priorProposals.value.map((proposal) => ({ entity: pair.prior, proposal }));
-        const currentFields = currentProposals.value.map((proposal) => ({ entity: pair.current, proposal }));
-        const fields = diffKeyedMultiset(priorFields, currentFields, {
+        for (const proposal of occurrences.value.additions) {
+            const fieldKey = identity("fieldIdentity", () => input.fieldIdentity(pair.current, proposal));
+            if (!fieldKey.ok)
+                return fieldKey;
+            addedProposalEvidence.push(evidence(input.current, entityKey, fieldKey.value, proposal));
+        }
+        for (const proposal of occurrences.value.removals) {
+            const fieldKey = identity("fieldIdentity", () => input.fieldIdentity(pair.prior, proposal));
+            if (!fieldKey.ok)
+                return fieldKey;
+            removedProposalEvidence.push(evidence(input.prior, entityKey, fieldKey.value, proposal));
+        }
+        const priorFields = semanticFieldOrder(priorProposals.value.map((proposal) => ({ entity: pair.prior, proposal })), ({ entity, proposal }) => input.fieldIdentity(entity, proposal));
+        if (!priorFields.ok)
+            return priorFields;
+        const currentFields = semanticFieldOrder(currentProposals.value.map((proposal) => ({ entity: pair.current, proposal })), ({ entity, proposal }) => input.fieldIdentity(entity, proposal));
+        if (!currentFields.ok)
+            return currentFields;
+        const fields = diffKeyedMultiset(priorFields.value, currentFields.value, {
             identity: ({ entity, proposal }) => input.fieldIdentity(entity, proposal),
         });
         if (!fields.ok)
@@ -184,6 +222,7 @@ export function diffProposalSets(input) {
             if (!fieldKey.ok)
                 return fieldKey;
             current.push(evidence(input.current, entityKeyResult.value, fieldKey.value, proposal));
+            addedProposalEvidence.push(evidence(input.current, entityKeyResult.value, fieldKey.value, proposal));
             addedProposalOccurrences.push(proposal);
         }
         events.push({ kind: "new-entity-appeared", entityKey: entityKeyResult.value, current });
@@ -197,12 +236,18 @@ export function diffProposalSets(input) {
         if (!proposals.ok)
             return proposals;
         removedProposalOccurrences.push(...proposals.value);
+        for (const proposal of proposals.value) {
+            const fieldKey = identity("fieldIdentity", () => input.fieldIdentity(entity, proposal));
+            if (!fieldKey.ok)
+                return fieldKey;
+            removedProposalEvidence.push(evidence(input.prior, entityKeyResult.value, fieldKey.value, proposal));
+        }
     }
     return {
         ok: true,
         value: {
             events,
-            facts: { retainedProposalOccurrences, addedProposalOccurrences, removedProposalOccurrences, provenanceChanges, removedEntities },
+            facts: { retainedProposalOccurrences, addedProposalOccurrences, removedProposalOccurrences, provenanceChanges, removedEntities, addedProposalEvidence, removedProposalEvidence },
         },
     };
 }

package/dist/src/semantic-review-projection.d.ts

@@ -0,0 +1,13 @@
+import type { TargetFieldSchema } from "@kontourai/traverse";
+import { type DiffResult } from "./canonical-value.js";
+import type { ProposalSetDiff, ProposalSetObservation } from "./proposal-diff.js";
+import { type SemanticClaimTarget, type SemanticObservationIdentity, type SemanticReviewChange, type SemanticReviewItem } from "./semantic-review-types.js";
+export declare function reviewKey(value: unknown): DiffResult<string>;
+export declare function sanitizeError<T>(result: DiffResult<T>): DiffResult<T>;
+export declare function validateObservationIdentity(identity: SemanticObservationIdentity): DiffResult<SemanticObservationIdentity>;
+export declare function collectSemanticChanges(input: {
+    prior: ProposalSetObservation;
+    current: ProposalSetObservation;
+    schema?: readonly TargetFieldSchema[];
+}, diff: ProposalSetDiff): SemanticReviewChange[];
+export declare function projectReviewItem(change: SemanticReviewChange, occurrence: number, transitionId: string, identities: SemanticObservationIdentity, prior: ProposalSetObservation, current: ProposalSetObservation, target: SemanticClaimTarget): DiffResult<SemanticReviewItem>;

package/dist/src/semantic-review-projection.js

@@ -0,0 +1,68 @@
+import { createHash } from "node:crypto";
+import { canonicalValueKey } from "./canonical-value.js";
+import { checkSchemaCoverage } from "./coverage.js";
+import { semanticReviewApiVersion } from "./semantic-review-types.js";
+export function reviewKey(value) {
+    const canonical = canonicalValueKey(value);
+    return canonical.ok ? { ok: true, value: createHash("sha256").update(canonical.key).digest("hex").slice(0, 24) } : sanitizeError(canonical);
+}
+export function sanitizeError(result) {
+    if (result.ok)
+        return result;
+    return { ok: false, error: { kind: result.error.kind, message: "Semantic review derivation failed" } };
+}
+export function validateObservationIdentity(identity) {
+    for (const [name, value] of Object.entries(identity))
+        if (typeof value !== "string" || value.length === 0 || /authorization\s*[:=]|bearer\s+|(?:token|secret|password|api[-_]?key)=/i.test(value)) {
+            return { ok: false, error: { kind: "unsupported-value", message: `${name} observation identity is invalid`, path: `$.observationIdentity.${name}` } };
+        }
+    return { ok: true, value: identity };
+}
+const incomplete = (evidence) => evidence.provenance.locator.length === 0 || evidence.provenance.excerpt.length === 0;
+const sameEvidence = (left, right) => left.entityKey === right.entityKey && left.fieldKey === right.fieldKey && left.snapshotRef === right.snapshotRef && left.provenance.locator === right.provenance.locator && left.provenance.excerpt === right.provenance.excerpt;
+const addedKind = (current) => incomplete(current) ? "provenance-gap" : "proposal-added";
+export function collectSemanticChanges(input, diff) {
+    const changes = [];
+    for (const event of diff.events) {
+        if (event.kind === "new-entity-appeared")
+            for (const current of event.current)
+                changes.push({ kind: addedKind(current), fieldPath: current.fieldPath, entityKey: current.entityKey, current });
+        else if (event.prior && event.current)
+            changes.push({ kind: "proposal-value-changed", fieldPath: event.current.fieldPath, entityKey: event.entityKey, prior: event.prior, current: event.current });
+        else if (event.current)
+            changes.push({ kind: addedKind(event.current), fieldPath: event.current.fieldPath, entityKey: event.entityKey, current: event.current });
+        else if (event.prior)
+            changes.push({ kind: "proposal-removed", fieldPath: event.prior.fieldPath, entityKey: event.entityKey, prior: event.prior });
+    }
+    const representedPrior = changes.flatMap((change) => change.prior ? [change.prior] : []);
+    const representedCurrent = changes.flatMap((change) => change.current ? [change.current] : []);
+    for (const prior of diff.facts.removedProposalEvidence ?? [])
+        if (!diff.facts.provenanceChanges.some((item) => sameEvidence(item.prior, prior)) && !representedPrior.some((item) => sameEvidence(item, prior)))
+            changes.push({ kind: "proposal-removed", fieldPath: prior.fieldPath, entityKey: prior.entityKey, prior });
+    for (const current of diff.facts.addedProposalEvidence ?? [])
+        if (!diff.facts.provenanceChanges.some((item) => sameEvidence(item.current, current)) && !representedCurrent.some((item) => sameEvidence(item, current)))
+            changes.push({ kind: addedKind(current), fieldPath: current.fieldPath, entityKey: current.entityKey, current });
+    for (const change of diff.facts.provenanceChanges) {
+        const kind = incomplete(change.current) && !incomplete(change.prior) ? "provenance-gap" : change.prior.provenance.locator !== change.current.provenance.locator ? "proposal-moved" : "proposal-provenance-changed";
+        changes.push({ kind, fieldPath: change.current.fieldPath, entityKey: change.entityKey, prior: change.prior, current: change.current });
+    }
+    if (input.schema) {
+        const priorGaps = new Set(checkSchemaCoverage(input.schema, input.prior.proposals).gaps.map((gap) => gap.fieldPath));
+        for (const gap of checkSchemaCoverage(input.schema, input.current.proposals).gaps)
+            if (!priorGaps.has(gap.fieldPath))
+                changes.push({ kind: "coverage-gap", fieldPath: gap.fieldPath, entityKey: gap.fieldPath, gap });
+    }
+    return changes;
+}
+function candidate(id, role, observationId, evidence, fallback, target, fieldPath) {
+    const present = evidence !== undefined;
+    return { id: `${id}.${role}`, role, value: present ? evidence.value : null, ...(present ? { confidence: evidence.confidence } : {}), source: { sourceRef: evidence?.snapshotRef ?? fallback.snapshotRef, sourceId: evidence?.sourceId ?? fallback.sourceId, observedAt: evidence?.observedAt ?? fallback.observedAt, locatorScheme: "text-span" }, ...(present && !incomplete(evidence) ? { locator: { scheme: "text-span", locator: evidence.provenance.locator, excerpt: evidence.provenance.excerpt } } : {}), extraction: { extractionId: `${id}.${role}.extraction`, target: fieldPath, ...(present ? { confidence: evidence.confidence, extractor: evidence.extractor } : {}), extractedAt: evidence?.observedAt ?? fallback.observedAt }, claimTarget: target, producer: { "lookout.kontourai.io/semantic-transition": { observationId, evidenceState: present ? "present" : "absent" } } };
+}
+export function projectReviewItem(change, occurrence, transitionId, identities, prior, current, target) {
+    const itemIdentity = reviewKey({ transitionId, change, occurrence });
+    if (!itemIdentity.ok)
+        return itemIdentity;
+    const name = `lookout-semantic.${itemIdentity.value}`;
+    const candidates = [candidate(name, "current", identities.prior, change.prior, prior, target, change.fieldPath), candidate(name, "proposed", identities.current, change.current, current, target, change.fieldPath)];
+    return { ok: true, value: { apiVersion: semanticReviewApiVersion, kind: "ReviewItem", metadata: { name, producer: { "lookout.kontourai.io/semantic-transition": { semanticKind: change.kind, transitionId, priorObservationId: identities.prior, currentObservationId: identities.current } } }, spec: { target: change.fieldPath, candidates, candidateSetStatus: "needs-review", editable: false }, status: { observedCandidateCount: candidates.length } } };
+}

package/dist/src/semantic-review-types.d.ts

@@ -0,0 +1,95 @@
+import type { TargetFieldSchema } from "@kontourai/traverse";
+import type { SchemaCoverageGap } from "./coverage.js";
+import type { ProposalEvidence, ProposalSetDiffInput, ProposalSetObservation } from "./proposal-diff.js";
+export declare const semanticReviewApiVersion = "survey.kontourai.io/v1alpha1";
+export type SemanticReviewKind = "proposal-added" | "proposal-removed" | "proposal-moved" | "proposal-provenance-changed" | "proposal-value-changed" | "coverage-gap" | "provenance-gap";
+export interface SemanticObservationIdentity {
+    readonly prior: string;
+    readonly current: string;
+}
+export interface SemanticClaimTarget {
+    readonly subjectType: string;
+    readonly subjectId: string;
+    readonly facet: string;
+    readonly claimType: string;
+    readonly fieldOrBehavior: string;
+    readonly impactLevel: "low" | "medium" | "high" | "critical";
+    readonly [key: string]: unknown;
+}
+export interface SemanticReviewCandidate {
+    readonly id: string;
+    readonly role: "current" | "proposed" | "source-version";
+    readonly value: unknown;
+    readonly confidence?: number;
+    readonly source: {
+        readonly sourceRef: string;
+        readonly sourceId: string;
+        readonly observedAt: string;
+        readonly locatorScheme: "text-span";
+    };
+    readonly locator?: {
+        readonly scheme: "text-span";
+        readonly locator: string;
+        readonly excerpt: string;
+    };
+    readonly extraction: {
+        readonly extractionId: string;
+        readonly target: string;
+        readonly confidence?: number;
+        readonly extractor?: string;
+        readonly extractedAt: string;
+    };
+    readonly claimTarget: SemanticClaimTarget;
+    readonly producer: {
+        readonly "lookout.kontourai.io/semantic-transition": {
+            readonly observationId: string;
+            readonly evidenceState: "present" | "absent";
+        };
+    };
+}
+/** Structural match for Survey ReviewItem; Lookout deliberately imports no review package. */
+export interface SemanticReviewItem {
+    readonly apiVersion: typeof semanticReviewApiVersion;
+    readonly kind: "ReviewItem";
+    readonly metadata: {
+        readonly name: string;
+        readonly producer: {
+            readonly "lookout.kontourai.io/semantic-transition": {
+                readonly semanticKind: SemanticReviewKind;
+                readonly transitionId: string;
+                readonly priorObservationId: string;
+                readonly currentObservationId: string;
+            };
+        };
+    };
+    readonly spec: {
+        readonly target: string;
+        readonly candidates: SemanticReviewCandidate[];
+        readonly candidateSetStatus: "needs-review";
+        readonly editable: false;
+    };
+    readonly status: {
+        readonly observedCandidateCount: number;
+    };
+}
+export interface SemanticReviewChange {
+    readonly kind: SemanticReviewKind;
+    readonly fieldPath: string;
+    readonly entityKey: string;
+    readonly prior?: ProposalEvidence;
+    readonly current?: ProposalEvidence;
+    readonly gap?: SchemaCoverageGap;
+}
+export interface SemanticReviewWork {
+    readonly transitionId: string;
+    readonly priorObservationId: string;
+    readonly currentObservationId: string;
+    readonly items: readonly SemanticReviewItem[];
+}
+export interface BuildSemanticReviewWorkInput<E> extends Omit<ProposalSetDiffInput<E>, "prior" | "current"> {
+    readonly prior: ProposalSetObservation;
+    readonly current: ProposalSetObservation;
+    readonly observationIdentity: SemanticObservationIdentity;
+    readonly schema?: readonly TargetFieldSchema[];
+    readonly claimTarget: (change: SemanticReviewChange) => SemanticClaimTarget;
+}

package/dist/src/semantic-review-types.js

@@ -0,0 +1 @@
+export const semanticReviewApiVersion = "survey.kontourai.io/v1alpha1";

package/dist/src/semantic-review-work.d.ts

@@ -0,0 +1,5 @@
+import type { BuildSemanticReviewWorkInput, SemanticReviewWork } from "./semantic-review-types.js";
+export { semanticReviewApiVersion } from "./semantic-review-types.js";
+export type { BuildSemanticReviewWorkInput, SemanticClaimTarget, SemanticObservationIdentity, SemanticReviewCandidate, SemanticReviewChange, SemanticReviewItem, SemanticReviewKind, SemanticReviewWork } from "./semantic-review-types.js";
+/** Project one genuine proposal-observation transition into deterministic review work. */
+export declare function buildSemanticReviewWork<E>(input: BuildSemanticReviewWorkInput<E>): import("./canonical-value.js").DiffResult<SemanticReviewWork>;

package/dist/src/semantic-review-work.js

@@ -0,0 +1,36 @@
+import { diffProposalSets } from "./proposal-diff.js";
+import { collectSemanticChanges, projectReviewItem, reviewKey, sanitizeError, validateObservationIdentity } from "./semantic-review-projection.js";
+export { semanticReviewApiVersion } from "./semantic-review-types.js";
+/** Project one genuine proposal-observation transition into deterministic review work. */
+export function buildSemanticReviewWork(input) {
+    const identities = validateObservationIdentity(input.observationIdentity);
+    if (!identities.ok)
+        return identities;
+    const diff = diffProposalSets(input);
+    if (!diff.ok)
+        return sanitizeError(diff);
+    const transition = reviewKey({ sourceId: input.current.sourceId, priorObservationId: identities.value.prior, currentObservationId: identities.value.current });
+    if (!transition.ok)
+        return transition;
+    const items = [];
+    const occurrences = new Map();
+    for (const change of collectSemanticChanges(input, diff.value)) {
+        let target;
+        try {
+            target = input.claimTarget(change);
+        }
+        catch {
+            return { ok: false, error: { kind: "callback-threw", message: "claimTarget callback threw", path: "$.claimTarget" } };
+        }
+        const base = reviewKey(change);
+        if (!base.ok)
+            return base;
+        const occurrence = occurrences.get(base.value) ?? 0;
+        occurrences.set(base.value, occurrence + 1);
+        const item = projectReviewItem(change, occurrence, transition.value, identities.value, input.prior, input.current, target);
+        if (!item.ok)
+            return item;
+        items.push(item.value);
+    }
+    return { ok: true, value: { transitionId: transition.value, priorObservationId: identities.value.prior, currentObservationId: identities.value.current, items } };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontourai/lookout",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "A small source registry and drift-check runner built on Forage snapshots.",
   "license": "Apache-2.0",
   "type": "module",
@@ -36,18 +36,20 @@
     "prepare": "npm run build",
     "typecheck": "tsc --noEmit",
     "test": "npm run build && node --test dist/tests/*.test.js",
-    "verify": "npm run check:content-boundary && npm run check:decisions && npm run typecheck && npm test && npm run check:pack",
+    "verify": "npm run check:content-boundary && npm run check:decisions && npm run typecheck && npm test && npm run check:pack && npm run check:consumer",
     "check:content-boundary": "node scripts/check-content-boundary.cjs",
     "check:decisions": "node scripts/check-decisions.cjs check",
     "gen:decisions-index": "node scripts/check-decisions.cjs gen-index",
-    "check:pack": "node scripts/check-package-contents.mjs"
+    "check:pack": "node scripts/check-package-contents.mjs",
+    "check:consumer": "node scripts/check-installed-consumer.mjs"
   },
   "dependencies": {
-    "@kontourai/datum": "0.3.0",
+    "@kontourai/datum": "0.7.0",
     "@kontourai/forage": "0.4.1",
-    "@kontourai/traverse": "0.18.0"
+    "@kontourai/traverse": "0.22.0"
   },
   "devDependencies": {
+    "@kontourai/survey": "2.1.0",
     "@types/node": "^25.6.0",
     "typescript": "^5.8.0"
   },