@lanes-sh/link 0.6.11 → 0.7.0

package/src/providers/entities/find.ts

@@ -0,0 +1,279 @@
+import type { Backlink, Catalogue, CatalogueEntity } from './catalogue.ts';
+
+/**
+ * What a name means, and what happens when it means more than one thing.
+ *
+ * This is the whole reason the component exists, so the rules are stated here
+ * rather than distributed through the handlers:
+ *
+ * **Several matches is a normal answer, not an error.** An assistant handed two
+ * people called Jan asks which one; it does not fail. So `find` returns every
+ * candidate and sets no error, and what it refuses to do is *choose*.
+ *
+ * **Ordering is not selection.** Candidates are ranked so the list is legible —
+ * an exact id above a substring — and nothing in the response presents the
+ * first as the answer. There is deliberately no scoring inside a rank: no
+ * most-recently-updated tiebreak that would quietly promote one of two exact
+ * alias matches. `updatedAt` orders *within* a rank and never across. This is
+ * the one thing a later contributor will be tempted to improve into a silent
+ * pick.
+ *
+ * **Exact suppresses approximate.** If anything matched exactly, prefix and
+ * substring candidates are dropped. That is a boundary between *kinds* of
+ * match, not a precedence among equals: two exact alias matches both survive,
+ * and both are returned.
+ *
+ * **A tag is never matched by `query`.** A tag is a category, not an identity,
+ * so `find("client")` must not surface one of eleven clients as if it were a
+ * name. Filter by `tag` to mean the category.
+ *
+ * Everything here is pure and synchronous over a catalogue already in memory,
+ * which is what lets the interesting cases — ambiguity, dangling edges,
+ * preference order — be tested with literal arrays and no I/O.
+ */
+
+export type Direction = 'out' | 'in' | 'any';
+
+export interface AttributeCriterion {
+  readonly kind: string;
+  /** Omitted means "has this kind at all", which is a useful browse. */
+  readonly value?: string | undefined;
+}
+
+export interface RelationCriterion {
+  /** Omitted means any predicate. */
+  readonly predicate?: string | undefined;
+  readonly entity: string;
+  /**
+   * `out` — the candidate declares an edge *to* `entity`. The default, because
+   * it is what the natural phrasing means: "who works at Acme" wants Acme's
+   * employees and not Acme.
+   */
+  readonly direction?: Direction | undefined;
+}
+
+/**
+ * Every field optional, and explicitly `| undefined`.
+ *
+ * The handler destructures its validated input and hands the pieces straight
+ * here, so a criterion the caller omitted arrives as `undefined` rather than
+ * being absent — writing that out is what lets the surface stay a one-line
+ * pass-through instead of six conditional spreads.
+ */
+export interface Criteria {
+  readonly query?: string | undefined;
+  readonly type?: string | undefined;
+  readonly tag?: string | undefined;
+  readonly attr?: readonly AttributeCriterion[] | undefined;
+  readonly related?: readonly RelationCriterion[] | undefined;
+  readonly limit?: number | undefined;
+}
+
+export const DEFAULT_LIMIT = 10;
+export const MAX_LIMIT = 50;
+
+/**
+ * How a candidate matched, in the order a list shows them.
+ *
+ * Ranks 1-4 are what a lookup means. 5 and 6 exist so a browse is useful, and
+ * are dropped entirely whenever anything above them matched.
+ */
+const RANKS = ['id', 'name', 'alias', 'attribute', 'prefix', 'substring'] as const;
+export type Rank = (typeof RANKS)[number];
+
+const APPROXIMATE: readonly Rank[] = ['prefix', 'substring'];
+
+export interface Candidate {
+  readonly entity: CatalogueEntity;
+  readonly rank: Rank;
+  /** The field that matched, as a person would say it: `alias "Jan"`, `email`. */
+  readonly matched: string;
+}
+
+export interface Matches {
+  readonly candidates: readonly Candidate[];
+  /** How many matched before `limit` cut the list. */
+  readonly total: number;
+  /** How many entities were considered, for the audit annotation. */
+  readonly scanned: number;
+}
+
+/**
+ * Normalised for comparison: trimmed, NFC, lowercased.
+ *
+ * NFC because a name typed with a combining accent in one place and precomposed
+ * in another is the same person, and this is the only comparison in the
+ * provider where that difference can decide an identity.
+ */
+function fold(text: string): string {
+  return text.trim().normalize('NFC').toLowerCase();
+}
+
+export function matchEntities(catalogue: Catalogue, criteria: Criteria): Matches {
+  const filtered = catalogue.entities.filter((entity) => passesFilters(catalogue, entity, criteria));
+
+  const query = criteria.query === undefined ? '' : fold(criteria.query);
+  const matched: Candidate[] = [];
+
+  for (const entity of filtered) {
+    if (query.length === 0) {
+      matched.push({ entity, rank: 'name', matched: 'listed' });
+      continue;
+    }
+    const candidate = rankOf(entity, query);
+    if (candidate !== null) matched.push(candidate);
+  }
+
+  const exact = matched.filter((one) => !APPROXIMATE.includes(one.rank));
+  const kept = exact.length > 0 ? exact : matched;
+
+  kept.sort(
+    (a, b) =>
+      RANKS.indexOf(a.rank) - RANKS.indexOf(b.rank) ||
+      b.entity.updatedAt.localeCompare(a.entity.updatedAt),
+  );
+
+  const limit = Math.min(Math.max(criteria.limit ?? DEFAULT_LIMIT, 1), MAX_LIMIT);
+
+  return { candidates: kept.slice(0, limit), total: kept.length, scanned: catalogue.entities.length };
+}
+
+/** All criteria present are AND-ed. None of them looks at `query`. */
+function passesFilters(
+  catalogue: Catalogue,
+  entity: CatalogueEntity,
+  criteria: Criteria,
+): boolean {
+  if (criteria.type !== undefined && fold(entity.type) !== fold(criteria.type)) return false;
+
+  if (criteria.tag !== undefined && !entity.tags.some((tag) => fold(tag) === fold(criteria.tag!))) {
+    return false;
+  }
+
+  for (const want of criteria.attr ?? []) {
+    const present = entity.attributes.some(
+      (attribute) =>
+        fold(attribute.kind) === fold(want.kind) &&
+        (want.value === undefined || fold(attribute.value) === fold(want.value)),
+    );
+    if (!present) return false;
+  }
+
+  for (const want of criteria.related ?? []) {
+    if (!relatedTo(catalogue, entity, want)) return false;
+  }
+
+  return true;
+}
+
+function relatedTo(
+  catalogue: Catalogue,
+  entity: CatalogueEntity,
+  want: RelationCriterion,
+): boolean {
+  const direction = want.direction ?? 'out';
+  const target = fold(want.entity);
+  const predicate = want.predicate === undefined ? null : fold(want.predicate);
+
+  const out = entity.relations.some(
+    (relation) =>
+      fold(relation.entity) === target &&
+      (predicate === null || fold(relation.predicate) === predicate),
+  );
+  if (direction === 'out') return out;
+
+  const into = (catalogue.backlinks.get(entity.id) ?? []).some(
+    (backlink) =>
+      fold(backlink.from) === target &&
+      (predicate === null || fold(backlink.predicate) === predicate),
+  );
+
+  return direction === 'in' ? into : out || into;
+}
+
+/** The strongest way this entity matches the query, or null. */
+function rankOf(entity: CatalogueEntity, query: string): Candidate | null {
+  if (fold(entity.id) === query) return { entity, rank: 'id', matched: 'id' };
+  if (fold(entity.name) === query) return { entity, rank: 'name', matched: 'name' };
+
+  const alias = entity.aliases.find((one) => fold(one) === query);
+  if (alias !== undefined) return { entity, rank: 'alias', matched: `alias "${alias}"` };
+
+  const attribute = entity.attributes.find((one) => fold(one.value) === query);
+  if (attribute !== undefined) {
+    return { entity, rank: 'attribute', matched: attribute.kind };
+  }
+
+  const prefixed = [entity.name, ...entity.aliases].find((one) => fold(one).startsWith(query));
+  if (prefixed !== undefined) return { entity, rank: 'prefix', matched: `starts with "${query}"` };
+
+  const haystack = [entity.name, ...entity.aliases, ...entity.attributes.map((one) => one.value)];
+  if (haystack.some((one) => fold(one).includes(query))) {
+    return { entity, rank: 'substring', matched: `contains "${query}"` };
+  }
+
+  return null;
+}
+
+/**
+ * The fields that actually differ across a set of candidates.
+ *
+ * This is what makes several matches a usable answer rather than a dump. Two
+ * people called Jan separated by their employer is a question the surrounding
+ * context usually settles; two rows of identical detail is not, and printing
+ * everything about both buries the one column that would have decided it.
+ *
+ * Fields shared by every candidate are omitted for that reason, not to save
+ * space: they cannot disambiguate, and they crowd out what can.
+ *
+ * Values *are* rendered, and that is a deliberate reversal of an earlier draft
+ * which withheld them. An address is usually the most distinguishing thing
+ * about a person, so withholding it leaves a row that says two people differ by
+ * their email without saying how — which is the ambiguity again, one level
+ * down. It discloses nothing either: `find` and `get` are both in the default
+ * read bundle, so anything that can see this list can already open either
+ * record. What it costs is verbosity, and only for fields that actually differ.
+ *
+ * The audit log is the separate question and is answered differently: the query
+ * is withheld there and only the ids that matched are recorded. A response goes
+ * to a caller that already has the read grant; the log outlives the call.
+ */
+export function distinguish(candidates: readonly Candidate[]): string[][] {
+  const facets = candidates.map(facetsOf);
+  const keys = [...new Set(facets.flatMap((one) => [...one.keys()]))];
+
+  const differing = keys.filter((key) => {
+    const values = facets.map((one) => one.get(key) ?? '');
+    return values.some((value) => value !== values[0]);
+  });
+
+  return facets.map((one) =>
+    differing.flatMap((key) => {
+      const value = one.get(key);
+      return value === undefined ? [] : [`${key} ${value}`];
+    }),
+  );
+}
+
+/** One candidate's comparable surface: type, tags, attribute kinds, edges. */
+function facetsOf(candidate: Candidate): Map<string, string> {
+  const facets = new Map<string, string>();
+  const { entity } = candidate;
+
+  if (entity.type) facets.set('type', entity.type);
+  if (entity.tags.length > 0) facets.set('tags', [...entity.tags].sort().join(', '));
+
+  for (const kind of new Set(entity.attributes.map((one) => one.kind))) {
+    const values = entity.attributes.filter((one) => one.kind === kind).map((one) => one.value);
+    facets.set(kind, values.join(', '));
+  }
+
+  for (const predicate of new Set(entity.relations.map((one) => one.predicate))) {
+    const targets = entity.relations
+      .filter((one) => one.predicate === predicate)
+      .map((one) => one.entity);
+    facets.set(`${predicate} →`, targets.join(', '));
+  }
+
+  return facets;
+}

package/src/providers/entities/provider.ts

@@ -0,0 +1,334 @@
+import { z } from 'zod';
+import {
+  defineLocalProvider,
+  keepKeys,
+  type BlobStore,
+  type ProviderDefinition,
+} from '#connectivity';
+import {
+  openCatalogue,
+  rebuildCatalogue,
+  type Catalogue,
+  type CatalogueEntity,
+} from './catalogue.ts';
+import { DEFAULT_LIMIT, MAX_LIMIT, matchEntities, type Criteria } from './find.ts';
+import { describe, renderCandidates, renderEntity } from './render.ts';
+import { readEntity, type Entity } from './store.ts';
+import { writeCapabilities } from './writes.ts';
+
+/**
+ * `entities` — who and what everyone else is.
+ *
+ * `identity` declares who the *owner* is, because an agent writing as them was
+ * otherwise inferring a name from whatever was in the conversation (ADR-042).
+ * The same failure happens one step outward and nothing catches it: asked to
+ * "email Jan about the invoice", an agent reaches for an address it saw in a
+ * thread. The information is knowable; there was nowhere to write it down.
+ *
+ * **`find` answers with everything that matches and never chooses.** One match
+ * is an answer; several is a question for the owner, and the response shows
+ * what *separates* the candidates so that question can usually be settled from
+ * context rather than asked. Several matches is a normal outcome and carries no
+ * error — an assistant handed two people called Jan asks which one, it does not
+ * fail. What is refused is silently picking one.
+ *
+ * **Reading and writing are separate capabilities**, following `memory` and
+ * ADR-012 §2. A writable store persists injections: an instruction written once
+ * is re-served to every later session, including to a different agent. That
+ * argument applies here with a twist worth naming — an entity is *acted on*, so
+ * a bad write is not only re-served, it is used to address a message. The write
+ * bundle is not default, and `deny` takes three rules to close
+ * (`entities.write`, `entities.link`, `entities.forget`), not one.
+ *
+ * Unlike `identity`, this **is** agent-writable, and the two are not
+ * inconsistent. ADR-050's test for a default grant is not "is it empty" but
+ * "can it be filled in from here": identity is configuration and changed in the
+ * CLI (ADR-007), so an agent able to edit it could edit the one fact that stops
+ * it signing as the wrong person. Everyone else's details are ordinary owner
+ * material, accumulated in conversation, on the same surface that reads them.
+ *
+ * Storage is `store.ts`, the derived index is `catalogue.ts`, matching is
+ * `find.ts` and wording is `render.ts`. This file is only the surface: schemas,
+ * bundles, redaction, and what reaches the audit log.
+ */
+
+const DESCRIPTION =
+  'The people, companies and projects the owner deals with, with their canonical addresses and ' +
+  'handles. Call entities.find before acting on a name: it returns every match and never chooses, ' +
+  'so more than one means ask rather than take the first.';
+
+export const entitiesProvider: ProviderDefinition = defineLocalProvider({
+  id: 'entities',
+  name: 'Entities',
+  version: '1.0.0',
+  description: DESCRIPTION,
+
+  configSchema: z.object({}),
+  connectionSchema: z.object({}),
+
+  bundles: [
+    {
+      name: 'read',
+      description: 'Look entities up and read them.',
+      oauth_scopes: [],
+      capabilities: ['entity', 'find', 'get'],
+      default: true,
+    },
+    {
+      // Not in the default bundle — see the provider docstring. Denying it
+      // takes all three names; there is no single rule that covers them.
+      name: 'write',
+      description: 'Declare, relate and remove entities.',
+      oauth_scopes: [],
+      capabilities: ['write', 'link', 'forget'],
+    },
+  ],
+
+  capabilities: [
+    /**
+     * Retrieval by address — a resource, not a tool (ADR-006).
+     *
+     * Not optional, and not decoration: `resourceLinkRouter` builds its set of
+     * routable origins from this provider's own `uriTemplate`s and returns the
+     * identity function when there are none. Without it every `resource_link`
+     * below would reach the client naming no profile and no connection, which
+     * no client can read.
+     */
+    {
+      kind: 'resource',
+      name: 'entity',
+      title: 'Entity',
+      description: 'One declared entity, addressed by its id.',
+      uriTemplate: 'entities://entity/{id}',
+      mimeType: 'text/markdown',
+      redact: keepKeys('uri'),
+
+      async list(context) {
+        const catalogue = await openCatalogue(context.storage);
+        return catalogue.entities.map((entity) => ({
+          uri: `entities://entity/${encodeURIComponent(entity.id)}`,
+          name: entity.name,
+        }));
+      },
+
+      async read(uri, params, context) {
+        const raw = params['id'];
+        if (!raw) throw new Error(`Malformed entities URI: ${uri}`);
+
+        const id = decodeURIComponent(raw);
+        const entity = await readEntity(context.storage, id);
+        if (entity === null) throw new Error(`No entity "${id}" on ${context.connection.key}`);
+
+        const catalogue = await openCatalogue(context.storage);
+        return { uri, mimeType: 'text/markdown', text: renderEntity(entity, catalogue, entity.body) };
+      },
+    },
+
+    {
+      kind: 'tool',
+      name: 'find',
+      title: 'Look up an entity',
+      description:
+        'Find entities by name, alias, address, type, tag, attribute or relationship. All criteria ' +
+        'given are combined. Returns every match: exactly one is an answer, several means ask which ' +
+        'is meant rather than taking the first, and the order is not a ranking. Call this before ' +
+        'using anyone’s address rather than recalling one.',
+      inputSchema: z.object({
+        query: z
+          .string()
+          .optional()
+          .describe('A name, alias, id or address. Matched exactly first, then by prefix and substring.'),
+        type: z.string().optional().describe('Restrict to one type, e.g. person, company, project'),
+        tag: z.string().optional().describe('Restrict to entities carrying this tag'),
+        attr: z
+          .array(
+            z.object({
+              kind: z.string().min(1).describe('Attribute kind, e.g. email, github'),
+              value: z.string().optional().describe('Omit to mean "has this kind at all"'),
+            }),
+          )
+          .optional()
+          .describe('Restrict to entities carrying these attributes'),
+        related: z
+          .array(
+            z.object({
+              predicate: z.string().optional().describe('Edge name, e.g. works_at. Omit for any.'),
+              entity: z.string().min(1).describe('The entity id on the other end'),
+              direction: z
+                .enum(['out', 'in', 'any'])
+                .optional()
+                .describe('out (default): this entity points at the named one'),
+            }),
+          )
+          .optional()
+          .describe('Restrict by relationship, one hop'),
+        limit: z
+          .number()
+          .int()
+          .min(1)
+          .max(MAX_LIMIT)
+          .optional()
+          .describe(`Maximum results (default ${DEFAULT_LIMIT})`),
+      }),
+      /**
+       * The query is withheld; the outcome is annotated instead.
+       *
+       * A lookup string here is frequently a third party's address, typed by
+       * someone who never wrote it down — the same class of thing
+       * `memory.search` withholds its query for. The ids that came back are the
+       * more useful record anyway: they are stable across spellings, and now
+       * that several matches is a normal outcome the log should show that two
+       * candidates were offered and which, so a later wrong message is
+       * traceable to the moment the choice was made.
+       */
+      redact: keepKeys('type', 'tag', 'limit'),
+      async handler({ query, type, tag, attr, related, limit }, context) {
+        const criteria: Criteria = { query, type, tag, attr, related, limit };
+
+        let catalogue = await openCatalogue(context.storage);
+        let matches = matchEntities(catalogue, criteria);
+
+        // Confirm-on-read: one candidate, served from an index, is the only
+        // shape where a wrong answer gets acted on. See `reconcile`.
+        const only = matches.candidates.length === 1 ? matches.candidates[0] : undefined;
+        if (catalogue.fromIndex && only !== undefined) {
+          const rebuilt = await reconcile(context.storage, catalogue, only.entity);
+          if (rebuilt !== null) {
+            context.log.debug('entities: index disagreed with a matched file, rebuilt');
+            catalogue = rebuilt;
+            matches = matchEntities(catalogue, criteria);
+          }
+        }
+
+        context.audit.annotate({
+          scanned: matches.scanned,
+          matched: matches.total,
+          candidates: matches.candidates.map((one) => one.entity.id),
+        });
+
+        if (matches.candidates.length === 0) {
+          return {
+            content: [
+              {
+                type: 'text',
+                text:
+                  `Nothing on ${context.connection.key} matches ${describe(criteria)}. ` +
+                  'Do not use an address that is not here — `entities.write` declares a new one, ' +
+                  'or ask the owner.',
+              },
+            ],
+          };
+        }
+
+        if (matches.candidates.length > 1) {
+          return {
+            content: [
+              { type: 'text', text: renderCandidates(matches, criteria, context.connection.key) },
+              ...matches.candidates.map((one) => ({
+                type: 'resource_link' as const,
+                uri: `entities://entity/${encodeURIComponent(one.entity.id)}`,
+                name: one.entity.name,
+              })),
+            ],
+          };
+        }
+
+        const found = matches.candidates[0]!.entity;
+        const file = await readEntity(context.storage, found.id);
+
+        return {
+          content: [
+            {
+              type: 'resource_link' as const,
+              uri: `entities://entity/${encodeURIComponent(found.id)}`,
+              name: found.name,
+            },
+            { type: 'text', text: renderEntity(found, catalogue, file?.body ?? '') },
+          ],
+        };
+      },
+    },
+
+    {
+      kind: 'tool',
+      name: 'get',
+      title: 'Read one entity',
+      description:
+        'Return one entity by id, with its relationships and everything pointing at it. The resource ' +
+        'entities://entity/{id} is the same content; this exists for clients that do not read resources.',
+      inputSchema: z.object({ id: z.string().min(1).describe('Entity id') }),
+      redact: keepKeys('id'),
+      async handler({ id }, context) {
+        const entity = await readEntity(context.storage, id);
+        if (entity === null) {
+          return {
+            content: [{ type: 'text', text: `No entity "${id}" on ${context.connection.key}.` }],
+            isError: true,
+          };
+        }
+
+        const catalogue = await openCatalogue(context.storage);
+        return { content: [{ type: 'text', text: renderEntity(entity, catalogue, entity.body) }] };
+      },
+    },
+
+    ...writeCapabilities,
+  ],
+});
+
+/**
+ * Re-check a single match against its own file before an agent acts on it.
+ *
+ * The index's fingerprint stamps the *entity files*, so an index edited on its
+ * own — by hand, or corrupted in a way that still parses — passes it and is
+ * served. That is the accepted cost of keeping the index beside the documents,
+ * and this is where it is paid back: on the one path where an answer is about
+ * to be used to address something, the file is opened and compared. One extra
+ * read, which `get` would have cost anyway.
+ *
+ * On any disagreement the whole catalogue is rebuilt and the search re-run,
+ * rather than the one row being patched. Patching would answer with an entity
+ * that no longer matches what was asked for — the index may have been the only
+ * reason it matched — and "here is your one result" is exactly the wrong thing
+ * to say then. Re-running can legitimately return none, or several; both are
+ * better answers than a confident wrong one.
+ *
+ * Not done when there are several candidates: nothing is being acted on yet,
+ * and `get` reads the file.
+ */
+async function reconcile(
+  storage: BlobStore,
+  catalogue: Catalogue,
+  candidate: CatalogueEntity,
+): Promise<Catalogue | null> {
+  const file = await readEntity(storage, candidate.id);
+  if (file !== null && canonical(strip(file)) === canonical(candidate)) return null;
+
+  return rebuildCatalogue(storage);
+}
+
+function strip(entity: Entity): CatalogueEntity {
+  const { body: _body, bytes: _bytes, ...row } = entity;
+  return row;
+}
+
+/**
+ * Everything about a row that could have decided the match, as one string.
+ *
+ * Written out field by field rather than `JSON.stringify(row)` so the
+ * comparison does not depend on two parsers inserting keys in the same order —
+ * a difference that would read as a disagreement and rebuild on every call.
+ */
+function canonical(row: CatalogueEntity): string {
+  return JSON.stringify([
+    row.type,
+    row.name,
+    [...row.aliases],
+    [...row.tags],
+    row.attributes.map((one) => [one.kind, one.value, one.note ?? '']),
+    row.relations.map((one) => [one.predicate, one.entity, one.note ?? '']),
+    row.updatedAt,
+  ]);
+}
+
+export default entitiesProvider;