@lanes-sh/link 0.6.11 → 0.7.0

package/src/providers/entities/render.ts

@@ -0,0 +1,142 @@
+import type { Catalogue, CatalogueEntity } from './catalogue.ts';
+import { distinguish, type Candidate, type Criteria, type Matches } from './find.ts';
+
+/**
+ * How an answer reads, kept apart from what an answer is.
+ *
+ * `find.ts` decides which entities match; this decides what a person or a model
+ * sees, and the two are separated because the interesting failures are
+ * different in kind. A matching bug returns the wrong entity. A rendering bug
+ * returns the right entity in a form that invites the wrong next move — a list
+ * of two that reads like a recommendation of one, or an edge to something
+ * undeclared silently omitted so the graph looks complete.
+ *
+ * Every function here is pure over a catalogue already in memory.
+ */
+
+/** One entity in full, for the answer an agent is about to act on. */
+export function renderEntity(
+  entity: CatalogueEntity,
+  catalogue: Catalogue,
+  body: string,
+): string {
+  const head = entity.type ? `${entity.name} — ${entity.type} (${entity.id})` : `${entity.name} (${entity.id})`;
+  const lines: string[] = [head];
+
+  if (entity.aliases.length > 0) lines.push(`Also known as ${entity.aliases.join(', ')}.`);
+  if (entity.tags.length > 0) lines.push(`Tagged ${entity.tags.join(', ')}.`);
+
+  if (entity.attributes.length > 0) {
+    const kinds = [...new Set(entity.attributes.map((one) => one.kind))];
+    const ordered = kinds.flatMap((kind) => entity.attributes.filter((one) => one.kind === kind));
+    const width = Math.max(...ordered.map((one) => one.kind.length));
+
+    lines.push('');
+    // The kind is repeated on every line rather than written once as a heading,
+    // for identity's reason: a line lifted out of this block on its own still
+    // says what it is, and a model quoting one line is what happens next.
+    for (const one of ordered) {
+      const head = `  ${one.kind.padEnd(width)}  ${one.value}`;
+      lines.push(one.note ? `${head}  — ${one.note}` : head);
+    }
+
+    if (kinds.some((kind) => entity.attributes.filter((one) => one.kind === kind).length > 1)) {
+      lines.push('');
+      lines.push(
+        'Where a kind holds more than one, the first is the default and the notes say when to ' +
+          'prefer another. If none of them fits what you are doing, ask rather than combining them.',
+      );
+    }
+  }
+
+  const edges = renderEdges(entity, catalogue);
+  if (edges.length > 0) lines.push('', ...edges);
+
+  if (body.trim().length > 0) lines.push('', body.trim());
+
+  return lines.join('\n');
+}
+
+function renderEdges(entity: CatalogueEntity, catalogue: Catalogue): string[] {
+  const lines: string[] = [];
+
+  for (const relation of entity.relations) {
+    lines.push(`  ${relation.predicate} → ${nameOf(catalogue, relation.entity)}${note(relation.note)}`);
+  }
+
+  for (const backlink of catalogue.backlinks.get(entity.id) ?? []) {
+    lines.push(`  ← ${backlink.predicate} ${nameOf(catalogue, backlink.from)}${note(backlink.note)}`);
+  }
+
+  return lines;
+}
+
+/**
+ * A declared entity by name and id; an undeclared one by id, said so.
+ *
+ * Never an error and never a dropped line: an edge to something not written
+ * down yet is a fact the owner recorded, and hiding it would make the graph
+ * quietly wrong rather than visibly incomplete.
+ */
+function nameOf(catalogue: Catalogue, id: string): string {
+  const entity = catalogue.byId.get(id);
+  return entity === undefined ? `${id} (not a declared entity)` : `${entity.name} (${id})`;
+}
+
+function note(text: string | undefined): string {
+  return text === undefined ? '' : ` — ${text}`;
+}
+
+/** Several candidates: the count first, then only what tells them apart. */
+export function renderCandidates(
+  matches: Matches,
+  criteria: Criteria,
+  connection: string,
+): string {
+  const { candidates, total } = matches;
+  const differing = distinguish(candidates);
+  const idWidth = Math.max(...candidates.map((one) => one.entity.id.length));
+  const nameWidth = Math.max(...candidates.map((one) => one.entity.name.length));
+
+  const rows = candidates.map((candidate, index) => {
+    const facets = differing[index] ?? [];
+    const head = `  ${candidate.entity.id.padEnd(idWidth)}  ${candidate.entity.name.padEnd(nameWidth)}  ${candidate.matched}`;
+    return facets.length > 0 ? `${head}  ·  ${facets.join('  ·  ')}` : head;
+  });
+
+  const nothing = differing.every((one) => one.length === 0);
+
+  return [
+    // The count leads, before any candidate: a client that truncates the
+    // response must still have seen that there was more than one.
+    `${total} entities match ${describe(criteria)} on \`${connection}\`.` +
+      (total > candidates.length ? ` The first ${candidates.length} are below; raise \`limit\` for more.` : ''),
+    '',
+    ...rows,
+    '',
+    nothing
+      ? 'Nothing here tells these apart beyond their ids — which usually means the owner has a ' +
+        'duplicate to merge. Ask which is meant; do not pick one.'
+      : 'If the context does not make it clear which is meant, ask before acting. Nothing here ' +
+        'chooses between them, and the order is not a ranking.',
+  ].join('\n');
+}
+
+/** What was asked for, in the words the caller used. */
+export function describe(criteria: Criteria): string {
+  const parts: string[] = [];
+
+  if (criteria.query !== undefined) parts.push(`"${criteria.query}"`);
+  if (criteria.type !== undefined) parts.push(`type ${criteria.type}`);
+  if (criteria.tag !== undefined) parts.push(`tag ${criteria.tag}`);
+
+  for (const one of criteria.attr ?? []) {
+    parts.push(one.value === undefined ? `with a ${one.kind}` : `${one.kind} ${one.value}`);
+  }
+  for (const one of criteria.related ?? []) {
+    const arrow = (one.direction ?? 'out') === 'in' ? '←' : '→';
+    parts.push(`${one.predicate ?? 'related'} ${arrow} ${one.entity}`);
+  }
+
+  return parts.length === 0 ? 'no criteria' : parts.join(', ');
+}

package/src/providers/entities/store.ts

@@ -0,0 +1,276 @@
+import type { BlobStore } from '#connectivity';
+import {
+  splitOptionalFrontmatter,
+  stringList,
+  withFrontmatter,
+} from '#providers/shared/frontmatter.ts';
+import { slugify as slugifyText } from '#providers/shared/slug.ts';
+
+/**
+ * How an entity is stored, and the only place that knows.
+ *
+ * **One entity is one Markdown file**, exactly as a memory entry and a task
+ * are, and for the same reason (ADR-014): `lanes link entities` and a text
+ * editor reach the same bytes, and there is no row anywhere that can disagree
+ * with the file it describes. The document is frontmatter — type, name,
+ * aliases, tags, attributes, relations, timestamp — above a body that is the
+ * owner's notes on this person or thing.
+ *
+ * The `_index.json` beside these files is a *derived* artefact and is not a
+ * counter-example: it carries a fingerprint of the files it was built from and
+ * is rebuilt from them whenever that fingerprint disagrees. See `catalogue.ts`.
+ *
+ * **`attributes` is a list, not a map**, and the argument is identity's,
+ * verbatim (`#profile/identity.ts`): a map cannot say *when* to use which, and
+ * a map silently forbids two email addresses — the case that matters most.
+ * Order is preference order, so the first of a kind is the default.
+ *
+ * **`relations` is one-sided.** An edge is written into the entity that
+ * declares it and nowhere else; the reverse direction is derived when the
+ * catalogue is built. Writing both sides would be two files for one fact, and
+ * nothing in this codebase locks — an interrupted write would leave a half-edge
+ * that nothing detects.
+ *
+ * The store arrives scoped to `entities/<connection>` by core, so nothing here
+ * prefixes a key or thinks about isolation.
+ */
+
+/** One addressable fact about an entity: an address, a handle, a number. */
+export interface Attribute {
+  readonly kind: string;
+  readonly value: string;
+  /** When this one applies, in the owner's words. See `identityEntrySchema`. */
+  readonly note?: string;
+}
+
+/** A typed edge to another entity, as written on the entity that declares it. */
+export interface Relation {
+  readonly predicate: string;
+  /** An entity id. Not required to exist — see `parseEntity`. */
+  readonly entity: string;
+  readonly note?: string;
+}
+
+export interface Entity {
+  readonly id: string;
+  /** `person`, `company`, `project` — or anything else. Never a closed list. */
+  readonly type: string;
+  /** Falls back to the id, as a memory entry's title does. */
+  readonly name: string;
+  readonly aliases: readonly string[];
+  readonly tags: readonly string[];
+  /** Preference order: the first of a kind is the default. */
+  readonly attributes: readonly Attribute[];
+  readonly relations: readonly Relation[];
+  readonly updatedAt: string;
+  readonly body: string;
+  readonly bytes: number;
+}
+
+const ENTITY_ID = /^[a-z0-9][a-z0-9_-]*$/;
+
+/**
+ * What a `kind` or a `predicate` may be, enforced on write only.
+ *
+ * The same shape `identityEntrySchema.kind` holds, so an agent that has read
+ * `identity_list` recognises an entity's attributes without learning a second
+ * format. Free-form within that shape: `signal` and `bluesky` must not need a
+ * release, which is why this is a character class and not an enum.
+ */
+const IDENTIFIER = /^[a-z][a-z0-9_]*$/;
+
+export function entityKey(id: string): string {
+  return `${id}.md`;
+}
+
+/**
+ * The id a key holds, or null for a key that is not an entity.
+ *
+ * This one predicate is what keeps `_index.json` out of the entity listing, out
+ * of the fingerprint, out of the resource listing and out of the CLI listing —
+ * four places, no special case in any of them.
+ */
+export function idFromKey(key: string): string | null {
+  if (!key.endsWith('.md')) return null;
+  const id = key.slice(0, -'.md'.length);
+  return ENTITY_ID.test(id) ? id : null;
+}
+
+export function assertEntityId(id: string): void {
+  if (!ENTITY_ID.test(id)) {
+    throw new Error(
+      `Entity id ${JSON.stringify(id)} must be lowercase letters, digits, "_" or "-".`,
+    );
+  }
+}
+
+export function assertKind(kind: string, label: 'kind' | 'predicate'): void {
+  if (!IDENTIFIER.test(kind)) {
+    throw new Error(
+      `Attribute ${label} ${JSON.stringify(kind)} must be lowercase letters, digits and ` +
+        `underscores, starting with a letter — "email", "github", "works_at".`,
+    );
+  }
+}
+
+/** A stable id from a name, so writing does not demand one be invented. */
+export function slugify(name: string): string {
+  return slugifyText(name, 'entity');
+}
+
+/**
+ * Parse one stored entity, tolerating anything.
+ *
+ * Every field falls back and no fallback is an error, because this reads a
+ * directory the owner is invited to edit. A plain Markdown file dropped in
+ * there is an entity named after its filename, which is a better answer than an
+ * exception that hides every other entity behind it.
+ *
+ * A malformed row inside `attributes` or `relations` is **skipped rather than
+ * thrown**, and that is the same argument one level down: one bad list item
+ * must not cost the whole directory. The visible failure is an attribute that
+ * did not appear, which is diagnosable by opening the file; the alternative is
+ * a listing that will not render and does not say which file broke it.
+ */
+export function parseEntity(id: string, text: string, fallbackUpdatedAt: string): Entity {
+  const { frontmatter, body } = splitOptionalFrontmatter(text);
+
+  const type = frontmatter['type'];
+  const name = frontmatter['name'];
+  const updatedAt = frontmatter['updated_at'];
+
+  return {
+    id,
+    type: typeof type === 'string' && type.trim().length > 0 ? type.trim() : '',
+    name: typeof name === 'string' && name.trim().length > 0 ? name.trim() : id,
+    aliases: stringList(frontmatter['aliases']),
+    tags: stringList(frontmatter['tags']),
+    attributes: parseAttributes(frontmatter['attributes']),
+    relations: parseRelations(frontmatter['relations']),
+    updatedAt: typeof updatedAt === 'string' ? updatedAt : fallbackUpdatedAt,
+    body: body.trimEnd(),
+    bytes: new TextEncoder().encode(text).byteLength,
+  };
+}
+
+function parseAttributes(raw: unknown): Attribute[] {
+  if (!Array.isArray(raw)) return [];
+
+  return raw.flatMap((item) => {
+    const kind = field(item, 'kind');
+    const value = field(item, 'value');
+    if (kind === null || value === null) return [];
+
+    const note = field(item, 'note');
+    return [{ kind, value, ...(note === null ? {} : { note }) }];
+  });
+}
+
+function parseRelations(raw: unknown): Relation[] {
+  if (!Array.isArray(raw)) return [];
+
+  return raw.flatMap((item) => {
+    const predicate = field(item, 'predicate');
+    const entity = field(item, 'entity');
+    if (predicate === null || entity === null) return [];
+
+    const note = field(item, 'note');
+    return [{ predicate, entity, ...(note === null ? {} : { note }) }];
+  });
+}
+
+/** One non-empty string field off a frontmatter row, or null. */
+function field(item: unknown, key: string): string | null {
+  if (item === null || typeof item !== 'object' || Array.isArray(item)) return null;
+  const raw = (item as Record<string, unknown>)[key];
+  if (typeof raw !== 'string') return null;
+  const trimmed = raw.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+export function serialiseEntity(entity: Omit<Entity, 'id' | 'bytes'>): string {
+  return withFrontmatter(
+    {
+      ...(entity.type ? { type: entity.type } : {}),
+      name: entity.name,
+      ...(entity.aliases.length > 0 ? { aliases: [...entity.aliases] } : {}),
+      ...(entity.tags.length > 0 ? { tags: [...entity.tags] } : {}),
+      ...(entity.attributes.length > 0
+        ? { attributes: entity.attributes.map((one) => ({ ...one })) }
+        : {}),
+      ...(entity.relations.length > 0
+        ? { relations: entity.relations.map((one) => ({ ...one })) }
+        : {}),
+      updated_at: entity.updatedAt,
+    },
+    `${entity.body.trimEnd()}\n`,
+  );
+}
+
+export async function readEntity(storage: BlobStore, id: string): Promise<Entity | null> {
+  const bytes = await storage.get(entityKey(id));
+  if (bytes === null) return null;
+
+  return parseEntity(id, new TextDecoder().decode(bytes), new Date(0).toISOString());
+}
+
+/** Write one entity, returning the byte length the catalogue's fingerprint needs. */
+export async function writeEntity(storage: BlobStore, entity: Entity): Promise<number> {
+  const { id: _id, bytes: _bytes, ...rest } = entity;
+  const encoded = new TextEncoder().encode(serialiseEntity(rest));
+
+  await storage.put(entityKey(entity.id), encoded, { contentType: 'text/markdown' });
+  return encoded.byteLength;
+}
+
+/**
+ * How many entities are read at once.
+ *
+ * The bound memory and tasks use, for the reason memory gives: against a bucket
+ * each read is an HTTPS request, and firing a thousand at once trades a slow
+ * rebuild for a rate-limited one.
+ */
+const READ_CONCURRENCY = 16;
+
+/**
+ * Every entity, newest first.
+ *
+ * **This reads every file**, and is the expensive path this provider exists to
+ * avoid taking twice: it runs when the catalogue's index is absent, stale or
+ * unreadable, and never on a read that found a valid one. `catalogue.ts` has
+ * the arithmetic for what that costs at a thousand entities on a bucket.
+ */
+export async function allEntities(storage: BlobStore): Promise<Entity[]> {
+  const blobs = (await storage.list()).flatMap((blob) => {
+    const id = idFromKey(blob.key);
+    return id === null ? [] : [{ blob, id }];
+  });
+
+  const entities: Entity[] = [];
+
+  for (let start = 0; start < blobs.length; start += READ_CONCURRENCY) {
+    const batch = await Promise.all(
+      blobs.slice(start, start + READ_CONCURRENCY).map(async ({ blob, id }) => {
+        const bytes = await storage.get(blob.key);
+        return bytes === null
+          ? null
+          : parseEntity(id, new TextDecoder().decode(bytes), blob.modifiedAt.toISOString());
+      }),
+    );
+    for (const entity of batch) if (entity) entities.push(entity);
+  }
+
+  return entities.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+}
+
+/** The pieces `lanes link entities` needs to reach the same bytes the provider does. */
+export const entityStorage = {
+  key: entityKey,
+  idFromKey,
+  parse: parseEntity,
+  serialise: serialiseEntity,
+  read: readEntity,
+  write: writeEntity,
+  all: allEntities,
+  slugify,
+};

package/src/providers/entities/writes.ts

@@ -0,0 +1,279 @@
+import { z } from 'zod';
+import { keepKeys, type BlobStore, type Capability } from '#connectivity';
+import { fingerprintAfter, openCatalogue, writeCatalogue, type Catalogue } from './catalogue.ts';
+import {
+  assertEntityId,
+  assertKind,
+  entityKey,
+  readEntity,
+  slugify,
+  writeEntity,
+  type Attribute,
+  type Entity,
+  type Relation,
+} from './store.ts';
+
+/**
+ * The three capabilities that change something, and the index maintenance they
+ * share.
+ *
+ * Their own file because the file boundary is the *bundle* boundary, and the
+ * bundle boundary is the security argument: `read` is default and this is not
+ * (ADR-012 §2). A reader deciding whether an agent should hold `entities.write`
+ * has one file to read, and a grep for what an agent with only the default
+ * bundle can do does not have to distinguish handlers inside one long list.
+ *
+ * All three go through `persist`, so there is one implementation of "write an
+ * entity and leave the index describing what is now there".
+ */
+
+export const writeCapabilities: readonly Capability[] = [
+    {
+      kind: 'tool',
+      name: 'write',
+      title: 'Declare or update an entity',
+      description:
+        'Create an entity, or update one that exists. A field you do not supply is left as it is — ' +
+        'send attributes: [] to clear them deliberately. Attribute order is preference order: the ' +
+        'first of a kind is the default. Separate from reading, because what is written here is used ' +
+        'to address messages in every later session.',
+      inputSchema: z.object({
+        name: z.string().min(1).describe('How the owner refers to this entity'),
+        id: z
+          .string()
+          .optional()
+          .describe('Entity id. Derived from the name when omitted; naming an existing one updates it.'),
+        type: z.string().optional().describe('person, company, project — or anything else'),
+        aliases: z.array(z.string()).optional().describe('Other names this is known by'),
+        tags: z.array(z.string()).optional().describe('Labels for filtering'),
+        attributes: z
+          .array(
+            z.object({
+              kind: z.string().min(1).describe('email, github, phone — lowercase, no spaces'),
+              value: z.string().min(1),
+              note: z.string().optional().describe('When to use this one rather than another'),
+            }),
+          )
+          .optional()
+          .describe('Addresses and handles, most-preferred first'),
+        relations: z
+          .array(
+            z.object({
+              predicate: z.string().min(1).describe('works_at, owns, part_of'),
+              entity: z.string().min(1).describe('The entity id on the other end'),
+              note: z.string().optional(),
+            }),
+          )
+          .optional()
+          .describe('Edges from this entity. Replaces the existing set; entities.link appends one.'),
+        notes: z.string().optional().describe('Free prose about this entity, as Markdown'),
+      }),
+      // The id, type and name are addresses — and `id` is `slugify(name)`, so
+      // keeping one while withholding the other would be theatre. Every value
+      // is withheld; `annotate` records the shape instead.
+      redact: keepKeys('id', 'type', 'name', 'tags'),
+      async handler(
+        { name, id: given, type, aliases, tags, attributes, relations, notes },
+        context,
+      ) {
+        const id = given ?? slugify(name);
+        assertEntityId(id);
+        for (const one of attributes ?? []) assertKind(one.kind, 'kind');
+        for (const one of relations ?? []) assertKind(one.predicate, 'predicate');
+
+        const existing = await readEntity(context.storage, id);
+        // A field that was not supplied keeps what is on disk. Spelled out
+        // rather than merged generically, because the alternative — a model
+        // resending an entity minus an attribute it forgot — is a lost update
+        // with a language model holding the pen.
+        const next: Entity = {
+          id,
+          name,
+          type: type ?? existing?.type ?? '',
+          aliases: aliases ?? existing?.aliases ?? [],
+          tags: tags ?? existing?.tags ?? [],
+          attributes: (attributes ?? existing?.attributes ?? []) as readonly Attribute[],
+          relations: (relations ?? existing?.relations ?? []) as readonly Relation[],
+          updatedAt: new Date().toISOString(),
+          body: notes ?? existing?.body ?? '',
+          bytes: 0,
+        };
+
+        await persistEntity(context.storage, next);
+
+        // `redact` maps keys to keep-or-typemark and cannot express "keep the
+        // shape of this list, drop its values" — left to it alone, the log
+        // would record `<array:3>` and say nothing about what changed. The
+        // kinds are the reviewable fact; the addresses stay out of an
+        // append-only hash-chained log. ADR-017.
+        context.audit.annotate({
+          entity: id,
+          created: existing === null,
+          attributes: next.attributes.length,
+          kinds: [...new Set(next.attributes.map((one) => one.kind))],
+          relations: next.relations.length,
+        });
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `${existing === null ? 'Declared' : 'Updated'} "${id}" on ${context.connection.key}.`,
+            },
+            { type: 'resource_link', uri: `entities://entity/${id}`, name },
+          ],
+        };
+      },
+    },
+
+    {
+      kind: 'tool',
+      name: 'link',
+      title: 'Relate one entity to another',
+      description:
+        'Add one edge to an entity, leaving everything else on it alone. The edge is written only on ' +
+        'the entity it comes from; the reverse direction is derived, so do not also write it the other ' +
+        'way. The other end need not exist yet.',
+      inputSchema: z.object({
+        from: z.string().min(1).describe('Entity id the edge comes from'),
+        predicate: z.string().min(1).describe('works_at, owns, part_of'),
+        to: z.string().min(1).describe('Entity id the edge points at'),
+        note: z.string().optional(),
+      }),
+      redact: keepKeys('from', 'predicate', 'to'),
+      async handler({ from, predicate, to, note }, context) {
+        assertKind(predicate, 'predicate');
+
+        const entity = await readEntity(context.storage, from);
+        if (entity === null) {
+          return {
+            content: [{ type: 'text', text: `No entity "${from}" on ${context.connection.key}.` }],
+            isError: true,
+          };
+        }
+
+        const already = entity.relations.some(
+          (one) => one.predicate === predicate && one.entity === to,
+        );
+        if (already) {
+          return {
+            content: [{ type: 'text', text: `"${from}" already ${predicate} "${to}".` }],
+          };
+        }
+
+        const relation: Relation = { predicate, entity: to, ...(note === undefined ? {} : { note }) };
+        const next: Entity = {
+          ...entity,
+          relations: [...entity.relations, relation],
+          updatedAt: new Date().toISOString(),
+        };
+
+        const catalogue = await persistEntity(context.storage, next);
+
+        // Recorded because a dangling edge is legal and useful, and is also how
+        // a typo in an id looks. The log is where that becomes visible.
+        const dangling = !catalogue.byId.has(to);
+        context.audit.annotate({ dangling });
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text:
+                `"${from}" ${predicate} "${to}".` +
+                (dangling ? ` "${to}" is not declared yet — the edge is kept as written.` : ''),
+            },
+          ],
+        };
+      },
+    },
+
+    {
+      kind: 'tool',
+      name: 'forget',
+      title: 'Remove an entity',
+      description:
+        'Delete an entity. Edges pointing at it from other entities are left alone and are reported, ' +
+        'so nothing else is rewritten behind your back — clean them up deliberately if you mean to.',
+      inputSchema: z.object({ id: z.string().min(1).describe('Entity id') }),
+      redact: keepKeys('id'),
+      async handler({ id }, context) {
+        const catalogue = await openCatalogue(context.storage);
+        const existed = catalogue.byId.has(id);
+        const referencedBy = (catalogue.backlinks.get(id) ?? []).map((one) => one.from);
+
+        context.audit.annotate({ existed, referenced_by: referencedBy.length });
+
+        if (!existed) {
+          return {
+            content: [{ type: 'text', text: `No entity "${id}" on ${context.connection.key}.` }],
+            isError: true,
+          };
+        }
+
+        await forgetEntity(context.storage, catalogue, id, new Date().toISOString());
+
+        // Deliberately not a cascade: a delete that rewrote five other people's
+        // files could not be reviewed as one change. Saying who still points
+        // here is what keeps the breakage from being silent.
+        return {
+          content: [
+            {
+              type: 'text',
+              text:
+                `Removed "${id}" from ${context.connection.key}.` +
+                (referencedBy.length > 0
+                  ? ` Still referenced by ${referencedBy.join(', ')} — those edges now dangle.`
+                  : ''),
+            },
+          ],
+        };
+      },
+    },
+];
+
+/**
+ * Write one entity and the index that describes the store afterwards.
+ *
+ * The fingerprint is computed from the listing taken *before* the put plus the
+ * byte length being written, so there is no second `list()` and no read-back —
+ * see `catalogue.ts` for why `key:size` is what makes that possible.
+ *
+ * Exported because `lanes link entities write` needs exactly this and an
+ * earlier version of it had its own: a rebuild-then-write that read every file
+ * on every call, which is one extra pass by hand and a quadratic bulk load from
+ * a script. Two implementations of index maintenance is the same drift the
+ * shared `entityStorage` exists to prevent, one layer up.
+ */
+export async function persistEntity(storage: BlobStore, entity: Entity): Promise<Catalogue> {
+  const catalogue = await openCatalogue(storage);
+  const bytes = await writeEntity(storage, entity);
+
+  const { body: _body, bytes: _bytes, ...row } = entity;
+  const rows = [...catalogue.entities.filter((one) => one.id !== entity.id), row];
+
+  await writeCatalogue(
+    storage,
+    rows,
+    fingerprintAfter(catalogue.listing, { key: entityKey(entity.id), size: bytes }),
+    entity.updatedAt,
+  );
+
+  return catalogue;
+}
+
+/** Remove one entity and leave the index describing what is left. */
+export async function forgetEntity(
+  storage: BlobStore,
+  catalogue: Catalogue,
+  id: string,
+  now: string,
+): Promise<void> {
+  await storage.delete(entityKey(id));
+  await writeCatalogue(
+    storage,
+    catalogue.entities.filter((one) => one.id !== id),
+    fingerprintAfter(catalogue.listing, { key: entityKey(id), deleted: true }),
+    now,
+  );
+}