knodin 0.12.2 → 0.13.0

package/dist/src/engine/apex-entry-points.js

@@ -0,0 +1,98 @@
+const normalized = (value) => value.replace(/^@/, "").toLowerCase();
+const ownerKey = (row) => JSON.stringify([row.file, normalized(row.declaration.owner)]);
+const callbacks = new Map([
+    ["queueable", ["execute"]],
+    ["system.queueable", ["execute"]],
+    ["database.batchable", ["start", "execute", "finish"]],
+    ["schedulable", ["execute"]],
+    ["system.schedulable", ["execute"]],
+    ["messaging.inboundemailhandler", ["handleinboundemail"]],
+]);
+function callbackSignature(contract, declaration) {
+    const name = normalized(declaration.name);
+    const types = declaration.parameterTypes.map((type) => normalized(type)
+        .replace(/\s/g, "")
+        .replace(/^system\./, ""));
+    if (declaration.arity !== types.length)
+        return false;
+    if (contract === "queueable" || contract === "system.queueable")
+        return name === "execute" && types.length === 1 && types[0] === "queueablecontext";
+    if (contract === "schedulable" || contract === "system.schedulable")
+        return name === "execute" && types.length === 1 && types[0] === "schedulablecontext";
+    if (contract === "messaging.inboundemailhandler")
+        return (name === "handleinboundemail" &&
+            types.length === 2 &&
+            types[0] === "messaging.inboundemail" &&
+            types[1] === "messaging.inboundenvelope");
+    if (contract === "database.batchable") {
+        if (types[0] !== "database.batchablecontext")
+            return false;
+        if (name === "start" || name === "finish")
+            return types.length === 1;
+        return (name === "execute" &&
+            types.length === 2 &&
+            (/^list<.+>$/.test(types[1]) || types[1].endsWith("[]")));
+    }
+    return false;
+}
+/** Static org-facing declarations, never a claim that an org actually invokes them. */
+export function apexOrgEntryPoints(rows) {
+    const protectedSymbols = new Map();
+    const classes = new Map();
+    for (const row of rows) {
+        const decl = row.declaration;
+        if (decl.kind !== "class")
+            continue;
+        const key = ownerKey(row);
+        classes.set(key, [...(classes.get(key) ?? []), row]);
+        if (decl.annotations.some((name) => normalized(name) === "restresource"))
+            protectedSymbols.set(row.key, "REST resource declaration");
+        if (decl.implements.some((name) => callbacks.has(normalized(name))))
+            protectedSymbols.set(row.key, "Salesforce platform callback contract");
+    }
+    for (const row of rows) {
+        const decl = row.declaration;
+        if (decl.kind !== "method")
+            continue;
+        const owners = classes.get(ownerKey(row)) ?? [];
+        // Duplicate declarations cannot establish a specific enclosing contract.
+        if (owners.length !== 1)
+            continue;
+        const owner = owners[0];
+        const annotations = new Set(decl.annotations.map(normalized));
+        const modifiers = new Set(decl.modifiers.map(normalized));
+        let reason;
+        if (annotations.has("invocablemethod") && decl.static)
+            reason = "Invocable Apex declaration";
+        if (annotations.has("auraenabled") && decl.static)
+            reason = "Lightning Apex API declaration";
+        if (annotations.has("future") && decl.static)
+            reason = "Future Apex callback declaration";
+        if (modifiers.has("webservice") && decl.static)
+            reason = "SOAP Apex declaration";
+        if (decl.static &&
+            owner.declaration.annotations.some((name) => normalized(name) === "restresource") &&
+            ["httpget", "httppost", "httpput", "httppatch", "httpdelete"].some((name) => annotations.has(name)))
+            reason = "REST Apex method declaration";
+        if (!decl.static &&
+            (modifiers.has("public") || modifiers.has("global")) &&
+            owner.declaration.implements.some((name) => callbackSignature(normalized(name), decl)))
+            reason = "Salesforce platform callback method";
+        if (reason) {
+            protectedSymbols.set(row.key, reason);
+            protectedSymbols.set(owner.key, "Owner of an org-facing Apex declaration");
+        }
+    }
+    // A constructor of an org-facing class is a boundary, not an ordinary helper.
+    for (const row of rows) {
+        const decl = row.declaration;
+        if (decl.kind !== "method" || decl.static)
+            continue;
+        const owners = classes.get(ownerKey(row)) ?? [];
+        if (owners.length === 1 &&
+            protectedSymbols.has(owners[0].key) &&
+            normalized(decl.name) === normalized(owners[0].declaration.name))
+            protectedSymbols.set(row.key, "Constructor of an org-facing Apex class");
+    }
+    return protectedSymbols;
+}

package/dist/src/engine/apex-receiver.js

@@ -0,0 +1,301 @@
+const identifier = /^[A-Za-z_]\w*(?:\.[A-Za-z_]\w*)*$/;
+const fold = (value) => value.toLowerCase();
+const countArguments = (node, field) => node.childForFieldName(field)?.namedChildren.filter((child) => !child.type.includes("comment"))
+    .length ?? 0;
+function ownerPath(node, includeSelf = false) {
+    const names = [];
+    for (let parent = includeSelf ? node : node.parent; parent; parent = parent.parent) {
+        if (parent.type === "class_declaration") {
+            const name = parent.childForFieldName("name")?.text;
+            if (name)
+                names.unshift(name);
+        }
+    }
+    return names.join(".");
+}
+/** Extract an implemented type identity from grammar nodes, not sanitized source text. */
+function implementedTypeName(node) {
+    if (node.type === "generic_type") {
+        const children = node.namedChildren.filter((child) => !child.type.includes("comment"));
+        if (children.length !== 2 || children[1].type !== "type_arguments")
+            return null;
+        return implementedTypeName(children[0]);
+    }
+    if (node.type !== "type_identifier" && node.type !== "scoped_type_identifier")
+        return null;
+    const name = node.text.trim();
+    return identifier.test(name) ? name : null;
+}
+export function apexDeclaration(node) {
+    const modifiers = node.namedChildren.find((child) => child.type === "modifiers");
+    const words = modifiers?.namedChildren
+        .filter((child) => child.type === "modifier")
+        .map((child) => fold(child.text)) ?? [];
+    const annotations = modifiers?.namedChildren
+        .filter((child) => child.type === "annotation")
+        .map((child) => child.childForFieldName("name")?.text ?? "") ?? [];
+    const kind = node.type === "class_declaration" ? "class" : "method";
+    const interfaces = node.childForFieldName("interfaces");
+    const types = interfaces?.hasError()
+        ? undefined
+        : interfaces?.namedChildren.find((child) => child.type === "type_list");
+    return {
+        version: 1,
+        kind,
+        owner: ownerPath(node, kind === "class"),
+        name: node.childForFieldName("name")?.text ?? "",
+        arity: kind === "method" ? countArguments(node, "parameters") : null,
+        parameterTypes: kind === "method"
+            ? (node.childForFieldName("parameters")?.namedChildren ?? [])
+                .filter((child) => !child.type.includes("comment"))
+                .map((child) => child.childForFieldName("type")?.text ?? "")
+            : [],
+        static: words.includes("static"),
+        constructors: kind === "class"
+            ? (node.childForFieldName("body")?.namedChildren ?? [])
+                .filter((child) => child.type === "constructor_declaration")
+                .map((child) => countArguments(child, "parameters"))
+            : [],
+        modifiers: words,
+        annotations,
+        implements: types?.namedChildren
+            .map(implementedTypeName)
+            .filter((name) => name !== null) ?? [],
+    };
+}
+/** Conservative lexical proof: inherited/unknown scopes and value shadowing do not resolve. */
+export function apexCall(node) {
+    const isConstructor = node.type === "object_creation_expression";
+    const receiver = node.childForFieldName(isConstructor ? "type" : "object")?.text ?? "";
+    const member = isConstructor
+        ? (receiver.split(".").at(-1) ?? receiver)
+        : (node.childForFieldName("name")?.text ?? "");
+    let blocked = !identifier.test(receiver) || !identifier.test(member);
+    if (!receiver.includes(".")) {
+        for (let scope = node.parent; scope; scope = scope.parent) {
+            if (scope.type !== "class_declaration")
+                continue;
+            if (scope
+                .descendantsOfType("class_declaration")
+                .some((candidate) => ownerPath(candidate, true).includes(".") &&
+                fold(candidate.childForFieldName("name")?.text ?? "") === fold(receiver)))
+                blocked = true;
+        }
+    }
+    if (!isConstructor) {
+        const first = fold(receiver.split(".")[0] ?? "");
+        for (let scope = node.parent; scope; scope = scope.parent) {
+            if (scope.type === "class_declaration" && scope.childForFieldName("superclass"))
+                blocked = true;
+            if (![
+                "class_declaration",
+                "method_declaration",
+                "constructor_declaration",
+                "trigger_declaration",
+            ].includes(scope.type))
+                continue;
+            for (const binding of scope.descendantsOfType([
+                "formal_parameter",
+                "variable_declarator",
+                "property_declaration",
+                "enhanced_for_statement",
+                "catch_formal_parameter",
+            ])) {
+                const name = binding.childForFieldName("name")?.text;
+                if (name && fold(name) === first)
+                    blocked = true;
+            }
+        }
+    }
+    return {
+        version: 1,
+        kind: isConstructor ? "constructor" : "static",
+        receiver,
+        member,
+        arity: countArguments(node, "arguments"),
+        blocked,
+    };
+}
+function payload(raw) {
+    if (!raw || raw.length > 16_384)
+        return null;
+    try {
+        const value = JSON.parse(raw);
+        return value && typeof value === "object" && value.version === 1 ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+const strings = (value) => Array.isArray(value) &&
+    value.length <= 1000 &&
+    value.every((entry) => typeof entry === "string" && entry.length <= 500);
+const arity = (value) => typeof value === "number" && Number.isInteger(value) && value >= 0 && value <= 1000;
+export function parseApexDeclaration(raw) {
+    const value = payload(raw);
+    if (!value ||
+        !["class", "method"].includes(String(value.kind)) ||
+        typeof value.owner !== "string" ||
+        !identifier.test(value.owner) ||
+        typeof value.name !== "string" ||
+        !identifier.test(value.name) ||
+        typeof value.static !== "boolean" ||
+        !(value.arity === null || arity(value.arity)) ||
+        !Array.isArray(value.constructors) ||
+        !value.constructors.every(arity) ||
+        !strings(value.modifiers) ||
+        !strings(value.annotations) ||
+        !strings(value.implements))
+        return null;
+    if (!strings(value.parameterTypes) ||
+        (value.kind === "method" &&
+            (!arity(value.arity) || value.parameterTypes.length !== value.arity)) ||
+        (value.kind === "class" && (value.arity !== null || value.parameterTypes.length !== 0)))
+        return null;
+    return value;
+}
+export function parseApexCall(raw) {
+    const value = payload(raw);
+    if (!value ||
+        !["static", "constructor"].includes(String(value.kind)) ||
+        typeof value.receiver !== "string" ||
+        value.receiver.length > 500 ||
+        typeof value.member !== "string" ||
+        value.member.length > 500 ||
+        typeof value.blocked !== "boolean" ||
+        !arity(value.arity))
+        return null;
+    return value;
+}
+/** Read-time defense against damaged provenance retaining an older canonical endpoint. */
+export function apexReferenceReadGuard(db) {
+    const targets = new Map();
+    return (reference) => {
+        if (reference.apexCall == null)
+            return true;
+        const call = parseApexCall(reference.apexCall);
+        if (!call ||
+            call.blocked ||
+            !identifier.test(call.receiver) ||
+            !identifier.test(call.member) ||
+            !reference.calleeIdentity ||
+            !reference.calleeFile)
+            return false;
+        const key = JSON.stringify([reference.calleeIdentity, reference.calleeFile]);
+        if (!targets.has(key)) {
+            const row = db
+                .query("SELECT * FROM symbols WHERE identity=? AND filePath=?")
+                .get(reference.calleeIdentity, reference.calleeFile);
+            targets.set(key, parseApexDeclaration(row?.apexDeclaration));
+        }
+        const target = targets.get(key);
+        if (!target || fold(target.owner) !== fold(call.receiver))
+            return false;
+        if (call.kind === "constructor")
+            return (target.kind === "class" &&
+                !target.modifiers.includes("abstract") &&
+                (target.constructors.length === 0
+                    ? call.arity === 0
+                    : target.constructors.filter((value) => value === call.arity).length === 1));
+        return (target.kind === "method" &&
+            target.static &&
+            target.arity === call.arity &&
+            fold(target.name) === fold(call.member));
+    };
+}
+/** One indexed catalog and raw-call scan per changed-Apex batch; never opens source files. */
+export function persistApexReferenceEndpoints(db) {
+    const declarations = db
+        .query("SELECT name,filePath,identity,apexDeclaration FROM symbols WHERE apexDeclaration IS NOT NULL")
+        .all()
+        .flatMap((row) => {
+        const declaration = parseApexDeclaration(row.apexDeclaration);
+        return declaration ? [{ row, declaration }] : [];
+    });
+    const classes = new Map();
+    const methods = new Map();
+    for (const entry of declarations) {
+        const map = entry.declaration.kind === "class" ? classes : methods;
+        const key = fold(entry.declaration.owner);
+        const list = map.get(key) ?? [];
+        list.push(entry);
+        map.set(key, list);
+    }
+    const refs = db
+        .query('SELECT id,apexCall,calleeSymbol FROM "references" WHERE apexCall IS NOT NULL')
+        .all();
+    const update = db.query('UPDATE "references" SET calleeSymbol=?, calleeFile=?, calleeIdentity=? WHERE id=?');
+    for (const ref of refs) {
+        const call = parseApexCall(ref.apexCall);
+        let target;
+        if (call && !call.blocked && identifier.test(call.receiver) && identifier.test(call.member)) {
+            const owners = classes.get(fold(call.receiver)) ?? [];
+            if (owners.length === 1) {
+                const owner = owners[0];
+                if (call.kind === "constructor") {
+                    const ctors = owner.declaration.constructors;
+                    if (!owner.declaration.modifiers.includes("abstract") &&
+                        (ctors.length
+                            ? ctors.filter((count) => count === call.arity).length === 1
+                            : call.arity === 0))
+                        target = owner.row;
+                }
+                else {
+                    const candidates = (methods.get(fold(call.receiver)) ?? []).filter((entry) => entry.row.filePath === owner.row.filePath &&
+                        fold(entry.declaration.name) === fold(call.member) &&
+                        entry.declaration.arity === call.arity);
+                    if (candidates.length === 1 && candidates[0].declaration.static)
+                        target = candidates[0].row;
+                }
+            }
+        }
+        update.run(target?.name ?? call?.member ?? ref.calleeSymbol, target?.identity ? target.filePath : null, target?.identity ?? null, ref.id);
+    }
+    update.finalize();
+}
+export function apexReceiverCapability(db, filePath) {
+    const scope = filePath === undefined ? [] : [filePath];
+    const epochTable = !!db
+        .query("SELECT name FROM sqlite_master WHERE type='table' AND name='apex_file_capabilities'")
+        .get();
+    const hasColumn = (table, name) => db
+        .query(`PRAGMA table_info("${table}")`)
+        .all()
+        .some((column) => column.name === name);
+    const provenance = epochTable && hasColumn("symbols", "apexDeclaration") && hasColumn("references", "apexCall");
+    const predicate = `FROM index_state i ${provenance ? "LEFT JOIN apex_file_capabilities a ON a.filePath=i.filePath" : ""} WHERE (i.filePath LIKE '%.cls' OR i.filePath LIKE '%.trigger')${provenance ? " AND (a.version IS NULL OR a.version<>1)" : ""}${filePath === undefined ? "" : " AND i.filePath=?"}`;
+    const missingFiles = db.query(`SELECT COUNT(*) count ${predicate}`).get(...scope)
+        ?.count ?? 0;
+    const missingPaths = db
+        .query(`SELECT i.filePath ${predicate} ORDER BY i.filePath LIMIT 10`)
+        .all(...scope)
+        .map((row) => row.filePath);
+    // Keyset pages bound memory and use the exact same strict parser as resolution.
+    // This is an indexed-payload validation scan, not a source-filesystem traversal.
+    const invalid = (table, column, fileColumn, parse) => {
+        let count = 0, last = 0;
+        for (;;) {
+            const rows = db
+                .query(`SELECT id,substr(${column},1,16385) raw FROM "${table}" WHERE id>? AND ${column} IS NOT NULL${filePath === undefined ? "" : ` AND ${fileColumn}=?`} ORDER BY id LIMIT 128`)
+                .all(last, ...scope);
+            const lastRow = rows.at(-1);
+            if (!lastRow)
+                return count;
+            for (const row of rows)
+                if (!parse(row.raw))
+                    count++;
+            last = lastRow.id;
+        }
+    };
+    const invalidPayloads = provenance
+        ? invalid("symbols", "apexDeclaration", "filePath", parseApexDeclaration) +
+            invalid("references", "apexCall", "callerFile", parseApexCall)
+        : 0;
+    return {
+        partial: missingFiles > 0 || invalidPayloads > 0,
+        missingFiles,
+        missingPaths,
+        invalidPayloads,
+        repair: "Run knodin index <Apex files missing receiver provenance> --force --skip-embeddings (or a scoped --under rebuild) to populate Apex receiver capability v1.",
+    };
+}

package/dist/src/engine/embedding-reuse.js

@@ -0,0 +1,57 @@
+import { createHash } from "node:crypto";
+import { EMBEDDING_DIMENSIONS } from "./embeddings.js";
+// ~12 MiB of vector payload, plus fixed-size keys/digests and SQLite overhead.
+// A disposable per-graph acceleration table, not another source of graph truth.
+export const EMBEDDING_REUSE_MAX_ENTRIES = 8192;
+// Bump whenever embeddingInputFor/source preparation changes, even if model stays pinned.
+export const EMBEDDING_INPUT_REPRESENTATION = "name-kind-summary-source:1000:v1";
+const VECTOR_BYTES = EMBEDDING_DIMENSIONS * Float32Array.BYTES_PER_ELEMENT;
+function digest(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+export function embeddingReuseKey(modelIdentity, input, representation = EMBEDDING_INPUT_REPRESENTATION) {
+    return digest(JSON.stringify([modelIdentity, representation, input]));
+}
+/** Exact-input cache independent of ephemeral symbol IDs. Stores no source text. */
+export class EmbeddingReuseCache {
+    db;
+    maxEntries;
+    constructor(db, maxEntries = EMBEDDING_REUSE_MAX_ENTRIES) {
+        this.db = db;
+        this.maxEntries = maxEntries;
+        if (!Number.isSafeInteger(maxEntries) ||
+            maxEntries < 1 ||
+            maxEntries > EMBEDDING_REUSE_MAX_ENTRIES)
+            throw new Error("Invalid embedding reuse cache bound");
+        db.run(`CREATE TABLE IF NOT EXISTS embedding_reuse_v1 (
+			cacheKey TEXT PRIMARY KEY CHECK(length(cacheKey) = 64),
+			vector BLOB NOT NULL CHECK(length(vector) = ${VECTOR_BYTES}),
+			digest TEXT NOT NULL CHECK(length(digest) = 64)
+		)`);
+        this.prune();
+    }
+    get(key) {
+        const row = this.db
+            .query("SELECT vector, digest FROM embedding_reuse_v1 WHERE cacheKey = ?")
+            .get(key);
+        if (!row)
+            return;
+        if (row.vector.byteLength === VECTOR_BYTES && digest(row.vector) === row.digest) {
+            const vector = new Float32Array(Uint8Array.from(row.vector).buffer);
+            if (vector.every(Number.isFinite))
+                return vector;
+        }
+        this.db.run("DELETE FROM embedding_reuse_v1 WHERE cacheKey = ?", [key]);
+    }
+    /** Call within the embedding batch transaction; reinsertion refreshes LRU order. */
+    put(key, vector) {
+        if (vector.length !== EMBEDDING_DIMENSIONS || !vector.every(Number.isFinite))
+            return;
+        const bytes = new Uint8Array(vector.buffer, vector.byteOffset, vector.byteLength);
+        this.db.run("INSERT OR REPLACE INTO embedding_reuse_v1(cacheKey, vector, digest) VALUES (?, ?, ?)", [key, bytes, digest(bytes)]);
+    }
+    /** Bound all generations together; stale model/input keys compete in the same LRU. */
+    prune() {
+        this.db.run("DELETE FROM embedding_reuse_v1 WHERE rowid IN (SELECT rowid FROM embedding_reuse_v1 ORDER BY rowid DESC LIMIT -1 OFFSET ?)", [this.maxEntries]);
+    }
+}

package/dist/src/engine/embeddings.js

@@ -9,6 +9,7 @@
  * and reads as a natural pro-tier feature precisely because enabling it is a
  * deliberate trade against this file's local/no-egress guarantee.
  */
+import { randomUUID } from "node:crypto";
 import os from "node:os";
 import path from "node:path";
 let embedderPromise = null;
@@ -20,6 +21,27 @@ export const EMBEDDING_MODEL_ID = "Xenova/all-MiniLM-L6-v2";
 export const EMBEDDING_MODEL_REVISION = "751bff37182d3f1213fa05d7196b954e230abad9";
 export const EMBEDDING_MODEL_DTYPE = "q8";
 const DEFAULT_MODEL_REMOTE_HOST = "https://huggingface.co/";
+const overrideCacheIdentities = new WeakMap();
+/** Pin reuse to the pipeline contract; test overrides never alias the real model. */
+export function getEmbeddingCacheIdentity() {
+    if (embedderOverride) {
+        let identity = overrideCacheIdentities.get(embedderOverride);
+        if (!identity) {
+            identity = `override:${randomUUID()}`;
+            overrideCacheIdentities.set(embedderOverride, identity);
+        }
+        return identity;
+    }
+    return JSON.stringify([
+        EMBEDDING_MODEL_ID,
+        EMBEDDING_MODEL_REVISION,
+        EMBEDDING_MODEL_DTYPE,
+        EMBEDDING_DIMENSIONS,
+        "mean",
+        "normalize:true",
+        getModelRemoteHost(),
+    ]);
+}
 /**
  * One machine-level model cache shared by every repository and every installed
  * knodin version. An explicit override makes managed/offline environments and