@nanolink/mirrors 1.1.50 → 1.1.51

package/dist/definitions/annotations.d.ts

@@ -0,0 +1,84 @@
+import { Subscriptions } from './mirrors';
+/**
+ * Semantic annotations for the predefined mirrors.
+ *
+ * WHY THESE LIVE HERE, next to the documents they describe:
+ *
+ * Everything mechanical about a mirror can be derived — field names, types,
+ * aliases and variables all fall out of the GraphQL document validated against
+ * the server SDL. What cannot be derived is *meaning*: what a collection is,
+ * when someone should reach for it, and whether it belongs in a surface exposed
+ * to an AI assistant at all. That has to be authored by whoever knows the data,
+ * and the closest place to the data is here.
+ *
+ * THE BUILD GATE IS THE TYPE ITSELF.
+ *
+ * `Record<keyof typeof Subscriptions, MirrorAnnotation>` means adding a mirror
+ * without annotating it is a compile error in this package. No lint rule to
+ * remember, no script to run — it simply will not build. Consumers (the MCP
+ * server) do a second pass: they refuse to expose anything whose annotation is
+ * still unreviewed, and they re-derive schemas from the live SDL so a document
+ * that drifts away from the server fails their build too.
+ */
+/** Who a mirror is meant for. */
+export type MirrorAudience = 
+/** Safe and useful to expose as an AI tool. */
+'ai'
+/** Internal plumbing, diagnostics, or too specialised to be worth a tool. */
+ | 'internal';
+/** Rough size, so consumers can pick sensible default page limits. */
+export type MirrorCardinality = 
+/** Tens of rows. Safe to read whole. */
+'small'
+/** Hundreds. Usually wants a limit. */
+ | 'medium'
+/** Thousands or unbounded. Always wants a limit and a filter. */
+ | 'large';
+export interface MirrorAnnotation {
+    /** Short noun phrase, e.g. "Trackers". Becomes the tool title. */
+    title: string;
+    /**
+     * What this collection *is*, in the words a reader needs — not a restatement
+     * of the field list, which is generated anyway.
+     */
+    description: string;
+    /**
+     * When to reach for this one, and when not. This is what stops an assistant
+     * from picking a plausible-sounding neighbour.
+     */
+    useWhen?: string;
+    /** Whether this belongs in an AI-facing surface. */
+    audience: MirrorAudience;
+    /**
+     * Fields worth returning by default.
+     *
+     * Some documents select a great deal — `references` selects 100 fields — and
+     * sending all of it into a model's context is wasteful. Consumers return
+     * these by default and keep the rest available on request. Names are the
+     * *aliased* output names, as they appear in results.
+     */
+    summaryFields?: readonly string[];
+    cardinality?: MirrorCardinality;
+    /**
+     * Has a human confirmed this description is accurate?
+     *
+     * Defaults to absent, which consumers must treat as "not reviewed" and
+     * refuse to expose. This exists so a mirror can be added and compile without
+     * anyone inventing a plausible-sounding description that turns out to be
+     * wrong — an incorrect tool description is worse than a missing tool,
+     * because it produces confidently wrong answers rather than no answer.
+     */
+    reviewed?: true;
+}
+/**
+ * Annotation for every predefined mirror.
+ *
+ * Entries below are seeded from the GraphQL documents and the server schema.
+ * Anything not marked `reviewed: true` is a DRAFT and will not be exposed by
+ * consumers, regardless of `audience`.
+ */
+export declare const MirrorAnnotations: Record<keyof typeof Subscriptions, MirrorAnnotation>;
+/** Mirrors an AI-facing consumer may expose: annotated, reviewed, and marked `ai`. */
+export declare function exposedMirrors(): Array<keyof typeof Subscriptions>;
+/** Names still carrying a draft description, for a build-time report. */
+export declare function draftMirrors(): Array<keyof typeof Subscriptions>;