@plur-ai/core 0.3.0 → 0.4.0

package/dist/index.d.ts

@@ -260,6 +260,8 @@ declare const EngramSchema: z.ZodObject<{
     }>>;
     /** Extensible key-value data for domain-specific fields. */
     structured_data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    /** Polarity classification: 'do' for directives, 'dont' for prohibitions, null for unclassified. */
+    polarity: z.ZodDefault<z.ZodNullable<z.ZodEnum<["do", "dont"]>>>;
 }, "strip", z.ZodTypeAny, {
     type: "behavioral" | "architectural" | "procedural" | "terminological";
     status: "active" | "dormant" | "retired" | "candidate";
@@ -298,6 +300,7 @@ declare const EngramSchema: z.ZodObject<{
         negative: number;
         neutral: number;
     };
+    polarity: "do" | "dont" | null;
     rationale?: string | undefined;
     contraindications?: string[] | undefined;
     source?: string | undefined;
@@ -446,6 +449,7 @@ declare const EngramSchema: z.ZodObject<{
         contradiction_rate?: number | undefined;
     } | undefined;
     structured_data?: Record<string, unknown> | undefined;
+    polarity?: "do" | "dont" | null | undefined;
 }>;
 type Engram = z.infer<typeof EngramSchema>;
 type KnowledgeAnchor = z.infer<typeof KnowledgeAnchorSchema>;
@@ -611,6 +615,7 @@ declare const PlurConfigSchema: z.ZodObject<{
         spread_budget?: number | undefined;
         co_access?: boolean | undefined;
     }>>>;
+    allow_secrets: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
 }, "strip", z.ZodTypeAny, {
     auto_learn?: boolean | undefined;
     auto_capture?: boolean | undefined;
@@ -623,6 +628,7 @@ declare const PlurConfigSchema: z.ZodObject<{
         spread_budget: number;
         co_access: boolean;
     } | undefined;
+    allow_secrets?: boolean | undefined;
 }, {
     auto_learn?: boolean | undefined;
     auto_capture?: boolean | undefined;
@@ -635,6 +641,7 @@ declare const PlurConfigSchema: z.ZodObject<{
         spread_budget?: number | undefined;
         co_access?: boolean | undefined;
     } | undefined;
+    allow_secrets?: boolean | undefined;
 }>;
 type PlurConfig = z.infer<typeof PlurConfigSchema>;
 
@@ -666,6 +673,7 @@ interface InjectOptions {
 }
 interface InjectionResult {
     directives: string;
+    constraints: string;
     consider: string;
     count: number;
     tokens_used: number;
@@ -684,9 +692,470 @@ interface TimelineQuery {
     search?: string;
 }
 
+interface TypedRole {
+    role: string;
+    domain_instance: string;
+}
+interface RelationalTriple {
+    subject: TypedRole;
+    predicate: string;
+    object: TypedRole;
+    outcome?: string;
+}
+interface RelationalAnalysis {
+    engram_id: string;
+    triples: RelationalTriple[];
+    goal_context: string;
+    is_failure_driven: boolean;
+    domain: string;
+    polarity: 'do' | 'dont';
+}
+declare function analyzeStructure(engrams: Engram[], llm: LlmFunction): Promise<RelationalAnalysis[]>;
+
+interface EngramCluster {
+    cluster_id: string;
+    members: RelationalAnalysis[];
+    domains: string[];
+    is_cross_domain: boolean;
+    cohesion: number;
+}
+/**
+ * Cluster relational analyses by structural similarity.
+ * Prefers embedding-based cosine similarity (384-dim BGE vectors) for semantic depth.
+ * Falls back to token overlap when @huggingface/transformers is unavailable.
+ */
+declare function clusterByStructure(analyses: RelationalAnalysis[], threshold?: number): Promise<EngramCluster[]>;
+
+declare const StructuralTemplateSchema: z.ZodObject<{
+    goal_type: z.ZodString;
+    constraint_type: z.ZodString;
+    outcome_type: z.ZodString;
+    template: z.ZodString;
+    /** Structural frame — declares which relational pattern this meta-engram uses.
+     *  Allows flexible analogy beyond rigid [goal]+[constraint]->[outcome]. */
+    structure_type: z.ZodDefault<z.ZodEnum<["goal-constraint-outcome", "feedback-loop", "causal-chain", "recursive", "tradeoff", "freeform"]>>;
+    /** For patterns that don't fit the standard template fields — the LLM's own structural description */
+    freeform_structure: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    template: string;
+    goal_type: string;
+    constraint_type: string;
+    outcome_type: string;
+    structure_type: "goal-constraint-outcome" | "feedback-loop" | "causal-chain" | "recursive" | "tradeoff" | "freeform";
+    freeform_structure?: string | undefined;
+}, {
+    template: string;
+    goal_type: string;
+    constraint_type: string;
+    outcome_type: string;
+    structure_type?: "goal-constraint-outcome" | "feedback-loop" | "causal-chain" | "recursive" | "tradeoff" | "freeform" | undefined;
+    freeform_structure?: string | undefined;
+}>;
+declare const EvidenceEntrySchema: z.ZodObject<{
+    engram_id: z.ZodString;
+    domain: z.ZodString;
+    mapping_rationale: z.ZodString;
+    alignment_score: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    domain: string;
+    engram_id: string;
+    mapping_rationale: string;
+    alignment_score: number;
+}, {
+    domain: string;
+    engram_id: string;
+    mapping_rationale: string;
+    alignment_score: number;
+}>;
+declare const FalsificationSchema: z.ZodObject<{
+    expected_conditions: z.ZodString;
+    expected_exceptions: z.ZodString;
+    test_prediction: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    expected_conditions: string;
+    expected_exceptions: string;
+    test_prediction?: string | undefined;
+}, {
+    expected_conditions: string;
+    expected_exceptions: string;
+    test_prediction?: string | undefined;
+}>;
+declare const MetaConfidenceSchema: z.ZodObject<{
+    evidence_count: z.ZodNumber;
+    domain_count: z.ZodNumber;
+    structural_depth: z.ZodNumber;
+    validation_ratio: z.ZodDefault<z.ZodNumber>;
+    composite: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    evidence_count: number;
+    domain_count: number;
+    structural_depth: number;
+    validation_ratio: number;
+    composite: number;
+}, {
+    evidence_count: number;
+    domain_count: number;
+    structural_depth: number;
+    composite: number;
+    validation_ratio?: number | undefined;
+}>;
+declare const DomainCoverageSchema: z.ZodObject<{
+    validated: z.ZodArray<z.ZodString, "many">;
+    failed: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    predicted: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    validated: string[];
+    failed: string[];
+    predicted: string[];
+}, {
+    validated: string[];
+    failed?: string[] | undefined;
+    predicted?: string[] | undefined;
+}>;
+declare const HierarchyPositionSchema: z.ZodObject<{
+    level: z.ZodEnum<["mop", "top"]>;
+    parent: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    children: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    level: "mop" | "top";
+    parent: string | null;
+    children: string[];
+}, {
+    level: "mop" | "top";
+    parent?: string | null | undefined;
+    children?: string[] | undefined;
+}>;
+declare const MetaFieldSchema: z.ZodObject<{
+    structure: z.ZodObject<{
+        goal_type: z.ZodString;
+        constraint_type: z.ZodString;
+        outcome_type: z.ZodString;
+        template: z.ZodString;
+        /** Structural frame — declares which relational pattern this meta-engram uses.
+         *  Allows flexible analogy beyond rigid [goal]+[constraint]->[outcome]. */
+        structure_type: z.ZodDefault<z.ZodEnum<["goal-constraint-outcome", "feedback-loop", "causal-chain", "recursive", "tradeoff", "freeform"]>>;
+        /** For patterns that don't fit the standard template fields — the LLM's own structural description */
+        freeform_structure: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        template: string;
+        goal_type: string;
+        constraint_type: string;
+        outcome_type: string;
+        structure_type: "goal-constraint-outcome" | "feedback-loop" | "causal-chain" | "recursive" | "tradeoff" | "freeform";
+        freeform_structure?: string | undefined;
+    }, {
+        template: string;
+        goal_type: string;
+        constraint_type: string;
+        outcome_type: string;
+        structure_type?: "goal-constraint-outcome" | "feedback-loop" | "causal-chain" | "recursive" | "tradeoff" | "freeform" | undefined;
+        freeform_structure?: string | undefined;
+    }>;
+    evidence: z.ZodArray<z.ZodObject<{
+        engram_id: z.ZodString;
+        domain: z.ZodString;
+        mapping_rationale: z.ZodString;
+        alignment_score: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        domain: string;
+        engram_id: string;
+        mapping_rationale: string;
+        alignment_score: number;
+    }, {
+        domain: string;
+        engram_id: string;
+        mapping_rationale: string;
+        alignment_score: number;
+    }>, "many">;
+    domain_coverage: z.ZodObject<{
+        validated: z.ZodArray<z.ZodString, "many">;
+        failed: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        predicted: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        validated: string[];
+        failed: string[];
+        predicted: string[];
+    }, {
+        validated: string[];
+        failed?: string[] | undefined;
+        predicted?: string[] | undefined;
+    }>;
+    falsification: z.ZodObject<{
+        expected_conditions: z.ZodString;
+        expected_exceptions: z.ZodString;
+        test_prediction: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        expected_conditions: string;
+        expected_exceptions: string;
+        test_prediction?: string | undefined;
+    }, {
+        expected_conditions: string;
+        expected_exceptions: string;
+        test_prediction?: string | undefined;
+    }>;
+    confidence: z.ZodObject<{
+        evidence_count: z.ZodNumber;
+        domain_count: z.ZodNumber;
+        structural_depth: z.ZodNumber;
+        validation_ratio: z.ZodDefault<z.ZodNumber>;
+        composite: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        evidence_count: number;
+        domain_count: number;
+        structural_depth: number;
+        validation_ratio: number;
+        composite: number;
+    }, {
+        evidence_count: number;
+        domain_count: number;
+        structural_depth: number;
+        composite: number;
+        validation_ratio?: number | undefined;
+    }>;
+    hierarchy: z.ZodObject<{
+        level: z.ZodEnum<["mop", "top"]>;
+        parent: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        children: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        level: "mop" | "top";
+        parent: string | null;
+        children: string[];
+    }, {
+        level: "mop" | "top";
+        parent?: string | null | undefined;
+        children?: string[] | undefined;
+    }>;
+    pipeline_version: z.ZodString;
+    last_validated: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    confidence: {
+        evidence_count: number;
+        domain_count: number;
+        structural_depth: number;
+        validation_ratio: number;
+        composite: number;
+    };
+    structure: {
+        template: string;
+        goal_type: string;
+        constraint_type: string;
+        outcome_type: string;
+        structure_type: "goal-constraint-outcome" | "feedback-loop" | "causal-chain" | "recursive" | "tradeoff" | "freeform";
+        freeform_structure?: string | undefined;
+    };
+    evidence: {
+        domain: string;
+        engram_id: string;
+        mapping_rationale: string;
+        alignment_score: number;
+    }[];
+    domain_coverage: {
+        validated: string[];
+        failed: string[];
+        predicted: string[];
+    };
+    falsification: {
+        expected_conditions: string;
+        expected_exceptions: string;
+        test_prediction?: string | undefined;
+    };
+    hierarchy: {
+        level: "mop" | "top";
+        parent: string | null;
+        children: string[];
+    };
+    pipeline_version: string;
+    last_validated?: string | undefined;
+}, {
+    confidence: {
+        evidence_count: number;
+        domain_count: number;
+        structural_depth: number;
+        composite: number;
+        validation_ratio?: number | undefined;
+    };
+    structure: {
+        template: string;
+        goal_type: string;
+        constraint_type: string;
+        outcome_type: string;
+        structure_type?: "goal-constraint-outcome" | "feedback-loop" | "causal-chain" | "recursive" | "tradeoff" | "freeform" | undefined;
+        freeform_structure?: string | undefined;
+    };
+    evidence: {
+        domain: string;
+        engram_id: string;
+        mapping_rationale: string;
+        alignment_score: number;
+    }[];
+    domain_coverage: {
+        validated: string[];
+        failed?: string[] | undefined;
+        predicted?: string[] | undefined;
+    };
+    falsification: {
+        expected_conditions: string;
+        expected_exceptions: string;
+        test_prediction?: string | undefined;
+    };
+    hierarchy: {
+        level: "mop" | "top";
+        parent?: string | null | undefined;
+        children?: string[] | undefined;
+    };
+    pipeline_version: string;
+    last_validated?: string | undefined;
+}>;
+type MetaField = z.infer<typeof MetaFieldSchema>;
+type StructuralTemplate = z.infer<typeof StructuralTemplateSchema>;
+type EvidenceEntry = z.infer<typeof EvidenceEntrySchema>;
+type MetaConfidence = z.infer<typeof MetaConfidenceSchema>;
+type DomainCoverage = z.infer<typeof DomainCoverageSchema>;
+type HierarchyPosition = z.infer<typeof HierarchyPositionSchema>;
+type Falsification = z.infer<typeof FalsificationSchema>;
+
+interface MemberAlignment {
+    engram_id: string;
+    alignment_score: number;
+    mapping_rationale: string;
+}
+interface AlignmentResult {
+    cluster_id: string;
+    common_structure: StructuralTemplate;
+    member_alignments: MemberAlignment[];
+    structural_depth: number;
+    systematicity: number;
+    candidate_inferences: string[];
+}
+declare function alignCluster(cluster: EngramCluster, llm: LlmFunction): Promise<AlignmentResult | null>;
+
+declare function formulateMetaEngram(alignment: AlignmentResult, llm: LlmFunction, existingMetas?: Engram[], 
+/** Distinct domains from the cluster (provided by pipeline orchestrator) */
+domains?: string[]): Promise<Engram | null>;
+
+interface ValidationResult {
+    meta_engram_id: string;
+    test_domain: string;
+    prediction_held: boolean;
+    matching_engram_id: string | null;
+    alignment_score: number;
+    rationale: string;
+}
+declare function validateMetaEngram(meta: Engram, testEngrams: Engram[], testDomain: string, llm: LlmFunction): Promise<ValidationResult>;
+
+/**
+ * Organize meta-engrams into MOP/TOP hierarchy.
+ * Purely deterministic: pairwise template similarity, parent-child by domain subsumption.
+ * Returns engrams with updated hierarchy fields.
+ */
+declare function organizeHierarchy(metaEngrams: Engram[]): Engram[];
+
+interface ExtractOptions {
+    /** Whether to run Stage 5 validation (default: false — can be deferred) */
+    run_validation?: boolean;
+    /** Engrams to use for validation (held-out domains) */
+    validation_engrams?: Engram[];
+    /** Existing meta-engrams to check for deduplication */
+    existing_metas?: Engram[];
+    /** Minimum cluster size to attempt alignment (default: 2) */
+    min_cluster_size?: number;
+}
+interface ExtractionResult {
+    engrams_analyzed: number;
+    clusters_found: number;
+    alignments_passed: number;
+    meta_engrams_extracted: number;
+    rejected_as_platitudes: number;
+    validation_results: ValidationResult[];
+    results: Engram[];
+    duration_ms: number;
+}
+/**
+ * Full meta-engram extraction pipeline: Stages 1 → 2 → 3 → 4 → 5(optional) → 6
+ */
+declare function extractMetaEngrams(engrams: Engram[], llm: LlmFunction, options?: ExtractOptions): Promise<ExtractionResult>;
+
+/** Patterns that are too generic to be useful as meta-engrams */
+declare const PLATITUDE_PATTERNS: string[];
+declare function isPlatitude(statement: string): boolean;
+
+/** Token-based similarity between two template strings. Used for clustering, dedup, and hierarchy. */
+declare function tokenSimilarity(a: string, b: string): number;
+
+declare function classifyPolarity(statement: string): 'dont' | null;
+
+/**
+ * Minimal interface for confidence computation.
+ * Accepts any object with these optional fields — works with Engram,
+ * AgentEngram, WireEngram, or any subset.
+ */
+interface ConfidenceInput {
+    feedback_signals?: {
+        positive: number;
+        negative: number;
+        neutral: number;
+    };
+    consolidated?: boolean;
+}
+/**
+ * Compute a confidence score (0.0-1.0) from feedback signals.
+ *
+ * Uses sigmoid of net feedback ratio, dampened by sample size.
+ * No feedback → 0.5 (neutral). Heavy positive → approaches 1.0.
+ * Small sample sizes are dampened toward 0.5.
+ */
+declare function computeConfidence(input: ConfidenceInput): number;
+/**
+ * Compute a composite meta-confidence score (0.0-1.0) for a META- engram
+ * based on the richness of its evidence, domain coverage, structural depth,
+ * and validation ratio.
+ *
+ * Weights:
+ *   - evidenceCount (capped at 5): 25%
+ *   - domainCount   (capped at 3): 35%
+ *   - structuralDepth (capped at 3): 20%
+ *   - validationRatio (0.0–1.0): 20%
+ */
+declare function computeMetaConfidence(evidenceCount: number, domainCount: number, structuralDepth: number, validationRatio: number): number;
+/** Convert numeric confidence to human-readable band */
+declare function confidenceBand(score: number): 'low' | 'medium' | 'high';
+
+interface ToolCallRecord {
+    tool: string;
+    args_keys: string;
+    timestamp: string;
+}
+declare class SessionBreadcrumbs {
+    private toolCalls;
+    private engramsRecalled;
+    recordToolCall(tool: string, args: Record<string, unknown>): void;
+    recordEngramRecalled(engramId: string): void;
+    getToolCalls(): ToolCallRecord[];
+    getEngramsRecalled(): string[];
+    /**
+     * Returns only engram IDs that have the META- prefix.
+     * These represent meta-engrams injected into the session context.
+     */
+    getMetaEngramsRecalled(): string[];
+    generateContinuationContext(): string;
+}
+
+/**
+ * Generate CLAUDE.md guardrails markdown for PLUR install.
+ * Appended to project CLAUDE.md (or equivalent instruction file) during setup.
+ */
+declare function generateGuardrails(): string;
+
 /** Build searchable text from all engram fields */
 declare function engramSearchText(engram: Engram): string;
 
+interface SecretMatch {
+    pattern: string;
+    match: string;
+}
+/** Scan text for potential secrets. Returns empty array if clean. */
+declare function detectSecrets(text: string): SecretMatch[];
+
 interface PlurPaths {
     root: string;
     engrams: string;
@@ -768,9 +1237,15 @@ declare class Plur {
     recallExpanded(query: string, options: RecallOptions & {
         llm: LlmFunction;
     }): Promise<Engram[]>;
+    /** List all active engrams, optionally filtered by scope/domain. No search — returns all matches. */
+    list(options?: {
+        scope?: string;
+        domain?: string;
+        min_strength?: number;
+    }): Engram[];
     /** Filter engrams by scope/domain/strength (shared by both modes) */
     private _filterEngrams;
-    /** Reactivate accessed engrams (bump retrieval strength, frequency, last_accessed) */
+    /** Reactivate accessed engrams and update co-access associations */
     private _reactivateResults;
     /** Scored injection within token budget (BM25 only). Returns formatted strings. */
     inject(task: string, options?: InjectOptions): InjectionResult;
@@ -779,6 +1254,13 @@ declare class Plur {
     private _formatInjection;
     /** Update feedback_signals and adjust retrieval_strength. */
     feedback(id: string, signal: 'positive' | 'negative' | 'neutral'): void;
+    /** Save extracted meta-engrams to the engram store. Skips IDs that already exist. */
+    saveMetaEngrams(metas: Engram[]): {
+        saved: number;
+        skipped: number;
+    };
+    /** Update an existing engram in the store by ID. Returns true if found and updated. */
+    updateEngram(updated: Engram): boolean;
     /** Set engram status to 'retired'. */
     forget(id: string, reason?: string): void;
     /** Capture an episodic memory. */
@@ -812,4 +1294,4 @@ declare class Plur {
     status(): StatusResult;
 }
 
-export { type Association, type CaptureContext, type Engram, type Episode, type IngestCandidate, type IngestOptions, type InjectOptions, type InjectionResult, type KnowledgeAnchor, type LearnContext, type LlmFunction, type PackManifest, Plur, type PlurConfig, type PlurPaths, type RecallOptions, type StatusResult, type SyncResult, type SyncStatus, type TimelineQuery, type VersionCheckResult, checkForUpdate, clearVersionCache, detectPlurStorage, engramSearchText, getCachedUpdateCheck };
+export { type AlignmentResult, type Association, type CaptureContext, type DomainCoverage, DomainCoverageSchema, type Engram, type EngramCluster, type Episode, type EvidenceEntry, EvidenceEntrySchema, type ExtractOptions, type ExtractionResult, type Falsification, FalsificationSchema, type HierarchyPosition, HierarchyPositionSchema, type IngestCandidate, type IngestOptions, type InjectOptions, type InjectionResult, type KnowledgeAnchor, type LearnContext, type LlmFunction, type MemberAlignment, type MetaConfidence, MetaConfidenceSchema, type MetaField, MetaFieldSchema, PLATITUDE_PATTERNS, type PackManifest, Plur, type PlurConfig, type PlurPaths, type RecallOptions, type RelationalAnalysis, type RelationalTriple, SessionBreadcrumbs, type StatusResult, type StructuralTemplate, StructuralTemplateSchema, type SyncResult, type SyncStatus, type TimelineQuery, type TypedRole, type ValidationResult, type VersionCheckResult, alignCluster, analyzeStructure, checkForUpdate, classifyPolarity, clearVersionCache, clusterByStructure, computeConfidence, computeMetaConfidence, confidenceBand, detectPlurStorage, detectSecrets, engramSearchText, extractMetaEngrams, formulateMetaEngram, generateGuardrails, getCachedUpdateCheck, isPlatitude, organizeHierarchy, tokenSimilarity, validateMetaEngram };