@superbee/core 0.2.0-pre.40 → 0.2.0-pre.42

package/dist/site-manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"site-manifest.d.ts","sourceRoot":"","sources":["../src/site-manifest.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,SAAS,SAAS,CAAC;AAChC,eAAO,MAAM,YAAY,WAAW,CAAC;AACrC,iFAAiF;AACjF,eAAO,MAAM,UAAU,QAAmC,CAAC;AAC3D,eAAO,MAAM,WAAW,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,MACwB,CAAC;AAC/E,eAAO,MAAM,kBAAkB,+HAAgI,CAAC;AAEhK,MAAM,MAAM,yBAAyB,GACjC;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC7E;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC;AACjE,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,YAAY,EAAE,yBAAyB,CAAC;IACjD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAChC,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACpD,QAAQ,CAAC,KAAK,CAAC,EAAE;QAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,CAAC;CACjF;AACD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAC;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AACD,MAAM,MAAM,uBAAuB,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAA;CAAE,GACxF;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,iBAAiB,EAAE,CAAA;CAAE,CAAC;AA8B1E;qGACqG;AACrG,wBAAgB,oBAAoB,CAAC,GAAG,EAAE;IAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;CAAE,GAAG,uBAAuB,CA6CnJ"}

package/dist/site-manifest.js

@@ -0,0 +1,113 @@
+/** Portable Site declaration grammar. Parsing grants no build, install or publication authority. */
+import { assertSafeBlobKey, assertSafeConceptId, nonCanonicalDocumentId } from "./paths.js";
+import { isJsonData } from "./json-data.js";
+import { isOkfStandardField } from "./okf-standard-fields.js";
+import { isManagedDocumentMetadataField } from "./managed-document-metadata.js";
+export const SITE_TYPE = "Site";
+export const SITES_PREFIX = "sites/";
+/** One site label leaves room for its workspace label in a combined DNS name. */
+export const SITE_LABEL = /^[a-z][a-z0-9-]{1,30}[a-z0-9]$/;
+export const isSiteLabel = (value) => typeof value === "string" && SITE_LABEL.test(value) && !value.includes("--");
+export const SITE_DOCUMENT_KEYS = ["type", "title", "description", "presentation", "landing", "views", "audience", "capabilities", "options", "brand"];
+const record = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const packageName = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
+const exactVersion = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$/;
+const encoder = new TextEncoder();
+function presentationReference(raw) {
+    if (typeof raw !== "string" || raw.length > 512)
+        return undefined;
+    if (raw.startsWith("repo:")) {
+        const repository = raw.slice(5);
+        return /^[A-Za-z0-9][A-Za-z0-9-]{0,38}\/[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/.test(repository) && !repository.endsWith(".git")
+            ? { kind: "repository", repository } : undefined;
+    }
+    const at = raw.lastIndexOf("@");
+    if (at < 1)
+        return undefined;
+    const name = raw.slice(0, at), version = raw.slice(at + 1), match = exactVersion.exec(version);
+    if (name.length > 214 || !packageName.test(name) || !match ||
+        !match.slice(1, 4).every(part => Number.isSafeInteger(Number(part))) ||
+        match[4]?.split(".").some(part => /^\d+$/.test(part) && (part.length > 1 && part.startsWith("0") || !Number.isSafeInteger(Number(part)))))
+        return undefined;
+    return { kind: "package", name, version };
+}
+const concept = (raw) => {
+    if (typeof raw !== "string")
+        return false;
+    try {
+        assertSafeConceptId(raw);
+        return nonCanonicalDocumentId(raw) === null;
+    }
+    catch {
+        return false;
+    }
+};
+const blob = (raw) => {
+    if (typeof raw !== "string")
+        return false;
+    try {
+        assertSafeBlobKey(raw);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/** Standard OKF and managed metadata survive on the document; only Site fields enter this value.
+ * Presentation owners validate option semantics. Builders separately admit trusted resolved code. */
+export function parseSiteManifestDoc(doc) {
+    const errors = [];
+    const fail = (path, message) => { errors.push({ code: "SITE_MANIFEST_INVALID", path, message }); };
+    const fm = record(doc?.frontmatter) ? doc.frontmatter : {};
+    const site = typeof doc?.id === "string" && doc.id.startsWith(SITES_PREFIX) ? doc.id.slice(SITES_PREFIX.length) : "";
+    if (!isSiteLabel(site))
+        fail("/id", "a Site lives at sites/<site>, using one site label");
+    if (fm.type !== SITE_TYPE)
+        fail("/type", "type must be Site");
+    if (Object.keys(fm).some(key => !SITE_DOCUMENT_KEYS.includes(key) && !isOkfStandardField(key) && !isManagedDocumentMetadataField(key)))
+        fail("", "unrecognized Site fields");
+    if (typeof fm.title !== "string" || fm.title.trim() === "" || encoder.encode(fm.title).byteLength > 512)
+        fail("/title", "title must be a nonempty string of at most 512 bytes");
+    if (fm.description !== undefined && (typeof fm.description !== "string" || encoder.encode(fm.description).byteLength > 8192))
+        fail("/description", "description must be a string of at most 8192 bytes");
+    const presentation = presentationReference(fm.presentation);
+    if (!presentation)
+        fail("/presentation", "presentation must name an exact npm version or repo:owner/name");
+    if (fm.audience !== "restricted")
+        fail("/audience", "only the restricted audience is supported");
+    const list = (raw, path, maximum, valid) => {
+        if (!Array.isArray(raw) || raw.length > maximum || !raw.every(valid) || new Set(raw).size !== raw.length) {
+            fail(path, "expected a bounded list of unique valid references");
+            return [];
+        }
+        return [...raw];
+    };
+    const views = list(fm.views, "/views", 64, concept);
+    const capability = (v) => typeof v === "string" && /^[a-z][a-z0-9-]{0,63}$/.test(v);
+    const capabilities = list(fm.capabilities ?? [], "/capabilities", 16, capability);
+    if (fm.landing !== undefined && !concept(fm.landing))
+        fail("/landing", "landing must be a canonical document or View id");
+    const options = fm.options ?? {};
+    if (!record(options) || !isJsonData(options) || encoder.encode(JSON.stringify(options)).byteLength > 16384)
+        fail("/options", "options must be JSON data of at most 16384 bytes");
+    let brand;
+    if (fm.brand !== undefined) {
+        if (!record(fm.brand) || Object.keys(fm.brand).some(key => key !== "logo" && key !== "fonts"))
+            fail("/brand", "brand may only name a logo and fonts");
+        else {
+            if (fm.brand.logo !== undefined && !blob(fm.brand.logo))
+                fail("/brand/logo", "logo must be a bundle blob reference");
+            const fonts = fm.brand.fonts === undefined ? undefined : list(fm.brand.fonts, "/brand/fonts", 16, blob);
+            brand = { ...(typeof fm.brand.logo === "string" ? { logo: fm.brand.logo } : {}), ...(fonts ? { fonts } : {}) };
+        }
+    }
+    if (errors.length)
+        return { ok: false, errors };
+    return { ok: true, manifest: {
+            id: doc.id, site, title: fm.title, presentation: presentation, audience: "restricted", views, capabilities,
+            options: JSON.parse(JSON.stringify(options)),
+            ...(fm.description === undefined ? {} : { description: fm.description }),
+            ...(fm.landing === undefined ? {} : { landing: fm.landing }), ...(brand ? { brand } : {}),
+        } };
+}
+//# sourceMappingURL=site-manifest.js.map

package/dist/site-manifest.js.map

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

package/dist/skip-reasons.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The skip reason a resilient scan gives a document the host refused to read, and the one test
+ * for it. Dependency-free so a browser bundle can tell a permission problem from a malformed
+ * document without loading the scan.
+ */
+/** The skip reason for a read refused with `code` (`EACCES` or `EPERM`); never the host path. */
+export declare function permissionDeniedReason(code: "EACCES" | "EPERM"): string;
+/** True when a scan skipped this document because the host refused to read it, not because it is malformed. */
+export declare function isPermissionDeniedSkip(skip: {
+    reason: string;
+}): boolean;
+//# sourceMappingURL=skip-reasons.d.ts.map

package/dist/skip-reasons.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skip-reasons.d.ts","sourceRoot":"","sources":["../src/skip-reasons.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,iGAAiG;AACjG,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,GAAG,MAAM,CAEvE;AAED,+GAA+G;AAC/G,wBAAgB,sBAAsB,CAAC,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAExE"}

package/dist/skip-reasons.js

@@ -0,0 +1,15 @@
+/**
+ * The skip reason a resilient scan gives a document the host refused to read, and the one test
+ * for it. Dependency-free so a browser bundle can tell a permission problem from a malformed
+ * document without loading the scan.
+ */
+const PERMISSION_DENIED_PREFIX = "permission denied (";
+/** The skip reason for a read refused with `code` (`EACCES` or `EPERM`); never the host path. */
+export function permissionDeniedReason(code) {
+    return `${PERMISSION_DENIED_PREFIX}${code})`;
+}
+/** True when a scan skipped this document because the host refused to read it, not because it is malformed. */
+export function isPermissionDeniedSkip(skip) {
+    return skip.reason.startsWith(PERMISSION_DENIED_PREFIX);
+}
+//# sourceMappingURL=skip-reasons.js.map

package/dist/skip-reasons.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skip-reasons.js","sourceRoot":"","sources":["../src/skip-reasons.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,wBAAwB,GAAG,qBAAqB,CAAC;AAEvD,iGAAiG;AACjG,MAAM,UAAU,sBAAsB,CAAC,IAAwB;IAC7D,OAAO,GAAG,wBAAwB,GAAG,IAAI,GAAG,CAAC;AAC/C,CAAC;AAED,+GAA+G;AAC/G,MAAM,UAAU,sBAAsB,CAAC,IAAwB;IAC7D,OAAO,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,wBAAwB,CAAC,CAAC;AAC1D,CAAC"}

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

@@ -1,15 +1,15 @@
+export { isJsonData } from "../json-data.js";
 /** Internal observation owner shared by network and finite acquisition wrappers. */
 import { type BoundFeed } from "../connectors.js";
 import type { Finding } from "../record-overlay/types.js";
+import type { SourceCommitPreparation } from "./target.js";
 import { type Stop } from "./guard.js";
-import type { MachineState, SourceState } from "./machine-state.js";
+import { type MachineState, type SourceState } from "./machine-state.js";
 import type { CommitResult, PageCommit, SourceRunReceipt } from "./types.js";
 export declare const DEFAULT_MISSING_THRESHOLD = 2;
 export declare const MAX_CURSOR_CHARS = 8192;
 export declare const MAX_REPLAY_FAILURES = 5;
 export declare const UNSUPPORTED_CONTENT = "SOURCE_UNSUPPORTED_CONTENT";
-/** JSON data only: finite numbers, plain objects and arrays, no undefined members. */
-export declare function isJsonData(value: unknown, depth?: number): boolean;
 interface DriverOptions {
     bound: BoundFeed;
     state: MachineState;
@@ -33,8 +33,8 @@ interface DriverOptions {
     lastUrl?(): string | undefined;
     stop(stop: Stop, url?: string): void;
     extraFindings: Finding[];
+    prepareCommit?(page: PageCommit): Promise<SourceCommitPreparation>;
     commit(page: PageCommit): Promise<CommitResult | void>;
 }
 export declare function driveObservation(options: DriverOptions): Promise<void>;
-export {};
 //# sourceMappingURL=driver.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../../src/source-engine/driver.ts"],"names":[],"mappings":"AAAA,oFAAoF;AACpF,OAAO,EAA4B,KAAK,SAAS,EAA0B,MAAM,kBAAkB,CAAC;AAEpG,OAAO,KAAK,EAAE,OAAO,EAAgB,MAAM,4BAA4B,CAAC;AACxE,OAAO,EAAc,KAAK,IAAI,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,KAAK,EAAE,YAAY,EAA8B,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAChG,OAAO,KAAK,EAAE,YAAY,EAAe,UAAU,EAAqB,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE7G,eAAO,MAAM,yBAAyB,IAAI,CAAC;AAC3C,eAAO,MAAM,gBAAgB,OAAO,CAAC;AACrC,eAAO,MAAM,mBAAmB,IAAI,CAAC;AACrC,eAAO,MAAM,mBAAmB,+BAA+B,CAAC;AAMhE,sFAAsF;AACtF,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,SAAI,GAAG,OAAO,CAU7D;AAiGD,UAAU,aAAa;IACrB,KAAK,EAAE,SAAS,CAAC;IACjB,KAAK,EAAE,YAAY,CAAC;IACpB,OAAO,EAAE,WAAW,CAAC;IACrB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,OAAO,EAAE,gBAAgB,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,aAAa,GAAG,UAAU,CAAC;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,WAAW,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,2FAA2F;IAC3F,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,OAAO,CAAC,KAAK,EAAE;QAAE,MAAM,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,aAAa,GAAG,UAAU,CAAC;QAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,IAAI,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/J,OAAO,CAAC,IAAI,IAAI,GAAG,SAAS,CAAC;IAC7B,OAAO,CAAC,IAAI,MAAM,GAAG,SAAS,CAAC;IAC/B,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,aAAa,EAAE,OAAO,EAAE,CAAC;IACzB,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;CACxD;AACD,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CA0N5E"}
+{"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../../src/source-engine/driver.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,oFAAoF;AACpF,OAAO,EAA4B,KAAK,SAAS,EAA0B,MAAM,kBAAkB,CAAC;AAEpG,OAAO,KAAK,EAAE,OAAO,EAAgB,MAAM,4BAA4B,CAAC;AAKxE,OAAO,KAAK,EAAE,uBAAuB,EAAuB,MAAM,aAAa,CAAC;AAChF,OAAO,EAAc,KAAK,IAAI,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EAA4C,KAAK,YAAY,EAAwC,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACzJ,OAAO,KAAK,EAAE,YAAY,EAAe,UAAU,EAAqB,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE7G,eAAO,MAAM,yBAAyB,IAAI,CAAC;AAC3C,eAAO,MAAM,gBAAgB,OAAO,CAAC;AACrC,eAAO,MAAM,mBAAmB,IAAI,CAAC;AACrC,eAAO,MAAM,mBAAmB,+BAA+B,CAAC;AAyGhE,UAAU,aAAa;IACrB,KAAK,EAAE,SAAS,CAAC;IACjB,KAAK,EAAE,YAAY,CAAC;IACpB,OAAO,EAAE,WAAW,CAAC;IACrB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,OAAO,EAAE,gBAAgB,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,aAAa,GAAG,UAAU,CAAC;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,WAAW,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,2FAA2F;IAC3F,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,OAAO,CAAC,KAAK,EAAE;QAAE,MAAM,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,aAAa,GAAG,UAAU,CAAC;QAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,IAAI,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/J,OAAO,CAAC,IAAI,IAAI,GAAG,SAAS,CAAC;IAC7B,OAAO,CAAC,IAAI,MAAM,GAAG,SAAS,CAAC;IAC/B,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,aAAa,EAAE,OAAO,EAAE,CAAC;IACzB,aAAa,CAAC,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAAC;IACnE,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;CACxD;AACD,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAsU5E"}

package/dist/source-engine/driver.js

@@ -1,31 +1,23 @@
+import { isJsonData } from "../json-data.js";
+export { isJsonData } from "../json-data.js";
 /** Internal observation owner shared by network and finite acquisition wrappers. */
 import { changeBetween, mapRecord } from "../connectors.js";
 import { overlayCanonicalJson } from "../record-overlay/canonical.js";
+import { parseIsoInstant } from "../verification.js";
+import { parseMarkdown } from "../document-codec.js";
+import { discardSourceTargetConsumer, isSourceTargetConsumer } from "./target-consumer.js";
+import { isSourceEstablishment } from "./target-descriptor.js";
 import { SourceStop } from "./guard.js";
+import { hasProtectedSourcePending, isSourceState } from "./machine-state.js";
 export const DEFAULT_MISSING_THRESHOLD = 2;
 export const MAX_CURSOR_CHARS = 8192;
 export const MAX_REPLAY_FAILURES = 5;
 export const UNSUPPORTED_CONTENT = "SOURCE_UNSUPPORTED_CONTENT";
 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. */
-export 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));
-}
+/** External identities are arbitrary strings, including Object.prototype member names. */
+const idMap = (entries) => Object.assign(Object.create(null), entries);
+const ownEntry = (entries, id) => Object.hasOwn(entries, id) ? entries[id] : undefined;
 /** The page as the engine accepts it, or why not. */
 function pageProblem(page) {
     if (!record(page))
@@ -74,7 +66,7 @@ function diffPage(state, page, bound, observedAt) {
     const changes = [];
     const entries = new Map();
     for (const [id, mapped] of last) {
-        const stored = Object.hasOwn(state.records, id) ? state.records[id] : undefined;
+        const stored = ownEntry(state.records, id);
         if (mapped.kind === "refused") {
             // Refused but present: still observed, so never missing; its accepted values stay.
             if (stored)
@@ -126,6 +118,7 @@ function commitResult(result) {
 export async function driveObservation(options) {
     const { bound, receipt, observedAt, mode, resumed, signal, extraFindings } = options;
     const key = bound.policy.feed;
+    const qualified = isSourceTargetConsumer(options.prepareCommit, options.commit);
     let state = options.initial;
     let version = options.version;
     const baseline = version === null;
@@ -138,6 +131,12 @@ export async function driveObservation(options) {
     /** Store `next` after a commit; false when the store refused it and the run has stopped. */
     const store = async (next) => {
         try {
+            if ((qualified || options.prepareCommit || hasProtectedSourcePending(state))
+                && ((qualified ? Object.keys(next.pending ?? {}).length : Object.values(next.pending ?? {}).filter(p => p.establishment).length) > 100
+                    || new TextEncoder().encode(JSON.stringify(next)).length > 4194304))
+                throw new Error("source establishment state limit");
+            if (!isSourceState(next))
+                throw new Error("invalid source state");
             version = await options.state.write(key, next, version);
             state = next;
             receipt.pending = Object.keys(next.pending ?? {}).length;
@@ -153,28 +152,92 @@ export async function driveObservation(options) {
         // 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 retained = hasProtectedSourcePending(state);
+        if (retained && !qualified) {
+            stop = { outcome: "failed", reason: "establishment_consumer_required", retry: false };
+            return;
+        }
+        if (retained && (Object.keys(state.pending ?? {}).length > 100 || new TextEncoder().encode(JSON.stringify(state)).length > 4194304)) {
+            stop = { outcome: "failed", reason: "establishment_state_limit", retry: false };
+            return;
+        }
+        if (retained && !signal.aborted) {
+            const pending = state.pending;
+            const context = state.pending_commit;
+            // Old establishment checkpoints never recorded page order/flags. Retain their stable
+            // legacy order only when every entry belongs to one original group and observation.
+            const ids = context?.order ?? Object.keys(pending).sort();
+            const at = pending[ids[0]].held_at;
+            const first = pending[ids[0]].establishment;
+            if (!context && (!first || parseIsoInstant(at) === null || ids.some(id => {
+                const p = pending[id], e = p.establishment;
+                return !e || e.group !== first.group || e.generation !== first.generation || e.observed_at !== at || p.held_at !== at;
+            }))) {
+                stop = { outcome: "failed", reason: "establishment_scope_changed", retry: false };
+                return;
+            }
+            const records = idMap();
+            for (const id of ids)
+                records[id] = { fields: { ...(pending[id].change.after ?? pending[id].change.before ?? {}) } };
+            let result;
+            try {
+                const establishments = Object.fromEntries(ids.filter(id => pending[id].establishment !== undefined).map(id => [id, pending[id].establishment]));
+                result = commitResult(await options.commit(structuredClone({ feed: key, provider: bound.policy.provider,
+                    observed_at: at, page: context?.page ?? 0, replay: true, changes: ids.map(id => pending[id].change), records,
+                    baseline: context?.baseline ?? false, complete: context?.complete ?? false,
+                    ...(Object.keys(establishments).length ? { establishments } : {}) })));
+            }
+            catch (error) {
+                receipt.held += ids.length;
+                stop = { outcome: "failed", reason: "establishment_pending", retry: true, detail: errorText(error) };
+                return;
+            }
+            if (ids.some(id => result.hold.has(id) || result.retry.has(id))) {
+                receipt.held += ids.length;
+                stop = { outcome: "failed", reason: "establishment_pending", retry: true };
+                return;
+            }
+            const nextRecords = idMap(state.records);
+            for (const id of ids)
+                nextRecords[id] = entryJson(pending[id].entry);
+            const next = { ...state, records: nextRecords };
+            delete next.pending;
+            delete next.pending_commit;
+            // No next cursor/validators were stored in the supplying checkpoint. A successful
+            // recovery may rescan from the old cursor; it cannot claim the lost page completed.
+            if (!(await store(next)))
+                return;
+        }
         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 live = pendingIds.filter((id) => pending[id].establishment !== undefined || !ownEntry(state.records, id)?.gone || pending[id].change.change_kind === "new");
+            const marked = live.filter(id => pending[id].establishment !== undefined);
+            const establishments = Object.fromEntries(marked.map(id => [id, pending[id].establishment]));
             const changes = live.map((id) => pending[id].change);
-            const records = {};
+            const records = idMap();
             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({
+                    result = commitResult(await options.commit(structuredClone({
                         feed: key, provider: bound.policy.provider, observed_at: observedAt, page: 0, replay: true, changes, records, baseline: false, complete: false,
-                    }));
+                        ...(marked.length ? { establishments } : {}),
+                    })));
                 }
                 catch (error) {
                     failure = errorText(error);
                 }
             }
-            const nextRecords = { ...state.records };
-            const nextPending = {};
+            if (marked.some(id => failure !== undefined || result.retry.has(id) || result.hold.has(id))) {
+                receipt.held += marked.length;
+                stop = { outcome: "failed", reason: "establishment_pending", retry: true, ...(failure ? { detail: failure } : {}) };
+                return;
+            }
+            const nextRecords = idMap(state.records);
+            const nextPending = idMap();
             const dropped = [];
             for (const id of live) {
                 const entry = pending[id];
@@ -193,7 +256,7 @@ export async function driveObservation(options) {
                 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];
+                    const current = ownEntry(state.records, id);
                     nextRecords[id] = entryJson(current?.gone ? entry.entry : { ...entry.entry, missing: current?.missing ?? 0, first_missing_at: current?.first_missing_at });
                 }
             }
@@ -224,6 +287,10 @@ export async function driveObservation(options) {
             if (!(await store(next)))
                 return;
         }
+        if (qualified && Object.keys(state.pending ?? {}).length) {
+            stop = { outcome: "failed", reason: "establishment_pending", retry: true };
+            return;
+        }
         if (signal.aborted) {
             stop = { outcome: "deferred", reason: "deadline", retry: true };
             return;
@@ -295,7 +362,7 @@ export async function driveObservation(options) {
                 seen.add(id);
             const ended = !page.more;
             const complete = ended && mode === "complete" && page.complete && sourceComplete;
-            const merged = { ...state.records };
+            const merged = idMap(state.records);
             for (const [id, entry] of diff.entries)
                 merged[id] = entry;
             const missing = complete ? missingAfterComplete(merged, seen, threshold, observedAt) : { changes: [], entries: new Map() };
@@ -308,7 +375,7 @@ export async function driveObservation(options) {
             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 };
+                const remaining = idMap(state.pending);
                 for (const id of superseded)
                     delete remaining[id];
                 const pre = { ...state };
@@ -319,15 +386,64 @@ export async function driveObservation(options) {
                 if (!(await store(pre)))
                     break;
             }
-            const records = {};
+            const records = idMap();
             for (const change of changes)
                 records[change.external_id] = { fields: { ...(change.after ?? change.before ?? {}) } };
             let result;
             try {
-                result = commitResult(await options.commit({
+                const commitPage = JSON.parse(JSON.stringify({
                     feed: key, provider: bound.policy.provider, observed_at: observedAt, page: receipt.pages + 1, replay: false,
                     changes, records, baseline, complete,
                 }));
+                if (options.prepareCommit) {
+                    const prepared = await options.prepareCommit(structuredClone(commitPage));
+                    if (!isJsonData(prepared) || !record(prepared.establishments))
+                        throw new Error("invalid source preparation");
+                    const descriptors = JSON.parse(JSON.stringify(prepared.establishments));
+                    const ids = Object.keys(descriptors);
+                    if (ids.length > 100)
+                        throw new Error("source establishment page limit");
+                    const pending = idMap(state.pending);
+                    for (const id of ids) {
+                        const change = byId.get(id), entry = diff.entries.get(id), e = descriptors[id];
+                        if (!change?.after || !entry || !isSourceEstablishment(e) || e.observed_at !== observedAt)
+                            throw new Error("invalid source establishment");
+                        if (e.intent) {
+                            const fm = parseMarkdown(e.intent.content, e.target).frontmatter;
+                            if (fm.type !== bound.kind.governs || !Array.isArray(fm.sources) || fm.sources.length !== 1
+                                || fm.sources[0]?.resource !== bound.resource || fm.sources[0]?.id !== id)
+                                throw new Error("invalid source establishment identity");
+                        }
+                        pending[id] = { change: structuredClone(change), entry: entryJson(structuredClone(entry)), held_at: observedAt, establishment: e };
+                    }
+                    if (qualified && changes.length) {
+                        for (const change of changes) {
+                            const id = change.external_id, entry = diff.entries.get(id) ?? missing.entries.get(id);
+                            if (!entry)
+                                throw new Error("source pending entry missing");
+                            pending[id] = { change: structuredClone(change), entry: entryJson(structuredClone(entry)), held_at: observedAt,
+                                ...(Object.hasOwn(descriptors, id) ? { establishment: descriptors[id] } : {}) };
+                        }
+                    }
+                    if ((qualified ? Object.keys(pending).length : Object.values(pending).filter(p => p.establishment).length) > 100)
+                        throw new Error("source establishment pending limit");
+                    if (ids.length || qualified && changes.length) {
+                        const pre = { ...state, pending, ...(qualified ? { pending_commit: {
+                                    v: 1, order: changes.map(change => change.external_id), page: commitPage.page,
+                                    baseline: commitPage.baseline, complete: commitPage.complete,
+                                } } : {}) };
+                        if (new TextEncoder().encode(JSON.stringify(pre)).length > 4194304)
+                            throw new Error("source establishment envelope limit");
+                        if (!(await store(pre)))
+                            return;
+                        commitPage.establishments = structuredClone(descriptors);
+                    }
+                }
+                result = commitResult(await options.commit(commitPage));
+                if ((qualified ? changes.map(c => c.external_id) : Object.keys(commitPage.establishments ?? {})).some(id => result.hold.has(id) || result.retry.has(id))) {
+                    stop = { outcome: "failed", reason: "establishment_pending", retry: true };
+                    return;
+                }
             }
             catch (error) {
                 stop = { outcome: "failed", reason: "commit_failed", retry: true, detail: errorText(error) };
@@ -335,13 +451,15 @@ export async function driveObservation(options) {
             }
             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 };
+            const nextRecords = idMap(state.records);
+            const nextPending = idMap(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))
+                else if (!notWritten(id)) {
                     nextRecords[id] = entryJson(entry);
+                    delete nextPending[id];
+                }
             }
             const next = {
                 ...state,
@@ -356,6 +474,7 @@ export async function driveObservation(options) {
                 next.pending = nextPending;
             else
                 delete next.pending;
+            delete next.pending_commit;
             if (!(await store(next)))
                 break;
             receipt.pages += 1;
@@ -385,8 +504,10 @@ export async function driveObservation(options) {
         return;
     }
     finally {
-        if (stop)
+        if (stop) {
+            discardSourceTargetConsumer(options.prepareCommit, options.commit);
             options.stop(stop, stopUrl);
+        }
     }
 }
 //# sourceMappingURL=driver.js.map