@fingerskier/augment 0.3.1 → 0.5.0

package/dist/service.d.ts

@@ -1,6 +1,9 @@
 import type { AugmentConfig } from "./config.js";
 import { AugmentDatabase } from "./db.js";
+import { type DecoctionDiscoveryCluster } from "./decoction.js";
 import type { EmbeddingProvider } from "./embeddings.js";
+import type { LinkType, MemoryKind } from "./constants.js";
+import { type Proposal, type ProposalStatus } from "./proposals.js";
 import { type SleepCluster } from "./sleep.js";
 import type { LinkRecord, MemoryRecord, ProjectGraph, ProjectRecord, SearchInput, SearchResult, UpsertInput } from "./types.js";
 export interface InitProjectInput {
@@ -15,6 +18,58 @@ export interface SearchOutput {
     text: string;
     results: SearchResult[];
 }
+export interface DecoctionRemovalSuggestion {
+    path: string;
+    reason: string;
+}
+export interface DecoctionGleanDiscoverInput {
+    action: "discover";
+    min_cosine?: number;
+    limit?: number;
+}
+export interface DecoctionGleanWriteInput {
+    action: "write";
+    kind: "SPEC" | "ARCH";
+    name: string;
+    content: string;
+    tags?: string[];
+    derived_from: string[];
+    suggested_removals?: DecoctionRemovalSuggestion[];
+    expected_content_hash?: string;
+    expected_frontmatter_hash?: string;
+}
+export type DecoctionGleanInput = DecoctionGleanDiscoverInput | DecoctionGleanWriteInput;
+export interface DecoctionGleanDiscoverOutput {
+    action: "discover";
+    text: string;
+    eligible: number;
+    embedded: number;
+    min_cosine: number;
+    min_projects: number;
+    clusters: DecoctionDiscoveryCluster[];
+}
+export interface DecoctionGleanWriteOutput {
+    action: "write";
+    memory: MemoryRecord;
+    upsert_action: UpsertResult["action"];
+    suggested_removals: DecoctionRemovalSuggestion[];
+    warnings: string[];
+    text: string;
+}
+export interface DecoctionCleanupInput {
+    generic_path: string;
+    source_paths: string[];
+}
+export interface DecoctionCleanupResult {
+    generic_path: string;
+    results: Array<{
+        source_path: string;
+        status: "deleted" | "failed";
+        retargeted_links: number;
+        error?: string;
+    }>;
+    text: string;
+}
 export interface SleepCandidatesInput {
     /** Restrict to one project; omit to preview candidates in every project (clusters never span projects). */
     project_name?: string;
@@ -28,6 +83,64 @@ export interface SleepCandidatesOutput {
     clusters: SleepCluster[];
     eligible: number;
 }
+/** Draft a sleep consolidation: >=2 WORK sources fold into one new SPEC/ARCH.
+ * The proposal is written OUTSIDE the corpus for review; nothing is consolidated
+ * until {@link AugmentService.sleepApply}. */
+export interface SleepProposeInput {
+    project_name: string;
+    kind: "SPEC" | "ARCH";
+    name: string;
+    content: string;
+    derived_from: string[];
+    rationale?: string;
+}
+export interface SleepApplyInput {
+    filename: string;
+}
+export interface SleepApplyOutput {
+    memory: MemoryRecord;
+    archived: string[];
+    proposal: Proposal;
+    text: string;
+}
+/** Draft a speculative memory in the active project from one or more existing
+ * inspirations. Inspirations are deliberately global: they may belong to the
+ * active project, the reserved generic project, or any foreign project. */
+export interface DreamMemoryProposeInput {
+    project_name: string;
+    kind: MemoryKind;
+    name: string;
+    content: string;
+    derived_from: string[];
+    rationale?: string;
+    link?: never;
+}
+/** Draft a speculative link. Applying it may only rewrite a source in the
+ * active project, while the target may be current, generic, or foreign. */
+export interface DreamLinkProposeInput {
+    project_name: string;
+    link: {
+        from: string;
+        to: string;
+        type: LinkType;
+    };
+    rationale?: string;
+    kind?: never;
+    name?: never;
+    content?: never;
+    derived_from?: never;
+}
+export type DreamProposeInput = DreamMemoryProposeInput | DreamLinkProposeInput;
+export interface DreamApplyInput {
+    filename: string;
+}
+export interface DreamApplyOutput {
+    type: "dream-memory" | "dream-link";
+    proposal: Proposal;
+    memory?: MemoryRecord;
+    link?: LinkRecord;
+    text: string;
+}
 export declare class AugmentService {
     private readonly config;
     private readonly embeddingProvider;
@@ -44,6 +157,10 @@ export declare class AugmentService {
      * searches. */
     private corpusPromise?;
     private readonly queryEmbeddingCache;
+    /** FIFO critical section for every corpus mutation. Compound operations use
+     * their private `*Core` helpers while holding this lock so their validation,
+     * frontmatter rewrites, and deletes cannot interleave with another request. */
+    private mutationTail;
     constructor(config: AugmentConfig, embeddingProvider?: EmbeddingProvider);
     useStateDir(stateDir: string): void;
     close(): Promise<void>;
@@ -72,6 +189,7 @@ export declare class AugmentService {
      */
     consumeSelfWrite(relativePath: string): boolean;
     private recordSelfWrite;
+    private memoryFileExists;
     upsert(input: UpsertInput): Promise<UpsertResult>;
     private upsertCore;
     read(id: number): Promise<MemoryRecord>;
@@ -101,17 +219,94 @@ export declare class AugmentService {
     }>;
     private unlinkCore;
     private invalidateCorpusSnapshot;
+    /** Queue one corpus mutation after the previous request, keeping the queue
+     * usable after failures. Assignment happens synchronously before any caller
+     * can enqueue the next request. */
+    private serializeMutation;
     private corpus;
     /** Query vectors depend only on the query text and the (process-pinned) model,
      * so unlike the corpus snapshot they never need invalidating on writes. */
     private embedQuery;
     search(input: SearchInput): Promise<SearchOutput>;
+    decoctionGlean(input: DecoctionGleanDiscoverInput): Promise<DecoctionGleanDiscoverOutput>;
+    decoctionGlean(input: DecoctionGleanWriteInput): Promise<DecoctionGleanWriteOutput>;
+    private decoctionGleanWrite;
+    decoctionCleanup(input: DecoctionCleanupInput): Promise<DecoctionCleanupResult>;
+    private decoctionCleanupCore;
     /**
      * READ-ONLY sleep preview: which settled WORK memories WOULD consolidate.
-     * Performs zero writes — the actual write-back (`sleep_apply`) is deferred
-     * behind the Phase-2 go/no-go and does not exist.
+     * Performs zero writes; an agent must draft a proposal and receive explicit
+     * user approval before `sleep_apply` changes the corpus.
      */
     sleepCandidates(input?: SleepCandidatesInput, now?: number): Promise<SleepCandidatesOutput>;
+    /**
+     * Draft a sleep consolidation as a review artifact OUTSIDE the corpus. Writes
+     * nothing to the memory store: the corpus is only mutated by {@link sleepApply}
+     * on an explicitly approved proposal. Validates the sources up front (same
+     * checks apply re-runs against the live corpus) so an impossible proposal fails
+     * loudly at draft time.
+     */
+    sleepPropose(input: SleepProposeInput): Promise<{
+        proposal: Proposal;
+        text: string;
+    }>;
+    sleepProposals(status?: ProposalStatus): Promise<{
+        proposals: Proposal[];
+        text: string;
+    }>;
+    /**
+     * Apply an approved sleep proposal — the ONLY corpus mutation in the flow. The
+     * sequence is a contract: read the proposal fresh from disk (user edits count),
+     * require it still be `proposed`, re-validate against the LIVE corpus (drafts
+     * sit while the corpus moves underneath them), upsert the consolidated record
+     * (provenance threaded into frontmatter), archive each source in place (body
+     * untouched, verbatim), then flip the proposal to `applied`. Does NOT commit
+     * git: the route commits the whole pass as one revertible commit.
+     */
+    sleepApply(input: SleepApplyInput): Promise<SleepApplyOutput>;
+    private sleepApplyCore;
+    sleepReject(filename: string): Promise<{
+        proposal: Proposal;
+        text: string;
+    }>;
+    /**
+     * Draft one speculative memory or link outside the corpus. The daemon never
+     * synthesizes a dream: an agent supplies the complete candidate and this
+     * method only validates its live references and writes a review artifact.
+     */
+    dreamPropose(input: DreamProposeInput): Promise<{
+        proposal: Proposal;
+        text: string;
+    }>;
+    /** List the whole dreams/ proposal family, including both dream-memory and
+     * dream-link records. `dream-memory` is intentionally only the directory
+     * selector used by the shared proposal store. */
+    dreamProposals(status?: ProposalStatus): Promise<{
+        proposals: Proposal[];
+        text: string;
+    }>;
+    /** Apply the explicitly approved proposal after re-reading and re-validating
+     * it against the live corpus. The HTTP route owns the single git commit. */
+    dreamApply(input: DreamApplyInput): Promise<DreamApplyOutput>;
+    private dreamApplyCore;
+    dreamReject(filename: string): Promise<{
+        proposal: Proposal;
+        text: string;
+    }>;
+    private validateDreamMemory;
+    private validateDreamLink;
+    /**
+     * Shared sleep validation, run at propose time and re-run against the live
+     * corpus at apply time. Every source must resolve, be a WORK memory in
+     * `projectName` (single-project constraint), and be unarchived; there must be
+     * >=2 of them; and the consolidation target must not already exist. Every
+     * violation names the offending path.
+     */
+    private validateSleepSources;
+    /** Rewrite one source's frontmatter to archived + consolidated_into, leaving
+     * the body verbatim, and reindex it. Mirrors {@link scrubInboundLinks}. Returns
+     * the source's relative path. */
+    private archiveSource;
     private findSimilarMemory;
     private ensureEmbedding;
 }