@kontourai/lookout 0.3.0 → 0.3.2

package/dist/src/observe-extract-diff.js

@@ -0,0 +1,154 @@
+import { validatePreparedArtifact } from "@kontourai/traverse";
+export function createObserveExtractDiff(options) {
+    return {
+        async observe(source) {
+            try {
+                let check;
+                try {
+                    check = await options.acquisition.check(source);
+                }
+                catch (cause) {
+                    return { ok: false, error: error("acquisition-threw", "Acquisition capability threw", cause) };
+                }
+                if (!isCheckResult(check)) {
+                    return { ok: false, error: error("dependency-contract", "Acquisition capability returned an invalid check result") };
+                }
+                if (check.sourceId !== source.id || check.sourceUrl !== source.url) {
+                    return { ok: false, error: error("dependency-contract", "Acquisition result does not identify the requested source") };
+                }
+                if (check.kind === "error") {
+                    return record(options.recorder, baseObservation(source, check, "acquisition-error", null, null, null, null));
+                }
+                if (check.kind === "unchanged-304" || check.kind === "unchanged-hash") {
+                    return record(options.recorder, baseObservation(source, check, "unchanged", snapshotFor(check), null, null, null));
+                }
+                const sourceSnapshot = snapshotFor(check);
+                let extraction;
+                try {
+                    extraction = await options.extraction.extract({ source, snapshotRef: sourceSnapshot.currentSnapshotRef });
+                }
+                catch {
+                    return record(options.recorder, baseObservation(source, check, "extraction-failure", sourceSnapshot, null, null, null));
+                }
+                if (!isExtractionResult(extraction)) {
+                    return { ok: false, error: error("dependency-contract", "Extraction capability returned an invalid extraction result") };
+                }
+                const attempt = attemptFor(extraction);
+                const proposalSet = {
+                    sourceId: source.id,
+                    snapshotRef: sourceSnapshot.currentSnapshotRef,
+                    observedAt: extraction.extractedAt,
+                    proposals: extraction.proposals,
+                };
+                const outcome = outcomeFor(extraction);
+                if (outcome !== "extraction-failure") {
+                    if (extraction.preparedArtifact === undefined) {
+                        return { ok: false, error: error("dependency-contract", "Extraction result is missing its prepared artifact") };
+                    }
+                }
+                if (extraction.preparedArtifact !== undefined) {
+                    const validation = validatePreparedArtifact(extraction.preparedArtifact);
+                    if (validation.status !== "valid") {
+                        return { ok: false, error: error("dependency-contract", `Extraction result has an invalid prepared artifact: ${validation.status}`) };
+                    }
+                    if (validation.artifact.sourceSnapshotRef !== sourceSnapshot.currentSnapshotRef) {
+                        return { ok: false, error: error("dependency-contract", "Prepared artifact does not identify the current source snapshot") };
+                    }
+                }
+                return record(options.recorder, baseObservation(source, check, outcome, sourceSnapshot, extraction.preparedArtifact ?? null, proposalSet, attempt));
+            }
+            catch (cause) {
+                return { ok: false, error: error("dependency-contract", "Observe-extract composition could not inspect a capability result", cause) };
+            }
+        },
+    };
+}
+function baseObservation(source, check, outcome, sourceSnapshot, preparedArtifact, proposalSet, attempt) {
+    return {
+        source: { id: source.id, url: source.url, kind: source.kind },
+        check,
+        outcome,
+        sourceSnapshot,
+        preparedArtifact,
+        proposalSet,
+        attempt,
+    };
+}
+async function record(recorder, observation) {
+    try {
+        const identity = await recorder.record(observation);
+        if (!isIdentity(identity)) {
+            return { ok: false, error: error("dependency-contract", "Observation recorder returned an invalid identity"), observation };
+        }
+        return {
+            ok: true,
+            value: {
+                ...observation,
+                observationId: identity.observationId,
+                priorObservationId: identity.priorObservationId,
+            },
+        };
+    }
+    catch (cause) {
+        return { ok: false, error: error("recording-failed", "Observation recorder failed", cause), observation };
+    }
+}
+function snapshotFor(check) {
+    if (check.kind === "unchanged-304")
+        return { priorSnapshotRef: check.snapshotRef, currentSnapshotRef: check.snapshotRef };
+    return { priorSnapshotRef: check.priorSnapshotRef, currentSnapshotRef: check.currentSnapshotRef };
+}
+function attemptFor(result) {
+    return {
+        extractedAt: result.extractedAt,
+        providerCalls: result.providerCalls,
+        totalTokensUsed: result.totalTokensUsed,
+        ...(result.partial === undefined ? {} : { partial: result.partial }),
+        ...(result.providerFailures === undefined ? {} : {
+            providerFailures: result.providerFailures.map(({ kind, retryable }) => ({ kind, retryable })),
+        }),
+    };
+}
+function outcomeFor(result) {
+    const hasProviderFailures = (result.providerFailures?.length ?? 0) > 0;
+    if (result.partial !== undefined && hasProviderFailures)
+        return "partial-provider-failure";
+    if (hasProviderFailures)
+        return "provider-failure";
+    if (result.error !== undefined)
+        return "extraction-failure";
+    return result.partial === undefined ? "completed" : "partial";
+}
+function isCheckResult(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const result = value;
+    if (typeof result.sourceId !== "string" || typeof result.sourceUrl !== "string" ||
+        typeof result.checkedAt !== "string" || !Array.isArray(result.warnings))
+        return false;
+    if (result.kind === "unchanged-304")
+        return typeof result.snapshotRef === "string";
+    if (result.kind === "unchanged-hash")
+        return typeof result.priorSnapshotRef === "string" && typeof result.currentSnapshotRef === "string";
+    if (result.kind === "changed")
+        return (result.priorSnapshotRef === null || typeof result.priorSnapshotRef === "string") &&
+            typeof result.currentSnapshotRef === "string" && (result.changeBasis === "initial" || result.changeBasis === "hash");
+    return result.kind === "error" && (result.origin === "forage" || result.origin === "lookout") && result.error !== undefined;
+}
+function isExtractionResult(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const result = value;
+    return Array.isArray(result.proposals) && typeof result.extractedAt === "string" &&
+        Number.isFinite(result.providerCalls) && Number.isFinite(result.totalTokensUsed);
+}
+function isIdentity(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const identity = value;
+    return typeof identity.observationId === "string" && identity.observationId !== "" &&
+        (identity.priorObservationId === null || (typeof identity.priorObservationId === "string" && identity.priorObservationId !== ""));
+}
+function error(kind, text, cause) {
+    return { kind, message: text, ...(cause === undefined ? {} : { cause }) };
+}

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/registry.d.ts

@@ -1,14 +1,25 @@
 import type { TargetFieldSchema } from "@kontourai/traverse";
-export type LookoutSourceKind = "web-page" | "api-record";
+export type LookoutSourceKind = "web-page" | "api-record" | "structured-file";
+export type StructuredFileFormat = "yaml" | "json" | "csv";
 export type RenderPolicy = "never" | "on-shell-warning" | "always";
-export interface LookoutSource {
+interface LookoutSourceBase {
     id: string;
-    kind: LookoutSourceKind;
     url: string;
-    targetSchema: TargetFieldSchema[];
     cadenceHint: string;
+}
+export interface ExtractableLookoutSource extends LookoutSourceBase {
+    kind: "web-page" | "api-record";
+    targetSchema: TargetFieldSchema[];
     renderPolicy: RenderPolicy;
+    format?: never;
+}
+export interface StructuredFileLookoutSource extends LookoutSourceBase {
+    kind: "structured-file";
+    format: StructuredFileFormat;
+    targetSchema?: never;
+    renderPolicy?: never;
 }
+export type LookoutSource = ExtractableLookoutSource | StructuredFileLookoutSource;
 export interface LookoutRegistryDocument {
     version: 1;
     sources: LookoutSource[];
@@ -27,3 +38,4 @@ export declare class LookoutRegistry {
 }
 export declare function loadRegistry(registryPath?: string): Promise<LookoutRegistry>;
 export declare function parseRegistry(value: unknown): LookoutRegistry;
+export {};

package/dist/src/registry.js

@@ -49,55 +49,120 @@ export function parseRegistry(value) {
     const ids = new Map();
     const sources = [];
     value.sources.forEach((candidate, index) => {
-        const context = `sources[${index}]`;
-        if (!isRecord(candidate)) {
-            issues.push(`${context} must be an object`);
-            return;
-        }
-        const id = candidate.id;
-        const label = typeof id === "string" && id.trim() ? `${context} (id "${id}")` : context;
-        if (typeof id !== "string" || id.trim() === "") {
-            issues.push(`${context}.id must be a non-empty string`);
-        }
-        else {
-            const first = ids.get(id);
-            if (first !== undefined)
-                issues.push(`${label}.id duplicates sources[${first}].id`);
-            else
-                ids.set(id, index);
-        }
-        if (candidate.kind !== "web-page" && candidate.kind !== "api-record") {
-            issues.push(`${label}.kind must be "web-page" or "api-record"`);
-        }
-        if (!isHttpUrl(candidate.url)) {
-            issues.push(`${label}.url must be an absolute HTTP(S) URL`);
-        }
-        if (typeof candidate.cadenceHint !== "string" || candidate.cadenceHint.trim() === "") {
-            issues.push(`${label}.cadenceHint must be a non-empty string`);
-        }
-        if (candidate.renderPolicy !== "never" &&
-            candidate.renderPolicy !== "on-shell-warning" &&
-            candidate.renderPolicy !== "always") {
-            issues.push(`${label}.renderPolicy must be "never", "on-shell-warning", or "always"`);
-        }
-        validateTargetSchema(candidate.targetSchema, label, issues);
-        if (typeof id === "string" && id.trim() !== "" &&
-            (candidate.kind === "web-page" || candidate.kind === "api-record") &&
-            isHttpUrl(candidate.url) &&
-            typeof candidate.cadenceHint === "string" && candidate.cadenceHint.trim() !== "" &&
-            (candidate.renderPolicy === "never" || candidate.renderPolicy === "on-shell-warning" || candidate.renderPolicy === "always") &&
-            Array.isArray(candidate.targetSchema)) {
-            sources.push(candidate);
-        }
+        const source = parseSource(candidate, index, ids, issues);
+        if (source !== undefined)
+            sources.push(source);
     });
     if (issues.length > 0)
         throw new RegistryValidationError(issues);
     return new LookoutRegistry(sources);
 }
+function parseSource(candidate, index, ids, issues) {
+    const context = `sources[${index}]`;
+    if (!isRecord(candidate)) {
+        issues.push(`${context} must be an object`);
+        return undefined;
+    }
+    const firstIssue = issues.length;
+    const common = validateCommonSource(candidate, index, ids, issues);
+    const source = candidate.kind === "structured-file"
+        ? parseStructuredFileSource(candidate, common, issues)
+        : candidate.kind === "web-page" || candidate.kind === "api-record"
+            ? parseExtractableSource(candidate, candidate.kind, common, issues)
+            : invalidSourceKind(candidate, common.label, issues);
+    return issues.length === firstIssue ? source : undefined;
+}
+function validateCommonSource(candidate, index, ids, issues) {
+    const context = `sources[${index}]`;
+    const id = typeof candidate.id === "string" && candidate.id.trim() !== "" ? candidate.id : undefined;
+    const label = id === undefined ? context : `${context} (id "${id}")`;
+    if (id === undefined) {
+        issues.push(`${context}.id must be a non-empty string`);
+    }
+    else {
+        const first = ids.get(id);
+        if (first !== undefined)
+            issues.push(`${label}.id duplicates sources[${first}].id`);
+        else
+            ids.set(id, index);
+    }
+    const url = isHttpUrl(candidate.url) ? candidate.url : undefined;
+    if (url === undefined) {
+        issues.push(`${label}.url must be an absolute HTTP(S) URL`);
+    }
+    const cadenceHint = typeof candidate.cadenceHint === "string" && candidate.cadenceHint.trim() !== ""
+        ? candidate.cadenceHint
+        : undefined;
+    if (cadenceHint === undefined) {
+        issues.push(`${label}.cadenceHint must be a non-empty string`);
+    }
+    return { id, url, cadenceHint, label };
+}
+function parseStructuredFileSource(candidate, common, issues) {
+    if (!isStructuredFileFormat(candidate.format)) {
+        issues.push(`${common.label}.format must be "yaml", "json", or "csv"`);
+    }
+    if (candidate.targetSchema !== undefined) {
+        issues.push(`${common.label}.targetSchema is not allowed for structured-file sources`);
+    }
+    if (candidate.renderPolicy !== undefined) {
+        issues.push(`${common.label}.renderPolicy is not allowed for structured-file sources`);
+    }
+    if (common.id === undefined || common.url === undefined || common.cadenceHint === undefined ||
+        !isStructuredFileFormat(candidate.format))
+        return undefined;
+    return {
+        id: common.id,
+        kind: "structured-file",
+        format: candidate.format,
+        url: common.url,
+        cadenceHint: common.cadenceHint,
+    };
+}
+function parseExtractableSource(candidate, kind, common, issues) {
+    if (!isRenderPolicy(candidate.renderPolicy)) {
+        issues.push(`${common.label}.renderPolicy must be "never", "on-shell-warning", or "always"`);
+    }
+    const targetSchema = validateTargetSchema(candidate.targetSchema, common.label, issues)
+        ? candidate.targetSchema
+        : undefined;
+    if (candidate.format !== undefined) {
+        issues.push(`${common.label}.format is only allowed for structured-file sources`);
+    }
+    if (common.id === undefined || common.url === undefined || common.cadenceHint === undefined ||
+        !isRenderPolicy(candidate.renderPolicy) || targetSchema === undefined)
+        return undefined;
+    return {
+        id: common.id,
+        kind,
+        url: common.url,
+        targetSchema,
+        cadenceHint: common.cadenceHint,
+        renderPolicy: candidate.renderPolicy,
+    };
+}
+function invalidSourceKind(candidate, label, issues) {
+    issues.push(`${label}.kind must be "web-page", "api-record", or "structured-file"`);
+    if (!isRenderPolicy(candidate.renderPolicy)) {
+        issues.push(`${label}.renderPolicy must be "never", "on-shell-warning", or "always"`);
+    }
+    validateTargetSchema(candidate.targetSchema, label, issues);
+    if (candidate.format !== undefined) {
+        issues.push(`${label}.format is only allowed for structured-file sources`);
+    }
+    return undefined;
+}
+function isStructuredFileFormat(value) {
+    return value === "yaml" || value === "json" || value === "csv";
+}
+function isRenderPolicy(value) {
+    return value === "never" || value === "on-shell-warning" || value === "always";
+}
 function validateTargetSchema(value, context, issues) {
+    const firstIssue = issues.length;
     if (!Array.isArray(value)) {
         issues.push(`${context}.targetSchema must be an array`);
-        return;
+        return false;
     }
     const allowedTypes = new Set(["string", "number", "boolean", "date", "enum", "array", "object"]);
     value.forEach((field, index) => {
@@ -124,6 +189,7 @@ function validateTargetSchema(value, context, issues) {
             issues.push(`${label}.inferenceType must be "explicit" or "inferred"`);
         }
     });
+    return issues.length === firstIssue;
 }
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);

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>;