akm-cli 0.9.0-rc.0 → 0.9.0-rc.13

package/dist/commands/improve/proactive-maintenance.js

@@ -1,6 +1,29 @@
 // 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/.
+/**
+ * Layer 2 of the `akm improve` redesign — the PROACTIVE MAINTENANCE SELECTOR.
+ *
+ * The signal-delta gate (Layer 1) only surfaces assets that have *fresh*
+ * feedback. It never revisits a stable, useful asset on a schedule. On a quiet
+ * stash with no new feedback the improve loop can therefore go indefinitely
+ * without touching high-value assets that have simply gone stale.
+ *
+ * This selector is a SECOND eligibility SOURCE. It runs only on whole-stash /
+ * type scope, enumerates the eligible asset population, computes a composite
+ * maintenance priority per asset, gates on staleness (the "due" gate), bounds
+ * the result to top-N by priority, and feeds the winners into the SAME
+ * reflect/distill candidate set as the signal-delta gate — so they flow through
+ * the existing #580 empty-diff/cosmetic suppression and additive-distill gates.
+ * It adds NO new mutation or suppression logic of its own.
+ *
+ * The selector is intentionally pure: it takes pre-built staleness maps and
+ * retrieval counts (the planner already builds these for the signal-delta gate)
+ * plus an injectable `now`, and returns a deterministic selection.
+ * All DB access happens in the caller through the existing storage abstractions;
+ * this module never opens a database.
+ */
+import { typeNameFromConceptId } from "../../core/asset/resolve-ref.js";
 import { computeSalience } from "./salience.js";
 /** One day in milliseconds. */
 const DAY_MS = 86_400_000;
@@ -10,10 +33,14 @@ export const DEFAULT_DUE_DAYS = 30;
 export const DEFAULT_MAX_PER_RUN = 25;
 /** Lower bound on size used in the cost denominator so tiny files don't divide by ~0. */
 const SIZE_FLOOR_BYTES = 200;
-/** Parse the bare asset type out of a `type:name` ref. Returns "" when unparseable. */
+/**
+ * Derive the asset type from a candidate's canonical conceptId ref
+ * (`[bundle//]<stash-subdir>/<name>`) via the permanent reverse table. Returns
+ * "" when the leading segment is not a known stash subdir.
+ */
 function refType(ref) {
-    const i = ref.indexOf(":");
-    return i > 0 ? ref.slice(0, i) : "";
+    const body = ref.includes("//") ? ref.slice(ref.indexOf("//") + 2) : ref;
+    return typeNameFromConceptId(body)?.type ?? "";
 }
 /**
  * Score and select due assets for proactive maintenance.
@@ -86,13 +113,11 @@ export function selectProactiveMaintenanceRefs(params) {
     return { selected, dueTotal, neverReflected, scored };
 }
 /**
- * Post-lock re-filter for proactive refs.
+ * Pre-execution re-filter for proactive refs.
  *
- * Called INSIDE the reflect-distill.lock window with freshly-read timestamp
- * maps so that any `reflect_invoked` events committed by a concurrent run
- * while this run was waiting for the lock are visible. Refs that became
- * non-due (staleDays ≤ dueDays) since planning time are dropped before
- * execution, closing the SELECT-time cooldown race.
+ * Called under the whole-run lock with freshly-read timestamp maps. Refs that
+ * became non-due before this run acquired the lock are dropped before execution,
+ * closing the SELECT-time cooldown race.
  *
  * The logic mirrors the DUE gate in `selectProactiveMaintenanceRefs` — an
  * asset is due only when never touched OR last touched more than `dueDays`

package/dist/commands/improve/proposal-envelope.js

@@ -0,0 +1,31 @@
+// 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/.
+/**
+ * `emitProposal` — the proposal-envelope facade (D10 / R7).
+ *
+ * Every improve verb that raises a proposal (revise = reflect, learn =
+ * distill/promote/extract, consolidate = the merge/promote ops) routes it
+ * through this single seam instead of calling {@link createProposal} directly.
+ *
+ * Since WI-6.2 the envelope carries `changes: FileChange[]` + `beforeHash`:
+ * `createProposal` derives a single-entry change set (whose `after` IS
+ * `payload.content`) and the mint-time before-state hash for every proposal
+ * emitted through this seam — producers stay payload-shaped and get the
+ * envelope for free. The facade remains a pass-through: it does NOT synthesise
+ * `sourceRun` or mutate the input — each emit site owns its own
+ * `source`/`sourceRun`/attribution.
+ *
+ * Pinned by `tests/commands/improve/proposal-envelope.test.ts`.
+ */
+import { createProposal, } from "../proposal/repository.js";
+/**
+ * Emit a proposal through the single improve envelope seam. Equivalent to
+ * `createProposal(ctx.stashDir, input, ctx.proposalsCtx)`; returns either the
+ * persisted {@link import("../proposal/repository.js").Proposal} or a
+ * {@link import("../proposal/repository.js").CreateProposalSkipped} record when a
+ * dedup/cooldown guard fires (detect with `isProposalSkipped`).
+ */
+export function emitProposal(ctx, input) {
+    return createProposal(ctx.stashDir, input, ctx.proposalsCtx);
+}