@haverstack/core 0.41.0 → 0.43.0

package/dist/types/events.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Change events: what `subscribe()` delivers and the options it takes.
+ */
+import type { DataAssociation } from './associations.js';
+import type { RecordId, TypeId, AppId, Actor } from './ids.js';
+import type { RecordFilter } from './query.js';
+import type { StackRecord } from './records.js';
+/**
+ * The coarse branch every subscriber makes, closed at four values. A
+ * handler covering exactly these is complete, not merely adequate:
+ * `changed` is an upsert signal carrying nine distinct verbs.
+ * See docs/spec/events.md § The event shape.
+ */
+export type ChangeKind = 'created' | 'changed' | 'removed' | 'purged';
+/**
+ * The precise verb behind a ChangeKind, for consumers that distinguish a
+ * reshare from an edit. Each is named after the call that produced it; see
+ * docs/spec/events.md § The event shape for the three that aren't a method
+ * name. `associate`, `dissociate`, `reshare`, `reparent`, `unlist` and
+ * `list` don't bump; see docs/spec/versioning.md § Version history.
+ */
+export type ChangeOp = 'create' | 'patch' | 'associate' | 'dissociate' | 'reshare' | 'migrate' | 'restore' | 'delete' | 'undelete' | 'purge'
+/**
+ * Emitted even though the record's post-change state (`unlistedAt` now
+ * set) would otherwise be excluded by the same filter it announces —
+ * subscribers who already know the record need telling to drop it. See
+ * docs/spec/events.md § The unlisted transition.
+ */
+ | 'unlist'
+/** The publish moment — mechanically an upsert, like `undelete`. */
+ | 'list'
+/**
+ * A move between containers. Matched by a `parentId` filter naming
+ * *either* side of the move, so a subscriber watching the old container
+ * learns the record left it — the record's post-change state alone
+ * would answer only for the destination. See docs/spec/events.md
+ * § The reparent transition.
+ */
+ | 'reparent';
+/**
+ * Who performed a change — never who authored the record. Absent from a
+ * RecordChange entirely when unknown, which means a write by an unscoped
+ * `Stack`: absence is a fact of its own and never stands in for the
+ * author. See docs/spec/events.md § Attribution.
+ */
+export type ChangeActor = Actor & {
+    /** Self-reported at create, never a trust input. See AppId. */
+    appId?: AppId;
+};
+/**
+ * One change to one record. The envelope describes the change; the record
+ * describes the record, so nothing of the record's own provenance appears
+ * here — a consumer that wants it asks for `record`.
+ * See docs/spec/events.md § The event shape.
+ */
+export type RecordChange = {
+    kind: ChangeKind;
+    /**
+     * Every aspect this version moved, diffed against prior state rather
+     * than read off the request. Never empty; multi-entry only for an
+     * association write that both adds and removes.
+     * See docs/spec/events.md § The event shape.
+     */
+    ops: ChangeOp[];
+    recordId: RecordId;
+    /** As stored at the moment of the change. */
+    typeId: TypeId;
+    /**
+     * The version this change produced; on `purged`, the version destroyed.
+     * Unchanged from the record's prior version on every op that doesn't
+     * bump — see ChangeOp.
+     */
+    version: number;
+    /**
+     * As persisted by this change; on `purged`, when the delete ran.
+     * Unchanged from the record's prior `updatedAt` on every op that
+     * doesn't bump.
+     */
+    updatedAt: Date;
+    parentId?: RecordId;
+    actor?: ChangeActor;
+    /**
+     * Associations now present that weren't before — current annotation
+     * included, so a re-point appears here under its new
+     * `attachmentRecordId`. Present whenever `ops` includes `associate`, on
+     * the same "as of this change" convention as every other field here.
+     */
+    associationsAdded?: DataAssociation[];
+    /**
+     * Associations no longer present, identity only — kind and label, plus
+     * `fileId` for an attachment — present whenever `ops` includes
+     * `dissociate`. An attachment's `attachmentRecordId` is never repeated
+     * here, the same way a `purged` frame never carries what it destroyed.
+     */
+    associationsRemoved?: DataAssociation[];
+    /**
+     * The record as of this change — present only when asked for and
+     * available, never on `purged`. Shared with every other subscriber on
+     * this emission, so a handler that needs to alter it copies first.
+     */
+    record?: StackRecord;
+    /**
+     * Resume cursor, minted by a server. Local changes carry none, this
+     * stack's own writes included — so a consumer holding a cursor keeps
+     * the last one that was present rather than the last change's.
+     */
+    cursor?: string;
+};
+/**
+ * Applied by the emitter, exactly: a filtered subscription never receives
+ * an event outside its filter, so filtering again is redundant rather than
+ * defensive. Every key means what it means on `RecordFilter`, so one value
+ * can drive both `query()` and `subscribe()`. See docs/spec/events.md
+ * § Subscribing.
+ */
+export type ChangeFilter = Pick<RecordFilter, 'typeId' | 'baseId' | 'parentId' | 'createdBy' | 'includeUnlisted'> & {
+    kinds?: ChangeKind[];
+};
+/** Ends a subscription. Safe to call more than once. */
+export type Unsubscribe = () => void;
+/**
+ * What a subscriber asks for, and what `Stack` forwards unchanged to an
+ * adapter's `subscribeChanges()` relay — the relay honors every key.
+ * See docs/spec/events.md § Subscribing and § Where events come from.
+ */
+export type SubscribeOptions = {
+    filter?: ChangeFilter;
+    /** Ask the emitter to include `record`. Honored when it can; never assume it. */
+    includeRecords?: boolean;
+    /**
+     * Resume from this cursor — the last `cursor` that was *present* on a
+     * delivered `RecordChange`. Refused with `StackBadRequestError` on a
+     * stack with no relay, which has no cursor it could have minted.
+     * See docs/spec/events.md § Subscribing.
+     */
+    since?: string;
+    /**
+     * Where a throwing handler's error goes, and on a relaying stack a
+     * connection the relay could not restore. Without one a handler error is
+     * rethrown asynchronously; it never reaches the mutation's caller.
+     */
+    onError?: (err: unknown) => void;
+    /**
+     * A gap opened that resumption could not close: reconcile by query.
+     * Never fires on a local stack. Can fire on the first connection when
+     * the far end will not honor `since`.
+     */
+    onReset?: () => void;
+};
+//# sourceMappingURL=events.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/types/events.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AAC/D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEtE;;;;;;GAMG;AACH,MAAM,MAAM,QAAQ,GAChB,QAAQ,GACR,OAAO,GACP,WAAW,GACX,YAAY,GACZ,SAAS,GACT,SAAS,GACT,SAAS,GACT,QAAQ,GACR,UAAU,GACV,OAAO;AACT;;;;;GAKG;GACD,QAAQ;AACV,oEAAoE;GAClE,MAAM;AACR;;;;;;GAMG;GACD,UAAU,CAAC;AAEf;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG;IAChC,+DAA+D;IAC/D,KAAK,CAAC,EAAE,KAAK,CAAC;CACf,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,UAAU,CAAC;IACjB;;;;;OAKG;IACH,GAAG,EAAE,QAAQ,EAAE,CAAC;IAChB,QAAQ,EAAE,QAAQ,CAAC;IACnB,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,SAAS,EAAE,IAAI,CAAC;IAChB,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,eAAe,EAAE,CAAC;IACtC;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,eAAe,EAAE,CAAC;IACxC;;;;OAIG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG,IAAI,CAC7B,YAAY,EACZ,QAAQ,GAAG,QAAQ,GAAG,UAAU,GAAG,WAAW,GAAG,iBAAiB,CACnE,GAAG;IACF,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC;CACtB,CAAC;AAEF,wDAAwD;AACxD,MAAM,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC;AAErC;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,iFAAiF;IACjF,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;IACjC;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;CACtB,CAAC"}

package/dist/types/events.js

@@ -0,0 +1,5 @@
+/**
+ * Change events: what `subscribe()` delivers and the options it takes.
+ */
+export {};
+//# sourceMappingURL=events.js.map

package/dist/types/events.js.map

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

package/dist/types/ids.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Identifiers, and the Actor that pairs two of them.
+ */
+/**
+ * Crockford base-32 encoded ID — time-sortable, unique within a stack.
+ * Format: 9-char timestamp prefix + 3-char random suffix = 12 chars total.
+ * Human-readable and URL-safe. Uniqueness is within-stack only;
+ * cross-stack references must include a stackUrl to disambiguate.
+ */
+export type RecordId = string;
+/** Namespaced, versioned type identifier e.g. "com.example.myapp/note@2" */
+export type TypeId = string;
+/** A type family: a TypeId without its version, e.g. "com.example.myapp/note" */
+export type BaseId = string;
+/** Opaque file identifier returned by putBlob() */
+export type FileId = string;
+/**
+ * Reverse-DNS identifier for the software that wrote a Record, e.g.
+ * "com.example.myapp" — not a RecordId. Self-reported and never a
+ * permission input; `StackRecord.createdBy.principalId` is the verified
+ * counterpart.
+ * See docs/spec/identity.md § App.
+ */
+export type AppId = string;
+/**
+ * Identifies a "who" — a DID string, e.g. "did:key:z6Mk...". A
+ * self-certifying identifier that means the same thing in every stack,
+ * unlike a RecordId. did:key is the mandatory floor method (see did/did.ts).
+ * See docs/spec/identity.md.
+ */
+export type EntityId = string;
+/**
+ * Who did something, and through which principal. `subjectId` is who the
+ * act is attributed to; `principalId` is who authenticated, present only
+ * when it differs — a delegated app acting for its user. `Stack` stores
+ * a `principalId` equal to `subjectId` as absent, so the two spellings of
+ * "acted as itself" never diverge. See docs/spec/data-model.md § Actor.
+ */
+export type Actor = {
+    subjectId: EntityId;
+    principalId?: EntityId;
+};
+//# sourceMappingURL=ids.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ids.d.ts","sourceRoot":"","sources":["../../src/types/ids.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC;AAE9B,4EAA4E;AAC5E,MAAM,MAAM,MAAM,GAAG,MAAM,CAAC;AAE5B,iFAAiF;AACjF,MAAM,MAAM,MAAM,GAAG,MAAM,CAAC;AAE5B,mDAAmD;AACnD,MAAM,MAAM,MAAM,GAAG,MAAM,CAAC;AAE5B;;;;;;GAMG;AACH,MAAM,MAAM,KAAK,GAAG,MAAM,CAAC;AAE3B;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC;AAE9B;;;;;;GAMG;AACH,MAAM,MAAM,KAAK,GAAG;IAClB,SAAS,EAAE,QAAQ,CAAC;IACpB,WAAW,CAAC,EAAE,QAAQ,CAAC;CACxB,CAAC"}

package/dist/types/ids.js

@@ -0,0 +1,5 @@
+/**
+ * Identifiers, and the Actor that pairs two of them.
+ */
+export {};
+//# sourceMappingURL=ids.js.map

package/dist/types/ids.js.map

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

package/dist/types/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Stack — Core Type Definitions
+ * -------------------------------------------------------
+ * The source of truth for all types in the Stack library, one module per
+ * concern. No logic lives here — just shapes. Import from this barrel
+ * rather than from a module, so a type can move without touching callers.
+ */
+export * from './ids.js';
+export * from './associations.js';
+export * from './records.js';
+export * from './schema.js';
+export * from './system.js';
+export * from './query.js';
+export * from './capabilities.js';
+export * from './journal.js';
+export * from './events.js';
+export * from './adapter.js';
+export * from './tokens.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,UAAU,CAAC;AACzB,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC"}

package/dist/types/index.js

@@ -0,0 +1,19 @@
+/**
+ * Stack — Core Type Definitions
+ * -------------------------------------------------------
+ * The source of truth for all types in the Stack library, one module per
+ * concern. No logic lives here — just shapes. Import from this barrel
+ * rather than from a module, so a type can move without touching callers.
+ */
+export * from './ids.js';
+export * from './associations.js';
+export * from './records.js';
+export * from './schema.js';
+export * from './system.js';
+export * from './query.js';
+export * from './capabilities.js';
+export * from './journal.js';
+export * from './events.js';
+export * from './adapter.js';
+export * from './tokens.js';
+//# sourceMappingURL=index.js.map

package/dist/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,UAAU,CAAC;AACzB,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC"}

package/dist/types/journal.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The change journal: the per-record log of what each write moved.
+ */
+import type { AssociationChange } from './associations.js';
+import type { ChangeKind, ChangeOp, ChangeActor } from './events.js';
+import type { RecordId, TypeId } from './ids.js';
+/**
+ * The part of a change the record cannot report once the write has
+ * landed: which aspects moved, who moved them, and what an association
+ * mutation displaced. The adapter stamps the rest of the entry from the
+ * row it just wrote, so the two never drift. See docs/spec/journal.md.
+ */
+export type JournalEntryInput = {
+    ops: ChangeOp[];
+    kind: ChangeKind;
+    actor?: ChangeActor;
+    /** The container a move took the record out of, `null` for the root. */
+    previousParentId?: RecordId | null;
+    /**
+     * What an association mutation moved, one tagged edit per association,
+     * with `previous` beside whatever displaced it.
+     * See docs/spec/journal.md § The entry.
+     */
+    associations?: AssociationChange[];
+};
+/**
+ * One durable entry in a record's change journal. Envelope only — content
+ * lives on a RecordVersion. See docs/spec/journal.md § Ordering for why
+ * `seq` is the only ordering.
+ */
+export type RecordJournalEntry = JournalEntryInput & {
+    seq: number;
+    /** When the entry was appended — not the record's `updatedAt`, which an association change leaves alone. */
+    at: Date;
+    /** The version this change produced — unchanged on an op that doesn't bump; see ChangeOp. */
+    version: number;
+    typeId: TypeId;
+    /** Where the record sat after the change, absent for the root. */
+    parentId?: RecordId;
+};
+/** Window into a record's journal. Omitting both reads the whole log, oldest first. */
+export type JournalQuery = {
+    /** Entries after this seq, exclusive. */
+    afterSeq?: number;
+    limit?: number;
+};
+//# sourceMappingURL=journal.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"journal.d.ts","sourceRoot":"","sources":["../../src/types/journal.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACrE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAEjD;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,GAAG,EAAE,QAAQ,EAAE,CAAC;IAChB,IAAI,EAAE,UAAU,CAAC;IACjB,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,wEAAwE;IACxE,gBAAgB,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC;IACnC;;;;OAIG;IACH,YAAY,CAAC,EAAE,iBAAiB,EAAE,CAAC;CACpC,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,iBAAiB,GAAG;IACnD,GAAG,EAAE,MAAM,CAAC;IACZ,4GAA4G;IAC5G,EAAE,EAAE,IAAI,CAAC;IACT,6FAA6F;IAC7F,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB,CAAC;AAEF,uFAAuF;AACvF,MAAM,MAAM,YAAY,GAAG;IACzB,yCAAyC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC"}

package/dist/types/journal.js

@@ -0,0 +1,5 @@
+/**
+ * The change journal: the per-record log of what each write moved.
+ */
+export {};
+//# sourceMappingURL=journal.js.map

package/dist/types/journal.js.map

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

package/dist/types/query.d.ts

@@ -0,0 +1,185 @@
+/**
+ * Query filters, sorting, and the page a query returns.
+ */
+import type { RecordId, TypeId, BaseId, FileId, AppId, EntityId } from './ids.js';
+import type { StackRecord } from './records.js';
+/**
+ * A target pattern in `RecordFilter.relatedTo` — the association shape with
+ * the parts a query may leave open: an `external` target without `id`
+ * matches its whole namespace.
+ */
+export type RelationshipTargetPattern = {
+    kind: 'record';
+    recordId: RecordId;
+    stackUrl?: string;
+} | {
+    kind: 'entity';
+    entityId: EntityId;
+} | {
+    kind: 'external';
+    ns: string;
+    id?: string;
+};
+/**
+ * A relationship query names a label, a target, or both — never neither.
+ * "Carries any relationship at all" is deliberately not expressible, in
+ * line with `tags` and `attachment`, which likewise have no match-any
+ * form. See docs/spec/data-model.md § Filter.
+ */
+export type RelatedToFilter = {
+    label: string;
+    target?: RelationshipTargetPattern;
+} | {
+    label?: string;
+    target: RelationshipTargetPattern;
+};
+/**
+ * An attachment query names a label, a file, or both — never neither —
+ * and both halves together match one association. See
+ * docs/spec/data-model.md § Filter.
+ */
+export type AttachmentFilter = {
+    label: string;
+    fileId?: FileId;
+} | {
+    label?: string;
+    fileId: FileId;
+};
+export type DateRange = {
+    before?: Date;
+    after?: Date;
+};
+/** One Type's arm of `RecordFilter.contentByType`, flat by design. */
+export type ContentArm = {
+    content?: Record<string, unknown>;
+    contentPresent?: string[];
+};
+export type RecordFilter = {
+    typeId?: TypeId | TypeId[];
+    /**
+     * Match every version of a type family: a record whose typeId, without
+     * its `@version` suffix, is one of these. Intersects with `typeId` when
+     * both are given. A value carrying an `@version` suffix is refused with
+     * StackValidationError. See docs/spec/data-model.md § Filter.
+     */
+    baseId?: BaseId | BaseId[];
+    parentId?: RecordId | null;
+    appId?: AppId | AppId[];
+    /** Matches the record's author — never the latest actor, which isn't filterable. */
+    createdBy?: {
+        subjectId?: EntityId | EntityId[];
+        principalId?: EntityId | EntityId[];
+    };
+    createdAt?: DateRange;
+    updatedAt?: DateRange;
+    tags?: string[];
+    /** Records carrying a matching attachment association. See docs/spec/data-model.md § Filter. */
+    attachment?: AttachmentFilter;
+    /**
+     * Records carrying a matching relationship association. Either half may
+     * be given alone and each is a pattern: a bare `label` matches every
+     * target under it, and an `external` target with no `id` matches the
+     * whole namespace. An absent `stackUrl` on a `record` target matches
+     * only local targets. See docs/spec/data-model.md § Filter.
+     */
+    relatedTo?: RelatedToFilter;
+    /**
+     * Records that reference this file, through an attachment association
+     * or a top-level `file-ref` content field — the question GC and
+     * `deleteAttachment()` ask. See docs/spec/attachments.md § Deleting attachments.
+     */
+    referencesFileId?: FileId;
+    /**
+     * Exact match on content fields, keyed by a dot-separated path
+     * (`'emails.value'`); an array along the path matches element-wise. A
+     * multi-segment key needs `filter.content: 'path'`. POST /records/query
+     * only. See docs/spec/data-model.md § Filter.
+     */
+    content?: Record<string, unknown>;
+    /**
+     * Paths that must hold a non-null value — the question `content` cannot
+     * ask. Element-wise like `content`. Needs `filter.contentPresent`.
+     * POST /records/query only. See docs/spec/data-model.md § Filter.
+     */
+    contentPresent?: string[];
+    /**
+     * A content predicate per Type: a record matches when its `typeId` is a
+     * key and its content satisfies that arm. Generated by a collection from
+     * a migration chain; never beside `content` or `contentPresent`. Needs
+     * `filter.contentByType`. POST /records/query only. See
+     * docs/spec/data-model.md § Content by type.
+     */
+    contentByType?: Record<TypeId, ContentArm>;
+    search?: string;
+    includeDeleted?: boolean;
+    /**
+     * Unlisted records are excluded by default, like soft-deleted ones.
+     * Owner-only under `ScopedStack` — enumeration standing rests on nothing
+     * but ownership, so a grant or delegation never carries it. See
+     * docs/spec/unlisted.md.
+     */
+    includeUnlisted?: boolean;
+};
+/**
+ * The Record columns every adapter stores natively, and can order by. The
+ * array is the source of truth, so the runtime checks that narrow a wire
+ * value or a cursor to this set can't drift from NativeSortField.
+ */
+export declare const NATIVE_SORT_FIELDS: readonly ["createdAt", "updatedAt", "version"];
+export type NativeSortField = (typeof NATIVE_SORT_FIELDS)[number];
+/**
+ * What a record at one Type orders by under `contentFieldByType`: a
+ * top-level field of its own, or a constant already reduced to what it
+ * orders as — a number, text, or `null` for no value.
+ */
+export type ContentSortKey = {
+    field: string;
+    value?: never;
+} | {
+    field?: never;
+    value: string | number | null;
+};
+/**
+ * Order by a native column, a top-level content field, or a content field
+ * per Type — separate members, so a content field named `version` stays
+ * distinct from the native column. `direction` defaults to `asc`; a query
+ * with no sort is `createdAt`, newest first. See docs/spec/data-model.md
+ * § Sorting by a content field.
+ */
+export type QuerySort = {
+    field: NativeSortField;
+    contentField?: never;
+    contentFieldByType?: never;
+    direction?: 'asc' | 'desc';
+} | {
+    field?: never;
+    contentField: string;
+    contentFieldByType?: never;
+    direction?: 'asc' | 'desc';
+} | {
+    field?: never;
+    contentField?: never;
+    contentFieldByType: Record<TypeId, ContentSortKey>;
+    direction?: 'asc' | 'desc';
+};
+export type StackQuery = {
+    filter?: RecordFilter;
+    sort?: QuerySort;
+    limit?: number;
+    cursor?: string;
+    /**
+     * "stored" (the default) returns records as stored; "latest" applies the
+     * migration chain in memory, never written back. Throws
+     * StackMigrationError if a matched record has no path to the latest.
+     */
+    presentAt?: 'stored' | 'latest';
+};
+/**
+ * A page of results and where the next one resumes. There is no count of
+ * the whole match: see docs/spec/data-model.md § Sorting and pagination.
+ */
+export type QueryResult = {
+    records: StackRecord[];
+    cursor: string | null;
+};
+//# sourceMappingURL=query.d.ts.map

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

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

package/dist/types/query.js

@@ -0,0 +1,10 @@
+/**
+ * Query filters, sorting, and the page a query returns.
+ */
+/**
+ * The Record columns every adapter stores natively, and can order by. The
+ * array is the source of truth, so the runtime checks that narrow a wire
+ * value or a cursor to this set can't drift from NativeSortField.
+ */
+export const NATIVE_SORT_FIELDS = ['createdAt', 'updatedAt', 'version'];
+//# sourceMappingURL=query.js.map

package/dist/types/query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.js","sourceRoot":"","sources":["../../src/types/query.ts"],"names":[],"mappings":"AAAA;;GAEG;AA2HH;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,WAAW,EAAE,WAAW,EAAE,SAAS,CAAU,CAAC"}

package/dist/types/records.d.ts

@@ -0,0 +1,76 @@
+/**
+ * The Record itself and its version snapshots.
+ */
+import type { AuthorityAssociation, DataAssociation } from './associations.js';
+import type { RecordId, TypeId, AppId, Actor } from './ids.js';
+export type StackRecord = {
+    id: RecordId;
+    typeId: TypeId;
+    createdAt: Date;
+    updatedAt: Date;
+    content: Record<string, unknown>;
+    /**
+     * Ordinal of the snapshot history, not a count of changes: associations,
+     * permissions, parent and listing moves leave it alone. See
+     * docs/spec/versioning.md § Version history.
+     */
+    version: number;
+    parentId?: RecordId;
+    appId?: AppId;
+    /**
+     * The record's author, stamped once by the create. A `principalId` here
+     * is what lets `appId` be checked against the `_app` record naming that
+     * DID; without one, `appId` is an unverifiable self-report.
+     * See docs/spec/data-model.md § Authorship and attribution.
+     */
+    createdBy?: Actor;
+    /**
+     * Who performed the mutation this version records — unlike `createdBy`,
+     * it moves with every write. Absent means an unscoped `Stack` wrote it,
+     * which names no requester.
+     * See docs/spec/data-model.md § Authorship and attribution.
+     */
+    updatedBy?: Actor;
+    deletedAt?: Date;
+    /**
+     * Present when the record is withheld from enumeration: absent from
+     * `query()` and the change feed by default, but reachable by `get()` for
+     * anyone who may read it. Says nothing about who that is.
+     * See docs/spec/unlisted.md.
+     */
+    unlistedAt?: Date;
+    /**
+     * Who reaches this Record, projected from the association table's
+     * authority kinds. Absent or empty means private — readable only by the
+     * stack owner. Declarative intent; enforcement is `ScopedStack`'s.
+     * See docs/spec/access-control.md § Record-level permissions.
+     */
+    permissions?: AuthorityAssociation[];
+    associations?: DataAssociation[];
+};
+export type RecordVersion = {
+    version: number;
+    /** The record's typeId at the moment this version was snapshotted. */
+    typeId: TypeId;
+    content: Record<string, unknown>;
+    updatedAt: Date;
+    /**
+     * The record's author, carried through from `record.createdBy` — not the
+     * actor of the change this version records.
+     * See docs/spec/versioning.md § Version history.
+     */
+    createdBy?: Actor;
+    /** Who performed the mutation that produced this version. */
+    updatedBy?: Actor;
+};
+/**
+ * Window into a record's version history. Newest first, the reverse of
+ * JournalQuery; omitting both reads every version.
+ * See docs/spec/versioning.md § Version history.
+ */
+export type VersionsQuery = {
+    /** Versions strictly older than this, exclusive. */
+    beforeVersion?: number;
+    limit?: number;
+};
+//# sourceMappingURL=records.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"records.d.ts","sourceRoot":"","sources":["../../src/types/records.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAC/E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AAE/D,MAAM,MAAM,WAAW,GAAG;IAExB,EAAE,EAAE,QAAQ,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,IAAI,CAAC;IAChB,SAAS,EAAE,IAAI,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;IAGhB,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,KAAK,CAAC,EAAE,KAAK,CAAC;IACd;;;;;OAKG;IACH,SAAS,CAAC,EAAE,KAAK,CAAC;IAClB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,KAAK,CAAC;IAClB,SAAS,CAAC,EAAE,IAAI,CAAC;IACjB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,IAAI,CAAC;IAClB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,oBAAoB,EAAE,CAAC;IACrC,YAAY,CAAC,EAAE,eAAe,EAAE,CAAC;CAClC,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,SAAS,EAAE,IAAI,CAAC;IAChB;;;;OAIG;IACH,SAAS,CAAC,EAAE,KAAK,CAAC;IAClB,6DAA6D;IAC7D,SAAS,CAAC,EAAE,KAAK,CAAC;CACnB,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,oDAAoD;IACpD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC"}

package/dist/types/records.js

@@ -0,0 +1,5 @@
+/**
+ * The Record itself and its version snapshots.
+ */
+export {};
+//# sourceMappingURL=records.js.map

package/dist/types/records.js.map

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