akm-cli 0.9.0-rc.4 → 0.9.0-rc.6

package/dist/commands/env/secret-cli.js

@@ -18,11 +18,12 @@
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
+import { getParsedInvocation } from "../../cli/invocation.js";
 import { getStringArg } from "../../cli/parse-args.js";
 import { defineGroupCommand, defineJsonCommand, output } from "../../cli/shared.js";
-import { deriveCanonicalAssetName } from "../../core/asset/asset-spec.js";
+import { deriveCanonicalAssetName } from "../../core/asset/asset-placement.js";
 import { loadConfig } from "../../core/config/config.js";
-import { makeSecretRef, resolveSecretPath } from "../../core/env-secret-ref.js";
+import { commitEnvSecretWrite, makeSecretRef, resolveSecretPath, resolveSecretWriteTarget, writeTargetDisplaySource, } from "../../core/env-secret-ref.js";
 import { ConfigError, NotFoundError, UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
 import { resolveSourceEntries } from "../../indexer/search/search-source.js";
@@ -94,10 +95,17 @@ const secretSetCommand = defineJsonCommand({
         },
         "from-file": { type: "string", description: "Read the value from this file (stored byte-exact)" },
         "from-env": { type: "string", description: "Read the value from the named environment variable" },
+        target: {
+            type: "string",
+            description: "Override the write destination. Accepts a source name from your config; falls back to defaultWriteTarget then the working stash.",
+        },
     },
     async run({ args }) {
         const { setSecret } = await import("./secret.js");
-        const { name, absPath, source } = resolveSecretPath(args.ref, { subPath: getStringArg(args, "path") });
+        const { name, absPath, target } = resolveSecretWriteTarget(args.ref, args.target, {
+            subPath: getStringArg(args, "path"),
+        });
+        const displaySource = writeTargetDisplaySource(target);
         const fromEnv = args["from-env"];
         const fromFile = args["from-file"];
         if (fromEnv !== undefined && fromFile !== undefined) {
@@ -132,7 +140,8 @@ const secretSetCommand = defineJsonCommand({
             value = Buffer.from(stdinBuf.toString("utf8").replace(/\n$/, ""), "utf8");
         }
         setSecret(absPath, value);
-        output("secret-set", { ref: makeSecretRef(name, source) });
+        commitEnvSecretWrite(target, { type: "secret", name }, "Update", [absPath]);
+        output("secret-set", { ref: makeSecretRef(name, displaySource) });
     },
 });
 const secretPathCommand = defineJsonCommand({
@@ -181,11 +190,10 @@ const secretRunCommand = defineJsonCommand({
         if (isDangerousEnvKey(varName)) {
             throw new UsageError(`Refusing to inject a secret into "${varName}": it is a known process-hijacking variable (e.g. LD_PRELOAD, PATH).`, "INVALID_FLAG_VALUE");
         }
-        const dashIndex = process.argv.indexOf("--");
-        if (dashIndex < 0 || dashIndex === process.argv.length - 1) {
+        const command = getParsedInvocation().passthroughArgs();
+        if (command.length === 0) {
             throw new UsageError("Missing command. Usage: akm secret run <ref> <VAR> -- <command>");
         }
-        const command = process.argv.slice(dashIndex + 1);
         const { name, absPath, source } = resolveSecretPath(args.ref);
         if (!fs.existsSync(absPath)) {
             throw new NotFoundError(`Secret not found: ${makeSecretRef(name, source)}`);
@@ -224,9 +232,14 @@ const secretRemoveCommand = defineJsonCommand({
     args: {
         ref: { type: "positional", description: "Secret ref", required: true },
         yes: { type: "boolean", alias: "y", description: "Skip confirmation prompt", default: false },
+        target: {
+            type: "string",
+            description: "Override the write destination. Accepts a source name from your config; falls back to defaultWriteTarget then the working stash.",
+        },
     },
     async run({ args }) {
-        const { name, absPath, source } = resolveSecretPath(args.ref);
+        const { name, absPath, target } = resolveSecretWriteTarget(args.ref, args.target);
+        const displaySource = writeTargetDisplaySource(target);
         const { confirmDestructive } = await import("../../cli/confirm.js");
         const confirmed = await confirmDestructive(`Remove secret "${args.ref}"? This cannot be undone.`, {
             yes: args.yes === true,
@@ -237,10 +250,11 @@ const secretRemoveCommand = defineJsonCommand({
         }
         const { removeSecret } = await import("./secret.js");
         if (!fs.existsSync(absPath)) {
-            throw new NotFoundError(`Secret not found: ${makeSecretRef(name, source)}`);
+            throw new NotFoundError(`Secret not found: ${makeSecretRef(name, displaySource)}`);
         }
         const removed = removeSecret(absPath);
-        output("secret-remove", { ref: makeSecretRef(name, source), removed });
+        commitEnvSecretWrite(target, { type: "secret", name }, "Remove", [absPath, `${absPath}.sensitive`]);
+        output("secret-remove", { ref: makeSecretRef(name, displaySource), removed });
     },
 });
 export const secretCommand = defineGroupCommand({

package/dist/commands/events.js

@@ -10,7 +10,7 @@
  * text-renderer pipeline as the rest of the CLI (no silent
  * `JSON.stringify` fallback).
  */
-import { parseAssetRef } from "../core/asset/asset-ref.js";
+import { parseRefInput } from "../core/asset/resolve-ref.js";
 import { UsageError } from "../core/errors.js";
 import { readEvents, tailEvents } from "../core/events.js";
 import { parseSinceToIso } from "../core/time.js";
@@ -43,7 +43,7 @@ function validateRef(ref) {
     if (!trimmed) {
         throw new UsageError("--ref cannot be empty.", "INVALID_FLAG_VALUE");
     }
-    parseAssetRef(trimmed);
+    parseRefInput(trimmed);
     return trimmed;
 }
 export function akmEventsList(options = {}) {

package/dist/commands/feedback-cli.js

@@ -3,18 +3,21 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import fs from "node:fs";
 import { defineJsonCommand, output, parseAllFlagValues } from "../cli/shared.js";
-import { parseAssetRef, refToString } from "../core/asset/asset-ref.js";
 import { assembleAsset } from "../core/asset/asset-serialize.js";
 import { parseFrontmatter, parseFrontmatterBlock } from "../core/asset/frontmatter.js";
+import { conceptIdFromTypeName, displayRef, parseRefInput } from "../core/asset/resolve-ref.js";
 import { writeFileAtomic } from "../core/common.js";
 import { FEEDBACK_FAILURE_MODES, loadConfig } from "../core/config/config.js";
 import { UsageError } from "../core/errors.js";
 import { appendEvent } from "../core/events.js";
 import { getDbPath } from "../core/paths.js";
+import { withStateDb } from "../core/state-db.js";
 import { warn } from "../core/warn.js";
-import { applyFeedbackToUtilityScore, closeDatabase, findEntryIdByRef, getEntryById, getEntryFilePathById, openExistingDatabase, } from "../indexer/db/db.js";
 import { resolveSourceEntries } from "../indexer/search/search-source.js";
-import { countFeedbackSignals, insertUsageEvent } from "../indexer/usage/usage-events.js";
+import { countFeedbackSignals, insertUsageEvent, resolveUsageEventSource } from "../indexer/usage/usage-events.js";
+import { closeDatabase, openExistingDatabase } from "../storage/repositories/index-connection.js";
+import { findEntryIdByRef, getEntryById, getEntryFilePathById, getItemRefById, } from "../storage/repositories/index-entries-repository.js";
+import { applyFeedbackToUtilityScore } from "../storage/repositories/index-utility-repository.js";
 // ── Tag validation ────────────────────────────────────────────────────────────
 const TAG_KEY_RE = /^[a-z_][a-z0-9_]*$/;
 const MAX_FEEDBACK_TAGS = 10;
@@ -54,7 +57,10 @@ function validateFeedbackTags(raw) {
  * `inferenceProcessed`.
  */
 function appendLessonStrength(type, name, feedbackRef) {
-    const ref = `${type}:${name}`;
+    // Canonical 0.9.0 conceptId (`lessons/<name>`, D-R3) — `findEntryIdByRef`
+    // keys on the stored `item_ref` and parses its argument as the new grammar,
+    // so a `type:name` lookup here would never match.
+    const ref = conceptIdFromTypeName(type, name);
     let filePath;
     const db = openExistingDatabase();
     try {
@@ -107,6 +113,39 @@ function appendLessonStrength(type, name, feedbackRef) {
     }
     return { strength: strengthList.length };
 }
+/**
+ * Persist the feedback usage-event (state.db) and immediately fold it into the
+ * entry's MemRL utility score (index.db). Chunk-8 WI-8.3: usage_events lives in
+ * state.db; entries + utility_scores stay in `indexDb`. Positive signals raise
+ * search ranking on the next read without a full reindex; negatives are durable
+ * but take effect at the next `akm index`. Uses the bounded-step EMA policy
+ * (F-5 / #386, arXiv:2601.03192). Best-effort: a utility-update failure never
+ * fails the feedback record.
+ */
+function recordFeedbackUsage(indexDb, entryId, durableEntryRef, signal, metadataStr) {
+    let utilityResult;
+    const eventSource = resolveUsageEventSource();
+    withStateDb((stateDb) => {
+        insertUsageEvent(stateDb, {
+            event_type: "feedback",
+            entry_ref: durableEntryRef,
+            entry_id: entryId,
+            signal,
+            metadata: metadataStr,
+            source: eventSource,
+        });
+        if (eventSource !== "user")
+            return;
+        try {
+            const { pos, neg } = countFeedbackSignals(stateDb, entryId);
+            utilityResult = applyFeedbackToUtilityScore(indexDb, entryId, pos, neg);
+        }
+        catch {
+            // best-effort — feedback recording succeeds even if utility update fails
+        }
+    });
+    return utilityResult;
+}
 // ── Command definition ────────────────────────────────────────────────────────
 export const feedbackCommand = defineJsonCommand({
     meta: {
@@ -123,7 +162,7 @@ export const feedbackCommand = defineJsonCommand({
         // Optional in citty so run() is invoked even when omitted; we re-validate
         // and throw a structured UsageError below so exit code is 2 (USAGE) rather
         // than citty's default 0 (help banner).
-        ref: { type: "positional", description: "Asset ref (type:name)", required: false },
+        ref: { type: "positional", description: "Asset ref ([bundle//]conceptId, e.g. lessons/deploy)", required: false },
         positive: { type: "boolean", description: "Record positive feedback (boosts ranking immediately)", default: false },
         negative: {
             type: "boolean",
@@ -147,7 +186,7 @@ export const feedbackCommand = defineJsonCommand({
         },
         "applied-to": {
             type: "string",
-            description: "Credit a lesson that helped resolve this task. Accepts a `lesson:<name>` ref. " +
+            description: "Credit a lesson that helped resolve this task. Accepts a `lessons/<name>` ref. " +
                 "When combined with --positive, appends this feedback ref to the target lesson's " +
                 "`lessonStrength[]` frontmatter array (dedup, idempotent). Ignored on non-lesson targets.",
         },
@@ -155,9 +194,9 @@ export const feedbackCommand = defineJsonCommand({
     async run({ args }) {
         const ref = (args.ref ?? "").trim();
         if (!ref) {
-            throw new UsageError("Asset ref is required. Usage: akm feedback <ref> --positive|--negative", "MISSING_REQUIRED_ARGUMENT", "Pass a ref like `skill:deploy` and either --positive or --negative.");
+            throw new UsageError("Asset ref is required. Usage: akm feedback <ref> --positive|--negative", "MISSING_REQUIRED_ARGUMENT", "Pass a ref like `skills/deploy` and either --positive or --negative.");
         }
-        const parsedRef = parseAssetRef(ref);
+        const parsedRef = parseRefInput(ref);
         if (args.positive && args.negative) {
             throw new UsageError("Specify either --positive or --negative, not both.");
         }
@@ -241,29 +280,16 @@ export const feedbackCommand = defineJsonCommand({
             // in search results until after reindexing.
             const indexedEntry = getEntryById(db, entryId);
             const source = sources.find((candidate) => candidate.path === indexedEntry?.stashDir);
-            durableRef = refToString({
-                ...parsedRef,
-                origin: parsedRef.origin ?? source?.registryId ?? "stash",
-            });
-            insertUsageEvent(db, {
-                event_type: "feedback",
-                entry_ref: durableRef,
-                entry_id: entryId,
-                signal,
-                metadata: metadataStr,
-            });
-            // Apply feedback-derived utility score adjustment immediately so that
-            // positive/negative signals influence search ranking without requiring
-            // a full reindex. We query the total accumulated feedback counts from
-            // usage_events so the delta reflects the entire signal history.
-            // Uses MemRL bounded-step EMA (F-5 / #386, arXiv:2601.03192).
-            try {
-                const { pos, neg } = countFeedbackSignals(db, entryId);
-                utilityResult = applyFeedbackToUtilityScore(db, entryId, pos, neg);
-            }
-            catch {
-                // best-effort — feedback recording succeeds even if utility update fails
-            }
+            const durableOrigin = parsedRef.origin ?? source?.registryId ?? "stash";
+            // WI-8.5b: the `feedback` / `improve_review_needed` events key on the
+            // resolved entry's fully-qualified item_ref — the SAME durable key the
+            // usage_events row carries and the SAME spelling the signal-delta
+            // correlation reads (buildLatestFeedbackTsMap, collapsed to [item_ref]).
+            // The D-R5 display spelling is the fallback only for a NULL-provenance
+            // (pre-cutover) row that the one-time re-key has not yet finalized.
+            const itemRef = getItemRefById(db, entryId) ?? undefined;
+            durableRef = itemRef ?? displayRef({ type: parsedRef.type, name: parsedRef.name, bundleId: durableOrigin });
+            utilityResult = recordFeedbackUsage(db, entryId, itemRef, signal, metadataStr);
         }
         finally {
             closeDatabase(db);
@@ -299,7 +325,7 @@ export const feedbackCommand = defineJsonCommand({
             }
         }
         // Phase 7A / Advantage D4b: --applied-to credits a lesson. When the
-        // target is a `lesson:<name>` ref and the signal is positive, append
+        // target is a `lessons/<name>` ref and the signal is positive, append
         // the feedback ref to the target lesson's `lessonStrength[]`
         // frontmatter array (dedup, idempotent). Non-lesson targets are
         // ignored. Failures here are warnings — feedback recording is the
@@ -308,7 +334,7 @@ export const feedbackCommand = defineJsonCommand({
         let appliedToResult = null;
         if (appliedToRaw && signal === "positive") {
             try {
-                const parsedApplied = parseAssetRef(appliedToRaw);
+                const parsedApplied = parseRefInput(appliedToRaw);
                 if (parsedApplied.type === "lesson") {
                     const updated = appendLessonStrength(parsedApplied.type, parsedApplied.name, ref);
                     if (updated) {

package/dist/commands/graph/graph.js

@@ -3,12 +3,11 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import fs from "node:fs";
 import path from "node:path";
-import { parseAssetRef } from "../../core/asset/asset-ref.js";
+import { displayRef, parseQualifiedRefInput } from "../../core/asset/resolve-ref.js";
 import { loadConfig } from "../../core/config/config.js";
 import { NotFoundError, UsageError } from "../../core/errors.js";
 import { getDbPath } from "../../core/paths.js";
 import { warn } from "../../core/warn.js";
-import { closeDatabase, findEntryIdByRef, getEntryById, getEntryRefRowsForStashRoot, openExistingDatabase, openIndexDatabase, } from "../../indexer/db/db.js";
 import { loadStoredGraphSnapshot } from "../../indexer/db/graph-db.js";
 import { listRelatedPathsForFile } from "../../indexer/graph/graph-boost.js";
 import { runGraphExtractionPass } from "../../indexer/graph/graph-extraction.js";
@@ -16,6 +15,8 @@ import { withIndexWriterLease } from "../../indexer/index-writer-lock.js";
 import { lookup } from "../../indexer/indexer.js";
 import { findSourceForPath, resolveSourceEntries } from "../../indexer/search/search-source.js";
 import { resolveAssetPath } from "../../indexer/walk/path-resolver.js";
+import { closeDatabase, openExistingDatabase, openIndexDatabase } from "../../storage/repositories/index-connection.js";
+import { findEntryIdByRef, getEntryById, getEntryRefRowsForStashRoot, } from "../../storage/repositories/index-entries-repository.js";
 function resolveGraphStashPath(source) {
     const sources = resolveSourceEntries(undefined, loadConfig());
     if (sources.length === 0) {
@@ -252,7 +253,8 @@ function buildRefByPath(stashRoot, db) {
         try {
             const entry = JSON.parse(row.entry_json);
             if (typeof entry.type === "string" && typeof entry.name === "string") {
-                map.set(row.file_path, { ref: `${entry.type}:${entry.name}`, type: entry.type });
+                // F4b output-spelling flip: emit the 0.9.0 conceptId grammar.
+                map.set(row.file_path, { ref: displayRef({ type: entry.type, name: entry.name }), type: entry.type });
             }
         }
         catch {
@@ -460,7 +462,7 @@ export async function akmGraphUpdate(options) {
     });
 }
 async function resolveGraphTarget(ref, source) {
-    const parsedRef = parseAssetRef(ref);
+    const parsedRef = parseQualifiedRefInput(ref);
     const filePath = (await resolveAssetPath(parsedRef, {
         mode: "index-first",
         honorOrigin: true,

package/dist/commands/health/advisories.js

@@ -77,7 +77,7 @@ export function collectImproveAdvisories(db, stateDbPath, since, improveSummary)
             confidence: "high",
             message: `Enrichment lanes minted ${minting.minted} NEW asset(s) vs ${minting.updated} update(s) ` +
                 `(${Math.round(minting.share * 100)}% minted, threshold ${Math.round(ENRICHMENT_MINTED_WARN_SHARE * 100)}%). ` +
-                "Enrichment-classed lanes (proactive/high-salience/high-retrieval/signal-delta) are ratified to edit " +
+                "Enrichment-classed lanes (proactive/high-salience/signal-delta) are ratified to edit " +
                 "existing assets only — new-asset generation belongs to the signal-gated minting lanes.",
         });
     }
@@ -98,7 +98,7 @@ export function collectImproveAdvisories(db, stateDbPath, since, improveSummary)
     // R5 collapse/churn detector: surface any collapse_detector_alert events
     // in the health window, plus the latest cycle row's headline numbers so
     // the operator can act without opening the DB. `unknown` when the detector
-    // has never produced a cycle row (no consolidate/recombine work yet).
+    // has never produced a cycle row (no consolidate work yet).
     try {
         // Reuse the already-open state.db handle (readEvents supports a
         // borrowed connection) — no extra open/migrate/close per health call.
@@ -120,7 +120,7 @@ export function collectImproveAdvisories(db, stateDbPath, since, improveSummary)
                 // volume thresholds are still being tuned (design doc §7).
                 confidence: collapseKinds.length > 0 ? "high" : "medium",
                 message: `R5 detector fired ${collapseAlertEvents.length} alert(s) in window (kinds: ${kinds.join(", ")}). ` +
-                    `${cycleSummary} See docs/design/improve-collapse-churn-detector-design.md §6.3 runbook queries.`,
+                    `${cycleSummary} See docs/architecture/specs/improve-collapse-churn-detector-design.md §6.3 runbook queries.`,
             });
         }
         else if (latestCycle) {
@@ -139,7 +139,7 @@ export function collectImproveAdvisories(db, stateDbPath, since, improveSummary)
                 kind: "deterministic",
                 confidence: "high",
                 message: "No detector cycle rows yet — the collapse/churn detector runs only on improve cycles " +
-                    "where consolidate/recombine did work (synthesis lanes may be idle).",
+                    "where consolidate did work.",
             });
         }
     }