@fallen-8/studio 0.0.32

package/dist-lib/types/api/endpoints.d.ts

@@ -0,0 +1,197 @@
+import type { InstanceConfig } from "../instances/types";
+import type { AnalyticsResultREST, DocumentBinding, DocumentDetail, DocumentEntityList, DocumentList, DocumentSearchResult, DocumentSearchSpecification, DocumentSummary, IngestTextSpecification, IntegrationJobReport, IntegrationJobRequest, IntegrationProvider, NamespaceActivationREST, NamespaceEntry, NamespacesResponse, NamespaceTriState, AnalyticsSpecification, BenchmarkResult, BulkImportResultREST, GraphGenerationResult, AlgorithmPluginRegistration, DelegateKind, DelegateValidationResult, EdgeREST, EmbedElementSpecification, FunctionPluginRegistration, GraphFunctionResultREST, PluginAuthoringCategory, PluginDetailREST, PluginSummaryREST, PluginValidationResult, PluginValidationSpecification, ConfigREST, ConfigWriteREST, ConfigWriteSpec, ChatCompletionSpec, ChatCompletionResultREST, EmbeddingSearchSpecification, EmbeddingWriteSpecification, SaveGame, EdgeSpecification, FulltextIndexScanSpecification, FulltextSearchResultREST, GraphREST, GraphStatisticsREST, IndexAddToSpecification, IndexKeySpecification, IndexScanSpecification, PartitionMembersREST, PathREST, PathSpecification, PluginSpecification, PropertySearchSpecification, PropertySpecification, RangeIndexScanSpecification, ScanSpecification, SearchDistanceSpecification, GraphElementBatchREST, StatusREST, StoredQueryDetailREST, StoredQuerySpecification, StoredQuerySummaryREST, SubGraphSpecification, SubGraphSummary, VectorIndexAddSpecification, VectorIndexScanSpecification, VectorSearchResultREST, VertexREST, VertexSpecification } from "./types";
+export declare const getStatus: (i: InstanceConfig, signal?: AbortSignal) => Promise<StatusREST | null>;
+/**
+ * Instance configuration (feature instance-config): the read-only operator view of the
+ * semantic providers + observability posture. Fallen-8-level (bare /config, never per
+ * namespace) and API-key gated like /statistics; secrets are redacted server-side.
+ */
+export declare const getConfig: (i: InstanceConfig, signal?: AbortSignal) => Promise<ConfigREST | null>;
+/**
+ * Writes instance configuration (feature writable-instance-config). A null value CLEARS a stored
+ * override and restores whatever layer sits below it, which is the undo this surface ships instead of
+ * history. Every key is validated before any is stored, so a batch applies whole or changes nothing:
+ * a 400 names the key and why, and a 409 means either the environment declares that key (so a stored
+ * value could never win) or the instance has nowhere to persist.
+ *
+ * Needs TWO operator acts server-side, an API key AND Fallen8:Security:EnableConfigurationWrite, or
+ * it is refused (401 for an unauthenticated caller, 403 otherwise); ConfigREST.configWriteEnabled is
+ * how the panel knows not to offer the write at all.
+ */
+export declare const writeConfig: (i: InstanceConfig, spec: ConfigWriteSpec, signal?: AbortSignal) => Promise<ConfigWriteREST | null>;
+/**
+ * Chat completion proxied through the instance (feature instance-config): browser -> F8 ->
+ * the model backend. Fallen-8-level; the model is server-owned so the request carries none.
+ * This is the DEFAULT NL-assist transport (custom endpoints stay browser-direct, off this path).
+ */
+export declare const postChat: (i: InstanceConfig, spec: ChatCompletionSpec, signal?: AbortSignal) => Promise<ChatCompletionResultREST | null>;
+/** Authorized iff the instance needs no key or accepted ours (server contract on StatusREST.ApiKeyRequired). */
+export declare const isAuthorized: (s: StatusREST) => boolean;
+/**
+ * Graph-shape snapshot (feature studio-coverage): O(V+E), budgeted and rate-limited
+ * server-side — only ever fetched on explicit demand (the Graph shape panel's Compute).
+ */
+export declare const getStatistics: (i: InstanceConfig, signal?: AbortSignal) => Promise<GraphStatisticsREST | null>;
+export declare const saveGraph: (i: InstanceConfig, path?: string) => Promise<SaveGame | null>;
+/** Saves EVERY namespace into one spanning save-game entry (Fallen-8-level). */
+export declare const saveAllNamespaces: (i: InstanceConfig) => Promise<SaveGame | null>;
+/** Factory reset: drops every non-default namespace and erases "default" (Fallen-8-level). */
+export declare const tabulaRasaAll: (i: InstanceConfig) => Promise<void | null>;
+export declare const listNamespaces: (i: InstanceConfig, signal?: AbortSignal) => Promise<NamespacesResponse | null>;
+export declare const createNamespace: (i: InstanceConfig, name: string) => Promise<NamespaceEntry | null>;
+export declare const renameNamespace: (i: InstanceConfig, name: string, newName: string) => Promise<NamespaceEntry | null>;
+/**
+ * Sets whether the NEXT boot loads this namespace (feature namespace-startup-load);
+ * "inherit" clears the override and falls back to the server's configured default. It never
+ * loads or unloads the running process's engine, so nothing observable changes until a
+ * restart. Its own function rather than a parameter on renameNamespace, because the server
+ * applies the whole PATCH body atomically: a shared caller would have to send a name it was
+ * not asked to change, and a stale one would rename the namespace as a side effect of a
+ * policy edit. The reserved "default" namespace refuses this field with 409.
+ */
+export declare const setNamespaceLoadOnStartup: (i: InstanceConfig, name: string, loadOnStartup: NamespaceTriState) => Promise<NamespaceEntry | null>;
+/**
+ * Loads a cataloged-but-not-loaded namespace into the RUNNING process (feature
+ * namespace-startup-load): the server constructs its engine, restores its newest registered save
+ * game and replays the write-ahead-log tail on top before it serves anything, so a failed restore
+ * leaves it exactly as not-loaded as it was. Idempotent - activating a loaded namespace answers
+ * 200 with `activated: false`. It does NOT change the persisted policy, which is what the next
+ * boot honours: that is `setNamespaceLoadOnStartup`, and the two are separate on purpose.
+ */
+export declare const activateNamespace: (i: InstanceConfig, name: string) => Promise<NamespaceActivationREST | null>;
+export declare const dropNamespace: (i: InstanceConfig, name: string) => Promise<void | null>;
+export declare const listSaveGames: (i: InstanceConfig, signal?: AbortSignal) => Promise<SaveGame[] | null>;
+export declare const getSaveGame: (i: InstanceConfig, id: string) => Promise<SaveGame | null>;
+/** Restores the entry's namespaces — or exactly one of them via `namespaceName`. */
+export declare const loadSaveGame: (i: InstanceConfig, id: string, namespaceName?: string) => Promise<SaveGame | null>;
+export declare const deleteSaveGame: (i: InstanceConfig, id: string, deleteFiles: boolean) => Promise<void | null>;
+export declare const loadGraph: (i: InstanceConfig, path: string, startServices?: boolean) => Promise<void | null>;
+export declare const trimGraph: (i: InstanceConfig) => Promise<void | null>;
+export declare const tabulaRasa: (i: InstanceConfig) => Promise<void | null>;
+/**
+ * Generates a random benchmark graph server-side (edgeCount = out-edges PER VERTEX) INTO THE
+ * ACTIVE NAMESPACE. Namespace-scoped like every other write: the server refuses the bare form
+ * rather than generating into "default", so the /ns/{ns} prefix is not optional here.
+ */
+export declare const generateGraph: (i: InstanceConfig, nodeCount?: number, edgeCount?: number, distribution?: "uniform" | "preferential") => Promise<GraphGenerationResult | null>;
+/** Runs the edge-traversal benchmark over the ACTIVE namespace's graph. */
+export declare const runBenchmark: (i: InstanceConfig, iterations?: number) => Promise<BenchmarkResult | null>;
+/** Streams the graph (or a filtered subset) to a Blob for a browser download. */
+export declare function exportBulk(i: InstanceConfig, filters?: {
+    vertexLabel?: string;
+    edgeLabel?: string;
+    edgePropertyId?: string;
+}, signal?: AbortSignal): Promise<Blob>;
+/** Imports into an EMPTY graph (server 409s otherwise); fail-fast with a line number. */
+export declare function importBulk(i: InstanceConfig, file: Blob): Promise<BulkImportResultREST | null>;
+export declare const getGraph: (i: InstanceConfig, maxElements: number, signal?: AbortSignal) => Promise<GraphREST | null>;
+export declare const getVertex: (i: InstanceConfig, id: number, signal?: AbortSignal) => Promise<VertexREST | null>;
+export declare const getEdge: (i: InstanceConfig, id: number, signal?: AbortSignal) => Promise<EdgeREST | null>;
+export declare const getGraphElement: (i: InstanceConfig, id: number, signal?: AbortSignal) => Promise<VertexREST | EdgeREST | null>;
+/**
+ * A whole page of elements in ONE request. What comes back is a complete VertexREST for a vertex;
+ * an edge lacks its endpoints, because the route omits adjacency by design - see hydrateElements,
+ * which re-reads those singly.
+ */
+export declare const getGraphElements: (i: InstanceConfig, ids: number[], signal?: AbortSignal) => Promise<GraphElementBatchREST | null>;
+export declare const getOutEdgeProperties: (i: InstanceConfig, id: number) => Promise<string[] | null>;
+export declare const getInEdgeProperties: (i: InstanceConfig, id: number) => Promise<string[] | null>;
+export declare const getOutEdges: (i: InstanceConfig, id: number, edgePropertyId: string) => Promise<number[] | null>;
+export declare const getInEdges: (i: InstanceConfig, id: number, edgePropertyId: string) => Promise<number[] | null>;
+export declare const getInDegree: (i: InstanceConfig, id: number) => Promise<number | null>;
+export declare const getOutDegree: (i: InstanceConfig, id: number) => Promise<number | null>;
+export declare const getEdgePropertyDegree: (i: InstanceConfig, id: number, direction: "in" | "out", edgePropertyId: string) => Promise<number | null>;
+export declare const getEdgeSource: (i: InstanceConfig, id: number) => Promise<number | null>;
+export declare const getEdgeTarget: (i: InstanceConfig, id: number) => Promise<number | null>;
+export declare const scanProperty: (i: InstanceConfig, propertyId: string, spec: ScanSpecification) => Promise<number[] | null>;
+export declare const scanProperties: (i: InstanceConfig, spec: PropertySearchSpecification) => Promise<number[] | null>;
+export declare const scanIndex: (i: InstanceConfig, spec: IndexScanSpecification) => Promise<number[] | null>;
+export declare const scanIndexRange: (i: InstanceConfig, spec: RangeIndexScanSpecification) => Promise<number[] | null>;
+export declare const scanFulltext: (i: InstanceConfig, spec: FulltextIndexScanSpecification) => Promise<FulltextSearchResultREST | null>;
+export declare const scanSpatial: (i: InstanceConfig, spec: SearchDistanceSpecification) => Promise<number[] | null>;
+export declare const scanVector: (i: InstanceConfig, spec: VectorIndexScanSpecification) => Promise<VectorSearchResultREST | null>;
+/** Single-element add/replace; bulk embedding ingestion is deliberately curl territory. */
+export declare const addVectorToIndex: (i: InstanceConfig, indexId: string, spec: VectorIndexAddSpecification) => Promise<boolean | null>;
+export declare const putElementEmbedding: (i: InstanceConfig, id: number, name: string, spec: EmbeddingWriteSpecification) => Promise<void | null>;
+export declare const deleteElementEmbedding: (i: InstanceConfig, id: number, name: string) => Promise<void | null>;
+/** Embed text and store it as the element's named embedding (+ model stamp), one txn. */
+export declare const embedElement: (i: InstanceConfig, spec: EmbedElementSpecification) => Promise<boolean | null>;
+/** Semantic search: embed the query text once, then kNN — same result shape as scanVector. */
+export declare const embeddingSearch: (i: InstanceConfig, spec: EmbeddingSearchSpecification) => Promise<VectorSearchResultREST | null>;
+export declare const createIndex: (i: InstanceConfig, spec: PluginSpecification) => Promise<boolean | null>;
+export declare const addToIndex: (i: InstanceConfig, indexId: string, spec: IndexAddToSpecification) => Promise<boolean | null>;
+export declare const removeIndexKey: (i: InstanceConfig, indexId: string, key: IndexKeySpecification) => Promise<boolean | null>;
+export declare const removeFromIndex: (i: InstanceConfig, indexId: string, graphElementId: number) => Promise<boolean | null>;
+export declare const deleteIndex: (i: InstanceConfig, indexId: string) => Promise<void | null>;
+export declare const findPaths: (i: InstanceConfig, from: number, to: number, spec: PathSpecification, signal?: AbortSignal) => Promise<PathREST[] | null>;
+/** GET /subgraph returns the registered NAMES; fetch summaries per name. */
+export declare const listSubGraphNames: (i: InstanceConfig, signal?: AbortSignal) => Promise<string[] | null>;
+export declare const listSubGraphSummaries: (i: InstanceConfig, signal?: AbortSignal) => Promise<SubGraphSummary[]>;
+export declare const getSubGraph: (i: InstanceConfig, name: string) => Promise<SubGraphSummary | null>;
+export declare const getSubGraphContents: (i: InstanceConfig, name: string) => Promise<GraphREST | null>;
+/** `fromSubGraph` (optional nesting) travels as a query parameter per the API contract. */
+export declare const createSubGraph: (i: InstanceConfig, spec: SubGraphSpecification, fromSubGraph?: string) => Promise<SubGraphSummary | null>;
+export declare const recalculateSubGraph: (i: InstanceConfig, name: string) => Promise<SubGraphSummary | null>;
+export declare const deleteSubGraph: (i: InstanceConfig, name: string) => Promise<void | null>;
+/** Map of algorithm name → one-line description; the picker IS the discovery surface. */
+export declare const listAnalyticsAlgorithms: (i: InstanceConfig, signal?: AbortSignal) => Promise<Record<string, string> | null>;
+export declare const runAnalytics: (i: InstanceConfig, algorithmName: string, spec: AnalyticsSpecification) => Promise<AnalyticsResultREST | null>;
+export declare const getPartitionMembers: (i: InstanceConfig, algorithmName: string, partitionId: number, spec: AnalyticsSpecification) => Promise<PartitionMembersREST | null>;
+export declare const listStoredQueries: (i: InstanceConfig, signal?: AbortSignal) => Promise<StoredQuerySummaryREST[] | null>;
+export declare const getStoredQuery: (i: InstanceConfig, name: string, signal?: AbortSignal) => Promise<StoredQueryDetailREST | null>;
+/** Registration compiles C#, so it needs the API key when one is configured (401 otherwise). */
+export declare const registerStoredQuery: (i: InstanceConfig, spec: StoredQuerySpecification) => Promise<StoredQuerySummaryREST | null>;
+export declare const deleteStoredQuery: (i: InstanceConfig, name: string) => Promise<void | null>;
+export declare const listPlugins: (i: InstanceConfig, signal?: AbortSignal) => Promise<PluginSummaryREST[] | null>;
+export declare const getPlugin: (i: InstanceConfig, name: string, signal?: AbortSignal) => Promise<PluginDetailREST | null>;
+/** Registration compiles C#, so it needs the API key when one is configured, plus the gate. */
+export declare const registerAlgorithmPlugin: (i: InstanceConfig, spec: AlgorithmPluginRegistration) => Promise<PluginSummaryREST | null>;
+export declare const registerFunctionPlugin: (i: InstanceConfig, spec: FunctionPluginRegistration) => Promise<PluginSummaryREST | null>;
+export declare const deletePlugin: (i: InstanceConfig, name: string) => Promise<void | null>;
+/** Runs a registered graph function by name; the result references existing elements. */
+export declare const invokeGraphFunction: (i: InstanceConfig, name: string, parameters?: Record<string, string>) => Promise<GraphFunctionResultREST | null>;
+/**
+ * Side-effect-free compile+contract check for the authoring editor. `category` selects the
+ * endpoint (`algorithm`/`function`); `contract` inside the spec is read only for algorithm.
+ */
+export declare const validatePlugin: (i: InstanceConfig, category: PluginAuthoringCategory, spec: PluginValidationSpecification, signal?: AbortSignal) => Promise<PluginValidationResult | null>;
+export declare const createVertex: (i: InstanceConfig, spec: VertexSpecification) => Promise<void | null>;
+export declare const createEdge: (i: InstanceConfig, spec: EdgeSpecification) => Promise<void | null>;
+export declare const setProperty: (i: InstanceConfig, id: number, propertyId: string, spec: PropertySpecification) => Promise<void | null>;
+export declare const removeProperty: (i: InstanceConfig, id: number, propertyId: string) => Promise<void | null>;
+export declare const removeGraphElement: (i: InstanceConfig, id: number) => Promise<void | null>;
+export declare const validateDelegate: (i: InstanceConfig, delegateKind: DelegateKind, fragment: string, signal?: AbortSignal) => Promise<DelegateValidationResult | null>;
+export declare const listDocuments: (i: InstanceConfig, signal?: AbortSignal) => Promise<DocumentList | null>;
+export declare const getDocument: (i: InstanceConfig, id: number, signal?: AbortSignal) => Promise<DocumentDetail | null>;
+export declare const deleteDocument: (i: InstanceConfig, id: number) => Promise<void | null>;
+export declare const ingestText: (i: InstanceConfig, spec: IngestTextSpecification) => Promise<DocumentSummary | null>;
+/**
+ * Multipart upload; `embed=false` ingests without vectors (provider off). `link` is the
+ * multipart twin of the JSON body's link block: it rides as the `linkJson` form field, so a
+ * binary upload can request the same exact-match structural linking a text ingest can.
+ */
+export declare const ingestFile: (i: InstanceConfig, file: File, options?: {
+    name?: string;
+    embed?: boolean;
+    sourceUri?: string;
+    link?: {
+        indexIds: string[];
+        maxLinksPerChunk?: number;
+    };
+}) => Promise<DocumentSummary | null>;
+/** Fused (dense + lexical) chunk retrieval; hits are chunk vertex ids. */
+export declare const searchDocuments: (i: InstanceConfig, spec: DocumentSearchSpecification) => Promise<DocumentSearchResult | null>;
+/** The index binding state: which indices exist, are the right shape, and whether ingest is ready. */
+export declare const getDocumentBinding: (i: InstanceConfig, signal?: AbortSignal) => Promise<DocumentBinding | null>;
+/** Create the required indices (idempotent). The ONLY path that creates a bound index. */
+export declare const ensureDocumentBinding: (i: InstanceConfig) => Promise<DocumentBinding | null>;
+/** The deduplicated Entity network, ranked by mention count; each id is a graph seed. */
+export declare const listEntities: (i: InstanceConfig, options?: {
+    type?: string;
+    contains?: string;
+    limit?: number;
+}, signal?: AbortSignal) => Promise<DocumentEntityList | null>;
+/** The integrations this instance's runtime ships. A 403 or 401 means the capability is off. */
+export declare const listIntegrationProviders: (i: InstanceConfig, signal?: AbortSignal) => Promise<IntegrationProvider[] | null>;
+/** Runs one job and returns its report. A job that RAN and failed still answers 200. */
+export declare const submitIntegrationJob: (i: InstanceConfig, job: IntegrationJobRequest) => Promise<IntegrationJobReport | null>;

package/dist-lib/types/api/queries.d.ts

@@ -0,0 +1,8 @@
+import type { QueryClient } from "@tanstack/react-query";
+/**
+ * Invalidates EVERY query of an instance — the raw-keyed Fallen-8-level ones
+ * (`[<id>, ...]`: save games, the namespace inventory) AND the per-namespace
+ * ones keyed by the bound view's compound id (`[<id>/<ns>, ...]`, feature
+ * graph-namespaces). Accepts either id shape.
+ */
+export declare function invalidateInstanceQueries(queryClient: QueryClient, instanceId: string): Promise<void>;