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
/**
* Open-decision vault (write-side-trust wave, Lane E, Task 10).
*
* A decision can only be RECORDED after it is made (`record.ts` requires
* `chosen`); this store is the artifact that parks the question before
* that: one Markdown record per open question at
* `Brain/decisions/open-<slug>.md`, with the enumerated options an agent
* or operator is choosing between.
*
* The lifecycle follows the trigger store (`triggers/store.ts`), not the
* pending queue: history is a status change, not a file move. Terminal
* records (resolved / discarded) stay in place so `list` is a status
* filter and the resolved pointer survives. There is deliberately NO
* read-time expiry - a parked judgment question is exactly the thing
* that must not silently expire.
*
* Resolution mints a REAL `type: decision` page through `recordDecision`
* (so the review obligation, the `decision-record` log event and the B4
* change trail all happen exactly once, in the one place that owns
* them), then stamps the open record `resolved` with a
* `[[decision-<slug>]]` pointer and appends exactly one `open_resolved`
* receipt to the decision-change trail. The minted page's slug is
* planned per record (the title slug first, then a title carrying the
* record's own unique id, numbered on collision): two parked questions
* under one title must never fight for one page, and a page that already
* carries this record's `[[open-<slug>]]` provenance is a crashed
* earlier attempt the next resolve converges against instead of
* failing. Creating an open decision is
* exempt from the write gate by design: accountability lanes stay
* writable when content lanes are gated, the same principle that keeps
* the audit lane appending under freeze.
*
* An unreadable record is confined to itself: every read partitions the
* directory into the records that parsed and the ones that did not, so
* one hand-edited file names itself instead of taking the list, the
* brief and the transitions down with it.
*/
import { createHash } from "node:crypto";
import { mkdirSync } from "node:fs";
import { join } from "node:path";
import lockfile from "proper-lockfile";
import { normalizeAgentArgument } from "../../agent-identity.ts";
import { resolveAgentName } from "../../config.ts";
import { sanitiseTextField } from "../../redactor.ts";
import { parseFrontmatterText, SLUG_MAX_LEN, slugify } from "../../vault.ts";
import { appendLogEvent } from "../log.ts";
import { BRAIN_DECISIONS_REL } from "../path-constants.ts";
import { decisionsDir, decisionPath } from "../paths.ts";
import { isoDate, isoSecond } from "../time.ts";
import { BRAIN_LOG_EVENT_KIND } from "../types.ts";
import { recordDecision } from "./record.ts";
import { appendDecisionChangeReceipt, DECISION_CHANGE_REASON } from "./receipts.ts";
import {
assertLaneWrite,
lanePageExists,
listLaneFiles,
readLaneFile,
readLaneText,
writeLaneText,
lanePagesInStore,
withLaneLock,
} from "../../store/lane-pages.ts";
// ----- Vocabulary -----------------------------------------------------------
/**
* Lifecycle states of one open decision. Frozen object + companion list
* + type guard: the closed-vocabulary trio, census-registered in
* `tests/core/architecture/verdict-vocabulary-census.test.ts`.
*/
export const OPEN_DECISION_STATUS = Object.freeze({
open: "open",
resolved: "resolved",
discarded: "discarded",
} as const);
export type OpenDecisionStatus = (typeof OPEN_DECISION_STATUS)[keyof typeof OPEN_DECISION_STATUS];
/** The statuses in lifecycle order - the single source every filter reads. */
export const OPEN_DECISION_STATUSES: ReadonlyArray<OpenDecisionStatus> = Object.freeze([
OPEN_DECISION_STATUS.open,
OPEN_DECISION_STATUS.resolved,
OPEN_DECISION_STATUS.discarded,
]);
export function isOpenDecisionStatus(value: unknown): value is OpenDecisionStatus {
return (
typeof value === "string" && (OPEN_DECISION_STATUSES as ReadonlyArray<string>).includes(value)
);
}
// ----- Constants ------------------------------------------------------------
/**
* How long a held decisions-directory lock may sit before another
* process treats it as abandoned. Exported so a test can hold the same
* lock the writers take rather than guessing at its options.
*/
export const OPEN_LOCK_STALE_MS = 10_000;
/** Cap on the short prose frontmatter fields (title mirrors record.ts). */
const TITLE_MAX_LEN = 200;
/** Cap on one enumerated option (single line). */
const OPTION_MAX_LEN = 512;
/** Cap on the question and context body sections. */
const BODY_MAX_LEN = 2000;
/** Cap on the discard reason / resolution rationale. */
const REASON_MAX_LEN = 512;
/** Longest run of an unreadable field value reproduced in an error. */
const FIELD_EXCERPT_MAX = 120;
/**
* The frontmatter keys of a stored open decision, in one frozen table.
* The renderer, the parser and the refusal messages all read the names
* from here, so a key can never be spelled one way on the way out and
* another way on the way back in.
*/
const OPEN_KEY = Object.freeze({
id: "open_decision_id",
status: "status",
questionHash: "question_hash",
createdAt: "created_at",
resolvedAt: "resolved_at",
discardedAt: "discarded_at",
title: "title",
agent: "agent",
choice: "choice",
decision: "decision",
discardReason: "discard_reason",
} as const);
/** Extension of every open-decision record file under `Brain/decisions/`. */
const OPEN_FILE_EXT = ".md";
/** Filename prefix that separates open decisions from `decision-` pages. */
const OPEN_FILE_PREFIX = "open-";
export function openDecisionsRel(id: string): string {
return `${BRAIN_DECISIONS_REL}/${id}${OPEN_FILE_EXT}`;
}
// ----- Errors ---------------------------------------------------------------
/** Every failure path in this module raises this typed error. */
export class OpenDecisionError extends Error {
constructor(message: string, options?: ErrorOptions) {
super(message, options);
this.name = "OpenDecisionError";
}
}
/**
* A question that already has an OPEN record refuses to park twice. Dedup
* is on the sha16 of the NORMALIZED question and scoped to open records -
* the dedup key runs across open records only, so the same wording may be
* parked again once its twin has settled (resolved or discarded). The
* refusal names the existing id so the caller can go straight to it.
*/
export class OpenDecisionDuplicateError extends OpenDecisionError {
/** The id of the record already carrying this question. */
readonly existingId: string;
/** The absolute path of the record already carrying this question. */
readonly existingPath: string;
constructor(existingId: string, existingPath: string) {
super(
`open decision: this question is already parked as ${existingId} ` +
`(${existingPath}); resolve or discard it first, or word the ` +
`question differently`,
);
this.name = "OpenDecisionDuplicateError";
this.existingId = existingId;
this.existingPath = existingPath;
}
}
// ----- Shapes ---------------------------------------------------------------
export interface OpenDecisionRecord {
/** Filename basename without `.md`. Equals `open-<slug>`. */
readonly id: string;
readonly slug: string;
readonly status: OpenDecisionStatus;
/** Short label that drove the slug (frontmatter, JSON-quoted). */
readonly title: string;
/** The full question (body `## Question` section). */
readonly question: string;
/** The enumerated options (body `## Options` bullets, in file order). */
readonly options: ReadonlyArray<string>;
/** Background prose (body `## Context` section); empty when none. */
readonly context: string;
/** sha16 of the normalized question - the dedup key. */
readonly questionHash: string;
readonly createdAt: string;
readonly resolvedAt: string | null;
readonly discardedAt: string | null;
/** The chosen option, stamped by {@link resolveOpenDecision}. */
readonly choice: string | null;
/** `[[decision-<slug>]]` pointer stamped on resolution. */
readonly decision: string | null;
/** Why the question was closed without a decision, on discard. */
readonly discardReason: string | null;
readonly agent: string;
readonly path: string;
}
export interface OpenDecisionInput {
/** Short label that drives the slug. */
readonly title: string;
/** The full question; dedup key (normalized). */
readonly question: string;
/** The enumerated options; at least one. */
readonly options: ReadonlyArray<string>;
/** Optional background prose. */
readonly context?: string;
readonly agent?: string;
readonly now?: Date;
readonly configPath?: string;
}
export interface ListOpenDecisionsOptions {
/** Filter on status. Unreadable entries are reported either way. */
readonly status?: OpenDecisionStatus;
/**
* The vault-relative paths the caller may read, as the decision pages
* take them. A record it may not read is answered as an absent one:
* skipped by the list, refused by the single-id reads with the absent
* id's error.
*/
readonly readable?: (relPath: string) => boolean;
}
export interface ListOpenDecisionsResult {
/** Readable records, oldest first (created_at asc, then id). */
readonly records: ReadonlyArray<OpenDecisionRecord>;
/** Records that named themselves and then failed to parse, by path. */
readonly unreadable: ReadonlyArray<{ path: string; reason: string }>;
}
export interface ResolveOpenDecisionInput {
/** The chosen option; must be one of the record's enumerated options. */
readonly choice: string;
/** Agent/human who resolved the question. */
readonly actor?: string;
/** Why this option won; becomes the minted page's assumption. */
readonly rationale?: string;
readonly now?: Date;
readonly configPath?: string;
}
export interface DiscardOpenDecisionInput {
/** Why the question is being closed without a decision. Required. */
readonly reason: string;
readonly actor?: string;
readonly now?: Date;
readonly configPath?: string;
}
// ----- Field helpers --------------------------------------------------------
function excerptFieldValue(raw: unknown): string {
const text = typeof raw === "string" ? raw : String(raw);
return text.length <= FIELD_EXCERPT_MAX ? text : `${text.slice(0, FIELD_EXCERPT_MAX)}…`;
}
function presentButUnreadable(expectation: string, raw: unknown): string {
return `is present but ${expectation}: ${excerptFieldValue(raw)}`;
}
/**
* One frontmatter field of one record cannot be read. Absent and
* unreadable are different claims; substituting a default for the second
* would state a value nothing supports. The refusal is scoped to ONE
* record: the directory reader catches it per file and reports it
* alongside the records that read cleanly.
*/
class OpenDecisionFieldError extends Error {
readonly path: string;
readonly key: string;
constructor(path: string, key: string, detail: string) {
super(`open decision ${path}: ${key} ${detail}`);
this.name = "OpenDecisionFieldError";
this.path = path;
this.key = key;
}
}
function requireTextField(value: unknown, label: string, maxLen: number): string {
if (typeof value !== "string") {
throw new OpenDecisionError(`open decision: ${label} is required`);
}
const cleaned = sanitiseTextField(value, { maxLen, singleLine: true }).trim();
if (!cleaned) throw new OpenDecisionError(`open decision: ${label} is required`);
return cleaned;
}
function optionalTextField(value: unknown, label: string, maxLen: number): string {
if (value === undefined) return "";
if (typeof value !== "string") {
throw new OpenDecisionError(`open decision: ${label} must be a string`);
}
return sanitiseTextField(value, { maxLen }).trim();
}
/** Normalize a question for dedup: whitespace-collapsed, lowercased. */
export function normalizeOpenQuestion(question: string): string {
return question.replace(/\s+/g, " ").trim().toLowerCase();
}
/** sha16 of the normalized question - the stable dedup key. */
export function openQuestionHash(question: string): string {
return createHash("sha256").update(normalizeOpenQuestion(question)).digest("hex").slice(0, 16);
}
// ----- (De)serialization ----------------------------------------------------
function sectionText(body: string, heading: string): string {
const re = new RegExp(`^## ${heading}$`, "mu");
const match = re.exec(body);
if (!match) return "";
const start = match.index + match[0].length;
const next = /^## /mu.exec(body.slice(start + 1));
const end = next ? start + 1 + next.index : body.length;
return body.slice(start, end).trim();
}
/**
* A line of free-text body prose whose first non-space character is `#`
* would read back as a section heading: a question carrying its own
* `## Options` line re-partitions the body on parse, and its bullets
* become the record's options. The writer indents such a line by one
* space (breaking the `^## ` anchors the section reader matches); the
* reader dedents exactly the lines the writer could have indented - a
* line the writer left alone never has `#` as its first non-space
* character, because that shape is what the writer escapes - so the
* round trip is byte-faithful for every line the section reader's own
* trim leaves alone, an already-indented heading-shaped line included.
* The exception is the section's opening line: the reader's trim strips
* a section's leading whitespace - the writer's escape with it - before
* the dedent runs, so a question OPENING with an indented heading-shaped
* line reads back dedented. (It re-escapes on the next render, so the
* shape is stable; the first round trip just is not byte-faithful there.)
*/
function escapeBodyProse(text: string): string {
return text
.split("\n")
.map((line) => (/^\s*#/u.test(line) ? ` ${line}` : line))
.join("\n");
}
function unescapeBodyProse(text: string): string {
return text
.split("\n")
.map((line) => (line.startsWith(" ") && /^\s*#/u.test(line) ? line.slice(1) : line))
.join("\n");
}
function renderRecord(record: OpenDecisionRecord): string {
const lines = [
"---",
`${OPEN_KEY.id}: ${record.id}`,
`${OPEN_KEY.status}: ${record.status}`,
`${OPEN_KEY.questionHash}: ${record.questionHash}`,
`${OPEN_KEY.createdAt}: ${record.createdAt}`,
...(record.resolvedAt !== null ? [`${OPEN_KEY.resolvedAt}: ${record.resolvedAt}`] : []),
...(record.discardedAt !== null ? [`${OPEN_KEY.discardedAt}: ${record.discardedAt}`] : []),
// Free-text values are JSON-quoted so YAML-significant characters can
// never corrupt the file (triggers/intentions pattern).
`${OPEN_KEY.title}: ${JSON.stringify(record.title)}`,
`${OPEN_KEY.agent}: ${JSON.stringify(record.agent)}`,
...(record.choice !== null ? [`${OPEN_KEY.choice}: ${JSON.stringify(record.choice)}`] : []),
...(record.decision !== null
? [`${OPEN_KEY.decision}: ${JSON.stringify(record.decision)}`]
: []),
...(record.discardReason !== null
? [`${OPEN_KEY.discardReason}: ${JSON.stringify(record.discardReason)}`]
: []),
"---",
"",
"## Question",
"",
escapeBodyProse(record.question),
"",
"## Options",
"",
];
for (const option of record.options) lines.push(`- ${option}`);
lines.push("");
if (record.context.length > 0) {
lines.push("## Context", "", escapeBodyProse(record.context), "");
}
return lines.join("\n");
}
/**
* Read one file as an open-decision record. `null` means the file is not
* an open decision at all (no id, so nothing claims it belongs here -
* `decision-` pages and operator notes share the directory). Every OTHER
* failure throws {@link OpenDecisionFieldError} naming the field.
*/
function parseOpenRecord(vault: string, fileName: string): OpenDecisionRecord | null {
const path = join(decisionsDir(vault), fileName);
let raw: string;
try {
raw = readLaneFile(vault, path);
} catch (err) {
throw new OpenDecisionFieldError(
path,
OPEN_KEY.id,
`the file cannot be read: ${(err as Error).message ?? String(err)}`,
);
}
const [meta, body] = parseFrontmatterText(raw);
const id = meta[OPEN_KEY.id];
if (id === undefined) return null;
if (typeof id !== "string" || id === "") {
throw new OpenDecisionFieldError(path, OPEN_KEY.id, presentButUnreadable("not an id", id));
}
if (!id.startsWith(OPEN_FILE_PREFIX)) {
throw new OpenDecisionFieldError(
path,
OPEN_KEY.id,
presentButUnreadable(`not an ${OPEN_FILE_PREFIX}<slug> id`, id),
);
}
const status = meta[OPEN_KEY.status];
if (!isOpenDecisionStatus(status)) {
throw new OpenDecisionFieldError(
path,
OPEN_KEY.status,
presentButUnreadable(`not one of ${OPEN_DECISION_STATUSES.join(", ")}`, status),
);
}
const question = unescapeBodyProse(sectionText(body, "Question"));
if (!question) {
throw new OpenDecisionFieldError(
path,
"## Question",
"the question section is missing or empty",
);
}
const options = sectionText(body, "Options")
.split("\n")
.map((line) => line.trim())
.filter((line) => line.startsWith("- "))
.map((line) => line.slice(2).trim())
.filter((line) => line.length > 0);
if (options.length === 0) {
throw new OpenDecisionFieldError(path, "## Options", "the options section carries no options");
}
// The dedup hash is derived data: a hand-edit that dropped the key is
// recomputed from the question body, but a PRESENT value that cannot
// be read refuses rather than standing in for the operator's bytes.
const rawHash = meta[OPEN_KEY.questionHash];
let questionHash: string;
if (rawHash === undefined) {
questionHash = openQuestionHash(question);
} else if (typeof rawHash === "string" && /^[0-9a-f]{16}$/u.test(rawHash)) {
questionHash = rawHash;
} else {
throw new OpenDecisionFieldError(
path,
OPEN_KEY.questionHash,
presentButUnreadable("not a 16-hex-character hash", rawHash),
);
}
const createdAt = meta[OPEN_KEY.createdAt];
if (typeof createdAt !== "string" || createdAt === "" || Number.isNaN(Date.parse(createdAt))) {
throw new OpenDecisionFieldError(
path,
OPEN_KEY.createdAt,
createdAt === undefined
? "is missing, and a record is ordered and aged by it"
: presentButUnreadable("not a readable instant", createdAt),
);
}
const textOrNull = (key: string): string | null => {
const v = meta[key];
return typeof v === "string" ? v : null;
};
// The title is derived data like the dedup hash: a hand-edit that
// dropped the key falls back to the id, but a PRESENT value that cannot
// be read refuses rather than standing in for the operator's bytes.
const titleMeta = meta[OPEN_KEY.title];
if (titleMeta !== undefined && typeof titleMeta !== "string") {
throw new OpenDecisionFieldError(
path,
OPEN_KEY.title,
presentButUnreadable("not a string", titleMeta),
);
}
return Object.freeze({
id,
slug: id.slice(OPEN_FILE_PREFIX.length),
status,
title: typeof titleMeta === "string" ? titleMeta : id,
question,
options: Object.freeze(options),
context: unescapeBodyProse(sectionText(body, "Context")),
questionHash,
createdAt,
resolvedAt: textOrNull(OPEN_KEY.resolvedAt),
discardedAt: textOrNull(OPEN_KEY.discardedAt),
choice: textOrNull(OPEN_KEY.choice),
decision: textOrNull(OPEN_KEY.decision),
discardReason: textOrNull(OPEN_KEY.discardReason),
agent: textOrNull(OPEN_KEY.agent) ?? "",
path,
});
}
// ----- Reads ----------------------------------------------------------------
/**
* Read the whole open-decision slice of `Brain/decisions/`, keeping a
* broken record's blast radius to itself. This is the reader every
* surface goes through: a refusal from one file is caught here and
* reported next to the records that read cleanly. The status filter
* applies to the readable records only - an unreadable record has no
* status to compare, and dropping it from a filtered view would hide it
* exactly where a caller is most likely to conclude the queue is empty.
*/
export function listOpenDecisions(
vault: string,
opts: ListOpenDecisionsOptions = {},
): ListOpenDecisionsResult {
const dir = decisionsDir(vault);
if (!lanePageExists(vault, dir)) return { records: [], unreadable: [] };
const records: OpenDecisionRecord[] = [];
const unreadable: Array<{ path: string; reason: string }> = [];
for (const name of listLaneFiles(vault, dir, "")) {
if (!name.endsWith(OPEN_FILE_EXT) || !name.startsWith(OPEN_FILE_PREFIX)) continue;
const path = join(dir, name);
if (opts.readable !== undefined && !opts.readable(openDecisionsRel(stripExt(name)))) continue;
try {
const record = parseOpenRecord(vault, name);
if (record === null) continue;
if (opts.status !== undefined && record.status !== opts.status) continue;
records.push(record);
} catch (err) {
if (!(err instanceof OpenDecisionFieldError)) throw err;
unreadable.push({ path, reason: err.message });
}
}
records.sort((a, b) => {
if (a.createdAt !== b.createdAt) return a.createdAt < b.createdAt ? -1 : 1;
return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
});
unreadable.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
return { records, unreadable };
}
function stripExt(name: string): string {
return name.slice(0, -OPEN_FILE_EXT.length);
}
/**
* One open decision by id, or null. A record the caller cannot read
* (absent, or excluded by the readable predicate) is answered as absent.
*/
export function showOpenDecision(
vault: string,
id: string,
opts: Pick<ListOpenDecisionsOptions, "readable"> = {},
): OpenDecisionRecord | null {
const listed = listOpenDecisions(vault, opts);
return listed.records.find((r) => r.id === id) ?? null;
}
// ----- Directory lock -------------------------------------------------------
/**
* Run one read-then-write pass under the decisions-directory lock. Every
* writer here goes through it: the CLI and the MCP server can both reach
* the store, and without the lock two callers could each observe "no
* twin" for one question and persist duplicates.
*/
function withOpenDirLock<T>(vault: string, body: () => T): T {
const dir = decisionsDir(vault);
// A store-only machine holds the same lock device-locally: no lock file
// and no decisions directory land in the vault.
if (lanePagesInStore(vault)) return withLaneLock(vault, dir, body);
mkdirSync(dir, { recursive: true });
const release = lockfile.lockSync(dir, { stale: OPEN_LOCK_STALE_MS, realpath: false });
try {
return body();
} finally {
release();
}
}
// ----- Creation -------------------------------------------------------------
/**
* Park a question with its enumerated options. Dedup is on the sha16 of
* the normalized question, scoped to OPEN records: a twin question (same
* words, different whitespace or casing) with an open record refuses with
* {@link OpenDecisionDuplicateError} naming the existing id; the same
* wording parks again once the twin has settled. A DISTINCT question
* under an occupied slug gets a suffixed filename, never a clobber.
*/
export function openDecision(vault: string, input: OpenDecisionInput): OpenDecisionRecord {
// Vault-identity write guard (context-integrity-gates, Unit J).
assertLaneWrite(vault);
const title = requireTextField(input.title, "title", TITLE_MAX_LEN);
const question = optionalTextField(input.question, "question", BODY_MAX_LEN);
if (!question) throw new OpenDecisionError("open decision: question is required");
if (!Array.isArray(input.options) || input.options.length === 0) {
throw new OpenDecisionError("open decision: at least one option is required");
}
const options = input.options.map((option) =>
requireTextField(option, "options", OPTION_MAX_LEN),
);
const context = optionalTextField(input.context ?? "", "context", BODY_MAX_LEN);
const now = input.now ?? new Date();
const questionHash = openQuestionHash(question);
return withOpenDirLock(vault, () => {
// Dedup is scoped to open records: a settled (resolved / discarded)
// twin is history, and the same wording must be parkable again.
const existing = listOpenDecisions(vault, { status: OPEN_DECISION_STATUS.open }).records.find(
(r) => r.questionHash === questionHash,
);
if (existing !== undefined) {
throw new OpenDecisionDuplicateError(existing.id, existing.path);
}
const explicitAgent = normalizeAgentArgument(input.agent ?? null);
const agent = explicitAgent ?? resolveAgentName(input.configPath);
const dir = decisionsDir(vault);
const slug = slugify(title);
let id = `${OPEN_FILE_PREFIX}${slug}`;
let suffix = 2;
while (lanePageExists(vault, join(dir, `${id}${OPEN_FILE_EXT}`))) {
id = `${OPEN_FILE_PREFIX}${slug}-${suffix}`;
suffix += 1;
}
const record: OpenDecisionRecord = Object.freeze({
id,
slug: id.slice(OPEN_FILE_PREFIX.length),
status: OPEN_DECISION_STATUS.open,
title,
question,
options: Object.freeze(options),
context,
questionHash,
createdAt: isoSecond(now),
resolvedAt: null,
discardedAt: null,
choice: null,
decision: null,
discardReason: null,
agent,
path: join(dir, `${id}${OPEN_FILE_EXT}`),
});
writeLaneText(vault, record.path, renderRecord(record));
try {
appendLogEvent(
vault,
{
timestamp: isoSecond(now),
eventType: BRAIN_LOG_EVENT_KIND.decisionOpen,
agent,
body: {
open: `[[${record.id}]]`,
title,
options: String(options.length),
agent,
},
},
{ failOpen: true },
);
} catch {
// The record file is authoritative; the timeline mirror is best-effort.
}
return record;
});
}
// ----- Transitions ----------------------------------------------------------
/**
* Refuse an id no readable record carries. When part of the queue is
* unreadable the refusal says so: "no such record" would otherwise
* assert the question is not there when in truth the store could not
* look.
*/
function unknownOpenDecisionError(
id: string,
unreadable: ReadonlyArray<{ path: string; reason: string }>,
): OpenDecisionError {
if (unreadable.length === 0) {
return new OpenDecisionError(`no open decision: ${id}`);
}
return new OpenDecisionError(
`no open decision: ${id} - and ${unreadable.length} record(s) in the directory could not be ` +
`read, so the id may belong to one of them: ${unreadable.map((u) => u.reason).join("; ")}`,
);
}
function requireOpenRecord(vault: string, id: string): OpenDecisionRecord {
const listed = listOpenDecisions(vault);
const record = listed.records.find((r) => r.id === id);
if (record === undefined) throw unknownOpenDecisionError(id, listed.unreadable);
return record;
}
function actorFor(input: { actor?: string; configPath?: string }, fallback: string): string {
const explicit = normalizeAgentArgument(input.actor ?? null);
if (explicit !== null) return explicit;
const carried = normalizeAgentArgument(fallback);
return carried ?? resolveAgentName(input.configPath);
}
/**
* The provenance a minted page always carries: the wikilink naming the
* open record it came from, in the body, so a resolve that crashed
* between minting the page and stamping the record can be recognized and
* converged on the next attempt.
*/
function mintProvenance(record: OpenDecisionRecord): string {
return `resolved from [[${record.id}]]`;
}
/** The minted page's body: the open record's context plus the provenance. */
function mintNotes(record: OpenDecisionRecord): string {
return [record.context, mintProvenance(record)].filter((part) => part !== "").join("\n\n");
}
/** The minted page's title exactly as `recordDecision` will sanitise it, so
* the occupy-check below tests the slug the mint will actually write. */
function sanitiseMintTitle(value: string): string {
return sanitiseTextField(value, { maxLen: TITLE_MAX_LEN, singleLine: true }).trim();
}
/**
* The slug budget the mint head keeps to: long enough to carry the
* question's opening words, short enough that the per-record tail that
* follows it - the record's own id, and from the second candidate on a
* counter - fits inside {@link SLUG_MAX_LEN} beside it.
*/
const MINT_HEAD_MAX = 40;
/**
* The head every derived mint candidate is built on: the longest
* word-prefix of the title whose slug stays within {@link MINT_HEAD_MAX}.
* Working word by word keeps the head on a word boundary; a single word
* longer than the budget yields an empty head, and the derived candidates
* then carry the id alone.
*/
function mintHead(title: string): string {
let head = "";
for (const word of title.split(/\s+/u)) {
if (word === "") continue;
const next = head === "" ? word : `${head} ${word}`;
if (slugify(next).length > MINT_HEAD_MAX) break;
head = next;
}
return head;
}
/**
* A derived mint title: `<head> (<id>)`, numbered `<head> (<id> N)` from
* the second candidate on. The id - unique among records - is PRE-SHAVED
* so the whole tail sits INSIDE the slug cap: `slugify` truncates from the
* START of the slug, so a tail appended past the cap is silently dropped
* and every candidate would slugify identically - an occupied slug then
* wedges the mint walk forever. With the tail budgeted inside the cap the
* numbered candidates keep their counter on the slug too (the id's slice
* shrinks as the counter grows), so successive candidates slugify
* distinctly and the walk terminates by construction.
*/
function derivedMintTitle(sanitisedTitle: string, id: string, suffix: number): string {
const counter = suffix === 0 ? "" : ` ${suffix}`;
const counterLen = suffix === 0 ? 0 : 1 + String(suffix).length;
const head = mintHead(sanitisedTitle);
const headLen = head === "" ? 0 : slugify(head).length + 1;
let budget = SLUG_MAX_LEN - headLen - counterLen;
let effectiveHead = head;
if (budget < 1) {
// The head leaves no room for even a one-character id slice: the
// candidate drops it rather than pushing the tail past the cap.
effectiveHead = "";
budget = SLUG_MAX_LEN - counterLen;
}
const tailId = id.slice(0, Math.max(1, budget)).replace(/-+$/u, "");
const tail = `(${tailId}${counter})`;
return effectiveHead === "" ? tail : `${effectiveHead} ${tail}`;
}
interface ResolveMintTarget {
/** The title to pass to `recordDecision`; its slug is `slug`. */
readonly title: string;
/** The slug the page occupies, or will occupy. */
readonly slug: string;
/**
* True when `slug` is already occupied by a page carrying this
* record's `[[open-<slug>]]` provenance - a crashed earlier attempt
* the resolve converges against by stamping, not by minting again.
*/
readonly ours: boolean;
}
/**
* Plan the page one resolve mints. The bare title slug first; if that is
* occupied by a page that does not reference this record, fall through the
* per-record derived titles (head plus id, numbered on collision) - the
* same occupy-check `openDecision` runs for the record filename. The
* derived candidates keep their distinguishing tail INSIDE the slug cap
* (see {@link derivedMintTitle}), so a title whose slug fills the cap
* still walks onto fresh slugs instead of spinning on the same one. Never
* the bare title alone: `recordDecision` refuses an existing slug, so a
* second "Pick DB" question would otherwise be wedged open forever (and
* a crash between minting and stamping would wedge the first one too).
*/
function resolveMintTarget(vault: string, record: OpenDecisionRecord): ResolveMintTarget {
const reference = `[[${record.id}]]`;
const sanitised = sanitiseMintTitle(record.title);
let title = sanitised;
let slug = slugify(title);
let suffix = 0;
for (;;) {
const path = decisionPath(vault, slug);
if (!lanePageExists(vault, path)) return { title, slug, ours: false };
if ((readLaneText(vault, path) ?? "").includes(reference)) return { title, slug, ours: true };
title = sanitiseMintTitle(derivedMintTitle(sanitised, record.id, suffix));
slug = slugify(title);
suffix = suffix === 0 ? 2 : suffix + 1;
}
}
/**
* Close a parked question by CHOOSING: mint the real `type: decision`
* page through {@link recordDecision} (review obligation, log event and
* the B4 change trail included - the one place that owns them), stamp
* the open record `resolved` with the `[[decision-<slug>]]` pointer, and
* append exactly one `open_resolved` receipt. The open record stays in
* place: history is a status filter.
*
* Idempotent-safe: when the planned page already exists and carries this
* record's `[[open-<slug>]]` provenance - a previous attempt that minted
* the page and crashed before stamping - the resolve converges by
* stamping against that page instead of failing.
*/
export function resolveOpenDecision(
vault: string,
id: string,
input: ResolveOpenDecisionInput,
): { decision: string } {
// Vault-identity write guard (context-integrity-gates, Unit J).
assertLaneWrite(vault);
const choice = requireTextField(input.choice, "choice", OPTION_MAX_LEN);
return withOpenDirLock(vault, () => {
const record = requireOpenRecord(vault, id);
if (record.status !== OPEN_DECISION_STATUS.open) {
throw new OpenDecisionError(
`open decision ${id} is terminal (${record.status}); only an open record can be resolved`,
);
}
if (!record.options.includes(choice)) {
throw new OpenDecisionError(
`open decision ${id}: choice ${JSON.stringify(choice)} is not one of the enumerated ` +
`options (${record.options.map((o) => JSON.stringify(o)).join(", ")})`,
);
}
const actor = actorFor(input, record.agent);
const now = input.now ?? new Date();
const rationale = optionalTextField(input.rationale ?? "", "rationale", REASON_MAX_LEN);
// The minted page is a first-class decision record: `recordDecision`
// owns the slug, the review obligation, the log event and the
// decision-record receipt. When the operator gave no rationale the
// assumption names the provenance (which open record decided this)
// rather than inventing a belief, and the body always carries the
// provenance link so a crashed resolve can converge (see
// {@link resolveMintTarget}).
const target = resolveMintTarget(vault, record);
let decisionId: string;
if (target.ours) {
// A previous attempt minted this page and crashed before stamping
// the record: the page is already authoritative, so only the stamp
// (and its mirrors) remain.
decisionId = `decision-${target.slug}`;
} else {
const minted = recordDecision(vault, {
title: target.title,
chosen: choice,
assumption: rationale || mintProvenance(record),
reviewDate: isoDate(now),
notes: mintNotes(record),
agent: actor,
now,
...(input.configPath !== undefined ? { configPath: input.configPath } : {}),
});
decisionId = minted.record.id;
}
const stamped: OpenDecisionRecord = Object.freeze({
...record,
status: OPEN_DECISION_STATUS.resolved,
resolvedAt: isoSecond(now),
choice,
decision: `[[${decisionId}]]`,
});
writeLaneText(vault, record.path, renderRecord(stamped));
try {
appendLogEvent(
vault,
{
timestamp: isoSecond(now),
eventType: BRAIN_LOG_EVENT_KIND.decisionResolved,
agent: actor,
body: {
open: `[[${record.id}]]`,
decision: `[[${decisionId}]]`,
choice,
agent: actor,
},
},
{ failOpen: true },
);
} catch {
// The record file is authoritative; the timeline mirror is best-effort.
}
// Exactly one open_resolved receipt per resolution (the receipts
// module's idempotency key makes a replay a no-op). Fail-soft like
// the record.ts trail: the stamped open record and the minted page
// are authoritative, so an accountability-log hiccup must not fail
// the transition itself.
try {
appendDecisionChangeReceipt(vault, {
subject: `[[${record.id}]]`,
before: OPEN_DECISION_STATUS.open,
after: `${OPEN_DECISION_STATUS.resolved} -> [[${decisionId}]]`,
evidenceTriggers: [`[[${decisionId}]]`],
actor,
...(rationale ? { rationale } : {}),
reasonCode: DECISION_CHANGE_REASON.openResolved,
ts: isoSecond(now),
...(input.configPath !== undefined ? { configPath: input.configPath } : {}),
});
} catch {
// Best-effort accountability; the stamped record is authoritative.
}
return { decision: decisionId };
});
}
/**
* Close a parked question WITHOUT deciding: stamp the reason and the
* instant, keep the record in place. No receipt - the change trail
* records belief changes, and a discarded question changed none.
*/
export function discardOpenDecision(
vault: string,
id: string,
input: DiscardOpenDecisionInput,
): void {
// Vault-identity write guard (context-integrity-gates, Unit J).
assertLaneWrite(vault);
const reason = requireTextField(input.reason, "reason", REASON_MAX_LEN);
withOpenDirLock(vault, () => {
const record = requireOpenRecord(vault, id);
if (record.status !== OPEN_DECISION_STATUS.open) {
throw new OpenDecisionError(
`open decision ${id} is terminal (${record.status}); only an open record can be discarded`,
);
}
const actor = actorFor(input, record.agent);
const now = input.now ?? new Date();
const stamped: OpenDecisionRecord = Object.freeze({
...record,
status: OPEN_DECISION_STATUS.discarded,
discardedAt: isoSecond(now),
discardReason: reason,
});
writeLaneText(vault, record.path, renderRecord(stamped));
try {
appendLogEvent(
vault,
{
timestamp: isoSecond(now),
eventType: BRAIN_LOG_EVENT_KIND.decisionDiscarded,
agent: actor,
body: {
open: `[[${record.id}]]`,
reason,
agent: actor,
},
},
{ failOpen: true },
);
} catch {
// The record file is authoritative; the timeline mirror is best-effort.
}
});
}