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
/**
* Preference (`pref-*.md`) and retired (`ret-*.md`) parsers, writer, and
* the `preferences/ → retired/` mover.
*
* Preferences are rules promoted from clusters of signals (design doc
* §5.3). They live in `Brain/preferences/` while active; they migrate
* to `Brain/retired/` once they leave the loop, gaining retire metadata
* but otherwise keeping the original slug — only the filename prefix
* flips from `pref-` to `ret-`. The same identity slug is preserved
* across the move so wikilinks pointing at `[[pref-foo]]` continue to
* resolve (Obsidian indexes by basename regardless of folder, and the
* retired file's frontmatter `id` flips to `ret-foo`).
*
* Four concerns matter:
*
* 1. **Default `pinned: false`** when parsing a file whose
* frontmatter omits the field. The design doc §5.3 makes this
* explicit; the type contract in `types.ts` says parsers MUST
* coerce missing/null/undefined to `false`.
*
* 2. **Status-vs-folder invariant.** A file in `preferences/` whose
* frontmatter `status` is `retired` (or a file in `retired/` whose
* kind is `brain-preference`) is corrupt — almost certainly the
* result of a half-completed move. Parsers throw
* {@link BrainStatusFolderMismatchError} on read so the doctor
* command (Task 4) can surface it as a warning. The parsers
* themselves throw because the typed return value would otherwise
* lie about the on-disk state.
*
* 3. **Atomic move.** `moveToRetired` performs the rename via two
* atomic operations (write the new file, unlink the old) to keep
* the filesystem consistent on a mid-run crash: the new file is
* complete before the old one disappears.
*
* 4. **Store-only** (task 2.10). Once the machine is switched
* (`../store/store-only.ts`) a preference is no page: the writer,
* the mover and {@link loadPreference} read the store's preference
* fold (`./preference-store.ts`) and write `preference-set` records
* only, so nothing under `Brain/` changes.
*/
import type { StorePreference } from "../store/read/store-entities.ts";
import { loadPermissionsDocumentFor } from "./permissions/document-source.ts";
import { legacyVaultOf } from "./no-vault.ts";
import type { Authority } from "../store/constants.ts";
import { authorityFromOrigin, dualWrite, type DualWriteRecord } from "../store/dual-write.ts";
import {
isPrivateFrontmatter,
preferenceFields,
preferenceSetRecord,
} from "../store/dual-write-records.ts";
import {
callerInput,
operationPrivacy,
PREFERENCE_OPAQUE_FIELDS,
type JudgedContent,
type OperationPrivacy,
} from "../store/operation-privacy.ts";
import { withOperationPrivacy } from "../store/operation-scope.ts";
import { existsSync, readFileSync, unlinkSync } from "node:fs";
import { basename, dirname, join, relative } from "node:path";
import type { FrontmatterMap } from "../types.ts";
import {
formatFrontmatter,
parseFrontmatter,
parseFrontmatterWithNotices,
slugify,
writeFrontmatterAtomic,
} from "../vault.ts";
import { FileAlreadyExistsError } from "../fs-atomic.ts";
import { routeWrite, storeWrite } from "../store/store-write.ts";
import { DERIVED_FIELDS, storeEntryMeta } from "./preference-page-meta.ts";
import {
fieldsUnchanged,
isRetiredEntry,
PREFERENCE_TEXT_FIELD,
preferencesStoreOnly,
storePreferenceEntry,
textOfFields,
typedPreferenceFields,
} from "./preference-store.ts";
import {
appendRetiredSection,
preferencePageProse,
renderPreferenceBody,
} from "./preference-body.ts";
import { requireObsidianTagValue, scopeTagValues } from "./tag-syntax.ts";
import { BrainParseError } from "./parse-error.ts";
import { FrontmatterTierConflictError, mergeFrontmatterTiered } from "./frontmatter-tiers.ts";
import { loadSchemaPack } from "./schema-pack.ts";
import { DEFAULT_RELATION_TYPES, type DefaultRelationType } from "../graph/relation-vocab.ts";
import {
isKnownSchemaToken,
validateSchemaToken,
type BrainSchemaVocabulary,
} from "./schema-vocab.ts";
import {
brainDirsForWrite,
brainDirsOf,
preferencePath,
preferencePathOf,
retiredPath,
retiredPathOf,
validateSlug,
} from "./paths.ts";
import { assertVaultIdentityForWrite } from "./vault-identity.ts";
import { OWNER_UNRESOLVED, normalizeAgentScope, ownerStampFor } from "../graph/agent-scope.ts";
import { normalizeAgentArgument } from "../agent-identity.ts";
import { resolveAgentName, UNCONFIGURED_AGENT_NAME } from "../config.ts";
import { DEGRADATION_CODE } from "../integrity/degradation.ts";
import { GATE_MODE } from "../integrity/stamp.ts";
import { loadIntegrityConfigForWrite, loadIntegrityConfigSafe } from "./policy.ts";
import { appendDecisionLedger } from "./permissions/ledger.ts";
import { OWNER_SCOPE_WRITES_KEY, refuseCrossOwnerWrite } from "./trust/owner-write-gate.ts";
import { substrateSubject, type WriteSubject } from "./write-disposition.ts";
import { asProvenanceLevel, type ProvenanceLevel } from "./provenance/provenance.ts";
import { sanitisePrinciple } from "./text/sanitize-principle.ts";
import {
BRAIN_CONFIDENCE,
BRAIN_MEMORY_LAYER,
BRAIN_PREFERENCE_STATUS,
BRAIN_RETIRED_REASON,
BRAIN_TOMBSTONE_STATUS,
type BrainConfidence,
type BrainEvidenceSummary,
type BrainMemoryLayer,
type BrainPreference,
type BrainPreferenceStatus,
type BrainRetired,
type BrainRetiredReason,
type BrainCommitmentTier,
isBrainMemoryLayer,
} from "./types.ts";
import { readCommitmentTier, validateCommitmentTier } from "./commitment.ts";
import { readMergedInto } from "./page-meta/page-id.ts";
import type { PageLifecycle } from "./page-meta/lifecycle.ts";
import type { PageTier } from "./page-meta/tier.ts";
import { computeContentHash } from "./content-hash.ts";
import { EXPIRATION_DATE_FIELD, normalizeExpirationDate } from "./expiration.ts";
import { KNOWLEDGE_PACK_FIELD, parseKnowledgePackStamp } from "./portability/pack-stamp.ts";
import {
computePayloadHash,
IdempotencyPayloadMismatchError,
lookupKey,
rememberKey,
} from "./idempotency-ledger.ts";
import { appendPrefAudit } from "./pref-audit.ts";
import { PREF_AUDIT_OP } from "./types.ts";
// ----- Errors ---------------------------------------------------------------
/**
* Raised when a preference / retired file disagrees with the folder
* it lives in. Surfaces both pieces of information so the caller (and
* `o2b brain doctor`) can render an actionable message.
*
* A {@link BrainParseError}, so the path travels as a field and the
* doctor's `status-folder-mismatch` branch reports it the same way as
* every other parse failure. `status` and `folder` stay in the prose:
* unlike the path, a `DoctorIssue` has no field for them.
*
* The sentence a bare caller reads is unchanged: `o2b brain reject`
* prints `(exc as Error).message` with nowhere else to put a location,
* and this message has always named the path INSIDE the data group,
* before `status` and `folder`. Moving it to the end would gain nothing
* and would break an operator matching on the text, so the composition
* is supplied rather than left to the default appender.
*/
export class BrainStatusFolderMismatchError extends BrainParseError {
readonly status: string;
readonly folder: "preferences" | "retired";
constructor(message: string, path: string, status: string, folder: "preferences" | "retired") {
super(`${message} (${statusFolderFacts(status, folder)})`, path, {
composedMessage: `${message} (path=${path}, ${statusFolderFacts(status, folder)})`,
});
this.name = "BrainStatusFolderMismatchError";
this.status = status;
this.folder = folder;
}
}
/** The two facts a `DoctorIssue` has no field for, in their stored order. */
function statusFolderFacts(status: string, folder: "preferences" | "retired"): string {
return `status=${status}, folder=${folder}`;
}
// ----- Writer inputs --------------------------------------------------------
export interface WritePreferenceInput {
/** Slug stem (no `pref-` prefix). Used as the file basename. */
readonly slug: string;
readonly topic: string;
readonly principle: string;
readonly created_at: string;
readonly unconfirmed_until: string;
readonly status: BrainPreferenceStatus;
readonly evidenced_by: ReadonlyArray<string>;
readonly confirmed_at?: string | null;
readonly scope?: string;
/**
* Compose the `brain/scope/...` tags leniently: a scope segment that
* fails the shared tag rule is slugified (or dropped when the slug
* fails too) instead of refusing the write. Set only when the scope is
* re-read from a persisted record - the dream pass rewriting a stored
* preference or promoting stored signals - so a legacy value written
* before v1.78.0 cannot abort it. The `scope` field stays verbatim
* either way; new caller input leaves this unset and stays strict.
*/
readonly lenientScopeTags?: boolean;
/**
* Optional owner token (Knowledge Provenance suite, v1.7). When set, the
* fact is owner-private: owner-scoped recall returns it only to its owner,
* while ownerless facts stay shared. Stored verbatim; normalized for
* comparison by the shared owner-visibility model.
*/
readonly owner?: string;
/**
* Optional `visibility:` tokens (already normalised by `pageVisibility`).
* Emitted only when non-empty, so a default-visibility preference stays
* byte-identical. The dream pass stamps the strictest visibility of the
* signals a preference is drafted from; a rewrite that omits it keeps the
* file's own line through the tiered merge (it is a user-tier field).
*/
readonly visibility?: ReadonlyArray<string>;
/**
* Optional provenance trust level (Knowledge Provenance suite, v1.7).
* Absent reads as `stated` (operator-asserted) for every existing
* preference. A derived fact is written `deduced` or `inferred` with its
* premise links in `evidenced_by`.
*/
readonly provenance?: ProvenanceLevel;
readonly applied_count?: number;
readonly violated_count?: number;
readonly last_evidence_at?: string | null;
readonly confidence?: BrainConfidence;
/**
* Numeric `confidence_value` (Wilson lower bound × freshness
* decay). `null` or absent leaves the on-disk field as `null`,
* signalling "not yet computed" to downstream readers. Dream's
* refresh pass always supplies a finite value.
*/
readonly confidence_value?: number | null;
/**
* Per-page lifecycle. Defaults to `stable` when unspecified so
* legacy callers do not need to thread the field through. Dream
* promotes `stable` → `verified` once a preference accumulates
* enough independent applied-evidence events; the lint --consolidate
* pass can demote `stable` → `draft` for very old, never-applied
* pages.
*/
readonly lifecycle?: PageLifecycle;
/**
* Per-page importance tier. User-editable, unprefixed in YAML
* (next to `pinned`). Reader-side default is `supporting`; emitted
* only when supplied so legacy fixtures stay byte-identical.
*/
readonly tier?: PageTier;
/**
* Optional commitment tier (Belief lifecycle suite, B3, t_e112c63c):
* `exploring | leaning | decided | locked`. User-editable, unprefixed
* in YAML. Validated on write; emitted only when supplied so legacy
* fixtures stay byte-identical.
*/
readonly commitment?: BrainCommitmentTier;
readonly pinned?: boolean;
/**
* Directional freshness trend (Time-Aware Recall & Activation Suite,
* t_ee09a6ce). Stamped by the dream refresh pass from the evidence
* time distribution; emitted only when supplied so legacy fixtures
* stay byte-identical. Recall reads it as a bounded ranking
* multiplier; absent means neutral.
*/
readonly freshness_trend?: string;
/**
* Brain Integrity Suite (v0.12.0). Optional monotonic write counter
* persisted as `_revision`. `writePreferenceTxn` auto-stamps the
* next value when callers omit. Direct `writePreference` callers
* that omit the field skip the emission entirely - legacy fixtures
* stay byte-identical (the reader treats absent as `0`).
*/
readonly revision?: number;
/**
* Brain Integrity Suite (v0.12.0). Optional sha256 of the canonical
* `(principle, scope)` pair persisted as `_content_hash`. Dream
* supplies on promotion to `confirmed`; emitted verbatim when
* supplied, omitted otherwise.
*/
readonly content_hash?: string;
readonly supersedes?: string;
readonly aliases?: ReadonlyArray<string>;
readonly schema_type?: string;
readonly memory_layer?: BrainMemoryLayer;
readonly memory_branch?: string;
readonly related?: ReadonlyArray<string>;
readonly extends?: ReadonlyArray<string>;
readonly depends_on?: ReadonlyArray<string>;
readonly refines?: ReadonlyArray<string>;
readonly contradicts?: ReadonlyArray<string>;
/**
* Brain lifecycle suite (F5). Bi-temporal validity window, filled by
* the dream promotion path from the source signal's ISO temporal
* text. Emitted verbatim when supplied; absent leaves the field off.
*/
readonly valid_from?: string;
readonly valid_until?: string;
/**
* Caller-settable expiration (C5 / t_a82b674e). ISO date
* (`YYYY-MM-DD`) or full timestamp. Additive and optional: absent →
* the write is byte-identical to the historical path. When present it
* is validated and stamped into frontmatter; the default read/list
* path drops a preference past this date unless the caller opts into
* `showExpired`. Orthogonal to dream retirement — the file is never
* moved to `Brain/retired/` on expiry.
*/
readonly expiration_date?: string;
/**
* Knowledge-pack provenance stamp (`<name>@<digest12>`), supplied only
* by the pack installer. Emitted only when supplied, so every other
* write is byte-identical. The key is user-tier to the frontmatter
* merge, so a later framework rewrite (the dream refresh) that does not
* pass it keeps the stamp instead of dropping it.
*/
readonly knowledge_pack?: string;
/** Optional extra tags merged after the canonical set. */
readonly extraTags?: ReadonlyArray<string>;
/** Free-form "How to apply" prose (rendered as a section). */
readonly howToApply?: string;
/**
* Client-supplied idempotency key (C1 / t_213f356b). Additive and
* optional: absent → the write is byte-identical to the historical
* path. When present, the writer hashes the identity-defining fields
* (slug, topic, principle, scope, status, evidenced_by — never the
* timestamps or dream-owned counters) and consults the idempotency
* ledger. A repeat with the same key + same payload is a deduped no-op;
* the same key + a different payload throws
* {@link IdempotencyPayloadMismatchError}. Used by the force-confirmed
* feedback path and by C4's session checkpoint.
*/
readonly idempotency_key?: string;
/**
* Recent `apply-evidence applied` rows for this pref, derived from
* `Brain/log/`. Newest first. Used by {@link renderPreferenceBody}
* to render `## Recent applications` so the file mirrors what the
* counters say.
*/
readonly recentApplied?: ReadonlyArray<BrainEvidenceSummary>;
/**
* Recent `apply-evidence violated` / `outdated` rows. Newest first.
*/
readonly recentViolated?: ReadonlyArray<BrainEvidenceSummary>;
}
export interface WritePreferenceOptions {
/** When true, overwrite an existing file at the target path. */
readonly overwrite?: boolean;
/**
* Plugin config the writing agent's identity is resolved from when the
* ownership gate stamps a newly created preference. Absent falls back
* to the default config discovery, which is what every other core
* writer that takes an identity does (`note.ts`, `decisions/record.ts`).
* A surface that runs against a non-default config - the MCP server
* started with `--config`, any `o2b brain` verb - passes its own, so
* the stamped owner is the identity that surface answers under.
*/
readonly configPath?: string;
/**
* The credential-minted subject of the caller (write-side-trust, Task
* 7), when the transport resolved one. When present it WINS over the
* config resolution everywhere this writer resolves an identity: the
* owner-write gate's resolved identity, the subject the permissions
* document is consulted under, and the owner stamped onto a newly
* created preference. Absent (stdio, the CLI) keeps the
* config-derived identity.
*/
readonly subject?: WriteSubject;
/**
* Who decided this write, for the brain store dual write (task 1.11):
* `human` (an operator command), `agent` (an agent or an automatic pass
* such as dream) or `model` (a decision-model verdict). Absent derives
* it from the process's origin channel (`authorityFromOrigin`). It does
* not change the legacy file.
*/
readonly authority?: Authority;
}
export interface ParsePreferenceOptions {
readonly schemaVocabulary?: BrainSchemaVocabulary;
}
export interface WritePreferenceResult {
readonly path: string;
readonly id: string;
/**
* Set to `true` when an `idempotency_key` matched a prior write with an
* identical payload, so this call was a deduped no-op. Absent on a
* normal write, so existing callers are unaffected.
*/
readonly deduped?: boolean;
}
export interface MoveToRetiredOptions {
readonly now: Date;
readonly retired_by: string;
readonly superseded_by?: string;
/**
* Free-form reason supplied by `o2b brain reject --reason <text>`.
* Persisted to the retired frontmatter as `user_rejected_reason`
* and rendered in the `## Retired` body block. Required by the CLI
* for `user-rejected` retires; left undefined for automatic
* retire-reasons emitted by dream.
*/
readonly user_rejected_reason?: string;
/**
* Pre-collected evidence slice to render into the retired snapshot.
* Dream passes this to avoid re-scanning the log when it already
* computed evidence during the refresh phase; the CLI reject path
* leaves it undefined and {@link moveToRetired} collects internally.
*/
readonly evidenceApplied?: ReadonlyArray<BrainEvidenceSummary>;
readonly evidenceViolated?: ReadonlyArray<BrainEvidenceSummary>;
/**
* Opt-in per-preference audit (Brain lifecycle suite F1). When
* supplied, a `retire` record is appended to the original
* preference's audit trail (`pref-<slug>.jsonl`) so the whole
* lifecycle stays in one file. The retire reason is taken from the
* `reason` argument, not from the sink. Omitting it preserves
* pre-suite behaviour (no audit file).
*/
readonly audit?: { readonly agent: string };
/**
* Who decided this write, for the brain store dual write (task 1.11):
* `human` (an operator command), `agent` (an agent or an automatic pass
* such as dream) or `model` (a decision-model verdict). Absent derives
* it from the process's origin channel (`authorityFromOrigin`). It does
* not change the legacy file.
*/
readonly authority?: Authority;
}
export interface MoveToRetiredResult {
readonly path: string;
readonly id: string;
}
// ----- Writer ---------------------------------------------------------------
/**
* Write a preference atomically to `Brain/preferences/pref-<slug>.md`.
*
* The frontmatter snapshot includes every field on `BrainPreference`,
* with safe defaults for the optional counters (zero) and confidence
* (`low`). The body is the canonical three-section layout described in
* §5.3 — "## Principle", "## Origin", "## How to apply".
*/
export function writePreference(
vault: string | null,
input: WritePreferenceInput,
options: WritePreferenceOptions = {},
): WritePreferenceResult {
// Vault-identity guard (context-integrity-gates, Unit J). This writer
// reaches the tree through `preferencePath`, not `brainDirs`, so
// `brainDirsForWrite` cannot cover it - the assertion has to sit at
// the entry point, ahead of the field validation and every write.
// With no vault the store write checks the store identity instead.
if (vault !== null) assertVaultIdentityForWrite(vault);
if (!input.slug?.trim()) throw new Error("preference missing field: slug");
if (!input.topic?.trim()) throw new Error("preference missing field: topic");
if (!input.principle?.trim()) {
throw new Error("preference missing field: principle");
}
if (!input.created_at?.trim()) {
throw new Error("preference missing field: created_at");
}
if (!input.unconfirmed_until?.trim()) {
throw new Error("preference missing field: unconfirmed_until");
}
if (
input.status !== BRAIN_PREFERENCE_STATUS.unconfirmed &&
input.status !== BRAIN_PREFERENCE_STATUS.confirmed &&
input.status !== BRAIN_PREFERENCE_STATUS.quarantine
) {
throw new Error(
`preference field 'status' must be 'unconfirmed', 'confirmed', or 'quarantine'; got ${JSON.stringify(input.status)}`,
);
}
const slug = validateSlug(input.slug);
const path = preferencePathOf(vault, slug);
const id = `pref-${slug}`;
// Every store record written from here on (an owner-write decision row,
// the idempotency receipt, the preference's records, anything a writer
// below appends) carries one verdict (`store/operation-scope.ts`): the
// caller's fields as the page will carry them and its whole input, and
// the page the write lands on, as it reads when the first record is
// judged. Both sides of the merge a rewrite makes are so covered.
const privacy = operationPrivacy(vault, {
inherit: [
() =>
preferencePrivacy(vault, storeFieldsOf(preferenceFrontmatter(input, id)), [
callerInput(input, PREFERENCE_OPAQUE_FIELDS),
])(),
() =>
vault !== null &&
existsSync(path) &&
preferencePrivacy(vault, storeFieldsOf(parseFrontmatter(path)[0]))(),
// Store-only: the preference the write lands on, as the fold holds it.
() =>
preferencesStoreOnly(vault, options.configPath) &&
(storePreferenceEntry(slug, options.configPath)?.private ?? false),
],
});
return withOperationPrivacy(privacy, () =>
writeJudgedPreference(vault, input, options, slug, path, id),
);
}
function writeJudgedPreference(
vault: string | null,
input: WritePreferenceInput,
options: WritePreferenceOptions,
slug: string,
path: string,
id: string,
): WritePreferenceResult {
// Ownership (a-label-is-not-a-boundary, U1). Resolved BEFORE the
// idempotency hash so a write that changes the owner cannot dedupe
// against one that did not - the hash already folds `owner` in for
// exactly that reason.
const owned = withResolvedOwner(vault, path, input, options.configPath, options.subject);
// Idempotency consult (C1): a repeat with the same key + same payload
// dedupes; the same key + a different payload throws before any write.
const idKey = owned.idempotency_key?.trim();
let idContentHash: string | undefined;
if (idKey) {
idContentHash = computePayloadHash(preferencePayloadFields(owned, slug));
const existing = lookupKey(vault, idKey);
if (existing) {
if (existing.contentHash === idContentHash) {
return { path, id, deduped: true };
}
throw new IdempotencyPayloadMismatchError(idKey, existing.contentHash, idContentHash);
}
}
if (vault === null || preferencesStoreOnly(vault, options.configPath)) {
return writeStorePreference(vault, input, options, owned, path, id, idKey, idContentHash);
}
let metadata = preferenceFrontmatter(owned, id);
const body = renderPreferenceBody(owned);
if (options.overwrite && existsSync(path)) {
// Tier guard (write-time-integrity-governance): rewrites merge
// through the tier model so a user-tier field a human added by
// hand survives, framework-owned legacy keys the writer no longer
// emits are dropped, and a changed identity join key throws
// instead of being silently re-accepted. An unreadable existing
// file or schema pack falls back to the plain framework write.
try {
const [existingMeta] = parseFrontmatter(path);
metadata = mergeFrontmatterTiered(existingMeta, metadata, {
kind: "brain-preference",
pack: loadSchemaPack(vault),
});
} catch (exc) {
if (exc instanceof FrontmatterTierConflictError) throw exc;
}
// Content-level idempotency: skip the rename when the file would
// be byte-identical. Keeps the dream invariant "a no-op rerun
// must not rewrite preference files" even after v0.10.1 expanded
// what dream recomputes per pass (evidence slices), and it spares
// Syncthing peers from spurious sync events.
try {
const next = formatFrontmatter(metadata, body);
const prev = readFileSync(path, "utf8");
if (next === prev) {
const unchanged = preferencePrivacy(vault, storeFieldsOf(metadata), [
callerInput(input, PREFERENCE_OPAQUE_FIELDS),
]);
recordPreferenceKey(vault, idKey, idContentHash, owned.created_at, id, path, unchanged);
return { path, id };
}
} catch {
// Fall through to the atomic write — a read failure should not
// prevent a legitimate update.
}
}
writeFrontmatterAtomic(path, metadata, body, {
overwrite: options.overwrite ?? false,
existsErrorKind: "preference",
vaultForRelativePath: vault,
});
// One privacy verdict for every store record this write produces: the
// idempotency receipt and the preference's human and derived records,
// judged from the fields they carry and the caller's whole input.
const written = withGuidance(storeFieldsOf(metadata), owned, metadata, body);
const privacy = preferencePrivacy(vault, written, [callerInput(input, PREFERENCE_OPAQUE_FIELDS)]);
recordPreferenceKey(vault, idKey, idContentHash, owned.created_at, id, path, privacy);
// Brain store dual write (task 1.11): off by default, never fails this write.
dualWrite(
() =>
preferenceStoreRecords(id, written, options.authority ?? authorityFromOrigin(), privacy()),
{ vault, ...(options.configPath !== undefined ? { configPath: options.configPath } : {}) },
);
return { path, id };
}
/**
* The store-only preference write (task 2.10): no page, the preference's
* records only. The rules the page writer keeps hold for the fold: a
* create refuses a preference the fold already holds active (as the
* exclusive create refuses an existing page), and an overwrite that would
* change no field the fold holds writes nothing (the page writer's
* byte-identical no-op), so a no-op dream rerun appends no record.
*/
function writeStorePreference(
vault: string | null,
input: WritePreferenceInput,
options: WritePreferenceOptions,
owned: WritePreferenceInput,
path: string,
id: string,
idKey: string | undefined,
idContentHash: string | undefined,
): WritePreferenceResult {
const slug = id.slice("pref-".length);
const found = storePreferenceEntry(slug, options.configPath);
const live = found !== undefined && !isRetiredEntry(found) ? found : undefined;
if (live !== undefined && options.overwrite !== true) {
throw new FileAlreadyExistsError(path, {
kind: "preference",
displayPath: vault === null ? path : relative(vault, path),
});
}
const frontmatter = preferenceFrontmatter(owned, id);
const written = withGuidance(
storeFieldsOf(frontmatter),
owned,
frontmatter,
renderPreferenceBody(owned),
);
const privacy = preferencePrivacy(vault, written, [callerInput(input, PREFERENCE_OPAQUE_FIELDS)]);
// A record only proposes the fields it names, so the fields a retired
// life left in the fold are cleared explicitly (`null`): a retire's
// metadata never rides on a live preference, and a slug brought back
// starts with no prose of its old life, as a fresh page would.
const cleared = clearedFields(found, written, live === undefined);
if (
options.overwrite === true &&
Object.keys(cleared).length === 0 &&
fieldsUnchanged(preferenceFields(written), live)
) {
recordPreferenceKey(vault, idKey, idContentHash, owned.created_at, id, path, privacy);
return { path, id };
}
const fields = { ...written, ...cleared };
storeWrite(
() => preferenceStoreRecords(id, fields, options.authority ?? authorityFromOrigin(), privacy()),
{ vault, ...(options.configPath !== undefined ? { configPath: options.configPath } : {}) },
);
recordPreferenceKey(vault, idKey, idContentHash, owned.created_at, id, path, privacy);
return { path, id };
}
/** Fields only a retire writes: never part of a live preference. */
const RETIRE_ONLY_FIELDS: ReadonlyArray<string> = Object.freeze([
"retired_at",
"retired_reason",
"retired_by",
"superseded_by",
"user_rejected_reason",
]);
/**
* The fields of `found` a write of `written` must clear: the retire-only
* ones it holds, and, when the write brings a retired slug back
* (`revive`), every field of the old life the write does not name (its
* prose, scope, aliases, merge pointer, rejection and guidance fields),
* so the result is the fresh page an unswitched machine writes beside the
* retired one. The counters are derived, never fields.
*/
function clearedFields(
found: StorePreference | undefined,
written: Readonly<Record<string, unknown>>,
revive: boolean,
): Record<string, null> {
const out: Record<string, null> = {};
if (found === undefined) return out;
const names = revive ? Object.keys(found.state.fields) : RETIRE_ONLY_FIELDS;
for (const name of names) {
const held = found.state.fields[name];
if (!(name in written) && held !== undefined && held !== null) out[name] = null;
}
return out;
}
export {
derivedPreferenceBody,
preferencePageBody,
preferencePageProse,
withPreferenceProse,
} from "./preference-body.ts";
/**
* The store fields of a `writePreference` write, with the page body as
* `text` when the caller handed prose guidance (`howToApply`), the one
* part of the body the fields do not render. A write without guidance
* leaves `text` as it is: the page writer re-renders the body from the
* fields, and prose another writer left in the fold is not overwritten.
*/
function withGuidance(
fields: Record<string, unknown>,
owned: WritePreferenceInput,
meta: FrontmatterMap,
body: string,
): Record<string, unknown> {
if (!owned.howToApply?.trim()) return fields;
const prose = preferencePageProse(meta, body, false);
return prose === null ? fields : { ...fields, [PREFERENCE_TEXT_FIELD]: prose };
}
/**
* The `owner:` a write emits, in one place for every writer.
*
* Three sources, in this order, and the order is the whole rule:
*
* 1. **The caller's explicit token** - after the owner-write gate has
* had its say ({@link gateNamedOwner}): the token still decides,
* but under `integrity.owner_scope_writes` a name that disagrees
* with the resolved identity is refused rather than honoured, so
* the claim a write records is one the caller was allowed to make.
* An absent explicit token skips the gate entirely, which is what
* keeps the restore and import paths byte-identical.
* 2. **What the file already says.** A rewrite NEVER re-owns. Ownership
* is a property of the agent that created the memory, so a dream
* pass, a merge or a refresh run by anyone cannot quietly transfer
* it, and a page created before the gate was switched on stays
* shared rather than being retro-owned by whoever rewrote it first.
* 3. **The server-resolved writing identity**, and only when creating a
* new file with `integrity.owner_scope_delivery` switched on.
*
* With the gate `off` this returns the input untouched, so a vault that
* never opted in is byte-identical - the same contract `agent-scope.ts`
* and the delivery collector state for the read side.
*
* `warn` stamps as `fail` does, deliberately: it exists so an operator
* can see what `fail` would withhold before tightening the gate, and a
* mode that wrote no ownership would leave nothing to look at.
*
* Where they look is the FILES. This stamp is the whole of `warn`'s
* observability today: the read surfaces are inert under `warn`
* (`owner-scope-view.ts` states why), so the population `fail` would
* start withholding is visible by reading `owner:` off
* `Brain/preferences/`, not by any per-response field.
*
* The gate is read through {@link loadIntegrityConfigForWrite}, NOT the
* safe loader every reader uses. This is the WRITE side of the
* reader/writer asymmetry that loader documents: an unreadable
* `_brain.yaml` resolves STRICT for a reader, which only withholds more,
* but strict here means STAMP - so a single bad token in the YAML would
* have started marking new pages with an owner the operator never asked
* for, permanently, since ownership is carried forward and never
* re-derived. A writer cannot infer an intent to enable ownership from a
* file it could not read, so the write is refused with the parse failure
* named. Absent config is a different condition and still resolves to
* the defaults, i.e. `off`.
*/
function withResolvedOwner(
vault: string | null,
path: string,
input: WritePreferenceInput,
configPath: string | undefined,
subject?: WriteSubject,
): WritePreferenceInput {
const owner = resolvedOwnerFor(vault, path, input.owner, configPath, subject);
return owner === undefined ? input : { ...input, owner };
}
/**
* The `owner:` value a NEW preference file at `path` must carry, or
* `undefined` for "write no `owner:` field".
*
* The rule {@link withResolvedOwner} documents, exposed on its own so a
* writer that does not build a {@link WritePreferenceInput} can still
* ask it. `import-claude-memory.ts` is that writer: it renders its own
* frontmatter and calls `atomicWriteFileSync` directly, so it never
* reached `writePreference` and every memory it imported landed
* ownerless and was then delivered to every agent - while the claim
* "every production preference writer stamps the identity" was held true
* by a hand-written list of four writers that did not include it.
*
* Exported rather than duplicated for that reason: a second copy of this
* decision is how the fifth writer gets it wrong again.
*/
export function resolvedOwnerFor(
vault: string | null,
path: string,
explicit: string | undefined,
configPath: string | undefined,
subject?: WriteSubject,
): string | undefined {
const given = explicit?.trim();
if (given) return gateNamedOwner(vault, path, given, configPath, subject);
let mode: string;
try {
mode = loadIntegrityConfigForWrite(vault).owner_scope_delivery;
} catch (err) {
throw new Error(
`preference owner cannot be resolved: Brain/_brain.yaml exists but could not be ` +
`read (${err instanceof Error ? err.message : String(err)}), so whether ` +
`integrity.owner_scope_delivery asks this write to stamp an owner is unknown. ` +
`A writer does not guess that: stamping would mark this page with an owner the ` +
`operator may never have asked for, and skipping would leave it shared under a ` +
`gate that may be on. Fix the file, then re-run.`,
{ cause: err },
);
}
if (mode === GATE_MODE.off) return undefined;
if (vault === null || preferencesStoreOnly(vault, configPath)) {
// Store-only: the preference the fold holds carries its owner forward.
const held = storePreferenceEntry(basename(path, ".md").slice("pref-".length), configPath);
if (held !== undefined && !isRetiredEntry(held)) {
const owner = held.state.fields["owner"];
return typeof owner === "string" && owner.trim() !== "" ? owner.trim() : undefined;
}
} else if (existsSync(path)) return carriedOwner(path).owner;
const agent = subject?.agent ?? resolveAgentName(configPath);
const stamp = ownerStampFor(agent);
if (stamp === null) {
throw new Error(
`preference owner cannot be resolved: integrity.owner_scope_delivery is ` +
`${JSON.stringify(mode)}, which stamps the writing agent onto every new ` +
`preference, and the resolved identity ${JSON.stringify(agent)} does not ` +
`reduce to one ownership token - it is blank, it is not one string, or it is a ` +
`placeholder name (${JSON.stringify(UNCONFIGURED_AGENT_NAME)} and the rest of ` +
`PLACEHOLDER_AGENT_VALUES), which owner-scope delivery refuses as an identity ` +
`and therefore refuses as an owner; set VAULT_AGENT_NAME or 'agent_name' in ` +
`the plugin config to a real, non-placeholder name`,
);
}
return stamp;
}
/**
* The owner-write gate (write-side-trust, Task 8), consulted ONLY on the
* explicit-owner arm: a caller-named owner is a claim, and
* `integrity.owner_scope_writes` decides whether this caller may make it.
* An absent explicit token never reaches here, so the restore and import
* paths are byte-identical whatever the gate says.
*
* The gate mode reads through {@link loadIntegrityConfigSafe}, NOT the
* writer loader the stamp arm uses, and the difference is the same
* reader/writer asymmetry the stamp arm documents, resolved the other way
* for a refusal gate. Strict here means REFUSE - the unreadable config
* cannot loosen this gate, it can only close it - so failing closed to
* `fail` is the conservative direction and the operator's typo stops the
* foreign-owner write instead of waving it through. An unreadable
* permissions document raises through Lane A's loader with the field
* named, which is that document's own fail-closed contract.
*
* Under `warn` a cross-owner write passes and exactly one decision-ledger
* row is appended with the gate key as its source: warn exists so an
* operator can watch what `fail` would refuse, and the row IS the
* watching. The row condition recomputes the same normalised comparison
* the predicate makes - the module exposes only the pinned predicate and
* key - and only the case `fail` would refuse logs, so a matching-owner
* write stays silent.
*
* A failed ledger append never fails the write: the append contract
* returns `audit_reason` instead of throwing, and the verdict the caller
* already received must not be retroactively withdrawn because
* accountability could not be recorded.
*/
function gateNamedOwner(
vault: string | null,
path: string,
given: string,
configPath: string | undefined,
subject?: WriteSubject,
): string {
// The credential-minted subject wins over the config resolution
// (write-side-trust, Task 7): a token's owner gate answers for the
// token's agent, never for whoever the process config names.
const resolved = subject?.agent ?? resolveAgentName(configPath);
const gateMode = loadIntegrityConfigSafe(vault).owner_scope_writes;
// The permissions document: the operator's shared setting, or the legacy
// file on an unswitched machine (document-source.ts).
const { document } = loadPermissionsDocumentFor(vault, configPath);
const verdict = refuseCrossOwnerWrite({
explicitOwner: given,
resolvedIdentity: resolved,
gateMode,
document,
subject: substrateSubject(subject ?? { agent: resolved, via: "config" }),
});
if (verdict.refused) {
throw new Error(
`preference write at ${vault === null ? path : relative(vault, path)}: ${verdict.reason}`,
);
}
if (gateMode === GATE_MODE.warn) {
logWatchedOwnerWrite(vault, path, given, resolved, subject?.via ?? "config");
}
return given;
}
/**
* The one `warn` ledger row for an explicit-owner preference write, or
* nothing when the named owner agrees with the resolved identity (the
* one case `fail` would not refuse is the one case there is nothing to
* watch).
*/
function logWatchedOwnerWrite(
vault: string | null,
path: string,
given: string,
resolved: string,
via: WriteSubject["via"] = "config",
): void {
const named = normalizeAgentScope(given);
const identity = normalizeAgentScope(normalizeAgentArgument(resolved) ?? undefined);
if (named === null || identity === null || named === identity) return;
appendDecisionLedger(vault, {
ts: new Date().toISOString(),
actor: resolved,
via,
action: "owner_write",
target: vault === null ? path : relative(vault, path),
verdict: GATE_MODE.warn,
source: OWNER_SCOPE_WRITES_KEY,
reason:
`explicit owner ${JSON.stringify(given)} allowed under ${GATE_MODE.warn}; ` +
`${OWNER_SCOPE_WRITES_KEY}=${GATE_MODE.fail} would refuse it ` +
`(resolved identity ${JSON.stringify(resolved)})`,
});
}
/** Attribution recorded on the notices the ownership carry-forward reads produce. */
const OWNER_CARRY_SITE = "brain.preference.owner";
/**
* The ownership claim an existing preference file already carries, as a
* spreadable slice - `{}` when the file makes no claim this parser can
* reduce to one token.
*
* An unreadable file RAISES rather than resolving to `{}`. Every other
* degraded read on this path can afford to fall soft, but this one
* decides a boundary: resolving to "no claim" would republish an
* owner-private memory to every agent on the next rewrite, and nothing
* would have said so. A claim the parser cannot reduce to one token
* (`owner:` as a list or a mapping) is left alone instead, because the
* tiered frontmatter merge preserves it verbatim and re-emitting it as a
* normalised string would rewrite bytes this writer does not own.
*/
function carriedOwner(path: string): { owner?: string } {
const [meta, , notices] = parseFrontmatterWithNotices(path, { site: OWNER_CARRY_SITE });
const unreadable = notices.find((n) => n.code === DEGRADATION_CODE.frontmatterUnreadable);
if (unreadable) {
throw new Error(
`preference owner cannot be carried forward: ${path} exists but could not be ` +
`read (${unreadable.detail}), so the ownership this rewrite must preserve ` +
`is unknown`,
);
}
const raw = meta["owner"];
return typeof raw === "string" && raw.trim().length > 0 ? { owner: raw.trim() } : {};
}
/**
* The identity-defining fields of a preference for idempotency hashing.
* Timestamps, dream-owned counters, and confidence are excluded so a
* retried write (or a force-confirmed re-record) with the same rule
* dedupes regardless of when it arrives.
*/
function preferencePayloadFields(
input: WritePreferenceInput,
slug: string,
): Record<string, unknown> {
return {
slug,
topic: input.topic.trim(),
principle: sanitisePrinciple(input.principle),
scope: input.scope?.trim(),
status: input.status,
evidenced_by: [...input.evidenced_by],
// `owner` drives owner-scoped visibility and is written to frontmatter,
// so a retry that only changes it must NOT silently dedupe — fold it into
// the idempotency hash (mirrors the write path at recordPreference).
owner: input.owner?.trim(),
};
}
/**
* Record the idempotency key after a successful preference write so a
* future retry dedupes. No-op when no key was supplied.
*/
function recordPreferenceKey(
vault: string | null,
idKey: string | undefined,
contentHash: string | undefined,
createdAt: string,
id: string,
path: string,
privacy: OperationPrivacy,
): void {
if (!idKey || contentHash === undefined) return;
rememberKey(vault, {
key: idKey,
contentHash,
createdAt,
ref: { id, path: vault === null ? path : relative(vault, path) },
private: privacy,
});
}
/**
* Predicate twin of {@link writePreference}'s content-equality
* short-circuit. Returns `true` iff calling `writePreference(vault,
* input, { overwrite: true })` would change the on-disk bytes
* (file missing, or file present with different content). The dream
* pass uses this to decide whether a pref needs to land in the
* refresh set — emitting a refresh entry triggers a snapshot + log
* event, so we must not emit one if the rewrite would be a no-op.
*
* Cheap: one stat + one readFileSync + one render of frontmatter +
* body. Caller-side cost is negligible compared with the writePref
* + log overhead avoided when the body is up to date.
*/
export function wouldRewritePreference(vault: string | null, input: WritePreferenceInput): boolean {
const slug = validateSlug(input.slug);
const path = preferencePathOf(vault, slug);
if (vault === null || preferencesStoreOnly(vault)) {
// Store-only: the write changes something when a field the fold holds
// would take a new value (the store twin of the byte comparison).
try {
const found = storePreferenceEntry(slug);
if (found === undefined || isRetiredEntry(found)) return true;
const owned = withResolvedOwner(vault, path, input, undefined);
const frontmatter = preferenceFrontmatter(owned, `pref-${slug}`);
const written = withGuidance(
storeFieldsOf(frontmatter),
owned,
frontmatter,
renderPreferenceBody(owned),
);
return !fieldsUnchanged(preferenceFields(written), found);
} catch {
return true;
}
}
if (!existsSync(path)) return true;
try {
const id = `pref-${slug}`;
// The same ownership resolution the write performs, or this
// predicate reports "would change" on every owner-carrying
// preference forever: `writePreference` carries the existing owner
// forward, and a render that omitted it would never match the bytes
// on disk. No config path is needed - the file exists, so the
// resolution can only carry forward, never stamp.
const owned = withResolvedOwner(vault, path, input, undefined);
const rendered = preferenceFrontmatter(owned, id);
const body = renderPreferenceBody(owned);
// The same tier merge the overwrite write performs, or this
// predicate reports "would change" on every pass forever against a
// file carrying a user-tier field the render does not emit: the
// merge preserves the field, the comparison against a render that
// dropped it never matches, and each pass re-plans the rewrite the
// previous pass just performed. The write's fallback order is
// mirrored too - an unreadable existing file or schema pack
// compares against the plain render.
let metadata = rendered;
try {
const [existingMeta] = parseFrontmatter(path);
metadata = mergeFrontmatterTiered(existingMeta, rendered, {
kind: "brain-preference",
pack: loadSchemaPack(vault),
});
} catch (exc) {
if (exc instanceof FrontmatterTierConflictError) throw exc;
}
const next = formatFrontmatter(metadata, body);
const prev = readFileSync(path, "utf8");
return next !== prev;
} catch {
// Conservative: a read or render failure should not silently
// mark the file as up-to-date.
return true;
}
}
function preferenceFrontmatter(input: WritePreferenceInput, id: string): FrontmatterMap {
const tags = composePreferenceTags(input);
const confidence = input.confidence ?? BRAIN_CONFIDENCE.low;
const pinned = input.pinned ?? false;
const applied = input.applied_count ?? 0;
const violated = input.violated_count ?? 0;
// Round numeric confidence to 4 decimals so a no-op rerun produces
// byte-identical YAML even if upstream callers pass a value with
// floating-point jitter. `null` sentinel mirrors the other Group C
// null-encoded fields so the simple parser keeps round-tripping.
const confidenceValueRaw = input.confidence_value;
const confidenceValueField =
confidenceValueRaw === undefined || confidenceValueRaw === null
? "null"
: Math.round(confidenceValueRaw * 10000) / 10000;
// §24: Group C derived fields gain `_` prefix so the visual
// boundary between "what dream owns" and "what the user owns"
// becomes obvious in Obsidian. Identity (`kind`, `id`, `created_at`,
// `unconfirmed_until`, `topic`, `principle`, `scope`, `tags`,
// `aliases`, `supersedes`) and user-editable (`pinned`) stay
// unprefixed. Parser accepts both shapes; writer only emits the new.
const metadata: FrontmatterMap = {
kind: "brain-preference",
id,
created_at: input.created_at,
// Use a textual sentinel for `null` so the simple parser surfaces
// an empty string and the loader coerces back to `null`. We store
// the literal text "null" rather than an empty value to keep the
// emitted YAML one-token per line and the field always present.
_confirmed_at: input.confirmed_at ?? "null",
unconfirmed_until: input.unconfirmed_until,
tags: [...tags],
topic: input.topic.trim(),
_status: input.status,
principle: sanitisePrinciple(input.principle),
_evidenced_by: [...input.evidenced_by],
_applied_count: applied,
_violated_count: violated,
_last_evidence_at: input.last_evidence_at ?? "null",
_confidence: confidence,
_confidence_value: confidenceValueField,
pinned,
};
// Brain Integrity Suite additive fields. Both follow the
// `_lifecycle` precedent: emit only when the caller supplies a
// value so legacy fixtures and the starter bundle stay
// byte-identical with absent-as-default reader semantics.
if (input.revision !== undefined) metadata["_revision"] = input.revision;
if (input.content_hash) metadata["_content_hash"] = input.content_hash;
if (input.scope?.trim()) metadata["scope"] = input.scope.trim();
if (input.owner?.trim()) metadata["owner"] = input.owner.trim();
if (input.knowledge_pack?.trim()) {
metadata[KNOWLEDGE_PACK_FIELD] = input.knowledge_pack.trim();
}
// Only emit a non-default provenance; absent reads as `stated`, so an
// existing preference stays byte-identical.
if (input.provenance !== undefined && input.provenance !== "stated") {
metadata["provenance"] = input.provenance;
}
if (input.supersedes?.trim()) metadata["supersedes"] = input.supersedes.trim();
if (input.aliases && input.aliases.length > 0) {
metadata["aliases"] = [...input.aliases];
}
if (input.schema_type?.trim()) {
metadata["schema_type"] = validateSchemaToken(input.schema_type, "schema_type");
}
if (input.memory_layer !== undefined) {
metadata["memory_layer"] = validateMemoryLayer(input.memory_layer, "writePreference");
}
if (input.memory_branch?.trim()) {
metadata["memory_branch"] = validateMemoryBranch(input.memory_branch, "writePreference");
}
for (const field of PREFERENCE_RELATION_FIELDS) {
const values = input[field];
if (values && values.length > 0) metadata[field] = [...values];
}
// `_lifecycle` is emitted only when the caller supplies it. Legacy
// call sites stay byte-identical; new writers (dream refresh pass,
// lint consolidate) opt in by passing the field. Readers fall back
// to `stable` via `readLifecycle()`.
if (input.lifecycle !== undefined) {
metadata["_lifecycle"] = input.lifecycle;
}
// `tier` is user-editable (unprefixed). Emitted only when supplied;
// readers fall back to `supporting` via `readTier()`.
if (input.tier !== undefined) {
metadata["tier"] = input.tier;
}
// `commitment` tier (B3): validated on write, emitted only when a valid
// tier is supplied so unset preferences stay byte-identical.
const commitment = validateCommitmentTier(input.commitment);
if (commitment !== null) {
metadata["commitment"] = commitment;
}
// Brain lifecycle suite (F5): bi-temporal validity, emitted only when
// supplied (e.g. dream filled it from the source signal's ISO text).
// Reader-side support already exists via readBitemporalSlots; legacy
// callers stay byte-identical.
if (input.valid_from?.trim()) metadata["valid_from"] = input.valid_from.trim();
if (input.valid_until?.trim()) metadata["valid_until"] = input.valid_until.trim();
// Caller-settable expiration (C5): validated + emitted only when
// supplied so legacy callers stay byte-identical. Reader-side support
// is via parsePreference's optional-scalar read + the expiration filter.
if (input.expiration_date?.trim()) {
metadata[EXPIRATION_DATE_FIELD] = normalizeExpirationDate(input.expiration_date);
}
// Freshness trend (t_ee09a6ce): stamped by the dream refresh pass;
// emitted only when supplied so legacy callers stay byte-identical.
if (input.freshness_trend?.trim()) metadata["freshness_trend"] = input.freshness_trend.trim();
if (input.visibility !== undefined && input.visibility.length > 0) {
metadata["visibility"] = [...input.visibility];
}
return metadata;
}
function composePreferenceTags(input: WritePreferenceInput): string[] {
const out: string[] = [];
const seen = new Set<string>();
const push = (t: string): void => {
if (!seen.has(t)) {
seen.add(t);
out.push(t);
}
};
// Composed values obey the ONE shared tag rule (`src/core/tags.ts`, via
// `tag-syntax.ts`), with the same polarity as the signal composer: the
// topic segment is slugified then validated; scope segments and
// `extraTags` entries are caller-controlled input, refused unrewritten
// with the field named. A comma-separated scope composes one tag per
// segment (`scopeTagValues`); `lenientScopeTags` relaxes the scope
// refusal for rewrites of persisted records.
push("brain");
push("brain/preference");
push(`brain/topic/${requireObsidianTagValue(slugify(input.topic.trim()), "topic")}`);
for (const scope of scopeTagValues(input.scope ?? "", {
record: `pref-${input.slug}`,
lenient: input.lenientScopeTags === true,
})) {
push(`brain/scope/${scope}`);
}
for (const t of input.extraTags ?? []) {
if (t.trim()) push(requireObsidianTagValue(t.trim(), "extraTags"));
}
return out;
}
// ----- Parsers --------------------------------------------------------------
export { DERIVED_FIELDS };
/**
* Rename `_`-prefixed Group C keys (`_status`, `_applied_count`, ...)
* to their canonical un-prefixed form so every downstream
* `meta[name]` call site keeps working. Returns a shallow copy of
* `meta`; original is untouched. Exported because the backlink
* index and other raw-frontmatter consumers need the same rule.
*/
export function normalizeDerivedKeys(meta: Record<string, unknown>): Record<string, unknown> {
const out: Record<string, unknown> = { ...meta };
for (const name of DERIVED_FIELDS) {
if (name in out && out[name] !== undefined) {
throw new Error(
`frontmatter field '${name}' must use the '_'-prefixed shape ('_${name}'); ` +
"un-prefixed Group C keys are no longer accepted",
);
}
const prefixed = `_${name}`;
if (prefixed in out && out[prefixed] !== undefined) {
out[name] = out[prefixed];
delete out[prefixed];
}
}
return out;
}
/**
* A preference's frontmatter under the field names the brain store folds
* (dual writes, task 1.11): derived keys lose their on-disk `_` prefix and
* the textual `"null"` sentinel becomes `null`, so the store holds what
* the file means rather than how it is spelled.
*/
export function storeFieldsOf(meta: Record<string, unknown>): Record<string, unknown> {
const out = normalizeDerivedKeys(meta);
for (const name of DERIVED_FIELDS) if (out[name] === "null") out[name] = null;
return out;
}
const DERIVED_FIELD_SET: ReadonlySet<string> = new Set(DERIVED_FIELDS);
/** The derived field a retire decides itself, at the retiring caller's authority. */
const RETIRE_DECIDED_FIELDS: ReadonlyArray<string> = Object.freeze(["status"]);
/**
* The single privacy verdict of a preference write
* (`store/operation-privacy.ts`), from the fields the store records carry:
* the frontmatter reserving the preference as private, or any content
* field (`principle`, `evidenced_by`, `supersedes` and the other
* relationship fields, ...) naming a private or unresolvable page or
* carrying a `<private>` region. `extra` is further content of the same
* operation (the writer's caller input, a pin's log event). Judged once,
* on first use.
*/
export function preferencePrivacy(
vault: string | null,
fields: Readonly<Record<string, unknown>>,
extra: ReadonlyArray<JudgedContent> = [],
): OperationPrivacy {
return operationPrivacy(vault, {
target: () => isPrivateFrontmatter(fields),
content: [{ value: fields, opaque: PREFERENCE_OPAQUE_FIELDS }, ...extra],
});
}
/**
* The brain store records of one preference write (dual writes, task
* 1.11). Fields the fold resolves by authority first: when a human writes,
* only the fields the human decided carry human authority. The derived
* fields the dream pass owns ({@link DERIVED_FIELDS}, minus `decided`, the
* ones this write itself decides) go out in a second record at agent
* authority, so a later dream write can still win them, as it does on the
* file. Every record keeps the scope the whole preference has and the
* partition of the write's one privacy verdict (`isPrivate`).
*/
export function preferenceStoreRecords(
id: string,
fields: Readonly<Record<string, unknown>>,
authority: Authority,
isPrivate: boolean,
decided: ReadonlyArray<string> = [],
): DualWriteRecord[] | null {
const whole = preferenceSetRecord({ id, frontmatter: fields, authority, private: isPrivate });
if (whole === null) return null;
if (authority !== "human") return [whole];
const keep = new Set(decided);
const own: Record<string, unknown> = {};
const derived: Record<string, unknown> = {};
for (const [name, value] of Object.entries(fields)) {
if (DERIVED_FIELD_SET.has(name) && !keep.has(name)) derived[name] = value;
else own[name] = value;
}
const placement = { scope: whole.scope ?? null };
const out: DualWriteRecord[] = [];
for (const record of [
preferenceSetRecord({ id, frontmatter: own, authority, private: isPrivate }),
preferenceSetRecord({ id, frontmatter: derived, authority: "agent", private: isPrivate }),
]) {
if (record !== null) out.push({ ...record, ...placement });
}
return out;
}
/**
* Parse a preference file. Defaults `pinned` to `false` when the field
* is absent (§5.3). Throws {@link BrainStatusFolderMismatchError} when
* the file lives in `preferences/` but its `status` reads `retired`
* (or any other state outside `unconfirmed` / `confirmed`).
*
* Derived Group C fields use the `_`-prefixed shape on disk
* (`_status:`, `_applied_count:`, ...); {@link normalizeDerivedKeys}
* renames them to the un-prefixed form for downstream readers.
*/
export function parsePreference(
path: string,
options: ParsePreferenceOptions = {},
): BrainPreference {
// The body is unused for preferences — it is purely human prose;
// every machine-actionable field lives in the frontmatter.
return preferenceFromMeta(parseFrontmatter(path)[0], path, options);
}
/**
* The preference `pref-<slug>` of the vault: its page on an unswitched
* machine, the store's fold once switched (task 2.10), or `null` when it
* does not exist (or is retired). Parsed by the same rules either way.
*/
export function loadPreference(
vault: string | null,
slug: string,
options: ParsePreferenceOptions & { readonly configPath?: string } = {},
): BrainPreference | null {
const path = preferencePathOf(vault, slug);
// No vault means store-only too (design D14).
if (vault === null || preferencesStoreOnly(vault, options.configPath)) {
const page = storePreferenceMeta(slug, options.configPath);
return page === null || page.retired ? null : preferenceFromMeta(page.meta, path, options);
}
return existsSync(path) ? parsePreference(path, options) : null;
}
/**
* Whether the preference `pref-<slug>` is active, retired or absent: its
* pages on an unswitched machine, the store's fold once switched.
*/
export function preferencePresence(
vault: string | null,
slug: string,
configPath?: string,
): "active" | "retired" | "absent" {
if (vault === null || preferencesStoreOnly(vault, configPath)) {
const entry = storePreferenceEntry(slug, configPath);
if (entry === undefined) return "absent";
return isRetiredEntry(entry) ? "retired" : "active";
}
if (existsSync(preferencePath(vault, slug))) return "active";
return existsSync(retiredPath(vault, slug)) ? "retired" : "absent";
}
/**
* The preference `pref-<slug>` as its page would carry it, rebuilt from
* the store's fold: the fold's fields under their on-disk names (derived
* fields `_`-prefixed, `null` as the textual sentinel), the counters the
* fold derives, and the page's identity keys. The result goes through the
* page writer and parser once, so every value has the type the legacy
* parser gives it. `null` when the fold does not hold the preference.
*/
export function storePreferenceMeta(
slug: string,
configPath?: string,
): {
readonly meta: FrontmatterMap;
readonly retired: boolean;
/** The page body the fold carries (`text`), or `null` when no writer wrote one. */
readonly text: string | null;
} | null {
const entry = storePreferenceEntry(slug, configPath);
if (entry === undefined) return null;
return { ...storeEntryMeta(entry, slug), text: textOfFields(entry.state.fields) };
}
function preferenceFromMeta(
rawMeta: FrontmatterMap,
path: string,
options: ParsePreferenceOptions,
): BrainPreference {
const meta = normalizeDerivedKeys(rawMeta);
requireField(meta, "kind", path);
if (meta["kind"] !== "brain-preference") {
throw new BrainParseError(
`preference kind must be 'brain-preference'; got ${JSON.stringify(meta["kind"])}`,
path,
);
}
const status = requireString(meta, "status", path);
// Reject unknown status values BEFORE the folder invariant: a malformed
// file should never coerce into a typed `BrainPreference.status`
// downstream, regardless of which folder it sits in. We tolerate
// `status: "retired"` here because that case is the dedicated
// status-folder-mismatch the parser surfaces below as a typed error
// (doctor downgrades it to a warning) — see §4 of the design doc.
const statusValues = Object.values(BRAIN_PREFERENCE_STATUS) as ReadonlyArray<string>;
// `tombstoned` (Belief lifecycle suite, t_7d5a3589) is a cross-type
// lifecycle status the tombstone module stamps into `_status` in place.
// It is tolerated on read - like `retired` - so an audit read and the
// doctor see a coherent tombstoned entry rather than a corrupt file;
// recall / inject / active.md / dream exclude it via `isTombstoned`.
if (!statusValues.includes(status) && status !== "retired" && status !== BRAIN_TOMBSTONE_STATUS) {
throw new BrainParseError(
`preference status must be one of ${statusValues.join(", ")}; got ${JSON.stringify(status)}`,
path,
);
}
enforceStatusFolderInvariant(path, status, "preferences");
const id = requireString(meta, "id", path);
const created_at = requireString(meta, "created_at", path);
const unconfirmed_until = requireString(meta, "unconfirmed_until", path);
const tags = requireStringArray(meta, "tags", path);
const topic = requireString(meta, "topic", path);
const principle = requireString(meta, "principle", path);
const evidenced_by = optionalStringArray(meta, "evidenced_by", path);
const confirmed_at = optionalNullableString(meta, "confirmed_at", path);
const last_evidence_at = optionalNullableString(meta, "last_evidence_at", path);
// Provenance level: validated through the shared narrowing guard, never cast.
const provenance = asProvenanceLevel(meta["provenance"]);
const result: BrainPreference = {
kind: "brain-preference",
id,
created_at,
confirmed_at,
unconfirmed_until,
tags,
topic,
status: status as BrainPreferenceStatus,
principle,
evidenced_by,
applied_count: optionalNumber(meta, "applied_count", 0, path),
violated_count: optionalNumber(meta, "violated_count", 0, path),
last_evidence_at,
confidence: parseConfidence(meta, path),
confidence_value: parseConfidenceValue(meta, path),
pinned: parsePinned(meta),
revision: optionalNumber(meta, "revision", 0, path),
...(optionalScalarString(meta, "content_hash") !== undefined
? { content_hash: optionalScalarString(meta, "content_hash") }
: {}),
...(optionalScalarString(meta, "scope") !== undefined
? { scope: optionalScalarString(meta, "scope") }
: {}),
...(optionalOwnerField(meta) !== undefined ? { owner: optionalOwnerField(meta) } : {}),
...(provenance !== null ? { provenance } : {}),
...(optionalScalarString(meta, "freshness_trend") !== undefined
? { freshness_trend: optionalScalarString(meta, "freshness_trend") }
: {}),
...(optionalScalarString(meta, "expiration_date") !== undefined
? { expiration_date: optionalScalarString(meta, "expiration_date") }
: {}),
// Surfaced only when the value is a well-formed stamp: a hand-typed
// `knowledge_pack:` that is not one names no pack an uninstall keys on.
...(parseKnowledgePackStamp(meta[KNOWLEDGE_PACK_FIELD]) !== null
? { knowledge_pack: String(meta[KNOWLEDGE_PACK_FIELD]).trim() }
: {}),
...(optionalScalarString(meta, "supersedes") !== undefined
? { supersedes: optionalScalarString(meta, "supersedes") }
: {}),
...(readMergedInto(meta) !== null ? { merged_into: readMergedInto(meta)! } : {}),
...(readCommitmentTier(meta) !== null ? { commitment: readCommitmentTier(meta)! } : {}),
...(meta["aliases"] !== undefined && Array.isArray(meta["aliases"])
? { aliases: [...(meta["aliases"] as ReadonlyArray<string>)] }
: {}),
...spreadSchemaMetadata(meta, path, "preference_types", options),
...spreadMemorySemantics(meta, path),
...spreadBiTemporal(meta),
};
return Object.freeze(result);
}
// `promised_to` stays out: pledge projection rides the shared
// frontmatter-relations ingest (see relation-vocab.ts), and the
// dated-commitments design rejects projecting pledges into preference
// facts as duplication.
type PreferenceRelationField = Exclude<DefaultRelationType, "superseded_by" | "promised_to">;
const PREFERENCE_RELATION_FIELDS = Object.freeze(
DEFAULT_RELATION_TYPES.filter(
(field): field is PreferenceRelationField =>
field !== "superseded_by" && field !== "promised_to",
),
);
function spreadMemorySemantics(
meta: Record<string, unknown>,
path: string,
): {
readonly memory_layer?: BrainMemoryLayer;
readonly memory_branch?: string;
readonly related?: ReadonlyArray<string>;
readonly extends?: ReadonlyArray<string>;
readonly depends_on?: ReadonlyArray<string>;
readonly refines?: ReadonlyArray<string>;
readonly contradicts?: ReadonlyArray<string>;
} {
const out: Record<string, BrainMemoryLayer | string | ReadonlyArray<string>> = {};
const memoryLayer = optionalScalarString(meta, "memory_layer");
if (memoryLayer !== undefined) {
out["memory_layer"] = validateMemoryLayer(memoryLayer, path);
}
const memoryBranch = optionalScalarString(meta, "memory_branch");
if (memoryBranch !== undefined) {
out["memory_branch"] = validateMemoryBranch(memoryBranch, path);
}
for (const field of PREFERENCE_RELATION_FIELDS) {
const values = optionalStringList(meta, field, path);
if (values !== undefined) out[field] = values;
}
return out;
}
function spreadSchemaMetadata(
meta: Record<string, unknown>,
path: string,
category: "preference_types" | "signal_types",
options: ParsePreferenceOptions,
): { readonly schema_type?: string } {
const raw = optionalScalarString(meta, "schema_type");
if (raw === undefined) return {};
const schemaType = validateSchemaToken(raw, "schema_type");
const vocab = options.schemaVocabulary;
if (vocab !== undefined && !isKnownSchemaToken(vocab, category, schemaType)) {
throw new BrainParseError(
`schema_type ${JSON.stringify(schemaType)} is not declared in ${category}`,
path,
);
}
return { schema_type: schemaType };
}
function validateMemoryLayer(value: string, path: string): BrainMemoryLayer {
if (isBrainMemoryLayer(value)) return value;
const allowed = Object.values(BRAIN_MEMORY_LAYER).join(", ");
throw new BrainParseError(
`preference field 'memory_layer' must be one of ${allowed}; got ${JSON.stringify(value)}`,
path,
);
}
function validateMemoryBranch(value: string, path: string): string {
try {
return validateSlug(value);
} catch (err) {
const reason = err instanceof Error ? err.message : String(err);
throw new BrainParseError(`preference field 'memory_branch' is invalid: ${reason}`, path, {
cause: err,
});
}
}
/**
* Read the additive bi-temporal slots (`valid_from`, `valid_until`,
* `recorded_at`) from a frontmatter map. Returns a partial object
* with only the slots the file actually carries; absent on legacy
* files. Shared between `parsePreference` and `parseRetired` so the
* spread call site stays one-line and the slot names live in exactly
* one place.
*/
function spreadBiTemporal(meta: Record<string, unknown>): {
readonly valid_from?: string;
readonly valid_until?: string;
readonly recorded_at?: string;
} {
const validFrom = optionalScalarString(meta, "valid_from");
const validUntil = optionalScalarString(meta, "valid_until");
const recordedAt = optionalScalarString(meta, "recorded_at");
return {
...(validFrom !== undefined ? { valid_from: validFrom } : {}),
...(validUntil !== undefined ? { valid_until: validUntil } : {}),
...(recordedAt !== undefined ? { recorded_at: recordedAt } : {}),
};
}
/**
* Parse a retired-preference file. Mirrors {@link parsePreference} but
* enforces the `retired/` folder invariant and validates the
* `retired_reason` enum.
*
* Shares {@link normalizeDerivedKeys} with `parsePreference` so
* both forms of Group C frontmatter parse identically.
*/
export function parseRetired(path: string, options: ParsePreferenceOptions = {}): BrainRetired {
return parseRetiredMeta(parseFrontmatter(path)[0], path, options);
}
/**
* {@link parsePreference} over frontmatter already read: a page's, or one
* rebuilt from the store's fold ({@link storePreferenceMeta}), so a reader
* that switched to the store parses by the page's rules (task 2.10).
*/
export function parsePreferenceMeta(
meta: FrontmatterMap,
path: string,
options: ParsePreferenceOptions = {},
): BrainPreference {
return preferenceFromMeta(meta, path, options);
}
/** {@link parseRetired} over frontmatter already read (see {@link parsePreferenceMeta}). */
export function parseRetiredMeta(
rawMeta: FrontmatterMap,
path: string,
options: ParsePreferenceOptions = {},
): BrainRetired {
const meta = normalizeDerivedKeys(rawMeta);
requireField(meta, "kind", path);
if (meta["kind"] !== "brain-retired") {
throw new BrainParseError(
`retired kind must be 'brain-retired'; got ${JSON.stringify(meta["kind"])}`,
path,
);
}
const status = requireString(meta, "status", path);
if (status !== "retired") {
throw new BrainStatusFolderMismatchError(
"retired file frontmatter status is not 'retired'",
path,
status,
"retired",
);
}
enforceStatusFolderInvariant(path, status, "retired");
const id = requireString(meta, "id", path);
const retired_at = requireString(meta, "retired_at", path);
const reasonStr = requireString(meta, "retired_reason", path);
const reasonValues = Object.values(BRAIN_RETIRED_REASON) as ReadonlyArray<string>;
if (!reasonValues.includes(reasonStr)) {
throw new BrainParseError(
`retired_reason must be one of ${reasonValues.join(", ")}; got ${JSON.stringify(reasonStr)}`,
path,
);
}
const retired_by = requireString(meta, "retired_by", path);
const created_at = requireString(meta, "created_at", path);
const tags = requireStringArray(meta, "tags", path);
const topic = requireString(meta, "topic", path);
const principle = requireString(meta, "principle", path);
const result: BrainRetired = {
kind: "brain-retired",
id,
status: "retired",
retired_at,
retired_reason: reasonStr as BrainRetiredReason,
retired_by,
created_at,
tags,
topic,
principle,
evidenced_by: optionalStringArray(meta, "evidenced_by", path),
applied_count: optionalNumber(meta, "applied_count", 0, path),
violated_count: optionalNumber(meta, "violated_count", 0, path),
last_evidence_at: optionalNullableString(meta, "last_evidence_at", path),
confidence: parseConfidence(meta, path),
confidence_value: parseConfidenceValue(meta, path),
pinned: parsePinned(meta),
...(optionalScalarString(meta, "scope") !== undefined
? { scope: optionalScalarString(meta, "scope") }
: {}),
// Retirement KEEPS ownership - see `BrainRetired.owner`.
...(optionalOwnerField(meta) !== undefined ? { owner: optionalOwnerField(meta) } : {}),
...(optionalScalarString(meta, "superseded_by") !== undefined
? { superseded_by: optionalScalarString(meta, "superseded_by") }
: {}),
...(meta["aliases"] !== undefined && Array.isArray(meta["aliases"])
? { aliases: [...(meta["aliases"] as ReadonlyArray<string>)] }
: {}),
...spreadSchemaMetadata(meta, path, "preference_types", options),
...spreadMemorySemantics(meta, path),
...(optionalScalarString(meta, "user_rejected_reason") !== undefined
? {
user_rejected_reason: optionalScalarString(meta, "user_rejected_reason"),
}
: {}),
...spreadBiTemporal(meta),
};
return Object.freeze(result);
}
// ----- preferences/ -> retired/ mover --------------------------------------
/**
* Move a preference into `Brain/retired/`. Rewrites the frontmatter
* with the retire metadata (status, kind, retired_at, retired_reason,
* retired_by, optional superseded_by) and preserves the inherited
* fields (topic, principle, evidenced_by, …).
*
* Body decision: we keep the original "## Principle" / "## Origin" /
* "## How to apply" sections and append a "## Retired" section that
* names the reason and pointer. The design doc §5.4 is silent on the
* body shape; keeping the prose intact (rather than truncating it)
* preserves the audit trail value — a future reader sees both what the
* rule was and why it left.
*
* The move is performed as: write the new file atomically under
* `retired/`, then `unlink` the original under `preferences/`. If the
* write fails, the original stays untouched. If the unlink fails after
* a successful write, the caller is left with both copies — `o2b brain
* doctor` flags the duplicate id.
*/
export function moveToRetired(
vault: string | null,
prefPath: string,
reason: BrainRetiredReason,
opts: MoveToRetiredOptions,
): MoveToRetiredResult {
// Pre-condition: ensure the source path is actually inside the
// canonical `preferences/` folder. Doing this check *before* any I/O
// means a buggy caller cannot trick us into deleting an unrelated
// file: a misrouted call fails fast with no destructive side effect.
// With no vault the paths are vault-relative and the store write checks
// the store identity (design D14).
const dirs = vault === null ? brainDirsOf(null) : brainDirsForWrite(vault);
if (dirname(prefPath) !== dirs.preferences) {
throw new Error(`moveToRetired: source path was not under preferences/: ${prefPath}`);
}
// Store-only (task 2.10): the preference is read from the store's fold
// and the retire is records only; no page is written or removed.
const storeOnly = vault === null || preferencesStoreOnly(vault);
const [meta, body] = storeOnly ? storeRetireSource(prefPath) : parseFrontmatter(prefPath);
if (meta["kind"] !== "brain-preference") {
throw new Error(
`moveToRetired: expected a preference file; got kind ${JSON.stringify(meta["kind"])} (${prefPath})`,
);
}
const oldId = requireString(meta, "id", prefPath);
if (!oldId.startsWith("pref-")) {
throw new Error(
`moveToRetired: preference id must start with 'pref-'; got ${oldId} (${prefPath})`,
);
}
const slug = oldId.slice("pref-".length);
if (!slug) {
throw new Error(`moveToRetired: empty slug derived from id ${oldId}`);
}
const newId = `ret-${slug}`;
const newPath = retiredPathOf(vault, slug);
// Build the new frontmatter map. We preserve every inherited field
// verbatim (`topic`, `principle`, `evidenced_by`, counters, …), drop
// the active-state fields that no longer apply (`unconfirmed_until`,
// `confirmed_at`), and stamp the retire metadata on top.
const derivedSet = new Set<string>(DERIVED_FIELDS);
const newMeta: FrontmatterMap = {};
for (const [k, v] of Object.entries(meta)) {
// Identity keys overwritten below.
if (k === "kind" || k === "id" || k === "status" || k === "_status") continue;
// Fields that don't apply to retired (drop both shapes per §24).
if (k === "unconfirmed_until") continue;
if (k === "confirmed_at" || k === "_confirmed_at") continue;
if (k === "tags") {
// Replace the `brain/preference` tag with `brain/retired`.
const arr = Array.isArray(v) ? [...v] : [];
newMeta["tags"] = arr.map((t) => (t === "brain/preference" ? "brain/retired" : t));
continue;
}
// Group C derived fields go to disk in the `_`-prefixed shape so
// parseRetired's `normalizeDerivedKeys` accepts the file. `meta`
// is the normalised in-memory view, so the keys here are still
// un-prefixed and need re-prefixing on write.
if (derivedSet.has(k)) {
newMeta[`_${k}`] = v as never;
continue;
}
newMeta[k] = v as never;
}
newMeta["kind"] = "brain-retired";
newMeta["id"] = newId;
newMeta["_status"] = "retired";
newMeta["retired_at"] = opts.now.toISOString();
newMeta["retired_reason"] = reason;
newMeta["retired_by"] = opts.retired_by;
if (opts.superseded_by?.trim()) {
newMeta["superseded_by"] = opts.superseded_by.trim();
}
if (opts.user_rejected_reason?.trim()) {
newMeta["user_rejected_reason"] = opts.user_rejected_reason.trim();
}
// Add the prior `pref-<slug>` basename as an Obsidian alias on the
// retired file. Wikilinks in append-only logs and signal frontmatter
// were written when the file still lived in `preferences/`; without
// this alias they would stop resolving the moment the file is
// renamed. Obsidian's wikilink resolver checks `aliases` after
// basename, so `[[pref-<slug>]]` continues to land on the right note
// without rewriting any historical entry.
const existingAliases = Array.isArray(newMeta["aliases"])
? (newMeta["aliases"] as ReadonlyArray<string>)
: [];
if (!existingAliases.includes(oldId)) {
newMeta["aliases"] = [oldId, ...existingAliases];
}
// A retire is a field change of the same preference id (`status:
// retired`), never a removal. The retired page's identity keys (`id:
// ret-<slug>`, `kind`, `aliases`) are not fields of `pref-<slug>`, so they
// stay out; the status is what a retire decides, at the caller's
// authority. Values carry the types the preference writer writes: the
// page parser reads every scalar as text, and `pinned: "false"` is not
// the boolean the fold folds.
const lifecycleRecords = () => {
const {
id: _id,
kind: _kind,
aliases: _aliases,
...lifecycle
} = typedPreferenceFields(storeFieldsOf(newMeta));
// Once switched, a preference the fold holds as private (any of its
// records sits in `private/`, whatever its fields say) keeps its
// retire there too: one entity, one partition, as the other writers.
const heldPrivate = storeOnly && (storePreferenceEntry(slug)?.private ?? true);
return preferenceStoreRecords(
oldId,
lifecycle,
opts.authority ?? authorityFromOrigin(),
heldPrivate || preferencePrivacy(vault, lifecycle)(),
RETIRE_DECIDED_FIELDS,
);
};
routeWrite({
legacy: () => {
// Re-render the body from scratch so the retired file carries the
// v0.10.1 shape (only sections with content), even if the source
// pref was last written in the v0.9.x placeholder format. Evidence
// is collected from the live log so the snapshot reflects how the
// rule was actually used right up to retirement.
const renderInput: WritePreferenceInput = {
slug,
topic: requireString(meta, "topic", prefPath),
principle: requireString(meta, "principle", prefPath),
created_at: requireString(meta, "created_at", prefPath),
unconfirmed_until: requireString(meta, "unconfirmed_until", prefPath),
status: BRAIN_PREFERENCE_STATUS.confirmed, // body render is status-agnostic
evidenced_by: optionalStringArray(meta, "evidenced_by", prefPath),
...(opts.evidenceApplied !== undefined ? { recentApplied: opts.evidenceApplied } : {}),
...(opts.evidenceViolated !== undefined ? { recentViolated: opts.evidenceViolated } : {}),
};
// moveToRetired is also called outside dream (CLI reject) — when the
// caller did not pre-fetch evidence, we collect it here so the
// retired file is the canonical historical snapshot in both paths.
let renderInputWithEvidence: WritePreferenceInput = renderInput;
if (renderInput.recentApplied === undefined && renderInput.recentViolated === undefined) {
// Late-bound import to avoid a cyclic dependency: evidence.ts
// imports nothing from preference.ts at module load time.
// eslint-disable-next-line @typescript-eslint/no-require-imports
const ev = (
require("./evidence.ts") as typeof import("./evidence.ts")
).collectEvidenceForSlug(vault, slug, { sinceIso: renderInput.created_at });
renderInputWithEvidence = {
...renderInput,
recentApplied: ev.applied,
recentViolated: ev.violated,
};
}
const renderedBody = renderPreferenceBody(renderInputWithEvidence);
const newBody = appendRetiredSection(renderedBody, reason, opts);
void body; // original source body is intentionally discarded — see above.
writeFrontmatterAtomic(newPath, newMeta, newBody, {
overwrite: false,
existsErrorKind: "retired",
vaultForRelativePath: legacyVaultOf(vault, "moveToRetired"),
});
// Confirm the new file actually landed before unlinking the source.
if (!existsSync(newPath)) {
throw new Error(`moveToRetired: write of ${newPath} reported success but file is absent`);
}
unlinkSync(prefPath);
},
// Brain store dual write (task 1.11) on an unswitched machine: off by
// default, never fails this write.
store: lifecycleRecords,
context: { vault },
});
// Per-preference mutation audit (opt-in, Brain lifecycle suite F1).
// Keyed by the ORIGINAL `pref-<slug>` id so create -> ... -> retire
// all land in one trail. A retire is a lifecycle transition, so it
// always records (the audit's no-op rule only suppresses `update`).
if (opts.audit) {
const principle = requireString(meta, "principle", prefPath);
const scope = typeof meta["scope"] === "string" ? (meta["scope"] as string) : undefined;
const revRaw = meta["_revision"];
const contentHash = computeContentHash(principle, scope);
appendPrefAudit(
vault,
{
pref_id: oldId,
op: PREF_AUDIT_OP.retire,
agent: opts.audit.agent,
reason,
revision_before: typeof revRaw === "number" ? revRaw : null,
revision_after: null,
hash_before: contentHash,
hash_after: contentHash,
private: isPrivateFrontmatter(meta),
},
{ now: opts.now },
);
}
return { path: newPath, id: newId };
}
/**
* The preference a store-only retire moves, from the store's fold, as the
* page `parseFrontmatter` would have read (and an empty body: the retired
* page is not written). Throws when the fold holds no active preference
* of that id, as the page read throws for a missing page.
*/
function storeRetireSource(prefPath: string): [FrontmatterMap, string] {
const slug = basename(prefPath, ".md").slice("pref-".length);
const page = slug === "" ? null : storePreferenceMeta(slug);
if (page === null || page.retired) {
throw new Error(`moveToRetired: the brain store holds no active preference pref-${slug}`);
}
return [page.meta, ""];
}
// ----- Field helpers --------------------------------------------------------
function enforceStatusFolderInvariant(
path: string,
status: string,
expectedFolder: "preferences" | "retired",
): void {
// Resolve the immediate parent directory's basename. Files outside
// the canonical `Brain/<folder>/...` get a softer treatment: we let
// the caller use the parser on a synthetic path (e.g. tests writing
// to a tmpdir) so long as the status itself is coherent.
const parent = basename(dirname(path));
if (expectedFolder === "preferences") {
// We accept `preferences` as the canonical folder. A status of
// `retired` here is the mismatch case the design doc §4 calls out.
if (
parent === "preferences" &&
status !== BRAIN_PREFERENCE_STATUS.unconfirmed &&
status !== BRAIN_PREFERENCE_STATUS.confirmed &&
status !== BRAIN_PREFERENCE_STATUS.quarantine &&
// A tombstoned preference stays in `preferences/` for audit; the
// lifecycle module marks it in place rather than moving the file.
status !== BRAIN_TOMBSTONE_STATUS
) {
throw new BrainStatusFolderMismatchError(
"preference file frontmatter status does not match preferences/ folder",
path,
status,
"preferences",
);
}
} else {
if (parent === "retired" && status !== "retired") {
throw new BrainStatusFolderMismatchError(
"retired file frontmatter status does not match retired/ folder",
path,
status,
"retired",
);
}
}
}
function requireField(meta: Record<string, unknown>, field: string, path: string): void {
if (!(field in meta) || meta[field] === undefined || meta[field] === null) {
throw new BrainParseError(`preference missing field: ${field}`, path);
}
if (typeof meta[field] === "string" && (meta[field] as string).trim() === "") {
throw new BrainParseError(`preference missing field: ${field}`, path);
}
}
function requireString(meta: Record<string, unknown>, field: string, path: string): string {
requireField(meta, field, path);
const v = meta[field];
if (typeof v !== "string") {
throw new BrainParseError(`preference field '${field}' must be a string`, path);
}
return v;
}
function requireStringArray(
meta: Record<string, unknown>,
field: string,
path: string,
): ReadonlyArray<string> {
requireField(meta, field, path);
const v = meta[field];
if (!Array.isArray(v)) {
throw new BrainParseError(`preference field '${field}' must be an array`, path);
}
for (const item of v) {
if (typeof item !== "string") {
throw new BrainParseError(`preference field '${field}' must be an array of strings`, path);
}
}
return [...(v as ReadonlyArray<string>)];
}
function optionalStringArray(
meta: Record<string, unknown>,
field: string,
path: string,
): ReadonlyArray<string> {
const v = meta[field];
if (v === undefined || v === null) return [];
if (!Array.isArray(v)) {
throw new BrainParseError(`preference field '${field}' must be an array`, path);
}
for (const item of v) {
if (typeof item !== "string") {
throw new BrainParseError(`preference field '${field}' must be an array of strings`, path);
}
}
return [...(v as ReadonlyArray<string>)];
}
function optionalStringList(
meta: Record<string, unknown>,
field: PreferenceRelationField,
path: string,
): ReadonlyArray<string> | undefined {
const v = meta[field];
if (v === undefined || v === null) return undefined;
if (typeof v === "string") return v.trim() ? [v] : [];
if (!Array.isArray(v)) {
throw new BrainParseError(
`preference field '${field}' must be a string or array of strings`,
path,
);
}
for (const item of v) {
if (typeof item !== "string") {
throw new BrainParseError(
`preference field '${field}' must be a string or array of strings`,
path,
);
}
}
return [...(v as ReadonlyArray<string>)];
}
/**
* Parse a string field whose semantic value is nullable. Both the
* literal string `"null"` and an empty string surface as JS `null` so
* the on-disk roundtrip survives the simple YAML emitter (which has no
* native null token).
*/
function optionalNullableString(
meta: Record<string, unknown>,
field: string,
path: string,
): string | null {
const v = meta[field];
if (v === undefined || v === null) return null;
if (typeof v !== "string") {
throw new BrainParseError(`preference field '${field}' must be a string or null`, path);
}
const trimmed = v.trim();
if (trimmed === "" || trimmed === "null") return null;
return v;
}
function optionalNumber(
meta: Record<string, unknown>,
field: string,
fallback: number,
path: string,
): number {
const v = meta[field];
if (v === undefined || v === null || v === "") return fallback;
// The simple parser surfaces all values as strings; numerics included.
if (typeof v === "number") return v;
if (typeof v === "string") {
const n = Number(v);
if (!Number.isFinite(n)) {
throw new BrainParseError(
`preference field '${field}' must be a finite number; got ${JSON.stringify(v)}`,
path,
);
}
return n;
}
throw new BrainParseError(`preference field '${field}' must be a number`, path);
}
/**
* Read the `owner:` frontmatter field (context-integrity-gates, Unit A).
*
* Distinct from {@link optionalScalarString} because a present-but-
* non-string value must NOT read as absent here: Obsidian Properties
* writes any list-shaped field as a YAML sequence, and `owner:` parsed as
* an array would otherwise make an owner-private memory ownerless — that
* is, shared with every agent. Such a claim resolves to
* {@link OWNER_UNRESOLVED}, which no requested scope can equal, so the
* memory reads as somebody else's. A usable string is stored VERBATIM,
* exactly as before; normalization for comparison stays in
* `preferenceOwner`.
*/
function optionalOwnerField(meta: Record<string, unknown>): string | undefined {
const raw = meta["owner"];
if (raw === undefined || raw === null) return undefined;
if (typeof raw !== "string") return OWNER_UNRESOLVED;
return raw.trim() === "" ? undefined : raw;
}
function optionalScalarString(meta: Record<string, unknown>, field: string): string | undefined {
const v = meta[field];
if (v === undefined || v === null) return undefined;
if (typeof v !== "string") return undefined;
const trimmed = v.trim();
return trimmed === "" ? undefined : v;
}
function parseConfidence(meta: Record<string, unknown>, path: string): BrainConfidence {
const v = meta["confidence"];
if (v === undefined || v === null || v === "") return BRAIN_CONFIDENCE.low;
if (typeof v !== "string") {
throw new BrainParseError("preference field 'confidence' must be a string", path);
}
const values = Object.values(BRAIN_CONFIDENCE) as ReadonlyArray<string>;
if (!values.includes(v)) {
throw new BrainParseError(
`preference field 'confidence' must be one of ${values.join(", ")}; got ${JSON.stringify(v)}`,
path,
);
}
return v as BrainConfidence;
}
/**
* Parse the numeric `confidence_value` field.
*
* Returns `null` when the field is absent, empty, or carries the
* literal sentinel `"null"` (the writer's null encoding for the
* simple YAML formatter). Otherwise must be a finite number in
* `[0, 1]`; out-of-range / non-finite / non-numeric values raise a
* hard parse error — drifting numeric confidence into `> 1` or
* `NaN` would corrupt every downstream comparison silently.
*/
function parseConfidenceValue(meta: Record<string, unknown>, path: string): number | null {
const v = meta["confidence_value"];
if (v === undefined || v === null || v === "" || v === "null") return null;
let n: number | null = null;
if (typeof v === "number") {
n = v;
} else if (typeof v === "string") {
const trimmed = v.trim();
// Whitespace-only string is the "null" sentinel in disguise.
// `Number("")` coerces to `0`, which would otherwise smuggle in a
// confident-zero band for a file the writer never produced a
// value for.
if (trimmed.length === 0 || trimmed === "null") return null;
const candidate = Number(trimmed);
if (Number.isFinite(candidate)) n = candidate;
}
if (n === null || !Number.isFinite(n) || n < 0 || n > 1) {
throw new BrainParseError(
`preference field 'confidence_value' must be a number in [0, 1]; got ${JSON.stringify(v)}`,
path,
);
}
return n;
}
/**
* Coerce `pinned` to boolean with a hard default of `false`. Accepts
* the literal string forms ("true"/"false") emitted by the simple
* formatter and the native boolean if a richer parser ever lands.
*
* Exported (t_f7bef96a) so the search indexer persists the SAME coercion
* into `documents.pinned` instead of duplicating it: one rule, one
* spelling, so the ranking signal and the preference flows can never
* disagree about what a note's `pinned` frontmatter says.
*/
export function parsePinned(meta: Record<string, unknown>): boolean {
const v = meta["pinned"];
if (v === undefined || v === null || v === "") return false;
if (typeof v === "boolean") return v;
if (typeof v === "string") {
if (v === "true") return true;
if (v === "false") return false;
}
// Unexpected representations fall back to false; we treat this as a
// forward-compat soft default rather than an error so a hand-edited
// file with an oddly-quoted boolean still parses.
return false;
}
// Internal use only: prevent "unused variable" lint after destructuring.
void join;