Relationships
#4671 Datastore fails to open on fresh checkout: early vault service never auto-resolves the datastore-auth vault's extension type
Opened by kneel · 11/12/2026· Shipped 11/12/2026
Datastore fails to open on a fresh checkout when the datastore-auth vault uses an extension vault type (early vault service never auto-resolves the vault type)
Summary
When a repository's datastore config reads its credential from a vault
(vault.get(<vault>, <key>)) and that vault's type is provided by an
extension (e.g. an @scope/pass type) rather than a built-in type
(local_encryption), a fresh checkout/worktree/clone cannot open the datastore.
The early (pre-datastore) vault service that resolves the datastore config only
registers vaults whose type bundle is already cached under
.swamp/vault-bundles/. Unlike the canonical vault loader, it never
auto-resolves a missing vault-type extension. The datastore type itself is
auto-resolved, so it installs fine -- but the vault type needed to read the
datastore's own credential is skipped, the auth vault fails to register, and the
datastore never opens.
Environment
- swamp
20261111.234122.0-sha.cd35f58c(also reproduced on...001635...). - Linux x86_64 (not platform-specific; the trigger is the empty
.swamp/). - Datastore: an extension datastore type whose config reads its credential via
vault.get(<authVault>, <key>), where<authVault>'s type is an extension vault type.datastore.managedConfigis unset/false (see note below). .swamp/is gitignored, sogit worktree add/ a fresh clone starts with an empty.swamp/and no cached vault-type bundles.
Reproduction
A repo whose
.swamp.yamldatastore block reads its credential from an extension-typed vault:datastore: type: "@example/blob-datastore" config: auth: connectionString: "${{ vault.get(dsauth, CONNECTION_STRING) }}"
with the auth vault definition tracked in the repo's
vaults/dir, e.g.vaults/@example/pass/<uuid>.yaml:name: dsauth type: "@example/pass" config: { prefix: "example/dsauth" }
(
@example/passis an extension vault type; its bundle is NOT a built-in.)git worktree add ../wt -b wt main-- fresh, empty.swamp/(so.swamp/vault-bundles/does not exist).In the worktree, run any datastore-backed command, e.g.
swamp data query '<predicate>' --json.
Expected
The datastore opens: swamp auto-resolves dsauth's vault-type extension
(subject to trustedCollectives), exactly as it already auto-resolves the
datastore type, and exactly as the canonical vault loader already does.
Actual
The datastore cannot open. With only the extension-typed dsauth present, zero
vaults register, so the surfaced error is the empty-set branch:
Failed to resolve vault expression in datastore config: Vault 'dsauth' not found. No vaults are configured.(If the repo also has built-in local_encryption vaults, those DO register and
the message instead lists them: Vault 'dsauth' not found. Available vaults: <the local_encryption vaults only> -- every extension-typed vault is still
absent.)
The true cause is emitted separately, one log line earlier, at warn:
Vault 'dsauth' not available for datastore config expressions: Unsupported vault type: '@example/pass' (vault 'dsauth'). Available vault types: <...>So the fatal error says "not found" (pointing at a missing vault definition,
which is wrong -- the def is present and git-tracked), while the real cause
("unsupported/uninstalled vault type") is only in a non-fatal warn line, and
neither message tells the user to swamp extension pull <type>.
Root cause
src/cli/datastore_expression_resolver.ts:
createEarlyVaultService(repoDir)builds the vault service used to resolve the datastore config'svault.get(...)before the datastore exists. It callsloadCachedVaultBundles(repoDir)(~lines 48-94), which only imports vault-type bundles already present under.swamp/vault-bundles/. There is no auto-resolution of a missing vault-type extension.- It then reads each vault def from the git-tracked
vaults/dir and callsregisterVault(...)per def (~lines 116-132). For a def whosetypeis an uncached extension type,createVaultProviderhits its default branch and throwsUnsupported vault type: '<type>' (vault '<name>').(src/domain/vaults/vault_provider_factory.ts:73). The loop catches it and skips that vault, logging at warn (datastore_expression_resolver.ts:128-131). - Net: every extension-typed vault is dropped whenever its bundle isn't already
cached. The datastore-auth vault is dropped on a fresh checkout, so
service.get(<authVault>, ...)throws one of the "not found" branches (src/domain/vaults/vault_service.ts:323empty /:334non-empty).
This is a stripped reimplementation of the canonical loader. The normal path,
VaultService.fromRepository (src/domain/vaults/vault_service.ts:169-174),
does exactly the missing step:
await vaultTypeRegistry.ensureTypeLoaded(vaultType);
if (!vaultTypeRegistry.has(vaultType) && vaultType.startsWith("@")) {
await resolveVaultType(vaultType, getAutoResolver());
}createEarlyVaultService omits that resolveVaultType(...) call, so the early
(datastore-bootstrap) path can't install a vault type the normal path would.
The asymmetry is also visible against the datastore type: resolve_datastore.ts
auto-resolves the datastore type via
resolveDatastoreType(dsType, autoResolver) (~lines 446-447), but nothing
performs the equivalent for the vault type the datastore's own credential
depends on.
Because .swamp/vault-bundles/ is gitignored and per-checkout, this bites every
fresh clone/worktree, not just a first-ever setup.
Impact
- Any repo whose datastore-auth vault uses an extension vault type cannot
bootstrap a fresh clone or
git worktree-- the datastore simply won't open. - Misleading: the fatal error says "Vault not found" (implying a missing def)
while the def is present and tracked; the real cause (uninstalled vault type)
is only in a separate warn line and never suggests
swamp extension pull.
Suggested fix
In createEarlyVaultService (datastore_expression_resolver.ts), mirror
VaultService.fromRepository: after ensureTypeLoaded, if a vault def's type
is an uncached @-extension type, call
resolveVaultType(type, getAutoResolver()) (honoring trustedCollectives) --
the primitive already exists at
src/domain/extensions/extension_auto_resolver.ts:711-721 and honors
allowedCollectives, exactly like resolveDatastoreType. At minimum, resolve
the vault type(s) referenced by the datastore config's vault.get(...)
expressions before/while building the early vault service. No new trust surface:
the datastore extension is already installed and executed at this stage.
Implementation caveat: auto-resolution emits progress JSON to stdout, which can
corrupt --json output (see the note at resolve_datastore.ts:441-443, which
calls ensureLoaded() first to avoid exactly this). Any vault auto-resolve added
to the early path must route that progress output the same way.
Secondary (cheap, independent): make the surfaced error distinguish "vault def
not found" from "vault type bundle not installed (run
swamp extension pull <type>)", so the fatal message names the real cause
instead of only the warn line.
Workaround
In the affected checkout, pre-cache the bundles:
swamp extension pull <datastore-type-extension>
swamp extension pull <auth-vault-type-extension>This caches both bundles under .swamp/, after which the datastore opens
normally. No datastore write and no vault re-creation is involved -- the vault
defs are already tracked in vaults/. (Explicit pull does not require the
collective to be trusted; trust only gates auto-resolve.)
Note: managedConfig
This bug applies only when datastore.managedConfig is unset/false. If it is
truthy, vault.get(...) in datastore config is refused outright
(datastore_expression_resolver.ts:145-153) with a message directing you to env
vars, so the early vault service is never built.
Shipped
Click a lifecycle step above to view its details.
zack commented 11/12/2026, 2:25:07 PM
Thanks @kneel for reporting this! We shipped: Make the datastore bootstrap vault service work on a fresh checkout when the datastore-auth vault uses an extension vault type: install the Zod global before importing cached vault bundles, auto-resolve the missing extension type of the vault named in a vault.get (lazily, honouring trustedCollectives and installed-only callers, never touching the vault registry loader), and replace the misleading Vault not found error with one naming the uninstalled type and the swamp extension pull command.. The fix has been merged and a release is on its way. We appreciate your contribution to swamp.
Sign in to post a ripple.