@superbee/core 0.2.0-pre.4 → 0.2.0-pre.41

package/dist/source-engine/machine-state.js

@@ -0,0 +1,94 @@
+/**
+ * The machine-state port: one JSON document per Source Feed holding the stored cursor, the last
+ * accepted values of every record and the changes still pending a write, written with a
+ * compare-and-swap on its version. The managed runner keeps it in its own store;
+ * `MemoryMachineState` serves tests and local runs.
+ */
+import { parseIsoInstant } from "../verification.js";
+import { isSourceEstablishment } from "./target-descriptor.js";
+export class MachineStateConflict extends Error {
+    code = "MACHINE_STATE_CONFLICT";
+    constructor(key) {
+        super(`machine state for ${key} changed since it was read`);
+        this.name = "MachineStateConflict";
+    }
+}
+/** Machine state in memory. Values are copied in and out, so a caller never aliases the store. */
+export class MemoryMachineState {
+    entries = new Map();
+    counter = 0;
+    async read(key) {
+        const entry = this.entries.get(key);
+        return entry ? { state: JSON.parse(entry.json), version: entry.version } : null;
+    }
+    async write(key, state, expected) {
+        const current = this.entries.get(key)?.version ?? null;
+        if (current !== expected)
+            throw new MachineStateConflict(key);
+        const version = String(++this.counter);
+        this.entries.set(key, { json: JSON.stringify(state), version });
+        return version;
+    }
+    /** Every key stored. */
+    keys() {
+        return [...this.entries.keys()].sort();
+    }
+}
+const record = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+/** Whether a stored value has the shape the engine writes. */
+const isEntry = (entry) => record(entry) && record(entry.after) && typeof entry.digest === "string"
+    && Number.isInteger(entry.missing) && typeof entry.seen_at === "string";
+/** Establishments written by older consumers remain protected without inventing page context. */
+export function hasProtectedSourcePending(state) {
+    return state.pending_commit !== undefined || Object.values(state.pending ?? {}).some(p => p.establishment !== undefined);
+}
+const scalarId = (id) => typeof id === "string" && id.length > 0
+    && !/[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/u.test(id);
+function pendingCommitValid(state) {
+    const context = state.pending_commit;
+    if (context === undefined)
+        return true;
+    if (!record(context) || Object.keys(context).some(k => !["v", "order", "page", "baseline", "complete"].includes(k))
+        || context.v !== 1 || !Array.isArray(context.order) || context.order.length < 1 || context.order.length > 100
+        || !context.order.every(scalarId) || new Set(context.order).size !== context.order.length
+        || !Number.isSafeInteger(context.page) || context.page < 1
+        || typeof context.baseline !== "boolean" || typeof context.complete !== "boolean" || !record(state.pending)
+        || Object.keys(state.pending).length !== context.order.length)
+        return false;
+    let at;
+    for (const id of context.order) {
+        if (!Object.hasOwn(state.pending, id))
+            return false;
+        const pending = state.pending[id];
+        if (!record(pending) || typeof pending.held_at !== "string" || parseIsoInstant(pending.held_at) === null
+            || at !== undefined && pending.held_at !== at)
+            return false;
+        if (pending.establishment !== undefined && (!isSourceEstablishment(pending.establishment)
+            || pending.establishment.observed_at !== pending.held_at))
+            return false;
+        at = pending.held_at;
+    }
+    try {
+        return new TextEncoder().encode(JSON.stringify(state)).length <= 4194304;
+    }
+    catch {
+        return false;
+    }
+}
+export function isSourceState(value) {
+    if (!record(value) || value.v !== 1 || typeof value.open !== "boolean" || !record(value.records))
+        return false;
+    if (!record(value.profile) || typeof value.profile.id !== "string" || !Number.isInteger(value.profile.version))
+        return false;
+    if (!Number.isInteger(value.complete_observations))
+        return false;
+    if (value.validators !== undefined && !record(value.validators))
+        return false;
+    if (value.pending !== undefined && !(record(value.pending) && Object.entries(value.pending).every(([id, pending]) => record(pending)
+        && isEntry(pending.entry) && typeof pending.held_at === "string" && record(pending.change) && pending.change.external_id === id
+        && typeof pending.change.change_kind === "string"
+        && (pending.establishment === undefined || isSourceEstablishment(pending.establishment)))))
+        return false;
+    return Object.values(value.records).every(isEntry) && pendingCommitValid(value);
+}
+//# sourceMappingURL=machine-state.js.map

package/dist/source-engine/machine-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"machine-state.js","sourceRoot":"","sources":["../../src/source-engine/machine-state.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAoE/D,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IACpC,IAAI,GAAG,wBAAwB,CAAC;IACzC,YAAY,GAAW;QACrB,KAAK,CAAC,qBAAqB,GAAG,4BAA4B,CAAC,CAAC;QAC5D,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF;AAED,kGAAkG;AAClG,MAAM,OAAO,kBAAkB;IACZ,OAAO,GAAG,IAAI,GAAG,EAA6C,CAAC;IACxE,OAAO,GAAG,CAAC,CAAC;IAEpB,KAAK,CAAC,IAAI,CAAC,GAAW;QACpB,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACpC,OAAO,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAgB,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IACjG,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,GAAW,EAAE,KAAkB,EAAE,QAAuB;QAClE,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,OAAO,IAAI,IAAI,CAAC;QACvD,IAAI,OAAO,KAAK,QAAQ;YAAE,MAAM,IAAI,oBAAoB,CAAC,GAAG,CAAC,CAAC;QAC9D,MAAM,OAAO,GAAG,MAAM,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QACvC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC;QAChE,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,wBAAwB;IACxB,IAAI;QACF,OAAO,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACzC,CAAC;CACF;AAED,MAAM,MAAM,GAAG,CAAC,KAAc,EAAoC,EAAE,CAClE,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAEvE,8DAA8D;AAC9D,MAAM,OAAO,GAAG,CAAC,KAAc,EAAW,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ;OAChH,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ,CAAC;AAE1E,iGAAiG;AACjG,MAAM,UAAU,yBAAyB,CAAC,KAAkB;IAC1D,OAAO,KAAK,CAAC,cAAc,KAAK,SAAS,IAAI,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,aAAa,KAAK,SAAS,CAAC,CAAC;AAC3H,CAAC;AAED,MAAM,QAAQ,GAAG,CAAC,EAAW,EAAgB,EAAE,CAAC,OAAO,EAAE,KAAK,QAAQ,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC;OAClF,CAAC,yEAAyE,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AAEzF,SAAS,kBAAkB,CAAC,KAA8B;IACxD,MAAM,OAAO,GAAG,KAAK,CAAC,cAAc,CAAC;IACrC,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACvC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;WAC9G,OAAO,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,OAAO,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,OAAO,CAAC,KAAK,CAAC,MAAM,GAAG,GAAG;WAC1G,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,IAAI,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC,KAAK,CAAC,MAAM;WACtF,CAAC,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,IAAI,CAAC,IAAK,OAAO,CAAC,IAAe,GAAG,CAAC;WACnE,OAAO,OAAO,CAAC,QAAQ,KAAK,SAAS,IAAI,OAAO,OAAO,CAAC,QAAQ,KAAK,SAAS,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC;WACxG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,MAAM,KAAK,OAAO,CAAC,KAAK,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAC9E,IAAI,EAAsB,CAAC;IAC3B,KAAK,MAAM,EAAE,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;QAC/B,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;YAAE,OAAO,KAAK,CAAC;QACpD,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAClC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,OAAO,OAAO,CAAC,OAAO,KAAK,QAAQ,IAAI,eAAe,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,IAAI;eACnG,EAAE,KAAK,SAAS,IAAI,OAAO,CAAC,OAAO,KAAK,EAAE;YAAE,OAAO,KAAK,CAAC;QAC9D,IAAI,OAAO,CAAC,aAAa,KAAK,SAAS,IAAI,CAAC,CAAC,qBAAqB,CAAC,OAAO,CAAC,aAAa,CAAC;eACpF,OAAO,CAAC,aAAa,CAAC,WAAW,KAAK,OAAO,CAAC,OAAO,CAAC;YAAE,OAAO,KAAK,CAAC;QAC1E,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC;IACvB,CAAC;IACD,IAAI,CAAC;QAAC,OAAO,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,IAAI,OAAO,CAAC;IAAC,CAAC;IACjF,MAAM,CAAC;QAAC,OAAO,KAAK,CAAC;IAAC,CAAC;AACzB,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,CAAC,KAAK,CAAC,IAAI,OAAO,KAAK,CAAC,IAAI,KAAK,SAAS,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC;QAAE,OAAO,KAAK,CAAC;IAC/G,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,OAAO,KAAK,CAAC,OAAO,CAAC,EAAE,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC;QAAE,OAAO,KAAK,CAAC;IAC7H,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,qBAAqB,CAAC;QAAE,OAAO,KAAK,CAAC;IACjE,IAAI,KAAK,CAAC,UAAU,KAAK,SAAS,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC;QAAE,OAAO,KAAK,CAAC;IAC9E,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC;WAC/H,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,OAAO,OAAO,CAAC,OAAO,KAAK,QAAQ,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,OAAO,CAAC,MAAM,CAAC,WAAW,KAAK,EAAE;WAC5H,OAAO,OAAO,CAAC,MAAM,CAAC,WAAW,KAAK,QAAQ;WAC9C,CAAC,OAAO,CAAC,aAAa,KAAK,SAAS,IAAI,qBAAqB,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IAC3G,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,kBAAkB,CAAC,KAAK,CAAC,CAAC;AAClF,CAAC"}

package/dist/source-engine/observe.d.ts

@@ -0,0 +1,10 @@
+import type { ObserveSourceOptions, SourceRunReceipt } from "./types.js";
+export { DEFAULT_MISSING_THRESHOLD, MAX_CURSOR_CHARS, MAX_REPLAY_FAILURES } from "./driver.js";
+/** Thrown by a profile that cannot read a provider's body; the run ends `unsupported_content`. */
+export declare function unsupportedContent(detail: string): never;
+/**
+ * Run one observation of a bound Source Feed. Returns a receipt; never throws for a provider,
+ * profile, guard or commit problem, which all end the run with an outcome and a finding.
+ */
+export declare function observeSource<Spec, Cursor>(options: ObserveSourceOptions<Spec, Cursor>): Promise<SourceRunReceipt>;
+//# sourceMappingURL=observe.d.ts.map

package/dist/source-engine/observe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observe.d.ts","sourceRoot":"","sources":["../../src/source-engine/observe.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EACV,oBAAoB,EAGpB,gBAAgB,EAEjB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,yBAAyB,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAM/F,kGAAkG;AAClG,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,KAAK,CAExD;AAoED;;;GAGG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,oBAAoB,CAAC,IAAI,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAgKxH"}

package/dist/source-engine/observe.js

@@ -0,0 +1,276 @@
+import { validateConnectorRequest, declarationRequestRules, placeholders, providerRequestRules } from "../connector-request.js";
+/**
+ * The observation loop: run a profile page by page behind the guarded transport, diff each page
+ * against the stored records into record-overlay changes, hand them to the caller's commit, and
+ * only then store the cursor and the records. A change the commit asks to retry stays pending in
+ * the machine state and is planned again before the next run fetches anything. Generic observers
+ * may advance past a held record. The registered target consumer instead checkpoints the whole
+ * supplying group before effects and cannot advance while any member remains unresolved.
+ * A pass counts as a complete observation only when it ran in complete
+ * mode from no cursor to its last page within this run, the profile claimed it complete and the
+ * source is declared complete; only a complete observation counts a stored record as missing, and
+ * a record is `disappeared` after `missing_threshold` of them.
+ */
+import { findingsFor, inspectSourceReadPolicy } from "../connectors.js";
+import { DEFAULT_SOURCE_BUDGET, DEFAULT_STATUS_RULES, guardTransport, raceAbort, sourceHostSet } from "./guard.js";
+import { hasProtectedSourcePending, isSourceState } from "./machine-state.js";
+export { DEFAULT_MISSING_THRESHOLD, MAX_CURSOR_CHARS, MAX_REPLAY_FAILURES } from "./driver.js";
+import { driveObservation, UNSUPPORTED_CONTENT } from "./driver.js";
+const PROFILE_ID = /^[a-z][a-z0-9-]*$/;
+/** Thrown by a profile that cannot read a provider's body; the run ends `unsupported_content`. */
+export function unsupportedContent(detail) {
+    throw Object.assign(new Error(`unsupported content: ${detail}`), { code: UNSUPPORTED_CONTENT, detail });
+}
+const record = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const clip = (text, n) => text.length > n ? text.slice(0, n - 1) + "…" : text;
+function budgetOf(given) {
+    const budget = { ...DEFAULT_SOURCE_BUDGET, ...given };
+    // Timer delays above 2^31 - 1 milliseconds overflow to an immediate timeout.
+    const ok = ["requests", "maxBytes", "redirects", "pages", "deadlineMs", "requestTimeoutMs"].every((key) => Number.isInteger(budget[key])
+        && budget[key] >= (key === "redirects" ? 0 : 1) && budget[key] <= 2 ** 31 - 1);
+    return ok ? budget : undefined;
+}
+function statusesOf(given) {
+    const statuses = { ...DEFAULT_STATUS_RULES, ...given };
+    const ok = Object.values(statuses).every((list) => Array.isArray(list) && list.every((s) => Number.isInteger(s) && s >= 400 && s <= 599));
+    return ok ? statuses : undefined;
+}
+function profileProblem(profile) {
+    if (!record(profile))
+        return "not a profile";
+    if (typeof profile.id !== "string" || !PROFILE_ID.test(profile.id))
+        return "id is a slug";
+    if (!Number.isInteger(profile.version) || profile.version < 1)
+        return "version is a positive integer";
+    if (profile.kind !== "generic" && profile.kind !== "extension")
+        return "kind is generic or extension";
+    if (typeof profile.validateSpec !== "function" || typeof profile.hostsFor !== "function" || typeof profile.observe !== "function")
+        return "missing a method";
+    return undefined;
+}
+function emptyState(profile) {
+    return { v: 1, profile: { id: profile.id, version: profile.version }, cursor: null, open: false, records: {}, complete_observations: 0 };
+}
+const OUTCOME_TEXT = {
+    deferred: "the provider asked to slow down; the run stopped and resumes from the last committed page",
+    credential_refused: "the provider refused the credential; runs stay stopped until the credential changes",
+    provider_unavailable: "the provider did not answer usefully; nothing past the last committed page was read",
+    not_found: "the provider says the resource does not exist",
+    unsupported_content: "the provider sent a body the profile cannot read; nothing from it was written",
+    too_large: "the provider sent a body over the byte bound; nothing from it was written",
+    refused: "a request was refused before it was sent",
+    failed: "the run failed before its page was stored",
+};
+/** One finding for a run that did not end as observed, keyed so a repeat collapses into one Signal. */
+function outcomeFinding(source, stop, url) {
+    if (stop.outcome === "observed" || (stop.outcome === "deferred" && (stop.reason === "budget" || stop.reason === "deadline")))
+        return null;
+    const where = url ? ` (${clip(url, 160)})` : "";
+    const status = stop.status !== undefined ? ` Status ${stop.status}.` : "";
+    return {
+        key: `source:${source}:${stop.outcome}${stop.reason ? `:${stop.reason}` : ""}`,
+        title: clip(`Source ${source}: ${stop.outcome.replaceAll("_", " ")}${stop.reason ? ` (${stop.reason.replaceAll("_", " ")})` : ""}`, 140),
+        summary: clip(`${OUTCOME_TEXT[stop.outcome] ?? stop.outcome}.${status}${where}`, 600),
+        priority: stop.outcome === "credential_refused" || stop.outcome === "refused" || stop.outcome === "failed" ? "normal" : "low",
+        facts: { outcome: stop.outcome, reason: stop.reason ?? null, status: stop.status ?? null },
+    };
+}
+/** A URL as a finding shows it: scheme, host and path, never the query. */
+function findingUrl(url) {
+    if (!url)
+        return undefined;
+    try {
+        const parsed = new URL(url);
+        return `${parsed.protocol}//${parsed.host}${parsed.pathname}`;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Run one observation of a bound Source Feed. Returns a receipt; never throws for a provider,
+ * profile, guard or commit problem, which all end the run with an outcome and a finding.
+ */
+export async function observeSource(options) {
+    const now = options.now ?? (() => new Date());
+    const observedAt = now().toISOString();
+    // Authority is private to this run: callback views cannot rewrite the checked declaration.
+    const { bound, connector, readPolicyApproval } = structuredClone({ bound: options.bound, connector: options.connector, readPolicyApproval: options.readPolicyApproval });
+    const profile = options.profile;
+    const requestedMode = options.mode ?? "incremental";
+    const receipt = {
+        feed: bound.policy.feed,
+        provider: bound.policy.provider,
+        source: bound.source.name,
+        profile: { id: String(profile?.id), version: Number(profile?.version) },
+        mode: requestedMode,
+        observed_at: observedAt,
+        outcome: "observed",
+        retry: true,
+        pages: 0,
+        held: 0,
+        pending: 0,
+        requests: [],
+        pass: { resumed: false, ended: false, complete: false },
+        changes: { new: 0, changed: 0, disappeared: 0 },
+        cursor: null,
+        diagnostics: [],
+        profile_diagnostics: [],
+        findings: [],
+    };
+    let stop;
+    let stopUrl;
+    const extraFindings = [];
+    const finish = () => {
+        if (stop) {
+            receipt.outcome = stop.outcome;
+            receipt.retry = stop.retry;
+            if (stop.reason !== undefined)
+                receipt.reason = stop.reason;
+            if (stop.detail !== undefined)
+                receipt.detail = clip(stop.detail, 300);
+            if (stop.status !== undefined)
+                receipt.status = stop.status;
+            if (stop.retry_after !== undefined)
+                receipt.retry_after = stop.retry_after;
+        }
+        const mapping = findingsFor(receipt.diagnostics, { source: bound.source.name });
+        const outcome = stop ? outcomeFinding(bound.source.name, stop, findingUrl(stopUrl)) : null;
+        receipt.findings = [...(outcome ? [outcome] : []), ...extraFindings, ...mapping];
+        return receipt;
+    };
+    const refuse = (reason, detail) => {
+        stop = { outcome: "refused", reason, retry: false, ...(detail !== undefined ? { detail } : {}) };
+        return finish();
+    };
+    const errorText = (error) => (error instanceof Error ? error.message : String(error));
+    if (bound.source.request?.read_policy !== undefined) {
+        try {
+            const inspected = inspectSourceReadPolicy(connector, bound);
+            if (readPolicyApproval?.contract !== 1 || readPolicyApproval.digest !== inspected.digest || Object.keys(readPolicyApproval).length !== 2)
+                return refuse("read_policy_unapproved");
+        }
+        catch {
+            return refuse("binding_invalid");
+        }
+    }
+    const problem = profileProblem(profile);
+    if (problem)
+        return refuse("profile_invalid", problem);
+    if (profile.id !== bound.source.profile)
+        return refuse("profile_mismatch", `the source names ${bound.source.profile}`);
+    if (requestedMode !== "incremental" && requestedMode !== "complete")
+        return refuse("mode_invalid");
+    const declaredRequest = bound.source.request;
+    if (declaredRequest !== undefined) {
+        const problems = validateConnectorRequest(bound.source, connector);
+        if (problems.length)
+            return refuse("declaration_invalid", problems.map(p => `${p.path} ${p.message}`).join("; "));
+    }
+    if (declaredRequest && placeholders(bound.source.identity.resource).some(name => typeof bound.parameters[name] !== "string" || bound.parameters[name] === "" || [".", ".."].includes(bound.parameters[name])))
+        return refuse("binding_invalid", "request requires every resource binding value");
+    const budget = budgetOf(options.budget);
+    if (!budget)
+        return refuse("budget_invalid");
+    if (declaredRequest?.rate)
+        budget.requests = Math.min(budget.requests, declaredRequest.rate.requests);
+    const statuses = statusesOf(declaredRequest?.errors ?? options.statuses);
+    if (!statuses)
+        return refuse("statuses_invalid");
+    const identity = structuredClone(options.identity);
+    if (!record(identity) || typeof identity.userAgent !== "string" || !/^[\x20-\x7e]{1,512}$/.test(identity.userAgent)
+        || typeof identity.productToken !== "string" || !/^[A-Za-z_-]{1,64}$/.test(identity.productToken))
+        return refuse("identity_invalid");
+    let spec;
+    let hosts;
+    try {
+        const checked = profile.validateSpec(options.spec);
+        if (!checked.ok)
+            return refuse("spec_invalid", checked.errors.map((e) => `${e.path} ${e.message}`).join("; "));
+        spec = checked.spec;
+        hosts = profile.hostsFor(spec, structuredClone(bound));
+    }
+    catch (error) {
+        stop = { outcome: "failed", reason: "profile_error", retry: false, detail: errorText(error) };
+        return finish();
+    }
+    if (!Array.isArray(hosts) || !hosts.every((host) => typeof host === "string"))
+        return refuse("hosts_invalid");
+    const hostSet = sourceHostSet(connector, hosts);
+    if (!hostSet.ok)
+        return refuse("hosts_undeclared", hostSet.undeclared.join(", "));
+    if (hostSet.hosts.credential.size && !declaredRequest)
+        return refuse("declaration_required", "credentialed sources require a binding-scoped request declaration");
+    const key = bound.policy.feed;
+    let version;
+    let state;
+    try {
+        const stored = await options.state.read(key);
+        if (stored && !isSourceState(stored.state)) {
+            stop = { outcome: "failed", reason: "state_invalid", retry: false };
+            return finish();
+        }
+        version = stored?.version ?? null;
+        state = stored?.state ?? emptyState(profile);
+    }
+    catch (error) {
+        stop = { outcome: "failed", reason: "state_unreadable", retry: true, detail: errorText(error) };
+        return finish();
+    }
+    const baseline = version === null;
+    receipt.cursor = state.cursor;
+    receipt.pending = Object.keys(state.pending ?? {}).length;
+    let mode = requestedMode;
+    if (state.profile.id !== profile.id || state.profile.version !== profile.version) {
+        if (hasProtectedSourcePending(state)) {
+            stop = { outcome: "failed", reason: "establishment_scope_changed", retry: false };
+            return finish();
+        }
+        // A cursor is the profile's own format, so another profile's is never handed back.
+        if (!baseline)
+            receipt.cursor_reset = "profile_version";
+        state = { ...state, profile: { id: profile.id, version: profile.version }, cursor: null, open: false };
+        delete state.validators;
+        if (!baseline)
+            mode = "complete";
+    }
+    receipt.mode = mode;
+    // A complete observation always lists from the start; an incremental one continues the stored cursor.
+    const resumed = mode === "incremental" && state.open;
+    receipt.pass.resumed = resumed;
+    // Without the caller's deadline the run has its own; every request has its own timeout either way.
+    const ownDeadline = options.signal ? undefined : new AbortController();
+    const timer = ownDeadline ? setTimeout(() => ownDeadline.abort(), budget.deadlineMs) : undefined;
+    const signal = options.signal ?? ownDeadline.signal;
+    const declarationRules = declaredRequest ? declarationRequestRules(connector, bound) : undefined;
+    const customRules = options.rules;
+    const rules = declarationRules ? {
+        url: (url, hop) => declarationRules.url(url, hop) && (!customRules?.url || customRules.url(url, hop)),
+        post: (url, body) => declarationRules.post(url, body) && (!customRules?.post || customRules.post(url, body)),
+        header: (name, url) => declarationRules.header(name, url) && (!customRules?.header || customRules.header(name, url)),
+        response: declarationRules.response,
+    } : customRules ?? {};
+    const guard = guardTransport({
+        hosts: hostSet.hosts, transport: options.transport, identity, budget, rules, statuses, now, conditional: mode === "incremental",
+        signal, requestTimeoutMs: budget.requestTimeoutMs, authority: declarationRules, graphqlPaths: providerRequestRules(connector.auth)?.read_posts.filter(p => p.graphql).map(p => p.path),
+    });
+    receipt.requests = guard.requests;
+    try {
+        await driveObservation({
+            bound, state: options.state, initial: state, version, receipt, observedAt, mode, resumed, signal, pages: budget.pages,
+            acquire: ({ cursor, resumed, mode, validators }) => raceAbort(profile.observe({
+                spec, bound: structuredClone(bound), cursor, resumed, mode, transport: guard.transport,
+                budget: { requests: guard.remaining(), maxBytes: budget.maxBytes }, now: now(), validators,
+            }), signal),
+            stopped: () => guard.stopped(), lastUrl: () => guard.requests.at(-1)?.url,
+            stop: (value, url) => { stop = value; stopUrl = url; }, extraFindings, prepareCommit: options.prepareCommit, commit: options.commit,
+        });
+        return finish();
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        guard.close();
+    }
+}
+//# sourceMappingURL=observe.js.map

package/dist/source-engine/observe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observe.js","sourceRoot":"","sources":["../../src/source-engine/observe.ts"],"names":[],"mappings":"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"}

package/dist/source-engine/overlay.d.ts

@@ -0,0 +1,50 @@
+import type { SourceIndex } from "../record-overlay/source-index.js";
+import type { Finding, OverlayBundle, OverlayHooks, OverlayPolicy, OverlayReceipt, PlanInput, RecordChange } from "../record-overlay/types.js";
+import type { SourceState } from "./machine-state.js";
+import type { CommitResult, PageCommit } from "./types.js";
+export declare const MAX_SOURCE_OVERLAY_ENTRIES = 10000;
+export interface SourceOverlayEntry {
+    feed: string;
+    resource: string;
+    external_id: string;
+    target: string;
+    after: Record<string, unknown>;
+}
+export interface SourceOverlaySnapshot {
+    v: 1;
+    entries: SourceOverlayEntry[];
+}
+export interface SourceOverlayResult extends CommitResult {
+    receipt: OverlayReceipt;
+    changes: RecordChange[];
+}
+export interface SourceOverlayOptions {
+    content: OverlayBundle;
+    ops?: OverlayBundle;
+    policy: OverlayPolicy;
+    actor: string;
+    overlays: SourceIndex;
+    accepted?: SourceOverlaySnapshot;
+    slug?: string;
+    sameBundle?: boolean;
+    hooks?: OverlayHooks;
+    signals?: PlanInput["signals"];
+}
+/** Validate before admitting private persisted acceptance; never silently reset malformed state. */
+export declare function isSourceOverlaySnapshot(value: unknown): value is SourceOverlaySnapshot;
+/**
+ * One adapter per run with one fresh index shared by planning and application. Its staged
+ * snapshot must be co-published with the supplying observation, then consumed. Failure discards
+ * the stage; the caller must stop the run. This object owns no durable state or cursor.
+ */
+export declare function createSourceOverlayAdapter(options: SourceOverlayOptions): {
+    snapshot: () => SourceOverlaySnapshot;
+    stagedSnapshot: () => SourceOverlaySnapshot | null;
+    consume(): void;
+    discard(): void;
+    commit: (page: PageCommit) => Promise<SourceOverlayResult>;
+    reconcile(state: SourceState, observedAt: string): Promise<SourceOverlayResult>;
+    applyFindings(findings: readonly Finding[], observedAt: string): Promise<OverlayReceipt>;
+};
+export type SourceOverlayAdapter = ReturnType<typeof createSourceOverlayAdapter>;
+//# sourceMappingURL=overlay.d.ts.map

package/dist/source-engine/overlay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlay.d.ts","sourceRoot":"","sources":["../../src/source-engine/overlay.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mCAAmC,CAAC;AACrE,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC/I,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE3D,eAAO,MAAM,0BAA0B,QAAS,CAAC;AACjD,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AACD,MAAM,WAAW,qBAAqB;IAAG,CAAC,EAAE,CAAC,CAAC;IAAC,OAAO,EAAE,kBAAkB,EAAE,CAAA;CAAE;AAC9E,MAAM,WAAW,mBAAoB,SAAQ,YAAY;IAAG,OAAO,EAAE,cAAc,CAAC;IAAC,OAAO,EAAE,YAAY,EAAE,CAAA;CAAE;AAC9G,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,aAAa,CAAC;IACvB,GAAG,CAAC,EAAE,aAAa,CAAC;IACpB,MAAM,EAAE,aAAa,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,WAAW,CAAC;IACtB,QAAQ,CAAC,EAAE,qBAAqB,CAAC;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,OAAO,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;CAChC;AAGD,oGAAoG;AACpG,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,qBAAqB,CAStF;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,oBAAoB;oBAiDtD,qBAAqB;0BACf,qBAAqB,GAAG,IAAI;eACrC,IAAI;eACJ,IAAI;mBACA,UAAU,KAAG,OAAO,CAAC,mBAAmB,CAAC;qBACjC,WAAW,cAAc,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;4BAUvD,SAAS,OAAO,EAAE,cAAc,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;EAOjG;AACD,MAAM,MAAM,oBAAoB,GAAG,UAAU,CAAC,OAAO,0BAA0B,CAAC,CAAC"}

package/dist/source-engine/overlay.js

@@ -0,0 +1,114 @@
+/** Tuple acceptance belongs to the overlay, separately from the engine's observation baseline. */
+import { changeBetween } from "../connectors.js";
+import { applyRecordOverlay } from "../record-overlay/apply.js";
+import { HOLD_STORE, RETRYABLE } from "../record-overlay/errors.js";
+import { planFindings } from "../record-overlay/findings.js";
+import { planRecordOverlay } from "../record-overlay/plan.js";
+export const MAX_SOURCE_OVERLAY_ENTRIES = 10_000;
+const object = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const key = (e) => JSON.stringify([e.feed, e.resource, e.external_id, e.target]);
+/** Validate before admitting private persisted acceptance; never silently reset malformed state. */
+export function isSourceOverlaySnapshot(value) {
+    if (!object(value) || value.v !== 1 || !Array.isArray(value.entries) || value.entries.length > MAX_SOURCE_OVERLAY_ENTRIES)
+        return false;
+    const keys = new Set();
+    return value.entries.every((entry) => {
+        if (!object(entry) || ![entry.feed, entry.resource, entry.external_id, entry.target].every(v => typeof v === "string" && v.length > 0) || !object(entry.after))
+            return false;
+        const k = key(entry);
+        if (keys.has(k))
+            return false;
+        keys.add(k);
+        return true;
+    });
+}
+/**
+ * One adapter per run with one fresh index shared by planning and application. Its staged
+ * snapshot must be co-published with the supplying observation, then consumed. Failure discards
+ * the stage; the caller must stop the run. This object owns no durable state or cursor.
+ */
+export function createSourceOverlayAdapter(options) {
+    const { content, policy, actor, overlays } = options;
+    const ops = options.ops ?? content;
+    if (options.accepted !== undefined && !isSourceOverlaySnapshot(options.accepted))
+        throw new Error("invalid source overlay snapshot");
+    let committed = new Map();
+    for (const entry of options.accepted?.entries ?? []) {
+        if (entry.feed === policy.feed && entry.resource === policy.provider
+            && overlays.lookup(entry.resource, entry.external_id, { type: policy.target_kind }).some(h => h.id === entry.target)) {
+            committed.set(key(entry), structuredClone(entry));
+        }
+    }
+    let staged = null;
+    const snapshotOf = (entries) => ({ v: 1, entries: structuredClone([...entries.values()].sort((a, b) => key(a).localeCompare(key(b)))) });
+    const context = { content, ops, policy, actor, overlays, hooks: options.hooks, signals: options.signals };
+    async function apply(changes, observedAt, page) {
+        if (staged !== null)
+            throw new Error("source overlay acceptance awaits publication");
+        const candidates = [];
+        const adjusted = changes.map(change => {
+            if (change.after === null || change.change_kind === "disappeared")
+                return change;
+            const matches = overlays.lookup(policy.provider, change.external_id, { type: policy.target_kind });
+            if (matches.length !== 1)
+                return change;
+            const entry = { feed: policy.feed, resource: policy.provider, external_id: change.external_id, target: matches[0].id, after: change.after };
+            const previous = committed.get(key(entry))?.after ?? {};
+            const diff = changeBetween(previous, { kind: "mapped", external_id: change.external_id, fields: change.after, unobserved: [], cleared: Object.keys(previous).filter(f => !Object.hasOwn(change.after, f)), diagnostics: [] }, { external_id: change.external_id, change_kind: "changed" });
+            candidates.push({ ...entry, after: diff.after });
+            return { ...change, ...diff };
+        });
+        if (committed.size + candidates.filter(e => !committed.has(key(e))).length > MAX_SOURCE_OVERLAY_ENTRIES)
+            throw new Error("source overlay acceptance limit exceeded");
+        const plan = await planRecordOverlay({ content, ops, policy, changes: adjusted, observedAt, overlays,
+            sameBundle: options.sameBundle ?? ops === content, hooks: options.hooks, signals: options.signals,
+            ...(page ? { records: { ...page.records }, observation: { baseline: page.baseline, replay: page.replay } } : {}) });
+        const receipt = await applyRecordOverlay(plan, context);
+        const retry = new Set();
+        const hold = new Set();
+        const refused = [...receipt.refusals, ...receipt.results.filter(r => r.outcome === "refused" && r.code !== undefined)];
+        for (const row of refused) {
+            if (row.code && RETRYABLE.has(row.code))
+                retry.add(row.external_id);
+            else if (row.code && HOLD_STORE.has(row.code))
+                hold.add(row.external_id);
+        }
+        staged = new Map(committed);
+        for (const candidate of candidates) {
+            const id = candidate.external_id;
+            const failed = receipt.results.some(r => r.external_id === id && r.outcome === "refused")
+                || receipt.refusals.some(r => r.external_id === id && r.code !== "OVERLAY_DOC_CONFLICT");
+            if (!failed)
+                staged.set(key(candidate), structuredClone(candidate));
+        }
+        return { receipt, changes: adjusted, retry: [...retry], hold: [...hold] };
+    }
+    return {
+        snapshot: () => snapshotOf(committed),
+        stagedSnapshot: () => staged === null ? null : snapshotOf(staged),
+        consume() { if (staged !== null)
+            committed = staged; staged = null; },
+        discard() { staged = null; },
+        commit: (page) => apply(page.changes, page.observed_at, page),
+        async reconcile(state, observedAt) {
+            const changes = [];
+            for (const [id, entry] of Object.entries(state.records)) {
+                if (entry.gone || Object.hasOwn(state.pending ?? {}, id))
+                    continue;
+                const matches = overlays.lookup(policy.provider, id, { type: policy.target_kind });
+                if (matches.length === 0)
+                    continue;
+                changes.push({ external_id: id, change_kind: "changed", before: null, after: entry.after, changed_fields: Object.keys(entry.after), content_digest: entry.digest });
+            }
+            return apply(changes, observedAt);
+        },
+        async applyFindings(findings, observedAt) {
+            if (staged !== null)
+                throw new Error("source overlay acceptance awaits publication");
+            const steps = await planFindings({ ops, provider: policy.provider, feed: policy.feed,
+                slug: options.slug ?? `${policy.feed.split("/").pop()}-source`, findings, observedAt, signals: options.signals });
+            return applyRecordOverlay({ feed: policy.feed, provider: policy.provider, observed_at: observedAt, steps, refusals: [] }, context);
+        },
+    };
+}
+//# sourceMappingURL=overlay.js.map

package/dist/source-engine/overlay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlay.js","sourceRoot":"","sources":["../../src/source-engine/overlay.ts"],"names":[],"mappings":"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"}