akm-cli 0.9.1 → 0.9.2-alpha.1

package/dist/execution/source.js

@@ -0,0 +1,320 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import { bundleRefToString, isBundleSlug, parseBundleRef } from "../core/asset/asset-ref.js";
+import { cloneExecutionJson, cloneExecutionJsonObject, } from "./json.js";
+import { assertSnapshotKeys, snapshotStrictRecord } from "./record.js";
+export const EXECUTION_SOURCE_SCHEMA_VERSION = 1;
+/** Current internal adapter identifiers are lowercase kebab-case registry keys. */
+export const EXECUTION_ADAPTER_ID_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const CONTROL_OR_LINE_SEPARATOR_PATTERN = /[\p{Cc}\p{Zl}\p{Zp}]/u;
+const FORMAT_CHARACTER_PATTERN = /\p{Cf}/u;
+const WINDOWS_DRIVE_PREFIX_PATTERN = /^[A-Za-z]:/;
+const RESERVED_EXTENSION_OWNERS = new Set(["__proto__", "constructor", "prototype", "tostring"]);
+const renderedSourceBrand = Symbol("akm.adapter-rendered-execution-source");
+const renderedSourceInstances = new WeakSet();
+function requireRecord(value, path) {
+    return snapshotStrictRecord(value, path);
+}
+function assertOnlyKeys(value, allowed, path) {
+    assertSnapshotKeys(value, allowed, path);
+}
+function validateExtensionOwner(owner) {
+    const normalized = owner.toLowerCase();
+    if (!EXECUTION_ADAPTER_ID_PATTERN.test(owner) || RESERVED_EXTENSION_OWNERS.has(normalized)) {
+        throw new TypeError(`extension owner must be a canonical, non-reserved adapter identifier: ${owner}`);
+    }
+}
+function frozenNullPrototypeMap(entries) {
+    const out = Object.create(null);
+    for (const [key, value] of entries) {
+        Object.defineProperty(out, key, { value, enumerable: true, configurable: false, writable: false });
+    }
+    return Object.freeze(out);
+}
+function cloneExtensionEntry(value, index) {
+    const path = `extension entry ${index}`;
+    const cloned = cloneExecutionJson(value, path);
+    if (!Array.isArray(cloned) || cloned.length !== 2) {
+        throw new TypeError(`${path} must be a two-element [owner, values] array`);
+    }
+    const [owner, values] = cloned;
+    if (typeof owner !== "string")
+        throw new TypeError(`${path} owner must be a string`);
+    if (values === null || Array.isArray(values) || typeof values !== "object") {
+        throw new TypeError(`${path} values must be a JSON object`);
+    }
+    return [owner, values];
+}
+export function createAdapterExtensions(first, second, ...rest) {
+    const rawEntries = typeof first === "string"
+        ? [[first, second]]
+        : [first, ...(second === undefined ? [] : [second]), ...rest];
+    const seen = new Set();
+    const cloned = [];
+    for (const [index, rawEntry] of rawEntries.entries()) {
+        const [owner, values] = cloneExtensionEntry(rawEntry, index);
+        validateExtensionOwner(owner);
+        if (seen.has(owner))
+            throw new TypeError(`duplicate extension owner: ${owner}`);
+        seen.add(owner);
+        cloned.push([owner, cloneExecutionJsonObject(values, `extensions.${owner}`)]);
+    }
+    return frozenNullPrototypeMap(cloned);
+}
+export function cloneAdapterExtensions(value, path) {
+    const record = requireRecord(value, path);
+    const entries = Object.entries(record).map(([owner, fields]) => [owner, cloneExecutionJsonObject(fields, `${path}.${owner}`)]);
+    const [first, ...rest] = entries;
+    return first ? createAdapterExtensions(first, ...rest) : frozenNullPrototypeMap([]);
+}
+function requireCanonicalString(value, path) {
+    if (typeof value !== "string" ||
+        value.length === 0 ||
+        !isWellFormedUnicode(value) ||
+        value.normalize("NFC") !== value) {
+        throw new TypeError(`${path} must be a non-empty NFC string`);
+    }
+    if (hasUnsafeIdentityCharacter(value)) {
+        throw new TypeError(`${path} must not contain Unicode control or dangerous format characters`);
+    }
+    return value;
+}
+/**
+ * Validate a selector/layer identifier that may cross the durable execution
+ * boundary. Keep this shared with the cascade planner so resume cannot admit a
+ * selector the live planner would reject.
+ */
+export function requireStableExecutionSelector(value, path) {
+    let selector;
+    try {
+        selector = requireCanonicalString(value, path);
+    }
+    catch (cause) {
+        throw new TypeError(`${path} must be a non-empty stable NFC identifier`, { cause });
+    }
+    if (selector.length > 512 || selector.trim() !== selector) {
+        throw new TypeError(`${path} must be a non-empty stable NFC identifier`);
+    }
+    return selector;
+}
+export function isPortableExecutionAgentSelector(value) {
+    return /^(?:[^/]+\/\/)?agents\/[^/]/.test(value);
+}
+export function executionPersonaMatchesSelector(selector, personaRef) {
+    return selector.includes("//") ? selector === personaRef : personaRef.endsWith(`//${selector}`);
+}
+function hasUnsafeIdentityCharacter(value) {
+    for (const character of value) {
+        if (CONTROL_OR_LINE_SEPARATOR_PATTERN.test(character))
+            return true;
+        // Join controls are meaningful in emoji and several writing systems. All
+        // other format controls are rejected because they can conceal identity.
+        if (FORMAT_CHARACTER_PATTERN.test(character) && character !== "\u200C" && character !== "\u200D")
+            return true;
+    }
+    return false;
+}
+function isWellFormedUnicode(value) {
+    for (let index = 0; index < value.length; index += 1) {
+        const code = value.charCodeAt(index);
+        if (code >= 0xd800 && code <= 0xdbff) {
+            const next = value.charCodeAt(index + 1);
+            if (!(next >= 0xdc00 && next <= 0xdfff))
+                return false;
+            index += 1;
+        }
+        else if (code >= 0xdc00 && code <= 0xdfff) {
+            return false;
+        }
+    }
+    return true;
+}
+function validateCanonicalIdentity(input, path) {
+    assertOnlyKeys(input, ["ref", "bundle", "adapter", "file", "hash"], path);
+    const ref = requireCanonicalString(input.ref, `${path}.ref`);
+    const bundle = requireCanonicalString(input.bundle, `${path}.bundle`);
+    const adapter = requireCanonicalString(input.adapter, `${path}.adapter`);
+    const file = requireCanonicalString(input.file, `${path}.file`);
+    const hash = requireCanonicalString(input.hash, `${path}.hash`);
+    let parsed;
+    try {
+        parsed = parseBundleRef(ref);
+    }
+    catch (cause) {
+        throw new TypeError(`${path}.ref is not a canonical bundle ref`, { cause });
+    }
+    if (parsed.bundle === undefined ||
+        parsed.bundle !== bundle ||
+        parsed.fragment !== undefined ||
+        !isBundleSlug(bundle) ||
+        bundleRefToString(parsed) !== ref) {
+        throw new TypeError(`${path}.ref must round-trip as the same fully-qualified bundle ref without a fragment`);
+    }
+    if (!EXECUTION_ADAPTER_ID_PATTERN.test(adapter)) {
+        throw new TypeError(`${path}.adapter must use the current lowercase kebab-case adapter identifier grammar`);
+    }
+    const segments = file.split("/");
+    if (file.startsWith("/") ||
+        WINDOWS_DRIVE_PREFIX_PATTERN.test(file) ||
+        file.includes("\\") ||
+        segments.some((segment) => !segment || segment === "." || segment === "..")) {
+        throw new TypeError(`${path}.file must be a normalized relative POSIX path`);
+    }
+    if (!/^[a-f0-9]{64}$/.test(hash))
+        throw new TypeError(`${path}.hash must be a SHA-256 hex digest`);
+    return { ref, bundle, adapter, file, hash };
+}
+/** Validate, clone, and freeze an identity produced by an adapter renderer. */
+export function createExecutionSourceIdentity(input) {
+    return Object.freeze(validateCanonicalIdentity(requireRecord(input, "execution source identity"), "execution source identity"));
+}
+/** Validate and freeze a source identity read back from a frozen request. */
+export function decodeExecutionSourceIdentity(value, path = "execution source identity") {
+    return Object.freeze(validateCanonicalIdentity(requireRecord(value, path), path));
+}
+export function cloneUnresolvedExecutionDefaults(input, path = "execution source defaults") {
+    const record = requireRecord(input, path);
+    assertOnlyKeys(record, [
+        "agent",
+        "engine",
+        "model",
+        "inference",
+        "outputSchema",
+        "tools",
+        "timeout",
+        "workspace",
+        "environment",
+        "runtime",
+    ], path);
+    const json = { ...cloneExecutionJsonObject(record, path) };
+    for (const key of ["agent", "engine", "model", "workspace"]) {
+        const value = json[key];
+        if (value !== undefined && value !== null && typeof value !== "string") {
+            throw new TypeError(`${path}.${key} must be a string or null`);
+        }
+    }
+    const timeout = json.timeout;
+    if (timeout !== undefined && timeout !== null && typeof timeout !== "string" && typeof timeout !== "number") {
+        throw new TypeError(`${path}.timeout must be a string, number, or null`);
+    }
+    for (const key of ["inference", "outputSchema", "runtime"]) {
+        const value = json[key];
+        if (value !== undefined && value !== null && (Array.isArray(value) || typeof value !== "object")) {
+            throw new TypeError(`${path}.${key} must be an object or null`);
+        }
+    }
+    const environment = json.environment;
+    if (environment !== undefined && environment !== null) {
+        if (Array.isArray(environment) || typeof environment !== "object") {
+            throw new TypeError(`${path}.environment must be an object or null`);
+        }
+        if (Object.values(environment).some((value) => typeof value !== "string")) {
+            throw new TypeError(`${path}.environment values must be strings`);
+        }
+    }
+    if (Object.hasOwn(json, "tools"))
+        json.tools = cloneToolSelection(json.tools, `${path}.tools`);
+    return Object.freeze(json);
+}
+export function cloneToolSelection(value, path = "tools") {
+    if (value === null || typeof value === "string")
+        return value;
+    const cloned = cloneExecutionJson(value, path);
+    if (Array.isArray(cloned)) {
+        if (cloned.some((tool) => typeof tool !== "string"))
+            throw new TypeError(`${path} array values must be strings`);
+        return cloned;
+    }
+    return cloneExecutionJsonObject(cloned, path);
+}
+export function createAdapterRenderedExecutionSource(input) {
+    const record = requireRecord(input, "adapter-rendered execution source");
+    assertOnlyKeys(record, ["kind", "content", "identity", "defaults", "extensions"], "adapter-rendered execution source");
+    const kind = record.kind;
+    const content = record.content;
+    if (kind !== "command" && kind !== "persona")
+        throw new TypeError("execution source kind is invalid");
+    if (typeof content !== "string")
+        throw new TypeError("execution source content must be a string");
+    const defaults = Object.hasOwn(record, "defaults") ? record.defaults : {};
+    if (defaults === undefined) {
+        throw new TypeError("execution source defaults must be omitted or be an object");
+    }
+    const source = {
+        schemaVersion: EXECUTION_SOURCE_SCHEMA_VERSION,
+        kind,
+        content,
+        defaults: cloneUnresolvedExecutionDefaults(defaults),
+        identity: createExecutionSourceIdentity(record.identity),
+    };
+    if (Object.hasOwn(record, "extensions")) {
+        source.extensions = cloneAdapterExtensions(record.extensions, "execution source extensions");
+    }
+    Object.defineProperty(source, renderedSourceBrand, { value: true, enumerable: false });
+    const frozen = Object.freeze(source);
+    renderedSourceInstances.add(frozen);
+    return frozen;
+}
+function isAdapterRenderedSource(value, kind) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    if (!renderedSourceInstances.has(value))
+        return false;
+    if (Object.getPrototypeOf(value) !== Object.prototype || !Object.isFrozen(value))
+        return false;
+    if (!Object.hasOwn(value, renderedSourceBrand))
+        return false;
+    const required = new Set(["schemaVersion", "kind", "content", "defaults", "identity"]);
+    const optional = new Set(["extensions"]);
+    for (const key of Reflect.ownKeys(value)) {
+        if (key === renderedSourceBrand)
+            continue;
+        if (typeof key !== "string" || (!required.delete(key) && !optional.has(key)))
+            return false;
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (!descriptor || !("value" in descriptor) || !descriptor.enumerable)
+            return false;
+    }
+    if (required.size > 0)
+        return false;
+    const brand = Object.getOwnPropertyDescriptor(value, renderedSourceBrand);
+    const source = value;
+    if (brand?.value !== true ||
+        brand.enumerable !== false ||
+        brand.configurable !== false ||
+        brand.writable !== false ||
+        source.schemaVersion !== EXECUTION_SOURCE_SCHEMA_VERSION ||
+        source.kind !== kind ||
+        typeof source.content !== "string" ||
+        typeof source.defaults !== "object" ||
+        source.defaults === null ||
+        !Object.isFrozen(source.defaults) ||
+        typeof source.identity !== "object" ||
+        source.identity === null ||
+        Object.getPrototypeOf(source.identity) !== Object.prototype ||
+        !Object.isFrozen(source.identity)) {
+        return false;
+    }
+    if (Object.hasOwn(source, "extensions")) {
+        if (typeof source.extensions !== "object" ||
+            source.extensions === null ||
+            Object.getPrototypeOf(source.extensions) !== null ||
+            !Object.isFrozen(source.extensions)) {
+            return false;
+        }
+    }
+    try {
+        decodeExecutionSourceIdentity(source.identity);
+    }
+    catch {
+        return false;
+    }
+    return true;
+}
+export function isAdapterRenderedCommandSource(value) {
+    return isAdapterRenderedSource(value, "command");
+}
+export function isAdapterRenderedPersonaSource(value) {
+    return isAdapterRenderedSource(value, "persona");
+}

package/dist/indexer/bundle-identity-guard.js

@@ -31,7 +31,7 @@ import fs from "node:fs";
 import { loadConfig } from "../core/config/config.js";
 import { getDbPath } from "../core/paths.js";
 import { warn } from "../core/warn.js";
-import { openDatabase } from "../storage/database.js";
+import { closeDatabase, openReadonlyExistingDatabase } from "../storage/repositories/index-connection.js";
 let guardSettled = false;
 /** TEST-ONLY: re-arm the once-per-process guard between cases. */
 export function resetBundleIdentityGuardForTests() {
@@ -43,8 +43,8 @@ function indexBundlePrefixes(dbPath) {
         return undefined;
     let db;
     try {
-        db = openDatabase(dbPath, { readonly: true });
-        if (!db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='entries'").get())
+        db = openReadonlyExistingDatabase(dbPath);
+        if (!db)
             return undefined;
         return db
             .prepare("SELECT DISTINCT bundle_id AS b FROM entries WHERE bundle_id IS NOT NULL AND bundle_id != ''")
@@ -54,7 +54,8 @@ function indexBundlePrefixes(dbPath) {
         return undefined;
     }
     finally {
-        db?.close();
+        if (db)
+            closeDatabase(db);
     }
 }
 /**

package/dist/indexer/db/graph-db.js

@@ -219,6 +219,39 @@ export function drainExtractionQueue(db, stashRoot, limit) {
         return [];
     }
 }
+/** Read queued graph work without claiming or deleting it. */
+export function peekExtractionQueue(db, stashRoot, limit) {
+    try {
+        const rows = db
+            .prepare(`SELECT file_path, body_hash, priority
+           FROM graph_extraction_queue
+           WHERE stash_root = ?
+           ORDER BY priority DESC, queued_at ASC
+           LIMIT ?`)
+            .all(stashRoot, limit);
+        return rows.map((row) => ({ filePath: row.file_path, bodyHash: row.body_hash, priority: row.priority }));
+    }
+    catch (err) {
+        rethrowIfTestIsolationError(err);
+        return [];
+    }
+}
+/**
+ * Acknowledge the exact queued revision that was classified and handled.
+ * A concurrent re-enqueue with a new body hash therefore survives.
+ */
+export function acknowledgeExtractionQueueEntry(db, stashRoot, filePath, bodyHash) {
+    try {
+        const result = db
+            .prepare("DELETE FROM graph_extraction_queue WHERE stash_root = ? AND file_path = ? AND body_hash = ?")
+            .run(stashRoot, filePath, bodyHash);
+        return result.changes > 0;
+    }
+    catch (err) {
+        rethrowIfTestIsolationError(err);
+        return false;
+    }
+}
 /**
  * Scoped loader — graph_files rows without entities/relations. Used for
  * orphan detection and entity overview commands.

package/dist/indexer/graph/graph-boost.js

@@ -250,7 +250,7 @@ export function collectGraphRelatedHit(context, filePath) {
  * idx_graph_files_path guarantees one graph_files row per path).
  *
  * The returned `ref` field carries the canonical indexed `concept_id`, never a
- * value re-derived from presentation fields or `entry_key`. It is undefined
+ * value re-derived from presentation fields. It is undefined
  * when the graph row has no matching entry with current indexed provenance.
  */
 export function listRelatedPathsForFile(stashRoot, filePath, limit = 5, db) {
@@ -348,9 +348,8 @@ export function listRelatedPathsForFile(stashRoot, filePath, limit = 5, db) {
     try {
         const entryRows = db
             .prepare(`SELECT file_path, concept_id FROM entries
-          WHERE file_path IN (${placeholders}) AND stash_dir = ?
-            AND item_ref IS NOT NULL AND concept_id IS NOT NULL`)
-            .all(...candidatePaths, stashRoot);
+          WHERE file_path IN (${placeholders})`)
+            .all(...candidatePaths);
         for (const row of entryRows) {
             refByPath.set(row.file_path, row.concept_id);
         }