@popmelt.com/core 0.8.3 → 0.8.5

package/dist/server.d.mts

@@ -1,4 +1,141 @@
+type ImprintExplanationKind = 'intention' | 'principle' | 'pattern';
+type ImprintExplanationState = 'emerging' | 'testing' | 'grounded' | 'challenged' | 'retired';
+type ImprintScopeKind = 'project' | 'route' | 'component' | 'selector' | 'file';
+type ImprintScope = {
+    kind: ImprintScopeKind;
+    values: string[];
+};
+type ImprintEvidence = {
+    id: string;
+    kind: 'observation' | 'application' | 'confirmation' | 'correction' | 'exception' | 'rejection';
+    stance: 'supports' | 'challenges' | 'excepts';
+    summary: string;
+    threadId: string;
+    jobId: string;
+    createdAt: string;
+};
+type ImprintExplanation = {
+    id: string;
+    kind: ImprintExplanationKind;
+    statement: string;
+    rationale: string;
+    scope: ImprintScope;
+    state: ImprintExplanationState;
+    createdAt: string;
+    updatedAt: string;
+    evidence: ImprintEvidence[];
+    supersededBy?: string;
+};
+type ImprintConcrete = {
+    id: string;
+    modelPath: string;
+    value: unknown;
+    createdAt: string;
+    updatedAt: string;
+};
+type ImprintRelationType = 'operationalizes' | 'refines' | 'supports' | 'contradicts' | 'excepts' | 'instantiates';
+type ImprintRelation = {
+    id: string;
+    type: ImprintRelationType;
+    fromId: string;
+    toId: string;
+    rationale: string;
+    createdAt: string;
+};
+type ImprintGraph = {
+    version: 1;
+    projectId: string;
+    createdAt: string;
+    updatedAt: string;
+    head: {
+        sequence: number;
+        hash: string | null;
+    };
+    explanations: ImprintExplanation[];
+    concrete: ImprintConcrete[];
+    relations: ImprintRelation[];
+};
+type ImprintMutation = {
+    op: 'add_explanation';
+    explanation: ImprintExplanation;
+} | {
+    op: 'replace_explanation';
+    explanation: ImprintExplanation;
+} | {
+    op: 'remove_explanation';
+    explanationId: string;
+} | {
+    op: 'add_concrete';
+    concrete: ImprintConcrete;
+} | {
+    op: 'remove_concrete';
+    concreteId: string;
+} | {
+    op: 'add_evidence';
+    explanationId: string;
+    evidence: ImprintEvidence;
+} | {
+    op: 'revise_explanation';
+    explanationId: string;
+    patch: Partial<Pick<ImprintExplanation, 'statement' | 'rationale' | 'scope' | 'state' | 'supersededBy'>>;
+    updatedAt: string;
+} | {
+    op: 'add_relation';
+    relation: ImprintRelation;
+} | {
+    op: 'remove_relation';
+    relationId: string;
+};
+type ImprintTransaction = {
+    version: 1;
+    sequence: number;
+    transactionId: string;
+    projectId: string;
+    committedAt: string;
+    previousHash: string | null;
+    hash: string;
+    source: {
+        kind: 'automatic' | 'grounding' | 'correction' | 'undo';
+        threadId: string;
+        jobId: string;
+    };
+    summary: string;
+    mutations: ImprintMutation[];
+    inverseMutations: ImprintMutation[];
+    undoesTransactionId?: string;
+};
+type ImprintSummaryKind = 'added' | 'strengthened' | 'refined' | 'challenged' | 'exception' | 'consolidated';
+type ImprintThreadSummary = {
+    transactionId: string;
+    coalescedTransactionIds?: string[];
+    additionalObservationCount?: number;
+    kind: ImprintSummaryKind;
+    title: string;
+    detail: string;
+    changes: Array<{
+        explanationId: string;
+        action: 'added' | 'revised' | 'supported' | 'challenged' | 'retired' | 'related';
+        statement: string;
+        state: ImprintExplanationState;
+    }>;
+    grounding?: {
+        explanationId: string;
+        question: string;
+        state: 'testing';
+    };
+    resolvedAction?: ImprintGroundingAction;
+};
+type ImprintGroundingAction = 'confirm' | 'reason_wrong' | 'narrow' | 'exception' | 'edit' | 'dont_learn' | 'undo';
+type ImprintContext = {
+    explanations: Array<Pick<ImprintExplanation, 'id' | 'kind' | 'statement' | 'rationale' | 'scope' | 'state'> & {
+        concrete: Array<Pick<ImprintConcrete, 'id' | 'modelPath' | 'value'>>;
+    }>;
+    truncated: boolean;
+    pendingGroundingExplanationIds?: string[];
+};
+
 type Provider = 'claude' | 'codex' | 'copilot';
+
 type PopmeltOptions = {
     port?: number;
     projectRoot?: string;
@@ -19,9 +156,143 @@ type PopmeltHandle = {
     close: () => Promise<void>;
 };
 
-declare function startPopmelt(options?: PopmeltOptions & {
+type ImprintLoadResult = {
+    graph: ImprintGraph;
+    transactions: ImprintTransaction[];
+    recoveredTransactions: number;
+};
+declare class ImprintStore {
+    private readonly projectRoot;
+    private readonly projectId;
+    private readonly imprintDir;
+    private readonly manifestPath;
+    private readonly graphPath;
+    private readonly journalDir;
+    private writeChain;
+    constructor(projectRoot: string, projectId: string);
+    private readManifest;
+    load(): Promise<ImprintLoadResult>;
+    commit(input: {
+        transactionId: string;
+        committedAt: string;
+        source: ImprintTransaction['source'];
+        summary: string;
+        mutations: ImprintMutation[];
+        undoesTransactionId?: string;
+    }): Promise<{
+        graph: ImprintGraph;
+        transaction: ImprintTransaction;
+    }>;
+    undo(transactionId: string, source: ImprintTransaction['source'], committedAt: string, undoTransactionId: string): Promise<{
+        graph: ImprintGraph;
+        transaction: ImprintTransaction;
+    }>;
+    recover(): Promise<ImprintLoadResult>;
+}
+
+type ProposedMutation = {
+    op: 'add';
+    clientId?: string;
+    kind: ImprintExplanationKind;
+    statement: string;
+    rationale: string;
+    scope?: ImprintScope;
+} | {
+    op: 'revise';
+    explanationId: string;
+    statement?: string;
+    rationale?: string;
+    scope?: ImprintScope;
+    reopenGrounding?: boolean;
+} | {
+    op: 'evidence';
+    explanationId: string;
+    stance: 'supports' | 'challenges' | 'excepts';
+    summary: string;
+} | {
+    op: 'relation';
+    type: ImprintRelationType;
+    fromId: string;
+    toId: string;
+    rationale: string;
+} | {
+    op: 'supersede';
+    explanationId: string;
+    replacementId: string;
+    reason: string;
+} | {
+    op: 'bind_concrete';
+    explanationId: string;
+    modelPath: string;
+    rationale: string;
+} | {
+    op: 'retire';
+    explanationId: string;
+    reason: string;
+};
+type ImprintNoopReason = 'application_only' | 'transient_state' | 'concrete_without_model_path' | 'duplicate' | 'insufficient_evidence' | 'task_specific_detail' | 'no_shared_understanding_change';
+type ImprintMutationDraft = {
+    decision: 'mutate';
+    summary: {
+        kind: ImprintSummaryKind;
+        title: string;
+        detail: string;
+    };
+    appliedExplanationIds: string[];
+    mutations: ProposedMutation[];
+    grounding?: {
+        explanationId: string;
+        question: string;
+    };
+};
+type ImprintDraft = ImprintMutationDraft | {
+    decision: 'none';
+    reason: ImprintNoopReason;
+};
+type ImprintCaptureInput = {
+    threadId: string;
+    jobId: string;
+    occurredAt?: string;
+    concreteModel?: Record<string, unknown> | null;
+    pendingGroundingExplanationIds?: string[];
+};
+declare function parseImprintDraft(responseText: string): {
+    draft?: ImprintDraft;
+    visibleText: string;
+    error?: string;
+};
+declare function formatImprintPrompt(context: ImprintContext | undefined): string;
+declare class ImprintService {
+    readonly store: ImprintStore;
+    private readonly noopCounts;
+    constructor(projectRoot: string, projectId: string);
+    recordNoop(reason: ImprintNoopReason): void;
+    diagnostics(): {
+        noopDecisions: Partial<Record<ImprintNoopReason, number>>;
+    };
+    contextualize(input: {
+        text?: string;
+        subjectHints?: string[];
+        maxExplanations?: number;
+        pendingGroundingExplanationIds?: string[];
+    }): Promise<ImprintContext | undefined>;
+    capture(draft: ImprintMutationDraft, input: ImprintCaptureInput): Promise<ImprintThreadSummary | undefined>;
+    applyGroundingAction(input: {
+        summary: ImprintThreadSummary;
+        action: ImprintGroundingAction;
+        value?: string;
+        threadId: string;
+        jobId: string;
+        occurredAt?: string;
+    }): Promise<void>;
+}
+
+type StartPopmeltOptions = PopmeltOptions & {
     force?: boolean;
     detached?: boolean;
-}): Promise<PopmeltHandle>;
+    /** Set false when another lifecycle owner, such as a Vite HTTP server, manages the lease. */
+    manageLease?: boolean;
+};
+declare function startPopmelt(options?: StartPopmeltOptions): Promise<PopmeltHandle>;
 
-export { type PopmeltHandle, type PopmeltOptions, startPopmelt };
+export { type ImprintConcrete, type ImprintContext, type ImprintEvidence, type ImprintExplanation, type ImprintExplanationKind, type ImprintExplanationState, type ImprintGraph, type ImprintGroundingAction, type ImprintMutation, type ImprintRelation, type ImprintRelationType, type ImprintScope, ImprintService, ImprintStore, type ImprintThreadSummary, type ImprintTransaction, type PopmeltHandle, type PopmeltOptions, type StartPopmeltOptions, formatImprintPrompt, parseImprintDraft, startPopmelt };