@haverstack/core 0.41.0 → 0.43.0

package/dist/stack/integrity.js.map

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

package/dist/{limits.d.ts → stack/limits.d.ts}

@@ -13,11 +13,8 @@
 export declare function assertAttachmentSize(byteLength: number, attachmentBytes: number | null): void;
 /**
  * The content half of the same pre-check, on Stack.create() and
- * Stack.mutate(). Local adapters declare `limits.contentBytes: null` and skip
- * the serialization entirely; only a server declares a ceiling, and its
- * own request-size limit stays authoritative — this just spares an app the
- * round trip and gives it a typed failure instead of a 413 it has to
- * interpret. See docs/spec/wire-format.md § Request size limits.
+ * Stack.patchContent(). A `null` ceiling — every local adapter's — skips the
+ * serialization entirely.
  */
 export declare function assertContentSize(content: Record<string, unknown>, contentBytes: number | null, what: 'Content' | 'Patch'): void;
 //# sourceMappingURL=limits.d.ts.map

package/dist/stack/limits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.d.ts","sourceRoot":"","sources":["../../src/stack/limits.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,uEAAuE;AACvE,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAM7F;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,YAAY,EAAE,MAAM,GAAG,IAAI,EAC3B,IAAI,EAAE,SAAS,GAAG,OAAO,GACxB,IAAI,CAQN"}

package/dist/{limits.js → stack/limits.js}

@@ -9,7 +9,7 @@
  *
  * See docs/spec/wire-format.md § Request size limits.
  */
-import { StackPayloadTooLargeError } from './errors.js';
+import { StackPayloadTooLargeError } from '../errors.js';
 /** Shared by Stack.putAttachment() and ScopedStack.putAttachment(). */
 export function assertAttachmentSize(byteLength, attachmentBytes) {
     if (attachmentBytes !== null && byteLength > attachmentBytes) {
@@ -18,11 +18,8 @@ export function assertAttachmentSize(byteLength, attachmentBytes) {
 }
 /**
  * The content half of the same pre-check, on Stack.create() and
- * Stack.mutate(). Local adapters declare `limits.contentBytes: null` and skip
- * the serialization entirely; only a server declares a ceiling, and its
- * own request-size limit stays authoritative — this just spares an app the
- * round trip and gives it a typed failure instead of a 413 it has to
- * interpret. See docs/spec/wire-format.md § Request size limits.
+ * Stack.patchContent(). A `null` ceiling — every local adapter's — skips the
+ * serialization entirely.
  */
 export function assertContentSize(content, contentBytes, what) {
     if (contentBytes === null)

package/dist/stack/limits.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.js","sourceRoot":"","sources":["../../src/stack/limits.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAC;AAEzD,uEAAuE;AACvE,MAAM,UAAU,oBAAoB,CAAC,UAAkB,EAAE,eAA8B;IACrF,IAAI,eAAe,KAAK,IAAI,IAAI,UAAU,GAAG,eAAe,EAAE,CAAC;QAC7D,MAAM,IAAI,yBAAyB,CACjC,eAAe,UAAU,uBAAuB,eAAe,cAAc,CAC9E,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAC/B,OAAgC,EAChC,YAA2B,EAC3B,IAAyB;IAEzB,IAAI,YAAY,KAAK,IAAI;QAAE,OAAO;IAClC,MAAM,UAAU,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC;IAC5E,IAAI,UAAU,GAAG,YAAY,EAAE,CAAC;QAC9B,MAAM,IAAI,yBAAyB,CACjC,GAAG,IAAI,KAAK,UAAU,uBAAuB,YAAY,cAAc,CACxE,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/stack/migrations.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Migration registry
+ * -------------------------------------------------------
+ * The migrations a Stack was opened with, and what this app process
+ * understands of each type family. Answers two questions for the Stack:
+ * which chain carries a record from one TypeId to another (for
+ * migrateAll() and a collection's in-memory reads), and how a stored
+ * record reads at `presentAt: 'latest'` — never written back. See
+ * docs/spec/data-model.md § Type migrations.
+ */
+import type { StackRecord, TypeId } from '../types/index.js';
+import type { Migration } from '../type-handle.js';
+import type { FieldOrigins } from '../migration-steps.js';
+export declare class MigrationRegistry {
+    private readonly steps;
+    /**
+     * Highest version this instance has defineType()'d, per baseId — what
+     * this app process understands, as distinct from what exists in shared
+     * storage. Used to detect the stale-writer case in presentAtLatest().
+     */
+    private readonly maxDefinedVersion;
+    /**
+     * Refuses anything the walkers below could not follow. Each TypeId has at
+     * most one step out, so the graph is a set of chains, and a walk that
+     * comes back to a TypeId it already passed is a cycle.
+     */
+    constructor(migrations: readonly Migration[]);
+    /**
+     * Record that this instance has defined `version` of `baseId` — on the
+     * idempotent-no-op path too, since presentAtLatest()'s stale-writer
+     * detection depends on it.
+     */
+    noteDefined(baseId: string, version: number): void;
+    /**
+     * Find and compose a migration path from one TypeId to another.
+     * Returns null if no path exists.
+     */
+    path(fromId: TypeId, toId: TypeId): Migration['migrate'] | null;
+    /**
+     * What each of `toId`'s top-level fields is in terms of `fromId`'s,
+     * composed along the path between them. Null when there is no path, or
+     * when a step on it was not built by `migration()` and so declares
+     * nothing. See docs/spec/data-model.md § Content queries across versions.
+     */
+    origins(fromId: TypeId, toId: TypeId): FieldOrigins | null;
+    /**
+     * Find the latest registered version of a type family.
+     * Follows the migration chain from the given typeId to the end.
+     */
+    latest(fromId: TypeId): TypeId;
+    /**
+     * Apply the registered migration chain in memory, for presentAt:
+     * 'latest'. Never writes back. Throws StackMigrationError when the
+     * record's version can't be reconciled with what this instance has
+     * registered — the stale-writer case.
+     */
+    presentAtLatest(record: StackRecord): StackRecord;
+}
+//# sourceMappingURL=migrations.d.ts.map

package/dist/stack/migrations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrations.d.ts","sourceRoot":"","sources":["../../src/stack/migrations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAC7D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAEnD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAE1D,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgC;IACtD;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA6B;IAE/D;;;;OAIG;gBACS,UAAU,EAAE,SAAS,SAAS,EAAE;IAiC5C;;;;OAIG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAKlD;;;OAGG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC,SAAS,CAAC,GAAG,IAAI;IAgB/D;;;;;OAKG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IAY1D;;;OAGG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAQ9B;;;;;OAKG;IACH,eAAe,CAAC,MAAM,EAAE,WAAW,GAAG,WAAW;CA2BlD"}

package/dist/stack/migrations.js

@@ -0,0 +1,141 @@
+/**
+ * Migration registry
+ * -------------------------------------------------------
+ * The migrations a Stack was opened with, and what this app process
+ * understands of each type family. Answers two questions for the Stack:
+ * which chain carries a record from one TypeId to another (for
+ * migrateAll() and a collection's in-memory reads), and how a stored
+ * record reads at `presentAt: 'latest'` — never written back. See
+ * docs/spec/data-model.md § Type migrations.
+ */
+import { parseTypeId } from '../schema.js';
+import { StackMigrationError } from '../errors.js';
+import { composeOrigins, originsOf } from '../migration-steps.js';
+export class MigrationRegistry {
+    steps = new Map();
+    /**
+     * Highest version this instance has defineType()'d, per baseId — what
+     * this app process understands, as distinct from what exists in shared
+     * storage. Used to detect the stale-writer case in presentAtLatest().
+     */
+    maxDefinedVersion = new Map();
+    /**
+     * Refuses anything the walkers below could not follow. Each TypeId has at
+     * most one step out, so the graph is a set of chains, and a walk that
+     * comes back to a TypeId it already passed is a cycle.
+     */
+    constructor(migrations) {
+        for (const m of migrations) {
+            const from = parseTypeId(m.from);
+            const to = parseTypeId(m.to);
+            if (!from || !to) {
+                throw new StackMigrationError(`Migration "${m.from}" → "${m.to}" must name two versioned TypeIds.`);
+            }
+            if (from.baseId === to.baseId && to.version <= from.version) {
+                throw new StackMigrationError(`Migration "${m.from}" → "${m.to}" must go to a later version of its family.`);
+            }
+            if (this.steps.has(m.from)) {
+                throw new StackMigrationError(`More than one migration from "${m.from}" was passed.`);
+            }
+            this.steps.set(m.from, m);
+        }
+        const acyclic = new Set();
+        for (const start of this.steps.keys()) {
+            const walked = new Set();
+            for (let at = start; at && !acyclic.has(at);) {
+                if (walked.has(at)) {
+                    throw new StackMigrationError(`The migrations passed form a cycle through "${at}".`);
+                }
+                walked.add(at);
+                at = this.steps.get(at)?.to;
+            }
+            for (const id of walked)
+                acyclic.add(id);
+        }
+    }
+    /**
+     * Record that this instance has defined `version` of `baseId` — on the
+     * idempotent-no-op path too, since presentAtLatest()'s stale-writer
+     * detection depends on it.
+     */
+    noteDefined(baseId, version) {
+        const priorMax = this.maxDefinedVersion.get(baseId) ?? 0;
+        if (version > priorMax)
+            this.maxDefinedVersion.set(baseId, version);
+    }
+    /**
+     * Find and compose a migration path from one TypeId to another.
+     * Returns null if no path exists.
+     */
+    path(fromId, toId) {
+        if (fromId === toId)
+            return (content) => content;
+        const steps = [];
+        let current = fromId;
+        while (current !== toId) {
+            const step = this.steps.get(current);
+            if (!step)
+                return null;
+            steps.push(step);
+            current = step.to;
+        }
+        return (content) => steps.reduce((c, step) => step.migrate(c), content);
+    }
+    /**
+     * What each of `toId`'s top-level fields is in terms of `fromId`'s,
+     * composed along the path between them. Null when there is no path, or
+     * when a step on it was not built by `migration()` and so declares
+     * nothing. See docs/spec/data-model.md § Content queries across versions.
+     */
+    origins(fromId, toId) {
+        let composed = null;
+        for (let current = fromId; current !== toId;) {
+            const step = this.steps.get(current);
+            const origins = step && originsOf(step);
+            if (!origins)
+                return null;
+            composed = composed ? composeOrigins(composed, origins) : origins;
+            current = step.to;
+        }
+        return composed;
+    }
+    /**
+     * Find the latest registered version of a type family.
+     * Follows the migration chain from the given typeId to the end.
+     */
+    latest(fromId) {
+        let current = fromId;
+        for (let step = this.steps.get(current); step; step = this.steps.get(current)) {
+            current = step.to;
+        }
+        return current;
+    }
+    /**
+     * Apply the registered migration chain in memory, for presentAt:
+     * 'latest'. Never writes back. Throws StackMigrationError when the
+     * record's version can't be reconciled with what this instance has
+     * registered — the stale-writer case.
+     */
+    presentAtLatest(record) {
+        const latestId = this.latest(record.typeId);
+        if (latestId !== record.typeId) {
+            // latest() found this by walking the same migration graph path()
+            // walks, from the same starting point, so a path is always
+            // resolvable here.
+            const migrateFn = this.path(record.typeId, latestId);
+            return { ...record, typeId: latestId, content: migrateFn(record.content) };
+        }
+        const parsed = parseTypeId(record.typeId);
+        const knownMax = parsed ? this.maxDefinedVersion.get(parsed.baseId) : undefined;
+        if (parsed && knownMax !== undefined && parsed.version !== knownMax) {
+            const direction = parsed.version > knownMax
+                ? `the record is newer than this app instance understands — update the app, or pass it the missing migrations`
+                : `no migration passed to Stack.open() bridges the gap`;
+            throw new StackMigrationError(`Record "${record.id}" is at "${record.typeId}", but this app instance has defined ` +
+                `up to "${parsed.baseId}@${knownMax}": ${direction}. Omit presentAt: "latest" to ` +
+                `read the record as stored.`);
+        }
+        return record;
+    }
+}
+//# sourceMappingURL=migrations.js.map

package/dist/stack/migrations.js.map

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

package/dist/stack/reads.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Canned reads over a stack
+ * -------------------------------------------------------
+ * The internal call sites that need every match rather than a page —
+ * grant checks, attachment cleanup, DID resolution — expressed once. Most
+ * take the query function to run against, so the same read serves an
+ * unscoped `Stack` and a permission-filtered `ScopedStack` without either
+ * knowing which it got; the `_app` and `_install` reads must see past
+ * deletion and listing, so they take the unscoped `Stack` itself. Also the
+ * page-size bounds both classes' query() applies.
+ *
+ * None of these is a public API.
+ */
+import type { Stack } from './stack.js';
+import type { EntityId, GrantContent, GroupRole, InstallContent, QueryResult, RecordId, StackQuery, StackRecord } from '../types/index.js';
+/**
+ * Walks `cursor` to exhaustion for the internal call sites that need every
+ * match (grant checks, attachment cleanup) — query() itself always
+ * paginates. Throws StackBadRequestError past `max` rather than silently
+ * truncating a runaway scan. Not a public API.
+ */
+export declare function queryAllPages(run: (query: StackQuery) => Promise<QueryResult>, query: StackQuery, max?: number): Promise<StackRecord[]>;
+/**
+ * Cursor-walks `run(query)` looking for the first record matching
+ * `predicate`, short-circuiting on a match. Same bounded-scan discipline
+ * as queryAllPages(): a match past page one is still found, and a
+ * non-terminating scan throws StackBadRequestError.
+ */
+export declare function findFirstMatch(run: (query: StackQuery) => Promise<QueryResult>, query: StackQuery, predicate: (record: StackRecord) => boolean | Promise<boolean>, max?: number): Promise<StackRecord | undefined>;
+/**
+ * Shared implementation behind Stack.getEntityByDid() and
+ * ScopedStack.getEntityByDid() — see docs/spec/identity.md § DID bindings
+ * for the matching rules. `includeUnlisted` is a parameter rather than
+ * hardcoded, so a caller not permitted to set it can omit it instead of
+ * having query() throw.
+ */
+export declare function lookupEntityByDid(run: (query: StackQuery) => Promise<QueryResult>, did: EntityId, canFilterContent: boolean, includeUnlisted: boolean): Promise<StackRecord | null>;
+/**
+ * The `_app` card claiming `did`, deleted and unlisted included — the
+ * binding rules make it single-valued. Takes the unscoped Stack, since no
+ * scoped view may read past deletion and listing for everyone.
+ * See docs/spec/identity.md § DID bindings.
+ */
+export declare function findAppCardByDid(stack: Stack, did: EntityId): Promise<StackRecord | undefined>;
+/**
+ * Every `_install` Record, deleted and unlisted included — a deleted
+ * install keeps its claims. Takes the unscoped Stack, as findAppCardByDid().
+ */
+export declare function loadInstallRecords(stack: Stack): Promise<(StackRecord & {
+    content: InstallContent;
+})[]>;
+/**
+ * Every `_grant` Record, cursor-walked through an unscoped query: a grant
+ * decides who may read, so it can't sit behind a read check. Unlisted ones
+ * count, as listing decides nothing about what a grant confers; deleted
+ * ones don't, as soft-deleting is revoking. See docs/spec/unlisted.md.
+ */
+export declare function loadGrantRecords(run: (query: StackQuery) => Promise<QueryResult>): Promise<(StackRecord & {
+    content: GrantContent;
+})[]>;
+/**
+ * The role `entityId` holds on every roster that holds it, keyed by group
+ * id — the one reading of which rosters reach an entity. A roster is a
+ * live `_group`'s relationships: a Record outside the family or a deleted
+ * Group reaches nobody, and unlisted ones count, as for grants above. See
+ * docs/spec/access-control.md § Record-level permissions.
+ */
+export declare function loadRosterRoles(run: (query: StackQuery) => Promise<QueryResult>, entityId: EntityId): Promise<Map<RecordId, GroupRole>>;
+//# sourceMappingURL=reads.d.ts.map

package/dist/stack/reads.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reads.d.ts","sourceRoot":"","sources":["../../src/stack/reads.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,EAGV,QAAQ,EACR,YAAY,EACZ,SAAS,EACT,cAAc,EACd,WAAW,EACX,QAAQ,EACR,UAAU,EACV,WAAW,EACZ,MAAM,mBAAmB,CAAC;AAE3B;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAC,WAAW,CAAC,EAChD,KAAK,EAAE,UAAU,EACjB,GAAG,SAAgB,GAClB,OAAO,CAAC,WAAW,EAAE,CAAC,CAcxB;AAKD;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAC,WAAW,CAAC,EAChD,KAAK,EAAE,UAAU,EACjB,SAAS,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,EAC9D,GAAG,SAAgB,GAClB,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAiBlC;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAC,WAAW,CAAC,EAChD,GAAG,EAAE,QAAQ,EACb,gBAAgB,EAAE,OAAO,EACzB,eAAe,EAAE,OAAO,GACvB,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAc7B;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAa9F;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,KAAK,GACX,OAAO,CAAC,CAAC,WAAW,GAAG;IAAE,OAAO,EAAE,cAAc,CAAA;CAAE,CAAC,EAAE,CAAC,CAKxD;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAC,WAAW,CAAC,GAC/C,OAAO,CAAC,CAAC,WAAW,GAAG;IAAE,OAAO,EAAE,YAAY,CAAA;CAAE,CAAC,EAAE,CAAC,CAKtD;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAC,WAAW,CAAC,EAChD,QAAQ,EAAE,QAAQ,GACjB,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC,CAcnC"}

package/dist/stack/reads.js

@@ -0,0 +1,141 @@
+/**
+ * Canned reads over a stack
+ * -------------------------------------------------------
+ * The internal call sites that need every match rather than a page —
+ * grant checks, attachment cleanup, DID resolution — expressed once. Most
+ * take the query function to run against, so the same read serves an
+ * unscoped `Stack` and a permission-filtered `ScopedStack` without either
+ * knowing which it got; the `_app` and `_install` reads must see past
+ * deletion and listing, so they take the unscoped `Stack` itself. Also the
+ * page-size bounds both classes' query() applies.
+ *
+ * None of these is a public API.
+ */
+import { groupRoleFromAssociations } from '../access.js';
+import { StackBadRequestError } from '../errors.js';
+import { filtersContent } from '../query-validation.js';
+import { SYSTEM_TYPES } from '../types/index.js';
+/**
+ * Walks `cursor` to exhaustion for the internal call sites that need every
+ * match (grant checks, attachment cleanup) — query() itself always
+ * paginates. Throws StackBadRequestError past `max` rather than silently
+ * truncating a runaway scan. Not a public API.
+ */
+export async function queryAllPages(run, query, max = QUERY_ALL_MAX) {
+    const records = [];
+    let cursor = query.cursor;
+    do {
+        const page = await run({ ...query, cursor });
+        records.push(...page.records);
+        if (records.length > max) {
+            throw new StackBadRequestError(`queryAllPages: exceeded max of ${max} records without exhausting the cursor`);
+        }
+        cursor = page.cursor ?? undefined;
+    } while (cursor);
+    return records;
+}
+/** Safety cap for queryAllPages() — generous for personal-stack scale. */
+const QUERY_ALL_MAX = 10_000;
+/**
+ * Cursor-walks `run(query)` looking for the first record matching
+ * `predicate`, short-circuiting on a match. Same bounded-scan discipline
+ * as queryAllPages(): a match past page one is still found, and a
+ * non-terminating scan throws StackBadRequestError.
+ */
+export async function findFirstMatch(run, query, predicate, max = QUERY_ALL_MAX) {
+    let cursor = query.cursor;
+    let totalFetched = 0;
+    do {
+        const page = await run({ ...query, cursor });
+        totalFetched += page.records.length;
+        if (totalFetched > max) {
+            throw new StackBadRequestError(`findFirstMatch: exceeded max of ${max} records without exhausting the cursor`);
+        }
+        for (const record of page.records) {
+            if (await predicate(record))
+                return record;
+        }
+        cursor = page.cursor ?? undefined;
+    } while (cursor);
+    return undefined;
+}
+/**
+ * Shared implementation behind Stack.getEntityByDid() and
+ * ScopedStack.getEntityByDid() — see docs/spec/identity.md § DID bindings
+ * for the matching rules. `includeUnlisted` is a parameter rather than
+ * hardcoded, so a caller not permitted to set it can omit it instead of
+ * having query() throw.
+ */
+export async function lookupEntityByDid(run, did, canFilterContent, includeUnlisted) {
+    const record = await findFirstMatch(run, {
+        filter: {
+            baseId: SYSTEM_TYPES.ENTITY,
+            includeDeleted: true,
+            ...(includeUnlisted && { includeUnlisted: true }),
+            ...(canFilterContent && { content: { did } }),
+        },
+    }, (r) => r.content.did === did);
+    return record ?? null;
+}
+/**
+ * The `_app` card claiming `did`, deleted and unlisted included — the
+ * binding rules make it single-valued. Takes the unscoped Stack, since no
+ * scoped view may read past deletion and listing for everyone.
+ * See docs/spec/identity.md § DID bindings.
+ */
+export function findAppCardByDid(stack, did) {
+    return findFirstMatch((q) => stack.query(q), {
+        filter: {
+            baseId: SYSTEM_TYPES.APP,
+            includeDeleted: true,
+            includeUnlisted: true,
+            ...(filtersContent(stack.capabilities) && { content: { did } }),
+        },
+    }, (r) => r.content.did === did);
+}
+/**
+ * Every `_install` Record, deleted and unlisted included — a deleted
+ * install keeps its claims. Takes the unscoped Stack, as findAppCardByDid().
+ */
+export async function loadInstallRecords(stack) {
+    const records = await queryAllPages((q) => stack.query(q), {
+        filter: { baseId: SYSTEM_TYPES.INSTALL, includeDeleted: true, includeUnlisted: true },
+    });
+    return records;
+}
+/**
+ * Every `_grant` Record, cursor-walked through an unscoped query: a grant
+ * decides who may read, so it can't sit behind a read check. Unlisted ones
+ * count, as listing decides nothing about what a grant confers; deleted
+ * ones don't, as soft-deleting is revoking. See docs/spec/unlisted.md.
+ */
+export async function loadGrantRecords(run) {
+    const records = await queryAllPages(run, {
+        filter: { typeId: `${SYSTEM_TYPES.GRANT}@1`, includeUnlisted: true },
+    });
+    return records;
+}
+/**
+ * The role `entityId` holds on every roster that holds it, keyed by group
+ * id — the one reading of which rosters reach an entity. A roster is a
+ * live `_group`'s relationships: a Record outside the family or a deleted
+ * Group reaches nobody, and unlisted ones count, as for grants above. See
+ * docs/spec/access-control.md § Record-level permissions.
+ */
+export async function loadRosterRoles(run, entityId) {
+    const groups = await queryAllPages(run, {
+        filter: {
+            baseId: SYSTEM_TYPES.GROUP,
+            relatedTo: { target: { kind: 'entity', entityId } },
+            includeUnlisted: true,
+        },
+    });
+    const roles = new Map();
+    for (const group of groups) {
+        const role = groupRoleFromAssociations(group.associations, entityId);
+        if (role)
+            roles.set(group.id, role);
+    }
+    return roles;
+}
+//# sourceMappingURL=reads.js.map

package/dist/stack/reads.js.map

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

package/dist/stack/record-id.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Record ID and clock-field validation
+ * -------------------------------------------------------
+ * The rules a caller-supplied `id`, `parentId`, `createdAt` or `updatedAt`
+ * is held to before any of them reaches storage. A client may mint its own
+ * id and backdate a record's clock, so both are untrusted input here even
+ * when the types say otherwise.
+ *
+ * See docs/spec/data-model.md § Record IDs.
+ */
+import type { ValidationError } from '../validate.js';
+export declare const DEFAULT_ID_TIMESTAMP_SKEW_MS: number;
+/**
+ * Format and reserved-prefix checks for a caller-supplied id, reported
+ * under `field` — `parentId` when the id names a destination rather than
+ * the record being written. The prefix is asked first so "_config" gets a
+ * specific refusal. StackBadRequestError, not StackValidationError: a
+ * malformed id never reaches schema validation.
+ */
+export declare function validateRecordId(id: string, field?: string): void;
+/**
+ * Validity and range check for a backdated `createdAt`/`updatedAt`. An
+ * Invalid Date would switch the ordering and skew checks off rather than
+ * fail them, and one outside an id's encodable range has no id to agree
+ * with. See docs/spec/data-model.md § Backdating on import.
+ */
+export declare function validateClockField(value: Date | undefined, path: string): ValidationError[];
+/**
+ * Whether an id's embedded timestamp is within `skewMs` of `reference`:
+ * the current time for a live scoped create, where it stops a grantee
+ * forging a sort position, or an explicit `createdAt`, which the id must
+ * agree with. Pass null to disable. See docs/spec/data-model.md § Record IDs.
+ */
+export declare function validateIdTimestampSkew(id: string, toleranceMs: number | null, referenceMs: number, referenceLabel: string): void;
+//# sourceMappingURL=record-id.d.ts.map

package/dist/stack/record-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-id.d.ts","sourceRoot":"","sources":["../../src/stack/record-id.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAOtD,eAAO,MAAM,4BAA4B,QAAsB,CAAC;AAEhE;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,SAAO,GAAG,IAAI,CAW/D;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,IAAI,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,eAAe,EAAE,CAuB3F;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,EAAE,EAAE,MAAM,EACV,WAAW,EAAE,MAAM,GAAG,IAAI,EAC1B,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE,MAAM,GACrB,IAAI,CAcN"}

package/dist/stack/record-id.js

@@ -0,0 +1,82 @@
+/**
+ * Record ID and clock-field validation
+ * -------------------------------------------------------
+ * The rules a caller-supplied `id`, `parentId`, `createdAt` or `updatedAt`
+ * is held to before any of them reaches storage. A client may mint its own
+ * id and backdate a record's clock, so both are untrusted input here even
+ * when the types say otherwise.
+ *
+ * See docs/spec/data-model.md § Record IDs.
+ */
+import { isValidIdFormat, idTimestamp, MAX_ID_TIMESTAMP } from '../id.js';
+import { ARGUMENTS_INVALID, StackBadRequestError, StackValidationError } from '../errors.js';
+// -------------------------------------------------------
+// Record ID validation
+// -------------------------------------------------------
+const RESERVED_ID_PREFIX = '_';
+export const DEFAULT_ID_TIMESTAMP_SKEW_MS = 24 * 60 * 60 * 1000;
+/**
+ * Format and reserved-prefix checks for a caller-supplied id, reported
+ * under `field` — `parentId` when the id names a destination rather than
+ * the record being written. The prefix is asked first so "_config" gets a
+ * specific refusal. StackBadRequestError, not StackValidationError: a
+ * malformed id never reaches schema validation.
+ */
+export function validateRecordId(id, field = 'ID') {
+    if (id.startsWith(RESERVED_ID_PREFIX)) {
+        throw new StackBadRequestError(`Invalid ${field} "${id}": uses the reserved "${RESERVED_ID_PREFIX}" prefix.`);
+    }
+    if (!isValidIdFormat(id)) {
+        throw new StackBadRequestError(`Invalid ${field} "${id}": expected 12 lowercase Crockford base-32 characters.`);
+    }
+}
+/**
+ * Validity and range check for a backdated `createdAt`/`updatedAt`. An
+ * Invalid Date would switch the ordering and skew checks off rather than
+ * fail them, and one outside an id's encodable range has no id to agree
+ * with. See docs/spec/data-model.md § Backdating on import.
+ */
+export function validateClockField(value, path) {
+    if (value === undefined)
+        return [];
+    // Reachable from the wire, where JSON has no Date: a forwarded request
+    // body hands over an ISO string, which must be a 400 naming the field
+    // rather than a TypeError from the getTime() below.
+    if (!(value instanceof Date)) {
+        return [{ path, message: `${path} must be a Date.` }];
+    }
+    const ms = value.getTime();
+    if (Number.isNaN(ms)) {
+        return [{ path, message: `${path} is not a valid Date.` }];
+    }
+    if (ms < 0 || ms > MAX_ID_TIMESTAMP) {
+        return [
+            {
+                path,
+                message: `${path} is outside the representable range ` +
+                    `(1970-01-01T00:00:00.000Z…${new Date(MAX_ID_TIMESTAMP).toISOString()}).`,
+            },
+        ];
+    }
+    return [];
+}
+/**
+ * Whether an id's embedded timestamp is within `skewMs` of `reference`:
+ * the current time for a live scoped create, where it stops a grantee
+ * forging a sort position, or an explicit `createdAt`, which the id must
+ * agree with. Pass null to disable. See docs/spec/data-model.md § Record IDs.
+ */
+export function validateIdTimestampSkew(id, toleranceMs, referenceMs, referenceLabel) {
+    if (toleranceMs === null)
+        return;
+    const skew = Math.abs(referenceMs - idTimestamp(id));
+    if (skew > toleranceMs) {
+        throw new StackValidationError([
+            {
+                path: 'id',
+                message: `ID "${id}" timestamp disagrees with ${referenceLabel} by more than the allowed clock-skew tolerance (${toleranceMs}ms).`,
+            },
+        ], ARGUMENTS_INVALID);
+    }
+}
+//# sourceMappingURL=record-id.js.map

package/dist/stack/record-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-id.js","sourceRoot":"","sources":["../../src/stack/record-id.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAC1E,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAG7F,0DAA0D;AAC1D,uBAAuB;AACvB,0DAA0D;AAE1D,MAAM,kBAAkB,GAAG,GAAG,CAAC;AAC/B,MAAM,CAAC,MAAM,4BAA4B,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAEhE;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,EAAU,EAAE,KAAK,GAAG,IAAI;IACvD,IAAI,EAAE,CAAC,UAAU,CAAC,kBAAkB,CAAC,EAAE,CAAC;QACtC,MAAM,IAAI,oBAAoB,CAC5B,WAAW,KAAK,KAAK,EAAE,yBAAyB,kBAAkB,WAAW,CAC9E,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,eAAe,CAAC,EAAE,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,oBAAoB,CAC5B,WAAW,KAAK,KAAK,EAAE,wDAAwD,CAChF,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAuB,EAAE,IAAY;IACtE,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IACnC,uEAAuE;IACvE,sEAAsE;IACtE,oDAAoD;IACpD,IAAI,CAAC,CAAC,KAAK,YAAY,IAAI,CAAC,EAAE,CAAC;QAC7B,OAAO,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,kBAAkB,EAAE,CAAC,CAAC;IACxD,CAAC;IACD,MAAM,EAAE,GAAG,KAAK,CAAC,OAAO,EAAE,CAAC;IAC3B,IAAI,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC;QACrB,OAAO,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,uBAAuB,EAAE,CAAC,CAAC;IAC7D,CAAC;IACD,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,GAAG,gBAAgB,EAAE,CAAC;QACpC,OAAO;YACL;gBACE,IAAI;gBACJ,OAAO,EACL,GAAG,IAAI,sCAAsC;oBAC7C,6BAA6B,IAAI,IAAI,CAAC,gBAAgB,CAAC,CAAC,WAAW,EAAE,IAAI;aAC5E;SACF,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CACrC,EAAU,EACV,WAA0B,EAC1B,WAAmB,EACnB,cAAsB;IAEtB,IAAI,WAAW,KAAK,IAAI;QAAE,OAAO;IACjC,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,WAAW,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC;IACrD,IAAI,IAAI,GAAG,WAAW,EAAE,CAAC;QACvB,MAAM,IAAI,oBAAoB,CAC5B;YACE;gBACE,IAAI,EAAE,IAAI;gBACV,OAAO,EAAE,OAAO,EAAE,8BAA8B,cAAc,mDAAmD,WAAW,MAAM;aACnI;SACF,EACD,iBAAiB,CAClB,CAAC;IACJ,CAAC;AACH,CAAC"}