akm-cli 0.9.16-alpha.1 → 0.9.16-alpha.2

package/dist/commands/tasks/validate.js

@@ -9,23 +9,18 @@
  * a bundle/adapter/concept id at all — it reads exactly the path it was
  * given and classifies it.
  *
- * Reuses the exact version-routing shim `parseTaskSource`
- * (`src/tasks/source/parse-task-source.ts`) already applies for every other
- * task-source reader (`akm task sync`'s `compileTaskSources` included) —
- * this module never forks a second parser or a second v2/v3 migration
- * planner. `readBoundedTaskSourceYaml` / `peekTaskSourceVersion` / `own` are
- * the SAME front-end helpers that shim itself calls first; they are used
- * here only to recover the file's ORIGINALLY DECLARED schema version for
- * the report, because `parseTaskSource`'s own `ParsedTaskSource.version` is
- * always `4` post-shim — it cannot answer "was this a v2/v3/v4 file?" on
- * its own once a v2/v3 source has been converted in memory.
+ * Reuses the exact current-schema router `parseTaskSource`
+ * (`src/tasks/source/parse-task-source.ts`) used by every other task-source
+ * reader. Historical v2/v3 documents are deliberately rejected here and
+ * point to `akm migrate apply`; validation does not embed a second legacy
+ * parser or perform an in-memory migration.
  *
  * Beyond parsing, this module also runs the SAME two per-source gates
  * `akm task sync`'s `compileTaskSources` runs before it ever installs a
  * schedule — `assertTaskScheduleInputsSatisfyContract` and
  * `assertTaskScheduleCronValid` (both extracted from `scheduler-sync.ts` for
  * exactly this reuse) — so a file `sync` would reject can never
- * be reported `valid`/`converts` here. Cron dialect is checked against
+ * be reported `valid` here. Cron dialect is checked against
  * `backendNameForPlatform()`, the same platform default `sync` falls back
  * to whenever it has no injected/native-inspected backend to hand (see
  * `akmTasksAdd`, `src/commands/tasks/tasks.ts`); a bare file was never
@@ -48,19 +43,12 @@
  * table in its header, extended for the two gates above):
  *   - `valid`       — parses as task source v4 directly (declared `version: 4`)
  *                      and passes both sync gates.
- *   - `converts`    — declared `version: 2` or `3`; the deterministic
- *                      in-memory migrator produced a valid v4 document that
- *                      passes both sync gates.
- *   - `blocked`     — declared `version: 2` or `3`; the migrator itself
- *                      could not convert it (an ambiguous/unmigratable
- *                      shape) — the ONLY way `parseTaskSource` ever throws
- *                      for those two version numbers, so no message-text
- *                      sniffing is needed to tell this apart from `invalid`.
+ *   - `blocked`     — declared `version: 2` or `3`; runtime does not accept
+ *                      it and the explicit migrator must rewrite it first.
  *   - `invalid`     — the document declares SOME version (`4`, or anything
  *                      other than 2/3/4) but fails to parse/validate, OR it
- *                      parsed (directly or via a SUCCESSFUL v2/v3
- *                      conversion) but fails one of the two sync gates
- *                      above, OR the YAML itself does not parse at all
+ *                      parsed but fails one of the two sync gates above, OR
+ *                      the YAML itself does not parse at all
  *                      (a genuine syntax error, not merely a non-task
  *                      shape) — reported with the parser's own reason.
  *   - `not-a-task`  — the document parses as YAML but never declares a
@@ -138,11 +126,14 @@ export async function akmTaskValidate(filePath) {
         if (!(cause instanceof UsageError))
             throw cause;
         const reason = cause.message;
-        // `parseTaskSource` only ever throws for a declared version 2/3 via the
-        // unmigratable-conversion branch (see this file's header) — no separate
-        // message check needed to recognize "blocked" here.
         if (declaredVersion === 2 || declaredVersion === 3) {
-            return { ok: false, path: resolvedPath, sourceVersion: declaredVersion, outcome: "blocked", reason };
+            return {
+                ok: false,
+                path: resolvedPath,
+                sourceVersion: declaredVersion,
+                outcome: "blocked",
+                reason: `${reason} Run \`akm migrate apply --dry-run\`, review the plan, then run \`akm migrate apply\`.`,
+            };
         }
         if (peekFailed) {
             return { ok: false, path: resolvedPath, outcome: "invalid", reason };
@@ -161,11 +152,8 @@ export async function akmTaskValidate(filePath) {
     // Success is unreachable from any path that leaves `declaredVersion`
     // undefined — the router requires a numeric 2/3/4 version to reach here.
     const sourceVersion = declaredVersion ?? 4;
-    // The document itself parsed (directly, or via a successful v2/v3
-    // conversion) — now the two gates `compileTaskSources` runs before
-    // accepting it. A violation here is `invalid`, never `blocked`: the
-    // migrator already succeeded, so this is the same kind of defect a
-    // native v4 document with the identical schedule would have.
+    // The current document parsed; now run the two gates `compileTaskSources`
+    // applies before accepting it.
     try {
         assertTaskScheduleInputsSatisfyContract(parsed.v4, resolvedPath);
         assertTaskScheduleCronValid(parsed.v4, backend);
@@ -180,7 +168,7 @@ export async function akmTaskValidate(filePath) {
         ok: true,
         path: resolvedPath,
         sourceVersion,
-        outcome: sourceVersion === 2 || sourceVersion === 3 ? "converts" : "valid",
+        outcome: "valid",
         resolved: buildResolved(id, parsed.v4),
     };
 }

package/dist/core/activation-policy.js

@@ -22,7 +22,7 @@ const INTERACTIVE_TOOL_ENV_KEYS = new Set(["EDITOR", "VISUAL", "PAGER"]);
  * genuine RCE-class key; first-party stashes warn. The interactive-tool
  * group (see {@link INTERACTIVE_TOOL_ENV_KEYS}) only ever warns, since akm's
  * own env-injection path never invokes those keys as a command. An explicit
- * `--allow-insecure` (threaded through by the caller, same override
+ * `--allow-dangerous-env-keys` (threaded through by the caller, same override
  * `decideDangerousKeyInstall`'s `"warn-allow"` already honors for rule 2)
  * downgrades a remaining block to a warning too — the operator is not racing
  * themselves. See rule 1 above.
@@ -31,7 +31,7 @@ const INTERACTIVE_TOOL_ENV_KEYS = new Set(["EDITOR", "VISUAL", "PAGER"]);
  *   (already filtered by the caller via `isDangerousEnvKey`).
  * @param thirdParty `true` when the env's source is a third-party stash — i.e.
  *   its origin carries a `registryId`.
- * @param allowInsecure `true` when the operator passed `--allow-insecure` (or
+ * @param allowDangerousEnvKeys `true` when the operator passed `--allow-dangerous-env-keys` (or
  *   its equivalent) for this injection. Defaults to `false`.
  */
 export function decideDangerousEnvInjection(input) {
@@ -39,7 +39,7 @@ export function decideDangerousEnvInjection(input) {
         return "allow";
     if (!input.thirdParty)
         return "warn";
-    if (input.allowInsecure)
+    if (input.allowDangerousEnvKeys)
         return "warn";
     const onlyInteractiveTool = input.dangerousKeys.every((key) => INTERACTIVE_TOOL_ENV_KEYS.has(key));
     return onlyInteractiveTool ? "warn" : "block";
@@ -53,7 +53,7 @@ export function decideDangerousEnvInjection(input) {
 export function decideDangerousKeyInstall(input) {
     if (!input.findingsPresent)
         return "allow";
-    return input.allowInsecure ? "warn-allow" : "gate";
+    return input.allowDangerousEnvKeys ? "warn-allow" : "gate";
 }
 // ── Rule 3: write activation (search-source.ts, installations.ts) ────────────
 /**

package/dist/core/adapter/adapters/akm-adapter.js

@@ -82,7 +82,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { applyPostContributorFields, applyPreContributorFields, extractPackageMetadata, getMarkdownFragmentContent, hasMarkdownFragmentContent, setMarkdownFragmentContent, } from "../../../indexer/passes/metadata.js";
-import { assetPathCandidatesAreOrderedByPreference, assetPathCandidatesForName, assetPathForName, deriveCanonicalAssetNameFromStashRoot, placementTypes, stashDirFor, stashDirNames, } from "../../asset/asset-placement.js";
+import { assetPathCandidatesForName, assetPathForName, deriveCanonicalAssetNameFromStashRoot, placementTypes, stashDirFor, stashDirNames, } from "../../asset/asset-placement.js";
 import { parseFrontmatter } from "../../asset/frontmatter.js";
 import { executionDefaultsFromFrontmatter, renderMarkdownExecutionSource } from "../execution-source.js";
 import { recognizeMatch } from "../recognize-match.js";
@@ -130,6 +130,11 @@ function akmStashAbstains(root, absPath) {
     const segments = relPath.split(/[\\/]+/).filter(Boolean);
     if (segments.length === 0)
         return false;
+    // A bundle's root README describes the bundle itself; it is not an AKM
+    // knowledge asset. Nested README files remain adapter-owned documentation
+    // and are handled by the normal typed-directory matcher policy.
+    if (segments.length === 1 && segments[0]?.toLowerCase() === "readme.md")
+        return true;
     // Skip env `.env` files that have a sibling `.sensitive` marker file.
     if (segments[0] === "env" && (absPath.endsWith(".env") || path.basename(absPath) === ".env")) {
         if (fs.existsSync(absPath.replace(/\.env$/, ".sensitive")))
@@ -489,25 +494,7 @@ export const akmAdapter = {
      * type's own stash subdir) and the LOOSE FALLBACK (authored anywhere else
      * in the bundle, so the canonical name is the file's full path relative to
      * the bundle root instead of the stash subdir). `assetPathCandidatesForName`
-     * additionally expands `env`'s `.env`/`<name>.env` duality, and memory's
-     * `<name>`/`<name>.derived` twin duality, on each.
-     *
-     * `priority` (#882 fix) carries each candidate's rank WITHIN its own root's
-     * list, but ONLY for a type whose duality is a declared, ORDERED
-     * preference per `assetPathCandidatesAreOrderedByPreference` (only
-     * `memory`, today) — `assetPathCandidatesForName` returns primary before
-     * derived-twin for that type, so index 0 is the declared winner when both
-     * exist. CANONICAL and LOOSE are separate lists whose ranks both start
-     * back at 0: two candidates that tie on rank (e.g. the canonical and loose
-     * spellings both being the primary, rank-0, form) are a genuine collision
-     * between two independently-authored files, not a declared preference —
-     * only a rank difference WITHIN one root's own list resolves silently.
-     * Every other type's candidates (including `env`'s `.env`/`default.env`
-     * pair — co-equal spellings, not an ordered preference, per that same
-     * predicate's doc comment) carry NO `priority`, unchanged from before
-     * #882: `resolveAdapterConceptOwner` treats priority-less candidates as
-     * tied, so more than one existing together still collides. See
-     * `AdapterReadCandidate.priority`'s doc comment.
+     * additionally expands `env`'s `.env`/`<name>.env` duality on each.
      */
     readCandidates(c, conceptId) {
         const posix = conceptId.replace(/\\/g, "/");
@@ -521,23 +508,9 @@ export const akmAdapter = {
             return [];
         const canonical = assetPathCandidatesForName(type, path.join(c.root, head), rest);
         const loose = assetPathCandidatesForName(type, c.root, rest);
-        if (!assetPathCandidatesAreOrderedByPreference(type)) {
-            return [...new Set([...canonical, ...loose])].map((candidatePath) => ({
-                path: candidatePath,
-                conceptId: posix,
-            }));
-        }
-        const priorityByPath = new Map();
-        for (const list of [canonical, loose]) {
-            list.forEach((candidatePath, rank) => {
-                if (!priorityByPath.has(candidatePath))
-                    priorityByPath.set(candidatePath, rank);
-            });
-        }
-        return [...priorityByPath.keys()].map((candidatePath) => ({
+        return [...new Set([...canonical, ...loose])].map((candidatePath) => ({
             path: candidatePath,
             conceptId: posix,
-            priority: priorityByPath.get(candidatePath),
         }));
     },
     /**

package/dist/core/adapter/adapters/akm-metadata.js

@@ -172,17 +172,7 @@ export function foldRecognizedMetadata(rendererName, file) {
                 const fm = parseFrontmatter(file.content()).data;
                 applyFrontmatterDescriptionAndTags(fm, out);
                 const hints = new Set();
-                // fix-ranking-derived-outranks-primary: `source:` on an ordinary
-                // memory is an author-written citation worth indexing as a hint, but
-                // on an inferred (`.derived`) twin it is ALWAYS the machine-written
-                // provenance backref `memory-inference.ts` writes (`memories/<parent>`
-                // — see its `FM_SOURCE`), already captured properly as
-                // `entry.derivedFrom` (metadata.ts). Folding that backref into
-                // searchHints too means the base memory's own name — almost always a
-                // query token whenever the base is relevant — auto-credits the twin
-                // via `search-hint-ranking`'s substring match, independent of whether
-                // the twin's own content actually matches the query.
-                const source = fm.inferred === true ? undefined : nonEmptyString(fm.source);
+                const source = nonEmptyString(fm.source);
                 if (source)
                     hints.add(source);
                 const fmObservedAt = nonEmptyString(fm.observed_at);

package/dist/core/adapter/execution-source.js

@@ -127,15 +127,6 @@ function nullableString(value, path) {
 function nullableObject(value, path) {
     return value === null ? null : cloneExecutionJsonObject(value, path);
 }
-function nullableEnvironment(value, path) {
-    if (value === null)
-        return null;
-    const environment = cloneExecutionJsonObject(value, path);
-    if (Object.values(environment).some((entry) => typeof entry !== "string")) {
-        throw new TypeError(`${path} values must be strings`);
-    }
-    return environment;
-}
 function nullableTimeout(value, path) {
     const timeout = cloneExecutionJson(value, path);
     if (timeout !== null && typeof timeout !== "string" && typeof timeout !== "number") {
@@ -167,6 +158,16 @@ export function executionDefaultsFromFrontmatter(data, options) {
     const namespace = own(frontmatter, "akm")
         ? requireMetadataMapping(frontmatter.akm, "frontmatter.akm")
         : snapshotStrictRecord({}, "frontmatter.akm");
+    for (const key of ["workspace", "environment", "runtime"]) {
+        const location = own(frontmatter, key)
+            ? `frontmatter.${key}`
+            : own(namespace, key)
+                ? `frontmatter.akm.${key}`
+                : undefined;
+        if (location) {
+            throw new TypeError(`${location} is host-controlled and cannot be declared by an executable asset; configure the selected engine or workflow execution environment instead`);
+        }
+    }
     const out = Object.create(null);
     if (kind === "command" && own(frontmatter, "agent")) {
         out.agent = nullableString(frontmatter.agent, "frontmatter.agent");
@@ -269,26 +270,6 @@ export function executionDefaultsFromFrontmatter(data, options) {
             ? topLevelTimeouts.get(selectedTimeoutKey)
             : namespacedTimeouts.get(selectedTimeoutKey);
     }
-    for (const key of ["workspace", "environment", "runtime"]) {
-        const namespaced = own(namespace, key)
-            ? key === "workspace"
-                ? nullableString(namespace[key], `frontmatter.akm.${key}`)
-                : key === "environment"
-                    ? nullableEnvironment(namespace[key], `frontmatter.akm.${key}`)
-                    : nullableObject(namespace[key], `frontmatter.akm.${key}`)
-            : undefined;
-        const topLevel = allowTopLevelEngine && own(frontmatter, key)
-            ? key === "workspace"
-                ? nullableString(frontmatter[key], `frontmatter.${key}`)
-                : key === "environment"
-                    ? nullableEnvironment(frontmatter[key], `frontmatter.${key}`)
-                    : nullableObject(frontmatter[key], `frontmatter.${key}`)
-            : undefined;
-        if (topLevel !== undefined)
-            out[key] = topLevel;
-        else if (namespaced !== undefined)
-            out[key] = namespaced;
-    }
     return out;
 }
 function snapshotRendererInput(input) {

package/dist/core/asset/asset-placement.js

@@ -269,38 +269,3 @@ export function assetPathCandidatesForName(assetType, typeRoot, name) {
     const namedForm = path.join(typeRoot, base, "default.env");
     return [...new Set([primary, dotForm, namedForm])];
 }
-/**
- * Whether {@link assetPathCandidatesForName}'s returned list for `assetType`
- * is an ORDERED preference — earlier candidates are a declared winner over
- * later ones, so a physical-owner resolver may pick the earliest that exists
- * with no throw when more than one does — or a set of CO-EQUAL spellings,
- * where more than one existing together is a genuine authoring collision to
- * report, not a preference to resolve silently. #882's fix (the memory
- * `.derived`-twin bug) needs this distinction: attaching a declared rank to
- * every multi-candidate type's list turned `env`'s co-equal collision into a
- * silently-resolved false negative (#882 follow-up) — the two dualities this
- * module documents are NOT the same kind of thing.
- *
- * Only `memory` is ordered. Its own doc comment above states a winner in so
- * many words: "The plain `.md` file wins when both exist, so it stays
- * `primary`" — `.derived` is a provenance marker on the SAME identity, not a
- * second, independently-authored file.
- *
- * `env`'s `.env`/`default.env` duality is explicitly NOT ordered — the doc
- * comment above says only that both spellings "derive the same canonical
- * name" and a lookup "must consider both", never that one wins over the
- * other. They are two independently authored files that happen to collide
- * on one ref; both existing together is exactly the ambiguity
- * `AdapterConceptCollisionError` exists to report.
- *
- * Callers that attach a preference rank to distinguish a declared duality
- * from a genuine collision (`AdapterReadCandidate.priority`,
- * `resolveAdapterConceptOwner` in `indexer/lookup/adapter-concept-owner.ts`)
- * must consult this predicate per asset type rather than assuming every
- * multi-candidate type behaves like `memory` — and must NOT special-case the
- * literal `.derived` suffix or `assetType === "memory"` themselves; this is
- * the one place that knowledge lives.
- */
-export function assetPathCandidatesAreOrderedByPreference(assetType) {
-    return assetType === "memory";
-}

package/dist/core/config/config-schema.js

@@ -29,28 +29,29 @@
  *   typo in an optional section.
  * - Unsupported top-level source shapes and provider kinds are hard-rejected;
  *   silently dropping them would mask user data loss.
- * - UNKNOWN-KEY POLICY: object schemas use passthrough (unknown keys are
- *   preserved and ignored, NOT rejected). akm runs across multiple installed
- *   versions sharing one config.json; a newer version writes keys an older
- *   version's schema doesn't know yet, so hard-rejecting unknown keys turned
- *   benign version skew into `INVALID_CONFIG_FILE` failures. Known keys are
- *   still type-checked; passthrough preserves unknown keys across a
- *   load→save round trip so an older reader never strips a newer writer's
- *   settings. (Replaced the prior strict-mode object walls.)
+ * - UNKNOWN-KEY POLICY: portable descriptive sections generally use
+ *   passthrough so version skew round-trips newer settings. Small finite
+ *   authority/toggle sections (`scheduler`, `execution`, `experimental`, and
+ *   reranker policy) are strict: a misspelling there must not silently turn a
+ *   safety decision off. The top level remains passthrough and warns on
+ *   unknown keys.
  * - `defaultWriteTarget` resolution and similar cross-field invariants are
  *   enforced at save time via `superRefine` on the top-level schema.
  */
 import { z } from "zod";
+import { bundleRefToString, parseBundleRef } from "../asset/asset-ref.js";
 import { warnOnce } from "../warn.js";
 import { BUILTIN_IMPROVE_STRATEGY_NAMES, IMPROVE_PROCESS_ENGINE_CAPABILITIES } from "./engine-semantics.js";
 import { EmbeddingConnectionConfigSchema } from "./schema/embedding.js";
 import { EnginesSchema } from "./schema/engines.js";
+import { ExecutionPolicyConfigSchema } from "./schema/execution.js";
 import { ExperimentalConfigSchema } from "./schema/experimental.js";
 import { FeedbackConfigSchema } from "./schema/feedback.js";
 import { ImproveConfigSchema } from "./schema/improve.js";
 import { IndexConfigSchema } from "./schema/index-config.js";
 import { OutputConfigSchema } from "./schema/output.js";
 import { CURRENT_CONFIG_VERSION, engineName, nonEmptyString, nonNegativeNumber } from "./schema/primitives.js";
+import { SchedulerConfigSchema } from "./schema/scheduler.js";
 import { SearchConfigSchema } from "./schema/search.js";
 import { SetupConfigSchema } from "./schema/setup.js";
 import { BundlesConfigSchema, RegistryConfigEntrySchema } from "./schema/sources-bundles.js";
@@ -65,6 +66,7 @@ export { ConsolidateProcessConfigSchema, DistillProcessConfigSchema, ExtractProc
 export { IndexConfigSchema, IndexPassConfigSchema } from "./schema/index-config.js";
 export { OutputConfigSchema } from "./schema/output.js";
 export { CURRENT_CONFIG_VERSION, LlmInvocationOverridesSchema } from "./schema/primitives.js";
+export { SchedulerActivationSchema, SchedulerConfigSchema } from "./schema/scheduler.js";
 export { SearchConfigSchema } from "./schema/search.js";
 export { SetupConfigSchema } from "./schema/setup.js";
 export { BundleConfigEntrySchema, BundlesConfigSchema, RegistryConfigEntrySchema, SourceConfigEntrySchema, } from "./schema/sources-bundles.js";
@@ -107,6 +109,8 @@ export const AkmConfigShape = {
     defaults: DefaultsSchema.optional(),
     semanticSearchMode: z.enum(["off", "auto"]).default("off"),
     embedding: EmbeddingConnectionConfigSchema.optional(),
+    // Host-local execution authority. Inherited layers are stripped.
+    execution: ExecutionPolicyConfigSchema.optional(),
     index: IndexConfigSchema.optional(),
     registries: z.array(RegistryConfigEntrySchema).optional(),
     // `bundles` + `defaultBundle` are the only source configuration shape. The
@@ -122,6 +126,9 @@ export const AkmConfigShape = {
     archiveRetentionDays: nonNegativeNumber.optional(),
     improve: ImproveConfigSchema.optional(),
     workflow: WorkflowConfigSchema.optional(),
+    // Host-local scheduler grants. Inherited layers are stripped by
+    // `resolveExtendsChain`; bundle-provided config never activates code.
+    scheduler: SchedulerConfigSchema.optional(),
     setup: SetupConfigSchema.optional(),
     // D8 — explicit opt-ins for behaviour outside the stability contract. Every
     // key defaults to OFF; see `src/core/config/experimental.ts` for the readers.
@@ -168,6 +175,55 @@ export const AkmConfigSchema = AkmConfigBaseSchema.superRefine((config, ctx) =>
                 message: `defaultBundle "${config.defaultBundle}" does not name a configured bundle`,
             });
         }
+        else if (config.bundles[config.defaultBundle]?.enabled === false) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["defaultBundle"],
+                message: `defaultBundle "${config.defaultBundle}" is disabled`,
+            });
+        }
+    }
+    if (config.defaultWriteTarget !== undefined) {
+        const target = config.bundles?.[config.defaultWriteTarget];
+        if (!target) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["defaultWriteTarget"],
+                message: `defaultWriteTarget "${config.defaultWriteTarget}" does not name a configured bundle`,
+            });
+        }
+        else if (target.enabled === false) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["defaultWriteTarget"],
+                message: `defaultWriteTarget "${config.defaultWriteTarget}" is disabled`,
+            });
+        }
+    }
+    const activationKeys = new Set();
+    for (const [index, activation] of (config.scheduler?.enabled ?? []).entries()) {
+        try {
+            const parsed = parseBundleRef(activation.ref);
+            if (!parsed.bundle || parsed.fragment !== undefined || bundleRefToString(parsed) !== activation.ref) {
+                throw new Error("not canonical");
+            }
+            const key = `${activation.kind}\0${activation.ref}`;
+            if (activationKeys.has(key)) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: ["scheduler", "enabled", index],
+                    message: "duplicates an earlier scheduler activation",
+                });
+            }
+            activationKeys.add(key);
+        }
+        catch {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["scheduler", "enabled", index, "ref"],
+                message: "must be one canonical fully-qualified ref without a fragment",
+            });
+        }
     }
     for (const key of ["llm", "agent", "improve"]) {
         if (config.defaults && key in config.defaults) {

package/dist/core/config/config-sources.js

@@ -6,6 +6,7 @@
  * values from the current bundle map in an {@link AkmConfig}.
  */
 import { createHash } from "node:crypto";
+import fs from "node:fs";
 import path from "node:path";
 import { ConfigError } from "../errors.js";
 /** The current one-component-per-bundle configuration entry, if present. */
@@ -33,6 +34,87 @@ export function bundleComponentConfig(bundle) {
 export function bundleContentRoot(entryPath, componentRoot) {
     return path.resolve(entryPath, componentRoot ?? ".");
 }
+/**
+ * Physical identity for an already materialized filesystem bundle.
+ *
+ * Configuration may spell the same directory through relative paths or
+ * symbolic links. Those spellings are not distinct sources: treating them as
+ * distinct would make ownership, default-source trust, and scheduler grants
+ * depend on syntax instead of the directory the OS will actually read.
+ */
+export function bundlePhysicalContentRoot(entryPath, componentRoot) {
+    const resolved = bundleContentRoot(entryPath, componentRoot);
+    try {
+        return fs.realpathSync.native(resolved);
+    }
+    catch (cause) {
+        // Cache-backed sources can be configured before they are materialized.
+        // Their source descriptor remains the identity until a real path exists.
+        if (cause.code === "ENOENT")
+            return resolved;
+        throw new ConfigError(`Unable to resolve physical bundle root ${JSON.stringify(resolved)}: ${cause instanceof Error ? cause.message : String(cause)}`, "INVALID_CONFIG_FILE");
+    }
+}
+/** Whether a configured bundle participates in reads, writes, and execution. */
+export function isBundleEnabled(config, bundleId) {
+    const bundle = config.bundles?.[bundleId];
+    return bundle !== undefined && bundle.enabled !== false;
+}
+/**
+ * Stable identity of the origin currently installed under a bundle id.
+ *
+ * This deliberately excludes mutable policy (`enabled`, `writable`,
+ * credentials, adapter selection) and bundle contents. Ordinary updates and
+ * adapter auto-detection for the same origin keep their grant; changing the
+ * locator or component root does not.
+ */
+export function bundleSourceId(config, bundleId) {
+    const bundle = config.bundles?.[bundleId];
+    if (!bundle) {
+        throw new ConfigError(`Bundle ${JSON.stringify(bundleId)} is not configured.`, "INVALID_CONFIG_FILE");
+    }
+    const component = bundleComponentConfig(bundle);
+    let source;
+    if (bundle.path !== undefined) {
+        source = { kind: "filesystem", locator: bundlePhysicalContentRoot(bundle.path, component?.root) };
+    }
+    else if (bundle.git !== undefined) {
+        source = { kind: "git", locator: normalizeInstalledGitRef("git", bundle.git) };
+    }
+    else if (bundle.website !== undefined) {
+        // Crawl/refresh settings are mutable fetch policy, not source identity.
+        // Changing them must not silently revoke a user's scheduling decision for
+        // the same website origin.
+        source = { kind: "website", url: bundle.website.url };
+    }
+    else if (bundle.npm !== undefined) {
+        source = { kind: "npm", locator: bundle.npm };
+    }
+    else {
+        throw new ConfigError(`Bundle ${JSON.stringify(bundleId)} has no source descriptor.`, "INVALID_CONFIG_FILE");
+    }
+    return hashBundleSourceIdentity({
+        version: 1,
+        source,
+        registryId: bundle.registryId ?? null,
+        componentRoot: component?.root ?? ".",
+    });
+}
+/** Identity for an environment-only filesystem bundle not persisted in config. */
+export function filesystemBundleSourceId(contentRoot) {
+    return hashBundleSourceIdentity({
+        version: 1,
+        source: { kind: "filesystem", locator: bundlePhysicalContentRoot(contentRoot) },
+        registryId: null,
+        componentRoot: ".",
+    });
+}
+function hashBundleSourceIdentity(identity) {
+    return `sha256:${createHash("sha256")
+        .update("akm.bundle-source\0v1\0")
+        .update(JSON.stringify(identity))
+        .digest("hex")}`;
+}
 /**
  * The resolved primary stash path — the `defaultBundle`'s filesystem `path`
  * (spec §10.1) — or `undefined` when no filesystem primary is configured.
@@ -68,13 +150,20 @@ export function bundleContentRoots(config) {
     for (const [id, entry] of Object.entries(bundles)) {
         if (typeof entry.path !== "string" || entry.path.length === 0)
             continue;
-        out.push({ id, contentRoot: bundleContentRoot(entry.path, bundleComponentConfig(entry)?.root) });
+        out.push({ id, contentRoot: bundlePhysicalContentRoot(entry.path, bundleComponentConfig(entry)?.root) });
     }
     return out;
 }
 /** The bundle id whose resolved content root already matches `resolvedContentRoot`, if any. */
 export function bundleKeyForContentRoot(config, resolvedContentRoot) {
-    return bundleContentRoots(config).find((entry) => entry.contentRoot === resolvedContentRoot)?.id;
+    let physical = path.resolve(resolvedContentRoot);
+    try {
+        physical = fs.realpathSync.native(physical);
+    }
+    catch {
+        // Compare the unresolved absolute locator when the candidate is not yet materialized.
+    }
+    return bundleContentRoots(config).find((entry) => entry.contentRoot === physical)?.id;
 }
 export function bundlesToSourceEntries(config) {
     const bundles = config.bundles;
@@ -96,6 +185,7 @@ export function bundleEntryToSourceEntry(key, bundle, isPrimary = false) {
     const base = {
         name: key,
         ...(bundle.writable !== undefined ? { writable: bundle.writable } : {}),
+        ...(bundle.credential !== undefined ? { credential: bundle.credential } : {}),
         ...(bundle.enabled !== undefined ? { enabled: bundle.enabled } : {}),
         ...(isPrimary ? { primary: true } : {}),
     };
@@ -235,6 +325,10 @@ export function resolveConfiguredSources(config) {
     }
     return out;
 }
+/** Active sources in the same deterministic order as `resolveConfiguredSources`. */
+export function resolveActiveConfiguredSources(config) {
+    return resolveConfiguredSources(config).filter((source) => source.enabled !== false);
+}
 function toConfiguredSource(persisted, isPrimary) {
     const source = parseSourceSpec(persisted);
     if (!source)