@haverstack/core 0.27.0 → 0.28.0

package/dist/stack.js

@@ -657,6 +657,20 @@ const DEFAULT_GC_GRACE_MS = 24 * 60 * 60 * 1000;
  * pagination cursor a StackQueryError rather than a content-validation
  * failure. See StackQueryError's doc comment.
  */
+/**
+ * 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.
+ */
+function validateParentId(parentId) {
+    if (parentId.startsWith(RESERVED_ID_PREFIX)) {
+        throw new StackQueryError(`Invalid parentId "${parentId}": uses the reserved "${RESERVED_ID_PREFIX}" prefix.`);
+    }
+    if (!isValidIdFormat(parentId)) {
+        throw new StackQueryError(`Invalid parentId "${parentId}": expected 12 lowercase Crockford base-32 characters.`);
+    }
+}
 function validateRecordId(id) {
     if (id.startsWith(RESERVED_ID_PREFIX)) {
         throw new StackQueryError(`ID "${id}" uses the reserved "${RESERVED_ID_PREFIX}" prefix.`);
@@ -1193,6 +1207,13 @@ export class Stack {
             if (opts.createdAt !== undefined) {
                 validateIdTimestampSkew(opts.id, this.idTimestampSkewMsValue, opts.createdAt.getTime(), 'createdAt');
             }
+            // A generated id names nothing, so a create under a parent cannot
+            // close a loop. A caller-supplied one can: existing records may
+            // already point at it, and the chain above the parent can lead back
+            // to it — so the walk is asked only for that combination.
+            // See docs/spec/data-model.md § Reparenting.
+            if (opts.parentId !== undefined)
+                await this.assertNoParentCycle(opts.id, opts.parentId);
         }
         const associations = baseIdOf(typeId) === SYSTEM_TYPES.GROUP
             ? stampGroupAdmin(opts.associations, opts.entityId ?? this.ownerEntityId)
@@ -1210,6 +1231,20 @@ export class Stack {
             (opts.createdAt !== undefined
                 ? generateIdForTimestamp(createdAt.getTime())
                 : generateId(createdAt.getTime()));
+        // An id field a caller supplies is a value or it is absent — never the
+        // empty string, which names nobody. Refused rather than dropped: an
+        // ignored field is the silent-normalization this mapper family was just
+        // fixed for, one layer up.
+        for (const field of ['entityId', 'appId', 'principalId']) {
+            if (opts[field] === '') {
+                throw new StackQueryError(`Invalid ${field}: the empty string is not an id.`);
+            }
+        }
+        // Every create naming a parent owes the reference check, whether or not
+        // it supplied an id: a destination a caller names has to be one that
+        // exists. This is the read an ordinary create used to skip.
+        if (opts.parentId !== undefined)
+            await this.assertParentExists(id, opts.parentId);
         const record = {
             id,
             typeId,
@@ -1217,10 +1252,14 @@ export class Stack {
             updatedAt,
             content,
             version: 1,
-            ...(opts.parentId && { parentId: opts.parentId }),
-            ...(opts.entityId && { entityId: opts.entityId }),
-            ...(opts.appId && { appId: opts.appId }),
-            ...(opts.principalId && { principalId: opts.principalId }),
+            // Read for presence, not truthiness — every one of these is checked
+            // above, so '' never reaches here and absence is the only thing a
+            // falsy value could mean. Presence says that outright instead of
+            // relying on it.
+            ...(opts.parentId !== undefined && { parentId: opts.parentId }),
+            ...(opts.entityId !== undefined && { entityId: opts.entityId }),
+            ...(opts.appId !== undefined && { appId: opts.appId }),
+            ...(opts.principalId !== undefined && { principalId: opts.principalId }),
             // A create's actor is its author, so these are derived rather than
             // taken: stamping them here keeps "absent means an unscoped write"
             // true of version 1 as it is of every later version.
@@ -1445,6 +1484,96 @@ export class Stack {
         this.emitChange(unlisted ? 'unlist' : 'list', updated);
         return updated;
     }
+    /**
+     * Move a record into another container, or to the root with `null`.
+     * Snapshots and bumps version, same as setUnlisted(). No-op if the
+     * record is already there. Returns the record as it now stands —
+     * unchanged on a no-op.
+     *
+     * `parentId` is the one native field a write-holder may move after
+     * creation, and it confers nothing: containment is not an
+     * access-control edge, so a move changes which queries and feeds
+     * enumerate a record and nothing about who may read it. See
+     * docs/spec/data-model.md § Reparenting.
+     */
+    async setParent(id, parentId, opts = {}) {
+        this.assertOpen();
+        const existing = await this.adapter.getRecord(id);
+        if (!existing) {
+            throw new StackNotFoundError(`Record not found: "${id}"`);
+        }
+        this.checkIfVersion(existing, opts.ifVersion);
+        const previousParentId = existing.parentId ?? null;
+        if (previousParentId === parentId)
+            return existing;
+        if (parentId !== null) {
+            await this.assertParentExists(id, parentId);
+            await this.assertNoParentCycle(id, parentId);
+        }
+        const updated = await this.adapter.setParent(id, parentId, {
+            expectedVersion: opts.ifVersion,
+            snapshot: this.buildVersionSnapshot(existing),
+            updatedBy: opts.updatedBy,
+            updatedVia: opts.updatedVia,
+        });
+        this.emitChange('reparent', updated, { previousParentId });
+        return updated;
+    }
+    /**
+     * Refuse an edge that would make a record its own ancestor — asked at
+     * every site that adds one: setParent(), a restore putting a container
+     * back, and a create naming both its own id and a parent. Nothing
+     * downstream (a generator deriving a page path, a folder view) is
+     * written to survive a cycle.
+     *
+     * Walks with the unscoped adapter deliberately: a walk that skipped the
+     * links a requester cannot read would let a cycle be assembled through
+     * them and break the invariant for every reader. The walk is bounded
+     * because a chain long enough to exhaust it is already pathological.
+     *
+     * Read-then-write, so two moves racing on opposite ends of one chain can
+     * both pass — closing that means the invariant lives in the adapter,
+     * where the write is atomic, which puts a graph constraint in the
+     * storage contract every adapter then implements. Same deferral as
+     * checkBindingUnique() above. Consumers that walk `parentId` should
+     * carry a visited set rather than trust this alone; MAX_PARENT_DEPTH is
+     * the same posture applied here.
+     * See docs/spec/data-model.md § Reparenting.
+     */
+    /**
+     * The checks a *caller-named* destination owes, before the cycle walk:
+     * `parentId` is a real, well-formed record id. Format first, so a
+     * malformed one is a 400 naming the problem rather than a read that
+     * cannot match. Existence closes the gap between the owner path and a
+     * non-owner's, where canReadReferent() already refuses a parent that
+     * isn't there.
+     *
+     * restoreVersion() deliberately does not call this — see its own comment.
+     * See docs/spec/data-model.md § Reparenting.
+     */
+    async assertParentExists(id, parentId) {
+        validateParentId(parentId);
+        if (!(await this.adapter.getRecord(parentId))) {
+            throw new StackConflictError(`Cannot parent record "${id}" to "${parentId}": no such record. A container has to ` +
+                'exist when it is named.');
+        }
+    }
+    async assertNoParentCycle(id, parentId) {
+        let cursor = parentId;
+        for (let depth = 0; cursor !== undefined; depth++) {
+            if (cursor === id) {
+                throw new StackConflictError(`Cannot parent record "${id}" to "${parentId}": it is a descendant of "${id}", ` +
+                    'and the move would make the record its own ancestor.');
+            }
+            // The cap bounds work, and guarantees this terminates on a chain that
+            // is already cyclic. It does not refuse the move: a chain this long is
+            // past what the check can speak to, not evidence of a loop, and
+            // refusing it would claim an invariant core does not maintain.
+            if (depth >= MAX_PARENT_DEPTH)
+                return;
+            cursor = (await this.adapter.getRecord(cursor))?.parentId;
+        }
+    }
     /**
      * Soft-delete a record (default) or hard-delete it permanently, removing
      * the record and its version history. Soft delete snapshots and bumps
@@ -1571,9 +1700,10 @@ 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 never restores permissions. See docs/spec/versioning.md § Restore
-     * semantics.
+     * 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
+     * docs/spec/versioning.md § Restore semantics.
      */
     async restoreVersion(id, version, opts = {}) {
         this.assertOpen();
@@ -1605,13 +1735,29 @@ export class Stack {
         for (const field of bindingFieldsOf(baseIdOf(target.typeId))) {
             this.checkBindingImmutable(baseIdOf(target.typeId), field, existing.content[field], target.content[field]);
         }
+        // A restore that puts a container back is an edge-adding site like
+        // setParent(), and the chain above that container may have moved since
+        // the snapshot was taken. The cycle walk therefore applies — but
+        // assertParentExists() deliberately does not: a restore is not a caller
+        // naming a destination, it is history being put back, and the container
+        // may have been hard-deleted since. Refusing here would make an
+        // unrelated deletion cost the record its content rollback, which is the
+        // recoverability this whole verb exists for. A dangling parentId is
+        // legal at rest anyway — deleting a container never touches its
+        // children. See docs/spec/versioning.md § Restore semantics.
+        const previousParentId = existing.parentId ?? null;
+        const targetParentId = target.parentId ?? null;
+        const moves = targetParentId !== previousParentId;
+        if (moves && targetParentId !== null) {
+            await this.assertNoParentCycle(id, targetParentId);
+        }
         const restored = await this.adapter.restoreVersion(id, version, {
             expectedVersion: opts.ifVersion,
             snapshot: this.buildVersionSnapshot(existing),
             updatedBy: opts.updatedBy,
             updatedVia: opts.updatedVia,
         });
-        this.emitChange('restore', restored);
+        this.emitChange('restore', restored, moves ? { previousParentId } : {});
         return restored;
     }
     /**
@@ -2424,8 +2570,9 @@ 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`
-     * is always present ([] when empty) so restore can distinguish "cleared"
-     * from a snapshot that omits the key entirely ("leave as-is"). See
+     * 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
      * docs/spec/versioning.md § Version history.
      */
     buildVersionSnapshot(record) {
@@ -2437,6 +2584,7 @@ export class Stack {
             ...(record.entityId && { entityId: record.entityId }),
             ...(record.updatedBy && { updatedBy: record.updatedBy }),
             ...(record.updatedVia && { updatedVia: record.updatedVia }),
+            ...(record.parentId !== undefined && { parentId: record.parentId }),
             associations: record.associations ?? [],
             ...(record.permissions && { permissions: record.permissions }),
         };
@@ -2494,6 +2642,13 @@ function permissionsEqual(a, b) {
 /** Default page size used to fill a permission-filtered query result. */
 const DEFAULT_QUERY_LIMIT = 50;
 const MAX_QUERY_LIMIT = 1000;
+/**
+ * How far setParent() will walk a proposed ancestor chain before refusing
+ * the move. Bounds the reads one call can cost; a hierarchy deeper than
+ * this is beyond what `parentId` is for. See docs/spec/data-model.md
+ * § Reparenting.
+ */
+const MAX_PARENT_DEPTH = 64;
 /**
  * Ensures `creator` carries an `admin` relationship association, adding one
  * if it's not already present. Used to bootstrap a `_group` record's first
@@ -3444,6 +3599,25 @@ export class ScopedStack {
         this.refuseIfDeleted(record, true);
         return this.stack.setUnlisted(id, unlisted, { ...opts, ...this.actor });
     }
+    /**
+     * Move a record into another container, or to the root with `null`.
+     * Gated as an ordinary write on the record, plus read access to the
+     * destination — the same reference gate `create()` applies to a
+     * `parentId`, asked again here so a move cannot reach a container an
+     * authoring call could not have named. Not reshare-gated like
+     * setUnlisted(): containment decides which listings enumerate a record,
+     * never who may read it, so a move discloses it to nobody who could not
+     * already read it. The origin is ungated — knowing it requires reading
+     * the record, which this caller has already had to do. See
+     * docs/spec/access-control.md § Reference-creation gating.
+     */
+    async setParent(id, parentId, opts = {}) {
+        await this.requireUpdatable(id);
+        if (parentId !== null && !(await this.canReadReferent(parentId))) {
+            throw new StackPermissionError();
+        }
+        return this.stack.setParent(id, parentId, { ...opts, ...this.actor });
+    }
     /**
      * Hard delete is owner-only: it is irreversible and destroys version
      * history, so neither the write bit nor delete-own/delete-any grants
@@ -3493,9 +3667,11 @@ export class ScopedStack {
     /**
      * Re-runs the reference-creation checks against the snapshot, so a
      * restore can't re-convey access to a file or record the subject can no
-     * longer reach today. Only the owner acting alone is exempt: under
-     * delegation the checks resolve against the subject, which is whose reach
-     * the restore would widen. See docs/spec/versioning.md § Restore semantics.
+     * longer reach today — the snapshot's `parentId` among them, gated
+     * exactly as setParent() gates a destination named directly. Only the
+     * owner acting alone is exempt: under delegation the checks resolve
+     * against the subject, which is whose reach the restore would widen.
+     * See docs/spec/versioning.md § Restore semantics.
      */
     async restoreVersion(id, version, opts = {}) {
         const record = await this.requireUpdatable(id);
@@ -3506,6 +3682,16 @@ export class ScopedStack {
                 // decision update() reserves to the owner, reached by another route.
                 this.requireOwnerForAppIdentity(record.typeId, (field) => target.content[field] !==
                     record.content[field]);
+                // Only a restore that moves the record *into* a container creates a
+                // reference. A snapshot at the root names nothing, and a parentId
+                // the restore would not change is not re-gated: the record is
+                // already there, so a content rollback is not refused over a move
+                // it isn't making.
+                if (target.parentId !== undefined &&
+                    target.parentId !== record.parentId &&
+                    !(await this.canReadReferent(target.parentId))) {
+                    throw new StackPermissionError();
+                }
                 await this.requireFileRefAccess(target.typeId, target.content);
                 for (const association of target.associations ?? []) {
                     await this.requireAssociationAccess(target.typeId, association);