@ordinatio/entities 1.2.0 → 1.3.0

package/README.md

@@ -193,7 +193,7 @@ await app.entities.createNote({ entityType: 'client', entityId: 'client-123', co
 
 ### Tags Module (`@ordinatio/entities/tags`, experimental)
 
-Pure, zero-dependency helpers for tags, on their own subpath so a browser component can import them without pulling in the rest of the package (no Prisma, zod or Node modules): `tagNameKey` / `cleanTagName` / `checkTagName` (the case-insensitive identity of a name; **pinned to its first shipped behaviour** because apps store the key in a unique column), `TAG_COLORS` / `isTagColor` / `resolveTagColor`, `DEFAULT_TAG_LIMITS` (name length 40, 50 changes per save, 15 pinned, 500 per workspace: defaults, a store takes them as arguments), and the picker helpers `describeTagChanges`, `tagSetKey`, `rebaseSelection`, `mergeTagOptions`. The `./schemas` and `./errors` subpaths exist only in the workspace (source) exports map and are not part of the published package yet. On the separate server entry `@ordinatio/entities/tags/server` (EXPERIMENTAL until a second product has used it): the `TagStore` interface (built per workspace, so the package never sees a tenant id; atomic, typed, limit-aware operations), `createTagService(store, limits?)` (the tag rules over any store: validate and clean names and colours, create and find-or-create, rename/recolour/pin, remove, apply only the changes a user made to one item's tags, and read tags back sorted; every outcome a user can cause is a typed `{ ok: false, reason, ... }` result with the context an app needs for its message, and a store result it does not know throws; a store that throws is not caught, so an app that must never fail a page, such as a sidebar of pinned tags, wraps that one call itself; `pinned()` asks the store for the first `maxPinned` pinned tags, so make `listPinned` return them in a stable order such as by name), `planTagChanges`, an in-memory reference store (`createMemoryTagWorld`, `createMemoryTagHarness`) and the store contract suite `defineTagStoreContract` that any storage adapter must pass (framework-agnostic: pass your runner's `describe`/`it`/`expect`). Pin this package's exact version while the server entry is experimental: adding a required store method or a contract rule can break an adapter that passed before. The concurrency tests are meaningful only against a real store: run them against your database with a connection pool of at least 10. **Adapters and mappers must treat an unknown result `kind` or reason as an error**, never as success: adding a kind is a breaking change for an exhaustive switch.
+Pure, zero-dependency helpers for tags, on their own subpath so a browser component can import them without pulling in the rest of the package (no Prisma, zod or Node modules): `tagNameKey` / `cleanTagName` / `checkTagName` (the case-insensitive identity of a name; **pinned to its first shipped behaviour** because apps store the key in a unique column), `TAG_COLORS` / `isTagColor` / `resolveTagColor`, `DEFAULT_TAG_LIMITS` (name length 40, 50 changes per save, 15 pinned, 500 per workspace: defaults, a store takes them as arguments), and the picker helpers `describeTagChanges`, `tagSetKey`, `rebaseSelection`, `mergeTagOptions`. The `./schemas` and `./errors` subpaths exist only in the workspace (source) exports map and are not part of the published package yet. On the separate server entry `@ordinatio/entities/tags/server` (EXPERIMENTAL until a second product has used it): the `TagStore` interface (built per workspace, so the package never sees a tenant id; atomic, typed, limit-aware operations), `createTagService(store, limits?)` (the tag rules over any store: validate and clean names and colours, create and find-or-create, rename/recolour/pin, remove, apply only the changes a user made to one item's tags, and read tags back sorted; every outcome a user can cause is a typed `{ ok: false, reason, ... }` result with the context an app needs for its message, and a store result it does not know throws; a store that throws is not caught, so an app that must never fail a page, such as a sidebar of pinned tags, wraps that one call itself; `pinned()` asks the store for the first `maxPinned` pinned tags, so make `listPinned` return them in a stable order such as by name), `planTagChanges`, an in-memory reference store (`createMemoryTagWorld`, `createMemoryTagHarness`) and the store contract suite `defineTagStoreContract` that any storage adapter must pass (framework-agnostic: pass your runner's `describe`/`it`/`expect`). On a further entry, `@ordinatio/entities/tags/prisma` (also EXPERIMENTAL): `createPrismaTagStore(config)`, a ready-made `TagStore` for a Prisma client on Postgres, so an app writes configuration instead of storage code. It holds the generic storage rules: a per-workspace advisory lock around the two limits (the lock key prefix is configurable, so an app can keep an older key), lock waits that THROW on timeout in create, pin and update (a remove and a link write start no explicit lock of their own, so they wait only on locks other transactions hold, bounded only if those transactions are), `FOR UPDATE` on the tag row in an update (which briefly serialises with the key-share lock a concurrent link insert takes on the same tag), `createManyAndReturn` and `DELETE ... RETURNING` so `added` and `removed` come from rows really written, and foreign-key-abort handling (a link to a tag or item deleted a moment ago becomes `tagGone` or `targetGone`, decided by a fresh read after the aborted transaction). The configuration names your client (as a getter, called each time the store needs the client), the tag model and table, the workspace column, and per taggable kind the join model, table and columns and the item model; every name that reaches SQL is checked once and double-quoted, values are always bound. It needs Prisma 5.14 or later and unique and foreign-key constraints in your database (listed at the top of its `types.ts`) and does not import `@prisma/client`. **Prove it on YOUR database** by running `defineTagStoreContract` against it with a harness of your own (with at least ten connections available): the contract, not the unit tests of this package, is what shows the SQL, the locks and the foreign keys behave. Pin this package's exact version while the server entry is experimental: adding a required store method or a contract rule can break an adapter that passed before. The concurrency tests are meaningful only against a real store: run them against your database with a connection pool of at least 10. **Adapters and mappers must treat an unknown result `kind` or reason as an error**, never as success: adding a kind is a breaking change for an exhaustive switch.
 
 ### Contacts Module
 

package/dist/tags/prisma/index.d.mts

@@ -0,0 +1,60 @@
+import { T as TagRecord, a as TagStore } from '../../types-C81I1Teg.mjs';
+
+/** One taggable kind (a person, a task, a message ...). Names are Prisma model delegates, SQL tables and columns of YOUR schema. */
+interface PrismaTagTarget {
+    /** Prisma delegate of the join model, e.g. `contactTag`. */
+    linkModel: string;
+    /** SQL table of the join model, e.g. `ContactTag` (used in the one raw `DELETE ... RETURNING`). */
+    linkTable: string;
+    /** Column AND Prisma field on the join model that points at the item, e.g. `contactId`. */
+    targetColumn: string;
+    /** Prisma delegate of the item model, e.g. `contact`. */
+    targetModel: string;
+    /** The item model's workspace column. Defaults to the tag's. */
+    targetWorkspaceColumn?: string;
+}
+interface PrismaTagStoreConfig<Target extends string> {
+    /** Called each time the store needs the client (never at import), so a test can swap in a client with a bigger pool. */
+    client: () => PrismaLikeClient;
+    /** The workspace (organization, account, tenant) this store is built for. Every query is scoped by it. */
+    workspaceId: string;
+    /** Prisma delegate of the tag model, e.g. `tag`. */
+    tagModel: string;
+    /** SQL table of the tag model, e.g. `Tag` (used in the `SELECT ... FOR UPDATE`). */
+    tagTable: string;
+    /** Workspace column on the tag model, e.g. `organizationId`. */
+    workspaceColumn: string;
+    targets: Record<Target, PrismaTagTarget>;
+    /** Relation field on a join model to the tag. Default `tag`. */
+    tagRelation?: string;
+    /** Column AND field on a join model for the tag id. Default `tagId`. */
+    tagIdColumn?: string;
+    /** Column AND field on a join model for who tagged it. Default `addedBy`. */
+    addedByColumn?: string;
+    /** The advisory lock is on `prefix + workspaceId` (hashed by Postgres). Default `tags:`. Keep an old app's value so old and new servers serialise. */
+    lockKeyPrefix?: string;
+    /** How long a transaction waits for any one lock before it throws (Postgres lock_timeout). Default 5000. */
+    lockWaitMs?: number;
+    /** Interactive transaction limits. Defaults: maxWait 10000, timeout 15000. */
+    transaction?: {
+        maxWait?: number;
+        timeout?: number;
+    };
+    /** TEST ONLY: runs inside `applyLinks` after the existence reads and before the write, holding NO row lock, so a test can delete a tag or item there. */
+    onBeforeLinkWrite?: () => Promise<void>;
+}
+/** The part of a transaction client the store uses. A real Prisma transaction client satisfies it; model delegates are looked up by name. */
+interface PrismaLikeTx {
+    $executeRawUnsafe(query: string, ...values: unknown[]): Promise<unknown>;
+    $queryRawUnsafe(query: string, ...values: unknown[]): Promise<unknown>;
+}
+interface PrismaLikeClient extends PrismaLikeTx {
+    $transaction<R>(fn: (tx: PrismaLikeTx) => Promise<R>, options?: {
+        maxWait?: number;
+        timeout?: number;
+    }): Promise<R>;
+}
+
+declare function createPrismaTagStore<T extends TagRecord = TagRecord, Target extends string = string>(config: PrismaTagStoreConfig<Target>): TagStore<T, Target>;
+
+export { type PrismaLikeClient, type PrismaLikeTx, type PrismaTagStoreConfig, type PrismaTagTarget, createPrismaTagStore };

package/dist/tags/prisma/index.mjs

@@ -0,0 +1,268 @@
+// src/tags/prisma/identifiers.ts
+var IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+var RESERVED = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype", "toString", "valueOf", "hasOwnProperty"]);
+function assertIdentifier(value, what) {
+  if (typeof value !== "string" || !IDENTIFIER.test(value) || RESERVED.has(value)) {
+    throw new Error(`createPrismaTagStore: ${what} must be a plain identifier (letters, digits and underscores, not starting with a digit), got ${JSON.stringify(value)}`);
+  }
+  return value;
+}
+function quote(identifier) {
+  return `"${identifier}"`;
+}
+
+// src/tags/prisma/context.ts
+function resolveTarget(kind, target, defaultWorkspaceColumn) {
+  const where = `targets.${kind}`;
+  return {
+    linkModel: assertIdentifier(target.linkModel, `${where}.linkModel`),
+    linkTable: assertIdentifier(target.linkTable, `${where}.linkTable`),
+    targetColumn: assertIdentifier(target.targetColumn, `${where}.targetColumn`),
+    targetModel: assertIdentifier(target.targetModel, `${where}.targetModel`),
+    targetWorkspaceColumn: assertIdentifier(target.targetWorkspaceColumn ?? defaultWorkspaceColumn, `${where}.targetWorkspaceColumn`)
+  };
+}
+function createContext(config) {
+  if (typeof config.client !== "function") throw new Error("createPrismaTagStore: client must be a function that returns the Prisma client");
+  if (typeof config.workspaceId !== "string" || config.workspaceId === "") throw new Error("createPrismaTagStore: workspaceId must be a non-empty string");
+  const workspaceColumn = assertIdentifier(config.workspaceColumn, "workspaceColumn");
+  const tagModel = assertIdentifier(config.tagModel, "tagModel");
+  const tagTable = assertIdentifier(config.tagTable, "tagTable");
+  const tagRelation = assertIdentifier(config.tagRelation ?? "tag", "tagRelation");
+  const tagIdColumn = assertIdentifier(config.tagIdColumn ?? "tagId", "tagIdColumn");
+  const addedByColumn = assertIdentifier(config.addedByColumn ?? "addedBy", "addedByColumn");
+  const lockKeyPrefix = config.lockKeyPrefix ?? "tags:";
+  const lockWaitMs = config.lockWaitMs ?? 5e3;
+  if (!Number.isInteger(lockWaitMs) || lockWaitMs <= 0) throw new Error("createPrismaTagStore: lockWaitMs must be a positive integer");
+  const kinds = Object.keys(config.targets);
+  if (kinds.length === 0) throw new Error("createPrismaTagStore: targets must name at least one taggable kind");
+  const targets = new Map(kinds.map((kind) => [kind, resolveTarget(kind, config.targets[kind], workspaceColumn)]));
+  const lockKey = `${lockKeyPrefix}${config.workspaceId}`;
+  const txOptions = { maxWait: config.transaction?.maxWait ?? 1e4, timeout: config.transaction?.timeout ?? 15e3 };
+  const model = (client, name) => {
+    const found = client[name];
+    if (typeof found !== "object" || found === null) throw new Error(`createPrismaTagStore: the Prisma client has no model "${name}" (check the configuration)`);
+    return found;
+  };
+  return {
+    kinds,
+    workspaceId: config.workspaceId,
+    workspaceColumn,
+    tagRelation,
+    tagIdColumn,
+    addedByColumn,
+    sql: { tagTable: quote(tagTable), workspaceColumn: quote(workspaceColumn) },
+    target: (kind) => {
+      const found = targets.get(kind);
+      if (!found) throw new Error(`createPrismaTagStore: "${kind}" is not a configured taggable kind (configured: ${[...targets.keys()].join(", ")})`);
+      return found;
+    },
+    txOptions,
+    beforeLinkWrite: config.onBeforeLinkWrite,
+    client: config.client,
+    model,
+    tags: (client) => model(client, tagModel),
+    link: (client, kind) => model(client, targets.get(kind).linkModel),
+    tagWhere: (extra = {}) => ({ ...extra, [workspaceColumn]: config.workspaceId }),
+    async limitLockWait(tx) {
+      await tx.$executeRawUnsafe(`SELECT set_config('lock_timeout', $1, true)`, `${lockWaitMs}ms`);
+    },
+    async lockWorkspace(tx) {
+      await tx.$executeRawUnsafe(`SELECT pg_advisory_xact_lock(hashtext($1))`, lockKey);
+    }
+  };
+}
+
+// src/tags/prisma/errors.ts
+function hasCode(error, code, depth) {
+  if (typeof error !== "object" || error === null || depth > 4) return false;
+  const fields = error;
+  if (fields.code === code) return true;
+  return ["cause", "meta", "originalError", "driverAdapterError"].some((key) => hasCode(fields[key], code, depth + 1));
+}
+var isUniqueViolation = (error) => hasCode(error, "P2002", 0);
+var isForeignKeyViolation = (error) => hasCode(error, "P2003", 0);
+
+// src/tags/prisma/links.ts
+function createLinks(context, targetExists) {
+  return {
+    async applyLinks(kind, targetId, change, actorId) {
+      if (!await targetExists(kind, targetId)) return { kind: "targetGone" };
+      const target = context.target(kind);
+      const adding = [...new Set(change.add)];
+      const removing = [...new Set(change.remove)];
+      const asked = [.../* @__PURE__ */ new Set([...adding, ...removing])];
+      const known = /* @__PURE__ */ new Set();
+      if (asked.length > 0) {
+        const rows = await context.tags(context.client()).findMany({ where: context.tagWhere({ id: { in: asked } }), select: { id: true } });
+        for (const row of rows) known.add(row.id);
+      }
+      const attachable = adding.filter((id) => known.has(id));
+      const skipped = adding.filter((id) => !known.has(id));
+      const removable = removing.filter((id) => known.has(id));
+      if (context.beforeLinkWrite) await context.beforeLinkWrite();
+      if (attachable.length === 0 && removable.length === 0) return { kind: "applied", added: [], removed: [], skipped };
+      try {
+        const result = await context.client().$transaction(async (tx) => {
+          let added = [];
+          if (attachable.length > 0) {
+            const rows = await context.link(tx, kind).createManyAndReturn({
+              data: attachable.map((tagId) => ({ [target.targetColumn]: targetId, [context.tagIdColumn]: tagId, [context.addedByColumn]: actorId })),
+              skipDuplicates: true,
+              select: { [context.tagIdColumn]: true }
+            });
+            added = rows.map((row) => row[context.tagIdColumn]);
+          }
+          let removed = [];
+          if (removable.length > 0) {
+            const rows = await tx.$queryRawUnsafe(
+              `DELETE FROM ${quote(target.linkTable)} WHERE ${quote(target.targetColumn)} = $1 AND ${quote(context.tagIdColumn)} = ANY($2::text[]) RETURNING ${quote(context.tagIdColumn)} AS "tagId"`,
+              targetId,
+              removable
+            );
+            removed = rows.map((row) => row.tagId);
+          }
+          return { kind: "applied", added, removed, skipped };
+        }, context.txOptions);
+        if (result.added.length === 0 && result.removed.length === 0 && (attachable.length > 0 || removable.length > 0) && !await targetExists(kind, targetId)) return { kind: "targetGone" };
+        return result;
+      } catch (error) {
+        if (!isForeignKeyViolation(error)) throw error;
+        return await targetExists(kind, targetId) ? { kind: "tagGone" } : { kind: "targetGone" };
+      }
+    }
+  };
+}
+
+// src/tags/prisma/reads.ts
+function createReads(context) {
+  const { tagWhere } = context;
+  const db = () => context.client();
+  async function tagsOnTargets(kind, targetIds) {
+    if (targetIds.length === 0) return [];
+    const { targetColumn } = context.target(kind);
+    const rows = await context.link(db(), kind).findMany({
+      where: { [targetColumn]: { in: targetIds }, [context.tagRelation]: tagWhere() },
+      include: { [context.tagRelation]: true }
+    });
+    return rows.map((row) => ({ targetId: row[targetColumn], tag: row[context.tagRelation] }));
+  }
+  return {
+    async list() {
+      return await context.tags(db()).findMany({ where: tagWhere() });
+    },
+    async listPinned(limit) {
+      if (limit <= 0) return [];
+      return await context.tags(db()).findMany({ where: tagWhere({ pinned: true }), orderBy: [{ name: "asc" }, { id: "asc" }], take: limit });
+    },
+    async getMany(ids) {
+      if (ids.length === 0) return [];
+      return await context.tags(db()).findMany({ where: tagWhere({ id: { in: [...new Set(ids)] } }) });
+    },
+    async findByKey(nameKey) {
+      return await context.tags(db()).findFirst({ where: tagWhere({ nameKey }) });
+    },
+    async get(id) {
+      return await context.tags(db()).findFirst({ where: tagWhere({ id }) });
+    },
+    async targetExists(kind, targetId) {
+      const target = context.target(kind);
+      const row = await context.model(db(), target.targetModel).findFirst({ where: { id: targetId, [target.targetWorkspaceColumn]: context.workspaceId }, select: { id: true } });
+      return row !== null && row !== void 0;
+    },
+    async counts(ids) {
+      if (ids && ids.length === 0) return /* @__PURE__ */ new Map();
+      const tags = await context.tags(db()).findMany({ where: tagWhere(ids ? { id: { in: [...new Set(ids)] } } : {}), select: { id: true } });
+      const result = /* @__PURE__ */ new Map();
+      for (const { id } of tags) result.set(id, Object.fromEntries(context.kinds.map((kind) => [kind, 0])));
+      if (tags.length === 0) return result;
+      for (const kind of context.kinds) {
+        const grouped = await context.link(db(), kind).groupBy({ by: [context.tagIdColumn], where: { [context.tagIdColumn]: { in: tags.map((tag) => tag.id) } }, _count: { _all: true } });
+        for (const row of grouped) {
+          const entry = result.get(row[context.tagIdColumn]);
+          if (entry) entry[kind] = row._count._all;
+        }
+      }
+      return result;
+    },
+    async tagsForTarget(kind, targetId) {
+      return (await tagsOnTargets(kind, [targetId])).map((row) => row.tag);
+    },
+    async tagsForTargets(kind, targetIds) {
+      const result = /* @__PURE__ */ new Map();
+      for (const { targetId, tag } of await tagsOnTargets(kind, [...new Set(targetIds)])) {
+        const list = result.get(targetId) ?? [];
+        list.push(tag);
+        result.set(targetId, list);
+      }
+      return result;
+    }
+  };
+}
+
+// src/tags/prisma/writes.ts
+function createWrites(context) {
+  const { tagWhere } = context;
+  const db = () => context.client();
+  return {
+    async create(input, limits) {
+      try {
+        return await db().$transaction(async (tx) => {
+          await context.limitLockWait(tx);
+          await context.lockWorkspace(tx);
+          const tags = context.tags(tx);
+          if (await tags.count({ where: tagWhere() }) >= limits.maxTags) return { kind: "limit" };
+          if (await tags.findFirst({ where: tagWhere({ nameKey: input.nameKey }), select: { id: true } })) return { kind: "duplicate" };
+          const tag = await tags.create({ data: { ...tagWhere(), name: input.name, nameKey: input.nameKey, color: input.color } });
+          return { kind: "created", tag };
+        }, context.txOptions);
+      } catch (error) {
+        if (isUniqueViolation(error)) return { kind: "duplicate" };
+        throw error;
+      }
+    },
+    async update(id, patch, limits) {
+      const wantsPin = patch.pinned === true;
+      try {
+        return await db().$transaction(async (tx) => {
+          await context.limitLockWait(tx);
+          if (wantsPin) await context.lockWorkspace(tx);
+          const locked = await tx.$queryRawUnsafe(`SELECT "id" FROM ${context.sql.tagTable} WHERE "id" = $1 AND ${context.sql.workspaceColumn} = $2 FOR UPDATE`, id, context.workspaceId);
+          const tags = context.tags(tx);
+          const before = locked.length === 0 ? null : await tags.findFirst({ where: tagWhere({ id }) });
+          if (!before) return { kind: "notFound" };
+          if (patch.rename === void 0 && patch.color === void 0 && patch.pinned === void 0) return { kind: "updated", before, after: { ...before } };
+          if (wantsPin && !before.pinned && await tags.count({ where: tagWhere({ pinned: true }) }) >= limits.maxPinned) return { kind: "pinLimit" };
+          if (patch.rename && await tags.findFirst({ where: tagWhere({ nameKey: patch.rename.nameKey, NOT: { id } }), select: { id: true } })) return { kind: "duplicate" };
+          const data = {};
+          if (patch.rename) Object.assign(data, { name: patch.rename.name, nameKey: patch.rename.nameKey });
+          if (patch.color !== void 0) data.color = patch.color;
+          if (patch.pinned !== void 0) data.pinned = patch.pinned;
+          await tags.updateMany({ where: tagWhere({ id }), data });
+          const after = await tags.findFirst({ where: tagWhere({ id }) });
+          return { kind: "updated", before, after };
+        }, context.txOptions);
+      } catch (error) {
+        if (isUniqueViolation(error)) return { kind: "duplicate" };
+        throw error;
+      }
+    },
+    async remove(id) {
+      const tags = context.tags(db());
+      const tag = await tags.findFirst({ where: tagWhere({ id }) });
+      if (!tag) return { kind: "notFound" };
+      const { count } = await tags.deleteMany({ where: tagWhere({ id }) });
+      return count === 0 ? { kind: "notFound" } : { kind: "removed", tag };
+    }
+  };
+}
+
+// src/tags/prisma/index.ts
+function createPrismaTagStore(config) {
+  const context = createContext(config);
+  const reads = createReads(context);
+  return { ...reads, ...createWrites(context), ...createLinks(context, reads.targetExists) };
+}
+export {
+  createPrismaTagStore
+};

package/dist/tags/server/index.d.mts

@@ -1,121 +1,7 @@
+import { b as TagLinkChange, T as TagRecord, a as TagStore } from '../../types-C81I1Teg.mjs';
+export { c as TagApplyResult, d as TagCreateLimits, e as TagCreateResult, f as TagRemoveResult, g as TagUpdateLimits, h as TagUpdatePatch, i as TagUpdateResult } from '../../types-C81I1Teg.mjs';
 import { b as TagLimits } from '../../constants-DSRJ-l7Z.mjs';
 
-/** The fields the rules need. An adapter may return a wider row (createdAt ...): the store is generic over it. */
-interface TagRecord {
-    id: string;
-    name: string;
-    /** The case-insensitive identity of the name (unique per workspace): see `tagNameKey` in `@ordinatio/entities/tags`. */
-    nameKey: string;
-    color: string;
-    pinned: boolean;
-}
-/** Named object types so a future limit is an additive field, not a signature change. */
-interface TagCreateLimits {
-    maxTags: number;
-}
-interface TagUpdateLimits {
-    maxPinned: number;
-}
-type TagCreateResult<T extends TagRecord> = {
-    kind: 'created';
-    tag: T;
-} | {
-    kind: 'duplicate';
-} | {
-    kind: 'limit';
-};
-interface TagUpdatePatch {
-    /** Name and key travel TOGETHER so they cannot disagree. */
-    rename?: {
-        name: string;
-        nameKey: string;
-    };
-    color?: string;
-    pinned?: boolean;
-}
-type TagUpdateResult<T extends TagRecord> = {
-    kind: 'updated';
-    before: T;
-    after: T;
-} | {
-    kind: 'notFound';
-} | {
-    kind: 'pinLimit';
-} | {
-    kind: 'duplicate';
-};
-type TagRemoveResult<T extends TagRecord> = {
-    kind: 'removed';
-    tag: T;
-} | {
-    kind: 'notFound';
-};
-interface TagLinkChange {
-    add: string[];
-    remove: string[];
-}
-type TagApplyResult = {
-    kind: 'applied';
-    added: string[];
-    removed: string[];
-    skipped: string[];
-} | {
-    kind: 'targetGone';
-} | {
-    kind: 'tagGone';
-};
-interface TagStore<T extends TagRecord = TagRecord, Target extends string = string> {
-    /** Every tag of the workspace. ORDER IS UNSPECIFIED: the service sorts. */
-    list(): Promise<T[]>;
-    /**
-     * Pinned tags only, at most `limit`, in ONE bounded query (an app may run this on every page). Order unspecified, but when more are pinned
-     * than `limit` the SAME ones should come back each time (for example by name), or the bookmarks would change from page to page.
-     */
-    listPinned(limit: number): Promise<T[]>;
-    /** The tags of THIS workspace among `ids`; foreign or deleted ids are simply absent. */
-    getMany(ids: string[]): Promise<T[]>;
-    findByKey(nameKey: string): Promise<T | null>;
-    get(id: string): Promise<T | null>;
-    /**
-     * ATOMIC: the limit is enforced together with the insert, so simultaneous creates can never overshoot it. Precedence: `limit` wins over
-     * `duplicate` (a duplicate name when the workspace is full is `limit`).
-     */
-    create(input: {
-        name: string;
-        nameKey: string;
-        color: string;
-    }, limits: TagCreateLimits): Promise<TagCreateResult<T>>;
-    /**
-     * ATOMIC. Precedence: `notFound`, then `pinLimit`, then `duplicate`. Pinning a tag that is ALREADY pinned never counts against the limit
-     * (the pinned flag is re-read under the lock); unpinning needs no limit. Renaming a tag to the same key it already has (a case change) is
-     * not a duplicate. An empty patch is a no-op that returns `updated` with `before` equal to `after`.
-     * `before` is read in the same transaction as the write, so `before`/`after` are consistent under concurrent edits.
-     */
-    update(id: string, patch: TagUpdatePatch, limits: TagUpdateLimits): Promise<TagUpdateResult<T>>;
-    /** The tag's links go with it. Ten parallel removes of one tag give exactly one `removed`. */
-    remove(id: string): Promise<TagRemoveResult<T>>;
-    targetExists(target: Target, targetId: string): Promise<boolean>;
-    /**
-     * One transaction. Frozen result shapes:
-     *  - `skipped` = ids in `add` that are NOT tags of this workspace at the START of the call. Ids in `remove` that are not this workspace's
-     *    tags are IGNORED silently (never reported, never touched). An `add` that is already linked is in neither `added` nor `skipped`.
-     *  - A tag that existed at the start but is gone when the write happens: `tagGone`, nothing applied. A target that vanished: `targetGone`.
-     *  - `added` / `removed` come from rows the database REALLY inserted / deleted, so concurrent saves never double-report one change.
-     * An id in BOTH `add` and `remove` is undefined behaviour: the service never sends it (`planTagChanges` drops it from `remove`).
-     * `actorId` is stored with each new link (who tagged it); it is opaque to this package.
-     */
-    applyLinks(target: Target, targetId: string, change: TagLinkChange, actorId: string): Promise<TagApplyResult>;
-    /** Tags on one target. Order unspecified. */
-    tagsForTarget(target: Target, targetId: string): Promise<T[]>;
-    /** Tags for many targets in ONE round trip. Only targets with at least one tag appear in the map. */
-    tagsForTargets(target: Target, targetIds: string[]): Promise<Map<string, T[]>>;
-    /**
-     * Items per tag per target type, for EVERY tag of the workspace (or only `ids`): a tag with no links appears with zero for every target
-     * type. One grouped query per target type in a real adapter, not one per tag. An EMPTY `ids` asks for nothing: it returns an empty map.
-     */
-    counts(ids?: string[]): Promise<Map<string, Record<Target, number>>>;
-}
-
 type TagChangePlan = {
     ok: true;
     change: TagLinkChange;
@@ -279,4 +165,4 @@ declare function createMemoryTagHarness<Target extends string>(targetTypes: read
 
 declare function defineTagStoreContract<Target extends string>(api: TagContractRunner, harness: TagStoreHarness<Target>): void;
 
-export { type MemoryTagWorld, type MemoryTagWorldOptions, type TagApplyResult, type TagChangePlan, type TagContractRunner, type TagCreateLimits, type TagCreateResult, type TagFailure, type TagLinkChange, type TagOption, type TagRecord, type TagRemoveResult, type TagResult, type TagService, type TagStore, type TagStoreHarness, type TagUpdateLimits, type TagUpdatePatch, type TagUpdateResult, createMemoryTagHarness, createMemoryTagWorld, createTagService, defineTagStoreContract, planTagChanges };
+export { type MemoryTagWorld, type MemoryTagWorldOptions, type TagChangePlan, type TagContractRunner, type TagFailure, TagLinkChange, type TagOption, TagRecord, type TagResult, type TagService, TagStore, type TagStoreHarness, createMemoryTagHarness, createMemoryTagWorld, createTagService, defineTagStoreContract, planTagChanges };

package/dist/tags/server/index.mjs

@@ -878,6 +878,17 @@ function defineTagStoreScopingContract(kit) {
       expect(await store.applyLinks(first, target, { add: [a.id], remove: [] }, "u")).toEqual({ kind: "targetGone" });
       expect((await store.counts()).get(a.id)?.[first]).toBe(0);
     });
+    mid("a target deleted between the check and the write is targetGone for a removal too, not an empty success", async () => {
+      const { workspace, store, make } = await setup();
+      const a = await make(store, "a");
+      const target = await harness.addTarget(workspace, first);
+      await store.applyLinks(first, target, { add: [a.id], remove: [] }, "u");
+      harness.armBeforeLinkWrite?.(async () => {
+        await harness.removeTarget(workspace, first, target);
+      });
+      expect(await store.applyLinks(first, target, { add: [], remove: [a.id] }, "u")).toEqual({ kind: "targetGone" });
+      expect((await store.counts()).get(a.id)?.[first]).toBe(0);
+    });
   });
 }
 

package/dist/types-C81I1Teg.d.mts

@@ -0,0 +1,117 @@
+/** The fields the rules need. An adapter may return a wider row (createdAt ...): the store is generic over it. */
+interface TagRecord {
+    id: string;
+    name: string;
+    /** The case-insensitive identity of the name (unique per workspace): see `tagNameKey` in `@ordinatio/entities/tags`. */
+    nameKey: string;
+    color: string;
+    pinned: boolean;
+}
+/** Named object types so a future limit is an additive field, not a signature change. */
+interface TagCreateLimits {
+    maxTags: number;
+}
+interface TagUpdateLimits {
+    maxPinned: number;
+}
+type TagCreateResult<T extends TagRecord> = {
+    kind: 'created';
+    tag: T;
+} | {
+    kind: 'duplicate';
+} | {
+    kind: 'limit';
+};
+interface TagUpdatePatch {
+    /** Name and key travel TOGETHER so they cannot disagree. */
+    rename?: {
+        name: string;
+        nameKey: string;
+    };
+    color?: string;
+    pinned?: boolean;
+}
+type TagUpdateResult<T extends TagRecord> = {
+    kind: 'updated';
+    before: T;
+    after: T;
+} | {
+    kind: 'notFound';
+} | {
+    kind: 'pinLimit';
+} | {
+    kind: 'duplicate';
+};
+type TagRemoveResult<T extends TagRecord> = {
+    kind: 'removed';
+    tag: T;
+} | {
+    kind: 'notFound';
+};
+interface TagLinkChange {
+    add: string[];
+    remove: string[];
+}
+type TagApplyResult = {
+    kind: 'applied';
+    added: string[];
+    removed: string[];
+    skipped: string[];
+} | {
+    kind: 'targetGone';
+} | {
+    kind: 'tagGone';
+};
+interface TagStore<T extends TagRecord = TagRecord, Target extends string = string> {
+    /** Every tag of the workspace. ORDER IS UNSPECIFIED: the service sorts. */
+    list(): Promise<T[]>;
+    /**
+     * Pinned tags only, at most `limit`, in ONE bounded query (an app may run this on every page). Order unspecified, but when more are pinned
+     * than `limit` the SAME ones should come back each time (for example by name), or the bookmarks would change from page to page.
+     */
+    listPinned(limit: number): Promise<T[]>;
+    /** The tags of THIS workspace among `ids`; foreign or deleted ids are simply absent. */
+    getMany(ids: string[]): Promise<T[]>;
+    findByKey(nameKey: string): Promise<T | null>;
+    get(id: string): Promise<T | null>;
+    /**
+     * ATOMIC: the limit is enforced together with the insert, so simultaneous creates can never overshoot it. Precedence: `limit` wins over
+     * `duplicate` (a duplicate name when the workspace is full is `limit`).
+     */
+    create(input: {
+        name: string;
+        nameKey: string;
+        color: string;
+    }, limits: TagCreateLimits): Promise<TagCreateResult<T>>;
+    /**
+     * ATOMIC. Precedence: `notFound`, then `pinLimit`, then `duplicate`. Pinning a tag that is ALREADY pinned never counts against the limit
+     * (the pinned flag is re-read under the lock); unpinning needs no limit. Renaming a tag to the same key it already has (a case change) is
+     * not a duplicate. An empty patch is a no-op that returns `updated` with `before` equal to `after`.
+     * `before` is read in the same transaction as the write, so `before`/`after` are consistent under concurrent edits.
+     */
+    update(id: string, patch: TagUpdatePatch, limits: TagUpdateLimits): Promise<TagUpdateResult<T>>;
+    /** The tag's links go with it. Ten parallel removes of one tag give exactly one `removed`. */
+    remove(id: string): Promise<TagRemoveResult<T>>;
+    targetExists(target: Target, targetId: string): Promise<boolean>;
+    /**
+     * One transaction. Frozen result shapes:
+     *  - `skipped` = ids in `add` that are NOT tags of this workspace at the START of the call. Ids in `remove` that are not this workspace's
+     *    tags are IGNORED silently (never reported, never touched). An `add` that is already linked is in neither `added` nor `skipped`.
+     *  - A tag that existed at the start but is gone when the write happens: `tagGone`, nothing applied. A target that vanished: `targetGone`.
+     *  - `added` / `removed` come from rows the database REALLY inserted / deleted, so concurrent saves never double-report one change.
+     * An id in BOTH `add` and `remove` is undefined behaviour: the service never sends it (`planTagChanges` drops it from `remove`).
+     * `actorId` is stored with each new link (who tagged it); it is opaque to this package.
+     */
+    applyLinks(target: Target, targetId: string, change: TagLinkChange, actorId: string): Promise<TagApplyResult>;
+    /** Tags on one target. Order unspecified. */
+    tagsForTarget(target: Target, targetId: string): Promise<T[]>;
+    /** Tags for many targets in ONE round trip. Only targets with at least one tag appear in the map. */
+    tagsForTargets(target: Target, targetIds: string[]): Promise<Map<string, T[]>>;
+    /**
+     * Items per tag per target type, for EVERY tag of the workspace (or only `ids`): a tag with no links appears with zero for every target
+     * type. One grouped query per target type in a real adapter, not one per tag. An EMPTY `ids` asks for nothing: it returns an empty map.
+     */
+    counts(ids?: string[]): Promise<Map<string, Record<Target, number>>>;
+}
+
+export type { TagRecord as T, TagStore as a, TagLinkChange as b, TagApplyResult as c, TagCreateLimits as d, TagCreateResult as e, TagRemoveResult as f, TagUpdateLimits as g, TagUpdatePatch as h, TagUpdateResult as i };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ordinatio/entities",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "private": false,
   "license": "MIT",
   "description": "Entity knowledge, agent intelligence, notes, and contacts",
@@ -24,6 +24,11 @@
       "types": "./dist/tags/server/index.d.mts",
       "import": "./dist/tags/server/index.mjs",
       "default": "./dist/tags/server/index.mjs"
+    },
+    "./tags/prisma": {
+      "types": "./dist/tags/prisma/index.d.mts",
+      "import": "./dist/tags/prisma/index.mjs",
+      "default": "./dist/tags/prisma/index.mjs"
     }
   },
   "publishConfig": {
@@ -54,7 +59,7 @@
     }
   },
   "scripts": {
-    "build": "tsup src/index.ts src/tags/index.ts src/tags/server/index.ts --format esm --dts --clean",
+    "build": "tsup src/index.ts src/tags/index.ts src/tags/server/index.ts src/tags/prisma/index.ts --format esm --dts --clean",
     "test": "vitest",
     "test:run": "vitest run"
   }