@compilr-dev/factory 0.1.13 → 0.1.15

package/dist/research-model/operations-source.js

@@ -0,0 +1,78 @@
+/**
+ * Source Operations
+ *
+ * source_add, source_update, source_remove
+ */
+import { generateId } from './defaults.js';
+// ─── Operations ──────────────────────────────────────────────────────────────
+export function sourceAdd(model, op) {
+    if (model.sources.some((s) => s.citeKey === op.source.citeKey)) {
+        throw new Error(`Source with citeKey "${op.source.citeKey}" already exists`);
+    }
+    const source = {
+        id: op.source.id ?? generateId('src'),
+        citeKey: op.source.citeKey,
+        citation: op.source.citation,
+        kbPath: op.source.kbPath,
+        keyFindings: op.source.keyFindings,
+        tags: op.source.tags,
+        relevance: op.source.relevance,
+        analyzed: op.source.analyzed ?? false,
+    };
+    return { ...model, sources: [...model.sources, source] };
+}
+export function sourceUpdate(model, op) {
+    if (!model.sources.some((s) => s.id === op.sourceId)) {
+        throw new Error(`Source "${op.sourceId}" not found`);
+    }
+    // Check citeKey uniqueness if being changed
+    if (op.updates.citeKey) {
+        const existing = model.sources.find((s) => s.citeKey === op.updates.citeKey && s.id !== op.sourceId);
+        if (existing) {
+            throw new Error(`Source with citeKey "${op.updates.citeKey}" already exists`);
+        }
+    }
+    return {
+        ...model,
+        sources: model.sources.map((s) => {
+            if (s.id !== op.sourceId)
+                return s;
+            return { ...s, ...op.updates, id: s.id };
+        }),
+    };
+}
+export function sourceRemove(model, op) {
+    if (!model.sources.some((s) => s.id === op.sourceId)) {
+        throw new Error(`Source "${op.sourceId}" not found`);
+    }
+    // Check if source is referenced by any claims
+    const referencingClaims = [];
+    for (const section of model.sections) {
+        for (const claim of section.claims) {
+            const refs = [...claim.supportingSources, ...claim.contradictingSources];
+            if (refs.some((r) => r.sourceId === op.sourceId)) {
+                referencingClaims.push(claim.id);
+            }
+        }
+    }
+    if (referencingClaims.length > 0 && !op.force) {
+        throw new Error(`Cannot remove source "${op.sourceId}": referenced by ${String(referencingClaims.length)} claim(s). Use force: true to cascade.`);
+    }
+    let sections = model.sections;
+    if (op.force) {
+        // Remove source references from all claims
+        sections = sections.map((s) => ({
+            ...s,
+            claims: s.claims.map((c) => ({
+                ...c,
+                supportingSources: c.supportingSources.filter((r) => r.sourceId !== op.sourceId),
+                contradictingSources: c.contradictingSources.filter((r) => r.sourceId !== op.sourceId),
+            })),
+        }));
+    }
+    return {
+        ...model,
+        sections,
+        sources: model.sources.filter((s) => s.id !== op.sourceId),
+    };
+}

package/dist/research-model/operations.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Research Model Operation Dispatcher
+ *
+ * Routes op → handler, manages revision + updatedAt.
+ */
+import type { ResearchModel } from './types.js';
+import { type SectionOperation } from './operations-section.js';
+import { type ClaimOperation } from './operations-claim.js';
+import { type SourceOperation } from './operations-source.js';
+import { type QuestionOperation } from './operations-question.js';
+import { type MetadataOperation } from './operations-metadata.js';
+export type ResearchModelOperation = SectionOperation | ClaimOperation | SourceOperation | QuestionOperation | MetadataOperation;
+export declare function applyResearchOperation(model: ResearchModel, operation: ResearchModelOperation): ResearchModel;

package/dist/research-model/operations.js

@@ -0,0 +1,80 @@
+/**
+ * Research Model Operation Dispatcher
+ *
+ * Routes op → handler, manages revision + updatedAt.
+ */
+import { sectionAdd, sectionUpdate, sectionRemove, sectionReorder, sectionMove, } from './operations-section.js';
+import { claimAdd, claimUpdate, claimRemove, claimLinkSource, claimUnlinkSource, } from './operations-claim.js';
+import { sourceAdd, sourceUpdate, sourceRemove, } from './operations-source.js';
+import { questionAdd, questionUpdate, questionRemove, questionLinkSection, } from './operations-question.js';
+import { setTitle, setAbstract, setCitationStyle, setKeywords, setMethodology, setAuthors, setTargetJournal, } from './operations-metadata.js';
+function dispatchOperation(model, operation) {
+    switch (operation.op) {
+        // Section operations
+        case 'section_add':
+            return sectionAdd(model, operation);
+        case 'section_update':
+            return sectionUpdate(model, operation);
+        case 'section_remove':
+            return sectionRemove(model, operation);
+        case 'section_reorder':
+            return sectionReorder(model, operation);
+        case 'section_move':
+            return sectionMove(model, operation);
+        // Claim operations
+        case 'claim_add':
+            return claimAdd(model, operation);
+        case 'claim_update':
+            return claimUpdate(model, operation);
+        case 'claim_remove':
+            return claimRemove(model, operation);
+        case 'claim_link_source':
+            return claimLinkSource(model, operation);
+        case 'claim_unlink_source':
+            return claimUnlinkSource(model, operation);
+        // Source operations
+        case 'source_add':
+            return sourceAdd(model, operation);
+        case 'source_update':
+            return sourceUpdate(model, operation);
+        case 'source_remove':
+            return sourceRemove(model, operation);
+        // Question operations
+        case 'question_add':
+            return questionAdd(model, operation);
+        case 'question_update':
+            return questionUpdate(model, operation);
+        case 'question_remove':
+            return questionRemove(model, operation);
+        case 'question_link_section':
+            return questionLinkSection(model, operation);
+        // Metadata operations
+        case 'set_title':
+            return setTitle(model, operation);
+        case 'set_abstract':
+            return setAbstract(model, operation);
+        case 'set_citation_style':
+            return setCitationStyle(model, operation);
+        case 'set_keywords':
+            return setKeywords(model, operation);
+        case 'set_methodology':
+            return setMethodology(model, operation);
+        case 'set_authors':
+            return setAuthors(model, operation);
+        case 'set_target_journal':
+            return setTargetJournal(model, operation);
+        default:
+            throw new Error(`Unknown operation: ${operation.op}`);
+    }
+}
+export function applyResearchOperation(model, operation) {
+    const result = dispatchOperation(model, operation);
+    return {
+        ...result,
+        meta: {
+            ...result.meta,
+            revision: result.meta.revision + 1,
+            updatedAt: new Date().toISOString(),
+        },
+    };
+}

package/dist/research-model/persistence.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Research Model Store — Persistence Layer
+ *
+ * Reads and writes the ResearchModel as a project document
+ * with doc_type: 'research-model' via IDocumentRepository.
+ */
+import type { IDocumentRepository } from '@compilr-dev/sdk';
+import type { ResearchModel } from './types.js';
+export declare class ResearchModelStore {
+    private readonly documents;
+    private readonly projectId;
+    constructor(config: {
+        documents: IDocumentRepository;
+        projectId: number;
+    });
+    get(): Promise<ResearchModel | null>;
+    save(model: ResearchModel): Promise<void>;
+    exists(): Promise<boolean>;
+}

package/dist/research-model/persistence.js

@@ -0,0 +1,40 @@
+/**
+ * Research Model Store — Persistence Layer
+ *
+ * Reads and writes the ResearchModel as a project document
+ * with doc_type: 'research-model' via IDocumentRepository.
+ */
+const RESEARCH_MODEL_DOC_TYPE = 'research-model';
+const RESEARCH_MODEL_TITLE = 'Research Model';
+export class ResearchModelStore {
+    documents;
+    projectId;
+    constructor(config) {
+        this.documents = config.documents;
+        this.projectId = config.projectId;
+    }
+    async get() {
+        const doc = await this.documents.getByType(this.projectId, RESEARCH_MODEL_DOC_TYPE);
+        if (!doc)
+            return null;
+        try {
+            return JSON.parse(doc.content);
+        }
+        catch {
+            return null;
+        }
+    }
+    async save(model) {
+        const content = JSON.stringify(model, null, 2);
+        await this.documents.upsert({
+            project_id: this.projectId,
+            doc_type: RESEARCH_MODEL_DOC_TYPE,
+            title: RESEARCH_MODEL_TITLE,
+            content,
+        });
+    }
+    async exists() {
+        const doc = await this.documents.getByType(this.projectId, RESEARCH_MODEL_DOC_TYPE);
+        return doc !== null;
+    }
+}

package/dist/research-model/schema.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Research Model Validation
+ *
+ * Structural validation + research-specific checks:
+ * - Unsupported claims (no source refs)
+ * - Orphan sources (not linked to any claim)
+ * - Unanswered questions (no sections address them)
+ * - Empty sections (outlined but no claims)
+ * - Unanalyzed sources
+ * - Referential integrity (source refs point to existing sources, etc.)
+ */
+import type { ResearchModel } from './types.js';
+export interface ResearchValidationError {
+    readonly path: string;
+    readonly message: string;
+    readonly severity: 'error' | 'warning';
+}
+export interface ResearchValidationResult {
+    readonly valid: boolean;
+    readonly errors: readonly ResearchValidationError[];
+    readonly warnings: readonly ResearchValidationError[];
+}
+export declare function validateResearchModel(model: ResearchModel): ResearchValidationResult;

package/dist/research-model/schema.js

@@ -0,0 +1,293 @@
+/**
+ * Research Model Validation
+ *
+ * Structural validation + research-specific checks:
+ * - Unsupported claims (no source refs)
+ * - Orphan sources (not linked to any claim)
+ * - Unanswered questions (no sections address them)
+ * - Empty sections (outlined but no claims)
+ * - Unanalyzed sources
+ * - Referential integrity (source refs point to existing sources, etc.)
+ */
+// =============================================================================
+// Structural Validation
+// =============================================================================
+function validateTitle(model) {
+    const errors = [];
+    if (!model.title || model.title.trim().length === 0) {
+        errors.push({ path: 'title', message: 'Title is required', severity: 'error' });
+    }
+    return errors;
+}
+function validateCitationStyle(model) {
+    const errors = [];
+    const valid = ['apa', 'mla', 'chicago', 'ieee', 'harvard'];
+    if (!valid.includes(model.citationStyle)) {
+        errors.push({
+            path: 'citationStyle',
+            message: `Invalid citation style "${model.citationStyle}"`,
+            severity: 'error',
+        });
+    }
+    return errors;
+}
+function validateSections(model) {
+    const errors = [];
+    const sectionIds = new Set();
+    for (const section of model.sections) {
+        if (!section.id) {
+            errors.push({ path: 'sections', message: 'Section missing id', severity: 'error' });
+            continue;
+        }
+        if (sectionIds.has(section.id)) {
+            errors.push({
+                path: `sections[${section.id}]`,
+                message: `Duplicate section id "${section.id}"`,
+                severity: 'error',
+            });
+        }
+        sectionIds.add(section.id);
+        if (!section.title || section.title.trim().length === 0) {
+            errors.push({
+                path: `sections[${section.id}].title`,
+                message: 'Section title is required',
+                severity: 'error',
+            });
+        }
+        // Validate parentId references
+        if (section.parentId && !model.sections.some((s) => s.id === section.parentId)) {
+            errors.push({
+                path: `sections[${section.id}].parentId`,
+                message: `Parent section "${section.parentId}" not found`,
+                severity: 'error',
+            });
+        }
+        // Validate claims within section
+        errors.push(...validateClaims(section, model));
+    }
+    return errors;
+}
+function validateClaims(section, model) {
+    const errors = [];
+    const claimIds = new Set();
+    const sourceIds = new Set(model.sources.map((s) => s.id));
+    for (const claim of section.claims) {
+        if (!claim.id) {
+            errors.push({
+                path: `sections[${section.id}].claims`,
+                message: 'Claim missing id',
+                severity: 'error',
+            });
+            continue;
+        }
+        if (claimIds.has(claim.id)) {
+            errors.push({
+                path: `sections[${section.id}].claims[${claim.id}]`,
+                message: `Duplicate claim id "${claim.id}"`,
+                severity: 'error',
+            });
+        }
+        claimIds.add(claim.id);
+        if (!claim.statement || claim.statement.trim().length === 0) {
+            errors.push({
+                path: `sections[${section.id}].claims[${claim.id}].statement`,
+                message: 'Claim statement is required',
+                severity: 'error',
+            });
+        }
+        // Validate source refs point to existing sources
+        for (const ref of claim.supportingSources) {
+            if (!sourceIds.has(ref.sourceId)) {
+                errors.push({
+                    path: `sections[${section.id}].claims[${claim.id}].supportingSources`,
+                    message: `Source "${ref.sourceId}" not found`,
+                    severity: 'error',
+                });
+            }
+        }
+        for (const ref of claim.contradictingSources) {
+            if (!sourceIds.has(ref.sourceId)) {
+                errors.push({
+                    path: `sections[${section.id}].claims[${claim.id}].contradictingSources`,
+                    message: `Source "${ref.sourceId}" not found`,
+                    severity: 'error',
+                });
+            }
+        }
+    }
+    return errors;
+}
+function validateSources(model) {
+    const errors = [];
+    const citeKeys = new Set();
+    for (const source of model.sources) {
+        if (!source.id) {
+            errors.push({ path: 'sources', message: 'Source missing id', severity: 'error' });
+            continue;
+        }
+        if (!source.citeKey || source.citeKey.trim().length === 0) {
+            errors.push({
+                path: `sources[${source.id}].citeKey`,
+                message: 'Source citeKey is required',
+                severity: 'error',
+            });
+        }
+        else if (citeKeys.has(source.citeKey)) {
+            errors.push({
+                path: `sources[${source.id}].citeKey`,
+                message: `Duplicate citeKey "${source.citeKey}"`,
+                severity: 'error',
+            });
+        }
+        citeKeys.add(source.citeKey);
+        if (!source.citation.title) {
+            errors.push({
+                path: `sources[${source.id}].citation.title`,
+                message: 'Source citation title is required',
+                severity: 'error',
+            });
+        }
+    }
+    return errors;
+}
+function validateQuestions(model) {
+    const errors = [];
+    const sectionIds = new Set(model.sections.map((s) => s.id));
+    for (const q of model.researchQuestions) {
+        if (!q.id) {
+            errors.push({ path: 'researchQuestions', message: 'Question missing id', severity: 'error' });
+            continue;
+        }
+        if (!q.question || q.question.trim().length === 0) {
+            errors.push({
+                path: `researchQuestions[${q.id}].question`,
+                message: 'Question text is required',
+                severity: 'error',
+            });
+        }
+        // Validate section refs
+        for (const ref of q.sectionRefs) {
+            if (!sectionIds.has(ref)) {
+                errors.push({
+                    path: `researchQuestions[${q.id}].sectionRefs`,
+                    message: `Section "${ref}" not found`,
+                    severity: 'error',
+                });
+            }
+        }
+    }
+    return errors;
+}
+// =============================================================================
+// Research-Specific Warnings
+// =============================================================================
+function checkUnsupportedClaims(model) {
+    const warnings = [];
+    for (const section of model.sections) {
+        for (const claim of section.claims) {
+            if (claim.supportingSources.length === 0 &&
+                claim.contradictingSources.length === 0 &&
+                claim.type !== 'original') {
+                warnings.push({
+                    path: `sections[${section.id}].claims[${claim.id}]`,
+                    message: `Claim "${truncate(claim.statement)}" has no source references`,
+                    severity: 'warning',
+                });
+            }
+        }
+    }
+    return warnings;
+}
+function checkOrphanSources(model) {
+    const warnings = [];
+    const referencedSourceIds = new Set();
+    for (const section of model.sections) {
+        for (const claim of section.claims) {
+            for (const ref of claim.supportingSources)
+                referencedSourceIds.add(ref.sourceId);
+            for (const ref of claim.contradictingSources)
+                referencedSourceIds.add(ref.sourceId);
+        }
+    }
+    for (const source of model.sources) {
+        if (!referencedSourceIds.has(source.id)) {
+            warnings.push({
+                path: `sources[${source.id}]`,
+                message: `Source "${source.citeKey}" is not linked to any claim`,
+                severity: 'warning',
+            });
+        }
+    }
+    return warnings;
+}
+function checkUnansweredQuestions(model) {
+    const warnings = [];
+    for (const q of model.researchQuestions) {
+        if (q.sectionRefs.length === 0 && q.status === 'open') {
+            warnings.push({
+                path: `researchQuestions[${q.id}]`,
+                message: `Question "${truncate(q.question)}" has no sections addressing it`,
+                severity: 'warning',
+            });
+        }
+    }
+    return warnings;
+}
+function checkEmptySections(model) {
+    const warnings = [];
+    for (const section of model.sections) {
+        if (section.claims.length === 0 && section.status === 'outlined') {
+            warnings.push({
+                path: `sections[${section.id}]`,
+                message: `Section "${section.title}" has no claims yet`,
+                severity: 'warning',
+            });
+        }
+    }
+    return warnings;
+}
+function checkUnanalyzedSources(model) {
+    const warnings = [];
+    for (const source of model.sources) {
+        if (!source.analyzed) {
+            warnings.push({
+                path: `sources[${source.id}]`,
+                message: `Source "${source.citeKey}" has not been analyzed yet`,
+                severity: 'warning',
+            });
+        }
+    }
+    return warnings;
+}
+// =============================================================================
+// Helpers
+// =============================================================================
+function truncate(str, max = 60) {
+    if (str.length <= max)
+        return str;
+    return str.slice(0, max - 3) + '...';
+}
+// =============================================================================
+// Main Validator
+// =============================================================================
+export function validateResearchModel(model) {
+    const errors = [
+        ...validateTitle(model),
+        ...validateCitationStyle(model),
+        ...validateSections(model),
+        ...validateSources(model),
+        ...validateQuestions(model),
+    ];
+    const warnings = [
+        ...checkUnsupportedClaims(model),
+        ...checkOrphanSources(model),
+        ...checkUnansweredQuestions(model),
+        ...checkEmptySections(model),
+        ...checkUnanalyzedSources(model),
+    ];
+    return {
+        valid: errors.length === 0,
+        errors,
+        warnings,
+    };
+}

package/dist/research-model/tools.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Research Model Tools
+ *
+ * research_model_get — scoped reads of the Research Model
+ * research_model_update — semantic operations on the model
+ * research_model_validate — check model health
+ */
+import type { Tool } from '@compilr-dev/agents';
+import type { PlatformContext } from '@compilr-dev/sdk';
+export interface ResearchModelToolsConfig {
+    readonly context: PlatformContext;
+}
+export declare function createResearchModelTools(config: ResearchModelToolsConfig): Tool<never>[];