@jskit-ai/assistant-runtime 0.1.3 → 0.1.4

package/package.descriptor.mjs

@@ -1,7 +1,7 @@
 export default Object.freeze({
   packageVersion: 1,
   packageId: "@jskit-ai/assistant-runtime",
-  version: "0.1.3",
+  version: "0.1.4",
   kind: "runtime",
   description: "Shared assistant runtime with per-surface assistant registration.",
   dependsOn: [
@@ -74,13 +74,13 @@ export default Object.freeze({
   mutations: {
     dependencies: {
       runtime: {
-        "@jskit-ai/assistant-core": "0.1.8",
-        "@jskit-ai/database-runtime": "0.1.32",
-        "@jskit-ai/http-runtime": "0.1.31",
-        "@jskit-ai/kernel": "0.1.32",
-        "@jskit-ai/shell-web": "0.1.31",
-        "@jskit-ai/users-core": "0.1.42",
-        "@jskit-ai/users-web": "0.1.47",
+        "@jskit-ai/assistant-core": "0.1.9",
+        "@jskit-ai/database-runtime": "0.1.33",
+        "@jskit-ai/http-runtime": "0.1.32",
+        "@jskit-ai/kernel": "0.1.33",
+        "@jskit-ai/shell-web": "0.1.32",
+        "@jskit-ai/users-core": "0.1.43",
+        "@jskit-ai/users-web": "0.1.48",
         "@tanstack/vue-query": "^5.90.5",
         "vuetify": "^4.0.0"
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/assistant-runtime",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "type": "module",
   "exports": {
     "./client": "./src/client/index.js",
@@ -8,13 +8,13 @@
     "./server/actionIds": "./src/server/actionIds.js"
   },
   "dependencies": {
-    "@jskit-ai/assistant-core": "0.1.8",
-    "@jskit-ai/database-runtime": "0.1.32",
-    "@jskit-ai/http-runtime": "0.1.31",
-    "@jskit-ai/kernel": "0.1.32",
-    "@jskit-ai/shell-web": "0.1.31",
-    "@jskit-ai/users-core": "0.1.42",
-    "@jskit-ai/users-web": "0.1.47",
+    "@jskit-ai/assistant-core": "0.1.9",
+    "@jskit-ai/database-runtime": "0.1.33",
+    "@jskit-ai/http-runtime": "0.1.32",
+    "@jskit-ai/kernel": "0.1.33",
+    "@jskit-ai/shell-web": "0.1.32",
+    "@jskit-ai/users-core": "0.1.43",
+    "@jskit-ai/users-web": "0.1.48",
     "@tanstack/vue-query": "^5.90.5",
     "vuetify": "^4.0.0"
   }

package/src/client/components/AssistantSettingsClientElement.vue

@@ -25,7 +25,7 @@
 import { computed, reactive, watch } from "vue";
 import { useMutation, useQuery, useQueryClient } from "@tanstack/vue-query";
 import { getClientAppConfig } from "@jskit-ai/kernel/client";
-import { normalizeObject, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+import { normalizeObject, normalizeRecordId, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
 import { validateOperationSection } from "@jskit-ai/http-runtime/shared/validators/operationValidation";
 import { assistantHttpClient, createAssistantApi, AssistantSettingsFormCard } from "@jskit-ai/assistant-core/client";
 import { assistantConfigResource, assistantSettingsQueryKey, buildAssistantApiPath } from "@jskit-ai/assistant-core/shared";
@@ -65,8 +65,8 @@ const scope = computed(() => {
     targetSurfaceId: normalizeText(assistantSurface.value?.targetSurfaceId).toLowerCase(),
     workspaceSlug,
     workspaceId: settingsRequiresWorkspace
-      ? Number(placementSnapshot.value?.workspace?.id || 0) || 0
-      : 0
+      ? normalizeRecordId(placementSnapshot.value?.workspace?.id, { fallback: null })
+      : null
   };
 });
 const hasScope = computed(() =>

package/src/client/composables/useAssistantRuntime.js

@@ -1,7 +1,7 @@
 import { computed, ref, watch } from "vue";
 import { useQueryClient } from "@tanstack/vue-query";
 import { getClientAppConfig } from "@jskit-ai/kernel/client";
-import { normalizeObject, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+import { normalizeObject, normalizeRecordId, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
 import { buildAssistantApiPath } from "@jskit-ai/assistant-core/shared";
 import {
   ASSISTANT_STREAM_EVENT_TYPES,
@@ -47,13 +47,13 @@ function buildScopeStorageKey(scope = {}) {
 
 function readStoredActiveConversationId(scope = {}) {
   if (typeof window === "undefined" || !window.sessionStorage) {
-    return 0;
+    return "";
   }
 
   try {
-    return toPositiveInteger(window.sessionStorage.getItem(buildScopeStorageKey(scope)), 0);
+    return normalizeRecordId(window.sessionStorage.getItem(buildScopeStorageKey(scope)), { fallback: "" });
   } catch {
-    return 0;
+    return "";
   }
 }
 
@@ -62,11 +62,11 @@ function writeStoredActiveConversationId(scope = {}, conversationId) {
     return;
   }
 
-  const normalizedConversationId = toPositiveInteger(conversationId, 0);
+  const normalizedConversationId = normalizeRecordId(conversationId, { fallback: null });
   const storageKey = buildScopeStorageKey(scope);
   try {
-    if (normalizedConversationId > 0) {
-      window.sessionStorage.setItem(storageKey, String(normalizedConversationId));
+    if (normalizedConversationId) {
+      window.sessionStorage.setItem(storageKey, normalizedConversationId);
       return;
     }
 
@@ -164,7 +164,8 @@ function mapTranscriptEntriesToAssistantState(entries) {
     const role = normalizeText(entry?.role).toLowerCase();
     const kind = normalizeText(entry?.kind).toLowerCase();
     const metadata = normalizeObject(entry?.metadata);
-    const messageId = Number(entry?.id) > 0 ? `transcript_${entry.id}` : buildId("transcript");
+    const transcriptId = normalizeRecordId(entry?.id, { fallback: null });
+    const messageId = transcriptId ? `transcript_${transcriptId}` : buildId("transcript");
 
     if (kind === "chat" && (role === "user" || role === "assistant")) {
       messages.push({
@@ -258,8 +259,8 @@ function useAssistantRuntime({ api = null, surfaceId = "" } = {}) {
       targetSurfaceId: normalizeText(assistantSurface.value?.targetSurfaceId).toLowerCase(),
       workspaceSlug,
       workspaceId: assistantSurface.value?.runtimeSurfaceRequiresWorkspace
-        ? toPositiveInteger(placementSnapshot.value?.workspace?.id, 0)
-        : 0
+        ? normalizeRecordId(placementSnapshot.value?.workspace?.id, { fallback: null })
+        : null
     };
   });
   const hasRuntimeScope = computed(() =>
@@ -278,7 +279,7 @@ function useAssistantRuntime({ api = null, surfaceId = "" } = {}) {
     resolveSurfaceId: () => normalizeText(currentSurfaceId.value).toLowerCase()
   });
 
-  const activeConversationId = computed(() => normalizeText(conversationId.value));
+  const activeConversationId = computed(() => normalizeRecordId(conversationId.value, { fallback: "" }));
   const isAdminSurface = computed(() => normalizeText(currentSurfaceId.value).toLowerCase() === "admin");
   const canSend = computed(() => {
     return Boolean(
@@ -320,8 +321,7 @@ function useAssistantRuntime({ api = null, surfaceId = "" } = {}) {
       }),
     initialPageParam: null,
     dedupeBy(entry) {
-      const conversationNumericId = toPositiveInteger(entry?.id, 0);
-      return conversationNumericId > 0 ? String(conversationNumericId) : normalizeText(entry?.id);
+      return normalizeRecordId(entry?.id, { fallback: normalizeText(entry?.id) });
     },
     enabled: computed(() => hasRuntimeScope.value),
     queryOptions: {
@@ -345,15 +345,15 @@ function useAssistantRuntime({ api = null, surfaceId = "" } = {}) {
       return;
     }
 
-    const nextConversationNumericId = toPositiveInteger(nextConversationId, 0);
-    if (nextConversationNumericId > 0) {
-      writeStoredActiveConversationId(runtimeScope.value, nextConversationNumericId);
+    const nextConversationIdKey = normalizeRecordId(nextConversationId, { fallback: null });
+    if (nextConversationIdKey) {
+      writeStoredActiveConversationId(runtimeScope.value, nextConversationIdKey);
       return;
     }
 
-    const previousConversationNumericId = toPositiveInteger(previousConversationId, 0);
-    if (previousConversationNumericId > 0) {
-      writeStoredActiveConversationId(runtimeScope.value, 0);
+    const previousConversationIdKey = normalizeRecordId(previousConversationId, { fallback: null });
+    if (previousConversationIdKey) {
+      writeStoredActiveConversationId(runtimeScope.value, "");
     }
   });
 
@@ -378,8 +378,8 @@ function useAssistantRuntime({ api = null, surfaceId = "" } = {}) {
         return;
       }
 
-      const activeConversationNumericId = toPositiveInteger(nextConversationId, 0);
-      if (activeConversationNumericId > 0) {
+      const activeConversationIdKey = normalizeRecordId(nextConversationId, { fallback: null });
+      if (activeConversationIdKey) {
         return;
       }
 
@@ -394,10 +394,10 @@ function useAssistantRuntime({ api = null, surfaceId = "" } = {}) {
       }
 
       const hasStoredConversation = sourceEntries.some(
-        (entry) => toPositiveInteger(entry?.id, 0) === storedConversationId
+        (entry) => normalizeRecordId(entry?.id, { fallback: null }) === storedConversationId
       );
       if (!hasStoredConversation) {
-        writeStoredActiveConversationId(nextRuntimeScope, 0);
+        writeStoredActiveConversationId(nextRuntimeScope, "");
         return;
       }
 
@@ -458,13 +458,13 @@ function useAssistantRuntime({ api = null, surfaceId = "" } = {}) {
       return;
     }
 
-    const parsedConversationId = toPositiveInteger(normalizedConversationId, 0);
+    const parsedConversationId = normalizeRecordId(normalizedConversationId, { fallback: null });
     if (!parsedConversationId) {
       return;
     }
 
     const previousConversationId = conversationId.value;
-    conversationId.value = String(parsedConversationId);
+    conversationId.value = parsedConversationId;
     isRestoringConversation.value = true;
     setRuntimeError("");
 
@@ -507,7 +507,7 @@ function useAssistantRuntime({ api = null, surfaceId = "" } = {}) {
     input.value = "";
     setRuntimeError("");
     conversationId.value = null;
-    writeStoredActiveConversationId(runtimeScope.value, 0);
+    writeStoredActiveConversationId(runtimeScope.value, "");
     isStreaming.value = false;
     isRestoringConversation.value = false;
     abortController.value = null;
@@ -546,7 +546,7 @@ function useAssistantRuntime({ api = null, surfaceId = "" } = {}) {
     const messageId = buildId("message");
     const assistantMessageId = buildId("assistant");
     const history = buildHistory(messages.value);
-    const parsedConversationId = toPositiveInteger(conversationId.value, 0);
+    const parsedConversationId = normalizeRecordId(conversationId.value, { fallback: null });
 
     appendMessage({
       id: buildId("user"),
@@ -581,7 +581,7 @@ function useAssistantRuntime({ api = null, surfaceId = "" } = {}) {
       await runtimeApi.streamChat(
         {
           messageId,
-          ...(parsedConversationId > 0 ? { conversationId: parsedConversationId } : {}),
+          ...(parsedConversationId ? { conversationId: parsedConversationId } : {}),
           input: normalizedInput,
           history
         },
@@ -591,7 +591,7 @@ function useAssistantRuntime({ api = null, surfaceId = "" } = {}) {
             const eventType = normalizeAssistantStreamEventType(event?.type, "");
 
             if (eventType === ASSISTANT_STREAM_EVENT_TYPES.META && Object.hasOwn(event || {}, "conversationId")) {
-              conversationId.value = event?.conversationId ? String(event.conversationId) : null;
+              conversationId.value = normalizeRecordId(event?.conversationId, { fallback: null });
               return;
             }
 

package/src/server/repositories/assistantConfigRepository.js

@@ -1,6 +1,6 @@
-import { parsePositiveInteger } from "@jskit-ai/kernel/server/runtime";
+import { normalizeDbRecordId, createWithTransaction } from "@jskit-ai/database-runtime/shared";
 import { normalizeSurfaceId } from "@jskit-ai/kernel/shared/surface/registry";
-import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+import { normalizeRecordId, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
 import { resolveInsertedId } from "@jskit-ai/assistant-core/server";
 import { assistantRuntimeConfig } from "../../shared/assistantRuntimeConfig.js";
 
@@ -9,7 +9,11 @@ function normalizeTargetSurfaceId(value = "") {
 }
 
 function normalizeWorkspaceId(value) {
-  return parsePositiveInteger(value) || null;
+  return normalizeRecordId(value, { fallback: null });
+}
+
+function normalizeWorkspaceDbId(value) {
+  return normalizeDbRecordId(value, { fallback: null });
 }
 
 function buildScopeKey(targetSurfaceId, workspaceId = null) {
@@ -29,7 +33,7 @@ function mapConfigRow(row = {}) {
   return {
     targetSurfaceId: normalizeTargetSurfaceId(row.target_surface_id),
     scopeKey: normalizeText(row.scope_key),
-    workspaceId: normalizeWorkspaceId(row.workspace_id),
+    workspaceId: normalizeWorkspaceDbId(row.workspace_id),
     settings: {
       systemPrompt: String(row.system_prompt || "")
     }
@@ -57,6 +61,7 @@ function createRepository(knex) {
   if (!knex || typeof knex !== "function") {
     throw new Error("createAssistantConfigRepository requires knex client.");
   }
+  const withTransaction = createWithTransaction(knex);
 
   async function findByScope({ targetSurfaceId = "", workspaceId = null } = {}, options = {}) {
     const client = options?.trx || knex;
@@ -139,6 +144,7 @@ function createRepository(knex) {
   }
 
   return Object.freeze({
+    withTransaction,
     createDefaultRecord,
     findByScope,
     upsertByScope

package/src/server/repositories/conversationsRepository.js

@@ -1,7 +1,6 @@
-import { runInTransaction } from "@jskit-ai/database-runtime/shared/repositoryOptions";
-import { parsePositiveInteger } from "@jskit-ai/kernel/server/runtime";
+import { createWithTransaction, normalizeDbRecordId, runInTransaction } from "@jskit-ai/database-runtime/shared/repositoryOptions";
 import { normalizeSurfaceId } from "@jskit-ai/kernel/shared/surface/registry";
-import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+import { normalizeRecordId, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
 import {
   parseJsonObject,
   resolveInsertedId,
@@ -11,7 +10,15 @@ import {
 import { assistantRuntimeConfig } from "../../shared/assistantRuntimeConfig.js";
 
 function normalizeWorkspaceId(value) {
-  return parsePositiveInteger(value) || null;
+  return normalizeRecordId(value, { fallback: null });
+}
+
+function normalizeDbWorkspaceId(value) {
+  return normalizeDbRecordId(value, { fallback: null });
+}
+
+function normalizeInputRecordId(value) {
+  return normalizeRecordId(value, { fallback: null });
 }
 
 function normalizeRequiredSurfaceId(value) {
@@ -34,10 +41,10 @@ function applyWorkspaceScope(query, columnName, workspaceId) {
 
 function mapConversationRow(row = {}) {
   return {
-    id: Number(row.id),
-    workspaceId: normalizeWorkspaceId(row.workspace_id),
+    id: normalizeDbRecordId(row.id, { fallback: "" }),
+    workspaceId: normalizeDbWorkspaceId(row.workspace_id),
     title: String(row.title || "New conversation"),
-    createdByUserId: row.created_by_user_id == null ? null : Number(row.created_by_user_id),
+    createdByUserId: row.created_by_user_id == null ? null : normalizeDbRecordId(row.created_by_user_id, { fallback: null }),
     status: String(row.status || "active"),
     provider: String(row.provider || ""),
     model: String(row.model || ""),
@@ -52,8 +59,11 @@ function mapConversationRow(row = {}) {
 }
 
 function normalizeCursorPagination(pagination = {}, { defaultLimit = 20, maxLimit = 200 } = {}) {
-  const cursor = parsePositiveInteger(pagination.cursor) || 0;
-  const limit = Math.max(1, Math.min(maxLimit, parsePositiveInteger(pagination.limit) || defaultLimit));
+  const cursor = normalizeInputRecordId(pagination.cursor) || "";
+  const parsedLimit = Number(pagination.limit);
+  const limit = Number.isInteger(parsedLimit) && parsedLimit > 0
+    ? Math.max(1, Math.min(maxLimit, parsedLimit))
+    : defaultLimit;
 
   return {
     cursor,
@@ -69,16 +79,17 @@ function createRepository(knex) {
   if (!knex || typeof knex !== "function") {
     throw new Error("createConversationsRepository requires knex client.");
   }
+  const withTransaction = createWithTransaction(knex);
 
   async function findById(conversationId, options = {}) {
-    const numericConversationId = parsePositiveInteger(conversationId);
-    if (!numericConversationId) {
+    const normalizedConversationId = normalizeInputRecordId(conversationId);
+    if (!normalizedConversationId) {
       return null;
     }
 
     const client = options?.trx || knex;
     const row = await createConversationBaseQuery(client)
-      .where("c.id", numericConversationId)
+      .where("c.id", normalizedConversationId)
       .first();
 
     return row ? mapConversationRow(row) : null;
@@ -89,17 +100,17 @@ function createRepository(knex) {
     { workspaceId = null, actorUserId = null, surfaceId = "" } = {},
     options = {}
   ) {
-    const numericConversationId = parsePositiveInteger(conversationId);
-    const numericActorUserId = parsePositiveInteger(actorUserId);
+    const normalizedConversationId = normalizeInputRecordId(conversationId);
+    const normalizedActorUserId = normalizeInputRecordId(actorUserId);
     const normalizedSurfaceId = normalizeSurfaceId(surfaceId);
-    if (!numericConversationId || !numericActorUserId || !normalizedSurfaceId) {
+    if (!normalizedConversationId || !normalizedActorUserId || !normalizedSurfaceId) {
       return null;
     }
 
     const client = options?.trx || knex;
     const query = createConversationBaseQuery(client)
-      .where("c.id", numericConversationId)
-      .where("c.created_by_user_id", numericActorUserId)
+      .where("c.id", normalizedConversationId)
+      .where("c.created_by_user_id", normalizedActorUserId)
       .where("c.surface_id", normalizedSurfaceId);
     applyWorkspaceScope(query, "c.workspace_id", workspaceId);
     const row = await query.first();
@@ -113,13 +124,13 @@ function createRepository(knex) {
     const surfaceId = normalizeRequiredSurfaceId(payload.surfaceId);
     const insertResult = await client(assistantRuntimeConfig.conversationsTable).insert({
       workspace_id: normalizeWorkspaceId(payload.workspaceId),
-      created_by_user_id: parsePositiveInteger(payload.createdByUserId) || null,
+      created_by_user_id: normalizeInputRecordId(payload.createdByUserId),
       title: normalizeText(payload.title) || "New conversation",
       status: normalizeText(payload.status).toLowerCase() || "active",
       provider: normalizeText(payload.provider),
       model: normalizeText(payload.model),
       surface_id: surfaceId,
-      message_count: parsePositiveInteger(payload.messageCount) || 0,
+      message_count: Math.max(0, Number(payload.messageCount || 0)),
       metadata_json: stringifyJsonObject(payload.metadata),
       started_at: payload.startedAt ? new Date(payload.startedAt) : now,
       ended_at: payload.endedAt ? new Date(payload.endedAt) : null,
@@ -137,8 +148,8 @@ function createRepository(knex) {
   }
 
   async function updateById(conversationId, patch = {}, options = {}) {
-    const numericConversationId = parsePositiveInteger(conversationId);
-    if (!numericConversationId) {
+    const normalizedConversationId = normalizeInputRecordId(conversationId);
+    if (!normalizedConversationId) {
       return null;
     }
 
@@ -173,31 +184,31 @@ function createRepository(knex) {
     if (Object.keys(updatePatch).length > 0) {
       updatePatch.updated_at = new Date();
       await client(assistantRuntimeConfig.conversationsTable)
-        .where({ id: numericConversationId })
+        .where({ id: normalizedConversationId })
         .update(updatePatch);
     }
 
-    return findById(numericConversationId, {
+    return findById(normalizedConversationId, {
       trx: client
     });
   }
 
   async function incrementMessageCount(conversationId, delta = 1, options = {}) {
-    const numericConversationId = parsePositiveInteger(conversationId);
-    if (!numericConversationId) {
+    const normalizedConversationId = normalizeInputRecordId(conversationId);
+    if (!normalizedConversationId) {
       return null;
     }
 
     const client = options?.trx || knex;
     const incrementBy = Number.isInteger(Number(delta)) ? Number(delta) : 1;
     await client(assistantRuntimeConfig.conversationsTable)
-      .where({ id: numericConversationId })
+      .where({ id: normalizedConversationId })
       .update({
         message_count: client.raw("GREATEST(0, message_count + ?)", [incrementBy]),
         updated_at: new Date()
       });
 
-    return findById(numericConversationId, {
+    return findById(normalizedConversationId, {
       trx: client
     });
   }
@@ -206,9 +217,9 @@ function createRepository(knex) {
     { workspaceId = null, actorUserId = null, surfaceId = "", pagination = {}, filters = {} } = {},
     options = {}
   ) {
-    const numericActorUserId = parsePositiveInteger(actorUserId);
+    const normalizedActorUserId = normalizeInputRecordId(actorUserId);
     const normalizedSurfaceId = normalizeSurfaceId(surfaceId);
-    if (!numericActorUserId || !normalizedSurfaceId) {
+    if (!normalizedActorUserId || !normalizedSurfaceId) {
       return {
         items: [],
         nextCursor: null
@@ -218,7 +229,7 @@ function createRepository(knex) {
     const client = options?.trx || knex;
     const { cursor, limit } = normalizeCursorPagination(pagination);
     let query = createConversationBaseQuery(client)
-      .where("c.created_by_user_id", numericActorUserId)
+      .where("c.created_by_user_id", normalizedActorUserId)
       .where("c.surface_id", normalizedSurfaceId);
     query = applyWorkspaceScope(query, "c.workspace_id", workspaceId);
 
@@ -226,7 +237,7 @@ function createRepository(knex) {
     if (normalizedStatus) {
       query = query.where("c.status", normalizedStatus);
     }
-    if (cursor > 0) {
+    if (cursor) {
       query = query.where("c.id", "<", cursor);
     }
 
@@ -237,7 +248,9 @@ function createRepository(knex) {
     const hasMore = rows.length > limit;
     const pageRows = hasMore ? rows.slice(0, limit) : rows;
     const items = pageRows.map(mapConversationRow);
-    const nextCursor = hasMore && pageRows.length > 0 ? String(pageRows[pageRows.length - 1].id) : null;
+    const nextCursor = hasMore && pageRows.length > 0
+      ? normalizeDbRecordId(pageRows[pageRows.length - 1].id, { fallback: null })
+      : null;
 
     return {
       items,
@@ -250,6 +263,7 @@ function createRepository(knex) {
   }
 
   return Object.freeze({
+    withTransaction,
     findById,
     findByIdForActorScope,
     create,

package/src/server/repositories/messagesRepository.js

@@ -1,6 +1,5 @@
-import { runInTransaction } from "@jskit-ai/database-runtime/shared/repositoryOptions";
-import { parsePositiveInteger } from "@jskit-ai/kernel/server/runtime";
-import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+import { createWithTransaction, normalizeDbRecordId, runInTransaction } from "@jskit-ai/database-runtime/shared/repositoryOptions";
+import { normalizeRecordId, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
 import {
   parseJsonObject,
   resolveInsertedId,
@@ -10,7 +9,15 @@ import {
 import { assistantRuntimeConfig } from "../../shared/assistantRuntimeConfig.js";
 
 function normalizeWorkspaceId(value) {
-  return parsePositiveInteger(value) || null;
+  return normalizeRecordId(value, { fallback: null });
+}
+
+function normalizeDbWorkspaceId(value) {
+  return normalizeDbRecordId(value, { fallback: null });
+}
+
+function normalizeInputRecordId(value) {
+  return normalizeRecordId(value, { fallback: null });
 }
 
 function applyWorkspaceScope(query, columnName, workspaceId) {
@@ -24,14 +31,14 @@ function applyWorkspaceScope(query, columnName, workspaceId) {
 
 function mapMessageRow(row = {}) {
   return {
-    id: Number(row.id),
-    conversationId: Number(row.conversation_id),
-    workspaceId: normalizeWorkspaceId(row.workspace_id),
+    id: normalizeDbRecordId(row.id, { fallback: "" }),
+    conversationId: normalizeDbRecordId(row.conversation_id, { fallback: "" }),
+    workspaceId: normalizeDbWorkspaceId(row.workspace_id),
     seq: Number(row.seq),
     role: String(row.role || ""),
     kind: String(row.kind || "chat"),
     clientMessageSid: String(row.client_message_sid || ""),
-    actorUserId: row.actor_user_id == null ? null : Number(row.actor_user_id),
+    actorUserId: row.actor_user_id == null ? null : normalizeDbRecordId(row.actor_user_id, { fallback: null }),
     contentText: row.content_text == null ? null : String(row.content_text),
     metadata: parseJsonObject(row.metadata_json),
     createdAt: toIso(row.created_at)
@@ -39,8 +46,12 @@ function mapMessageRow(row = {}) {
 }
 
 function normalizePagination(pagination = {}, { defaultPage = 1, defaultPageSize = 200, maxPageSize = 500 } = {}) {
-  const page = Math.max(1, parsePositiveInteger(pagination.page) || defaultPage);
-  const pageSize = Math.max(1, Math.min(maxPageSize, parsePositiveInteger(pagination.pageSize) || defaultPageSize));
+  const rawPage = Number(pagination.page);
+  const rawPageSize = Number(pagination.pageSize);
+  const page = Number.isInteger(rawPage) && rawPage > 0 ? rawPage : defaultPage;
+  const pageSize = Number.isInteger(rawPageSize) && rawPageSize > 0
+    ? Math.max(1, Math.min(maxPageSize, rawPageSize))
+    : defaultPageSize;
 
   return {
     page,
@@ -65,16 +76,17 @@ function createRepository(knex) {
   if (!knex || typeof knex !== "function") {
     throw new Error("createMessagesRepository requires knex client.");
   }
+  const withTransaction = createWithTransaction(knex);
 
   async function findById(messageId, options = {}) {
-    const numericMessageId = parsePositiveInteger(messageId);
-    if (!numericMessageId) {
+    const normalizedMessageId = normalizeInputRecordId(messageId);
+    if (!normalizedMessageId) {
       return null;
     }
 
     const client = options?.trx || knex;
     const row = await client(assistantRuntimeConfig.messagesTable)
-      .where({ id: numericMessageId })
+      .where({ id: normalizedMessageId })
       .first();
 
     return row ? mapMessageRow(row) : null;
@@ -82,12 +94,13 @@ function createRepository(knex) {
 
   async function create(payload = {}, options = {}) {
     const client = options?.trx || knex;
-    const conversationId = parsePositiveInteger(payload.conversationId);
+    const conversationId = normalizeInputRecordId(payload.conversationId);
     if (!conversationId) {
       throw new TypeError("messagesRepository.create requires conversationId.");
     }
 
-    const seq = parsePositiveInteger(payload.seq) || (await resolveNextSequence(client, conversationId));
+    const providedSeq = Number(payload.seq);
+    const seq = Number.isInteger(providedSeq) && providedSeq > 0 ? providedSeq : (await resolveNextSequence(client, conversationId));
     const insertResult = await client(assistantRuntimeConfig.messagesTable).insert({
       conversation_id: conversationId,
       workspace_id: normalizeWorkspaceId(payload.workspaceId),
@@ -95,7 +108,7 @@ function createRepository(knex) {
       role: normalizeText(payload.role).toLowerCase(),
       kind: normalizeText(payload.kind).toLowerCase() || "chat",
       client_message_sid: normalizeText(payload.clientMessageSid),
-      actor_user_id: parsePositiveInteger(payload.actorUserId) || null,
+      actor_user_id: normalizeInputRecordId(payload.actorUserId),
       content_text: payload.contentText == null ? null : String(payload.contentText),
       metadata_json: stringifyJsonObject(payload.metadata),
       created_at: payload.createdAt ? new Date(payload.createdAt) : new Date()
@@ -111,14 +124,14 @@ function createRepository(knex) {
   }
 
   async function countByConversationScope(conversationId, { workspaceId = null } = {}, options = {}) {
-    const numericConversationId = parsePositiveInteger(conversationId);
-    if (!numericConversationId) {
+    const normalizedConversationId = normalizeInputRecordId(conversationId);
+    if (!normalizedConversationId) {
       return 0;
     }
 
     const client = options?.trx || knex;
     const query = client(assistantRuntimeConfig.messagesTable).where({
-      conversation_id: numericConversationId
+      conversation_id: normalizedConversationId
     });
     applyWorkspaceScope(query, "workspace_id", workspaceId);
     const row = await query.count({ total: "*" }).first();
@@ -128,8 +141,8 @@ function createRepository(knex) {
   }
 
   async function listByConversationScope(conversationId, { workspaceId = null } = {}, pagination = {}, options = {}) {
-    const numericConversationId = parsePositiveInteger(conversationId);
-    if (!numericConversationId) {
+    const normalizedConversationId = normalizeInputRecordId(conversationId);
+    if (!normalizedConversationId) {
       return [];
     }
 
@@ -138,7 +151,7 @@ function createRepository(knex) {
     const offset = (page - 1) * pageSize;
 
     const query = client(assistantRuntimeConfig.messagesTable).where({
-      conversation_id: numericConversationId
+      conversation_id: normalizedConversationId
     });
     applyWorkspaceScope(query, "workspace_id", workspaceId);
     const rows = await query
@@ -155,6 +168,7 @@ function createRepository(knex) {
   }
 
   return Object.freeze({
+    withTransaction,
     findById,
     create,
     countByConversationScope,

package/src/server/services/assistantConfigService.js

@@ -1,5 +1,5 @@
-import { AppError, parsePositiveInteger, requireAuth } from "@jskit-ai/kernel/server/runtime";
-import { normalizeObject } from "@jskit-ai/kernel/shared/support/normalize";
+import { AppError, requireAuth } from "@jskit-ai/kernel/server/runtime";
+import { normalizeObject, normalizeRecordId } from "@jskit-ai/kernel/shared/support/normalize";
 import { resolveWorkspace } from "@jskit-ai/users-core/server/support/resolveWorkspace";
 import { resolveAssistantSurfaceConfig } from "../../shared/assistantSurfaces.js";
 
@@ -64,7 +64,7 @@ function createService({ assistantConfigRepository, consoleService = null, appCo
     }
 
     const resolvedWorkspace = workspace || resolveWorkspace(context, input);
-    const workspaceId = parsePositiveInteger(resolvedWorkspace?.id);
+    const workspaceId = normalizeRecordId(resolvedWorkspace?.id, { fallback: null });
     if (!workspaceId) {
       throw new AppError(409, "Workspace selection required.");
     }

package/src/server/services/chatService.js

@@ -1,5 +1,5 @@
-import { AppError, parsePositiveInteger } from "@jskit-ai/kernel/server/runtime";
-import { normalizeObject, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+import { AppError } from "@jskit-ai/kernel/server/runtime";
+import { normalizeObject, normalizeRecordId, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
 import { resolveWorkspace } from "@jskit-ai/users-core/server/support/resolveWorkspace";
 import { resolveWorkspaceSlug } from "@jskit-ai/assistant-core/server";
 import {
@@ -12,8 +12,7 @@ const MAX_INPUT_CHARS = 8000;
 const MAX_TOOL_ROUNDS = 4;
 
 function normalizeConversationId(value) {
-  const parsed = parsePositiveInteger(value);
-  return parsed > 0 ? parsed : null;
+  return normalizeRecordId(value, { fallback: null });
 }
 
 function normalizeHistory(history = []) {

package/src/server/services/transcriptService.js

@@ -1,6 +1,6 @@
 import { AppError, parsePositiveInteger } from "@jskit-ai/kernel/server/runtime";
 import { normalizeSurfaceId } from "@jskit-ai/kernel/shared/surface/registry";
-import { normalizeObject, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+import { normalizeObject, normalizeRecordId, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
 import { normalizeConversationStatus } from "@jskit-ai/assistant-core/shared";
 
 const DEFAULT_PAGE_SIZE = 20;
@@ -11,21 +11,21 @@ const DEFAULT_CONVERSATION_TITLE = "New conversation";
 const MAX_CONVERSATION_TITLE_LENGTH = 80;
 
 function resolveWorkspaceId(workspace, { required = false } = {}) {
-  const workspaceId = parsePositiveInteger(workspace?.id || workspace);
+  const workspaceId = normalizeRecordId(workspace?.id || workspace, { fallback: null });
   if (!workspaceId && required) {
     throw new AppError(409, "Workspace selection required.");
   }
 
-  return workspaceId || null;
+  return workspaceId;
 }
 
 function resolveActorUserId(user, { required = false } = {}) {
-  const actorUserId = parsePositiveInteger(user?.id);
+  const actorUserId = normalizeRecordId(user?.id, { fallback: null });
   if (!actorUserId && required) {
     throw new AppError(401, "Authentication required.");
   }
 
-  return actorUserId || null;
+  return actorUserId;
 }
 
 function normalizePagination(pagination = {}, { defaultPageSize = DEFAULT_PAGE_SIZE, maxPageSize = MAX_PAGE_SIZE } = {}) {
@@ -39,7 +39,7 @@ function normalizePagination(pagination = {}, { defaultPageSize = DEFAULT_PAGE_S
 }
 
 function normalizeCursorPagination(query = {}, { defaultLimit = DEFAULT_PAGE_SIZE, maxLimit = MAX_PAGE_SIZE } = {}) {
-  const cursor = parsePositiveInteger(query.cursor) || 0;
+  const cursor = normalizeRecordId(query.cursor, { fallback: null });
   const limit = Math.max(1, Math.min(maxLimit, parsePositiveInteger(query.limit) || defaultLimit));
 
   return {
@@ -92,7 +92,7 @@ function createTranscriptService({ conversationsRepository, messagesRepository }
       required: true
     });
     const source = normalizeObject(options);
-    const conversationId = parsePositiveInteger(source.conversationId);
+    const conversationId = normalizeRecordId(source.conversationId, { fallback: null });
 
     if (conversationId) {
       const existing = await conversationsRepository.findByIdForActorScope(conversationId, {
@@ -143,16 +143,16 @@ function createTranscriptService({ conversationsRepository, messagesRepository }
 
   async function appendMessage(assistantSurface, conversationId, payload = {}, options = {}) {
     const resolvedAssistantSurface = requireAssistantSurface(assistantSurface);
-    const numericConversationId = parsePositiveInteger(conversationId);
-    if (!numericConversationId) {
+    const normalizedConversationId = normalizeRecordId(conversationId, { fallback: null });
+    if (!normalizedConversationId) {
       throw new TypeError("appendMessage requires conversationId.");
     }
 
     const source = normalizeObject(payload);
     const context = normalizeObject(options.context);
-    const actorUserId = parsePositiveInteger(source.actorUserId) || resolveActorUserId(context.actor);
+    const actorUserId = normalizeRecordId(source.actorUserId, { fallback: null }) || resolveActorUserId(context.actor);
     const workspaceId = resolveExpectedWorkspaceId(resolvedAssistantSurface, options.workspace || context.workspace);
-    const conversation = await conversationsRepository.findByIdForActorScope(numericConversationId, {
+    const conversation = await conversationsRepository.findByIdForActorScope(normalizedConversationId, {
       workspaceId,
       actorUserId,
       surfaceId: resolvedAssistantSurface.targetSurfaceId
@@ -162,7 +162,7 @@ function createTranscriptService({ conversationsRepository, messagesRepository }
     }
 
     const createdMessage = await messagesRepository.create({
-      conversationId: numericConversationId,
+      conversationId: normalizedConversationId,
       workspaceId: conversation.workspaceId,
       role: normalizeText(source.role).toLowerCase(),
       kind: normalizeText(source.kind).toLowerCase() || "chat",
@@ -172,29 +172,29 @@ function createTranscriptService({ conversationsRepository, messagesRepository }
       metadata: normalizeObject(source.metadata)
     });
 
-    await conversationsRepository.incrementMessageCount(numericConversationId, 1);
+    await conversationsRepository.incrementMessageCount(normalizedConversationId, 1);
 
     const messageRole = normalizeText(source.role).toLowerCase();
     const messageKind = normalizeText(source.kind).toLowerCase() || "chat";
     if (messageRole === "user" && messageKind === "chat" && isDefaultConversationTitle(conversation.title)) {
       const derivedTitle = deriveConversationTitleFromMessage(source.contentText);
       if (derivedTitle) {
-        await conversationsRepository.updateById(numericConversationId, {
+        await conversationsRepository.updateById(normalizedConversationId, {
           title: derivedTitle
         });
       }
     }
 
     return {
-      conversationId: numericConversationId,
+      conversationId: normalizedConversationId,
       message: createdMessage
     };
   }
 
   async function completeConversation(assistantSurface, conversationId, payload = {}, options = {}) {
     const resolvedAssistantSurface = requireAssistantSurface(assistantSurface);
-    const numericConversationId = parsePositiveInteger(conversationId);
-    if (!numericConversationId) {
+    const normalizedConversationId = normalizeRecordId(conversationId, { fallback: null });
+    if (!normalizedConversationId) {
       throw new TypeError("completeConversation requires conversationId.");
     }
 
@@ -204,7 +204,7 @@ function createTranscriptService({ conversationsRepository, messagesRepository }
       required: true
     });
     const workspaceId = resolveExpectedWorkspaceId(resolvedAssistantSurface, options.workspace || context.workspace);
-    const existing = await conversationsRepository.findByIdForActorScope(numericConversationId, {
+    const existing = await conversationsRepository.findByIdForActorScope(normalizedConversationId, {
       workspaceId,
       actorUserId,
       surfaceId: resolvedAssistantSurface.targetSurfaceId
@@ -213,7 +213,7 @@ function createTranscriptService({ conversationsRepository, messagesRepository }
       throw new AppError(404, "Conversation not found.");
     }
 
-    return conversationsRepository.updateById(numericConversationId, {
+    return conversationsRepository.updateById(normalizedConversationId, {
       status: normalizeConversationStatus(source.status, {
         fallback: "completed"
       }),
@@ -243,18 +243,16 @@ function createTranscriptService({ conversationsRepository, messagesRepository }
       ...(status ? { status } : {})
     };
 
-    return conversationsRepository.listForActorScope(
-      {
-        workspaceId,
-        actorUserId,
-        surfaceId: resolvedAssistantSurface.targetSurfaceId,
-        pagination: {
-          cursor: pagination.cursor,
-          limit: pagination.limit
-        },
-        filters
-      }
-    );
+    return conversationsRepository.listForActorScope({
+      workspaceId,
+      actorUserId,
+      surfaceId: resolvedAssistantSurface.targetSurfaceId,
+      pagination: {
+        cursor: pagination.cursor,
+        limit: pagination.limit
+      },
+      filters
+    });
   }
 
   async function getConversationMessagesForUser(assistantSurface, workspace, user, conversationId, query = {}) {
@@ -263,19 +261,19 @@ function createTranscriptService({ conversationsRepository, messagesRepository }
     const actorUserId = resolveActorUserId(user, {
       required: true
     });
-    const numericConversationId = parsePositiveInteger(conversationId);
-    if (!numericConversationId) {
+    const normalizedConversationId = normalizeRecordId(conversationId, { fallback: null });
+    if (!normalizedConversationId) {
       throw new AppError(400, "Validation failed.", {
         details: {
           fieldErrors: {
-            conversationId: "conversationId must be a positive integer."
+            conversationId: "conversationId must be a valid record id."
           }
         }
       });
     }
 
     const conversation = await conversationsRepository.findByIdForActorScope(
-      numericConversationId,
+      normalizedConversationId,
       {
         workspaceId,
         actorUserId,
@@ -291,7 +289,7 @@ function createTranscriptService({ conversationsRepository, messagesRepository }
       maxPageSize: MAX_MESSAGES_PAGE_SIZE
     });
     const total = await messagesRepository.countByConversationScope(
-      numericConversationId,
+      normalizedConversationId,
       {
         workspaceId
       }
@@ -299,7 +297,7 @@ function createTranscriptService({ conversationsRepository, messagesRepository }
     const totalPages = Math.max(1, Math.ceil(total / pagination.pageSize));
     const page = Math.min(pagination.page, totalPages);
     const entries = await messagesRepository.listByConversationScope(
-      numericConversationId,
+      normalizedConversationId,
       {
         workspaceId
       },

package/templates/migrations/assistant_config_initial.cjs

@@ -4,10 +4,10 @@ exports.up = async function up(knex) {
     const hasWorkspacesTable = await knex.schema.hasTable("workspaces");
 
     await knex.schema.createTable("assistant_config", (table) => {
-      table.increments("id").unsigned().primary();
+      table.bigIncrements("id").primary();
       table.string("target_surface_id", 64).notNullable();
       table.string("scope_key", 160).notNullable();
-      table.integer("workspace_id").unsigned().nullable();
+      table.bigInteger("workspace_id").unsigned().nullable();
       if (hasWorkspacesTable) {
         table.foreign("workspace_id").references("id").inTable("workspaces").onDelete("CASCADE");
       }

package/templates/migrations/assistant_transcripts_initial.cjs

@@ -3,12 +3,12 @@ exports.up = async function up(knex) {
   const hasConversationsTable = await knex.schema.hasTable("assistant_conversations");
   if (!hasConversationsTable) {
     await knex.schema.createTable("assistant_conversations", (table) => {
-      table.increments("id").unsigned().primary();
-      table.integer("workspace_id").unsigned().nullable();
+      table.bigIncrements("id").primary();
+      table.bigInteger("workspace_id").unsigned().nullable();
       if (hasWorkspacesTable) {
         table.foreign("workspace_id").references("id").inTable("workspaces").onDelete("CASCADE");
       }
-      table.integer("created_by_user_id").unsigned().nullable().references("id").inTable("users").onDelete("SET NULL").index();
+      table.bigInteger("created_by_user_id").unsigned().nullable().references("id").inTable("users").onDelete("SET NULL").index();
       table.string("title", 160).notNullable().defaultTo("New conversation");
       table.string("status", 32).notNullable().defaultTo("active");
       table.string("provider", 64).notNullable().defaultTo("");
@@ -30,9 +30,9 @@ exports.up = async function up(knex) {
   const hasMessagesTable = await knex.schema.hasTable("assistant_messages");
   if (!hasMessagesTable) {
     await knex.schema.createTable("assistant_messages", (table) => {
-      table.increments("id").unsigned().primary();
-      table.integer("conversation_id").unsigned().notNullable().references("id").inTable("assistant_conversations").onDelete("CASCADE");
-      table.integer("workspace_id").unsigned().nullable();
+      table.bigIncrements("id").primary();
+      table.bigInteger("conversation_id").unsigned().notNullable().references("id").inTable("assistant_conversations").onDelete("CASCADE");
+      table.bigInteger("workspace_id").unsigned().nullable();
       if (hasWorkspacesTable) {
         table.foreign("workspace_id").references("id").inTable("workspaces").onDelete("CASCADE");
       }
@@ -40,7 +40,7 @@ exports.up = async function up(knex) {
       table.string("role", 32).notNullable();
       table.string("kind", 32).notNullable().defaultTo("chat");
       table.string("client_message_sid", 128).notNullable().defaultTo("");
-      table.integer("actor_user_id").unsigned().nullable().references("id").inTable("users").onDelete("SET NULL").index();
+      table.bigInteger("actor_user_id").unsigned().nullable().references("id").inTable("users").onDelete("SET NULL").index();
       table.text("content_text").nullable();
       table.text("metadata_json").nullable();
       table.timestamp("created_at").notNullable().defaultTo(knex.fn.now());

package/test/repositoryContracts.test.js

@@ -0,0 +1,32 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createRepository as createAssistantConfigRepository } from "../src/server/repositories/assistantConfigRepository.js";
+import { createRepository as createConversationsRepository } from "../src/server/repositories/conversationsRepository.js";
+import { createRepository as createMessagesRepository } from "../src/server/repositories/messagesRepository.js";
+
+function createKnexStub() {
+  const knex = Object.assign(() => {
+    throw new Error("query execution not expected");
+  }, {
+    async transaction(work) {
+      return work({ trxId: "trx-1" });
+    }
+  });
+
+  return knex;
+}
+
+test("assistant-runtime repositories expose withTransaction", async () => {
+  const knex = createKnexStub();
+  const repositories = [
+    createAssistantConfigRepository(knex),
+    createConversationsRepository(knex),
+    createMessagesRepository(knex)
+  ];
+
+  for (const repository of repositories) {
+    assert.equal(typeof repository.withTransaction, "function");
+    const result = await repository.withTransaction(async (trx) => ({ id: trx.trxId }));
+    assert.deepEqual(result, { id: "trx-1" });
+  }
+});