@haverstack/core 0.32.0 → 0.34.0

package/dist/stack.js

@@ -19,16 +19,16 @@ import { validateContent, validateContentKeys, validatePatchValues, validateRese
 import { applyMergePatch } from './merge.js';
 import { hasGroupAdmin, isGroupAdminAssociation, validatePermissions } from './access.js';
 import { compareRecordedAttachments } from './attachment-download.js';
-import { ChangeEmitter, RelayDelivery, buildEmission, assertSinceUsable } from './changes.js';
+import { ChangeEmitter, RelayDelivery, PendingChange, assertSinceUsable } from './changes.js';
 import { SYSTEM_TYPES } from './types.js';
 import { StackClosedError, StackConflictError, StackMigrationError, StackNotFoundError, StackPermissionError, StackQueryError, StackSchemaDriftError, StackValidationError, StackVersionConflictError, } from './errors.js';
-import { assertQueryCapabilities, assertSortCapability, assertValidRelatedTo, assertValidSort, filtersContent, validateAssociation, validateAssociations, } from './query-validation.js';
+import { assertQueryCapabilities, assertSortCapability, assertValidRelatedTo, assertValidJournalQuery, assertValidSort, filtersContent, validateAssociation, validateAssociations, } from './query-validation.js';
 import { GRANT_ACTION_SET, READ_COMPANIONS, grantConveys, matchesGrantTarget, validateGrantTarget, grantCoversGrantee, UNGRANTABLE_SYSTEM_TYPES, loadGrantRecords, } from './grants.js';
 import { bindingFieldsOf, uniqueBindingFieldsOf } from './identity-bindings.js';
 import { assertAttachmentSize, assertContentSize } from './limits.js';
 import { validateParentId, validateRecordId, validateClockField, validateIdTimestampSkew, DEFAULT_ID_TIMESTAMP_SKEW_MS, } from './record-id.js';
 import { queryAllPages, findFirstMatch, lookupEntityByDid, MAX_QUERY_LIMIT, } from './stack-reads.js';
-import { associationEqual, associationIdentical, assertNonEmptyChangeSet, changeSetOps, effectiveChanges, stampGroupAdmin, isGroupRecord, } from './record-changes.js';
+import { associationDelta, associationEqual, associationIdentical, assertNonEmptyChangeSet, changeSetOps, bumpsVersion, takesIfVersion, effectiveChanges, stampGroupAdmin, isGroupRecord, } from './record-changes.js';
 import { ScopedStack } from './scoped-stack.js';
 // -------------------------------------------------------
 // Supporting types
@@ -97,16 +97,39 @@ export class Stack {
      * and nothing about work they deferred. A handler cannot fail the write:
      * there is nothing left to fail. See docs/spec/events.md § Handlers.
      */
-    emitChange(op, record, opts = {}) {
-        this.changes.emit(buildEmission(op, record, opts));
+    announce(change, record, at) {
+        this.changes.emit(change.emission(record, at));
     }
     /**
-     * The requester behind a hard delete, which stamps nothing on a record
-     * that no longer exists. Owner-acting-alone is the only way to reach the
-     * verb, so there is never a principal to name beside the subject.
+     * The actor for a `create` journal entry, read off the record as just
+     * built. Create is the one journaled write that stamps the requester
+     * onto the row itself, so the record in hand is authoritative — and it
+     * carries `appId`, which ActorOptions has no field for.
      */
-    static purgeActor(opts) {
-        return opts.updatedBy ? { entityId: opts.updatedBy } : undefined;
+    static createActor(record) {
+        if (!record.updatedBy)
+            return undefined;
+        return {
+            entityId: record.updatedBy,
+            ...(record.updatedVia !== undefined && { principalId: record.updatedVia }),
+            ...(record.appId !== undefined && { appId: record.appId }),
+        };
+    }
+    /**
+     * The requester behind a write that stamps nothing on the record itself —
+     * a hard delete, which leaves no record to stamp, and associate()/
+     * dissociate(), which don't bump and so don't touch updatedBy/updatedVia.
+     * Hard delete is owner-acting-alone only, so it never has a principal to
+     * name beside the subject; associate()/dissociate() can run delegated,
+     * so `updatedVia` rides along here when present.
+     */
+    static actorFrom(opts) {
+        if (!opts.updatedBy)
+            return undefined;
+        return {
+            entityId: opts.updatedBy,
+            ...(opts.updatedVia !== undefined && { principalId: opts.updatedVia }),
+        };
     }
     async getTypeCached(id) {
         const cached = this.typeCache.get(id);
@@ -519,8 +542,9 @@ export class Stack {
             ...(associations?.length && { associations }),
             ...(opts.unlisted && { unlistedAt: createdAt }),
         };
-        const created = await this.adapter.createRecord(record);
-        this.emitChange('create', created);
+        const change = new PendingChange('create', { actor: Stack.createActor(record) });
+        const created = await this.adapter.createRecord(record, { journal: change.journal });
+        this.announce(change, created);
         return created;
     }
     /**
@@ -586,7 +610,12 @@ export class Stack {
         if (!existing) {
             throw new StackNotFoundError(`Record not found: "${id}"`);
         }
-        this.checkIfVersion(existing, opts.ifVersion);
+        // Checked before validation, so a caller that lost the race learns its
+        // version is stale rather than that its patch is bad, and before the
+        // no-op short-circuit below, so a precondition is never satisfied by a
+        // write that turned out to move nothing.
+        if (takesIfVersion(changes))
+            this.checkIfVersion(existing, opts.ifVersion);
         const merged = await this.validateChangeSet(id, existing, changes);
         const ops = changeSetOps(existing, changes, merged);
         // Nothing moved, so there is nothing to version. Decided here rather
@@ -595,9 +624,35 @@ export class Stack {
         // writes nothing.
         if (ops.length === 0)
             return existing;
+        // A change set touching only `associations` doesn't bump — the same
+        // rule associate()/dissociate() follow unconditionally. Its actor
+        // travels as an explicit opt rather than a record stamp, since a
+        // non-bumping write never touches updatedBy/updatedVia.
+        // See docs/spec/versioning.md § Version history.
+        const bumps = bumpsVersion(ops);
+        // Computed against the same before/after changeSetOps compared, so
+        // whether associate/dissociate appear in `ops` and what it lists can
+        // never disagree. See docs/spec/events.md § The event shape.
+        const assocDelta = changes.associations
+            ? associationDelta(existing.associations ?? [], changes.associations)
+            : undefined;
         const previousParentId = existing.parentId ?? null;
-        const updated = await this.adapter.mutateRecord(id, effectiveChanges(changes, ops), this.writeOptions(existing, opts));
-        this.emitChange(ops, updated, ops.includes('reparent') ? { previousParentId } : {});
+        const change = new PendingChange(ops, {
+            actor: Stack.actorFrom(opts),
+            ...(ops.includes('reparent') && { previousParentId }),
+            ...(assocDelta && { associations: assocDelta }),
+        });
+        const updated = await this.adapter.mutateRecord(id, effectiveChanges(changes, ops), {
+            ...(bumps
+                ? this.writeOptions(existing, opts)
+                : {
+                    updatedBy: opts.updatedBy,
+                    updatedVia: opts.updatedVia,
+                }),
+            bumpsVersion: bumps,
+            journal: change.journal,
+        });
+        this.announce(change, updated);
         return updated;
     }
     /**
@@ -698,15 +753,22 @@ export class Stack {
             'least one `admin` relationship association. Name the incoming admin in the same write.');
     }
     /**
-     * Add an association to a record. Snapshots the record's prior state and
-     * bumps version, same as patchContent() — associations are covered by the same
-     * versioning rule as content.
+     * Add an association to a record. Never bumps `version`/`updatedAt` and
+     * never snapshots — a set-add composes correctly regardless of write
+     * order, so it needs neither the OCC `ifVersion` guards content,
+     * `parentId` and `permissions`, nor the rollback history that guards.
+     * See docs/spec/versioning.md § Version history.
+     *
      * An association the record already holds, saying the same thing, is a
      * no-op; one matching an existing association's identity but naming a
      * different `attachmentRecordId` — or none, which clears the one stored —
      * re-points that association in place, rather than adding a second
-     * reference to the same file.
-     * Returns the record as it now stands — unchanged on a no-op.
+     * reference to the same file. The emitted event's `associationsAdded`
+     * carries the association as it now stands either way; what a re-point
+     * overwrote is kept only by the journal, on that entry's `repoint`. See
+     * docs/spec/events.md § The event shape and docs/spec/journal.md
+     * § The entry. Returns the record as it now stands — unchanged on a
+     * no-op.
      */
     async associate(id, association, opts = {}) {
         this.assertOpen();
@@ -717,19 +779,31 @@ export class Stack {
         if (!existing) {
             throw new StackNotFoundError(`Record not found: "${id}"`);
         }
-        this.checkIfVersion(existing, opts.ifVersion);
         if ((existing.associations ?? []).some((a) => associationIdentical(a, association))) {
             return existing;
         }
+        const replaced = (existing.associations ?? []).find((a) => associationEqual(a, association));
         await this.checkAttachmentAssociationPointers([association]);
-        const updated = await this.adapter.associate(id, association, this.writeOptions(existing, opts));
-        this.emitChange('associate', updated);
+        const change = new PendingChange('associate', {
+            actor: Stack.actorFrom(opts),
+            // A re-point carries what it overwrote: nothing else retains the
+            // attachmentRecordId that association held.
+            associations: [
+                replaced ? { op: 'repoint', association, previous: replaced } : { op: 'add', association },
+            ],
+        });
+        const updated = await this.adapter.associate(id, association, { journal: change.journal });
+        this.announce(change, updated);
         return updated;
     }
     /**
-     * Remove an association from a record. Snapshots and bumps version, same
-     * as associate(). Matched by kind, label, and payload. No-op if not found.
-     * Returns the record as it now stands — unchanged on a no-op.
+     * Remove an association from a record. Never bumps `version`/`updatedAt`
+     * — see associate(). Matched by kind, label, and payload. No-op if not
+     * found. The emitted event's `associationsRemoved` names the association
+     * by identity only — an attachment's `attachmentRecordId` is not
+     * repeated there, since it no longer describes anything current, and the
+     * journal is where it survives. See docs/spec/events.md § The event
+     * shape. Returns the record as it now stands — unchanged on a no-op.
      */
     async dissociate(id, association, opts = {}) {
         this.assertOpen();
@@ -740,8 +814,8 @@ export class Stack {
         if (!existing) {
             throw new StackNotFoundError(`Record not found: "${id}"`);
         }
-        this.checkIfVersion(existing, opts.ifVersion);
-        if (!(existing.associations ?? []).some((a) => associationEqual(a, association))) {
+        const matched = (existing.associations ?? []).find((a) => associationEqual(a, association));
+        if (!matched) {
             return existing;
         }
         // Removing anything else cannot take the roster to zero, so only an
@@ -751,8 +825,15 @@ export class Stack {
         if (isGroupAdminAssociation(association)) {
             this.assertGroupAdminRemains(existing, (existing.associations ?? []).filter((a) => !associationEqual(a, association)));
         }
-        const updated = await this.adapter.dissociate(id, association, this.writeOptions(existing, opts));
-        this.emitChange('dissociate', updated);
+        const change = new PendingChange('dissociate', {
+            actor: Stack.actorFrom(opts),
+            // In full, annotation included — what makes a removal as undoable
+            // from the log as a re-point is. The frame this becomes still names
+            // identity only. See docs/spec/journal.md § The entry.
+            associations: [{ op: 'remove', previous: matched }],
+        });
+        const updated = await this.adapter.dissociate(id, association, { journal: change.journal });
+        this.announce(change, updated);
         return updated;
     }
     /**
@@ -816,6 +897,12 @@ export class Stack {
      * version; a no-op if already deleted. `_config` is never deletable
      * (docs/spec.md § The `_config` record). See docs/spec/versioning.md
      * § Deletion.
+     *
+     * A purge reports the files the record referenced. It deletes none of
+     * them — byte lifetime is not the purged record's to decide — but it
+     * destroys the only rows naming them, so a caller who means to erase the
+     * bytes too has nowhere else to read the argument from afterwards. See
+     * docs/spec/attachments.md § A purge strands the bytes it referenced.
      */
     async delete(id, opts = {}) {
         this.assertOpen();
@@ -827,24 +914,48 @@ export class Stack {
             // write: a read here instead would race the delete, and afterwards
             // there is nothing left to read. Null means there was no record, so
             // nothing was purged and nothing is announced.
+            const change = new PendingChange('hard-delete', { actor: Stack.actorFrom(opts) });
             const purged = await this.adapter.deleteRecord(id, {
                 hard: true,
                 expectedVersion: opts.ifVersion,
+                journal: change.journal,
             });
-            if (purged)
-                this.emitChange('hard-delete', purged, { actor: Stack.purgeActor(opts) });
-            return;
+            if (!purged)
+                return { referencedFileIds: [] };
+            this.announce(change, purged);
+            return { referencedFileIds: await this.referencedFileIds(purged) };
         }
         const existing = await this.adapter.getRecord(id);
         if (!existing) {
             throw new StackNotFoundError(`Record not found: "${id}"`);
         }
         this.checkIfVersion(existing, opts.ifVersion);
+        // A tombstone's references stand — undelete() must find its
+        // attachments intact — so nothing is stranded and nothing is reported.
         if (existing.deletedAt)
-            return;
-        const deleted = await this.adapter.deleteRecord(id, this.writeOptions(existing, opts));
+            return { referencedFileIds: [] };
+        const change = new PendingChange('delete', { actor: Stack.actorFrom(opts) });
+        const deleted = await this.adapter.deleteRecord(id, {
+            ...this.writeOptions(existing, opts),
+            journal: change.journal,
+        });
         if (deleted)
-            this.emitChange('delete', deleted);
+            this.announce(change, deleted);
+        return { referencedFileIds: [] };
+    }
+    /**
+     * The files a record references, by the same definition
+     * deleteAttachment() and the garbage sweep use: attachment associations
+     * and top-level `file-ref` content fields. An `_attachment` record's own
+     * `fileId` is a plain string by design and is not one, which is why
+     * purging a metadata record reports nothing — see initSystemTypes().
+     */
+    async referencedFileIds(record) {
+        const fromAssociations = (record.associations ?? []).flatMap((a) => a.kind === 'attachment' ? [a.fileId] : []);
+        const type = await this.getType(record.typeId);
+        const content = record.content;
+        const fromContent = Object.entries(type?.schema ?? {}).flatMap(([field, def]) => def.kind === 'file-ref' && typeof content[field] === 'string' ? [content[field]] : []);
+        return [...new Set([...fromAssociations, ...fromContent])];
     }
     /**
      * Reverse a soft delete. Idempotent — undeleting a record that isn't
@@ -861,8 +972,12 @@ export class Stack {
         this.checkIfVersion(existing, opts.ifVersion);
         if (!existing.deletedAt)
             return existing;
-        const undeleted = await this.adapter.undeleteRecord(id, this.writeOptions(existing, opts));
-        this.emitChange('undelete', undeleted);
+        const change = new PendingChange('undelete', { actor: Stack.actorFrom(opts) });
+        const undeleted = await this.adapter.undeleteRecord(id, {
+            ...this.writeOptions(existing, opts),
+            journal: change.journal,
+        });
+        this.announce(change, undeleted);
         return undeleted;
     }
     /**
@@ -919,6 +1034,26 @@ export class Stack {
         this.assertOpen();
         return this.adapter.getVersions(id);
     }
+    /**
+     * A record's change journal, oldest first — what moved, who moved it,
+     * and the association deltas nothing else retains. The mutation
+     * surface's read, on the same footing as getVersions(): a log of who
+     * changed what, gated on current read access, would make a record's past
+     * exactly as reachable as its present. `ScopedStack` applies that gate;
+     * this layer is unscoped and trusted by definition.
+     *
+     * An adapter with no journal to read refuses rather than answering an
+     * empty log — "nothing changed" and "this stack does not remember" are
+     * not the same answer, and a caller reconstructing an association's
+     * history cannot tell them apart. A record that isn't there is
+     * StackNotFoundError for the same reason, a purged one included.
+     * See docs/spec/journal.md § Reading it.
+     */
+    async getJournal(id, query = {}) {
+        this.assertOpen();
+        assertValidJournalQuery(query);
+        return this.adapter.getJournal(id, query);
+    }
     async getVersion(id, version) {
         this.assertOpen();
         return this.adapter.getVersion(id, version);
@@ -926,9 +1061,9 @@ export class Stack {
     /**
      * Restore a record to a previous version by creating a new version —
      * never rewrites history. The snapshot is validated against its own
-     * stored typeId (not the record's current type), restores associations
-     * and `parentId` (absent on the snapshot is the root, so a restore
-     * always settles containment), and never restores permissions. See
+     * stored typeId (not the record's current type), restores `parentId`
+     * (absent on the snapshot is the root, so a restore always settles
+     * containment), and restores neither associations nor permissions. See
      * docs/spec/versioning.md § Restore semantics.
      */
     async restoreVersion(id, version, opts = {}) {
@@ -977,13 +1112,18 @@ export class Stack {
         if (moves && targetParentId !== null) {
             await this.assertNoParentCycle(id, targetParentId);
         }
-        // A `_group`'s roster is authority, not data: it does not roll back.
+        // Associations never restore, for any Record — a snapshot never
+        // carries them, so there's nothing here for the adapter to roll back.
         // See docs/spec/versioning.md § Restore semantics.
+        const change = new PendingChange('restore', {
+            actor: Stack.actorFrom(opts),
+            ...(moves && { previousParentId }),
+        });
         const restored = await this.adapter.restoreVersion(id, version, {
             ...this.writeOptions(existing, opts),
-            ...(isGroupRecord(existing) && { restoreAssociations: false }),
+            journal: change.journal,
         });
-        this.emitChange('restore', restored, moves ? { previousParentId } : {});
+        this.announce(change, restored);
         return restored;
     }
     /**
@@ -1074,8 +1214,12 @@ export class Stack {
         if (id === SYSTEM_TYPES.CONFIG) {
             this.checkConfigEntityIdUnchanged(existing.content.entityId, content.entityId);
         }
-        const migrated = await this.adapter.commitMigration(id, toTypeId, content, this.writeOptions(existing, opts));
-        this.emitChange('migrate', migrated);
+        const change = new PendingChange('migrate', { actor: Stack.actorFrom(opts) });
+        const migrated = await this.adapter.commitMigration(id, toTypeId, content, {
+            ...this.writeOptions(existing, opts),
+            journal: change.journal,
+        });
+        this.announce(change, migrated);
         return migrated;
     }
     /** Uniqueness for every unique binding field a newly created card claims. */
@@ -1312,7 +1456,11 @@ export class Stack {
             // The metadata record is written inside the adapter, so create()
             // never sees it and this is the only place it can be announced.
             const record = await this.adapter.putAttachmentWithMetadata(data, mimeType, filename, appId);
-            this.emitChange('create', record);
+            // The one emission with no journal half of its own: the far side
+            // wrote the record, so it appended the entry in that same write —
+            // the same division saveVersion() follows over this adapter. See
+            // docs/spec/journal.md § The entry set is the event set.
+            this.announce(new PendingChange('create'), record);
             return record;
         }
         const fileId = await this.adapter.putAttachment(data);
@@ -1378,7 +1526,7 @@ export class Stack {
             deletedRecords = await this.adapter.deleteUnreferencedAttachmentRecords(fileId, await this.attachmentTypeIds());
             const at = new Date();
             for (const record of deletedRecords) {
-                this.emitChange('hard-delete', record, { actor: Stack.purgeActor(opts), at });
+                this.announce(new PendingChange('hard-delete', { actor: Stack.actorFrom(opts) }), record, at);
             }
         }
         else {
@@ -1812,10 +1960,12 @@ export class Stack {
     }
     /**
      * Snapshot of a record's prior state, passed with the mutating adapter
-     * call so snapshot and mutation land in one atomic write. `associations`
-     * and `parentId` are always present (`[]` and `null` where the record has
-     * neither) so restore can distinguish "cleared" and "at the root" from a
-     * snapshot that omits the key entirely ("leave as-is"). See
+     * call so snapshot and mutation land in one atomic write. `parentId` is
+     * always present (`null` where the record has none) so restore can
+     * distinguish "at the root" from a snapshot that omits the key entirely
+     * ("leave as-is"). Never carries `associations` — associate()/
+     * dissociate() don't bump, so no version ever snapshots the association
+     * set, and there is nothing for a restore to roll back to. See
      * docs/spec/versioning.md § Version history.
      */
     buildVersionSnapshot(record) {
@@ -1828,7 +1978,6 @@ export class Stack {
             ...(record.updatedBy && { updatedBy: record.updatedBy }),
             ...(record.updatedVia && { updatedVia: record.updatedVia }),
             ...(record.parentId !== undefined && { parentId: record.parentId }),
-            associations: record.associations ?? [],
             ...(record.permissions && { permissions: record.permissions }),
         };
     }