fluffy-context 0.3.1 → 0.6.0

package/dist/src/cognition/readiness.js

@@ -0,0 +1,81 @@
+import { access, readdir } from 'node:fs/promises';
+import { resolveProjectRoot } from '../project/project-resolver.js';
+import { contextMetadataPath, contextsRoot, cognitionManifestPath, manifestPath, snapshotPath, snapshotsDirectory } from '../storage/layout.js';
+import { readJson } from '../storage/json-store.js';
+import { listDeadends, listKnowledge } from '../runtime/knowledge.js';
+import { listNotes } from '../runtime/notes.js';
+import { rebuildSnapshot } from '../runtime/runtime.js';
+async function exists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function migrationReadiness(startPath) {
+    const projectRoot = await resolveProjectRoot(startPath);
+    const counts = { contexts: 0, snapshots: 0, notes: 0, knowledge: 0, deadends: 0 };
+    const issues = [];
+    const v1Present = await exists(manifestPath(projectRoot));
+    const v2Present = await exists(cognitionManifestPath(projectRoot));
+    if (!v1Present) {
+        issues.push('v1 manifest is missing');
+        return { projectRoot, eligible: false, v1Present, v2Present, counts, issues };
+    }
+    try {
+        const manifest = await readJson(manifestPath(projectRoot));
+        if (manifest.schemaVersion !== 1 || manifest.layoutVersion !== 'compact-json-v1' || manifest.projectRoot !== projectRoot) {
+            issues.push('v1 manifest is invalid');
+        }
+    }
+    catch (error) {
+        issues.push(`v1 manifest: ${error instanceof Error ? error.message : 'invalid'}`);
+    }
+    let contextIds = [];
+    try {
+        contextIds = await readdir(contextsRoot(projectRoot));
+    }
+    catch (error) {
+        issues.push(`v1 contexts: ${error instanceof Error ? error.message : 'unavailable'}`);
+    }
+    for (const contextId of contextIds) {
+        try {
+            const context = await readJson(contextMetadataPath(projectRoot, contextId));
+            if (context.schemaVersion !== 1 || context.id !== contextId || context.projectRoot !== projectRoot) {
+                throw new Error('invalid context metadata');
+            }
+            counts.contexts += 1;
+            const snapshots = (await readdir(snapshotsDirectory(projectRoot, contextId))).filter((entry) => entry.endsWith('.json'));
+            counts.snapshots += snapshots.length;
+            for (const snapshotFile of snapshots) {
+                const snapshotId = snapshotFile.slice(0, -'.json'.length);
+                await readJson(snapshotPath(projectRoot, contextId, snapshotId));
+                await rebuildSnapshot(projectRoot, contextId, snapshotId);
+            }
+        }
+        catch (error) {
+            issues.push(`context ${contextId}: ${error instanceof Error ? error.message : 'invalid'}`);
+        }
+    }
+    try {
+        counts.notes = (await listNotes(projectRoot, { limit: Number.MAX_SAFE_INTEGER, maxChars: Number.MAX_SAFE_INTEGER })).length;
+    }
+    catch (error) {
+        issues.push(`notes: ${error instanceof Error ? error.message : 'invalid'}`);
+    }
+    try {
+        counts.knowledge = (await listKnowledge(projectRoot, true)).length;
+    }
+    catch (error) {
+        issues.push(`knowledge: ${error instanceof Error ? error.message : 'invalid'}`);
+    }
+    try {
+        counts.deadends = (await listDeadends(projectRoot, true)).length;
+    }
+    catch (error) {
+        issues.push(`deadends: ${error instanceof Error ? error.message : 'invalid'}`);
+    }
+    return { projectRoot, eligible: issues.length === 0, v1Present, v2Present, counts, issues };
+}

package/dist/src/cognition/retrieval.d.ts

@@ -0,0 +1,26 @@
+import type { DeadendDiscoveryResult, KnowledgeDiscoveryResult } from '../runtime/types.js';
+import type { CognitionEvent, CognitionRetrievalProjection } from './types.js';
+export declare function normalized(value: string): string;
+export declare function queryTerms(query: string): string[];
+export declare function buildRetrievalProjection(events: CognitionEvent[]): CognitionRetrievalProjection;
+export interface RetrievalExclusions {
+    status_not_verified: number;
+    applicability_mismatch: number;
+    scope_mismatch: number;
+    query_no_match: number;
+    result_limit: number;
+}
+export interface V2Discovery<T> {
+    result: T;
+    exclusions: RetrievalExclusions;
+}
+export declare function discoverV2Knowledge(index: CognitionRetrievalProjection, query: string, current: CognitionEvent['git'], options: {
+    scope?: string;
+    limit: number;
+    maxChars: number;
+}): V2Discovery<KnowledgeDiscoveryResult>;
+export declare function discoverV2Deadends(index: CognitionRetrievalProjection, query: string, current: CognitionEvent['git'], options: {
+    scope?: string;
+    limit: number;
+    maxChars: number;
+}): V2Discovery<DeadendDiscoveryResult>;

package/dist/src/cognition/retrieval.js

@@ -0,0 +1,273 @@
+const aliasGroups = [
+    ['投保人认证', '投保人身份认证', '身份核验', '实名认证', 'applicant authentication', 'identity verification'],
+    ['短信验证码', '验证码', 'sms verification', 'otp'],
+    ['证件ocr', '证件识别', 'identity ocr', 'document ocr'],
+    ['人脸识别', '人脸认证', 'face recognition', 'facial verification'],
+];
+export function normalized(value) {
+    return value.trim().toLocaleLowerCase();
+}
+export function queryTerms(query) {
+    const clean = normalized(query);
+    const terms = new Set(clean.split(/\s+/).filter(Boolean));
+    for (const group of aliasGroups) {
+        if (group.some((alias) => clean.includes(normalized(alias)))) {
+            for (const alias of group)
+                terms.add(normalized(alias));
+        }
+    }
+    return [...terms].sort();
+}
+function strings(record, entity) {
+    return entity === 'knowledge'
+        ? {
+            statement: typeof record.statement === 'string' ? record.statement : '',
+            kind: typeof record.kind === 'string' ? record.kind : '',
+            scope: typeof record.scope === 'string' ? record.scope : '',
+        }
+        : {
+            attempt: typeof record.attempt === 'string' ? record.attempt : '',
+            reason: typeof record.reason === 'string' ? record.reason : '',
+            scope: typeof record.scope === 'string' ? record.scope : '',
+        };
+}
+function defaultApplicability(event) {
+    if (event.git.ref === null && event.git.branch === null)
+        return { project: true, branchMode: 'global' };
+    return {
+        project: true,
+        branchMode: 'exact',
+        branches: [event.git.ref ?? event.git.branch ?? 'detached'],
+        sourceCommit: event.git.head,
+    };
+}
+function applicability(record, event) {
+    const value = record.applicability;
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+        const candidate = value;
+        if (candidate.project === true && (candidate.branchMode === 'global' || candidate.branchMode === 'exact')) {
+            return {
+                project: true,
+                branchMode: candidate.branchMode,
+                ...(Array.isArray(candidate.branches) ? { branches: candidate.branches.filter((item) => typeof item === 'string').sort() } : {}),
+                ...(Array.isArray(candidate.paths) ? { paths: candidate.paths.filter((item) => typeof item === 'string').sort() } : {}),
+                ...(typeof candidate.sourceCommit === 'string' || candidate.sourceCommit === null ? { sourceCommit: candidate.sourceCommit } : {}),
+            };
+        }
+    }
+    return defaultApplicability(event);
+}
+function recordPayload(event) {
+    const payload = event.payload;
+    return payload.record && typeof payload.record === 'object' && !Array.isArray(payload.record)
+        ? payload.record
+        : null;
+}
+function lifecycleEntity(event, record) {
+    if (event.type.startsWith('knowledge.') && typeof record.knowledgeId === 'string')
+        return { entity: 'knowledge', entityId: record.knowledgeId };
+    if (event.type.startsWith('deadend.') && typeof record.deadendId === 'string')
+        return { entity: 'deadend', entityId: record.deadendId };
+    return null;
+}
+function lifecycleEvent(event) {
+    return [
+        'knowledge.proposed', 'knowledge.verified', 'knowledge.deprecated', 'knowledge.rejected',
+        'deadend.proposed', 'deadend.verified', 'deadend.obsoleted', 'deadend.rejected',
+    ].includes(event.type);
+}
+export function buildRetrievalProjection(events) {
+    const entries = new Map();
+    const feedback = new Map();
+    for (const event of events) {
+        if (event.type === 'record.used') {
+            const payload = event.payload;
+            const entity = payload.entity === 'knowledge' || payload.entity === 'deadend' ? payload.entity : null;
+            const entityId = typeof payload.entityId === 'string' ? payload.entityId : null;
+            if (!entity || !entityId)
+                continue;
+            const key = `${entity}:${entityId}`;
+            const prior = feedback.get(key) ?? { usedCount: 0, latestUsedAt: event.occurredAt };
+            feedback.set(key, { usedCount: prior.usedCount + 1, latestUsedAt: event.occurredAt });
+            continue;
+        }
+        if (!lifecycleEvent(event))
+            continue;
+        const record = recordPayload(event);
+        if (!record)
+            continue;
+        const identity = lifecycleEntity(event, record);
+        if (!identity)
+            continue;
+        const fields = strings(record, identity.entity);
+        const normalizedTerms = [...new Set(Object.values(fields).flatMap((value) => {
+                const normalizedValue = normalized(value);
+                return normalizedValue ? [normalizedValue, ...normalizedValue.split(/\s+/).filter(Boolean)] : [];
+            }))].sort();
+        const key = `${identity.entity}:${identity.entityId}`;
+        entries.set(key, {
+            entity: identity.entity,
+            entityId: identity.entityId,
+            status: typeof record.status === 'string' ? record.status : 'candidate',
+            record,
+            applicability: applicability(record, event),
+            searchable: Object.fromEntries(Object.entries(fields).map(([field, value]) => [field, normalized(value)])),
+            normalizedTerms,
+            provenance: {
+                eventId: event.eventId,
+                eventType: event.type,
+                occurredAt: event.occurredAt,
+                git: event.git,
+                ...(typeof event.payload.anchorProvenance === 'string' ? { anchorProvenance: event.payload.anchorProvenance } : {}),
+            },
+            feedback: { usedCount: 0, latestUsedAt: null },
+        });
+    }
+    for (const [key, entry] of entries) {
+        const value = feedback.get(key);
+        if (value)
+            entry.feedback = value;
+    }
+    const ordered = Object.fromEntries([...entries.entries()].sort(([left], [right]) => left.localeCompare(right)));
+    const terms = new Map();
+    for (const [key, entry] of Object.entries(ordered)) {
+        for (const term of entry.normalizedTerms)
+            terms.set(term, [...(terms.get(term) ?? []), key]);
+    }
+    return {
+        schemaVersion: 2,
+        entries: ordered,
+        terms: Object.fromEntries([...terms.entries()].sort(([left], [right]) => left.localeCompare(right)).map(([term, ids]) => [term, ids.sort()])),
+    };
+}
+function emptyExclusions() {
+    return { status_not_verified: 0, applicability_mismatch: 0, scope_mismatch: 0, query_no_match: 0, result_limit: 0 };
+}
+function applicable(entry, current) {
+    if (entry.applicability.branchMode === 'global')
+        return true;
+    const anchor = entry.provenance.git;
+    return anchor.ref === current.ref
+        && anchor.branch === current.branch
+        && (anchor.worktreeId === null || anchor.worktreeId === current.worktreeId);
+}
+function match(entry, terms, entity) {
+    const fields = new Set();
+    const matched = new Set();
+    let score = 0;
+    const phrase = terms.join(' ');
+    const statementField = entity === 'knowledge' ? 'statement' : 'attempt';
+    if (entry.searchable[statementField]?.includes(phrase))
+        score += entity === 'knowledge' ? 20 : 0;
+    for (const term of terms) {
+        for (const [field, value] of Object.entries(entry.searchable)) {
+            if (!value.includes(term))
+                continue;
+            fields.add(field);
+            matched.add(term);
+            score += field === statementField ? 5 : field === 'scope' ? 4 : 3;
+        }
+    }
+    if (entry.searchable.scope === phrase)
+        score += 10;
+    return { score, matchedTerms: [...matched].sort(), matchedFields: [...fields].sort() };
+}
+function limitText(value, maxChars) {
+    return value.length <= maxChars ? value : `${value.slice(0, Math.max(0, maxChars - 1))}…`;
+}
+export function discoverV2Knowledge(index, query, current, options) {
+    const exclusions = emptyExclusions();
+    const terms = queryTerms(query);
+    const hits = Object.values(index.entries).flatMap((entry) => {
+        if (entry.entity !== 'knowledge')
+            return [];
+        if (entry.status !== 'verified') {
+            exclusions.status_not_verified += 1;
+            return [];
+        }
+        if (!applicable(entry, current)) {
+            exclusions.applicability_mismatch += 1;
+            return [];
+        }
+        const knowledge = entry.record;
+        if (options.scope && normalized(knowledge.scope) !== normalized(options.scope)) {
+            exclusions.scope_mismatch += 1;
+            return [];
+        }
+        const matched = match(entry, terms, 'knowledge');
+        if (matched.matchedTerms.length === 0) {
+            exclusions.query_no_match += 1;
+            return [];
+        }
+        return [{ entry, knowledge, ...matched }];
+    }).sort((left, right) => right.score - left.score
+        || Math.min(right.entry.feedback.usedCount, 5) - Math.min(left.entry.feedback.usedCount, 5)
+        || right.knowledge.confidence - left.knowledge.confidence
+        || right.entry.provenance.occurredAt.localeCompare(left.entry.provenance.occurredAt)
+        || left.knowledge.knowledgeId.localeCompare(right.knowledge.knowledgeId));
+    const selected = hits.slice(0, options.limit);
+    exclusions.result_limit = hits.length - selected.length;
+    return {
+        result: {
+            query,
+            total: hits.length,
+            truncated: hits.length > selected.length,
+            hits: selected.map(({ knowledge, score, matchedTerms, matchedFields, entry }) => ({
+                knowledge: { ...knowledge, statement: limitText(knowledge.statement, options.maxChars), supportingEvidence: knowledge.supportingEvidence.map((value) => limitText(value, options.maxChars)) },
+                score,
+                matchedTerms,
+                matchedFields,
+                why: [...matchedFields.map((field) => `matched ${field}`), ...(entry.feedback.usedCount > 0 ? ['prior recorded use'] : [])],
+            })),
+            duplicateIds: [],
+            possibleConflicts: [],
+        },
+        exclusions,
+    };
+}
+export function discoverV2Deadends(index, query, current, options) {
+    const exclusions = emptyExclusions();
+    const terms = queryTerms(query);
+    const hits = Object.values(index.entries).flatMap((entry) => {
+        if (entry.entity !== 'deadend')
+            return [];
+        if (entry.status !== 'verified') {
+            exclusions.status_not_verified += 1;
+            return [];
+        }
+        if (!applicable(entry, current)) {
+            exclusions.applicability_mismatch += 1;
+            return [];
+        }
+        const deadend = entry.record;
+        if (options.scope && normalized(deadend.scope) !== normalized(options.scope)) {
+            exclusions.scope_mismatch += 1;
+            return [];
+        }
+        const matched = match(entry, terms, 'deadend');
+        if (matched.matchedTerms.length === 0) {
+            exclusions.query_no_match += 1;
+            return [];
+        }
+        return [{ entry, deadend, ...matched }];
+    }).sort((left, right) => right.score - left.score
+        || Math.min(right.entry.feedback.usedCount, 5) - Math.min(left.entry.feedback.usedCount, 5)
+        || right.entry.provenance.occurredAt.localeCompare(left.entry.provenance.occurredAt)
+        || left.deadend.deadendId.localeCompare(right.deadend.deadendId));
+    const selected = hits.slice(0, options.limit);
+    exclusions.result_limit = hits.length - selected.length;
+    return {
+        result: {
+            query,
+            total: hits.length,
+            truncated: hits.length > selected.length,
+            hits: selected.map(({ deadend, score, matchedTerms, matchedFields }) => ({
+                deadend: { ...deadend, attempt: limitText(deadend.attempt, options.maxChars), reason: limitText(deadend.reason, options.maxChars), observedEvidence: deadend.observedEvidence.map((value) => limitText(value, options.maxChars)) },
+                score,
+                matchedTerms,
+                matchedFields,
+            })),
+        },
+        exclusions,
+    };
+}

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

@@ -0,0 +1,12 @@
+import type { RuntimeLease, RuntimeStatus } from './types.js';
+export interface RuntimeServer {
+    lease: RuntimeLease;
+    close(reason?: string): Promise<void>;
+}
+export declare function serveRuntime(startPath?: string): Promise<RuntimeServer>;
+export declare function runtimeStatus(startPath?: string): Promise<RuntimeStatus>;
+export declare function enableRuntime(startPath?: string): Promise<RuntimeStatus>;
+export declare function disableRuntime(startPath?: string): Promise<RuntimeStatus>;
+export declare function startRuntime(startPath?: string): Promise<RuntimeStatus>;
+export declare function stopRuntime(startPath?: string): Promise<RuntimeStatus>;
+export declare function observeRuntime(startPath?: string): Promise<boolean>;