From 59d8ebcb2542756ca2f6363c60a15a35558cc1b4 Mon Sep 17 00:00:00 2001
From: David Snelling <david@soulcraft.com>
Date: Fri, 28 Aug 2026 11:56:26 -0700
Subject: [PATCH] feat(open): name the two steps that hold the vfs-bootstrap
 phase
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

MEASURED on a 14,056-noun / 72,679-verb production-shaped store, measured
solo under an exclusive lock: the vfs-bootstrap
phase costs 37.8s on main and 38.0s on this branch — unchanged — and NO
"vfs.init" step line was emitted at all, meaning the VFS's own init fell under
the 2s narration threshold. The phase is therefore almost entirely NOT the VFS,
and the old-root sweep this branch moved to the background was never what made
it expensive.

What else lives in that span is now named: the log-authority artifact read, the
adoption ORACLE (which verifies the log against canonical before flipping a
brain to durable-at-ack), the legacy pending-embed sidecar bridge, and the
pending-embed recovery fold. One of those holds ~38 seconds of every open of
this store and the next measurement will say which, by name, instead of leaving
a phase label to be guessed at.
---
 src/brainy.ts | 25 +++++++++++++++++++++----
 1 file changed, 21 insertions(+), 4 deletions(-)

diff --git a/src/brainy.ts b/src/brainy.ts
index 3426dcce..70d46973 100644
--- a/src/brainy.ts
+++ b/src/brainy.ts
@@ -1760,7 +1760,11 @@ export class Brainy<T = any> implements BrainyInterface<T> {
         const storedArtifact = await this.storage
           .readRawObject(LOG_AUTHORITY_PATH)
           .catch(() => null)
-        const authority = await readLogAuthority(this.storage)
+        const authority = await step(
+          'read-log-authority',
+          'reading the stored storage-authority artifact',
+          () => readLogAuthority(this.storage)
+        )
         this._logAuthority = authority
         if (authority.authority === 'log') {
           this.generationStore.setLogDurability('at-ack')
@@ -1771,7 +1775,12 @@ export class Brainy<T = any> implements BrainyInterface<T> {
           this.generationStore.getFactLog() !== null
         ) {
           try {
-            await this.adoptLogAuthority()
+            await step(
+              'adopt-log-authority',
+              'the adoption oracle: verifying the log against canonical before flipping this ' +
+                'brain to durable-at-ack, and backfilling any curable divergence',
+              () => this.adoptLogAuthority()
+            )
             prodLog.info(
               '[Brainy] storage authority adopted at open: generation log ' +
                 '(fleet default; oracle green; durable-at-ack enabled)'
@@ -1811,8 +1820,16 @@ export class Brainy<T = any> implements BrainyInterface<T> {
       // this is where it lands.
       if (!this.isReadOnly) {
         try {
-          await this.bridgeLegacyPendingEmbedSidecars()
-          await this.recoverPendingEmbedsFromLog()
+          await step(
+            'bridge-pending-embed-sidecars',
+            'migrating any pre-log deferred-embed marker files into the generation log',
+            () => this.bridgeLegacyPendingEmbedSidecars()
+          )
+          await step(
+            'recover-pending-embeds',
+            'folding the generation log\'s deferred-embed markers back into the pending set',
+            () => this.recoverPendingEmbedsFromLog()
+          )
           if (this._pendingEmbedIds.size > 0) {
             prodLog.info(
               `[Brainy] ${this._pendingEmbedIds.size} deferred embed(s) pending from a previous ` +