@haverstack/core 0.40.0 → 0.42.0

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/adapter/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,YAAY,EACV,YAAY,EACZ,kBAAkB,EAClB,gBAAgB,EAChB,QAAQ,EACR,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,aAAa,GACd,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EACL,uBAAuB,EACvB,oBAAoB,EACpB,eAAe,EACf,6BAA6B,EAC7B,uBAAuB,EACvB,wBAAwB,EACxB,cAAc,EACd,qBAAqB,GACtB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,kBAAkB,EAClB,iBAAiB,EACjB,YAAY,GACb,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,2BAA2B,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC"}

package/dist/{adapter-entry.js → adapter/index.js}

@@ -7,8 +7,9 @@
  * adapters). Types an app reads too, such as StackCapabilities, live in
  * the root entry point instead: every export has exactly one home.
  */
-export { OwnerMismatchError } from './errors.js';
+export { OwnerMismatchError } from '../errors.js';
 export { combineAdapters } from './combine.js';
-export { assertQueryCapabilities, assertSortCapability, assertValidSort, assertValidAssociationFilters, assertValidJournalQuery, assertValidVersionsQuery, filtersContent, parseContentFilterKey, } from './query-validation.js';
-export { contentSortEntry, contentSortKey, compareSortEntries } from './sort.js';
-//# sourceMappingURL=adapter-entry.js.map
+export { assertQueryCapabilities, assertSortCapability, assertValidSort, assertValidAssociationFilters, assertValidJournalQuery, assertValidVersionsQuery, filtersContent, parseContentFilterKey, } from '../query-validation.js';
+export { contentSortEntry, contentSortKey, compareSortEntries, constantSortEntry, sortConstant, } from './sort.js';
+export { AUTHORITY_ASSOCIATION_KINDS, partitionAssociations } from '../associations/identity.js';
+//# sourceMappingURL=index.js.map

package/dist/adapter/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/adapter/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAaH,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EACL,uBAAuB,EACvB,oBAAoB,EACpB,eAAe,EACf,6BAA6B,EAC7B,uBAAuB,EACvB,wBAAwB,EACxB,cAAc,EACd,qBAAqB,GACtB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,kBAAkB,EAClB,iBAAiB,EACjB,YAAY,GACb,MAAM,WAAW,CAAC;AAEnB,OAAO,EAAE,2BAA2B,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC"}

package/dist/{sort.d.ts → adapter/sort.d.ts}

@@ -10,7 +10,7 @@
  *
  * See docs/spec/data-model.md § Sorting by a content field.
  */
-import type { ScalarFieldKind } from './types.js';
+import type { ScalarFieldKind } from '../types/index.js';
 /**
  * A field's value reduced to something ordered: a number, or text plus
  * the key its ordering actually uses (see contentSortKey).
@@ -24,30 +24,30 @@ export type SortEntry = {
     key: string;
 };
 /**
- * Fold text into the key it sorts by: compatibility-decompose, drop
- * combining marks, lowercase. `Émile` files with `emile` and `Zebra` with
- * `zebra`, which is what a person reading a list expects and what raw
- * code-point order gets wrong.
- *
- * `toLowerCase()`, never `toLocaleLowerCase()` — a locale-sensitive fold
- * would order Turkish `İstanbul` differently from every other runtime's,
- * and the key is stored, so the divergence would be baked into an index.
- * What this deliberately does not promise is in
- * docs/spec/data-model.md § Text ordering.
+ * Fold text into the key it sorts by — decompose, drop combining marks,
+ * lowercase — so `Émile` files with `emile`. `toLowerCase()`, never the
+ * locale form: the key is stored, so a locale-sensitive fold would bake one
+ * runtime's order into the index. See docs/spec/data-model.md § Text ordering.
  */
 export declare const contentSortKey: (value: string) => string;
 /**
- * The ordered form of `value` held in a field of the declared `kind`, or
- * null when there is nothing to order by. The kind comes from the schema
- * rather than from the value's runtime type: a field that is numeric on
- * the records that carry it must not order as text on the ones that
- * spell it differently.
- *
- * `date` normalizes to epoch milliseconds so a date field orders the way
- * `createdAt` does instead of by ISO string collation, and `boolean` to
- * 0/1 so false precedes true.
+ * The ordered form of `value` in a field of the declared `kind`, or null
+ * when there is nothing to order by. The kind comes from the schema, not
+ * the value, so a field orders one way on every record. `date` orders as
+ * epoch ms like `createdAt`, `boolean` as 0/1, and an enum as text, since
+ * its declaration order is not part of the schema.
  */
 export declare function contentSortEntry(kind: ScalarFieldKind, value: unknown): SortEntry | null;
+/**
+ * A constant a `contentFieldByType` key orders by, reduced from a value of
+ * `kind` to what it orders as: a number, text, or null for no value. The
+ * reduction happens before the query is sent, so an adapter orders it
+ * without knowing the kind. See docs/spec/data-model.md § Sorting by a
+ * content field.
+ */
+export declare function sortConstant(kind: ScalarFieldKind, value: unknown): string | number | null;
+/** The entry a reduced constant orders as; see sortConstant(). */
+export declare function constantSortEntry(value: string | number | null): SortEntry | null;
 /**
  * Order two records by one sort field, absent values last. `direction`
  * reverses the order between values but never moves absence: a record

package/dist/adapter/sort.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sort.d.ts","sourceRoot":"","sources":["../../src/adapter/sort.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEzD;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnG;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GAAI,OAAO,MAAM,KAAG,MACe,CAAC;AAU/D;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,OAAO,GAAG,SAAS,GAAG,IAAI,CAsBxF;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,CAG1F;AAED,kEAAkE;AAClE,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,CAIjF;AA+BD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,CAAC,EAAE,SAAS,GAAG,IAAI,EACnB,CAAC,EAAE,SAAS,GAAG,IAAI,EACnB,SAAS,EAAE,KAAK,GAAG,MAAM,GACxB,MAAM,CAGR"}

package/dist/{sort.js → adapter/sort.js}

@@ -11,38 +11,25 @@
  * See docs/spec/data-model.md § Sorting by a content field.
  */
 /**
- * Fold text into the key it sorts by: compatibility-decompose, drop
- * combining marks, lowercase. `Émile` files with `emile` and `Zebra` with
- * `zebra`, which is what a person reading a list expects and what raw
- * code-point order gets wrong.
- *
- * `toLowerCase()`, never `toLocaleLowerCase()` — a locale-sensitive fold
- * would order Turkish `İstanbul` differently from every other runtime's,
- * and the key is stored, so the divergence would be baked into an index.
- * What this deliberately does not promise is in
- * docs/spec/data-model.md § Text ordering.
+ * Fold text into the key it sorts by — decompose, drop combining marks,
+ * lowercase — so `Émile` files with `emile`. `toLowerCase()`, never the
+ * locale form: the key is stored, so a locale-sensitive fold would bake one
+ * runtime's order into the index. See docs/spec/data-model.md § Text ordering.
  */
 export const contentSortKey = (value) => value.normalize('NFKD').replace(/\p{M}/gu, '').toLowerCase();
 /**
- * A `date` field may hold an offset-less date-time — the offset is
- * optional in the shape validate.ts pins — and bare `Date.parse` resolves
- * one of those in the *host's* zone. The stored index value and a cursor
- * value re-derived elsewhere would then disagree, skipping or repeating a
- * record at a page boundary, and two adapters in two zones would answer
- * one query in two orders. A zone-less date-time is read as UTC, which is
- * what `Date.parse` already does for a date-only string.
+ * A zone-less date-time, read as UTC as `Date.parse` already reads a
+ * date-only string. Read in the host's zone, a stored index value and a
+ * cursor re-derived elsewhere would disagree at a page boundary, and two
+ * adapters in two zones would order one query two ways.
  */
 const ZONELESS_DATE_TIME_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?$/;
 /**
- * The ordered form of `value` held in a field of the declared `kind`, or
- * null when there is nothing to order by. The kind comes from the schema
- * rather than from the value's runtime type: a field that is numeric on
- * the records that carry it must not order as text on the ones that
- * spell it differently.
- *
- * `date` normalizes to epoch milliseconds so a date field orders the way
- * `createdAt` does instead of by ISO string collation, and `boolean` to
- * 0/1 so false precedes true.
+ * The ordered form of `value` in a field of the declared `kind`, or null
+ * when there is nothing to order by. The kind comes from the schema, not
+ * the value, so a field orders one way on every record. `date` orders as
+ * epoch ms like `createdAt`, `boolean` as 0/1, and an enum as text, since
+ * its declaration order is not part of the schema.
  */
 export function contentSortEntry(kind, value) {
     switch (kind) {
@@ -58,12 +45,35 @@ export function contentSortEntry(kind, value) {
             const ms = Date.parse(ZONELESS_DATE_TIME_RE.test(value) ? `${value}Z` : value);
             return Number.isNaN(ms) ? null : { kind: 'num', num: ms };
         }
-        default:
+        case 'string':
+        case 'text':
+        case 'record-ref':
+        case 'file-ref':
+        case 'enum':
             return typeof value === 'string'
                 ? { kind: 'text', text: value, key: contentSortKey(value) }
                 : null;
     }
 }
+/**
+ * A constant a `contentFieldByType` key orders by, reduced from a value of
+ * `kind` to what it orders as: a number, text, or null for no value. The
+ * reduction happens before the query is sent, so an adapter orders it
+ * without knowing the kind. See docs/spec/data-model.md § Sorting by a
+ * content field.
+ */
+export function sortConstant(kind, value) {
+    const entry = contentSortEntry(kind, value);
+    return entry === null ? null : entry.kind === 'num' ? entry.num : entry.text;
+}
+/** The entry a reduced constant orders as; see sortConstant(). */
+export function constantSortEntry(value) {
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? { kind: 'num', num: value } : null;
+    if (typeof value === 'string')
+        return { kind: 'text', text: value, key: contentSortKey(value) };
+    return null;
+}
 /**
  * Order two strings by code point. JS `<` compares UTF-16 code units,
  * which files every supplementary character (U+10000 and above, stored as

package/dist/adapter/sort.js.map

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

package/dist/associations/identity.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Association identity and edits
+ * -------------------------------------------------------
+ * When two associations are the same one, what a list of edits leaves
+ * behind, and what it moved. Identity is asked by every layer that touches
+ * an association — the no-op decision, the journal's delta, an adapter
+ * applying edits, the feed — so they answer it with one comparison and
+ * can never disagree. See docs/spec/data-model.md § Associations.
+ */
+import type { Association, AssociationChange, AssociationEdit, AuthorityAssociation, DataAssociation, Grantee, RelationshipTarget } from '../types/index.js';
+/**
+ * Association identity — what dissociate() matches and a repeat associate()
+ * collides with; the SQLite adapter's primary key. An attachment's
+ * `attachmentRecordId` annotates a reference rather than naming one, so it
+ * is outside; a group grantee's `role` names a different set of people, so
+ * it is inside. See docs/spec/data-model.md § Associations.
+ */
+export declare function associationEqual(a: Association, b: Association): boolean;
+/**
+ * Structural equality per grantee arm. `role` is required, so there is no
+ * absent-means-any spelling to normalize.
+ */
+export declare function granteeEqual(a: Grantee, b: Grantee): boolean;
+/** Structural equality per target arm — what dissociate() matches on. */
+export declare function targetEqual(a: RelationshipTarget, b: RelationshipTarget): boolean;
+/**
+ * Identity plus every annotation outside it, so a write that only re-points
+ * an attachment association's `attachmentRecordId` still counts as a
+ * change. Identity alone decides which stored association a write lands on;
+ * this decides whether it says anything new.
+ */
+export declare function associationIdentical(a: Association, b: Association): boolean;
+/**
+ * The association kinds that carry authority. Every other kind is data.
+ * Storage that partitions by kind in a query reads this list rather than
+ * restating it, so a new authority kind can't fall into the data half.
+ */
+export declare const AUTHORITY_ASSOCIATION_KINDS: readonly AuthorityAssociation['kind'][];
+/**
+ * Whether an association carries authority rather than data — the partition
+ * `StackRecord.permissions` and `StackRecord.associations` project, and the
+ * line `associate()`/`dissociate()` refuse to cross.
+ * See docs/spec/access-control.md § Record-level permissions.
+ */
+export declare function isAuthorityAssociation(a: Association): a is AuthorityAssociation;
+/**
+ * One stored association set split into the two the record presents. An app
+ * editing tags never sees the authority half, so it cannot drop it.
+ */
+export declare function partitionAssociations(associations: Association[]): {
+    associations: DataAssociation[];
+    permissions: AuthorityAssociation[];
+};
+/**
+ * What a `changes.associations` list moves against a record's current set,
+ * one tagged edit each. An entry matching an existing identity displaced it:
+ * a `repoint`, carrying the prior association in full as `previous` — the
+ * only place an overwritten `attachmentRecordId` survives.
+ * See docs/spec/journal.md § The entry.
+ */
+export declare function associationDelta(before: Association[], after: Association[]): AssociationChange[];
+/**
+ * The two flat lists a change frame carries, derived from the tagged list.
+ * The feed reports what is true now, so a `repoint` appears only under its
+ * new value and a `remove` by identity alone — the prior state the journal
+ * keeps has no place on a notification. The data half alone: `reshare` is
+ * what announces an ACL move. See docs/spec/events.md § The event shape.
+ */
+export declare function feedAssociationDelta(changes: AssociationChange[]): {
+    added: DataAssociation[];
+    removed: DataAssociation[];
+};
+/**
+ * An association edit list travels one surface: authority and data share
+ * storage and a delta, and never share a call. Refused here so every
+ * adapter inherits the same rule.
+ * See docs/spec/access-control.md § Storage unifies; the API does not.
+ */
+export declare function assertOneSurface(changes: readonly AssociationEdit[]): void;
+/**
+ * The set a list of edits leaves behind: removes first, then adds, an add
+ * landing on an identity already held in place. Adds naming one identity
+ * collapse, last wins; an add outlives a remove of the same identity.
+ * See docs/spec/adapters.md § Amending associations.
+ */
+export declare function applyAssociationEdits(current: Association[], changes: readonly AssociationEdit[]): Association[];
+/**
+ * The same op over every element of a list — what associate(),
+ * dissociate(), grantAccess() and revokeAccess() hand to the amend verb
+ * each is one half of.
+ */
+export declare function editsOf(op: 'add' | 'remove', associations: Association[]): AssociationEdit[];
+//# sourceMappingURL=identity.d.ts.map

package/dist/associations/identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../../src/associations/identity.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EACV,WAAW,EACX,iBAAiB,EACjB,eAAe,EACf,oBAAoB,EACpB,eAAe,EACf,OAAO,EACP,kBAAkB,EACnB,MAAM,mBAAmB,CAAC;AAE3B;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,WAAW,GAAG,OAAO,CAaxE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CAQ5D;AAED,yEAAyE;AACzE,wBAAgB,WAAW,CAAC,CAAC,EAAE,kBAAkB,EAAE,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAQjF;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,WAAW,GAAG,OAAO,CAM5E;AAcD;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,EAAE,SAAS,oBAAoB,CAAC,MAAM,CAAC,EAG9E,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,WAAW,GAAG,CAAC,IAAI,oBAAoB,CAEhF;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,WAAW,EAAE,GAAG;IAClE,YAAY,EAAE,eAAe,EAAE,CAAC;IAChC,WAAW,EAAE,oBAAoB,EAAE,CAAC;CACrC,CAKA;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,WAAW,EAAE,EAAE,KAAK,EAAE,WAAW,EAAE,GAAG,iBAAiB,EAAE,CAcjG;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,iBAAiB,EAAE,GAAG;IAClE,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB,OAAO,EAAE,eAAe,EAAE,CAAC;CAC5B,CAYA;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,GAAG,IAAI,CAO1E;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,WAAW,EAAE,EACtB,OAAO,EAAE,SAAS,eAAe,EAAE,GAClC,WAAW,EAAE,CAWf;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,EAAE,EAAE,KAAK,GAAG,QAAQ,EAAE,YAAY,EAAE,WAAW,EAAE,GAAG,eAAe,EAAE,CAE5F"}

package/dist/associations/identity.js

@@ -0,0 +1,198 @@
+/**
+ * Association identity and edits
+ * -------------------------------------------------------
+ * When two associations are the same one, what a list of edits leaves
+ * behind, and what it moved. Identity is asked by every layer that touches
+ * an association — the no-op decision, the journal's delta, an adapter
+ * applying edits, the feed — so they answer it with one comparison and
+ * can never disagree. See docs/spec/data-model.md § Associations.
+ */
+import { StackBadRequestError } from '../errors.js';
+/**
+ * Association identity — what dissociate() matches and a repeat associate()
+ * collides with; the SQLite adapter's primary key. An attachment's
+ * `attachmentRecordId` annotates a reference rather than naming one, so it
+ * is outside; a group grantee's `role` names a different set of people, so
+ * it is inside. See docs/spec/data-model.md § Associations.
+ */
+export function associationEqual(a, b) {
+    // Never "the same one": naming a malformed association is
+    // validateAssociation()'s job, which this must reach without throwing.
+    if (!a || !b)
+        return false;
+    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);
+    }
+    if (a.kind === 'permission' && b.kind === 'permission') {
+        return granteeEqual(a.grantee, b.grantee);
+    }
+    return true;
+}
+/**
+ * Structural equality per grantee arm. `role` is required, so there is no
+ * absent-means-any spelling to normalize.
+ */
+export function granteeEqual(a, b) {
+    if (!a || !b)
+        return false;
+    if (a.kind !== b.kind)
+        return false;
+    if (a.kind === 'entity' && b.kind === 'entity')
+        return a.entityId === b.entityId;
+    if (a.kind === 'group' && b.kind === 'group') {
+        return a.groupId === b.groupId && a.role === b.role;
+    }
+    return false;
+}
+/** Structural equality per target arm — what dissociate() matches on. */
+export function targetEqual(a, b) {
+    if (a.kind !== b.kind)
+        return false;
+    if (a.kind === 'record' && b.kind === 'record') {
+        return a.recordId === b.recordId && (a.stackUrl ?? '') === (b.stackUrl ?? '');
+    }
+    if (a.kind === 'entity' && b.kind === 'entity')
+        return a.entityId === b.entityId;
+    if (a.kind === 'external' && b.kind === 'external')
+        return a.ns === b.ns && a.id === b.id;
+    return false;
+}
+/**
+ * Identity plus every annotation outside it, so a write that only re-points
+ * an attachment association's `attachmentRecordId` still counts as a
+ * change. Identity alone decides which stored association a write lands on;
+ * this decides whether it says anything new.
+ */
+export function associationIdentical(a, b) {
+    if (!associationEqual(a, b))
+        return false;
+    if (a.kind === 'attachment' && b.kind === 'attachment') {
+        return (a.attachmentRecordId ?? '') === (b.attachmentRecordId ?? '');
+    }
+    return true;
+}
+/**
+ * An association's identity alone, its annotation dropped — what a change
+ * event reports for an association that's gone, as a `purged` frame names
+ * a destroyed record without repeating its content.
+ * See docs/spec/events.md § The event shape.
+ */
+function stripAssociationAnnotation(association) {
+    if (association.kind !== 'attachment')
+        return association;
+    const { attachmentRecordId: _attachmentRecordId, ...identity } = association;
+    return identity;
+}
+/**
+ * The association kinds that carry authority. Every other kind is data.
+ * Storage that partitions by kind in a query reads this list rather than
+ * restating it, so a new authority kind can't fall into the data half.
+ */
+export const AUTHORITY_ASSOCIATION_KINDS = [
+    'permission',
+    'anyone',
+];
+/**
+ * Whether an association carries authority rather than data — the partition
+ * `StackRecord.permissions` and `StackRecord.associations` project, and the
+ * line `associate()`/`dissociate()` refuse to cross.
+ * See docs/spec/access-control.md § Record-level permissions.
+ */
+export function isAuthorityAssociation(a) {
+    return AUTHORITY_ASSOCIATION_KINDS.includes(a.kind);
+}
+/**
+ * One stored association set split into the two the record presents. An app
+ * editing tags never sees the authority half, so it cannot drop it.
+ */
+export function partitionAssociations(associations) {
+    return {
+        associations: associations.filter((a) => !isAuthorityAssociation(a)),
+        permissions: associations.filter(isAuthorityAssociation),
+    };
+}
+/**
+ * What a `changes.associations` list moves against a record's current set,
+ * one tagged edit each. An entry matching an existing identity displaced it:
+ * a `repoint`, carrying the prior association in full as `previous` — the
+ * only place an overwritten `attachmentRecordId` survives.
+ * See docs/spec/journal.md § The entry.
+ */
+export function associationDelta(before, after) {
+    const changes = after
+        .filter((a) => !before.some((b) => associationIdentical(a, b)))
+        .map((association) => {
+        const previous = before.find((b) => associationEqual(b, association));
+        return previous
+            ? { op: 'repoint', association, previous }
+            : { op: 'add', association };
+    });
+    return changes.concat(before
+        .filter((b) => !after.some((a) => associationEqual(a, b)))
+        .map((association) => ({ op: 'remove', association })));
+}
+/**
+ * The two flat lists a change frame carries, derived from the tagged list.
+ * The feed reports what is true now, so a `repoint` appears only under its
+ * new value and a `remove` by identity alone — the prior state the journal
+ * keeps has no place on a notification. The data half alone: `reshare` is
+ * what announces an ACL move. See docs/spec/events.md § The event shape.
+ */
+export function feedAssociationDelta(changes) {
+    const added = [];
+    const removed = [];
+    for (const c of changes) {
+        if (c.op === 'remove') {
+            const identity = stripAssociationAnnotation(c.association);
+            if (!isAuthorityAssociation(identity))
+                removed.push(identity);
+        }
+        else if (!isAuthorityAssociation(c.association)) {
+            added.push(c.association);
+        }
+    }
+    return { added, removed };
+}
+/**
+ * An association edit list travels one surface: authority and data share
+ * storage and a delta, and never share a call. Refused here so every
+ * adapter inherits the same rule.
+ * See docs/spec/access-control.md § Storage unifies; the API does not.
+ */
+export function assertOneSurface(changes) {
+    const authority = changes.filter((c) => isAuthorityAssociation(c.association)).length;
+    if (authority === 0 || authority === changes.length)
+        return;
+    throw new StackBadRequestError('An association edit list carries authority or data, never both: permission and anyone ' +
+        'elements travel on the permissions surface.');
+}
+/**
+ * The set a list of edits leaves behind: removes first, then adds, an add
+ * landing on an identity already held in place. Adds naming one identity
+ * collapse, last wins; an add outlives a remove of the same identity.
+ * See docs/spec/adapters.md § Amending associations.
+ */
+export function applyAssociationEdits(current, changes) {
+    let next = current.filter((a) => !changes.some((c) => c.op === 'remove' && associationEqual(c.association, a)));
+    for (const c of changes) {
+        if (c.op !== 'add')
+            continue;
+        next = next.some((a) => associationEqual(a, c.association))
+            ? next.map((a) => (associationEqual(a, c.association) ? c.association : a))
+            : [...next, c.association];
+    }
+    return next;
+}
+/**
+ * The same op over every element of a list — what associate(),
+ * dissociate(), grantAccess() and revokeAccess() hand to the amend verb
+ * each is one half of.
+ */
+export function editsOf(op, associations) {
+    return associations.map((association) => ({ op, association }));
+}
+//# sourceMappingURL=identity.js.map

package/dist/associations/identity.js.map

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

package/dist/associations/validation.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Association validation
+ * -------------------------------------------------------
+ * The rules an association is held to before it is stored: a known kind,
+ * only the keys that kind defines, a well-formed target or grantee, the
+ * right half of the authority/data partition, and each identity named
+ * once. A discriminated union is a compile-time promise, and a server
+ * mapping a request body onto one supplies raw JSON no compiler has seen,
+ * so the rules live in the invariant layer where no adapter can forget
+ * one. See docs/spec/data-model.md § Associations.
+ */
+import type { ValidationError } from '../validate.js';
+import type { Association, AssociationEdit, AuthorityAssociation, DataAssociation, GrantGrantee, RelationshipTarget, RelationshipTargetPattern } from '../types/index.js';
+/** Every key each relationship target arm defines. */
+export declare const TARGET_KEYS: Record<RelationshipTarget['kind'], readonly string[]>;
+/** Every key each grantee arm defines, the default tier included. */
+export declare const GRANTEE_KEYS: Record<GrantGrantee['kind'], readonly string[]>;
+/**
+ * The keys of `value` its arm does not define. An element carrying one is
+ * refused rather than stored: an adapter keeps only the keys it has
+ * columns for, so the rest would answer 200 and then vanish.
+ * See docs/spec/data-model.md § Associations.
+ */
+export declare function unknownKeys(value: object, keys: readonly string[]): string[];
+/** unknownKeys() as a refusal. 400, not 422: the key addresses nothing. */
+export declare function assertKnownKeys(value: object, keys: readonly string[], path: string): void;
+/**
+ * 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.
+ */
+export declare function targetErrors(target: RelationshipTarget | RelationshipTargetPattern, path: string, opts?: {
+    externalIdOptional?: boolean;
+}): ValidationError[];
+/**
+ * Reject an association outside the closed set the types promise: a request
+ * body is raw JSON, and an unknown target kind would otherwise be stored as
+ * a Record in this stack. A key its kind does not define is a 400 at every
+ * depth, as on a request body. See docs/spec/data-model.md § Associations.
+ */
+export declare function validateAssociation(association: Association, path?: string): ValidationError[];
+/**
+ * What makes a grantee malformed, under `path`: first a key its tier does not
+ * define — a 400 under `throw`, as on a request body, or collected on a
+ * stored `_grant` — then its tier's own fields. `role` has no default to fall
+ * back on. `authenticated` is a `_grant` tier alone; `anyRole` admits `'any'`.
+ */
+export declare function granteeErrors(grantee: unknown, path: string, opts: {
+    unknownKeys: 'throw' | 'collect';
+    authenticated?: boolean;
+    anyRole?: boolean;
+}): ValidationError[];
+/**
+ * Refuse an authority element on the data surface. The two halves share
+ * storage but never a call, or an app editing tags could replace an ACL it
+ * was never shown. Thrown, not collected: the caller named the wrong
+ * surface, and wanted grantAccess()/revokeAccess().
+ * See docs/spec/access-control.md § Record-level permissions.
+ */
+export declare function assertDataAssociations(associations: readonly Association[], surface: string): asserts associations is DataAssociation[];
+/**
+ * The mirror of assertDataAssociations(): the `permissions` surface takes
+ * authority kinds alone, so a tag routed through it is refused rather than
+ * quietly becoming an ACL entry the `associations` projection never shows.
+ */
+export declare function assertAuthorityAssociations(permissions: readonly Association[], surface: string): asserts permissions is AuthorityAssociation[];
+/**
+ * Every association in a list, plus the list's own rule: identities are
+ * distinct. An adapter keys associations by identity, so a repeat would
+ * displace the first and leave which one stands to chance — a caller bug,
+ * refused rather than collapsed. See docs/spec/data-model.md § Associations.
+ */
+export declare function validateAssociations(associations: Association[] | undefined, path?: string): ValidationError[];
+/**
+ * Hold an edit list to the rules every verb shares: non-empty, known `op`s
+ * over well-formed associations, one surface, each identity once — removing
+ * and adding one identity is as ambiguous as naming it twice. `repoint` is
+ * the journal's word, never a request. See docs/spec/data-model.md § Mutations.
+ */
+export declare function assertAssociationEdits(changes: unknown, surface: string, half: 'data' | 'authority'): asserts changes is AssociationEdit[];
+/**
+ * assertAssociationEdits() for the verbs taking a bare list — associate(),
+ * grantAccess() and their inverses — asked before wrapping, so problems are
+ * reported under `param`, the name the caller used. Same order of checks,
+ * so a wrong-surface element is refused as such before duplicates count.
+ */
+export declare function assertAssociationList(associations: unknown, surface: string, param: string, half: 'data' | 'authority'): asserts associations is Association[];
+//# sourceMappingURL=validation.d.ts.map

package/dist/associations/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/associations/validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACtD,OAAO,KAAK,EAEV,WAAW,EACX,eAAe,EAEf,oBAAoB,EACpB,eAAe,EAGf,YAAY,EAKZ,kBAAkB,EAClB,yBAAyB,EAE1B,MAAM,mBAAmB,CAAC;AAY3B,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;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,kBAAkB,GAAG,yBAAyB,EACtD,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE;IAAE,kBAAkB,CAAC,EAAE,OAAO,CAAA;CAAO,GAC1C,eAAe,EAAE,CAyBnB;AAmBD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,WAAW,EACxB,IAAI,SAAgB,GACnB,eAAe,EAAE,CAoBnB;AAmCD;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE;IAAE,WAAW,EAAE,OAAO,GAAG,SAAS,CAAC;IAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GACrF,eAAe,EAAE,CA+CnB;AAED;;;;;;GAMG;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;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,YAAY,EAAE,WAAW,EAAE,GAAG,SAAS,EACvC,IAAI,SAAiB,GACpB,eAAe,EAAE,CAMnB;AAgBD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,GAAG,WAAW,GACzB,OAAO,CAAC,OAAO,IAAI,eAAe,EAAE,CAoCtC;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,YAAY,EAAE,OAAO,EACrB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,GAAG,WAAW,GACzB,OAAO,CAAC,YAAY,IAAI,WAAW,EAAE,CAoBvC"}