@stackbone/sdk 0.1.0-alpha.0 → 0.1.0-alpha.2

package/index.js

@@ -1786,9 +1786,9 @@ var nanoid = /^[a-zA-Z0-9_-]{21}$/;
 var duration = /^P(?:(\d+W)|(?!.*W)(?=\d|T\d)(\d+Y)?(\d+M)?(\d+D)?(T(?=\d)(\d+H)?(\d+M)?(\d+([.,]\d+)?S)?)?)$/;
 var extendedDuration = /^[-+]?P(?!$)(?:(?:[-+]?\d+Y)|(?:[-+]?\d+[.,]\d+Y$))?(?:(?:[-+]?\d+M)|(?:[-+]?\d+[.,]\d+M$))?(?:(?:[-+]?\d+W)|(?:[-+]?\d+[.,]\d+W$))?(?:(?:[-+]?\d+D)|(?:[-+]?\d+[.,]\d+D$))?(?:T(?=[\d+-])(?:(?:[-+]?\d+H)|(?:[-+]?\d+[.,]\d+H$))?(?:(?:[-+]?\d+M)|(?:[-+]?\d+[.,]\d+M$))?(?:[-+]?\d+(?:[.,]\d+)?S)?)??$/;
 var guid = /^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$/;
-var uuid = /* @__PURE__ */ __name((version2) => {
-  if (!version2) return /^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/;
-  return new RegExp(`^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-${version2}[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$`);
+var uuid = /* @__PURE__ */ __name((version3) => {
+  if (!version3) return /^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/;
+  return new RegExp(`^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-${version3}[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$`);
 }, "uuid");
 var uuid4 = /* @__PURE__ */ uuid(4);
 var uuid6 = /* @__PURE__ */ uuid(6);
@@ -14972,10 +14972,10 @@ function fromJSONSchema(schema, params) {
   if (typeof schema === "boolean") {
     return schema ? z.any() : z.never();
   }
-  const version2 = detectVersion(schema, params?.defaultTarget);
+  const version3 = detectVersion(schema, params?.defaultTarget);
   const defs = schema.$defs || schema.definitions || {};
   const ctx = {
-    version: version2,
+    version: version3,
     defs,
     refs: /* @__PURE__ */ new Map(),
     processing: /* @__PURE__ */ new Set(),
@@ -15553,6 +15553,13 @@ external_exports.object({
   nextCursor: external_exports.string().nullable(),
   prevCursor: external_exports.string().nullable()
 });
+external_exports.object({
+  fxtId: external_exports.uuid()
+});
+external_exports.object({
+  input: jsonObject().nullable(),
+  output: jsonObject().nullable()
+});
 
 // ../validators/src/lib/auth/session.ts
 var sessionUserSchema = external_exports.object({
@@ -16637,6 +16644,34 @@ function pickDefinedAsStrings(source) {
 }
 __name(pickDefinedAsStrings, "pickDefinedAsStrings");
 
+// src/lib/facade-helpers.ts
+function remapHttpNotFound(code, domainCode, message, meta3) {
+  if (code !== "http_not_found") return null;
+  const error48 = {
+    code: domainCode,
+    message
+  };
+  if (meta3) error48.meta = meta3;
+  return err(error48);
+}
+__name(remapHttpNotFound, "remapHttpNotFound");
+function validateStringArray(values, field, errorCode) {
+  if (!Array.isArray(values) || values.length === 0) {
+    return err({
+      code: errorCode,
+      message: `\`${field}\` must be a non-empty array.`
+    });
+  }
+  if (values.some((v) => typeof v !== "string" || !v.trim())) {
+    return err({
+      code: errorCode,
+      message: `\`${field}[*]\` must be non-empty strings.`
+    });
+  }
+  return null;
+}
+__name(validateStringArray, "validateStringArray");
+
 // src/facades/config/config.ts
 var ConfigFacade = class {
   static {
@@ -16658,7 +16693,11 @@ var ConfigFacade = class {
     const gateResult = await this._gate();
     if (gateResult.error) return err(gateResult.error);
     const result = await this._http.get(`/api/config/${encodeURIComponent(key)}`);
-    if (result.error) return remapNotFound(result.error.code, key) ?? result;
+    if (result.error) {
+      return remapHttpNotFound(result.error.code, "config_not_found", `Config key \`${key}\` is not set for this agent.`, {
+        key
+      }) ?? result;
+    }
     return ok(result.data.value);
   }
   /**
@@ -16668,18 +16707,8 @@ var ConfigFacade = class {
   * is `Partial<T>`).
   */
   async getMany(keys) {
-    if (!Array.isArray(keys) || keys.length === 0) {
-      return err({
-        code: "config_invalid_request",
-        message: "`keys` must be a non-empty array."
-      });
-    }
-    if (keys.some((k) => !k.trim())) {
-      return err({
-        code: "config_invalid_request",
-        message: "`keys[*]` must be non-empty strings."
-      });
-    }
+    const invalid = validateStringArray(keys, "keys", "config_invalid_request");
+    if (invalid) return invalid;
     const gateResult = await this._gate();
     if (gateResult.error) return err(gateResult.error);
     const result = await this._http.get("/api/config", {
@@ -16698,17 +16727,6 @@ var ConfigFacade = class {
     return ok(values);
   }
 };
-function remapNotFound(code, key) {
-  if (code !== "http_not_found") return null;
-  return err({
-    code: "config_not_found",
-    message: `Config key \`${key}\` is not set for this agent.`,
-    meta: {
-      key
-    }
-  });
-}
-__name(remapNotFound, "remapNotFound");
 
 // src/facades/connections/connections.ts
 var ConnectionsFacade = class {
@@ -16794,7 +16812,11 @@ var SecretsFacade = class {
     const gateResult = await this._gate();
     if (gateResult.error) return err(gateResult.error);
     const result = await this._http.get(`/api/secrets/${encodeURIComponent(name)}`);
-    if (result.error) return remapNotFound2(result.error.code, name) ?? result;
+    if (result.error) {
+      return remapHttpNotFound(result.error.code, "secrets_not_found", `Secret \`${name}\` is not registered for this organization.`, {
+        name
+      }) ?? result;
+    }
     if (typeof result.data.value !== "string") {
       return err({
         code: "secrets_invalid_response",
@@ -16807,23 +16829,13 @@ var SecretsFacade = class {
     return ok(result.data.value);
   }
   /**
-  * Names absent from the workspace come back as omissions in the response —
+  * Names absent from the organization come back as omissions in the response —
   * the returned map only contains entries the control plane actually has.
   * Callers that need "all-or-nothing" semantics should diff the keys.
   */
   async getMany(names) {
-    if (!Array.isArray(names) || names.length === 0) {
-      return err({
-        code: "secrets_invalid_request",
-        message: "`names` must be a non-empty array."
-      });
-    }
-    if (names.some((n) => !n.trim())) {
-      return err({
-        code: "secrets_invalid_request",
-        message: "`names[*]` must be non-empty strings."
-      });
-    }
+    const invalid = validateStringArray(names, "names", "secrets_invalid_request");
+    if (invalid) return invalid;
     const gateResult = await this._gate();
     if (gateResult.error) return err(gateResult.error);
     const result = await this._http.get("/api/secrets", {
@@ -16842,17 +16854,6 @@ var SecretsFacade = class {
     return ok(values);
   }
 };
-function remapNotFound2(code, name) {
-  if (code !== "http_not_found") return null;
-  return err({
-    code: "secrets_not_found",
-    message: `Secret \`${name}\` is not registered for this workspace.`,
-    meta: {
-      name
-    }
-  });
-}
-__name(remapNotFound2, "remapNotFound");
 
 // src/lib/http-client.ts
 var RETRYABLE_STATUS = /* @__PURE__ */ new Set([
@@ -17735,6 +17736,11 @@ async function aggregateRunCost(runId, options) {
   };
 }
 __name(aggregateRunCost, "aggregateRunCost");
+
+// package.json
+var version2 = "0.1.0-alpha.2";
+
+// src/observability/logger.ts
 var LOG_LEVELS = {
   trace: 10,
   debug: 20,
@@ -17948,7 +17954,7 @@ var OtlpHttpDestination = class OtlpHttpDestination2 {
 };
 var SDK_SCOPE = {
   name: "@stackbone/sdk",
-  version: "0.0.1"
+  version: version2
 };
 function buildOtlpLogsBody(records, resourceAttributes) {
   return {
@@ -17981,11 +17987,12 @@ function toOtlpLogRecord(record2) {
   };
 }
 __name(toOtlpLogRecord, "toOtlpLogRecord");
+var SEVERITY_TEXT_BY_LEVEL = Object.fromEntries(Object.entries(LOG_LEVELS).map(([name, value]) => [
+  value,
+  name.toUpperCase()
+]));
 function severityText(level) {
-  for (const [name, value] of Object.entries(LOG_LEVELS)) {
-    if (value === level) return name.toUpperCase();
-  }
-  return "INFO";
+  return SEVERITY_TEXT_BY_LEVEL[level] ?? "INFO";
 }
 __name(severityText, "severityText");
 function toOtlpAttributes(attrs) {
@@ -18113,7 +18120,7 @@ var RunStepsSpanProcessor = class {
     this.intervalMs = options.flushIntervalMs ?? DEFAULT_INTERVAL_MS2;
     this.resolveStepType = options.resolveStepType ?? defaultStepTypeResolver;
     this.newId = options.newId ?? randomUUID;
-    this.connectionString = options.connectionString ?? process.env["DATABASE_URL"];
+    this.connectionString = options.connectionString ?? process.env["STACKBONE_POSTGRES_URL"];
     if (options.sql) {
       this.sql = options.sql;
       this.ownsSql = false;
@@ -18153,11 +18160,11 @@ var RunStepsSpanProcessor = class {
     }
   }
   buildRow(span) {
-    const runId = readString(span.attributes[RUN_ID_ATTRIBUTE]);
-    if (!runId) return null;
     const spanId = span.spanContext().spanId;
     const stepId = this.stepIdBySpanId.get(spanId) ?? this.newId();
     this.stepIdBySpanId.delete(spanId);
+    const runId = readString(span.attributes[RUN_ID_ATTRIBUTE]);
+    if (!runId) return null;
     const parentSpanId = span.parentSpanContext?.spanId ?? span.parentSpanId ?? null;
     const parentStepId = parentSpanId ? this.stepIdBySpanId.get(parentSpanId) ?? null : null;
     const startedAt = formatHrTime(span.startTime);
@@ -18297,7 +18304,7 @@ var ObservabilityModule = class {
     if (!this._processor) {
       const merged = {
         ...options,
-        connectionString: options.connectionString ?? this._resolved.config.databaseUrl ?? this._resolved.env["DATABASE_URL"]
+        connectionString: options.connectionString ?? this._resolved.config.databaseUrl ?? this._resolved.env["STACKBONE_POSTGRES_URL"]
       };
       this._processor = new RunStepsSpanProcessor(merged);
     }
@@ -18356,7 +18363,7 @@ var ObservabilityModule = class {
     if (!sql) {
       return err({
         code: "database_url_missing",
-        message: "Cannot reach the agent Postgres \u2014 set `DATABASE_URL` in the container or pass `databaseUrl` to `createClient({...})`."
+        message: "Cannot reach the agent Postgres \u2014 set `STACKBONE_POSTGRES_URL` in the container or pass `databaseUrl` to `createClient({...})`."
       });
     }
     try {
@@ -18377,7 +18384,7 @@ var ObservabilityModule = class {
   // don't pay the dep cost.
   async resolveSql() {
     if (this._sqlResolved) return this._sql;
-    const connectionString = this._resolved.config.databaseUrl ?? this._resolved.env["DATABASE_URL"];
+    const connectionString = this._resolved.config.databaseUrl ?? this._resolved.env["STACKBONE_POSTGRES_URL"];
     if (!connectionString) {
       this._sqlResolved = true;
       return null;
@@ -18607,6 +18614,41 @@ function isUnsupportedModelError(error48) {
 }
 __name(isUnsupportedModelError, "isUnsupportedModelError");
 
+// src/modules/rag/errors.ts
+var PG_UNDEFINED_TABLE = "42P01";
+var RAG_SCHEMA_MISSING_HINT = "run `stackbone db migrate add-rag` and `stackbone db migrate up`";
+function isTaggedError(cause) {
+  return cause instanceof Error;
+}
+__name(isTaggedError, "isTaggedError");
+function toRagError(cause, message, fallbackCode = "rag_error") {
+  if (isTaggedError(cause) && cause.code === PG_UNDEFINED_TABLE) {
+    return {
+      code: "rag_schema_missing",
+      message: `RAG tables are not installed \u2014 ${RAG_SCHEMA_MISSING_HINT}.`,
+      cause,
+      meta: {
+        hint: RAG_SCHEMA_MISSING_HINT
+      }
+    };
+  }
+  if (isTaggedError(cause)) {
+    const error48 = {
+      code: cause.code ?? fallbackCode,
+      message: `${message}: ${cause.message}`,
+      cause
+    };
+    if (cause.meta) error48.meta = cause.meta;
+    return error48;
+  }
+  return {
+    code: fallbackCode,
+    message,
+    cause
+  };
+}
+__name(toRagError, "toRagError");
+
 // src/modules/rag/jobs.ts
 function createSqlJobWriter(sql) {
   return {
@@ -18632,7 +18674,7 @@ function createSqlJobWriter(sql) {
           jobId: row.id
         });
       } catch (cause) {
-        return err(toJobsError(cause, "Job start failed"));
+        return err(toRagError(cause, "Job start failed", "rag_jobs_error"));
       }
     },
     async progress({ jobId, processedChunks, totalChunks, currentDocument }) {
@@ -18671,7 +18713,7 @@ function createSqlJobWriter(sql) {
     },
     async isCancelled({ jobId }) {
       const rows = await sql`
-        SELECT id, status FROM stackbone_rag_jobs WHERE id = ${jobId}
+        SELECT status FROM stackbone_rag_jobs WHERE id = ${jobId} LIMIT 1
       `;
       return rows[0]?.status === "cancelled";
     }
@@ -18679,10 +18721,6 @@ function createSqlJobWriter(sql) {
 }
 __name(createSqlJobWriter, "createSqlJobWriter");
 async function ensureCollection(sql, name) {
-  const existing = await sql`
-    SELECT id FROM stackbone_rag_collections WHERE name = ${name} LIMIT 1
-  `;
-  if (existing[0]) return existing[0].id;
   const inserted = await sql`
     INSERT INTO stackbone_rag_collections (name) VALUES (${name})
     ON CONFLICT (name) DO UPDATE SET name = EXCLUDED.name
@@ -18690,37 +18728,11 @@ async function ensureCollection(sql, name) {
   `;
   const row = inserted[0];
   if (!row) {
-    throw new Error(`stackbone_rag_collections insert returned no row for ${name}`);
+    throw new Error(`stackbone_rag_collections upsert returned no row for ${name}`);
   }
   return row.id;
 }
 __name(ensureCollection, "ensureCollection");
-function toJobsError(cause, message) {
-  if (cause instanceof Error) {
-    const tagged = cause;
-    if (tagged.code === "42P01") {
-      return {
-        code: "rag_schema_missing",
-        message: "RAG tables are not installed \u2014 run `stackbone db migrate add-rag` and `stackbone db migrate up`.",
-        cause,
-        meta: {
-          hint: "run `stackbone db migrate add-rag` and `stackbone db migrate up`"
-        }
-      };
-    }
-    return {
-      code: tagged.code ?? "rag_jobs_error",
-      message: `${message}: ${cause.message}`,
-      cause
-    };
-  }
-  return {
-    code: "rag_jobs_error",
-    message,
-    cause
-  };
-}
-__name(toJobsError, "toJobsError");
 var PDF_MIME_TYPES = /* @__PURE__ */ new Set([
   "application/pdf",
   "application/x-pdf"
@@ -18780,10 +18792,12 @@ __name(looksLikePdf, "looksLikePdf");
 var DEFAULT_NAMESPACE = "default";
 var META_KEY_DIMENSIONS = "dimensions";
 var META_KEY_DISTANCE = "distance";
+var schemaVerifiedDimensions = /* @__PURE__ */ new WeakMap();
 async function ensureSchema(sql, dimensions) {
   if (!Number.isInteger(dimensions) || dimensions <= 0 || dimensions > 8192) {
     throw new Error(`rag.ensureSchema: invalid dimensions ${dimensions}. Must be a positive integer <= 8192.`);
   }
+  if (schemaVerifiedDimensions.get(sql) === dimensions) return;
   const existing = await sql`
     SELECT value::int AS value FROM _rag_meta WHERE key = ${META_KEY_DIMENSIONS}
   `.catch(() => []);
@@ -18798,6 +18812,7 @@ async function ensureSchema(sql, dimensions) {
       };
       throw error48;
     }
+    schemaVerifiedDimensions.set(sql, dimensions);
     return;
   }
   await sql.begin(async (tx) => {
@@ -18817,6 +18832,7 @@ async function ensureSchema(sql, dimensions) {
       ON CONFLICT (key) DO NOTHING
     `;
   });
+  schemaVerifiedDimensions.set(sql, dimensions);
 }
 __name(ensureSchema, "ensureSchema");
 async function reset(sql) {
@@ -18824,29 +18840,31 @@ async function reset(sql) {
     await tx`DROP TABLE IF EXISTS rag_chunks`;
     await tx`DROP TABLE IF EXISTS _rag_meta`;
   });
+  schemaVerifiedDimensions.delete(sql);
 }
 __name(reset, "reset");
-async function ingestDocument(sql, docId, namespace, rows) {
+async function clearDocument(sql, docId, namespace) {
+  await sql`
+    DELETE FROM rag_chunks
+    WHERE namespace = ${namespace} AND doc_id = ${docId}
+  `;
+}
+__name(clearDocument, "clearDocument");
+async function ingestDocument(sql, rows) {
   if (rows.length === 0) return 0;
-  await sql.begin(async (tx) => {
-    await tx`
-      DELETE FROM rag_chunks
-      WHERE namespace = ${namespace} AND doc_id = ${docId}
-    `;
-    const placeholders = rows.map((_, i) => {
-      const base = i * 6;
-      return `($${base + 1}, $${base + 2}, $${base + 3}, $${base + 4}, $${base + 5}::vector, $${base + 6}::jsonb)`;
-    }).join(",");
-    const params = rows.flatMap((row) => [
-      row.docId,
-      row.chunkIdx,
-      row.namespace,
-      row.content,
-      formatVector(row.embedding),
-      JSON.stringify(row.metadata)
-    ]);
-    await tx.unsafe(`INSERT INTO rag_chunks (doc_id, chunk_idx, namespace, content, embedding, metadata) VALUES ${placeholders}`, params);
-  });
+  const placeholders = rows.map((_, i) => {
+    const base = i * 6;
+    return `($${base + 1}, $${base + 2}, $${base + 3}, $${base + 4}, $${base + 5}::vector, $${base + 6}::jsonb)`;
+  }).join(",");
+  const params = rows.flatMap((row) => [
+    row.docId,
+    row.chunkIdx,
+    row.namespace,
+    row.content,
+    formatVector(row.embedding),
+    JSON.stringify(row.metadata)
+  ]);
+  await sql.unsafe(`INSERT INTO rag_chunks (doc_id, chunk_idx, namespace, content, embedding, metadata) VALUES ${placeholders}`, params);
   return rows.length;
 }
 __name(ingestDocument, "ingestDocument");
@@ -18916,8 +18934,6 @@ var CHUNK_INDEXES_DDL = `
 
 // src/modules/rag/pipeline.ts
 var DEFAULT_TOP_K = 5;
-var RAG_SCHEMA_MISSING_HINT = "run `stackbone db migrate add-rag` and `stackbone db migrate up`";
-var PG_UNDEFINED_TABLE = "42P01";
 var RagPipeline = class {
   static {
     __name(this, "RagPipeline");
@@ -18982,19 +18998,16 @@ var RagPipeline = class {
       if (started.error) return err(started.error);
       jobId = started.data.jobId;
     }
-    const emit = /* @__PURE__ */ __name(async (event) => {
-      if (onProgress) await onProgress(event);
-    }, "emit");
-    const startEvent = {
+    await onProgress?.({
       type: "started",
       jobId: jobId ?? request.id,
       totalChunks
-    };
-    await emit(startEvent);
+    });
     try {
       await ensureSchema(sql.data, dimensions);
       const needsBatching = Boolean(writer || onProgress);
       const batchSize = this._progressBatchSize ?? (needsBatching ? 1 : rows.length || 1);
+      await clearDocument(sql.data, request.id, namespace);
       let processed = 0;
       for (let offset = 0; offset < rows.length; offset += batchSize) {
         if (writer && jobId) {
@@ -19014,37 +19027,33 @@ var RagPipeline = class {
           }
         }
         const slice = rows.slice(offset, offset + batchSize);
-        await ingestDocument(sql.data, request.id, namespace, slice);
+        await ingestDocument(sql.data, slice);
         processed += slice.length;
-        const progressEvent = {
+        const currentDocument = {
+          source: request.id,
+          ordinal: processed - 1
+        };
+        await onProgress?.({
           type: "progress",
           jobId: jobId ?? request.id,
           processedChunks: processed,
           totalChunks,
-          currentDocument: {
-            source: request.id,
-            ordinal: processed - 1
-          }
-        };
-        await emit(progressEvent);
+          currentDocument
+        });
         if (writer && jobId) {
           await writer.progress({
             jobId,
             processedChunks: processed,
             totalChunks,
-            currentDocument: {
-              source: request.id,
-              ordinal: processed - 1
-            }
+            currentDocument
           });
         }
       }
-      const completedEvent = {
+      await onProgress?.({
         type: "completed",
         jobId: jobId ?? request.id,
         totalChunks
-      };
-      await emit(completedEvent);
+      });
       if (writer && jobId) await writer.complete({
         jobId,
         totalChunks
@@ -19055,12 +19064,11 @@ var RagPipeline = class {
       });
     } catch (cause) {
       const mapped = toRagError(cause, "Ingest failed");
-      const failedEvent = {
+      await onProgress?.({
         type: "failed",
         jobId: jobId ?? request.id,
         error: mapped.message
-      };
-      await emit(failedEvent);
+      });
       if (writer && jobId) await writer.fail({
         jobId,
         error: mapped.message
@@ -19220,37 +19228,6 @@ function validateIngest(request, hasEmbedder) {
   return ok(true);
 }
 __name(validateIngest, "validateIngest");
-function isTaggedError(cause) {
-  return cause instanceof Error;
-}
-__name(isTaggedError, "isTaggedError");
-function toRagError(cause, message) {
-  if (isTaggedError(cause) && cause.code === PG_UNDEFINED_TABLE) {
-    return {
-      code: "rag_schema_missing",
-      message: `RAG tables are not installed \u2014 ${RAG_SCHEMA_MISSING_HINT}.`,
-      cause,
-      meta: {
-        hint: RAG_SCHEMA_MISSING_HINT
-      }
-    };
-  }
-  if (isTaggedError(cause)) {
-    const error48 = {
-      code: cause.code ?? "rag_error",
-      message: `${message}: ${cause.message}`,
-      cause
-    };
-    if (cause.meta) error48.meta = cause.meta;
-    return error48;
-  }
-  return {
-    code: "rag_error",
-    message,
-    cause
-  };
-}
-__name(toRagError, "toRagError");
 
 // src/modules/rag/rag.ts
 var DEFAULT_BATCH_SIZE4 = 128;
@@ -19262,10 +19239,14 @@ var RagModule = class {
   _resolved;
   _getAi;
   _gate;
-  constructor(_resolved, _getAi, gate) {
+  _testSqlOverride;
+  _testJobWriterFactory;
+  constructor(_resolved, _getAi, gate, testDeps) {
     this._resolved = _resolved;
     this._getAi = _getAi;
     this._gate = gate ?? createModuleGate("rag", _resolved);
+    if (testDeps?.sqlProvider) this._testSqlOverride = testDeps.sqlProvider;
+    if (testDeps?.jobWriterFactory) this._testJobWriterFactory = testDeps.jobWriterFactory;
   }
   async ingest(request) {
     const gateResult = await this._gate();
@@ -19298,7 +19279,8 @@ var RagModule = class {
     if (gateResult.error) return err(gateResult.error);
     const sql = this._testSqlOverride ? this._testSqlOverride() : this.sql();
     if (sql.error) return err(sql.error);
-    const writer = this._testJobWriter ?? createSqlJobWriter(sql.data);
+    const writerFactory = this._testJobWriterFactory ?? createSqlJobWriter;
+    const writer = writerFactory(sql.data);
     const channel = createProgressChannel();
     const resolved = resolveIngestModel(request, this._resolved);
     const requestWithHook = {
@@ -19329,7 +19311,7 @@ var RagModule = class {
       return r;
     }).catch((cause) => {
       channel.close();
-      return err(toRagError2(cause, "Ingest failed"));
+      return err(toRagError(cause, "Ingest failed"));
     });
     return ok({
       jobId,
@@ -19337,10 +19319,6 @@ var RagModule = class {
       result
     });
   }
-  /** Test-only seam — assigned by `ingest-async.spec.ts`. */
-  _testJobWriter;
-  /** Test-only seam — assigned by `ingest-async.spec.ts`. */
-  _testSqlOverride;
   async delete(ids, options) {
     const gateResult = await this._gate();
     if (gateResult.error) return err(gateResult.error);
@@ -19372,7 +19350,7 @@ var RagModule = class {
       await reset(sql.data);
       return ok(void 0);
     } catch (cause) {
-      return err(toRagError2(cause, "Reset failed"));
+      return err(toRagError(cause, "Reset failed"));
     }
   }
   /**
@@ -19400,22 +19378,18 @@ var RagModule = class {
   * `Result.err` with the same `database_not_configured` shape `client.database`
   * raises, instead of throwing through the public surface.
   */
-  // `_resolved` is reserved for future per-config overrides (e.g. routing
-  // RAG queries through a logical replica). The URL itself is owned by the
-  // shared handle.
   sql() {
-    void this._resolved;
     try {
       return ok(getDatabaseHandle().$client);
     } catch (cause) {
-      if (isTaggedError2(cause) && cause.code === "database_not_configured") {
+      if (isTaggedError(cause) && cause.code === "database_not_configured") {
         return err({
           code: "database_not_configured",
           message: cause.message,
           cause
         });
       }
-      return err(toRagError2(cause, "Database handle unavailable"));
+      return err(toRagError(cause, "Database handle unavailable"));
     }
   }
   async withPipeline(embedder, run) {
@@ -19536,27 +19510,6 @@ function resolveRetrieveModel(request, resolved) {
   };
 }
 __name(resolveRetrieveModel, "resolveRetrieveModel");
-function isTaggedError2(cause) {
-  return cause instanceof Error;
-}
-__name(isTaggedError2, "isTaggedError");
-function toRagError2(cause, message) {
-  if (isTaggedError2(cause)) {
-    const error48 = {
-      code: cause.code ?? "rag_error",
-      message: `${message}: ${cause.message}`,
-      cause
-    };
-    if (cause.meta) error48.meta = cause.meta;
-    return error48;
-  }
-  return {
-    code: "rag_error",
-    message,
-    cause
-  };
-}
-__name(toRagError2, "toRagError");
 var DEFAULT_SIGNED_URL_TTL_SECONDS = 3600;
 var StorageModule = class {
   static {
@@ -19573,11 +19526,12 @@ var StorageModule = class {
     return new StorageBucket(bucket, () => this.settings(), this._gate);
   }
   settings() {
-    const accessKeyId = this._resolved.config.s3?.accessKeyId ?? this._resolved.env["AWS_ACCESS_KEY_ID"];
-    const secretAccessKey = this._resolved.config.s3?.secretAccessKey ?? this._resolved.env["AWS_SECRET_ACCESS_KEY"];
-    const endpoint = this._resolved.config.s3?.endpoint ?? this._resolved.env["S3_ENDPOINT"];
-    const bucket = this._resolved.config.s3?.bucket ?? this._resolved.env["S3_BUCKET"];
+    const accessKeyId = this._resolved.config.s3?.accessKeyId ?? this._resolved.env["STACKBONE_S3_ACCESS_KEY"];
+    const secretAccessKey = this._resolved.config.s3?.secretAccessKey ?? this._resolved.env["STACKBONE_S3_SECRET_KEY"];
+    const endpoint = this._resolved.config.s3?.endpoint ?? this._resolved.env["STACKBONE_S3_ENDPOINT"];
+    const bucket = this._resolved.config.s3?.bucket ?? this._resolved.env["STACKBONE_S3_BUCKET"];
     const agentId = this._resolved.config.agentId ?? this._resolved.env["STACKBONE_AGENT_ID"];
+    const region = this._resolved.config.s3?.region ?? this._resolved.env["STACKBONE_S3_REGION"] ?? "auto";
     if (!accessKeyId || !secretAccessKey || !endpoint) {
       return err({
         code: "s3_credentials_missing",
@@ -19598,7 +19552,7 @@ var StorageModule = class {
     }
     this._s3 ??= new S3Client({
       endpoint,
-      region: "auto",
+      region,
       forcePathStyle: true,
       credentials: {
         accessKeyId,
@@ -19757,29 +19711,19 @@ var StorageBucket = class {
     return ok(`${base}/${bucket}/${encodeS3Key(fullKey)}`);
   }
   async getSignedUploadUrl(key, options) {
-    const gateResult = await this.gate();
-    if (gateResult.error) return err(gateResult.error);
-    const resolved = this.resolve(key);
-    if (resolved.error) return err(resolved.error);
-    const { client, bucket, fullKey } = resolved.data;
-    const expiresIn = options?.expiresIn ?? DEFAULT_SIGNED_URL_TTL_SECONDS;
-    try {
-      const url2 = await getSignedUrl(client, new PutObjectCommand({
-        Bucket: bucket,
-        Key: fullKey,
-        ContentType: options?.contentType
-      }), {
-        expiresIn
-      });
-      return ok({
-        url: url2,
-        expiresAt: new Date(Date.now() + expiresIn * 1e3)
-      });
-    } catch (cause) {
-      return err(toStorageError("Signing upload URL failed", cause));
-    }
+    return this.signUrl(key, options, "Signing upload URL failed", ({ bucket, fullKey }) => new PutObjectCommand({
+      Bucket: bucket,
+      Key: fullKey,
+      ContentType: options?.contentType
+    }));
   }
   async getSignedDownloadUrl(key, options) {
+    return this.signUrl(key, options, "Signing download URL failed", ({ bucket, fullKey }) => new GetObjectCommand({
+      Bucket: bucket,
+      Key: fullKey
+    }));
+  }
+  async signUrl(key, options, failureMessage, buildCommand) {
     const gateResult = await this.gate();
     if (gateResult.error) return err(gateResult.error);
     const resolved = this.resolve(key);
@@ -19787,9 +19731,9 @@ var StorageBucket = class {
     const { client, bucket, fullKey } = resolved.data;
     const expiresIn = options?.expiresIn ?? DEFAULT_SIGNED_URL_TTL_SECONDS;
     try {
-      const url2 = await getSignedUrl(client, new GetObjectCommand({
-        Bucket: bucket,
-        Key: fullKey
+      const url2 = await getSignedUrl(client, buildCommand({
+        bucket,
+        fullKey
       }), {
         expiresIn
       });
@@ -19798,7 +19742,7 @@ var StorageBucket = class {
         expiresAt: new Date(Date.now() + expiresIn * 1e3)
       });
     } catch (cause) {
-      return err(toStorageError("Signing download URL failed", cause));
+      return err(toStorageError(failureMessage, cause));
     }
   }
   /**
@@ -19824,8 +19768,8 @@ var StorageBucket = class {
     });
   }
 };
-var S3_CREDENTIALS_MISSING_MESSAGE = "Cannot reach object storage \u2014 set `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `S3_ENDPOINT` in the container or pass `s3` to `createClient({...})`.";
-var S3_BUCKET_MISSING_MESSAGE = "No storage bucket configured \u2014 set `S3_BUCKET` in the container or pass `s3.bucket` to `createClient({...})`.";
+var S3_CREDENTIALS_MISSING_MESSAGE = "Cannot reach object storage \u2014 set `STACKBONE_S3_ACCESS_KEY`, `STACKBONE_S3_SECRET_KEY`, and `STACKBONE_S3_ENDPOINT` in the container or pass `s3` to `createClient({...})`.";
+var S3_BUCKET_MISSING_MESSAGE = "No storage bucket configured \u2014 set `STACKBONE_S3_BUCKET` in the container or pass `s3.bucket` to `createClient({...})`.";
 var AGENT_ID_MISSING_MESSAGE = "No agent identity configured \u2014 set `STACKBONE_AGENT_ID` in the container or pass `agentId` to `createClient({...})`.";
 function stripEtag(etag) {
   return etag?.replace(/^"|"$/g, "");