@aiwayds/dsh-topics-memory 0.22.0 → 0.24.0

package/src/store.ts

@@ -18,6 +18,7 @@ import {
   appendFile,
   access,
   rm,
+  copyFile,
 } from 'node:fs/promises'
 import { readFileSync } from 'node:fs'
 import { constants as FsConstants } from 'node:fs'
@@ -38,19 +39,34 @@ export interface TopicMeta {
   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 const topicKindOf = 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 {
@@ -93,6 +109,15 @@ function sameStrings(a: readonly string[], b: readonly string[]): boolean {
   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 interface BundleStoreOptions {
   /** Override the stamped actor (tests). Defaults to `agent:dsh-topics-memory@<host>`. */
   actor?: string
@@ -348,9 +373,17 @@ 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: { slug: string; doc: okf.TopicDoc },
+    input: { slug: string; doc: okf.TopicDoc; links?: readonly string[] },
     opts: { message: string; actor?: string; created?: boolean },
   ): Promise<SaveResult> {
     return this.enqueue(async () => {
@@ -358,9 +391,22 @@ 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: string[] = []
+        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: okf.TopicDoc = {
         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)
@@ -388,6 +434,30 @@ export class BundleStore {
     })
   }
 
+  /**
+   * 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: string, opts: { message: string }): Promise<{ archivedTo: string; committed: boolean } | undefined> {
+    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 }
+    })
+  }
+
   private async regenerateIndex(): Promise<void> {    const metas = await this.listTopics()
     const entries: okf.IndexEntry[] = metas.map((m) => ({
       slug: m.slug,
@@ -453,9 +523,10 @@ export class BundleStore {
 
   async appendObservation(input: {
     kind: ObservationKind
-    source: 'model' | 'auto'
+    source: ObservationSource
     text: string
     sessionId?: string
+    by?: string
   }): Promise<Observation> {
     const obs: Observation = {
       id: `obs-${Date.now().toString(36)}-${randomUUID().slice(0, 8)}`,
@@ -466,6 +537,7 @@ export class BundleStore {
       distilled: false,
     }
     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.