@zackbart/connecta 0.41.0 → 0.42.0

package/dist/registry.js

@@ -6,15 +6,15 @@ import { authCall, authInvoke } from "./auth/native.js";
 import { Clock, Duration, Effect, Random } from "effect";
 import { activityRequest } from "./activity-request.js";
 import { aggregateCallAdmissionSnapshots, ConnectorCallAdmissionController, } from "./call-admission.js";
-import { attachCatalogCache, catalogExpiry, catalogFetchedAt, customCatalogFallback, invalidateCatalogCache, observeUncachedCatalogRefresh, retainedCatalogIdentity, storeCustomCatalogFallback, } from "./catalog-cache.js";
-import { carryCatalogFreshness, markCatalogFreshness } from "./catalog-freshness.js";
+import { attachCatalogCache, catalogExpiry, catalogFetchedAt, bindCustomCatalogListing, customCatalogFallback, customCatalogPeek, fenceCustomCatalog, invalidateCatalogCache, observeUncachedCatalogRefresh, retainedCatalogIdentity, storeCustomCatalogFallback, } from "./catalog-cache.js";
+import { carryCatalogFreshness, markCatalogFreshness, markCatalogStale } from "./catalog-freshness.js";
 import { MAX_CATALOG_TOOLS, MAX_SERIALIZED_CATALOG_BYTES } from "./catalog-limits.js";
 import { CONFIG_DEFAULTS } from "./config-defaults.js";
 import { usesCallerIdentity } from "./connector-caller.js";
 import { forwardsPrincipal } from "./request-principal.js";
 import { canonicalJson } from "./canonical-json.js";
 import { storedCredentialShape } from "./credential-rules.js";
-import { ConnectorCallError } from "./errors.js";
+import { ConnectorCallError, isAccessRefusal } from "./errors.js";
 import { attachOAuthPartition, oauthPartitionIdle } from "./oauth-partition.js";
 import { attachOAuthSealer, vaultOAuthSealer } from "./oauth-sealing.js";
 import { boundedStatus, failureRecord, failureStatus, logFailure, ownStatus } from "./operator-record.js";
@@ -34,7 +34,7 @@ import { redactCatalog, sentSecretsFor, sentSecretsForRequest } from "./sent-sec
 import { GUIDE_SUMMARY_LENGTH, normalizeGuideSummary, connectorGuide, connectorGuideSummary } from "./skills.js";
 import { jsonCodec, OAUTH_HANDOFF_TTL_SECONDS, oauthHandoffKeys, resultKeys, scopes, stashExpiryKeys, stashLedgerKeys, } from "./storage/keys.js";
 import { assertStaticToolNames, hasControlCharacters } from "./tool-name.js";
-import { carryToolClassification, classifyTool } from "./tool-safety.js";
+import { carryToolClassification, classifyTool, sourceDeclaresWrite, } from "./tool-safety.js";
 import { isWorkspaceAddress } from "./workspace-address.js";
 import { workspaceSubjectOf } from "./workspace-subject.js";
 const ID_RE = /^[a-z0-9_-]+$/;
@@ -145,12 +145,18 @@ const STASH_WRITE_TIMEOUT_MS = 30_000;
 const STASH_COMPLETION_TIMEOUT_MS = 15_000;
 /** Reservation, chunk writes and completion share one finite outer budget. */
 const STASH_TIMEOUT_MS = STASH_WRITE_TIMEOUT_MS + STASH_COMPLETION_TIMEOUT_MS;
+/** Chunks one release deletes at a time; a stash holds at most 32. */
+const STASH_RELEASE_CONCURRENCY = 16;
 /** Stop waiting without starting background storage work after the deadline. */
 function completeStash(effect) {
     return effect.pipe(Effect.asVoid, Effect.timeoutOrElse({ duration: Duration.millis(STASH_COMPLETION_TIMEOUT_MS), orElse: () => Effect.void }), 
     // onError finalizers are otherwise uninterruptible, including their I/O.
     Effect.interruptible);
 }
+/** The reservation id of one result id, which is random and never reused. */
+function stashCharge(id) {
+    return Effect.tryPromise({ try: () => sha256Hex(id), catch: (error) => error });
+}
 /**
  * Live charges in a stored ledger. Anything malformed reads as empty: the
  * ledger bounds an advisory cache, and the next successful swap replaces it.
@@ -317,8 +323,8 @@ export class Registry {
         Object.freeze(this.classification);
         for (const [id, overrides] of Object.entries(this.classification)) {
             for (const [name, verdict] of Object.entries(overrides)) {
-                if (!name || (verdict !== "read" && verdict !== "write" && verdict !== "hidden")) {
-                    throw new Error(`ConnectaConfig.classification.${id}.${name}: expected "read", "write", or "hidden"`);
+                if (!name || !["read", "read-repeatable", "write", "hidden"].includes(verdict)) {
+                    throw new Error(`ConnectaConfig.classification.${id}.${name}: expected "read", "read-repeatable", "write", or "hidden"`);
                 }
             }
             const connector = this.connectors.get(id);
@@ -617,8 +623,11 @@ export class Registry {
      * unconfirmed and retain their charge. Cleanup/release and settlement each
      * stop waiting after 15 seconds. Storage TTL reclaims the rows.
      */
-    stashResult(id, chunks, ttlSeconds, partition = scopes.results) {
-        return runOnPartition(registryEdgeProgram(Registry.prototype, this, "stashResult", id, chunks, ttlSeconds, partition), this.opts);
+    stashResult(id, chunks, ttlSeconds, options = {}) {
+        return runOnPartition(registryEdgeProgram(Registry.prototype, this, "stashResult", id, chunks, ttlSeconds, options), this.opts);
+    }
+    releaseResult(id, chunkCount, partition = scopes.results) {
+        return runOnPartition(registryEdgeProgram(Registry.prototype, this, "releaseResult", id, chunkCount, partition), this.opts);
     }
     /**
      * Storage namespaced to the root result partition, kept separate from any
@@ -681,7 +690,16 @@ export class Registry {
             if (connector.staticTools)
                 return markCatalogFreshness(connector.staticTools, Infinity);
             const ctx = this.contextFor(id, baseUrl, requestScope, callOptions, scope);
-            const listed = yield* authInvoke(connector, "listTools", [ctx]).pipe(Effect.catch((error) => Effect.gen(function* () {
+            // `remoteMcp()` binds and fences its own attempts, knowing how each was made.
+            const customListing = connector.peekCatalog
+                ? undefined
+                : yield* authCall(bindCustomCatalogListing, [ctx, id]).pipe(Effect.catch((failure) => Effect.sync(() => {
+                    logFailure(this.opts.logger, "catalog read failed", failureRecord({ connector: id }, failure));
+                    return undefined;
+                })));
+            const listed = yield* authInvoke(connector, "listTools", [ctx]).pipe(Effect.catch((error) => Effect.gen({ self: this }, function* () {
+                if (customListing && isAccessRefusal(error))
+                    yield* authCall(fenceCustomCatalog, [ctx, id, customListing]).pipe(Effect.catch((failure) => Effect.sync(() => logFailure(this.opts.logger, "catalog fence failed", failureRecord({ connector: id }, failure)))));
                 const fallback = error instanceof ConnectorCallError && error.code === "unavailable"
                     ? yield* authCall(customCatalogFallback, [ctx, id]).pipe(Effect.catch(() => Effect.succeed(undefined)))
                     : undefined;
@@ -697,12 +715,18 @@ export class Registry {
             const facts = frozenFacts(structuredClone(tools));
             const accepted = this.acceptToolNames(facts);
             if (catalogFetchedAt(ctx) === undefined) {
-                for (const observe of [storeCustomCatalogFallback, observeUncachedCatalogRefresh]) {
-                    yield* authCall(observe, [ctx, id, facts]).pipe(Effect.catch((error) => Effect.sync(() => logFailure(this.opts.logger, "catalog refresh observation failed", failureRecord({ connector: id }, error)))));
+                for (const observe of [
+                    authCall(storeCustomCatalogFallback, [ctx, facts, customListing]),
+                    authCall(observeUncachedCatalogRefresh, [ctx, id, facts]),
+                ]) {
+                    yield* observe.pipe(Effect.catch((error) => Effect.sync(() => logFailure(this.opts.logger, "catalog refresh observation failed", failureRecord({ connector: id }, error)))));
                 }
             }
             const provenance = catalogExpiry(ctx);
             const freshUntil = provenance && !provenance.staleFallback ? provenance.expiresAt : 0;
+            // A transient-failure fallback answers the listing; discovery still reports its age.
+            if (provenance?.staleFallback)
+                markCatalogStale(accepted, { code: "unavailable", ageMs: Math.max(0, Date.now() - provenance.fetchedAt) });
             // Principal-forwarded listings belong to one caller, never to the shared
             // operator observation store. The actual catalog cache is identity-bound.
             if (!forwardsPrincipal(connector)) {
@@ -715,6 +739,30 @@ export class Registry {
             return markCatalogFreshness(accepted, freshUntil);
         });
     }
+    /** See {@link RegistryView.peekCatalog}. Same classification and filtering as `loadTools`. */
+    loadPeek(id, baseUrl, requestScope, callOptions = {}, scope) {
+        return Effect.gen({ self: this }, function* () {
+            const connector = this.connectors.get(id);
+            if (!connector || connector.staticTools)
+                return undefined;
+            const ctx = this.contextFor(id, baseUrl, requestScope, callOptions, scope);
+            const peek = connector.peekCatalog
+                ? yield* authInvoke(connector, "peekCatalog", [ctx])
+                : yield* authCall(customCatalogPeek, [ctx, id]);
+            if (!peek)
+                return undefined;
+            const facts = redactCatalog(ctx, peek.tools).map(({ classification: _ignored, ...fact }) => fact);
+            const overrides = this.classification[id];
+            return {
+                tools: this.acceptToolNames(frozenFacts(structuredClone(facts)))
+                    .filter((tool) => overrides?.[tool.name] !== "hidden")
+                    .map((tool) => this.publishTool(id, tool)),
+                fetchedAt: peek.fetchedAt,
+                // A custom catalog is always listed anew, so its retained copy is never current.
+                fresh: connector.peekCatalog !== undefined && peek.expiresAt > Date.now(),
+            };
+        });
+    }
     /** The served catalog excludes control-character names; raw caches stay complete. */
     acceptToolNames(tools) {
         const accepted = tools.filter((tool) => !hasControlCharacters(tool.name));
@@ -741,19 +789,20 @@ export class Registry {
     }
     publishTool(id, tool) {
         const override = this.classification[id]?.[tool.name];
+        const classification = classifyTool(tool, override === "hidden" ? undefined : override);
         return carryToolClassification(tool, {
             ...structuredClone(tool),
-            classification: classifyTool(tool, override === "hidden" ? undefined : override),
+            classification,
             ...(override !== undefined
                 ? {
                     annotations: {
                         ...structuredClone(tool.annotations),
-                        readOnlyHint: override === "read",
-                        destructiveHint: override === "write",
+                        readOnlyHint: override !== "hidden" && classification === "read",
+                        destructiveHint: override !== "hidden" && classification === "write",
                     },
                 }
                 : {}),
-        });
+        }, override === "read-repeatable" || undefined);
     }
     /** Construction-only view for the secret-free static config description. */
     describeStaticTools(id) {
@@ -771,19 +820,30 @@ export class Registry {
                 return;
             this.overrideWarningCatalogs.set(partition, catalog);
         }
-        const known = new Set(tools.map((tool) => tool.name));
-        for (const name of Object.keys(overrides ?? {})) {
-            if (known.has(name))
-                continue;
-            if (this.connectors.get(id)?.staticTools) {
+        const known = new Map(tools.map((tool) => [tool.name, tool]));
+        const staticCatalog = this.connectors.get(id)?.staticTools !== undefined;
+        for (const [name, override] of Object.entries(overrides ?? {})) {
+            const tool = known.get(name);
+            if (!tool && staticCatalog) {
                 throw new Error(`ConnectaConfig.classification: connector "${id}" has no tool "${name}"`);
             }
             // Only deployment-authored names, never downstream text. JSON quoting
             // prevents control characters from forging operator log lines.
             const quoted = JSON.stringify(`${id}.${name}`).replace(/[\u2028\u2029]/g, (ch) => `\\u${ch.charCodeAt(0).toString(16)}`);
+            if (tool) {
+                // A static catalog cannot change, so the deployment's construction reports it once.
+                const reports = staticCatalog ? partition === undefined && this.opts.constructionChecks !== false : true;
+                if (override === "read" && reports && sourceDeclaresWrite(tool)) {
+                    this.opts.logger.warn(`classification override ${quoted} to "read" is not applied because the connector declares this tool a write; it stays a write. "read-repeatable" serves it as a read and accepts that hosts may repeat it`);
+                }
+                continue;
+            }
             this.opts.logger.warn(`classification override ${quoted} is dormant because the runtime catalog lists no such tool`);
         }
     }
+    peekCatalog(id, baseUrl, requestScope, callOptions = {}, scope) {
+        return runEdge(registryEdgeProgram(Registry.prototype, this, "peekCatalog", id, baseUrl, requestScope, callOptions, scope));
+    }
     getTools(id, baseUrl, requestScope, callOptions = {}, scope) {
         return runEdge(registryEdgeProgram(Registry.prototype, this, "getTools", id, baseUrl, requestScope, callOptions, scope));
     }
@@ -818,7 +878,8 @@ export class Registry {
     }
     static {
         provideRegistryPrograms(Registry.prototype, {
-            stashResult: (self, id, chunks, ttlSeconds, partition = scopes.results) => Effect.gen({ self }, function* () {
+            stashResult: (self, id, chunks, ttlSeconds, options = {}) => Effect.gen({ self }, function* () {
+                const partition = options.partition ?? scopes.results;
                 const maxBytes = this.opts.results?.maxStashBytes ?? CONFIG_DEFAULTS.results.maxStashBytes;
                 const maxEntries = this.opts.results?.maxStashEntries ?? CONFIG_DEFAULTS.results.maxStashEntries;
                 // The paging envelope is ASCII, so its string length is its stored byte count.
@@ -826,8 +887,9 @@ export class Registry {
                 if (bytes > maxBytes || maxEntries === 0)
                     return false;
                 const keys = chunks.map((_, index) => partition + resultKeys.chunk(id, index));
-                // IDs belong to reservations, not reusable result IDs or subjects.
-                const charge = crypto.randomUUID();
+                // A digest finds this reservation again on release without putting
+                // the result's ID in the deployment-wide ledger.
+                const charge = yield* stashCharge(id);
                 const ttlMs = ttlSeconds * 1000;
                 if (!Number.isSafeInteger(ttlMs) || ttlMs <= 0)
                     return false;
@@ -882,7 +944,8 @@ export class Registry {
                 const remaining = Math.max(0, writeDeadline - (yield* Clock.currentTimeMillis));
                 const written = yield* Effect.gen(function* () {
                     const multi = getNativeStorage(self.opts.storage)?.setMany;
-                    for (let index = keys.length - 1; index >= 0;) {
+                    const lowest = options.holdFirst ? 1 : 0;
+                    for (let index = keys.length - 1; index >= lowest;) {
                         const first = multi && index > 0 ? Math.max(1, index - 63) : index;
                         const before = yield* Clock.currentTimeMillis;
                         if (before >= writeDeadline || before >= chunkExpiry)
@@ -905,6 +968,15 @@ export class Registry {
                     yield* completeStash(settle);
                 return written;
             }).pipe(Effect.timeoutOrElse({ duration: Duration.millis(STASH_TIMEOUT_MS), orElse: () => Effect.succeed(false) }), Effect.provideService(Storage, self.opts.storage)),
+            releaseResult: (self, id, chunkCount, partition = scopes.results) => completeStash(Effect.gen(function* () {
+                const charge = yield* stashCharge(id);
+                // Bytes first: a failed delete keeps its charge, so the ledger never
+                // undercounts what storage holds.
+                yield* Effect.forEach(Array.from({ length: chunkCount }, (_, index) => partition + resultKeys.chunk(id, index)), (key) => storageDelete(key), { concurrency: STASH_RELEASE_CONCURRENCY, discard: true });
+                yield* swapStashLedger((live) => live.some((entry) => entry[0] === charge)
+                    ? { entries: live.filter((entry) => entry[0] !== charge), result: undefined }
+                    : { result: undefined });
+            })).pipe(Effect.ignore, Effect.provideService(Storage, self.opts.storage)),
             recheckResultAccess: () => Effect.succeed(true),
             storeOAuthHandoff: (self, connectorId, state, principalKey) => Effect.gen(function* () {
                 const key = oauthHandoffKeys.handoff(connectorId, yield* Effect.tryPromise({ try: () => sha256Hex(state), catch: (error) => error }));
@@ -973,6 +1045,12 @@ export class Registry {
                     return yield* load.join(signal);
                 }));
             }),
+            peekCatalog: (self, id, baseUrl, requestScope, callOptions = {}, scope) => Effect.suspend(() => {
+                if (!self.connectors.has(id))
+                    return Effect.succeed(undefined);
+                const owner = self.contextFor(id, baseUrl, requestScope, callOptions, scope);
+                return duringViewEffect(owner, (signal) => self.loadPeek(id, baseUrl, owner.requestScope, { ...callOptions, signal }, scope));
+            }),
             credentialDriftFor: (self, id, requestScope) => Effect.gen(function* () {
                 const credential = self.connectors.get(id)?.credential;
                 const vault = self.opts.credentialVault;
@@ -1097,6 +1175,9 @@ class ScopedRegistryView {
     getTools(...args) {
         return runEdge(registryEdgeProgram(ScopedRegistryView.prototype, this, "getTools", ...args));
     }
+    peekCatalog(...args) {
+        return runEdge(registryEdgeProgram(ScopedRegistryView.prototype, this, "peekCatalog", ...args));
+    }
     contextFor(...args) {
         const registry = this.registryFor(args[0]);
         if (!registry)
@@ -1110,8 +1191,14 @@ class ScopedRegistryView {
         }
         return registry.admitCall(...args);
     }
-    stashResult(id, chunks, ttlSeconds) {
-        return this.root.stashResult(id, chunks, ttlSeconds, this.scope.subjectKey ? scopes.subject(this.scope.subjectKey) : scopes.results);
+    stashResult(id, chunks, ttlSeconds, options = {}) {
+        return this.root.stashResult(id, chunks, ttlSeconds, {
+            ...options,
+            partition: this.scope.subjectKey ? scopes.subject(this.scope.subjectKey) : scopes.results,
+        });
+    }
+    releaseResult(id, chunkCount) {
+        return this.root.releaseResult(id, chunkCount, this.scope.subjectKey ? scopes.subject(this.scope.subjectKey) : scopes.results);
     }
     resultIdentity() {
         return {
@@ -1158,7 +1245,11 @@ class ScopedRegistryView {
     }
     static {
         provideRegistryPrograms(ScopedRegistryView.prototype, {
-            stashResult: (self, id, chunks, ttlSeconds) => registryProgram(self.root, "stashResult", id, chunks, ttlSeconds, self.scope.subjectKey ? scopes.subject(self.scope.subjectKey) : scopes.results),
+            releaseResult: (self, id, chunkCount) => registryProgram(self.root, "releaseResult", id, chunkCount, self.scope.subjectKey ? scopes.subject(self.scope.subjectKey) : scopes.results),
+            stashResult: (self, id, chunks, ttlSeconds, options = {}) => registryProgram(self.root, "stashResult", id, chunks, ttlSeconds, {
+                ...options,
+                partition: self.scope.subjectKey ? scopes.subject(self.scope.subjectKey) : scopes.results,
+            }),
             recheckResultAccess: (self, dependencies, classification, signal) => Effect.tryPromise({
                 try: () => self.scope.currentResultAccess?.(dependencies, classification, signal) ?? Promise.resolve(true),
                 catch: (error) => error,
@@ -1185,6 +1276,15 @@ class ScopedRegistryView {
                 }
                 return carryCatalogFreshness(tools, visible);
             }),
+            peekCatalog: (self, ...args) => Effect.gen(function* () {
+                const registry = self.registryFor(args[0]);
+                if (!registry)
+                    return undefined;
+                const peek = yield* registryProgram(registry, "peekCatalog", args[0], args[1], args[2], args[3], self.scope);
+                const granted = self.scope.toolAccess?.get(args[0]);
+                // A pool grant binds a stale listing exactly as it binds a live one.
+                return peek && granted ? { ...peek, tools: peek.tools.filter((tool) => granted.has(tool.name)) } : peek;
+            }),
             credentialDriftFor: (self, id, requestScope) => Effect.suspend(() => {
                 const registry = self.registryFor(id);
                 return registry

package/dist/result-preview.js

@@ -0,0 +1,210 @@
+/**
+ * Schema-aware views of direct reads past their cap, as pure functions of redacted
+ * text. Presentation only: the stash and what a program sees stay byte-identical
+ * to the full result, and everything shown here also appears in it, unchanged.
+ * Rules: documentation/meta-tools.md#previews-of-reads-over-the-cap.
+ */
+const enc = new TextEncoder();
+const dec = new TextDecoder();
+/** Bytes of whole rows a view shows. */
+const ROW_BYTES = 1_500;
+/** One row can pass ROW_BYTES up to this, so a wide list still shows its shape. */
+const FIRST_ROW_BYTES = 3_000;
+/** Everything outside the list stays whole, or the read is not a list. */
+const REST_BYTES = 1_024;
+const TEXT_HEAD_BYTES = 1_200;
+const TEXT_TAIL_BYTES = 800;
+const MIN_ROWS = 3;
+const MAX_ROW_DEPTH = 3;
+const MAX_KEYS = 40;
+const MAX_KEY_CHARS = 64;
+/** Rows sampled for key names. */
+const KEY_SAMPLE_ROWS = 50;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+const byteLength = (text) => enc.encode(text).length;
+/** The largest list of records within MAX_ROW_DEPTH keys of the root. */
+function dominantRows(root) {
+    let best;
+    const visit = (node, path) => {
+        if (Array.isArray(node)) {
+            if (node.length >= MIN_ROWS && node.every((row) => isRecord(row) || Array.isArray(row))) {
+                const bytes = byteLength(JSON.stringify(node));
+                if (!best || bytes > best.bytes)
+                    best = { path, rows: node, bytes };
+            }
+            return;
+        }
+        if (!isRecord(node) || path.length >= MAX_ROW_DEPTH)
+            return;
+        for (const key of Object.keys(node))
+            visit(node[key], [...path, key]);
+    };
+    visit(root, []);
+    return best;
+}
+function withRows(root, path, rows) {
+    if (!path.length)
+        return rows;
+    const [head, ...tail] = path;
+    const record = root;
+    // Computed keys define own properties, so a key named __proto__ stays data.
+    return { ...record, [head]: withRows(record[head], tail, rows) };
+}
+function rowKeys(rows) {
+    const keys = new Set();
+    for (const row of rows.slice(0, KEY_SAMPLE_ROWS)) {
+        if (!isRecord(row))
+            continue;
+        for (const key of Object.keys(row))
+            if (key.length <= MAX_KEY_CHARS)
+                keys.add(key);
+        if (keys.size >= MAX_KEYS)
+            break;
+    }
+    return [...keys].slice(0, MAX_KEYS);
+}
+/** JavaScript that reads `path` from a parsed value; a program runs it, so it must be exact. */
+function accessor(path) {
+    return path.map((key) => (/^[A-Za-z_$][\w$]*$/.test(key) ? `.${key}` : `[${JSON.stringify(key)}]`)).join("");
+}
+function rowsPreview(parsed, total, cap) {
+    const found = dominantRows(parsed);
+    if (!found || found.bytes * 2 < total)
+        return undefined;
+    // The bytes outside the list; the ways it can be spelled do not change them.
+    const rest = byteLength(JSON.stringify(withRows(parsed, found.path, [])));
+    if (rest > REST_BYTES)
+        return undefined;
+    const firstRowBytes = Math.min(FIRST_ROW_BYTES, cap - rest);
+    const rowBytes = Math.min(ROW_BYTES, cap - rest);
+    const shown = [];
+    let used = 0;
+    for (const row of found.rows) {
+        const size = byteLength(JSON.stringify(row)) + 1;
+        if (used + size > (shown.length ? rowBytes : firstRowBytes))
+            break;
+        shown.push(row);
+        used += size;
+    }
+    const count = found.rows.length;
+    // An empty list would read as a list with no rows, and a whole one needs no sample.
+    if (!shown.length || shown.length === count)
+        return undefined;
+    const keys = rowKeys(found.rows);
+    const path = found.path.length ? accessor(found.path).replace(/^\./, "") : "(root)";
+    const body = JSON.stringify(withRows(parsed, found.path, shown));
+    if (byteLength(body) > cap)
+        return undefined;
+    return {
+        fields: { rows: { path, count, shown: shown.length, keys } },
+        body,
+        shown: `Sample only: ${shown.length === 1 ? "row 1" : `rows 1-${shown.length}`} of ${count} at ${path} follow, in the result's own shape, with every value outside the list; the other ${count - shown.length} are not shown.`,
+        noun: "rows",
+        reduce: `const rows = JSON.parse(text)${accessor(found.path)}; return { count: rows.length, rows: rows.slice(0, 5) };`,
+    };
+}
+function lineCount(text) {
+    let lines = 1;
+    for (let at = text.indexOf("\n"); at !== -1; at = text.indexOf("\n", at + 1))
+        lines++;
+    return lines;
+}
+/** Whether a byte continues a UTF-8 character rather than starting one. */
+const continues = (byte) => byte !== undefined && (byte & 0xc0) === 0x80;
+function textPreview(text, reading, cap) {
+    const bytes = enc.encode(text);
+    if (bytes.length <= TEXT_HEAD_BYTES + TEXT_TAIL_BYTES)
+        return undefined;
+    const marker = (omitted) => `\n…[${omitted} bytes omitted]…\n`;
+    let headEnd = TEXT_HEAD_BYTES;
+    while (continues(bytes[headEnd]))
+        headEnd--;
+    let tailStart = bytes.length - TEXT_TAIL_BYTES;
+    while (continues(bytes[tailStart]))
+        tailStart++;
+    const shownBytes = headEnd + bytes.length - tailStart;
+    const body = `${dec.decode(bytes.subarray(0, headEnd))}${marker(tailStart - headEnd)}${dec.decode(bytes.subarray(tailStart))}`;
+    if (byteLength(body) > cap)
+        return undefined;
+    const lines = lineCount(text);
+    return {
+        fields: { text: { lines, shownBytes } },
+        body,
+        shown: `Sample only: the first ${headEnd} and last ${bytes.length - tailStart} bytes of ${lines} lines follow; the ${tailStart - headEnd} bytes between them are not shown.`,
+        noun: "text",
+        reduce: `const lines = ${reading}.split("\\n"); return { lines: lines.length, matches: lines.filter((line) => /error|fail/i.test(line)).map((line) => line.slice(0, 500)).slice(0, 40) };`,
+    };
+}
+/** Parts of a JSON number token whose exact value is the same however it is spelled. */
+function exactValue(token) {
+    const match = /^(-?)(\d+)(?:\.(\d+))?(?:[eE]([+-]?\d+))?$/.exec(token);
+    if (!match)
+        return undefined;
+    const fraction = match[3] ?? "";
+    const digits = `${match[2]}${fraction}`;
+    let start = 0;
+    let end = digits.length;
+    while (digits[start] === "0")
+        start++;
+    while (end > start && digits[end - 1] === "0")
+        end--;
+    if (start === end)
+        return `${match[1]}0`;
+    return `${match[1]}${digits.slice(start, end)}e${Number(match[4] ?? 0) - fraction.length + digits.length - end}`;
+}
+/** Whether JSON.parse then JSON.stringify keeps this token's value, including its sign and range. */
+function keepsNumber(token) {
+    const printed = String(Number(token));
+    return printed === token || exactValue(printed) === exactValue(token);
+}
+/**
+ * Whether every number in text JSON.parse has already accepted survives parsing.
+ * Both a view and the offered program parse it, so one lossy number anywhere,
+ * inside or outside the rows, declines the view. Strings are skipped, not read.
+ */
+function keepsNumbers(json) {
+    let at = 0;
+    while (at < json.length) {
+        const code = json.charCodeAt(at);
+        if (code === 34) {
+            at++;
+            while (json.charCodeAt(at) !== 34)
+                at += json.charCodeAt(at) === 92 ? 2 : 1;
+            at++;
+        }
+        else if (code === 45 || (code >= 48 && code <= 57)) {
+            const start = at;
+            while (at < json.length && "+-.0123456789Ee".includes(json[at]))
+                at++;
+            if (!keepsNumber(json.slice(start, at)))
+                return false;
+        }
+        else
+            at++;
+    }
+    return true;
+}
+/**
+ * The view of a read past its cap, or undefined when its first bytes should stand:
+ * documents, scalars, shallow or deep lists a view would misstate, and numbers
+ * parsing would change.
+ *
+ * `format` is the result's own: an API connector's text arrives here as one
+ * JSON string, whose decoded text is what a person would call the result.
+ */
+export function previewResult(text, format, cap) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return textPreview(text, "text", cap);
+    }
+    if (typeof parsed === "string" && format === "text")
+        return textPreview(parsed, "JSON.parse(text)", cap);
+    if (typeof parsed !== "object" || parsed === null || !keepsNumbers(text))
+        return undefined;
+    return rowsPreview(parsed, byteLength(text), cap);
+}