@haverstack/core 0.28.0 → 0.30.0

package/dist/index.d.ts

@@ -14,10 +14,13 @@
  * Storage adapters are published as separate packages:
  *   @haverstack/adapter-sqlite
  */
-export { Stack, ScopedStack, StackError, StackValidationError, StackMigrationError, StackPermissionError, StackNotFoundError, StackConflictError, StackVersionConflictError, StackQueryError, StackSchemaDriftError, StackPayloadTooLargeError, StackTimeoutError, StackClosedError, StackRelayScopeError, } from './stack.js';
-export type { StackErrorCode, StackClient, CreateRecordOptions, BackdatableCreateRecordOptions, StackOptions, GetRecordOptions, DeleteRecordOptions, IfVersionOptions, CollectAttachmentGarbageOptions, CollectAttachmentGarbageResult, } from './stack.js';
-export type { RecordId, TypeId, FileId, EntityId, AttachmentContent, StackRecord, RecordVersion, ActorOptions, ChangeKind, ChangeOp, ChangeActor, RecordChange, ChangeFilter, SubscribeOptions, Unsubscribe, ExpectedVersionOptions, SnapshotOptions, StackType, TypeSchema, FieldDef, ScalarFieldDef, ArrayFieldDef, ObjectFieldDef, ScalarFieldKind, Association, TagAssociation, AttachmentAssociation, RelationshipAssociation, RelationshipTarget, RecordTarget, EntityTarget, ExternalTarget, Permission, StackQuery, RecordFilter, RelatedToFilter, RelationshipTargetPattern, QuerySort, NativeSortField, ContentFilterReach, QueryResult, DateRange, Migration, MigrationFn, StackAdapter, StackFeatures, TokenSession, EntityContent, AppContent, GroupContent, GrantAction, GrantContent, ConfigContent, } from './types.js';
-export { SYSTEM_TYPES } from './types.js';
+export { Stack } from './stack.js';
+export { ScopedStack } from './scoped-stack.js';
+export type { StackClient, CreateRecordOptions, BackdatableCreateRecordOptions, StackOptions, GetRecordOptions, DeleteRecordOptions, IfVersionOptions, CollectAttachmentGarbageOptions, CollectAttachmentGarbageResult, } from './stack.js';
+export { StackError, StackValidationError, StackMigrationError, StackPermissionError, StackNotFoundError, StackConflictError, StackVersionConflictError, StackQueryError, StackSchemaDriftError, StackPayloadTooLargeError, StackTimeoutError, StackClosedError, StackRelayScopeError, } from './errors.js';
+export type { StackErrorCode } from './errors.js';
+export type { RecordId, TypeId, FileId, EntityId, AttachmentContent, StackRecord, RecordChanges, RecordVersion, ActorOptions, ChangeKind, ChangeOp, ChangeActor, RecordChange, ChangeFilter, SubscribeOptions, Unsubscribe, ExpectedVersionOptions, SnapshotOptions, StackType, TypeSchema, FieldDef, ScalarFieldDef, ArrayFieldDef, ObjectFieldDef, ScalarFieldKind, Association, TagAssociation, AttachmentAssociation, RelationshipAssociation, RelationshipTarget, RecordTarget, EntityTarget, ExternalTarget, Permission, StackQuery, RecordFilter, RelatedToFilter, RelationshipTargetPattern, QuerySort, NativeSortField, ContentFilterReach, QueryResult, DateRange, Migration, MigrationFn, StackAdapter, StackFeatures, TokenSession, EntityContent, AppContent, GroupContent, GrantAction, GrantContent, ConfigContent, } from './types.js';
+export { SYSTEM_TYPES, NATIVE_SORT_FIELDS } from './types.js';
 export { generateId } from './id.js';
 export { hashSchema, isCompatible } from './schema.js';
 export type { SchemaDriftViolation } from './schema.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,EACL,KAAK,EACL,WAAW,EACX,UAAU,EACV,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACpB,kBAAkB,EAClB,kBAAkB,EAClB,yBAAyB,EACzB,eAAe,EACf,qBAAqB,EACrB,yBAAyB,EACzB,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,cAAc,EACd,WAAW,EACX,mBAAmB,EACnB,8BAA8B,EAC9B,YAAY,EACZ,gBAAgB,EAChB,mBAAmB,EACnB,gBAAgB,EAChB,+BAA+B,EAC/B,8BAA8B,GAC/B,MAAM,YAAY,CAAC;AAGpB,YAAY,EACV,QAAQ,EACR,MAAM,EACN,MAAM,EACN,QAAQ,EACR,iBAAiB,EACjB,WAAW,EACX,aAAa,EACb,YAAY,EACZ,UAAU,EACV,QAAQ,EACR,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,gBAAgB,EAChB,WAAW,EACX,sBAAsB,EACtB,eAAe,EACf,SAAS,EACT,UAAU,EACV,QAAQ,EACR,cAAc,EACd,aAAa,EACb,cAAc,EACd,eAAe,EACf,WAAW,EACX,cAAc,EACd,qBAAqB,EACrB,uBAAuB,EACvB,kBAAkB,EAClB,YAAY,EACZ,YAAY,EACZ,cAAc,EACd,UAAU,EACV,UAAU,EACV,YAAY,EACZ,eAAe,EACf,yBAAyB,EACzB,SAAS,EACT,eAAe,EACf,kBAAkB,EAClB,WAAW,EACX,SAAS,EACT,SAAS,EACT,WAAW,EACX,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,aAAa,EACb,UAAU,EACV,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,aAAa,GACd,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAM1C,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACvD,YAAY,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACxD,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EACV,WAAW,EACX,mBAAmB,EACnB,8BAA8B,EAC9B,YAAY,EACZ,gBAAgB,EAChB,mBAAmB,EACnB,gBAAgB,EAChB,+BAA+B,EAC/B,8BAA8B,GAC/B,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,UAAU,EACV,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACpB,kBAAkB,EAClB,kBAAkB,EAClB,yBAAyB,EACzB,eAAe,EACf,qBAAqB,EACrB,yBAAyB,EACzB,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAGlD,YAAY,EACV,QAAQ,EACR,MAAM,EACN,MAAM,EACN,QAAQ,EACR,iBAAiB,EACjB,WAAW,EACX,aAAa,EACb,aAAa,EACb,YAAY,EACZ,UAAU,EACV,QAAQ,EACR,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,gBAAgB,EAChB,WAAW,EACX,sBAAsB,EACtB,eAAe,EACf,SAAS,EACT,UAAU,EACV,QAAQ,EACR,cAAc,EACd,aAAa,EACb,cAAc,EACd,eAAe,EACf,WAAW,EACX,cAAc,EACd,qBAAqB,EACrB,uBAAuB,EACvB,kBAAkB,EAClB,YAAY,EACZ,YAAY,EACZ,cAAc,EACd,UAAU,EACV,UAAU,EACV,YAAY,EACZ,eAAe,EACf,yBAAyB,EACzB,SAAS,EACT,eAAe,EACf,kBAAkB,EAClB,WAAW,EACX,SAAS,EACT,SAAS,EACT,WAAW,EACX,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,aAAa,EACb,UAAU,EACV,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,aAAa,GACd,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAM9D,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACvD,YAAY,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACxD,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -15,8 +15,11 @@
  *   @haverstack/adapter-sqlite
  */
 // Core class and client interface
-export { Stack, ScopedStack, StackError, StackValidationError, StackMigrationError, StackPermissionError, StackNotFoundError, StackConflictError, StackVersionConflictError, StackQueryError, StackSchemaDriftError, StackPayloadTooLargeError, StackTimeoutError, StackClosedError, StackRelayScopeError, } from './stack.js';
-export { SYSTEM_TYPES } from './types.js';
+export { Stack } from './stack.js';
+export { ScopedStack } from './scoped-stack.js';
+// The error taxonomy
+export { StackError, StackValidationError, StackMigrationError, StackPermissionError, StackNotFoundError, StackConflictError, StackVersionConflictError, StackQueryError, StackSchemaDriftError, StackPayloadTooLargeError, StackTimeoutError, StackClosedError, StackRelayScopeError, } from './errors.js';
+export { SYSTEM_TYPES, NATIVE_SORT_FIELDS } from './types.js';
 // Utilities
 // No in-repo caller: client-minted IDs are the default per spec, and an app
 // needing the ID before the write round-trips has to mint one itself.

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,kCAAkC;AAClC,OAAO,EACL,KAAK,EACL,WAAW,EACX,UAAU,EACV,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACpB,kBAAkB,EAClB,kBAAkB,EAClB,yBAAyB,EACzB,eAAe,EACf,qBAAqB,EACrB,yBAAyB,EACzB,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,YAAY,CAAC;AAuEpB,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1C,YAAY;AAEZ,4EAA4E;AAC5E,sEAAsE;AACtE,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAGvD,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,kCAAkC;AAClC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAahD,qBAAqB;AACrB,OAAO,EACL,UAAU,EACV,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACpB,kBAAkB,EAClB,kBAAkB,EAClB,yBAAyB,EACzB,eAAe,EACf,qBAAqB,EACrB,yBAAyB,EACzB,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,aAAa,CAAC;AA6DrB,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAE9D,YAAY;AAEZ,4EAA4E;AAC5E,sEAAsE;AACtE,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAGvD,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC"}

package/dist/limits.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Declared-ceiling pre-checks
+ * -------------------------------------------------------
+ * Client-side guards against an adapter's declared `limits`. Local
+ * adapters declare `null` and skip them entirely; only a server names a
+ * ceiling, and its own request-size limit stays authoritative — these just
+ * spare an app the round trip and give it a typed failure instead of a 413
+ * it has to interpret.
+ *
+ * See docs/spec/wire-format.md § Request size limits.
+ */
+/** Shared by Stack.putAttachment() and ScopedStack.putAttachment(). */
+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.
+ */
+export declare function assertContentSize(content: Record<string, unknown>, contentBytes: number | null, what: 'Content' | 'Patch'): void;
+//# sourceMappingURL=limits.d.ts.map

package/dist/limits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.d.ts","sourceRoot":"","sources":["../src/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;;;;;;;GAOG;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

@@ -0,0 +1,35 @@
+/**
+ * Declared-ceiling pre-checks
+ * -------------------------------------------------------
+ * Client-side guards against an adapter's declared `limits`. Local
+ * adapters declare `null` and skip them entirely; only a server names a
+ * ceiling, and its own request-size limit stays authoritative — these just
+ * spare an app the round trip and give it a typed failure instead of a 413
+ * it has to interpret.
+ *
+ * See docs/spec/wire-format.md § Request size limits.
+ */
+import { StackPayloadTooLargeError } from './errors.js';
+/** Shared by Stack.putAttachment() and ScopedStack.putAttachment(). */
+export function assertAttachmentSize(byteLength, attachmentBytes) {
+    if (attachmentBytes !== null && byteLength > attachmentBytes) {
+        throw new StackPayloadTooLargeError(`Attachment (${byteLength} bytes) exceeds the ${attachmentBytes}-byte limit.`);
+    }
+}
+/**
+ * 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.
+ */
+export function assertContentSize(content, contentBytes, what) {
+    if (contentBytes === null)
+        return;
+    const byteLength = new TextEncoder().encode(JSON.stringify(content)).length;
+    if (byteLength > contentBytes) {
+        throw new StackPayloadTooLargeError(`${what} (${byteLength} bytes) exceeds the ${contentBytes}-byte limit.`);
+    }
+}
+//# sourceMappingURL=limits.js.map

package/dist/limits.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.js","sourceRoot":"","sources":["../src/limits.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AAExD,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;;;;;;;GAOG;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/merge.d.ts

@@ -3,7 +3,7 @@
  * -------------------------------------------------------
  * Shallow merge-patch semantics for record content: a field set to `null`
  * removes it, any other value replaces it, and omitted fields are retained.
- * Shared by Stack.update() (for client-side validation) and every
+ * Shared by Stack.mutate() (for client-side validation) and every
  * StackRecordAdapter's patchContent() implementation, so a patch produces
  * the same merged content everywhere it's applied.
  */

package/dist/merge.js

@@ -3,7 +3,7 @@
  * -------------------------------------------------------
  * Shallow merge-patch semantics for record content: a field set to `null`
  * removes it, any other value replaces it, and omitted fields are retained.
- * Shared by Stack.update() (for client-side validation) and every
+ * Shared by Stack.mutate() (for client-side validation) and every
  * StackRecordAdapter's patchContent() implementation, so a patch produces
  * the same merged content everywhere it's applied.
  */
@@ -22,7 +22,7 @@ export function applyMergePatch(content, patch) {
             // the same key is read back, so both write paths agree. The spread
             // above is already safe (it copies data properties directly).
             //
-            // Stack.create()/update() reject the reserved keys outright (see
+            // Stack.create()/Stack.mutate() reject the reserved keys outright (see
             // validateReservedKeys); this is the backstop for adapters that call
             // this directly, and for the day someone deepens the merge.
             Object.defineProperty(merged, key, {

package/dist/merge.js.map

@@ -1 +1 @@
-{"version":3,"file":"merge.js","sourceRoot":"","sources":["../src/merge.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,UAAU,eAAe,CAC7B,OAAgC,EAChC,KAAqC;IAErC,MAAM,MAAM,GAA4B,EAAE,GAAG,OAAO,EAAE,CAAC;IACvD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACjD,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YACnB,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;QACrB,CAAC;aAAM,CAAC;YACN,qEAAqE;YACrE,oEAAoE;YACpE,kEAAkE;YAClE,mEAAmE;YACnE,qEAAqE;YACrE,mEAAmE;YACnE,8DAA8D;YAC9D,EAAE;YACF,iEAAiE;YACjE,qEAAqE;YACrE,4DAA4D;YAC5D,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,GAAG,EAAE;gBACjC,KAAK;gBACL,QAAQ,EAAE,IAAI;gBACd,UAAU,EAAE,IAAI;gBAChB,YAAY,EAAE,IAAI;aACnB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"merge.js","sourceRoot":"","sources":["../src/merge.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,UAAU,eAAe,CAC7B,OAAgC,EAChC,KAAqC;IAErC,MAAM,MAAM,GAA4B,EAAE,GAAG,OAAO,EAAE,CAAC;IACvD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACjD,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YACnB,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;QACrB,CAAC;aAAM,CAAC;YACN,qEAAqE;YACrE,oEAAoE;YACpE,kEAAkE;YAClE,mEAAmE;YACnE,qEAAqE;YACrE,mEAAmE;YACnE,8DAA8D;YAC9D,EAAE;YACF,uEAAuE;YACvE,qEAAqE;YACrE,4DAA4D;YAC5D,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,GAAG,EAAE;gBACjC,KAAK;gBACL,QAAQ,EAAE,IAAI;gBACd,UAAU,EAAE,IAAI;gBAChB,YAAY,EAAE,IAAI;aACnB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/query-validation.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Query and association validation
+ * -------------------------------------------------------
+ * The sanitizers a query passes through before any adapter sees it, plus
+ * the relationship-target rules an association is held to. Both sides of
+ * the same job: a discriminated union and a `QuerySort` field are compile-
+ * time promises, and a server mapping a request body onto either supplies
+ * raw JSON that no compiler has seen.
+ *
+ * These live in the invariant layer for the reason validation and
+ * `_config` protection do — so no adapter can forget one. `assertQueryCapabilities`
+ * and its neighbours are shared verbatim with `adapter-api`, which asks the
+ * same questions of a request arriving over the wire.
+ * See docs/spec/data-model.md § Capability-gated filters.
+ */
+import type { ValidationError } from './validate.js';
+import type { Association, QuerySort, RecordFilter, StackFeatures } from './types.js';
+/**
+ * Fail loud rather than silently widen: a filter the adapter can't honor
+ * would otherwise be dropped, returning an unfiltered superset presented
+ * as the filtered result. Shared by Stack.query() and
+ * APIAdapter.queryRecords(). See docs/spec/data-model.md
+ * § Capability-gated filters.
+ */
+export declare function assertQueryCapabilities(filter: RecordFilter | undefined, capabilities: Pick<StackFeatures, 'filter'>): void;
+/**
+ * Whether a single-segment content filter can be pushed down to the
+ * adapter. Callers that read a content field pair this with an in-memory
+ * predicate over the wider result, so the query stays correct against an
+ * adapter that reaches no content at all — the rung comparison lives here
+ * rather than at each of them.
+ */
+export declare function filtersContent(features: Pick<StackFeatures, 'filter'>): boolean;
+/**
+ * Split a content filter key into path segments. Write-time validation
+ * keeps stored field names free of the path metacharacters, but a filter
+ * arrives from a request body and has made no such promise, so the same
+ * rule is enforced here. See docs/spec/data-model.md § Content field names.
+ */
+export declare function parseContentFilterKey(key: string): string[];
+/**
+ * Reject a sort whose field or direction is outside the closed set the
+ * types promise. `QuerySort` is typed `'asc' | 'desc'`, but a type is not a
+ * runtime guard: a server mapping `?direction=` onto a query, or a
+ * delegated app calling query(), supplies a raw string. A SQLite record
+ * adapter interpolates the direction straight into `ORDER BY`, so an
+ * unvalidated value there is a SQL-injection sink reachable from every
+ * untrusted caller. Validating in the invariant layer — the same reason
+ * emission and _config protection live here — means no adapter can forget
+ * it. See docs/spec/data-model.md § Sorting and pagination.
+ */
+export declare function assertValidSort(sort: QuerySort | undefined): void;
+/**
+ * Fail loud rather than silently reorder: an adapter that can't honor the
+ * requested sort would otherwise answer in some other order, which a
+ * caller paging a bounded window has no way to notice. The companion to
+ * assertQueryCapabilities(), split from it because a sort is not a filter
+ * — see docs/spec/data-model.md § Capability-gated filters.
+ */
+export declare function assertSortCapability(sort: QuerySort | undefined, capabilities: Pick<StackFeatures, 'sort'>): void;
+/**
+ * Reject a relationship target outside the closed set the types promise.
+ * A discriminated union is not a runtime guard — a server mapping a
+ * request body onto an association supplies raw JSON — and an
+ * unrecognized scope would otherwise be stored under the one arm that
+ * names a Record in this stack. See docs/spec/data-model.md
+ * § Relationship targets.
+ */
+export declare function validateAssociation(association: Association, path?: string): ValidationError[];
+/** validateAssociation() over a create's `associations` array. */
+export declare function validateAssociations(associations: Association[] | undefined, path?: string): ValidationError[];
+/**
+ * Reject a relationship filter that names neither a label nor a target,
+ * or whose target is malformed. `RelatedToFilter` promises one half is
+ * always present; without the runtime check a filter decoded from a
+ * request could arrive empty and match every record carrying any
+ * relationship. See docs/spec/data-model.md § Filter.
+ */
+export declare function assertValidRelatedTo(relatedTo: RecordFilter['relatedTo']): void;
+//# sourceMappingURL=query-validation.d.ts.map

package/dist/query-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-validation.d.ts","sourceRoot":"","sources":["../src/query-validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD,OAAO,KAAK,EACV,WAAW,EACX,SAAS,EACT,YAAY,EAGZ,aAAa,EACd,MAAM,YAAY,CAAC;AAEpB;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,YAAY,GAAG,SAAS,EAChC,YAAY,EAAE,IAAI,CAAC,aAAa,EAAE,QAAQ,CAAC,GAC1C,IAAI,CA6BN;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,IAAI,CAAC,aAAa,EAAE,QAAQ,CAAC,GAAG,OAAO,CAE/E;AAKD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAwB3D;AAYD;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,GAAG,SAAS,GAAG,IAAI,CA2BjE;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,SAAS,GAAG,SAAS,EAC3B,YAAY,EAAE,IAAI,CAAC,aAAa,EAAE,MAAM,CAAC,GACxC,IAAI,CAiBN;AA0CD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,WAAW,EACxB,IAAI,SAAgB,GACnB,eAAe,EAAE,CAGnB;AAED,kEAAkE;AAClE,wBAAgB,oBAAoB,CAClC,YAAY,EAAE,WAAW,EAAE,GAAG,SAAS,EACvC,IAAI,SAAiB,GACpB,eAAe,EAAE,CAEnB;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,YAAY,CAAC,WAAW,CAAC,GAAG,IAAI,CAY/E"}

package/dist/query-validation.js

@@ -0,0 +1,223 @@
+/**
+ * Query and association validation
+ * -------------------------------------------------------
+ * The sanitizers a query passes through before any adapter sees it, plus
+ * the relationship-target rules an association is held to. Both sides of
+ * the same job: a discriminated union and a `QuerySort` field are compile-
+ * time promises, and a server mapping a request body onto either supplies
+ * raw JSON that no compiler has seen.
+ *
+ * These live in the invariant layer for the reason validation and
+ * `_config` protection do — so no adapter can forget one. `assertQueryCapabilities`
+ * and its neighbours are shared verbatim with `adapter-api`, which asks the
+ * same questions of a request arriving over the wire.
+ * See docs/spec/data-model.md § Capability-gated filters.
+ */
+import { StackQueryError } from './errors.js';
+import { CONTENT_SEGMENT_METACHARACTERS, SEGMENT_METACHARACTER_RE } from './validate.js';
+import { NATIVE_SORT_FIELDS } from './types.js';
+/**
+ * Fail loud rather than silently widen: a filter the adapter can't honor
+ * would otherwise be dropped, returning an unfiltered superset presented
+ * as the filtered result. Shared by Stack.query() and
+ * APIAdapter.queryRecords(). See docs/spec/data-model.md
+ * § Capability-gated filters.
+ */
+export function assertQueryCapabilities(filter, capabilities) {
+    const { content: reach, contentPresent, search } = capabilities.filter;
+    if (filter?.search && !search) {
+        throw new StackQueryError('Query uses filter.search, but this adapter does not declare the filter.search capability.');
+    }
+    const present = filter?.contentPresent?.length ? filter.contentPresent : undefined;
+    if (!filter?.content && !present)
+        return;
+    if (reach === 'none') {
+        throw new StackQueryError(`Query uses ${present && !filter?.content ? 'filter.contentPresent' : 'filter.content'}, ` +
+            'but this adapter declares filter.content: "none".');
+    }
+    if (present && !contentPresent) {
+        throw new StackQueryError('Query uses filter.contentPresent, but this adapter does not declare the ' +
+            'filter.contentPresent capability.');
+    }
+    for (const key of [...Object.keys(filter?.content ?? {}), ...(present ?? [])]) {
+        if (parseContentFilterKey(key).length > 1 && reach !== 'path') {
+            throw new StackQueryError(`Query uses the nested content path "${key}", but this adapter declares ` +
+                `filter.content: "${reach}".`);
+        }
+    }
+}
+/**
+ * Whether a single-segment content filter can be pushed down to the
+ * adapter. Callers that read a content field pair this with an in-memory
+ * predicate over the wider result, so the query stays correct against an
+ * adapter that reaches no content at all — the rung comparison lives here
+ * rather than at each of them.
+ */
+export function filtersContent(features) {
+    return features.filter.content !== 'none';
+}
+/** The longest path both SQLite engines can execute — see the spec link below. */
+const MAX_CONTENT_PATH_SEGMENTS = 32;
+/**
+ * Split a content filter key into path segments. Write-time validation
+ * keeps stored field names free of the path metacharacters, but a filter
+ * arrives from a request body and has made no such promise, so the same
+ * rule is enforced here. See docs/spec/data-model.md § Content field names.
+ */
+export function parseContentFilterKey(key) {
+    const segments = key.split('.');
+    // A SQLite adapter spends two json_each joins per segment against a
+    // 64-table join limit, so a path past the cap is one the engine could
+    // not execute. See docs/spec/data-model.md § Nested content paths.
+    if (segments.length > MAX_CONTENT_PATH_SEGMENTS) {
+        throw new StackQueryError(`Invalid content filter path "${key}": at most ${MAX_CONTENT_PATH_SEGMENTS} segments.`);
+    }
+    for (const segment of segments) {
+        if (segment === '') {
+            throw new StackQueryError(`Invalid content filter path "${key}": a path segment cannot be empty.`);
+        }
+        if (SEGMENT_METACHARACTER_RE.test(segment)) {
+            throw new StackQueryError(`Invalid content filter path "${key}": a segment cannot contain any of ` +
+                `${CONTENT_SEGMENT_METACHARACTERS.join(' ')}.`);
+        }
+    }
+    return segments;
+}
+/**
+ * The only sort fields any adapter maps; anything else is a caller error.
+ * Narrowed against the one array NativeSortField is derived from, so this
+ * gate — which every query passes through before an adapter sees it —
+ * can't be the copy that a fourth native column is missing from.
+ */
+const VALID_SORT_FIELDS = new Set(NATIVE_SORT_FIELDS);
+/** The only two sort directions; see assertValidSort. */
+const VALID_SORT_DIRECTIONS = new Set(['asc', 'desc']);
+/**
+ * Reject a sort whose field or direction is outside the closed set the
+ * types promise. `QuerySort` is typed `'asc' | 'desc'`, but a type is not a
+ * runtime guard: a server mapping `?direction=` onto a query, or a
+ * delegated app calling query(), supplies a raw string. A SQLite record
+ * adapter interpolates the direction straight into `ORDER BY`, so an
+ * unvalidated value there is a SQL-injection sink reachable from every
+ * untrusted caller. Validating in the invariant layer — the same reason
+ * emission and _config protection live here — means no adapter can forget
+ * it. See docs/spec/data-model.md § Sorting and pagination.
+ */
+export function assertValidSort(sort) {
+    if (!sort)
+        return;
+    if (sort.field !== undefined && sort.contentField !== undefined) {
+        throw new StackQueryError('A sort names either a native field or a content field, never both.');
+    }
+    if (sort.field !== undefined && !VALID_SORT_FIELDS.has(sort.field)) {
+        throw new StackQueryError(`Invalid sort field "${sort.field}": expected one of ${NATIVE_SORT_FIELDS.join(', ')}.`);
+    }
+    if (sort.contentField !== undefined) {
+        // Parsed by the same rule a filter key is, so a name a filter could
+        // never address is not one a sort can either — then held to one
+        // segment, because a value inside an array or object has no single
+        // position to order its record by (docs/spec/data-model.md
+        // § Sorting by a content field).
+        if (parseContentFilterKey(sort.contentField).length > 1) {
+            throw new StackQueryError(`Invalid sort content field "${sort.contentField}": sorting reaches top-level fields only.`);
+        }
+    }
+    if (sort.direction !== undefined && !VALID_SORT_DIRECTIONS.has(sort.direction)) {
+        throw new StackQueryError(`Invalid sort direction "${sort.direction}": expected "asc" or "desc".`);
+    }
+}
+/**
+ * Fail loud rather than silently reorder: an adapter that can't honor the
+ * requested sort would otherwise answer in some other order, which a
+ * caller paging a bounded window has no way to notice. The companion to
+ * assertQueryCapabilities(), split from it because a sort is not a filter
+ * — see docs/spec/data-model.md § Capability-gated filters.
+ */
+export function assertSortCapability(sort, capabilities) {
+    if (!sort)
+        return;
+    if (sort.contentField !== undefined) {
+        if (!capabilities.sort.contentField) {
+            throw new StackQueryError('Query uses sort.contentField, but this adapter does not declare the sort.contentField ' +
+                'capability.');
+        }
+        return;
+    }
+    const field = sort.field ?? 'createdAt';
+    if (!capabilities.sort.fields.includes(field)) {
+        throw new StackQueryError(`Query sorts by "${field}", which this adapter does not declare in sort.fields.`);
+    }
+}
+/** The identifier spaces a relationship target may name. */
+const TARGET_SCOPES = new Set(['record', 'entity', 'external']);
+/**
+ * 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.
+ */
+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_SCOPES.has(target.scope)) {
+        return fail(`Unknown relationship target scope "${target.scope}": expected "record", "entity" or "external".`);
+    }
+    if (target.scope === '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.scope === '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.");
+}
+/**
+ * Reject a relationship target outside the closed set the types promise.
+ * A discriminated union is not a runtime guard — a server mapping a
+ * request body onto an association supplies raw JSON — and an
+ * unrecognized scope would otherwise be stored under the one arm that
+ * names a Record in this stack. See docs/spec/data-model.md
+ * § Relationship targets.
+ */
+export function validateAssociation(association, path = 'association') {
+    if (association?.kind !== 'relationship')
+        return [];
+    return targetErrors(association.target, `${path}.target`);
+}
+/** validateAssociation() over a create's `associations` array. */
+export function validateAssociations(associations, path = 'associations') {
+    return (associations ?? []).flatMap((a, i) => validateAssociation(a, `${path}[${i}]`));
+}
+/**
+ * Reject a relationship filter that names neither a label nor a target,
+ * or whose target is malformed. `RelatedToFilter` promises one half is
+ * always present; without the runtime check a filter decoded from a
+ * request could arrive empty and match every record carrying any
+ * relationship. See docs/spec/data-model.md § Filter.
+ */
+export function assertValidRelatedTo(relatedTo) {
+    if (!relatedTo)
+        return;
+    if (relatedTo.label === undefined && relatedTo.target === undefined) {
+        throw new StackQueryError('filter.relatedTo must name a label, a target, or both — "any relationship at all" is not a filter.');
+    }
+    if (relatedTo.target === undefined)
+        return;
+    const errors = targetErrors(relatedTo.target, 'filter.relatedTo.target', {
+        externalIdOptional: true,
+    });
+    if (errors.length > 0)
+        throw new StackQueryError(errors[0].message);
+}
+//# sourceMappingURL=query-validation.js.map

package/dist/query-validation.js.map

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

package/dist/record-changes.d.ts

@@ -0,0 +1,89 @@
+/**
+ * What a write moved, and how a Record is presented
+ * -------------------------------------------------------
+ * Two jobs that share one question — what does this Record actually say?
+ *
+ * The equality helpers answer it against a proposed write, so the no-op
+ * decision and a change event's `ops` are the same comparison and can never
+ * disagree. The projections answer it against a reader: a soft-deleted
+ * Record is its tombstone, and a snapshot's `permissions` are owner-only
+ * audit data.
+ *
+ * See docs/spec/events.md § The event shape and docs/spec/versioning.md
+ * § The tombstone is literal.
+ */
+import type { Association, ChangeOp, EntityId, Permission, RecordChanges, RecordVersion, RelationshipTarget, StackRecord } from './types.js';
+/**
+ * Matches the SQLite adapter's association primary key (kind, label,
+ * file_id, related_scope, related_id, related_ns, related_stack).
+ */
+export declare function associationEqual(a: Association, b: Association): boolean;
+/** Structural equality per target arm — what dissociate() matches on. */
+export declare function targetEqual(a: RelationshipTarget, b: RelationshipTarget): boolean;
+export declare function permissionEqual(a: Permission, b: Permission): boolean;
+/**
+ * A change set has to name at least one aspect. Refused rather than read
+ * as a no-op: it addresses nothing, so there is nothing it could have
+ * failed to satisfy, and every way of producing one is a caller bug —
+ * typically a conditional that built an empty object.
+ * See docs/spec/data-model.md § Mutations.
+ */
+export declare function assertNonEmptyChangeSet(changes: RecordChanges): void;
+/**
+ * Which aspects a change set actually moves, against the record as it
+ * stands — the no-op decision and the change event's `ops` are the same
+ * comparison, so they can never disagree. A key naming the value a record
+ * already holds contributes nothing.
+ *
+ * `merged` is the content the patch produces, computed once by the
+ * caller that had to validate it anyway.
+ * See docs/spec/events.md § The event shape.
+ */
+export declare function changeSetOps(existing: StackRecord, changes: RecordChanges, merged: Record<string, unknown> | undefined): ChangeOp[];
+/**
+ * The change set narrowed to the aspects that actually moved. An adapter
+ * is handed this rather than what the caller wrote, so restating an aspect
+ * cannot rewrite it: `unlisted: true` on an already-unlisted record would
+ * otherwise drag `unlistedAt` forward, moving the record's publish moment
+ * with no op reporting it. It also keeps the adapter contract honest —
+ * every key an adapter receives is one it must write.
+ */
+export declare function effectiveChanges(changes: RecordChanges, ops: ChangeOp[]): RecordChanges;
+/**
+ * Whether a merge patch produced the content the record already held.
+ * Compared by serialization: content is JSON by construction — it round
+ * trips through storage that way — and a patch preserves key order for
+ * every field it does not name, so the encoding of an unchanged record is
+ * stable. A reordering patch that changes nothing else is the one case
+ * this reports as a change, which costs an empty version rather than a
+ * wrong answer.
+ */
+export declare function contentEqual(a: Record<string, unknown>, b: Record<string, unknown>): boolean;
+export declare function permissionsEqual(a: Permission[], b: Permission[]): boolean;
+/**
+ * Ensures `creator` carries an `admin` relationship association, adding one
+ * if it's not already present. Used to bootstrap a `_group` record's first
+ * admin at create time.
+ */
+export declare function stampGroupAdmin(associations: Association[] | undefined, creator: EntityId): Association[];
+/**
+ * Whether a Record is a `_group`, in any of its type versions — the family
+ * whose roster rules apply.
+ */
+export declare function isGroupRecord(record: StackRecord): boolean;
+/**
+ * Drops a snapshot's `permissions` — owner-only audit data, never served
+ * to a non-owner history reader. `entityId` (change attribution) stays.
+ * See docs/spec/versioning.md § History access.
+ */
+export declare function stripVersionPermissions(version: RecordVersion): RecordVersion;
+/**
+ * The tombstone a soft-deleted Record is presented as. `permissions` is
+ * retained because it decides whether the caller may undelete; history is
+ * exempt, which is why getVersions() still serves the content this
+ * withholds. See docs/spec/versioning.md § The tombstone is literal.
+ */
+export declare function tombstoneOf(record: StackRecord): StackRecord;
+/** A soft-deleted Record presented as its tombstone; anything else untouched. */
+export declare const presentDeleted: (record: StackRecord) => StackRecord;
+//# sourceMappingURL=record-changes.d.ts.map

package/dist/record-changes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-changes.d.ts","sourceRoot":"","sources":["../src/record-changes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,OAAO,KAAK,EACV,WAAW,EACX,QAAQ,EACR,QAAQ,EACR,UAAU,EACV,aAAa,EACb,aAAa,EACb,kBAAkB,EAClB,WAAW,EACZ,MAAM,YAAY,CAAC;AAEpB;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,WAAW,GAAG,OAAO,CAOxE;AAED,yEAAyE;AACzE,wBAAgB,WAAW,CAAC,CAAC,EAAE,kBAAkB,EAAE,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAQjF;AAED,wBAAgB,eAAe,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,GAAG,OAAO,CAUrE;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,CAQpE;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,WAAW,EACrB,OAAO,EAAE,aAAa,EACtB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAC1C,QAAQ,EAAE,CAyBZ;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,aAAa,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,aAAa,CAUvF;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAE5F;AAED,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,UAAU,EAAE,EAAE,CAAC,EAAE,UAAU,EAAE,GAAG,OAAO,CAE1E;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,YAAY,EAAE,WAAW,EAAE,GAAG,SAAS,EACvC,OAAO,EAAE,QAAQ,GAChB,WAAW,EAAE,CAcf;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAE1D;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,aAAa,GAAG,aAAa,CAI7E;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,WAAW,CAY5D;AAED,iFAAiF;AACjF,eAAO,MAAM,cAAc,GAAI,QAAQ,WAAW,KAAG,WACJ,CAAC"}