@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 +86 -0
- package/dist/index.d.ts +192 -0
- package/dist/index.js +839 -0
- package/dist/lock.d.ts +36 -0
- package/dist/lock.js +44 -0
- package/package.json +46 -0
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`.
|
package/dist/index.d.ts
ADDED
|
@@ -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
|
+
}
|