cognitive-core 0.0.2 → 0.1.2

package/dist/types/knowledge.d.ts

@@ -0,0 +1,280 @@
+import { z } from 'zod';
+export declare const AllLinkRelations: readonly ["related-to", "depends-on", "specializes", "generalizes", "supports", "observed-before", "observed-after", "co-occurred", "supersedes", "caused-by", "led-to", "broke", "enabled", "prevented", "uses", "part-of", "interacts-with", "contradicts", "created-by"];
+export declare const LinkRelationSchema: z.ZodEnum<["related-to", "depends-on", "specializes", "generalizes", "supports", "observed-before", "observed-after", "co-occurred", "supersedes", "caused-by", "led-to", "broke", "enabled", "prevented", "uses", "part-of", "interacts-with", "contradicts", "created-by"]>;
+export type LinkRelation = z.infer<typeof LinkRelationSchema>;
+/** Map relation to its natural graph layer */
+export declare function inferLayerFromRelation(relation: LinkRelation): 'semantic' | 'temporal' | 'causal' | 'entity';
+export declare const NoteTypeSchema: z.ZodEnum<["observation", "entity", "domain-summary"]>;
+export type NoteType = z.infer<typeof NoteTypeSchema>;
+export declare const SourceOriginSchema: z.ZodEnum<["extracted", "agent-authored", "imported"]>;
+export type SourceOrigin = z.infer<typeof SourceOriginSchema>;
+export declare const GraphLayerNameSchema: z.ZodEnum<["semantic", "temporal", "causal", "entity"]>;
+export type GraphLayerName = z.infer<typeof GraphLayerNameSchema>;
+export declare const KnowledgeLinkSchema: z.ZodObject<{
+    target: z.ZodString;
+    relation: z.ZodEnum<["related-to", "depends-on", "specializes", "generalizes", "supports", "observed-before", "observed-after", "co-occurred", "supersedes", "caused-by", "led-to", "broke", "enabled", "prevented", "uses", "part-of", "interacts-with", "contradicts", "created-by"]>;
+    layer: z.ZodOptional<z.ZodEnum<["semantic", "temporal", "causal", "entity"]>>;
+}, "strip", z.ZodTypeAny, {
+    target: string;
+    relation: "related-to" | "depends-on" | "specializes" | "generalizes" | "supports" | "observed-before" | "observed-after" | "co-occurred" | "supersedes" | "caused-by" | "led-to" | "broke" | "enabled" | "prevented" | "uses" | "part-of" | "interacts-with" | "contradicts" | "created-by";
+    layer?: "semantic" | "temporal" | "causal" | "entity" | undefined;
+}, {
+    target: string;
+    relation: "related-to" | "depends-on" | "specializes" | "generalizes" | "supports" | "observed-before" | "observed-after" | "co-occurred" | "supersedes" | "caused-by" | "led-to" | "broke" | "enabled" | "prevented" | "uses" | "part-of" | "interacts-with" | "contradicts" | "created-by";
+    layer?: "semantic" | "temporal" | "causal" | "entity" | undefined;
+}>;
+export type KnowledgeLink = z.infer<typeof KnowledgeLinkSchema>;
+export declare const KnowledgeSourceSchema: z.ZodObject<{
+    origin: z.ZodEnum<["extracted", "agent-authored", "imported"]>;
+    trajectories: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    playbooks: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    agentId: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    origin: "extracted" | "imported" | "agent-authored";
+    agentId?: string | undefined;
+    trajectories?: string[] | undefined;
+    playbooks?: string[] | undefined;
+}, {
+    origin: "extracted" | "imported" | "agent-authored";
+    agentId?: string | undefined;
+    trajectories?: string[] | undefined;
+    playbooks?: string[] | undefined;
+}>;
+export type KnowledgeSource = z.infer<typeof KnowledgeSourceSchema>;
+export declare const KnowledgeNoteFrontmatterSchema: z.ZodObject<{
+    /** Unique identifier (kebab-case, prefixed with k- for observations) */
+    id: z.ZodString;
+    /** Note type determines organization and lifecycle */
+    type: z.ZodEnum<["observation", "entity", "domain-summary"]>;
+    /** Knowledge domains this note belongs to */
+    domain: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /** Specific entities (tools, libraries, patterns) referenced */
+    entities: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /** Freeform tags for additional categorization */
+    tags: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /** Confidence in this knowledge (0-1) */
+    confidence: z.ZodDefault<z.ZodNumber>;
+    /** Where this knowledge came from */
+    source: z.ZodObject<{
+        origin: z.ZodEnum<["extracted", "agent-authored", "imported"]>;
+        trajectories: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        playbooks: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        agentId: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        origin: "extracted" | "imported" | "agent-authored";
+        agentId?: string | undefined;
+        trajectories?: string[] | undefined;
+        playbooks?: string[] | undefined;
+    }, {
+        origin: "extracted" | "imported" | "agent-authored";
+        agentId?: string | undefined;
+        trajectories?: string[] | undefined;
+        playbooks?: string[] | undefined;
+    }>;
+    /** Explicit links to other knowledge notes */
+    links: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        target: z.ZodString;
+        relation: z.ZodEnum<["related-to", "depends-on", "specializes", "generalizes", "supports", "observed-before", "observed-after", "co-occurred", "supersedes", "caused-by", "led-to", "broke", "enabled", "prevented", "uses", "part-of", "interacts-with", "contradicts", "created-by"]>;
+        layer: z.ZodOptional<z.ZodEnum<["semantic", "temporal", "causal", "entity"]>>;
+    }, "strip", z.ZodTypeAny, {
+        target: string;
+        relation: "related-to" | "depends-on" | "specializes" | "generalizes" | "supports" | "observed-before" | "observed-after" | "co-occurred" | "supersedes" | "caused-by" | "led-to" | "broke" | "enabled" | "prevented" | "uses" | "part-of" | "interacts-with" | "contradicts" | "created-by";
+        layer?: "semantic" | "temporal" | "causal" | "entity" | undefined;
+    }, {
+        target: string;
+        relation: "related-to" | "depends-on" | "specializes" | "generalizes" | "supports" | "observed-before" | "observed-after" | "co-occurred" | "supersedes" | "caused-by" | "led-to" | "broke" | "enabled" | "prevented" | "uses" | "part-of" | "interacts-with" | "contradicts" | "created-by";
+        layer?: "semantic" | "temporal" | "causal" | "entity" | undefined;
+    }>, "many">>;
+    /** ISO 8601 creation timestamp */
+    created: z.ZodString;
+    /** ISO 8601 last updated timestamp */
+    updated: z.ZodString;
+    /** If this note replaces a previous one (contradiction resolution) */
+    supersedes: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    type: "observation" | "entity" | "domain-summary";
+    id: string;
+    domain: string[];
+    source: {
+        origin: "extracted" | "imported" | "agent-authored";
+        agentId?: string | undefined;
+        trajectories?: string[] | undefined;
+        playbooks?: string[] | undefined;
+    };
+    confidence: number;
+    entities: string[];
+    tags: string[];
+    links: {
+        target: string;
+        relation: "related-to" | "depends-on" | "specializes" | "generalizes" | "supports" | "observed-before" | "observed-after" | "co-occurred" | "supersedes" | "caused-by" | "led-to" | "broke" | "enabled" | "prevented" | "uses" | "part-of" | "interacts-with" | "contradicts" | "created-by";
+        layer?: "semantic" | "temporal" | "causal" | "entity" | undefined;
+    }[];
+    created: string;
+    updated: string;
+    supersedes?: string | null | undefined;
+}, {
+    type: "observation" | "entity" | "domain-summary";
+    id: string;
+    source: {
+        origin: "extracted" | "imported" | "agent-authored";
+        agentId?: string | undefined;
+        trajectories?: string[] | undefined;
+        playbooks?: string[] | undefined;
+    };
+    created: string;
+    updated: string;
+    domain?: string[] | undefined;
+    confidence?: number | undefined;
+    supersedes?: string | null | undefined;
+    entities?: string[] | undefined;
+    tags?: string[] | undefined;
+    links?: {
+        target: string;
+        relation: "related-to" | "depends-on" | "specializes" | "generalizes" | "supports" | "observed-before" | "observed-after" | "co-occurred" | "supersedes" | "caused-by" | "led-to" | "broke" | "enabled" | "prevented" | "uses" | "part-of" | "interacts-with" | "contradicts" | "created-by";
+        layer?: "semantic" | "temporal" | "causal" | "entity" | undefined;
+    }[] | undefined;
+}>;
+export type KnowledgeNoteFrontmatter = z.infer<typeof KnowledgeNoteFrontmatterSchema>;
+export interface KnowledgeNote {
+    /** Parsed frontmatter */
+    frontmatter: KnowledgeNoteFrontmatter;
+    /** Markdown body content (after frontmatter) */
+    body: string;
+    /** Resolved file path (derived from type + name, not stored in frontmatter) */
+    filePath: string;
+}
+export interface KnowledgeMatch {
+    note: KnowledgeNote;
+    score: number;
+    matchType?: 'domain' | 'entity' | 'semantic' | 'graph';
+}
+export interface EntityUpdate {
+    /** Entity note ID to update */
+    entityId: string;
+    /** Section to append */
+    section: string;
+    /** Evidence source trajectory ID */
+    trajectoryId: string;
+}
+export interface Contradiction {
+    /** Existing note that is contradicted */
+    existingNoteId: string;
+    /** New observation that contradicts it */
+    newObservation: KnowledgeNote;
+    /** How they conflict */
+    conflictDescription: string;
+    /** Recommendation */
+    resolution: 'supersede' | 'coexist' | 'review';
+}
+export interface PlaybookLink {
+    /** Knowledge note ID */
+    noteId: string;
+    /** Playbook ID */
+    playbookId: string;
+    /** Relationship direction */
+    relation: 'supports' | 'contradicts' | 'contextualizes';
+}
+export interface NewLink {
+    from: string;
+    to: string;
+    relation: LinkRelation;
+    layer?: GraphLayerName;
+    weight?: number;
+}
+export interface ExtractedKnowledge {
+    /** New observations to create */
+    observations: KnowledgeNote[];
+    /** Updates to existing entity notes (append sections) */
+    entityUpdates: EntityUpdate[];
+    /** Contradictions detected with existing knowledge */
+    contradictions: Contradiction[];
+    /** New links to add to the graph */
+    links: NewLink[];
+    /** Cross-references to playbooks */
+    playbookLinks: PlaybookLink[];
+}
+export interface InboxResult {
+    /** Total files processed */
+    processed: number;
+    /** Files that failed to parse/move */
+    failed: number;
+    /** Files moved to observations/ */
+    movedToObservations: number;
+    /** Files moved to entities/ */
+    movedToEntities: number;
+    /** Files moved to domains/ */
+    movedToDomains: number;
+}
+export interface DefragResult {
+    /** Inbox processing results */
+    inbox: InboxResult;
+    /** Number of observations consolidated into entity notes */
+    consolidated: number;
+    /** Number of contradictions detected */
+    contradictions: number;
+    /** Whether the graph was rebuilt */
+    graphRebuilt: boolean;
+    /** Number of domain summaries regenerated */
+    domainSummariesRegenerated: number;
+    /** Decay results */
+    decay: DecayResult;
+}
+export interface DecayResult {
+    /** Notes with reduced confidence */
+    decayed: number;
+    /** Notes newly marked as stale */
+    newlyStale: number;
+    /** Notes already marked stale */
+    alreadyStale: number;
+}
+export interface KnowledgeStats {
+    observationCount: number;
+    entityCount: number;
+    domainCount: number;
+    inboxCount: number;
+    graph: {
+        nodeCount: number;
+        edgeCountByLayer: Record<string, number>;
+        enabledLayers: string[];
+    };
+    avgConfidence: number;
+    staleCount: number;
+    domainBreakdown: Record<string, number>;
+}
+/**
+ * Create a new observation note
+ */
+export declare function createObservation(input: {
+    id?: string;
+    title: string;
+    body: string;
+    domain: string[];
+    entities: string[];
+    tags?: string[];
+    confidence?: number;
+    source: KnowledgeSource;
+    links?: KnowledgeLink[];
+}): KnowledgeNote;
+/**
+ * Create a new entity note
+ */
+export declare function createEntityNote(input: {
+    entityName: string;
+    body: string;
+    domain: string[];
+    tags?: string[];
+    confidence?: number;
+    source: KnowledgeSource;
+    links?: KnowledgeLink[];
+}): KnowledgeNote;
+/**
+ * Create a new domain summary note
+ */
+export declare function createDomainSummary(input: {
+    domainName: string;
+    body: string;
+    entities?: string[];
+    tags?: string[];
+    source: KnowledgeSource;
+}): KnowledgeNote;
+//# sourceMappingURL=knowledge.d.ts.map

package/dist/types/knowledge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge.d.ts","sourceRoot":"","sources":["../../src/types/knowledge.ts"],"names":[],"mappings":"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"}

package/dist/types/knowledge.js

@@ -0,0 +1,191 @@
+import { z } from 'zod';
+// ============================================================================
+// Link Relations (organized by graph layer)
+// ============================================================================
+/** Semantic layer relations */
+const SemanticRelations = [
+    'related-to',
+    'depends-on',
+    'specializes',
+    'generalizes',
+    'supports',
+];
+/** Temporal layer relations */
+const TemporalRelations = [
+    'observed-before',
+    'observed-after',
+    'co-occurred',
+    'supersedes',
+];
+/** Causal layer relations */
+const CausalRelations = [
+    'caused-by',
+    'led-to',
+    'broke',
+    'enabled',
+    'prevented',
+];
+/** Entity layer relations */
+const EntityRelations = [
+    'uses',
+    'part-of',
+    'interacts-with',
+    'contradicts',
+    'created-by',
+];
+export const AllLinkRelations = [
+    ...SemanticRelations,
+    ...TemporalRelations,
+    ...CausalRelations,
+    ...EntityRelations,
+];
+export const LinkRelationSchema = z.enum(AllLinkRelations);
+/** Map relation to its natural graph layer */
+export function inferLayerFromRelation(relation) {
+    if (SemanticRelations.includes(relation))
+        return 'semantic';
+    if (TemporalRelations.includes(relation))
+        return 'temporal';
+    if (CausalRelations.includes(relation))
+        return 'causal';
+    return 'entity';
+}
+// ============================================================================
+// Note Types
+// ============================================================================
+export const NoteTypeSchema = z.enum([
+    'observation',
+    'entity',
+    'domain-summary',
+]);
+export const SourceOriginSchema = z.enum([
+    'extracted',
+    'agent-authored',
+    'imported',
+]);
+export const GraphLayerNameSchema = z.enum([
+    'semantic',
+    'temporal',
+    'causal',
+    'entity',
+]);
+// ============================================================================
+// Knowledge Note Frontmatter Schema
+// ============================================================================
+export const KnowledgeLinkSchema = z.object({
+    target: z.string(),
+    relation: LinkRelationSchema,
+    layer: GraphLayerNameSchema.optional(),
+});
+export const KnowledgeSourceSchema = z.object({
+    origin: SourceOriginSchema,
+    trajectories: z.array(z.string()).optional(),
+    playbooks: z.array(z.string()).optional(),
+    agentId: z.string().optional(),
+});
+export const KnowledgeNoteFrontmatterSchema = z.object({
+    /** Unique identifier (kebab-case, prefixed with k- for observations) */
+    id: z.string(),
+    /** Note type determines organization and lifecycle */
+    type: NoteTypeSchema,
+    /** Knowledge domains this note belongs to */
+    domain: z.array(z.string()).default([]),
+    /** Specific entities (tools, libraries, patterns) referenced */
+    entities: z.array(z.string()).default([]),
+    /** Freeform tags for additional categorization */
+    tags: z.array(z.string()).default([]),
+    /** Confidence in this knowledge (0-1) */
+    confidence: z.number().min(0).max(1).default(0.5),
+    /** Where this knowledge came from */
+    source: KnowledgeSourceSchema,
+    /** Explicit links to other knowledge notes */
+    links: z.array(KnowledgeLinkSchema).default([]),
+    /** ISO 8601 creation timestamp */
+    created: z.string(),
+    /** ISO 8601 last updated timestamp */
+    updated: z.string(),
+    /** If this note replaces a previous one (contradiction resolution) */
+    supersedes: z.string().nullable().optional(),
+});
+// ============================================================================
+// Factory Functions
+// ============================================================================
+let noteCounter = 0;
+function generateNoteId(prefix) {
+    const timestamp = Date.now().toString(36);
+    const counter = (noteCounter++).toString(36);
+    return `${prefix}-${timestamp}-${counter}`;
+}
+/**
+ * Create a new observation note
+ */
+export function createObservation(input) {
+    const now = new Date().toISOString();
+    const id = input.id ?? generateNoteId('k');
+    return {
+        frontmatter: {
+            id,
+            type: 'observation',
+            domain: input.domain,
+            entities: input.entities,
+            tags: input.tags ?? [],
+            confidence: input.confidence ?? 0.3,
+            source: input.source,
+            links: input.links ?? [],
+            created: now,
+            updated: now,
+            supersedes: null,
+        },
+        body: `# ${input.title}\n\n${input.body}`,
+        filePath: `knowledge/observations/${id}.md`,
+    };
+}
+/**
+ * Create a new entity note
+ */
+export function createEntityNote(input) {
+    const now = new Date().toISOString();
+    const slug = input.entityName.toLowerCase().replace(/[^a-z0-9]+/g, '-');
+    return {
+        frontmatter: {
+            id: slug,
+            type: 'entity',
+            domain: input.domain,
+            entities: [input.entityName],
+            tags: input.tags ?? [],
+            confidence: input.confidence ?? 0.5,
+            source: input.source,
+            links: input.links ?? [],
+            created: now,
+            updated: now,
+            supersedes: null,
+        },
+        body: `# ${input.entityName}\n\n${input.body}`,
+        filePath: `knowledge/entities/${slug}.md`,
+    };
+}
+/**
+ * Create a new domain summary note
+ */
+export function createDomainSummary(input) {
+    const now = new Date().toISOString();
+    const slug = input.domainName.toLowerCase().replace(/[^a-z0-9]+/g, '-');
+    return {
+        frontmatter: {
+            id: slug,
+            type: 'domain-summary',
+            domain: [input.domainName],
+            entities: input.entities ?? [],
+            tags: input.tags ?? [],
+            confidence: 1.0,
+            source: input.source,
+            links: [],
+            created: now,
+            updated: now,
+            supersedes: null,
+        },
+        body: `# ${input.domainName}\n\n${input.body}`,
+        filePath: `knowledge/domains/${slug}.md`,
+    };
+}
+//# sourceMappingURL=knowledge.js.map

package/dist/types/knowledge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge.js","sourceRoot":"","sources":["../../src/types/knowledge.ts"],"names":[],"mappings":"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"}