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
/**
* The schema mutation lane: apply (or preview) a batch of vocabulary
* changes to the `Brain/_brain.yaml` pack, with an audit record and a
* pack digest per apply.
*
* DENY COUPLING (PR #248 review L9): this lane consults the permissions
* document under the `ingest` action, so a deny on ingest also blocks
* schema batches and there is no way to deny schema changes alone - a
* dedicated action is a design change, not made here.
*/
import { existsSync, readFileSync } from "node:fs";
import { join } from "node:path";
import { appendAuditRecord } from "../reliability/audit.ts";
import { isStoreOnly } from "../store/store-only.ts";
import { atomicWriteText } from "../fs-atomic.ts";
import { withFileLock } from "../reliability/lock.ts";
import { brainConfigPath, brainDirsForWrite } from "./paths.ts";
import { applySchemaMutationsToStore } from "./schema-mutate-store.ts";
import { assertVaultIdentityForWrite } from "./vault-identity.ts";
import { REVIEW_LANE } from "./write-gate.ts";
import { refuseDocumentDeny, type WriteSubject } from "./write-disposition.ts";
import {
computeSchemaPackDigest,
SCHEMA_MUTATION_AUDIT_ACTION,
SCHEMA_MUTATION_AUDIT_DIR,
SCHEMA_PACK_DIGEST_FIELD,
} from "./schema-integrity.ts";
import {
ABSENT_SCHEMA_CONFIG_TEXT,
loadSchemaPack,
parseSchemaPack,
renderSchemaBlock,
replaceSchemaBlock,
pairEndpoints,
schemaPackTokens,
validateEndpointPair,
FRONTMATTER_TIERS,
type FrontmatterTier,
type SchemaPack,
} from "./schema-pack.ts";
import {
SCHEMA_VOCAB_CATEGORIES,
resolveSchemaVocabulary,
validateSchemaDeclarations,
validateSchemaToken,
type BrainSchemaDeclarations,
type SchemaVocabularyCategory,
} from "./schema-vocab.ts";
export type SchemaMutation =
| {
readonly op: "add_type" | "remove_type";
readonly category: SchemaVocabularyCategory;
readonly token: string;
}
| {
readonly op: "update_type";
readonly category: SchemaVocabularyCategory;
readonly token: string;
readonly new_token: string;
}
| {
readonly op: "add_alias" | "remove_alias";
readonly token: string;
readonly alias: string;
}
| {
readonly op: "add_prefix";
readonly prefix: string;
readonly token: string;
}
| { readonly op: "remove_prefix"; readonly prefix: string }
| {
readonly op: "add_link_type" | "remove_link_type";
readonly token: string;
}
| {
readonly op: "set_extractable";
readonly token: string;
readonly enabled: boolean;
}
| {
readonly op: "set_expert_routing";
readonly token: string;
readonly expert: string | null;
}
| {
readonly op: "add_label_dimension";
readonly dimension: string;
readonly values: ReadonlyArray<string>;
}
| { readonly op: "remove_label_dimension"; readonly dimension: string }
| {
readonly op: "add_link_constraint" | "remove_link_constraint";
readonly link_type: string;
readonly source: string;
readonly target: string;
}
| {
readonly op: "set_attribute_field";
readonly type: string;
readonly field: string;
readonly description: string;
}
| {
readonly op: "remove_attribute_field";
readonly type: string;
readonly field: string;
}
| {
readonly op: "set_frontmatter_tier";
readonly kind: string;
readonly field: string;
readonly tier: FrontmatterTier;
}
| {
readonly op: "remove_frontmatter_tier";
readonly kind: string;
readonly field: string;
};
/** The vault-relative pack path the deny consult and the audit record name. */
export const BRAIN_CONFIG_TARGET = "Brain/_brain.yaml";
export interface ApplySchemaMutationsOptions {
readonly actor: string;
readonly now?: Date;
readonly reason?: string;
readonly lockStaleMs?: number;
/**
* The credential subject the deny consult answers for (write-side trust,
* Task 12). Absent - stdio, the CLI - the consult falls back to the
* principal this process's config declares, exactly like the other
* deny-consulted mutation lanes. Never the caller-named `actor`: that
* label is an audit field, not an identity a policy can answer on.
*/
readonly subject?: WriteSubject;
/**
* Authority of the store records on a store-only machine: `human` from
* the CLI, `agent` from MCP. Absent: decided by the process's origin.
*/
readonly authority?: "human" | "agent";
/** Store-only: adopt unattested deciding records (operator only; `./schema-mutate-store.ts`). */
readonly adoptUnattested?: boolean;
}
export interface ApplySchemaMutationsResult {
readonly applied: number;
readonly audit_path: string;
readonly pack: SchemaPack;
/**
* Digest of the pack this batch produced, identical to the value written
* into the audit record. Returned so a caller can seal a downstream
* artifact against the same expectation a later
* `assessSchemaPackIntegrity` will compare with, without re-reading the
* audit trail it just wrote.
*/
readonly pack_digest: string;
}
/**
* One leaf-level difference between two schema packs.
*
* `before === null` means the leaf would appear, `after === null` means it
* would disappear, and two non-null values mean a scalar leaf's value would
* change. A `path` is the dotted address of the leaf inside the pack
* (`declarations.preference_types`, `prefixes.pref`, `attributes.paper.doi`);
* list-valued paths report one entry per member, so a rename shows as a
* removal and an addition under the same path rather than as a mutation of
* an anonymous list.
*/
export interface SchemaPackDiffEntry {
readonly path: string;
readonly before: string | null;
readonly after: string | null;
}
/**
* The result of {@link previewSchemaMutations}. Deliberately NOT the shape of
* {@link ApplySchemaMutationsResult}: a preview has no `audit_path` because it
* wrote no audit record, and it reports `would_apply` rather than `applied`
* because nothing was applied. A caller can therefore never mistake a dry run
* for a real mutation.
*/
export interface PreviewSchemaMutationsResult {
readonly dry_run: true;
/** How many mutations were submitted; see `diff` for what would change. */
readonly would_apply: number;
readonly pack: SchemaPack;
readonly diff: ReadonlyArray<SchemaPackDiffEntry>;
}
/** The refusal of an adoption with no mutation on an unswitched machine. */
export const SCHEMA_ADOPT_ONLY_UNSWITCHED =
"schema apply --adopt-unattested without a mutation is for a store-only machine; " +
"this one reads its schema from the vault file, which has no records to adopt";
/**
* Separates a leaf's path from its value when keying a list MEMBER, so two
* members of the same list do not collide in the flat map the diff walks. A
* NUL byte cannot occur in a schema token, an endpoint pair, or a rendered
* single-line description, so the key is unambiguous.
*/
const LEAF_KEY_SEPARATOR = "\u0000";
interface PackLeaf {
readonly path: string;
readonly value: string;
}
interface MutableSchemaPack {
declarations: Record<SchemaVocabularyCategory, string[]>;
aliases: Record<string, string[]>;
prefixes: Record<string, string>;
link_types: string[];
extractable: string[];
expert_routing: Record<string, string>;
labels: Record<string, string[]>;
link_constraints: Record<string, string[]>;
attributes: Record<string, Record<string, string>>;
frontmatter_tiers: Record<string, Record<string, FrontmatterTier>>;
}
export async function applySchemaMutations(
vault: string,
mutations: ReadonlyArray<SchemaMutation>,
opts: ApplySchemaMutationsOptions,
): Promise<ApplySchemaMutationsResult> {
// Vault-identity write guard (context-integrity-gates, Unit J), ahead
// of the `_brain.yaml` rewrite - the trailing audit append is far too
// late to stop a schema landing in the wrong store.
const storeOnly = isStoreOnly({ vault });
// A store-only machine checks the store's identity on the write itself;
// the vault identity guard is the legacy tree's.
if (!storeOnly) assertVaultIdentityForWrite(vault);
// Adoption alone (an empty batch) is for a store-only machine: the file
// path has no records to adopt, and an empty apply there would rewrite
// and re-attest `_brain.yaml` as it stands.
if (!storeOnly && mutations.length === 0 && opts.adoptUnattested === true) {
throw new Error(SCHEMA_ADOPT_ONLY_UNSWITCHED);
}
// Deny-consulted evidence (write-side trust, PR #247 review M3 residual,
// schema sibling): a schema batch rewrites the operator's vocabulary pack
// - the same mutation-lane shape as update, append and delete_by_source -
// so the document is resolved against the credential subject and a deny
// refuses with the SAME typed error BEFORE the config is read for
// rewriting or any audit record exists, one decision-ledger row behind
// it. The pack shapes what every later ingest and note write admits, so
// a caller a document closed must not reach it around the rule. An ask
// and an allow change nothing: no row, no stage, the apply proceeds
// exactly as before. With no permissions document this is a no-op. The
// dry-run preview below stays a read and stays ungated.
refuseDocumentDeny(vault, REVIEW_LANE.ingest, opts.subject, {
target: BRAIN_CONFIG_TARGET,
...(opts.now !== undefined ? { now: opts.now } : {}),
});
const now = opts.now ?? new Date();
if (storeOnly) {
return await applySchemaMutationsToStore(vault, mutations, {
actor: opts.actor,
now,
...(opts.reason !== undefined ? { reason: opts.reason } : {}),
...(opts.lockStaleMs !== undefined ? { lockStaleMs: opts.lockStaleMs } : {}),
...(opts.authority !== undefined ? { authority: opts.authority } : {}),
...(opts.adoptUnattested === true ? { adoptUnattested: true } : {}),
next: (current) => applyMutationsToPack(current, mutations),
});
}
const configPath = brainConfigPath(vault);
return await withFileLock(configPath, { staleMs: opts.lockStaleMs ?? 30_000, retries: 3 }, () => {
const before = existsSync(configPath)
? readFileSync(configPath, "utf8")
: ABSENT_SCHEMA_CONFIG_TEXT;
const nextPack = applyMutationsToPack(parseSchemaPack(before), mutations);
const nextText = replaceSchemaBlock(before, renderSchemaBlock(nextPack));
atomicWriteText(configPath, nextText, {
validate: (candidate) => {
parseSchemaPack(candidate);
},
});
// The audit record has always said WHICH mutations were requested. The
// digest is what it was missing: an expectation a later read can hold
// the file against, so a hand-edit after this apply is detectable
// rather than indistinguishable from the pack this batch produced.
const packDigest = computeSchemaPackDigest(nextPack);
const auditPath = appendAuditRecord(
join(brainDirsForWrite(vault).log, SCHEMA_MUTATION_AUDIT_DIR),
{
timestamp: now.toISOString(),
actor: opts.actor,
action: SCHEMA_MUTATION_AUDIT_ACTION,
target: BRAIN_CONFIG_TARGET,
ok: true,
details: {
applied: mutations.length,
mutations,
[SCHEMA_PACK_DIGEST_FIELD]: packDigest,
...(opts.reason ? { reason: opts.reason } : {}),
},
},
vault,
);
return {
applied: mutations.length,
audit_path: auditPath,
pack: nextPack,
pack_digest: packDigest,
};
});
}
export function applyMutationsToPack(
pack: SchemaPack,
mutations: ReadonlyArray<SchemaMutation>,
): SchemaPack {
const mutable = clonePack(pack);
for (const mutation of mutations) {
applyOne(mutable, mutation);
}
const next = freezeMutable(mutable);
validateSchemaPackReferences(next);
return next;
}
/**
* Build the pack {@link applySchemaMutations} would persist for this batch,
* WITHOUT touching disk, together with its difference from the pack currently
* on disk.
*
* The preview runs the same {@link applyMutationsToPack} the write path runs,
* so a batch the validator rejects raises here exactly what it would raise
* there, and a batch it accepts yields exactly the pack that would land. A
* preview that were more permissive than the apply it previews would be worse
* than no preview at all.
*
* Two deliberate asymmetries with the write path, both because nothing is
* written: no file lock is taken (a lock is a file, and a preview creates no
* files), and the vault-identity WRITE guard is not run - its job is to refuse
* a write to a store this process did not open, and running it here would pin
* this process's identity as a side effect of a read.
*/
export function previewSchemaMutations(
vault: string,
mutations: ReadonlyArray<SchemaMutation>,
): PreviewSchemaMutationsResult {
const current = loadSchemaPack(vault);
const next = applyMutationsToPack(current, mutations);
return {
dry_run: true,
would_apply: mutations.length,
pack: next,
diff: diffSchemaPacks(current, next),
};
}
/**
* Leaf-level difference between two schema packs, ordered by path so the same
* two packs always produce the same list.
*
* `vocabulary` is excluded: it is the closure of `declarations` over the
* built-in vocabulary, so every difference in it is already reported under
* `declarations` and listing both would double-count one change.
*/
export function diffSchemaPacks(
before: SchemaPack,
after: SchemaPack,
): ReadonlyArray<SchemaPackDiffEntry> {
const left = flattenPack(before);
const right = flattenPack(after);
const entries: SchemaPackDiffEntry[] = [];
for (const [key, leaf] of left) {
const next = right.get(key);
if (next === undefined) {
entries.push({ path: leaf.path, before: leaf.value, after: null });
} else if (next.value !== leaf.value) {
entries.push({ path: leaf.path, before: leaf.value, after: next.value });
}
}
for (const [key, leaf] of right) {
if (!left.has(key)) entries.push({ path: leaf.path, before: null, after: leaf.value });
}
// Ordered by path, then by the value each entry is about - so a rename
// under one path reports the departing member before the arriving one.
return entries.toSorted(
(a, b) => a.path.localeCompare(b.path) || diffEntryValue(a).localeCompare(diffEntryValue(b)),
);
}
/** The value a diff entry is about: what left, or - for an addition - what arrived. */
function diffEntryValue(entry: SchemaPackDiffEntry): string {
return entry.before ?? entry.after ?? "";
}
/** Flatten every authored leaf of a pack to `key -> {path, value}`. */
function flattenPack(pack: SchemaPack): Map<string, PackLeaf> {
const leaves = new Map<string, PackLeaf>();
for (const category of SCHEMA_VOCAB_CATEGORIES) {
addMembers(leaves, `declarations.${category}`, pack.declarations[category] ?? []);
}
addRecordMembers(leaves, "aliases", pack.aliases);
addScalars(leaves, "prefixes", pack.prefixes);
addMembers(leaves, "link_types", pack.link_types);
addMembers(leaves, "extractable", pack.extractable);
addScalars(leaves, "expert_routing", pack.expert_routing);
addRecordMembers(leaves, "labels", pack.labels);
addRecordMembers(leaves, "link_constraints", pack.link_constraints);
addNestedScalars(leaves, "attributes", pack.attributes);
addNestedScalars(leaves, "frontmatter_tiers", pack.frontmatter_tiers);
return leaves;
}
/**
* List members: the value is part of the key, so membership changes read as
* an addition or a removal and never as an in-place edit of a list slot.
*/
function addMembers(
leaves: Map<string, PackLeaf>,
path: string,
values: ReadonlyArray<string>,
): void {
for (const value of values) {
leaves.set(`${path}${LEAF_KEY_SEPARATOR}${value}`, { path, value });
}
}
/** Scalar map: the key is the leaf path, so a changed value reads as an edit. */
function addScalars(
leaves: Map<string, PackLeaf>,
prefix: string,
record: Readonly<Record<string, string>>,
): void {
for (const [key, value] of Object.entries(record)) {
const path = `${prefix}.${key}`;
leaves.set(path, { path, value });
}
}
function addRecordMembers(
leaves: Map<string, PackLeaf>,
prefix: string,
record: Readonly<Record<string, ReadonlyArray<string>>>,
): void {
for (const [key, values] of Object.entries(record))
addMembers(leaves, `${prefix}.${key}`, values);
}
function addNestedScalars(
leaves: Map<string, PackLeaf>,
prefix: string,
record: Readonly<Record<string, Readonly<Record<string, string>>>>,
): void {
for (const [key, inner] of Object.entries(record)) addScalars(leaves, `${prefix}.${key}`, inner);
}
function applyOne(pack: MutableSchemaPack, mutation: SchemaMutation): void {
switch (mutation.op) {
case "add_type": {
const token = validateSchemaToken(mutation.token, `schema.${mutation.category}`);
addUnique(pack.declarations[mutation.category], token);
return;
}
case "remove_type": {
const token = validateSchemaToken(mutation.token, `schema.${mutation.category}`);
removeValue(pack.declarations[mutation.category], token);
delete pack.aliases[token];
for (const [prefix, target] of Object.entries(pack.prefixes)) {
if (target === token) delete pack.prefixes[prefix];
}
removeValue(pack.extractable, token);
delete pack.expert_routing[token];
delete pack.attributes[token];
for (const [linkType, pairs] of Object.entries(pack.link_constraints)) {
const kept = pairs.filter((pair) => !pairEndpoints(pair).includes(token));
if (kept.length > 0) pack.link_constraints[linkType] = kept;
else delete pack.link_constraints[linkType];
}
return;
}
case "update_type": {
const token = validateSchemaToken(mutation.token, `schema.${mutation.category}`);
const next = validateSchemaToken(mutation.new_token, `schema.${mutation.category}`);
replaceDeclaredValue(pack.declarations[mutation.category], token, next, mutation.category);
if (pack.aliases[token]) {
pack.aliases[next] = pack.aliases[token]!;
delete pack.aliases[token];
}
for (const [prefix, target] of Object.entries(pack.prefixes)) {
if (target === token) pack.prefixes[prefix] = next;
}
replaceExistingValue(pack.extractable, token, next);
if (pack.expert_routing[token]) {
pack.expert_routing[next] = pack.expert_routing[token]!;
delete pack.expert_routing[token];
}
if (pack.attributes[token]) {
pack.attributes[next] = pack.attributes[token]!;
delete pack.attributes[token];
}
for (const [linkType, pairs] of Object.entries(pack.link_constraints)) {
pack.link_constraints[linkType] = pairs.map((pair) => {
const [source, target] = pair.split("->");
const nextSource = source === token ? next : source!;
const nextTarget = target === token ? next : target!;
return `${nextSource}->${nextTarget}`;
});
}
return;
}
case "add_alias": {
const token = validateSchemaToken(mutation.token, "schema.aliases");
const alias = validateSchemaToken(mutation.alias, `schema.aliases.${token}`);
pack.aliases[token] = pack.aliases[token] ?? [];
addUnique(pack.aliases[token]!, alias);
return;
}
case "remove_alias": {
const token = validateSchemaToken(mutation.token, "schema.aliases");
const alias = validateSchemaToken(mutation.alias, `schema.aliases.${token}`);
removeValue(pack.aliases[token] ?? [], alias);
if ((pack.aliases[token]?.length ?? 0) === 0) delete pack.aliases[token];
return;
}
case "add_prefix": {
const prefix = validateSchemaToken(mutation.prefix, "schema.prefixes");
const token = validateSchemaToken(mutation.token, `schema.prefixes.${prefix}`);
pack.prefixes[prefix] = token;
return;
}
case "remove_prefix": {
const prefix = validateSchemaToken(mutation.prefix, "schema.prefixes");
delete pack.prefixes[prefix];
return;
}
case "add_link_type": {
const token = validateSchemaToken(mutation.token, "schema.link_types");
addUnique(pack.link_types, token);
return;
}
case "remove_link_type": {
const token = validateSchemaToken(mutation.token, "schema.link_types");
removeValue(pack.link_types, token);
delete pack.link_constraints[token];
// A pair of another link type may name the link type as an endpoint;
// it goes with it unless a vocabulary type keeps the token declared.
const vocabulary = resolveSchemaVocabulary(pruneDeclarations(pack.declarations));
if (SCHEMA_VOCAB_CATEGORIES.some((category) => vocabulary[category].includes(token))) {
return;
}
for (const [linkType, pairs] of Object.entries(pack.link_constraints)) {
const kept = pairs.filter((pair) => !pairEndpoints(pair).includes(token));
if (kept.length > 0) pack.link_constraints[linkType] = kept;
else delete pack.link_constraints[linkType];
}
return;
}
case "set_extractable": {
const token = validateSchemaToken(mutation.token, "schema.extractable");
if (mutation.enabled) addUnique(pack.extractable, token);
else removeValue(pack.extractable, token);
return;
}
case "set_expert_routing": {
const token = validateSchemaToken(mutation.token, "schema.expert_routing");
const expert = mutation.expert?.trim() ?? "";
if (mutation.expert === null || expert === "") {
delete pack.expert_routing[token];
} else if (/[\r\n]/.test(mutation.expert)) {
throw new Error(`schema.expert_routing.${token}: expert must be a single line`);
} else {
pack.expert_routing[token] = expert;
}
return;
}
case "add_label_dimension": {
const dimension = validateSchemaToken(mutation.dimension, "schema.labels");
const values = mutation.values.map((value, index) =>
validateSchemaToken(value, `schema.labels.${dimension}[${index}]`),
);
if (values.length === 0) {
throw new Error(`schema.labels.${dimension}: at least one value is required`);
}
pack.labels[dimension] = pack.labels[dimension] ?? [];
for (const value of values) addUnique(pack.labels[dimension]!, value);
return;
}
case "remove_label_dimension": {
const dimension = validateSchemaToken(mutation.dimension, "schema.labels");
delete pack.labels[dimension];
return;
}
case "add_link_constraint": {
const linkType = validateSchemaToken(mutation.link_type, "schema.link_constraints");
const pair = validateEndpointPair(
`${mutation.source}->${mutation.target}`,
`schema.link_constraints.${linkType}`,
);
pack.link_constraints[linkType] = pack.link_constraints[linkType] ?? [];
addUnique(pack.link_constraints[linkType]!, pair);
return;
}
case "remove_link_constraint": {
const linkType = validateSchemaToken(mutation.link_type, "schema.link_constraints");
const pair = validateEndpointPair(
`${mutation.source}->${mutation.target}`,
`schema.link_constraints.${linkType}`,
);
removeValue(pack.link_constraints[linkType] ?? [], pair);
if ((pack.link_constraints[linkType]?.length ?? 0) === 0) {
delete pack.link_constraints[linkType];
}
return;
}
case "set_attribute_field": {
const type = validateSchemaToken(mutation.type, "schema.attributes");
const field = validateSchemaToken(mutation.field, `schema.attributes.${type}`);
const description = mutation.description.trim();
if (description.length === 0) {
throw new Error(`schema.attributes.${type}.${field}: description must not be empty`);
}
if (/[\r\n]/.test(mutation.description)) {
throw new Error(`schema.attributes.${type}.${field}: description must be a single line`);
}
pack.attributes[type] = pack.attributes[type] ?? {};
pack.attributes[type]![field] = description;
return;
}
case "remove_attribute_field": {
const type = validateSchemaToken(mutation.type, "schema.attributes");
const field = validateSchemaToken(mutation.field, `schema.attributes.${type}`);
delete pack.attributes[type]?.[field];
if (Object.keys(pack.attributes[type] ?? {}).length === 0) delete pack.attributes[type];
return;
}
case "set_frontmatter_tier": {
const kind = validateSchemaToken(mutation.kind, "schema.frontmatter_tiers");
const field = validateSchemaToken(mutation.field, `schema.frontmatter_tiers.${kind}`);
if (!FRONTMATTER_TIERS.includes(mutation.tier)) {
throw new Error(
`schema.frontmatter_tiers.${kind}.${field}: tier must be one of ${FRONTMATTER_TIERS.join(", ")}`,
);
}
pack.frontmatter_tiers[kind] = pack.frontmatter_tiers[kind] ?? {};
pack.frontmatter_tiers[kind]![field] = mutation.tier;
return;
}
case "remove_frontmatter_tier": {
const kind = validateSchemaToken(mutation.kind, "schema.frontmatter_tiers");
const field = validateSchemaToken(mutation.field, `schema.frontmatter_tiers.${kind}`);
delete pack.frontmatter_tiers[kind]?.[field];
if (Object.keys(pack.frontmatter_tiers[kind] ?? {}).length === 0) {
delete pack.frontmatter_tiers[kind];
}
return;
}
}
}
function clonePack(pack: SchemaPack): MutableSchemaPack {
return {
declarations: {
preference_types: [...(pack.declarations.preference_types ?? [])],
signal_types: [...(pack.declarations.signal_types ?? [])],
page_types: [...(pack.declarations.page_types ?? [])],
log_event_kinds: [...(pack.declarations.log_event_kinds ?? [])],
},
aliases: mapArrayRecord(pack.aliases),
prefixes: { ...pack.prefixes },
link_types: [...pack.link_types],
extractable: [...pack.extractable],
expert_routing: { ...pack.expert_routing },
labels: mapArrayRecord(pack.labels),
link_constraints: mapArrayRecord(pack.link_constraints),
attributes: mapNestedRecord(pack.attributes),
frontmatter_tiers: mapNestedRecord(pack.frontmatter_tiers),
};
}
function freezeMutable(input: MutableSchemaPack): SchemaPack {
const declarations = validateSchemaDeclarations(pruneDeclarations(input.declarations));
return parseSchemaPack(
renderSchemaBlock({
declarations,
vocabulary: {} as never,
aliases: freezeArrayRecord(input.aliases),
prefixes: Object.freeze({ ...input.prefixes }),
link_types: Object.freeze([...input.link_types]),
extractable: Object.freeze([...input.extractable]),
expert_routing: Object.freeze({ ...input.expert_routing }),
labels: freezeArrayRecord(input.labels),
link_constraints: freezeArrayRecord(input.link_constraints),
attributes: freezeNestedRecord(input.attributes),
frontmatter_tiers: freezeNestedRecord(input.frontmatter_tiers),
}),
);
}
function validateSchemaPackReferences(pack: SchemaPack): void {
const tokens = schemaPackTokens(pack);
for (const token of Object.keys(pack.aliases)) {
if (!tokens.has(token)) throw new Error(`schema.aliases.${token}: token is not declared`);
}
for (const [prefix, token] of Object.entries(pack.prefixes)) {
if (!tokens.has(token)) throw new Error(`schema.prefixes.${prefix}: token is not declared`);
}
for (const token of pack.extractable) {
if (!tokens.has(token)) throw new Error(`schema.extractable.${token}: token is not declared`);
}
for (const token of Object.keys(pack.expert_routing)) {
if (!tokens.has(token)) {
throw new Error(`schema.expert_routing.${token}: token is not declared`);
}
}
for (const [linkType, pairs] of Object.entries(pack.link_constraints)) {
if (!pack.link_types.includes(linkType)) {
throw new Error(`schema.link_constraints.${linkType}: link type is not declared`);
}
for (const pair of pairs) {
if (!pairEndpoints(pair).every((token) => tokens.has(token))) {
throw new Error(`schema.link_constraints.${linkType}: ${pair}: token is not declared`);
}
}
}
for (const type of Object.keys(pack.attributes)) {
if (!tokens.has(type)) {
throw new Error(`schema.attributes.${type}: token is not declared`);
}
}
}
function mapNestedRecord<T extends string>(
record: Readonly<Record<string, Readonly<Record<string, T>>>>,
): Record<string, Record<string, T>> {
const out: Record<string, Record<string, T>> = {};
for (const [key, inner] of Object.entries(record)) out[key] = { ...inner };
return out;
}
function freezeNestedRecord<T extends string>(
record: Record<string, Record<string, T>>,
): Readonly<Record<string, Readonly<Record<string, T>>>> {
const out: Record<string, Readonly<Record<string, T>>> = {};
for (const [key, inner] of Object.entries(record)) out[key] = Object.freeze({ ...inner });
return Object.freeze(out);
}
function pruneDeclarations(
declarations: Record<SchemaVocabularyCategory, string[]>,
): BrainSchemaDeclarations {
const out: Partial<Record<SchemaVocabularyCategory, ReadonlyArray<string>>> = {};
for (const category of SCHEMA_VOCAB_CATEGORIES) {
const values = declarations[category];
if (values.length > 0) out[category] = values;
}
return out as BrainSchemaDeclarations;
}
function mapArrayRecord(
record: Readonly<Record<string, ReadonlyArray<string>>>,
): Record<string, string[]> {
const out: Record<string, string[]> = {};
for (const [key, values] of Object.entries(record)) out[key] = [...values];
return out;
}
function freezeArrayRecord(
record: Record<string, string[]>,
): Readonly<Record<string, ReadonlyArray<string>>> {
const out: Record<string, ReadonlyArray<string>> = {};
for (const [key, values] of Object.entries(record)) out[key] = Object.freeze([...values]);
return Object.freeze(out);
}
function addUnique(values: string[], token: string): void {
if (!values.includes(token)) values.push(token);
}
function removeValue(values: string[], token: string): void {
const index = values.indexOf(token);
if (index >= 0) values.splice(index, 1);
}
function replaceDeclaredValue(
values: string[],
token: string,
next: string,
category: SchemaVocabularyCategory,
): void {
const index = values.indexOf(token);
if (index < 0) throw new Error(`schema.${category}: ${token} is not declared`);
values[index] = next;
}
function replaceExistingValue(values: string[], token: string, next: string): void {
const index = values.indexOf(token);
if (index >= 0) values[index] = next;
}