@haverstack/core 0.39.0 → 0.41.0

package/dist/index.js

@@ -20,6 +20,9 @@
 // Core class and client interface
 export { Stack } from './stack.js';
 export { ScopedStack } from './scoped-stack.js';
+export { isPlanEmpty } from './install.js';
+// Type handles
+export { typeHandle } from './type-handle.js';
 // The error taxonomy
 export { StackError, StackValidationError, StackMigrationError, StackPermissionError, StackNotFoundError, StackConflictError, StackVersionConflictError, StackBadRequestError, StackSchemaDriftError, StackPayloadTooLargeError, StackTimeoutError, } from './errors.js';
 // Local errors outside the taxonomy — no wire representation, and no
@@ -32,4 +35,5 @@ export { SYSTEM_TYPES, NATIVE_SORT_FIELDS } from './types.js';
 export { generateId } from './id.js';
 export { hashSchema, isCompatible } from './schema.js';
 export { applyMergePatch } from './merge.js';
+export { assertOneSurface } from './record-changes.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,kCAAkC;AAClC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAehD,qBAAqB;AACrB,OAAO,EACL,UAAU,EACV,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACpB,kBAAkB,EAClB,kBAAkB,EAClB,yBAAyB,EACzB,oBAAoB,EACpB,qBAAqB,EACrB,yBAAyB,EACzB,iBAAiB,GAClB,MAAM,aAAa,CAAC;AACrB,qEAAqE;AACrE,oEAAoE;AACpE,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AA4EvF,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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,kCAAkC;AAClC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAgBhD,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C,eAAe;AACf,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAc9C,qBAAqB;AACrB,OAAO,EACL,UAAU,EACV,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACpB,kBAAkB,EAClB,kBAAkB,EAClB,yBAAyB,EACzB,oBAAoB,EACpB,qBAAqB,EACrB,yBAAyB,EACzB,iBAAiB,GAClB,MAAM,aAAa,CAAC;AACrB,qEAAqE;AACrE,oEAAoE;AACpE,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAgFvF,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;AAC7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/install.d.ts

@@ -0,0 +1,144 @@
+/**
+ * App installs
+ * -------------------------------------------------------
+ * An app the owner does not run ships a manifest — the types it defines
+ * and the type-level grants it asks for — and the owner applies it with
+ * `Stack.planInstall()` then `Stack.installApp()`. What the stack keeps is
+ * not the manifest but the owner's approval of it: an `_install` Record,
+ * one per `appId`, linked by association to the `_app` cards it was
+ * installed for and the `_grant` Records it produced. Its version history
+ * is the upgrade log, and soft-deleting it is uninstalling.
+ *
+ * An install claims the families it defines, one install per family. That
+ * claim is what lets a contained app commit migrations within its own
+ * families without the owner running its code — see
+ * ScopedStack.commitMigration().
+ *
+ * This module holds the parts that read an install as data: the write-time
+ * shape rules, the family claim, and the plan diff. The verbs that write
+ * live on `Stack`. See docs/spec/apps.md.
+ */
+import type { AppId, AuthorityAssociation, BaseId, EntityId, GrantContent, InstallContent, InstallRequest, RecordId, RelationshipAssociation, StackRecord, TypeId } from './types.js';
+import type { DefineTypeOptions } from './stack.js';
+import type { ValidationError } from './validate.js';
+/** What an app ships: the types it defines and the grants it asks for. */
+export type AppManifest = {
+    appId: AppId;
+    name: string;
+    version?: string;
+    types: DefineTypeOptions[];
+    requests: InstallRequest[];
+};
+/** A request on a family this install does not define, and who owns that family. */
+export type ForeignRequest = InstallRequest & {
+    /**
+     * The app whose namespace the family is in, whether or not it is
+     * installed; `'commons'` or `'system'` for families no app owns; null
+     * for a family with no namespace.
+     */
+    owner: AppId | 'commons' | 'system' | null;
+};
+/**
+ * A manifest type whose definition would write: one not yet defined, or
+ * defined with a different schema or name. Commons types included, since
+ * defining one claims nothing but still fixes its shape for every app.
+ */
+export type TypeChange = {
+    id: TypeId;
+    change: 'new' | 'schema' | 'name';
+};
+/**
+ * What applying a manifest would change, for the owner to approve.
+ * `installApp()` applies a plan only while it is still what planning the
+ * same manifest would produce. See docs/spec/apps.md § Plan, then apply.
+ */
+export type InstallPlan = {
+    manifest: AppManifest;
+    /** The key being installed. */
+    did: EntityId;
+    /** The install as it stood when planned — null for a first install. */
+    existing: (StackRecord & {
+        content: InstallContent;
+    }) | null;
+    /** Families this install would claim that it does not claim yet. */
+    newFamilies: BaseId[];
+    /** Type versions not yet in the install's `defines`. */
+    newVersions: TypeId[];
+    requestsAdded: InstallRequest[];
+    requestsRemoved: InstallRequest[];
+    /** Requests on families the manifest does not define — the ones an approval most needs to show. */
+    foreignRequests: ForeignRequest[];
+    /** Every manifest type `installApp()` would define or redefine. */
+    typeChanges: TypeChange[];
+    /**
+     * Whether `did` would gain access: not yet linked to this install, or
+     * linked through an `_app` card that is soft-deleted, which installApp()
+     * undeletes. See docs/spec/apps.md § Plan, then apply.
+     */
+    newKey: boolean;
+    /**
+     * The keys already linked to the install. Each holds `requests`, so a
+     * plan that changes them changes every one — and a new key joins them
+     * as the same app. See docs/spec/apps.md § Plan, then apply.
+     */
+    linkedKeys: EntityId[];
+};
+/** Relationship label from an install to an `_app` card it was installed for. */
+export declare const INSTALL_APP_LABEL = "install.app";
+/** Relationship label from an install to a `_grant` it produced. */
+export declare const INSTALL_GRANT_LABEL = "install.grant";
+export declare const installAppLink: (recordId: RecordId) => RelationshipAssociation;
+export declare const installGrantLink: (recordId: RecordId) => RelationshipAssociation;
+/** Record-level `read` on an install for one of its keys. */
+export declare const installReader: (entityId: EntityId) => AuthorityAssociation;
+/** Record ids an install links to under `label`. */
+export declare function linkedIds(record: StackRecord, label: string): RecordId[];
+export declare const isSystemFamily: (baseId: BaseId) => boolean;
+/** The Schema Commons namespace: families no app owns. See docs/commons/README.md. */
+export declare const COMMONS_NAMESPACE = "org.haverstack";
+/** The part of a family before its `/` — `com.example.notes` for `com.example.notes/note`. */
+export declare const namespaceOf: (baseId: BaseId) => string | null;
+/**
+ * How a family stands toward the app `appId`: its own (the family's
+ * namespace is the `appId`), a commons or system family nobody owns, or
+ * another app's. Only an app's own families can be claimed, so which app
+ * owns a family never depends on which was installed first.
+ * See docs/spec/apps.md § Who owns a family.
+ */
+export declare function familyStanding(baseId: BaseId, appId: AppId): 'own' | 'commons' | 'system' | 'foreign';
+/**
+ * The families an install claims, read as data: entries that are not
+ * well-formed TypeIds claim nothing.
+ */
+export declare function claimedFamilies(content: unknown): Set<BaseId>;
+/**
+ * An `_install`'s `defines` and `requests`, asked of its content on every
+ * write. A schema can say both are lists; only this can say what their
+ * entries must name. See docs/spec/apps.md § The `_install` record.
+ */
+export declare function validateInstall(typeId: TypeId, content: unknown): ValidationError[];
+/** The manifest's types in its own namespace — the versions an install of it defines. */
+export declare function ownTypeIds(manifest: AppManifest): TypeId[];
+/**
+ * A deep-frozen copy of `manifest`, so the plan that holds it applies what
+ * was reviewed even if the caller's object changes afterwards.
+ */
+export declare function snapshotManifest(manifest: AppManifest): AppManifest;
+/** Whether two requests ask for the same family and exactly the same actions. */
+export declare function sameRequest(a: InstallRequest, b: InstallRequest): boolean;
+/** Whether a stored grant is exactly `request`, made out to `did`. */
+export declare function grantIsRequest(grant: GrantContent, request: InstallRequest, did: EntityId): boolean;
+/**
+ * Whether applying `plan` would change nothing: the install is live, this
+ * key is linked to it, the manifest adds and removes nothing, and its
+ * `name` and `version` are the ones the install holds. A server
+ * answers such a request as already installed rather than queuing it.
+ * See docs/spec/wire-format.md § Installs.
+ */
+export declare function isPlanEmpty(plan: InstallPlan): boolean;
+/**
+ * The parts of a plan that depend on the stack's state — what
+ * `installApp()` compares to refuse a stale one.
+ */
+export declare function planFingerprint(plan: InstallPlan): string;
+//# sourceMappingURL=install.d.ts.map

package/dist/install.d.ts.map

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

package/dist/install.js

@@ -0,0 +1,223 @@
+/**
+ * App installs
+ * -------------------------------------------------------
+ * An app the owner does not run ships a manifest — the types it defines
+ * and the type-level grants it asks for — and the owner applies it with
+ * `Stack.planInstall()` then `Stack.installApp()`. What the stack keeps is
+ * not the manifest but the owner's approval of it: an `_install` Record,
+ * one per `appId`, linked by association to the `_app` cards it was
+ * installed for and the `_grant` Records it produced. Its version history
+ * is the upgrade log, and soft-deleting it is uninstalling.
+ *
+ * An install claims the families it defines, one install per family. That
+ * claim is what lets a contained app commit migrations within its own
+ * families without the owner running its code — see
+ * ScopedStack.commitMigration().
+ *
+ * This module holds the parts that read an install as data: the write-time
+ * shape rules, the family claim, and the plan diff. The verbs that write
+ * live on `Stack`. See docs/spec/apps.md.
+ */
+import { baseIdOf, familyIdProblem, parseTypeId } from './schema.js';
+import { GRANT_ACTION_SET, UNGRANTABLE_SYSTEM_TYPES } from './grants.js';
+import { SYSTEM_TYPES } from './types.js';
+/** Relationship label from an install to an `_app` card it was installed for. */
+export const INSTALL_APP_LABEL = 'install.app';
+/** Relationship label from an install to a `_grant` it produced. */
+export const INSTALL_GRANT_LABEL = 'install.grant';
+export const installAppLink = (recordId) => ({
+    kind: 'relationship',
+    label: INSTALL_APP_LABEL,
+    target: { kind: 'record', recordId },
+});
+export const installGrantLink = (recordId) => ({
+    kind: 'relationship',
+    label: INSTALL_GRANT_LABEL,
+    target: { kind: 'record', recordId },
+});
+/** Record-level `read` on an install for one of its keys. */
+export const installReader = (entityId) => ({
+    kind: 'permission',
+    label: 'read',
+    grantee: { kind: 'entity', entityId },
+});
+/** Record ids an install links to under `label`. */
+export function linkedIds(record, label) {
+    const ids = [];
+    for (const a of record.associations ?? []) {
+        if (a.kind === 'relationship' && a.label === label && a.target.kind === 'record') {
+            ids.push(a.target.recordId);
+        }
+    }
+    return ids;
+}
+const SYSTEM_FAMILIES = new Set(Object.values(SYSTEM_TYPES));
+export const isSystemFamily = (baseId) => SYSTEM_FAMILIES.has(baseId);
+/** The Schema Commons namespace: families no app owns. See docs/commons/README.md. */
+export const COMMONS_NAMESPACE = 'org.haverstack';
+/** The part of a family before its `/` — `com.example.notes` for `com.example.notes/note`. */
+export const namespaceOf = (baseId) => {
+    const slash = baseId.indexOf('/');
+    return slash > 0 ? baseId.slice(0, slash) : null;
+};
+/**
+ * How a family stands toward the app `appId`: its own (the family's
+ * namespace is the `appId`), a commons or system family nobody owns, or
+ * another app's. Only an app's own families can be claimed, so which app
+ * owns a family never depends on which was installed first.
+ * See docs/spec/apps.md § Who owns a family.
+ */
+export function familyStanding(baseId, appId) {
+    if (isSystemFamily(baseId))
+        return 'system';
+    const namespace = namespaceOf(baseId);
+    if (namespace === COMMONS_NAMESPACE)
+        return 'commons';
+    return namespace === appId ? 'own' : 'foreign';
+}
+/**
+ * The families an install claims, read as data: entries that are not
+ * well-formed TypeIds claim nothing.
+ */
+export function claimedFamilies(content) {
+    const defines = content?.defines;
+    const families = new Set();
+    if (!Array.isArray(defines))
+        return families;
+    for (const id of defines) {
+        if (typeof id !== 'string')
+            continue;
+        const parsed = parseTypeId(id);
+        if (parsed)
+            families.add(parsed.baseId);
+    }
+    return families;
+}
+/**
+ * An `_install`'s `defines` and `requests`, asked of its content on every
+ * write. A schema can say both are lists; only this can say what their
+ * entries must name. See docs/spec/apps.md § The `_install` record.
+ */
+export function validateInstall(typeId, content) {
+    if (baseIdOf(typeId) !== SYSTEM_TYPES.INSTALL)
+        return [];
+    const c = content;
+    const errors = [];
+    if (Array.isArray(c?.defines)) {
+        c.defines.forEach((id, i) => {
+            const parsed = typeof id === 'string' ? parseTypeId(id) : null;
+            if (!parsed) {
+                errors.push({ path: `defines[${i}]`, message: 'Expected a versioned TypeId' });
+            }
+            else if (typeof c?.appId === 'string' && familyStanding(parsed.baseId, c.appId) !== 'own') {
+                errors.push({
+                    path: `defines[${i}]`,
+                    message: `"${parsed.baseId}" is outside the namespace "${c.appId}"; an install claims only its own families`,
+                });
+            }
+        });
+    }
+    if (Array.isArray(c?.requests)) {
+        c.requests.forEach((r, i) => {
+            const req = r;
+            const problem = familyIdProblem(req?.baseId, `requests[${i}].baseId`);
+            if (problem) {
+                errors.push({ path: `requests[${i}].baseId`, message: problem });
+            }
+            else if (UNGRANTABLE_SYSTEM_TYPES.has(req.baseId)) {
+                errors.push({
+                    path: `requests[${i}].baseId`,
+                    message: `"${String(req.baseId)}" cannot be granted, so no install can request it`,
+                });
+            }
+            if (Array.isArray(req?.actions)) {
+                req.actions.forEach((a, j) => {
+                    if (!GRANT_ACTION_SET.has(a)) {
+                        errors.push({
+                            path: `requests[${i}].actions[${j}]`,
+                            message: `Unknown grant action "${String(a)}"`,
+                        });
+                    }
+                });
+            }
+        });
+    }
+    return errors;
+}
+/** The manifest's types in its own namespace — the versions an install of it defines. */
+export function ownTypeIds(manifest) {
+    const ids = manifest.types
+        .map((t) => t.id)
+        .filter((id) => familyStanding(baseIdOf(id), manifest.appId) === 'own');
+    return [...new Set(ids)];
+}
+/**
+ * A deep-frozen copy of `manifest`, so the plan that holds it applies what
+ * was reviewed even if the caller's object changes afterwards.
+ */
+export function snapshotManifest(manifest) {
+    return deepFreeze(structuredClone(manifest));
+}
+function deepFreeze(value) {
+    if (typeof value === 'object' && value !== null && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const v of Object.values(value))
+            deepFreeze(v);
+    }
+    return value;
+}
+/** Whether two requests ask for the same family and exactly the same actions. */
+export function sameRequest(a, b) {
+    if (a.baseId !== b.baseId)
+        return false;
+    const as = new Set(a.actions);
+    const bs = new Set(b.actions);
+    return as.size === bs.size && [...bs].every((x) => as.has(x));
+}
+/** Whether a stored grant is exactly `request`, made out to `did`. */
+export function grantIsRequest(grant, request, did) {
+    if (grant.grantee?.kind !== 'entity' || grant.grantee.entityId !== did)
+        return false;
+    if (!Array.isArray(grant.actions))
+        return false;
+    return sameRequest({ baseId: grant.baseId, actions: grant.actions }, request);
+}
+/**
+ * Whether applying `plan` would change nothing: the install is live, this
+ * key is linked to it, the manifest adds and removes nothing, and its
+ * `name` and `version` are the ones the install holds. A server
+ * answers such a request as already installed rather than queuing it.
+ * See docs/spec/wire-format.md § Installs.
+ */
+export function isPlanEmpty(plan) {
+    return (plan.existing !== null &&
+        !plan.existing.deletedAt &&
+        !plan.newKey &&
+        plan.manifest.name === plan.existing.content.name &&
+        (plan.manifest.version ?? null) === (plan.existing.content.version ?? null) &&
+        plan.newFamilies.length === 0 &&
+        plan.newVersions.length === 0 &&
+        plan.typeChanges.length === 0 &&
+        plan.requestsAdded.length === 0 &&
+        plan.requestsRemoved.length === 0);
+}
+/**
+ * The parts of a plan that depend on the stack's state — what
+ * `installApp()` compares to refuse a stale one.
+ */
+export function planFingerprint(plan) {
+    return JSON.stringify([
+        plan.existing?.id ?? null,
+        plan.existing?.version ?? null,
+        plan.existing?.deletedAt ? true : false,
+        plan.newFamilies,
+        plan.newVersions,
+        plan.requestsAdded,
+        plan.requestsRemoved,
+        plan.foreignRequests,
+        plan.typeChanges,
+        plan.newKey,
+        plan.linkedKeys,
+    ]);
+}
+//# sourceMappingURL=install.js.map

package/dist/install.js.map

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

package/dist/query-validation.d.ts

@@ -17,7 +17,7 @@
  * See docs/spec/data-model.md § Capability-gated filters.
  */
 import type { ValidationError } from './validate.js';
-import type { Association, AuthorityAssociation, DataAssociation, GrantGrantee, JournalQuery, QuerySort, RecordFilter, RelationshipTarget, StackCapabilities } from './types.js';
+import type { Association, AssociationEdit, AuthorityAssociation, DataAssociation, GrantGrantee, JournalQuery, VersionsQuery, QuerySort, RecordFilter, RelationshipTarget, StackCapabilities } 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
@@ -53,6 +53,16 @@ export declare function parseContentFilterKey(key: string): string[];
  * it. See docs/spec/data-model.md § Sorting and pagination.
  */
 export declare function assertValidSort(sort: QuerySort | undefined): void;
+/**
+ * The sort every adapter receives: a named sort with no `direction` is
+ * ascending, resolved here so no adapter carries its own default. No sort
+ * stays absent — the adapter's unsorted order is `createdAt` newest first,
+ * and an explicit sort would be re-checked against the server's declared
+ * `sort.fields`. See docs/spec/data-model.md § Sorting and pagination.
+ */
+export declare function normalizeSort(sort: QuerySort | undefined): (QuerySort & {
+    direction: 'asc' | 'desc';
+}) | undefined;
 /**
  * Fail loud rather than silently reorder: an adapter that can't honor the
  * requested sort would otherwise answer in some other order, which a
@@ -118,6 +128,15 @@ export declare function assertAuthorityAssociations(permissions: readonly Associ
  * See docs/spec/data-model.md § Associations.
  */
 export declare function validateAssociations(associations: Association[] | undefined, path?: string): ValidationError[];
+/**
+ * Hold an association edit list to the rules every verb shares: non-empty,
+ * every element a known `op` over a well-formed association, one surface,
+ * and each identity named once — a list that both removes and adds one
+ * identity is the same ambiguity as naming it twice. `repoint` is the
+ * journal's word, never a request. Asked of the whole list before anything
+ * is read or written. See docs/spec/data-model.md § Mutations.
+ */
+export declare function assertAssociationEdits(changes: unknown, surface: string, half: 'data' | 'authority'): asserts changes is AssociationEdit[];
 /**
  * Reject an association filter that names neither of its halves, or whose
  * relationship target is malformed. `RelatedToFilter` and `AttachmentFilter`
@@ -126,6 +145,14 @@ export declare function validateAssociations(associations: Association[] | undef
  * any association of that kind. See docs/spec/data-model.md § Filter.
  */
 export declare function assertValidAssociationFilters(filter: RecordFilter | undefined): void;
+/**
+ * Refuse a `baseId` carrying an `@version` suffix. A family filter resolves
+ * against registered families, so a TypeId there would match nothing and
+ * say nothing. See docs/spec/data-model.md § Filter.
+ */
+export declare function assertValidBaseIdFilter(filter: {
+    baseId?: string | string[];
+} | undefined): void;
 /**
  * Hold a journal window to the shape both adapters can honor identically.
  *
@@ -140,4 +167,10 @@ export declare function assertValidAssociationFilters(filter: RecordFilter | und
  * reconstructing an association's full history.
  */
 export declare function assertValidJournalQuery(query: JournalQuery | undefined): void;
+/**
+ * Refuse a `getVersions()` window the adapters would read differently, as
+ * assertValidJournalQuery() does for the journal. No ceiling is imposed:
+ * omitting `limit` reads every version by contract.
+ */
+export declare function assertValidVersionsQuery(query: VersionsQuery | undefined): void;
 //# sourceMappingURL=query-validation.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"query-validation.d.ts","sourceRoot":"","sources":["../src/query-validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD,OAAO,KAAK,EAEV,WAAW,EAEX,oBAAoB,EACpB,eAAe,EAGf,YAAY,EACZ,YAAY,EAMZ,SAAS,EACT,YAAY,EACZ,kBAAkB,EAElB,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAEpB;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,YAAY,GAAG,SAAS,EAChC,YAAY,EAAE,IAAI,CAAC,iBAAiB,EAAE,QAAQ,CAAC,GAC9C,IAAI,CAmCN;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,IAAI,CAAC,iBAAiB,EAAE,QAAQ,CAAC,GAAG,OAAO,CAEnF;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,CA6BjE;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,SAAS,GAAG,SAAS,EAC3B,YAAY,EAAE,IAAI,CAAC,iBAAiB,EAAE,MAAM,CAAC,GAC5C,IAAI,CAmBN;AAYD,sDAAsD;AACtD,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,kBAAkB,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAI7E,CAAC;AAgBF,qEAAqE;AACrE,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,YAAY,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAIxE,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAE5E;AAED,2EAA2E;AAC3E,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAM1F;AAwCD;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,WAAW,EACxB,IAAI,SAAgB,GACnB,eAAe,EAAE,CAoBnB;AAsED;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CACpC,YAAY,EAAE,SAAS,WAAW,EAAE,EACpC,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,YAAY,IAAI,eAAe,EAAE,CAO3C;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CACzC,WAAW,EAAE,SAAS,WAAW,EAAE,EACnC,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,WAAW,IAAI,oBAAoB,EAAE,CAO/C;AAED,kEAAkE;AAClE;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,YAAY,EAAE,WAAW,EAAE,GAAG,SAAS,EACvC,IAAI,SAAiB,GACpB,eAAe,EAAE,CAenB;AAED;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,YAAY,GAAG,SAAS,GAAG,IAAI,CAmBpF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,YAAY,GAAG,SAAS,GAAG,IAAI,CAW7E"}
+{"version":3,"file":"query-validation.d.ts","sourceRoot":"","sources":["../src/query-validation.ts"],"names":[],"mappings":"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"}

package/dist/query-validation.js

@@ -16,7 +16,8 @@
  * the query — one rule, one answer.
  * See docs/spec/data-model.md § Capability-gated filters.
  */
-import { StackBadRequestError } from './errors.js';
+import { StackBadRequestError, StackValidationError } from './errors.js';
+import { familyIdProblem } from './schema.js';
 import { associationEqual, isAuthorityAssociation } from './record-changes.js';
 import { CONTENT_SEGMENT_METACHARACTERS, SEGMENT_METACHARACTER_RE } from './validate.js';
 import { NATIVE_SORT_FIELDS } from './types.js';
@@ -132,6 +133,18 @@ export function assertValidSort(sort) {
         throw new StackBadRequestError(`Invalid sort direction "${sort.direction}": expected "asc" or "desc".`);
     }
 }
+/**
+ * The sort every adapter receives: a named sort with no `direction` is
+ * ascending, resolved here so no adapter carries its own default. No sort
+ * stays absent — the adapter's unsorted order is `createdAt` newest first,
+ * and an explicit sort would be re-checked against the server's declared
+ * `sort.fields`. See docs/spec/data-model.md § Sorting and pagination.
+ */
+export function normalizeSort(sort) {
+    if (!sort)
+        return undefined;
+    return { ...sort, direction: sort.direction ?? 'asc' };
+}
 /**
  * Fail loud rather than silently reorder: an adapter that can't honor the
  * requested sort would otherwise answer in some other order, which a
@@ -384,6 +397,61 @@ export function validateAssociations(associations, path = 'associations') {
             : []),
     ];
 }
+/**
+ * Hold an association edit list to the rules every verb shares: non-empty,
+ * every element a known `op` over a well-formed association, one surface,
+ * and each identity named once — a list that both removes and adds one
+ * identity is the same ambiguity as naming it twice. `repoint` is the
+ * journal's word, never a request. Asked of the whole list before anything
+ * is read or written. See docs/spec/data-model.md § Mutations.
+ */
+export function assertAssociationEdits(changes, surface, half) {
+    if (!Array.isArray(changes) || changes.length === 0) {
+        throw new StackValidationError([
+            { path: 'changes', message: `${surface} names at least one change.` },
+        ]);
+    }
+    const errors = [];
+    changes.forEach((raw, i) => {
+        const path = `changes[${i}]`;
+        if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+            errors.push({ path, message: `${path} must be an object.` });
+            return;
+        }
+        const edit = raw;
+        if (edit.op !== 'repoint')
+            assertKnownKeys(edit, ['op', 'association'], path);
+        if (edit.op === 'repoint') {
+            errors.push({
+                path: `${path}.op`,
+                message: 'op: "repoint" is recorded by the journal, not requested. ' +
+                    "Send { op: 'add', association }: an add naming an attachment the record already holds re-points it in place.",
+            });
+        }
+        else if (edit.op !== 'add' && edit.op !== 'remove') {
+            errors.push({ path: `${path}.op`, message: 'op must be "add" or "remove".' });
+        }
+        errors.push(...validateAssociation(edit.association, `${path}.association`));
+    });
+    if (errors.length > 0)
+        throw new StackValidationError(errors);
+    const associations = changes.map((c) => c.association);
+    if (half === 'data')
+        assertDataAssociations(associations, surface);
+    else
+        assertAuthorityAssociations(associations, surface);
+    const duplicates = [];
+    associations.forEach((a, i) => {
+        if (associations.slice(0, i).some((b) => associationEqual(a, b))) {
+            duplicates.push({
+                path: `changes[${i}]`,
+                message: `Duplicate association identity: ${a.kind} "${a.label}"${granteeSuffix(a)} is named more than once.`,
+            });
+        }
+    });
+    if (duplicates.length > 0)
+        throw new StackValidationError(duplicates);
+}
 /**
  * Reject an association filter that names neither of its halves, or whose
  * relationship target is malformed. `RelatedToFilter` and `AttachmentFilter`
@@ -410,6 +478,21 @@ export function assertValidAssociationFilters(filter) {
     if (errors.length > 0)
         throw new StackBadRequestError(errors[0].message);
 }
+/**
+ * Refuse a `baseId` carrying an `@version` suffix. A family filter resolves
+ * against registered families, so a TypeId there would match nothing and
+ * say nothing. See docs/spec/data-model.md § Filter.
+ */
+export function assertValidBaseIdFilter(filter) {
+    if (filter?.baseId === undefined)
+        return;
+    const errors = (Array.isArray(filter.baseId) ? filter.baseId : [filter.baseId])
+        .map((b) => familyIdProblem(b, 'filter.baseId'))
+        .filter((m) => m !== null)
+        .map((message) => ({ path: 'filter.baseId', message }));
+    if (errors.length > 0)
+        throw new StackValidationError(errors);
+}
 /**
  * Hold a journal window to the shape both adapters can honor identically.
  *
@@ -435,4 +518,21 @@ export function assertValidJournalQuery(query) {
         }
     }
 }
+/**
+ * Refuse a `getVersions()` window the adapters would read differently, as
+ * assertValidJournalQuery() does for the journal. No ceiling is imposed:
+ * omitting `limit` reads every version by contract.
+ */
+export function assertValidVersionsQuery(query) {
+    if (!query)
+        return;
+    for (const key of ['beforeVersion', 'limit']) {
+        const value = query[key];
+        if (value === undefined)
+            continue;
+        if (!Number.isInteger(value) || value < 1) {
+            throw new StackBadRequestError(`Invalid versions ${key} ${String(value)}: expected a positive integer.`);
+        }
+    }
+}
 //# sourceMappingURL=query-validation.js.map