@farmslot/protocol 0.83.1 → 0.84.0

package/dist/client-cache/entity-collection.js

@@ -0,0 +1,323 @@
+/**
+ * Entity collection for entity sync (ADR-071 Amendment 4): fleet slots and PR rows held as
+ * entities with content versions, kept current by pushes, a versions read and ids pages.
+ *
+ * Rules:
+ * - Rows stay displayed across reconnects; after every connection or epoch change the listing is
+ *   verified by a versions read before the collection counts as current.
+ * - A push or deletion that lands after a read was sent wins over that read's entry for the id.
+ * - A change without a usable body reads that id; a deletion removes it.
+ * - An id the versions read listed but the ids page did not return ends in a fresh versions read,
+ *   at most twice per sync, never a repeated page.
+ */
+const FIRST_PAGE = 20;
+/** Fresh versions reads after an ids page could not serve a listed id, per sync. */
+const MAX_RECONCILES = 2;
+/** Sync passes per call: new work arriving during a pass is picked up, but never forever. */
+const MAX_PASSES = 6;
+function superseded() {
+    return Object.assign(new Error('Entity collection read superseded'), {
+        code: 'RESOURCE_READ_SUPERSEDED',
+    });
+}
+export class EntityCollection {
+    constructor(options) {
+        this.options = options;
+        /** Every row held, displayed or not yet verified. */
+        this.rows = new Map();
+        /** The listing was confirmed by a versions read on the current connection. */
+        this.verified = false;
+        /** Ids whose change came without a usable body. */
+        this.pending = new Set();
+        /** Last local change per id, so a reply sent before it cannot overwrite it. */
+        this.touched = new Map();
+        this.sequence = 0;
+        /** Rows changed or removed since the store last took them. */
+        this.unstored = new Set();
+        this.unstoredDeletes = new Set();
+    }
+    /** The collection holds rows or a listing to show. */
+    get held() {
+        return this.listed !== undefined || this.rows.size > 0;
+    }
+    /** Verified on this connection, nothing notified since is unread, every listed row is held. */
+    get current() {
+        return this.verified && !this.membershipStale() && this.pending.size === 0 && this.complete();
+    }
+    /** True while a sync is running. */
+    get syncing() {
+        return this.inflight !== undefined;
+    }
+    membershipStale() {
+        return (this.membershipAskedAt !== undefined ||
+            (this.seenMarker !== undefined &&
+                (this.listedMarker === undefined || this.seenMarker > this.listedMarker)));
+    }
+    complete() {
+        if (!this.listed)
+            return false;
+        for (const [id, version] of this.listed)
+            if (this.rows.get(id)?.version !== version)
+                return false;
+        return true;
+    }
+    touch(id) {
+        this.touched.set(id, ++this.sequence);
+    }
+    changedSince(id, start) {
+        return (this.touched.get(id) ?? 0) > start;
+    }
+    /**
+     * Brings the collection current: a versions read when the listing is unverified or membership
+     * moved, then ids pages for what is missing or changed. Resolves true when current.
+     */
+    sync() {
+        if (this.inflight)
+            return this.inflight.promise;
+        const controller = new AbortController();
+        const inflight = {
+            controller,
+            promise: this.run(controller.signal).finally(() => {
+                if (this.inflight === inflight)
+                    this.inflight = undefined;
+            }),
+        };
+        this.inflight = inflight;
+        return inflight.promise;
+    }
+    async run(signal) {
+        let reconciles = 0;
+        let reconcile = false;
+        for (let pass = 0; pass < MAX_PASSES && !this.current; pass++) {
+            if (!this.verified || !this.listed || this.membershipStale() || reconcile) {
+                await this.readVersions(signal);
+                reconcile = false;
+            }
+            const missing = await this.readPages(signal);
+            if (missing && reconciles < MAX_RECONCILES) {
+                reconciles++;
+                reconcile = true;
+            }
+            else if (missing)
+                break;
+        }
+        return this.current;
+    }
+    async readVersions(signal) {
+        const start = this.sequence;
+        const markerAtStart = this.seenMarker;
+        const reply = await this.options.fetchVersions(signal);
+        if (signal.aborted)
+            throw superseded();
+        const replied = new Map();
+        for (const entry of Array.isArray(reply.versions) ? reply.versions : [])
+            if (entry && typeof entry.id === 'string' && typeof entry.version === 'string')
+                replied.set(entry.id, entry.version);
+        // The reply's order is the gateway's; a change after the request was sent wins over its entry.
+        const listed = new Map();
+        for (const [id, version] of replied) {
+            const row = this.rows.get(id);
+            if (!this.changedSince(id, start))
+                listed.set(id, version);
+            // Pushed after the request: a member at the pushed version.
+            else if (row)
+                listed.set(id, row.version);
+            // Changed without a usable body: a member, read below. A deletion stays deleted.
+            else if (this.pending.has(id))
+                listed.set(id, version);
+        }
+        // Added by a push after the request: a member the reply could not list.
+        for (const [id, row] of this.rows)
+            if (this.changedSince(id, start) && !listed.has(id))
+                listed.set(id, row.version);
+        for (const id of [...this.rows.keys()]) {
+            if (listed.has(id))
+                continue;
+            this.rows.delete(id);
+            this.unstored.delete(id);
+            this.unstoredDeletes.add(id);
+        }
+        for (const id of [...this.pending])
+            if (!listed.has(id))
+                this.pending.delete(id);
+        this.listed = listed;
+        this.verified = true;
+        // A question raised after this request was sent needs a reply of its own.
+        if ((this.membershipAskedAt ?? 0) <= start)
+            this.membershipAskedAt = undefined;
+        const marker = reply.membershipRevision ?? markerAtStart;
+        this.listedMarker = marker;
+        if (marker !== undefined && (this.seenMarker === undefined || marker > this.seenMarker))
+            this.seenMarker = marker;
+    }
+    /** Reads every listed id whose row is missing or differs. Returns true if a listed id was not served. */
+    async readPages(signal) {
+        const listed = this.listed;
+        if (!listed)
+            return false;
+        let ask = [...listed]
+            .filter(([id, version]) => this.pending.has(id) || this.rows.get(id)?.version !== version)
+            .map(([id]) => id);
+        const total = ask.length;
+        if (total === 0)
+            return false;
+        let done = 0;
+        let missing = false;
+        let first = true;
+        while (ask.length > 0) {
+            const request = first ? ask.slice(0, FIRST_PAGE) : ask;
+            first = false;
+            const start = this.sequence;
+            const page = await this.options.fetchPage(request, signal);
+            if (signal.aborted)
+                throw superseded();
+            const served = new Set();
+            const versions = Array.isArray(page.versions) ? page.versions : [];
+            const entities = Array.isArray(page.entities) ? page.entities : [];
+            versions.forEach((entry, index) => {
+                if (!entry || typeof entry.id !== 'string' || !request.includes(entry.id))
+                    return;
+                served.add(entry.id);
+                // A push after this page was sent is newer than the page.
+                if (this.changedSince(entry.id, start) || !this.listed?.has(entry.id))
+                    return;
+                const entity = entities[index];
+                if (!this.options.accept(entity, entry.id, entry.version)) {
+                    served.delete(entry.id);
+                    return;
+                }
+                this.rows.set(entry.id, { entity, version: entry.version });
+                // A page is newer than the listing it followed.
+                this.listed.set(entry.id, entry.version);
+                this.pending.delete(entry.id);
+                this.unstored.add(entry.id);
+                this.unstoredDeletes.delete(entry.id);
+            });
+            // Pages keep request order and stop at a byte cap: ids before the last served one that
+            // were not served are gone or unusable; the rest are asked next.
+            let last = -1;
+            request.forEach((id, index) => {
+                if (served.has(id))
+                    last = index;
+            });
+            const unserved = (last < 0 ? request : request.slice(0, last + 1)).filter((id) => !served.has(id) && !this.changedSince(id, start));
+            if (unserved.length)
+                missing = true;
+            const answered = new Set(last < 0 ? request : request.slice(0, last + 1));
+            ask = ask.filter((id) => !answered.has(id));
+            done += served.size;
+            this.options.onPage?.(Math.min(done, total), total);
+        }
+        return missing;
+    }
+    /** The listing must be read again: a change the client cannot place by itself. */
+    ask() {
+        this.membershipAskedAt = ++this.sequence;
+    }
+    /** A change without a usable body: read the id, or the listing when it does not hold the id. */
+    need(id) {
+        if (this.listed && !this.listed.has(id))
+            this.ask();
+        else
+            this.pending.add(id);
+    }
+    /** A pushed body. Returns false when it was not admitted; that id is then read. */
+    applyEntity(id, value, version) {
+        this.touch(id);
+        if (!this.options.accept(value, id, version)) {
+            this.need(id);
+            return false;
+        }
+        this.rows.set(id, { entity: value, version });
+        this.listed?.set(id, version);
+        this.pending.delete(id);
+        this.unstored.add(id);
+        this.unstoredDeletes.delete(id);
+        return true;
+    }
+    /** A change that names only the version: nothing to do when that version is held. */
+    applyVersion(id, version) {
+        this.touch(id);
+        if (this.rows.get(id)?.version === version) {
+            this.listed?.set(id, version);
+            this.pending.delete(id);
+        }
+        else
+            this.need(id);
+    }
+    /** A change with no body at all: read that id. */
+    applyUnknown(id) {
+        this.touch(id);
+        this.need(id);
+    }
+    applyDeleted(id) {
+        this.touch(id);
+        this.rows.delete(id);
+        this.listed?.delete(id);
+        this.pending.delete(id);
+        this.unstored.delete(id);
+        this.unstoredDeletes.add(id);
+    }
+    /** A collection change: its marker says whether membership or collection fields moved. */
+    noteMembership(marker) {
+        if (marker === undefined || !Number.isSafeInteger(marker)) {
+            this.ask();
+            return;
+        }
+        if (this.seenMarker === undefined || marker > this.seenMarker)
+            this.seenMarker = marker;
+    }
+    /** Stored rows from a previous session: admitted ones are shown, unverified, until a versions read. */
+    hydrate(rows) {
+        for (const row of rows) {
+            if (this.rows.has(row.id) || !this.options.accept(row.body, row.id, row.version))
+                continue;
+            this.rows.set(row.id, { entity: row.body, version: row.version });
+        }
+    }
+    /** Rows in the gateway's order: the listing's members once one exists, else every held row. */
+    assemble() {
+        if (!this.held)
+            return undefined;
+        if (!this.listed)
+            return [...this.rows.values()].map((row) => row.entity);
+        const entities = [];
+        for (const id of this.listed.keys()) {
+            const row = this.rows.get(id);
+            if (row)
+                entities.push(row.entity);
+        }
+        return entities;
+    }
+    /** Rows changed and removed since the last call, for one store merge. */
+    takeUnstored() {
+        const upserts = [...this.unstored].flatMap((id) => {
+            const row = this.rows.get(id);
+            return row ? [{ id, version: row.version, entity: row.entity }] : [];
+        });
+        const deletes = [...this.unstoredDeletes];
+        this.unstored.clear();
+        this.unstoredDeletes.clear();
+        return { upserts, deletes };
+    }
+    /** A new connection or epoch: keep the rows on screen, verify them before they count as current. */
+    unverify() {
+        this.inflight?.controller.abort();
+        this.inflight = undefined;
+        this.verified = false;
+        this.listedMarker = undefined;
+        this.seenMarker = undefined;
+        this.membershipAskedAt = undefined;
+        this.pending.clear();
+    }
+    /** Forget everything: a new store, owner or refusal. */
+    clear() {
+        this.unverify();
+        this.rows.clear();
+        this.listed = undefined;
+        this.touched.clear();
+        this.unstored.clear();
+        this.unstoredDeletes.clear();
+    }
+}
+//# sourceMappingURL=entity-collection.js.map

package/dist/client-cache/entity-collection.js.map

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

package/dist/client-cache/entity-guards.d.ts

@@ -0,0 +1,47 @@
+import type { PRStatus } from '../contracts/reviews.js';
+import type { MachineHealth, SlotEntity } from '../contracts/slots.js';
+/** An entity's version: sha256 of its canonical JSON, the same digest the gateway stores. */
+export declare function entityContentVersion(entity: unknown): string;
+/** A pushed entity rides on its notification only up to this many UTF-8 JSON bytes. */
+export declare const CHANGED_ENTITY_MAX_BYTES: number;
+/**
+ * The fields of a slot that summary, host-load reattachment, sorting and the slot views read
+ * without a check of their own; the gateway's row transform always fills them.
+ *
+ * This is the boundary of admission: identity, the fields list consumers dereference unguarded,
+ * and agent contexts by their declared type. Everything else is trusted from the current
+ * gateway. A refused row is read again.
+ */
+export declare function isSlotEntity(value: unknown): value is SlotEntity;
+/**
+ * The fields of a PR row the board, its filters and the project scopes read without a check,
+ * down to the elements they dereference: a check, a bot comment, a reviewer.
+ */
+export declare function isPRStatusEntity(value: unknown): value is PRStatus;
+/** The fields host-load reattachment and the machine bar read. */
+export declare function isMachineHealthEntity(value: unknown): value is MachineHealth;
+/** A PR's entity id within its list: `owner/repo/number`. */
+export declare function prEntityId(row: Pick<PRStatus, 'repo' | 'pr'>): string;
+/** Admits an untrusted body only when its shape, identity and content version all match. */
+export declare function admitEntity<T>(guard: (value: unknown) => value is T, idOf: (entity: T) => string, value: unknown, id: string, version: string): value is T;
+/** Most ids one entity read may name. */
+export declare const ENTITY_READ_MAX_IDS = 10000;
+/** A fleet.status or pr.list read: the view it reads and, for entity sync, its read shape. */
+export type EntitySyncRead = {
+    ok: true;
+    view: Record<string, unknown>;
+    shape?: {
+        versions: true;
+    } | {
+        ids: string[];
+    };
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * Splits `{ versions: true }` or `{ ids }` from the view params they read. Both shapes read the
+ * same resource as the view, so the gateway stamps and authorizes them as the view.
+ */
+export declare function entitySyncRead(params: unknown): EntitySyncRead;
+//# sourceMappingURL=entity-guards.d.ts.map

package/dist/client-cache/entity-guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-guards.d.ts","sourceRoot":"","sources":["../../src/client-cache/entity-guards.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAMvE,6FAA6F;AAC7F,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAE5D;AAED,uFAAuF;AACvF,eAAO,MAAM,wBAAwB,QAAY,CAAC;AAoElD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAyBhE;AAuBD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CA2BlE;AAED,kEAAkE;AAClE,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAW5E;AAED,6DAA6D;AAC7D,wBAAgB,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC,GAAG,MAAM,CAErE;AAED,4FAA4F;AAC5F,wBAAgB,WAAW,CAAC,CAAC,EAC3B,KAAK,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,KAAK,IAAI,CAAC,EACrC,IAAI,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,MAAM,EAC3B,KAAK,EAAE,OAAO,EACd,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,MAAM,GACd,KAAK,IAAI,CAAC,CAOZ;AAED,yCAAyC;AACzC,eAAO,MAAM,mBAAmB,QAAS,CAAC;AAE1C,8FAA8F;AAC9F,MAAM,MAAM,cAAc,GACtB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,KAAK,CAAC,EAAE;QAAE,QAAQ,EAAE,IAAI,CAAA;KAAE,GAAG;QAAE,GAAG,EAAE,MAAM,EAAE,CAAA;KAAE,CAAA;CAAE,GAC3F;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnC;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,GAAG,cAAc,CAoB9D"}

package/dist/client-cache/entity-guards.js

@@ -0,0 +1,193 @@
+// Entity sync (ADR-071 Amendment 4): stored, paged and pushed entities are untrusted. One set of
+// guards admits them: the shape every consumer dereferences, the identity and the content version.
+import { sha256 } from '@noble/hashes/sha256';
+import { bytesToHex } from '@noble/hashes/utils';
+import { AGENT_ROLES } from '../contracts/agents.js';
+import { canonicalResourceJson } from './keys.js';
+const encoder = new TextEncoder();
+/** An entity's version: sha256 of its canonical JSON, the same digest the gateway stores. */
+export function entityContentVersion(entity) {
+    return bytesToHex(sha256(encoder.encode(canonicalResourceJson(entity))));
+}
+/** A pushed entity rides on its notification only up to this many UTF-8 JSON bytes. */
+export const CHANGED_ENTITY_MAX_BYTES = 16 * 1024;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+const isString = (value) => typeof value === 'string';
+const isNumber = (value) => typeof value === 'number' && Number.isFinite(value);
+const isNullableString = (value) => value === null || typeof value === 'string';
+const everyOf = (value, each) => Array.isArray(value) && value.every(each);
+const absentOr = (value, check) => value === undefined || value === null || check(value);
+const AGENT_CONTEXT_STRINGS = [
+    'runId',
+    'taskFile',
+    'taskIdentity',
+    'signalFile',
+    'runner',
+    'model',
+    'nativeCommandId',
+    'lastSignalAt',
+    'updatedAt',
+];
+const isAgentContextTarget = (value) => isRecord(value) &&
+    isString(value.session) &&
+    isString(value.target) &&
+    absentOr(value.window, isString) &&
+    absentOr(value.pane, isString) &&
+    absentOr(value.paneId, isString);
+/** The fields of a native binding the slot view and its session lookups read. */
+const isNativeSessionBinding = (value) => isRecord(value) &&
+    isString(value.sessionId) &&
+    isString(value.executionNodeId) &&
+    isString(value.leaseId) &&
+    absentOr(value.closedAt, isString) &&
+    absentOr(value.releasedAt, isString);
+const isNativeSessionOwner = (value) => isRecord(value) &&
+    isString(value.contextId) &&
+    isString(value.sessionId) &&
+    isString(value.leaseId);
+/** An agent context summary, field by field by its declared type (AgentContextSummary). */
+function isAgentContextSummary(value) {
+    return (isRecord(value) &&
+        isString(value.id) &&
+        isString(value.label) &&
+        AGENT_ROLES.some((role) => role === value.role) &&
+        isString(value.status) &&
+        AGENT_CONTEXT_STRINGS.every((field) => absentOr(value[field], isString)) &&
+        absentOr(value.nudgeCount, isNumber) &&
+        absentOr(value.ctxPct, isNumber) &&
+        absentOr(value.target, isAgentContextTarget) &&
+        absentOr(value.nativeSession, isNativeSessionBinding) &&
+        absentOr(value.nativeSessionOwner, isNativeSessionOwner));
+}
+/**
+ * The fields of a slot that summary, host-load reattachment, sorting and the slot views read
+ * without a check of their own; the gateway's row transform always fills them.
+ *
+ * This is the boundary of admission: identity, the fields list consumers dereference unguarded,
+ * and agent contexts by their declared type. Everything else is trusted from the current
+ * gateway. A refused row is read again.
+ */
+export function isSlotEntity(value) {
+    if (!isRecord(value) || !isRecord(value.health))
+        return false;
+    const health = value.health;
+    return (isString(value.slot) &&
+        value.slot.length > 0 &&
+        isString(value.machine) &&
+        isString(value.platform) &&
+        isString(value.project) &&
+        isString(value.branch) &&
+        isString(value.agent) &&
+        isString(value.lifecycle) &&
+        isNullableString(value.phase) &&
+        typeof value.enabled === 'boolean' &&
+        typeof value.dispatchable === 'boolean' &&
+        typeof value.warm === 'boolean' &&
+        isString(health.ssh) &&
+        isString(health.device) &&
+        isString(health.devserver) &&
+        isString(health.cdp) &&
+        isString(health.fixtures) &&
+        absentOr(value.agentContexts, (contexts) => everyOf(contexts, isAgentContextSummary)) &&
+        // Host load is reattached from machine samples and never part of a slot entity.
+        value.hostLoad === undefined);
+}
+function isCheckSummary(value) {
+    return (isRecord(value) &&
+        isNumber(value.passed) &&
+        isNumber(value.failed) &&
+        isNumber(value.pending) &&
+        isNumber(value.skipped) &&
+        isNumber(value.total));
+}
+const isStrings = (value) => everyOf(value, isString);
+const isCheck = (value) => isRecord(value) && isString(value.name) && isString(value.status);
+const isBotComment = (value) => isRecord(value) && isString(value.author) && isString(value.createdAt);
+const isReviewVerdict = (value) => isRecord(value) && isString(value.reviewer) && isString(value.state);
+const isReviewRequests = (value) => isRecord(value) && isStrings(value.teams) && isStrings(value.users);
+/**
+ * The fields of a PR row the board, its filters and the project scopes read without a check,
+ * down to the elements they dereference: a check, a bot comment, a reviewer.
+ */
+export function isPRStatusEntity(value) {
+    return (isRecord(value) &&
+        isString(value.repo) &&
+        value.repo.length > 0 &&
+        isNumber(value.pr) &&
+        isString(value.title) &&
+        isString(value.project) &&
+        isString(value.prState) &&
+        isString(value.recommendation) &&
+        isString(value.mergeable) &&
+        isString(value.reviewDecision) &&
+        typeof value.allPassed === 'boolean' &&
+        typeof value.anyFailed === 'boolean' &&
+        typeof value.merged === 'boolean' &&
+        typeof value.mergeConflict === 'boolean' &&
+        everyOf(value.checks, isCheck) &&
+        isStrings(value.failedNames) &&
+        everyOf(value.botComments, isBotComment) &&
+        everyOf(value.actionableBotComments, isBotComment) &&
+        isCheckSummary(value.checkSummary) &&
+        absentOr(value.allCheckSummary, isCheckSummary) &&
+        absentOr(value.allPendingNames, isStrings) &&
+        absentOr(value.allFailedNames, isStrings) &&
+        absentOr(value.reviewVerdicts, (verdicts) => everyOf(verdicts, isReviewVerdict)) &&
+        absentOr(value.reviewRequests, isReviewRequests));
+}
+/** The fields host-load reattachment and the machine bar read. */
+export function isMachineHealthEntity(value) {
+    if (!isRecord(value) || !isString(value.machine) || !value.machine)
+        return false;
+    if (typeof value.online !== 'boolean' || !isString(value.headroom))
+        return false;
+    if (value.system === undefined)
+        return true;
+    const system = value.system;
+    return (isRecord(system) &&
+        isNumber(system.cpuPercent) &&
+        isNumber(system.memoryPercent) &&
+        isNumber(system.diskPercent));
+}
+/** A PR's entity id within its list: `owner/repo/number`. */
+export function prEntityId(row) {
+    return `${row.repo}/${row.pr}`;
+}
+/** Admits an untrusted body only when its shape, identity and content version all match. */
+export function admitEntity(guard, idOf, value, id, version) {
+    return (guard(value) &&
+        idOf(value) === id &&
+        typeof version === 'string' &&
+        entityContentVersion(value) === version);
+}
+/** Most ids one entity read may name. */
+export const ENTITY_READ_MAX_IDS = 10_000;
+/**
+ * Splits `{ versions: true }` or `{ ids }` from the view params they read. Both shapes read the
+ * same resource as the view, so the gateway stamps and authorizes them as the view.
+ */
+export function entitySyncRead(params) {
+    if (params === undefined || params === null)
+        return { ok: true, view: {} };
+    if (!isRecord(params))
+        return { ok: false, message: 'Read params must be an object' };
+    const { versions, ids, ...view } = params;
+    if (versions !== undefined && versions !== true)
+        return { ok: false, message: 'versions must be true or absent' };
+    if (ids !== undefined) {
+        if (versions !== undefined)
+            return { ok: false, message: 'Ask for versions or ids, not both' };
+        if (!Array.isArray(ids) ||
+            ids.length > ENTITY_READ_MAX_IDS ||
+            !ids.every((id) => typeof id === 'string' && id.length > 0 && id.length <= 1024))
+            return {
+                ok: false,
+                message: `ids must be at most ${ENTITY_READ_MAX_IDS} non-empty strings`,
+            };
+        return { ok: true, view, shape: { ids } };
+    }
+    return versions === true ? { ok: true, view, shape: { versions: true } } : { ok: true, view };
+}
+//# sourceMappingURL=entity-guards.js.map

package/dist/client-cache/entity-guards.js.map

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