Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
32.1 KB
Raw Blame

Schema packs: mutation surface (key files cluster)

Subsystem index.

The schema-pack mutation surface: six foundation modules + a mutate skeleton + stats/sync data plane + CLI verbs + MCP ops + a first-class agent skill.

Key files:

  • src/core/persistence/staging.ts — journaled same-directory staging descriptors reserve names, expected sizes and full hashes before any sink. Owner-locked recovery removes only known complete regular files; partial/unexpected bytes keep the root and recovery quota blocked, including committed receipt cleanup. Legacy records acquire durable staging descriptors before any new restoration. Final accounting requires verified absence and parent-directory durability. Stage digests are read in pieces (large-file.ts hashDescriptor). Wave B: a before stage (.<sha256>.tmp.before-<uuid>, a name older binaries refuse) holds the copy of a prior canonical file over 24 MiB; a live request's recovery keeps it (cleanupRecoveryStaging(record, { keepBefore })) until restoreBeforeStage renames it back over the file with its recorded mode or it is removed because the file already holds the prior bytes. A publication stage's stream still under its in-progress name (<stage>.streaming) is removed unread by cleanupRecoveryStaging and discardStreamingStage (never published; its bytes are produced again) and must be absent for final accounting; a partial file at the stage's own name still refuses. publishStreamedStage is the forward half of a version 2 withdrawal-mirror record (effect-model.ts): its verified publication stage, streamed from a segmented page's segments, is renamed over the canonical file; a missing stage refuses unexpected_staging_bytes. A regular-file ancestor proves an uncreated staging leaf is absent; recovery flushes the containing directory and settles the storage failure without deleting that ancestor or retaining a false recovery fence. Tests: atomic-write.test.ts, atomic-long-staging.test.ts, persistence-staging.test.ts, and eight-boundary process-crash harness.

  • src/core/fs-durable.ts — the shared durable-flush leaf (imports only node:fs). flushFile(path) fsyncs a file nobody holds open through 'r+' on win32 (Windows FlushFileBuffers needs write access) and 'r' elsewhere (a 0444 file stays flushable); a read-only file on win32 cannot be opened writable and is left to the OS. flushDirectory(path, { bestEffort }) is strict by default: every error propagates except the win32 no-directory-flush codes (EISDIR/EPERM/EINVAL/ENOTSUP), a non-directory path fails ENOTDIR, and bestEffort swallows everything. sameFileMode(actual, expected) compares every permission bit on POSIX and only the owner write bit on win32, whose stat reports 0444/0666. A writer that still holds its descriptor sets the mode with fchmodSync(fd) and fsyncs that descriptor instead (atomic-write, skill-bundle staging). Callers: atomic-write, the persistence coordinator, identity, root registry, physical-root records, reconcile backups, recovery staging, topology checkouts (flushTopologyDirectory re-export, flushTopologyTree), skill bundles, agent-install state (syncDirectory re-export), sources reconcile previews and attendance-repair checkpoints. scripts/check-durable-flush.ts keeps new read-handle flushes out of src/ (docs/ci-guards.md#durable-flush-guard). Tests: test/fs-durable.test.ts, test/persistence-windows-flush-5595.test.ts, test/bundle-files-windows-5475.test.ts, test/init-packaged-skills-native.test.ts, run natively on windows-latest in the test.yml security-regressions job.

  • src/core/atomic-write.ts — the shared atomic file writer for brain-repo markdown writers: unique short hidden tmp sibling from atomicStagingPath (.<sha256(full target path)>.tmp.<uuid>, so a valid basename near NAME_MAX still stages, #5861; validateAtomicStagingPath also accepts the historical <target>.tmp.<uuid> journal form, and recovery (persistence/staging.ts upgradeRecoveryStaging) durably swaps in a short stage only for a recorded historical leaf that returns ENAMETOOLONG; timeline-write-through.ts reuses the same allocator) → write loop until every byte lands (writeSync may legally short-write under disk pressure; a silent short write could atomically install truncated content) → fsync → close → synchronous staging boundary → optional verify(onDiskBytes) callback (throw = abort, tmp removed, target untouched) → atomic rename → parent-directory fsync through fs-durable.ts flushDirectory (rename durability; strict under durable, the journaled-publication flag, best-effort otherwise). The stage is opened with its final mode and fchmod-ed on the descriptor past the umask before any byte is written: AtomicWriteOpts.mode sets exact bits and reasserts them over an existing target's mode (a legacy 0644 file tightens on its next write); omitted, the target's existing mode is preserved, else 0644 & ~umask. mkdirPrivate(dir, root = dir) creates gbrain-private directories: a missing root gets default-permission ancestors and is itself made exactly 0700, each missing directory between root and dir is created 0700 (O_NOFOLLOW fchmod), and a directory that already exists, possibly one the user chose, is never chmod-ed; dir outside root throws. Consumers of the private modes: the Google connector (google-source.ts, sources-ops.ts Google add) and the persistence coordinator's Google publication. Consumed by src/commands/backlinks.ts (which verifies with parseMarkdown({validate:true}) before the rename). Rename prevents torn writes, NOT lost updates — read-modify-write callers pair it with withPageLock (backlinks does). Unifying the per-module copies (skillopt/apply-edits, write-through, lint) is a filed TODO.

  • src/core/schema-pack/unify-types-handler.ts + src/core/onboard/checks.ts (checkPackUpgradeAvailable) — pack-upgrade retype (runUnifyTypes, the unify-types job). #6196: on a managed brain apply runs the dry run first (applyOnManagedBrain): with nothing to retype, link or alias it only switches the active pack (flipActivePack, DB + file plane); otherwise it refuses writer_coordinator_required with the counts and a read-only gbrain onboard --check --explain fix before any lock or write, and the dry run warns that apply waits for coordinated retype. pack_upgrade_available on a managed brain is an info row (readiness_state: degraded) with that preview as its fix and no unify-types apply remediation it could not run. Coordinated retype (D2) is deferred.

  • src/core/onboard/checks.ts (checkTypeProliferation) — doctor/onboard type_proliferation (#6289): one SELECT DISTINCT source_id, type read; each source resolves its own pack through loadActivePackForLocalEngine(engine, { sourceId }) (per-source DB config included); sources sharing a pack pool their labels, an alias counts as its canonical type (classifyStoredType), and each pool is graded with the unchanged thresholds (warn above declared + 5, fail above declared × 2). The message names the worst pool's sources, pack and up to five undeclared labels. A source whose pack does not resolve, or a failed query, warns "not verified", never ok. Pinned by test/onboard-pack-upgrade-checks.test.ts.

  • src/core/schema-pack/pack-lock.ts — Atomic O_CREAT|O_EXCL per-pack lock. DELIBERATELY NOT the existsSync + writeFileSync TOCTOU shape from src/core/page-lock.ts. Default 60s TTL, refresh every 10s while withPackLock(fn) runs, --force semantics = "steal stale lock" NOT "skip locking." Lock path per-pack so two packs never block each other.

  • src/core/schema-pack/write-vocabulary.ts — write-time pack-vocabulary enforcement shared by the write surfaces (capture op, add_link op, gbrain capture CLI). loadActivePackForWriteVocabulary(ctx) pairs the engine's DB-plane schema_pack key with FILE-ONLY config (the loadActivePackForLocalEngine posture) while threading remote (fail-closed: anything not strictly false is remote) + sourceId; NEVER throws — null means "no resolvable pack", which callers MUST treat as "no vocabulary to enforce" (the write proceeds exactly as before). packDeclaresPageType/packDeclaresLinkType + message/suggestion formatters reject an EXPLICIT undeclared name with the pack's declared vocabulary in the error so agents self-correct without a gbrain schema explain round-trip. The DEFAULT note path is never checked here — callers validate EXPLICIT names only, so bare gbrain capture works under a pack that doesn't declare note. loadActivePackForWriteVocabulary also swallows a rejecting getConfig; previewNames bounds the vocabulary preview in the error (the first 12 names + (N total)). Pinned by test/write-vocabulary.test.ts.

  • src/core/schema-pack/mutate-audit.ts — ISO-week JSONL at ~/.gbrain/audit/schema-mutations-YYYY-Www.jsonl. Privacy-redacted: type names → sha8, prefixes → first slug segment only, matches candidate-audit.ts privacy posture. Logs BOTH success AND failure events so a future schema_pack_writability doctor check has signal. summarizeMutations() is the cross-surface parity primitive.

  • src/core/schema-pack/registry.ts — resolvePack walks the extends chain (depth cap via EXTENDS_DEPTH_WARN / EXTENDS_DEPTH_HARD_CAP), RETAINS each ancestor manifest, materializes borrow_from, and composes all of it into resolved.manifest through mergeInheritedManifest. Every downstream consumer reads resolved.manifest, so doing the merge here is what makes inheritance visible without per-consumer wiring. borrow_from is selective (only the named types / link_types, and only from the target's OWN declarations), non-transitive, and fail-closed — a missing target throws UnknownPackError via loadByName, matching the extends path; an omitted category borrows none of it. The alias graph + closure hash are computed on the MERGED manifest, so a cross-pack alias cycle surfaces as AliasCycleError at resolve. manifest_sha8 / packIdentity stay the CHILD's own bytes — a parent edit does not move the child's identity, so the invalidation path is what keeps a child honest. invalidatePackCache(name?) walks the extends-chain reverse-graph (editing a parent pack must not leave children stale). tryCachedPack(name) TTL-gated fast path: inside STAT_TTL_MS (default 1000ms, env GBRAIN_PACK_STAT_TTL_MS) returns cached without statting; outside the window it stats every TRACKED file — the extends chain PLUS every borrowed pack — and cascade-invalidates on mtime change (cross-process detection), so editing a borrowed pack invalidates its borrowers. Pinned by test/schema-pack-registry.test.ts + test/schema-pack-merge.test.ts.

  • src/core/schema-pack/merge.ts — the pure child-wins composition helper behind resolvePack. mergeInheritedManifest(ancestorsBaseFirst, child, borrowed) returns the fully-composed manifest; precedence is child → borrowed → nearest parent … → base. SIX ingest/query-shaping fields inherit: page_types, link_types, frontmatter_links, enrichable_types, filing_rules, takes_kinds. phases + calibration_domains are DELIBERATELY child-only — they gate real cycle execution (cycle.ts packDeclaresPhase), so inheriting them would silently run phases a pack never declared; mapping_rules, migration_from, extends, borrow_from, and the identity fields are child-only too (all ride the ...child spread). mergePageTypes carries the ordering contract inferTypeFromPack depends on (first-path_prefix-match-wins, array order): the BASE (root, extends: null) pack is the ordered foundation/tail; an override of a base type keeps the base POSITION (Map.set updates the value, keeps insertion order) so base's curated priority survives; a genuinely-new type from ANY non-base layer — child, borrowed, or a middle pack — is PREPENDED nearest-first, so a more-derived prefix wins regardless of chain depth. mergeByKey keeps the first occurrence per key walking highest-precedence-first (the order-insensitive keyed fields); frontmatter_links keys on page_type\x00link_type — a NUL, not a space, because both are unconstrained strings and a space-join would collide {"a b","c"} with {"a","b c"}. mergeUnion backs takes_kinds: UNION not replace, because the Zod default makes an omitted field indistinguishable from an explicit one — so a child can ADD kinds but CANNOT narrow below base ∪ parent. Pure + deterministic: no disk, no engine. Pinned by test/schema-pack-merge.test.ts.

  • src/core/schema-pack/engine-resolution.ts — schema-only live-engine boundary shared by best-effort, write vocabulary, op trust, import/sync, managed prepared import, and the MCP inspection ops (get_active_schema_pack, schema_explain_type, schema_graph, schema_lint on the active pack; #7942, test/schema-pack-source-inspection-7942.test.ts). engineSchemaInput reads selected-engine brain/source schema keys, using file-only config for the fallback while retaining per-call/environment precedence; it never merges model/provider settings. DB lookup failures propagate; only absent/empty keys permit fallback. Best-effort wrappers return null on failure instead of selecting host vocabulary. approvedSchemaIdentity hashes the full resolved manifest, including inherited link/inference definitions, independently of the alias-only hash. checkApprovedSchemaForEngine bypasses the registry TTL and rejects changed approved identities, untrusted callers, conflicting explicit/environment/per-source overrides, and unreadable DB state. It is read-only: allowBinding returns only {key: 'schema_pack', value, expectedValue} for the caller's selected-DB admission transaction. The caller must check destination compatibility/emptiness and apply the binding under its lifecycle lock/CAS; this helper neither authorizes that write nor writes host config. Tests: test/schema-engine-isolation.serial.test.ts.

  • src/core/schema-pack/query-types.ts — expands scalar/multiple type filters through the selected engine's active alias graph. Scalar and array filters retain intersection semantics; explicit empty arrays deny before any engine/cache access. Missing packs yield an empty filter that consumers return as no results, never as an unrestricted query; DB lookup failures propagate through keyword, hybrid and image readers. Mixed-pack explicit source scopes refuse rather than arbitrarily choosing a closure. Used by hybrid search and the search/query keyword-only/image bypasses; typed hybrid requests bypass semantic result caching. Tests: test/schema-engine-isolation.serial.test.ts, test/ops-search-types.test.ts.

  • src/core/schema-pack/entity-types.ts — #4772: the one answer to "is this stored type an entity" for the counters. entityTypesFromPack(manifest) returns the pack's primitive: entity type names (plus undeclared aliases of them) and the legacy names (entity, person, company, organization) the pack leaves undeclared; a pack that declares a legacy name under another primitive reclassified it and wins. resolveEntityTypes(engine, scope) resolves per source (every requested source id, or brain-wide: the brain's pack plus every registered source with a schema_pack.source.<id> override) into an EntityTypeFilter (default list + per-source lists that differ), and returns pack_unavailable with an empty filter when any pack in scope fails to load (the best-effort.ts null contract: empty filter, never hardcoded defaults). entityTypePredicateSql(alias, filter) renders it as a parameter-bound sqlFragment. #6953: personTypesFromPack / resolvePersonTypes answer "is this type person-like" the same way (per source, same pack_unavailable contract): person plus its alias closure (closure.ts), never primitive siblings; consumer cycle/edge-contradictions.ts: its works_at members are admitted before grouping and LIMIT only when the subject is person-like by its source's pack (a pack that does not load admits none) and the target is neither person-like nor a NON_EMPLOYER_TYPES type (untyped: NON_EMPLOYER_PREFIXES; both lists shared with link-target-roles.ts's targetTakesVerb); an open proposal made before that rule is not re-checked when applied (test/edge-employment-roles.test.ts + Postgres twin; personTypesFromPack in test/schema-pack-person-types-6953.test.ts). Consumers: engine-sql/health.ts through HealthDeps.entityTypes (both engines delegate), commands/doctor/checks/graph-health.ts (graph_coverage, orphan_ratio), onboard/checks.ts (entity_link_coverage, timeline_coverage, and visibleEntityCoverageSql for onboard/impact-capture.ts; a pack that does not load warns entity_types_unavailable), onboard/mcp-onboarding.ts (the three entity counts are null with entityTypesStatus: pack_unavailable; the timeline result predicate) and extract-ner.ts (the target-type map; pack_unavailable when a source's pack does not load). mentions/policy.ts keeps its own linkable-type union. Pinned by test/onboard-entity-types-pack-4772.test.ts. Lazy-imports the pack loader so the engines can import it statically.

  • src/core/schema-pack/best-effort.ts — loadActivePackBestEffort(ctx) returns ResolvedPack | null. Single source of truth for the pack-aware wiring sites. null means EMPTY FILTER (NOT hardcoded defaults, which would silently violate the pack). Threads the tier-4 DB-plane schema_pack from ctx.engine, so every caller resolves the SAME pack schema active / get_active_schema_pack report. readDbSchemaPack(engine?) is the ONE spelling of that tier-4 read (null-safe, propagates DB read failures, trims missing/empty values to undefined) — shared by both loaders here, the CLI inspection verbs (schema show/graph/lint/explain, via readDbSchemaPackConfig in src/commands/schema.ts, which keeps the cfg-null gate so an unconfigured home never cold-creates a PGLite dir) and the MCP schema_lint/schema_graph/schema_explain_type ops. loadActivePackForLocalEngine(engine) is the remote: false + FILE-ONLY-config variant for local engine-backed surfaces. Pinned by test/schema-pack-best-effort.test.ts, test/operations-schema-pack.test.ts, test/schema-cli-db-config.test.ts.

  • src/core/schema-pack/type-usage.ts — stored-type classifier behind the alias-footgun visibility surfaces: classifyStoredType(type, pack) → canonical | alias_of (with the canonical type + path_prefixes[0] filing directory) | undeclared, over a STRUCTURAL pack shape so import-file's thin activePack and the full manifest both satisfy it. sanitizeTypeForDisplay strips control chars + caps length (type strings come from frontmatter and get echoed into terminals); renderTypeWarningSummary renders the once-per-type-per-run lines. Consumers: importFromContent (advisory ImportResult.type_warning at the typeExplicit site — the type is still stored literally, zero filing change), sync/import summary aggregation (+ SyncResult.type_warnings so worker-driven syncs surface counts in job results), the stored_type_is_alias/stored_type_undeclared data-plane lint rules, all gated by config schema.type_warnings (default on; lint rules always active). storedTypeMissesPack(type, pack) (empty type, or undeclared) is the one predicate every pack-conformance surface uses: findTypeOrphans (schema-pack/review.ts), schema_stats coverage, doctor schema_pack_consistency, gbrain lint's type-undeclared rule. WRITER_OWNED_PAGE_SQL exempts pages gbrain's own writers wrote, judged by provenance (a code importer page, type and page_kind both code; a dream_generated extract_receipt under extracts/), from doctor schema_pack_consistency's undeclared count, so a custom pack copied before gbrain-base-v2 declared those types (#6818) is not reported as drift, while a user's Markdown page typed code still is (#8815, test/doctor-schema-pack-own-types-8815.test.ts). Pinned by test/schema-type-usage.test.ts and test/schema-pack-type-conformance.test.ts.

  • src/core/schema-pack/lint-rules.ts — 14 pure rule functions. withMutation's pre-write validation gate composes the 10 file-plane rules; the 4 DB-aware rules (extractable_empty_corpus, mutation_count_anomaly, stored_type_is_alias, stored_type_undeclared) need an engine (CLI --with-db; the stored-type pair accepts LintOpts.sourceId scoping, not yet threaded from the CLI). Single source of truth consumed by CLI lint + MCP schema_lint + the pre-write validation gate. File-plane rule link_regex_catastrophic_backtrack — advisory ReDoS pre-screen flagging the classic nested-quantifier shapes ((a+)+, (a*)*, (a+)*, (\w+)+) in a link_type's inference.regex via NESTED_QUANTIFIER_RE. WARNING not error: a hard reject would disable the whole pack on upgrade (pages fall back to legacy typing). The runtime input-length cap in redos-guard.ts is the actual safety net; this rule tells the pack author to fix the pattern.

  • src/core/schema-pack/redos-guard.ts + src/core/schema-pack/link-inference.ts — ReDoS hardening for pack inference regexes. redos-guard.ts provides MAX_REGEX_INPUT_CHARS (default 64_000, env GBRAIN_MAX_REGEX_INPUT_CHARS) — a hard input-length cap, the real runtime safety net (catastrophic backtracking needs a long input; a link-extraction context is normally a sentence or short paragraph). Over the cap, runRegexBounded throws the tagged RegexInputTooLargeError and the regex is skipped (degrade-to-mentions) without entering the node:vm. link-inference.ts:inferLinkTypeFromPack no-budget branch (test contexts) routes through runRegexBounded so the input-length cap + per-regex vm timeout (PER_REGEX_TIMEOUT_MS = 50) apply on every path. Defensive hardening + diagnostics; the deterministic ~3100-file sync-wedge root cause remains open. Pinned by test/redos-hardening.test.ts + test/schema-pack-lint-rules.test.ts.

  • src/core/schema-pack/query-cache-invalidator.ts — invalidateQueryCache(engine, sourceId?) DELETEs query_cache rows so cached search results bound to old page types don't survive a schema mutation.

  • src/core/schema-pack/mutate.ts — 8-step withMutation skeleton (bundled-guard → lock → read → mutator → validate → atomic write → audit → invalidate) backs the 11 single-mutation primitives: addTypeToPack, removeTypeFromPack (with reference check), updateTypeOnPack, addAliasToType, removeAliasFromType, addPrefixToType, removePrefixFromType, addLinkTypeToPack, removeLinkTypeFromPack, setExtractableOnType, setExpertRoutingOnType. Each primitive's business-rule validation + transform is factored into a build*Mutator(...) pure (manifest) => manifest function shared with applyMutationsAtomic (the schema_apply_mutations batch entry point) so single-call and batched mutations can never validate differently. applyMutationsAtomic locks + reads the pack file ONCE, applies + lint-validates every mutation in the batch against an in-memory manifest, and calls writePackManifest at MOST ONCE — only after the whole batch checks out — so a batch that fails partway leaves the pack file byte-identical to its pre-batch state. Atomic single write via .tmp + fsync + rename — the pack file on disk is NEVER partial, for either a single mutation or a batch. Inline minimal JSON→YAML emitter so YAML packs stay YAML (does NOT preserve comments — pin pack.json if you care about layout); double-quoted scalars are JSON-escaped and src/core/schema-pack/loader.ts's parseYamlMini decodes exactly that subset (single quotes are literal with ''), so emit → parse is the identity (#6432). writePackManifest parses its own output and compares it to the manifest as normalized structures (key order free) before the atomic write, refusing EMIT_MISMATCH with the file unchanged; loadPackFromFile refuses PACK_TOO_LARGE from the open descriptor's size before reading (8 MiB, GBRAIN_SCHEMA_PACK_MAX_BYTES), and withMutation / applyMutationsAtomic keep that typed code instead of wrapping it as PACK_CORRUPT. Doctor's schema_pack_active warns on a mutable pack above 1 MiB (GBRAIN_SCHEMA_PACK_WARN_BYTES) with the hand-repair runbook (docs/architecture/schema-packs.md#oversized-pack). Pinned by test/schema-pack-roundtrip.test.ts, the #6432 cases of test/schema-pack-loader.test.ts and test/schema-pack-mutate.test.ts, and test/doctor-schema-pack.test.ts. AddTypeOpts.noPrefix (batch field no_prefix) declares a frontmatter-only type with path_prefixes: [] (#6135); it refuses alongside a prefix, extractable (lint rule extractable_empty_corpus) or expertRouting (lint rule expert_routing_without_prefix), and a missing prefix without it stays INVALID_RESULT.

  • src/core/schema-pack/stats.ts — runStatsCore(engine, opts) returns per-source + aggregate page counts + coverage % + dead_prefixes (declared prefixes with zero matching pages — agent drilldown signal). Multi-source aware (sourceIds[] federated, sourceId single, or whole-brain). PGLite + Postgres parity via executeRaw. undeclared_pages counts pages whose non-empty type the active pack neither declares nor aliases; coverage is the share of pages matching the pack (untyped and undeclared both count against it). Empty brain → coverage:1.0 (vacuous truth).

  • src/core/schema-pack/review.ts — schema review-candidates / review-orphans. findTypeOrphans(engine, manifest, scope, limit) (shared by the CLI and the schema_review_orphans MCP op) returns pages with no active-pack type match (untyped or undeclared, each with type + reason), the true orphan_count, undeclared_types counts and truncated; a query failure throws instead of reading as zero orphans.

  • src/core/schema-pack/sync.ts — runSyncCore(engine, opts) chunked UPDATE in 1000-row batches per declared prefix. Concurrent writers never block on a single row >100ms. Write-side scoping via ctx.sourceId directly (NOT sourceScopeOpts, which inherits OAuth read federation). Idempotent on --apply re-run.

  • src/commands/schema.ts — schema CLI dispatch, including lint [<pack>] [--with-db] [--json]. Lint parses --with-db as a boolean rather than a pack name, accepts it before or after the optional pack, and rejects unknown flags, boolean values, and multiple pack positionals. The DB-backed lane resolves the active pack and runs DB-plane rules on the same connection; plain lint does not run those rules. test/schema-cli-lint-with-db.test.ts drives real isolated CLI subprocesses for implicit/explicit packs, JSON output, missing packs, global source flags, invalid arguments, and plain-lint separation. withConnectedEngine routes loadConfig() through the canonical toEngineConfig() helper and passes the complete result (database_url and database_path) to factory construction and connect, so PGLite schema commands open the configured brain. Lifecycle-grouped help text (Inspection / Activation / Authoring / Discovery+repair). Pinned by test/schema-cli-database-path.serial.test.ts. Help after any subcommand prints usage without running it, and use, downgrade, init and remove-* refuse arguments they would ignore (src/cli/strict-args.ts).

  • src/commands/schema-active.ts — schema active [--source <id>] [--json] (#6090). Resolves through engineSchemaInput(engine, { remote: false, sourceId }), the engine's own tier chain, so the per-source override (schema_pack.source.<id>) is honored and the output names the tier (resolved_from). An unregistered or archived source (fetchSource) refuses with unknown_source (fix gbrain sources list --json); a database that can't be read is a degraded read: stderr marker in text mode (exit 0), a database_error envelope carrying the file-plane answer and degraded: true under --json (nonzero). schema.ts's runActive only parses flags and passes withConnectedEngine. Pinned by test/schema-active-source.test.ts.

  • src/commands/schema-add-type.ts — parseAddTypeArgs for schema add-type (#6135). The type name is the first positional that is not a value-flag's value (--primitive concept archive names archive). A type needs --prefix <dir/> or an explicit --no-prefix; missing both, --prefix with --no-prefix, and --no-prefix with --extractable/--expert each refuse with invalid_params (exit 2) before the pack is touched. Each refusal's fix.argv is one complete corrected command with <NAME>/<PRIMITIVE>/<PREFIX> placeholders described in inputs; NO_PREFIX_NOTE is the success note (note under --json). A switch written with a value (--extractable=true) refuses with invalid_params, except --json=true, which runAddTypeCmd reads as --json (#7619). Pinned by test/schema-add-type-no-prefix.test.ts (core mutator, batch path, CLI subprocess, and every refusal's fix parsing under the same parser). W4.10: schemaPositionals(args, valueFlags) (exported with SCHEMA_PACK_VALUE_FLAGS: --pack, --source, --source-id) gives every other pack-authoring subcommand in schema.ts (remove-type, update-type, add|remove-alias, add|remove-prefix, add|remove-link-type, set-extractable, set-expert-routing, scaffold-extractable) the same rule, with each subcommand's own value flags (--inverse, --page-type, --target-type, --primitive, --dims, ...); pinned by test/schema-positionals-w410.test.ts.

  • skills/schema-author/SKILL.md — Agent dispatcher for "evolve the schema pack." Triggers: 15+ phrasings incl. "add a page type", "my brain has untyped pages", "propose new types from my corpus", "backfill page types". Explicit Non-goals callout to brain-taxonomist (files one page) and eiirp (schema-check during iteration) so agents pick the right surface. 7-phase workflow: brain → assess → propose → apply → sync → verify → commit. Lists every gbrain schema CLI verb + every MCP op the skill uses. brain_first: exempt frontmatter. Required conformance sections: Contract, Anti-Patterns, Output Format.

  • skills/conventions/schema-evolution.md — Canonical convention: "when to add a type vs alias vs prefix." Decision tree: <20 pages → don't pack-codify; 20-100 → alias or narrow prefix on existing type; 100+ → first-class type. Don'ts section + "when to remove a type" + "when to commit the pack" all answered in one place.

Pack-aware wiring is partial. Three follow-ups are filed in TODOS.md: enrichment-service.ts union widening ('person' | 'company' → string), facts/eligibility.ts pack-aware ELIGIBLE_TYPES wiring, and 3 doctor checks (schema_pack_coverage, schema_pack_writability, schema_pack_mutation_audit).

  • src/core/vector-index.ts + src/commands/doctor/checks/embedding-health.ts:embedding_column_registry — shared pgvector HNSW eligibility policy. hnswIndexExpected(columnType, dims) derives the answer from the canonical vector/halfvec dimension caps already used by migration index generation. Doctor reports an HNSW-less active embedding column as a healthy exact-scan configuration when its declared width exceeds the applicable pgvector cap, and only emits the index repair recipe when an index is actually supported. Pinned at both cap boundaries by test/vector-index-lifecycle.test.ts. readExistingEmbeddingShape resolves the same relation as migration DDL and validates its actual type and width. Historical facts/query-cache replay uses that shape instead of extension/config defaults, preserving existing rows, vectors and compatible indexes; malformed existing shapes refuse before migration writes. test/migration-vector-replay.test.ts and its PostgreSQL wrapper pin both engines. withHnswBuildMemory(engine, table, column, build) wraps every PGLite HNSW build (the deferred ANN build in embedding-ann-build.ts, gbrain reindex --vectors): it sets maintenance_work_mem to hnswBuildMemoryMb(rows, vectorBytes) (stored vector plus 640 B per element, +10%, floor 64 MB) so pgvector keeps the whole graph in memory instead of falling back to on-disk inserts, resets it after, and refuses with pglite_vector_index_too_large (fix: the read-only gbrain migrate --to postgres --plan --json) before building when the graph passes PGLITE_HNSW_GRAPH_BUDGET_BYTES (1.5 GiB of pglite.wasm's 2 GiB heap, about 300k 1024-dim chunks). Postgres runs build unchanged. Measured and pinned by test/pglite-hnsw-build.test.ts; ceiling documented in docs/ENGINES.md#pglite-vector-index-ceiling.