@the-40-thieves/obsidian-tc-shared 1.13.0 → 1.14.0

package/dist/config/auth-acl.schema.d.ts

@@ -0,0 +1,36 @@
+import { z } from "zod";
+export declare const AuthConfigSchema: z.ZodObject<{
+    mode: z.ZodDefault<z.ZodEnum<{
+        jwt: "jwt";
+        none: "none";
+    }>>;
+    jwtSecret: z.ZodOptional<z.ZodString>;
+    tokenTtlSeconds: z.ZodDefault<z.ZodNumber>;
+    jwks: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    jwksFile: z.ZodOptional<z.ZodString>;
+    jwksUri: z.ZodOptional<z.ZodString>;
+    algorithms: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    audience: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+    issuer: z.ZodOptional<z.ZodString>;
+    resource: z.ZodOptional<z.ZodString>;
+    authorizationServers: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    resourceName: z.ZodOptional<z.ZodString>;
+    scopesSupported: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export declare const AclRuleSchema: z.ZodObject<{
+    glob: z.ZodString;
+    scopes: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export declare const AclConfigSchema: z.ZodObject<{
+    readOnly: z.ZodDefault<z.ZodBoolean>;
+    defaultScopes: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    rules: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        glob: z.ZodString;
+        scopes: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>>;
+    readPaths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    writePaths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    deletePaths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    strictReadDefault: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+//# sourceMappingURL=auth-acl.schema.d.ts.map

package/dist/config/auth-acl.schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-acl.schema.d.ts","sourceRoot":"","sources":["../../src/config/auth-acl.schema.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;iBAqHzB,CAAC;AACL,eAAO,MAAM,aAAa;;;iBAQxB,CAAC;AAEH,eAAO,MAAM,eAAe;;;;;;;;;;;iBAiD1B,CAAC"}

package/dist/config/auth-acl.schema.js

@@ -0,0 +1,145 @@
+// WP1.1: extracted from ../config.schema.ts (which stays a compatibility facade re-exporting
+// these same symbol names). Leaf schema — imports Zod only, no shared scalars needed here.
+//
+// Import direction is non-negotiable: this file must never import config.schema.ts,
+// server.schema.ts, or any vault schema. Refinements that only read fields WITHIN auth or ACL
+// move here with their schema; a refinement that reads ANOTHER domain (e.g. the http/auth
+// interlock in ServerConfigSchema.superRefine) stays in config.schema.ts.
+import { z } from "zod";
+export const AuthConfigSchema = z
+    .object({
+    mode: z
+        .enum(["none", "jwt"])
+        .default("none")
+        .describe("Authentication mode. `none` grants every request full wildcard scopes and is refused on a non-loopback HTTP bind; `jwt` requires a jwtSecret or a JWKS."),
+    jwtSecret: z
+        .string()
+        .min(32)
+        .optional()
+        .describe("Shared secret for HS256 verification, minimum 32 characters. Secret. HS256 tokens verify ONLY against this, never against the JWKS."),
+    tokenTtlSeconds: z
+        .number()
+        .int()
+        .positive()
+        .default(86400)
+        .describe("Maximum accepted token AGE in seconds, measured from the token's `iat`. This caps age INDEPENDENTLY of `exp`: a token with a one-year expiry is still rejected once it is older than this, so a long-lived credential needs this raised to match."),
+    // THE-297 — asymmetric verification (RS256/ES256/EdDSA) behind the TokenVerifier seam.
+    // `jwks` is an inline JWKS document; `jwksFile` a path loaded once at transport boot (file
+    // or inline only — no URL fetch: no new network attack surface). Key rotation = multiple
+    // keys in the set, selected by the token's `kid` header (jose). HS256 stays available
+    // beside it; alg-confusion is structurally impossible (HS256 verifies ONLY against
+    // jwtSecret, asymmetric algs ONLY against the JWKS).
+    jwks: z
+        .record(z.string(), z.unknown())
+        .optional()
+        .describe("Inline JWKS document for asymmetric verification (RS256/ES256/EdDSA). Rotation is multiple keys in the set, selected by the token's `kid`."),
+    jwksFile: z
+        .string()
+        .optional()
+        .describe("Path to a JWKS document, loaded once at transport boot. Adds no network dependency; prefer it over jwksUri when the keys are static."),
+    // THE-658: fetch the JWKS from an authorization server's `jwks_uri`.
+    //
+    // THE-297 deliberately allowed inline/file ONLY, reasoning that a URL fetch adds network
+    // attack surface. That reasoning still holds and is why this is OPT-IN and unset by default —
+    // it is not a silent reversal. What it buys is the thing that made adopting a real
+    // authorization server a code change rather than a config change: with inline keys, every AS
+    // key rotation means an operator hand-copying a JWKS and redeploying, so rotation (the entire
+    // point of asymmetric verification) becomes a manual outage risk.
+    //
+    // The added surface is bounded: jose caches the fetched set and re-fetches only on an unknown
+    // `kid`, the URL is operator-configured (never derived from a request), and a fetch failure
+    // rejects the token rather than falling back to any other key source.
+    jwksUri: z
+        .string()
+        .url()
+        .optional()
+        .describe("URL of an authorization server's JWKS (its `jwks_uri`), fetched and cached for asymmetric verification. Opt-in: it adds a network dependency to token verification, which jwks/jwksFile do not. Use it when an external AS rotates keys."),
+    algorithms: z
+        .array(z.string())
+        .optional()
+        .describe("Explicit allowlist of accepted JWT algorithms. Algorithm confusion is structurally impossible regardless: HS256 verifies only against jwtSecret and asymmetric algorithms only against the JWKS."),
+    // THE-456 — audience/issuer binding. When set, the JWT verifier enforces them (jose rejects a
+    // token whose `aud`/`iss` does not match), closing the confused-deputy / token-passthrough gap
+    // the MCP 2025-11-25 authorization spec requires of a protected resource. `audience` defaults to
+    // the configured `resource` URI (below) when PRM is set, so a token an external AS minted for a
+    // DIFFERENT service is rejected here. Both unset (and no PRM `resource`) keeps the current
+    // behavior for local self-issued HS256 tokens.
+    audience: z
+        .union([z.string(), z.array(z.string())])
+        .optional()
+        .describe("Expected `aud` claim. Binding it rejects a token an issuer minted for a DIFFERENT service (confused deputy). Required with a JWKS or a non-loopback bind; defaults to `resource` when Protected Resource Metadata is configured."),
+    issuer: z
+        .string()
+        .optional()
+        .describe("Expected `iss` claim. Setting it also requires an audience — validating the issuer alone does not establish that the token was meant for this server."),
+    // MCP 2025-11-25 / RFC 9728 Protected Resource Metadata (THE-278). All optional; the HS256 token
+    // format is unchanged. When `resource` + at least one `authorizationServers` entry are set, the
+    // HTTP transport advertises a spec-compliant PRM document + WWW-Authenticate challenge for the
+    // OAuth 2.1 resource-server role. The authorization-server half (token issuance / DCR / OIDC)
+    // stays out of scope until a real external AS exists.
+    resource: z
+        .string()
+        .url()
+        .optional()
+        .describe("This server's canonical resource URI (RFC 9728). Set together with authorizationServers to advertise Protected Resource Metadata; also serves as the default bound audience."),
+    authorizationServers: z
+        .array(z.string().url())
+        .optional()
+        .describe("Authorization server issuer URLs advertised in the Protected Resource Metadata document. At least one is needed for PRM to be served."),
+    resourceName: z
+        .string()
+        .optional()
+        .describe("Human-readable resource name published in the Protected Resource Metadata document."),
+    scopesSupported: z
+        .array(z.string())
+        .optional()
+        .describe("Scopes advertised as supported in the Protected Resource Metadata document."),
+})
+    .refine((c) => c.mode !== "jwt" || !!c.jwtSecret || !!c.jwks || !!c.jwksFile || !!c.jwksUri, {
+    message: "auth.mode 'jwt' requires jwtSecret (>=32 chars) or a JWKS (jwks / jwksFile / jwksUri)",
+    path: ["jwtSecret"],
+});
+export const AclRuleSchema = z.object({
+    glob: z.string().min(1).describe("Glob matched against the vault-relative note path."),
+    scopes: z
+        .array(z.string())
+        .default([])
+        .describe("Scopes REQUIRED to operate on paths matching this rule (P1.4): a caller must hold every listed scope, in addition to the tool's own required scopes, to read/write/delete a matching path. The LAST matching rule wins, replacing rather than merging the scopes of earlier matches. An empty list adds no requirement. Enforced at dispatch on tool operations; it does not filter search/enumeration result visibility, which is governed by readPaths."),
+});
+export const AclConfigSchema = z.object({
+    readOnly: z
+        .boolean()
+        .default(false)
+        .describe("Reject every mutating operation on this vault regardless of the scopes a caller holds."),
+    defaultScopes: z
+        .array(z.string())
+        .default([])
+        .describe("Scopes REQUIRED to operate on a path that matches no rule (P1.4). Empty (the default) adds no requirement."),
+    rules: z
+        .array(AclRuleSchema)
+        .default([])
+        .describe("Ordered glob-to-required-scope rules enforced at dispatch (P1.4). Later matches override earlier ones."),
+    // Per-path operation ACL (G2.2 section 5 / G2.4). Optional and back-compatible:
+    // when a field is omitted that operation kind is unrestricted (M0 behavior);
+    // when present it is a glob whitelist — a path must match at least one entry.
+    // camelCase mirrors the rest of the config (readOnly, defaultScopes).
+    readPaths: z
+        .array(z.string())
+        .optional()
+        .describe("Glob whitelist for reads: a path must match at least one entry. Omitted leaves reads unrestricted (see strictReadDefault)."),
+    writePaths: z
+        .array(z.string())
+        .optional()
+        .describe("Glob whitelist for writes: a path must match at least one entry. Omitted leaves writes unrestricted."),
+    deletePaths: z
+        .array(z.string())
+        .optional()
+        .describe("Glob whitelist for deletes: a path must match at least one entry. Omitted leaves deletes unrestricted."),
+    /** When true, an UNDEFINED readPaths whitelist fails CLOSED on the request path (read_note et
+     *  al.), not just bridge enumeration (THE-268). Default false = M0 allow-all back-compat. */
+    strictReadDefault: z
+        .boolean()
+        .default(false)
+        .describe("When true, an UNDEFINED readPaths whitelist fails CLOSED on the request path rather than only on bridge enumeration. Default false preserves allow-all back-compatibility."),
+});
+//# sourceMappingURL=auth-acl.schema.js.map

package/dist/config/auth-acl.schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-acl.schema.js","sourceRoot":"","sources":["../../src/config/auth-acl.schema.ts"],"names":[],"mappings":"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"}

package/dist/config/indexing-embeddings.schema.d.ts

@@ -0,0 +1,43 @@
+import { z } from "zod";
+export declare const EmbeddingsConfigSchema: z.ZodObject<{
+    provider: z.ZodDefault<z.ZodString>;
+    model: z.ZodDefault<z.ZodString>;
+    dimensions: z.ZodDefault<z.ZodNumber>;
+    baseUrl: z.ZodOptional<z.ZodString>;
+    apiKey: z.ZodOptional<z.ZodString>;
+    apiKeyEnv: z.ZodOptional<z.ZodString>;
+    modulePath: z.ZodOptional<z.ZodString>;
+    revision: z.ZodOptional<z.ZodString>;
+    pooling: z.ZodOptional<z.ZodString>;
+    timeoutMs: z.ZodDefault<z.ZodNumber>;
+    batchSize: z.ZodDefault<z.ZodNumber>;
+    maxBatchTokens: z.ZodDefault<z.ZodNumber>;
+    concurrency: z.ZodDefault<z.ZodNumber>;
+    truncate: z.ZodDefault<z.ZodBoolean>;
+    chunkContext: z.ZodDefault<z.ZodBoolean>;
+    queryPrefix: z.ZodDefault<z.ZodString>;
+    documentPrefix: z.ZodDefault<z.ZodString>;
+    modelTier: z.ZodOptional<z.ZodObject<{
+        dense: z.ZodObject<{
+            baseUrl: z.ZodString;
+            model: z.ZodDefault<z.ZodString>;
+            revision: z.ZodOptional<z.ZodString>;
+            pooling: z.ZodDefault<z.ZodString>;
+        }, z.core.$strip>;
+        full: z.ZodOptional<z.ZodObject<{
+            baseUrl: z.ZodString;
+            model: z.ZodDefault<z.ZodString>;
+            revision: z.ZodOptional<z.ZodString>;
+            authToken: z.ZodOptional<z.ZodString>;
+            dimensions: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const IndexingConfigSchema: z.ZodPrefault<z.ZodObject<{
+    writeConcurrency: z.ZodDefault<z.ZodNumber>;
+    writeConcurrencyPerVault: z.ZodDefault<z.ZodNumber>;
+    queueMax: z.ZodDefault<z.ZodNumber>;
+    streamingWalk: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>>;
+export type IndexingConfig = z.infer<typeof IndexingConfigSchema>;
+//# sourceMappingURL=indexing-embeddings.schema.d.ts.map

package/dist/config/indexing-embeddings.schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexing-embeddings.schema.d.ts","sourceRoot":"","sources":["../../src/config/indexing-embeddings.schema.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAqMjC,CAAC;AAOH,eAAO,MAAM,oBAAoB;;;;;kBAoClB,CAAC;AAChB,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC"}

package/dist/config/indexing-embeddings.schema.js

@@ -0,0 +1,209 @@
+// WP1.4: extracted from ../config.schema.ts (which stays a compatibility facade re-exporting
+// these same symbol names). Leaf schema — imports Zod only, no shared scalars needed here.
+//
+// Import direction is non-negotiable: this file must never import config.schema.ts,
+// server.schema.ts, or any other schema module. IndexingConfigSchema chains only
+// `.prefault({})` (a default-application combinator, not a `.refine`/`.superRefine`) — there is
+// no cross-domain field read to keep back in config.schema.ts, so the whole schema moves here.
+import { z } from "zod";
+export const EmbeddingsConfigSchema = z.object({
+    provider: z
+        .string()
+        .min(1)
+        .default("ollama")
+        .describe("Embeddings backend name, resolved against the provider registry at startup. Built-ins: ollama, openai, voyage, cohere, bge-m3, model-tier (splits dense and multi-vector across two services), the generic openai-compatible, and the profile-gated module. An unregistered name is a startup error listing every valid option."),
+    model: z
+        .string()
+        .default("nomic-embed-text")
+        .describe("Embedding model name as the provider names it."),
+    dimensions: z
+        .number()
+        .int()
+        .positive()
+        .default(768)
+        .describe("Stored vector width, and the width of the vec0 column. Changing it requires a fresh index — existing vectors are not re-projected."),
+    baseUrl: z
+        .string()
+        .url()
+        .optional()
+        .describe("Provider base URL. Required for self-hosted runners; hosted providers default to their public API."),
+    apiKey: z
+        .string()
+        .optional()
+        .describe("Provider API key. Secret — never logged or returned by a tool."),
+    apiKeyEnv: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Name of the environment variable holding the provider API key. Needed for generic providers, which have no entry in the built-in per-vendor variable map. An inline apiKey takes precedence."),
+    modulePath: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Module exporting createEmbeddingProvider, for provider 'module'. Resolved against the config file's directory. Refused under the hardened security profile, and refused on CLI/eval entry points (module providers load only from the server's boot wiring). The factory may be sync or async (an async factory is awaited). It must return an object with a non-empty string id, provider, and model — id is what chunk_embeddings.model and the vec fingerprint identify the provider by, so two module providers sharing (or omitting) id are indistinguishable to the index — a positive integer dimensions, and embed(texts). Validated at load time, before first use."),
+    revision: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Model revision / commit / checkpoint id. Folded into vec_index_fingerprint, so declaring it makes a checkpoint upgrade at the SAME model name and width rebuild the index instead of silently serving the old checkpoint's vectors against queries embedded by the new one. Omitting it reproduces today's behaviour exactly."),
+    pooling: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Pooling strategy the backend applies (e.g. 'mean', 'last-token'). Folded into the representation identity persisted as vec_index_fingerprint, so changing it rebuilds the vector index rather than serving vectors pooled a different way against queries pooled the new way. The rebuild reuses the stored embeddings — it does not re-embed, and costs no provider calls."),
+    // GH #171/#172: local-runner indexing robustness. Local models are far slower than hosted APIs,
+    // and a stock local runner (llama-server) crashes on a token-dense batch, so these are
+    // configurable with local-safe defaults. `timeoutMs` bounds each embed request (was a hardcoded
+    // 30s with no knob). `batchSize` caps inputs/request; `maxBatchTokens` caps a request's estimated
+    // tokens (chars/4) so a dense sub-batch is split before it overruns a local runner's budget (a
+    // single over-budget text still goes alone). `concurrency` is how many embed requests run in flight.
+    // THE-390: `maxBatchTokens` must stay UNDER the provider's loaded context — Ollama defaults to
+    // n_ctx 4096 and 400-rejects a request whose summed tokens exceed it, and the chars/4 estimate
+    // undercounts real tokenization (~2-2.5x on link-dense markdown). 2048 estimated keeps a batch
+    // inside a 4096 context with that drift; the indexer also bisects + retries a rejected batch,
+    // so an occasional overshoot costs a retry, not the reindex.
+    timeoutMs: z
+        .number()
+        .int()
+        .positive()
+        .default(120000)
+        .describe("Timeout in ms for a single embed request. Defaults high because local runners are far slower than hosted APIs."),
+    batchSize: z.number().int().positive().default(512).describe("Maximum inputs per embed request."),
+    maxBatchTokens: z
+        .number()
+        .int()
+        .positive()
+        .default(2048)
+        .describe("Estimated-token ceiling per request (chars/4), splitting a dense sub-batch before it overruns a local runner's budget. Must stay UNDER the provider's loaded context: Ollama defaults to n_ctx 4096 and rejects an over-budget request, and the chars/4 estimate undercounts real tokenization on link-dense markdown."),
+    concurrency: z
+        .number()
+        .int()
+        .positive()
+        .default(4)
+        .describe("How many embed requests run in flight at once."),
+    // THE-387: Matryoshka (MRL) dimension truncation. When true, a provider that returns vectors
+    // WIDER than `dimensions` is truncated to the first `dimensions` components + renormalised (so a
+    // wide MRL model such as Qwen3-8B at 4096 can be stored at 1024). Off by default; a non-MRL width
+    // mismatch still errors rather than silently truncating meaningless prefixes.
+    truncate: z
+        .boolean()
+        .default(false)
+        .describe("Matryoshka (MRL) truncation: accept a provider vector WIDER than `dimensions` by keeping the first `dimensions` components and renormalising. Off by default so a non-MRL width mismatch errors instead of silently storing a meaningless prefix."),
+    /** THE-406: contextual chunk enrichment. When true, each chunk is embedded and BM25-indexed as
+     *  "{note title}{ — heading breadcrumb}\n\n{content}" instead of the bare section text — the
+     *  chunker strips heading lines into metadata, so title/heading-only evidence is otherwise
+     *  invisible to both retrieval streams. Display content (chunks.content) stays raw. The chunk
+     *  content hash covers the enriched text, so flipping this re-embeds the vault on the next
+     *  reconcile. DEFAULT ON since THE-408: measured +0.223 nDCG@10 (p=0.0001) with the divergence
+     *  rebuild now enrichment-aware. UPGRADE NOTE: an index built with the flag off re-embeds in
+     *  full on the first reconcile after upgrading (hash change) — set `chunkContext: false` to
+     *  keep the old representation. */
+    chunkContext: z
+        .boolean()
+        .default(true)
+        .describe('Embed and BM25-index each chunk as "{title}{ — heading breadcrumb}\\n\\n{content}" rather than bare section text, so title- and heading-only evidence is visible to both retrieval streams. Displayed content stays raw. The chunk hash covers the enriched text, so changing this re-embeds the vault on the next reconcile.'),
+    /** THE-405: asymmetric instruct prefixes for models whose cards require them (e.g.
+     *  Qwen3-Embedding's "Instruct: ...\nQuery: " on the query side, documents plain). Applied at
+     *  the provider factory: `queryPrefix` on embeds marked input:"query", `documentPrefix` on
+     *  everything else (indexing). BOTH default empty — nomic-style prefixes measured HARMFUL on
+     *  this vault (2026-07-11), so nothing changes unless a config opts in. Changing
+     *  `documentPrefix` re-embeds nothing by itself (hashes cover chunk text, not the prefix) —
+     *  pair a document-prefix change with a fresh cacheDir. */
+    queryPrefix: z
+        .string()
+        .default("")
+        .describe("Instruct prefix prepended to query-side embeds, for models whose cards require one. Empty by default — such prefixes measured harmful on this corpus."),
+    documentPrefix: z
+        .string()
+        .default("")
+        .describe("Instruct prefix prepended to document-side (indexing) embeds. Empty by default. Changing it re-embeds nothing on its own, since hashes cover chunk text and not the prefix — pair a change with a fresh cacheDir."),
+    /** #237: polyglot model tier - dense retrieval from Qwen3 via the Rust TEI service,
+     *  sparse+ColBERT from BGE-M3 via the Python service (services/bge-m3-service). Required when
+     *  provider is "model-tier". The two are SEPARATE streams fused by RRF on ranks;
+     *  embeddings.dimensions is the Qwen dense width (the vec0 column). */
+    modelTier: z
+        .object({
+        dense: z
+            .object({
+            baseUrl: z
+                .string()
+                .url()
+                .describe("Base URL of the dense (Qwen3 via Rust TEI) embedding service."),
+            model: z
+                .string()
+                .default("Qwen/Qwen3-Embedding-0.6B")
+                .describe("Dense model id. Its width is what embeddings.dimensions must match."),
+            revision: z
+                .string()
+                .optional()
+                .describe("Pinned model revision for the dense service. PROVENANCE ONLY: it moves neither provider.id nor vec_index_fingerprint, so changing it does not rebuild the index. Use the top-level embeddings.revision to force a re-embed — it applies to model-tier too."),
+            pooling: z
+                .string()
+                .default("last-token")
+                .describe("Pooling strategy for the dense model."),
+        })
+            .describe("Dense retrieval half of the model tier. Required when provider is model-tier."),
+        full: z
+            .object({
+            baseUrl: z.string().url().describe("Base URL of the multi-vector (BGE-M3) service."),
+            model: z.string().default("BAAI/bge-m3").describe("Multi-vector model id."),
+            revision: z
+                .string()
+                .optional()
+                .describe("Pinned model revision for the multi-vector service. PROVENANCE ONLY: it moves neither provider.id nor vec_index_fingerprint, so changing it does not rebuild the index. Use the top-level embeddings.revision to force a re-embed — it applies to model-tier too."),
+            authToken: z
+                .string()
+                .optional()
+                .describe("Bearer token for the multi-vector service. Secret."),
+            dimensions: z
+                .number()
+                .int()
+                .positive()
+                .default(1024)
+                .describe("Dense width of the multi-vector model, separate from embeddings.dimensions."),
+        })
+            .optional()
+            .describe("Sparse and ColBERT half of the model tier. Absent disables the retrieval.sparse and retrieval.colbert streams."),
+    })
+        .optional()
+        .describe("Polyglot model tier: dense retrieval from one service and sparse/ColBERT from another, fused by RRF on ranks. Required when provider is model-tier."),
+});
+// THE-458 (audit #5): index-on-write coordinator concurrency + backpressure. Fully defaulted so a
+// config predating it validates unchanged. `writeConcurrency` bounds concurrent index/embed calls
+// across ALL vaults; `writeConcurrencyPerVault` bounds them per vault (audit recommends 2–4);
+// `queueMax` is a soft distinct-pending-path cap that surfaces backpressure in server_health (writes
+// are never dropped).
+export const IndexingConfigSchema = z
+    .object({
+    writeConcurrency: z
+        .number()
+        .int()
+        .positive()
+        .default(8)
+        .describe("Ceiling on concurrent index/embed calls across ALL vaults."),
+    writeConcurrencyPerVault: z
+        .number()
+        .int()
+        .positive()
+        .default(4)
+        .describe("Ceiling on concurrent index/embed calls for a single vault."),
+    queueMax: z
+        .number()
+        .int()
+        .positive()
+        .default(1000)
+        .describe("Soft cap on distinct pending paths, surfaced as backpressure in server_health. Writes are never dropped when it is exceeded."),
+    /** THE-490/THE-591: indexVault's opt-in per-directory-sorted streaming walk
+     *  (walkVaultStream), vs the default eager walkVault that materializes the whole sorted
+     *  file list before any note is processed. Measured -43% peak RSS on a full reindex; index
+     *  OUTPUT is unchanged either way (test/index-stream-walk-equivalence.test.ts). Until this
+     *  flag existed, none of the three production callers (add_vault, the boot reconcile, the
+     *  index_vault tool) ever set it, so the flag was unreachable outside tests — OFF by default
+     *  and stays off until enabling it is a deliberate decision, not a de facto one. */
+    streamingWalk: z
+        .boolean()
+        .default(false)
+        .describe("Walk the vault lazily per-directory (walkVaultStream) instead of materializing the full sorted file list before indexing starts. Lower peak memory on large vaults; index output is unchanged either way."),
+})
+    .prefault({});
+//# sourceMappingURL=indexing-embeddings.schema.js.map

package/dist/config/indexing-embeddings.schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexing-embeddings.schema.js","sourceRoot":"","sources":["../../src/config/indexing-embeddings.schema.ts"],"names":[],"mappings":"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"}

package/dist/config/observability.schema.d.ts

@@ -0,0 +1,53 @@
+import { z } from "zod";
+export declare const ObservabilityConfigSchema: z.ZodObject<{
+    otel: z.ZodPrefault<z.ZodObject<{
+        endpoint: z.ZodOptional<z.ZodString>;
+        headers: z.ZodPrefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strip>>;
+    prometheus: z.ZodPrefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        port: z.ZodDefault<z.ZodNumber>;
+        bind: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>>;
+    morgiana: z.ZodPrefault<z.ZodObject<{
+        spool: z.ZodDefault<z.ZodBoolean>;
+        httpEndpoint: z.ZodOptional<z.ZodString>;
+        httpHeaders: z.ZodPrefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strip>>;
+    retention: z.ZodPrefault<z.ZodObject<{
+        eventLogDays: z.ZodDefault<z.ZodNumber>;
+        tracesDays: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const SnapshotsConfigSchema: z.ZodPrefault<z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    retention: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>>;
+export declare const MaintenanceConfigSchema: z.ZodPrefault<z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    intervalMinutes: z.ZodDefault<z.ZodNumber>;
+    jobsCompleteRetentionDays: z.ZodDefault<z.ZodNumber>;
+    reconcileIntervalMinutes: z.ZodOptional<z.ZodNumber>;
+    episodesRetentionDays: z.ZodDefault<z.ZodNumber>;
+    retrievalsRetentionDays: z.ZodDefault<z.ZodNumber>;
+    jobsFailedRetentionDays: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>>;
+export declare const WatchConfigSchema: z.ZodPrefault<z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    debounceMs: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>>;
+export declare const SchedulerConfigSchema: z.ZodPrefault<z.ZodObject<{
+    eventLoopDeferMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>>;
+export declare const PlaneConfigSchema: z.ZodPrefault<z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    intervalMinutes: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>>;
+export declare const PlurConfigSchema: z.ZodObject<{
+    endpoint: z.ZodOptional<z.ZodString>;
+    apiKey: z.ZodOptional<z.ZodString>;
+    apiPrefix: z.ZodDefault<z.ZodString>;
+    timeoutMs: z.ZodDefault<z.ZodNumber>;
+    command: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+//# sourceMappingURL=observability.schema.d.ts.map

package/dist/config/observability.schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observability.schema.d.ts","sourceRoot":"","sources":["../../src/config/observability.schema.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;iBA8EpC,CAAC;AAGH,eAAO,MAAM,qBAAqB;;;kBAgBnB,CAAC;AAGhB,eAAO,MAAM,uBAAuB;;;;;;;;kBAmErB,CAAC;AAOhB,eAAO,MAAM,iBAAiB;;;kBAiBf,CAAC;AAWhB,eAAO,MAAM,qBAAqB;;kBAWnB,CAAC;AAIhB,eAAO,MAAM,iBAAiB;;;kBAef,CAAC;AAUhB,eAAO,MAAM,gBAAgB;;;;;;iBAgC3B,CAAC"}