@enbox/api 0.6.24 → 0.6.25

package/src/enbox.ts

@@ -4,15 +4,24 @@
  */
 /// <reference types="@enbox/dwn-sdk-js" />
 
-import type { AuthSession } from '@enbox/auth';
-import type { DidMethodResolver } from '@enbox/dids';
-import type { EnboxAgent } from '@enbox/agent';
+import type { EnboxPlatformAgent } from '@enbox/agent';
 import type { ProtocolDefinition } from '@enbox/dwn-sdk-js';
+import type { AuthManagerOptions, ConnectOptions, HandlerConnectOptions, LocalConnectOptions } from '@enbox/auth';
 
+import type {
+  EnboxAnonymousApi,
+  EnboxAnonymousOptions,
+  EnboxConnectOptions,
+  EnboxConnectResult,
+  EnboxParams,
+  EnboxSessionParams,
+} from './enbox-types.js';
 import type { SchemaMap, TypedProtocol } from './protocol-types.js';
 
 import { AnonymousDwnApi } from '@enbox/agent';
+import { AuthManager } from '@enbox/auth/auth-manager';
 import { EnboxRpcClient } from '@enbox/dwn-clients';
+import { omitUndefined } from '@enbox/common';
 import { DidDht, DidJwk, DidKey, DidResolverCacheMemory, DidWeb, UniversalResolver } from '@enbox/dids';
 
 import { DidApi } from './did-api.js';
@@ -22,74 +31,51 @@ import { TypedEnbox } from './typed-enbox.js';
 import { VcApi } from './vc-api.js';
 
 /**
- * Options for creating an anonymous (read-only) Enbox instance via {@link Enbox.anonymous}.
+ * Module-level registry of in-flight {@link Enbox.connect} calls, keyed by
+ * the resolved data path (or a sentinel for "default path").
  *
- * @beta
+ * `AuthManager.create()` opens LevelDB handles at the agent's `dataPath`;
+ * LevelDB enforces an exclusive lock per directory, so two parallel
+ * `Enbox.connect()` invocations on the same path would race on the lock
+ * and surface a cryptic `LEVEL_LOCKED` error to the caller. The registry
+ * detects the race at the API boundary and throws a clear, domain-level
+ * error instead. Custom `storage` adapters that don't share a path with
+ * the agent's vault can still race below this guard — but for the default
+ * path that every dapp uses, this catches the common case.
  */
-export type EnboxAnonymousOptions = {
-  /** Override the default DID method resolvers. Defaults to `[DidDht, DidJwk, DidKey, DidWeb]`. */
-  didResolvers?: DidMethodResolver[];
-};
-
-/**
- * The result of calling {@link Enbox.anonymous}.
- *
- * Contains only a read-only `dwn` property — no `did`, `vc`, or `agent`.
- *
- * @beta
- */
-export type EnboxAnonymousApi = {
-  /** A read-only DWN API for querying public data on remote DWNs. */
-  dwn: DwnReaderApi;
-};
-
-/**
- * Parameters for constructing an {@link Enbox} instance.
- *
- * These are the minimal primitives needed to interact with the DWN network.
- * Typically obtained from an {@link AuthSession} via `@enbox/auth`.
- */
-export type EnboxParams = {
-  /**
-   * A {@link EnboxAgent} instance that handles DIDs, DWNs and VCs requests. The agent manages the
-   * user keys and identities, and is responsible to sign and verify messages.
-   */
-  agent: EnboxAgent;
-
-  /** The DID of the tenant under which all DID, DWN, and VC requests are being performed. */
-  connectedDid: string;
-
-  /** The DID that will be signing messages using grants from the connectedDid. */
-  delegateDid?: string;
-};
+const DEFAULT_DATA_PATH_KEY = '\x00default\x00';
+const inflightConnects = new Map<string, Promise<unknown>>();
 
 /**
  * The main Enbox API interface. It provides protocol-scoped access to
  * Decentralized Web Nodes (DWNs), Decentralized Identifiers (DIDs),
  * and Verifiable Credentials (VCs).
  *
- * Authentication and identity management are handled externally by
- * `@enbox/auth`. Use {@link Enbox.connect} to create an instance from
- * an {@link AuthSession} or raw parameters.
+ * For common app flows, use the asynchronous {@link Enbox.connect} helper.
+ * For custom auth/session flows, use {@link Enbox.fromSession} with an
+ * existing session, or the public constructor with raw `{ agent, connectedDid }`.
  *
  * @example
  * ```ts
- * import { AuthManager } from '@enbox/auth';
  * import { Enbox } from '@enbox/api';
  *
- * const auth = await AuthManager.create({ sync: '15s' });
- * const session = await auth.connect();
+ * const { enbox } = await Enbox.connect({
+ *   createIdentity: true,
+ *   sync: '15s',
+ * });
  *
- * const enbox = Enbox.connect({ session });
  * const social = enbox.using(SocialProtocol);
  * ```
  */
 export class Enbox {
   /**
-   * A {@link EnboxAgent} instance that handles DIDs, DWNs and VCs requests. The agent manages the
-   * user keys and identities, and is responsible to sign and verify messages.
+   * The {@link EnboxPlatformAgent} this instance is bound to. The platform
+   * agent handles DIDs, DWN access, signing keys, and DWN sync — every
+   * Enbox session needs all of those, so the type is narrower than the
+   * minimal {@link EnboxAgent} interface and the constructor refuses
+   * non-platform agents at compile time.
    */
-  public agent: EnboxAgent;
+  public agent: EnboxPlatformAgent;
 
   /** Exposed instance to the DID APIs, allow users to create and resolve DIDs. */
   public did: DidApi;
@@ -109,6 +95,22 @@ export class Enbox {
   /** Exposed instance to the VC APIs, allow users to issue, present and verify VCs. */
   public vc: VcApi;
 
+  /**
+   * The `AuthManager` this instance owns and is responsible for tearing down
+   * during {@link Enbox.disconnect}. Set only by the async
+   * {@link Enbox.connect} factory; never populated by the public constructor
+   * or {@link Enbox.fromSession}.
+   */
+  private _ownedAuth?: AuthManager;
+
+  /**
+   * Memoized teardown promise. Two parallel `enbox.disconnect()` calls
+   * share the same promise so `agent.sync.stopSync()` (and the optional
+   * `auth.shutdown()`) run exactly once even when callers fire the
+   * teardown from independent code paths.
+   */
+  private _disconnecting?: Promise<void>;
+
   constructor({ agent, connectedDid, delegateDid }: EnboxParams) {
     this.agent = agent;
     this.did = new DidApi({ agent, connectedDid });
@@ -162,30 +164,105 @@ export class Enbox {
   }
 
   /**
-   * Stops DWN sync and clears the cached {@link TypedEnbox} instances.
+   * Signs the user out and releases resources held by this Enbox instance.
+   *
+   * When this instance owns the underlying `AuthManager` (i.e. it was
+   * created via `Enbox.connect()` with no caller-supplied `agent`), the
+   * disconnect proceeds in three phases:
    *
-   * Call this when the application is shutting down or the user is
-   * disconnecting to cleanly release background resources. After calling
-   * `disconnect()`, the `Enbox` instance should not be reused.
+   *   1. **Stop sync** — `agent.sync.stopSync(timeout)` halts the DWN
+   *      sync engine. Always runs, regardless of ownership.
+   *   2. **Sign out** — `AuthManager.disconnect()` sends delegate-grant
+   *      revocations to the connected DWN endpoints, clears session
+   *      restore markers (PREVIOUSLY_CONNECTED, ACTIVE_IDENTITY,
+   *      delegate keys, etc.) from the StorageAdapter, and clears the
+   *      in-memory delegate decryption key cache. **Without this step
+   *      a later `Enbox.connect()` would silently restore the
+   *      supposedly signed-out session from the persisted markers.**
+   *   3. **Release resources** — `AuthManager.shutdown()` locks the
+   *      vault, closes the sync engine, and closes the StorageAdapter.
+   *
+   * When the instance was created from a caller-owned session
+   * ({@link Enbox.fromSession}), a raw agent (the public constructor),
+   * or `Enbox.connect({ agent })`, only step 1 (stop sync) runs — the
+   * caller's AuthManager / agent keep their lifecycle. The caller is
+   * responsible for calling `auth.disconnect()` and `auth.shutdown()`
+   * on their own handle when they're done.
+   *
+   * Idempotent: parallel calls share the same teardown promise. After
+   * calling `disconnect()`, the `Enbox` instance should not be reused.
    *
    * @param timeout - Maximum milliseconds to wait for an in-progress sync
    *   cycle to finish before force-stopping. Defaults to `2000`.
    *
    * @example
    * ```ts
-   * await enbox.disconnect();
+   * // High-level flow: a single disconnect() does sign-out + teardown.
+   * const { enbox } = await Enbox.connect({ createIdentity: true });
+   * // ... user uses the app ...
+   * await enbox.disconnect();   // revoke grants, clear markers, close vault
+   *
+   * // Caller-owned auth: enbox.disconnect() only stops Enbox-side state.
+   * const auth = await AuthManager.create({...});
+   * const session = await auth.connect();
+   * const enbox = Enbox.fromSession(session);
+   * await enbox.disconnect();   // stops sync + clears typed-enbox cache
+   * await auth.disconnect();    // sign-out: caller's responsibility
+   * await auth.shutdown();      // close resources: caller's responsibility
    * ```
    *
    * @beta
    */
   public async disconnect(timeout?: number): Promise<void> {
-    // Stop any active sync.
-    if ('sync' in this.agent && typeof (this.agent as any).sync?.stopSync === 'function') {
-      await (this.agent as any).sync.stopSync(timeout);
+    // Memoize so parallel calls share the same teardown promise. Without
+    // this, two concurrent disconnect()s would each invoke
+    // agent.sync.stopSync (idempotent, but redundant) and could race on
+    // _ownedAuth ownership transfer.
+    if (this._disconnecting !== undefined) {
+      return this._disconnecting;
     }
+    this._disconnecting = this._doDisconnect(timeout);
+    return this._disconnecting;
+  }
+
+  private async _doDisconnect(timeout?: number): Promise<void> {
+    await this.agent.sync.stopSync(timeout);
 
     // Clear cached TypedEnbox instances so they are not accidentally reused.
     this._typedInstances.clear();
+
+    // If this Enbox owns the AuthManager (created via Enbox.connect), the
+    // sign-out + resource-teardown both fall on us:
+    //
+    //   1. `auth.disconnect()` — sign-out semantics: revoke delegate
+    //      grants on the remote DWN, clear session restore markers
+    //      (PREVIOUSLY_CONNECTED, ACTIVE_IDENTITY, delegate keys, etc.)
+    //      from the StorageAdapter, and clear the in-memory delegate
+    //      decryption key cache. MUST run while the agent's resources
+    //      are still open (revocations need DWN access). Without this,
+    //      a later `Enbox.connect()` would restore the supposedly
+    //      signed-out session from the persisted markers.
+    //   2. `auth.shutdown()` — resource teardown: lock the vault,
+    //      close the sync engine, close the storage adapter. Runs
+    //      after disconnect so revocation traffic completes first.
+    //
+    // Both are idempotent and best-effort; failures are logged but do
+    // not propagate. We always attempt shutdown() even if disconnect()
+    // throws, so resources still close.
+    if (this._ownedAuth !== undefined) {
+      const owned = this._ownedAuth;
+      this._ownedAuth = undefined;
+      try {
+        await owned.disconnect({ timeout });
+      } catch (error: unknown) {
+        console.warn('[@enbox/api] Enbox.disconnect: AuthManager.disconnect() failed', error);
+      }
+      try {
+        await owned.shutdown({ timeout });
+      } catch (error: unknown) {
+        console.warn('[@enbox/api] Enbox.disconnect: AuthManager.shutdown() failed', error);
+      }
+    }
   }
 
   /**
@@ -229,37 +306,217 @@ export class Enbox {
   }
 
   /**
-   * Creates an {@link Enbox} instance from an {@link AuthSession} or raw parameters.
+   * Creates an {@link Enbox} instance from a session-shaped object.
    *
-   * This is a thin factory — all authentication, identity management, vault
-   * initialization, DWN registration, and sync setup are handled externally
-   * by `@enbox/auth` via {@link AuthSession}.
+   * Accepts `AuthSession`, `AgentSession`, or any compatible custom session
+   * with `{ agent, did, delegateDid? }`. This is the right entry point
+   * whenever you already hold an active session — including ones produced by
+   * a caller-managed `AuthManager`.
    *
-   * @param params - Either `{ session }` with an {@link AuthSession} from
-   *   `@enbox/auth`, or raw `{ agent, connectedDid, delegateDid? }` parameters.
-   * @returns A new {@link Enbox} instance ready for use.
+   * For raw `{ agent, connectedDid }` access (no session shape), use the
+   * public constructor directly: `new Enbox({ agent, connectedDid })`.
+   */
+  public static fromSession(session: EnboxSessionParams): Enbox {
+    return new Enbox({
+      agent        : session.agent,
+      connectedDid : session.did,
+      delegateDid  : session.delegateDid,
+    });
+  }
+
+  /**
+   * High-level entry point that creates an {@link AuthManager}, runs
+   * `auth.connect()`, and returns the resulting `{ auth, session, enbox }`.
+   *
+   * For callers that already own an agent and DID, use the dedicated
+   * synchronous entry points instead:
+   * - `new Enbox({ agent, connectedDid })` for raw parameters
+   * - {@link Enbox.fromSession} for session-shaped objects
+   *
+   * Routing happens at runtime inside `AuthManager._isLocalConnect`:
+   * presence of a non-empty `protocols` array or a `connectHandler` selects
+   * the handler flow; everything else routes to local. Local-style fields
+   * (`password`, `dwnEndpoints`, etc.) are forwarded to both the manager
+   * (as defaults) and the per-call payload, so behavior is consistent with
+   * restored sessions.
+   *
+   * If you need exact control of the `AuthManager.connect()` payload,
+   * drop down one layer: create the `AuthManager` yourself with
+   * `AuthManager.create()`, call `auth.connect(...)` with your exact
+   * options, and pass the resulting session to `Enbox.fromSession`.
    *
    * @example
    * ```ts
-   * // Using an AuthSession from @enbox/auth
-   * import { AuthManager } from '@enbox/auth';
-   * const auth = await AuthManager.create({ sync: '15s' });
-   * const session = await auth.connect();
-   * const enbox = Enbox.connect({ session });
-   *
-   * // Using raw parameters
-   * const enbox = Enbox.connect({ agent, connectedDid: did });
+   * const { enbox, session, auth } = await Enbox.connect({ createIdentity: true });
+   * // ...
+   * await enbox.disconnect();
+   * await auth.shutdown(); // release vault + storage handles
    * ```
    */
-  public static connect(params: { session: AuthSession } | EnboxParams): Enbox {
-    if ('session' in params) {
-      const { session } = params;
-      return new Enbox({
-        agent        : session.agent,
-        connectedDid : session.did,
-        delegateDid  : session.delegateDid,
-      });
+  public static async connect(options: EnboxConnectOptions = {}): Promise<EnboxConnectResult> {
+    // Cross-instance concurrency guard. `AuthManager.create()` opens the
+    // agent's LevelDB at `options.dataPath` (or the platform default), and
+    // LevelDB enforces an exclusive `LOCK` file per directory — two
+    // parallel calls on the same path would otherwise race and surface
+    // `LEVEL_LOCKED` as a low-level error. The guard / ownership flag
+    // tracks one question only: did we build the underlying agent? If
+    // `options.agent` is supplied the caller owns the agent's lifecycle
+    // and on-disk handles, so we skip both the guard (no new dataPath
+    // race) and ownership cleanup (`disconnect()` must not tear down
+    // the caller's agent). A custom `storage` adapter alone is NOT a
+    // basis for skipping — Enbox still builds an agent that opens
+    // LevelDB handles at `dataPath`, and the storage adapter governs
+    // session-persistence keys, not the agent vault.
+    //
+    // Limitation: the key is the raw `options.dataPath` string, not its
+    // resolved on-disk location. Two callers — one with `dataPath`
+    // omitted and another passing the explicit platform default
+    // ('DATA/AGENT' in browser, '~/.enbox' in CLI) — refer to the same
+    // directory but produce different keys, so the guard won't catch
+    // that race. Resolving the path here would require pulling in the
+    // platform-default logic from `@enbox/agent`, which we deliberately
+    // avoid to keep the helper layered above the agent. Pick one
+    // convention per app: always omit `dataPath`, or always set it
+    // explicitly.
+    const shouldGuard = options.agent === undefined;
+    const key = options.dataPath ?? DEFAULT_DATA_PATH_KEY;
+
+    if (shouldGuard && inflightConnects.has(key)) {
+      throw new Error(
+        `[@enbox/api] Enbox.connect() is already in progress for dataPath '${
+          options.dataPath ?? '<default>'
+        }'. Await the in-flight call before starting another, or pass a custom dataPath.`
+      );
+    }
+
+    const run = async (): Promise<EnboxConnectResult> => {
+      const auth = await AuthManager.create(Enbox.toAuthManagerOptions(options));
+
+      try {
+        const session = await auth.connect(Enbox.toAuthConnectOptions(options));
+        const enbox = Enbox.fromSession(session);
+        // Take AuthManager ownership ONLY when we built the agent
+        // ourselves — `auth.shutdown()` will lock that agent's vault
+        // and close its sync engine. If the caller supplied
+        // `options.agent`, they retain agent ownership and must not
+        // have its lifecycle resources torn down by
+        // `enbox.disconnect()`. Callers that want explicit control
+        // (e.g. their own storage adapter without their own agent)
+        // can still grab the `auth` handle from the result and call
+        // `auth.shutdown()` themselves; we always include it in the
+        // returned `EnboxConnectResult`.
+        if (shouldGuard) {
+          enbox._ownedAuth = auth;
+        }
+
+        return { auth, enbox, session };
+      } catch (error: unknown) {
+        try {
+          await auth.shutdown();
+        } catch (shutdownError: unknown) {
+          // Surface the recovery failure for diagnosis but preserve the
+          // original connect rejection on the rethrow path below.
+          console.warn(
+            '[@enbox/api] Enbox.connect: auth.shutdown() failed during error recovery',
+            shutdownError,
+          );
+        }
+        throw error;
+      }
+    };
+
+    if (!shouldGuard) {
+      return run();
     }
-    return new Enbox(params);
+
+    const promise = run();
+    inflightConnects.set(key, promise);
+    try {
+      return await promise;
+    } finally {
+      inflightConnects.delete(key);
+    }
+  }
+
+  /**
+   * Split `EnboxConnectOptions` into the manager-wide defaults that
+   * `AuthManager.create()` consumes.
+   *
+   * Implemented as an **explicit allowlist** for the same reason as
+   * `toAuthConnectOptions`: a denylist would silently leak future
+   * `HandlerConnectOptions` / `LocalConnectOptions` fields into the
+   * manager-default record. The `satisfies Partial<AuthManagerOptions>`
+   * annotation makes the compiler verify every key in the allowlist
+   * exists on `AuthManagerOptions`, so a misspelled or stale field name
+   * is a type error.
+   */
+  private static toAuthManagerOptions(options: EnboxConnectOptions): AuthManagerOptions {
+    // Explicit allowlist — every key must exist on `AuthManagerOptions`
+    // (verified by `satisfies` below).
+    const allowlisted = {
+      agent            : options.agent,
+      agentVault       : options.agentVault,
+      localDwnStrategy : options.localDwnStrategy,
+      dataPath         : options.dataPath,
+      storage          : options.storage,
+      password         : options.password,
+      passwordProvider : options.passwordProvider,
+      sync             : options.sync,
+      dwnEndpoints     : options.dwnEndpoints,
+      registration     : options.registration,
+      connectHandler   : options.connectHandler,
+    } satisfies Partial<AuthManagerOptions>;
+    return omitUndefined(allowlisted);
+  }
+
+  /**
+   * Split `EnboxConnectOptions` into the per-call payload that
+   * `AuthManager.connect()` consumes.
+   *
+   * Implemented as an **explicit allowlist** of the fields declared on
+   * {@link HandlerConnectOptions} ∪ {@link LocalConnectOptions}. A
+   * denylist (strip manager-only fields, forward the rest) would
+   * silently leak any future `AuthManagerOptions` field into
+   * `AuthManager.connect()`; the allowlist makes the type boundary
+   * explicit and the leak impossible. The trade-off is symmetric:
+   * any new connect-options field requires an edit here. That's
+   * acceptable — it's the same edit the public `ConnectOptions` type
+   * already needs, just on one extra line.
+   *
+   * The `satisfies Partial<ConnectOptions>` annotation makes the
+   * compiler verify every key in the allowlist exists on `ConnectOptions`,
+   * so misspelling a field name is a type error rather than a silent
+   * drop. Routing between local and handler flow happens inside
+   * `AuthManager._isLocalConnect` based on the presence of `protocols`
+   * / `connectHandler`.
+   *
+   * `protocols: []` is normalized away — an empty array carries no
+   * permission intent and would otherwise produce a zero-grant
+   * "connected" handler session indistinguishable from a denied connect.
+   */
+  private static toAuthConnectOptions(options: EnboxConnectOptions): ConnectOptions | undefined {
+    // Explicit allowlist — every key must exist on the
+    // `ConnectOptions` union (verified by `satisfies` below).
+    const allowlisted = {
+      // Shared across handler + local
+      password       : options.password,
+      sync           : options.sync,
+      dwnEndpoints   : options.dwnEndpoints,
+      // Handler-only
+      protocols      : options.protocols,
+      connectHandler : options.connectHandler,
+      // Local-only
+      recoveryPhrase : options.recoveryPhrase,
+      createIdentity : options.createIdentity,
+      metadata       : options.metadata,
+    } satisfies Partial<HandlerConnectOptions & LocalConnectOptions>;
+
+    // Normalize `protocols: []` to undefined so omitUndefined strips it.
+    const normalized = (Array.isArray(allowlisted.protocols) && allowlisted.protocols.length === 0)
+      ? { ...allowlisted, protocols: undefined }
+      : allowlisted;
+
+    const cleaned = omitUndefined(normalized);
+    return Object.keys(cleaned).length === 0 ? undefined : cleaned;
   }
 }

package/src/index.ts

@@ -4,16 +4,18 @@
  * The SDK provides protocol-scoped access to DWN records with compile-time
  * type safety, DID management, and Verifiable Credential operations.
  *
- * Authentication and identity management are handled by `@enbox/auth`.
+ * Common authentication and identity setup is available through
+ * `Enbox.connect()`. Advanced session management can use `@enbox/auth` or
+ * `@enbox/agent` directly.
  *
  * @example
  * ```ts
- * import { AuthManager } from '@enbox/auth';
  * import { Enbox } from '@enbox/api';
  *
- * const auth = await AuthManager.create({ sync: '15s' });
- * const session = await auth.connect();
- * const enbox = Enbox.connect({ session });
+ * const { enbox } = await Enbox.connect({
+ *   createIdentity: true,
+ *   sync: '15s',
+ * });
  * ```
  *
  * [Link to GitHub Repo](https://github.com/enboxorg/enbox)
@@ -25,6 +27,7 @@ export * from './define-protocol.js';
 export * from './did-api.js';
 export * from './dwn-reader-api.js';
 export * from './enbox.js';
+export type * from './enbox-types.js';
 export * from './grant-revocation.js';
 export * from './live-query.js';
 export * from './permission-grant.js';

package/src/read-only-record.ts

@@ -217,7 +217,7 @@ export class ReadOnlyRecord {
       },
 
       async json<T = unknown>(): Promise<T> {
-        return await Stream.consumeToJson({ readableStream: await this.stream() }) as T;
+        return await Stream.consumeToJson<T>({ readableStream: await this.stream() });
       },
 
       async text(): Promise<string> {

package/src/repository.ts

@@ -24,6 +24,25 @@
  * const members = await social.group.member.query(groupContextId);
  * ```
  *
+ * ## Deliberate `as never` pattern
+ *
+ * The CRUD methods below pass their `options: Record<string, unknown>`
+ * parameter to `typed.records.{create, query, subscribe, update}` with
+ * `as never`. This is the type-system bridge between the type-erased
+ * Proxy (which doesn't carry the per-protocol generic) and the strictly-
+ * typed record methods (which take `TypedRecordCreateParams<...>` etc.).
+ *
+ * `never` is the universal bottom subtype, so any strict generic is
+ * satisfied. The structural runtime shape of `options` is validated by
+ * the DWN SDK's grant-processing layer downstream — the cast is a
+ * narrow, intentional escape hatch at the proxy boundary.
+ *
+ * SonarCloud's `typescript:S4325` flags these casts as redundant
+ * because its rule doesn't model generic-parameter constraints. We
+ * suppress S4325 at the file level (see `sonar-project.properties`)
+ * because every CRUD method uses the same pattern and per-line
+ * `// NOSONAR` would dwarf the actual code.
+ *
  * @module
  */
 
@@ -51,10 +70,12 @@ function isRecordLimitExceeded(status: { code: number; detail: string }): boolea
  * (has `$recordLimit: { max: 1 }`).
  */
 function isSingletonPath(definition: ProtocolDefinition, path: string): boolean {
-  const segments = path.split('/');
-  let node: ProtocolRuleSet | undefined = definition.structure as unknown as ProtocolRuleSet;
+  const [first, ...rest] = path.split('/');
+  // Top-level lookup uses the declared `{ [key: string]: ProtocolRuleSet }`
+  // index signature directly — no top-level cast needed.
+  let node: ProtocolRuleSet | undefined = definition.structure[first];
 
-  for (const seg of segments) {
+  for (const seg of rest) {
     if (!node || typeof node !== 'object') { return false; }
     node = (node as Record<string, ProtocolRuleSet>)[seg];
   }
@@ -72,8 +93,13 @@ function isSingletonPath(definition: ProtocolDefinition, path: string): boolean
  * reached by the given path.
  */
 function getChildKeys(definition: ProtocolDefinition, path: string): string[] {
+  // Top-level: walk into the structure's declared index-signature value.
+  // The structure is `{ [key: string]: ProtocolRuleSet }`; navigating
+  // beneath the first segment uses `ProtocolRuleSet`'s own index
+  // signature, which contains both rule-set children and `$`-prefixed
+  // metadata — we filter out the metadata at the leaf below.
   const segments = path.split('/');
-  let node: Record<string, unknown> = definition.structure as unknown as Record<string, unknown>;
+  let node: Record<string, unknown> = definition.structure;
 
   for (const seg of segments) {
     if (!node || typeof node !== 'object') { return []; }