@semiont/core 0.5.27 → 0.5.28

package/dist/index.d.ts

@@ -1960,9 +1960,28 @@ interface components {
                 updatedAt: string;
             }[];
         };
-        /** @description Web Annotation / W3C PROV Agent. Discriminated by @type — Person, Organization, or Software. Each branch carries fields appropriate to its kind. Software peers are first-class participants, not a sub-class of Person. */
-        Agent: ({
-            /** @constant */
+        /** @description Web Annotation / W3C PROV Agent. Discriminated by @type — Person, Organization, or Software (named member schemas: AgentPerson, AgentOrganization, AgentSoftware). Software peers are first-class participants, not a sub-class of Person. */
+        Agent: components["schemas"]["AgentPerson"] | components["schemas"]["AgentOrganization"] | components["schemas"]["AgentSoftware"];
+        /** @description An organization — the Organization branch of Agent. */
+        AgentOrganization: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            "@type": "Organization";
+            /** Format: uri */
+            "@id"?: string;
+            name: string;
+            homepage?: string;
+        } & {
+            [key: string]: unknown;
+        };
+        /** @description A human participant — the Person branch of Agent. */
+        AgentPerson: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
             "@type": "Person";
             /**
              * Format: uri
@@ -1977,17 +1996,13 @@ interface components {
             homepage?: string;
         } & {
             [key: string]: unknown;
-        }) | ({
-            /** @constant */
-            "@type": "Organization";
-            /** Format: uri */
-            "@id"?: string;
-            name: string;
-            homepage?: string;
-        } & {
-            [key: string]: unknown;
-        }) | ({
-            /** @constant */
+        };
+        /** @description A software peer (an inference model acting as a first-class participant) — the Software branch of Agent. Carries structured provider + model. */
+        AgentSoftware: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
             "@type": "Software";
             /**
              * Format: uri
@@ -2006,7 +2021,7 @@ interface components {
             };
         } & {
             [key: string]: unknown;
-        });
+        };
         Annotation: {
             /**
              * @description W3C Web Annotation JSON-LD context
@@ -2041,7 +2056,7 @@ interface components {
             /** @description SHA-256 of resource content at annotation time */
             contentChecksum?: string;
         };
-        /** @description Phase 2: Body can be TextualBody (for entity tags, descriptions) or SpecificResource (for links) */
+        /** @description An annotation's body: a TextualBody carries text the annotation states (entity tags, descriptions, comments), a SpecificResource points at what it links to. Tell them apart by `type`, which is required on both and single-valued — a consumer never has to probe for which fields happen to be present. */
         AnnotationBody: components["schemas"]["TextualBody"] | components["schemas"]["SpecificResource"];
         /** @description Payload for mark:body-updated domain event */
         AnnotationBodyUpdatedPayload: {
@@ -2339,7 +2354,7 @@ interface components {
         /** @description A resource's stored extraction outcome — the coordinate map with its provenance, or a named decline — or null when none has been derived. Null is the common case and not an error: a native text layer is read in the browser, and a media type with no extractor never produces one. */
         BrowseAnchoredTextResult: {
             correlationId: string;
-            response: components["schemas"]["ExtractionOutcome"] | null;
+            response: Omit<components["schemas"]["ExtractionOutcome"], "kind"> | null;
         };
         /** @description Request to browse a single resource */
         BrowseResourceRequest: {
@@ -2493,7 +2508,7 @@ interface components {
             /** @description Optional body. Omit for annotations whose motivation alone is meaningful (highlighting) or whose user-supplied content is empty. Shape matches Annotation.body. */
             body?: components["schemas"]["AnnotationBody"] | components["schemas"]["AnnotationBody"][];
         };
-        /** @description Response body for POST /resources (202 Accepted). Resource creation is asynchronous — the backend writes content to disk, emits yield:create on the bus, and returns the newly-minted resourceId immediately. Consumers watch SSE domain events (yield:created) to observe the fully-persisted state. */
+        /** @description Response body for POST /resources (202 Accepted). The route writes content to disk, emits yield:create, and AWAITS the confirmed-write reply — so the returned resourceId is the one Stower minted, and the resource's event is persisted before this response is sent. What remains asynchronous is downstream projection: graph, views and vectors settle after the 202. */
         CreateResourceResponse: {
             /** @description The id of the newly-created resource. Assigned by Stower when it persists yield:create. */
             resourceId: string;
@@ -2503,7 +2518,10 @@ interface components {
             message: string;
         };
         DirEntry: {
-            /** @enum {string} */
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
             type: "dir";
             /** @description Entry name (basename) */
             name: string;
@@ -2515,6 +2533,7 @@ interface components {
              */
             mtime: string;
         };
+        /** @description One entry in a directory listing: a file, which may carry the resource it was ingested as, or a subdirectory. Tell them apart by `type`, which is required on both and single-valued. */
         DirectoryEntry: components["schemas"]["FileEntry"] | components["schemas"]["DirEntry"];
         /**
          * DiscoveredKB
@@ -2552,7 +2571,7 @@ interface components {
             /** @description Every KB the launcher currently manages, local and forwarded */
             kbs: components["schemas"]["DiscoveredKB"][];
         };
-        /** @description Wire format emitted by GET /resources/:id/events/stream. Extends StoredEventResponse with optional enrichment fields populated from the materialized view at SSE-write time. Subscribers can read the enrichment fields directly to update local caches without an additional fetch. */
+        /** @description Wire format for persisted events delivered over the bus SSE stream (GET /bus/subscribe). Extends StoredEventResponse with optional enrichment fields the EventStore populates from the materialized view at publish time (persistence → view → enrich → notification). Subscribers read the enrichment fields directly to update local caches without an additional fetch. */
         EnrichedResourceEvent: components["schemas"]["StoredEventResponse"] & {
             /** @description Populated for events that mutate an annotation (mark:added, mark:body-updated, mark:removed). Carries the post-materialization annotation as it exists in the view, so subscribers can update local caches in-place without refetching. Absent for events that don't touch annotations. */
             annotation?: components["schemas"]["Annotation"];
@@ -2582,8 +2601,13 @@ interface components {
             data: string;
             id?: string;
         };
-        /** @description The full outcome of text extraction for one representation — the record the anchored-text store holds and the wire serves (PERSIST-ANCHORS decision D1). Either a success (the anchored text plus its provenance: how it was extracted, what class of PDF it came from, how confident OCR was, which pages could not be read) or a named decline. A decline is a first-class, cacheable outcome: 'we ran and there was nothing' costs a full recognition pass to discover. ocrConfidence is extraction quality for operators, deliberately not anchor confidence. */
-        ExtractionOutcome: (components["schemas"]["AnchoredText"] & {
+        /** @description A successful extraction: the anchored text plus its provenance (WIRE-UNION-DISCRIMINANTS P5c named this member; PERSIST-ANCHORS D1 made it the stored record). */
+        ExtractedText: components["schemas"]["AnchoredText"] & {
+            /**
+             * @description Discriminant — both ExtractionOutcome members carry `kind`, single-valued (D6: category here, detail in `method`).
+             * @enum {string}
+             */
+            kind: "extracted";
             /**
              * @description How the text was extracted.
              * @enum {string}
@@ -2604,15 +2628,33 @@ interface components {
             };
             /** @description 1-indexed pages this extraction could not read — present only for partially covered documents (class C). */
             unreadPages?: number[];
-        }) | {
+        } & {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            kind: "extracted";
+        };
+        /** @description A named decline: extraction ran and yielded nothing, by class. A first-class, cacheable outcome — 'we ran and there was nothing' costs a full recognition pass to discover. */
+        ExtractionDeclined: {
+            /**
+             * @description Discriminant — both ExtractionOutcome members carry `kind`, single-valued (D6: category here, detail in `declined`). (enum property replaced by openapi-typescript)
+             * @enum {string}
+             */
+            kind: "declined";
             /**
              * @description Why extraction yielded nothing, by class.
              * @enum {string}
              */
             declined: "no-text-layer" | "encrypted" | "corrupt" | "too-large";
         };
+        /** @description The full outcome of text extraction for one representation — the record the anchored-text store holds and the wire serves (PERSIST-ANCHORS decision D1). Discriminated on `kind` (WIRE-UNION-DISCRIMINANTS P5c/D6): 'extracted' — the anchored text with its provenance; 'declined' — a named decline. ocrConfidence is extraction quality for operators, deliberately not anchor confidence. */
+        ExtractionOutcome: components["schemas"]["ExtractedText"] | components["schemas"]["ExtractionDeclined"];
         FileEntry: {
-            /** @enum {string} */
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
             type: "file";
             /** @description Entry name (basename) */
             name: string;
@@ -2811,7 +2853,7 @@ interface components {
             title: string;
             /** @description Storage URI for the generated resource's content. */
             storageUri: string;
-            /** @description The gathered context that grounds the generation. Its `focus` names the anchor (the sdk derives the job's resourceId — and referenceId, for annotation focus — from it); under `cite`, the ids its embedding carries are the only valid citation targets. */
+            /** @description The gathered context that grounds the generation. Its `focus` names the anchor: the DISPATCHER derives the job's resourceId from it (resource focus → focus.resource; annotation focus → focus.sourceResource, with the worker auto-binding to focus.annotation) and REJECTS a caller-supplied id — the context is authoritative. Under `cite`, the ids its embedding carries are the only valid citation targets. */
             context: components["schemas"]["GatheredContext"];
             /** @description Refining instruction, composed with `task` (task = what, prompt = how). */
             prompt?: string;
@@ -2910,8 +2952,48 @@ interface components {
             /** @description Maximum output tokens per generation. Equal to contextTokens when the provider has a single shared window. */
             maxOutputTokens: number;
         };
+        /** @description An annotation's graph presence. The node IS the annotation, so the full W3C object is required — selectors and body included, which is what lets a client place context annotations without a second fetch. Citations ride here too: an inbound reference is its linking annotation, anchored by an `annotation-of` edge to the resource it lives on and a `cites` edge to the focal resource. */
+        GraphAnnotationNode: {
+            /** @description The AnnotationId — the same value as annotation.id */
+            id: string;
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            type: "annotation";
+            /** @description The annotation's motivation, as a display label */
+            label: string;
+            /** @description Entity types carried by the annotation */
+            entityTypes?: string[];
+            annotation: components["schemas"]["Annotation"];
+            metadata?: {
+                [key: string]: unknown;
+            };
+        };
+        /** @description A resource's presence in the gathered knowledge graph. */
+        GraphResourceNode: {
+            /** @description The resource's ResourceId */
+            id: string;
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            type: "resource";
+            /** @description The resource's display name — its raw id when the resource's view was missing at build time */
+            label: string;
+            /** @description Entity types on the resource */
+            entityTypes?: string[];
+            metadata?: {
+                [key: string]: unknown;
+            };
+        };
         /** @description Result of a completed assessment-annotation job. */
         JobAssessmentAnnotationResult: {
+            /**
+             * @description Discriminant — every JobResult member carries `kind`, single-valued, so a consumer holding only the result can tell what it is (WIRE-UNION-DISCRIMINANTS D1). (enum property replaced by openapi-typescript)
+             * @enum {string}
+             */
+            kind: "assessment-annotation";
             assessmentsFound: number;
             assessmentsCreated: number;
         };
@@ -2929,6 +3011,11 @@ interface components {
         };
         /** @description Result of a completed comment-annotation job. */
         JobCommentAnnotationResult: {
+            /**
+             * @description Discriminant — every JobResult member carries `kind`, single-valued, so a consumer holding only the result can tell what it is (WIRE-UNION-DISCRIMINANTS D1). (enum property replaced by openapi-typescript)
+             * @enum {string}
+             */
+            kind: "comment-annotation";
             commentsFound: number;
             commentsCreated: number;
         };
@@ -2993,6 +3080,11 @@ interface components {
         };
         /** @description Result of a job that completed without doing its work because the resource could not be read. Distinct from a failure: nothing went wrong, there was simply no text to work with — an encrypted or damaged PDF, a scan whose text could not be recognized, or a document that yielded nothing. The reasons are the extraction vocabulary the Smelter reports on `smelt:settled`, MINUS `no-extractor`: a media type that can never yield text (a zip, an image) is a bad request rather than a decline, so a worker asked to detect over one throws and the job reports `job:fail`. Everything here is a resource-specific outcome — the same media type would have succeeded on a different document. */
         JobDeclinedResult: {
+            /**
+             * @description Discriminant — every JobResult member carries `kind`, single-valued, so a consumer holding only the result can tell what it is (WIRE-UNION-DISCRIMINANTS D1). (enum property replaced by openapi-typescript)
+             * @enum {string}
+             */
+            kind: "declined";
             /**
              * @description Discriminant. Always true — a job that did its work reports one of the other result shapes.
              * @enum {boolean}
@@ -3013,15 +3105,27 @@ interface components {
             error: string;
             details?: string;
         };
-        /** @description Result of a completed generation job. resourceId is assigned by Stower when yield:create is processed; the worker emits job:complete with only resourceName, and Stower populates resourceId on the persisted payload. */
+        /** @description Result of a completed generation job. The worker creates the resource first (the yield:create round-trip returns the id), then emits job:complete carrying it — so resourceId is always present on the wire. */
         JobGenerationResult: {
-            /** @description ID of the generated resource (populated by Stower, not by the worker) */
-            resourceId?: string;
+            /**
+             * @description Discriminant — every JobResult member carries `kind`, single-valued, so a consumer holding only the result can tell what it is (WIRE-UNION-DISCRIMINANTS D1). (enum property replaced by openapi-typescript)
+             * @enum {string}
+             */
+            kind: "generation";
+            /** @description ID of the generated resource, obtained by the worker from the create round-trip before job:complete is emitted */
+            resourceId: string;
             /** @description Name of the generated resource */
             resourceName: string;
+            /** @description True when the model stopped at the maxTokens ceiling — the artifact is cut off, not complete. Derived at the producer from the provider's stopReason ('max_tokens' → true); required because the worker always knows (GENERATE-FROM-RESOURCE D6/P3a). */
+            truncated: boolean;
         };
         /** @description Result of a completed highlight-annotation job. */
         JobHighlightAnnotationResult: {
+            /**
+             * @description Discriminant — every JobResult member carries `kind`, single-valued, so a consumer holding only the result can tell what it is (WIRE-UNION-DISCRIMINANTS D1). (enum property replaced by openapi-typescript)
+             * @enum {string}
+             */
+            kind: "highlight-annotation";
             highlightsFound: number;
             highlightsCreated: number;
         };
@@ -3069,22 +3173,30 @@ interface components {
                 value: string;
             }[];
         };
-        /** @description What a running job is doing right now, as a code plus typed params — never a prose sentence. The producer reports what happened; each client renders it in the user's language (react-ui from its translations, the Go launcher from its English map). The vocabulary is the census of every onProgress call site in @semiont/jobs (.plans/ASSIST-PROGRESS-CONSOLIDATION.md P1, 2026-08-12); extending it means adding a variant here and copy in every client, gated by the locale-completeness check. */
-        JobProgressMessage: {
-            /** @enum {string} */
-            code: "loading" | "analyzing" | "analyzing-tags" | "generating-resource" | "creating-resource";
-        } | {
-            /** @enum {string} */
-            code: "detecting-entities";
-            /** @description Entity type currently being detected */
-            entityType: string;
-        } | {
-            /** @enum {string} */
-            code: "creating-annotations" | "creating-tag-annotations";
-            /** @description How many annotations are being created */
-            count: number;
-        } | {
-            /** @enum {string} */
+        /** @description What a running job is doing right now, as a code plus typed params — never a prose sentence. The producer reports what happened; each client renders it in the user's language (react-ui from its translations, the Go launcher from its English map). One named schema per code, discriminated on `code` (WIRE-UNION-DISCRIMINANTS P5b), so generated clients get typed variants and copy-map completeness is statically checkable. The vocabulary is the census of every onProgress call site in @semiont/jobs (.plans/ASSIST-PROGRESS-CONSOLIDATION.md P1); extending it means adding a named variant here and copy in every client, gated by the locale-completeness check. */
+        JobProgressMessage: components["schemas"]["JobProgressLoading"] | components["schemas"]["JobProgressAnalyzing"] | components["schemas"]["JobProgressAnalyzingTags"] | components["schemas"]["JobProgressGeneratingResource"] | components["schemas"]["JobProgressCreatingResource"] | components["schemas"]["JobProgressCompleteGenerated"] | components["schemas"]["JobProgressDetectingEntities"] | components["schemas"]["JobProgressCreatingAnnotations"] | components["schemas"]["JobProgressCreatingTagAnnotations"] | components["schemas"]["JobProgressCompleteCreated"];
+        /** @description Analyzing the content. */
+        JobProgressAnalyzing: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            code: "analyzing";
+        };
+        /** @description Analyzing the content against the tag schema. */
+        JobProgressAnalyzingTags: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            code: "analyzing-tags";
+        };
+        /** @description Terminal success summary. */
+        JobProgressCompleteCreated: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
             code: "complete-created";
             /** @description How many annotations were created */
             count: number;
@@ -3094,6 +3206,70 @@ interface components {
              */
             kind: "highlight" | "comment" | "assessment" | "reference" | "tag";
         };
+        /** @description Generation's terminal success. Deliberately generic — the client already holds the title it typed, and the outcome (name + resource link) travels on job:complete, not on progress (GENERATE-FROM-RESOURCE D7/D8). `truncated` qualifies the completion (D6): the same bit `JobGenerationResult.truncated` carries, so the two surfaces cannot drift. */
+        JobProgressCompleteGenerated: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            code: "complete-generated";
+            /** @description True when the model stopped at the maxTokens ceiling — the artifact is cut off, not complete. */
+            truncated: boolean;
+        };
+        /** @description Writing detected annotations back to the resource. */
+        JobProgressCreatingAnnotations: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            code: "creating-annotations";
+            /** @description How many annotations are being created */
+            count: number;
+        };
+        /** @description Writing the generated resource. */
+        JobProgressCreatingResource: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            code: "creating-resource";
+        };
+        /** @description Writing detected tag annotations back to the resource. */
+        JobProgressCreatingTagAnnotations: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            code: "creating-tag-annotations";
+            /** @description How many annotations are being created */
+            count: number;
+        };
+        /** @description Entity detection, one entity type at a time. */
+        JobProgressDetectingEntities: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            code: "detecting-entities";
+            /** @description Entity type currently being detected */
+            entityType: string;
+        };
+        /** @description The model is generating the resource. */
+        JobProgressGeneratingResource: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            code: "generating-resource";
+        };
+        /** @description Loading the resource content. */
+        JobProgressLoading: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            code: "loading";
+        };
         /** @description Event indicating a job has been queued */
         JobQueuedEvent: {
             jobId: string;
@@ -3104,6 +3280,11 @@ interface components {
         };
         /** @description Result of a completed reference-annotation job. */
         JobReferenceAnnotationResult: {
+            /**
+             * @description Discriminant — every JobResult member carries `kind`, single-valued, so a consumer holding only the result can tell what it is (WIRE-UNION-DISCRIMINANTS D1). (enum property replaced by openapi-typescript)
+             * @enum {string}
+             */
+            kind: "reference-annotation";
             /** @description Total entities found */
             totalFound: number;
             /** @description Total annotations emitted */
@@ -3123,7 +3304,7 @@ interface components {
             percentage: number;
             progress?: components["schemas"]["JobProgress"];
         };
-        /** @description Discriminated union of all job result types. */
+        /** @description Discriminated union of all job result types — every member carries a single-valued `kind` (WIRE-UNION-DISCRIMINANTS D1/D2). Consumers switch on `kind`; generated clients get typed variants. */
         JobResult: components["schemas"]["JobGenerationResult"] | components["schemas"]["JobReferenceAnnotationResult"] | components["schemas"]["JobHighlightAnnotationResult"] | components["schemas"]["JobAssessmentAnnotationResult"] | components["schemas"]["JobCommentAnnotationResult"] | components["schemas"]["JobTagAnnotationResult"] | components["schemas"]["JobDeclinedResult"];
         /** @description Command to start a job */
         JobStartCommand: {
@@ -3159,7 +3340,7 @@ interface components {
             completedAt?: string;
             error?: string;
             progress?: unknown;
-            result?: unknown;
+            result?: components["schemas"]["JobResult"];
         };
         /** @description Result of a job status request */
         JobStatusResult: {
@@ -3168,6 +3349,11 @@ interface components {
         };
         /** @description Result of a completed tag-annotation job. */
         JobTagAnnotationResult: {
+            /**
+             * @description Discriminant — every JobResult member carries `kind`, single-valued, so a consumer holding only the result can tell what it is (WIRE-UNION-DISCRIMINANTS D1). (enum property replaced by openapi-typescript)
+             * @enum {string}
+             */
+            kind: "tag-annotation";
             tagsFound: number;
             tagsCreated: number;
             /** @description Count of tags created per category */
@@ -3182,25 +3368,11 @@ interface components {
         JobType: "reference-annotation" | "generation" | "highlight-annotation" | "assessment-annotation" | "comment-annotation" | "tag-annotation";
         /** @description Knowledge graph gathered for an LLM context — a shared backbone in which resources AND annotations are typed nodes, connected by typed (optionally bidirectional) edges. Flattened views the matcher/generation read (connections, citedBy, siblings) are derived from these nodes/edges. */
         KnowledgeGraph: {
-            nodes: {
-                /** @description Node identifier — a ResourceId or AnnotationId */
-                id: string;
-                /**
-                 * @description Whether this node is a resource or an annotation
-                 * @enum {string}
-                 */
-                type: "resource" | "annotation";
-                label: string;
-                /** @description Entity types on the node (resources) or carried by the annotation */
-                entityTypes?: string[];
-                metadata?: {
-                    [key: string]: unknown;
-                };
-            }[];
+            nodes: (components["schemas"]["GraphResourceNode"] | components["schemas"]["GraphAnnotationNode"])[];
             edges: {
                 source: string;
                 target: string;
-                /** @description Edge kind (e.g. citation, annotation-of, sibling) */
+                /** @description Edge kind: `annotation-of` (an annotation → the resource it lives on), `cites` (a citing linking annotation → the focal resource), or a peer connection's own relationshipType (free-form; `link` when unnamed) */
                 type: string;
                 /** @description Whether the connection goes both ways */
                 bidirectional?: boolean;
@@ -3596,6 +3768,8 @@ interface components {
             text: string;
             /** @description Source resource ID */
             resourceId: string;
+            /** @description The source resource's display name, resolved from its view at gather time. Required: a match card must name its source, and corpus matches routinely come from outside the graph neighborhood, so there is no node to borrow a name from. A match whose source no longer resolves to a view is dropped by the producer rather than served nameless. */
+            resourceName: string;
             /** @description Source annotation ID, if the match is from an annotation */
             annotationId?: string;
             /** @description Cosine similarity score (0-1) */
@@ -3633,7 +3807,10 @@ interface components {
             theme: "light" | "dark" | "system";
         };
         SpecificResource: {
-            /** @enum {string} */
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
             type: "SpecificResource";
             /** @description IRI of the target resource */
             source: string;
@@ -3726,7 +3903,10 @@ interface components {
             suffix?: string;
         };
         TextualBody: {
-            /** @enum {string} */
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
             type: "TextualBody";
             /** @description The text content (e.g., entity type name) */
             value: string;
@@ -8142,11 +8322,16 @@ declare function getAllPlatformTypes(): PlatformType[];
  * and `@semiont/jobs` (the generation prompt builder) can share one derivation. `buildKnowledgeGraph`
  * — which queries the graph DB — stays in make-meaning; this only transforms an already-built graph.
  *
- * Reports the graph as-is (Option A): missing-view citers are kept (the citation edge reflects a real
- * reference event); the only filter is excluding the focal annotation from siblings (an annotation
- * isn't its own sibling). Peer connections are edges out of `mainResourceId`; citations and
- * `annotation-of` edges point INTO it. The graph is a projection of the event log (the system of
- * record), read here because it is the queryable projection at gather time.
+ * Reports the graph as-is (Option A): missing-view citers are kept (the citing annotation reflects a
+ * real reference event; its resource label falls back to the raw id). A citation is its linking
+ * ANNOTATION: an annotation node with `annotation-of` → the citing resource and `cites` → the focal
+ * resource — so citedBy resolves through that pair, deduped per citing resource (several citations
+ * from one document are one citer). Siblings are annotations ON the focal resource
+ * (`annotation-of` → main), excluding the focal annotation — an annotation isn't its own sibling,
+ * and a CITING annotation lives on another resource, so it never was one. Peer connections are
+ * edges out of `mainResourceId`; derivation is structural (endpoints), never a match on the
+ * free-form relationshipType. The graph is a projection of the event log (the system of record),
+ * read here because it is the queryable projection at gather time.
  */
 
 type KnowledgeGraph = components['schemas']['KnowledgeGraph'];

package/dist/index.js

@@ -1,6 +1,7 @@
 export { createTomlConfigLoader, loadTomlConfig } from './chunk-JWTQJVKM.js';
 import { BUS_OPERATIONS } from './chunk-CUPZGI7I.js';
 export { BRIDGED_CHANNELS, BUS_OPERATIONS, EventBus, ScopedEventBus, accessToken, annotationUri, authCode, baseUrl, busLog, busLogEnabled, cloneToken, email, entityType, googleCredential, jobId, mcpToken, refreshToken, resourceAnnotationUri, resourceUri, searchQuery, setBusLogTraceIdProvider, userDID } from './chunk-CUPZGI7I.js';
+import './chunk-YLJ4XMA6.js';
 import { Observable, merge, TimeoutError, throwError, firstValueFrom } from 'rxjs';
 import { filter, map, take, timeout, catchError, defaultIfEmpty } from 'rxjs/operators';
 
@@ -2065,13 +2066,20 @@ function getAllPlatformTypes() {
 // src/knowledge-graph-views.ts
 function deriveViews(graph, mainResourceId, focalAnnotationId) {
   const nodeById = new Map(graph.nodes.map((n) => [n.id, n]));
+  const annotationOf = /* @__PURE__ */ new Map();
+  for (const edge of graph.edges) {
+    if (edge.type === "annotation-of") annotationOf.set(edge.source, edge.target);
+  }
   const connections = [];
   const citedBy = [];
+  const citingSeen = /* @__PURE__ */ new Set();
   for (const edge of graph.edges) {
-    if (edge.type === "citation") {
-      if (edge.target !== mainResourceId) continue;
-      const node = nodeById.get(edge.source);
-      citedBy.push({ resourceId: edge.source, resourceName: node?.label ?? edge.source });
+    const citingResource = edge.type === "cites" && edge.target === mainResourceId ? annotationOf.get(edge.source) : void 0;
+    if (citingResource !== void 0) {
+      if (citingSeen.has(citingResource)) continue;
+      citingSeen.add(citingResource);
+      const node = nodeById.get(citingResource);
+      citedBy.push({ resourceId: citingResource, resourceName: node?.label ?? citingResource });
     } else if (edge.source === mainResourceId) {
       const node = nodeById.get(edge.target);
       connections.push({
@@ -2084,7 +2092,7 @@ function deriveViews(graph, mainResourceId, focalAnnotationId) {
   }
   const siblingEntityTypes = /* @__PURE__ */ new Set();
   for (const node of graph.nodes) {
-    if (node.type === "annotation" && node.id !== focalAnnotationId) {
+    if (node.type === "annotation" && node.id !== focalAnnotationId && annotationOf.get(node.id) === mainResourceId) {
       for (const et of node.entityTypes ?? []) siblingEntityTypes.add(et);
     }
   }