mindgraph 0.9.0 → 0.11.0

package/dist/index.d.mts

@@ -23,12 +23,24 @@ interface GraphEdge {
     updated_at: number;
     tombstone_at: number | null;
 }
+/**
+ * A `/retrieve` (text/semantic/hybrid) result. BREAKING (D3): the wire shape is
+ * `{node, score, legs?}` — the previous flat `{uid, label, summary, node_type,
+ * score}` never matched the server. Read fields off `.node` (e.g. `.node.uid`).
+ * With `include_sources: true`, `.node.source_documents` carries provenance.
+ */
 interface SearchResult {
-    uid: string;
-    label: string;
-    summary: string;
-    node_type: string;
+    node: GraphNode & {
+        source_documents?: Array<{
+            uid: string;
+            title: string;
+            ingested_by_name?: string;
+            occurred_at?: string;
+        }>;
+    };
     score: number;
+    /** Present only when the hybrid search ran with `explain: true`. */
+    legs?: LegContribution[];
 }
 /**
  * One retrieval leg's contribution to a fused hybrid result — the
@@ -401,15 +413,27 @@ interface RetrieveRequest {
      * timestamp (seconds). Filters by INGESTION time, not event time.
      */
     created_before?: number;
+    /**
+     * When true (`text`/`semantic`/`hybrid`), annotate each result's `node` with
+     * `source_documents` (`[{uid, title, ingested_by_name?, occurred_at?}]`) —
+     * provenance for citing "which teammate's notes" (D3). Requires server ≥ 1.8.0.
+     */
+    include_sources?: boolean;
 }
 interface TraverseRequest {
-    action: "chain" | "neighborhood" | "path" | "subgraph";
+    action: "chain" | "neighborhood" | "path" | "subgraph" | "top_k_paths";
     start_uid: string;
     end_uid?: string;
     max_depth?: number;
     direction?: "outgoing" | "incoming" | "both";
     edge_types?: string[];
     weight_threshold?: number;
+    /** `top_k_paths` only: number of cheapest paths to return (default 3, cap 25). */
+    k?: number;
+    /** `top_k_paths` only: max edges per path (default 8, cap 16). */
+    max_hops?: number;
+    /** `top_k_paths` only: prune paths whose min-plus cost exceeds this. */
+    max_cost?: number;
 }
 interface EvolveRequest {
     action: "update" | "tombstone" | "restore" | "decay" | "history" | "snapshot" | "tombstone_edge" | "restore_edge" | "tombstone_cascade";
@@ -437,6 +461,16 @@ interface PageOffset {
     page: number;
     char_start: number;
 }
+/**
+ * A named participant in a conversation/transcript. Supplied at ingest so
+ * extraction can map generic speaker labels ("Interviewer:") to real people
+ * and attribute claims/preferences/demands to the named person.
+ */
+interface Participant {
+    name: string;
+    organization?: string;
+    role?: string;
+}
 interface IngestChunkRequest {
     content: string;
     chunk_type?: string;
@@ -445,6 +479,12 @@ interface IngestChunkRequest {
     label?: string;
     layers?: string[];
     agent_id?: string;
+    /**
+     * Optional ontology schema id. When set, the per-chunk ontology extraction
+     * pass runs inline after cognitive extraction and submits proposed domain
+     * objects/relations. Presence alone triggers it.
+     */
+    ontology_schema_id?: string;
 }
 interface IngestChunkResponse {
     chunk_uid: string;
@@ -483,6 +523,18 @@ interface IngestDocumentRequest {
     mime_type?: string;
     /** Re-ingest even if a document with the same content was already ingested. */
     force_reingest?: boolean;
+    /**
+     * Optional ontology schema id. When set, the ontology extraction pass runs
+     * after cognitive passes. Presence alone triggers it (no `"ontology"` layer
+     * required), so auto-classified documents still get typed extraction.
+     */
+    ontology_schema_id?: string;
+    /** Named conversation participants — maps speaker labels to real people. */
+    participants?: Participant[];
+    /** When the document/conversation occurred (ISO-8601, imprecision ok). */
+    occurred_at?: string;
+    /** Free-text context grounding attribution during extraction. */
+    context?: string;
 }
 interface IngestDocumentResponse {
     job_id: string;
@@ -498,6 +550,14 @@ interface IngestSessionRequest {
     chunk_overlap?: number;
     layers?: string[];
     agent_id?: string;
+    /** Optional ontology schema id — triggers the ontology post-pass over the transcript's chunks. */
+    ontology_schema_id?: string;
+    /** Named conversation participants — maps speaker labels to real people. */
+    participants?: Participant[];
+    /** When the conversation occurred (ISO-8601, imprecision ok). */
+    occurred_at?: string;
+    /** Free-text context grounding attribution during extraction. */
+    context?: string;
 }
 interface RetrieveContextRequest {
     query: string;
@@ -511,6 +571,11 @@ interface RetrieveContextRequest {
     layer?: string;
     include_graph?: boolean;
     min_similarity?: number;
+    /**
+     * M3 as-of (valid time): ISO-8601 date to judge validity windows against.
+     * Windowed nodes then carry `valid_at_time` instead of `currently_valid`.
+     */
+    valid_at?: string;
 }
 interface ArticleResult {
     uid: string;
@@ -582,9 +647,25 @@ interface RetrieveContextResponse {
             source_documents?: {
                 uid: string;
                 title: string;
+                /** User id of the teammate who ingested the source document (A4). */
+                ingested_by?: string;
+                /** Display name (else email) of the ingesting teammate. */
+                ingested_by_name?: string;
             }[];
             source_chunks?: SourceChunk[];
             believed_by?: BelievedBy[];
+            /** This node has been replaced by a newer value (Supersedes edge). */
+            superseded?: boolean;
+            /** UID of the node that superseded this one. */
+            superseded_by?: string;
+            /**
+             * Whether the node's valid-time window (`props.valid_from`/`valid_until`)
+             * contains today. Absent when the node carries no window — unknown is
+             * not false.
+             */
+            currently_valid?: boolean;
+            /** As-of variant of `currently_valid` when the request set `valid_at`. */
+            valid_at_time?: boolean;
         })[];
         edges: Record<string, unknown>[];
     };
@@ -1023,6 +1104,17 @@ interface LinkDomainObjectsRequest {
     confidence?: number;
     agent_id?: string;
 }
+interface CreateDomainObjectRequest {
+    schema_id: string;
+    object_type: string;
+    canonical_name: string;
+    fields?: Record<string, unknown>;
+    aliases?: string[];
+    identity?: Record<string, unknown>;
+    confidence?: number;
+    /** Skip the same-type + same-name duplicate guard (default false). */
+    allow_duplicate?: boolean;
+}
 interface ExtractOntologyRequest {
     ontology_schema_id: string;
     source_uids: string[];
@@ -1050,6 +1142,16 @@ declare class MindGraph {
         status: string;
     }>;
     stats(): Promise<Record<string, unknown>>;
+    /**
+     * Schema fill-rate report (measure-first tiering): per live node type,
+     * the exact live count and sampled per-field fill rates; near-empty
+     * fields flagged below 5%. `sample` caps per-type sampling (default
+     * 1000); `layer` restricts (e.g. "epistemic").
+     */
+    schemaFillStats(params?: {
+        sample?: number;
+        layer?: string;
+    }): Promise<unknown>;
     capture(req: CaptureRequest): Promise<unknown>;
     entity(req: EntityRequest): Promise<unknown>;
     /** Convenience: create or find an entity by label. */
@@ -1304,6 +1406,14 @@ declare class MindGraph {
     getAliases(uid: string): Promise<unknown>;
     resolveAlias(text: string): Promise<unknown>;
     exportGraph(): Promise<unknown>;
+    /**
+     * Export one document's extraction provenance as JSON-LD: PROV-O
+     * entities/agents, CiTO relations between extracted claims, and the
+     * citation anchors as W3C Web Annotations (TextQuoteSelector +
+     * TextPositionSelector; positions are chunk-relative UTF-8 byte offsets,
+     * flagged via `mg:offsetUnit`).
+     */
+    exportProvenance(documentUid: string): Promise<unknown>;
     importGraph(data: unknown): Promise<unknown>;
     decay(req: DecayRequest): Promise<unknown>;
     purge(req?: PurgeRequest): Promise<unknown>;
@@ -1517,6 +1627,37 @@ declare class MindGraph {
             score: number;
         }>;
     }>;
+    /**
+     * Per-object-type coverage stats for a schema (C2f): field fill rates
+     * (with a `near_empty` flag < 5%) and identity collisions, over a bounded
+     * per-type sample (default 500, max 2000).
+     */
+    ontologyStats(schemaId: string, sample?: number): Promise<{
+        schema_id: string;
+        object_types: Array<{
+            object_type: string;
+            count: number;
+            sampled: boolean;
+            fields: Array<{
+                name: string;
+                fill_rate: number;
+                near_empty: boolean;
+            }>;
+            collisions: Array<{
+                identity: string;
+                uids: string[];
+            }>;
+        }>;
+    }>;
+    /**
+     * Create a domain object by hand (auto-approved). Returns the created node
+     * uid + the audit proposal id. Throws 409 if an object of the same type +
+     * canonical_name already exists, unless `allow_duplicate` is set.
+     */
+    createDomainObject(req: CreateDomainObjectRequest): Promise<{
+        uid: string;
+        proposal_id: string;
+    }>;
     linkDomainObjects(req: LinkDomainObjectsRequest): Promise<{
         edge_uid: string;
     }>;
@@ -1525,4 +1666,4 @@ declare class MindGraph {
     }>;
 }
 
-export { type AnalogyCandidate, type ArgumentRequest, type ArticleResult, type BatchRequest, type BelievedBy, type CaptureRequest, type ClaimHub, type ClearResponse, type ClusterClaimSample, type ClusteredClaimHub, type CommitmentRequest, type ConceptCluster, type DecayRequest, type DeliberationRequest, type DialecticalPair, type DistillRequest, type DocumentRef, type EnrichedSearchResponse, type EntityBridge, type EntityRequest, type EpistemicCounts, type EventProps, type EvolveRequest, type ExecutionRequest, type GovernanceRequest, type GraphEdge, type GraphNode, type IngestChunkRequest, type IngestChunkResponse, type IngestDocumentRequest, type IngestDocumentResponse, type IngestSessionRequest, type InquiryRequest, type Job, type ListArticlesResponse, type MemoryConfigRequest, MindGraph, type MindGraphConfig, MindGraphError, type NationProps, type OrganizationProps, type PathStep, type PersonProps, type PlaceProps, type PlanRequest, type ProcedureRequest, type PurgeRequest, type RankedClaimHub, type RetrieveContextRequest, type RetrieveContextResponse, type RetrieveRequest, type RiskRequest, type SearchChunk, type SearchResult, type SessionRequest, type SignalsQuery, type SignalsResponse, type SourceChunk, type StructureRequest, type SynthesisJobResponse, type TextSelector, type TheorySupportGap, type TraverseRequest };
+export { type AnalogyCandidate, type ArgumentRequest, type ArticleResult, type BatchRequest, type BelievedBy, type CaptureRequest, type ClaimHub, type ClearResponse, type ClusterClaimSample, type ClusteredClaimHub, type CommitmentRequest, type ConceptCluster, type DecayRequest, type DeliberationRequest, type DialecticalPair, type DistillRequest, type DocumentRef, type EnrichedSearchResponse, type EntityBridge, type EntityRequest, type EpistemicCounts, type EventProps, type EvolveRequest, type ExecutionRequest, type GovernanceRequest, type GraphEdge, type GraphNode, type IngestChunkRequest, type IngestChunkResponse, type IngestDocumentRequest, type IngestDocumentResponse, type IngestSessionRequest, type InquiryRequest, type Job, type ListArticlesResponse, type MemoryConfigRequest, MindGraph, type MindGraphConfig, MindGraphError, type NationProps, type OrganizationProps, type Participant, type PathStep, type PersonProps, type PlaceProps, type PlanRequest, type ProcedureRequest, type PurgeRequest, type RankedClaimHub, type RetrieveContextRequest, type RetrieveContextResponse, type RetrieveRequest, type RiskRequest, type SearchChunk, type SearchResult, type SessionRequest, type SignalsQuery, type SignalsResponse, type SourceChunk, type StructureRequest, type SynthesisJobResponse, type TextSelector, type TheorySupportGap, type TraverseRequest };

package/dist/index.d.ts

@@ -23,12 +23,24 @@ interface GraphEdge {
     updated_at: number;
     tombstone_at: number | null;
 }
+/**
+ * A `/retrieve` (text/semantic/hybrid) result. BREAKING (D3): the wire shape is
+ * `{node, score, legs?}` — the previous flat `{uid, label, summary, node_type,
+ * score}` never matched the server. Read fields off `.node` (e.g. `.node.uid`).
+ * With `include_sources: true`, `.node.source_documents` carries provenance.
+ */
 interface SearchResult {
-    uid: string;
-    label: string;
-    summary: string;
-    node_type: string;
+    node: GraphNode & {
+        source_documents?: Array<{
+            uid: string;
+            title: string;
+            ingested_by_name?: string;
+            occurred_at?: string;
+        }>;
+    };
     score: number;
+    /** Present only when the hybrid search ran with `explain: true`. */
+    legs?: LegContribution[];
 }
 /**
  * One retrieval leg's contribution to a fused hybrid result — the
@@ -401,15 +413,27 @@ interface RetrieveRequest {
      * timestamp (seconds). Filters by INGESTION time, not event time.
      */
     created_before?: number;
+    /**
+     * When true (`text`/`semantic`/`hybrid`), annotate each result's `node` with
+     * `source_documents` (`[{uid, title, ingested_by_name?, occurred_at?}]`) —
+     * provenance for citing "which teammate's notes" (D3). Requires server ≥ 1.8.0.
+     */
+    include_sources?: boolean;
 }
 interface TraverseRequest {
-    action: "chain" | "neighborhood" | "path" | "subgraph";
+    action: "chain" | "neighborhood" | "path" | "subgraph" | "top_k_paths";
     start_uid: string;
     end_uid?: string;
     max_depth?: number;
     direction?: "outgoing" | "incoming" | "both";
     edge_types?: string[];
     weight_threshold?: number;
+    /** `top_k_paths` only: number of cheapest paths to return (default 3, cap 25). */
+    k?: number;
+    /** `top_k_paths` only: max edges per path (default 8, cap 16). */
+    max_hops?: number;
+    /** `top_k_paths` only: prune paths whose min-plus cost exceeds this. */
+    max_cost?: number;
 }
 interface EvolveRequest {
     action: "update" | "tombstone" | "restore" | "decay" | "history" | "snapshot" | "tombstone_edge" | "restore_edge" | "tombstone_cascade";
@@ -437,6 +461,16 @@ interface PageOffset {
     page: number;
     char_start: number;
 }
+/**
+ * A named participant in a conversation/transcript. Supplied at ingest so
+ * extraction can map generic speaker labels ("Interviewer:") to real people
+ * and attribute claims/preferences/demands to the named person.
+ */
+interface Participant {
+    name: string;
+    organization?: string;
+    role?: string;
+}
 interface IngestChunkRequest {
     content: string;
     chunk_type?: string;
@@ -445,6 +479,12 @@ interface IngestChunkRequest {
     label?: string;
     layers?: string[];
     agent_id?: string;
+    /**
+     * Optional ontology schema id. When set, the per-chunk ontology extraction
+     * pass runs inline after cognitive extraction and submits proposed domain
+     * objects/relations. Presence alone triggers it.
+     */
+    ontology_schema_id?: string;
 }
 interface IngestChunkResponse {
     chunk_uid: string;
@@ -483,6 +523,18 @@ interface IngestDocumentRequest {
     mime_type?: string;
     /** Re-ingest even if a document with the same content was already ingested. */
     force_reingest?: boolean;
+    /**
+     * Optional ontology schema id. When set, the ontology extraction pass runs
+     * after cognitive passes. Presence alone triggers it (no `"ontology"` layer
+     * required), so auto-classified documents still get typed extraction.
+     */
+    ontology_schema_id?: string;
+    /** Named conversation participants — maps speaker labels to real people. */
+    participants?: Participant[];
+    /** When the document/conversation occurred (ISO-8601, imprecision ok). */
+    occurred_at?: string;
+    /** Free-text context grounding attribution during extraction. */
+    context?: string;
 }
 interface IngestDocumentResponse {
     job_id: string;
@@ -498,6 +550,14 @@ interface IngestSessionRequest {
     chunk_overlap?: number;
     layers?: string[];
     agent_id?: string;
+    /** Optional ontology schema id — triggers the ontology post-pass over the transcript's chunks. */
+    ontology_schema_id?: string;
+    /** Named conversation participants — maps speaker labels to real people. */
+    participants?: Participant[];
+    /** When the conversation occurred (ISO-8601, imprecision ok). */
+    occurred_at?: string;
+    /** Free-text context grounding attribution during extraction. */
+    context?: string;
 }
 interface RetrieveContextRequest {
     query: string;
@@ -511,6 +571,11 @@ interface RetrieveContextRequest {
     layer?: string;
     include_graph?: boolean;
     min_similarity?: number;
+    /**
+     * M3 as-of (valid time): ISO-8601 date to judge validity windows against.
+     * Windowed nodes then carry `valid_at_time` instead of `currently_valid`.
+     */
+    valid_at?: string;
 }
 interface ArticleResult {
     uid: string;
@@ -582,9 +647,25 @@ interface RetrieveContextResponse {
             source_documents?: {
                 uid: string;
                 title: string;
+                /** User id of the teammate who ingested the source document (A4). */
+                ingested_by?: string;
+                /** Display name (else email) of the ingesting teammate. */
+                ingested_by_name?: string;
             }[];
             source_chunks?: SourceChunk[];
             believed_by?: BelievedBy[];
+            /** This node has been replaced by a newer value (Supersedes edge). */
+            superseded?: boolean;
+            /** UID of the node that superseded this one. */
+            superseded_by?: string;
+            /**
+             * Whether the node's valid-time window (`props.valid_from`/`valid_until`)
+             * contains today. Absent when the node carries no window — unknown is
+             * not false.
+             */
+            currently_valid?: boolean;
+            /** As-of variant of `currently_valid` when the request set `valid_at`. */
+            valid_at_time?: boolean;
         })[];
         edges: Record<string, unknown>[];
     };
@@ -1023,6 +1104,17 @@ interface LinkDomainObjectsRequest {
     confidence?: number;
     agent_id?: string;
 }
+interface CreateDomainObjectRequest {
+    schema_id: string;
+    object_type: string;
+    canonical_name: string;
+    fields?: Record<string, unknown>;
+    aliases?: string[];
+    identity?: Record<string, unknown>;
+    confidence?: number;
+    /** Skip the same-type + same-name duplicate guard (default false). */
+    allow_duplicate?: boolean;
+}
 interface ExtractOntologyRequest {
     ontology_schema_id: string;
     source_uids: string[];
@@ -1050,6 +1142,16 @@ declare class MindGraph {
         status: string;
     }>;
     stats(): Promise<Record<string, unknown>>;
+    /**
+     * Schema fill-rate report (measure-first tiering): per live node type,
+     * the exact live count and sampled per-field fill rates; near-empty
+     * fields flagged below 5%. `sample` caps per-type sampling (default
+     * 1000); `layer` restricts (e.g. "epistemic").
+     */
+    schemaFillStats(params?: {
+        sample?: number;
+        layer?: string;
+    }): Promise<unknown>;
     capture(req: CaptureRequest): Promise<unknown>;
     entity(req: EntityRequest): Promise<unknown>;
     /** Convenience: create or find an entity by label. */
@@ -1304,6 +1406,14 @@ declare class MindGraph {
     getAliases(uid: string): Promise<unknown>;
     resolveAlias(text: string): Promise<unknown>;
     exportGraph(): Promise<unknown>;
+    /**
+     * Export one document's extraction provenance as JSON-LD: PROV-O
+     * entities/agents, CiTO relations between extracted claims, and the
+     * citation anchors as W3C Web Annotations (TextQuoteSelector +
+     * TextPositionSelector; positions are chunk-relative UTF-8 byte offsets,
+     * flagged via `mg:offsetUnit`).
+     */
+    exportProvenance(documentUid: string): Promise<unknown>;
     importGraph(data: unknown): Promise<unknown>;
     decay(req: DecayRequest): Promise<unknown>;
     purge(req?: PurgeRequest): Promise<unknown>;
@@ -1517,6 +1627,37 @@ declare class MindGraph {
             score: number;
         }>;
     }>;
+    /**
+     * Per-object-type coverage stats for a schema (C2f): field fill rates
+     * (with a `near_empty` flag < 5%) and identity collisions, over a bounded
+     * per-type sample (default 500, max 2000).
+     */
+    ontologyStats(schemaId: string, sample?: number): Promise<{
+        schema_id: string;
+        object_types: Array<{
+            object_type: string;
+            count: number;
+            sampled: boolean;
+            fields: Array<{
+                name: string;
+                fill_rate: number;
+                near_empty: boolean;
+            }>;
+            collisions: Array<{
+                identity: string;
+                uids: string[];
+            }>;
+        }>;
+    }>;
+    /**
+     * Create a domain object by hand (auto-approved). Returns the created node
+     * uid + the audit proposal id. Throws 409 if an object of the same type +
+     * canonical_name already exists, unless `allow_duplicate` is set.
+     */
+    createDomainObject(req: CreateDomainObjectRequest): Promise<{
+        uid: string;
+        proposal_id: string;
+    }>;
     linkDomainObjects(req: LinkDomainObjectsRequest): Promise<{
         edge_uid: string;
     }>;
@@ -1525,4 +1666,4 @@ declare class MindGraph {
     }>;
 }
 
-export { type AnalogyCandidate, type ArgumentRequest, type ArticleResult, type BatchRequest, type BelievedBy, type CaptureRequest, type ClaimHub, type ClearResponse, type ClusterClaimSample, type ClusteredClaimHub, type CommitmentRequest, type ConceptCluster, type DecayRequest, type DeliberationRequest, type DialecticalPair, type DistillRequest, type DocumentRef, type EnrichedSearchResponse, type EntityBridge, type EntityRequest, type EpistemicCounts, type EventProps, type EvolveRequest, type ExecutionRequest, type GovernanceRequest, type GraphEdge, type GraphNode, type IngestChunkRequest, type IngestChunkResponse, type IngestDocumentRequest, type IngestDocumentResponse, type IngestSessionRequest, type InquiryRequest, type Job, type ListArticlesResponse, type MemoryConfigRequest, MindGraph, type MindGraphConfig, MindGraphError, type NationProps, type OrganizationProps, type PathStep, type PersonProps, type PlaceProps, type PlanRequest, type ProcedureRequest, type PurgeRequest, type RankedClaimHub, type RetrieveContextRequest, type RetrieveContextResponse, type RetrieveRequest, type RiskRequest, type SearchChunk, type SearchResult, type SessionRequest, type SignalsQuery, type SignalsResponse, type SourceChunk, type StructureRequest, type SynthesisJobResponse, type TextSelector, type TheorySupportGap, type TraverseRequest };
+export { type AnalogyCandidate, type ArgumentRequest, type ArticleResult, type BatchRequest, type BelievedBy, type CaptureRequest, type ClaimHub, type ClearResponse, type ClusterClaimSample, type ClusteredClaimHub, type CommitmentRequest, type ConceptCluster, type DecayRequest, type DeliberationRequest, type DialecticalPair, type DistillRequest, type DocumentRef, type EnrichedSearchResponse, type EntityBridge, type EntityRequest, type EpistemicCounts, type EventProps, type EvolveRequest, type ExecutionRequest, type GovernanceRequest, type GraphEdge, type GraphNode, type IngestChunkRequest, type IngestChunkResponse, type IngestDocumentRequest, type IngestDocumentResponse, type IngestSessionRequest, type InquiryRequest, type Job, type ListArticlesResponse, type MemoryConfigRequest, MindGraph, type MindGraphConfig, MindGraphError, type NationProps, type OrganizationProps, type Participant, type PathStep, type PersonProps, type PlaceProps, type PlanRequest, type ProcedureRequest, type PurgeRequest, type RankedClaimHub, type RetrieveContextRequest, type RetrieveContextResponse, type RetrieveRequest, type RiskRequest, type SearchChunk, type SearchResult, type SessionRequest, type SignalsQuery, type SignalsResponse, type SourceChunk, type StructureRequest, type SynthesisJobResponse, type TextSelector, type TheorySupportGap, type TraverseRequest };

package/dist/index.js

@@ -108,6 +108,19 @@ var MindGraph = class {
   async stats() {
     return this.get("/stats");
   }
+  /**
+   * Schema fill-rate report (measure-first tiering): per live node type,
+   * the exact live count and sampled per-field fill rates; near-empty
+   * fields flagged below 5%. `sample` caps per-type sampling (default
+   * 1000); `layer` restricts (e.g. "epistemic").
+   */
+  async schemaFillStats(params) {
+    const q = new URLSearchParams();
+    if (params?.sample !== void 0) q.set("sample", String(params.sample));
+    if (params?.layer) q.set("layer", params.layer);
+    const qs = q.toString();
+    return this.get(`/stats/schema-fill${qs ? `?${qs}` : ""}`);
+  }
   // ---- Reality Layer ----
   async capture(req) {
     return this.post("/reality/capture", req);
@@ -469,6 +482,18 @@ var MindGraph = class {
   async exportGraph() {
     return this.get("/export");
   }
+  /**
+   * Export one document's extraction provenance as JSON-LD: PROV-O
+   * entities/agents, CiTO relations between extracted claims, and the
+   * citation anchors as W3C Web Annotations (TextQuoteSelector +
+   * TextPositionSelector; positions are chunk-relative UTF-8 byte offsets,
+   * flagged via `mg:offsetUnit`).
+   */
+  async exportProvenance(documentUid) {
+    return this.get(
+      `/export/prov?document_uid=${encodeURIComponent(documentUid)}`
+    );
+  }
   async importGraph(data) {
     return this.post("/import", data);
   }
@@ -787,6 +812,24 @@ var MindGraph = class {
   async searchDomainObjects(query, opts) {
     return this.post("/ontology/objects/search", { query, ...opts ?? {} });
   }
+  /**
+   * Per-object-type coverage stats for a schema (C2f): field fill rates
+   * (with a `near_empty` flag < 5%) and identity collisions, over a bounded
+   * per-type sample (default 500, max 2000).
+   */
+  async ontologyStats(schemaId, sample) {
+    const q = new URLSearchParams({ schema_id: schemaId });
+    if (sample != null) q.set("sample", String(sample));
+    return this.get(`/ontology/stats?${q.toString()}`);
+  }
+  /**
+   * Create a domain object by hand (auto-approved). Returns the created node
+   * uid + the audit proposal id. Throws 409 if an object of the same type +
+   * canonical_name already exists, unless `allow_duplicate` is set.
+   */
+  async createDomainObject(req) {
+    return this.post("/v1/ontology/objects", req);
+  }
   async linkDomainObjects(req) {
     return this.post("/ontology/relation", { action: "create", ...req });
   }

package/dist/index.mjs

@@ -81,6 +81,19 @@ var MindGraph = class {
   async stats() {
     return this.get("/stats");
   }
+  /**
+   * Schema fill-rate report (measure-first tiering): per live node type,
+   * the exact live count and sampled per-field fill rates; near-empty
+   * fields flagged below 5%. `sample` caps per-type sampling (default
+   * 1000); `layer` restricts (e.g. "epistemic").
+   */
+  async schemaFillStats(params) {
+    const q = new URLSearchParams();
+    if (params?.sample !== void 0) q.set("sample", String(params.sample));
+    if (params?.layer) q.set("layer", params.layer);
+    const qs = q.toString();
+    return this.get(`/stats/schema-fill${qs ? `?${qs}` : ""}`);
+  }
   // ---- Reality Layer ----
   async capture(req) {
     return this.post("/reality/capture", req);
@@ -442,6 +455,18 @@ var MindGraph = class {
   async exportGraph() {
     return this.get("/export");
   }
+  /**
+   * Export one document's extraction provenance as JSON-LD: PROV-O
+   * entities/agents, CiTO relations between extracted claims, and the
+   * citation anchors as W3C Web Annotations (TextQuoteSelector +
+   * TextPositionSelector; positions are chunk-relative UTF-8 byte offsets,
+   * flagged via `mg:offsetUnit`).
+   */
+  async exportProvenance(documentUid) {
+    return this.get(
+      `/export/prov?document_uid=${encodeURIComponent(documentUid)}`
+    );
+  }
   async importGraph(data) {
     return this.post("/import", data);
   }
@@ -760,6 +785,24 @@ var MindGraph = class {
   async searchDomainObjects(query, opts) {
     return this.post("/ontology/objects/search", { query, ...opts ?? {} });
   }
+  /**
+   * Per-object-type coverage stats for a schema (C2f): field fill rates
+   * (with a `near_empty` flag < 5%) and identity collisions, over a bounded
+   * per-type sample (default 500, max 2000).
+   */
+  async ontologyStats(schemaId, sample) {
+    const q = new URLSearchParams({ schema_id: schemaId });
+    if (sample != null) q.set("sample", String(sample));
+    return this.get(`/ontology/stats?${q.toString()}`);
+  }
+  /**
+   * Create a domain object by hand (auto-approved). Returns the created node
+   * uid + the audit proposal id. Throws 409 if an object of the same type +
+   * canonical_name already exists, unless `allow_duplicate` is set.
+   */
+  async createDomainObject(req) {
+    return this.post("/v1/ontology/objects", req);
+  }
   async linkDomainObjects(req) {
     return this.post("/ontology/relation", { action: "create", ...req });
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mindgraph",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "TypeScript client for the MindGraph Cloud API",
   "main": "dist/index.js",
   "module": "dist/index.mjs",