fluffy-context 0.3.1 → 0.6.0

package/dist/src/runtime/diagnostics.js

@@ -4,6 +4,7 @@ import { readJson } from '../storage/json-store.js';
 import { contextRoot, contextMetadataPath, contextsRoot, indexPath, manifestPath, notesPath, snapshotPath } from '../storage/layout.js';
 import { rebuildIndex, rebuildSnapshot } from './runtime.js';
 import { isValidNote } from './notes.js';
+import { migrationReadiness } from '../cognition/readiness.js';
 import { filterPaths } from '../capture/context-filter.js';
 export async function status(startPath) {
     const projectRoot = await resolveProjectRoot(startPath);
@@ -95,5 +96,10 @@ export async function doctor(startPath) {
         if (rebuiltIds.size !== storedIds.size || [...rebuiltIds].some((id) => !storedIds.has(id)))
             throw new Error('index rebuild mismatch');
     });
+    await check('v2 migration readiness', async () => {
+        const readiness = await migrationReadiness(projectRoot);
+        if (!readiness.eligible)
+            throw new Error(readiness.issues.join('; '));
+    });
     return { healthy, projectRoot, checks };
 }

package/dist/src/runtime/knowledge.d.ts

@@ -3,7 +3,9 @@ export declare function learnKnowledge(startPath: string | undefined, statement:
 export declare function listKnowledge(startPath?: string, includeUnverified?: boolean): Promise<Knowledge[]>;
 export declare function discoverKnowledge(startPath: string | undefined, query: string, options?: KnowledgeDiscoverOptions): Promise<KnowledgeDiscoveryResult>;
 export declare function verifyKnowledge(startPath: string | undefined, knowledgeId: string): Promise<Knowledge>;
+export declare function transitionKnowledge(startPath: string | undefined, knowledgeId: string, status: 'deprecated' | 'rejected', reason: string): Promise<Knowledge>;
 export declare function recordDeadend(startPath: string | undefined, attempt: string, reason: string, scopeOrInput?: string | DeadendInput): Promise<Deadend>;
 export declare function listDeadends(startPath?: string, includeUnverified?: boolean): Promise<Deadend[]>;
 export declare function discoverDeadends(startPath: string | undefined, query: string, options?: DeadendDiscoverOptions): Promise<DeadendDiscoveryResult>;
+export declare function transitionDeadend(startPath: string | undefined, deadendId: string, status: 'obsolete' | 'rejected', reason: string): Promise<Deadend>;
 export declare function verifyDeadend(startPath: string | undefined, deadendId: string): Promise<Deadend>;

package/dist/src/runtime/knowledge.js

@@ -5,6 +5,7 @@ import { isRecord, readJson } from '../storage/json-store.js';
 import { withLock } from '../storage/lock.js';
 import { contextMetadataPath, deadendsPath, knowledgePath, locksDirectory, snapshotPath } from '../storage/layout.js';
 import { rebuildSnapshot } from './runtime.js';
+import { mirrorDeadend, mirrorKnowledge } from '../cognition/v1-bridge.js';
 function id(prefix) {
     return `${prefix}-${Date.now().toString(36)}-${crypto.randomBytes(4).toString('hex')}`;
 }
@@ -34,6 +35,23 @@ function isKnowledgeFile(value) {
 function cleanList(values) {
     return [...new Set((values ?? []).map((value) => value.trim()).filter(Boolean))];
 }
+function cleanApplicability(input) {
+    if (!input)
+        return { project: true, branchMode: 'global' };
+    if (input.project !== true || !['global', 'exact'].includes(input.branchMode))
+        throw new Error('invalid record applicability');
+    const branches = cleanList(input.branches);
+    const paths = cleanList(input.paths);
+    if (input.branchMode === 'exact' && branches.length === 0)
+        throw new Error('exact applicability requires a branch');
+    return {
+        project: true,
+        branchMode: input.branchMode,
+        ...(branches.length > 0 ? { branches } : {}),
+        ...(paths.length > 0 ? { paths } : {}),
+        ...(input.sourceCommit === undefined ? {} : { sourceCommit: input.sourceCommit }),
+    };
+}
 function normalized(value) {
     return value.trim().toLocaleLowerCase();
 }
@@ -115,10 +133,12 @@ export async function learnKnowledge(startPath, statement, scopeOrInput = 'proje
             sourceContextIds: cleanList(input.sourceContextId ? [input.sourceContextId] : []),
             sourceSnapshotIds: cleanList(input.sourceSnapshotId ? [input.sourceSnapshotId] : []),
             supportingEvidence: cleanList(input.evidence),
+            applicability: cleanApplicability(input.applicability),
             createdAt: now,
             updatedAt: now,
         };
         await atomicWriteJson(knowledgePath(projectRoot), { schemaVersion: 1, items: [...file.items, item] });
+        await mirrorKnowledge(projectRoot, item);
         return item;
     });
 }
@@ -206,10 +226,33 @@ export async function verifyKnowledge(startPath, knowledgeId) {
         const item = file.items.find((candidate) => candidate.knowledgeId === knowledgeId);
         if (!item)
             throw new Error(`knowledge not found: ${knowledgeId}`);
+        if (item.status !== 'candidate')
+            throw new Error(`knowledge must be a candidate to verify: ${knowledgeId}`);
         item.status = 'verified';
         item.confidence = Math.max(item.confidence, 0.8);
         item.updatedAt = new Date().toISOString();
         await atomicWriteJson(knowledgePath(projectRoot), file);
+        await mirrorKnowledge(projectRoot, item);
+        return item;
+    });
+}
+export async function transitionKnowledge(startPath, knowledgeId, status, reason) {
+    const projectRoot = await resolveProjectRoot(startPath);
+    if (!reason.trim())
+        throw new Error('knowledge transition reason must not be empty');
+    return withLock(`${locksDirectory(projectRoot)}/knowledge.lock`, async () => {
+        const file = await loadKnowledge(projectRoot);
+        const item = file.items.find((candidate) => candidate.knowledgeId === knowledgeId);
+        if (!item)
+            throw new Error(`knowledge not found: ${knowledgeId}`);
+        if ((status === 'deprecated' && item.status !== 'verified') || (status === 'rejected' && item.status !== 'candidate')) {
+            throw new Error(`invalid knowledge transition: ${item.status} to ${status}`);
+        }
+        item.status = status;
+        item.updatedAt = new Date().toISOString();
+        item.governance = { reason: reason.trim(), transitionedAt: item.updatedAt };
+        await atomicWriteJson(knowledgePath(projectRoot), file);
+        await mirrorKnowledge(projectRoot, item);
         return item;
     });
 }
@@ -229,10 +272,12 @@ export async function recordDeadend(startPath, attempt, reason, scopeOrInput = '
             status: 'candidate',
             sourceContextId: input.sourceContextId ?? null,
             sourceSnapshotId: input.sourceSnapshotId ?? null,
+            applicability: cleanApplicability(input.applicability),
             createdAt: now,
             updatedAt: now,
         };
         await atomicWriteJson(deadendsPath(projectRoot), { schemaVersion: 1, items: [...file.items, item] });
+        await mirrorDeadend(projectRoot, item);
         return item;
     });
 }
@@ -284,6 +329,26 @@ export async function discoverDeadends(startPath, query, options = {}) {
         hits: selected.map((item) => ({ ...item, deadend: limitedDeadend(item.deadend, maxChars) })),
     };
 }
+export async function transitionDeadend(startPath, deadendId, status, reason) {
+    const projectRoot = await resolveProjectRoot(startPath);
+    if (!reason.trim())
+        throw new Error('deadend transition reason must not be empty');
+    return withLock(`${locksDirectory(projectRoot)}/deadends.lock`, async () => {
+        const file = await loadDeadends(projectRoot);
+        const item = file.items.find((candidate) => candidate.deadendId === deadendId);
+        if (!item)
+            throw new Error(`deadend not found: ${deadendId}`);
+        if ((status === 'obsolete' && item.status !== 'verified') || (status === 'rejected' && item.status !== 'candidate')) {
+            throw new Error(`invalid deadend transition: ${item.status} to ${status}`);
+        }
+        item.status = status;
+        item.updatedAt = new Date().toISOString();
+        item.governance = { reason: reason.trim(), transitionedAt: item.updatedAt };
+        await atomicWriteJson(deadendsPath(projectRoot), file);
+        await mirrorDeadend(projectRoot, item);
+        return item;
+    });
+}
 export async function verifyDeadend(startPath, deadendId) {
     const projectRoot = await resolveProjectRoot(startPath);
     return withLock(`${locksDirectory(projectRoot)}/deadends.lock`, async () => {
@@ -291,9 +356,12 @@ export async function verifyDeadend(startPath, deadendId) {
         const item = file.items.find((candidate) => candidate.deadendId === deadendId);
         if (!item)
             throw new Error(`deadend not found: ${deadendId}`);
+        if (item.status !== 'candidate')
+            throw new Error(`deadend must be a candidate to verify: ${deadendId}`);
         item.status = 'verified';
         item.updatedAt = new Date().toISOString();
         await atomicWriteJson(deadendsPath(projectRoot), file);
+        await mirrorDeadend(projectRoot, item);
         return item;
     });
 }

package/dist/src/runtime/notes.js

@@ -6,6 +6,7 @@ import { atomicWriteJson } from '../storage/atomic-write.js';
 import { isRecord, readJson } from '../storage/json-store.js';
 import { contextMetadataPath, contextsRoot, locksDirectory, notesPath, snapshotPath, snapshotsDirectory } from '../storage/layout.js';
 import { withLock } from '../storage/lock.js';
+import { mirrorNote } from '../cognition/v1-bridge.js';
 function id() {
     return `note-${Date.now().toString(36)}-${crypto.randomBytes(4).toString('hex')}`;
 }
@@ -78,6 +79,7 @@ export async function addNote(startPath, message, input = {}) {
             updatedAt: now,
         };
         await atomicWriteJson(notesPath(projectRoot), { schemaVersion: 1, items: [...file.items, note] });
+        await mirrorNote(projectRoot, note);
         return note;
     });
 }
@@ -163,8 +165,13 @@ export async function absorbNotes(startPath, contextId, snapshotId) {
             absorbed += 1;
             return { ...note, absorbedBySnapshotId: snapshotId, updatedAt: new Date().toISOString() };
         });
-        if (absorbed > 0)
+        if (absorbed > 0) {
             await atomicWriteJson(notesPath(projectRoot), { schemaVersion: 1, items });
+            for (const note of items) {
+                if (note.contextId === contextId && note.absorbedBySnapshotId === snapshotId)
+                    await mirrorNote(projectRoot, note, true);
+            }
+        }
         return absorbed;
     });
 }

package/dist/src/runtime/runtime.d.ts

@@ -8,4 +8,5 @@ export declare function checkpoint(startPath: string | undefined, input: Checkpo
 export interface ResumeOptions {
     touchLastUsedAt?: boolean;
 }
+export declare function resumeSnapshot(startPath: string | undefined, contextId: string, snapshotId: string, maxChars?: number): Promise<ResumeResult>;
 export declare function resume(startPath?: string, contextId?: string, maxChars?: number, options?: ResumeOptions): Promise<ResumeResult>;

package/dist/src/runtime/runtime.js

@@ -9,6 +9,7 @@ import { contextDirectory, contextMetadataPath, contextsRoot, indexPath, locksDi
 import { loadManifest } from './init.js';
 import { filterPaths } from '../capture/context-filter.js';
 import { absorbNotes } from './notes.js';
+import { mirrorCheckpoint } from '../cognition/v1-bridge.js';
 const emptyContext = () => ({
     progressSummary: '',
     lastError: null,
@@ -307,9 +308,36 @@ export async function checkpoint(startPath, input, options = {}) {
         });
         if (input.absorbNotes)
             await absorbNotes(projectRoot, contextId, snapshotId);
+        await mirrorCheckpoint(projectRoot, updatedContext, snapshot);
         return { status: 'saved', context: updatedContext, snapshot };
     });
 }
+export async function resumeSnapshot(startPath, contextId, snapshotId, maxChars = 4000) {
+    const projectRoot = await resolveProjectRoot(startPath);
+    await loadManifest(projectRoot);
+    const [git, context, snapshot] = await Promise.all([
+        readGitState(projectRoot),
+        loadContext(projectRoot, contextId),
+        loadSnapshot(projectRoot, contextId, snapshotId),
+    ]);
+    const details = await rebuildSnapshot(projectRoot, contextId, snapshotId);
+    const budget = { remaining: Math.max(0, maxChars) };
+    return {
+        context,
+        snapshot,
+        details,
+        resumeSummary: {
+            progressSummary: limited(details.progressSummary, budget.remaining),
+            lastError: details.lastError === null ? null : limited(details.lastError, budget.remaining),
+            completed: limitedList(details.completed, budget),
+            pendingTasks: limitedList(details.pendingTasks, budget),
+            decisions: limitedList(details.decisions, budget),
+            risks: limitedList(details.risks, budget),
+            relatedFiles: limitedList(details.relatedFiles, budget),
+            branchOrCommitDrift: context.branch !== git.branch || context.commit !== git.commit,
+        },
+    };
+}
 export async function resume(startPath, contextId, maxChars = 4000, options = {}) {
     const projectRoot = await resolveProjectRoot(startPath);
     await loadManifest(projectRoot);

package/dist/src/runtime/types.d.ts

@@ -136,6 +136,13 @@ export interface ActivityResult {
 }
 export type KnowledgeStatus = 'candidate' | 'verified' | 'deprecated' | 'rejected';
 export type DeadendStatus = 'candidate' | 'verified' | 'obsolete' | 'rejected';
+export interface RecordApplicability {
+    project: true;
+    branches?: string[];
+    branchMode: 'global' | 'exact';
+    paths?: string[];
+    sourceCommit?: string | null;
+}
 export interface Knowledge {
     knowledgeId: string;
     kind: string;
@@ -146,6 +153,11 @@ export interface Knowledge {
     sourceContextIds: string[];
     sourceSnapshotIds: string[];
     supportingEvidence: string[];
+    applicability?: RecordApplicability;
+    governance?: {
+        reason: string;
+        transitionedAt: string;
+    };
     createdAt: string;
     updatedAt: string;
 }
@@ -155,6 +167,7 @@ export interface KnowledgeInput {
     sourceContextId?: string;
     sourceSnapshotId?: string;
     evidence?: string[];
+    applicability?: RecordApplicability;
 }
 export interface KnowledgeDiscoverOptions {
     scope?: string;
@@ -205,6 +218,7 @@ export interface DeadendInput {
     sourceContextId?: string;
     sourceSnapshotId?: string;
     evidence?: string[];
+    applicability?: RecordApplicability;
 }
 export interface Deadend {
     deadendId: string;
@@ -215,6 +229,11 @@ export interface Deadend {
     status: DeadendStatus;
     sourceContextId: string | null;
     sourceSnapshotId: string | null;
+    applicability?: RecordApplicability;
+    governance?: {
+        reason: string;
+        transitionedAt: string;
+    };
     createdAt: string;
     updatedAt: string;
 }

package/dist/src/storage/layout.d.ts

@@ -11,3 +11,22 @@ export declare function locksDirectory(projectRoot: string): string;
 export declare function knowledgePath(projectRoot: string): string;
 export declare function deadendsPath(projectRoot: string): string;
 export declare function notesPath(projectRoot: string): string;
+export declare function cognitionRoot(projectRoot: string): string;
+export declare function cognitionManifestPath(projectRoot: string): string;
+export declare function cognitionPolicyPath(projectRoot: string): string;
+export declare function cognitionJournalDirectory(projectRoot: string): string;
+export declare function cognitionProjectionsDirectory(projectRoot: string): string;
+export declare function cognitionProjectionCursorPath(projectRoot: string): string;
+export declare function cognitionBranchesDirectory(projectRoot: string): string;
+export declare function cognitionContextsProjectionPath(projectRoot: string): string;
+export declare function cognitionKnowledgeProjectionPath(projectRoot: string): string;
+export declare function cognitionDeadendsProjectionPath(projectRoot: string): string;
+export declare function cognitionNotesProjectionPath(projectRoot: string): string;
+export declare function cognitionRetrievalProjectionPath(projectRoot: string): string;
+export declare function cognitionMigrationsDirectory(projectRoot: string): string;
+export declare function cognitionV1ImportPath(projectRoot: string): string;
+export declare function cognitionRuntimeDirectory(projectRoot: string): string;
+export declare function cognitionRuntimeLeasePath(projectRoot: string): string;
+export declare function cognitionRuntimeSecretPath(projectRoot: string): string;
+export declare function cognitionV1SyncPath(projectRoot: string): string;
+export declare function cognitionQuarantineDirectory(projectRoot: string): string;

package/dist/src/storage/layout.js

@@ -38,3 +38,60 @@ export function deadendsPath(projectRoot) {
 export function notesPath(projectRoot) {
     return path.join(contextRoot(projectRoot), 'notes.json');
 }
+export function cognitionRoot(projectRoot) {
+    return path.join(contextRoot(projectRoot), 'v2');
+}
+export function cognitionManifestPath(projectRoot) {
+    return path.join(cognitionRoot(projectRoot), 'manifest.json');
+}
+export function cognitionPolicyPath(projectRoot) {
+    return path.join(cognitionRoot(projectRoot), 'policy.json');
+}
+export function cognitionJournalDirectory(projectRoot) {
+    return path.join(cognitionRoot(projectRoot), 'journal');
+}
+export function cognitionProjectionsDirectory(projectRoot) {
+    return path.join(cognitionRoot(projectRoot), 'projections');
+}
+export function cognitionProjectionCursorPath(projectRoot) {
+    return path.join(cognitionProjectionsDirectory(projectRoot), 'cursor.json');
+}
+export function cognitionBranchesDirectory(projectRoot) {
+    return path.join(cognitionProjectionsDirectory(projectRoot), 'branches');
+}
+export function cognitionContextsProjectionPath(projectRoot) {
+    return path.join(cognitionProjectionsDirectory(projectRoot), 'contexts.json');
+}
+export function cognitionKnowledgeProjectionPath(projectRoot) {
+    return path.join(cognitionProjectionsDirectory(projectRoot), 'knowledge.json');
+}
+export function cognitionDeadendsProjectionPath(projectRoot) {
+    return path.join(cognitionProjectionsDirectory(projectRoot), 'deadends.json');
+}
+export function cognitionNotesProjectionPath(projectRoot) {
+    return path.join(cognitionProjectionsDirectory(projectRoot), 'notes.json');
+}
+export function cognitionRetrievalProjectionPath(projectRoot) {
+    return path.join(cognitionProjectionsDirectory(projectRoot), 'retrieval.json');
+}
+export function cognitionMigrationsDirectory(projectRoot) {
+    return path.join(cognitionRoot(projectRoot), 'migrations');
+}
+export function cognitionV1ImportPath(projectRoot) {
+    return path.join(cognitionMigrationsDirectory(projectRoot), 'v1-import.json');
+}
+export function cognitionRuntimeDirectory(projectRoot) {
+    return path.join(cognitionRoot(projectRoot), 'runtime');
+}
+export function cognitionRuntimeLeasePath(projectRoot) {
+    return path.join(cognitionRuntimeDirectory(projectRoot), 'lease.json');
+}
+export function cognitionRuntimeSecretPath(projectRoot) {
+    return path.join(cognitionRuntimeDirectory(projectRoot), 'secret');
+}
+export function cognitionV1SyncPath(projectRoot) {
+    return path.join(cognitionRuntimeDirectory(projectRoot), 'v1-sync.json');
+}
+export function cognitionQuarantineDirectory(projectRoot) {
+    return path.join(cognitionRoot(projectRoot), 'quarantine');
+}

package/dist/src/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.3.1";
+export declare const VERSION = "0.6.0";

package/dist/src/version.js

@@ -1 +1 @@
-export const VERSION = '0.3.1';
+export const VERSION = '0.6.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fluffy-context",
-  "version": "0.3.1",
+  "version": "0.6.0",
   "description": "Local context management CLI and MCP tools for AI coding agents",
   "license": "MIT",
   "author": "FluffyChi-Xing",
@@ -55,7 +55,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.test.json --noEmit",
-    "test": "tsc -p tsconfig.test.json && node --test dist/test/*.test.js",
+    "test": "tsc -p tsconfig.test.json && node --test --test-concurrency=1 dist/test/*.test.js",
     "pack:check": "tsc -p tsconfig.test.json && node --test dist/test/package-smoke.test.js",
     "prepack": "npm run build",
     "prepublishOnly": "npm test && npm run pack:check",