@haverstack/core 0.29.0 → 0.31.0

package/dist/grants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grants.d.ts","sourceRoot":"","sources":["../src/grants.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EACV,QAAQ,EACR,WAAW,EACX,YAAY,EACZ,WAAW,EACX,QAAQ,EACR,UAAU,EACV,WAAW,EACZ,MAAM,YAAY,CAAC;AAGpB;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,EAAE,WAAW,CAAC,WAAW,CAA0B,CAAC;AAEjF;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,EAAE,WAAW,CAAC,WAAW,EAAE,SAAS,WAAW,EAAE,CAK3E,CAAC;AAEH;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAIrF;AAED;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG;IAAE,OAAO,EAAE,QAAQ,CAAA;CAAE,GAAG,IAAI,CAAC;AAElE,qFAAqF;AACrF,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAYtF;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAgB7D;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,CAAC,EAAE,YAAY,EACf,OAAO,EAAE,QAAQ,EACjB,IAAI,EAAE;IACJ,YAAY,EAAE,OAAO,CAAC;IACtB,UAAU,EAAE,OAAO,CAAC;IACpB,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAAC,CAAC;IAC1C,aAAa,EAAE,CAAC,EAAE,EAAE,QAAQ,KAAK,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;CAC9D,GACA,OAAO,CAAC,OAAO,CAAC,CAiBlB;AA+BD;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,EAAE,WAAW,CAAC,MAAM,CAIvD,CAAC;AAEH;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,CAAC,CAAC,EAAE,UAAU,KAAK,OAAO,CAAC,WAAW,CAAC,GAC7C,OAAO,CAAC,WAAW,EAAE,CAAC,CAExB"}

package/dist/grants.js

@@ -0,0 +1,157 @@
+/**
+ * Grant vocabulary and coverage
+ * -------------------------------------------------------
+ * What a `_grant` Record says, and who it says it about. The coverage
+ * question — does this grant reach this grantee — is answered here rather
+ * than at each call site so that the access checks and listGrants() cannot
+ * drift apart about it.
+ *
+ * See docs/spec/access-control.md § Type-level grants.
+ */
+import { baseIdOf } from './schema.js';
+import { StackQueryError } from './errors.js';
+import { SYSTEM_TYPES, GRANT_ACTIONS } from './types.js';
+import { groupRoleFromAssociations } from './access.js';
+import { queryAllPages } from './stack-reads.js';
+/**
+ * Valid GrantAction values, for runtime validation in Stack.grant().
+ * Built from GRANT_ACTIONS (types.ts), the source of truth GrantAction is
+ * itself derived from — so this can't drift from the type.
+ */
+export const GRANT_ACTION_SET = new Set(GRANT_ACTIONS);
+/**
+ * The read actions that make a mutate action coherent, scope for scope: a
+ * `-any` verb needs read over the same reach it can mutate, a `-own` verb
+ * needs read over its author's own. A grant carrying neither conveys the
+ * verb to nobody. `create` has no companion — writing a Record you then
+ * cannot read is the drop-box, and it discloses nothing.
+ * See docs/spec/access-control.md § Write implies read.
+ */
+export const READ_COMPANIONS = new Map([
+    ['update-own', ['read-own', 'read-any']],
+    ['delete-own', ['read-own', 'read-any']],
+    ['update-any', ['read-any']],
+    ['delete-any', ['read-any']],
+]);
+/**
+ * Whether one grant's action list conveys `action`. The companion has to
+ * sit in the same `_grant` Record, not merely somewhere in the grantee's
+ * set: a grant is revoked whole, so a rule satisfied across two records
+ * would let revoking the read one leave a mutate-without-read grant
+ * standing — the configuration this rule exists to refuse, arrived at
+ * without anyone writing it.
+ */
+export function grantConveys(actions, action) {
+    if (!actions.includes(action))
+        return false;
+    const companions = READ_COMPANIONS.get(action);
+    return !companions || companions.some((c) => actions.includes(c));
+}
+/** Direct (non-roster) match between a stored _grant's content and a GrantTarget. */
+export function matchesGrantTarget(content, target) {
+    if (target !== null && typeof target === 'object') {
+        // Guarded so an absent groupId can't match the absent granteeGroupId on
+        // every entity-targeted and default grant — `undefined === undefined`
+        // would otherwise sweep them all into a revoke aimed at one group.
+        if (!target.groupId)
+            return false;
+        return content.granteeGroupId === target.groupId;
+    }
+    if (target === null) {
+        return !content.granteeEntityId && !content.granteeGroupId;
+    }
+    return content.granteeEntityId === target;
+}
+/**
+ * Reject a grant target that names nobody. An empty groupId or entityId is
+ * falsy, so a stored record carrying one reads as a *default* grant — every
+ * authenticated entity — instead of the target the caller meant. `null` is
+ * the only way to say "default".
+ */
+export function validateGrantTarget(target) {
+    if (target === null)
+        return;
+    if (typeof target === 'string') {
+        if (target.length === 0) {
+            throw new StackQueryError('A grant target entityId cannot be empty. Pass null for a default grant.');
+        }
+        return;
+    }
+    if (typeof target.groupId !== 'string' || target.groupId.length === 0) {
+        throw new StackQueryError('A group grant target requires a non-empty groupId.');
+    }
+    // Not a format check: granteeGroupId is a reference to an existing
+    // Record, like parentId or an association's recordId, and none of those
+    // are parsed either. One that resolves to nothing simply denies.
+}
+/**
+ * Whether a stored _grant covers `grantee`: a direct DID match, roster
+ * membership when `allowGroup`, or a default when `allowDefault`. Presence
+ * decides the tier, never truthiness — an empty grantee field names nobody.
+ * Module-level so the access checks and listGrants() cannot drift apart.
+ * See docs/spec/access-control.md § Type-level grants.
+ */
+export async function grantCoversGrantee(c, grantee, opts) {
+    const namesEntity = c.granteeEntityId !== undefined;
+    const namesGroup = c.granteeGroupId !== undefined;
+    if (!namesEntity && !namesGroup)
+        return opts.allowDefault;
+    if (namesEntity && c.granteeEntityId !== grantee)
+        return false;
+    if (namesGroup) {
+        if (!opts.allowGroup)
+            return false;
+        if (!c.granteeGroupId)
+            return false;
+        const role = await resolveGroupRoleMemoized(c.granteeGroupId, grantee, opts.groupRoles, opts.resolveRecord);
+        if (role === null)
+            return false;
+    }
+    return true;
+}
+/**
+ * An entity's role on a `_group` roster, memoized in the caller's
+ * `groupRoles` map. That map is built per operation and threaded alongside
+ * `prefetchedGrants`, so no resolved role outlives the operation that
+ * resolved it — removal from a group must never go stale.
+ * See docs/spec/access-control.md § Type-level grants.
+ */
+async function resolveGroupRoleMemoized(groupId, entityId, groupRoles, resolveRecord) {
+    const key = `${groupId}:${entityId}`;
+    const cached = groupRoles.get(key);
+    if (cached !== undefined)
+        return cached;
+    const group = await resolveRecord(groupId);
+    // Only a real `_group` Record carries a roster. Without the family check
+    // any Record's relationship associations would serve as one, and a group
+    // migrated out of the family would keep resolving after it had stopped
+    // being a group.
+    const role = group && baseIdOf(group.typeId) === SYSTEM_TYPES.GROUP
+        ? groupRoleFromAssociations(group.associations, entityId)
+        : null;
+    groupRoles.set(key, role);
+    return role;
+}
+/**
+ * System type families grant() refuses to target: a grant on any of them
+ * would let the grantee mint their own grants, touch stack config, or
+ * register an app card claiming a DID that isn't theirs — the last of
+ * which is what verified app attribution rests on. See
+ * docs/spec/access-control.md § Type-level grants.
+ */
+export const UNGRANTABLE_SYSTEM_TYPES = new Set([
+    SYSTEM_TYPES.GRANT,
+    SYSTEM_TYPES.CONFIG,
+    SYSTEM_TYPES.APP,
+]);
+/**
+ * Every `_grant` Record, cursor-walked. Read through an unscoped query at
+ * every call site: a grant is what decides who may read, so it can never
+ * itself sit behind a read check. No content prefilter — a stored grant's
+ * typeId may be a bare baseId or versioned, so exact matching would wrongly
+ * exclude family versions.
+ */
+export function loadGrantRecords(query) {
+    return queryAllPages(query, { filter: { typeId: `${SYSTEM_TYPES.GRANT}@1` } });
+}
+//# sourceMappingURL=grants.js.map

package/dist/grants.js.map

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

package/dist/id.d.ts

@@ -15,9 +15,6 @@ export declare const RAND_SUFFIX_LENGTH = 3;
 export declare class IdGenerationError extends Error {
     constructor(message?: string);
 }
-export declare class IdGenerationOverflowError extends IdGenerationError {
-    constructor(message?: string);
-}
 export declare const crockford32Encode: (n: number) => string;
 export declare const crockford32Decode: (s: string) => number;
 export declare const _setLastNowId: (chars: string) => void;
@@ -39,8 +36,13 @@ export declare const MAX_ID_TIMESTAMP: number;
 /**
  * Generate a new Stack record ID. Time-sortable: lexicographic order
  * matches creation order, with same-millisecond IDs monotonically
- * incremented. Throws IdGenerationOverflowError past 32^3 IDs in one
- * millisecond.
+ * incremented.
+ *
+ * A millisecond whose suffix space is spent carries into the next one
+ * rather than failing, so how many IDs a millisecond holds never depends
+ * on where its random suffix happened to start — which is what keeps the
+ * order total and the call free of a capacity a caller cannot see.
+ * See docs/spec/data-model.md § Record IDs.
  *
  * @param timestamp - Override the timestamp (ms since epoch). Defaults to Date.now().
  */

package/dist/id.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"id.d.ts","sourceRoot":"","sources":["../src/id.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,eAAO,MAAM,IAAI,QAAoB,CAAC;AAGtC,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAcpC,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,OAAO,SAAK;CAIzB;AAED,qBAAa,yBAA0B,SAAQ,iBAAiB;gBAClD,OAAO,SAAK;CAIzB;AAMD,eAAO,MAAM,iBAAiB,GAAI,GAAG,MAAM,KAAG,MAiB7C,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAAI,GAAG,MAAM,KAAG,MAe7C,CAAC;AAoCF,eAAO,MAAM,aAAa,GAAI,OAAO,MAAM,KAAG,IAK7C,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAAI,OAAO,MAAM,KAAG,IAKjD,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAAI,WAAW,MAAM,KAAG,IAErD,CAAC;AAEF,wEAAwE;AACxE,eAAO,MAAM,aAAa,QAAO,IAIhC,CAAC;AAMF;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB,QAA2C,CAAC;AAEzE;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,GAAI,YAAW,MAAmB,KAAG,MAU3D,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,sBAAsB,GAAI,WAAW,MAAM,KAAG,MAS1D,CAAC;AASF;;;;GAIG;AACH,eAAO,MAAM,eAAe,GAAI,IAAI,MAAM,KAAG,OAA6B,CAAC;AAE3E;;;GAGG;AACH,eAAO,MAAM,WAAW,GAAI,IAAI,MAAM,KAAG,MACa,CAAC"}
+{"version":3,"file":"id.d.ts","sourceRoot":"","sources":["../src/id.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,eAAO,MAAM,IAAI,QAAoB,CAAC;AAGtC,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAcpC,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,OAAO,SAAK;CAIzB;AAMD,eAAO,MAAM,iBAAiB,GAAI,GAAG,MAAM,KAAG,MAiB7C,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAAI,GAAG,MAAM,KAAG,MAe7C,CAAC;AAkCF,eAAO,MAAM,aAAa,GAAI,OAAO,MAAM,KAAG,IAK7C,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAAI,OAAO,MAAM,KAAG,IAKjD,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAAI,WAAW,MAAM,KAAG,IAErD,CAAC;AAEF,wEAAwE;AACxE,eAAO,MAAM,aAAa,QAAO,IAIhC,CAAC;AAMF;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB,QAA2C,CAAC;AAEzE;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,UAAU,GAAI,YAAW,MAAmB,KAAG,MAgB3D,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,sBAAsB,GAAI,WAAW,MAAM,KAAG,MAS1D,CAAC;AASF;;;;GAIG;AACH,eAAO,MAAM,eAAe,GAAI,IAAI,MAAM,KAAG,OAA6B,CAAC;AAE3E;;;GAGG;AACH,eAAO,MAAM,WAAW,GAAI,IAAI,MAAM,KAAG,MACa,CAAC"}

package/dist/id.js

@@ -30,12 +30,6 @@ export class IdGenerationError extends Error {
         this.name = 'IdGenerationError';
     }
 }
-export class IdGenerationOverflowError extends IdGenerationError {
-    constructor(message = '') {
-        super(message || 'Too many IDs have been generated in the same millisecond.');
-        this.name = 'IdGenerationOverflowError';
-    }
-}
 // -------------------------------------------------------
 // Encoding / decoding
 // -------------------------------------------------------
@@ -88,12 +82,10 @@ const generateRandChars = () => {
     } while (value > Math.floor(0xffffffff / modulus) * modulus);
     return pad(crockford32Encode(value % modulus), RAND_SUFFIX_LENGTH);
 };
+/** The next suffix after `randChars`, or null once the space is spent. */
 const incrementRandChars = (randChars) => {
     const next = crockford32Encode(crockford32Decode(randChars) + 1);
-    if (next.length > RAND_SUFFIX_LENGTH) {
-        throw new IdGenerationOverflowError();
-    }
-    return pad(next, RAND_SUFFIX_LENGTH);
+    return next.length > RAND_SUFFIX_LENGTH ? null : pad(next, RAND_SUFFIX_LENGTH);
 };
 // -------------------------------------------------------
 // Test hooks (package-private)
@@ -136,15 +128,25 @@ export const MAX_ID_TIMESTAMP = Math.pow(BASE, MIN_TIMESTAMP_LENGTH) - 1;
 /**
  * Generate a new Stack record ID. Time-sortable: lexicographic order
  * matches creation order, with same-millisecond IDs monotonically
- * incremented. Throws IdGenerationOverflowError past 32^3 IDs in one
- * millisecond.
+ * incremented.
+ *
+ * A millisecond whose suffix space is spent carries into the next one
+ * rather than failing, so how many IDs a millisecond holds never depends
+ * on where its random suffix happened to start — which is what keeps the
+ * order total and the call free of a capacity a caller cannot see.
+ * See docs/spec/data-model.md § Record IDs.
  *
  * @param timestamp - Override the timestamp (ms since epoch). Defaults to Date.now().
  */
 export const generateId = (timestamp = Date.now()) => {
-    const effectiveTimestamp = Math.max(timestamp, lastTimestamp);
-    const nowId = pad(crockford32Encode(effectiveTimestamp), MIN_TIMESTAMP_LENGTH);
-    const randChars = nowId !== lastNowId ? generateRandChars() : incrementRandChars(lastRandChars);
+    let effectiveTimestamp = Math.max(timestamp, lastTimestamp);
+    let nowId = pad(crockford32Encode(effectiveTimestamp), MIN_TIMESTAMP_LENGTH);
+    let randChars = nowId === lastNowId ? incrementRandChars(lastRandChars) : generateRandChars();
+    if (randChars === null) {
+        effectiveTimestamp += 1;
+        nowId = pad(crockford32Encode(effectiveTimestamp), MIN_TIMESTAMP_LENGTH);
+        randChars = generateRandChars();
+    }
     lastTimestamp = effectiveTimestamp;
     lastNowId = nowId;
     lastRandChars = randChars;

package/dist/id.js.map

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

package/dist/identity-bindings.d.ts

@@ -0,0 +1,13 @@
+/**
+ * DID bindings
+ * -------------------------------------------------------
+ * Which content fields are lookup keys rather than display values, and
+ * which of those a stack resolves *by*. Every one is immutable once set;
+ * the unique subset is additionally one-per-stack, because a lookup with
+ * two answers is all an impersonating card needs.
+ *
+ * See docs/spec/identity.md § DID bindings.
+ */
+export declare const bindingFieldsOf: (family: string) => readonly ("did" | "appId")[];
+export declare const uniqueBindingFieldsOf: (family: string) => readonly ("did" | "appId")[];
+//# sourceMappingURL=identity-bindings.d.ts.map

package/dist/identity-bindings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity-bindings.d.ts","sourceRoot":"","sources":["../src/identity-bindings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAkCH,eAAO,MAAM,eAAe,GAAI,QAAQ,MAAM,KAAG,SAAS,CAAC,KAAK,GAAG,OAAO,CAAC,EACzC,CAAC;AAEnC,eAAO,MAAM,qBAAqB,GAAI,QAAQ,MAAM,KAAG,SAAS,CAAC,KAAK,GAAG,OAAO,CAAC,EACxC,CAAC"}

package/dist/identity-bindings.js

@@ -0,0 +1,42 @@
+/**
+ * DID bindings
+ * -------------------------------------------------------
+ * Which content fields are lookup keys rather than display values, and
+ * which of those a stack resolves *by*. Every one is immutable once set;
+ * the unique subset is additionally one-per-stack, because a lookup with
+ * two answers is all an impersonating card needs.
+ *
+ * See docs/spec/identity.md § DID bindings.
+ */
+import { SYSTEM_TYPES } from './types.js';
+/**
+ * Content fields that are lookup keys rather than display values: a card
+ * claims one, and something later resolves through it. Every one of them is
+ * immutable once set. See docs/spec/identity.md § DID bindings.
+ */
+const BINDING_FIELDS = new Map([
+    [SYSTEM_TYPES.APP, ['did', 'appId']],
+    [SYSTEM_TYPES.ENTITY, ['did']],
+]);
+/**
+ * The subset that is additionally unique per stack: the fields something
+ * resolves *by*. A Record's `principalId` finds its card by `_app.did` and
+ * its `entityId` by `_entity.did`, so a second card claiming either leaves
+ * that lookup without a single answer — and ambiguity is all an
+ * impersonating card needs.
+ *
+ * `_app.appId` is deliberately absent. Nothing resolves a card by it — the
+ * cross-check reaches the card by `did` and only compares `appId` — so
+ * uniqueness would buy no disambiguation, while forbidding the second card
+ * key rotation is supposed to produce: `appId` is required, so a
+ * replacement card for the same software necessarily repeats it. Moving one
+ * card onto another's `appId` is what immutability already refuses.
+ * See docs/spec/identity.md § DID bindings.
+ */
+const UNIQUE_BINDING_FIELDS = new Map([
+    [SYSTEM_TYPES.APP, ['did']],
+    [SYSTEM_TYPES.ENTITY, ['did']],
+]);
+export const bindingFieldsOf = (family) => BINDING_FIELDS.get(family) ?? [];
+export const uniqueBindingFieldsOf = (family) => UNIQUE_BINDING_FIELDS.get(family) ?? [];
+//# sourceMappingURL=identity-bindings.js.map

package/dist/identity-bindings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity-bindings.js","sourceRoot":"","sources":["../src/identity-bindings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1C;;;;GAIG;AACH,MAAM,cAAc,GAAsD,IAAI,GAAG,CAAC;IAChF,CAAC,YAAY,CAAC,GAAG,EAAE,CAAC,KAAK,EAAE,OAAO,CAAU,CAAC;IAC7C,CAAC,YAAY,CAAC,MAAM,EAAE,CAAC,KAAK,CAAU,CAAC;CACxC,CAAC,CAAC;AAEH;;;;;;;;;;;;;;GAcG;AACH,MAAM,qBAAqB,GAAsD,IAAI,GAAG,CAAC;IACvF,CAAC,YAAY,CAAC,GAAG,EAAE,CAAC,KAAK,CAAU,CAAC;IACpC,CAAC,YAAY,CAAC,MAAM,EAAE,CAAC,KAAK,CAAU,CAAC;CACxC,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,MAAc,EAAgC,EAAE,CAC9E,cAAc,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;AAEnC,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,MAAc,EAAgC,EAAE,CACpF,qBAAqB,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC"}

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, 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 } 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, MissingCapability, 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,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,iBAAiB,EACjB,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;AAwEpB,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;AA8DrB,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/query-validation.d.ts

@@ -0,0 +1,83 @@
+/**
+ * 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. A refusal names the
+ * capability it was refused for on the error itself, so a client reporting
+ * it in its own vocabulary reads that name rather than re-deriving it from
+ * the query — one rule, one answer.
+ * 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;;;;;;;;;;;;;;;;;GAiBG;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,CAmCN;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,CAmBN;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"}