@aiwayds/dsh-topics-memory 0.22.0 → 0.24.0

package/lib/store.d.ts

@@ -19,18 +19,31 @@ export interface TopicMeta {
     depends: string[];
     generatedAt: string;
 }
-export type ObservationKind = 'decision' | 'finding' | 'constraint' | 'question' | 'turn';
+/** Bundle entry kinds (B2, spec §6.5 落点表: store kind 枚举). Canonical
+ *  model lives in okf.ts next to TopicStatus; re-exported here as the store
+ *  surface the spec anchors on. */
+export type TopicKind = okf.TopicKind;
+export declare const topicKindOf: typeof okf.topicKindOf;
+export type ObservationKind = 'decision' | 'finding' | 'constraint' | 'question' | 'turn' | 'signal';
+/**
+ * Where an observation came from. `fed` marks entries that arrived through
+ * the feedObservations write seam (B-line dual-write, spec 卷二 §6.2) — the
+ * provenance marker the distill lane and audits key on.
+ */
+export type ObservationSource = 'model' | 'auto' | 'fed';
 export interface Observation {
     id: string;
     at: string;
     kind: ObservationKind;
-    source: 'model' | 'auto';
+    source: ObservationSource;
     text: string;
     sessionId?: string;
     distilled: boolean;
     distilledInto?: string[];
     /** Failed distill attempts: fed to the model but consumed by no op (GC counter). */
     attempts?: number;
+    /** Write-seam audit: the feedObservations caller identity (opts.actor). */
+    by?: string;
 }
 export interface SaveResult {
     slug: string;
@@ -110,10 +123,19 @@ export declare class BundleStore {
      * Write a topic (atomic), regenerate the index, and commit both — one
      * commit per conclusion change (ADR 0003). `slug` in the doc's depends is
      * NOT normalized here; callers pass bundle-relative paths.
+     *
+     * `links` (A2, optional): whitelist-surviving semantic targets from the
+     * distill lane. Applied INSIDE this one write transaction — the topic and
+     * its edges land together (先落 topic 再建边); the Links section lands as
+     * body wikilinks and the index/backlinks regeneration below (same
+     * transaction) recomputes the edge index over them. Normalized and
+     * self/dedup-guarded here too, so any caller benefits from the same guard
+     * the distill lane already ran.
      */
     saveTopic(input: {
         slug: string;
         doc: okf.TopicDoc;
+        links?: readonly string[];
     }, opts: {
         message: string;
         actor?: string;
@@ -126,6 +148,19 @@ export declare class BundleStore {
      * safe write path. Returns false when the slug doesn't exist (idempotent).
      */
     deleteTopic(slug: string, message: string): Promise<boolean>;
+    /**
+     * Lesson removal seam (B2/卷二 §6.2 MJ-B, spec 红线④): archive BEFORE the
+     * roster removal — the file is copied byte-exact to `archive/lessons/`
+     * inside the bundle and only then deleted from `topics/`, both landing in
+     * ONE git commit so `git revert` restores the lesson exactly (自动写资产
+     * 必须可回滚). Returns undefined when the slug doesn't exist (idempotent).
+     */
+    archiveLesson(slug: string, opts: {
+        message: string;
+    }): Promise<{
+        archivedTo: string;
+        committed: boolean;
+    } | undefined>;
     private regenerateIndex;
     /**
      * Reverse-reference index: slug → who references it and how (`depends`
@@ -140,9 +175,10 @@ export declare class BundleStore {
     }[]>>;
     appendObservation(input: {
         kind: ObservationKind;
-        source: 'model' | 'auto';
+        source: ObservationSource;
         text: string;
         sessionId?: string;
+        by?: string;
     }): Promise<Observation>;
     allObservations(limit?: number): Promise<Observation[]>;
     undistilledObservations(limit?: number): Promise<Observation[]>;

package/lib/store.js

@@ -8,7 +8,7 @@
  *
  * @module store
  */
-import { readdir, readFile, writeFile, rename, mkdir, appendFile, access, rm, } from 'node:fs/promises';
+import { readdir, readFile, writeFile, rename, mkdir, appendFile, access, rm, copyFile, } from 'node:fs/promises';
 import { readFileSync } from 'node:fs';
 import { constants as FsConstants } from 'node:fs';
 import { dirname, join } from 'node:path';
@@ -16,6 +16,7 @@ import { randomUUID } from 'node:crypto';
 import * as okf from "./okf.js";
 import * as gitmod from "./git.js";
 import { actorFor } from "./paths.js";
+export const topicKindOf = okf.topicKindOf;
 export class StoreError extends Error {
     name = 'StoreError';
 }
@@ -42,6 +43,14 @@ function dedupePaths(paths) {
 function sameStrings(a, b) {
     return a.length === b.length && a.every((v, i) => v === b[i]);
 }
+/**
+ * Body heading for caller-supplied semantic links (A2). Links are rendered as
+ * `[[wikilinks]]` under this section so the EXISTING link-edge machinery
+ * (okf.bodyLinkSlugs → computeBacklinks → retrieval graph walk) indexes them
+ * as `via: 'link'` edges — the edge representation gains no new type; the
+ * body landing spot is what makes them first-class links for free.
+ */
+const LINKS_HEADING = 'Links';
 export class BundleStore {
     root;
     actor;
@@ -285,6 +294,14 @@ export class BundleStore {
      * Write a topic (atomic), regenerate the index, and commit both — one
      * commit per conclusion change (ADR 0003). `slug` in the doc's depends is
      * NOT normalized here; callers pass bundle-relative paths.
+     *
+     * `links` (A2, optional): whitelist-surviving semantic targets from the
+     * distill lane. Applied INSIDE this one write transaction — the topic and
+     * its edges land together (先落 topic 再建边); the Links section lands as
+     * body wikilinks and the index/backlinks regeneration below (same
+     * transaction) recomputes the edge index over them. Normalized and
+     * self/dedup-guarded here too, so any caller benefits from the same guard
+     * the distill lane already ran.
      */
     async saveTopic(input, opts) {
         return this.enqueue(async () => {
@@ -292,9 +309,24 @@ export class BundleStore {
             const file = this.topicPath(slug);
             const created = opts.created ?? !(await existsSync(file));
             const now = new Date().toISOString();
+            let body = input.doc.body;
+            if (input.links !== undefined && input.links.length > 0) {
+                const targets = [];
+                for (const raw of input.links) {
+                    if (typeof raw !== 'string')
+                        continue;
+                    const target = okf.normalizeLinkTarget(raw);
+                    if (target === undefined || target === slug || targets.includes(target))
+                        continue;
+                    targets.push(target);
+                }
+                if (targets.length > 0) {
+                    body = okf.setSection(body, LINKS_HEADING, targets.map((t) => `- [[${t}]]`).join('\n'));
+                }
+            }
             const doc = {
                 fm: { ...input.doc.fm, generated: { by: opts.actor ?? this.actor, at: now } },
-                body: input.doc.body,
+                body,
             };
             const raw = okf.serializeTopicDoc(doc);
             await atomicWrite(file, raw);
@@ -321,6 +353,30 @@ export class BundleStore {
             return true;
         });
     }
+    /**
+     * Lesson removal seam (B2/卷二 §6.2 MJ-B, spec 红线④): archive BEFORE the
+     * roster removal — the file is copied byte-exact to `archive/lessons/`
+     * inside the bundle and only then deleted from `topics/`, both landing in
+     * ONE git commit so `git revert` restores the lesson exactly (自动写资产
+     * 必须可回滚). Returns undefined when the slug doesn't exist (idempotent).
+     */
+    async archiveLesson(slug, opts) {
+        return this.enqueue(async () => {
+            const clean = okf.slugify(slug);
+            const file = this.topicPath(clean);
+            if (!(await existsSync(file)))
+                return undefined;
+            const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+            const archivedTo = `archive/lessons/${clean}-${stamp}.md`;
+            const absTo = join(this.root, archivedTo);
+            await mkdir(dirname(absTo), { recursive: true });
+            await copyFile(file, absTo);
+            await rm(file);
+            await this.regenerateIndex();
+            const committed = await this.commit([archivedTo, `topics/${clean}.md`, 'index.md'], opts.message);
+            return { archivedTo, committed };
+        });
+    }
     async regenerateIndex() {
         const metas = await this.listTopics();
         const entries = metas.map((m) => ({
@@ -400,6 +456,8 @@ export class BundleStore {
         };
         if (input.sessionId !== undefined)
             obs.sessionId = input.sessionId;
+        if (input.by !== undefined)
+            obs.by = input.by;
         // Behind the store-wide queue: markDistilled / recordUnconsumed rewrite
         // the whole JSONL file — an unsynchronized append here could interleave
         // with a rewrite and lose either the new observation or the rewrite.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiwayds/dsh-topics-memory",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "description": "dsh-plugin: quality-first topic memory for dsh — a topic keeps the starting question, conclusion, impact and dependencies, not the process; local-first git-traced OKF bundle, budgeted LLM-free injection",
   "type": "module",
   "main": "lib/index.js",
@@ -42,7 +42,7 @@
     "build": "tsc -p tsconfig.json",
     "check": "tsc --noEmit -p tsconfig.json",
     "pretest": "tsc -p tsconfig.json",
-    "test": "node --test test/yaml.test.mjs test/okf.test.mjs test/retrieval.test.mjs test/digest.test.mjs test/ilog.test.mjs test/store.test.mjs test/paths.test.mjs test/git.test.mjs test/sync.test.mjs test/tools.test.mjs test/dedup.test.mjs test/commands.test.mjs test/onboard.test.mjs test/delegation.test.mjs test/observer.test.mjs test/distill.test.mjs test/consolidate.test.mjs test/viz.test.mjs test/corpus.test.mjs test/llm-scope.test.mjs test/quality.test.mjs test/replay-gate.test.mjs test/depends-repair.test.mjs test/skill.test.mjs test/fast-lane.test.mjs test/legacy-import.test.mjs test/jev-config.test.mjs test/jev-gate.test.mjs test/jev-client.test.mjs test/jev-log.test.mjs test/jev-dual.test.mjs test/jev-fastgate.test.mjs test/zero-open-decay.test.mjs",
+    "test": "node --test test/yaml.test.mjs test/okf.test.mjs test/retrieval.test.mjs test/digest.test.mjs test/digest-package.test.mjs test/ilog.test.mjs test/store.test.mjs test/paths.test.mjs test/git.test.mjs test/sync.test.mjs test/tools.test.mjs test/dedup.test.mjs test/commands.test.mjs test/onboard.test.mjs test/delegation.test.mjs test/observer.test.mjs test/distill.test.mjs test/consolidate.test.mjs test/viz.test.mjs test/corpus.test.mjs test/llm-scope.test.mjs test/quality.test.mjs test/replay-gate.test.mjs test/depends-repair.test.mjs test/skill.test.mjs test/fast-lane.test.mjs test/legacy-import.test.mjs test/jev-config.test.mjs test/jev-gate.test.mjs test/jev-client.test.mjs test/jev-log.test.mjs test/jev-dual.test.mjs test/jev-fastgate.test.mjs test/zero-open-decay.test.mjs test/embedding.test.mjs test/embedding-index.test.mjs test/query-sanitize.test.mjs test/semantic-rerank.test.mjs test/inject-config.test.mjs test/distill-links.test.mjs test/store-links.test.mjs test/lesson-seams.test.mjs",
     "smoke": "node scripts/smoke-boot.mjs"
   },
   "dependencies": {},

package/src/config.ts

@@ -105,6 +105,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 type TopicsConfigValue = {
@@ -149,6 +171,16 @@ 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 const CONFIG_KEYS = [
@@ -186,6 +218,10 @@ export const CONFIG_KEYS = [
   'jevSecretFile',
   'jevLayaFallback',
   'jevLayaUrl',
+  'embeddingProvider',
+  'embeddingModel',
+  'packageMode',
+  'lessonInject',
 ] as const
 
 export type ConfigKey = (typeof CONFIG_KEYS)[number]
@@ -257,10 +293,23 @@ export function parseConfigValue(key: ConfigKey, raw: string): boolean | number
     }
     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
       if (raw === 'off' || raw === 'false') return false