mindgraph 0.11.0 → 0.12.0

package/README.md

@@ -88,6 +88,7 @@ const entity = await graph.findOrCreateEntity("Some Entity");
 |--------|-------------|
 | `commit(req)` | Create a goal, project, or milestone |
 | `deliberate(req)` | Open decisions, add options/constraints, resolve decisions |
+| `resolveDecision(decisionUid, optionUid, opts)` | Resolve with optional dated context and session/retrieval-trace linkage |
 
 ### Action Layer
 
@@ -102,7 +103,7 @@ const entity = await graph.findOrCreateEntity("Some Entity");
 |--------|-------------|
 | `session(req)` | Open a session, record traces, or close a session |
 | `journal(label, props, options?)` | Record a journal entry linked to an optional session |
-| `distill(req)` | Create a summary that distills multiple source nodes |
+| `distill(req)` | Create a Summary (default) or Lesson with source provenance |
 | `memoryConfig(req)` | Set/get preferences and memory policies |
 
 ### Agent Layer
@@ -184,7 +185,7 @@ See the [Operational Ontology](https://mindgraph.cloud/docs/ontology) and [Conne
 | `ingestChunk(req)` | Ingest a single text chunk (sync): stores, embeds, and runs LLM extraction |
 | `ingestDocument(req)` | Ingest a full document (async): chunks text, returns job ID |
 | `ingestSession(req)` | Ingest a session transcript (async): links to session, returns job ID |
-| `retrieveContext(req)` | Retrieve semantically matched chunks + connected graph nodes/edges |
+| `retrieveContext(req)` | Direct retrieval plus optional cheapest-first graph expansion (`graph_expansion_limit`, `graph_max_depth`) |
 | `getJob(id)` | Get async job status and progress |
 | `clearGraph()` | Clear all graph data |
 
@@ -200,7 +201,7 @@ See the [Operational Ontology](https://mindgraph.cloud/docs/ontology) and [Conne
 | Method | Description |
 |--------|-------------|
 | `retrieve(req)` | Unified retrieval: text search, active goals, open questions, weak claims |
-| `traverse(req)` | Graph traversal: chain, neighborhood, path, or subgraph |
+| `traverse(req)` | Budgeted min-cost traversal; `depth` is the selected witness hop count |
 | `evolve(req)` | Lifecycle mutations: update, tombstone, restore, decay, history |
 
 ### Health & Stats

package/dist/index.d.mts

@@ -72,6 +72,25 @@ interface MergeCandidate {
     similarity: number | null;
     /** How the candidate was found: "exact" | "fuzzy" | "semantic" | "llm". */
     method: string | null;
+    /**
+     * Normalized `truth_status` of each side (Claims), so curation UIs can
+     * warn before merging a refuted claim. Absent on servers older than the
+     * hardening batch.
+     */
+    node_a_truth_status?: string | null;
+    node_b_truth_status?: string | null;
+}
+/** A derived statement awaiting review after a load-bearing premise changed. */
+interface StaleDerivation {
+    invalidation_uid: string;
+    invalidator_uid: string;
+    invalidator_label: string;
+    node_uid: string;
+    node_label: string;
+    node_summary: string;
+    node_type: string;
+    reason: string | null;
+    invalidated_at: string | null;
 }
 /** A `/retrieve` hybrid result: the full node plus the fused RRF score. */
 interface HybridSearchResult {
@@ -99,11 +118,10 @@ interface PathStep {
     edge_type: string | null;
     depth: number;
     parent_uid: string | null;
-    /** Min-plus cost of the returned BFS path from the start node
-     * (sum of -ln(weight), weights clamped to (1e-9, 1]); cost of the path
-     * the traversal returned, not the cheapest path. 0 at the start node. */
+    /** Min-plus cost of the selected cheapest path from the start node
+     * (sum of -ln(weight), weights clamped to (1e-9, 1]). */
     path_cost?: number;
-    /** Product of edge confidences along the returned BFS path (clamped to
+    /** Product of edge confidences along the selected min-cost path (clamped to
      * (1e-9, 1]); a ranking signal, not a calibrated probability. 1 at the
      * start node. */
     path_confidence?: number;
@@ -271,6 +289,12 @@ interface DeliberationRequest {
     chosen_option_uid?: string;
     blocks_uid?: string;
     informs_uid?: string[];
+    /** ISO 8601 date when resolve-time context was available. */
+    as_of_date?: string;
+    /** Session whose retrieval context informed the resolution. */
+    session_id?: string;
+    /** Optional identifier of the decision-time retrieval trace. */
+    retrieval_trace_id?: string;
     props?: Record<string, unknown>;
     agent_id?: string;
 }
@@ -311,6 +335,8 @@ interface SessionRequest {
 }
 interface DistillRequest {
     label: string;
+    /** Defaults to "summary" for backward compatibility. */
+    output_type?: "summary" | "lesson";
     summary?: string;
     confidence?: number;
     salience?: number;
@@ -377,7 +403,7 @@ interface RetrieveRequest {
      * Retrieval action. Note: `"semantic"` requires a configured embedding
      * provider on the server; for semantic search use `retrieveContext()` instead.
      */
-    action: "text" | "semantic" | "hybrid" | "active_goals" | "open_questions" | "weak_claims" | "pending_approvals" | "unresolved_contradictions" | "preferences" | "layer" | "recent";
+    action: "text" | "semantic" | "hybrid" | "active_goals" | "open_questions" | "weak_claims" | "pending_approvals" | "unresolved_contradictions" | "stale_derivations" | "preferences" | "layer" | "recent";
     /**
      * Required for `"text"`, `"semantic"`, `"hybrid"`. Optional for
      * `"preferences"`: with a `query` you get topic-relevant preferences (the
@@ -427,7 +453,12 @@ interface TraverseRequest {
     max_depth?: number;
     direction?: "outgoing" | "incoming" | "both";
     edge_types?: string[];
+    exclude_edge_types?: string[];
     weight_threshold?: number;
+    /** Include ingestion/provenance edges excluded by default. */
+    include_provenance?: boolean;
+    /** Global distinct-node budget, including the seed (default 500). */
+    max_nodes?: 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). */
@@ -571,6 +602,11 @@ interface RetrieveContextRequest {
     layer?: string;
     include_graph?: boolean;
     min_similarity?: number;
+    /** Reserve up to this many node slots for cheapest-first graph expansion.
+     * Default 0 preserves direct-only retrieval. */
+    graph_expansion_limit?: number;
+    /** Maximum graph-expansion hops (default 2). */
+    graph_max_depth?: 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`.
@@ -666,6 +702,11 @@ interface RetrieveContextResponse {
             currently_valid?: boolean;
             /** As-of variant of `currently_valid` when the request set `valid_at`. */
             valid_at_time?: boolean;
+            /** Present when the node was added by budgeted graph expansion. */
+            retrieval_origin?: "graph_expansion";
+            retrieval_path_cost?: number;
+            retrieval_depth?: number;
+            retrieval_parent_uid?: string | null;
         })[];
         edges: Record<string, unknown>[];
     };
@@ -833,6 +874,125 @@ interface MindGraphConfig {
     /** Initial backoff in ms before first retry. Doubles each attempt. Default: 1000. */
     retryBackoffMs?: number;
 }
+/** Schema-level behavior for compiled semantic-match diagnostics. */
+type SemanticValidationMode = "off" | "advisory" | "review" | "strict";
+/** Validation modes accepted by the M5.1 schema update endpoint. */
+type SemanticValidationAuthoringMode = "off" | "advisory";
+/** The six storage/runtime behaviors supported by semantic profile v1. */
+type SemanticRuntimeTemplate = "entity" | "dependent_entity" | "collective" | "relationship_object" | "event" | "observation";
+/** Optional orthogonal classifications that do not introduce storage layouts. */
+type SemanticModifier = "role" | "phase" | "social_construct";
+type OntologicalBaseKind = "kind" | "subkind" | "dependent_particular" | "collective" | "relator" | "event" | "quality" | "unspecified";
+type SemanticRigidity = "rigid" | "anti_rigid" | "unspecified";
+type SemanticIdentityMode = "provided" | "inherited" | "derived" | "unspecified";
+type SemanticDependence = "independent" | "bearer" | "external" | "unspecified";
+type SemanticTemporalMode = "persistent" | "interval" | "occurrence" | "observation_time" | "unspecified";
+type SemanticMatchStatus = "candidate" | "accepted" | "rejected" | "superseded";
+type SemanticEvidenceSourceKind = "corpus_span" | "declared_structure" | "sql_metadata" | "graph_usage" | "human_review" | "llm_classification";
+type SemanticSignalKind = "own_identity" | "borrowed_identity" | "host_attachment" | "participant_count" | "membership_relation" | "occurs_at" | "observed_at" | "externally_assigned" | "lifecycle_stage" | "institutionally_defined" | "relation_endpoints";
+type ParticipantSlotKind = "bearer" | "player" | "context" | "subject" | "source" | "participant" | "member" | "observed_entity" | "base_type";
+/** A typed participant requirement resolved against the containing schema version. */
+interface SemanticParticipantSlot {
+    name: string;
+    template_slot: ParticipantSlotKind;
+    object_types?: string[];
+    min?: number;
+    max?: number;
+    relation_type?: string;
+}
+type FieldSemanticKind = "phase_indicator" | "role_indicator" | "internal_disposition" | "event_time" | "observed_at" | "source_wording";
+/** Typed meaning for a concrete object field; prose is never compiled. */
+interface FieldSemantic {
+    field: string;
+    semantic: FieldSemanticKind;
+    temporal_mode?: SemanticTemporalMode;
+    lossy?: boolean;
+}
+type NormativeKind = "need" | "constraint" | "obligation" | "preference" | "unspecified";
+type CanonicalAttachmentAuthority = "relation" | "reference_field";
+type CanonicalAttachmentDirection = "outgoing" | "incoming";
+/** Declares which of a relation/reference-field pair owns an attachment fact. */
+interface CanonicalAttachmentBinding {
+    slot: string;
+    relation_type: string;
+    reference_field?: string;
+    authority: CanonicalAttachmentAuthority;
+    direction: CanonicalAttachmentDirection;
+}
+/** Pins a match to one immutable global archetype template version. */
+interface SemanticTemplateRef {
+    id: string;
+    version: number;
+}
+interface SemanticEvidenceRef {
+    id: string;
+    source_kind: SemanticEvidenceSourceKind;
+    source_ref: string;
+    asserted_by?: string;
+    asserted_at?: string;
+}
+interface SemanticGeneratorRef {
+    id: string;
+    version: number;
+    proposal_ref?: string;
+}
+interface SemanticSignal {
+    signal: SemanticSignalKind;
+    value: boolean | number | string;
+    evidence_ref: SemanticEvidenceRef;
+    generator?: SemanticGeneratorRef;
+    confidence: number;
+    observed_at?: string;
+}
+interface SemanticNegativeControl {
+    template: SemanticTemplateRef;
+    reason: string;
+}
+interface SemanticMatchAlternative {
+    template: SemanticTemplateRef;
+    confidence: number;
+    reason: string;
+    evidence?: SemanticSignal[];
+}
+interface SemanticModifierMatch {
+    template: SemanticTemplateRef;
+    evidence: SemanticSignal[];
+    negative_control: SemanticNegativeControl;
+}
+interface SemanticReviewDecision {
+    actor: string;
+    decided_at: string;
+    rationale: string;
+    premises?: string[];
+    supersedes?: string;
+}
+interface SemanticTenantBindings {
+    ontological_base_kind?: OntologicalBaseKind;
+    rigidity?: SemanticRigidity;
+    identity_mode?: SemanticIdentityMode;
+    dependence?: SemanticDependence;
+    temporal_mode?: SemanticTemporalMode;
+    slots?: SemanticParticipantSlot[];
+    fields?: FieldSemantic[];
+    normative_kind?: NormativeKind;
+    attachments?: CanonicalAttachmentBinding[];
+}
+type SemanticRelationKind = "association" | "mediation" | "participation" | "membership" | "characterization" | "part_whole" | "derivation" | "classification" | "unspecified";
+/** Unified evidence-backed classification for object and relation types. */
+interface SemanticMatch {
+    version: number;
+    template: SemanticTemplateRef;
+    modifiers?: SemanticModifierMatch[];
+    status: SemanticMatchStatus;
+    evidence: SemanticSignal[];
+    negative_control: SemanticNegativeControl;
+    alternatives?: SemanticMatchAlternative[];
+    bindings?: SemanticTenantBindings;
+    confidence: number;
+    rationale: string;
+    proposed_by?: SemanticGeneratorRef[];
+    decision?: SemanticReviewDecision;
+}
 /** Field schema entry inside `OntologyObjectType.fields_json`. */
 interface FieldDefinition {
     name: string;
@@ -910,6 +1070,12 @@ interface OntologySchema {
     description?: string;
     status: "draft" | "active" | "deprecated" | "archived";
     version: number;
+    /**
+     * Advisory semantic-profile validation is opt-in per schema. Optional so the
+     * SDK tolerates servers that predate the field (the server itself defaults
+     * absent rows to "off").
+     */
+    semantic_validation_mode?: SemanticValidationMode;
     propose_status?: "pending" | "running" | "ready" | "failed" | null;
     propose_job_id?: string | null;
     propose_error?: string | null;
@@ -935,6 +1101,8 @@ interface OntologyObjectType {
     extraction_hints?: string | null;
     default_confidence: number;
     review_policy: "always" | "low_confidence" | "never";
+    /** Accepted semantic match. Candidates remain in the proposal ledger. */
+    semantic_match?: SemanticMatch | null;
     /** Datasource binding (null = extracted/authored). */
     backing?: ObjectBacking | null;
     status: "active" | "deprecated" | "archived";
@@ -957,7 +1125,10 @@ interface OntologyRelationType {
     inverse_relation_type?: string | null;
     fields_json: FieldDefinition[];
     extraction_hints?: string | null;
+    default_confidence: number;
     review_policy: "always" | "low_confidence" | "never";
+    /** Accepted relation match. Candidates remain in the proposal ledger. */
+    semantic_match?: SemanticMatch | null;
     /** Datasource binding (null = extracted/authored). */
     backing?: RelationBacking | null;
     status: "active" | "deprecated" | "archived";
@@ -986,6 +1157,7 @@ interface CreateOntologySchemaRequest {
 interface UpdateOntologySchemaRequest {
     name?: string;
     description?: string;
+    semantic_validation_mode?: SemanticValidationAuthoringMode;
 }
 interface OntologyObjectTypeInput {
     name: string;
@@ -999,6 +1171,8 @@ interface OntologyObjectTypeInput {
     extraction_hints?: string;
     default_confidence?: number;
     review_policy?: "always" | "low_confidence" | "never";
+    /** Add, replace, or clear the object's accepted semantic match. */
+    semantic_match?: SemanticMatch | null;
     /** Bind this object type to an external source (SQL). Omit for extracted/authored. */
     backing?: ObjectBacking | null;
 }
@@ -1014,7 +1188,10 @@ interface OntologyRelationTypeInput {
     inverse_relation_type?: string;
     fields?: FieldDefinition[];
     extraction_hints?: string;
+    default_confidence?: number;
     review_policy?: "always" | "low_confidence" | "never";
+    /** Add, replace, or clear the relation's accepted semantic match. */
+    semantic_match?: SemanticMatch | null;
     /** Bind this relation to an FK column or M:M join table. Both endpoints must be sql-mapped. */
     backing?: RelationBacking | null;
 }
@@ -1025,6 +1202,8 @@ interface OntologyProposal {
     schema_id: string;
     proposal_type: string;
     proposed_by_agent_id?: string | null;
+    proposed_by_user_id?: string | null;
+    extract_job_id?: string | null;
     source_uids: string[];
     source_scope_ids: string[];
     changes_json: {
@@ -1049,6 +1228,34 @@ interface OntologyProposal {
     resolved_at?: string | null;
     resolved_by?: string | null;
 }
+interface OntologyDuplicateAudit {
+    schema_id: string;
+    object_groups: Array<{
+        object_type: string;
+        identity_hash: string;
+        canonical_uid: string;
+        members: Array<{
+            uid: string;
+            label: string;
+            source_uids: string[];
+        }>;
+        conflicting_fields: string[];
+        affected_edges: number;
+        auto_merge_safe: boolean;
+    }>;
+    relation_groups: Array<{
+        relation_type: string;
+        identity_hash: string;
+        canonical_uid: string;
+        edge_uids: string[];
+        from_uid: string;
+        to_uid: string;
+        auto_merge_safe: boolean;
+    }>;
+    objects_without_deterministic_identity: number;
+    context_ambiguous_objects: number;
+    repeatable_relations_skipped: number;
+}
 interface ProposalEdits {
     canonical_name?: string;
     fields?: Record<string, unknown>;
@@ -1235,6 +1442,11 @@ declare class MindGraph {
      */
     resolveDecision(decisionUid: string, chosenOptionUid: string, opts?: {
         summary?: string;
+        props?: Record<string, unknown>;
+        informs_uid?: string[];
+        as_of_date?: string;
+        session_id?: string;
+        retrieval_trace_id?: string;
         agent_id?: string;
     }): Promise<unknown>;
     procedure(req: ProcedureRequest): Promise<unknown>;
@@ -1441,6 +1653,8 @@ declare class MindGraph {
      * merge/dismiss decision (server >= 1.3).
      */
     getMergeCandidates(): Promise<MergeCandidate[]>;
+    /** Load-bearing conclusions awaiting repair after a premise changed. */
+    getStaleDerivations(limit?: number, offset?: number): Promise<StaleDerivation[]>;
     getPendingApprovals(): Promise<GraphNode[]>;
     ingestChunk(req: IngestChunkRequest): Promise<IngestChunkResponse>;
     ingestDocument(req: IngestDocumentRequest): Promise<IngestDocumentResponse>;
@@ -1546,10 +1760,18 @@ declare class MindGraph {
     addOntologyRelationType(schemaId: string, req: OntologyRelationTypeInput): Promise<OntologyRelationType>;
     updateOntologyRelationType(schemaId: string, typeId: string, req: Partial<OntologyRelationTypeInput>): Promise<OntologyRelationType>;
     deleteOntologyRelationType(schemaId: string, typeId: string): Promise<OntologyRelationType>;
+    /** Generate inert semantic classifications for individual human review. */
+    analyzeOntologySemanticGuidance(schemaId: string): Promise<{
+        created: number;
+    }>;
+    /** Read-only exact-identity collision audit; never merges graph data. */
+    auditOntologyDuplicates(schemaId: string): Promise<OntologyDuplicateAudit>;
     listOntologyProposals(opts?: {
         status?: string;
         schema_id?: string;
         object_type?: string;
+        proposal_type?: string;
+        extract_job_id?: string;
         limit?: number;
         offset?: number;
     }): Promise<{
@@ -1666,4 +1888,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 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 };
+export { type AnalogyCandidate, type ArgumentRequest, type ArticleResult, type BatchRequest, type BelievedBy, type CanonicalAttachmentAuthority, type CanonicalAttachmentBinding, type CanonicalAttachmentDirection, type CaptureRequest, type ClaimHub, type ClearResponse, type ClusterClaimSample, type ClusteredClaimHub, type CommitmentRequest, type ConceptCluster, type CreateOntologySchemaRequest, 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 FieldDefinition, type FieldSemantic, type FieldSemanticKind, 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 NormativeKind, type ObjectBacking, type OntologicalBaseKind, type OntologyDuplicateAudit, type OntologyObjectType, type OntologyObjectTypeInput, type OntologyProposal, type OntologyRelationType, type OntologyRelationTypeInput, type OntologySchema, type OntologySchemaDetail, type OrganizationProps, type Participant, type ParticipantSlotKind, type PathStep, type PersonProps, type PlaceProps, type PlanRequest, type ProcedureRequest, type ProposalEdits, type PurgeRequest, type RankedClaimHub, type RelationBacking, type RetrieveContextRequest, type RetrieveContextResponse, type RetrieveRequest, type RiskRequest, type SearchChunk, type SearchResult, type SemanticDependence, type SemanticEvidenceRef, type SemanticEvidenceSourceKind, type SemanticGeneratorRef, type SemanticIdentityMode, type SemanticMatch, type SemanticMatchAlternative, type SemanticMatchStatus, type SemanticModifier, type SemanticModifierMatch, type SemanticNegativeControl, type SemanticParticipantSlot, type SemanticRelationKind, type SemanticReviewDecision, type SemanticRigidity, type SemanticRuntimeTemplate, type SemanticSignal, type SemanticSignalKind, type SemanticTemplateRef, type SemanticTemporalMode, type SemanticTenantBindings, type SemanticValidationAuthoringMode, type SemanticValidationMode, type SessionRequest, type SignalsQuery, type SignalsResponse, type SourceChunk, type StructureRequest, type SynthesisJobResponse, type TextSelector, type TheorySupportGap, type TraverseRequest, type UpdateOntologySchemaRequest };

package/dist/index.d.ts

@@ -72,6 +72,25 @@ interface MergeCandidate {
     similarity: number | null;
     /** How the candidate was found: "exact" | "fuzzy" | "semantic" | "llm". */
     method: string | null;
+    /**
+     * Normalized `truth_status` of each side (Claims), so curation UIs can
+     * warn before merging a refuted claim. Absent on servers older than the
+     * hardening batch.
+     */
+    node_a_truth_status?: string | null;
+    node_b_truth_status?: string | null;
+}
+/** A derived statement awaiting review after a load-bearing premise changed. */
+interface StaleDerivation {
+    invalidation_uid: string;
+    invalidator_uid: string;
+    invalidator_label: string;
+    node_uid: string;
+    node_label: string;
+    node_summary: string;
+    node_type: string;
+    reason: string | null;
+    invalidated_at: string | null;
 }
 /** A `/retrieve` hybrid result: the full node plus the fused RRF score. */
 interface HybridSearchResult {
@@ -99,11 +118,10 @@ interface PathStep {
     edge_type: string | null;
     depth: number;
     parent_uid: string | null;
-    /** Min-plus cost of the returned BFS path from the start node
-     * (sum of -ln(weight), weights clamped to (1e-9, 1]); cost of the path
-     * the traversal returned, not the cheapest path. 0 at the start node. */
+    /** Min-plus cost of the selected cheapest path from the start node
+     * (sum of -ln(weight), weights clamped to (1e-9, 1]). */
     path_cost?: number;
-    /** Product of edge confidences along the returned BFS path (clamped to
+    /** Product of edge confidences along the selected min-cost path (clamped to
      * (1e-9, 1]); a ranking signal, not a calibrated probability. 1 at the
      * start node. */
     path_confidence?: number;
@@ -271,6 +289,12 @@ interface DeliberationRequest {
     chosen_option_uid?: string;
     blocks_uid?: string;
     informs_uid?: string[];
+    /** ISO 8601 date when resolve-time context was available. */
+    as_of_date?: string;
+    /** Session whose retrieval context informed the resolution. */
+    session_id?: string;
+    /** Optional identifier of the decision-time retrieval trace. */
+    retrieval_trace_id?: string;
     props?: Record<string, unknown>;
     agent_id?: string;
 }
@@ -311,6 +335,8 @@ interface SessionRequest {
 }
 interface DistillRequest {
     label: string;
+    /** Defaults to "summary" for backward compatibility. */
+    output_type?: "summary" | "lesson";
     summary?: string;
     confidence?: number;
     salience?: number;
@@ -377,7 +403,7 @@ interface RetrieveRequest {
      * Retrieval action. Note: `"semantic"` requires a configured embedding
      * provider on the server; for semantic search use `retrieveContext()` instead.
      */
-    action: "text" | "semantic" | "hybrid" | "active_goals" | "open_questions" | "weak_claims" | "pending_approvals" | "unresolved_contradictions" | "preferences" | "layer" | "recent";
+    action: "text" | "semantic" | "hybrid" | "active_goals" | "open_questions" | "weak_claims" | "pending_approvals" | "unresolved_contradictions" | "stale_derivations" | "preferences" | "layer" | "recent";
     /**
      * Required for `"text"`, `"semantic"`, `"hybrid"`. Optional for
      * `"preferences"`: with a `query` you get topic-relevant preferences (the
@@ -427,7 +453,12 @@ interface TraverseRequest {
     max_depth?: number;
     direction?: "outgoing" | "incoming" | "both";
     edge_types?: string[];
+    exclude_edge_types?: string[];
     weight_threshold?: number;
+    /** Include ingestion/provenance edges excluded by default. */
+    include_provenance?: boolean;
+    /** Global distinct-node budget, including the seed (default 500). */
+    max_nodes?: 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). */
@@ -571,6 +602,11 @@ interface RetrieveContextRequest {
     layer?: string;
     include_graph?: boolean;
     min_similarity?: number;
+    /** Reserve up to this many node slots for cheapest-first graph expansion.
+     * Default 0 preserves direct-only retrieval. */
+    graph_expansion_limit?: number;
+    /** Maximum graph-expansion hops (default 2). */
+    graph_max_depth?: 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`.
@@ -666,6 +702,11 @@ interface RetrieveContextResponse {
             currently_valid?: boolean;
             /** As-of variant of `currently_valid` when the request set `valid_at`. */
             valid_at_time?: boolean;
+            /** Present when the node was added by budgeted graph expansion. */
+            retrieval_origin?: "graph_expansion";
+            retrieval_path_cost?: number;
+            retrieval_depth?: number;
+            retrieval_parent_uid?: string | null;
         })[];
         edges: Record<string, unknown>[];
     };
@@ -833,6 +874,125 @@ interface MindGraphConfig {
     /** Initial backoff in ms before first retry. Doubles each attempt. Default: 1000. */
     retryBackoffMs?: number;
 }
+/** Schema-level behavior for compiled semantic-match diagnostics. */
+type SemanticValidationMode = "off" | "advisory" | "review" | "strict";
+/** Validation modes accepted by the M5.1 schema update endpoint. */
+type SemanticValidationAuthoringMode = "off" | "advisory";
+/** The six storage/runtime behaviors supported by semantic profile v1. */
+type SemanticRuntimeTemplate = "entity" | "dependent_entity" | "collective" | "relationship_object" | "event" | "observation";
+/** Optional orthogonal classifications that do not introduce storage layouts. */
+type SemanticModifier = "role" | "phase" | "social_construct";
+type OntologicalBaseKind = "kind" | "subkind" | "dependent_particular" | "collective" | "relator" | "event" | "quality" | "unspecified";
+type SemanticRigidity = "rigid" | "anti_rigid" | "unspecified";
+type SemanticIdentityMode = "provided" | "inherited" | "derived" | "unspecified";
+type SemanticDependence = "independent" | "bearer" | "external" | "unspecified";
+type SemanticTemporalMode = "persistent" | "interval" | "occurrence" | "observation_time" | "unspecified";
+type SemanticMatchStatus = "candidate" | "accepted" | "rejected" | "superseded";
+type SemanticEvidenceSourceKind = "corpus_span" | "declared_structure" | "sql_metadata" | "graph_usage" | "human_review" | "llm_classification";
+type SemanticSignalKind = "own_identity" | "borrowed_identity" | "host_attachment" | "participant_count" | "membership_relation" | "occurs_at" | "observed_at" | "externally_assigned" | "lifecycle_stage" | "institutionally_defined" | "relation_endpoints";
+type ParticipantSlotKind = "bearer" | "player" | "context" | "subject" | "source" | "participant" | "member" | "observed_entity" | "base_type";
+/** A typed participant requirement resolved against the containing schema version. */
+interface SemanticParticipantSlot {
+    name: string;
+    template_slot: ParticipantSlotKind;
+    object_types?: string[];
+    min?: number;
+    max?: number;
+    relation_type?: string;
+}
+type FieldSemanticKind = "phase_indicator" | "role_indicator" | "internal_disposition" | "event_time" | "observed_at" | "source_wording";
+/** Typed meaning for a concrete object field; prose is never compiled. */
+interface FieldSemantic {
+    field: string;
+    semantic: FieldSemanticKind;
+    temporal_mode?: SemanticTemporalMode;
+    lossy?: boolean;
+}
+type NormativeKind = "need" | "constraint" | "obligation" | "preference" | "unspecified";
+type CanonicalAttachmentAuthority = "relation" | "reference_field";
+type CanonicalAttachmentDirection = "outgoing" | "incoming";
+/** Declares which of a relation/reference-field pair owns an attachment fact. */
+interface CanonicalAttachmentBinding {
+    slot: string;
+    relation_type: string;
+    reference_field?: string;
+    authority: CanonicalAttachmentAuthority;
+    direction: CanonicalAttachmentDirection;
+}
+/** Pins a match to one immutable global archetype template version. */
+interface SemanticTemplateRef {
+    id: string;
+    version: number;
+}
+interface SemanticEvidenceRef {
+    id: string;
+    source_kind: SemanticEvidenceSourceKind;
+    source_ref: string;
+    asserted_by?: string;
+    asserted_at?: string;
+}
+interface SemanticGeneratorRef {
+    id: string;
+    version: number;
+    proposal_ref?: string;
+}
+interface SemanticSignal {
+    signal: SemanticSignalKind;
+    value: boolean | number | string;
+    evidence_ref: SemanticEvidenceRef;
+    generator?: SemanticGeneratorRef;
+    confidence: number;
+    observed_at?: string;
+}
+interface SemanticNegativeControl {
+    template: SemanticTemplateRef;
+    reason: string;
+}
+interface SemanticMatchAlternative {
+    template: SemanticTemplateRef;
+    confidence: number;
+    reason: string;
+    evidence?: SemanticSignal[];
+}
+interface SemanticModifierMatch {
+    template: SemanticTemplateRef;
+    evidence: SemanticSignal[];
+    negative_control: SemanticNegativeControl;
+}
+interface SemanticReviewDecision {
+    actor: string;
+    decided_at: string;
+    rationale: string;
+    premises?: string[];
+    supersedes?: string;
+}
+interface SemanticTenantBindings {
+    ontological_base_kind?: OntologicalBaseKind;
+    rigidity?: SemanticRigidity;
+    identity_mode?: SemanticIdentityMode;
+    dependence?: SemanticDependence;
+    temporal_mode?: SemanticTemporalMode;
+    slots?: SemanticParticipantSlot[];
+    fields?: FieldSemantic[];
+    normative_kind?: NormativeKind;
+    attachments?: CanonicalAttachmentBinding[];
+}
+type SemanticRelationKind = "association" | "mediation" | "participation" | "membership" | "characterization" | "part_whole" | "derivation" | "classification" | "unspecified";
+/** Unified evidence-backed classification for object and relation types. */
+interface SemanticMatch {
+    version: number;
+    template: SemanticTemplateRef;
+    modifiers?: SemanticModifierMatch[];
+    status: SemanticMatchStatus;
+    evidence: SemanticSignal[];
+    negative_control: SemanticNegativeControl;
+    alternatives?: SemanticMatchAlternative[];
+    bindings?: SemanticTenantBindings;
+    confidence: number;
+    rationale: string;
+    proposed_by?: SemanticGeneratorRef[];
+    decision?: SemanticReviewDecision;
+}
 /** Field schema entry inside `OntologyObjectType.fields_json`. */
 interface FieldDefinition {
     name: string;
@@ -910,6 +1070,12 @@ interface OntologySchema {
     description?: string;
     status: "draft" | "active" | "deprecated" | "archived";
     version: number;
+    /**
+     * Advisory semantic-profile validation is opt-in per schema. Optional so the
+     * SDK tolerates servers that predate the field (the server itself defaults
+     * absent rows to "off").
+     */
+    semantic_validation_mode?: SemanticValidationMode;
     propose_status?: "pending" | "running" | "ready" | "failed" | null;
     propose_job_id?: string | null;
     propose_error?: string | null;
@@ -935,6 +1101,8 @@ interface OntologyObjectType {
     extraction_hints?: string | null;
     default_confidence: number;
     review_policy: "always" | "low_confidence" | "never";
+    /** Accepted semantic match. Candidates remain in the proposal ledger. */
+    semantic_match?: SemanticMatch | null;
     /** Datasource binding (null = extracted/authored). */
     backing?: ObjectBacking | null;
     status: "active" | "deprecated" | "archived";
@@ -957,7 +1125,10 @@ interface OntologyRelationType {
     inverse_relation_type?: string | null;
     fields_json: FieldDefinition[];
     extraction_hints?: string | null;
+    default_confidence: number;
     review_policy: "always" | "low_confidence" | "never";
+    /** Accepted relation match. Candidates remain in the proposal ledger. */
+    semantic_match?: SemanticMatch | null;
     /** Datasource binding (null = extracted/authored). */
     backing?: RelationBacking | null;
     status: "active" | "deprecated" | "archived";
@@ -986,6 +1157,7 @@ interface CreateOntologySchemaRequest {
 interface UpdateOntologySchemaRequest {
     name?: string;
     description?: string;
+    semantic_validation_mode?: SemanticValidationAuthoringMode;
 }
 interface OntologyObjectTypeInput {
     name: string;
@@ -999,6 +1171,8 @@ interface OntologyObjectTypeInput {
     extraction_hints?: string;
     default_confidence?: number;
     review_policy?: "always" | "low_confidence" | "never";
+    /** Add, replace, or clear the object's accepted semantic match. */
+    semantic_match?: SemanticMatch | null;
     /** Bind this object type to an external source (SQL). Omit for extracted/authored. */
     backing?: ObjectBacking | null;
 }
@@ -1014,7 +1188,10 @@ interface OntologyRelationTypeInput {
     inverse_relation_type?: string;
     fields?: FieldDefinition[];
     extraction_hints?: string;
+    default_confidence?: number;
     review_policy?: "always" | "low_confidence" | "never";
+    /** Add, replace, or clear the relation's accepted semantic match. */
+    semantic_match?: SemanticMatch | null;
     /** Bind this relation to an FK column or M:M join table. Both endpoints must be sql-mapped. */
     backing?: RelationBacking | null;
 }
@@ -1025,6 +1202,8 @@ interface OntologyProposal {
     schema_id: string;
     proposal_type: string;
     proposed_by_agent_id?: string | null;
+    proposed_by_user_id?: string | null;
+    extract_job_id?: string | null;
     source_uids: string[];
     source_scope_ids: string[];
     changes_json: {
@@ -1049,6 +1228,34 @@ interface OntologyProposal {
     resolved_at?: string | null;
     resolved_by?: string | null;
 }
+interface OntologyDuplicateAudit {
+    schema_id: string;
+    object_groups: Array<{
+        object_type: string;
+        identity_hash: string;
+        canonical_uid: string;
+        members: Array<{
+            uid: string;
+            label: string;
+            source_uids: string[];
+        }>;
+        conflicting_fields: string[];
+        affected_edges: number;
+        auto_merge_safe: boolean;
+    }>;
+    relation_groups: Array<{
+        relation_type: string;
+        identity_hash: string;
+        canonical_uid: string;
+        edge_uids: string[];
+        from_uid: string;
+        to_uid: string;
+        auto_merge_safe: boolean;
+    }>;
+    objects_without_deterministic_identity: number;
+    context_ambiguous_objects: number;
+    repeatable_relations_skipped: number;
+}
 interface ProposalEdits {
     canonical_name?: string;
     fields?: Record<string, unknown>;
@@ -1235,6 +1442,11 @@ declare class MindGraph {
      */
     resolveDecision(decisionUid: string, chosenOptionUid: string, opts?: {
         summary?: string;
+        props?: Record<string, unknown>;
+        informs_uid?: string[];
+        as_of_date?: string;
+        session_id?: string;
+        retrieval_trace_id?: string;
         agent_id?: string;
     }): Promise<unknown>;
     procedure(req: ProcedureRequest): Promise<unknown>;
@@ -1441,6 +1653,8 @@ declare class MindGraph {
      * merge/dismiss decision (server >= 1.3).
      */
     getMergeCandidates(): Promise<MergeCandidate[]>;
+    /** Load-bearing conclusions awaiting repair after a premise changed. */
+    getStaleDerivations(limit?: number, offset?: number): Promise<StaleDerivation[]>;
     getPendingApprovals(): Promise<GraphNode[]>;
     ingestChunk(req: IngestChunkRequest): Promise<IngestChunkResponse>;
     ingestDocument(req: IngestDocumentRequest): Promise<IngestDocumentResponse>;
@@ -1546,10 +1760,18 @@ declare class MindGraph {
     addOntologyRelationType(schemaId: string, req: OntologyRelationTypeInput): Promise<OntologyRelationType>;
     updateOntologyRelationType(schemaId: string, typeId: string, req: Partial<OntologyRelationTypeInput>): Promise<OntologyRelationType>;
     deleteOntologyRelationType(schemaId: string, typeId: string): Promise<OntologyRelationType>;
+    /** Generate inert semantic classifications for individual human review. */
+    analyzeOntologySemanticGuidance(schemaId: string): Promise<{
+        created: number;
+    }>;
+    /** Read-only exact-identity collision audit; never merges graph data. */
+    auditOntologyDuplicates(schemaId: string): Promise<OntologyDuplicateAudit>;
     listOntologyProposals(opts?: {
         status?: string;
         schema_id?: string;
         object_type?: string;
+        proposal_type?: string;
+        extract_job_id?: string;
         limit?: number;
         offset?: number;
     }): Promise<{
@@ -1666,4 +1888,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 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 };
+export { type AnalogyCandidate, type ArgumentRequest, type ArticleResult, type BatchRequest, type BelievedBy, type CanonicalAttachmentAuthority, type CanonicalAttachmentBinding, type CanonicalAttachmentDirection, type CaptureRequest, type ClaimHub, type ClearResponse, type ClusterClaimSample, type ClusteredClaimHub, type CommitmentRequest, type ConceptCluster, type CreateOntologySchemaRequest, 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 FieldDefinition, type FieldSemantic, type FieldSemanticKind, 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 NormativeKind, type ObjectBacking, type OntologicalBaseKind, type OntologyDuplicateAudit, type OntologyObjectType, type OntologyObjectTypeInput, type OntologyProposal, type OntologyRelationType, type OntologyRelationTypeInput, type OntologySchema, type OntologySchemaDetail, type OrganizationProps, type Participant, type ParticipantSlotKind, type PathStep, type PersonProps, type PlaceProps, type PlanRequest, type ProcedureRequest, type ProposalEdits, type PurgeRequest, type RankedClaimHub, type RelationBacking, type RetrieveContextRequest, type RetrieveContextResponse, type RetrieveRequest, type RiskRequest, type SearchChunk, type SearchResult, type SemanticDependence, type SemanticEvidenceRef, type SemanticEvidenceSourceKind, type SemanticGeneratorRef, type SemanticIdentityMode, type SemanticMatch, type SemanticMatchAlternative, type SemanticMatchStatus, type SemanticModifier, type SemanticModifierMatch, type SemanticNegativeControl, type SemanticParticipantSlot, type SemanticRelationKind, type SemanticReviewDecision, type SemanticRigidity, type SemanticRuntimeTemplate, type SemanticSignal, type SemanticSignalKind, type SemanticTemplateRef, type SemanticTemporalMode, type SemanticTenantBindings, type SemanticValidationAuthoringMode, type SemanticValidationMode, type SessionRequest, type SignalsQuery, type SignalsResponse, type SourceChunk, type StructureRequest, type SynthesisJobResponse, type TextSelector, type TheorySupportGap, type TraverseRequest, type UpdateOntologySchemaRequest };

package/dist/index.js

@@ -564,6 +564,10 @@ var MindGraph = class {
   async getMergeCandidates() {
     return this.post("/retrieve", { action: "merge_candidates" });
   }
+  /** Load-bearing conclusions awaiting repair after a premise changed. */
+  async getStaleDerivations(limit = 50, offset = 0) {
+    return this.post("/retrieve", { action: "stale_derivations", limit, offset });
+  }
   async getPendingApprovals() {
     return this.get("/approvals/pending");
   }
@@ -745,12 +749,25 @@ var MindGraph = class {
       `/v1/ontology/schemas/${schemaId}/relation-types/${typeId}`
     );
   }
+  /** Generate inert semantic classifications for individual human review. */
+  async analyzeOntologySemanticGuidance(schemaId) {
+    return this.post(
+      `/v1/ontology/schemas/${schemaId}/semantic-guidance/analyze`,
+      {}
+    );
+  }
+  /** Read-only exact-identity collision audit; never merges graph data. */
+  async auditOntologyDuplicates(schemaId) {
+    return this.post(`/v1/ontology/schemas/${schemaId}/duplicates/audit`, {});
+  }
   // ---- Proposals ----
   async listOntologyProposals(opts) {
     const q = new URLSearchParams();
     if (opts?.status) q.set("status", opts.status);
     if (opts?.schema_id) q.set("schema_id", opts.schema_id);
     if (opts?.object_type) q.set("object_type", opts.object_type);
+    if (opts?.proposal_type) q.set("proposal_type", opts.proposal_type);
+    if (opts?.extract_job_id) q.set("extract_job_id", opts.extract_job_id);
     if (opts?.limit != null) q.set("limit", String(opts.limit));
     if (opts?.offset != null) q.set("offset", String(opts.offset));
     const qs = q.toString();

package/dist/index.mjs

@@ -537,6 +537,10 @@ var MindGraph = class {
   async getMergeCandidates() {
     return this.post("/retrieve", { action: "merge_candidates" });
   }
+  /** Load-bearing conclusions awaiting repair after a premise changed. */
+  async getStaleDerivations(limit = 50, offset = 0) {
+    return this.post("/retrieve", { action: "stale_derivations", limit, offset });
+  }
   async getPendingApprovals() {
     return this.get("/approvals/pending");
   }
@@ -718,12 +722,25 @@ var MindGraph = class {
       `/v1/ontology/schemas/${schemaId}/relation-types/${typeId}`
     );
   }
+  /** Generate inert semantic classifications for individual human review. */
+  async analyzeOntologySemanticGuidance(schemaId) {
+    return this.post(
+      `/v1/ontology/schemas/${schemaId}/semantic-guidance/analyze`,
+      {}
+    );
+  }
+  /** Read-only exact-identity collision audit; never merges graph data. */
+  async auditOntologyDuplicates(schemaId) {
+    return this.post(`/v1/ontology/schemas/${schemaId}/duplicates/audit`, {});
+  }
   // ---- Proposals ----
   async listOntologyProposals(opts) {
     const q = new URLSearchParams();
     if (opts?.status) q.set("status", opts.status);
     if (opts?.schema_id) q.set("schema_id", opts.schema_id);
     if (opts?.object_type) q.set("object_type", opts.object_type);
+    if (opts?.proposal_type) q.set("proposal_type", opts.proposal_type);
+    if (opts?.extract_job_id) q.set("extract_job_id", opts.extract_job_id);
     if (opts?.limit != null) q.set("limit", String(opts.limit));
     if (opts?.offset != null) q.set("offset", String(opts.offset));
     const qs = q.toString();

package/package.json

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