@haverstack/core 0.40.0 → 0.42.0

package/dist/associations/validation.js

@@ -0,0 +1,339 @@
+/**
+ * Association validation
+ * -------------------------------------------------------
+ * The rules an association is held to before it is stored: a known kind,
+ * only the keys that kind defines, a well-formed target or grantee, the
+ * right half of the authority/data partition, and each identity named
+ * once. A discriminated union is a compile-time promise, and a server
+ * mapping a request body onto one supplies raw JSON no compiler has seen,
+ * so the rules live in the invariant layer where no adapter can forget
+ * one. See docs/spec/data-model.md § Associations.
+ */
+import { ARGUMENTS_INVALID, StackBadRequestError, StackValidationError } from '../errors.js';
+import { associationEqual, isAuthorityAssociation } from './identity.js';
+/** The identifier spaces a relationship target may name. */
+const TARGET_KINDS = new Set(['record', 'entity', 'external']);
+/**
+ * The keys of one arm of a union, listed as an object so the compiler
+ * holds the list to the type: a field added to the arm fails to compile
+ * here until it is listed.
+ */
+const keysOf = (keys) => Object.keys(keys);
+/** Every key each relationship target arm defines. */
+export const TARGET_KEYS = {
+    record: keysOf({ kind: true, recordId: true, stackUrl: true }),
+    entity: keysOf({ kind: true, entityId: true }),
+    external: keysOf({ kind: true, ns: true, id: true }),
+};
+/** Every key each association kind defines. */
+const ASSOCIATION_KEYS = {
+    tag: keysOf({ kind: true, label: true }),
+    attachment: keysOf({
+        kind: true,
+        label: true,
+        fileId: true,
+        attachmentRecordId: true,
+    }),
+    relationship: keysOf({ kind: true, label: true, target: true }),
+    permission: keysOf({ kind: true, label: true, grantee: true }),
+    anyone: keysOf({ kind: true, label: true }),
+};
+/** Every key each grantee arm defines, the default tier included. */
+export const GRANTEE_KEYS = {
+    entity: keysOf({ kind: true, entityId: true }),
+    group: keysOf({ kind: true, groupId: true, role: true }),
+    authenticated: keysOf({ kind: true }),
+};
+/**
+ * The keys of `value` its arm does not define. An element carrying one is
+ * refused rather than stored: an adapter keeps only the keys it has
+ * columns for, so the rest would answer 200 and then vanish.
+ * See docs/spec/data-model.md § Associations.
+ */
+export function unknownKeys(value, keys) {
+    return Object.keys(value).filter((key) => !keys.includes(key));
+}
+/** unknownKeys() as a refusal. 400, not 422: the key addresses nothing. */
+export function assertKnownKeys(value, keys, path) {
+    const unknown = unknownKeys(value, keys);
+    if (unknown.length > 0)
+        throw new StackBadRequestError(`Unknown key${unknown.length > 1 ? 's' : ''} in ${path}: ${unknown.join(', ')}`);
+}
+/**
+ * Collect what makes a relationship target malformed. Absence is
+ * meaningful on `stackUrl` and an external `id` — this stack, and the
+ * whole namespace — so every part that names something must be non-empty:
+ * an empty string stores and matches as though it were absent.
+ * See docs/spec/data-model.md § Relationship targets.
+ */
+export function targetErrors(target, path, opts = {}) {
+    const fail = (message) => [{ path, message }];
+    if (!target || typeof target !== 'object')
+        return fail('A relationship target must be an object.');
+    if (!TARGET_KINDS.has(target.kind)) {
+        return fail(`Unknown relationship target kind "${target.kind}": expected "record", "entity" or "external".`);
+    }
+    assertKnownKeys(target, TARGET_KEYS[target.kind], path);
+    if (target.kind === 'record') {
+        if (!target.recordId)
+            return fail('A record target requires a non-empty recordId.');
+        if (target.stackUrl !== undefined && !target.stackUrl) {
+            return fail("A record target's stackUrl must be non-empty; omit it to name this stack.");
+        }
+        return [];
+    }
+    if (target.kind === 'entity') {
+        return target.entityId ? [] : fail('An entity target requires a non-empty entityId.');
+    }
+    if (!target.ns)
+        return fail('An external target requires a non-empty ns.');
+    if (target.id === undefined) {
+        return opts.externalIdOptional ? [] : fail('An external target requires an id.');
+    }
+    return target.id ? [] : fail("An external target's id must be non-empty when present.");
+}
+/** The kinds an association may name — the closed set every surface reads. */
+const ASSOCIATION_KINDS = new Set(['tag', 'attachment', 'relationship', 'permission', 'anyone']);
+/**
+ * Whether a value is an association at all. Asked ahead of the partition
+ * checks, so a malformed element is named as one rather than reported as
+ * the wrong surface for a kind it never had — a request body supplies raw
+ * JSON, and `null` or `{}` is neither half of the partition.
+ */
+function namesKind(association) {
+    return (!!association &&
+        typeof association === 'object' &&
+        ASSOCIATION_KINDS.has(association.kind));
+}
+/**
+ * Reject an association outside the closed set the types promise: a request
+ * body is raw JSON, and an unknown target kind would otherwise be stored as
+ * a Record in this stack. A key its kind does not define is a 400 at every
+ * depth, as on a request body. See docs/spec/data-model.md § Associations.
+ */
+export function validateAssociation(association, path = 'association') {
+    if (!namesKind(association)) {
+        return [
+            {
+                path: `${path}.kind`,
+                message: `Unknown association kind "${String(association?.kind)}": expected ${[...ASSOCIATION_KINDS].map((k) => `"${k}"`).join(', ')}.`,
+            },
+        ];
+    }
+    assertKnownKeys(association, ASSOCIATION_KEYS[association.kind], path);
+    if (association.kind === 'permission') {
+        return permissionErrors(association, path);
+    }
+    if (association.kind === 'anyone') {
+        return association.label === 'read'
+            ? []
+            : [{ path: `${path}.label`, message: 'An `anyone` association carries only `read`.' }];
+    }
+    if (association.kind !== 'relationship')
+        return [];
+    return targetErrors(association.target, `${path}.target`);
+}
+/**
+ * Who a duplicated permission names, since kind and label alone don't
+ * distinguish two grants of the same bit to different grantees.
+ */
+function granteeSuffix(association) {
+    if (association.kind !== 'permission')
+        return '';
+    const g = association.grantee;
+    return g.kind === 'entity' ? ` for "${g.entityId}"` : ` for ${g.role}s of "${g.groupId}"`;
+}
+/** The bits a permission element may name — the whole of its meaning. */
+const PERMISSION_LABELS = new Set(['read', 'write']);
+/** A permission element's label and grantee — see granteeErrors(). */
+function permissionErrors(association, path) {
+    if (!PERMISSION_LABELS.has(association.label)) {
+        return [
+            {
+                path: `${path}.label`,
+                message: `Unknown permission label "${association.label}": expected "read" or "write".`,
+            },
+        ];
+    }
+    const grantee = association.grantee;
+    if (!grantee || typeof grantee !== 'object') {
+        return [{ path: `${path}.grantee`, message: 'A permission requires a grantee.' }];
+    }
+    return granteeErrors(grantee, `${path}.grantee`, { unknownKeys: 'throw' });
+}
+/**
+ * What makes a grantee malformed, under `path`: first a key its tier does not
+ * define — a 400 under `throw`, as on a request body, or collected on a
+ * stored `_grant` — then its tier's own fields. `role` has no default to fall
+ * back on. `authenticated` is a `_grant` tier alone; `anyRole` admits `'any'`.
+ */
+export function granteeErrors(grantee, path, opts) {
+    const g = (grantee ?? {});
+    const tier = g.kind === 'entity' || g.kind === 'group' || (opts.authenticated && g.kind === 'authenticated')
+        ? g.kind
+        : null;
+    if (tier === null) {
+        return [
+            {
+                path: `${path}.kind`,
+                message: opts.authenticated
+                    ? "A grantee must name its tier: 'entity', 'group' or 'authenticated'."
+                    : "A grantee must name its tier: 'entity' or 'group'.",
+            },
+        ];
+    }
+    if (opts.unknownKeys === 'throw')
+        assertKnownKeys(g, GRANTEE_KEYS[tier], path);
+    const unknown = unknownKeys(g, GRANTEE_KEYS[tier]);
+    if (unknown.length > 0) {
+        const article = tier === 'group' ? 'A' : 'An';
+        return unknown.map((key) => ({
+            path: `${path}.${key}`,
+            message: `${article} ${tier} grantee does not carry ${key}.`,
+        }));
+    }
+    if (tier === 'authenticated')
+        return [];
+    if (tier === 'entity') {
+        return typeof g.entityId === 'string' && g.entityId.length > 0
+            ? []
+            : [{ path: `${path}.entityId`, message: 'An entity grantee requires a non-empty entityId.' }];
+    }
+    const errors = [];
+    if (typeof g.groupId !== 'string' || g.groupId.length === 0) {
+        errors.push({
+            path: `${path}.groupId`,
+            message: 'A group grantee requires a non-empty groupId.',
+        });
+    }
+    if (g.role !== 'member' && g.role !== 'admin' && !(opts.anyRole && g.role === 'any')) {
+        errors.push({
+            path: `${path}.role`,
+            message: opts.anyRole
+                ? "A group grantee requires role 'member', 'admin' or 'any'."
+                : "A group grantee requires role 'member' or 'admin'.",
+        });
+    }
+    return errors;
+}
+/**
+ * Refuse an authority element on the data surface. The two halves share
+ * storage but never a call, or an app editing tags could replace an ACL it
+ * was never shown. Thrown, not collected: the caller named the wrong
+ * surface, and wanted grantAccess()/revokeAccess().
+ * See docs/spec/access-control.md § Record-level permissions.
+ */
+export function assertDataAssociations(associations, surface) {
+    const authority = associations.find((a) => namesKind(a) && isAuthorityAssociation(a));
+    if (!authority)
+        return;
+    throw new StackBadRequestError(`${surface} does not carry authority: a "${authority.kind}" association belongs to the ` +
+        '`permissions` surface — use grantAccess()/revokeAccess(), or the `permissions` change-set key.');
+}
+/**
+ * The mirror of assertDataAssociations(): the `permissions` surface takes
+ * authority kinds alone, so a tag routed through it is refused rather than
+ * quietly becoming an ACL entry the `associations` projection never shows.
+ */
+export function assertAuthorityAssociations(permissions, surface) {
+    const data = permissions.find((a) => namesKind(a) && !isAuthorityAssociation(a));
+    if (!data)
+        return;
+    throw new StackBadRequestError(`${surface} carries authority alone: a "${data.kind}" association belongs to the ` +
+        '`associations` surface — use associate()/dissociate(), or the `associations` change-set key.');
+}
+/**
+ * Every association in a list, plus the list's own rule: identities are
+ * distinct. An adapter keys associations by identity, so a repeat would
+ * displace the first and leave which one stands to chance — a caller bug,
+ * refused rather than collapsed. See docs/spec/data-model.md § Associations.
+ */
+export function validateAssociations(associations, path = 'associations') {
+    const list = associations ?? [];
+    return [
+        ...list.flatMap((a, i) => validateAssociation(a, `${path}[${i}]`)),
+        ...duplicateIdentityErrors(list, path),
+    ];
+}
+/** Each element naming an identity an earlier element already named. */
+function duplicateIdentityErrors(list, path) {
+    return list.flatMap((a, i) => list.slice(0, i).some((b) => associationEqual(a, b))
+        ? [
+            {
+                path: `${path}[${i}]`,
+                message: `Duplicate association identity: ${a.kind} "${a.label}"${granteeSuffix(a)} is named more than once.`,
+            },
+        ]
+        : []);
+}
+/**
+ * Hold an edit list to the rules every verb shares: non-empty, known `op`s
+ * over well-formed associations, one surface, each identity once — removing
+ * and adding one identity is as ambiguous as naming it twice. `repoint` is
+ * the journal's word, never a request. See docs/spec/data-model.md § Mutations.
+ */
+export function assertAssociationEdits(changes, surface, half) {
+    if (!Array.isArray(changes) || changes.length === 0) {
+        throw new StackValidationError([{ path: 'changes', message: `${surface} names at least one change.` }], ARGUMENTS_INVALID);
+    }
+    const errors = [];
+    changes.forEach((raw, i) => {
+        const path = `changes[${i}]`;
+        if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+            errors.push({ path, message: `${path} must be an object.` });
+            return;
+        }
+        const edit = raw;
+        if (edit.op !== 'repoint')
+            assertKnownKeys(edit, ['op', 'association'], path);
+        if (edit.op === 'repoint') {
+            errors.push({
+                path: `${path}.op`,
+                message: 'op: "repoint" is recorded by the journal, not requested. ' +
+                    "Send { op: 'add', association }: an add naming an attachment the record already holds re-points it in place.",
+            });
+        }
+        else if (edit.op !== 'add' && edit.op !== 'remove') {
+            errors.push({ path: `${path}.op`, message: 'op must be "add" or "remove".' });
+        }
+        errors.push(...validateAssociation(edit.association, `${path}.association`));
+    });
+    if (errors.length > 0)
+        throw new StackValidationError(errors, ARGUMENTS_INVALID);
+    const associations = changes.map((c) => c.association);
+    if (half === 'data')
+        assertDataAssociations(associations, surface);
+    else
+        assertAuthorityAssociations(associations, surface);
+    const duplicates = duplicateIdentityErrors(associations, 'changes');
+    if (duplicates.length > 0)
+        throw new StackValidationError(duplicates, ARGUMENTS_INVALID);
+}
+/**
+ * assertAssociationEdits() for the verbs taking a bare list — associate(),
+ * grantAccess() and their inverses — asked before wrapping, so problems are
+ * reported under `param`, the name the caller used. Same order of checks,
+ * so a wrong-surface element is refused as such before duplicates count.
+ */
+export function assertAssociationList(associations, surface, param, half) {
+    if (!Array.isArray(associations) || associations.length === 0) {
+        throw new StackValidationError([{ path: param, message: `${surface} names at least one association.` }], ARGUMENTS_INVALID);
+    }
+    const errors = associations.flatMap((raw, i) => typeof raw === 'object' && raw !== null && !Array.isArray(raw)
+        ? []
+        : [{ path: `${param}[${i}]`, message: `${param}[${i}] must be an object.` }]);
+    if (errors.length > 0)
+        throw new StackValidationError(errors, ARGUMENTS_INVALID);
+    const list = associations;
+    const shapeErrors = list.flatMap((a, i) => validateAssociation(a, `${param}[${i}]`));
+    if (shapeErrors.length > 0)
+        throw new StackValidationError(shapeErrors, ARGUMENTS_INVALID);
+    if (half === 'data')
+        assertDataAssociations(list, surface);
+    else
+        assertAuthorityAssociations(list, surface);
+    const listErrors = validateAssociations(list, param);
+    if (listErrors.length > 0)
+        throw new StackValidationError(listErrors, ARGUMENTS_INVALID);
+}
+//# sourceMappingURL=validation.js.map

package/dist/associations/validation.js.map

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

package/dist/attachment-records.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Attachment metadata records
+ * -------------------------------------------------------
+ * Which of a fileId's `_attachment` records answers for it: the one that
+ * establishes its mimeType, and the one a given reference names. Pure and
+ * generic over the record shape, so `Stack` and a server's own rows reach
+ * the same answer — `@haverstack/core/wire` exports the selections, and
+ * this module imports nothing so that entry point stays light.
+ */
+/**
+ * Which `_attachment@1` record establishes a fileId's mimeType: earliest
+ * `createdAt`, ties to the lower `id`. Two racing first uploads can both
+ * land, so determinism rests on core's conflict check and every server
+ * ordering through here. The caller filters to one fileId.
+ * See docs/spec/attachments.md § Finding a `fileId`'s metadata records.
+ */
+export declare function firstRecordedAttachment<T extends {
+    id: string;
+    createdAt: Date;
+}>(records: readonly T[]): T | undefined;
+/**
+ * The same total order as a comparator, for a caller handing back the whole
+ * candidate set rather than the winner — sorted this way, the winner is
+ * element zero. Package-internal: `core/wire` exports the selection,
+ * since the ordering is only useful to something that already has every
+ * record.
+ */
+export declare function compareRecordedAttachments<T extends {
+    id: string;
+    createdAt: Date;
+}>(a: T, b: T): number;
+/**
+ * Which `_attachment` record a *reference* to a fileId names: its
+ * `attachmentRecordId`, else the requester's own upload, else the
+ * first-recorded — each step falling back rather than failing.
+ * See docs/spec/attachments.md § Naming the upload a reference came from.
+ */
+export declare function resolveReferencedAttachment<T extends {
+    id: string;
+    createdAt: Date;
+    createdBy?: {
+        subjectId: string;
+    };
+}>(records: readonly T[], opts?: {
+    attachmentRecordId?: string;
+    requesterEntityId?: string;
+}): T | undefined;
+//# sourceMappingURL=attachment-records.d.ts.map

package/dist/attachment-records.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachment-records.d.ts","sourceRoot":"","sources":["../src/attachment-records.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,SAAS;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,IAAI,CAAA;CAAE,EAC/E,OAAO,EAAE,SAAS,CAAC,EAAE,GACpB,CAAC,GAAG,SAAS,CAKf;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,CAAC,SAAS;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,IAAI,CAAA;CAAE,EAClF,CAAC,EAAE,CAAC,EACJ,CAAC,EAAE,CAAC,GACH,MAAM,CAIR;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CACzC,CAAC,SAAS;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,IAAI,CAAC;IAAC,SAAS,CAAC,EAAE;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,EAE5E,OAAO,EAAE,SAAS,CAAC,EAAE,EACrB,IAAI,GAAE;IAAE,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAAC,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAAO,GACrE,CAAC,GAAG,SAAS,CAUf"}

package/dist/attachment-records.js

@@ -0,0 +1,52 @@
+/**
+ * Attachment metadata records
+ * -------------------------------------------------------
+ * Which of a fileId's `_attachment` records answers for it: the one that
+ * establishes its mimeType, and the one a given reference names. Pure and
+ * generic over the record shape, so `Stack` and a server's own rows reach
+ * the same answer — `@haverstack/core/wire` exports the selections, and
+ * this module imports nothing so that entry point stays light.
+ */
+/**
+ * Which `_attachment@1` record establishes a fileId's mimeType: earliest
+ * `createdAt`, ties to the lower `id`. Two racing first uploads can both
+ * land, so determinism rests on core's conflict check and every server
+ * ordering through here. The caller filters to one fileId.
+ * See docs/spec/attachments.md § Finding a `fileId`'s metadata records.
+ */
+export function firstRecordedAttachment(records) {
+    return records.reduce((first, record) => (!first || compareRecordedAttachments(record, first) < 0 ? record : first), undefined);
+}
+/**
+ * The same total order as a comparator, for a caller handing back the whole
+ * candidate set rather than the winner — sorted this way, the winner is
+ * element zero. Package-internal: `core/wire` exports the selection,
+ * since the ordering is only useful to something that already has every
+ * record.
+ */
+export function compareRecordedAttachments(a, b) {
+    const delta = a.createdAt.getTime() - b.createdAt.getTime();
+    if (delta !== 0)
+        return delta;
+    return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+}
+/**
+ * Which `_attachment` record a *reference* to a fileId names: its
+ * `attachmentRecordId`, else the requester's own upload, else the
+ * first-recorded — each step falling back rather than failing.
+ * See docs/spec/attachments.md § Naming the upload a reference came from.
+ */
+export function resolveReferencedAttachment(records, opts = {}) {
+    if (opts.attachmentRecordId) {
+        const named = records.find((record) => record.id === opts.attachmentRecordId);
+        if (named)
+            return named;
+    }
+    if (opts.requesterEntityId) {
+        const own = records.filter((record) => record.createdBy?.subjectId === opts.requesterEntityId);
+        if (own.length > 0)
+            return firstRecordedAttachment(own);
+    }
+    return firstRecordedAttachment(records);
+}
+//# sourceMappingURL=attachment-records.js.map

package/dist/attachment-records.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachment-records.js","sourceRoot":"","sources":["../src/attachment-records.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;GAMG;AACH,MAAM,UAAU,uBAAuB,CACrC,OAAqB;IAErB,OAAO,OAAO,CAAC,MAAM,CACnB,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,IAAI,0BAA0B,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,EAC7F,SAAS,CACV,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,0BAA0B,CACxC,CAAI,EACJ,CAAI;IAEJ,MAAM,KAAK,GAAG,CAAC,CAAC,SAAS,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC;IAC5D,IAAI,KAAK,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC9B,OAAO,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAChD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,2BAA2B,CAGzC,OAAqB,EACrB,OAAoE,EAAE;IAEtE,IAAI,IAAI,CAAC,kBAAkB,EAAE,CAAC;QAC5B,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,EAAE,KAAK,IAAI,CAAC,kBAAkB,CAAC,CAAC;QAC9E,IAAI,KAAK;YAAE,OAAO,KAAK,CAAC;IAC1B,CAAC;IACD,IAAI,IAAI,CAAC,iBAAiB,EAAE,CAAC;QAC3B,MAAM,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,SAAS,EAAE,SAAS,KAAK,IAAI,CAAC,iBAAiB,CAAC,CAAC;QAC/F,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,uBAAuB,CAAC,GAAG,CAAC,CAAC;IAC1D,CAAC;IACD,OAAO,uBAAuB,CAAC,OAAO,CAAC,CAAC;AAC1C,CAAC"}

package/dist/collection.d.ts

@@ -0,0 +1,182 @@
+/**
+ * Collections — typed access to one type family
+ * -------------------------------------------------------
+ * `client.collection(handle)` returns a `Collection<C>`: every verb that
+ * addresses records of the handle's family, each taking and returning the
+ * handle's content type with one signature. Implemented once over the
+ * public `StackClient` verbs, so `Stack` and `ScopedStack` share it and a
+ * collection can do nothing its client could not.
+ *
+ * The collection's scope is the handle's whole family. Each record is read
+ * as stored and migrated in memory to the handle's version, one at a time,
+ * so a record the handle cannot represent — one stored at a newer version —
+ * is reported as a misfit rather than failing the page it sits on. A
+ * content write to a record at an older version commits its migration as a
+ * write of its own first. See docs/spec/data-model.md § Type handles.
+ */
+import type { MigrationRegistry } from './stack/migrations.js';
+import type { CreateRecordOptions, DeleteRecordOptions, DeleteResult, StackClient } from './stack/client.js';
+import type { ContentOf, ReadonlyTypeSchema, TypeHandle, UnlistedValue } from './type-handle.js';
+import type { AssociationEdit, AuthorityAssociation, ChangeFilter, DataAssociation, IfVersionOptions, NativeSortField, RecordChange, RecordChangeSet, RecordFilter, RecordId, StackQuery, StackType, StackRecord, SubscribeOptions, Unsubscribe } from './types/index.js';
+/**
+ * Content `C` as a read returns it: an enum may hold a value the handle
+ * does not list, since an enum can widen in place. Never flattens `C`, so
+ * an app that names its content with an `interface` keeps that name.
+ */
+export type StoredContent<C> = C extends string ? string extends C ? C : C | UnlistedValue : C extends readonly (infer I)[] ? StoredContent<I>[] : C extends object ? {
+    [K in keyof C]: StoredContent<C[K]>;
+} : C;
+/**
+ * The `contentPatch` content `C` accepts: every field optional, and `null`
+ * (removal) only on a field that is optional in `C`.
+ */
+export type ContentPatch<C> = {
+    [K in keyof C]?: Pick<C, K> extends Required<Pick<C, K>> ? C[K] : Exclude<C[K], undefined> | null;
+};
+/** A record of the collection, migrated to the handle's version. */
+export interface CollectionRecord<C> extends Omit<StackRecord, 'content'> {
+    content: StoredContent<C>;
+}
+/**
+ * A record in the handle's family that the handle cannot represent. Stored
+ * at a version newer than the handle's, it cannot be migrated down.
+ */
+export type Misfit = {
+    id: RecordId;
+    reason: 'newer-version';
+    /** Untyped, as stored. */
+    record: StackRecord;
+};
+/**
+ * A page of a collection. Misfits do not count as records, so a page can
+ * hold fewer than `limit` records with a cursor still set: the results end
+ * when `cursor` is `null`, not when a page comes back short.
+ */
+export type CollectionPage<C> = {
+    records: CollectionRecord<C>[];
+    misfits: Misfit[];
+    cursor: string | null;
+    /**
+     * Set when records at a version a content filter or sort could not reach
+     * match, or may match, the rest of the query. On the first page only,
+     * since it depends on the query rather than the page. See
+     * docs/spec/data-model.md § Content queries across versions.
+     */
+    skipped?: {
+        older: boolean;
+        newer: boolean;
+    };
+};
+/**
+ * Path typing stops at this depth and accepts any suffix below it, since a
+ * recursive path type otherwise exceeds the compiler's instantiation limit.
+ * A typing limit, not a query limit: see docs/spec/data-model.md § Nested
+ * content paths.
+ */
+type PathDepth = [never, 0, 1, 2, 3, 4];
+/** What a filter value can equal: an adapter compares the value a path reaches. */
+type Leaf = string | number | boolean;
+/**
+ * Each content path of `V` reached at `P`, paired with the value a filter
+ * compares there. An array is matched element-wise, so it is its element.
+ * An object never equals a filter value, so its path takes only `null`.
+ */
+type PathEntry<P extends string, V, D extends number> = [D] extends [never] ? [P | `${P}.${string}`, Leaf] : V extends readonly (infer E)[] ? unknown extends E ? [P | `${P}.${string}`, Leaf] : PathEntry<P, E, PathDepth[D]> : V extends object ? string extends keyof V ? [P, null] | [`${P}.${string}`, Leaf] : [P, null] | FieldEntry<V, `${P}.`, PathDepth[D]> : [P, V];
+/** `Required<C>[K]` rather than `NonNullable`, which would leak into errors. */
+type FieldEntry<C, Prefix extends string, D extends number> = [D] extends [never] ? [`${Prefix}${string}`, Leaf] : {
+    [K in keyof C & string]-?: PathEntry<`${Prefix}${K}`, Required<C>[K], D>;
+}[keyof C & string];
+/**
+ * Every content path of `C`: its fields, and dotted paths through declared
+ * objects and arrays. Below an `open` object or array, or six segments
+ * deep, any suffix is a path.
+ */
+export type ContentPathOf<C> = FieldEntry<C, '', 5>[0];
+/** The top-level scalar fields of `C`, the ones a content sort reaches. */
+export type SortableFieldOf<C> = string extends keyof C ? string : {
+    [K in keyof C & string]-?: Required<C>[K] extends string | number | boolean ? K : never;
+}[keyof C & string];
+/**
+ * A collection reads live records of its own family only, as stored, so
+ * none of `typeId`, `baseId`, `includeDeleted`, `presentAt` or the per-Type
+ * shapes it generates itself is offered. Content filter keys and the sort
+ * field are checked against `C`, and carried to older versions through the
+ * migrations. See docs/spec/data-model.md § Type handles.
+ */
+export type CollectionQuery<C> = Omit<StackQuery, 'filter' | 'presentAt' | 'sort'> & {
+    filter?: Omit<RecordFilter, 'typeId' | 'baseId' | 'includeDeleted' | 'content' | 'contentPresent' | 'contentByType'> & {
+        content?: {
+            [E in FieldEntry<C, '', 5> as E[0]]?: E[1] | null;
+        };
+        contentPresent?: ContentPathOf<C>[];
+    };
+    sort?: {
+        field: NativeSortField;
+        contentField?: never;
+        direction?: 'asc' | 'desc';
+    } | {
+        field?: never;
+        contentField: SortableFieldOf<C>;
+        direction?: 'asc' | 'desc';
+    };
+};
+/** The family is the collection's, so neither `typeId` nor `baseId` is a filter key. */
+export type CollectionSubscribeOptions = Omit<SubscribeOptions, 'filter'> & {
+    filter?: Omit<ChangeFilter, 'typeId' | 'baseId'>;
+};
+/**
+ * A change to a record of the family. `record`, when present, is migrated
+ * to the handle's version; `typeId` stays the stored one. A change whose
+ * record does not fit carries `misfit` instead, and one whose record is a
+ * tombstone carries neither.
+ */
+export type CollectionChange<C> = Omit<RecordChange, 'record'> & {
+    record?: CollectionRecord<C>;
+    misfit?: Misfit;
+};
+export type CollectionChangeSet<C> = Omit<RecordChangeSet, 'contentPatch'> & {
+    contentPatch?: ContentPatch<C>;
+};
+/**
+ * Typed access to one type family. History (`getVersions`, `getVersion`,
+ * `getJournal`) spans versions by nature and stays on `StackClient`. See
+ * docs/spec/data-model.md § Type handles.
+ */
+export interface Collection<C> {
+    /** `null` for a missing record, a tombstone, or a record of another family. */
+    get(id: RecordId): Promise<CollectionRecord<C> | null>;
+    query(query?: CollectionQuery<C>): Promise<CollectionPage<C>>;
+    subscribe(handler: (change: CollectionChange<C>) => void, opts?: CollectionSubscribeOptions): Promise<Unsubscribe>;
+    create(content: C, opts?: CreateRecordOptions): Promise<CollectionRecord<C>>;
+    mutate(id: RecordId, changes: CollectionChangeSet<C>, opts?: IfVersionOptions): Promise<CollectionRecord<C>>;
+    patchContent(id: RecordId, patch: ContentPatch<C>, opts?: IfVersionOptions): Promise<CollectionRecord<C>>;
+    associate(id: RecordId, associations: DataAssociation[]): Promise<CollectionRecord<C>>;
+    dissociate(id: RecordId, associations: DataAssociation[]): Promise<CollectionRecord<C>>;
+    amendAssociations(id: RecordId, changes: AssociationEdit[]): Promise<CollectionRecord<C>>;
+    grantAccess(id: RecordId, permissions: AuthorityAssociation[]): Promise<CollectionRecord<C>>;
+    revokeAccess(id: RecordId, permissions: AuthorityAssociation[]): Promise<CollectionRecord<C>>;
+    amendAccess(id: RecordId, changes: AssociationEdit[]): Promise<CollectionRecord<C>>;
+    delete(id: RecordId, opts?: DeleteRecordOptions): Promise<DeleteResult>;
+    undelete(id: RecordId, opts?: IfVersionOptions): Promise<CollectionRecord<C>>;
+    restoreVersion(id: RecordId, version: number, opts?: IfVersionOptions): Promise<CollectionRecord<C>>;
+}
+/**
+ * A record the collection asked for does not fit the handle. Raised only
+ * in the app's own process and never on the wire, so it sits outside the
+ * `StackError` taxonomy. A write that raises it after writing says so.
+ * See docs/spec/wire-format.md § The taxonomy root.
+ */
+export declare class MisfitError extends Error {
+    readonly reason: Misfit['reason'];
+    readonly record: StackRecord;
+    constructor(misfit: Misfit, handle: TypeHandle, written?: boolean);
+}
+/**
+ * The collection over `handle`, shared by `Stack.collection()` and
+ * `ScopedStack.collection()`. `registry` is the opening `Stack`'s, which
+ * the app's own process filled. `listTypes` names the family's versions,
+ * which `StackClient` does not offer.
+ */
+export declare const createCollection: <S extends ReadonlyTypeSchema>(client: StackClient, registry: MigrationRegistry, handle: TypeHandle<S>, listTypes: () => Promise<StackType[]>) => Collection<ContentOf<S>>;
+export {};
+//# sourceMappingURL=collection.d.ts.map