fluffy-context 0.5.0 → 0.7.2

package/dist/src/cognition/journal.js

@@ -5,6 +5,15 @@ import { resolveProjectRoot } from '../project/project-resolver.js';
 import { loadManifest } from '../runtime/init.js';
 import { withLock } from '../storage/lock.js';
 import { cognitionJournalDirectory, locksDirectory } from '../storage/layout.js';
+const eventTypes = new Set([
+    'runtime.enabled', 'runtime.started', 'runtime.stopped', 'host.session.started', 'host.prompt.submitted',
+    'git.state.observed', 'git.branch.changed', 'git.head.changed', 'workspace.paths.changed',
+    'context.checkpoint.imported', 'context.state.recorded', 'note.recorded', 'note.resolved', 'note.absorbed',
+    'knowledge.proposed', 'knowledge.verified', 'knowledge.deprecated', 'knowledge.rejected',
+    'deadend.proposed', 'deadend.verified', 'deadend.obsoleted', 'deadend.rejected', 'record.used',
+    'projection.advanced', 'projection.failed',
+]);
+const sourceKinds = new Set(['cli', 'claude-hook', 'mcp', 'git-observer', 'fs-observer', 'migration']);
 const segmentName = '00000001.ndjson';
 function canonical(value) {
     if (value === null || typeof value !== 'object')
@@ -33,6 +42,49 @@ async function journalFiles(projectRoot) {
         throw error;
     }
 }
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function validGitAnchor(value) {
+    return isRecord(value)
+        && (typeof value.worktreeId === 'string' || value.worktreeId === null)
+        && (typeof value.branch === 'string' || value.branch === null)
+        && (typeof value.ref === 'string' || value.ref === null)
+        && (typeof value.head === 'string' || value.head === null);
+}
+function validIsoDate(value) {
+    return typeof value === 'string' && Number.isFinite(Date.parse(value));
+}
+function validateEventShape(event, projectId, file, line) {
+    if (!isRecord(event)
+        || event.schemaVersion !== 2
+        || typeof event.eventId !== 'string'
+        || event.eventId.length === 0
+        || typeof event.type !== 'string'
+        || !eventTypes.has(event.type)
+        || !validIsoDate(event.occurredAt)
+        || !validIsoDate(event.observedAt)
+        || event.projectId !== projectId
+        || !isRecord(event.source)
+        || typeof event.source.kind !== 'string'
+        || !sourceKinds.has(event.source.kind)
+        || (event.source.instanceId !== undefined && typeof event.source.instanceId !== 'string')
+        || (event.correlationId !== undefined && typeof event.correlationId !== 'string')
+        || typeof event.idempotencyKey !== 'string'
+        || event.idempotencyKey.length === 0
+        || !validGitAnchor(event.git)
+        || !isRecord(event.privacy)
+        || (event.privacy.classification !== 'metadata' && event.privacy.classification !== 'redacted-text')
+        || typeof event.privacy.redactionCount !== 'number'
+        || !Number.isSafeInteger(event.privacy.redactionCount)
+        || event.privacy.redactionCount < 0
+        || !isRecord(event.payload)
+        || (event.previousHash !== null && typeof event.previousHash !== 'string')
+        || typeof event.hash !== 'string'
+        || event.hash.length === 0) {
+        throw new Error(`invalid journal record schema at ${file}:${line}`);
+    }
+}
 async function recoverPartialTail(projectRoot) {
     const files = await journalFiles(projectRoot);
     const file = files.at(-1);
@@ -46,13 +98,15 @@ async function recoverPartialTail(projectRoot) {
     const tail = content.slice(boundary + 1);
     try {
         JSON.parse(tail);
+        await appendFile(filePath, '\n', 'utf8');
     }
     catch {
         await truncate(filePath, boundary < 0 ? 0 : boundary + 1);
     }
 }
-export async function readJournal(startPath) {
+export async function readJournal(startPath, options = {}) {
     const projectRoot = await resolveProjectRoot(startPath);
+    const projectId = (await loadManifest(projectRoot)).projectId;
     const events = [];
     let previousHash = null;
     for (const file of await journalFiles(projectRoot)) {
@@ -67,12 +121,13 @@ export async function readJournal(startPath) {
                 event = JSON.parse(line);
             }
             catch (error) {
-                if (index === lines.length - 1 && !content.endsWith('\n'))
+                if (options.allowPartialTail !== false && index === lines.length - 1 && !content.endsWith('\n'))
                     break;
                 throw new Error(`invalid journal record ${file}:${index + 1}: ${error instanceof Error ? error.message : 'invalid JSON'}`);
             }
+            validateEventShape(event, projectId, file, index + 1);
             const { hash, ...withoutHash } = event;
-            if (event.schemaVersion !== 2 || !event.eventId || event.previousHash !== previousHash || hash !== eventHash(withoutHash)) {
+            if (event.previousHash !== previousHash || hash !== eventHash(withoutHash)) {
                 throw new Error(`invalid journal hash chain at ${file}:${index + 1}`);
             }
             previousHash = event.hash;
@@ -81,14 +136,38 @@ export async function readJournal(startPath) {
     }
     return events;
 }
+export async function verifyJournal(startPath) {
+    return readJournal(startPath, { allowPartialTail: false });
+}
 export async function appendEvent(startPath, input) {
     const projectRoot = await resolveProjectRoot(startPath);
     return withLock(`${locksDirectory(projectRoot)}/cognition-journal.lock`, async () => {
         await recoverPartialTail(projectRoot);
         const existing = await readJournal(projectRoot);
         const duplicate = existing.find((event) => event.idempotencyKey === input.idempotencyKey);
-        if (duplicate)
+        if (duplicate) {
+            const candidate = {
+                type: input.type,
+                source: input.source ?? { kind: 'cli' },
+                correlationId: input.correlationId,
+                idempotencyKey: input.idempotencyKey,
+                git: input.git ?? { worktreeId: null, branch: null, ref: null, head: null },
+                privacy: input.privacy ?? { classification: 'metadata', redactionCount: 0 },
+                payload: input.payload,
+            };
+            const existingSemantic = {
+                type: duplicate.type,
+                source: duplicate.source,
+                correlationId: duplicate.correlationId,
+                idempotencyKey: duplicate.idempotencyKey,
+                git: duplicate.git,
+                privacy: duplicate.privacy,
+                payload: duplicate.payload,
+            };
+            if (canonical(candidate) !== canonical(existingSemantic))
+                throw new Error(`idempotency key conflict: ${input.idempotencyKey}`);
             return { event: duplicate, appended: false };
+        }
         const now = new Date().toISOString();
         const eventWithoutHash = {
             eventId: input.eventId ?? eventId(),

package/dist/src/cognition/migration-v1.js

@@ -21,6 +21,16 @@ function sha256(value) {
 function isNotFound(error) {
     return typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT';
 }
+function eventType(record, live = false) {
+    const status = record.record.status;
+    if (record.kind === 'context')
+        return live ? 'context.state.recorded' : 'context.checkpoint.imported';
+    if (record.kind === 'note')
+        return record.record.absorbedBySnapshotId ? 'note.absorbed' : record.record.status === 'resolved' ? 'note.resolved' : 'note.recorded';
+    if (record.kind === 'knowledge')
+        return status === 'verified' ? 'knowledge.verified' : status === 'deprecated' ? 'knowledge.deprecated' : status === 'rejected' ? 'knowledge.rejected' : 'knowledge.proposed';
+    return status === 'verified' ? 'deadend.verified' : status === 'obsolete' ? 'deadend.obsoleted' : status === 'rejected' ? 'deadend.rejected' : 'deadend.proposed';
+}
 async function readOptional(filePath) {
     try {
         return await readFile(filePath, 'utf8');
@@ -95,7 +105,7 @@ async function sourceRecords(projectRoot) {
 async function writeV2Metadata(projectRoot) {
     const v1 = await loadManifest(projectRoot);
     const manifest = { schemaVersion: 2, layoutVersion: COGNITION_LAYOUT_VERSION, projectId: v1.projectId, createdAt: new Date().toISOString(), policyVersion: 1 };
-    const policy = { schemaVersion: 2, enabled: false, allowHookStartup: false, inactivityTimeoutMs: 300_000, promptIntentMaxChars: 500, filesystemEventsEnabled: false, retentionMaxBytes: 64 * 1024 * 1024 };
+    const policy = { schemaVersion: 2, enabled: true, autoStart: true, allowHookStartup: true, inactivityTimeoutMs: 300_000, promptIntentMaxChars: 500, filesystemEventsEnabled: false, retentionMaxBytes: 64 * 1024 * 1024 };
     await Promise.all([atomicWriteJson(cognitionManifestPath(projectRoot), manifest), atomicWriteJson(cognitionPolicyPath(projectRoot), policy)]);
 }
 async function quarantineReadiness(projectRoot, readiness) {
@@ -129,12 +139,8 @@ export async function importV1(startPath) {
         await writeV2Metadata(projectRoot);
         const importedEventIds = [];
         for (const record of records) {
-            const status = record.record.status;
             const event = await appendEvent(projectRoot, {
-                type: record.kind === 'context' ? 'context.checkpoint.imported'
-                    : record.kind === 'note' ? 'note.recorded'
-                        : record.kind === 'knowledge' ? status === 'verified' ? 'knowledge.verified' : 'knowledge.proposed'
-                            : status === 'verified' ? 'deadend.verified' : 'deadend.proposed',
+                type: eventType(record),
                 occurredAt: record.occurredAt,
                 source: { kind: 'migration' },
                 idempotencyKey: `v1:${record.sourceHash}:${record.kind}:${record.id}`,
@@ -158,12 +164,8 @@ export async function reconcileV1State(startPath) {
             return;
         const { records, sourceHash } = await sourceRecords(projectRoot);
         for (const record of records) {
-            const status = record.record.status;
             await appendEvent(projectRoot, {
-                type: record.kind === 'context' ? 'context.state.recorded'
-                    : record.kind === 'note' ? record.record.absorbedBySnapshotId ? 'note.absorbed' : record.record.status === 'resolved' ? 'note.resolved' : 'note.recorded'
-                        : record.kind === 'knowledge' ? status === 'verified' ? 'knowledge.verified' : 'knowledge.proposed'
-                            : status === 'verified' ? 'deadend.verified' : 'deadend.proposed',
+                type: eventType(record, true),
                 occurredAt: record.occurredAt,
                 source: { kind: 'migration' },
                 idempotencyKey: `v1-live-sync:${sourceHash}:${record.kind}:${record.id}`,

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

@@ -1,9 +1,13 @@
+import type { CognitionEvent, CognitionRetrievalProjection } from './types.js';
 export interface V2OrientationPlan {
     contextId: string;
     snapshotId: string;
     knowledgeIds: ReadonlySet<string>;
     deadendIds: ReadonlySet<string>;
     noteIds: ReadonlySet<string>;
+    retrieval: CognitionRetrievalProjection;
+    currentGit: CognitionEvent['git'];
+    selection: 'requested-context' | 'exact-worktree-ref' | 'legacy-ref-branch';
 }
 export declare function selectV2Orientation(projectRoot: string, contextId?: string): Promise<V2OrientationPlan | null>;
 export declare function v2Enabled(projectRoot: string): Promise<boolean>;

package/dist/src/cognition/orient.js

@@ -1,10 +1,12 @@
 import { access } from 'node:fs/promises';
 import { readGitWorktreeState } from '../git/git-adapter.js';
-import { cognitionManifestPath, cognitionPolicyPath } from '../storage/layout.js';
+import { cognitionManifestPath } from '../storage/layout.js';
 import { readJson } from '../storage/json-store.js';
 import { loadManifest } from '../runtime/init.js';
 import { readJournal } from './journal.js';
 import { projectEvents, workspaceKey } from './projections.js';
+import { buildRetrievalProjection } from './retrieval.js';
+import { loadRuntimePolicy } from './policy.js';
 import { v1Synced } from './v1-bridge.js';
 function contextReference(value) {
     const boundary = value.lastIndexOf(':');
@@ -47,7 +49,7 @@ export async function selectV2Orientation(projectRoot, contextId) {
         const [manifest, cognition, policy] = await Promise.all([
             loadManifest(projectRoot),
             readJson(cognitionManifestPath(projectRoot)),
-            readJson(cognitionPolicyPath(projectRoot)),
+            loadRuntimePolicy(projectRoot),
         ]);
         if (cognition.schemaVersion !== 2 || cognition.projectId !== manifest.projectId || !policy.enabled || !await v1Synced(projectRoot))
             return null;
@@ -56,6 +58,7 @@ export async function selectV2Orientation(projectRoot, contextId) {
             return null;
         const projection = projectEvents(events);
         let selected = null;
+        let selection = 'requested-context';
         if (contextId) {
             const matching = [...Object.keys(projection.contexts)].reverse().find((reference) => contextReference(reference)?.contextId === contextId);
             selected = matching ? contextReference(matching) : null;
@@ -65,10 +68,17 @@ export async function selectV2Orientation(projectRoot, contextId) {
             const legacy = Object.values(projection.workspaces).find((workspace) => workspace.worktreeId === null && (workspace.ref === current.ref || workspace.branch === current.branch));
             const reference = (exact?.activeContextRef ? exact : legacy)?.activeContextRef;
             selected = reference ? contextReference(reference) : null;
+            selection = exact?.activeContextRef ? 'exact-worktree-ref' : 'legacy-ref-branch';
         }
         if (!selected || !projection.contexts[`${selected.contextId}:${selected.snapshotId}`])
             return null;
-        return { ...selected, ...latestRecords(events, current, selected.contextId) };
+        return {
+            ...selected,
+            ...latestRecords(events, current, selected.contextId),
+            retrieval: buildRetrievalProjection(events),
+            currentGit: { worktreeId: current.worktreeId, branch: current.branch, ref: current.ref, head: current.commit },
+            selection,
+        };
     }
     catch {
         return null;
@@ -77,7 +87,7 @@ export async function selectV2Orientation(projectRoot, contextId) {
 export async function v2Enabled(projectRoot) {
     try {
         await access(cognitionManifestPath(projectRoot));
-        return (await readJson(cognitionPolicyPath(projectRoot))).enabled;
+        return (await loadRuntimePolicy(projectRoot)).enabled;
     }
     catch {
         return false;

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

@@ -0,0 +1,4 @@
+import type { CognitionRuntimePolicy } from './types.js';
+export declare function normalizeRuntimePolicy(value: Partial<CognitionRuntimePolicy>): CognitionRuntimePolicy;
+export declare function loadRuntimePolicy(projectRoot: string): Promise<CognitionRuntimePolicy>;
+export declare function writeRuntimePolicy(projectRoot: string, policy: CognitionRuntimePolicy): Promise<void>;

package/dist/src/cognition/policy.js

@@ -0,0 +1,49 @@
+import { atomicWriteJson } from '../storage/atomic-write.js';
+import { cognitionPolicyPath } from '../storage/layout.js';
+import { readJson } from '../storage/json-store.js';
+const defaults = {
+    schemaVersion: 2,
+    enabled: true,
+    autoStart: true,
+    allowHookStartup: true,
+    inactivityTimeoutMs: 300_000,
+    promptIntentMaxChars: 500,
+    filesystemEventsEnabled: false,
+    retentionMaxBytes: 64 * 1024 * 1024,
+};
+function booleanValue(value, fallback, field) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== 'boolean')
+        throw new Error(`runtime policy field ${field} must be boolean`);
+    return value;
+}
+function nonNegativeInteger(value, fallback, field) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0)
+        throw new Error(`runtime policy field ${field} must be a non-negative integer`);
+    return value;
+}
+export function normalizeRuntimePolicy(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('runtime policy must be an object');
+    if (value.schemaVersion !== undefined && value.schemaVersion !== 2)
+        throw new Error('unsupported runtime policy schema');
+    return {
+        ...defaults,
+        enabled: booleanValue(value.enabled, defaults.enabled, 'enabled'),
+        autoStart: booleanValue(value.autoStart, defaults.autoStart, 'autoStart'),
+        allowHookStartup: booleanValue(value.allowHookStartup, defaults.allowHookStartup, 'allowHookStartup'),
+        inactivityTimeoutMs: nonNegativeInteger(value.inactivityTimeoutMs, defaults.inactivityTimeoutMs, 'inactivityTimeoutMs'),
+        promptIntentMaxChars: nonNegativeInteger(value.promptIntentMaxChars, defaults.promptIntentMaxChars, 'promptIntentMaxChars'),
+        filesystemEventsEnabled: booleanValue(value.filesystemEventsEnabled, defaults.filesystemEventsEnabled, 'filesystemEventsEnabled'),
+        retentionMaxBytes: nonNegativeInteger(value.retentionMaxBytes, defaults.retentionMaxBytes, 'retentionMaxBytes'),
+    };
+}
+export async function loadRuntimePolicy(projectRoot) {
+    return normalizeRuntimePolicy(await readJson(cognitionPolicyPath(projectRoot)));
+}
+export async function writeRuntimePolicy(projectRoot, policy) {
+    await atomicWriteJson(cognitionPolicyPath(projectRoot), normalizeRuntimePolicy(policy));
+}

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

@@ -3,10 +3,29 @@ export interface RuntimeServer {
     lease: RuntimeLease;
     close(reason?: string): Promise<void>;
 }
-export declare function serveRuntime(startPath?: string): Promise<RuntimeServer>;
+interface RuntimeServeOptions {
+    inactivityTimeoutMs?: number;
+    heartbeatIntervalMs?: number;
+    pollIntervalMs?: number;
+}
+export interface EnsureRuntimeOptions {
+    source?: 'claude-hook' | 'mcp' | 'cli';
+    timeoutMs?: number;
+}
+export interface EnsureRuntimeResult {
+    projectRoot: string;
+    started: boolean;
+    running: boolean;
+    skipped: 'disabled' | 'not-migrated' | 'already-running' | 'startup-in-progress' | 'startup-failed' | 'unavailable' | null;
+}
+export declare function serveRuntime(startPath?: string, options?: RuntimeServeOptions): 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 setFilesystemEvents(startPath: string | undefined, enabled: boolean): Promise<RuntimeStatus>;
 export declare function startRuntime(startPath?: string): Promise<RuntimeStatus>;
+export declare function ensureRuntimeForSession(startPath?: string, options?: EnsureRuntimeOptions): Promise<EnsureRuntimeResult>;
 export declare function stopRuntime(startPath?: string): Promise<RuntimeStatus>;
 export declare function observeRuntime(startPath?: string): Promise<boolean>;
+export declare function touchRuntime(startPath?: string): Promise<boolean>;
+export {};