@aiwayds/dsh-topics-memory 0.22.0 → 0.24.0

package/lib/config.d.ts

@@ -103,6 +103,28 @@ export declare const TopicsConfig: z<Schemastery.ObjectS<NoInfer<{
     /** laya-serve systemone endpoint for the pace-maker (default: the local
      *  laya-serve bind from the laya repo's serve mode). */
     jevLayaUrl: z<string, string, "volatile-defined">;
+    /** Local embedding provider (A4 semantic reranker, spec §3.1): ''
+     *  sentinel = the whole semantic layer is OFF (pure lexical); 'ollama' =
+     *  the local ollama embed API (localhost is the ADR 0017 local exception).
+     *  v1 ships no remote provider — a remote embedding may only ever enter a
+     *  slow-lane/offline path, never the fast lane (red line ①). */
+    embeddingProvider: z<string, string, "volatile-defined">;
+    /** Embedding model; '' = provider default (ollama → nomic-embed-text),
+     *  same sentinel pattern as distillModel. */
+    embeddingModel: z<string, string, "volatile-defined">;
+    /** Injection-package master gate (A-line, spec §2/§3): off | shadow | on.
+     *  Carries the WHOLE new-behavior surface — query sanitization, the
+     *  three-layer package, nearFloor semantic rerank, degradation. off = zero
+     *  behavior change anywhere (byte-for-byte legacy); shadow = compute +
+     *  bypass-ledger only, nothing lands in context; on = engage. */
+    packageMode: z<string, string, "volatile-defined">;
+    /** Lesson injection gate (B2, spec §7 C1 MJ-4): off | shadow | on, default
+     *  off. off = established lessons neither inject nor shadow (zero injection-
+     *  side behavior); shadow = the lesson priority seat double-computes into
+     *  the bypass ledger (meta/lesson-shadow.jsonl), never lands in context;
+     *  on = established lessons inject. Only the injection side lives here —
+     *  the lesson loop (distill/approval) is the new repo's improveLoop gate. */
+    lessonInject: z<string, string, "volatile-defined">;
 }>>, Schemastery.ObjectT<NoInfer<{
     /** GitHub repo `owner/name`; empty = local-only mode (ADR 0008). */
     repo: z<string, string, "volatile-defined">;
@@ -201,6 +223,28 @@ export declare const TopicsConfig: z<Schemastery.ObjectS<NoInfer<{
     /** laya-serve systemone endpoint for the pace-maker (default: the local
      *  laya-serve bind from the laya repo's serve mode). */
     jevLayaUrl: z<string, string, "volatile-defined">;
+    /** Local embedding provider (A4 semantic reranker, spec §3.1): ''
+     *  sentinel = the whole semantic layer is OFF (pure lexical); 'ollama' =
+     *  the local ollama embed API (localhost is the ADR 0017 local exception).
+     *  v1 ships no remote provider — a remote embedding may only ever enter a
+     *  slow-lane/offline path, never the fast lane (red line ①). */
+    embeddingProvider: z<string, string, "volatile-defined">;
+    /** Embedding model; '' = provider default (ollama → nomic-embed-text),
+     *  same sentinel pattern as distillModel. */
+    embeddingModel: z<string, string, "volatile-defined">;
+    /** Injection-package master gate (A-line, spec §2/§3): off | shadow | on.
+     *  Carries the WHOLE new-behavior surface — query sanitization, the
+     *  three-layer package, nearFloor semantic rerank, degradation. off = zero
+     *  behavior change anywhere (byte-for-byte legacy); shadow = compute +
+     *  bypass-ledger only, nothing lands in context; on = engage. */
+    packageMode: z<string, string, "volatile-defined">;
+    /** Lesson injection gate (B2, spec §7 C1 MJ-4): off | shadow | on, default
+     *  off. off = established lessons neither inject nor shadow (zero injection-
+     *  side behavior); shadow = the lesson priority seat double-computes into
+     *  the bypass ledger (meta/lesson-shadow.jsonl), never lands in context;
+     *  on = established lessons inject. Only the injection side lives here —
+     *  the lesson loop (distill/approval) is the new repo's improveLoop gate. */
+    lessonInject: z<string, string, "volatile-defined">;
 }>>, "plain">;
 export type TopicsConfigValue = {
     repo: string;
@@ -244,8 +288,18 @@ export type TopicsConfigValue = {
     jevSecretFile?: string;
     jevLayaFallback?: boolean;
     jevLayaUrl?: string;
+    /** Injection-quality line keys (spec §7). Optional in this TS view only
+     *  (same sentinel pattern as the jev keys): index.ts's bare-harness
+     *  DEFAULTS literal predates them — consumers must treat undefined as the
+     *  documented default ('' / '' / 'off' = every new behavior zeroed). */
+    embeddingProvider?: string;
+    embeddingModel?: string;
+    packageMode?: 'off' | 'shadow' | 'on';
+    /** Lesson injection gate (B2). Optional in this TS view only (sentinel
+     *  pattern as above) — consumers treat undefined as 'off'. */
+    lessonInject?: 'off' | 'shadow' | 'on';
 };
-export declare const CONFIG_KEYS: readonly ["repo", "autoInject", "injectDedup", "suppressEcho", "topK", "perTopicBudget", "totalBudget", "matchThreshold", "tagBoost", "injectMode", "qualityLane", "graphDepth", "recencyWindowDays", "autoObserve", "includeSubagents", "observationMaxChars", "distillEveryTurns", "distillOnSessionEnd", "distillProvider", "distillModel", "distillBatchSize", "distillMaxModelCalls", "consolidateCadence", "deprecatedTtlDays", "usageBoost", "zeroOpenDecay", "pushDebounceSeconds", "jevEnabled", "jevBackend", "jevModel", "jevTimeoutMs", "jevSecretFile", "jevLayaFallback", "jevLayaUrl"];
+export declare const CONFIG_KEYS: readonly ["repo", "autoInject", "injectDedup", "suppressEcho", "topK", "perTopicBudget", "totalBudget", "matchThreshold", "tagBoost", "injectMode", "qualityLane", "graphDepth", "recencyWindowDays", "autoObserve", "includeSubagents", "observationMaxChars", "distillEveryTurns", "distillOnSessionEnd", "distillProvider", "distillModel", "distillBatchSize", "distillMaxModelCalls", "consolidateCadence", "deprecatedTtlDays", "usageBoost", "zeroOpenDecay", "pushDebounceSeconds", "jevEnabled", "jevBackend", "jevModel", "jevTimeoutMs", "jevSecretFile", "jevLayaFallback", "jevLayaUrl", "embeddingProvider", "embeddingModel", "packageMode", "lessonInject"];
 export type ConfigKey = (typeof CONFIG_KEYS)[number];
 /** CamelCase → dash-display (topK → top-k) for command output. */
 export declare function displayKey(key: string): string;

package/lib/config.js

@@ -103,6 +103,28 @@ export const TopicsConfig = z.object({
     /** laya-serve systemone endpoint for the pace-maker (default: the local
      *  laya-serve bind from the laya repo's serve mode). */
     jevLayaUrl: z.string().default('http://127.0.0.1:8000/v1/systemone').volatile(),
+    /** Local embedding provider (A4 semantic reranker, spec §3.1): ''
+     *  sentinel = the whole semantic layer is OFF (pure lexical); 'ollama' =
+     *  the local ollama embed API (localhost is the ADR 0017 local exception).
+     *  v1 ships no remote provider — a remote embedding may only ever enter a
+     *  slow-lane/offline path, never the fast lane (red line ①). */
+    embeddingProvider: z.string().default('').volatile(),
+    /** Embedding model; '' = provider default (ollama → nomic-embed-text),
+     *  same sentinel pattern as distillModel. */
+    embeddingModel: z.string().default('').volatile(),
+    /** Injection-package master gate (A-line, spec §2/§3): off | shadow | on.
+     *  Carries the WHOLE new-behavior surface — query sanitization, the
+     *  three-layer package, nearFloor semantic rerank, degradation. off = zero
+     *  behavior change anywhere (byte-for-byte legacy); shadow = compute +
+     *  bypass-ledger only, nothing lands in context; on = engage. */
+    packageMode: z.string().default('off').volatile(),
+    /** Lesson injection gate (B2, spec §7 C1 MJ-4): off | shadow | on, default
+     *  off. off = established lessons neither inject nor shadow (zero injection-
+     *  side behavior); shadow = the lesson priority seat double-computes into
+     *  the bypass ledger (meta/lesson-shadow.jsonl), never lands in context;
+     *  on = established lessons inject. Only the injection side lives here —
+     *  the lesson loop (distill/approval) is the new repo's improveLoop gate. */
+    lessonInject: z.string().default('off').volatile(),
 });
 export const CONFIG_KEYS = [
     'repo',
@@ -139,6 +161,10 @@ export const CONFIG_KEYS = [
     'jevSecretFile',
     'jevLayaFallback',
     'jevLayaUrl',
+    'embeddingProvider',
+    'embeddingModel',
+    'packageMode',
+    'lessonInject',
 ];
 /** CamelCase → dash-display (topK → top-k) for command output. */
 export function displayKey(key) {
@@ -214,10 +240,26 @@ export function parseConfigValue(key, raw) {
         }
         case 'distillProvider':
         case 'distillModel':
+        case 'embeddingModel':
         case 'jevModel':
         case 'jevSecretFile':
         case 'jevLayaUrl':
             return raw;
+        case 'embeddingProvider': {
+            if (raw === '' || raw === 'ollama')
+                return raw;
+            return { error: 'embedding-provider 仅支持 ollama（留空=语义层关；远程 provider 不进快道）' };
+        }
+        case 'packageMode': {
+            if (raw === 'off' || raw === 'shadow' || raw === 'on')
+                return raw;
+            return { error: 'package-mode 取值 off|shadow|on' };
+        }
+        case 'lessonInject': {
+            if (raw === 'off' || raw === 'shadow' || raw === 'on')
+                return raw;
+            return { error: 'lesson-inject 取值 off|shadow|on' };
+        }
         case 'jevLayaFallback': {
             if (raw === 'on' || raw === 'true')
                 return true;

package/lib/digest.d.ts

@@ -45,6 +45,8 @@ export interface AssembleResult {
     }[];
     /** Slow-lane pointers that entered the context (v4 §4.2). */
     slowIncluded?: string[];
+    /** Established lessons that entered the context (B2, spec 卷一 §6.3). */
+    lessonIncluded?: string[];
 }
 export interface AssembleConfig {
     perTopicBudget: number;
@@ -58,6 +60,27 @@ export interface SlowPointerInput {
     description?: string;
     why: string;
 }
+/**
+ * One established-lesson pointer (B2, spec 卷一 §6.3): flat-mode normal-entry
+ * rendering with the machine-recognizable source marker (MJ-C combination
+ * matrix — lessonInject=on without the A3 package injects lessons as plain
+ * entries, tagged `lesson source:<kind>`).
+ */
+export interface LessonPointerInput {
+    slug: string;
+    title: string;
+    status: string;
+    description?: string;
+    score: number;
+    source: string;
+}
+/** The `(lesson source:x)` marker on lesson entries — flat AND package form. */
+export declare function lessonSourceTag(source: string): string;
+/** One flat lesson entry: same two-line pointer shape + the source marker. */
+export declare function lessonEntryText(input: LessonPointerInput, budgetTokens: number): {
+    text: string;
+    usedTokens: number;
+};
 /**
  * One slow-lane pointer: same shape as a fast pointer plus the mandatory why
  * line (v4 §4.2 — 每条带 why 行). No score: the gate here was the LLM rerank,
@@ -69,11 +92,94 @@ export declare function slowEntryText(input: SlowPointerInput, budgetTokens: num
 };
 /**
  * Greedily pack pointer entries (hits already score-ordered) under the total
- * budget. Zero hits → empty text (ADR 0006: 零命中零注入).
+ * budget. Zero hits → empty text (ADR 0006: 零命中零注入). `lessons` (B2)
+ * packs after the slow pointers as flat entries with the source marker.
+ */
+export declare function assemblePointer(entries: readonly DigestInput[], cfg: AssembleConfig, slow?: readonly SlowPointerInput[], lessons?: readonly LessonPointerInput[]): AssembleResult;
+/**
+ * Greedily pack per-topic digests (hits already score-ordered) under the total
+ * budget. Zero hits → empty text (ADR 0006: 零命中零注入). `lessons` (B2).
+ */
+export declare function assembleInjection(entries: readonly DigestInput[], cfg: AssembleConfig, slow?: readonly SlowPointerInput[], lessons?: readonly LessonPointerInput[]): AssembleResult;
+/** One retrieval-side candidate, roster metadata pre-extracted by the caller. */
+export interface PackageCandidate {
+    slug: string;
+    title: string;
+    status: string;
+    description?: string;
+    /** Conclusion section first line (fallback for a missing description). */
+    conclusion?: string;
+    score: number;
+    /** Retrieval reason tags (`triggers:0.83` / `title:0.50` / `tags:…` / …). */
+    reasons: string[];
+    /** Edge/lane provenance: `depends:dN` | `slow-pick` | `semantic…` | raw. */
+    via?: string;
+    /**
+     * Lesson priority seat (B2, spec 卷一 §6.3): sorts FIRST in the direct
+     * layer and is exempt from the ≤2 direct-seat cap (still budget-bound) —
+     * 「主层 ≤2 席中命中 lesson 至少 1 席」. Absent on every topic candidate.
+     */
+    prioritySeat?: boolean;
+    /** Rendered as a `(${sourceTag})` suffix on the entry head — lesson source
+     *  marker (`lesson source:correction`), MJ-C. */
+    sourceTag?: string;
+}
+export interface PackageInput {
+    query: string;
+    /** Query lexemes the caller retrieved with (tokenize + §3.3 cleaning). */
+    queryTokens: string[];
+    /** Lexical strong hits (gate-passed); lands in the direct layer. */
+    direct: PackageCandidate[];
+    /** Graph expansion + slow-lane picks; lands in the neighborhood layer. */
+    neighborhood: PackageCandidate[];
+    /** nearFloor band (0.20–0.30) head; lands in the merged weak-signal line. */
+    weak: PackageCandidate[];
+    /** ADR 0015 usage signal — within-layer ordering tiebreak only (v1). */
+    usageBySlug?: Map<string, number>;
+}
+export interface PackageOpts {
+    /**
+     * `'on'` renders the live package; `'shadow'` means the caller double-runs
+     * (old assemblePointer + this) for the bypass ledger (spec §8.3). The pure
+     * output is identical in both modes — the mode is call-site bookkeeping.
+     */
+    mode?: 'on' | 'shadow';
+}
+export interface PackageResult {
+    text: string;
+    usedTokens: number;
+    included: string[];
+    dropped: {
+        slug: string;
+        reason: string;
+    }[];
+    /** Final per-layer rosters (what the 包头 counts report). */
+    layers: {
+        direct: string[];
+        neighborhood: string[];
+        weak: string[];
+    };
+}
+/** Total package cap — pinned, does not float with hit strength (A3 决议 3). */
+export declare const PACKAGE_TOTAL = 600;
+export declare const PACKAGE_DIRECT_MAX = 2;
+export declare const PACKAGE_DIRECT_BUDGET = 120;
+export declare const PACKAGE_NEIGHBOR_MAX = 3;
+export declare const PACKAGE_NEIGHBOR_BUDGET = 40;
+export declare const PACKAGE_WEAK_MAX = 2;
+/**
+ * Padded-trivial arm of the downgrade guard (spec §2.3 名词实体口径, an
+ * implementation-time item per §11): after stripping whitespace, a query this
+ * short counts as 琐碎 even when the tokenizer expands CJK bigrams past 3
+ * tokens. Calibrated on the two named scenarios: 场景① ack query strips to
+ * 15 chars (downgrade), a real review query strips to 18 (kept).
  */
-export declare function assemblePointer(entries: readonly DigestInput[], cfg: AssembleConfig, slow?: readonly SlowPointerInput[]): AssembleResult;
+export declare const PACKAGE_TRIVIAL_QUERY_CHARS = 16;
 /**
- * Greedily pack per-topic digests (hits already score-ordered) under the
- * total budget. Zero hits → empty text (ADR 0006: 零命中零注入).
+ * Assemble the three-layer package. Returns `null` — the whole-package skip
+ * signal — when the roster is empty (ADR 0006 零命中零注入) or when the
+ * downgrade guard fires (spec §2.3: 琐碎 query 且与全部候选 slug/title 零
+ * 词面实体交集). Packing is layered greedy: direct first, then neighborhood,
+ * then the weak line — over budget, lower layers are cut first.
  */
-export declare function assembleInjection(entries: readonly DigestInput[], cfg: AssembleConfig, slow?: readonly SlowPointerInput[]): AssembleResult;
+export declare function assemblePackage(input: PackageInput, opts?: PackageOpts): PackageResult | null;