@kontourai/lookout 0.3.4 → 0.3.6

package/README.md

@@ -279,6 +279,40 @@ Forage's SSRF-guarded fetcher), `fetchOptions`, and
 `clock` — so checks run with no live network or timers in tests. Injecting either
 `fetchSource` or `fetchOptions.fetch` overrides the default guarded transport.
 
+### Bring your own source store
+
+The registry file is a convenience, not the contract. What check
+classification, drift emission, and observation lineage actually consume is
+source identity — enumerate sources, resolve one by exact id — and that
+contract is the `SourceStore` interface: `list()` and `get(id)`, each
+returning its value directly or as a promise. `LookoutRegistry` (what
+`loadRegistry` returns) is the file-backed implementation; nothing downstream
+can tell implementations apart.
+
+Two application shapes motivate the seam. An application whose canonical
+source of truth is its own database — reviewed rows in Postgres or D1, not a
+JSON file — builds `LookoutSource` values from those rows and should not have
+to adopt a second store of record to inherit lineage, continuity, and CHECK
+classification. And a host that owns its own acquisition and run state wants
+to hand Lookout sources it already holds in memory. Both were previously
+re-implementing identity handling around the registry; either can now do:
+
+```ts
+import { inMemorySourceStore } from "@kontourai/lookout";
+
+const store = inMemorySourceStore(sourcesBuiltFromYourRows);
+const results = await runner.checkAll(await store.list());
+```
+
+`inMemorySourceStore` applies exactly the validation `loadRegistry` applies
+to a file — duplicate ids, URL shape, per-kind field rules, every issue
+reported at once — so source-id uniqueness is enforced structurally rather
+than by review convention. A database-backed application can also implement
+`SourceStore` directly (both methods may be async) and query lazily;
+`runCli`'s `loadRegistry` option accepts any `SourceStore`. Keep ids stable
+either way: snapshot identity and observation lineage key off `id`, so
+changing one starts a new history.
+
 ## Observe changed sources without re-extracting unchanged ones
 
 `createObserveExtractDiff` is an optional library composition for callers that

package/dist/src/cli.d.ts

@@ -1,14 +1,14 @@
 import type { Writable } from "node:stream";
 import { type CheckRunner } from "./check-runner.js";
-import { type LookoutRegistry } from "./registry.js";
+import type { SourceStore } from "./source-store.js";
 import { type DriftResult } from "./drift-emission.js";
 export interface RunCliOptions {
     argv?: string[];
     stdout?: Pick<Writable, "write">;
     stderr?: Pick<Writable, "write">;
-    loadRegistry?: (path?: string) => Promise<LookoutRegistry>;
+    loadRegistry?(path?: string): Promise<SourceStore>;
     runner?: CheckRunner;
     readObservation?: (path: string) => Promise<unknown>;
-    emitDrift?: (sourceId: string, value: unknown, registry: LookoutRegistry, observationRoot?: string) => Promise<DriftResult>;
+    emitDrift?(sourceId: string, value: unknown, store: SourceStore, observationRoot?: string): Promise<DriftResult>;
 }
 export declare function runCli(options?: RunCliOptions): Promise<number>;

package/dist/src/cli.js

@@ -13,16 +13,16 @@ export async function runCli(options = {}) {
         stderr.write(`${parsed}\n`);
         return 2;
     }
-    let registry;
+    let store;
     try {
-        registry = await (options.loadRegistry ?? loadRegistry)(parsed.registryPath);
+        store = await (options.loadRegistry ?? loadRegistry)(parsed.registryPath);
     }
     catch (error) {
         stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
         return 1;
     }
     if (parsed.command === "emit-drift") {
-        const source = registry.get(parsed.id);
+        const source = await store.get(parsed.id);
         if (!source) {
             stderr.write(`Unknown source id: ${parsed.id}\n`);
             return 1;
@@ -35,7 +35,7 @@ export async function runCli(options = {}) {
             stderr.write(`Could not read observation: ${error instanceof Error ? error.message : String(error)}\n`);
             return 1;
         }
-        const result = await (options.emitDrift ?? emitDrift)(parsed.id, value, registry, parsed.observationRoot);
+        const result = await (options.emitDrift ?? emitDrift)(parsed.id, value, store, parsed.observationRoot);
         if (!result.ok) {
             stderr.write(`${result.error.kind}: ${result.error.message}\n`);
             return 1;
@@ -47,12 +47,12 @@ export async function runCli(options = {}) {
         store: createLookoutSnapshotStore(parsed.snapshotRoot),
     });
     if (parsed.all) {
-        const results = await runner.checkAll(registry.list());
+        const results = await runner.checkAll(await store.list());
         for (const result of results)
             stdout.write(`${JSON.stringify(result)}\n`);
         return 0;
     }
-    const source = registry.get(parsed.id);
+    const source = await store.get(parsed.id);
     if (!source) {
         stderr.write(`Unknown source id: ${parsed.id}\n`);
         return 1;
@@ -164,10 +164,10 @@ function cliEntities(observation) {
     }
     return [...grouped].map(([key, proposals]) => ({ key, proposals }));
 }
-async function emitDrift(sourceId, value, registry, observationRoot) {
+async function emitDrift(sourceId, value, store, observationRoot) {
     if (!value || typeof value !== "object" || Array.isArray(value))
         return { ok: false, error: { kind: "invalid-input", message: "Observation document must be an object" } };
     const document = value;
-    const source = registry.get(sourceId);
+    const source = (await store.get(sourceId));
     return createDriftEmitter({ store: createObservationStore({ root: observationRoot }) }).emit({ source, current: document.observation, check: document.check, callbacks: { selectEntities: cliEntities, entityIdentity: (entity) => entity.key, proposalsFor: (entity) => entity.proposals, fieldIdentity: (_entity, proposal) => proposal.fieldPath } });
 }

package/dist/src/index.d.ts

@@ -6,6 +6,8 @@ export type { ChangedResult, CheckResult, CheckResultCommon, ErrorResult, Lookou
 export { defaultProviderResolver } from "./provider-resolution.js";
 export type { ProviderResolver } from "./provider-resolution.js";
 export { loadRegistry, LookoutRegistry, parseRegistry, RegistryValidationError, } from "./registry.js";
+export { inMemorySourceStore } from "./source-store.js";
+export type { SourceStore } from "./source-store.js";
 export type { ExtractableLookoutSource, LookoutRegistryDocument, LookoutSource, LookoutSourceKind, RenderPolicy, StructuredFileFormat, StructuredFileLookoutSource, } from "./registry.js";
 export { createLookoutSnapshotStore, resolveLookoutSnapshot, } from "./snapshot-store.js";
 export type { ResolveLookoutSnapshotOptions } from "./snapshot-store.js";

package/dist/src/index.js

@@ -2,6 +2,7 @@ export { runCli } from "./cli.js";
 export { createCheckRunner } from "./check-runner.js";
 export { defaultProviderResolver } from "./provider-resolution.js";
 export { loadRegistry, LookoutRegistry, parseRegistry, RegistryValidationError, } from "./registry.js";
+export { inMemorySourceStore } from "./source-store.js";
 export { createLookoutSnapshotStore, resolveLookoutSnapshot, } from "./snapshot-store.js";
 export { canonicalValueKey } from "./canonical-value.js";
 export { compareStructural, diffKeyedMultiset } from "./structural-diff.js";

package/dist/src/source-store.d.ts

@@ -0,0 +1,35 @@
+import { type LookoutRegistry, type LookoutSource } from "./registry.js";
+/**
+ * The seam between where sources live and everything Lookout does with them.
+ *
+ * Check classification, drift emission, and observation lineage all key off a
+ * source's identity (`LookoutSource.id`), not off the file the source was
+ * declared in. A `SourceStore` is the minimal contract those parts actually
+ * consume: enumerate sources and resolve one by exact id. The bundled file
+ * registry (`loadRegistry` / `LookoutRegistry`) is one implementation; an
+ * application whose canonical source of truth is its own database can
+ * implement this directly, or materialize rows through
+ * {@link inMemorySourceStore}, and still inherit lineage, continuity, and
+ * CHECK classification.
+ *
+ * Methods may return values synchronously or as promises so that an
+ * in-memory store stays allocation-free while a database-backed store can
+ * query lazily. Callers must `await` both methods.
+ */
+export interface SourceStore {
+    /** Every source, in the store's canonical order. */
+    list(): readonly LookoutSource[] | Promise<readonly LookoutSource[]>;
+    /** Exact-id lookup; `undefined` when the id is not present. */
+    get(id: string): LookoutSource | undefined | Promise<LookoutSource | undefined>;
+}
+/**
+ * Build a validated in-memory {@link SourceStore} from sources an application
+ * constructed itself (for example, from its own database rows).
+ *
+ * Runs exactly the validation `loadRegistry` applies to a registry file —
+ * duplicate ids, URL shape, per-kind field rules — and throws the same
+ * `RegistryValidationError` reporting every issue at once. The returned store
+ * is a `LookoutRegistry`, so file-backed and in-memory sources are
+ * indistinguishable downstream.
+ */
+export declare function inMemorySourceStore(sources: readonly LookoutSource[]): LookoutRegistry;

package/dist/src/source-store.js

@@ -0,0 +1,14 @@
+import { parseRegistry } from "./registry.js";
+/**
+ * Build a validated in-memory {@link SourceStore} from sources an application
+ * constructed itself (for example, from its own database rows).
+ *
+ * Runs exactly the validation `loadRegistry` applies to a registry file —
+ * duplicate ids, URL shape, per-kind field rules — and throws the same
+ * `RegistryValidationError` reporting every issue at once. The returned store
+ * is a `LookoutRegistry`, so file-backed and in-memory sources are
+ * indistinguishable downstream.
+ */
+export function inMemorySourceStore(sources) {
+    return parseRegistry({ version: 1, sources });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontourai/lookout",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "description": "A small source registry and drift-check runner built on Forage snapshots.",
   "license": "Apache-2.0",
   "type": "module",
@@ -35,23 +35,26 @@
     "build": "rm -rf dist && tsc",
     "prepare": "npm run build",
     "typecheck": "tsc --noEmit",
-    "test": "npm run build && node --test dist/tests/*.test.js",
+    "test": "npm run build && node scripts/run-tests.mjs",
     "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:consumer": "node scripts/check-installed-consumer.mjs"
+    "check:consumer": "node scripts/check-installed-consumer.mjs",
+    "workflow:sidecar": "flow-agents-workflow-sidecar",
+    "workflow:validate-artifacts": "flow-agents-validate-artifacts"
   },
   "dependencies": {
     "@kontourai/datum": "0.7.0",
     "@kontourai/forage": "0.5.0",
-    "@kontourai/traverse": "0.24.0"
+    "@kontourai/traverse": "0.25.0"
   },
   "devDependencies": {
-    "@kontourai/survey": "2.1.0",
-    "@types/node": "^25.6.0",
-    "typescript": "^5.8.0"
+    "@kontourai/flow-agents": "5.5.0",
+    "@kontourai/survey": "2.4.0",
+    "@types/node": "^26.1.2",
+    "typescript": "^7.0.2"
   },
   "engines": {
     "node": ">=22"