@kontourai/lookout 0.1.0

package/dist/src/survey-emission.js

@@ -0,0 +1,138 @@
+import { createHash } from "node:crypto";
+import { SurveyInputBuilder } from "@kontourai/survey";
+import { diffProposalSets } from "./proposal-diff.js";
+function id(...parts) { return createHash("sha256").update(JSON.stringify(parts)).digest("hex"); }
+function eventValue(event) {
+    return event.kind === "new-entity-appeared"
+        ? { kind: event.kind, entityKey: event.entityKey, currentValues: event.current.map((item) => ({ fieldKey: item.fieldKey, value: item.value })) }
+        : { kind: event.kind, changeKind: event.changeKind, entityKey: event.entityKey, fieldKey: event.fieldKey, ...(event.prior ? { priorValue: event.prior.value } : {}), ...(event.current ? { currentValue: event.current.value } : {}) };
+}
+function observationFor(source, prior, current, event, generatedAt, index) {
+    const eventId = id(source.id, prior.observationId, current.snapshotRef, event.kind, event.entityKey, event.kind === "field-changed" ? event.fieldKey : "", index);
+    const evidence = event.kind === "new-entity-appeared" ? event.current : [event.prior, event.current].filter((item) => item !== undefined);
+    const primary = event.kind === "new-entity-appeared" ? event.current[0] : event.current ?? event.prior;
+    const metadata = {
+        sourceId: source.id, eventKind: event.kind, priorObservationId: prior.observationId,
+        priorSnapshotRef: prior.snapshotRef, currentSnapshotRef: current.snapshotRef,
+        evidence: evidence.map((item) => ({ snapshotRef: item.snapshotRef, locator: item.provenance.locator, excerpt: item.provenance.excerpt, extractor: item.extractor, fieldPath: item.fieldPath })),
+        ...(event.kind === "field-changed" ? { changeKind: event.changeKind } : {}),
+    };
+    return {
+        id: `lookout-${eventId}`,
+        rawSource: { kind: source.kind, resolution: "observation", sourceRef: current.snapshotRef, observedAt: current.observedAt, locatorScheme: source.kind === "web-page" ? "html" : "structured-field", metadata },
+        extraction: { target: `lookout:${event.entityKey}:${event.kind === "field-changed" ? event.fieldKey : "appearance"}`, value: eventValue(event), confidence: primary?.confidence, locator: primary?.provenance.locator, excerpt: primary?.provenance.excerpt, extractor: primary?.extractor ?? "lookout:proposal-diff", extractedAt: generatedAt, metadata },
+        candidateSet: { status: "needs-review", metadata },
+        claim: { subjectType: "lookout.observed-entity", subjectId: event.entityKey, facet: "lookout.source-change", claimType: event.kind === "new-entity-appeared" ? "lookout.new-entity-appeared" : "lookout.field-changed", fieldOrBehavior: event.kind === "field-changed" ? event.fieldKey : event.entityKey, value: eventValue(event), status: "proposed", impactLevel: "low", collectedBy: "@kontourai/lookout", createdAt: generatedAt, evidenceMethod: "observation", metadata },
+    };
+}
+function containsAuthorizing(value) {
+    if (Array.isArray(value))
+        return value.some(containsAuthorizing);
+    if (!value || typeof value !== "object")
+        return false;
+    return Object.entries(value).some(([key, item]) => key === "authorizing" || containsAuthorizing(item));
+}
+function validateSurveyInput(input, source, current, prior, events) {
+    if (input.reviewOutcomes.length !== 0 || containsAuthorizing(input))
+        return false;
+    if (input.rawSources.length !== events.length || input.claims.length !== events.length)
+        return false;
+    for (const raw of input.rawSources)
+        if (raw.kind !== source.kind || raw.resolution !== "observation" || raw.sourceRef !== current.snapshotRef)
+            return false;
+    for (let index = 0; index < events.length; index += 1) {
+        const claim = input.claims[index];
+        const event = events[index];
+        if (!claim || !event || claim.status !== "proposed" || claim.metadata?.priorSnapshotRef !== prior.snapshotRef || claim.metadata?.currentSnapshotRef !== current.snapshotRef)
+            return false;
+        const evidence = claim.metadata.evidence;
+        if (!Array.isArray(evidence))
+            return false;
+        if (event.kind === "new-entity-appeared" && !event.current.every((side) => evidence.some((item) => item && typeof item === "object" && item.snapshotRef === side.snapshotRef)))
+            return false;
+        if (event.kind === "field-changed") {
+            if (event.prior && !evidence.some((item) => item && typeof item === "object" && item.snapshotRef === event.prior.snapshotRef))
+                return false;
+            if (event.current && !evidence.some((item) => item && typeof item === "object" && item.snapshotRef === event.current.snapshotRef))
+                return false;
+            if (!event.current && !input.rawSources[index] || input.rawSources[index]?.sourceRef !== current.snapshotRef)
+                return false;
+        }
+    }
+    return true;
+}
+function stableJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stableJson).join(",")}]`;
+    if (value && typeof value === "object")
+        return `{${Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([key, item]) => `${JSON.stringify(key)}:${stableJson(item)}`).join(",")}}`;
+    return JSON.stringify(value) ?? "undefined";
+}
+function normalizeDiff(value) {
+    const sorted = (items) => [...items].sort((a, b) => stableJson(a).localeCompare(stableJson(b)));
+    return { events: sorted(value.events), facts: { retainedProposalOccurrences: sorted(value.facts.retainedProposalOccurrences), addedProposalOccurrences: sorted(value.facts.addedProposalOccurrences), removedProposalOccurrences: sorted(value.facts.removedProposalOccurrences), provenanceChanges: sorted(value.facts.provenanceChanges), removedEntities: [...value.facts.removedEntities].sort() } };
+}
+export function createSurveyEmitter(options) {
+    const now = options.now ?? (() => new Date().toISOString());
+    const diff = options.diff ?? diffProposalSets;
+    return { async emit(input) {
+            try {
+                if (options.resolution !== undefined && options.resolution !== "observation")
+                    return { ok: false, error: { kind: "invalid-input", message: "Lookout may author only observation resolution" } };
+                if (!input.source || input.source.id !== input.current?.sourceId || input.check?.currentSnapshotRef !== input.current?.snapshotRef)
+                    return { ok: false, error: { kind: "invalid-input", message: "Registry source, observation, and check anchor must agree" } };
+                const loaded = await options.store.loadLatest(input.source.id);
+                if (!loaded.ok)
+                    return { ok: false, error: { kind: "prior-state-error", message: loaded.error.message, cause: loaded.error } };
+                const recordedAt = now();
+                let events = [];
+                let facts;
+                let surveyInput = null;
+                if (loaded.value === null) {
+                    facts = [{ kind: "baseline-established", sourceId: input.source.id, snapshotRef: input.current.snapshotRef, observedAt: input.current.observedAt, origin: input.source.kind, resolution: "observation", proposalCount: input.current.proposals.length }];
+                }
+                else {
+                    let derived;
+                    try {
+                        derived = diff({ prior: { sourceId: loaded.value.sourceId, snapshotRef: loaded.value.snapshotRef, observedAt: loaded.value.observedAt, proposals: loaded.value.proposals }, current: input.current, ...input.callbacks });
+                    }
+                    catch (cause) {
+                        return { ok: false, error: { kind: "diff-error", message: "Proposal diff threw", cause } };
+                    }
+                    if (!derived.ok)
+                        return { ok: false, error: { kind: "diff-error", message: derived.error.message, cause: derived.error } };
+                    const normalized = normalizeDiff(derived.value);
+                    events = normalized.events;
+                    facts = [{ kind: "proposal-set-facts", priorSnapshotRef: loaded.value.snapshotRef, currentSnapshotRef: input.current.snapshotRef, origin: input.source.kind, resolution: "observation", value: normalized.facts }];
+                    if (events.length > 0) {
+                        try {
+                            const builder = new SurveyInputBuilder({ source: "@kontourai/lookout", generatedAt: recordedAt });
+                            builder.addObservations(events.map((event, index) => observationFor(input.source, loaded.value, input.current, event, recordedAt, index)));
+                            surveyInput = builder.build();
+                            if (options.transformSurveyInput)
+                                surveyInput = options.transformSurveyInput(surveyInput);
+                            JSON.stringify(surveyInput);
+                            if (!validateSurveyInput(surveyInput, input.source, input.current, loaded.value, events))
+                                return { ok: false, error: { kind: "authoring-error", message: "SurveyInput violated observation-only provenance" } };
+                        }
+                        catch (cause) {
+                            return { ok: false, error: { kind: "authoring-error", message: "Could not author SurveyInput", cause } };
+                        }
+                    }
+                }
+                try {
+                    JSON.stringify({ events, facts, surveyInput });
+                }
+                catch (cause) {
+                    return { ok: false, error: { kind: "authoring-error", message: "Emission result is not serializable", cause } };
+                }
+                const committed = await options.store.commit({ observation: input.current, recordedAt, check: input.check }, loaded.value?.observationId ?? null);
+                if (!committed.ok)
+                    return { ok: false, error: { kind: "persistence-error", message: committed.error.message, cause: committed.error } };
+                return { ok: true, value: { sourceId: input.source.id, events, facts, surveyInput, committedObservation: committed.value, warnings: committed.warnings ?? [] } };
+            }
+            catch (cause) {
+                return { ok: false, error: { kind: "authoring-error", message: "Emission failed", cause } };
+            }
+        } };
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@kontourai/lookout",
+  "version": "0.1.0",
+  "description": "A small source registry and drift-check runner built on Traverse snapshots.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "private": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kontourai/lookout.git"
+  },
+  "homepage": "https://github.com/kontourai/lookout#readme",
+  "bugs": {
+    "url": "https://github.com/kontourai/lookout/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "bin": {
+    "lookout": "bin/lookout.mjs"
+  },
+  "files": [
+    "dist/src/",
+    "bin/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc",
+    "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",
+    "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"
+  },
+  "dependencies": {
+    "@kontourai/datum": "0.3.0",
+    "@kontourai/survey": "1.7.0",
+    "@kontourai/traverse": "0.14.1"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "typescript": "^5.8.0"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}