@semiont/make-meaning 0.5.28 → 0.5.29

package/dist/index.d.ts

@@ -1,14 +1,14 @@
 import { JobQueue } from '@semiont/jobs';
-import { SemiontProject } from '@semiont/core/node';
-import { GraphServiceConfig, VectorsServiceConfig, EmbeddingServiceConfig, StateUnit, EventBus, Logger, ResourceId, ResourceDescriptor, AnnotationId, components, ITransport, BaseUrl, ConnectionState, SemiontError, UserDID, EventMap, IContentTransport, PutBinaryRequest, PutBinaryOptions, ExtractionOutcome, AccessToken, BusRequestPrimitive, ChunkingConfig, StoredEvent, Annotation, UserId, GatheredContext, ResourceAnnotations, AnnotationCategory, GraphPath, GraphConnection } from '@semiont/core';
-import { EventStore, ViewStorage } from '@semiont/event-sourcing';
-import { WorkingTreeStore, AnchoredTextStore } from '@semiont/content';
+import { SemiontProject, SemiontState } from '@semiont/core/node';
+import { GraphServiceConfig, VectorsServiceConfig, EmbeddingServiceConfig, ArchivistServiceConfig, EnvironmentConfig, StateUnit, EventBus, Logger, ResourceId, ResourceDescriptor, components, AnnotationId, GatheredContext, ResourceAnnotations, Annotation, AnnotationCategory, ITransport, BaseUrl, ConnectionState, SemiontError, UserDID, EventMap, IContentTransport, PutBinaryRequest, PutBinaryOptions, ExtractionOutcome, AccessToken, BusRequestPrimitive, ChunkingConfig, UserId } from '@semiont/core';
+import { EventReadStorage, ViewMaterializer, EventStore, ViewStorage, EventLog } from '@semiont/event-sourcing';
+import { WorkingTreeStore, AnchoredTextStore, ContentReads } from '@semiont/content';
 import { GraphDatabase } from '@semiont/graph';
 import { VectorStore, EmbeddingProvider } from '@semiont/vectors';
 import { InferenceClient } from '@semiont/inference';
+import { Server } from 'http';
 import { BehaviorSubject, Observable } from 'rxjs';
 import { WorkerBus } from '@semiont/sdk';
-import { Writable, Readable } from 'node:stream';
 
 /**
  * Inference configuration for a single actor or worker.
@@ -74,10 +74,14 @@ interface MakeMeaningConfig {
         /** REQUIRED (same ruling): the embedding provider is the KB's semantic
          *  identity — always named, never detected or defaulted. */
         embedding: EmbeddingServiceConfig;
+        /** Where the record is. Optional in the type because the actors that
+         *  hold a KB mount never dial it; the Librarian does, and refuses at
+         *  boot when it is absent (SINGLE-KB-MOUNT P4). */
+        archivist?: ArchivistServiceConfig;
     };
     /**
      * The KB's canonical identity domain — the SAME value `/api/tokens/agent`
-     * mints agent DIDs from (backend `site.domain`). The agent roster consumes
+     * mints agent DIDs from (gateway `site.domain`). The agent roster consumes
      * it verbatim, so directory DIDs and work-stamped `generator` DIDs are
      * equal by construction; it is never derived from service topology
      * (.plans/bugs/agent-did-host-skew.md).
@@ -90,9 +94,25 @@ interface MakeMeaningConfig {
     /** Per-worker-type inference config */
     workers?: WorkerInferenceConfig;
 }
+/**
+ * Extract the MakeMeaningConfig slice from a full EnvironmentConfig.
+ * actors and workers come from _metadata (populated by the TOML loader).
+ *
+ * Lives here (not in a consumer) because every composition root that runs
+ * make-meaning actors — the gateway's startMakeMeaning and the Archivist's
+ * archivist-main — needs the identical mapping; two copies would drift.
+ */
+/**
+ * The KB name a mountless service composes its state paths from —
+ * `[kb] name`, staged by the launcher (SINGLE-KB-MOUNT D4). Refusing is the
+ * point: a defaulted name composes a state path nobody writes to, and the
+ * service reads an empty view store forever, silently.
+ */
+declare function requireKBName(config: EnvironmentConfig): string;
+declare function makeMeaningConfigFrom(config: EnvironmentConfig): MakeMeaningConfig;
 
 /**
- * WeaveProgress — backend-local fold of `weave:applied` signals
+ * WeaveProgress — gateway-local fold of `weave:applied` signals
  * (GRAPH-PROJECTION-SYNC P2, D2 = push).
  *
  * The Weaver emits `weave:applied` after applying an event (or a batch's
@@ -108,7 +128,7 @@ interface MakeMeaningConfig {
  * WEAVER-ISOLATION the same channel arrives through the bus gateway and
  * this unit does not change.
  *
- * The map is ephemeral by design — on backend restart it rebuilds lazily
+ * The map is ephemeral by design — on gateway restart it rebuilds lazily
  * from live signals. That loses nothing: a waiter only ever waits for an
  * apply that has not happened yet, and those signals are still to come.
  */
@@ -126,7 +146,7 @@ interface WeaveProgress extends StateUnit {
 }
 
 /**
- * SmeltProgress — backend-local fold of `smelt:settled` signals
+ * SmeltProgress — gateway-local fold of `smelt:settled` signals
  * (SMELTER-INDEX-SYNC P1, D1 = push barrier).
  *
  * The Smelter emits `smelt:settled` after deciding a resource's content:
@@ -144,7 +164,7 @@ interface WeaveProgress extends StateUnit {
  * worker; an in-process Smelter would ride the core EventBus and this unit
  * would not change (the WeaveProgress precedent).
  *
- * The fold is ephemeral by design — on backend restart it rebuilds lazily
+ * The fold is ephemeral by design — on gateway restart it rebuilds lazily
  * from live signals. Barrier callers probe the vector store first
  * (SMELTER-INDEX-SYNC A3), so a cold fold only costs waits for resources
  * whose settlement genuinely hasn't been observed yet.
@@ -200,6 +220,30 @@ interface KnowledgeBase {
     vectors: VectorStore;
     projectionsDir: string;
 }
+/**
+ * Capability slices of the record (EXTRACT-ARCHIVIST P1).
+ *
+ * An Archivist actor takes the slice it actually uses, never the whole
+ * KnowledgeBase. Every slice is DERIVED from the owning type with Pick;
+ * a hand-restated shape here would be a mirror of a fact someone else owns.
+ */
+/** The lifecycle half of the working tree (GATEWAY.md D4a): the Archivist
+ *  accessions, moves, removes and resolves — it never serves bytes. */
+type ContentLifecycle = Pick<WorkingTreeStore, 'register' | 'move' | 'remove' | 'resolveUri'>;
+/** The record's single write seam. `Stower` is the only appendEvent caller
+ *  anywhere in make-meaning or the gateway (post-#1252): single-owner by
+ *  construction. A second caller is a design smell, not a wiring chore. */
+type EventAppends = Pick<EventStore, 'appendEvent'>;
+/** Read-only reach into the event store: the log for queries, the
+ *  materializer for on-demand view assembly (`assembleResourceGraph`). */
+interface EventStoreReads {
+    log: {
+        storage: EventReadStorage;
+    };
+    views: {
+        materializer: Pick<ViewMaterializer, 'materialize'>;
+    };
+}
 interface CreateKnowledgeBaseOptions {
     /** Required (MANDATORY-EMBEDDING D0): a KB without vector search is not a
      *  configuration we support; `MemoryVectorStore` is the explicit named
@@ -227,6 +271,7 @@ declare function createKnowledgeBase(eventStore: EventStore, project: SemiontPro
  *
  * Subscriptions:
  * - yield:create       → resource.created (+ content store)   → yield:created / yield:create-failed
+ * - yield:clone-persist → resource.cloned (+ content store)   → yield:cloned / yield:clone-persist-failed
  * - yield:update       → resource.updated (+ content store)   → yield:updated / yield:update-failed
  * - yield:mv           → resource.moved (+ working tree move) → yield:moved / yield:move-failed
  * - mark:create        → annotation.added                     → mark:created / mark:create-failed
@@ -252,15 +297,43 @@ interface CreateResourceResult {
     resourceId: ResourceId;
     resource: ResourceDescriptor;
 }
+/**
+ * The stores Stower writes through (EXTRACT-ARCHIVIST P1): the record's
+ * single write seam plus the content lifecycle — never bytes (GATEWAY.md
+ * D4a). Resource resolution for moves goes through `project.projectionsDir`.
+ */
+interface StowerStores {
+    content: ContentLifecycle;
+    eventStore: EventAppends;
+}
 declare class Stower {
-    private kb;
+    private stores;
     private eventBus;
     private project;
     private subscription;
     private readonly logger;
-    constructor(kb: KnowledgeBase, eventBus: EventBus, project: SemiontProject, logger: Logger);
+    constructor(stores: StowerStores, eventBus: EventBus, project: SemiontProject, logger: Logger);
     initialize(): Promise<void>;
     private handleYieldCreate;
+    /**
+     * Persist a clone (the CloneTokenManager's second half).
+     *
+     * A clone is its own domain fact, not a creation with an extra field: it
+     * NAMES the resource it came from, and `ResourceClonedPayload` requires
+     * that name. So it gets its own command and appends its own event, rather
+     * than an optional parent turning `yield:created` into something else at
+     * runtime.
+     *
+     * The token was already validated and the source's entity types already
+     * read by the CloneTokenManager — the one party that can do either. What
+     * happens here is what only the Stower may do: register the bytes and
+     * append the event (single-writer, GATEWAY.md D4b).
+     *
+     * Generated resources do NOT come through here. Their provenance is
+     * `generatedFrom` on `yield:created`, which is a different relation: a
+     * generated resource is derived from a source, a clone IS a copy of one.
+     */
+    private handleYieldClonePersist;
     private handleYieldUpdate;
     private handleYieldMv;
     private handleMarkCreate;
@@ -277,6 +350,218 @@ declare class Stower {
     stop(): Promise<void>;
 }
 
+/**
+ * Graph Context
+ *
+ * Provides graph database operations for resources and annotations.
+ * All methods require graph traversal - must use graph database.
+ */
+
+/**
+ * What the unified graph builder reads (EXTRACT-LIBRARIAN P2) — Pick-derived,
+ * never restated. The weave fold is bus-fed (`weave:applied`), so this slice
+ * works identically in-process and in the standalone Librarian.
+ */
+interface KnowledgeGraphReads {
+    graph: Pick<GraphDatabase, 'getResource' | 'getResourceConnections' | 'getResourceReferencedBy' | 'getResourceAnnotations'>;
+    views: Pick<ViewStorage, 'get'>;
+    weaveProgress: Pick<WeaveProgress, 'whenApplied'>;
+}
+type KnowledgeGraph = components['schemas']['KnowledgeGraph'];
+declare class GraphContext {
+    /**
+     * Build the unified knowledge graph for a resource's neighborhood:
+     * resources AND annotations as typed nodes, typed/directional edges.
+     *
+     * This is the single graph builder (CONTEXT-UNIFICATION D3) — both the
+     * matcher (ranking) and the resource/viz path consume it. The flattened
+     * signals the matcher reads today (`connections`, `citedBy`/count,
+     * `siblingEntityTypes`, `bidirectional`) are all derivable from this:
+     *  - peer connections → resource nodes + main→peer edges carrying `bidirectional`
+     *  - inbound citations → citing-resource nodes + `citation` edges (citing→main),
+     *    so citedByCount = inbound citation-edge count
+     *  - annotations on the resource → `annotation` nodes + `annotation-of` edges,
+     *    so siblingEntityTypes = union of those nodes' entityTypes
+     */
+    static buildKnowledgeGraph(resourceId: ResourceId, kb: KnowledgeGraphReads, 
+    /** Breadcrumb sink for the projection-lag degrade path; the degrade counter fires regardless. */
+    logger?: Logger): Promise<KnowledgeGraph>;
+}
+
+/**
+ * Annotation Context
+ *
+ * Assembles annotation context from view storage and content store.
+ * Provides methods for:
+ * - Getting resource annotations
+ * - Building LLM context for annotations
+ * - Extracting annotation text context
+ * - Generating AI summaries
+ */
+
+/** The view slice the annotation reads run on (EXTRACT-ARCHIVIST P1). */
+type ViewGet = {
+    views: Pick<ViewStorage, 'get'>;
+};
+/**
+ * What the annotation-gather path reads (EXTRACT-LIBRARIAN P2; content
+ * re-keyed by D-CONTENT b) — the graph builder's slice plus this module's
+ * own reads. Pick-derived, never restated. In-process roots satisfy it with
+ * `workingTreeContentReads` over their `kb`; the Librarian passes
+ * `HttpContentTransport`.
+ */
+interface AnnotationGatherReads {
+    views: Pick<ViewStorage, 'get'>;
+    content: ContentReads;
+    graph: KnowledgeGraphReads['graph'] & Pick<GraphDatabase, 'getEntityTypeStats'>;
+    vectors: Pick<VectorStore, 'searchAnnotations'>;
+    weaveProgress: KnowledgeGraphReads['weaveProgress'];
+}
+
+type AnnotationContextResponse = components['schemas']['AnnotationContextResponse'];
+type ContextualSummaryResponse = components['schemas']['ContextualSummaryResponse'];
+interface BuildContextOptions {
+    includeSourceContext?: boolean;
+    includeTargetContext?: boolean;
+    contextWindow?: number;
+}
+declare class AnnotationContext {
+    /**
+     * Build LLM context for an annotation
+     *
+     * @param annotationId - Bare annotation ID
+     * @param resourceId - Source resource ID
+     * @param kb - Knowledge base stores
+     * @param options - Context building options
+     * @param inferenceClient - Optional inference client for target context summary
+     * @returns Rich context for LLM processing
+     * @throws Error if annotation or resource not found
+     */
+    static buildLLMContext(annotationId: AnnotationId, resourceId: ResourceId, kb: AnnotationGatherReads, embeddingProvider: EmbeddingProvider, options?: BuildContextOptions, inferenceClient?: InferenceClient, logger?: Logger): Promise<GatheredContext>;
+    /**
+     * Get resource annotations from view storage (fast path)
+     * Throws if view missing
+     */
+    static getResourceAnnotations(resourceId: ResourceId, kb: ViewGet): Promise<ResourceAnnotations>;
+    /**
+     * Get all annotations
+     * @returns Array of all annotation objects
+     */
+    static getAllAnnotations(resourceId: ResourceId, kb: ViewGet): Promise<Annotation[]>;
+    /**
+     * Enrich reference annotations with resolved document names
+     * Adds _resolvedDocumentName property to annotations that link to documents
+     * @private
+     */
+    private static enrichResolvedReferences;
+    /**
+     * Get resource stats (version info)
+     * @returns Version and timestamp info for the annotations
+     */
+    static getResourceStats(resourceId: ResourceId, kb: ViewGet): Promise<{
+        resourceId: ResourceId;
+        version: number;
+        updatedAt: string;
+    }>;
+    /**
+     * Check if resource exists in view storage
+     */
+    static resourceExists(resourceId: ResourceId, kb: {
+        views: Pick<ViewStorage, 'exists'>;
+    }): Promise<boolean>;
+    /**
+     * Get a single annotation by ID
+     * O(1) lookup using resource ID to access view storage
+     */
+    static getAnnotation(annotationId: AnnotationId, resourceId: ResourceId, kb: ViewGet): Promise<Annotation | null>;
+    /**
+     * List annotations with optional filtering
+     * @param filters - Optional filters like resourceId and type
+     * @throws Error if resourceId not provided (cross-resource queries not supported in view storage)
+     */
+    static listAnnotations(filters: {
+        resourceId?: ResourceId;
+        type?: AnnotationCategory;
+    } | undefined, kb: ViewGet): Promise<Annotation[]>;
+    /**
+     * Get annotation context (selected text with surrounding context)
+     */
+    static getAnnotationContext(annotationId: AnnotationId, resourceId: ResourceId, contextBefore: number, contextAfter: number, kb: ViewGet & {
+        content: ContentReads;
+    }): Promise<AnnotationContextResponse>;
+    /**
+     * Generate AI summary of annotation in context
+     */
+    static generateAnnotationSummary(annotationId: AnnotationId, resourceId: ResourceId, kb: ViewGet & {
+        content: ContentReads;
+    }, inferenceClient: InferenceClient): Promise<ContextualSummaryResponse>;
+    /**
+     * Get resource content as string. ResourceId-keyed (D-CONTENT b): the
+     * primary representation's `storageUri` stays the has-content signal, the
+     * fetch goes by id.
+     */
+    private static getResourceContent;
+    /**
+     * Extract annotation context from resource content
+     */
+    private static extractAnnotationContext;
+    /**
+     * Generate LLM summary of annotation in context
+     * Creates inference client per-request (HTTP handler context)
+     */
+    private static generateSummary;
+}
+
+/**
+ * LLM Context
+ *
+ * Builds comprehensive context for LLM processing of resources
+ * Orchestrates: ResourceContext, GraphContext, AnnotationContext, and generation functions
+ */
+
+/**
+ * What the resource-gather path reads (EXTRACT-LIBRARIAN P2; content re-keyed
+ * by D-CONTENT b) — the graph builder's slice plus this module's own reads.
+ * Pick-derived, never restated. In-process roots satisfy it with
+ * `workingTreeContentReads` over their `kb`; the Librarian passes
+ * `HttpContentTransport`.
+ */
+interface ResourceGatherReads {
+    views: Pick<ViewStorage, 'get'>;
+    content: ContentReads;
+    graph: KnowledgeGraphReads['graph'];
+    vectors: Pick<VectorStore, 'searchByResource'>;
+    weaveProgress: KnowledgeGraphReads['weaveProgress'];
+    smeltProgress: Pick<SmeltProgress, 'whenSettled'>;
+}
+interface LLMContextOptions {
+    depth: number;
+    maxResources: number;
+    includeContent: boolean;
+    includeSummary: boolean;
+    /**
+     * Entity types to exclude from the resource-gather semantic recall
+     * (caller-supplied; e.g. ['Question']). Optional; default none.
+     */
+    excludeEntityTypes?: string[];
+}
+declare class LLMContext {
+    /**
+     * Get comprehensive LLM context for a resource
+     * Includes: main resource, related resources, annotations, graph, content, summary, references
+     */
+    static getResourceContext(resourceId: ResourceId, options: LLMContextOptions, kb: ResourceGatherReads, inferenceClient: InferenceClient, 
+    /**
+     * Bound on the semanticContext read-your-writes barrier
+     * (SMELTER-INDEX-SYNC D3/D5). Operator-owned deployment policy: born in
+     * `[environments.<env>.make-meaning.gather] settleTimeoutMs` (the TOML
+     * loader holds the ONE default, 15s), threaded here as a plain argument
+     * via `MakeMeaningConfig.gather` → Gatherer. Must nest inside downstream
+     * watchdogs (A4) — e.g. my-chat's 90s generation stall watchdog.
+     */
+    settleTimeoutMs: number, logger: Logger): Promise<GatheredContext>;
+}
+
 /**
  * Gatherer Actor
  *
@@ -303,8 +588,16 @@ declare class Stower {
  * by RPC-style services.
  */
 
-declare class Gatherer$1 {
-    private kb;
+/**
+ * The Gatherer's capability slice (EXTRACT-LIBRARIAN P2) — DERIVED as the
+ * intersection of the two gather paths' reads, never restated. A full
+ * `KnowledgeBase` satisfies it structurally; the standalone Librarian (P3)
+ * builds it from the shared stateDir (views), the network clients
+ * (graph/vectors), bus-fed progress folds, and D-CONTENT's answer (content).
+ */
+type GathererStores = AnnotationGatherReads & ResourceGatherReads;
+declare class Gatherer {
+    private stores;
     private eventBus;
     private inferenceClient;
     /** Settle bound for the resource-gather barrier — operator-owned config (D5), threaded from `MakeMeaningConfig.gather`. */
@@ -312,7 +605,7 @@ declare class Gatherer$1 {
     private embeddingProvider;
     private subscriptions;
     private readonly logger;
-    constructor(kb: KnowledgeBase, eventBus: EventBus, inferenceClient: InferenceClient, 
+    constructor(stores: GathererStores, eventBus: EventBus, inferenceClient: InferenceClient, 
     /** Settle bound for the resource-gather barrier — operator-owned config (D5), threaded from `MakeMeaningConfig.gather`. */
     settleTimeoutMs: number, logger: Logger, embeddingProvider: EmbeddingProvider);
     initialize(): Promise<void>;
@@ -335,14 +628,27 @@ declare class Gatherer$1 {
  * is available from auth context.
  */
 
+/**
+ * The Matcher's capability slice (EXTRACT-LIBRARIAN P1) — Pick-derived,
+ * never restated. `graph.getResource` + `views.get` are
+ * `resourceWithViewGrace`'s two halves: the view fallback is a
+ * filesystem-backed projection read, served to the standalone service by
+ * the shared stateDir mount (D6), and to in-process callers by the same
+ * `kb` object, which satisfies this slice structurally.
+ */
+interface MatcherStores {
+    graph: Pick<GraphDatabase, 'listResources' | 'getResource'>;
+    views: Pick<ViewStorage, 'get'>;
+    vectors: Pick<VectorStore, 'searchResources'>;
+}
 declare class Matcher {
-    private kb;
+    private stores;
     private eventBus;
     private inferenceClient;
     private embeddingProvider;
     private subscriptions;
     private readonly logger;
-    constructor(kb: KnowledgeBase, eventBus: EventBus, logger: Logger, inferenceClient: InferenceClient, embeddingProvider: EmbeddingProvider);
+    constructor(stores: MatcherStores, eventBus: EventBus, logger: Logger, inferenceClient: InferenceClient, embeddingProvider: EmbeddingProvider);
     initialize(): Promise<void>;
     private handleSearch;
     /**
@@ -416,6 +722,8 @@ interface LimitsDiscovery {
  *
  * Handles:
  * - browse:resource-requested — single resource metadata (materialized from events)
+ * - browse:anchored-text-by-checksum-requested — the detection workers' read-through
+ *   cache consult: a stored extraction outcome by content identity (ANCHORED-TEXT-TO-SMELTER P2)
  * - browse:resources-requested — list resources
  * - browse:annotations-requested — all annotations for a resource
  * - browse:annotation-requested — single annotation with resolved resource
@@ -429,8 +737,22 @@ interface LimitsDiscovery {
  * - browse:directory-requested — list a project directory, merging fs + ViewStorage
  */
 
+/**
+ * Browser's measured surface of the record (EXTRACT-ARCHIVIST P1) — reads
+ * only, every member a derived slice of its owning type. What is absent is
+ * the point: no appendEvent, no content bytes beyond `retrieve`, no
+ * projectionsDir, no weaveProgress.
+ */
+interface BrowserReads {
+    views: Pick<ViewStorage, 'get' | 'getAll' | 'exists'>;
+    eventStore: EventStoreReads;
+    graph: Pick<GraphDatabase, 'getResource' | 'getResourceReferencedBy' | 'listResources' | 'getEntityTypeStats'>;
+    vectors: Pick<VectorStore, 'searchResources' | 'searchAnnotations'>;
+    content: Pick<WorkingTreeStore, 'retrieve'>;
+    anchoredText: Pick<AnchoredTextStore, 'read'>;
+    smeltProgress: Pick<SmeltProgress, 'whenSettled'>;
+}
 declare class Browser {
-    private views;
     private kb;
     private eventBus;
     private project;
@@ -441,7 +763,7 @@ declare class Browser {
     private embeddingProvider;
     private subscriptions;
     private readonly logger;
-    constructor(views: ViewStorage, kb: KnowledgeBase, eventBus: EventBus, project: SemiontProject, config: MakeMeaningConfig, 
+    constructor(kb: BrowserReads, eventBus: EventBus, project: SemiontProject, config: MakeMeaningConfig, 
     /** Discovered per-(provider, model) ceilings for the roster (INFERENCE-LIMITS-EXPOSURE P2). */
     limitsDiscovery: LimitsDiscovery, 
     /** For the semantic search fallback — mandatory (MANDATORY-EMBEDDING D0). */
@@ -462,6 +784,17 @@ declare class Browser {
      * this design exists to avoid.
      */
     private handleAnchoredText;
+    /**
+     * Serve the checksum-addressed consult (ANCHORED-TEXT-TO-SMELTER P2, D2) —
+     * the detection workers' read-through cache. The caller computed the key
+     * from bytes it already holds, so unlike the resource-addressed read there
+     * is nothing to resolve and no settle barrier: with no resourceId there is
+     * no content generation to wait on, and a miss means "extract it yourself".
+     * A hit — success or decline — is served whole, so the caller runs neither
+     * parser nor engine. Read-only over the wire: the Smelter is the sole
+     * writer and never answers here.
+     */
+    private handleAnchoredTextByChecksum;
     private handleBrowseResource;
     private handleBrowseResources;
     private handleBrowseAnnotations;
@@ -491,13 +824,24 @@ declare class Browser {
  * "Clone tokens produce new resources — that's yield."
  */
 
+/**
+ * What the clone workflow touches (EXTRACT-ARCHIVIST P1/P3): resource
+ * metadata via views, and `resolveUri` for existence checks — never bytes
+ * (GATEWAY.md D4a). The clone's own bytes are stored by the gateway's
+ * upload path before `yield:clone-create` arrives; this actor holds NO
+ * byte capability at all.
+ */
+interface CloneTokenStores {
+    views: Pick<ViewStorage, 'get'>;
+    content: Pick<WorkingTreeStore, 'resolveUri'>;
+}
 declare class CloneTokenManager {
-    private kb;
+    private stores;
     private eventBus;
     private subscriptions;
     private readonly logger;
     private readonly tokens;
-    constructor(kb: KnowledgeBase, eventBus: EventBus, logger: Logger);
+    constructor(stores: CloneTokenStores, eventBus: EventBus, logger: Logger);
     initialize(): Promise<void>;
     private handleGenerateToken;
     private handleGetResource;
@@ -521,7 +865,7 @@ declare class CloneTokenManager {
  * These are the five access actors. Two projection-pipeline actors complete
  * the seven, and BOTH run standalone (D4: the projections are part of their
  * stores' stacks, not of the embedding process): the Weaver (weaver-main →
- * graph) and the Smelter (smelter-main → vectors). The backend keeps only
+ * graph) and the Smelter (smelter-main → vectors). The gateway keeps only
  * the Weaver's `weave:applied` fold (kb.weaveProgress).
  *
  * EventBus, JobQueue, and workers are peers to KnowledgeSystem, not members.
@@ -530,12 +874,24 @@ declare class CloneTokenManager {
 interface KnowledgeSystem {
     kb: KnowledgeBase;
     stower: Stower;
-    gatherer: Gatherer$1;
+    gatherer: Gatherer;
     matcher: Matcher;
     browser: Browser;
     cloneTokenManager: CloneTokenManager;
     stop: () => Promise<void>;
 }
+/**
+ * The gateway's view of the system after EXTRACT-ARCHIVIST P3 and
+ * EXTRACT-LIBRARIAN P3: the Archivist service owns
+ * Stower/Browser/CloneTokenManager and the Librarian owns Matcher and
+ * Gatherer, out-of-process. The gateway hosts NO actors — `kb` here is a
+ * READ bundle over the shared stateDir for the handler subset and the
+ * gateway's routes; the one writer is the Archivist (D4b/D6).
+ */
+interface GatewayKnowledgeSystem {
+    kb: KnowledgeBase;
+    stop: () => Promise<void>;
+}
 declare function stopKnowledgeSystem(ks: KnowledgeSystem): Promise<void>;
 
 /**
@@ -549,7 +905,7 @@ interface MakeMeaningService {
     knowledgeSystem: KnowledgeSystem;
     jobQueue: JobQueue;
     /**
-     * The one SemiontProject this backend is serving — the same instance the
+     * The one SemiontProject this gateway is serving — the same instance the
      * KnowledgeSystem, the job queue and the bus handlers were built from.
      *
      * Exposed so request handlers reach for it instead of improvising their own
@@ -561,17 +917,132 @@ interface MakeMeaningService {
     project: SemiontProject;
     stop: () => Promise<void>;
 }
+/**
+ * The in-process composition root: every access actor and handler on one
+ * caller-owned bus, for `LocalTransport` consumers — the SDK test seam and
+ * embedding. Production composes the same actors as extracted services
+ * (archivist-main, librarian-main); this second root is supported, not legacy.
+ */
 declare function startMakeMeaning(project: SemiontProject, config: MakeMeaningConfig, eventBus: EventBus, logger: Logger, options?: {
     skipRebuild?: boolean;
 }): Promise<MakeMeaningService>;
+interface GatewayMakeMeaningService {
+    jobQueue: JobQueue;
+    /** Name + the state-mount paths. NOT a `SemiontProject`: the gateway
+     *  mounts no KB tree, and the type is what says so (SINGLE-KB-MOUNT P5). */
+    state: SemiontState;
+    stop: () => Promise<void>;
+}
+/**
+ * The gateway's composition root: everything startMakeMeaning builds EXCEPT
+ * the actors, which have all left. The Archivist (archivist-main) owns
+ * Stower/Browser/CloneTokenManager, enrichment, the entity-type bootstrap +
+ * warm, and the view rebuild; the Librarian (librarian-main) owns Matcher
+ * and Gatherer (EXTRACT-LIBRARIAN P1/P3).
+ *
+ * What remains is the JOB QUEUE, and nothing else. It used to call
+ * `connectStores` as well — a graph connection, a vector store, an embedding
+ * provider, an event store, a working tree and an anchored-text store — and
+ * SINGLE-KB-MOUNT P5 measured that **no consumer read any of it**: the whole
+ * `kb` bundle existed to be constructed. Deleting it is what lets the gateway
+ * take a `SemiontState` instead of a `SemiontProject`, and therefore what
+ * lets P6 drop the `/kb` mount: the type no longer HAS a KB root to want.
+ *
+ * The job queue lives on the shared state mount (D6), so what is left needs
+ * no tree at all.
+ */
+declare function startMakeMeaningGateway(state: SemiontState, config: MakeMeaningConfig, eventBus: EventBus, logger: Logger): Promise<GatewayMakeMeaningService>;
 
 /**
- * LocalTransport — `ITransport` for an in-process `KnowledgeSystem`.
+ * The Archivist's HTTP surface: the /health probe, the D1 sequence-ranged
+ * event read path (EXTRACT-ARCHIVIST P2a), and the content write and read
+ * paths (SINGLE-KB-MOUNT P2/P3).
+ *
+ * ⚠️ STANDING RULE, load-bearing: **this surface serves the KB tree, and
+ * nothing else.** `browse:*`, `match:*`, `gather:*` stay on the bus. The
+ * earlier, narrower rule — exactly one customer, the gateway's SSE resume —
+ * was re-examined by SINGLE-KB-MOUNT D1 (2026-08-29), which reversed
+ * GATEWAY.md D4a: the Archivist is the knowledge base's storage authority,
+ * and this HTTP surface is how bytes and record reads reach it (D2: bytes
+ * ride HTTP, never the bus). That is a change of design, not a widened seam;
+ * an endpoint that is not a KB-tree read or write still does not belong here.
+ *
+ * D1 (settled 2026-08-27): moving the event store out of the gateway breaks
+ * `/bus/subscribe`'s `Last-Event-ID` replay, which reads the log in-process
+ * (apps/gateway/src/routes/bus.ts). The answer is one narrow call —
+ * the events for ONE resource from ONE sequence — which the gateway calls
+ * directly:
+ *
+ *   GET /events/:resourceId?fromSequence=N   (inclusive, like the filter it
+ *   mirrors: `queryEvents(rId, { fromSequence })`; the caller does the +1)
+ *
+ * SINGLE-KB-MOUNT P2/P3: the gateway stops touching the shared mount for
+ * bytes and proxies both directions here —
+ *
+ *   PUT /content/:storageUri[?checksum=sha256hex]   (storageUri URI-encoded
+ *   as one path segment; an optional checksum is verified BEFORE anything is
+ *   written, and a disagreement is a 409)
+ *
+ *   GET /resources/:id/content                      (the bytes, streamed,
+ *   with the media type the record stores; the 404 carries `reason` so the
+ *   gateway can serve its two different not-found messages)
+ *
+ * **The addresses differ because the lifecycle does**, not by oversight: at
+ * write time neither the resource nor its view exists — bytes land before the
+ * event — so the write has only a tree address to be addressed by, while the
+ * read has a record. Both go through ONE resolution (`representation.ts`);
+ * neither restates where bytes live.
+ *
+ * The write is `noGit` and emits nothing: the event contract is untouched —
+ * the Stower still `register`s the bytes from disk and does the one `git add`
+ * on event apply (GATEWAY.md D4b, single-writer).
+ *
+ * Auth: callers authenticate with the same SEMIONT_WORKER_SECRET the
+ * agent-token flow uses — service-to-service, one shared deployment fact.
+ * With no secret configured, every path but /health refuses loudly (503)
+ * rather than serving unauthenticated: absence fails, it is never a
+ * default-open.
+ */
+
+interface ArchivistServerDeps {
+    /** The record's log — the read half only. */
+    events: Pick<EventLog, 'queryEvents'>;
+    /** The KB tree's byte paths. `register` and the git index stay the
+     *  Stower's on event apply; reads go through `resolveRepresentation`. */
+    content: Pick<WorkingTreeStore, 'store' | 'retrieveStream'>;
+    /** The record's views — the resource half of the one resolution. */
+    views: Pick<ViewStorage, 'get'>;
+    /** Shared service secret; empty disables everything but /health (503), never opens it. */
+    workerSecret: string;
+    /** Liveness payload for /health — actor states, counters. */
+    health: () => Record<string, unknown>;
+    /**
+     * The KB working tree's current branch, `null` outside a git checkout.
+     *
+     * A live fact about the tree, so it is answered by the process that HOLDS
+     * the tree (SINGLE-KB-MOUNT P5). The gateway used to read it off its own
+     * `/kb` mount; the launcher cannot stage it because a branch switch does
+     * not restart the stack, and a staged value would quietly go stale.
+     */
+    branch: () => string | null;
+    logger: Logger;
+}
+declare function createArchivistServer(deps: ArchivistServerDeps): Server;
+
+/**
+ * LocalTransport — `ITransport` onto an in-process make-meaning `EventBus`.
+ *
+ * It takes NO knowledge system. This is a bus transport: it publishes emits
+ * onto the bus and bridges the reply channels back. It never touched a
+ * `KnowledgeSystem` — the field that used to be here was declared and never
+ * read, which made the transport look coupled to the monolith's shape when it
+ * is coupled only to the bus. Whatever process hosts the actors on that bus
+ * satisfies it.
  *
  * Bus-ownership pattern (see `docs/protocol/TRANSPORT-CONTRACT.md`):
  *   - The caller owns a make-meaning `EventBus` and passes it to both
  *     `startMakeMeaning` and `LocalTransport` so the transport can publish
- *     directly onto the bus the `KnowledgeSystem` actors are listening on.
+ *     directly onto the bus the actors are listening on.
  *   - `SemiontClient` constructs its own `clientBus` and calls
  *     `bridgeInto(clientBus)` during construction. `LocalTransport`
  *     subscribes to every `BRIDGED_CHANNELS` entry on the make-meaning bus
@@ -579,22 +1050,17 @@ declare function startMakeMeaning(project: SemiontProject, config: MakeMeaningCo
  *   - The bus reference flows client → transport, never the other way.
  *
  * LocalTransport implements `ITransport` only. Auth, admin, and exchange
- * (`IBackendOperations`) are HTTP-shaped concepts that don't apply
+ * (`IGatewayOperations`) are HTTP-shaped concepts that don't apply
  * in-process — local mode runs as a single host-process identity supplied
  * at construction, with no token/credential lifecycle. A `SemiontClient`
  * built over this transport has no `.auth` / `.admin` namespaces.
  */
 
 interface LocalTransportConfig {
-    /**
-     * The in-process knowledge system. Lifetime is owned by the caller —
-     * `dispose()` on this transport does not stop the KnowledgeSystem.
-     */
-    knowledgeSystem: KnowledgeSystem;
     /**
      * The make-meaning `EventBus`. Must be the same instance passed to
-     * `startMakeMeaning` so that emits land on the bus KnowledgeSystem
-     * actors are subscribed to.
+     * `startMakeMeaning` so that emits land on the bus the actors are
+     * subscribed to.
      */
     eventBus: EventBus;
     /**
@@ -641,8 +1107,13 @@ declare class LocalTransport implements ITransport {
 }
 
 /**
- * LocalContentTransport — `IContentTransport` for an in-process
- * `KnowledgeSystem`.
+ * LocalContentTransport — `IContentTransport` over an in-process
+ * `KnowledgeBase`.
+ *
+ * Takes the KB, not the whole `KnowledgeSystem`: every read below goes through
+ * `kb.*` and no actor is ever touched. The wider parameter forced callers that
+ * legitimately hold only a KB to cast (`representation.test.ts` used
+ * `as never`), which is a cast hiding nothing but an over-wide signature.
  *
  * Reads go straight to `kb.views` (resource lookup) + `kb.content`
  * (byte retrieval). No network, no auth — local mode runs as a single
@@ -657,8 +1128,8 @@ declare class LocalTransport implements ITransport {
 
 type GetResourceResponse = components['schemas']['GetResourceResponse'];
 declare class LocalContentTransport implements IContentTransport {
-    private readonly ks;
-    constructor(ks: KnowledgeSystem);
+    private readonly kb;
+    constructor(kb: KnowledgeBase);
     putBinary(_request: PutBinaryRequest, _options?: PutBinaryOptions): Promise<{
         resourceId: ResourceId;
     }>;
@@ -704,6 +1175,12 @@ declare class LocalContentTransport implements IContentTransport {
         stream: ReadableStream<Uint8Array>;
         contentType: string;
     }>;
+    /**
+     * The same resolution the wire path serves, buffered — local and hosted
+     * modes must answer identically, which they did not before
+     * SINGLE-KB-MOUNT P3: this resolved through `representations[].storageUri`,
+     * a field `ViewMaterializer` never writes, so every binary read here threw.
+     */
     private loadBinary;
     /**
      * Assemble the resource's JSON-LD graph in-process from the KB — the local
@@ -718,7 +1195,7 @@ declare class LocalContentTransport implements IContentTransport {
 
 /**
  * Adapt a raw in-process `EventBus` to the `BusRequestPrimitive` that
- * `busRequest` consumes. Lets backend-internal callers (bootstrap, event
+ * `busRequest` consumes. Lets gateway-internal callers (bootstrap, event
  * replay, linked-data import) use the same confirmed request/reply path as the
  * SDK — `busRequest(asBusRequestPrimitive(eventBus), …)` — instead of
  * hand-rolled `race(domain-event, *-failed, timeout)` blocks. The reply is
@@ -742,13 +1219,42 @@ declare function asBusRequestPrimitive(eventBus: EventBus): BusRequestPrimitive;
  *
  * This is a deferred-ack pattern: the result event attests that Stower has
  * persisted the annotation, not merely that the command was well-formed.
+ *
+ * ## The annotatability gate (MEDIA-CAPABILITY-DISPATCH D6)
+ *
+ * Every GUI and SDK caller travels `mark:create-request` and is checked here.
+ * The check is deliberately NOT on `mark:create`, which Stower consumes: that
+ * channel is the fact-writing path, and gating it would need a leniency flag
+ * for restore — the compatibility switch D6 was written to avoid.
+ *
+ * D6's original second emitter, the TypeScript import/replay path, was deleted
+ * by EXPORT-VIA-LAUNCHER P3 (2026-08-27), so nothing travels the ungated
+ * channel today. The separation is kept anyway, because restore returns in the
+ * launcher and its fact-writing seam is still an open decision (that plan's
+ * P5) — a restore that re-subjected historical facts to this gate would be the
+ * 2026-07-09 "events are facts, commands are requests" ruling undone.
  */
-declare function registerAnnotationAssemblyHandler(eventBus: EventBus, parentLogger: Logger): void;
+declare function registerAnnotationAssemblyHandler(eventBus: EventBus, kb: {
+    views: Pick<ViewStorage, 'get'>;
+}, parentLogger: Logger): void;
 
-interface Gatherer {
-    generateAnnotationSummary(annId: AnnotationId, resId: ResourceId): Promise<Record<string, unknown>>;
-}
-declare function registerAnnotationLookupHandlers(eventBus: EventBus, kb: KnowledgeBase, gatherer: Gatherer, parentLogger: Logger): void;
+/**
+ * Annotation lookup handlers — split along the EXTRACT-LIBRARIAN P3 cutover:
+ *
+ * - `browse:annotation-context-requested` is a pure views+content read with
+ *   no Gatherer. It registers wherever those capabilities live — the gateway
+ *   and the standalone root.
+ * - `gather:summary-requested` calls the Gatherer's inference path, so it
+ *   follows the Gatherer (the Archivist's D2-i pattern): the standalone root
+ *   and librarian-main register it beside their Gatherer; the gateway does
+ *   NOT.
+ */
+
+declare function registerAnnotationContextHandler(eventBus: EventBus, kb: {
+    views: Pick<ViewStorage, 'get'>;
+    content: ContentReads;
+}, parentLogger: Logger): void;
+declare function registerGatherSummaryHandler(eventBus: EventBus, gatherer: Pick<Gatherer, 'generateAnnotationSummary'>, parentLogger: Logger): void;
 
 /**
  * Handles `bind:update-body` — the Bind flow's authoritative "apply body
@@ -768,7 +1274,7 @@ declare function registerAnnotationLookupHandlers(eventBus: EventBus, kb: Knowle
  */
 declare function registerBindUpdateBodyHandler(eventBus: EventBus, parentLogger: Logger): void;
 
-declare function registerJobCommandHandlers(eventBus: EventBus, jobQueue: JobQueue, project: SemiontProject, parentLogger: Logger): void;
+declare function registerJobCommandHandlers(eventBus: EventBus, jobQueue: JobQueue, state: SemiontState, parentLogger: Logger): void;
 
 /**
  * Bus command handlers — pure bus-event translators that bridge the
@@ -777,7 +1283,7 @@ declare function registerJobCommandHandlers(eventBus: EventBus, jobQueue: JobQue
  * `gather:summary-requested`) to the underlying make-meaning pipeline
  * (Stower, Browser, Gatherer, JobQueue).
  *
- * These ran in `apps/backend` historically because the HTTP gateway was
+ * These ran in `apps/gateway` historically because the HTTP gateway was
  * the only consumer that needed them. They are not HTTP-specific — moving
  * them here means `LocalTransport` consumers (and any future transport)
  * get the same contract automatically.
@@ -787,7 +1293,7 @@ declare function registerJobCommandHandlers(eventBus: EventBus, jobQueue: JobQue
  * Register all bus command handlers on the make-meaning EventBus. Called
  * during `startMakeMeaning` after the JobQueue and KnowledgeSystem exist.
  */
-declare function registerBusHandlers(eventBus: EventBus, knowledgeSystem: KnowledgeSystem, jobQueue: JobQueue, project: SemiontProject, logger: Logger): void;
+declare function registerBusHandlers(eventBus: EventBus, knowledgeSystem: Pick<KnowledgeSystem, 'kb' | 'gatherer'>, jobQueue: JobQueue, state: SemiontState, logger: Logger): void;
 
 /**
  * Entity Types Bootstrap
@@ -824,7 +1330,7 @@ declare function bootstrapEntityTypes(eventBus: EventBus, eventStore: EventStore
 /**
  * Read entity types from view storage projection
  */
-declare function readEntityTypesProjection(project: SemiontProject): Promise<string[]>;
+declare function readEntityTypesProjection(state: SemiontState): Promise<string[]>;
 
 /**
  * SmelterActorStateUnit — domain-event fan-in for the Smelter worker.
@@ -862,8 +1368,8 @@ declare function createSmelterActorStateUnit(options: SmelterActorStateUnitOptio
  *
  * Consumes the smelter-relevant domain events surfaced by
  * `SmelterActorStateUnit.events$`, reads resource content via the injected
- * `IContentTransport` (HTTP verbatim mode in worker deployments — the
- * stored bytes, untouched), chunks and embeds it via the configured
+ * `ContentReads` (in the fleet, the Archivist's byte route — the stored
+ * bytes, untouched), chunks and embeds it via the configured
  * EmbeddingProvider, and indexes vectors into the VectorStore (Qdrant).
  * `smelter-main` is the container entry point that wires this up.
  *
@@ -950,7 +1456,19 @@ declare class Smelter {
     private rebuildAnchors$;
     private vectorStore;
     private embeddingProvider;
+    /** Byte reads only — the Smelter never writes through this seam, so it
+     *  declares `ContentReads` and any implementation satisfies it: the
+     *  Archivist's client in the fleet, the working tree in-process. */
     private content;
+    /**
+     * The anchored-text store, held DIRECTLY (ANCHORED-TEXT-TO-SMELTER P1).
+     *
+     * It used to be built here over the content transport, which put the
+     * gateway between this process and an artifact it produces itself. The
+     * Smelter now owns the store on its own mount and is the only writer;
+     * every read of it moved to the Archivist's bus channels.
+     */
+    private anchoredStore;
     private bus;
     private chunkingConfig;
     private timing;
@@ -976,8 +1494,20 @@ declare class Smelter {
     private drainChain;
     constructor(events$: Observable<SmelterEvent>, 
     /** `smelt:rebuild-anchors` commands — a separate stream, never the event mailbox (see SmelterActorStateUnit). */
-    rebuildAnchors$: Observable<EventMap['smelt:rebuild-anchors']>, vectorStore: VectorStore, embeddingProvider: EmbeddingProvider, content: IContentTransport, bus: BusRequestPrimitive, chunkingConfig: ChunkingConfig, timing: SmelterTiming, logger: Logger);
-    private readonly anchoredStore;
+    rebuildAnchors$: Observable<EventMap['smelt:rebuild-anchors']>, vectorStore: VectorStore, embeddingProvider: EmbeddingProvider, 
+    /** Byte reads only — the Smelter never writes through this seam, so it
+     *  declares `ContentReads` and any implementation satisfies it: the
+     *  Archivist's client in the fleet, the working tree in-process. */
+    content: ContentReads, 
+    /**
+     * The anchored-text store, held DIRECTLY (ANCHORED-TEXT-TO-SMELTER P1).
+     *
+     * It used to be built here over the content transport, which put the
+     * gateway between this process and an artifact it produces itself. The
+     * Smelter now owns the store on its own mount and is the only writer;
+     * every read of it moved to the Archivist's bus channels.
+     */
+    anchoredStore: AnchoredTextStore, bus: BusRequestPrimitive, chunkingConfig: ChunkingConfig, timing: SmelterTiming, logger: Logger);
     get eventsProcessed(): number;
     get reconcileState(): ReconcileState;
     initialize(): void;
@@ -1135,228 +1665,6 @@ declare class Smelter {
     private listAllResources;
 }
 
-/**
- * Exchange Format Manifest Types
- *
- * Defines the metadata structures for backup archives.
- * The manifest is the first entry in an archive and describes its contents.
- */
-declare const BACKUP_FORMAT: "semiont-backup";
-declare const FORMAT_VERSION = 1;
-interface BackupManifestHeader {
-    format: typeof BACKUP_FORMAT;
-    version: number;
-    exportedAt: string;
-    sourceUrl: string;
-    stats: {
-        streams: number;
-        events: number;
-        blobs: number;
-        contentBytes: number;
-    };
-}
-interface BackupStreamSummary {
-    stream: string;
-    eventCount: number;
-}
-declare const LINKED_DATA_FORMAT: "semiont-linked-data";
-interface LinkedDataManifest {
-    '@context': Record<string, string>;
-    '@type': string;
-    'semiont:format': typeof LINKED_DATA_FORMAT;
-    'semiont:version': number;
-    'dct:created': string;
-    'prov:wasGeneratedBy': {
-        '@type': string;
-        'prov:used': string;
-    };
-    'semiont:entityTypes': string[];
-    'void:entities': number;
-}
-declare function isBackupManifest(obj: unknown): obj is BackupManifestHeader;
-declare function validateManifestVersion(version: number): void;
-
-/**
- * Backup Exporter
- *
- * Produces a lossless tar.gz archive of the system of record:
- * - Event log (all streams, JSONL format)
- * - Working-tree content (archived as checksum-named blobs)
- *
- * Reads events via EventStore and content via WorkingTreeStore.
- * The archive can restore a complete knowledge base.
- */
-
-/** Subset of EventStore used by the backup exporter. */
-interface BackupEventStoreReader {
-    log: {
-        storage: {
-            getAllResourceIds(): Promise<ResourceId[]>;
-        };
-        getEvents(resourceId: ResourceId): Promise<StoredEvent[]>;
-    };
-}
-/** Subset of WorkingTreeStore used by the backup exporter. */
-interface BackupContentReader {
-    retrieve(storageUri: string): Promise<Buffer>;
-}
-interface BackupExporterOptions {
-    eventStore: BackupEventStoreReader;
-    content: BackupContentReader;
-    sourceUrl: string;
-    logger?: Logger;
-}
-/**
- * Export a full backup of the knowledge base to a tar.gz stream.
- *
- * Archive structure:
- *   .semiont/manifest.jsonl              - Format metadata + per-stream checksums
- *   .semiont/events/__system__.jsonl     - System events
- *   .semiont/events/{resourceId}.jsonl   - Per-resource events
- *   {checksum}.{ext}                     - Content blobs (root level)
- */
-declare function exportBackup(options: BackupExporterOptions, output: Writable): Promise<BackupManifestHeader>;
-
-/**
- * Event Replay
- *
- * Replays parsed JSONL event streams through the EventBus.
- * Each domain event is translated to the corresponding command event
- * (e.g. yield:created → yield:create), emitted, and the result
- * event is awaited before proceeding (backpressure).
- *
- * Content blobs are resolved lazily via a lookup function so that
- * the caller controls memory strategy (streaming, on-disk, etc.).
- */
-
-/**
- * Resolves a content blob by its checksum.
- * Returned by the caller so replay doesn't dictate memory strategy.
- */
-type ContentBlobResolver = (checksum: string) => Buffer | undefined;
-interface ReplayStats {
-    eventsReplayed: number;
-    resourcesCreated: number;
-    annotationsCreated: number;
-    entityTypesAdded: number;
-}
-
-/**
- * Backup Importer
- *
- * Restores a knowledge base from a backup tar.gz archive.
- * Replays events through the EventBus → Stower pipeline so all
- * derived state (materialized views, graph) rebuilds naturally.
- *
- * Accepts a Readable stream so callers can pipe directly from disk
- * or network without buffering the entire archive first.
- * Content blobs are resolved lazily via a closure over the parsed
- * tar entries, avoiding a separate copy of all blob data in memory.
- */
-
-interface BackupImporterOptions {
-    eventBus: EventBus;
-    /** Replay appends historical events directly (facts, not commands). */
-    eventStore: EventStore;
-    contentStore: WorkingTreeStore;
-    logger?: Logger;
-}
-interface BackupImportResult {
-    manifest: BackupManifestHeader;
-    stats: ReplayStats;
-}
-/**
- * Import a backup archive by replaying events through the EventBus.
- *
- * Flow:
- *   1. Stream and decompress tar.gz entries
- *   2. Parse .semiont/manifest.jsonl → validate format
- *   3. Build blob resolver over root-level content entries
- *   4. Replay .semiont/events/__system__.jsonl (entity types)
- *   5. Replay each .semiont/events/{resourceId}.jsonl (resources, annotations)
- *
- * Events flow: importer → EventBus → Stower → EventStore + Views
- */
-declare function importBackup(archive: Readable, options: BackupImporterOptions): Promise<BackupImportResult>;
-
-/**
- * Linked Data Exporter
- *
- * Produces a JSON-LD tar.gz archive from the current state of the knowledge base.
- * Reads materialized views (not the event log) for a fast, current-state export.
- *
- * Archive structure:
- *   .semiont/manifest.jsonld                - JSON-LD manifest with format metadata
- *   .semiont/resources/{resourceId}.jsonld   - One JSON-LD document per resource
- *   {checksum}.{ext}                        - Content blobs (root level)
- */
-
-/** Subset of ViewStorage used by the linked-data exporter. */
-interface LinkedDataViewReader {
-    getAll(): Promise<Array<{
-        resource: ResourceDescriptor;
-        annotations: {
-            annotations: Annotation[];
-        };
-    }>>;
-}
-/** Subset of WorkingTreeStore used by the linked-data exporter. */
-interface LinkedDataContentReader {
-    retrieve(storageUri: string): Promise<Buffer>;
-}
-interface LinkedDataExporterOptions {
-    views: LinkedDataViewReader;
-    content: LinkedDataContentReader;
-    sourceUrl: string;
-    entityTypes: string[];
-    includeArchived?: boolean;
-    logger?: Logger;
-}
-/**
- * Export the knowledge base as a JSON-LD tar.gz archive.
- */
-declare function exportLinkedData(options: LinkedDataExporterOptions, output: Writable): Promise<LinkedDataManifest>;
-
-/**
- * Linked Data Importer
- *
- * Creates resources from a JSON-LD tar.gz archive exported by the linked-data exporter.
- * Unlike the backup importer, this is lossy — new resources are created (new IDs),
- * no event history is preserved. Entity types are restored from the manifest.
- *
- * Parses .semiont/manifest.jsonld for format validation and entity types,
- * then processes each .semiont/resources/{resourceId}.jsonld to create
- * resources and annotations via the EventBus → Stower pipeline.
- */
-
-interface LinkedDataImporterOptions {
-    eventBus: EventBus;
-    contentStore: WorkingTreeStore;
-    userId: UserId;
-    logger?: Logger;
-}
-interface LinkedDataImportResult {
-    manifest: LinkedDataManifest;
-    resourcesCreated: number;
-    annotationsCreated: number;
-    entityTypesAdded: number;
-}
-/**
- * Import a JSON-LD archive by creating resources through the EventBus.
- *
- * Flow:
- *   1. Stream and decompress tar.gz entries
- *   2. Parse .semiont/manifest.jsonld → validate format
- *   3. Build blob resolver over root-level content entries
- *   4. Add entity types from manifest via frame:add-entity-type
- *   5. For each .semiont/resources/{id}.jsonld:
- *      a. Parse JSON-LD document
- *      b. Resolve content blob by checksum from representations
- *      c. Emit yield:create → await yield:created
- *      d. For each annotation: emit mark:create → await mark:created
- */
-declare function importLinkedData(archive: Readable, options: LinkedDataImporterOptions): Promise<LinkedDataImportResult>;
-
 /**
  * Resource Operations
  *
@@ -1390,6 +1698,39 @@ declare class ResourceOperations {
      * Create a new resource via EventBus → Stower
      */
     static createResource(input: CreateResourceInput, userId: UserId, eventBus: EventBus): Promise<ResourceId>;
+    /**
+     * Persist a CLONE via EventBus → Stower.
+     *
+     * Separate from `createResource` because a clone is a separate fact: it
+     * names its parent, and `yield:cloned` requires that name. Callers reach
+     * this only after the CloneTokenManager has validated the token — it is the
+     * inner half of the flow, not a public entry point.
+     */
+    static persistClone(input: {
+        name: string;
+        storageUri: string;
+        contentChecksum: string;
+        byteSize: number;
+        format: ContentFormat;
+        parentResourceId: string;
+        entityTypes?: string[];
+        language?: string;
+    }, userId: UserId, eventBus: EventBus): Promise<ResourceId>;
+    /**
+     * Create a resource from a clone token via EventBus → CloneTokenManager.
+     * The bytes are already stored (the gateway's upload path, `noGit` — the
+     * Archivist's register does the one `git add`, D4b); the command carries
+     * storage coordinates only (EXTRACT-ARCHIVIST P3, D4a).
+     */
+    static createFromCloneToken(input: {
+        token: string;
+        name: string;
+        storageUri: string;
+        contentChecksum: string;
+        byteSize: number;
+        format: ContentFormat;
+        archiveOriginal?: boolean;
+    }, userId: UserId, eventBus: EventBus): Promise<ResourceId>;
 }
 
 /**
@@ -1418,15 +1759,21 @@ declare class AnnotationOperations {
     /**
      * Create a new annotation via EventBus → Stower
      */
-    static createAnnotation(request: CreateAnnotationRequest, userId: UserId, creator: Agent, eventBus: EventBus): Promise<CreateAnnotationResult>;
+    static createAnnotation(request: CreateAnnotationRequest, userId: UserId, creator: Agent, eventBus: EventBus, kb: {
+        views: Pick<ViewStorage, 'get'>;
+    }): Promise<CreateAnnotationResult>;
     /**
      * Update annotation body via EventBus → Stower
      */
-    static updateAnnotationBody(id: string, request: UpdateAnnotationBodyRequest, userId: UserId, eventBus: EventBus, kb: KnowledgeBase): Promise<UpdateAnnotationBodyResult>;
+    static updateAnnotationBody(id: string, request: UpdateAnnotationBodyRequest, userId: UserId, eventBus: EventBus, kb: {
+        views: Pick<ViewStorage, 'get'>;
+    }): Promise<UpdateAnnotationBodyResult>;
     /**
      * Delete an annotation via EventBus → Stower
      */
-    static deleteAnnotation(id: string, resourceIdStr: string, userId: UserId, eventBus: EventBus, kb: KnowledgeBase, logger?: Logger): Promise<void>;
+    static deleteAnnotation(id: string, resourceIdStr: string, userId: UserId, eventBus: EventBus, kb: {
+        views: Pick<ViewStorage, 'get'>;
+    }, logger?: Logger): Promise<void>;
 }
 
 /**
@@ -1439,6 +1786,14 @@ declare class AnnotationOperations {
  * single-index reads; anything that FUSES sources belongs to the Matcher.
  */
 
+/** What the listing paths read (EXTRACT-ARCHIVIST P1): lexical search in
+ *  the graph, unsearched listings from views, the semantic fallback in the
+ *  vector index — plus `resourceWithViewGrace`'s graph-first hydration. */
+interface ListResourcesReads {
+    views: Pick<ViewStorage, 'get' | 'getAll'>;
+    graph: Pick<GraphDatabase, 'listResources' | 'getResource'>;
+    vectors: Pick<VectorStore, 'searchResources'>;
+}
 interface ListResourcesFilters {
     search?: string;
     archived?: boolean;
@@ -1481,7 +1836,9 @@ declare class ResourceContext {
     /**
      * Get resource metadata from view storage
      */
-    static getResourceMetadata(resourceId: ResourceId, kb: KnowledgeBase): Promise<ResourceDescriptor | null>;
+    static getResourceMetadata(resourceId: ResourceId, kb: {
+        views: Pick<ViewStorage, 'get'>;
+    }): Promise<ResourceDescriptor | null>;
     /**
      * List resources, optionally filtered, as one page plus the size of the whole
      * match set. Every filter is applied before pagination on both paths — a
@@ -1496,7 +1853,7 @@ declare class ResourceContext {
      * barrier-stamped projection, so an unsearched listing is read-your-writes
      * where the graph is only eventually consistent.
      */
-    static listResources(filters: ListResourcesFilters | undefined, kb: KnowledgeBase, semantic: SemanticFallbackDeps): Promise<ListResourcesResult>;
+    static listResources(filters: ListResourcesFilters | undefined, kb: ListResourcesReads, semantic: SemanticFallbackDeps): Promise<ListResourcesResult>;
     /**
      * Answer an empty lexical search from the vector index (SEMANTIC-FALLBACK):
      * embed the query once, fold chunk hits per resource, floor them, and label
@@ -1517,189 +1874,21 @@ declare class ResourceContext {
      * Add content previews to resources (for search results)
      * Retrieves and decodes the first 200 characters of each resource's primary representation
      */
-    static addContentPreviews(resources: ResourceDescriptor[], kb: KnowledgeBase): Promise<Array<ResourceDescriptor & {
+    static addContentPreviews(resources: ResourceDescriptor[], kb: {
+        content: Pick<WorkingTreeStore, 'retrieve'>;
+    }): Promise<Array<ResourceDescriptor & {
         content: string;
     }>>;
     /**
      * Get full content for a resource
-     * Retrieves and decodes the primary representation
-     */
-    static getResourceContent(resource: ResourceDescriptor, kb: KnowledgeBase): Promise<string | undefined>;
-}
-
-/**
- * Annotation Context
- *
- * Assembles annotation context from view storage and content store.
- * Provides methods for:
- * - Getting resource annotations
- * - Building LLM context for annotations
- * - Extracting annotation text context
- * - Generating AI summaries
- */
-
-type AnnotationContextResponse = components['schemas']['AnnotationContextResponse'];
-type ContextualSummaryResponse = components['schemas']['ContextualSummaryResponse'];
-interface BuildContextOptions {
-    includeSourceContext?: boolean;
-    includeTargetContext?: boolean;
-    contextWindow?: number;
-}
-declare class AnnotationContext {
-    /**
-     * Build LLM context for an annotation
-     *
-     * @param annotationId - Bare annotation ID
-     * @param resourceId - Source resource ID
-     * @param kb - Knowledge base stores
-     * @param options - Context building options
-     * @param inferenceClient - Optional inference client for target context summary
-     * @returns Rich context for LLM processing
-     * @throws Error if annotation or resource not found
-     */
-    static buildLLMContext(annotationId: AnnotationId, resourceId: ResourceId, kb: KnowledgeBase, embeddingProvider: EmbeddingProvider, options?: BuildContextOptions, inferenceClient?: InferenceClient, logger?: Logger): Promise<GatheredContext>;
-    /**
-     * Get resource annotations from view storage (fast path)
-     * Throws if view missing
-     */
-    static getResourceAnnotations(resourceId: ResourceId, kb: KnowledgeBase): Promise<ResourceAnnotations>;
-    /**
-     * Get all annotations
-     * @returns Array of all annotation objects
-     */
-    static getAllAnnotations(resourceId: ResourceId, kb: KnowledgeBase): Promise<Annotation[]>;
-    /**
-     * Enrich reference annotations with resolved document names
-     * Adds _resolvedDocumentName property to annotations that link to documents
-     * @private
-     */
-    private static enrichResolvedReferences;
-    /**
-     * Get resource stats (version info)
-     * @returns Version and timestamp info for the annotations
-     */
-    static getResourceStats(resourceId: ResourceId, kb: KnowledgeBase): Promise<{
-        resourceId: ResourceId;
-        version: number;
-        updatedAt: string;
-    }>;
-    /**
-     * Check if resource exists in view storage
-     */
-    static resourceExists(resourceId: ResourceId, kb: KnowledgeBase): Promise<boolean>;
-    /**
-     * Get a single annotation by ID
-     * O(1) lookup using resource ID to access view storage
-     */
-    static getAnnotation(annotationId: AnnotationId, resourceId: ResourceId, kb: KnowledgeBase): Promise<Annotation | null>;
-    /**
-     * List annotations with optional filtering
-     * @param filters - Optional filters like resourceId and type
-     * @throws Error if resourceId not provided (cross-resource queries not supported in view storage)
-     */
-    static listAnnotations(filters: {
-        resourceId?: ResourceId;
-        type?: AnnotationCategory;
-    } | undefined, kb: KnowledgeBase): Promise<Annotation[]>;
-    /**
-     * Get annotation context (selected text with surrounding context)
-     */
-    static getAnnotationContext(annotationId: AnnotationId, resourceId: ResourceId, contextBefore: number, contextAfter: number, kb: KnowledgeBase): Promise<AnnotationContextResponse>;
-    /**
-     * Generate AI summary of annotation in context
-     */
-    static generateAnnotationSummary(annotationId: AnnotationId, resourceId: ResourceId, kb: KnowledgeBase, inferenceClient: InferenceClient): Promise<ContextualSummaryResponse>;
-    /**
-     * Get resource content as string
-     */
-    private static getResourceContent;
-    /**
-     * Extract annotation context from resource content
-     */
-    private static extractAnnotationContext;
-    /**
-     * Generate LLM summary of annotation in context
-     * Creates inference client per-request (HTTP handler context)
-     */
-    private static generateSummary;
-}
-
-/**
- * Graph Context
- *
- * Provides graph database operations for resources and annotations.
- * All methods require graph traversal - must use graph database.
- */
-
-type KnowledgeGraph = components['schemas']['KnowledgeGraph'];
-declare class GraphContext {
-    /**
-     * Get all resources referencing this resource (backlinks)
-     * Requires graph traversal - must use graph database
-     */
-    static getBacklinks(resourceId: ResourceId, kb: KnowledgeBase): Promise<Annotation[]>;
-    /**
-     * Find shortest path between two resources
-     * Requires graph traversal - must use graph database
-     */
-    static findPath(fromResourceId: ResourceId, toResourceId: ResourceId, kb: KnowledgeBase, maxDepth?: number): Promise<GraphPath[]>;
-    /**
-     * Get resource connections (graph edges)
-     * Requires graph traversal - must use graph database
-     */
-    static getResourceConnections(resourceId: ResourceId, kb: KnowledgeBase): Promise<GraphConnection[]>;
-    /**
-     * Build the unified knowledge graph for a resource's neighborhood:
-     * resources AND annotations as typed nodes, typed/directional edges.
-     *
-     * This is the single graph builder (CONTEXT-UNIFICATION D3) — both the
-     * matcher (ranking) and the resource/viz path consume it. The flattened
-     * signals the matcher reads today (`connections`, `citedBy`/count,
-     * `siblingEntityTypes`, `bidirectional`) are all derivable from this:
-     *  - peer connections → resource nodes + main→peer edges carrying `bidirectional`
-     *  - inbound citations → citing-resource nodes + `citation` edges (citing→main),
-     *    so citedByCount = inbound citation-edge count
-     *  - annotations on the resource → `annotation` nodes + `annotation-of` edges,
-     *    so siblingEntityTypes = union of those nodes' entityTypes
-     */
-    static buildKnowledgeGraph(resourceId: ResourceId, kb: KnowledgeBase, 
-    /** Breadcrumb sink for the projection-lag degrade path; the degrade counter fires regardless. */
-    logger?: Logger): Promise<KnowledgeGraph>;
-}
-
-/**
- * LLM Context
- *
- * Builds comprehensive context for LLM processing of resources
- * Orchestrates: ResourceContext, GraphContext, AnnotationContext, and generation functions
- */
-
-interface LLMContextOptions {
-    depth: number;
-    maxResources: number;
-    includeContent: boolean;
-    includeSummary: boolean;
-    /**
-     * Entity types to exclude from the resource-gather semantic recall
-     * (caller-supplied; e.g. ['Question']). Optional; default none.
-     */
-    excludeEntityTypes?: string[];
-}
-declare class LLMContext {
-    /**
-     * Get comprehensive LLM context for a resource
-     * Includes: main resource, related resources, annotations, graph, content, summary, references
-     */
-    static getResourceContext(resourceId: ResourceId, options: LLMContextOptions, kb: KnowledgeBase, inferenceClient: InferenceClient, 
-    /**
-     * Bound on the semanticContext read-your-writes barrier
-     * (SMELTER-INDEX-SYNC D3/D5). Operator-owned deployment policy: born in
-     * `[environments.<env>.make-meaning.gather] settleTimeoutMs` (the TOML
-     * loader holds the ONE default, 15s), threaded here as a plain argument
-     * via `MakeMeaningConfig.gather` → Gatherer. Must nest inside downstream
-     * watchdogs (A4) — e.g. my-chat's 90s generation stall watchdog.
-     */
-    settleTimeoutMs: number, logger: Logger): Promise<GatheredContext>;
+     * Retrieves and decodes the primary representation. ResourceId-keyed
+     * (EXTRACT-LIBRARIAN P3, D-CONTENT b): the descriptor's `storageUri` is the
+     * has-content signal; the fetch itself goes by id, so the standalone
+     * Librarian serves it over the transport.
+     */
+    static getResourceContent(resource: ResourceDescriptor, kb: {
+        content: ContentReads;
+    }): Promise<string | undefined>;
 }
 
 /**
@@ -1722,5 +1911,5 @@ declare function generateResourceSummary(resourceName: string, content: string,
  */
 declare function generateReferenceSuggestions(referenceTitle: string, client: InferenceClient, entityType?: string, currentContent?: string): Promise<string[] | null>;
 
-export { AnnotationContext, AnnotationOperations, BACKUP_FORMAT, Browser, CloneTokenManager, FORMAT_VERSION, Gatherer$1 as Gatherer, GraphContext, LLMContext, LocalContentTransport, LocalTransport, Matcher, ResourceContext, ResourceOperations, Smelter, Stower, asBusRequestPrimitive, bootstrapEntityTypes, createKnowledgeBase, createSmelterActorStateUnit, exportBackup, exportLinkedData, generateReferenceSuggestions, generateResourceSummary, importBackup, importLinkedData, isBackupManifest, readEntityTypesProjection, registerAnnotationAssemblyHandler, registerAnnotationLookupHandlers, registerBindUpdateBodyHandler, registerBusHandlers, registerJobCommandHandlers, startMakeMeaning, stopKnowledgeSystem, validateManifestVersion };
-export type { BackupContentReader, BackupEventStoreReader, BackupExporterOptions, BackupImportResult, BackupImporterOptions, BackupManifestHeader, BackupStreamSummary, BuildContextOptions, ContentBlobResolver, CreateAnnotationResult, CreateResourceInput, CreateResourceResult, KnowledgeBase, KnowledgeSystem, LLMContextOptions, LinkedDataContentReader, LinkedDataExporterOptions, LinkedDataImportResult, LinkedDataImporterOptions, LinkedDataViewReader, ListResourcesFilters, ListResourcesResult, LocalTransportConfig, MakeMeaningConfig, MakeMeaningService, ReconcileState, ReconcileSummary, ReplayStats, SmelterActorStateUnit, SmelterActorStateUnitOptions, SmelterEvent, SmelterInput, SmelterTiming, SmelterWorkItem, UpdateAnnotationBodyResult };
+export { AnnotationContext, AnnotationOperations, Browser, CloneTokenManager, Gatherer, GraphContext, LLMContext, LocalContentTransport, LocalTransport, Matcher, ResourceContext, ResourceOperations, Smelter, Stower, asBusRequestPrimitive, bootstrapEntityTypes, createArchivistServer, createKnowledgeBase, createSmelterActorStateUnit, generateReferenceSuggestions, generateResourceSummary, makeMeaningConfigFrom, readEntityTypesProjection, registerAnnotationAssemblyHandler, registerAnnotationContextHandler, registerBindUpdateBodyHandler, registerBusHandlers, registerGatherSummaryHandler, registerJobCommandHandlers, requireKBName, startMakeMeaning, startMakeMeaningGateway, stopKnowledgeSystem };
+export type { ArchivistServerDeps, BuildContextOptions, CreateAnnotationResult, CreateResourceInput, CreateResourceResult, GatewayKnowledgeSystem, GatewayMakeMeaningService, KnowledgeBase, KnowledgeSystem, LLMContextOptions, ListResourcesFilters, ListResourcesResult, LocalTransportConfig, MakeMeaningConfig, MakeMeaningService, ReconcileState, ReconcileSummary, SmelterActorStateUnit, SmelterActorStateUnitOptions, SmelterEvent, SmelterInput, SmelterTiming, SmelterWorkItem, UpdateAnnotationBodyResult };