@superbee/core 0.2.0-pre.30 → 0.2.0-pre.32

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

@@ -0,0 +1,39 @@
+/** Caller-associated applicability of original input bytes; independent of document freshness. */
+export interface SnapshotEvidenceIdentity {
+    id: string;
+    sha256: string;
+}
+export interface SnapshotEvidence {
+    v: 1;
+    association: "caller_asserted";
+    inputs: SnapshotEvidenceIdentity[];
+    settings_digest?: string;
+    required_identities?: SnapshotEvidenceIdentity[];
+}
+export interface SnapshotEvidenceObservation {
+    inputs: Readonly<Record<string, string | null | undefined>>;
+    required_identities?: Readonly<Record<string, string | null | undefined>>;
+    settings_digest?: string | null;
+}
+export interface SnapshotFreshnessRow {
+    dimension: "input" | "required_identity" | "settings";
+    id: string;
+    status: "equal" | "mismatch" | "unknown";
+}
+export interface SnapshotFreshness {
+    status: "current" | "stale" | "unverifiable";
+    association: "caller_asserted" | null;
+    basis: "declared_original_inputs";
+    reason: "all_required_equal" | "known_mismatch" | "missing_dimension" | "no_input_basis";
+    rows: SnapshotFreshnessRow[];
+}
+export declare const SNAPSHOT_SHA256: RegExp;
+export declare class SnapshotEvidenceRefusal extends Error {
+    readonly code = "SNAPSHOT_EVIDENCE_INVALID";
+    constructor();
+}
+/** Closed, bounded portable evidence. Logical IDs select no file or executable. */
+export declare function parseSnapshotEvidence(value: unknown): SnapshotEvidence;
+/** Known mismatches take precedence over unknown dimensions, including an empty input basis. */
+export declare function assessSnapshotFreshness(expected: SnapshotEvidence | undefined, observed: SnapshotEvidenceObservation): SnapshotFreshness;
+//# sourceMappingURL=evidence.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"evidence.d.ts","sourceRoot":"","sources":["../../src/source-engine/evidence.ts"],"names":[],"mappings":"AAAA,kGAAkG;AAClG,MAAM,WAAW,wBAAwB;IAAG,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE;AACxE,MAAM,WAAW,gBAAgB;IAC/B,CAAC,EAAE,CAAC,CAAC;IACL,WAAW,EAAE,iBAAiB,CAAC;IAC/B,MAAM,EAAE,wBAAwB,EAAE,CAAC;IACnC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,mBAAmB,CAAC,EAAE,wBAAwB,EAAE,CAAC;CAClD;AACD,MAAM,WAAW,2BAA2B;IAC1C,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC,CAAC;IAC5D,mBAAmB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC,CAAC;IAC1E,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AACD,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,OAAO,GAAG,mBAAmB,GAAG,UAAU,CAAC;IACtD,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,OAAO,GAAG,UAAU,GAAG,SAAS,CAAC;CAC1C;AACD,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,SAAS,GAAG,OAAO,GAAG,cAAc,CAAC;IAC7C,WAAW,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACtC,KAAK,EAAE,0BAA0B,CAAC;IAClC,MAAM,EAAE,oBAAoB,GAAG,gBAAgB,GAAG,mBAAmB,GAAG,gBAAgB,CAAC;IACzF,IAAI,EAAE,oBAAoB,EAAE,CAAC;CAC9B;AACD,eAAO,MAAM,eAAe,QAA0B,CAAC;AAKvD,qBAAa,uBAAwB,SAAQ,KAAK;IAChD,QAAQ,CAAC,IAAI,+BAA+B;;CAE7C;AACD,mFAAmF;AACnF,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,CAmBtE;AAED,gGAAgG;AAChG,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,SAAS,EAAE,QAAQ,EAAE,2BAA2B,GAAG,iBAAiB,CAgBxI"}

package/dist/source-engine/evidence.js

@@ -0,0 +1,54 @@
+export const SNAPSHOT_SHA256 = /^sha256:[0-9a-f]{64}$/;
+const LABEL = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+const object = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const closed = (v, keys) => Object.keys(v).every(k => keys.includes(k));
+export class SnapshotEvidenceRefusal extends Error {
+    code = "SNAPSHOT_EVIDENCE_INVALID";
+    constructor() { super("snapshot evidence is not a closed v1 caller-associated descriptor"); this.name = "SnapshotEvidenceRefusal"; }
+}
+/** Closed, bounded portable evidence. Logical IDs select no file or executable. */
+export function parseSnapshotEvidence(value) {
+    const refuse = () => { throw new SnapshotEvidenceRefusal(); };
+    if (!object(value) || !closed(value, ["v", "association", "inputs", "settings_digest", "required_identities"])
+        || value.v !== 1 || value.association !== "caller_asserted")
+        return refuse();
+    const identities = (raw) => {
+        if (!Array.isArray(raw) || raw.length > 10_000)
+            return refuse();
+        const seen = new Set();
+        return raw.map(row => {
+            if (!object(row) || !closed(row, ["id", "sha256"]) || typeof row.id !== "string" || !LABEL.test(row.id)
+                || typeof row.sha256 !== "string" || !SNAPSHOT_SHA256.test(row.sha256) || seen.has(row.id))
+                return refuse();
+            seen.add(row.id);
+            return { id: row.id, sha256: row.sha256 };
+        });
+    };
+    const inputs = identities(value.inputs);
+    if (value.settings_digest !== undefined && (typeof value.settings_digest !== "string" || !SNAPSHOT_SHA256.test(value.settings_digest)))
+        return refuse();
+    return { v: 1, association: "caller_asserted", inputs,
+        ...(value.settings_digest !== undefined ? { settings_digest: value.settings_digest } : {}),
+        ...(value.required_identities !== undefined ? { required_identities: identities(value.required_identities) } : {}) };
+}
+/** Known mismatches take precedence over unknown dimensions, including an empty input basis. */
+export function assessSnapshotFreshness(expected, observed) {
+    const evidence = expected === undefined ? undefined : parseSnapshotEvidence(expected);
+    const rows = [];
+    const row = (dimension, id, wanted, actual) => {
+        rows.push({ dimension, id, status: typeof actual !== "string" || !SNAPSHOT_SHA256.test(actual) ? "unknown" : actual === wanted ? "equal" : "mismatch" });
+    };
+    for (const input of evidence?.inputs ?? [])
+        row("input", input.id, input.sha256, Object.hasOwn(observed.inputs, input.id) ? observed.inputs[input.id] : undefined);
+    for (const identity of evidence?.required_identities ?? [])
+        row("required_identity", identity.id, identity.sha256, observed.required_identities && Object.hasOwn(observed.required_identities, identity.id) ? observed.required_identities[identity.id] : undefined);
+    if (evidence?.settings_digest !== undefined)
+        row("settings", "original_settings", evidence.settings_digest, observed.settings_digest);
+    const mismatch = rows.some(r => r.status === "mismatch");
+    const basis = (evidence?.inputs.length ?? 0) > 0;
+    const unknown = rows.some(r => r.status === "unknown");
+    return { status: mismatch ? "stale" : !basis || unknown ? "unverifiable" : "current",
+        association: evidence?.association ?? null, basis: "declared_original_inputs",
+        reason: mismatch ? "known_mismatch" : !basis ? "no_input_basis" : unknown ? "missing_dimension" : "all_required_equal", rows };
+}
+//# sourceMappingURL=evidence.js.map

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

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

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

@@ -11,6 +11,9 @@
  * the cursor rule (a cursor is stored only after its page commits), completeness, and the diff into
  * record-overlay changes, with disappearance only from a complete observation.
  *
+ * Finite local inputs use bindSnapshotSource/decodeSnapshot/admitSnapshot/observeSnapshot;
+ * admission precedes reconciliation and the same internal driver owns state transitions.
+ *
  * Storage-neutral and Worker-free: no Node globals or builtins, and nothing here calls `fetch`.
  */
 export { canonicalRobotsPath, fetchIdentity, parseRobots, refusedAddress, robotsDecision, robotsRuleMatches, } from "./robots.js";
@@ -23,4 +26,8 @@ export type { MachineState, PendingChange, RecordEntry, SourceState } from "./ma
 export type { CommitResult, HttpMethod, NormalizedRecord, ObserveContext, ObservePage, ObserveSourceOptions, PageCommit, ProfileDiagnostic, ProfileRequest, ProfileResponse, ProfileTransport, RequestRules, SourceBudget, SourceOutcome, SourceProfile, SourceRequestRow, SourceRunReceipt, SpecResult, StatusRules, Transport, TransportRequest, TransportResult, } from "./types.js";
 export { createSourceOverlayAdapter, isSourceOverlaySnapshot, MAX_SOURCE_OVERLAY_ENTRIES } from "./overlay.js";
 export type { SourceOverlayAdapter, SourceOverlayEntry, SourceOverlayOptions, SourceOverlayResult, SourceOverlaySnapshot } from "./overlay.js";
+export { SNAPSHOT_MAX_BYTES, SNAPSHOT_MAX_RECORDS, SNAPSHOT_PROFILE, SNAPSHOT_REFUSAL_CODES, SnapshotRefusal, bindSnapshotSource, decodeSnapshot, admitSnapshot, observeSnapshot } from "./snapshot.js";
+export type { BoundSnapshotSource, SnapshotDocument, DecodedSnapshot, SnapshotRefusalCode, SnapshotCapacityInput, SnapshotCapacityFacts, SnapshotAdmissionOptions, SnapshotAdmission, ObserveSnapshotOptions, SnapshotRunReceipt } from "./snapshot.js";
+export { SnapshotEvidenceRefusal, parseSnapshotEvidence, assessSnapshotFreshness } from "./evidence.js";
+export type { SnapshotEvidenceIdentity, SnapshotEvidence, SnapshotEvidenceObservation, SnapshotFreshnessRow, SnapshotFreshness } from "./evidence.js";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/source-engine/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EACL,mBAAmB,EACnB,aAAa,EACb,WAAW,EACX,cAAc,EACd,cAAc,EACd,iBAAiB,GAClB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AACxF,YAAY,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,yBAAyB,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AACnI,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAC7F,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAChG,YAAY,EACV,YAAY,EACZ,UAAU,EACV,gBAAgB,EAChB,cAAc,EACd,WAAW,EACX,oBAAoB,EACpB,UAAU,EACV,iBAAiB,EACjB,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,gBAAgB,EAChB,UAAU,EACV,WAAW,EACX,SAAS,EACT,gBAAgB,EAChB,eAAe,GAChB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,0BAA0B,EAAE,uBAAuB,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC;AAC/G,YAAY,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/source-engine/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EACL,mBAAmB,EACnB,aAAa,EACb,WAAW,EACX,cAAc,EACd,cAAc,EACd,iBAAiB,GAClB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AACxF,YAAY,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,yBAAyB,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AACnI,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAC7F,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAChG,YAAY,EACV,YAAY,EACZ,UAAU,EACV,gBAAgB,EAChB,cAAc,EACd,WAAW,EACX,oBAAoB,EACpB,UAAU,EACV,iBAAiB,EACjB,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,gBAAgB,EAChB,UAAU,EACV,WAAW,EACX,SAAS,EACT,gBAAgB,EAChB,eAAe,GAChB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,0BAA0B,EAAE,uBAAuB,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC;AAC/G,YAAY,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAC/I,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,eAAe,EAC1G,kBAAkB,EAAE,cAAc,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAC5F,YAAY,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,eAAe,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,qBAAqB,EACrI,wBAAwB,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACjH,OAAO,EAAE,uBAAuB,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AACxG,YAAY,EAAE,wBAAwB,EAAE,gBAAgB,EAAE,2BAA2B,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC"}

package/dist/source-engine/index.js

@@ -11,6 +11,9 @@
  * the cursor rule (a cursor is stored only after its page commits), completeness, and the diff into
  * record-overlay changes, with disappearance only from a complete observation.
  *
+ * Finite local inputs use bindSnapshotSource/decodeSnapshot/admitSnapshot/observeSnapshot;
+ * admission precedes reconciliation and the same internal driver owns state transitions.
+ *
  * Storage-neutral and Worker-free: no Node globals or builtins, and nothing here calls `fetch`.
  */
 export { canonicalRobotsPath, fetchIdentity, parseRobots, refusedAddress, robotsDecision, robotsRuleMatches, } from "./robots.js";
@@ -18,4 +21,6 @@ export { DEFAULT_SOURCE_BUDGET, DEFAULT_STATUS_RULES, sourceHostSet } from "./gu
 export { DEFAULT_MISSING_THRESHOLD, MAX_CURSOR_CHARS, MAX_REPLAY_FAILURES, observeSource, unsupportedContent } from "./observe.js";
 export { isSourceState, MachineStateConflict, MemoryMachineState } from "./machine-state.js";
 export { createSourceOverlayAdapter, isSourceOverlaySnapshot, MAX_SOURCE_OVERLAY_ENTRIES } from "./overlay.js";
+export { SNAPSHOT_MAX_BYTES, SNAPSHOT_MAX_RECORDS, SNAPSHOT_PROFILE, SNAPSHOT_REFUSAL_CODES, SnapshotRefusal, bindSnapshotSource, decodeSnapshot, admitSnapshot, observeSnapshot } from "./snapshot.js";
+export { SnapshotEvidenceRefusal, parseSnapshotEvidence, assessSnapshotFreshness } from "./evidence.js";
 //# sourceMappingURL=index.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/source-engine/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EACL,mBAAmB,EACnB,aAAa,EACb,WAAW,EACX,cAAc,EACd,cAAc,EACd,iBAAiB,GAClB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAExF,OAAO,EAAE,yBAAyB,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AACnI,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AA0B7F,OAAO,EAAE,0BAA0B,EAAE,uBAAuB,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/source-engine/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EACL,mBAAmB,EACnB,aAAa,EACb,WAAW,EACX,cAAc,EACd,cAAc,EACd,iBAAiB,GAClB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAExF,OAAO,EAAE,yBAAyB,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AACnI,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AA0B7F,OAAO,EAAE,0BAA0B,EAAE,uBAAuB,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC;AAE/G,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,eAAe,EAC1G,kBAAkB,EAAE,cAAc,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAG5F,OAAO,EAAE,uBAAuB,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC"}

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

@@ -1,13 +1,5 @@
 import type { ObserveSourceOptions, SourceRunReceipt } from "./types.js";
-/** Complete observations without a record before it is `disappeared`, when the feed names none. */
-export declare const DEFAULT_MISSING_THRESHOLD = 2;
-/** The largest stored cursor, as canonical JSON characters. */
-export declare const MAX_CURSOR_CHARS = 8192;
-/**
- * Replays of a pending change whose commit threw, after which the change is dropped with a finding:
- * the record is planned again when it is next observed.
- */
-export declare const MAX_REPLAY_FAILURES = 5;
+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;
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"observe.d.ts","sourceRoot":"","sources":["../../src/source-engine/observe.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAEV,oBAAoB,EAIpB,gBAAgB,EAEjB,MAAM,YAAY,CAAC;AAEpB,mGAAmG;AACnG,eAAO,MAAM,yBAAyB,IAAI,CAAC;AAC3C,+DAA+D;AAC/D,eAAO,MAAM,gBAAgB,OAAO,CAAC;AACrC;;;GAGG;AACH,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAKrC,kGAAkG;AAClG,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,KAAK,CAExD;AAiLD;;;GAGG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,oBAAoB,CAAC,IAAI,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA2VxH"}
+{"version":3,"file":"observe.d.ts","sourceRoot":"","sources":["../../src/source-engine/observe.ts"],"names":[],"mappings":"AAeA,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,CAsJxH"}

package/dist/source-engine/observe.js

@@ -9,45 +9,18 @@ import { validateConnectorRequest, declarationRequestRules, placeholders, provid
  * 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 { changeBetween, findingsFor, mapRecord } from "../connectors.js";
-import { overlayCanonicalJson } from "../record-overlay/canonical.js";
-import { DEFAULT_SOURCE_BUDGET, DEFAULT_STATUS_RULES, guardTransport, raceAbort, sourceHostSet, SourceStop } from "./guard.js";
+import { findingsFor } from "../connectors.js";
+import { DEFAULT_SOURCE_BUDGET, DEFAULT_STATUS_RULES, guardTransport, raceAbort, sourceHostSet } from "./guard.js";
 import { isSourceState } from "./machine-state.js";
-/** Complete observations without a record before it is `disappeared`, when the feed names none. */
-export const DEFAULT_MISSING_THRESHOLD = 2;
-/** The largest stored cursor, as canonical JSON characters. */
-export const MAX_CURSOR_CHARS = 8192;
-/**
- * Replays of a pending change whose commit threw, after which the change is dropped with a finding:
- * the record is planned again when it is next observed.
- */
-export const MAX_REPLAY_FAILURES = 5;
+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-]*$/;
-const UNSUPPORTED_CONTENT = "SOURCE_UNSUPPORTED_CONTENT";
 /** 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);
-/** JSON data only: finite numbers, plain objects and arrays, no undefined members. */
-function isJsonData(value, depth = 0) {
-    if (depth > 32)
-        return false;
-    if (value === null || typeof value === "string" || typeof value === "boolean")
-        return true;
-    if (typeof value === "number")
-        return Number.isFinite(value);
-    if (Array.isArray(value))
-        return value.every((item) => isJsonData(item, depth + 1));
-    if (!record(value))
-        return false;
-    // A plain object from any realm: its prototype is null or a prototype that itself has none.
-    const proto = Object.getPrototypeOf(value);
-    if (proto !== null && Object.getPrototypeOf(proto) !== null)
-        return false;
-    return Object.values(value).every((item) => item !== undefined && isJsonData(item, depth + 1));
-}
+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.
@@ -73,96 +46,6 @@ function profileProblem(profile) {
         return "missing a method";
     return undefined;
 }
-/** The page as the engine accepts it, or why not. */
-function pageProblem(page) {
-    if (!record(page))
-        return "page_invalid";
-    if (!Array.isArray(page.records) || typeof page.more !== "boolean" || typeof page.complete !== "boolean")
-        return "page_invalid";
-    if (page.diagnostics !== undefined && !(Array.isArray(page.diagnostics) && page.diagnostics.every((d) => record(d) && typeof d.code === "string" && typeof d.message === "string")))
-        return "page_invalid";
-    if (page.validators !== undefined && !(record(page.validators) && Object.values(page.validators).every((v) => typeof v === "string")))
-        return "page_invalid";
-    const cursor = page.nextCursor === undefined ? null : page.nextCursor;
-    if (!isJsonData(cursor) || (overlayCanonicalJson(cursor) ?? "").length > MAX_CURSOR_CHARS)
-        return "cursor_invalid";
-    return undefined;
-}
-/**
- * Diff one page against the stored records. Within a page the last occurrence of an id wins and is
- * diffed against the stored entry, so every change's `before` is what the overlay last accepted.
- */
-function diffPage(state, page, bound, observedAt) {
-    const diagnostics = [];
-    const profileDiagnostics = [...(page.diagnostics ?? [])].map((d) => ({ ...d }));
-    const last = new Map();
-    const seen = new Set();
-    let notObjects = 0;
-    let duplicates = 0;
-    for (const raw of page.records) {
-        if (!record(raw)) {
-            notObjects += 1;
-            continue;
-        }
-        const mapped = mapRecord(bound.source, raw, bound.kind);
-        diagnostics.push(...mapped.diagnostics);
-        const id = mapped.external_id;
-        if (id === null)
-            continue;
-        seen.add(id);
-        if (last.has(id))
-            duplicates += 1;
-        last.set(id, mapped);
-    }
-    if (notObjects)
-        profileDiagnostics.push({ code: "RECORD_NOT_OBJECT", message: "records that are not JSON objects were skipped", count: notObjects });
-    if (duplicates)
-        profileDiagnostics.push({ code: "RECORD_DUPLICATE", message: "a page listed the same record more than once; the last one was used", count: duplicates });
-    const changes = [];
-    const entries = new Map();
-    for (const [id, mapped] of last) {
-        const stored = Object.hasOwn(state.records, id) ? state.records[id] : undefined;
-        if (mapped.kind === "refused") {
-            // Refused but present: still observed, so never missing; its accepted values stay.
-            if (stored)
-                entries.set(id, { ...stored, missing: 0, seen_at: observedAt, first_missing_at: undefined });
-            continue;
-        }
-        const previous = stored && !stored.gone ? stored.after : null;
-        const change = changeBetween(previous, mapped, { external_id: id, change_kind: previous === null ? "new" : "changed" });
-        entries.set(id, { after: change.after, digest: change.content_digest, missing: 0, seen_at: observedAt });
-        if (previous === null || change.changed_fields.length > 0)
-            changes.push(change);
-    }
-    return { changes, entries, seen, diagnostics, profileDiagnostics };
-}
-/** Disappearances at the end of a complete observation: every present record the pass did not list. */
-function missingAfterComplete(records, seen, threshold, observedAt) {
-    const changes = [];
-    const entries = new Map();
-    for (const [id, entry] of Object.entries(records)) {
-        if (entry.gone || seen.has(id))
-            continue;
-        const missing = entry.missing + 1;
-        const firstMissingAt = entry.first_missing_at ?? observedAt;
-        if (missing >= threshold) {
-            entries.set(id, { ...entry, missing, first_missing_at: firstMissingAt, gone: true });
-            changes.push({
-                external_id: id, change_kind: "disappeared", changed_fields: [], before: { ...entry.after }, after: null,
-                content_digest: entry.digest, missing_count: missing, first_missing_at: firstMissingAt,
-            });
-        }
-        else {
-            entries.set(id, { ...entry, missing, first_missing_at: firstMissingAt });
-        }
-    }
-    return { changes, entries };
-}
-/** Drop `undefined` members so the stored state is plain JSON. */
-function entryJson(entry) {
-    const { first_missing_at: firstMissingAt, gone, ...rest } = entry;
-    return { ...rest, ...(firstMissingAt !== undefined ? { first_missing_at: firstMissingAt } : {}), ...(gone ? { gone } : {}) };
-}
 function emptyState(profile) {
     return { v: 1, profile: { id: profile.id, version: profile.version }, cursor: null, open: false, records: {}, complete_observations: 0 };
 }
@@ -202,13 +85,6 @@ function findingUrl(url) {
         return undefined;
     }
 }
-/** The ids a commit did not write, read defensively. */
-function commitResult(result) {
-    const ids = (value) => (Array.isArray(value) ? value.filter((id) => typeof id === "string") : []);
-    const retry = new Set(record(result) ? ids(result.retry) : []);
-    const hold = new Set((record(result) ? ids(result.hold) : []).filter((id) => !retry.has(id)));
-    return { hold, retry };
-}
 /**
  * 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.
@@ -346,9 +222,6 @@ export async function observeSource(options) {
     // 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;
-    let cursor = mode === "complete" ? null : state.cursor;
-    const threshold = bound.policy.missing_threshold ?? DEFAULT_MISSING_THRESHOLD;
-    const sourceComplete = bound.source.completeness === "complete";
     // 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;
@@ -366,249 +239,16 @@ export async function observeSource(options) {
         signal, requestTimeoutMs: budget.requestTimeoutMs, authority: declarationRules, graphqlPaths: providerRequestRules(connector.auth)?.read_posts.filter(p => p.graphql).map(p => p.path),
     });
     receipt.requests = guard.requests;
-    /** Store `next` after a commit; false when the store refused it and the run has stopped. */
-    const store = async (next) => {
-        try {
-            version = await options.state.write(key, next, version);
-            state = next;
-            receipt.pending = Object.keys(next.pending ?? {}).length;
-            return true;
-        }
-        catch (error) {
-            const conflict = record(error) && error.code === "MACHINE_STATE_CONFLICT";
-            stop = { outcome: "failed", reason: conflict ? "state_conflict" : "state_unwritable", retry: true };
-            return false;
-        }
-    };
     try {
-        // Changes an earlier commit asked to retry are planned again before anything is fetched. A
-        // record that has since disappeared has nothing left to write, unless the held change is the
-        // record coming back.
-        const pendingIds = signal.aborted ? [] : Object.keys(state.pending ?? {}).sort();
-        if (pendingIds.length) {
-            const pending = state.pending;
-            const live = pendingIds.filter((id) => !state.records[id]?.gone || pending[id].change.change_kind === "new");
-            const changes = live.map((id) => pending[id].change);
-            const records = {};
-            for (const change of changes)
-                records[change.external_id] = { fields: { ...(change.after ?? change.before ?? {}) } };
-            let result;
-            let failure;
-            if (live.length) {
-                try {
-                    result = commitResult(await options.commit({
-                        feed: key, provider: bound.policy.provider, observed_at: observedAt, page: 0, replay: true, changes, records, baseline: false, complete: false,
-                    }));
-                }
-                catch (error) {
-                    failure = errorText(error);
-                }
-            }
-            const nextRecords = { ...state.records };
-            const nextPending = {};
-            const dropped = [];
-            for (const id of live) {
-                const entry = pending[id];
-                if (failure !== undefined) {
-                    // A replay the commit cannot take stays pending, so a later sighting can still supersede
-                    // it, until it has failed too often.
-                    const failures = (entry.replay_failures ?? 0) + 1;
-                    if (failures >= MAX_REPLAY_FAILURES)
-                        dropped.push(id);
-                    else
-                        nextPending[id] = { ...entry, replay_failures: failures };
-                }
-                else if (result.retry.has(id)) {
-                    nextPending[id] = entry;
-                }
-                else if (!result.hold.has(id)) {
-                    // The record's absence since the hold is newer than the change, so its count stays; a
-                    // record that comes back starts afresh.
-                    const current = state.records[id];
-                    nextRecords[id] = entryJson(current?.gone ? entry.entry : { ...entry.entry, missing: current?.missing ?? 0, first_missing_at: current?.first_missing_at });
-                }
-            }
-            receipt.held += live.filter((id) => failure !== undefined || result.retry.has(id) || result.hold.has(id)).length;
-            if (failure !== undefined) {
-                extraFindings.push({
-                    key: `source:${bound.source.name}:replay_failed`,
-                    title: clip(`Source ${bound.source.name}: a held change could not be planned again`, 140),
-                    summary: clip(`Replaying ${live.length} pending change${live.length === 1 ? "" : "s"} failed (${failure}); they stay pending and the run went on to read the provider.`, 600),
-                    priority: "normal",
-                    facts: { outcome: "failed", reason: "replay_failed" },
-                });
-            }
-            if (dropped.length) {
-                extraFindings.push({
-                    key: `source:${bound.source.name}:replay_dropped`,
-                    title: clip(`Source ${bound.source.name}: held changes dropped after ${MAX_REPLAY_FAILURES} failed replays`, 140),
-                    summary: clip(`Dropped ${dropped.length} pending change${dropped.length === 1 ? "" : "s"} (${dropped.slice(0, 3).map((id) => clip(id, 60)).join(", ")}${dropped.length > 3 ? ", …" : ""}); each record is planned again when it is next observed.`, 600),
-                    priority: "normal",
-                    facts: { outcome: "failed", reason: "replay_dropped", count: dropped.length },
-                });
-            }
-            const next = { ...state, records: nextRecords };
-            if (Object.keys(nextPending).length)
-                next.pending = nextPending;
-            else
-                delete next.pending;
-            if (!(await store(next)))
-                return finish();
-        }
-        const seen = new Set();
-        /** The cursors this run has asked for; a page handing one back again has looped. */
-        const asked = new Set();
-        const lastRequestUrl = () => guard.requests.at(-1)?.url;
-        for (let first = true;; first = false) {
-            if (signal.aborted) {
-                stop = { outcome: "deferred", reason: "deadline", retry: true };
-                break;
-            }
-            // A resumed pass may restart from its first page, so the cursor it resumes from is not a loop.
-            if (cursor !== null && !(first && resumed))
-                asked.add(overlayCanonicalJson(cursor));
-            let raw;
-            try {
-                // The deadline bounds profile code too: a page still pending when it passes is discarded.
-                raw = await raceAbort(profile.observe({
-                    spec, bound: structuredClone(bound), cursor, resumed: first && resumed, mode, transport: guard.transport,
-                    budget: { requests: guard.remaining(), maxBytes: budget.maxBytes }, now: now(),
-                    validators: mode === "complete" ? null : state.validators ?? null,
-                }), signal);
-            }
-            catch (error) {
-                stop = guard.stopped() ?? (error instanceof SourceStop ? error.stop : undefined);
-                if (!stop && signal.aborted)
-                    stop = { outcome: "deferred", reason: "deadline", retry: true };
-                if (!stop) {
-                    const code = record(error) ? error.code : undefined;
-                    stop = code === UNSUPPORTED_CONTENT
-                        ? { outcome: "unsupported_content", retry: false, detail: String(error.detail ?? "") }
-                        : { outcome: "failed", reason: "profile_error", retry: false, detail: errorText(error) };
-                }
-                stopUrl = lastRequestUrl();
-                break;
-            }
-            // A stop the profile caught and swallowed still ends the run, and its page is discarded.
-            const guardStop = guard.stopped();
-            if (guardStop) {
-                stop = guardStop;
-                stopUrl = lastRequestUrl();
-                break;
-            }
-            let page;
-            try {
-                const invalid = pageProblem(raw);
-                if (invalid) {
-                    stop = { outcome: "failed", reason: invalid, retry: false };
-                    break;
-                }
-                // One read of the profile's page, as JSON data, so no getter or later mutation reaches the diff.
-                page = JSON.parse(JSON.stringify(raw));
-            }
-            catch (error) {
-                stop = { outcome: "failed", reason: "page_invalid", retry: false, detail: errorText(error) };
-                break;
-            }
-            const nextCursor = page.nextCursor ?? null;
-            // A page that promises more but hands back no cursor, or one this run already asked for, would
-            // read the same pages until the budget runs out.
-            if (page.more && (nextCursor === null || asked.has(overlayCanonicalJson(nextCursor)))) {
-                stop = { outcome: "failed", reason: "cursor_stuck", retry: false };
-                break;
-            }
-            const diff = diffPage(state, page, bound, observedAt);
-            for (const id of diff.seen)
-                seen.add(id);
-            const ended = !page.more;
-            const complete = ended && mode === "complete" && page.complete && sourceComplete;
-            const merged = { ...state.records };
-            for (const [id, entry] of diff.entries)
-                merged[id] = entry;
-            const missing = complete ? missingAfterComplete(merged, seen, threshold, observedAt) : { changes: [], entries: new Map() };
-            const changes = [...diff.changes, ...missing.changes];
-            const byId = new Map(changes.map((change) => [change.external_id, change]));
-            // A newer observation of a record, its listing or its absence from a complete pass, supersedes
-            // its pending change, whether or not the record was ever stored. Those entries are dropped and
-            // stored before the commit, so a crash after the commit never replays a change older than what
-            // the commit wrote.
-            const unlisted = complete ? Object.keys(state.pending ?? {}).filter((id) => !seen.has(id)) : [];
-            const superseded = [...new Set([...diff.seen, ...missing.entries.keys(), ...unlisted])].filter((id) => state.pending !== undefined && Object.hasOwn(state.pending, id));
-            if (superseded.length) {
-                const remaining = { ...state.pending };
-                for (const id of superseded)
-                    delete remaining[id];
-                const pre = { ...state };
-                if (Object.keys(remaining).length)
-                    pre.pending = remaining;
-                else
-                    delete pre.pending;
-                if (!(await store(pre)))
-                    break;
-            }
-            const records = {};
-            for (const change of changes)
-                records[change.external_id] = { fields: { ...(change.after ?? change.before ?? {}) } };
-            let result;
-            try {
-                result = commitResult(await options.commit({
-                    feed: key, provider: bound.policy.provider, observed_at: observedAt, page: receipt.pages + 1, replay: false,
-                    changes, records, baseline, complete,
-                }));
-            }
-            catch (error) {
-                stop = { outcome: "failed", reason: "commit_failed", retry: true, detail: errorText(error) };
-                break;
-            }
-            const notWritten = (id) => byId.has(id) && (result.hold.has(id) || result.retry.has(id));
-            // The page committed: now, and only now, its records and cursor are stored.
-            const nextRecords = { ...state.records };
-            const nextPending = { ...state.pending };
-            for (const [id, entry] of [...diff.entries, ...missing.entries]) {
-                if (byId.has(id) && result.retry.has(id))
-                    nextPending[id] = { change: byId.get(id), entry: entryJson(entry), held_at: observedAt };
-                else if (!notWritten(id))
-                    nextRecords[id] = entryJson(entry);
-            }
-            const next = {
-                ...state,
-                cursor: nextCursor,
-                open: page.more,
-                records: nextRecords,
-                complete_observations: state.complete_observations + (complete ? 1 : 0),
-                ...(complete ? { last_complete_at: observedAt } : {}),
-                ...(page.validators ? { validators: { ...page.validators } } : {}),
-            };
-            if (Object.keys(nextPending).length)
-                next.pending = nextPending;
-            else
-                delete next.pending;
-            if (!(await store(next)))
-                break;
-            receipt.pages += 1;
-            receipt.cursor = nextCursor;
-            receipt.diagnostics.push(...diff.diagnostics);
-            receipt.profile_diagnostics.push(...diff.profileDiagnostics);
-            for (const change of changes) {
-                if (notWritten(change.external_id)) {
-                    receipt.held += 1;
-                    continue;
-                }
-                const kind = change.change_kind;
-                if (Object.hasOwn(receipt.changes, kind))
-                    receipt.changes[kind] += 1;
-            }
-            if (ended) {
-                receipt.pass.ended = true;
-                receipt.pass.complete = complete;
-                break;
-            }
-            if (receipt.pages >= budget.pages) {
-                stop = { outcome: "deferred", reason: "budget", retry: true };
-                break;
-            }
-            cursor = nextCursor;
-        }
+        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, commit: options.commit,
+        });
         return finish();
     }
     finally {