Local-first 🧠memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.
TypeScript
/**
* Filesystem paths and slug allocation for the Brain layer.
*
* Layout lives under `<vault>/Brain/`:
*
* Brain/
* _brain.yaml
* inbox/
* sig-<date>-<slug>.md
* processed/sig-<date>-<slug>.md
* archived/sig-<date>-<slug>.md
* preferences/
* pref-<slug>.md
* retired/
* ret-<slug>.md
* log/
* <YYYY-MM-DD>.md
* .snapshots/
* <run_id>.tar.zst
*
* Every constructor here funnels through `ensureInsideVault` (re-exported
* from `../path-safety`) so a malformed slug or a `..` traversal cannot
* land a file outside the vault root. Slug validation rejects empties,
* path separators, traversal sequences, and Windows-reserved basenames.
*/
import { existsSync } from "node:fs";
import { join, posix } from "node:path";
import { isFileAlreadyExists } from "../fs-atomic.ts";
import { ensureInsideVault, vaultRelative } from "../path-safety.ts";
import { machineStatePath } from "../state/machine-state.ts";
import type { DegradationNotice } from "../integrity/degradation.ts";
import { JSONL_LEDGER_EXT, resolveAppendShardId, shardedFileName } from "./ledger-shards.ts";
import {
BRAIN_ARTIFACTS_REL,
BRAIN_ACTIVE_FILE,
BRAIN_ARCHIVED_SIGNALS_REL,
BRAIN_ATTENTION_REL,
BRAIN_BASES_REL,
BRAIN_CAPTURES_PROCESSED_REL,
BRAIN_CAPTURES_REL,
BRAIN_CLAIM_GRAPH_FILE,
BRAIN_CONFIG_FILE,
BRAIN_CROSS_TOPIC_LEDGER_FILE,
BRAIN_DECISIONS_REL,
BRAIN_DISTILLATIONS_REL,
BRAIN_ENTITIES_REL,
BRAIN_GAP_TASKS_REL,
BRAIN_INBOX_REL,
BRAIN_LESSONS_FILE,
BRAIN_LOG_REL,
BRAIN_MANUAL_FILE,
BRAIN_OBLIGATIONS_REL,
BRAIN_PAYLOADS_REL,
BRAIN_PENDING_REL,
BRAIN_PINNED_FILE,
BRAIN_PLEDGES_REL,
BRAIN_PREFERENCES_REL,
BRAIN_PROCEDURAL_MEMORY_REL,
BRAIN_PROCEDURES_REL,
BRAIN_PROCESSED_REL,
BRAIN_REPORTS_REL,
BRAIN_RETIRED_REL,
BRAIN_ROLLUP_LEDGER_FILE,
BRAIN_ROOT_REL,
BRAIN_SKILL_ACCEPT_JOURNAL_REL,
BRAIN_SKILL_PROPOSALS_ACCEPTED_REL,
BRAIN_SKILL_PROPOSALS_PENDING_REL,
BRAIN_SKILL_PROPOSALS_REJECTED_REL,
BRAIN_SNAPSHOTS_REL,
BRAIN_SOURCES_REL,
BRAIN_SCOPED_RULES_DIR,
BRAIN_STANDING_RULES_FILE,
BRAIN_STATE_REL,
BRAIN_TENSIONS_REL,
BRAIN_THESES_REL,
BRAIN_WRITE_IMAGES_REL,
DERIVED_STORE_DIR,
HOOK_AUDIT_DIR,
} from "./path-constants.ts";
import { assertVaultIdentityForWrite } from "./vault-identity.ts";
import {
SKILL_BENCHMARK_SPEC_FILE,
SKILL_BENCHMARK_TASKS_FILE,
SKILL_BENCH_SKILL_NAME_RE,
skillBenchmarkRelPath,
} from "./skill-rewrite-tasks.ts";
import { SKILL_REWRITE_ROUNDS_DIR } from "./skill-rewrite.ts";
import type { ScopedRuleAxis } from "./scoped-rule-axis.ts";
import type { WriteLane } from "./freeze-marker.ts";
export { ensureInsideVault, vaultRelative } from "../path-safety.ts";
/**
* The freeze marker's location, re-exported so callers reach every Brain
* path through this module. It is DEFINED in `freeze-marker.ts` because
* the guard that reads it sits below this module in the import graph -
* see that module's docblock for the cycle the split avoids.
*/
export { frozenMarkerPath } from "./freeze-marker.ts";
/** Shape of a sha256 digest as {@link writeImagePath} spells its file names. */
export const SHA256_HEX_RE = /^[0-9a-f]{64}$/;
// The canonical vault-relative names live in their own leaf module so
// `vault-identity.ts` can locate the marker without importing the
// builders that guard on it. Re-exported wholesale: every constant this
// module used to declare is still reachable from this path.
export * from "./path-constants.ts";
/**
* The runtime hooks' audit root: `<vault>/.open-second-brain/hook-audit`,
* or the same path under the device-local state once this machine is
* switched (`state/machine-state.ts`, design D14 item 1).
*
* Outside `Brain/` deliberately - it is derived operational evidence, not
* an authored artifact - and therefore not guarded by
* {@link assertVaultIdentityForWrite}: the hooks append to it on a
* fail-open path where a throw would cost the operator their prompt.
*/
export function hookAuditDir(vault: string): string {
return machineStatePath(vault, DERIVED_STORE_DIR, HOOK_AUDIT_DIR);
}
// The machine-state builders below name a vault-relative location and
// resolve it through `machineStatePath`: the vault on an unswitched
// machine, the device-local state once switched (design D14 items 6, 9,
// 11 and 13). Derived graph JSON, watermarks, artifacts, payloads, write
// images and snapshots are device-local; machines need not agree on them.
/** Path of the persisted claim-graph projection: `Brain/claim-graph.json`. */
export function claimGraphPath(vault: string): string {
return machineStatePath(vault, BRAIN_ROOT_REL, BRAIN_CLAIM_GRAPH_FILE);
}
/** Path of the rollup-ladder ledger: `Brain/rollup-ladder.json`. */
export function rollupLedgerPath(vault: string | null): string {
return machineStatePath(vault, BRAIN_ROOT_REL, BRAIN_ROLLUP_LEDGER_FILE);
}
/** Path of the cross-topic rule ledger: `Brain/cross-topic-rules.json` (t_642bc2b8). */
export function crossTopicLedgerPath(vault: string | null): string {
return machineStatePath(vault, BRAIN_ROOT_REL, BRAIN_CROSS_TOPIC_LEDGER_FILE);
}
const ISO_DATE_RE = /^(\d{4})-(\d{2})-(\d{2})$/;
// Run IDs follow `dream-<YYYY-MM-DD>-<HHMMSS>`; we accept the same generic
// "no path separators / no traversal" rules as slugs, plus a tighter
// shape check for the date-time stem.
const RUN_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
const WINDOWS_RESERVED_BASENAME_RE = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(\..*)?$/i;
export interface BrainDirs {
readonly brain: string;
readonly inbox: string;
/** Holding area for signals already folded into a preference. */
readonly processed: string;
/**
* Inbox signals that can no longer become candidates (outside the
* contradiction window, never consumed). Moved here by dream.
*/
readonly archived: string;
/** Write-approval staging area for extracted signals awaiting review. */
readonly pending: string;
readonly preferences: string;
readonly retired: string;
readonly log: string;
/** Canonical entity registry root: `Brain/entities/<category>/`. */
readonly entities: string;
/** Obsidian Bases view definitions: `Brain/bases/<view>.base`. */
readonly bases: string;
/** Pre-`dream` archive directory. Never recursed into by `dream`. */
readonly snapshots: string;
}
/**
* Compose every Brain subdirectory under `<vault>/Brain/`. Returns
* absolute paths so callers can hand them straight to `mkdirSync` /
* `readdirSync`. Each path is verified to resolve inside the vault.
*/
export function brainDirs(vault: string): BrainDirs {
const brain = ensureInsideVault(join(vault, BRAIN_ROOT_REL), vault);
return {
brain,
inbox: ensureInsideVault(join(vault, BRAIN_INBOX_REL), vault),
processed: ensureInsideVault(join(vault, BRAIN_PROCESSED_REL), vault),
archived: ensureInsideVault(join(vault, BRAIN_ARCHIVED_SIGNALS_REL), vault),
pending: ensureInsideVault(join(vault, BRAIN_PENDING_REL), vault),
preferences: ensureInsideVault(join(vault, BRAIN_PREFERENCES_REL), vault),
retired: ensureInsideVault(join(vault, BRAIN_RETIRED_REL), vault),
log: ensureInsideVault(join(vault, BRAIN_LOG_REL), vault),
entities: ensureInsideVault(join(vault, BRAIN_ENTITIES_REL), vault),
bases: ensureInsideVault(join(vault, BRAIN_BASES_REL), vault),
snapshots: ensureInsideVault(join(vault, BRAIN_SNAPSHOTS_REL), vault),
};
}
/**
* {@link brainDirs}, or with no vault (`null`, design D14) the same
* folders as the vault-relative names the store's rebuilt pages carry
* (`Brain/inbox`, ...). For readers that list memory folders through the
* store facades (`memory-pages.ts`), which take either form; never for a
* file operation.
*/
export function brainDirsOf(vault: string | null): BrainDirs {
if (vault !== null) return brainDirs(vault);
return {
brain: BRAIN_ROOT_REL,
inbox: BRAIN_INBOX_REL,
processed: BRAIN_PROCESSED_REL,
archived: BRAIN_ARCHIVED_SIGNALS_REL,
pending: BRAIN_PENDING_REL,
preferences: BRAIN_PREFERENCES_REL,
retired: BRAIN_RETIRED_REL,
log: BRAIN_LOG_REL,
entities: BRAIN_ENTITIES_REL,
bases: BRAIN_BASES_REL,
snapshots: BRAIN_SNAPSHOTS_REL,
};
}
/**
* {@link brainDirs} for a caller that is about to WRITE.
*
* Identical directories, plus the vault-identity assertion in front of
* them (context-integrity-gates, Unit J). The write-intent variant
* exists because the guard belongs on the write side only: read paths
* must stay unaffected, and a blanket assertion inside `brainDirs`
* would fire on every listing, every doctor pass, and every fail-soft
* hook that merely inspects the tree.
*
* An unmarked root emits a `vault-marker-absent` notice into `notices`
* and proceeds; a root whose marker differs from the one this process
* pinned raises `VaultIdentityMismatchError`. The bootstrap path
* deliberately uses plain {@link brainDirs}: it is what legitimately
* creates the tree, so it must not be gated on the marker it is about
* to write.
*
* ## Which call sites use this one
*
* A site is write-intent when EITHER the `BrainDirs` value it produces
* forms a path the same flow creates, moves, or deletes (even
* conditionally), OR the site is reached only from flows that mutate
* the Brain tree. Everything else stays on {@link brainDirs}:
*
* - read, query, report, and analysis flows - widening the guard onto
* them would break `src/openclaw/index.ts`, which silently defaults
* to the process working directory, and the hooks, which fail open
* by contract;
* - sites reached from BOTH a mutating flow and a read-only or
* dry-run preview of it, where the guard would fire on a preview;
* - the path builders in this module. They are intent-neutral by
* construction - `preferencePath` serves `parsePreference` and
* `writePreference` alike - so a writer that reaches the tree
* through one of them is guarded at its own entry point, not here.
* Those writers call `assertVaultIdentityForWrite` directly; see
* its docblock for the two call surfaces and why they differ.
*
* `lane` selects which half of the write surface the caller belongs to
* and is forwarded verbatim to the guard; see its docblock for the
* freeze the content lane carries. Exactly one caller passes anything
* but the default: the Brain log appender, whose events have to keep
* landing while the vault is frozen.
*/
export function brainDirsForWrite(
vault: string,
notices?: DegradationNotice[],
lane?: WriteLane,
): BrainDirs {
assertVaultIdentityForWrite(vault, notices, lane);
return brainDirs(vault);
}
/** Path of `Brain/_brain.yaml`. */
export function brainConfigPath(vault: string): string {
return ensureInsideVault(join(brainDirs(vault).brain, BRAIN_CONFIG_FILE), vault);
}
/** Path of the Brain operating manual rendered into the vault. */
export function brainManualPath(vault: string): string {
return ensureInsideVault(join(brainDirs(vault).brain, BRAIN_MANUAL_FILE), vault);
}
/**
* Path of the auto-generated active-preferences digest written by
* `dream` and CLI verbs that mutate preference state. Read by the
* `SessionStart` / `PostCompact` hook and exposed as the MCP resource
* `osb://preferences/active`.
*/
export function brainActivePath(vault: string): string {
return ensureInsideVault(join(brainDirs(vault).brain, BRAIN_ACTIVE_FILE), vault);
}
/**
* Path of the auto-generated lessons digest (`Brain/lessons.md`) written
* by `dream`: the unified, signed, recency-scored corpus over
* preferences and dead-ends. Read by the `SessionStart` / `PostCompact`
* hook alongside `active.md` and exposed as the MCP resource
* `osb://lessons`.
*/
export function brainLessonsPath(vault: string): string {
return ensureInsideVault(join(brainDirs(vault).brain, BRAIN_LESSONS_FILE), vault);
}
/**
* Path of the operator-authored standing-rules file
* (`Brain/standing-rules.md`, silence-is-not-an-answer U8).
*
* Unlike every other artefact at this level it is written by hand and
* never by this system: `dream` does not generate it, no CLI verb
* rewrites it, and the note-target resolver refuses it to every
* caller-named write tool because its first path segment is `Brain`.
* Read by the `SessionStart` hook ahead of the memory layer and by
* `brain_context`.
*/
export function brainStandingRulesPath(vault: string): string {
return ensureInsideVault(join(brainDirs(vault).brain, BRAIN_STANDING_RULES_FILE), vault);
}
/**
* Directory of the operator-authored scoped standing rules
* (`Brain/standing-rules/`). Hand-written like the constitution file and
* refused to every write path by `assertStandingRulesNotTargeted`.
*/
export function brainScopedRulesDir(vault: string): string {
return ensureInsideVault(join(brainDirs(vault).brain, BRAIN_SCOPED_RULES_DIR), vault);
}
/**
* Path of one scoped rule file: `Brain/standing-rules/<axis>/<key>.md`.
* `key` is expected to come from `scopedRuleKey` (letters, digits and
* dashes only); the containment check still runs on the result.
*/
export function brainScopedRulePath(vault: string, axis: ScopedRuleAxis, key: string): string {
return ensureInsideVault(join(brainScopedRulesDir(vault), axis, `${key}.md`), vault);
}
/** Path of the transient current-task scratchpad read by `brain_context`. */
export function brainPinnedPath(vault: string): string {
return ensureInsideVault(join(brainDirs(vault).brain, BRAIN_PINNED_FILE), vault);
}
/** Overwrite-only exact-state lane directory: `Brain/state/` (t_b0c9d0a3). */
export function brainStateDir(vault: string): string {
return ensureInsideVault(join(vault, BRAIN_STATE_REL), vault);
}
/**
* Content-addressed before-image store: `Brain/.state/write-images/`
* (who-wrote-what, Task A).
*
* Holds the raw bytes each note write replaced, keyed by their sha256, so
* a recorded write can be undone from the content it displaced rather
* than from a whole-tree archive. Inside `Brain/`, so the snapshot region
* already covers it.
*/
export function writeImagesDir(vault: string): string {
return machineStatePath(vault, BRAIN_WRITE_IMAGES_REL);
}
/**
* One before-image: `Brain/.state/write-images/<sha256>`.
*
* The digest is validated rather than trusted, because it reaches this
* builder from a log payload an operator may have hand-edited and a
* separator smuggled through it would be a traversal out of the store.
*/
export function writeImagePath(vault: string, sha256: string): string {
if (!SHA256_HEX_RE.test(sha256)) {
throw new Error(
`writeImagePath: invalid before-image digest ${JSON.stringify(sha256)} - ` +
"expected 64 lowercase hexadecimal characters",
);
}
return join(writeImagesDir(vault), sha256);
}
/** The payload registry's store: `Brain/.payloads/`. */
export function payloadsDir(vault: string): string {
return machineStatePath(vault, BRAIN_PAYLOADS_REL);
}
/**
* One externalized payload: `Brain/.payloads/<sha256>.txt`.
*
* The digest is validated rather than trusted: it reaches this builder
* from an `osb-payload://` ref a caller typed or a row an operator may
* have hand-edited, and a separator smuggled through it would be a
* traversal out of the store.
*/
export function payloadPath(vault: string, sha256: string): string {
if (!SHA256_HEX_RE.test(sha256)) {
throw new Error(
`payloadPath: invalid payload digest ${JSON.stringify(sha256)} - ` +
"expected 64 lowercase hexadecimal characters",
);
}
return join(payloadsDir(vault), `${sha256}.txt`);
}
/** A single exact-state aspect page: `Brain/state/<aspect>.md` (t_b0c9d0a3). */
export function exactStatePath(vault: string, aspect: string): string {
const s = validateSlug(aspect);
return ensureInsideVault(join(brainStateDir(vault), `${s}.md`), vault);
}
/** Active-signal path: `Brain/inbox/sig-<date>-<slug>.md`. */
export function signalPath(vault: string, date: string, slug: string): string {
const d = validateIsoDate(date);
const s = validateSlug(slug);
return ensureInsideVault(join(brainDirs(vault).inbox, `sig-${d}-${s}.md`), vault);
}
/**
* Archived-signal path: `Brain/inbox/archived/<basename>`. Takes the file's
* own basename rather than an id so the move preserves the name exactly.
*/
export function archivedSignalPath(vault: string, basename: string): string {
if (!basename.startsWith("sig-") || !basename.endsWith(".md") || /[\\/]/.test(basename)) {
throw new Error(`not a signal file name: ${JSON.stringify(basename)}`);
}
return ensureInsideVault(join(brainDirs(vault).archived, basename), vault);
}
/** Processed-signal path: `Brain/inbox/processed/sig-<date>-<slug>.md`. */
export function processedSignalPath(vault: string, date: string, slug: string): string {
const d = validateIsoDate(date);
const s = validateSlug(slug);
return ensureInsideVault(join(brainDirs(vault).processed, `sig-${d}-${s}.md`), vault);
}
/** Preference path: `Brain/preferences/pref-<slug>.md`. */
export function preferencePath(vault: string, slug: string): string {
const s = validateSlug(slug);
return ensureInsideVault(join(brainDirs(vault).preferences, `pref-${s}.md`), vault);
}
/**
* {@link preferencePath}, or with no vault (`null`) the vault-relative
* name the store's rebuilt page carries (`Brain/preferences/pref-<slug>.md`).
*/
export function preferencePathOf(vault: string | null, slug: string): string {
if (vault !== null) return preferencePath(vault, slug);
return posix.join(BRAIN_PREFERENCES_REL, `pref-${validateSlug(slug)}.md`);
}
/** {@link retiredPath}, or with no vault the vault-relative name (`Brain/retired/ret-<slug>.md`). */
export function retiredPathOf(vault: string | null, slug: string): string {
if (vault !== null) return retiredPath(vault, slug);
return posix.join(BRAIN_RETIRED_REL, `ret-${validateSlug(slug)}.md`);
}
/** Ingested source summary page: `Brain/sources/src-<slug>.md`. */
export function sourcePagePath(vault: string, slug: string): string {
const s = validateSlug(slug);
return ensureInsideVault(join(vault, BRAIN_SOURCES_REL, `src-${s}.md`), vault);
}
/** Source-distillation page: `Brain/distillations/dist-<slug>.md`. */
export function distillationPagePath(vault: string, slug: string): string {
const s = validateSlug(slug);
return ensureInsideVault(join(vault, BRAIN_DISTILLATIONS_REL, `dist-${s}.md`), vault);
}
/** Cited research report page: `Brain/reports/<date>-<slug>.md`. */
export function reportPagePath(vault: string, date: string, slug: string): string {
const d = validateIsoDate(date);
const s = validateSlug(slug);
return ensureInsideVault(join(vault, BRAIN_REPORTS_REL, `${d}-${s}.md`), vault);
}
/**
* Per-preference edit-history sidecar: `Brain/preferences/pref-<slug>.history.jsonl`.
* Lives next to the preference file; never enters the search index
* because the walker only yields `.md` files.
*/
export function preferenceHistoryPath(vault: string, slug: string): string {
// Per-device shard (t_774dea61): each machine appends to its own
// history file; the empty device id keeps the legacy un-sharded name.
return ensureInsideVault(
join(
brainDirs(vault).preferences,
shardedFileName(preferenceHistoryStem(slug), resolveAppendShardId(), JSONL_LEDGER_EXT),
),
vault,
);
}
/**
* The shard stem of one preference's edit history, `pref-<slug>.history`:
* the writer names its shard from it and the reader's grammar escapes it.
*/
export function preferenceHistoryStem(slug: string): string {
return `pref-${validateSlug(slug)}.history`;
}
/** Retired-preference path: `Brain/retired/ret-<slug>.md`. */
export function retiredPath(vault: string, slug: string): string {
const s = validateSlug(slug);
return ensureInsideVault(join(brainDirs(vault).retired, `ret-${s}.md`), vault);
}
/** Pending skill-proposal path: `Brain/skill-proposals/pending/prop-<slug>.md`. */
export function skillProposalPendingPath(vault: string, slug: string): string {
const s = validateSlug(slug);
return ensureInsideVault(join(vault, BRAIN_SKILL_PROPOSALS_PENDING_REL, `prop-${s}.md`), vault);
}
/** Accepted skill-proposal archive path: `Brain/skill-proposals/accepted/prop-<slug>.md`. */
export function skillProposalAcceptedPath(vault: string, slug: string): string {
const s = validateSlug(slug);
return ensureInsideVault(join(vault, BRAIN_SKILL_PROPOSALS_ACCEPTED_REL, `prop-${s}.md`), vault);
}
/** Rejected skill-proposal archive path: `Brain/skill-proposals/rejected/prop-<slug>.md`. */
export function skillProposalRejectedPath(vault: string, slug: string): string {
const s = validateSlug(slug);
return ensureInsideVault(join(vault, BRAIN_SKILL_PROPOSALS_REJECTED_REL, `prop-${s}.md`), vault);
}
/** Accept-journal path: `Brain/skill-proposals/accept-journal/<slug>.json`. */
export function skillAcceptJournalPath(vault: string, slug: string): string {
const s = validateSlug(slug);
return machineStatePath(vault, BRAIN_SKILL_ACCEPT_JOURNAL_REL, `${s}.json`);
}
/**
* Prior-content copy for an in-flight rewrite accept:
* `Brain/skill-proposals/accept-journal/<slug>.prior.md`.
*
* A scored rewrite OVERWRITES an incumbent SKILL.md, so the accept
* sequence captures the incumbent bytes here before the overwrite and
* the rollback restores content from it, not just existence. It is a
* repair artifact like the marker beside it and is removed when the
* journal is cleared.
*/
export function skillAcceptPriorContentPath(vault: string, slug: string): string {
const s = validateSlug(slug);
return machineStatePath(vault, BRAIN_SKILL_ACCEPT_JOURNAL_REL, `${s}.prior.md`);
}
/** Per-skill benchmark task set: `Brain/skill-benchmarks/<skill>/tasks.json`. */
export function skillBenchmarkTasksPath(vault: string, skillName: string): string {
assertBenchmarkSkillName(skillName);
return ensureInsideVault(
join(vault, skillBenchmarkRelPath(skillName, SKILL_BENCHMARK_TASKS_FILE)),
vault,
);
}
/** Frozen rewrite spec: `Brain/skill-benchmarks/<skill>/spec.json`. */
export function skillBenchmarkSpecPath(vault: string, skillName: string): string {
assertBenchmarkSkillName(skillName);
return ensureInsideVault(
join(vault, skillBenchmarkRelPath(skillName, SKILL_BENCHMARK_SPEC_FILE)),
vault,
);
}
/** Transcript drop site for gate rounds: `Brain/skill-benchmarks/<skill>/rounds/`. */
export function skillBenchmarkRoundsDir(vault: string, skillName: string): string {
assertBenchmarkSkillName(skillName);
return ensureInsideVault(
join(vault, skillBenchmarkRelPath(skillName, SKILL_REWRITE_ROUNDS_DIR)),
vault,
);
}
/**
* The name becomes a directory under the benchmark root, so it follows
* the skill-directory rule, re-checked here the way every path builder
* in this module re-checks the slug it derives from.
*/
function assertBenchmarkSkillName(skillName: string): void {
if (!SKILL_BENCH_SKILL_NAME_RE.test(skillName)) {
throw new Error(
`skill benchmark name is not a skill directory name ` +
`(lowercase letters, digits and single hyphens): ${JSON.stringify(skillName)}`,
);
}
}
/** Accepted procedure reference path: `Brain/procedures/proc-<slug>.md`. */
export function procedurePath(vault: string, slug: string): string {
const s = validateSlug(slug);
return ensureInsideVault(join(vault, BRAIN_PROCEDURES_REL, `proc-${s}.md`), vault);
}
/** Procedural-memory index path: `Brain/procedural-memory/index.json`. */
export function proceduralMemoryIndexPath(vault: string): string {
return ensureInsideVault(join(vault, BRAIN_PROCEDURAL_MEMORY_REL, "index.json"), vault);
}
/**
* Procedural-memory usage counters: `Brain/procedural-memory/usage.jsonl`,
* machine state (device-local once switched). They tick on every use, so a
* synced record per tick would grow the store without bound (task 3.10).
*/
export function proceduralMemoryUsagePath(vault: string): string {
return machineStatePath(vault, BRAIN_PROCEDURAL_MEMORY_REL, "usage.jsonl");
}
/** Procedural graph projection: `Brain/procedural-memory/graph.json`, machine state. */
export function proceduralGraphPath(vault: string): string {
return machineStatePath(vault, BRAIN_PROCEDURAL_MEMORY_REL, "graph.json");
}
/** Prospective recall hints: `Brain/procedural-memory/hints.json`, machine state. */
export function proceduralHintsPath(vault: string): string {
return machineStatePath(vault, BRAIN_PROCEDURAL_MEMORY_REL, "hints.json");
}
/** Declarative attention-flows directory: `Brain/attention/flows/`. */
export function attentionFlowsDir(vault: string): string {
return ensureInsideVault(join(vault, BRAIN_ATTENTION_REL, "flows"), vault);
}
/** Recurring-obligation pages dir: `Brain/obligations/`. */
export function obligationsDir(vault: string): string {
return ensureInsideVault(join(vault, BRAIN_OBLIGATIONS_REL), vault);
}
/** Retired-obligation archive dir: `Brain/obligations/archive/`. */
export function obligationsArchiveDir(vault: string): string {
return ensureInsideVault(join(vault, BRAIN_OBLIGATIONS_REL, "archive"), vault);
}
/** A single obligation page: `Brain/obligations/<slug>.md`. */
export function obligationPath(vault: string, slug: string): string {
return ensureInsideVault(join(vault, BRAIN_OBLIGATIONS_REL, `${slug}.md`), vault);
}
/** One-off pledge pages dir: `Brain/pledges/`. */
export function pledgesDir(vault: string): string {
return ensureInsideVault(join(vault, BRAIN_PLEDGES_REL), vault);
}
/** Fulfilled-pledge archive dir: `Brain/pledges/archive/`. */
export function pledgesArchiveDir(vault: string): string {
return ensureInsideVault(join(vault, BRAIN_PLEDGES_REL, "archive"), vault);
}
/** A single pledge page: `Brain/pledges/<slug>.md`. */
export function pledgePath(vault: string, slug: string): string {
return ensureInsideVault(join(vault, BRAIN_PLEDGES_REL, `${slug}.md`), vault);
}
/** Declared-thesis register pages dir: `Brain/theses/`. */
export function thesesDir(vault: string): string {
return ensureInsideVault(join(vault, BRAIN_THESES_REL), vault);
}
/** A single thesis page: `Brain/theses/thesis-<slug>.md`. */
export function thesisPath(vault: string, slug: string): string {
const s = validateSlug(slug);
return ensureInsideVault(join(vault, BRAIN_THESES_REL, `thesis-${s}.md`), vault);
}
/** Decision-record note-family dir: `Brain/decisions/`. */
export function decisionsDir(vault: string): string {
return ensureInsideVault(join(vault, BRAIN_DECISIONS_REL), vault);
}
/** A single decision page: `Brain/decisions/decision-<slug>.md`. */
export function decisionPath(vault: string, slug: string): string {
const s = validateSlug(slug);
return ensureInsideVault(join(vault, BRAIN_DECISIONS_REL, `decision-${s}.md`), vault);
}
/** Persisted-contradiction note-family dir: `Brain/tensions/` (S2). */
export function tensionsDir(vault: string): string {
return ensureInsideVault(join(vault, BRAIN_TENSIONS_REL), vault);
}
/** A single tension page: `Brain/tensions/tension-<slug>.md` (S2). */
export function tensionPath(vault: string, slug: string): string {
const s = validateSlug(slug);
return ensureInsideVault(join(vault, BRAIN_TENSIONS_REL, `tension-${s}.md`), vault);
}
/** Proposal scan watermark path: `Brain/procedural-memory/proposal-watermark.json`. */
export function proposalWatermarkPath(vault: string): string {
return machineStatePath(vault, BRAIN_PROCEDURAL_MEMORY_REL, "proposal-watermark.json");
}
/** Shard stem of the recurrence support ledger under `Brain/log/`. */
export const RECURRENCE_LEDGER_STEM = "recurrence-support";
/** Shard stem of the cross-query demand ledger under `Brain/log/`. */
export const QUERY_DEMAND_LEDGER_STEM = "query-demand";
/** Shard stem of the capture-decision ledger under `Brain/log/`. */
export const CAPTURE_DECISION_LEDGER_STEM = "capture-decisions";
/**
* The `Brain/log/` ledger file THIS device appends to for `stem`:
* `<stem>[.<deviceId>].jsonl` (t_774dea61). The empty device id yields the
* legacy un-sharded name, so a vault without a device id writes the same
* file it always did.
*/
function brainLogLedgerPath(vault: string, stem: string): string {
return ensureInsideVault(
join(vault, BRAIN_LOG_REL, shardedFileName(stem, resolveAppendShardId(), JSONL_LEDGER_EXT)),
vault,
);
}
/**
* Recurrence support ledger, this device's shard:
* `Brain/log/recurrence-support[.<deviceId>].jsonl`.
*/
export function proceduralRecurrencePath(vault: string): string {
return brainLogLedgerPath(vault, RECURRENCE_LEDGER_STEM);
}
/**
* Cross-query demand ledger, this device's shard:
* `Brain/log/query-demand[.<deviceId>].jsonl`. A rolling,
* byte-budget-capped append-only log of normalized recall queries with
* their result count and IDF-weighted coverage, aggregated to surface
* recurring queries the vault answers poorly (unmet demand).
*/
export function queryDemandLogPath(vault: string): string {
return brainLogLedgerPath(vault, QUERY_DEMAND_LEDGER_STEM);
}
/** Inbound-capture staging dir: `Brain/captures/` (seam 1, t_f8f5ef6a). */
export function capturesDir(vault: string): string {
return ensureInsideVault(join(vault, BRAIN_CAPTURES_REL), vault);
}
/** Inbound-capture archive dir: `Brain/captures/processed/` (seam 1). */
export function capturesProcessedDir(vault: string): string {
return ensureInsideVault(join(vault, BRAIN_CAPTURES_PROCESSED_REL), vault);
}
/** A staged capture page: `Brain/captures/<id>.md` (seam 1). */
export function captureStagingPath(vault: string, id: string): string {
return ensureInsideVault(join(capturesDir(vault), `${validateSlug(id)}.md`), vault);
}
/** An archived capture page: `Brain/captures/processed/<id>.md` (seam 1). */
export function captureArchivePath(vault: string, id: string): string {
return ensureInsideVault(join(capturesProcessedDir(vault), `${validateSlug(id)}.md`), vault);
}
/**
* Catchup watermark sidecar: `Brain/captures/.catchup-watermark.json` (seam
* 1). Dot-file so the vault walker never indexes it; records the id of the
* last capture acknowledged by a `/catchup` reply.
*/
export function captureWatermarkPath(vault: string): string {
return machineStatePath(vault, BRAIN_CAPTURES_REL, ".catchup-watermark.json");
}
/**
* Capture-decision ledger, this device's shard:
* `Brain/log/capture-decisions[.<deviceId>].jsonl` (seam 1).
* One JSON line per inbound update the bot handled - accepted, rejected, or
* malformed - so no update is ever silently dropped.
*/
export function captureDecisionLogPath(vault: string): string {
// Per-device shard (t_774dea61): the capture host on each machine appends
// to its own file; the empty device id keeps the legacy name.
return brainLogLedgerPath(vault, CAPTURE_DECISION_LEDGER_STEM);
}
/** Log file for the given UTC date: `Brain/log/<YYYY-MM-DD>.md`. */
export function logPath(vault: string, date: string): string {
const d = validateIsoDate(date);
return ensureInsideVault(join(brainDirs(vault).log, `${d}.md`), vault);
}
/**
* Canonical entity file path: `Brain/entities/<category>/<id>.md`
* (Memory Integrity Suite). Both segments are slug-validated; the id
* is the entity's stable identifier and the file basename.
*/
export function entityPath(vault: string, category: string, id: string): string {
const c = validateSlug(category);
const i = validateSlug(id);
return ensureInsideVault(join(brainDirs(vault).entities, c, `${i}.md`), vault);
}
/**
* Structured JSONL sidecar that accompanies each `<date>.md` log
* file (§23, v0.10.8). Every machine consumer reads through this
* helper instead of doing the `.md → .jsonl` string conversion
* inline; if the sidecar layout ever moves (subdirectory,
* compression, …) every caller follows in one edit.
*/
export function logJsonlPath(vault: string, date: string): string {
const d = validateIsoDate(date);
return ensureInsideVault(join(brainDirs(vault).log, `${d}.jsonl`), vault);
}
/**
* Per-device markdown log shard: `Brain/log/<date>.<deviceId>.md`
* (Memory Integrity Suite). The empty device id resolves to the
* legacy un-sharded path so pre-shard call sites keep working.
*/
export function logShardPath(vault: string, date: string, deviceId: string): string {
if (deviceId === "") return logPath(vault, date);
const d = validateIsoDate(date);
return ensureInsideVault(join(brainDirs(vault).log, `${d}.${validateSlug(deviceId)}.md`), vault);
}
/** Per-device JSONL log shard: `Brain/log/<date>.<deviceId>.jsonl`. */
export function logShardJsonlPath(vault: string, date: string, deviceId: string): string {
if (deviceId === "") return logJsonlPath(vault, date);
const d = validateIsoDate(date);
return ensureInsideVault(
join(brainDirs(vault).log, `${d}.${validateSlug(deviceId)}.jsonl`),
vault,
);
}
/**
* Brain Integrity Suite (v0.12.0). Workrun directory used by the
* durable dream-pass checkpoint surface: `Brain/log/dream-runs/`.
* Lives under the log dir so backups already include it.
*/
export function dreamRunsDir(vault: string): string {
return join(brainDirs(vault).log, "dream-runs");
}
/**
* Brain Integrity Suite (v0.12.0). Durable workrun JSONL for a
* single dream invocation: `Brain/log/dream-runs/<run-id>.jsonl`.
* The run id is validated through {@link validateRunId} so it stays
* inside the canonical directory.
*/
export function dreamWorkrunPath(vault: string, runId: string): string {
const id = validateRunId(runId);
return ensureInsideVault(join(dreamRunsDir(vault), `${id}.jsonl`), vault);
}
/**
* Brain lifecycle suite (Feature 1). Per-preference mutation audit
* directory: `Brain/log/pref-audit/`. Lives under the log dir so
* backups already include it.
*/
export function prefAuditDir(vault: string): string {
return join(brainDirs(vault).log, "pref-audit");
}
/**
* Brain lifecycle suite (Feature 1). The directory holding ONE
* preference's audit shards: `Brain/log/pref-audit/<pref-id>/`. The pref
* id (`pref-<slug>` / `ret-<slug>`) is validated through
* {@link validateSlug} so it cannot escape the canonical directory.
*
* A directory rather than a name prefix because {@link validateSlug}
* permits a dot inside a preference id: flat, `pref-a.b.jsonl` is both
* `pref-a.b`'s trail and `pref-a`'s shard on a device called `b`, and no
* separator built out of characters `validateSlug` accepts can tell them
* apart. One path segment per preference can never be another
* preference's segment. See the module docblock of
* `src/core/brain/pref-audit.ts` for the whole decision.
*/
export function prefAuditPrefDir(vault: string, prefId: string): string {
return ensureInsideVault(join(prefAuditDir(vault), validateSlug(prefId)), vault);
}
/**
* Brain lifecycle suite (Feature 1). Append-only audit JSONL for a
* single preference on a single device:
* `Brain/log/pref-audit/<pref-id>/device[.<deviceId>].jsonl`.
*
* `shardId` defaults to this device's id (who-wrote-what, Task B), so two
* machines editing one preference never append to the same file. The
* empty shard id is the un-sharded name inside that directory.
*
* The stem is fixed rather than the device id alone so the empty shard id
* still has a name, and so the shared shard grammar names this file the
* same way it names every other ledger's.
*/
export function prefAuditPath(
vault: string,
prefId: string,
shardId: string = resolveAppendShardId(),
): string {
return ensureInsideVault(
join(
prefAuditPrefDir(vault, prefId),
shardedFileName(PREF_AUDIT_STEM, shardId, PREF_AUDIT_EXT),
),
vault,
);
}
/** Extension of every preference-audit shard. */
export const PREF_AUDIT_EXT = "jsonl";
/**
* Fixed base name of every preference-audit shard inside its
* per-preference directory. A stem rather than the bare device id so the
* legacy empty shard id still yields a name.
*/
export const PREF_AUDIT_STEM = "device";
/** Snapshots directory: `Brain/.snapshots/`. */
export function snapshotsDir(vault: string): string {
return machineStatePath(vault, BRAIN_SNAPSHOTS_REL);
}
/**
* Filename suffix of the Markdown-tree archive. The extension stays
* `.zst` even when the host only has gzip: the restore probes the magic
* bytes rather than the name, and one suffix keeps the listing filter a
* single comparison.
*/
export const SNAPSHOT_ARCHIVE_SUFFIX = ".tar.zst";
/**
* Filename suffix of the derived-store archive that may sit BESIDE the
* tar for the same run id.
*
* Beside, not inside: the extractor requires a `Brain/` root and the
* restore is defined as "live `Brain/` equals archive `Brain/` minus the
* excluded entries", so a second top-level member in the tar would break
* both invariants. Keeping the file in the SAME `.snapshots/` directory
* keeps listing and retention one family with one loop.
*/
export const SNAPSHOT_STORE_ARCHIVE_SUFFIX = ".store.sqlite.zst";
/** Snapshot archive path: `Brain/.snapshots/<run_id>.tar.zst`. */
export function snapshotPath(vault: string, runId: string): string {
const id = validateRunId(runId);
return join(snapshotsDir(vault), `${id}${SNAPSHOT_ARCHIVE_SUFFIX}`);
}
/**
* Derived-store archive path:
* `Brain/.snapshots/<run_id>.store.sqlite.zst`.
*
* Built through the same run-id validation and vault containment as
* {@link snapshotPath}, because it is written into the same directory
* from the same caller-supplied id and deserves no weaker guard.
*/
export function snapshotStorePath(vault: string, runId: string): string {
const id = validateRunId(runId);
return join(snapshotsDir(vault), `${id}${SNAPSHOT_STORE_ARCHIVE_SUFFIX}`);
}
/** Artifacts root: `Brain/.artifacts/`. */
export function brainArtifactsDir(vault: string): string {
return machineStatePath(vault, BRAIN_ARTIFACTS_REL);
}
/** Knowledge-gap task notes root: `Brain/gap-tasks/` (A3 / t_67d38036). */
export function brainGapTasksDir(vault: string): string {
return ensureInsideVault(join(vault, BRAIN_GAP_TASKS_REL), vault);
}
/** Per-run artifact directory: `Brain/.artifacts/<run_id>/`. */
export function artifactRunDir(vault: string, runId: string): string {
const id = validateRunId(runId);
return join(brainArtifactsDir(vault), id);
}
/**
* Single artifact path: `Brain/.artifacts/<run_id>/<artifact_id>.json`.
* Both ids go through {@link validateRunId} (the same filesystem-safety
* contract: no separators, no traversal, no Windows reservation), so a
* malicious `artifact_id` from an MCP argument cannot escape the run dir.
*/
export function artifactPath(vault: string, runId: string, artifactId: string): string {
const aid = validateRunId(artifactId);
return join(artifactRunDir(vault, runId), `${aid}.json`);
}
// ----- Validators -----------------------------------------------------------
/**
* Reject slugs that could escape their intended subdirectory or hit a
* Windows-incompatible filename.
*/
export function validateSlug(slug: string): string {
const trimmed = slug.trim();
if (!trimmed) throw new Error("slug must not be empty");
if (trimmed.includes("/") || trimmed.includes("\\")) {
throw new Error(`slug must not contain path separators: ${slug}`);
}
// Reject Windows-invalid filename characters (`:*?"<>|`) and ASCII
// control characters (0x00-0x1F). On NTFS these are forbidden in a
// filename; on POSIX a NUL byte is illegal in a path and the rest are
// ambiguous when round-tripped through cross-platform tooling (zip
// archives, syncthing, git on Windows).
if (/[:*?"<>|\x00-\x1F]/.test(trimmed)) {
throw new Error(`slug contains invalid character: ${JSON.stringify(slug)}`);
}
if (trimmed === ".." || trimmed === "." || /(?:^|[^\w])\.\.(?:$|[^\w])/.test(trimmed)) {
throw new Error(`slug must not contain '..' traversal: ${slug}`);
}
if (/[. ]$/.test(trimmed)) {
throw new Error(`slug must not end with '.' or whitespace (Windows-incompatible): ${slug}`);
}
if (WINDOWS_RESERVED_BASENAME_RE.test(trimmed)) {
throw new Error(`slug uses a Windows-reserved filename: ${slug}`);
}
return trimmed;
}
/** Validate `YYYY-MM-DD`. Throws on bad shape or impossible calendar date. */
export function validateIsoDate(value: string): string {
const m = ISO_DATE_RE.exec(value);
if (!m) {
throw new Error(`brain date must use YYYY-MM-DD format: ${value}`);
}
const year = parseInt(m[1]!, 10);
const month = parseInt(m[2]!, 10);
const day = parseInt(m[3]!, 10);
const utc = new Date(Date.UTC(year, month - 1, day));
if (
utc.getUTCFullYear() !== year ||
utc.getUTCMonth() !== month - 1 ||
utc.getUTCDate() !== day
) {
throw new Error(`brain date is not a valid calendar date: ${value}`);
}
return value;
}
/**
* Validate a snapshot run_id. The dream algorithm forms run_ids as
* `dream-<YYYY-MM-DD>-<HHMMSS>`; the validator is intentionally
* permissive about the exact stem (we want manual snapshots later) and
* focuses on filesystem-safety: no separators, no traversal, no Windows
* reservation, no leading dot.
*/
export function validateRunId(runId: string): string {
const trimmed = runId.trim();
if (!trimmed) throw new Error("run_id must not be empty");
if (!RUN_ID_RE.test(trimmed)) {
throw new Error(`run_id must match /^[A-Za-z0-9][A-Za-z0-9._-]*$/: ${runId}`);
}
if (trimmed.includes("..") || trimmed.includes("/") || trimmed.includes("\\")) {
throw new Error(`run_id must not contain '..' or path separators: ${runId}`);
}
if (WINDOWS_RESERVED_BASENAME_RE.test(trimmed)) {
throw new Error(`run_id uses a Windows-reserved filename: ${runId}`);
}
return trimmed;
}
// ----- Slug-collision allocator --------------------------------------------
export interface AllocateSlugOptions {
/** Vault root. Required so collision probes stay inside the vault. */
readonly vault: string;
/** Directory the file will live in (absolute). */
readonly targetDir: string;
/** File-name prefix without trailing dash, e.g. `sig-2026-05-14`. */
readonly prefix: string;
/** Base slug requested by the caller. */
readonly slug: string;
/**
* Hard upper bound on how many DISTINCT candidate names are tried.
* Defaults to {@link SLUG_ALLOCATION_MAX_ATTEMPTS}, far beyond any
* realistic same-day collision count; it exists only to make a misuse
* error (caller passing a `targetDir` that resolves outside the vault,
* say) terminate instead of loop forever.
*
* One meaning, in both allocators: a name skipped because the probe
* found it taken and a name lost to a concurrent create each consume
* exactly one attempt.
*/
readonly maxAttempts?: number;
}
export interface AllocateSlugResult {
/** Allocated slug ready to be combined with the prefix. */
readonly slug: string;
/** Final absolute filename (`<targetDir>/<prefix>-<slug>.md`). */
readonly path: string;
/** Suffix that was appended (`null` when no collision). */
readonly suffix: number | null;
}
export interface AllocateAndCreateResult<T> {
/** The name that was successfully created under. */
readonly allocation: AllocateSlugResult;
/** Whatever the injected create returned. */
readonly value: T;
}
/**
* Default bound on distinct candidate names one allocation tries.
*
* Named rather than inlined because two allocators and every caller's
* docblock refer to it: a bound that lives as a literal in one loop is a
* bound nobody else can state.
*/
export const SLUG_ALLOCATION_MAX_ATTEMPTS = 10_000;
/**
* Candidate `attempt` of a collision ladder: the bare base first, then
* `-2`, `-3`, … per §5.1 / §9.2 of the design doc.
*
* Exported because the rule is not slug-specific - run ids ladder the
* same way in `snapshot-gate.ts` and `dream.ts`, and three private
* copies of `n === 1 ? base : \`${base}-${n}\`` were three places for
* the ladder to drift apart.
*/
export function collisionCandidateName(base: string, attempt: number): string {
return attempt === 1 ? base : `${base}-${attempt}`;
}
/** Shared guard: a prefix that is empty or carries separators is caller misuse. */
function assertUsablePrefix(caller: string, prefix: string): void {
if (!prefix || /[\\/]/.test(prefix)) {
throw new Error(`${caller}: prefix must be non-empty and path-clean: ${prefix}`);
}
}
/**
* Candidate `attempt` as a full allocation. The path is funnelled through
* `ensureInsideVault`, so a `targetDir` that resolves outside the vault
* raises before any disk probe is made.
*/
function slugCandidate(
opts: AllocateSlugOptions,
baseSlug: string,
attempt: number,
): AllocateSlugResult {
const slug = collisionCandidateName(baseSlug, attempt);
const path = ensureInsideVault(join(opts.targetDir, `${opts.prefix}-${slug}.md`), opts.vault);
return { slug, path, suffix: attempt === 1 ? null : attempt };
}
/**
* The one loud exhaustion error, shared by both allocators so their
* bounds cannot be reported in two different vocabularies. `lostRace`
* carries the last collision when at least one attempt was lost to a
* concurrent create: the operator gets both the bound that stopped us
* and the failure that consumed the attempts.
*/
function slugExhaustedError(
caller: string,
opts: AllocateSlugOptions,
baseSlug: string,
maxAttempts: number,
lostRace: unknown,
): Error {
const head =
`${caller}: could not find a free name after ${maxAttempts} attempts ` +
`(prefix=${opts.prefix}, slug=${baseSlug})`;
if (lostRace === undefined) return new Error(head);
return new Error(`${head}; the attempts include names lost to a concurrent create`, {
cause: lostRace,
});
}
/**
* Find the first free `<prefix>-<slug>.md` under `targetDir`, appending
* `-2`, `-3`, … to the slug on collision. The probe is read-only, so the
* name it returns can be taken by another process before the caller
* creates it.
*
* Prefer {@link allocateAndCreate} for anything that goes on to create
* the file: it is this probe fused with the create, and losing the race
* costs it one attempt instead of the whole write. This entry point
* remains for callers that only want to know a free name.
*/
export function allocateSlug(opts: AllocateSlugOptions): AllocateSlugResult {
const baseSlug = validateSlug(opts.slug);
const maxAttempts = opts.maxAttempts ?? SLUG_ALLOCATION_MAX_ATTEMPTS;
assertUsablePrefix("allocateSlug", opts.prefix);
for (let attempt = 1; attempt <= maxAttempts; attempt++) {
const candidate = slugCandidate(opts, baseSlug, attempt);
if (!existsSync(candidate.path)) return candidate;
}
throw slugExhaustedError("allocateSlug", opts, baseSlug, maxAttempts, undefined);
}
/**
* Allocate a name AND create the artifact under it, retrying the next
* candidate when the create loses the name to a concurrent writer.
*
* The probe and the create have to be one loop. Separately, they are a
* check-then-act: two agents writing a signal on the same topic and date
* both see `sig-<date>-<topic>.md` free, one wins the exclusive create,
* and the other used to fail terminally with its event dropped on the
* floor (GitHub #161). Nothing looped back to try `-2`.
*
* The create is INJECTED rather than performed here, and that is
* load-bearing twice over. Every caller derives its frontmatter `id`
* from the ALLOCATED slug, so a helper that re-linked pre-rendered bytes
* would ship a file whose `id` contradicts its own filename. And it
* keeps this module free of any write call, so the path vocabulary does
* not acquire a dependency on the frontmatter writer.
*
* The rejected alternative was the lockfile primitive in
* `sync-lockfile.ts`. It locks one known target path, whereas the
* contended resource here is "the next free name under this directory
* for this prefix" - a directory-scoped lock, which would add a
* crash-stale-lock failure mode (only `brain_doctor` clears one) to the
* hottest write path in the system while buying nothing: `link(2)`
* already gives race-free exclusivity. The only missing piece was "on
* collision, try the next name".
*
* Only a collision retries. Any other failure - a full disk, a
* read-only mount - propagates from the attempt that raised it, with
* nothing swallowed and nothing re-labelled; retrying those would burn
* the bound and then report the wrong problem.
*/
export function allocateAndCreate<T>(
opts: AllocateSlugOptions,
create: (allocation: AllocateSlugResult) => T,
): AllocateAndCreateResult<T> {
const baseSlug = validateSlug(opts.slug);
const maxAttempts = opts.maxAttempts ?? SLUG_ALLOCATION_MAX_ATTEMPTS;
assertUsablePrefix("allocateAndCreate", opts.prefix);
let lostRace: unknown;
for (let attempt = 1; attempt <= maxAttempts; attempt++) {
const allocation = slugCandidate(opts, baseSlug, attempt);
// The probe stays as a cheap skip past names already on disk: it
// saves rendering and a temp file per taken name. It is no longer
// load-bearing for correctness - the exclusive create is.
if (existsSync(allocation.path)) continue;
try {
return { allocation, value: create(allocation) };
} catch (err) {
if (!isFileAlreadyExists(err)) throw err;
lostRace = err;
}
}
throw slugExhaustedError("allocateAndCreate", opts, baseSlug, maxAttempts, lostRace);
}
/** Vault-relative renderer kept here for the `tests/core/brain.paths.test.ts` import. */
export function brainVaultRelative(target: string, vault: string): string {
return vaultRelative(target, vault);
}