@haverstack/record-adapter-sqlite 0.26.0 → 0.29.0

package/dist/index.js

@@ -24,14 +24,23 @@ var RECORD_SCHEMA_SQL = `
     updated_by  TEXT,
     updated_via TEXT,
     deleted_at  INTEGER,
-    unlisted_at INTEGER,
-    permissions TEXT CHECK (permissions IS NULL OR json_valid(permissions))
+    unlisted_at INTEGER
   ) STRICT;
 
+  -- Every edge a record carries, authority and data alike: a permission
+  -- entry has element identity and a delta the same shape as a tag's, so
+  -- it earns the same table and the same durability tier. The permissions
+  -- and associations fields are projections over it, partitioned by
+  -- kind. See docs/spec/access-control.md \xA7 Record-level permissions.
+  --
   -- A relationship's target is (related_scope, related_id) plus one
   -- qualifier: related_stack for a record in another stack, related_ns for
   -- a foreign namespace. All four are in the primary key, so two targets
-  -- differing only by namespace are two associations.
+  -- differing only by namespace are two associations. A permission's
+  -- grantee reuses them \u2014 related_scope 'entity' or 'group', related_id the
+  -- DID or group id \u2014 plus related_role, which only a group grantee sets
+  -- and which is in the key because member and admin name two different
+  -- sets of people.
   --
   -- attachment_record_id stays out of the primary key: it annotates a
   -- reference rather than naming one, so re-pointing it updates the row an
@@ -43,22 +52,21 @@ var RECORD_SCHEMA_SQL = `
   -- for the filter directions it cannot answer.
   CREATE TABLE IF NOT EXISTS associations (
     record_id     TEXT NOT NULL REFERENCES records(id),
-    kind          TEXT NOT NULL CHECK (kind IN ('tag', 'attachment', 'relationship')),
+    kind          TEXT NOT NULL CHECK (kind IN ('tag', 'attachment', 'relationship', 'permission', 'anyone')),
     label         TEXT NOT NULL,
     file_id       TEXT NOT NULL DEFAULT '',
-    related_scope TEXT NOT NULL DEFAULT '' CHECK (related_scope IN ('', 'record', 'entity', 'external')),
+    related_scope TEXT NOT NULL DEFAULT '' CHECK (related_scope IN ('', 'record', 'entity', 'external', 'group')),
     related_id    TEXT NOT NULL DEFAULT '',
     related_ns    TEXT NOT NULL DEFAULT '',
     related_stack TEXT NOT NULL DEFAULT '',
+    related_role  TEXT NOT NULL DEFAULT '' CHECK (related_role IN ('', 'member', 'admin')),
     attachment_record_id TEXT NOT NULL DEFAULT '',
-    PRIMARY KEY (record_id, kind, label, file_id, related_scope, related_id, related_ns, related_stack)
+    PRIMARY KEY (record_id, kind, label, file_id, related_scope, related_id, related_ns, related_stack, related_role)
   ) STRICT;
 
-  -- parent_id holds the container the record sat in, NULL for the root --
-  -- the same encoding records.parent_id uses, since a snapshot states
-  -- where the record was rather than an instruction to apply.
-  -- No associations column: associate()/dissociate() don't bump version,
-  -- so no version ever snapshots the association set. See
+  -- Content and the type it is read under. No parent_id, unlisted_at or
+  -- associations column: none of those aspects bumps version, so no
+  -- version ever snapshots one. See
   -- docs/spec/versioning.md \xA7 Version history.
   CREATE TABLE IF NOT EXISTS versions (
     record_id   TEXT NOT NULL REFERENCES records(id),
@@ -69,8 +77,6 @@ var RECORD_SCHEMA_SQL = `
     entity_id   TEXT,
     updated_by  TEXT,
     updated_via TEXT,
-    parent_id   TEXT,
-    permissions  TEXT CHECK (permissions IS NULL OR json_valid(permissions)),
     PRIMARY KEY (record_id, version)
   ) STRICT;
 
@@ -582,6 +588,10 @@ var buildQueryPlan = (query) => {
 // ../sqlite-shared/dist/mappers.js
 var toMs = (d) => d.getTime();
 var fromMs = (ms) => new Date(ms);
+var partitionAssociations = (associations) => ({
+  associations: associations.filter((a) => a.kind !== "permission" && a.kind !== "anyone"),
+  permissions: associations.filter((a) => a.kind === "permission" || a.kind === "anyone")
+});
 var rowToRecord = (row, associations) => {
   const record = {
     id: row.id,
@@ -607,16 +617,27 @@ var rowToRecord = (row, associations) => {
     record.deletedAt = fromMs(row.deleted_at);
   if (row.unlisted_at != null)
     record.unlistedAt = fromMs(row.unlisted_at);
-  if (row.permissions != null)
-    record.permissions = JSON.parse(row.permissions);
-  if (associations.length)
-    record.associations = associations;
+  const partitioned = partitionAssociations(associations);
+  if (partitioned.associations.length)
+    record.associations = partitioned.associations;
+  if (partitioned.permissions.length)
+    record.permissions = partitioned.permissions;
   return record;
 };
 var rowToAssociation = (row) => {
   if (row.kind === "tag") {
     return { kind: "tag", label: row.label };
   }
+  if (row.kind === "anyone") {
+    return { kind: "anyone", label: "read" };
+  }
+  if (row.kind === "permission") {
+    return {
+      kind: "permission",
+      label: row.label,
+      grantee: rowToGrantee(row)
+    };
+  }
   if (row.kind === "attachment") {
     const attachmentRecordId = row.attachment_record_id;
     return {
@@ -637,16 +658,25 @@ var rowToAssociation = (row) => {
 };
 var associationKeyColumns = (a) => {
   if (a.kind === "attachment")
-    return [a.fileId, "", "", "", ""];
+    return [a.fileId, "", "", "", "", ""];
+  if (a.kind === "permission") {
+    const g = a.grantee;
+    return g.scope === "entity" ? ["", "entity", g.entityId, "", "", ""] : ["", "group", g.groupId, "", "", g.role];
+  }
   if (a.kind !== "relationship")
-    return ["", "", "", "", ""];
+    return ["", "", "", "", "", ""];
   const t = a.target;
   if (t.scope === "entity")
-    return ["", "entity", t.entityId, "", ""];
+    return ["", "entity", t.entityId, "", "", ""];
   if (t.scope === "external")
-    return ["", "external", t.id, t.ns, ""];
-  return ["", "record", t.recordId, "", t.stackUrl ?? ""];
+    return ["", "external", t.id, t.ns, "", ""];
+  return ["", "record", t.recordId, "", t.stackUrl ?? "", ""];
 };
+var rowToGrantee = (row) => row.related_scope === "group" ? {
+  scope: "group",
+  groupId: row.related_id,
+  role: row.related_role
+} : { scope: "entity", entityId: row.related_id };
 var rowToTarget = (row) => {
   const id = row.related_id;
   if (row.related_scope === "entity")
@@ -684,10 +714,6 @@ var rowToVersion = (row) => {
     v.updatedBy = row.updated_by;
   if (row.updated_via != null)
     v.updatedVia = row.updated_via;
-  if (row.parent_id != null)
-    v.parentId = row.parent_id;
-  if (row.permissions != null)
-    v.permissions = JSON.parse(row.permissions);
   return v;
 };
 var rowToJournalEntry = (row) => {
@@ -752,9 +778,7 @@ var VERSION_COLUMNS = [
   "updated_at",
   "entity_id",
   "updated_by",
-  "updated_via",
-  "parent_id",
-  "permissions"
+  "updated_via"
 ];
 var versionRowValues = (version) => [
   version.typeId,
@@ -762,9 +786,7 @@ var versionRowValues = (version) => [
   toMs(version.updatedAt),
   version.entityId ?? null,
   version.updatedBy ?? null,
-  version.updatedVia ?? null,
-  version.parentId ?? null,
-  version.permissions ? JSON.stringify(version.permissions) : null
+  version.updatedVia ?? null
 ];
 var indexedFieldKinds = (schema) => {
   const kinds = /* @__PURE__ */ new Map();
@@ -775,7 +797,7 @@ var indexedFieldKinds = (schema) => {
   }
   return kinds;
 };
-var SharedSqlRecordLogic = class {
+var SharedSqlRecordLogic = class _SharedSqlRecordLogic {
   deps;
   /**
    * Per-typeId cache of the fields content_index covers and their declared
@@ -881,8 +903,8 @@ var SharedSqlRecordLogic = class {
         this.exec.run(`INSERT INTO records
           (id, type_id, created_at, updated_at, content, version,
            parent_id, entity_id, app_id, principal_id, updated_by, updated_via,
-           deleted_at, unlisted_at, permissions)
-         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+           deleted_at, unlisted_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
           record.id,
           record.typeId,
           toMs(record.createdAt),
@@ -896,8 +918,7 @@ var SharedSqlRecordLogic = class {
           record.updatedBy ?? null,
           record.updatedVia ?? null,
           record.deletedAt ? toMs(record.deletedAt) : null,
-          record.unlistedAt ? toMs(record.unlistedAt) : null,
-          record.permissions ? JSON.stringify(record.permissions) : null
+          record.unlistedAt ? toMs(record.unlistedAt) : null
         ]);
       } catch (err) {
         if (isUniqueConstraintViolation(err)) {
@@ -905,9 +926,9 @@ var SharedSqlRecordLogic = class {
         }
         throw err;
       }
-      if (record.associations?.length) {
-        this.insertAssociations(record.id, record.associations);
-      }
+      const edges = [...record.associations ?? [], ...record.permissions ?? []];
+      if (edges.length)
+        this.insertAssociations(record.id, edges);
       fts5Strategy.insert(this.exec, record.id, JSON.stringify(record.content));
       this.syncContentIndex(record.id, record.typeId, record.content);
       this.appendJournal(record.id, opts.journal);
@@ -945,13 +966,13 @@ var SharedSqlRecordLogic = class {
    * one call is one version whatever it moved.
    *
    * `opts.bumpsVersion: false` is a change set that touches only
-   * `associations` — Stack computes this from which ops the set actually
-   * moves. Such a write skips the records-table UPDATE (and the snapshot)
-   * entirely: nothing on that row changes, so there is nothing to bump and
-   * no version to snapshot. `expectedVersion`, if given, is still
-   * re-checked synchronously inside the transaction — the CAS guard the
-   * bumping path gets from its UPDATE's WHERE clause, restated as a read
-   * because there is no UPDATE here to carry it. See
+   * `associations`, `parentId` and/or `unlisted` — Stack computes this from
+   * which ops the set actually moves. Such a write still lands its columns,
+   * but leaves `version`, `updatedAt` and the actor stamps exactly as they
+   * stood and takes no snapshot. `expectedVersion`, if given, is re-checked
+   * synchronously inside the transaction — the CAS guard the bumping path
+   * gets from its UPDATE's WHERE clause, restated as a read because the
+   * UPDATE here carries no version predicate. See
    * docs/spec/versioning.md § Version history.
    *
    * The expectedVersion check for a bumping write is standalone rather than
@@ -965,38 +986,35 @@ var SharedSqlRecordLogic = class {
     if (!existing)
       throw new StackNotFoundError(`Record not found: "${id}"`);
     this.checkExpectedVersion(existing, opts.expectedVersion);
+    const now = toMs(/* @__PURE__ */ new Date());
+    const sets = [];
+    const values = [];
+    if (changes.parentId !== void 0) {
+      sets.push("parent_id = ?");
+      values.push(changes.parentId);
+    }
+    if (changes.unlisted !== void 0) {
+      sets.push("unlisted_at = ?");
+      values.push(changes.unlisted ? now : null);
+    }
     if (opts.bumpsVersion === false) {
       this.exec.transaction(() => {
         const current = this.readRecord(id);
         if (!current)
           throw new StackNotFoundError(`Record not found: "${id}"`);
         this.checkExpectedVersion(current, opts.expectedVersion);
-        if (changes.associations !== void 0) {
-          this.replaceAssociations(id, changes.associations);
+        if (sets.length > 0) {
+          this.exec.run(`UPDATE records SET ${sets.join(", ")} WHERE id = ?`, [...values, id]);
         }
+        this.replaceAssociationHalves(id, changes);
         this.appendJournal(id, opts.journal);
       });
       return this.reread(id, "mutateRecord");
     }
     const merged = changes.contentPatch ? applyMergePatch(existing.content, changes.contentPatch) : void 0;
-    const sets = [];
-    const values = [];
     if (merged !== void 0) {
-      sets.push("content = ?");
-      values.push(JSON.stringify(merged));
-    }
-    if (changes.parentId !== void 0) {
-      sets.push("parent_id = ?");
-      values.push(changes.parentId);
-    }
-    if (changes.permissions !== void 0) {
-      sets.push("permissions = ?");
-      values.push(changes.permissions.length ? JSON.stringify(changes.permissions) : null);
-    }
-    const now = toMs(/* @__PURE__ */ new Date());
-    if (changes.unlisted !== void 0) {
-      sets.push("unlisted_at = ?");
-      values.push(changes.unlisted ? now : null);
+      sets.unshift("content = ?");
+      values.unshift(JSON.stringify(merged));
     }
     this.exec.transaction(() => {
       if (opts.snapshot)
@@ -1004,9 +1022,7 @@ var SharedSqlRecordLogic = class {
       if (merged !== void 0)
         fts5Strategy.remove(this.exec, id);
       this.versionedUpdate(id, sets, values, opts, now);
-      if (changes.associations !== void 0) {
-        this.replaceAssociations(id, changes.associations);
-      }
+      this.replaceAssociationHalves(id, changes);
       if (merged !== void 0) {
         fts5Strategy.insert(this.exec, id, JSON.stringify(merged));
         this.syncContentIndex(id, existing.typeId, merged);
@@ -1073,7 +1089,7 @@ var SharedSqlRecordLogic = class {
     this.exec.transaction(() => {
       if (opts.snapshot)
         this.snapshotBeforeMutation(id, opts.snapshot);
-      this.rewriteContent(id, target.typeId, target.content, opts, ["parent_id = ?"], [target.parentId ?? null]);
+      this.rewriteContent(id, target.typeId, target.content, opts);
       this.appendJournal(id, opts.journal);
     });
     return this.reread(id, "restoreVersion");
@@ -1093,8 +1109,7 @@ var SharedSqlRecordLogic = class {
   }
   /**
    * Replace a record's type and content wholesale — what restoreVersion and
-   * commitMigration each do, differing only in where the content came from
-   * and whether the container moves with it.
+   * commitMigration each do, differing only in where the content came from.
    *
    * The order is the constraint: fts5Strategy.remove() has to read the old
    * content off the records row, so it runs before the UPDATE, and the
@@ -1102,10 +1117,10 @@ var SharedSqlRecordLogic = class {
    * exec.transaction() — a failure between the two halves would otherwise
    * leave the record unindexed.
    */
-  rewriteContent(id, typeId, content, opts, extraSets = [], extraValues = []) {
+  rewriteContent(id, typeId, content, opts) {
     const json = JSON.stringify(content);
     fts5Strategy.remove(this.exec, id);
-    this.versionedUpdate(id, ["type_id = ?", "content = ?", ...extraSets], [typeId, json, ...extraValues], opts);
+    this.versionedUpdate(id, ["type_id = ?", "content = ?"], [typeId, json], opts);
     fts5Strategy.insert(this.exec, id, json);
     this.syncContentIndex(id, typeId, content);
   }
@@ -1313,11 +1328,9 @@ var SharedSqlRecordLogic = class {
   // Associations
   // -------------------------------------------------------
   /**
-   * Never bumps `version`/`updatedAt` and never snapshots — a set-add
-   * composes correctly regardless of write order, so it needs neither OCC
-   * nor rollback history. The records row is untouched entirely; only the
-   * associations table changes. See docs/spec/versioning.md § Version
-   * history.
+   * Never bumps `version`/`updatedAt` and never snapshots — see
+   * StackRecordAdapter.associate(). The records row is untouched entirely;
+   * only the associations table changes.
    */
   async associate(recordId, association, opts = {}) {
     this.exec.transaction(() => {
@@ -1341,19 +1354,37 @@ var SharedSqlRecordLogic = class {
          AND related_scope = ?
          AND related_id    = ?
          AND related_ns    = ?
-         AND related_stack = ?`, [recordId, association.kind, association.label, ...associationKeyColumns(association)]);
+         AND related_stack = ?
+         AND related_role  = ?`, [recordId, association.kind, association.label, ...associationKeyColumns(association)]);
       this.appendJournal(recordId, opts.journal);
     });
     return this.reread(recordId, "dissociate");
   }
+  /** The kinds each change-set key replaces, and nothing else. */
+  static DATA_KINDS = ["tag", "attachment", "relationship"];
+  static AUTHORITY_KINDS = ["permission", "anyone"];
+  /**
+   * Apply a change set's two association keys, each replacing only within
+   * its own half of the partition. That partition is the whole reason a
+   * tag write cannot drop an ACL: the `associations` key deletes data
+   * kinds alone, so the authority rows beside them are never in scope.
+   * Caller-transactional, like every write below.
+   * See docs/spec/access-control.md § Record-level permissions.
+   */
+  replaceAssociationHalves(recordId, changes) {
+    if (changes.associations !== void 0) {
+      this.replaceAssociations(recordId, changes.associations, _SharedSqlRecordLogic.DATA_KINDS);
+    }
+    if (changes.permissions !== void 0) {
+      this.replaceAssociations(recordId, changes.permissions, _SharedSqlRecordLogic.AUTHORITY_KINDS);
+    }
+  }
   /**
-   * Swap a record's association set for `associations` wholesale — the
-   * "replace, don't merge" semantics a change set's association list and a
-   * version snapshot's both carry. Caller-transactional, like every write
-   * below.
+   * Swap one half of a record's association set wholesale — the "replace,
+   * don't merge" semantics a change set's association list carries.
    */
-  replaceAssociations(recordId, associations) {
-    this.exec.run("DELETE FROM associations WHERE record_id = ?", [recordId]);
+  replaceAssociations(recordId, associations, kinds) {
+    this.exec.run(`DELETE FROM associations WHERE record_id = ? AND kind IN (${kinds.map(() => "?").join(", ")})`, [recordId, ...kinds]);
     if (associations.length)
       this.insertAssociations(recordId, associations);
   }
@@ -1372,8 +1403,8 @@ var SharedSqlRecordLogic = class {
       try {
         this.exec.run(`INSERT INTO associations
             (record_id, kind, label, file_id, related_scope, related_id, related_ns,
-             related_stack, attachment_record_id)
-           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+             related_stack, related_role, attachment_record_id)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
            ON CONFLICT DO UPDATE SET attachment_record_id = excluded.attachment_record_id`, [
           recordId,
           assoc.kind,