@haverstack/core 0.41.0 → 0.43.0

package/dist/types/adapter.d.ts

@@ -0,0 +1,282 @@
+/**
+ * The storage adapter interfaces and the per-call options Stack hands them.
+ */
+import type { Association, AssociationEdit, AuthorityAssociation, DataAssociation } from './associations.js';
+import type { StackCapabilities } from './capabilities.js';
+import type { RecordChange, Unsubscribe, SubscribeOptions } from './events.js';
+import type { RecordId, TypeId, BaseId, FileId, AppId, EntityId, Actor } from './ids.js';
+import type { JournalEntryInput, RecordJournalEntry, JournalQuery } from './journal.js';
+import type { StackQuery, QuerySort, QueryResult } from './query.js';
+import type { StackRecord, RecordVersion, VersionsQuery } from './records.js';
+import type { StackType } from './schema.js';
+/**
+ * Opt-in optimistic-concurrency precondition. On mismatch the mutation
+ * throws StackVersionConflictError and changes nothing; an adapter checks
+ * it atomically inside its write. See docs/spec/versioning.md § Optimistic
+ * concurrency (`ifVersion`).
+ */
+export type IfVersionOptions = {
+    ifVersion?: number;
+};
+/**
+ * Accepted by every mutating StackRecordAdapter method. The adapter
+ * persists this prior-state snapshot as part of the SAME atomic write as
+ * the mutation, so a crash between the two can't leave an orphan versions
+ * row. Server-backed adapters (already atomic per-request) can ignore it.
+ */
+export type SnapshotOptions = {
+    snapshot?: RecordVersion;
+};
+/**
+ * Who is performing a mutation, stamped onto the record in the same write.
+ * `ScopedStack` supplies it from the request's identities; a caller of
+ * plain `Stack` supplies it only when reconstructing an attributed write.
+ * See docs/spec/data-model.md § Authorship and attribution.
+ */
+export type ActorOptions = {
+    actor?: Actor;
+};
+/**
+ * Accepted by every mutating StackRecordAdapter method. The adapter
+ * appends the entry, allocating its `seq`, inside the SAME write as the
+ * mutation, so a crash cannot leave a change unjournaled.
+ */
+export type JournalOptions = {
+    journal?: JournalEntryInput;
+};
+/**
+ * What every mutating StackRecordAdapter method that bumps `version` takes.
+ * deleteRecord() adds `purge`.
+ */
+export type MutateOptions = IfVersionOptions & SnapshotOptions & ActorOptions & JournalOptions;
+/**
+ * What every write that never bumps `version` takes: the precondition,
+ * checked atomically as a bumping write checks it, and the journal entry.
+ * No actor: such a write stamps nothing on the record, so its requester
+ * travels in the entry. See docs/spec/versioning.md § Version history.
+ */
+export type AspectWriteOptions = IfVersionOptions & JournalOptions;
+/**
+ * What the four element-set writes take: `expectSet` is the set `Stack`
+ * read and checked its rules against. An adapter compares it with the
+ * stored set inside its write and throws ElementSetMovedError on a
+ * mismatch, changing nothing. Omitted, the write is unconditional.
+ * See docs/spec/adapters.md § Editing associations.
+ */
+export type ElementWriteOptions<E extends Association> = AspectWriteOptions & {
+    expectSet?: readonly E[];
+};
+/** A named sort as an adapter receives it: `Stack` has resolved its `direction`. */
+export type AdapterSort = QuerySort & {
+    direction: 'asc' | 'desc';
+};
+/**
+ * A query without `presentAt`, which applies migrations — app code no
+ * adapter or server holds — with its defaults still open: what travels
+ * on the wire, and what resolveQuery() takes.
+ */
+export type PlainQuery = Omit<StackQuery, 'presentAt'>;
+/**
+ * A query as an adapter receives it, from resolveQuery(): every default
+ * resolved, so no adapter carries one. See docs/spec/data-model.md
+ * § Sorting and pagination.
+ */
+export type AdapterQuery = Omit<PlainQuery, 'sort' | 'limit'> & {
+    sort: AdapterSort;
+    limit: number;
+};
+/**
+ * The Records one scoped request may act on with one verb, as data matched
+ * rather than rules applied: inside `fence` and inside `within`, where an
+ * absent part constrains nothing. See docs/spec/access-control.md § Reach.
+ */
+export type Reach = {
+    /** Only Records in these families are in reach. */
+    fence?: BaseId[];
+    /** Records meeting one of these are in reach. */
+    within?: {
+        /** Every Record in these families. */
+        baseIds: BaseId[];
+        /** Records this subject authored in these families. */
+        authored?: {
+            subjectId: EntityId;
+            baseIds: BaseId[];
+        };
+        /** Records carrying every element of one of these sets, by association identity. */
+        permissions: AuthorityAssociation[][];
+    };
+};
+/** The metadata an upload's `_attachment@1` record carries beside its bytes. */
+export type PutAttachmentOptions = {
+    mimeType: string;
+    filename?: string;
+    /** Attribution for the metadata record, as create()'s `appId`. */
+    appId?: AppId;
+};
+/**
+ * The record-storage half of an adapter: structured data, queries,
+ * associations, versioning, type definitions, and stack identity.
+ */
+export interface StackRecordAdapter {
+    readonly capabilities: StackCapabilities;
+    /** DID of the stack owner. Set during adapter initialization. */
+    readonly ownerEntityId: EntityId;
+    /**
+     * IANA timezone string for this stack, or undefined if never set.
+     * Passthrough app metadata with no default — see docs/spec.md § The
+     * `_config` record.
+     */
+    readonly timezone: string | undefined;
+    /**
+     * Throws StackConflictError if `record.id` already exists — never a
+     * silent overwrite. The check must be atomic with the write (a PK/unique
+     * constraint or equivalent); Stack itself doesn't pre-check, so a raw
+     * adapter that skips this enforces nothing.
+     */
+    createRecord(record: StackRecord, opts?: JournalOptions): Promise<StackRecord>;
+    getRecord(id: RecordId): Promise<StackRecord | null>;
+    /**
+     * Merge a content patch, one level deep, into the content as it stands
+     * when the write lands. Bumps `version` and snapshots. Never touches
+     * `typeId`; see commitMigration(). See docs/spec/data-model.md § Mutations.
+     */
+    patchContent(id: RecordId, patch: Record<string, unknown | null>, opts?: MutateOptions): Promise<StackRecord>;
+    /**
+     * Returns the record this call acted on: as it now stands after a soft
+     * delete, and as it stood immediately before destruction after a
+     * purge — captured inside the same write, so nothing can observe or alter
+     * it in between. Null when there was no record to delete, which is the
+     * only case that mutates nothing.
+     */
+    deleteRecord(id: RecordId, opts?: {
+        purge?: boolean;
+    } & MutateOptions): Promise<StackRecord | null>;
+    /** Reverse a soft delete. Returns the record as it now stands. */
+    undeleteRecord(id: RecordId, opts?: MutateOptions): Promise<StackRecord>;
+    queryRecords(query: AdapterQuery): Promise<QueryResult>;
+    /**
+     * queryRecords() over the Records in `reach` alone: the reach is one
+     * more condition of the query, so the page, its cursor and whether one
+     * comes back are decided among those Records only. Optional — a stack
+     * whose adapter lacks it cannot be scoped, as a server-backed one never
+     * needs to be. See docs/spec/adapters.md § Querying within a reach.
+     */
+    queryReadable?(query: AdapterQuery, reach: Reach): Promise<QueryResult>;
+    /** `null` moves the record to the root. */
+    setParent(id: RecordId, parentId: RecordId | null, opts?: AspectWriteOptions): Promise<StackRecord>;
+    /** Stamps `unlistedAt` fresh on `true`; clears it on `false`. */
+    setUnlisted(id: RecordId, unlisted: boolean, opts?: AspectWriteOptions): Promise<StackRecord>;
+    /**
+     * Apply adds and removes to the record's data associations as one write.
+     * See docs/spec/adapters.md § Editing associations.
+     */
+    editAssociations(id: RecordId, edits: AssociationEdit[], opts?: ElementWriteOptions<DataAssociation>): Promise<StackRecord>;
+    /** Replace the record's data associations with exactly `associations`. */
+    setAssociations(id: RecordId, associations: DataAssociation[], opts?: ElementWriteOptions<DataAssociation>): Promise<StackRecord>;
+    /** editAssociations() over the record's permissions. */
+    editAccess(id: RecordId, edits: AssociationEdit[], opts?: ElementWriteOptions<AuthorityAssociation>): Promise<StackRecord>;
+    /** Replace the record's permissions with exactly `permissions`; `[]` is private. */
+    setAccess(id: RecordId, permissions: AuthorityAssociation[], opts?: ElementWriteOptions<AuthorityAssociation>): Promise<StackRecord>;
+    /**
+     * Snapshots newest first; omitting `query` reads every version.
+     * See docs/spec/versioning.md § Version history.
+     */
+    getVersions(id: RecordId, query?: VersionsQuery): Promise<RecordVersion[]>;
+    getVersion(id: RecordId, version: number): Promise<RecordVersion | null>;
+    /**
+     * Standalone snapshot write, outside of a mutation's own atomic path.
+     * Mutating methods above take a `snapshot` option instead, so the
+     * snapshot and the mutation land in one write — see SnapshotOptions.
+     */
+    saveVersion(id: RecordId, version: RecordVersion): Promise<void>;
+    /**
+     * Read a record's change journal, oldest first — required, on the same
+     * footing as getVersions(). A recovery mechanism an app cannot rely on is
+     * most of the way to no mechanism at all, so an adapter with no journal
+     * refuses the call rather than declining to have the method.
+     * See docs/spec/journal.md § Reading it.
+     */
+    getJournal(id: RecordId, query?: JournalQuery): Promise<RecordJournalEntry[]>;
+    /**
+     * Restore a record to a previous version's `content` and `typeId` —
+     * everything a snapshot carries. Containment, listing and associations
+     * are left where they stand, there being nothing to restore them *from*.
+     * Bumps version internally; throws StackNotFoundError if the version
+     * doesn't exist.
+     */
+    restoreVersion(id: RecordId, version: number, opts?: MutateOptions): Promise<StackRecord>;
+    /**
+     * Commit a migration: write new content under a new typeId in one step.
+     * This is the only way a record's typeId changes after creation — used by
+     * Stack.commitMigration() and Stack.migrateAll(); patchContent() never
+     * changes typeId as a side effect. Bumps version internally.
+     */
+    commitMigration(id: RecordId, toTypeId: TypeId, content: Record<string, unknown>, opts?: MutateOptions): Promise<StackRecord>;
+    saveType(type: StackType): Promise<void>;
+    getType(id: TypeId): Promise<StackType | null>;
+    listTypes(): Promise<StackType[]>;
+    /**
+     * Atomically verify fileId is unreferenced and purge its metadata
+     * records, returning them; StackConflictError if still referenced.
+     * Optional — Stack.deleteAttachment() has a non-atomic fallback.
+     * The metadata records are those in the `metadataBaseId` family, matched
+     * as `filter.baseId` matches one. See docs/spec/attachments.md § Deleting
+     * attachments.
+     */
+    deleteUnreferencedAttachmentRecords?(fileId: FileId, metadataBaseId: BaseId): Promise<StackRecord[]>;
+    /**
+     * Relay changes that originated elsewhere — the inverse direction from
+     * `Stack`, which emits every change made through it. Optional, and
+     * absent on every local adapter: exactly one process owns a stack's
+     * storage, so locally there is no third party whose writes could have
+     * been missed. See docs/spec/events.md § Where events come from.
+     */
+    subscribeChanges?(opts: SubscribeOptions, handler: (change: RecordChange) => void): Promise<Unsubscribe>;
+    flush?(): Promise<void>;
+    close?(): Promise<void>;
+}
+/** One stored blob, as reported by StackBlobAdapter.listBlobs(). */
+export type BlobInfo = {
+    fileId: FileId;
+    size: number;
+    /** When the blob was written. Used to apply a GC grace period to fresh, not-yet-associated uploads. */
+    modifiedAt: Date;
+};
+/**
+ * The blob-storage half of an adapter. Handles raw binary data only;
+ * attachment metadata lives on _attachment@1 records in the record adapter.
+ */
+export interface StackBlobAdapter {
+    putBlob(data: Uint8Array): Promise<FileId>;
+    /**
+     * Returns a plain `Uint8Array` (never a subclass such as `Buffer`) that the
+     * caller owns: changing it never changes the stored bytes.
+     */
+    getBlob(fileId: FileId): Promise<Uint8Array>;
+    deleteBlob(fileId: FileId): Promise<void>;
+    /**
+     * Enumerate every blob currently in storage. Optional — without it,
+     * garbage collection can't find bare-bytes orphans (bytes with no
+     * metadata record at all). See docs/spec/attachments.md § Garbage
+     * collection.
+     */
+    listBlobs?(): Promise<BlobInfo[]>;
+    flush?(): Promise<void>;
+    close?(): Promise<void>;
+}
+/**
+ * A complete adapter: record storage and blob storage combined.
+ * Pass this to Stack.open(). Build one with combineAdapters() when you
+ * want different backends for records and blobs (e.g. SQLite + S3).
+ */
+export type StackAdapter = StackRecordAdapter & StackBlobAdapter & {
+    /**
+     * Store bytes and create the accompanying _attachment@1 record as one
+     * atomic operation. Optional; implement only when bytes and records
+     * live behind a single boundary (today: APIAdapter alone), and never
+     * synthesized by combineAdapters(). A security boundary, not an
+     * efficiency shortcut — see docs/spec/adapters.md § Interface split.
+     */
+    putAttachmentWithMetadata?(data: Uint8Array, opts: PutAttachmentOptions): Promise<StackRecord>;
+};
+//# sourceMappingURL=adapter.d.ts.map

package/dist/types/adapter.d.ts.map

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

package/dist/types/adapter.js

@@ -0,0 +1,5 @@
+/**
+ * The storage adapter interfaces and the per-call options Stack hands them.
+ */
+export {};
+//# sourceMappingURL=adapter.js.map

package/dist/types/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../../src/types/adapter.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/types/associations.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Associations: the edges a Record carries, authority and data alike,
+ * and the change shapes that move them.
+ */
+import type { RecordId, FileId, EntityId } from './ids.js';
+export type TagAssociation = {
+    kind: 'tag';
+    label: string;
+};
+/**
+ * `attachmentRecordId` names the `_attachment` record whose upload
+ * established this reference — annotation, not identity, since `fileId`
+ * alone is what GC, the `referencesFileId` filter and file access ask
+ * about. See docs/spec/attachments.md § Naming the upload a reference came from.
+ */
+export type AttachmentAssociation = {
+    kind: 'attachment';
+    label: string;
+    fileId: FileId;
+    attachmentRecordId?: RecordId;
+};
+/**
+ * A Record in this stack, or in another one. `stackUrl` is what makes a
+ * RecordId meaningful outside the stack that minted it — absent means this
+ * stack. See docs/spec/data-model.md § Associations.
+ */
+export type RecordTarget = {
+    kind: 'record';
+    recordId: RecordId;
+    stackUrl?: string;
+};
+/**
+ * A "who" — a DID, which means the same thing in every stack. Group
+ * rosters are the canonical use: membership names identities, not records.
+ * See docs/spec/identity.md § Group.
+ */
+export type EntityTarget = {
+    kind: 'entity';
+    entityId: EntityId;
+};
+/**
+ * Something outside the stack entirely. `ns` names the scheme that
+ * interprets `id` — e.g. "atproto", "activitypub", "email", "url" — so an
+ * app selects on it rather than sniffing the identifier.
+ * See docs/spec/data-model.md § Relationship targets.
+ */
+export type ExternalTarget = {
+    kind: 'external';
+    ns: string;
+    id: string;
+};
+/** What a relationship association points at. */
+export type RelationshipTarget = RecordTarget | EntityTarget | ExternalTarget;
+export type RelationshipAssociation = {
+    kind: 'relationship';
+    label: string;
+    target: RelationshipTarget;
+};
+/**
+ * A grant of access to the Record carrying it. The bit is the label, so
+ * granting and revoking are a plain add and remove and the element's
+ * identity carries its whole meaning. Its grantee shape is its own rather
+ * than a `RelationshipTarget`: a target names no role and has no group
+ * arm. See docs/spec/access-control.md § Record-level permissions.
+ */
+export type PermissionAssociation = {
+    kind: 'permission';
+    label: 'read' | 'write';
+    grantee: Grantee;
+};
+/** An entity's standing within a `_group` Record's roster. `admin` implies `member` for ACL purposes. */
+export type GroupRole = 'member' | 'admin';
+/**
+ * The grantee arms both permission layers share, spelled identically so a
+ * value built for one is valid for the other. `role` is required — `member`
+ * is the wider set, `admin` the narrower, matching the roster labels where
+ * admin implies member. See docs/spec/access-control.md § Who a grant reaches.
+ */
+export type Grantee = {
+    kind: 'entity';
+    entityId: EntityId;
+} | {
+    kind: 'group';
+    groupId: RecordId;
+    role: GroupRole;
+};
+/**
+ * Reach to the world, spelled affirmatively: it names no grantee and
+ * carries no bit beyond `read`, so no dropped field on a
+ * `PermissionAssociation` can produce it.
+ * See docs/spec/access-control.md § Record-level permissions.
+ */
+export type AnyoneAssociation = {
+    kind: 'anyone';
+    label: 'read';
+};
+/**
+ * The authority half of the association table — what the `permissions`
+ * field projects. See docs/spec/access-control.md § Record-level
+ * permissions.
+ */
+export type AuthorityAssociation = PermissionAssociation | AnyoneAssociation;
+/**
+ * The data half — what the `associations` field projects, and the only
+ * kinds `editAssociations()`/`setAssociations()` accept.
+ * See docs/spec/data-model.md § Associations.
+ */
+export type DataAssociation = TagAssociation | AttachmentAssociation | RelationshipAssociation;
+/**
+ * Every edge a Record carries, authority and data alike. One shape, one
+ * delta and one durability tier; the two halves stay separate call
+ * surfaces because they carry different authority.
+ * See docs/spec/access-control.md § Record-level permissions.
+ */
+export type Association = DataAssociation | AuthorityAssociation;
+/**
+ * One association a write moved, and what it moved from. Each inverse is
+ * local to one element, so there is no join key to get wrong; `previous`
+ * is carried in full, which is what makes a `repoint` undoable.
+ * See docs/spec/journal.md § The entry.
+ */
+export type AssociationChange = {
+    op: 'add';
+    association: Association;
+} | {
+    op: 'repoint';
+    association: Association;
+    previous: Association;
+} | {
+    op: 'remove';
+    association: Association;
+};
+/**
+ * What a caller sends: the journal's shape without `repoint`, which the
+ * journal records and no caller requests. See docs/spec/journal.md § The entry.
+ */
+export type AssociationEdit = Exclude<AssociationChange, {
+    op: 'repoint';
+}>;
+//# sourceMappingURL=associations.d.ts.map

package/dist/types/associations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"associations.d.ts","sourceRoot":"","sources":["../../src/types/associations.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAE3D,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,EAAE,KAAK,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,IAAI,EAAE,YAAY,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,kBAAkB,CAAC,EAAE,QAAQ,CAAC;CAC/B,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,QAAQ,CAAC;IACf,QAAQ,EAAE,QAAQ,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,QAAQ,CAAC;IACf,QAAQ,EAAE,QAAQ,CAAC;CACpB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,EAAE,UAAU,CAAC;IACjB,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;CACZ,CAAC;AAEF,iDAAiD;AACjD,MAAM,MAAM,kBAAkB,GAAG,YAAY,GAAG,YAAY,GAAG,cAAc,CAAC;AAE9E,MAAM,MAAM,uBAAuB,GAAG;IACpC,IAAI,EAAE,cAAc,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,kBAAkB,CAAC;CAC5B,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,IAAI,EAAE,YAAY,CAAC;IACnB,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;IACxB,OAAO,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF,yGAAyG;AACzG,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE3C;;;;;GAKG;AACH,MAAM,MAAM,OAAO,GACf;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,GACtC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC;AAE1D;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,qBAAqB,GAAG,iBAAiB,CAAC;AAE7E;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,cAAc,GAAG,qBAAqB,GAAG,uBAAuB,CAAC;AAE/F;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,eAAe,GAAG,oBAAoB,CAAC;AAEjE;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GACzB;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,WAAW,EAAE,WAAW,CAAA;CAAE,GACvC;IAAE,EAAE,EAAE,SAAS,CAAC;IAAC,WAAW,EAAE,WAAW,CAAC;IAAC,QAAQ,EAAE,WAAW,CAAA;CAAE,GAClE;IAAE,EAAE,EAAE,QAAQ,CAAC;IAAC,WAAW,EAAE,WAAW,CAAA;CAAE,CAAC;AAE/C;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,OAAO,CAAC,iBAAiB,EAAE;IAAE,EAAE,EAAE,SAAS,CAAA;CAAE,CAAC,CAAC"}

package/dist/types/associations.js

@@ -0,0 +1,6 @@
+/**
+ * Associations: the edges a Record carries, authority and data alike,
+ * and the change shapes that move them.
+ */
+export {};
+//# sourceMappingURL=associations.js.map

package/dist/types/associations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"associations.js","sourceRoot":"","sources":["../../src/types/associations.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/types/capabilities.d.ts

@@ -0,0 +1,89 @@
+/**
+ * What a Stack and its adapter honor, and what a query can be refused for.
+ */
+import type { NativeSortField } from './query.js';
+/**
+ * How far into `content` a filter key may reach. The rungs nest, so they
+ * are one ordered value rather than booleans that can spell an impossible
+ * state. An unrecognized value reads as `'none'`: a refusal is recoverable,
+ * an unfiltered superset passed off as filtered is not.
+ * See docs/spec/adapters.md § Adapter capabilities.
+ */
+export type ContentFilterReach = 
+/** No `filter.content` and no `filter.contentPresent` at all. */
+'none'
+/** Single-segment field names only (`'did'`). */
+ | 'field'
+/** Multi-segment paths too (`'emails.value'`). */
+ | 'path';
+/**
+ * What a Stack — and the adapter under it — honors. Every `filter`/`sort`
+ * entry is named for the query key it gates, so the capability a query
+ * needs is derivable from the query. `limits` are numbers to pre-check
+ * against, not features. See docs/spec/adapters.md § Adapter capabilities.
+ */
+export type StackCapabilities = {
+    filter: {
+        /**
+         * Required `'path'` for local/in-process adapters; a wire adapter may
+         * report a shallower rung, driven by the server's discovery response.
+         * Stack.query() throws StackBadRequestError rather than silently widening.
+         */
+        content: ContentFilterReach;
+        /**
+         * Whether `filter.contentPresent` is honored. Beside the reach ladder,
+         * not on it: matching a value promises nothing about answering whether
+         * one is there. Meaningful only where `content` is not `'none'`.
+         */
+        contentPresent: boolean;
+        /**
+         * Whether `filter.contentByType` is honored. Local adapters must; a
+         * collection facing `false` queries its handle's version alone rather
+         * than failing. Meaningful only where `content` is not `'none'`. See
+         * docs/spec/adapters.md § Adapter capabilities.
+         */
+        contentByType: boolean;
+        /**
+         * Whether `filter.search` is honored. Not a rung on the ladder: a
+         * full-text index is a different mechanism from field matching, and
+         * neither implies the other. Local adapters may decline it.
+         */
+        search: boolean;
+    };
+    sort: {
+        /** Which native columns this adapter can order by; see NativeSortField. */
+        fields: NativeSortField[];
+        /**
+         * Whether `sort.contentField` is honored. A boolean rather than names
+         * in `fields`: an adapter that sorts by content indexes every top-level
+         * scalar. Independent of `filter.content`.
+         */
+        contentField: boolean;
+        /** Whether `sort.contentFieldByType` is honored, as `filter.contentByType`. */
+        contentFieldByType: boolean;
+    };
+    /**
+     * Ceilings a client can check before spending a request; the server's
+     * own limit stays authoritative. `null` means this client cannot
+     * pre-check, not that nothing is enforced — local adapters declare it.
+     * See docs/spec/adapters.md § Adapter capabilities.
+     */
+    limits: {
+        /** Maximum attachment upload size in bytes. */
+        attachmentBytes: number | null;
+        /**
+         * Maximum serialized size in bytes of a Record's content — a create
+         * body or a merge patch. Stack.create()/Stack.patchContent() pre-check
+         * against it and throw StackPayloadTooLargeError before sending.
+         */
+        contentBytes: number | null;
+    };
+};
+/**
+ * A capability a query can be refused for, as its path into
+ * StackCapabilities — the same name the spec and a discovery response
+ * use, so an error says which key to look at. `limits` never appears: a
+ * ceiling is not something a query can lack.
+ */
+export type MissingCapability = 'filter.content' | 'filter.contentPresent' | 'filter.contentByType' | 'filter.search' | 'sort.fields' | 'sort.contentField' | 'sort.contentFieldByType';
+//# sourceMappingURL=capabilities.d.ts.map

package/dist/types/capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../../src/types/capabilities.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB;AAC5B,iEAAiE;AAC/D,MAAM;AACR,iDAAiD;GAC/C,OAAO;AACT,kDAAkD;GAChD,MAAM,CAAC;AAEX;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,MAAM,EAAE;QACN;;;;WAIG;QACH,OAAO,EAAE,kBAAkB,CAAC;QAC5B;;;;WAIG;QACH,cAAc,EAAE,OAAO,CAAC;QACxB;;;;;WAKG;QACH,aAAa,EAAE,OAAO,CAAC;QACvB;;;;WAIG;QACH,MAAM,EAAE,OAAO,CAAC;KACjB,CAAC;IACF,IAAI,EAAE;QACJ,2EAA2E;QAC3E,MAAM,EAAE,eAAe,EAAE,CAAC;QAC1B;;;;WAIG;QACH,YAAY,EAAE,OAAO,CAAC;QACtB,+EAA+E;QAC/E,kBAAkB,EAAE,OAAO,CAAC;KAC7B,CAAC;IACF;;;;;OAKG;IACH,MAAM,EAAE;QACN,+CAA+C;QAC/C,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;QAC/B;;;;WAIG;QACH,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;KAC7B,CAAC;CACH,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GACzB,gBAAgB,GAChB,uBAAuB,GACvB,sBAAsB,GACtB,eAAe,GACf,aAAa,GACb,mBAAmB,GACnB,yBAAyB,CAAC"}

package/dist/types/capabilities.js

@@ -0,0 +1,5 @@
+/**
+ * What a Stack and its adapter honor, and what a query can be refused for.
+ */
+export {};
+//# sourceMappingURL=capabilities.js.map

package/dist/types/capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../../src/types/capabilities.ts"],"names":[],"mappings":"AAAA;;GAEG"}