@ordinatio/entities 1.1.0 → 1.3.0

package/dist/tags/server/index.mjs

@@ -0,0 +1,1043 @@
+import {
+  DEFAULT_TAG_LIMITS,
+  checkTagName,
+  resolveTagColor
+} from "../../chunk-KPZRBM5J.mjs";
+
+// src/tags/server/plan.ts
+function planTagChanges(change, maxChanges) {
+  const add = [...new Set(change.add)];
+  const adding = new Set(add);
+  const remove = [...new Set(change.remove)].filter((id) => !adding.has(id));
+  const count2 = add.length + remove.length;
+  if (count2 > maxChanges) return { ok: false, reason: "too-many-changes", count: count2 };
+  return { ok: true, change: { add, remove } };
+}
+
+// src/tags/server/service.ts
+function byName(a, b) {
+  return a.name.localeCompare(b.name) || a.id.localeCompare(b.id);
+}
+function unknownKind(method, result) {
+  throw new Error(`tag store ${method} returned an unknown result kind "${result.kind}": the store and the service are out of step`);
+}
+function createTagService(store, suppliedLimits = DEFAULT_TAG_LIMITS) {
+  const limits = { ...suppliedLimits };
+  function fail(failure) {
+    return { ok: false, ...failure };
+  }
+  function checkName(name) {
+    const checked = checkTagName(name, limits.maxNameLength);
+    if (checked.ok) return checked;
+    return { ok: false, failure: { reason: "invalid-name", problem: checked.reason, length: checked.length } };
+  }
+  async function create(input) {
+    const name = checkName(input.name);
+    if (!name.ok) return fail(name.failure);
+    const color = resolveTagColor(input.color);
+    if (!color.ok) return fail({ reason: "invalid-color", color: String(input.color) });
+    const result = await store.create({ name: name.name, nameKey: name.key, color: color.color }, { maxTags: limits.maxPerWorkspace });
+    if (result.kind === "created") return { ok: true, tag: result.tag };
+    if (result.kind === "duplicate") return fail({ reason: "duplicate" });
+    if (result.kind === "limit") return fail({ reason: "limit" });
+    return unknownKind("create", result);
+  }
+  async function findOrCreate(name) {
+    const checked = checkName(name);
+    if (!checked.ok) return fail(checked.failure);
+    const existing = await store.findByKey(checked.key);
+    if (existing) return { ok: true, tag: existing, created: false };
+    for (let attempt = 0; attempt < 2; attempt++) {
+      const made = await create({ name: checked.name });
+      if (made.ok) return { ok: true, tag: made.tag, created: true };
+      if (made.reason !== "duplicate") return made;
+      const raced = await store.findByKey(checked.key);
+      if (raced) return { ok: true, tag: raced, created: false };
+    }
+    return fail({ reason: "duplicate" });
+  }
+  async function update(id, input) {
+    if (!await store.get(id)) return fail({ reason: "not-found" });
+    const patch = {};
+    if (input.name !== void 0) {
+      const name = checkName(input.name);
+      if (!name.ok) return fail(name.failure);
+      patch.rename = { name: name.name, nameKey: name.key };
+    }
+    if (input.color !== void 0) {
+      const color = resolveTagColor(input.color);
+      if (!color.ok) return fail({ reason: "invalid-color", color: String(input.color) });
+      patch.color = color.color;
+    }
+    if (input.pinned !== void 0) patch.pinned = input.pinned;
+    const result = await store.update(id, patch, { maxPinned: limits.maxPinned });
+    if (result.kind === "updated") return { ok: true, before: result.before, after: result.after };
+    if (result.kind === "notFound") return fail({ reason: "not-found" });
+    if (result.kind === "pinLimit") return fail({ reason: "pin-limit" });
+    if (result.kind === "duplicate") return fail({ reason: "duplicate" });
+    return unknownKind("update", result);
+  }
+  return {
+    async list() {
+      return [...await store.list()].sort(byName);
+    },
+    async options() {
+      return [...await store.list()].sort(byName).map((tag) => ({ id: tag.id, name: tag.name, color: tag.color }));
+    },
+    async pinned() {
+      return [...await store.listPinned(limits.maxPinned)].sort(byName);
+    },
+    async get(id) {
+      const tag = await store.get(id);
+      return tag ? { ok: true, tag } : fail({ reason: "not-found" });
+    },
+    create,
+    findOrCreate,
+    update,
+    async remove(id) {
+      const result = await store.remove(id);
+      if (result.kind === "removed") return { ok: true, tag: result.tag };
+      if (result.kind === "notFound") return fail({ reason: "not-found" });
+      return unknownKind("remove", result);
+    },
+    async applyChanges(target, targetId, change, actorId) {
+      const plan = planTagChanges(change, limits.maxChangesPerSave);
+      if (!plan.ok) return fail({ reason: "too-many-changes", count: plan.count });
+      if (plan.change.add.length === 0 && plan.change.remove.length === 0) return { ok: true, added: [], removed: [], skipped: [] };
+      if (!await store.targetExists(target, targetId)) return fail({ reason: "target-gone" });
+      const result = await store.applyLinks(target, targetId, plan.change, actorId);
+      if (result.kind === "applied") return { ok: true, added: result.added, removed: result.removed, skipped: result.skipped };
+      if (result.kind === "targetGone") return fail({ reason: "target-gone" });
+      if (result.kind === "tagGone") return fail({ reason: "tag-gone" });
+      return unknownKind("applyLinks", result);
+    },
+    async forTarget(target, targetId) {
+      if (!await store.targetExists(target, targetId)) return fail({ reason: "target-gone" });
+      return { ok: true, tags: [...await store.tagsForTarget(target, targetId)].sort(byName) };
+    },
+    async forTargets(target, targetIds) {
+      const found = await store.tagsForTargets(target, targetIds);
+      return new Map([...found].map(([id, tags]) => [id, [...tags].sort(byName)]));
+    },
+    counts(ids2) {
+      return store.counts(ids2);
+    }
+  };
+}
+
+// src/tags/server/memory-store.ts
+var tick = () => Promise.resolve();
+var linkKey = (type, targetId, tagId) => `${type}\0${targetId}\0${tagId}`;
+var targetKey = (type, id) => `${type}\0${id}`;
+function createMemoryTagWorld(options) {
+  const serialise = options.serialise ?? true;
+  const tags = /* @__PURE__ */ new Map();
+  const links = /* @__PURE__ */ new Map();
+  const targets = /* @__PURE__ */ new Map();
+  let sequence = 0;
+  let pendingHook = null;
+  let tail = Promise.resolve();
+  function exclusive(fn) {
+    if (!serialise) return fn();
+    const run = tail.then(fn, fn);
+    tail = run.then(() => void 0, () => void 0);
+    return run;
+  }
+  const copy = (record) => ({ ...record });
+  function store(workspace) {
+    const mine = () => [...tags.values()].filter((row) => row.workspace === workspace).map((row) => row.record);
+    const own = (id) => {
+      const row = tags.get(id);
+      return row && row.workspace === workspace ? row.record : void 0;
+    };
+    const targetIsMine = (type, id) => targets.get(targetKey(type, id))?.workspace === workspace;
+    const zeroCounts = () => Object.fromEntries(options.targetTypes.map((type) => [type, 0]));
+    return {
+      async list() {
+        return mine().map(copy);
+      },
+      async listPinned(limit) {
+        return mine().filter((tag) => tag.pinned).slice(0, limit).map(copy);
+      },
+      async getMany(ids2) {
+        const wanted = new Set(ids2);
+        return mine().filter((tag) => wanted.has(tag.id)).map(copy);
+      },
+      async findByKey(nameKey) {
+        const found = mine().find((tag) => tag.nameKey === nameKey);
+        return found ? copy(found) : null;
+      },
+      async get(id) {
+        const found = own(id);
+        return found ? copy(found) : null;
+      },
+      create(input, limits) {
+        return exclusive(async () => {
+          if (mine().length >= limits.maxTags) return { kind: "limit" };
+          if (mine().some((tag) => tag.nameKey === input.nameKey)) return { kind: "duplicate" };
+          await tick();
+          const record = { id: `tag_${++sequence}`, name: input.name, nameKey: input.nameKey, color: input.color, pinned: false };
+          tags.set(record.id, { workspace, record });
+          return { kind: "created", tag: copy(record) };
+        });
+      },
+      update(id, patch, limits) {
+        return exclusive(async () => {
+          const current = own(id);
+          if (!current) return { kind: "notFound" };
+          const before = copy(current);
+          if (patch.pinned === true && !current.pinned && mine().filter((tag) => tag.pinned).length >= limits.maxPinned) return { kind: "pinLimit" };
+          if (patch.rename && mine().some((tag) => tag.id !== id && tag.nameKey === patch.rename?.nameKey)) return { kind: "duplicate" };
+          await tick();
+          if (patch.rename) {
+            current.name = patch.rename.name;
+            current.nameKey = patch.rename.nameKey;
+          }
+          if (patch.color !== void 0) current.color = patch.color;
+          if (patch.pinned !== void 0) current.pinned = patch.pinned;
+          return { kind: "updated", before, after: copy(current) };
+        });
+      },
+      remove(id) {
+        return exclusive(async () => {
+          const current = own(id);
+          if (!current) return { kind: "notFound" };
+          await tick();
+          tags.delete(id);
+          for (const [key3, link] of links) if (link.tagId === id) links.delete(key3);
+          return { kind: "removed", tag: copy(current) };
+        });
+      },
+      async targetExists(target, targetId) {
+        return targetIsMine(target, targetId);
+      },
+      async applyLinks(target, targetId, change, actorId) {
+        const first = await exclusive(async () => {
+          if (!targetIsMine(target, targetId)) return null;
+          const wanted = [...new Set(change.add)];
+          return { attachable: wanted.filter((id) => own(id)), skipped: wanted.filter((id) => !own(id)) };
+        });
+        if (!first) return { kind: "targetGone" };
+        const hook = pendingHook;
+        pendingHook = null;
+        if (hook) await hook();
+        return exclusive(async () => {
+          if (!targetIsMine(target, targetId)) return { kind: "targetGone" };
+          if (first.attachable.some((id) => !own(id))) return { kind: "tagGone" };
+          await tick();
+          const added = [];
+          for (const tagId of first.attachable) {
+            const key3 = linkKey(target, targetId, tagId);
+            if (links.has(key3)) continue;
+            await tick();
+            links.set(key3, { workspace, type: target, targetId, tagId, actorId });
+            added.push(tagId);
+          }
+          const removed = [];
+          for (const tagId of new Set(change.remove)) {
+            if (!own(tagId)) continue;
+            const existing = linkKey(target, targetId, tagId);
+            if (!links.has(existing)) continue;
+            await tick();
+            links.delete(existing);
+            removed.push(tagId);
+          }
+          return { kind: "applied", added, removed, skipped: first.skipped };
+        });
+      },
+      async tagsForTarget(target, targetId) {
+        if (!targetIsMine(target, targetId)) return [];
+        return [...links.values()].filter((link) => link.type === target && link.targetId === targetId).map((link) => own(link.tagId)).filter((tag) => Boolean(tag)).map(copy);
+      },
+      async tagsForTargets(target, targetIds) {
+        const wanted = new Set(targetIds.filter((id) => targetIsMine(target, id)));
+        const result = /* @__PURE__ */ new Map();
+        for (const link of links.values()) {
+          if (link.type !== target || !wanted.has(link.targetId)) continue;
+          const tag = own(link.tagId);
+          if (!tag) continue;
+          const list = result.get(link.targetId) ?? [];
+          list.push(copy(tag));
+          result.set(link.targetId, list);
+        }
+        return result;
+      },
+      async counts(ids2) {
+        const only = ids2 ? new Set(ids2) : null;
+        const result = /* @__PURE__ */ new Map();
+        for (const tag of mine()) if (!only || only.has(tag.id)) result.set(tag.id, zeroCounts());
+        for (const link of links.values()) {
+          if (link.workspace !== workspace) continue;
+          const entry = result.get(link.tagId);
+          if (entry && link.type in entry) entry[link.type] += 1;
+        }
+        return result;
+      }
+    };
+  }
+  return {
+    store,
+    addTarget(workspace, type, chosenId) {
+      const id = chosenId ?? `${type}_${++sequence}`;
+      targets.set(targetKey(type, id), { workspace });
+      return id;
+    },
+    removeTarget(_workspace, type, id) {
+      return exclusive(async () => {
+        targets.delete(targetKey(type, id));
+        for (const [key3, link] of links) if (link.type === type && link.targetId === id) links.delete(key3);
+      });
+    },
+    armBeforeLinkWrite(hook) {
+      pendingHook = hook;
+    },
+    actorOf(workspace, type, targetId, tagId) {
+      const link = links.get(linkKey(type, targetId, tagId));
+      return link && link.workspace === workspace ? link.actorId : void 0;
+    }
+  };
+}
+function createMemoryTagHarness(targetTypes, options = {}) {
+  const world = createMemoryTagWorld({ targetTypes, serialise: options.serialise });
+  let workspaces = 0;
+  return {
+    world,
+    targetTypes,
+    async newWorkspace() {
+      return `workspace_${++workspaces}`;
+    },
+    storeFor: (workspace) => world.store(workspace),
+    async addTarget(workspace, type) {
+      return world.addTarget(workspace, type);
+    },
+    async addTargetWithId(workspace, type, id) {
+      return world.addTarget(workspace, type, id);
+    },
+    async removeTarget(workspace, type, id) {
+      await world.removeTarget(workspace, type, id);
+    },
+    armBeforeLinkWrite: (hook) => world.armBeforeLinkWrite(hook),
+    async cleanup() {
+    }
+  };
+}
+
+// src/tags/server/contract-kit.ts
+var LIMITS = { maxTags: 100 };
+var PIN = { maxPinned: 100 };
+var key = (name) => name.toLowerCase();
+var ids = (tags) => tags.map((tag) => tag.id).sort();
+var core = (tag) => ({ id: tag.id, name: tag.name, nameKey: tag.nameKey, color: tag.color, pinned: tag.pinned });
+var cores = (tags) => tags.map(core).sort((x, y) => x.id.localeCompare(y.id));
+function makeKit(api, harness) {
+  if (harness.targetTypes.length < 3) throw new Error("the tag store contract needs at least three target types");
+  const [first, second, third] = harness.targetTypes;
+  async function setup() {
+    const workspace = await harness.newWorkspace();
+    const store = harness.storeFor(workspace);
+    const make = async (s, name, color = "neutral") => {
+      const result = await s.create({ name, nameKey: key(name), color }, LIMITS);
+      if (result.kind !== "created") throw new Error(`setup: could not create ${name}: ${result.kind}`);
+      return result.tag;
+    };
+    return { workspace, store, make };
+  }
+  return { api, harness, first, second, third, setup };
+}
+
+// src/tags/server/contract-tags.ts
+function defineTagStoreTagsContract(kit) {
+  const { describe, it, expect } = kit.api;
+  const { harness, first, second, setup } = kit;
+  describe("TagStore contract: tags", () => {
+    it("creates a tag and finds it by id, by key and in the list; getMany returns only this workspace's tags", async () => {
+      const { store, make } = await setup();
+      const vip = await make(store, "VIP", "red");
+      expect([vip.name, vip.nameKey, vip.color, vip.pinned]).toEqual(["VIP", "vip", "red", false]);
+      expect((await store.get(vip.id))?.id).toBe(vip.id);
+      expect((await store.findByKey("vip"))?.id).toBe(vip.id);
+      expect(await store.findByKey("nope")).toBeNull();
+      expect(ids(await store.list())).toEqual([vip.id]);
+      expect(cores(await store.list())).toEqual(cores([vip]));
+      expect(cores(await store.getMany([vip.id, "missing"]))).toEqual(cores([vip]));
+      expect(cores([await store.findByKey("vip")])).toEqual(cores([vip]));
+      expect(ids(await store.getMany([vip.id, "missing"]))).toEqual([vip.id]);
+      const other = await make(store, "Other");
+      const unasked = await make(store, "Unasked");
+      expect(ids(await store.getMany([vip.id, other.id, "missing"]))).toEqual(ids([vip, other]));
+      expect(await store.getMany([])).toEqual([]);
+      expect(ids(await store.getMany([vip.id, vip.id]))).toEqual([vip.id]);
+      expect(ids(await store.getMany([unasked.id]))).toEqual([unasked.id]);
+    });
+    it("the key is whatever the caller supplied, kept apart from the name through create, rename and remove, and a renamed-away key is free again", async () => {
+      const { store } = await setup();
+      const created = await store.create({ name: "Foo Bar", nameKey: "foo-bar", color: "neutral" }, LIMITS);
+      if (created.kind !== "created") throw new Error("setup");
+      expect(created.tag.nameKey).toBe("foo-bar");
+      expect((await store.findByKey("foo-bar"))?.id).toBe(created.tag.id);
+      expect(await store.findByKey("foo bar")).toBeNull();
+      const renamed = await store.update(created.tag.id, { rename: { name: "Baz Qux", nameKey: "baz-qux" } }, PIN);
+      expect(renamed.kind === "updated" && [renamed.before.nameKey, renamed.after.nameKey]).toEqual(["foo-bar", "baz-qux"]);
+      expect(await store.findByKey("foo-bar")).toBeNull();
+      expect((await store.create({ name: "Foo Bar", nameKey: "foo-bar", color: "neutral" }, LIMITS)).kind).toBe("created");
+      const removed = await store.remove(created.tag.id);
+      expect(removed.kind === "removed" && [removed.tag.name, removed.tag.nameKey]).toEqual(["Baz Qux", "baz-qux"]);
+    });
+    it("a second tag with the same key is a duplicate and changes nothing", async () => {
+      const { store, make } = await setup();
+      await make(store, "VIP");
+      expect(await store.create({ name: "vip", nameKey: "vip", color: "blue" }, LIMITS)).toEqual({ kind: "duplicate" });
+      expect((await store.list()).length).toBe(1);
+    });
+    it("the create limit wins over duplicate, and only this workspace's tags count toward it", async () => {
+      const { store, make } = await setup();
+      await make(store, "a");
+      await make(store, "b");
+      expect(await store.create({ name: "a", nameKey: "a", color: "neutral" }, { maxTags: 2 })).toEqual({ kind: "limit" });
+      expect(await store.create({ name: "new", nameKey: "new", color: "neutral" }, { maxTags: 0 })).toEqual({ kind: "limit" });
+      const pinned = await make(store, "pinned");
+      await store.update(pinned.id, { pinned: true }, PIN);
+      expect(await store.create({ name: "new", nameKey: "new", color: "neutral" }, { maxTags: 3 })).toEqual({ kind: "limit" });
+      const other = harness.storeFor(await harness.newWorkspace());
+      await make(other, "x");
+      await make(other, "y");
+      expect((await other.create({ name: "z", nameKey: "z", color: "neutral" }, { maxTags: 3 })).kind).toBe("created");
+    });
+    it("rename: a case change of the same tag works, onto another tag's key is a duplicate, and sequential renames give consistent pairs", async () => {
+      const { store, make } = await setup();
+      const a = await make(store, "vip");
+      const b = await make(store, "other");
+      const cased = await store.update(a.id, { rename: { name: "VIP", nameKey: "vip" } }, PIN);
+      expect(cased.kind === "updated" && [cased.before.name, cased.after.name]).toEqual(["vip", "VIP"]);
+      expect(await store.update(a.id, { rename: { name: "Other", nameKey: "other" }, color: "red", pinned: true }, PIN)).toEqual({ kind: "duplicate" });
+      expect(core(await store.get(a.id))).toEqual({ ...core(a), name: "VIP" });
+      expect(await store.update(a.id, { rename: { name: "Other", nameKey: "other" } }, PIN)).toEqual({ kind: "duplicate" });
+      const toB = await store.update(b.id, { rename: { name: "B", nameKey: "b" } }, PIN);
+      const toC = await store.update(b.id, { rename: { name: "C", nameKey: "c" } }, PIN);
+      expect(toB.kind === "updated" && toC.kind === "updated" && [toB.after.name, toC.before.name, toC.after.name]).toEqual(["B", "B", "C"]);
+    });
+    it("an empty update is a no-op that reports equal before and after", async () => {
+      const { store, make } = await setup();
+      const tag = await make(store, "x", "red");
+      const result = await store.update(tag.id, {}, PIN);
+      expect(result.kind === "updated" && [core(result.before), core(result.after)]).toEqual([core(tag), core(tag)]);
+    });
+    it("update changes colour and pinned together and reports before and after", async () => {
+      const { store, make } = await setup();
+      const tag = await make(store, "x");
+      const result = await store.update(tag.id, { color: "blue", pinned: true }, PIN);
+      expect(result.kind === "updated" && [result.before.color, result.before.pinned, result.after.color, result.after.pinned]).toEqual(["neutral", false, "blue", true]);
+    });
+    it("one update can rename, recolour and pin together, and every part is applied", async () => {
+      const { store, make } = await setup();
+      const tag = await make(store, "old");
+      const result = await store.update(tag.id, { rename: { name: "New", nameKey: "new" }, color: "blue", pinned: true }, PIN);
+      expect(result.kind === "updated" && [result.after.name, result.after.nameKey, result.after.color, result.after.pinned]).toEqual(["New", "new", "blue", true]);
+      expect(result.kind === "updated" && [result.before.name, result.before.color, result.before.pinned]).toEqual(["old", "neutral", false]);
+      expect((await store.findByKey("new"))?.id).toBe(tag.id);
+    });
+    it("a single-field update leaves the other fields as they were", async () => {
+      const { store, make } = await setup();
+      const tag = await make(store, "base", "red");
+      await store.update(tag.id, { pinned: true }, PIN);
+      const renamed = await store.update(tag.id, { rename: { name: "Renamed", nameKey: "renamed" } }, PIN);
+      expect(renamed.kind === "updated" && [renamed.after.color, renamed.after.pinned]).toEqual(["red", true]);
+      const recoloured = await store.update(tag.id, { color: "blue" }, PIN);
+      expect(recoloured.kind === "updated" && [recoloured.after.name, recoloured.after.pinned]).toEqual(["Renamed", true]);
+      const unpinned = await store.update(tag.id, { pinned: false }, PIN);
+      expect(unpinned.kind === "updated" && [unpinned.after.name, unpinned.after.color]).toEqual(["Renamed", "blue"]);
+    });
+    it("unpinning frees the pin slot for another tag", async () => {
+      const { store, make } = await setup();
+      const [a, b] = [await make(store, "a"), await make(store, "b")];
+      await store.update(a.id, { pinned: true }, { maxPinned: 1 });
+      expect((await store.update(b.id, { pinned: true }, { maxPinned: 1 })).kind).toBe("pinLimit");
+      await store.update(a.id, { pinned: false }, { maxPinned: 1 });
+      expect((await store.update(b.id, { pinned: true }, { maxPinned: 1 })).kind).toBe("updated");
+    });
+    it("pinning: pin limit wins over duplicate; an already-pinned tag re-pins at the limit; unpinning needs no limit", async () => {
+      const { store, make } = await setup();
+      const a = await make(store, "a");
+      const b = await make(store, "b");
+      expect((await store.update(a.id, { pinned: true }, { maxPinned: 1 })).kind).toBe("updated");
+      expect(await store.update(b.id, { rename: { name: "A", nameKey: "a" }, color: "red", pinned: true }, { maxPinned: 1 })).toEqual({ kind: "pinLimit" });
+      expect(core(await store.get(b.id))).toEqual(core(b));
+      expect((await store.update(a.id, { pinned: true }, { maxPinned: 1 })).kind).toBe("updated");
+      const unpinned = await store.update(a.id, { pinned: false }, { maxPinned: 0 });
+      expect(unpinned.kind === "updated" && [unpinned.before.pinned, unpinned.after.pinned]).toEqual([true, false]);
+      expect((await store.get(a.id))?.pinned).toBe(false);
+      expect((await store.update(b.id, { pinned: false }, { maxPinned: 0 })).kind).toBe("updated");
+      expect((await store.get(b.id))?.name).toBe("b");
+    });
+    it("update and remove of an unknown id are notFound, and listPinned returns only pinned tags up to the limit", async () => {
+      const { store, make } = await setup();
+      expect(await store.update("missing", { color: "red" }, PIN)).toEqual({ kind: "notFound" });
+      expect(await store.remove("missing")).toEqual({ kind: "notFound" });
+      const tags = [await make(store, "a"), await make(store, "b"), await make(store, "c"), await make(store, "d")];
+      for (const tag of tags.slice(1)) await store.update(tag.id, { pinned: true }, PIN);
+      expect((await store.listPinned(2)).length).toBe(2);
+      expect((await store.listPinned(0)).length).toBe(0);
+      expect(ids(await store.listPinned(10))).toEqual(ids(tags.slice(1)));
+      expect(cores(await store.listPinned(10))).toEqual(cores(tags.slice(1)).map((tag) => ({ ...tag, pinned: true })));
+    });
+    it("remove returns the tag, the tag disappears from its targets and from the counts, and a second remove is notFound", async () => {
+      const { workspace, store, make } = await setup();
+      const made = await make(store, "gone", "red");
+      await store.update(made.id, { pinned: true }, PIN);
+      const tag = await store.get(made.id);
+      const target = await harness.addTarget(workspace, first);
+      await store.applyLinks(first, target, { add: [tag.id], remove: [] }, "actor");
+      const removed = await store.remove(tag.id);
+      expect(removed.kind === "removed" && core(removed.tag)).toEqual(core(tag));
+      expect((await store.create({ name: "gone", nameKey: "gone", color: "red" }, { maxTags: 1 })).kind).toBe("created");
+      expect((await store.tagsForTarget(first, target)).length).toBe(0);
+      expect((await store.counts()).has(tag.id)).toBe(false);
+      expect(await store.remove(tag.id)).toEqual({ kind: "notFound" });
+    });
+  });
+}
+
+// src/tags/server/contract-links.ts
+function defineTagStoreLinksContract(kit) {
+  const { describe, it, expect } = kit.api;
+  const { harness, first, second, setup } = kit;
+  describe("TagStore contract: links", () => {
+    it("adds and removes links; repeating an add or a remove reports nothing the second time", async () => {
+      const { workspace, store, make } = await setup();
+      const [a, b] = [await make(store, "a"), await make(store, "b")];
+      const target = await harness.addTarget(workspace, first);
+      const added = await store.applyLinks(first, target, { add: [a.id, b.id], remove: [] }, "u1");
+      expect(added.kind === "applied" && [[...added.added].sort(), added.removed, added.skipped]).toEqual([[a.id, b.id].sort(), [], []]);
+      const again = await store.applyLinks(first, target, { add: [a.id], remove: [] }, "u2");
+      expect(again.kind === "applied" && [again.added, again.skipped]).toEqual([[], []]);
+      const removed = await store.applyLinks(first, target, { add: [], remove: [a.id] }, "u1");
+      expect(removed.kind === "applied" && removed.removed).toEqual([a.id]);
+      const removedAgain = await store.applyLinks(first, target, { add: [], remove: [a.id] }, "u1");
+      expect(removedAgain.kind === "applied" && removedAgain.removed).toEqual([]);
+      expect(ids(await store.tagsForTarget(first, target))).toEqual([b.id]);
+    });
+    it("removing a tag from one target leaves the same tag on another target of the same kind", async () => {
+      const { workspace, store, make } = await setup();
+      const a = await make(store, "a");
+      const [one, two] = [await harness.addTarget(workspace, first), await harness.addTarget(workspace, first)];
+      await store.applyLinks(first, one, { add: [a.id], remove: [] }, "u");
+      await store.applyLinks(first, two, { add: [a.id], remove: [] }, "u");
+      await store.applyLinks(first, two, { add: [], remove: [a.id] }, "u");
+      expect(ids(await store.tagsForTarget(first, two))).toEqual([]);
+      expect(ids(await store.tagsForTarget(first, one))).toEqual([a.id]);
+      expect((await store.counts([a.id])).get(a.id)?.[first]).toBe(1);
+    });
+    it("counts for several ids returns exactly the live ones asked for, each with its own numbers", async () => {
+      const { workspace, store, make } = await setup();
+      const [a, b, doomed] = [await make(store, "a"), await make(store, "b"), await make(store, "doomed")];
+      const [t1, t2] = [await harness.addTarget(workspace, first), await harness.addTarget(workspace, first)];
+      await store.applyLinks(first, t1, { add: [a.id, b.id], remove: [] }, "u");
+      await store.applyLinks(first, t2, { add: [a.id], remove: [] }, "u");
+      await store.remove(doomed.id);
+      const other = harness.storeFor(await harness.newWorkspace());
+      const foreign = await make(other, "foreign");
+      const counts = await store.counts([a.id, b.id, doomed.id, foreign.id, "missing"]);
+      expect([...counts.keys()].sort()).toEqual([a.id, b.id].sort());
+      expect([counts.get(a.id)?.[first], counts.get(b.id)?.[first]]).toEqual([2, 1]);
+    });
+    it("several skipped and several removed ids in one call are all reported, and only the ones really linked count as removed", async () => {
+      const { workspace, store, make } = await setup();
+      const [a, b, never] = [await make(store, "a"), await make(store, "b"), await make(store, "never")];
+      const target = await harness.addTarget(workspace, first);
+      const added = await store.applyLinks(first, target, { add: [a.id, b.id, "ghost-1", "ghost-2"], remove: [] }, "u");
+      expect(added.kind === "applied" && [[...added.added].sort(), [...added.skipped].sort()]).toEqual([[a.id, b.id].sort(), ["ghost-1", "ghost-2"]]);
+      const removed = await store.applyLinks(first, target, { add: [], remove: [a.id, never.id, b.id] }, "u");
+      expect(removed.kind === "applied" && [...removed.removed].sort()).toEqual([a.id, b.id].sort());
+      expect(ids(await store.tagsForTarget(first, target))).toEqual([]);
+    });
+    it("a removed tag is gone from every read, frees its pin slot and its key, and cannot be linked again", async () => {
+      const { workspace, store, make } = await setup();
+      const [gone, keeper] = [await make(store, "gone", "red"), await make(store, "keeper")];
+      await store.update(gone.id, { pinned: true }, PIN);
+      const target = await harness.addTarget(workspace, first);
+      await store.applyLinks(first, target, { add: [gone.id], remove: [] }, "u");
+      expect((await store.remove(gone.id)).kind).toBe("removed");
+      expect(ids(await store.list())).toEqual([keeper.id]);
+      expect(await store.listPinned(10)).toEqual([]);
+      expect(await store.getMany([gone.id])).toEqual([]);
+      expect(await store.get(gone.id)).toBeNull();
+      expect(await store.findByKey(gone.nameKey)).toBeNull();
+      expect(await store.update(gone.id, { color: "blue" }, PIN)).toEqual({ kind: "notFound" });
+      expect((await store.tagsForTargets(first, [target])).size).toBe(0);
+      expect((await store.update(keeper.id, { pinned: true }, { maxPinned: 1 })).kind).toBe("updated");
+      expect((await store.update(keeper.id, { rename: { name: "Gone", nameKey: "gone" } }, PIN)).kind).toBe("updated");
+      const relink = await store.applyLinks(first, target, { add: [gone.id], remove: [] }, "u");
+      expect(relink.kind === "applied" && [relink.added, relink.skipped]).toEqual([[], [gone.id]]);
+    });
+    it("removing one tag leaves every other tag's links, on all targets, untouched", async () => {
+      const { workspace, store, make } = await setup();
+      const [doomed, keeper] = [await make(store, "doomed"), await make(store, "keeper")];
+      const [one, two] = [await harness.addTarget(workspace, first), await harness.addTarget(workspace, second)];
+      await store.applyLinks(first, one, { add: [doomed.id, keeper.id], remove: [] }, "u");
+      await store.applyLinks(second, two, { add: [doomed.id, keeper.id], remove: [] }, "u");
+      expect((await store.remove(doomed.id)).kind).toBe("removed");
+      expect(ids(await store.tagsForTarget(first, one))).toEqual([keeper.id]);
+      expect(ids(await store.tagsForTarget(second, two))).toEqual([keeper.id]);
+      const counts = (await store.counts([keeper.id])).get(keeper.id);
+      expect([counts?.[first], counts?.[second]]).toEqual([1, 1]);
+    });
+    it("one save can add and remove together, and an empty save on an existing target applies nothing", async () => {
+      const { workspace, store, make } = await setup();
+      const [a, b] = [await make(store, "a"), await make(store, "b")];
+      const target = await harness.addTarget(workspace, first);
+      expect(await store.applyLinks(first, target, { add: [], remove: [] }, "u")).toEqual({ kind: "applied", added: [], removed: [], skipped: [] });
+      await store.applyLinks(first, target, { add: [a.id], remove: [] }, "u");
+      const swap = await store.applyLinks(first, target, { add: [b.id], remove: [a.id] }, "u");
+      expect(swap).toEqual({ kind: "applied", added: [b.id], removed: [a.id], skipped: [] });
+      expect(ids(await store.tagsForTarget(first, target))).toEqual([b.id]);
+    });
+    it("a tag can be added again after it was removed from the same target", 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");
+      await store.applyLinks(first, target, { add: [], remove: [a.id] }, "u");
+      const again = await store.applyLinks(first, target, { add: [a.id], remove: [] }, "u");
+      expect(again.kind === "applied" && again.added).toEqual([a.id]);
+      expect(ids(await store.tagsForTarget(first, target))).toEqual([a.id]);
+      expect((await store.counts([a.id])).get(a.id)?.[first]).toBe(1);
+    });
+    it("repeated ids in add or remove are applied once and reported once", async () => {
+      const { workspace, store, make } = await setup();
+      const a = await make(store, "a");
+      const target = await harness.addTarget(workspace, first);
+      const added = await store.applyLinks(first, target, { add: [a.id, a.id], remove: [] }, "u");
+      expect(added.kind === "applied" && [added.added, added.skipped]).toEqual([[a.id], []]);
+      const ghosts = await store.applyLinks(first, target, { add: ["ghost", "ghost"], remove: [] }, "u");
+      expect(ghosts.kind === "applied" && ghosts.skipped).toEqual(["ghost"]);
+      const removed = await store.applyLinks(first, target, { add: [], remove: [a.id, a.id] }, "u");
+      expect(removed.kind === "applied" && removed.removed).toEqual([a.id]);
+    });
+    it("skipped is only the ids in add that are not this workspace's tags; unknown ids in remove are ignored silently", async () => {
+      const { workspace, store, make } = await setup();
+      const a = await make(store, "a");
+      const target = await harness.addTarget(workspace, first);
+      const result = await store.applyLinks(first, target, { add: ["unknown", a.id], remove: ["also-unknown"] }, "u");
+      expect(result.kind === "applied" && [result.added, result.removed, result.skipped]).toEqual([[a.id], [], ["unknown"]]);
+    });
+  });
+}
+
+// src/tags/server/contract-scoping.ts
+function defineTagStoreScopingContract(kit) {
+  const { describe, it, expect } = kit.api;
+  const { harness, first, second, third, setup } = kit;
+  describe("TagStore contract: tenancy, targets and counts", () => {
+    it("tenancy: another workspace's tag and target are invisible and untouchable (skipped when added, reported as nothing when removed)", async () => {
+      const { workspace, store, make } = await setup();
+      const otherWorkspace = await harness.newWorkspace();
+      const other = harness.storeFor(otherWorkspace);
+      const foreignTag = await make(other, "foreign");
+      await other.update(foreignTag.id, { pinned: true }, PIN);
+      const foreignTarget = await harness.addTarget(otherWorkspace, first);
+      await other.applyLinks(first, foreignTarget, { add: [foreignTag.id], remove: [] }, "o");
+      const target = await harness.addTarget(workspace, first);
+      const added = await store.applyLinks(first, target, { add: [foreignTag.id], remove: [] }, "u");
+      expect(added.kind === "applied" && [added.added, added.skipped]).toEqual([[], [foreignTag.id]]);
+      const removed = await store.applyLinks(first, target, { add: [], remove: [foreignTag.id] }, "u");
+      expect(removed.kind === "applied" && [removed.removed, removed.skipped]).toEqual([[], []]);
+      expect(ids(await other.tagsForTarget(first, foreignTarget))).toEqual([foreignTag.id]);
+      expect(await store.applyLinks(first, foreignTarget, { add: [], remove: [] }, "u")).toEqual({ kind: "targetGone" });
+      expect(await store.targetExists(first, foreignTarget)).toBe(false);
+      expect(await store.tagsForTarget(first, foreignTarget)).toEqual([]);
+      expect((await store.tagsForTargets(first, [foreignTarget])).size).toBe(0);
+      expect(await store.get(foreignTag.id)).toBeNull();
+      expect(await store.findByKey(foreignTag.nameKey)).toBeNull();
+      expect(await store.update(foreignTag.id, { color: "red" }, PIN)).toEqual({ kind: "notFound" });
+      expect(await store.remove(foreignTag.id)).toEqual({ kind: "notFound" });
+      expect((await store.getMany([foreignTag.id])).length).toBe(0);
+      expect((await store.listPinned(10)).length).toBe(0);
+      expect((await store.counts([foreignTag.id])).size).toBe(0);
+      expect((await store.counts()).has(foreignTag.id)).toBe(false);
+      expect((await store.list()).length).toBe(0);
+      expect((await other.get(foreignTag.id))?.pinned).toBe(true);
+    });
+    it("only this workspace's pinned tags count toward the pin limit, and only its keys count for a rename", async () => {
+      const { store, make } = await setup();
+      const other = harness.storeFor(await harness.newWorkspace());
+      const foreign = await make(other, "taken");
+      await other.update(foreign.id, { pinned: true }, PIN);
+      const mine = await make(store, "mine");
+      expect((await store.update(mine.id, { pinned: true }, { maxPinned: 1 })).kind).toBe("updated");
+      const renamed = await store.update(mine.id, { rename: { name: "Taken", nameKey: "taken" } }, PIN);
+      expect(renamed.kind).toBe("updated");
+    });
+    it("calls aimed at another workspace's tag change nothing of it, not even before answering notFound", async () => {
+      const { store, make } = await setup();
+      const theirWorkspace = await harness.newWorkspace();
+      const other = harness.storeFor(theirWorkspace);
+      const foreign = await make(other, "shared", "red");
+      await other.update(foreign.id, { pinned: true }, PIN);
+      const foreignTarget = await harness.addTarget(theirWorkspace, first);
+      await other.applyLinks(first, foreignTarget, { add: [foreign.id], remove: [] }, "u");
+      const before = core(await other.get(foreign.id));
+      expect(await store.update(foreign.id, { rename: { name: "X", nameKey: "x" }, color: "blue", pinned: false }, PIN)).toEqual({ kind: "notFound" });
+      expect(await store.update(foreign.id, { color: "blue" }, PIN)).toEqual({ kind: "notFound" });
+      expect(await store.update(foreign.id, { pinned: false }, PIN)).toEqual({ kind: "notFound" });
+      expect(await store.update(foreign.id, {}, PIN)).toEqual({ kind: "notFound" });
+      expect(await store.remove(foreign.id)).toEqual({ kind: "notFound" });
+      const mine = await make(store, "shared");
+      expect((await store.remove(mine.id)).kind).toBe("removed");
+      expect(core(await other.get(foreign.id))).toEqual(before);
+      expect(ids(await other.tagsForTarget(first, foreignTarget))).toEqual([foreign.id]);
+      expect((await other.counts([foreign.id])).get(foreign.id)?.[first]).toBe(1);
+    });
+    it("an update of a tag that does not exist is notFound before anything else is looked at", async () => {
+      const { store, make } = await setup();
+      await make(store, "taken");
+      expect(await store.update("missing", {}, PIN)).toEqual({ kind: "notFound" });
+      expect(await store.update("missing", { pinned: true }, { maxPinned: 0 })).toEqual({ kind: "notFound" });
+      expect(await store.update("missing", { rename: { name: "Taken", nameKey: "taken" } }, PIN)).toEqual({ kind: "notFound" });
+    });
+    it("an update of one tag leaves every other tag as it was", async () => {
+      const { store, make } = await setup();
+      const [x, y] = [await make(store, "x", "red"), await make(store, "y", "green")];
+      await store.update(y.id, { pinned: true }, PIN);
+      await store.update(x.id, { pinned: true }, PIN);
+      const untouched = core(await store.get(y.id));
+      await store.update(x.id, { color: "blue" }, PIN);
+      await store.update(x.id, { rename: { name: "X2", nameKey: "x2" } }, PIN);
+      await store.update(x.id, { pinned: false }, PIN);
+      expect(core(await store.get(y.id))).toEqual(untouched);
+    });
+    it("no write touches anything it was not asked to: other tags, their links, their counts and the other workspace stay exactly as they were", async () => {
+      const { workspace, store, make } = await setup();
+      const otherWorkspace = await harness.newWorkspace();
+      const other = harness.storeFor(otherWorkspace);
+      const seed = async (s, ws) => {
+        const [dup, keep] = [await make(s, "dup", "red"), await make(s, "keep", "green")];
+        await s.update(dup.id, { pinned: true }, PIN);
+        const target = await harness.addTarget(ws, first);
+        await s.applyLinks(first, target, { add: [dup.id, keep.id], remove: [] }, "u");
+        return { dup, keep, target };
+      };
+      const fresh = await make(store, "fresh");
+      const mine = await seed(store, workspace);
+      const theirs = await seed(other, otherWorkspace);
+      const snap = async (s, target, skip = []) => {
+        const counts = await s.counts();
+        return { tags: cores((await s.list()).filter((tag) => !skip.includes(tag.id))), links: ids(await s.tagsForTarget(first, target)).filter((id) => !skip.includes(id)), counts: [...counts.entries()].filter(([id]) => !skip.includes(id)).sort() };
+      };
+      const theirsBefore = await snap(other, theirs.target);
+      const operations = [
+        ["create", [], async () => store.create({ name: "brand new", nameKey: "brand-new", color: "blue" }, LIMITS)],
+        ["recolour", [mine.dup.id], async () => store.update(mine.dup.id, { color: "blue" }, PIN)],
+        ["unpin", [mine.dup.id], async () => store.update(mine.dup.id, { pinned: false }, PIN)],
+        ["pin", [mine.dup.id], async () => store.update(mine.dup.id, { pinned: true }, PIN)],
+        ["rename", [mine.dup.id], async () => store.update(mine.dup.id, { rename: { name: "Dup 2", nameKey: "dup-2" } }, PIN)],
+        ["link to a missing target", [], async () => store.applyLinks(first, "nothing", { add: [fresh.id], remove: [] }, "u")],
+        ["link to a target under the wrong kind", [], async () => store.applyLinks(second, mine.target, { add: [fresh.id], remove: [] }, "u")],
+        ["link another workspace's tag", [], async () => store.applyLinks(first, mine.target, { add: [theirs.dup.id], remove: [] }, "u")],
+        ["link a tag", [fresh.id], async () => store.applyLinks(first, mine.target, { add: [fresh.id], remove: [] }, "u")],
+        ["unlink a tag", [fresh.id], async () => store.applyLinks(first, mine.target, { add: [], remove: [fresh.id] }, "u")],
+        ["remove a tag", [fresh.id], async () => store.remove(fresh.id)]
+      ];
+      for (const [name, touched, run] of operations) {
+        const skipNow = async () => {
+          const created = (await store.findByKey("brand-new"))?.id;
+          return created ? [...touched, created] : touched;
+        };
+        const before = await snap(store, mine.target, await skipNow());
+        await run();
+        const after = await snap(store, mine.target, await skipNow());
+        expect([name, after]).toEqual([name, before]);
+        expect([name, await snap(other, theirs.target)]).toEqual([name, theirsBefore]);
+      }
+      const dupLinked = ids(await store.tagsForTarget(first, mine.target));
+      expect(dupLinked.includes(mine.dup.id)).toBe(true);
+    });
+    it("the same tag name can exist in two workspaces", async () => {
+      const { store, make } = await setup();
+      const other = harness.storeFor(await harness.newWorkspace());
+      const mine = await make(store, "Shared");
+      const theirs = await make(other, "Shared");
+      expect((await store.findByKey("shared"))?.id).toBe(mine.id);
+      expect((await other.findByKey("shared"))?.id).toBe(theirs.id);
+    });
+    it("a target that never existed or was deleted is targetGone", async () => {
+      const { workspace, store, make } = await setup();
+      const a = await make(store, "a");
+      expect(await store.applyLinks(first, "nothing", { add: [a.id], remove: [] }, "u")).toEqual({ kind: "targetGone" });
+      const target = await harness.addTarget(workspace, first);
+      expect(await store.targetExists(first, target)).toBe(true);
+      await harness.removeTarget(workspace, first, target);
+      expect(await store.targetExists(first, target)).toBe(false);
+      expect(await store.applyLinks(first, target, { add: [a.id], remove: [] }, "u")).toEqual({ kind: "targetGone" });
+    });
+    it("a target id asked for under the wrong kind is targetGone, not a target of that kind", async () => {
+      const { workspace, store, make } = await setup();
+      const a = await make(store, "a");
+      const target = await harness.addTarget(workspace, first);
+      expect(await store.targetExists(second, target)).toBe(false);
+      expect(await store.applyLinks(second, target, { add: [a.id], remove: [] }, "u")).toEqual({ kind: "targetGone" });
+      expect(await store.tagsForTarget(second, target)).toEqual([]);
+      expect(await store.tagsForTarget(first, target)).toEqual([]);
+    });
+    const sharedId = harness.addTargetWithId ? it : it.skip ?? it;
+    sharedId("two targets of different kinds that share one id keep separate tags", async () => {
+      const { workspace, store, make } = await setup();
+      const [a, b] = [await make(store, "a"), await make(store, "b")];
+      await harness.addTargetWithId?.(workspace, first, "7");
+      await harness.addTargetWithId?.(workspace, second, "7");
+      await store.applyLinks(first, "7", { add: [a.id], remove: [] }, "u");
+      await store.applyLinks(second, "7", { add: [b.id], remove: [] }, "u");
+      expect(ids(await store.tagsForTarget(first, "7"))).toEqual([a.id]);
+      expect(ids(await store.tagsForTarget(second, "7"))).toEqual([b.id]);
+      expect(ids((await store.tagsForTargets(first, ["7"])).get("7") ?? [])).toEqual([a.id]);
+      expect([(await store.counts([a.id])).get(a.id)?.[first], (await store.counts([a.id])).get(a.id)?.[second]]).toEqual([1, 0]);
+    });
+    sharedId("with one id under two kinds, linking and unlinking the same tag on one kind never touches the other", async () => {
+      const { workspace, store, make } = await setup();
+      const t = await make(store, "t");
+      await harness.addTargetWithId?.(workspace, first, "9");
+      await harness.addTargetWithId?.(workspace, second, "9");
+      const onFirst = await store.applyLinks(first, "9", { add: [t.id], remove: [] }, "u");
+      const onSecond = await store.applyLinks(second, "9", { add: [t.id], remove: [] }, "u");
+      expect([onFirst.kind === "applied" && onFirst.added, onSecond.kind === "applied" && onSecond.added]).toEqual([[t.id], [t.id]]);
+      const gone = await store.applyLinks(second, "9", { add: [], remove: [t.id] }, "u");
+      expect(gone.kind === "applied" && gone.removed).toEqual([t.id]);
+      expect(ids(await store.tagsForTarget(first, "9"))).toEqual([t.id]);
+      expect(ids(await store.tagsForTarget(second, "9"))).toEqual([]);
+      const again = await store.applyLinks(second, "9", { add: [], remove: [t.id] }, "u");
+      expect(again.kind === "applied" && again.removed).toEqual([]);
+      expect(ids(await store.tagsForTarget(first, "9"))).toEqual([t.id]);
+    });
+    sharedId("deleting a target under one kind leaves the same id's tags under another kind alone", async () => {
+      const { workspace, store, make } = await setup();
+      const t = await make(store, "t");
+      await harness.addTargetWithId?.(workspace, first, "5");
+      await harness.addTargetWithId?.(workspace, second, "5");
+      await store.applyLinks(first, "5", { add: [t.id], remove: [] }, "u");
+      await store.applyLinks(second, "5", { add: [t.id], remove: [] }, "u");
+      await harness.removeTarget(workspace, first, "5");
+      expect(await store.targetExists(first, "5")).toBe(false);
+      expect(ids(await store.tagsForTarget(second, "5"))).toEqual([t.id]);
+      expect((await store.counts([t.id])).get(t.id)?.[second]).toBe(1);
+    });
+    it("tagsForTargets returns only targets that have tags, and not a target of another kind that was asked for", async () => {
+      const { workspace, store, make } = await setup();
+      const [a, b, c] = [await make(store, "a"), await make(store, "b"), await make(store, "c")];
+      const t1 = await harness.addTarget(workspace, first);
+      const t2 = await harness.addTarget(workspace, first);
+      const t3 = await harness.addTarget(workspace, first);
+      const other = await harness.addTarget(workspace, second);
+      const notAsked = await harness.addTarget(workspace, first);
+      await store.applyLinks(first, notAsked, { add: [a.id], remove: [] }, "u");
+      await store.applyLinks(first, t1, { add: [a.id, b.id, c.id], remove: [] }, "u");
+      await store.applyLinks(first, t2, { add: [b.id], remove: [] }, "u");
+      await store.applyLinks(second, other, { add: [a.id], remove: [] }, "u");
+      expect((await store.tagsForTargets(first, [])).size).toBe(0);
+      expect((await store.tagsForTargets(first, [t1, t1])).get(t1)?.length).toBe(3);
+      const map = await store.tagsForTargets(first, [t1, t2, t3, other]);
+      expect([...map.keys()].sort()).toEqual([t1, t2].sort());
+      expect(cores(map.get(t1) ?? [])).toEqual(cores([a, b, c]));
+      expect(cores(await store.tagsForTarget(first, t1))).toEqual(cores([a, b, c]));
+      expect(ids(map.get(t2) ?? [])).toEqual([b.id]);
+    });
+    it("counts include every tag with zero for every kind, count per kind, honour ids, and drop when a link is removed", async () => {
+      const { workspace, store, make } = await setup();
+      const [a, lonely] = [await make(store, "a"), await make(store, "lonely")];
+      const targets = [];
+      for (const type of harness.targetTypes) targets.push([type, await harness.addTarget(workspace, type)]);
+      for (const [type, id] of targets) await store.applyLinks(type, id, { add: [a.id], remove: [] }, "u");
+      const counts = await store.counts();
+      expect(Object.keys(counts.get(lonely.id) ?? {}).sort()).toEqual([...harness.targetTypes].sort());
+      expect(Object.values(counts.get(lonely.id) ?? {})).toEqual(harness.targetTypes.map(() => 0));
+      expect(Object.values(counts.get(a.id) ?? {})).toEqual(harness.targetTypes.map(() => 1));
+      expect([...(await store.counts([a.id])).keys()]).toEqual([a.id]);
+      expect((await store.counts([])).size).toBe(0);
+      await store.applyLinks(third, targets[2][1], { add: [], remove: [a.id] }, "u");
+      expect((await store.counts()).get(a.id)?.[third]).toBe(0);
+      for (let i = 0; i < 2; i++) await store.applyLinks(first, await harness.addTarget(workspace, first), { add: [a.id], remove: [] }, "u");
+      expect((await store.counts([a.id])).get(a.id)?.[first]).toBe(3);
+    });
+    const mid = harness.armBeforeLinkWrite ? it : it.skip ?? it;
+    mid("a tag deleted between the check and the write is tagGone and nothing is applied, additions and removals alike", async () => {
+      const { workspace, store, make } = await setup();
+      const [keep, doomed, old] = [await make(store, "keep"), await make(store, "doomed"), await make(store, "old")];
+      const target = await harness.addTarget(workspace, first);
+      await store.applyLinks(first, target, { add: [old.id], remove: [] }, "u");
+      harness.armBeforeLinkWrite?.(async () => {
+        await store.remove(doomed.id);
+      });
+      expect(await store.applyLinks(first, target, { add: [keep.id, doomed.id], remove: [old.id] }, "u")).toEqual({ kind: "tagGone" });
+      expect(ids(await store.tagsForTarget(first, target))).toEqual([old.id]);
+    });
+    mid("a target deleted between the check and the write is targetGone", async () => {
+      const { workspace, store, make } = await setup();
+      const a = await make(store, "a");
+      const target = await harness.addTarget(workspace, first);
+      harness.armBeforeLinkWrite?.(async () => {
+        await harness.removeTarget(workspace, first, target);
+      });
+      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);
+    });
+  });
+}
+
+// src/tags/server/contract-basics.ts
+function defineTagStoreBasicsContract(api, harness) {
+  const kit = makeKit(api, harness);
+  defineTagStoreTagsContract(kit);
+  defineTagStoreLinksContract(kit);
+  defineTagStoreScopingContract(kit);
+}
+
+// src/tags/server/contract-concurrency.ts
+var BIG = { maxTags: 1e3 };
+var PIN2 = { maxPinned: 1e3 };
+var key2 = (name) => name.toLowerCase();
+function count(results, kind) {
+  return results.filter((r) => r.kind === kind).length;
+}
+function many(n, make) {
+  return Promise.all(Array.from({ length: n }, (_, i) => make(i)));
+}
+function defineTagStoreConcurrencyContract(api, harness) {
+  const { describe, it, expect } = api;
+  const [first] = harness.targetTypes;
+  async function setup() {
+    const workspace = await harness.newWorkspace();
+    const store = harness.storeFor(workspace);
+    const make = async (s, name) => {
+      const result = await s.create({ name, nameKey: key2(name), color: "neutral" }, BIG);
+      if (result.kind !== "created") throw new Error(`setup: could not create ${name}: ${result.kind}`);
+      return result.tag;
+    };
+    return { workspace, store, make };
+  }
+  describe("TagStore contract: simultaneous callers", () => {
+    it("ten creates with different names at a limit of 3 give exactly 3 created and 7 limit", async () => {
+      const { store } = await setup();
+      const results = await many(10, (i) => store.create({ name: `t${i}`, nameKey: `t${i}`, color: "neutral" }, { maxTags: 3 }));
+      expect([count(results, "created"), count(results, "limit")]).toEqual([3, 7]);
+      expect((await store.list()).length).toBe(3);
+    });
+    it("ten creates of the same name give exactly one created and nine duplicates", async () => {
+      const { store } = await setup();
+      const results = await many(10, () => store.create({ name: "Same", nameKey: "same", color: "neutral" }, BIG));
+      expect([count(results, "created"), count(results, "duplicate")]).toEqual([1, 9]);
+      expect((await store.list()).length).toBe(1);
+    });
+    it("ten pins at a limit of 3 give exactly 3 updated and 7 pinLimit", async () => {
+      const { store, make } = await setup();
+      const tags = [];
+      for (let i = 0; i < 10; i++) tags.push(await make(store, `p${i}`));
+      const results = await Promise.all(tags.map((tag) => store.update(tag.id, { pinned: true }, { maxPinned: 3 })));
+      expect([count(results, "updated"), count(results, "pinLimit")]).toEqual([3, 7]);
+      expect((await store.listPinned(100)).length).toBe(3);
+    });
+    it("two renames onto the same key give one updated and one duplicate", async () => {
+      const { store, make } = await setup();
+      const [a, b] = [await make(store, "a"), await make(store, "b")];
+      const results = await Promise.all([a, b].map((tag) => store.update(tag.id, { rename: { name: "Target", nameKey: "target" } }, PIN2)));
+      expect([count(results, "updated"), count(results, "duplicate")]).toEqual([1, 1]);
+    });
+    it("a create and a rename onto the same key at once give exactly one winner", async () => {
+      const { store, make } = await setup();
+      const b = await make(store, "b");
+      const [created, renamed] = await Promise.all([
+        store.create({ name: "x", nameKey: "x", color: "neutral" }, BIG),
+        store.update(b.id, { rename: { name: "x", nameKey: "x" } }, PIN2)
+      ]);
+      expect([created.kind === "created", renamed.kind === "updated"].filter(Boolean).length).toBe(1);
+      expect((await store.list()).filter((tag) => tag.nameKey === "x").length).toBe(1);
+    });
+    it("two updates of one tag at once give a consistent before and after chain", async () => {
+      const { store, make } = await setup();
+      const tag = await make(store, "one");
+      const [red, blue] = await Promise.all([store.update(tag.id, { color: "red" }, PIN2), store.update(tag.id, { color: "blue" }, PIN2)]);
+      if (red.kind !== "updated" || blue.kind !== "updated") throw new Error("both updates should succeed");
+      const chain = [red, blue].map((r) => [r.before.color, r.after.color]).sort();
+      const redFirst = [["neutral", "red"], ["red", "blue"]].sort();
+      const blueFirst = [["blue", "red"], ["neutral", "blue"]].sort();
+      expect([JSON.stringify(redFirst), JSON.stringify(blueFirst)].includes(JSON.stringify(chain))).toBe(true);
+    });
+    it("saving tags onto a target that is deleted at the same moment never leaves a link behind", async () => {
+      const { workspace, store, make } = await setup();
+      const tag = await make(store, "a");
+      for (let delay = 0; delay < 12; delay++) {
+        const target = await harness.addTarget(workspace, first);
+        const apply = store.applyLinks(first, target, { add: [tag.id], remove: [] }, "u");
+        const remove = (async () => {
+          for (let i = 0; i < delay; i++) await Promise.resolve();
+          await harness.removeTarget(workspace, first, target);
+        })();
+        await Promise.all([apply, remove]);
+        expect(await store.targetExists(first, target)).toBe(false);
+      }
+      expect((await store.counts([tag.id])).get(tag.id)?.[first]).toBe(0);
+    });
+    it("ten removes of one tag give exactly one removed and nine notFound", async () => {
+      const { store, make } = await setup();
+      const tag = await make(store, "doomed");
+      const results = await many(10, () => store.remove(tag.id));
+      expect([count(results, "removed"), count(results, "notFound")]).toEqual([1, 9]);
+    });
+    it("two identical saves at once report the added tag exactly once in total", async () => {
+      const { workspace, store, make } = await setup();
+      const tag = await make(store, "a");
+      const target = await harness.addTarget(workspace, first);
+      const results = await many(2, () => store.applyLinks(first, target, { add: [tag.id], remove: [] }, "u"));
+      const reported = results.flatMap((r) => r.kind === "applied" ? r.added : []);
+      expect(reported).toEqual([tag.id]);
+      expect((await store.tagsForTarget(first, target)).length).toBe(1);
+    });
+    it("ten saves adding ten different tags all land, and two saves removing the same tag report the removal once", async () => {
+      const { workspace, store, make } = await setup();
+      const tags = [];
+      for (let i = 0; i < 10; i++) tags.push(await make(store, `l${i}`));
+      const target = await harness.addTarget(workspace, first);
+      const adds = await Promise.all(tags.map((tag) => store.applyLinks(first, target, { add: [tag.id], remove: [] }, "u")));
+      expect(count(adds, "applied")).toBe(10);
+      expect((await store.tagsForTarget(first, target)).length).toBe(10);
+      const removals = await many(2, () => store.applyLinks(first, target, { add: [], remove: [tags[0].id] }, "u"));
+      expect(removals.flatMap((r) => r.kind === "applied" ? r.removed : [])).toEqual([tags[0].id]);
+    });
+    it("a tag removed while a save links it ends up gone from the target and the counts, whichever finishes first", async () => {
+      const { workspace, store, make } = await setup();
+      const tag = await make(store, "racy");
+      const target = await harness.addTarget(workspace, first);
+      const [applied, removed] = await Promise.all([store.applyLinks(first, target, { add: [tag.id], remove: [] }, "u"), store.remove(tag.id)]);
+      expect(removed.kind).toBe("removed");
+      expect(["applied", "tagGone"].includes(applied.kind)).toBe(true);
+      expect((await store.tagsForTarget(first, target)).length).toBe(0);
+      expect((await store.counts()).has(tag.id)).toBe(false);
+    });
+  });
+}
+
+// src/tags/server/contract.ts
+function defineTagStoreContract(api, harness) {
+  api.describe("TagStore contract", () => {
+    defineTagStoreBasicsContract(api, harness);
+    defineTagStoreConcurrencyContract(api, harness);
+    api.it("cleans up", async () => {
+      await harness.cleanup();
+    });
+  });
+}
+export {
+  createMemoryTagHarness,
+  createMemoryTagWorld,
+  createTagService,
+  defineTagStoreContract,
+  planTagChanges
+};