homegraph 1.6.0 → 1.6.2

package/dist/search/query-plan.js

@@ -51,7 +51,8 @@ exports.compileQueryPlanStep = compileQueryPlanStep;
 exports.planQuery = planQuery;
 /** Versioned retrieval intent, not a replacement for the user's question or graph evidence. */
 const shape = __importStar(require("./query-utils"));
-exports.QUERY_PLAN_VERSION = 2;
+const request_contract_1 = require("./request-contract");
+exports.QUERY_PLAN_VERSION = 3;
 exports.QUERY_RELATIONS = ['incoming_references', 'registration_sites', 'outgoing_calls', 'module_imports', 'module_cycles'];
 exports.QUERY_SOURCE_SCOPES = ['local', 'sdk', 'all'];
 /** One shared bound for provider input, transferred plans and cache identity. */
@@ -193,6 +194,7 @@ function buildRuleQueryPlan(query, originalTaskContext) {
     return {
         version: exports.QUERY_PLAN_VERSION,
         originalQuery: query,
+        requestContract: (0, request_contract_1.ruleRequestContract)(canonicalQuery, literalTexts),
         ...(taskContext ? { taskContext } : {}),
         canonicalQuery,
         intent,
@@ -295,9 +297,14 @@ function compileQueryPlanStep(plan, step, resolvedAnchors = []) {
     const relation = step.relation;
     const stepIntent = intentForQueryRelation(downgradedOverview ? 'general' : step.intent, relation);
     const query = downgradedOverview ? plan.originalQuery : step.query;
-    const literalTexts = step.literalTexts ?? (plan.steps.length === 1 ? plan.literalTexts : undefined) ?? [];
-    // Spec 0042: non-LLM retrieval must not concatenate taskContext into the FTS string.
-    // Planner prose stays out of seeds; only typed slots (anchors/searchTerms/literalTexts) retrieve.
+    const literalTexts = [...new Set([...(step.literalTexts ?? (plan.steps.length === 1 ? plan.literalTexts : undefined) ?? []),
+            // Independent discovery keeps user labels; dependent helpers retain identity without global UI seeds.
+            ...(!step.dependsOn.length ? [...(plan.literalTexts ?? []), ...((0, request_contract_1.accuracyTargetsEnabled)() ? (0, request_contract_1.contractLiteralTexts)(plan.requestContract) : [])] : [])])].slice(0, 8);
+    // Scope and negations remain losslessly in originalQuery/taskContext for the
+    // executor and cache. Repeating that prose here erases the step's focus.
+    // A planner's English explanation is not source text. Only its typed slots
+    // become seeds; this prevents a verb such as "locate" matching an SDK method.
+    // Legacy/malformed seedless steps retain the USER's query, never planner prose.
     const seeds = [...new Set([...anchors, ...(step.searchTerms ?? []), ...literalTexts])];
     const retrievalQuery = plan.source === 'llm'
         ? seeds.join(' ') || plan.originalQuery : query;

package/dist/search/request-contract.d.ts

@@ -0,0 +1,29 @@
+/** Grounded request data, never repository facts or benchmark acceptance answers. */
+export declare const TARGET_ROLES: readonly ["page", "literal", "symbol", "object"];
+export declare const OBJECT_KINDS: readonly ["ui", "form", "native"];
+export declare const BEHAVIOR_KINDS: readonly ["enabled", "visibility", "event", "state", "route", "runtime"];
+export interface RequestTarget {
+    id: string;
+    text: string;
+    role: typeof TARGET_ROLES[number];
+    presence: 'existing' | 'requested';
+    objectKind?: typeof OBJECT_KINDS[number];
+}
+export interface BehaviorObligation {
+    id: string;
+    text: string;
+    kind: typeof BEHAVIOR_KINDS[number];
+    targetId?: string;
+}
+export interface RequestContract {
+    targets: RequestTarget[];
+    obligations: BehaviorObligation[];
+}
+export declare const accuracyTargetsEnabled: () => boolean;
+export declare const accuracyCoverageEnabled: () => boolean;
+/** No repair of invented text, no unknown enum values, no generated identifiers. */
+export declare function validateRequestContract(value: unknown, original: string): RequestContract | undefined;
+/** Fallback deliberately cannot decide whether quoted text should already exist. */
+export declare function ruleRequestContract(original: string, literals: string[]): RequestContract | undefined;
+export declare function contractLiteralTexts(contract?: RequestContract): string[];
+//# sourceMappingURL=request-contract.d.ts.map

package/dist/search/request-contract.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.accuracyCoverageEnabled = exports.accuracyTargetsEnabled = exports.BEHAVIOR_KINDS = exports.OBJECT_KINDS = exports.TARGET_ROLES = void 0;
+exports.validateRequestContract = validateRequestContract;
+exports.ruleRequestContract = ruleRequestContract;
+exports.contractLiteralTexts = contractLiteralTexts;
+/** Grounded request data, never repository facts or benchmark acceptance answers. */
+exports.TARGET_ROLES = ['page', 'literal', 'symbol', 'object'];
+exports.OBJECT_KINDS = ['ui', 'form', 'native'];
+exports.BEHAVIOR_KINDS = ['enabled', 'visibility', 'event', 'state', 'route', 'runtime'];
+const accuracyTargetsEnabled = () => process.env.HOMEGRAPH_ACCURACY_TARGETS !== '0';
+exports.accuracyTargetsEnabled = accuracyTargetsEnabled;
+const accuracyCoverageEnabled = () => process.env.HOMEGRAPH_ACCURACY_COVERAGE !== '0';
+exports.accuracyCoverageEnabled = accuracyCoverageEnabled;
+/** No repair of invented text, no unknown enum values, no generated identifiers. */
+function validateRequestContract(value, original) {
+    if (value === undefined)
+        return undefined;
+    const fail = () => { throw new Error('invalid_request_contract'); };
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return fail();
+    const v = value;
+    if (!Array.isArray(v.targets) || v.targets.length > 6 || !Array.isArray(v.obligations) || v.obligations.length > 6)
+        return fail();
+    if (Object.keys(v).some(key => !['targets', 'obligations'].includes(key)))
+        return fail();
+    const ids = new Set();
+    const record = (raw) => {
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+            return fail();
+        const r = raw;
+        if (typeof r.id !== 'string' || !/^[A-Za-z][\w-]{0,15}$/.test(r.id) || ids.has(r.id)
+            || typeof r.text !== 'string' || r.text.trim() !== r.text || r.text.length < 2 || r.text.length > 256
+            || /[\u0000-\u001f\u007f]/.test(r.text) || !original.includes(r.text))
+            return fail();
+        ids.add(r.id);
+        return r;
+    };
+    const targets = v.targets.map(raw => {
+        const r = record(raw);
+        if (Object.keys(r).some(key => !['id', 'text', 'role', 'presence', 'objectKind'].includes(key)))
+            return fail();
+        if (!exports.TARGET_ROLES.includes(r.role) || !['existing', 'requested'].includes(r.presence)
+            || (r.objectKind !== undefined && !exports.OBJECT_KINDS.includes(r.objectKind)))
+            return fail();
+        return { id: r.id, text: r.text, role: r.role,
+            presence: r.presence, ...(r.objectKind ? { objectKind: r.objectKind } : {}) };
+    });
+    const obligations = v.obligations.map(raw => {
+        const r = record(raw);
+        if (Object.keys(r).some(key => !['id', 'text', 'kind', 'targetId'].includes(key)))
+            return fail();
+        if (!exports.BEHAVIOR_KINDS.includes(r.kind)
+            || (r.targetId !== undefined && !targets.some(t => t.id === r.targetId)))
+            return fail();
+        return { id: r.id, text: r.text, kind: r.kind,
+            ...(r.targetId ? { targetId: r.targetId } : {}) };
+    });
+    return { targets, obligations };
+}
+/** Fallback deliberately cannot decide whether quoted text should already exist. */
+function ruleRequestContract(original, literals) {
+    const targets = literals.slice(0, 6).map((text, i) => ({ id: `t${i + 1}`, text, role: 'literal', presence: 'requested' }));
+    // A small language-level behavior trigger, not a list of task names or expected answers.
+    const statements = original.split(/[\n。；;]/).map(s => s.trim()).filter(Boolean);
+    const obligations = statements.filter(s => /禁用|启用|\bdisabl(?:e|ed|ing)\b|\benabl(?:e|ed|ing)\b/i.test(s))
+        .slice(0, 6).map((s, i) => {
+        const named = targets.filter(t => s.includes(t.text));
+        return { id: `b${i + 1}`, text: s.slice(0, 256), kind: 'enabled', ...(named.length === 1 ? { targetId: named[0].id } : {}) };
+    });
+    return targets.length || obligations.length ? { targets, obligations } : undefined;
+}
+function contractLiteralTexts(contract) {
+    return (contract?.targets ?? []).filter(t => t.role === 'literal' || t.role === 'page').map(t => t.text);
+}
+//# sourceMappingURL=request-contract.js.map

package/dist/sync/watcher.d.ts

@@ -88,7 +88,30 @@ export interface WatchOptions {
      * sets it.
      */
     inertForTests?: boolean;
+    /**
+     * Indexed size and mtime for a project-relative path, or null when the
+     * file is not in the index. On Windows this drops watcher events whose
+     * size and modification time still match the index — NTFS last-access
+     * updates look like edits (Spec 0055). Absent means every event is kept.
+     */
+    indexedFingerprint?: (relPath: string) => {
+        size: number;
+        modifiedAt: number;
+    } | null;
 }
+/**
+ * True when a watcher event is only an NTFS last-access update: Windows,
+ * the file is already indexed, and its size and modification time still
+ * match. A missing stat, a missing index row, or any other platform is a
+ * real change (fail open).
+ */
+export declare function isAccessTimeOnlyChange(platform: NodeJS.Platform, onDisk: {
+    size: number;
+    mtimeMs: number;
+} | null, indexed: {
+    size: number;
+    modifiedAt: number;
+} | null): boolean;
 /**
  * Thrown by a `syncFn` to signal that the underlying sync couldn't acquire
  * the cross-process write lock (#449). The watcher treats this as "no
@@ -209,6 +232,7 @@ export declare class FileWatcher {
     private readonly onSyncError?;
     private readonly onDegraded?;
     private readonly inertForTests;
+    private readonly indexedFingerprint?;
     constructor(projectRoot: string, syncFn: (paths?: string[]) => Promise<{
         filesChanged: number;
         durationMs: number;
@@ -257,6 +281,12 @@ export declare class FileWatcher {
      * — it drops node_modules/dist/.git churn before any sync is scheduled.
      */
     private handleChange;
+    /**
+     * Windows ReadDirectoryChangesW reports a read as `change` when NTFS
+     * updates last-access time. Drop that event when size and mtime still
+     * match the index. Stat or lookup failure keeps the event.
+     */
+    private isAccessTimeOnly;
     /**
      * A deleted DIRECTORY arrives as one event on the directory's own path —
      * no source extension, so the source-file filter drops it, and the files

package/dist/sync/watcher.js

@@ -67,6 +67,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FileWatcher = exports.LockUnavailableError = void 0;
 exports.__setFsWatchForTests = __setFsWatchForTests;
+exports.isAccessTimeOnlyChange = isAccessTimeOnlyChange;
 exports.__emitWatchEventForTests = __emitWatchEventForTests;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
@@ -186,6 +187,18 @@ function maxDirWatches() {
  */
 const liveWatchersForTests = new Map();
 const IS_TEST_RUNTIME = !!(process.env.VITEST || process.env.NODE_ENV === 'test');
+/**
+ * True when a watcher event is only an NTFS last-access update: Windows,
+ * the file is already indexed, and its size and modification time still
+ * match. A missing stat, a missing index row, or any other platform is a
+ * real change (fail open).
+ */
+function isAccessTimeOnlyChange(platform, onDisk, indexed) {
+    if (platform !== 'win32' || !onDisk || !indexed)
+        return false;
+    return onDisk.size === indexed.size
+        && Math.floor(onDisk.mtimeMs) === Math.floor(indexed.modifiedAt);
+}
 /**
  * Thrown by a `syncFn` to signal that the underlying sync couldn't acquire
  * the cross-process write lock (#449). The watcher treats this as "no
@@ -296,6 +309,7 @@ class FileWatcher {
     onSyncError;
     onDegraded;
     inertForTests;
+    indexedFingerprint;
     constructor(projectRoot, syncFn, options = {}) {
         this.projectRoot = projectRoot;
         this.syncFn = syncFn;
@@ -305,6 +319,7 @@ class FileWatcher {
         this.onSyncError = options.onSyncError;
         this.onDegraded = options.onDegraded;
         this.inertForTests = options.inertForTests ?? false;
+        this.indexedFingerprint = options.indexedFingerprint;
     }
     /**
      * Start watching for file changes.
@@ -528,6 +543,10 @@ class FileWatcher {
             this.maybeScheduleForRemovedDir(rel);
             return;
         }
+        if (this.isAccessTimeOnly(rel)) {
+            (0, errors_1.logDebug)('Ignoring Windows access-time watcher event', { file: rel });
+            return;
+        }
         (0, errors_1.logDebug)('File change detected', { file: rel });
         if (this.ready) {
             const now = Date.now();
@@ -539,6 +558,32 @@ class FileWatcher {
         }
         this.scheduleSync();
     }
+    /**
+     * Windows ReadDirectoryChangesW reports a read as `change` when NTFS
+     * updates last-access time. Drop that event when size and mtime still
+     * match the index. Stat or lookup failure keeps the event.
+     */
+    isAccessTimeOnly(rel) {
+        if (process.platform !== 'win32' || !this.indexedFingerprint)
+            return false;
+        let indexed;
+        try {
+            indexed = this.indexedFingerprint(rel);
+        }
+        catch {
+            return false;
+        }
+        let onDisk = null;
+        try {
+            const st = fs.statSync(path.join(this.projectRoot, rel));
+            if (st.isFile())
+                onDisk = { size: st.size, mtimeMs: st.mtimeMs };
+        }
+        catch {
+            onDisk = null;
+        }
+        return isAccessTimeOnlyChange(process.platform, onDisk, indexed);
+    }
     /**
      * A deleted DIRECTORY arrives as one event on the directory's own path —
      * no source extension, so the source-file filter drops it, and the files

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "homegraph",
-  "version": "1.6.0",
+  "version": "1.6.2",
   "description": "Supercharge AI coding agents with semantic code intelligence — surgical context, fewer tool calls, faster answers. 100% local.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",