@haverstack/core 0.29.0 → 0.31.0

package/dist/query-validation.js

@@ -0,0 +1,228 @@
+/**
+ * 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 { 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.', 'filter.search');
+    }
+    const present = filter?.contentPresent?.length ? filter.contentPresent : undefined;
+    if (!filter?.content && !present)
+        return;
+    if (reach === 'none') {
+        // Named as `filter.content` whichever key the query used: the reach
+        // is what is absent, and it is the entry to look at in discovery.
+        throw new StackQueryError(`Query uses ${present && !filter?.content ? 'filter.contentPresent' : 'filter.content'}, ` +
+            'but this adapter declares filter.content: "none".', 'filter.content');
+    }
+    if (present && !contentPresent) {
+        throw new StackQueryError('Query uses filter.contentPresent, but this adapter does not declare the ' +
+            'filter.contentPresent capability.', 'filter.contentPresent');
+    }
+    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}".`, 'filter.content');
+        }
+    }
+}
+/**
+ * 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.', 'sort.contentField');
+        }
+        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.`, '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"}

package/dist/record-changes.js

@@ -0,0 +1,201 @@
+/**
+ * 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 { baseIdOf } from './schema.js';
+import { StackQueryError } from './errors.js';
+import { SYSTEM_TYPES, RECORD_CHANGE_KEYS } from './types.js';
+/**
+ * Matches the SQLite adapter's association primary key (kind, label,
+ * file_id, related_scope, related_id, related_ns, related_stack).
+ */
+export function associationEqual(a, b) {
+    if (a.kind !== b.kind || a.label !== b.label)
+        return false;
+    if (a.kind === 'attachment' && b.kind === 'attachment')
+        return a.fileId === b.fileId;
+    if (a.kind === 'relationship' && b.kind === 'relationship') {
+        return targetEqual(a.target, b.target);
+    }
+    return true;
+}
+/** Structural equality per target arm — what dissociate() matches on. */
+export function targetEqual(a, b) {
+    if (a.scope !== b.scope)
+        return false;
+    if (a.scope === 'record' && b.scope === 'record') {
+        return a.recordId === b.recordId && (a.stackUrl ?? '') === (b.stackUrl ?? '');
+    }
+    if (a.scope === 'entity' && b.scope === 'entity')
+        return a.entityId === b.entityId;
+    if (a.scope === 'external' && b.scope === 'external')
+        return a.ns === b.ns && a.id === b.id;
+    return false;
+}
+export function permissionEqual(a, b) {
+    if (a.access !== b.access)
+        return false;
+    if (a.access === 'public')
+        return true;
+    if (a.access === 'entity' && b.access === 'entity') {
+        return a.entityId === b.entityId && a.read === b.read && a.write === b.write;
+    }
+    if (a.access === 'group' && b.access === 'group') {
+        return a.groupId === b.groupId && a.role === b.role && a.read === b.read && a.write === b.write;
+    }
+    return false;
+}
+/**
+ * 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 function assertNonEmptyChangeSet(changes) {
+    // Presence, not truthiness: `unlisted: false` and `parentId: null` are
+    // aspects this call names, and reading them as absent would drop a
+    // change the caller asked for.
+    if (RECORD_CHANGE_KEYS.some((key) => changes[key] !== undefined))
+        return;
+    throw new StackQueryError('A change set names at least one of: ' + RECORD_CHANGE_KEYS.join(', ') + '.');
+}
+/**
+ * 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 function changeSetOps(existing, changes, merged) {
+    const ops = [];
+    if (merged !== undefined && !contentEqual(existing.content, merged))
+        ops.push('patch');
+    if (changes.parentId !== undefined && changes.parentId !== (existing.parentId ?? null)) {
+        ops.push('reparent');
+    }
+    if (changes.permissions && !permissionsEqual(existing.permissions ?? [], changes.permissions)) {
+        ops.push('permissions');
+    }
+    if (changes.associations) {
+        const before = existing.associations ?? [];
+        const after = changes.associations;
+        if (after.some((a) => !before.some((b) => associationEqual(a, b))))
+            ops.push('associate');
+        if (before.some((b) => !after.some((a) => associationEqual(a, b))))
+            ops.push('dissociate');
+    }
+    if (changes.unlisted !== undefined && Boolean(existing.unlistedAt) !== changes.unlisted) {
+        ops.push(changes.unlisted ? 'unlist' : 'list');
+    }
+    return ops;
+}
+/**
+ * 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 function effectiveChanges(changes, ops) {
+    const effective = {};
+    if (ops.includes('patch'))
+        effective.contentPatch = changes.contentPatch;
+    if (ops.includes('reparent'))
+        effective.parentId = changes.parentId;
+    if (ops.includes('permissions'))
+        effective.permissions = changes.permissions;
+    if (ops.includes('associate') || ops.includes('dissociate')) {
+        effective.associations = changes.associations;
+    }
+    if (ops.includes('unlist') || ops.includes('list'))
+        effective.unlisted = changes.unlisted;
+    return effective;
+}
+/**
+ * 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 function contentEqual(a, b) {
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+export function permissionsEqual(a, b) {
+    return a.length === b.length && a.every((p, i) => permissionEqual(p, b[i]));
+}
+/**
+ * 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 function stampGroupAdmin(associations, creator) {
+    const list = associations ?? [];
+    const alreadyAdmin = list.some((a) => a.kind === 'relationship' &&
+        a.label === 'admin' &&
+        a.target.scope === 'entity' &&
+        a.target.entityId === creator);
+    if (alreadyAdmin)
+        return list;
+    return [
+        ...list,
+        { kind: 'relationship', label: 'admin', target: { scope: 'entity', entityId: creator } },
+    ];
+}
+/**
+ * Whether a Record is a `_group`, in any of its type versions — the family
+ * whose roster rules apply.
+ */
+export function isGroupRecord(record) {
+    return baseIdOf(record.typeId) === SYSTEM_TYPES.GROUP;
+}
+/**
+ * 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 function stripVersionPermissions(version) {
+    if (version.permissions === undefined)
+        return version;
+    const { permissions: _permissions, ...rest } = version;
+    return rest;
+}
+/**
+ * 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 function tombstoneOf(record) {
+    return {
+        id: record.id,
+        typeId: record.typeId,
+        createdAt: record.createdAt,
+        updatedAt: record.updatedAt,
+        version: record.version,
+        content: {},
+        ...(record.deletedAt !== undefined && { deletedAt: record.deletedAt }),
+        ...(record.unlistedAt !== undefined && { unlistedAt: record.unlistedAt }),
+        ...(record.permissions !== undefined && { permissions: record.permissions }),
+    };
+}
+/** A soft-deleted Record presented as its tombstone; anything else untouched. */
+export const presentDeleted = (record) => record.deletedAt ? tombstoneOf(record) : record;
+//# sourceMappingURL=record-changes.js.map

package/dist/record-changes.js.map

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

package/dist/record-id.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Record ID and clock-field validation
+ * -------------------------------------------------------
+ * The rules a caller-supplied `id`, `parentId`, `createdAt` or `updatedAt`
+ * is held to before any of them reaches storage. A client may mint its own
+ * id and backdate a record's clock, so both are untrusted input here even
+ * when the types say otherwise.
+ *
+ * See docs/spec/data-model.md § Record IDs.
+ */
+import type { ValidationError } from './validate.js';
+export declare const DEFAULT_ID_TIMESTAMP_SKEW_MS: number;
+/**
+ * The same format rule applied to a `parentId` a caller names. Separate
+ * from validateRecordId() only for its message: the id under discussion is
+ * the destination, not the record being written, and a shared message would
+ * report the wrong one. See docs/spec/data-model.md § Reparenting.
+ */
+export declare function validateParentId(parentId: string): void;
+/**
+ * Format and reserved-prefix checks — full-trust context (Stack.create()).
+ * Checked before the format check: the Crockford charset already excludes
+ * "_", so a reserved-looking id (e.g. "_config") would otherwise just fail
+ * as a generic format error instead of a specific, actionable one.
+ *
+ * Throws StackQueryError, not StackValidationError: a malformed id is
+ * structurally bad input the request never gets past — it doesn't reach
+ * type-schema validation — the same reasoning that makes an undecodable
+ * pagination cursor a StackQueryError rather than a content-validation
+ * failure. See StackQueryError's doc comment.
+ */
+export declare function validateRecordId(id: string): void;
+/**
+ * Validity and range check for the backdating options on unscoped
+ * Stack.create(). A Date is only as good as what the caller parsed it
+ * from, and the two failure modes both need catching here rather than
+ * downstream:
+ *
+ * - **Invalid Date** (`new Date('13/45/2020')` off a malformed import row)
+ *   has a NaN getTime(), and every comparison against NaN is false — so an
+ *   unchecked Invalid Date passes the updatedAt/createdAt ordering check
+ *   and the id/createdAt skew check by turning them off, mints the
+ *   epoch-zero ID `000000000xxx`, and persists a record whose
+ *   `createdAt.toISOString()` throws RangeError in serializeRecord() —
+ *   making that record, and any wire response containing it,
+ *   permanently unreadable.
+ * - **Out of encodable range** — before 1970 crockford32Encode() throws a
+ *   bare RangeError from deep inside the ID encoder, and past
+ *   MAX_ID_TIMESTAMP the derived ID silently grows to 13 characters and
+ *   fails isValidIdFormat().
+ *
+ * Checked at the door for both, as a StackValidationError naming the
+ * field. Applies whether or not an `id` is supplied: a clock field outside
+ * this range is unrepresentable regardless of where the ID came from.
+ */
+export declare function validateClockField(value: Date | undefined, path: string): ValidationError[];
+/**
+ * Timestamp-prefix plausibility check, shared by callers that compare an
+ * ID's embedded millisecond against a different reference each:
+ * ScopedStack.create() against the current time for any non-backdated
+ * create (a grantee is untrusted and could otherwise mint an ID that
+ * forges its sort position, and this is the one check standing between a
+ * delegated or grantee caller and doing so), and Stack.create() — reached
+ * directly when unscoped, or via ScopedStack.create() when the requester
+ * is the owner acting alone with an explicit `createdAt` — against that
+ * `createdAt` instead (the two must agree, not silently diverge — see
+ * docs/spec/data-model.md § Record IDs). Pass null to disable.
+ */
+export declare function validateIdTimestampSkew(id: string, toleranceMs: number | null, referenceMs: number, referenceLabel: string): void;
+//# sourceMappingURL=record-id.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"record-id.d.ts","sourceRoot":"","sources":["../src/record-id.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAOrD,eAAO,MAAM,4BAA4B,QAAsB,CAAC;AAEhE;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAWvD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CASjD;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,IAAI,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,eAAe,EAAE,CA0B3F;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CACrC,EAAE,EAAE,MAAM,EACV,WAAW,EAAE,MAAM,GAAG,IAAI,EAC1B,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE,MAAM,GACrB,IAAI,CAWN"}