@crewhaus/wiki-store 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md ADDED
@@ -0,0 +1,86 @@
1
+ # @crewhaus/wiki-store
2
+
3
+ v0.3.0 Goal 2 (design §3.1): the local, update-in-place **semantic memory
4
+ tier** — what the append-only fact store deliberately cannot be. Markdown
5
+ articles with YAML frontmatter under `.crewhaus/wiki/<spec>/`, versioned
6
+ forever, retrieved with hybrid ranking + link-graph expansion.
7
+
8
+ ```
9
+ .crewhaus/wiki/<spec>/
10
+ articles/<slug>.md # live version: YAML frontmatter + markdown body
11
+ versions/<slug>/<n>.md # immutable priors — supersede, never delete
12
+ index.json # slug → {title, tags, confidence, verified,
13
+ # version, updatedAt, links[], status}
14
+ .lock # advisory single-writer lock (§7.6)
15
+ ```
16
+
17
+ ```ts
18
+ import { createWikiStore } from "@crewhaus/wiki-store";
19
+ import { createEmbedder } from "@crewhaus/embedder";
20
+
21
+ const wiki = createWikiStore({
22
+ specName: "support-bot",
23
+ embedder: createEmbedder({ model: "mock/deterministic" }), // optional
24
+ });
25
+
26
+ await wiki.write({ slug: "csv-delimiters", title: "CSV delimiter conventions",
27
+ body: "…see [[eu-locale-rules]]\n\n## Sources\n- RFC 4180" });
28
+ const hits = await wiki.recall("csv delimiter", 6); // hybrid + one-hop
29
+ ```
30
+
31
+ ## The interface (design §3.1, verbatim)
32
+
33
+ `recall` / `search` / `get` / `write` / `list` / `related` / `setSignals` /
34
+ `stats` — plus one extension: `semanticSearch?` exists when an `embedder`
35
+ was supplied (the thredz-parity `wiki_semantic_search` tool needs a pure
36
+ cosine ranking with a `minScore` floor, which the fused recall score cannot
37
+ express).
38
+
39
+ ## Optimistic concurrency — the Thredz PATCH contract
40
+
41
+ `write()` upserts by slug. Updating an existing article REQUIRES
42
+ `expectedVersion` equal to its current version; a mismatch throws
43
+ `WikiVersionConflictError` whose `conflictCode` (and message) carry the
44
+ literal `stale_article_version` — the same contract as Thredz's HTTP 409,
45
+ so skills behave identically on both backends: re-read with `get`, then
46
+ re-apply the edit. Every content edit copies the outgoing file into
47
+ `versions/<slug>/<n>.md` FIRST (supersede, never delete — Theanine), then
48
+ lands atomically (tmp+rename).
49
+
50
+ ## Retrieval
51
+
52
+ - **Hybrid BM25 + embeddings via RRF (k=60)** — the same recipe as
53
+ memory-store's PR-6 hybrid recall. No embedder ⇒ BM25-only (offline
54
+ default, regression-pinned).
55
+ - **Contextual chunk headers** — every article is indexed as
56
+ `title\n[tags: …]\n\nbody`.
57
+ - **One-hop link expansion** with a documented re-rank rule: primary
58
+ candidates keep their reciprocal-rank vote `1/(60+rank)`; every one-hop
59
+ `[[wikilink]]` neighbor (either edge direction) of a top-k seed gains a
60
+ **half-weight** link vote `0.5/(60+bestSeedRank)`; votes sum, ties break
61
+ by slug. Half weight means a link corroborates but never displaces a
62
+ genuine match — while a linked-but-lexically-unrelated article still
63
+ surfaces when the query has fewer than k solid matches.
64
+
65
+ ## Semantics worth knowing
66
+
67
+ - `list({ staleFirst: true })` sorts `updatedAt` ascending — the REFLECT
68
+ pass order (matches thredz `wiki_list` sort=updated order=asc).
69
+ - `related(slug)` = shared tags (1 each) + link edges (2 each direction) +
70
+ cosine similarity when an embedder is present.
71
+ - `setSignals` (verified/confidence) is metadata-only: **no version bump,
72
+ no snapshot**. A content `write()` RESETS `verified` to false — a new
73
+ version is a new, not-yet-fact-checked claim.
74
+ - `index.json` is a derived cache: reads fall back to a scan of
75
+ `articles/` when it is missing or corrupt, and every mutation rewrites
76
+ it from that authoritative scan (crash-safe by construction).
77
+
78
+ ## Concurrency + tenancy
79
+
80
+ Mutations run under the §7.6 advisory `.lock`: wait up to 2 s → steal a
81
+ lock whose mtime is >30 s stale (with a `lock_stolen` warning) → fail
82
+ naming the holder pid. Reads never take the lock; atomic writes mean a
83
+ reader never observes a torn file. Under a tenant context (ambient
84
+ `withTenant` or the explicit `tenant` option) every resolved path is
85
+ fenced fail-closed against the tenant's root (CWE-1230), and the default
86
+ root becomes `<tenantRoot>/wiki`.
@@ -0,0 +1,192 @@
1
+ import { CrewhausError } from "@crewhaus/errors";
2
+ import { type Tenant } from "@crewhaus/tenancy";
3
+ import { type AcquireLockOptions } from "./lock";
4
+ export { type AcquireLockOptions, type LockHandle, type LockPolicy, DEFAULT_LOCK_POLICY, WikiLockError, acquireLock, withLock, } from "./lock";
5
+ export declare const DEFAULT_ROOT_DIR = ".crewhaus/wiki";
6
+ /** The Thredz-parity conflict code carried by `WikiVersionConflictError`. */
7
+ export declare const STALE_ARTICLE_VERSION = "stale_article_version";
8
+ export declare class WikiStoreError extends CrewhausError {
9
+ readonly name: string;
10
+ constructor(message: string, cause?: unknown);
11
+ }
12
+ /**
13
+ * Optimistic-concurrency conflict — the local twin of Thredz's HTTP 409
14
+ * `stale_article_version`. `conflictCode` is the machine-checkable code
15
+ * (CrewhausError's own `code` is the coarse family union); the message also
16
+ * carries the literal so string-matching callers behave like Thredz ones.
17
+ */
18
+ export declare class WikiVersionConflictError extends CrewhausError {
19
+ readonly name = "WikiVersionConflictError";
20
+ readonly conflictCode = "stale_article_version";
21
+ readonly slug: string;
22
+ readonly expectedVersion: number | undefined;
23
+ readonly currentVersion: number | undefined;
24
+ constructor(slug: string, expectedVersion: number | undefined, currentVersion: number | undefined);
25
+ }
26
+ export type WikiArticleStatus = "draft" | "published" | "review" | "archived";
27
+ /** Who wrote this VERSION of the article (prior writers live in versions/). */
28
+ export type WikiCreatedBy = {
29
+ readonly sessionId: string;
30
+ /** `formatAgentIdentity()`-style string, when a sub-agent/role wrote it. */
31
+ readonly agentIdentity?: string;
32
+ };
33
+ /** The YAML frontmatter of an article file (design §3.1). */
34
+ export type WikiFrontmatter = {
35
+ readonly slug: string;
36
+ readonly title: string;
37
+ readonly tags: readonly string[];
38
+ /** 0–1 confidence in the knowledge. */
39
+ readonly confidence: number;
40
+ /** Fact-checked against a primary source (set via `setSignals`; RESET to
41
+ * false by every content `write` — a new version is a new claim). */
42
+ readonly verified: boolean;
43
+ /** 1-based, bumped on every content write. */
44
+ readonly version: number;
45
+ readonly sources: readonly string[];
46
+ /** The version number this one superseded (absent on version 1). */
47
+ readonly supersedes?: number;
48
+ readonly createdBy?: WikiCreatedBy;
49
+ readonly status: WikiArticleStatus;
50
+ readonly createdAt: string;
51
+ readonly updatedAt: string;
52
+ };
53
+ export type WikiArticle = WikiFrontmatter & {
54
+ readonly body: string;
55
+ };
56
+ /** One `index.json` entry, plus its slug — the list/search/related unit. */
57
+ export type WikiRef = {
58
+ readonly slug: string;
59
+ readonly title: string;
60
+ readonly tags: readonly string[];
61
+ readonly confidence: number;
62
+ readonly verified: boolean;
63
+ readonly version: number;
64
+ readonly updatedAt: string;
65
+ /** Out-links extracted from `[[wikilinks]]` in the body (normalized slugs). */
66
+ readonly links: readonly string[];
67
+ readonly status: WikiArticleStatus;
68
+ };
69
+ export type WikiHit = {
70
+ readonly ref: WikiRef;
71
+ /** The fused re-rank score (RRF vote sum — see the re-rank rule above). */
72
+ readonly score: number;
73
+ readonly body: string;
74
+ /** `"match"` = positive primary (lexical/semantic) score; `"link"` =
75
+ * surfaced purely by one-hop link expansion. */
76
+ readonly via: "match" | "link";
77
+ };
78
+ export type WikiWrite = {
79
+ readonly slug: string;
80
+ readonly title: string;
81
+ readonly body: string;
82
+ readonly tags?: readonly string[];
83
+ /** 0–1. Create default 0.5; omitted on update = keep the prior value. */
84
+ readonly confidence?: number;
85
+ readonly sources?: readonly string[];
86
+ /** Create default "published"; omitted on update = keep the prior value. */
87
+ readonly status?: WikiArticleStatus;
88
+ /**
89
+ * Optimistic concurrency (the Thredz PATCH contract): REQUIRED and equal
90
+ * to the current version when the slug exists; omit (or pass 0) to
91
+ * create. Mismatch → `WikiVersionConflictError` (`stale_article_version`).
92
+ */
93
+ readonly expectedVersion?: number;
94
+ readonly createdBy?: WikiCreatedBy;
95
+ };
96
+ export type WikiListOptions = {
97
+ /** Sort updatedAt ASCENDING (stalest first — the REFLECT pass order).
98
+ * Default false = updatedAt descending. */
99
+ readonly staleFirst?: boolean;
100
+ /** Keep only articles carrying EVERY listed tag. */
101
+ readonly tags?: readonly string[];
102
+ /** Keep only articles with this status ("all" = no filter, the default). */
103
+ readonly status?: WikiArticleStatus | "all";
104
+ };
105
+ export type WikiSignals = {
106
+ readonly verified?: boolean;
107
+ readonly confidence?: number;
108
+ };
109
+ export type WikiStats = {
110
+ readonly articles: number;
111
+ readonly byStatus: Readonly<Record<WikiArticleStatus, number>>;
112
+ /** Immutable snapshots under versions/ (supersede-never-delete depth). */
113
+ readonly priorVersions: number;
114
+ readonly uniqueTags: number;
115
+ readonly verified: number;
116
+ /** Mean confidence across articles (0 when the wiki is empty). */
117
+ readonly averageConfidence: number;
118
+ /** Total out-link edges in the index. */
119
+ readonly links: number;
120
+ };
121
+ export type WikiRelatedRef = WikiRef & {
122
+ /** tag overlap + link adjacency (+ cosine similarity with an embedder). */
123
+ readonly relatedScore: number;
124
+ };
125
+ /**
126
+ * Minimal structural interface for the hybrid-recall embedder — the same
127
+ * shape memory-store uses. `@crewhaus/embedder`'s `Embedder` satisfies it
128
+ * (use `createEmbedder({ model: "mock/deterministic" })` offline).
129
+ */
130
+ export interface WikiEmbedder {
131
+ embed(texts: ReadonlyArray<string>): Promise<number[][]>;
132
+ }
133
+ /** The design-§3.1 interface, verbatim (recall/search/get/write/list/related/setSignals/stats). */
134
+ export interface WikiStore {
135
+ /** Hybrid-ranked top-k WITH bodies (the recall-before-act bundle), after
136
+ * one-hop link expansion. Archived articles are excluded. */
137
+ recall(query: string, k?: number): Promise<readonly WikiHit[]>;
138
+ /** Keyword/full-text (BM25) refs, best first. No expansion, no embedder —
139
+ * exact terms, names, numbers. Archived articles are excluded. */
140
+ search(query: string): Promise<readonly WikiRef[]>;
141
+ get(slug: string): Promise<WikiArticle | null>;
142
+ /** Upsert by slug with the optimistic version check (see `WikiWrite`).
143
+ * Every edit snapshots the prior file into versions/ FIRST. */
144
+ write(input: WikiWrite): Promise<{
145
+ slug: string;
146
+ version: number;
147
+ }>;
148
+ list(opts?: WikiListOptions): Promise<readonly WikiRef[]>;
149
+ /** Tag overlap + link adjacency (+ embedding similarity when available). */
150
+ related(slug: string): Promise<readonly WikiRelatedRef[]>;
151
+ /** Metadata-only quality signals — no version bump, no snapshot. */
152
+ setSignals(slug: string, signals: WikiSignals): Promise<void>;
153
+ stats(): Promise<WikiStats>;
154
+ /**
155
+ * Cosine-similarity-only ranking (a `minScore` floor, default 0.05) —
156
+ * present ONLY when the store was constructed with an `embedder`. This is
157
+ * the one member beyond the designed eight: the thredz-parity
158
+ * `wiki_semantic_search` tool needs a pure semantic ranking with a
159
+ * similarity floor, which the fused `recall` score cannot express.
160
+ * Without an embedder the tool degrades to keyword search (the same
161
+ * degradation Thredz applies on keyword-only plans).
162
+ */
163
+ semanticSearch?(query: string, k?: number, minScore?: number): Promise<readonly WikiHit[]>;
164
+ /** Diagnostic: where on disk this store lives. */
165
+ path(): string;
166
+ }
167
+ export type WikiStoreOptions = {
168
+ readonly specName: string;
169
+ /** Default `.crewhaus/wiki` (or `<tenantRoot>/wiki` under a tenant). */
170
+ readonly rootDir?: string;
171
+ readonly now?: () => Date;
172
+ /** Enables the hybrid (BM25 + embedding RRF) primary ranking and
173
+ * `semanticSearch`. Absent → BM25-only primary ranking. */
174
+ readonly embedder?: WikiEmbedder;
175
+ /** Explicit tenant to fence against (in addition to any ambient
176
+ * `withTenant` context, which is always honored). */
177
+ readonly tenant?: Tenant;
178
+ /** Lock policy overrides + warning sink (lock steals, §7.6). */
179
+ readonly lock?: AcquireLockOptions;
180
+ };
181
+ /** Extract `[[wikilink]]` targets from a body, normalized to slugs:
182
+ * `[[Some Page|label]]` → `some-page`. Invalid targets and duplicates are
183
+ * dropped; `self` (when given) is excluded. Exported for tests. */
184
+ export declare function extractWikilinks(body: string, self?: string): string[];
185
+ /** Serialize an article to `---\n<yaml>\n---\n\n<body>\n`. Exported for tests. */
186
+ export declare function serializeArticle(article: WikiArticle): string;
187
+ /** Parse an article file. Throws `WikiStoreError` on a malformed file. */
188
+ export declare function parseArticle(raw: string): WikiArticle;
189
+ /** The contextual chunk header (design §3.1): title + tags prefixed to the
190
+ * indexed text so retrieval sees each chunk in context. Exported for tests. */
191
+ export declare function indexedText(article: Pick<WikiArticle, "title" | "tags" | "body">): string;
192
+ export declare function createWikiStore(opts: WikiStoreOptions): WikiStore;
package/dist/index.js ADDED
@@ -0,0 +1,839 @@
1
+ /**
2
+ * v0.3.0 Goal 2 — `wiki-store` (design §3.1, PR 9).
3
+ *
4
+ * The update-in-place SEMANTIC memory tier — what the append-only
5
+ * memory-store deliberately cannot be. Human-readable markdown articles
6
+ * under `.crewhaus/wiki/<specName>/`:
7
+ *
8
+ * articles/<slug>.md — YAML frontmatter + markdown body (the live
9
+ * version of each article)
10
+ * versions/<slug>/<n>.md — immutable prior versions: every edit copies
11
+ * the outgoing file here FIRST (supersede,
12
+ * never delete — Theanine)
13
+ * index.json — slug → {title, tags, confidence, verified,
14
+ * version, updatedAt, links[], status} — a
15
+ * derived cache, always rebuildable from the
16
+ * articles (crash-safe by construction)
17
+ * .lock — advisory single-writer lock (see lock.ts;
18
+ * wait 2s → steal >30s stale → fail with pid)
19
+ *
20
+ * ## Optimistic concurrency (the Thredz PATCH contract)
21
+ *
22
+ * `write()` is an upsert by slug. When the slug already exists the caller
23
+ * MUST pass `expectedVersion` equal to the article's current version; a
24
+ * mismatch (or an omitted version on an existing article) throws
25
+ * `WikiVersionConflictError` carrying the literal code
26
+ * `stale_article_version` — the same contract as Thredz's PATCH
27
+ * (409 stale_article_version), so skills behave identically on the local
28
+ * and Thredz backends: re-read with `get`, then re-apply the edit.
29
+ *
30
+ * ## Retrieval (design §3.1 — the evidence base's strongest lever)
31
+ *
32
+ * Hybrid BM25 + embedding recall with reciprocal-rank fusion (RRF, k=60 —
33
+ * the same math as memory-store's PR-6 hybrid recall), over CONTEXTUAL
34
+ * chunks: the indexed text of every article is its body prefixed with a
35
+ * `title` + `[tags: …]` header, per the contextual-retrieval evidence.
36
+ * Without an `embedder` the primary ranking is BM25-only (offline
37
+ * default); with one (use `mock/…` from @crewhaus/embedder for tests) the
38
+ * primary ranking fuses BM25 and cosine-similarity ranks.
39
+ *
40
+ * ### One-hop link expansion + the re-rank rule
41
+ *
42
+ * After the primary ranking, `recall()` takes the top-k seeds, pulls every
43
+ * article that shares an `index.json` link edge with a seed (EITHER
44
+ * direction — [[wikilink]] out-links are indexed, so in-links are the
45
+ * reverse lookup), and re-ranks the union. THE RE-RANK RULE:
46
+ *
47
+ * 1. every candidate in the primary ranking keeps its reciprocal-rank
48
+ * vote — rank i contributes 1/(60+i);
49
+ * 2. every one-hop neighbor of a seed additionally receives a
50
+ * HALF-WEIGHT link vote, 0.5/(60 + bestSeedRank), where bestSeedRank
51
+ * is the rank of the best-ranked seed it shares an edge with;
52
+ * 3. votes sum per article; sort descending, ties broken by slug; the
53
+ * top k win.
54
+ *
55
+ * Half weight is the load-bearing choice: a link is corroboration, not a
56
+ * match, so a linked-but-lexically-unrelated neighbor can never displace
57
+ * the seed that pulled it in (0.5/(60+r) < 1/(60+r)) nor any primary
58
+ * match ranked at or above its seed — but it DOES surface whenever the
59
+ * query yields fewer than k solid matches, which is exactly the failure
60
+ * mode one-hop expansion exists to fix. Deterministic, pinned by test.
61
+ *
62
+ * ## Signals vs content
63
+ *
64
+ * `setSignals()` (verified / confidence) is a metadata-only mutation: it
65
+ * does NOT bump the version and does NOT snapshot (the body is untouched)
66
+ * — mirroring Thredz's separate signals endpoint. A content `write()`, by
67
+ * contrast, RESETS `verified` to false: the new version is a new claim
68
+ * that has not been fact-checked yet (re-verify via `setSignals`).
69
+ *
70
+ * ## Tenant fencing
71
+ *
72
+ * Same fail-closed path rules session-store enforces (CWE-1230): with a
73
+ * tenant context active (ambient `withTenant` or the explicit `tenant`
74
+ * option), any resolved path outside the tenant's root throws before any
75
+ * IO happens. The default root under a tenant is `<tenantRoot>/wiki`.
76
+ */
77
+ import { existsSync } from "node:fs";
78
+ import { mkdir, readFile, readdir, rename, writeFile } from "node:fs/promises";
79
+ import { dirname, join, resolve } from "node:path";
80
+ import { CrewhausError } from "@crewhaus/errors";
81
+ import { assertSamePath, currentTenantContext } from "@crewhaus/tenancy";
82
+ import YAML from "yaml";
83
+ import { withLock } from "./lock";
84
+ export { DEFAULT_LOCK_POLICY, WikiLockError, acquireLock, withLock, } from "./lock";
85
+ export const DEFAULT_ROOT_DIR = ".crewhaus/wiki";
86
+ /** The Thredz-parity conflict code carried by `WikiVersionConflictError`. */
87
+ export const STALE_ARTICLE_VERSION = "stale_article_version";
88
+ /** Reciprocal-rank-fusion constant (the standard k=60, matching memory-store). */
89
+ const RRF_K = 60;
90
+ const SPEC_NAME_REGEX = /^[a-zA-Z0-9_\-.]+$/;
91
+ /** Slugs are kebab-case AND double as file names — fail-closed on anything
92
+ * that could traverse (`..`, `/`, uppercase, spaces). */
93
+ const SLUG_REGEX = /^[a-z0-9][a-z0-9-]{0,127}$/;
94
+ const WIKILINK_REGEX = /\[\[([^\]]+)\]\]/g;
95
+ export class WikiStoreError extends CrewhausError {
96
+ name = "WikiStoreError";
97
+ constructor(message, cause) {
98
+ super("config", message, cause);
99
+ }
100
+ }
101
+ /**
102
+ * Optimistic-concurrency conflict — the local twin of Thredz's HTTP 409
103
+ * `stale_article_version`. `conflictCode` is the machine-checkable code
104
+ * (CrewhausError's own `code` is the coarse family union); the message also
105
+ * carries the literal so string-matching callers behave like Thredz ones.
106
+ */
107
+ export class WikiVersionConflictError extends CrewhausError {
108
+ name = "WikiVersionConflictError";
109
+ conflictCode = STALE_ARTICLE_VERSION;
110
+ slug;
111
+ expectedVersion;
112
+ currentVersion;
113
+ constructor(slug, expectedVersion, currentVersion) {
114
+ super("runtime", currentVersion === undefined
115
+ ? `${STALE_ARTICLE_VERSION}: no article "${slug}" exists (expected version ${expectedVersion}) — omit expectedVersion (or pass 0) to create it`
116
+ : `${STALE_ARTICLE_VERSION}: article "${slug}" is at version ${currentVersion}, not ${expectedVersion ?? "(none passed)"} — re-read it with get(), then re-apply your edit`);
117
+ this.slug = slug;
118
+ this.expectedVersion = expectedVersion;
119
+ this.currentVersion = currentVersion;
120
+ }
121
+ }
122
+ const ARTICLE_STATUSES = [
123
+ "draft",
124
+ "published",
125
+ "review",
126
+ "archived",
127
+ ];
128
+ // ---------------------------------------------------------------------------
129
+ // frontmatter + wikilinks
130
+ // ---------------------------------------------------------------------------
131
+ /** Extract `[[wikilink]]` targets from a body, normalized to slugs:
132
+ * `[[Some Page|label]]` → `some-page`. Invalid targets and duplicates are
133
+ * dropped; `self` (when given) is excluded. Exported for tests. */
134
+ export function extractWikilinks(body, self) {
135
+ const out = [];
136
+ const seen = new Set();
137
+ for (const match of body.matchAll(WIKILINK_REGEX)) {
138
+ const inner = match[1] ?? "";
139
+ const target = (inner.split("|")[0] ?? "").trim().toLowerCase().replace(/\s+/g, "-");
140
+ if (!SLUG_REGEX.test(target))
141
+ continue;
142
+ if (target === self)
143
+ continue;
144
+ if (seen.has(target))
145
+ continue;
146
+ seen.add(target);
147
+ out.push(target);
148
+ }
149
+ return out;
150
+ }
151
+ /** Serialize an article to `---\n<yaml>\n---\n\n<body>\n`. Exported for tests. */
152
+ export function serializeArticle(article) {
153
+ const { body, ...frontmatter } = article;
154
+ const fm = {
155
+ slug: frontmatter.slug,
156
+ title: frontmatter.title,
157
+ tags: [...frontmatter.tags],
158
+ confidence: frontmatter.confidence,
159
+ verified: frontmatter.verified,
160
+ version: frontmatter.version,
161
+ sources: [...frontmatter.sources],
162
+ ...(frontmatter.supersedes !== undefined ? { supersedes: frontmatter.supersedes } : {}),
163
+ ...(frontmatter.createdBy !== undefined
164
+ ? {
165
+ createdBy: {
166
+ sessionId: frontmatter.createdBy.sessionId,
167
+ ...(frontmatter.createdBy.agentIdentity !== undefined
168
+ ? { agentIdentity: frontmatter.createdBy.agentIdentity }
169
+ : {}),
170
+ },
171
+ }
172
+ : {}),
173
+ status: frontmatter.status,
174
+ createdAt: frontmatter.createdAt,
175
+ updatedAt: frontmatter.updatedAt,
176
+ };
177
+ const yamlText = YAML.stringify(fm).trimEnd();
178
+ return `---\n${yamlText}\n---\n\n${body.replace(/\s+$/, "")}\n`;
179
+ }
180
+ /** Parse an article file. Throws `WikiStoreError` on a malformed file. */
181
+ export function parseArticle(raw) {
182
+ if (!raw.startsWith("---\n")) {
183
+ throw new WikiStoreError("article file is missing its YAML frontmatter block");
184
+ }
185
+ const end = raw.indexOf("\n---", 4);
186
+ if (end === -1) {
187
+ throw new WikiStoreError("article frontmatter block is unterminated (no closing ---)");
188
+ }
189
+ const yamlText = raw.slice(4, end + 1);
190
+ const rest = raw.slice(end + 4);
191
+ const body = rest.replace(/^\r?\n+/, "").replace(/\s+$/, "");
192
+ let fm;
193
+ try {
194
+ fm = YAML.parse(yamlText);
195
+ }
196
+ catch (err) {
197
+ throw new WikiStoreError(`article frontmatter is not valid YAML: ${err.message}`, err);
198
+ }
199
+ if (typeof fm !== "object" || fm === null) {
200
+ throw new WikiStoreError("article frontmatter must be a YAML mapping");
201
+ }
202
+ const v = fm;
203
+ const strArr = (x) => Array.isArray(x) ? x.filter((t) => typeof t === "string") : [];
204
+ if (typeof v["slug"] !== "string" || !SLUG_REGEX.test(v["slug"])) {
205
+ throw new WikiStoreError("article frontmatter has a missing/invalid slug");
206
+ }
207
+ if (typeof v["title"] !== "string" || v["title"] === "") {
208
+ throw new WikiStoreError(`article "${v["slug"]}" frontmatter has a missing title`);
209
+ }
210
+ if (typeof v["version"] !== "number" || !Number.isInteger(v["version"]) || v["version"] < 1) {
211
+ throw new WikiStoreError(`article "${v["slug"]}" frontmatter has a missing/invalid version`);
212
+ }
213
+ const status = ARTICLE_STATUSES.includes(v["status"])
214
+ ? v["status"]
215
+ : "published";
216
+ const createdByRaw = v["createdBy"];
217
+ let createdBy;
218
+ if (typeof createdByRaw === "object" && createdByRaw !== null) {
219
+ const cb = createdByRaw;
220
+ if (typeof cb["sessionId"] === "string") {
221
+ createdBy = {
222
+ sessionId: cb["sessionId"],
223
+ ...(typeof cb["agentIdentity"] === "string" ? { agentIdentity: cb["agentIdentity"] } : {}),
224
+ };
225
+ }
226
+ }
227
+ return {
228
+ slug: v["slug"],
229
+ title: v["title"],
230
+ tags: strArr(v["tags"]),
231
+ confidence: clamp01(typeof v["confidence"] === "number" ? v["confidence"] : 0.5),
232
+ verified: v["verified"] === true,
233
+ version: v["version"],
234
+ sources: strArr(v["sources"]),
235
+ ...(typeof v["supersedes"] === "number" ? { supersedes: v["supersedes"] } : {}),
236
+ ...(createdBy !== undefined ? { createdBy } : {}),
237
+ status,
238
+ createdAt: typeof v["createdAt"] === "string" ? v["createdAt"] : "1970-01-01T00:00:00.000Z",
239
+ updatedAt: typeof v["updatedAt"] === "string" ? v["updatedAt"] : "1970-01-01T00:00:00.000Z",
240
+ body,
241
+ };
242
+ }
243
+ function clamp01(n) {
244
+ if (Number.isNaN(n))
245
+ return 0.5;
246
+ return Math.max(0, Math.min(1, n));
247
+ }
248
+ /** The contextual chunk header (design §3.1): title + tags prefixed to the
249
+ * indexed text so retrieval sees each chunk in context. Exported for tests. */
250
+ export function indexedText(article) {
251
+ const tagLine = article.tags.length > 0 ? `[tags: ${article.tags.join(", ")}]\n` : "";
252
+ return `${article.title}\n${tagLine}\n${article.body}`;
253
+ }
254
+ // ---------------------------------------------------------------------------
255
+ // BM25 (the exact memory-store math, over article docs)
256
+ // ---------------------------------------------------------------------------
257
+ function tokenize(text) {
258
+ return text
259
+ .toLowerCase()
260
+ .split(/[^a-z0-9]+/)
261
+ .filter((t) => t.length > 0);
262
+ }
263
+ function bm25Rank(docs, query) {
264
+ const queryTerms = tokenize(query);
265
+ if (queryTerms.length === 0 || docs.length === 0)
266
+ return [];
267
+ const k1 = 1.5;
268
+ const b = 0.75;
269
+ const tokenized = docs.map((d) => ({ slug: d.slug, terms: tokenize(d.text) }));
270
+ const N = tokenized.length;
271
+ const avgdl = tokenized.reduce((sum, d) => sum + d.terms.length, 0) / Math.max(1, N);
272
+ const df = new Map();
273
+ for (const t of new Set(queryTerms)) {
274
+ df.set(t, tokenized.filter((d) => d.terms.includes(t)).length);
275
+ }
276
+ const results = [];
277
+ for (const d of tokenized) {
278
+ let score = 0;
279
+ for (const t of queryTerms) {
280
+ const tf = d.terms.filter((x) => x === t).length;
281
+ if (tf === 0)
282
+ continue;
283
+ const dfi = df.get(t) ?? 0;
284
+ const idf = Math.log((N - dfi + 0.5) / (dfi + 0.5) + 1);
285
+ const dl = d.terms.length;
286
+ const norm = tf * (k1 + 1);
287
+ const denom = tf + k1 * (1 - b + (b * dl) / Math.max(1, avgdl));
288
+ score += idf * (norm / denom);
289
+ }
290
+ if (score > 0)
291
+ results.push({ slug: d.slug, score });
292
+ }
293
+ results.sort((a, b2) => b2.score - a.score || a.slug.localeCompare(b2.slug));
294
+ return results;
295
+ }
296
+ function cosineSimilarity(a, b) {
297
+ const n = Math.min(a.length, b.length);
298
+ let dot = 0;
299
+ let na = 0;
300
+ let nb = 0;
301
+ for (let i = 0; i < n; i++) {
302
+ const x = a[i] ?? 0;
303
+ const y = b[i] ?? 0;
304
+ dot += x * y;
305
+ na += x * x;
306
+ nb += y * y;
307
+ }
308
+ if (na === 0 || nb === 0)
309
+ return 0;
310
+ return dot / (Math.sqrt(na) * Math.sqrt(nb));
311
+ }
312
+ export function createWikiStore(opts) {
313
+ if (!opts.specName) {
314
+ throw new WikiStoreError("specName is required");
315
+ }
316
+ if (!SPEC_NAME_REGEX.test(opts.specName)) {
317
+ throw new WikiStoreError(`invalid specName "${opts.specName}" — must match [a-zA-Z0-9_\\-.]+`);
318
+ }
319
+ const now = opts.now ?? (() => new Date());
320
+ const embedder = opts.embedder;
321
+ // Tenant fencing (§2.7 / session-store rules): honor BOTH an explicit
322
+ // `tenant` option and the ambient AsyncLocalStorage context. With a tenant
323
+ // present, any resolved path outside the tenant's root fails closed
324
+ // (CWE-1230). The fence root is the tenant's directory (the parent of its
325
+ // sessionRoot), so the default wiki layout `<tenantRoot>/wiki/...` passes.
326
+ function tenantRootOf(tenant) {
327
+ return resolve(tenant.sessionRoot, "..");
328
+ }
329
+ function fence(absPath) {
330
+ if (opts.tenant !== undefined)
331
+ assertSamePath(absPath, tenantRootOf(opts.tenant));
332
+ const ctx = currentTenantContext();
333
+ if (ctx !== undefined)
334
+ assertSamePath(absPath, tenantRootOf(ctx.tenant));
335
+ return absPath;
336
+ }
337
+ const constructionTenant = opts.tenant ?? currentTenantContext()?.tenant;
338
+ const rootDir = opts.rootDir ??
339
+ (constructionTenant !== undefined
340
+ ? join(tenantRootOf(constructionTenant), "wiki")
341
+ : DEFAULT_ROOT_DIR);
342
+ const storeDir = resolve(rootDir, opts.specName);
343
+ const articlesDir = join(storeDir, "articles");
344
+ const versionsDir = join(storeDir, "versions");
345
+ const indexPath = join(storeDir, "index.json");
346
+ const lockPath = join(storeDir, ".lock");
347
+ // Embedding cache. Keyed by `slug@version` — a version bump re-embeds,
348
+ // an unchanged article never does (within one store instance).
349
+ const embeddingCache = new Map();
350
+ function locked(fn) {
351
+ return withLock(fence(lockPath), fn, opts.lock ?? {});
352
+ }
353
+ function validateSlug(slug) {
354
+ if (typeof slug !== "string" || !SLUG_REGEX.test(slug)) {
355
+ throw new WikiStoreError(`invalid slug "${slug}" — must be kebab-case ([a-z0-9][a-z0-9-]*, max 128 chars)`);
356
+ }
357
+ return slug;
358
+ }
359
+ function articlePath(slug) {
360
+ return fence(join(articlesDir, `${slug}.md`));
361
+ }
362
+ async function atomicWrite(absPath, content) {
363
+ fence(absPath);
364
+ await mkdir(dirname(absPath), { recursive: true });
365
+ const tmpPath = `${absPath}.tmp`;
366
+ await writeFile(tmpPath, content, { mode: 0o600 });
367
+ await rename(tmpPath, absPath);
368
+ }
369
+ async function readArticle(slug) {
370
+ const p = articlePath(slug);
371
+ if (!existsSync(p))
372
+ return null;
373
+ let raw;
374
+ try {
375
+ raw = await readFile(p, "utf8");
376
+ }
377
+ catch {
378
+ return null;
379
+ }
380
+ return parseArticle(raw);
381
+ }
382
+ async function listArticleSlugs() {
383
+ fence(articlesDir);
384
+ let entries;
385
+ try {
386
+ entries = await readdir(articlesDir);
387
+ }
388
+ catch {
389
+ return [];
390
+ }
391
+ return entries
392
+ .filter((f) => f.endsWith(".md") && SLUG_REGEX.test(f.slice(0, -3)))
393
+ .map((f) => f.slice(0, -3))
394
+ .sort();
395
+ }
396
+ function toIndexEntry(article) {
397
+ return {
398
+ title: article.title,
399
+ tags: [...article.tags],
400
+ confidence: article.confidence,
401
+ verified: article.verified,
402
+ version: article.version,
403
+ updatedAt: article.updatedAt,
404
+ links: extractWikilinks(article.body, article.slug),
405
+ status: article.status,
406
+ };
407
+ }
408
+ /** Rebuild the index from the articles on disk — the authoritative source.
409
+ * index.json is only ever a cache of this scan. */
410
+ async function rebuildIndex() {
411
+ const articles = {};
412
+ for (const slug of await listArticleSlugs()) {
413
+ try {
414
+ const article = await readArticle(slug);
415
+ if (article !== null)
416
+ articles[slug] = toIndexEntry(article);
417
+ }
418
+ catch {
419
+ // A malformed article never blocks the rest of the wiki.
420
+ }
421
+ }
422
+ return { version: 1, articles };
423
+ }
424
+ function isIndexFile(value) {
425
+ if (typeof value !== "object" || value === null)
426
+ return false;
427
+ const v = value;
428
+ return v["version"] === 1 && typeof v["articles"] === "object" && v["articles"] !== null;
429
+ }
430
+ /** Load index.json; on a missing/corrupt file, rebuild from the articles
431
+ * (the crash-safe guarantee: the index is always derivable). */
432
+ async function loadIndex() {
433
+ fence(indexPath);
434
+ if (existsSync(indexPath)) {
435
+ try {
436
+ const parsed = JSON.parse(await readFile(indexPath, "utf8"));
437
+ if (isIndexFile(parsed))
438
+ return parsed;
439
+ }
440
+ catch {
441
+ // fall through to rebuild
442
+ }
443
+ }
444
+ return rebuildIndex();
445
+ }
446
+ async function persistIndex(index) {
447
+ await atomicWrite(indexPath, `${JSON.stringify(index, null, 2)}\n`);
448
+ }
449
+ function refsOf(index) {
450
+ return Object.entries(index.articles)
451
+ .map(([slug, entry]) => ({ slug, ...entry }))
452
+ .sort((a, b) => a.slug.localeCompare(b.slug));
453
+ }
454
+ /** slug@version-cached embeddings of the given docs' indexed text. */
455
+ async function embeddingsFor(docs) {
456
+ const out = new Map();
457
+ if (embedder === undefined)
458
+ return out;
459
+ const missing = docs.filter((d) => !embeddingCache.has(`${d.slug}@${d.version}`));
460
+ if (missing.length > 0) {
461
+ const vectors = await embedder.embed(missing.map((d) => d.text));
462
+ missing.forEach((d, i) => {
463
+ const v = vectors[i];
464
+ if (v !== undefined)
465
+ embeddingCache.set(`${d.slug}@${d.version}`, v);
466
+ });
467
+ }
468
+ for (const d of docs) {
469
+ const v = embeddingCache.get(`${d.slug}@${d.version}`);
470
+ if (v !== undefined)
471
+ out.set(d.slug, v);
472
+ }
473
+ return out;
474
+ }
475
+ /** Non-archived articles with their contextual indexed text + bodies. */
476
+ async function recallDocs(index) {
477
+ const docs = [];
478
+ for (const ref of refsOf(index)) {
479
+ if (ref.status === "archived")
480
+ continue;
481
+ const article = await readArticle(ref.slug);
482
+ if (article === null)
483
+ continue;
484
+ docs.push({
485
+ slug: ref.slug,
486
+ version: ref.version,
487
+ text: indexedText(article),
488
+ body: article.body,
489
+ ref,
490
+ });
491
+ }
492
+ return docs;
493
+ }
494
+ /**
495
+ * The primary ranking: BM25 alone, or (with an embedder) the RRF fusion
496
+ * of the BM25 ranking and the cosine-similarity ranking — the exact
497
+ * memory-store PR-6 recipe (k=60, candidates = union of positive matches).
498
+ */
499
+ async function primaryRank(docs, query) {
500
+ const bm = bm25Rank(docs, query);
501
+ if (embedder === undefined)
502
+ return bm;
503
+ const [queryVec] = await embedder.embed([query]);
504
+ const vecs = await embeddingsFor(docs);
505
+ const simRanked = [];
506
+ if (queryVec !== undefined) {
507
+ for (const d of docs) {
508
+ const v = vecs.get(d.slug);
509
+ if (v === undefined)
510
+ continue;
511
+ const sim = cosineSimilarity(queryVec, v);
512
+ if (sim > 0)
513
+ simRanked.push({ slug: d.slug, sim });
514
+ }
515
+ simRanked.sort((a, b) => b.sim - a.sim || a.slug.localeCompare(b.slug));
516
+ }
517
+ const fused = new Map();
518
+ const vote = (slug, rank) => {
519
+ fused.set(slug, (fused.get(slug) ?? 0) + 1 / (RRF_K + rank));
520
+ };
521
+ bm.forEach((r, i) => vote(r.slug, i + 1));
522
+ simRanked.forEach((r, i) => vote(r.slug, i + 1));
523
+ return [...fused.entries()]
524
+ .map(([slug, score]) => ({ slug, score }))
525
+ .sort((a, b) => b.score - a.score || a.slug.localeCompare(b.slug));
526
+ }
527
+ return {
528
+ async recall(query, k = 6) {
529
+ if (typeof query !== "string" || query.length === 0) {
530
+ throw new WikiStoreError("recall(): query must be a non-empty string");
531
+ }
532
+ if (k <= 0)
533
+ return [];
534
+ const index = await loadIndex();
535
+ const docs = await recallDocs(index);
536
+ if (docs.length === 0)
537
+ return [];
538
+ const primary = await primaryRank(docs, query);
539
+ if (primary.length === 0)
540
+ return [];
541
+ const bySlug = new Map(docs.map((d) => [d.slug, d]));
542
+ // One-hop link expansion + the documented re-rank rule (see the module
543
+ // header): primary candidates keep their reciprocal-rank vote
544
+ // 1/(60+rank); each one-hop neighbor of a top-k seed (either edge
545
+ // direction) gains a HALF-WEIGHT link vote 0.5/(60 + bestSeedRank) —
546
+ // corroboration, not a match, so a neighbor can never displace its
547
+ // seed or any primary match ranked at or above it.
548
+ const seeds = primary.slice(0, k);
549
+ const seedRank = new Map(seeds.map((s, i) => [s.slug, i + 1]));
550
+ const neighborBestSeedRank = new Map();
551
+ for (const doc of docs) {
552
+ for (const [seedSlug, rank] of seedRank) {
553
+ if (doc.slug === seedSlug)
554
+ continue;
555
+ const seedDoc = bySlug.get(seedSlug);
556
+ if (seedDoc === undefined)
557
+ continue;
558
+ const linked = seedDoc.ref.links.includes(doc.slug) || doc.ref.links.includes(seedSlug);
559
+ if (!linked)
560
+ continue;
561
+ const prev = neighborBestSeedRank.get(doc.slug);
562
+ if (prev === undefined || rank < prev)
563
+ neighborBestSeedRank.set(doc.slug, rank);
564
+ }
565
+ }
566
+ const votes = new Map();
567
+ primary.forEach((r, i) => {
568
+ votes.set(r.slug, (votes.get(r.slug) ?? 0) + 1 / (RRF_K + i + 1));
569
+ });
570
+ for (const [slug, bestSeed] of neighborBestSeedRank) {
571
+ votes.set(slug, (votes.get(slug) ?? 0) + 0.5 / (RRF_K + bestSeed));
572
+ }
573
+ const primaryMatched = new Set(primary.map((r) => r.slug));
574
+ return [...votes.entries()]
575
+ .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
576
+ .slice(0, k)
577
+ .flatMap(([slug, score]) => {
578
+ const doc = bySlug.get(slug);
579
+ if (doc === undefined)
580
+ return [];
581
+ const hit = {
582
+ ref: doc.ref,
583
+ score,
584
+ body: doc.body,
585
+ via: primaryMatched.has(slug) ? "match" : "link",
586
+ };
587
+ return [hit];
588
+ });
589
+ },
590
+ async search(query) {
591
+ if (typeof query !== "string" || query.length === 0) {
592
+ throw new WikiStoreError("search(): query must be a non-empty string");
593
+ }
594
+ const index = await loadIndex();
595
+ const docs = await recallDocs(index);
596
+ const ranked = bm25Rank(docs, query);
597
+ const bySlug = new Map(docs.map((d) => [d.slug, d.ref]));
598
+ return ranked.flatMap((r) => {
599
+ const ref = bySlug.get(r.slug);
600
+ return ref !== undefined ? [ref] : [];
601
+ });
602
+ },
603
+ async get(slug) {
604
+ validateSlug(slug);
605
+ return readArticle(slug);
606
+ },
607
+ async write(input) {
608
+ const slug = validateSlug(input.slug);
609
+ if (typeof input.title !== "string" || input.title.trim() === "") {
610
+ throw new WikiStoreError("write(): title must be a non-empty string");
611
+ }
612
+ if (typeof input.body !== "string" || input.body.trim() === "") {
613
+ throw new WikiStoreError("write(): body must be a non-empty string");
614
+ }
615
+ if (input.confidence !== undefined &&
616
+ (typeof input.confidence !== "number" || input.confidence < 0 || input.confidence > 1)) {
617
+ throw new WikiStoreError("write(): confidence must be a number in [0, 1]");
618
+ }
619
+ return locked(async () => {
620
+ const existing = await readArticle(slug);
621
+ const at = now().toISOString();
622
+ let next;
623
+ if (existing === null) {
624
+ if (input.expectedVersion !== undefined && input.expectedVersion !== 0) {
625
+ throw new WikiVersionConflictError(slug, input.expectedVersion, undefined);
626
+ }
627
+ next = {
628
+ slug,
629
+ title: input.title,
630
+ tags: [...(input.tags ?? [])],
631
+ confidence: input.confidence ?? 0.5,
632
+ verified: false,
633
+ version: 1,
634
+ sources: [...(input.sources ?? [])],
635
+ ...(input.createdBy !== undefined ? { createdBy: input.createdBy } : {}),
636
+ status: input.status ?? "published",
637
+ createdAt: at,
638
+ updatedAt: at,
639
+ body: input.body,
640
+ };
641
+ }
642
+ else {
643
+ if (input.expectedVersion !== existing.version) {
644
+ throw new WikiVersionConflictError(slug, input.expectedVersion, existing.version);
645
+ }
646
+ // Supersede, never delete: freeze the outgoing version FIRST, so
647
+ // even a crash between snapshot and write loses nothing.
648
+ await atomicWrite(fence(join(versionsDir, slug, `${existing.version}.md`)), serializeArticle(existing));
649
+ next = {
650
+ slug,
651
+ title: input.title,
652
+ tags: input.tags !== undefined ? [...input.tags] : existing.tags,
653
+ confidence: input.confidence ?? existing.confidence,
654
+ // A new version is a new, not-yet-fact-checked claim.
655
+ verified: false,
656
+ version: existing.version + 1,
657
+ sources: input.sources !== undefined ? [...input.sources] : existing.sources,
658
+ supersedes: existing.version,
659
+ ...(input.createdBy !== undefined
660
+ ? { createdBy: input.createdBy }
661
+ : existing.createdBy !== undefined
662
+ ? { createdBy: existing.createdBy }
663
+ : {}),
664
+ status: input.status ?? existing.status,
665
+ createdAt: existing.createdAt,
666
+ updatedAt: at,
667
+ body: input.body,
668
+ };
669
+ }
670
+ await atomicWrite(articlePath(slug), serializeArticle(next));
671
+ // The index is a derived cache — rebuild from the authoritative
672
+ // article scan so a previously stale/corrupt index self-heals on
673
+ // the next mutation.
674
+ await persistIndex(await rebuildIndex());
675
+ return { slug, version: next.version };
676
+ });
677
+ },
678
+ async list(listOpts = {}) {
679
+ const index = await loadIndex();
680
+ let refs = refsOf(index);
681
+ if (listOpts.status !== undefined && listOpts.status !== "all") {
682
+ refs = refs.filter((r) => r.status === listOpts.status);
683
+ }
684
+ if (listOpts.tags !== undefined && listOpts.tags.length > 0) {
685
+ const wanted = listOpts.tags;
686
+ refs = refs.filter((r) => wanted.every((t) => r.tags.includes(t)));
687
+ }
688
+ const dir = listOpts.staleFirst === true ? 1 : -1;
689
+ refs.sort((a, b) => dir * (Date.parse(a.updatedAt) - Date.parse(b.updatedAt)) || a.slug.localeCompare(b.slug));
690
+ return refs;
691
+ },
692
+ async related(slug) {
693
+ validateSlug(slug);
694
+ const index = await loadIndex();
695
+ const entry = index.articles[slug];
696
+ if (entry === undefined) {
697
+ throw new WikiStoreError(`related(): no article "${slug}"`);
698
+ }
699
+ const refs = refsOf(index);
700
+ const me = { slug, ...entry };
701
+ // Embedding similarity contributes only when an embedder is present.
702
+ let sims = new Map();
703
+ if (embedder !== undefined) {
704
+ const docs = await recallDocs(index);
705
+ const vecs = await embeddingsFor(docs);
706
+ const mine = vecs.get(slug);
707
+ if (mine !== undefined) {
708
+ sims = new Map([...vecs.entries()]
709
+ .filter(([s]) => s !== slug)
710
+ .map(([s, v]) => [s, cosineSimilarity(mine, v)]));
711
+ }
712
+ }
713
+ const out = [];
714
+ for (const other of refs) {
715
+ if (other.slug === slug)
716
+ continue;
717
+ const sharedTags = other.tags.filter((t) => me.tags.includes(t)).length;
718
+ const linkEdges = (me.links.includes(other.slug) ? 1 : 0) + (other.links.includes(slug) ? 1 : 0);
719
+ const sim = Math.max(0, sims.get(other.slug) ?? 0);
720
+ // Documented weighting: each shared tag = 1 vote, each link edge
721
+ // (out + in counted separately) = 2 votes, embedding similarity
722
+ // adds its raw 0–1 cosine on top as a tie-refiner.
723
+ const score = sharedTags + 2 * linkEdges + sim;
724
+ if (score > 0)
725
+ out.push({ ...other, relatedScore: score });
726
+ }
727
+ out.sort((a, b) => b.relatedScore - a.relatedScore || a.slug.localeCompare(b.slug));
728
+ return out;
729
+ },
730
+ async setSignals(slug, signals) {
731
+ validateSlug(slug);
732
+ if (signals.verified === undefined && signals.confidence === undefined) {
733
+ throw new WikiStoreError("setSignals(): pass at least one of verified / confidence");
734
+ }
735
+ if (signals.confidence !== undefined &&
736
+ (typeof signals.confidence !== "number" || signals.confidence < 0 || signals.confidence > 1)) {
737
+ throw new WikiStoreError("setSignals(): confidence must be a number in [0, 1]");
738
+ }
739
+ return locked(async () => {
740
+ const existing = await readArticle(slug);
741
+ if (existing === null) {
742
+ throw new WikiStoreError(`setSignals(): no article "${slug}"`);
743
+ }
744
+ // Metadata-only: no version bump, no snapshot (the body is untouched).
745
+ const next = {
746
+ ...existing,
747
+ verified: signals.verified ?? existing.verified,
748
+ confidence: signals.confidence ?? existing.confidence,
749
+ updatedAt: now().toISOString(),
750
+ };
751
+ await atomicWrite(articlePath(slug), serializeArticle(next));
752
+ await persistIndex(await rebuildIndex());
753
+ });
754
+ },
755
+ async stats() {
756
+ const index = await loadIndex();
757
+ const refs = refsOf(index);
758
+ const byStatus = {
759
+ draft: 0,
760
+ published: 0,
761
+ review: 0,
762
+ archived: 0,
763
+ };
764
+ const tags = new Set();
765
+ let verified = 0;
766
+ let confidenceSum = 0;
767
+ let links = 0;
768
+ for (const r of refs) {
769
+ byStatus[r.status] += 1;
770
+ for (const t of r.tags)
771
+ tags.add(t);
772
+ if (r.verified)
773
+ verified += 1;
774
+ confidenceSum += r.confidence;
775
+ links += r.links.length;
776
+ }
777
+ // Count immutable snapshots (supersede-never-delete chain depth).
778
+ let priorVersions = 0;
779
+ fence(versionsDir);
780
+ try {
781
+ for (const slugDir of await readdir(versionsDir)) {
782
+ try {
783
+ priorVersions += (await readdir(join(versionsDir, slugDir))).filter((f) => f.endsWith(".md")).length;
784
+ }
785
+ catch {
786
+ // not a directory / raced away — skip
787
+ }
788
+ }
789
+ }
790
+ catch {
791
+ // no versions dir yet
792
+ }
793
+ return {
794
+ articles: refs.length,
795
+ byStatus,
796
+ priorVersions,
797
+ uniqueTags: tags.size,
798
+ verified,
799
+ averageConfidence: refs.length > 0 ? confidenceSum / refs.length : 0,
800
+ links,
801
+ };
802
+ },
803
+ ...(embedder !== undefined
804
+ ? {
805
+ async semanticSearch(query, k = 6, minScore = 0.05) {
806
+ if (typeof query !== "string" || query.length === 0) {
807
+ throw new WikiStoreError("semanticSearch(): query must be a non-empty string");
808
+ }
809
+ if (k <= 0)
810
+ return [];
811
+ const index = await loadIndex();
812
+ const docs = await recallDocs(index);
813
+ if (docs.length === 0)
814
+ return [];
815
+ const [queryVec] = await embedder.embed([query]);
816
+ if (queryVec === undefined)
817
+ return [];
818
+ const vecs = await embeddingsFor(docs);
819
+ const scored = docs
820
+ .flatMap((d) => {
821
+ const v = vecs.get(d.slug);
822
+ if (v === undefined)
823
+ return [];
824
+ const sim = cosineSimilarity(queryVec, v);
825
+ if (sim < minScore)
826
+ return [];
827
+ const hit = { ref: d.ref, score: sim, body: d.body, via: "match" };
828
+ return [hit];
829
+ })
830
+ .sort((a, b) => b.score - a.score || a.ref.slug.localeCompare(b.ref.slug));
831
+ return scored.slice(0, k);
832
+ },
833
+ }
834
+ : {}),
835
+ path() {
836
+ return storeDir;
837
+ },
838
+ };
839
+ }
package/dist/lock.d.ts ADDED
@@ -0,0 +1,36 @@
1
+ /**
2
+ * Advisory single-writer `.lock` for the update-in-place wiki store
3
+ * (design §7.6): wait up to 2 s → steal a lock whose mtime is > 30 s stale
4
+ * (with a `lock_stolen` warning naming the dead holder) → fail with a
5
+ * `WikiLockError` naming the holder pid.
6
+ *
7
+ * The policy IMPLEMENTATION lives in `@crewhaus/infra-utils`
8
+ * (`acquireFileLock`/`withFileLock`) — this module shipped as a duplicated
9
+ * copy of `continuity-store/src/lock.ts` while the two stores landed on
10
+ * parallel 0.3.0 branches; the composition-root PR unified the policy into
11
+ * the shared helper. This module keeps the store's public lock surface
12
+ * (error identity, message prefix, option and handle types) exactly as its
13
+ * tests pin it.
14
+ */
15
+ import { CrewhausError } from "@crewhaus/errors";
16
+ import { type FileLockHandle, type FileLockPolicy } from "@crewhaus/infra-utils";
17
+ export declare class WikiLockError extends CrewhausError {
18
+ readonly name = "WikiLockError";
19
+ constructor(message: string, cause?: unknown);
20
+ }
21
+ export type LockPolicy = FileLockPolicy;
22
+ export declare const DEFAULT_LOCK_POLICY: LockPolicy;
23
+ export type AcquireLockOptions = Partial<LockPolicy> & {
24
+ /** Receives the `lock_stolen` warning line. Default: `console.error`. */
25
+ readonly onWarn?: (message: string) => void;
26
+ };
27
+ export type LockHandle = FileLockHandle;
28
+ /**
29
+ * Acquire the advisory lock at `lockPath` under the §7.6 policy. Resolves to
30
+ * a handle whose `release()` unlinks the file; rejects with `WikiLockError`
31
+ * (naming the holder pid) when the lock stays held past `waitMs` without
32
+ * going stale.
33
+ */
34
+ export declare function acquireLock(lockPath: string, opts?: AcquireLockOptions): Promise<LockHandle>;
35
+ /** Run `fn` while holding the lock at `lockPath`; always releases. */
36
+ export declare function withLock<T>(lockPath: string, fn: () => Promise<T>, opts?: AcquireLockOptions): Promise<T>;
package/dist/lock.js ADDED
@@ -0,0 +1,44 @@
1
+ /**
2
+ * Advisory single-writer `.lock` for the update-in-place wiki store
3
+ * (design §7.6): wait up to 2 s → steal a lock whose mtime is > 30 s stale
4
+ * (with a `lock_stolen` warning naming the dead holder) → fail with a
5
+ * `WikiLockError` naming the holder pid.
6
+ *
7
+ * The policy IMPLEMENTATION lives in `@crewhaus/infra-utils`
8
+ * (`acquireFileLock`/`withFileLock`) — this module shipped as a duplicated
9
+ * copy of `continuity-store/src/lock.ts` while the two stores landed on
10
+ * parallel 0.3.0 branches; the composition-root PR unified the policy into
11
+ * the shared helper. This module keeps the store's public lock surface
12
+ * (error identity, message prefix, option and handle types) exactly as its
13
+ * tests pin it.
14
+ */
15
+ import { CrewhausError } from "@crewhaus/errors";
16
+ import { DEFAULT_FILE_LOCK_POLICY, acquireFileLock, withFileLock, } from "@crewhaus/infra-utils";
17
+ export class WikiLockError extends CrewhausError {
18
+ name = "WikiLockError";
19
+ constructor(message, cause) {
20
+ super("runtime", message, cause);
21
+ }
22
+ }
23
+ export const DEFAULT_LOCK_POLICY = DEFAULT_FILE_LOCK_POLICY;
24
+ const STORE_LABEL = "wiki-store";
25
+ function toFileLockOptions(opts) {
26
+ return {
27
+ ...opts,
28
+ label: STORE_LABEL,
29
+ createError: (message) => new WikiLockError(message),
30
+ };
31
+ }
32
+ /**
33
+ * Acquire the advisory lock at `lockPath` under the §7.6 policy. Resolves to
34
+ * a handle whose `release()` unlinks the file; rejects with `WikiLockError`
35
+ * (naming the holder pid) when the lock stays held past `waitMs` without
36
+ * going stale.
37
+ */
38
+ export async function acquireLock(lockPath, opts = {}) {
39
+ return acquireFileLock(lockPath, toFileLockOptions(opts));
40
+ }
41
+ /** Run `fn` while holding the lock at `lockPath`; always releases. */
42
+ export async function withLock(lockPath, fn, opts = {}) {
43
+ return withFileLock(lockPath, fn, toFileLockOptions(opts));
44
+ }
package/package.json ADDED
@@ -0,0 +1,46 @@
1
+ {
2
+ "name": "@crewhaus/wiki-store",
3
+ "version": "0.3.0",
4
+ "type": "module",
5
+ "description": "0.3.0 memory release §3.1 — local update-in-place wiki: versioned markdown articles (supersede, never delete), optimistic concurrency (stale_article_version), hybrid BM25+embedding recall with one-hop [[wikilink]] expansion.",
6
+ "main": "dist/index.js",
7
+ "types": "dist/index.d.ts",
8
+ "exports": {
9
+ ".": {
10
+ "types": "./dist/index.d.ts",
11
+ "import": "./dist/index.js"
12
+ }
13
+ },
14
+ "scripts": {
15
+ "test": "bun test src"
16
+ },
17
+ "dependencies": {
18
+ "@crewhaus/errors": "0.3.0",
19
+ "@crewhaus/infra-utils": "0.3.0",
20
+ "@crewhaus/tenancy": "0.3.0",
21
+ "yaml": "^2.6.0"
22
+ },
23
+ "devDependencies": {
24
+ "@crewhaus/embedder": "0.3.0",
25
+ "@crewhaus/memory-service": "0.3.0"
26
+ },
27
+ "license": "Apache-2.0",
28
+ "author": {
29
+ "name": "Max Meier",
30
+ "email": "max@crewhaus.ai",
31
+ "url": "https://crewhaus.ai"
32
+ },
33
+ "repository": {
34
+ "type": "git",
35
+ "url": "git+https://github.com/crewhaus/factory.git",
36
+ "directory": "packages/wiki-store"
37
+ },
38
+ "homepage": "https://github.com/crewhaus/factory/tree/main/packages/wiki-store#readme",
39
+ "bugs": {
40
+ "url": "https://github.com/crewhaus/factory/issues"
41
+ },
42
+ "publishConfig": {
43
+ "access": "public"
44
+ },
45
+ "files": ["dist", "README.md", "LICENSE", "NOTICE"]
46
+ }