@sixb/core 0.0.1 → 0.1.1

package/src/agents/validation.ts

@@ -1,4 +1,11 @@
-import { getInvalidJsonValueReason } from "../json"
+import { getInvalidJsonValueReason, isPlainRecord, type JsonValue } from "../json"
+import {
+  normalizeSchemaValue,
+  type ObjectSchema,
+  OntologyValidationError,
+  type ValueType,
+  validateSchemaValue,
+} from "../ontology"
 import type { GroupDefinition, SecurityRegistry } from "../security"
 import { AgentDefinitionError } from "./errors"
 import {
@@ -6,9 +13,26 @@ import {
   type AgentDefinition,
   type AgentLoopConfig,
   type AgentReasoningLevel,
+  type AgentToolDefinition,
+  type AgentToolInputSchema,
   type DefineAgentConfig,
 } from "./types"
 
+const AGENT_TOOL_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_-]{0,63}$/
+const AGENT_TOOL_PRIMITIVE_SCHEMAS = new Set([
+  "string",
+  "integer",
+  "double",
+  "decimal",
+  "boolean",
+  "date",
+  "timestamp",
+  "uuid",
+  "fileRef",
+])
+
+export const AGENT_RESERVED_TOOL_NAMES = ["bash"] as const
+
 export function assertNonEmpty(value: string, field: string): void {
   if (!value.trim()) {
     throw new AgentDefinitionError(`[Sixb] Agent ${field} must not be empty.`)
@@ -24,10 +48,117 @@ export function isAgentDefinition(value: unknown): value is AgentDefinition {
     typeof value.instructions === "string" &&
     (value.reasoning === undefined || isAgentReasoningLevel(value.reasoning)) &&
     (value.providerOptions === undefined || isProviderOptions(value.providerOptions)) &&
-    Array.isArray(value.groupIds)
+    Array.isArray(value.groupIds) &&
+    isAgentToolDefinitionArray(value.tools)
+  )
+}
+
+export function isAgentToolDefinition(value: unknown): value is AgentToolDefinition {
+  return (
+    isRecord(value) &&
+    value.kind === "agentTool" &&
+    typeof value.name === "string" &&
+    typeof value.description === "string" &&
+    isPlainRecord(value.input) &&
+    typeof value.handler === "function"
+  )
+}
+
+export function assertValidAgentToolName(name: unknown): asserts name is string {
+  if (typeof name !== "string" || !AGENT_TOOL_NAME_PATTERN.test(name)) {
+    throw new AgentDefinitionError(
+      "[Sixb] Agent tool name must be 1-64 characters, start with a letter or underscore, and contain only letters, numbers, underscores, or hyphens."
+    )
+  }
+  if ((AGENT_RESERVED_TOOL_NAMES as readonly string[]).includes(name)) {
+    throw new AgentDefinitionError(`[Sixb] Agent tool name '${name}' is reserved by the framework.`)
+  }
+}
+
+export function assertValidAgentToolDescription(name: string, description: unknown): void {
+  if (typeof description !== "string" || !description.trim()) {
+    throw new AgentDefinitionError(`[Sixb] Agent tool '${name}' description must not be empty.`)
+  }
+}
+
+export function assertValidAgentToolInput(name: string, input: unknown): void {
+  if (!isPlainRecord(input)) {
+    throw new AgentDefinitionError(`[Sixb] Agent tool '${name}' input must be a schema object.`)
+  }
+
+  for (const [field, schema] of Object.entries(input)) {
+    if (!field.trim()) {
+      throw new AgentDefinitionError(
+        `[Sixb] Agent tool '${name}' input field names must not be empty.`
+      )
+    }
+    assertValidAgentToolSchema(name, schema, `input.${field}`, new Set())
+  }
+}
+
+export function validateAndSnapshotAgentToolInput<TInput extends AgentToolInputSchema>(
+  toolName: string,
+  input: TInput
+): TInput {
+  assertValidAgentToolInput(toolName, input)
+  try {
+    return deepFreeze(structuredClone(input))
+  } catch {
+    throw new AgentDefinitionError(
+      `[Sixb] Agent tool '${toolName}' input must be safely snapshot-compatible.`
+    )
+  }
+}
+
+/** Validate model input against a tool schema, normalize it to JSON, and lock the snapshot. */
+export function validateAndNormalizeAgentToolInput(
+  toolName: string,
+  shape: AgentToolInputSchema,
+  value: unknown,
+  valueTypesById: ReadonlyMap<string, ValueType>
+): Record<string, JsonValue> {
+  const label = `Agent tool '${toolName}' input`
+  if (!isPlainRecord(value)) {
+    throw new OntologyValidationError(`[Sixb] ${label} must be a JSON object.`)
+  }
+
+  const reason = getInvalidJsonValueReason(value, label)
+  if (reason) {
+    throw new OntologyValidationError(`[Sixb] ${label} must be JSON-compatible; ${reason}.`)
+  }
+
+  const schema: ObjectSchema = {
+    type: "object",
+    properties: Object.fromEntries(
+      Object.entries(shape).map(([field, fieldSchema]) => [
+        field,
+        { schema: fieldSchema, required: true },
+      ])
+    ),
+  }
+  validateSchemaValue(schema, value, label, valueTypesById)
+  return deepFreeze(
+    normalizeSchemaValue(schema, value, label, valueTypesById) as Record<string, JsonValue>
   )
 }
 
+/** Revalidate and lock tool definitions supplied directly to the runtime. */
+export function validateAgentToolsAtStartup(agents: readonly AgentDefinition[]): void {
+  for (const agent of agents) {
+    if (!isAgentDefinition(agent)) {
+      throw new AgentDefinitionError("[Sixb] Agents must contain only valid agent definitions.")
+    }
+
+    assertValidAgentToolDefinitions(agent.id, agent.tools)
+    for (const tool of agent.tools) {
+      deepFreeze(tool.input)
+      Object.freeze(tool)
+    }
+    Object.freeze(agent.tools)
+    Object.freeze(agent)
+  }
+}
+
 export function assertValidLoopConfig(loop: AgentLoopConfig | undefined): void {
   const maxSteps = loop?.stopWhen?.maxSteps
   if (maxSteps === undefined) {
@@ -96,7 +227,7 @@ export function groupIdsFromDefinitions(
   })
 
   assertNoDuplicateGroupIds(agentId, groupIds)
-  return groupIds
+  return Object.freeze(groupIds)
 }
 
 export function validateAgentGroupReferences(
@@ -146,6 +277,159 @@ function isProviderOptions(
   )
 }
 
+function assertValidAgentToolSchema(
+  toolName: string,
+  schema: unknown,
+  path: string,
+  visiting: Set<object>
+): void {
+  if (typeof schema === "string") {
+    if (AGENT_TOOL_PRIMITIVE_SCHEMAS.has(schema)) {
+      return
+    }
+    throw invalidAgentToolSchema(toolName, path)
+  }
+  if (!isPlainRecord(schema) || typeof schema.type !== "string" || visiting.has(schema)) {
+    throw invalidAgentToolSchema(toolName, path)
+  }
+
+  visiting.add(schema)
+  switch (schema.type) {
+    case "enum": {
+      const values = schema.values
+      const validValues = isValidAgentToolEnumValues(values, schema.valueType)
+      if (!validValues || new Set(values).size !== values.length) {
+        throw invalidAgentToolSchema(toolName, path)
+      }
+      break
+    }
+    case "array":
+      assertValidAgentToolSchema(toolName, schema.items, `${path}.items`, visiting)
+      break
+    case "map":
+      if (schema.keySchema !== "string") {
+        throw invalidAgentToolSchema(toolName, path)
+      }
+      assertValidAgentToolSchema(toolName, schema.valueSchema, `${path}.valueSchema`, visiting)
+      break
+    case "object": {
+      if (!isPlainRecord(schema.properties)) {
+        throw invalidAgentToolSchema(toolName, path)
+      }
+      for (const [fieldId, field] of Object.entries(schema.properties)) {
+        if (!fieldId.trim() || !isPlainRecord(field) || !("schema" in field)) {
+          throw invalidAgentToolSchema(toolName, `${path}.properties.${fieldId}`)
+        }
+        if (
+          (field.required !== undefined && typeof field.required !== "boolean") ||
+          (field.nullable !== undefined && typeof field.nullable !== "boolean") ||
+          (field.description !== undefined &&
+            (typeof field.description !== "string" || !field.description.trim()))
+        ) {
+          throw invalidAgentToolSchema(toolName, `${path}.properties.${fieldId}`)
+        }
+        assertValidAgentToolSchema(
+          toolName,
+          field.schema,
+          `${path}.properties.${fieldId}.schema`,
+          visiting
+        )
+      }
+      break
+    }
+    case "valueTypeRef":
+      if (typeof schema.valueTypeId !== "string" || !schema.valueTypeId.trim()) {
+        throw invalidAgentToolSchema(toolName, path)
+      }
+      if (schema._resolved !== undefined) {
+        assertValidAgentToolSchema(toolName, schema._resolved, `${path}._resolved`, visiting)
+      }
+      break
+    default:
+      throw invalidAgentToolSchema(toolName, path)
+  }
+  visiting.delete(schema)
+}
+
+function invalidAgentToolSchema(toolName: string, path: string): AgentDefinitionError {
+  return new AgentDefinitionError(
+    `[Sixb] Agent tool '${toolName}' ${path} must be a valid Sixb schema.`
+  )
+}
+
+function isAgentToolDefinitionArray(value: unknown): value is readonly AgentToolDefinition[] {
+  if (!Array.isArray(value)) {
+    return false
+  }
+  for (let index = 0; index < value.length; index += 1) {
+    if (!Object.hasOwn(value, index) || !isAgentToolDefinition(value[index])) {
+      return false
+    }
+  }
+  return true
+}
+
+export function assertValidAgentToolDefinitions(
+  agentId: string,
+  tools: readonly AgentToolDefinition[]
+): void {
+  const seen = new Set<string>()
+  for (let index = 0; index < tools.length; index += 1) {
+    const tool = tools[index]
+    if (!Object.hasOwn(tools, index) || !isAgentToolDefinition(tool)) {
+      throw new AgentDefinitionError(
+        `[Sixb] Agent '${agentId}' tools must contain only agent tool definitions.`
+      )
+    }
+
+    assertValidAgentToolName(tool.name)
+    assertValidAgentToolDescription(tool.name, tool.description)
+    assertValidAgentToolInput(tool.name, tool.input)
+    if (seen.has(tool.name)) {
+      throw new AgentDefinitionError(
+        `[Sixb] Agent '${agentId}' tools contains duplicate tool name '${tool.name}'.`
+      )
+    }
+    seen.add(tool.name)
+  }
+}
+
+function isValidAgentToolEnumValues(values: unknown, valueType: unknown): values is unknown[] {
+  if (!Array.isArray(values) || values.length === 0) {
+    return false
+  }
+
+  for (let index = 0; index < values.length; index += 1) {
+    if (!Object.hasOwn(values, index)) {
+      return false
+    }
+    const value = values[index]
+    if (
+      valueType === "string"
+        ? typeof value !== "string"
+        : valueType !== "integer" || typeof value !== "number" || !Number.isInteger(value)
+    ) {
+      return false
+    }
+  }
+  return true
+}
+
+function deepFreeze<T>(value: T, seen: Set<object> = new Set()): T {
+  if (value === null || typeof value !== "object" || seen.has(value)) {
+    return value
+  }
+
+  seen.add(value)
+  for (const key of Reflect.ownKeys(value)) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key)
+    if (descriptor && "value" in descriptor) {
+      deepFreeze(descriptor.value, seen)
+    }
+  }
+  return Object.freeze(value)
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value)
 }

package/src/blob-storage/validation.ts

@@ -1,3 +1,4 @@
+import { isPlainRecord } from "../json"
 import { blobIdFromDigest } from "./derive"
 import type {
   BlobDigest,
@@ -7,22 +8,13 @@ import type {
   RangeReadableBlobStorage,
 } from "./types"
 
-function isPlainObject(value: unknown): value is Record<string, unknown> {
-  if (typeof value !== "object" || value === null || Array.isArray(value)) {
-    return false
-  }
-
-  const prototype = Object.getPrototypeOf(value)
-  return prototype === Object.prototype || prototype === null
-}
-
 export function isBlobDigest(value: unknown): value is BlobDigest {
   return typeof value === "string" && value.startsWith("sha256:") && value.length > "sha256:".length
 }
 
 export function isFileRef(value: unknown): value is FileRef {
   return (
-    isPlainObject(value) &&
+    isPlainRecord(value) &&
     typeof value.blobId === "string" &&
     value.blobId.trim().length > 0 &&
     isBlobDigest(value.digest) &&

package/src/datasets/builders.ts

@@ -4,6 +4,7 @@ import type {
   DatasetColumnNameOf,
   DatasetColumnType,
   DatasetDefinition,
+  DatasetPrimaryKey,
 } from "./types"
 import { assertDatasetColumnDefinition, assertDatasetDefinition } from "./validation"
 
@@ -13,6 +14,7 @@ type DatasetColumnOptions = {
 
 type DefineDatasetOptions = {
   readonly schema: readonly DatasetColumnDefinition[]
+  readonly primaryKey?: DatasetPrimaryKey
   readonly partitionBy?: readonly string[]
   readonly description?: string
 }
@@ -20,6 +22,7 @@ type DefineDatasetOptions = {
 type DeriveDatasetOptions<TParent extends DatasetDefinition> = {
   readonly pick?: readonly DatasetColumnNameOf<TParent>[]
   readonly add?: readonly DatasetColumnDefinition[]
+  readonly primaryKey?: DatasetPrimaryKey
   readonly partitionBy?: readonly string[]
   readonly description?: string
 }
@@ -39,6 +42,24 @@ type ColumnDefinitionOf<
   TName extends ColumnNameOf<TColumns>,
 > = Extract<TColumns[number], { readonly name: TName }>
 
+type PrimaryKeyColumnNameOf<TColumns extends readonly DatasetColumnDefinition[]> =
+  string extends ColumnNameOf<TColumns>
+    ? string
+    : {
+        [TName in ColumnNameOf<TColumns>]: ColumnDefinitionOf<
+          TColumns,
+          TName
+        >["type"] extends "string"
+          ? ColumnDefinitionOf<TColumns, TName> extends { readonly nullable: true }
+            ? never
+            : TName
+          : never
+      }[ColumnNameOf<TColumns>]
+
+type CheckedDefineDatasetOptions<TOptions extends DefineDatasetOptions> = TOptions & {
+  readonly primaryKey?: DatasetPrimaryKey<PrimaryKeyColumnNameOf<TOptions["schema"]>>
+}
+
 type PickColumns<
   TColumns extends readonly DatasetColumnDefinition[],
   TNames extends readonly ColumnNameOf<TColumns>[],
@@ -86,8 +107,9 @@ type DatasetColumnResult<
 
 type DatasetDefinitionResult<TId extends string, TOptions extends DefineDatasetOptions> = Omit<
   DatasetDefinition<TId, TOptions["schema"]>,
-  "partitionBy" | "description"
+  "primaryKey" | "partitionBy" | "description"
 > &
+  FieldFromOptions<TOptions, "primaryKey", DatasetPrimaryKey> &
   FieldFromOptions<TOptions, "partitionBy", readonly string[]> &
   FieldFromOptions<TOptions, "description", string>
 
@@ -95,10 +117,21 @@ type DerivedDatasetDefinitionResult<
   TId extends string,
   TParent extends DatasetDefinition,
   TOptions extends DeriveDatasetOptions<TParent> | undefined,
-> = Omit<DatasetDefinition<TId, DerivedColumns<TParent, TOptions>>, "partitionBy" | "description"> &
+> = Omit<
+  DatasetDefinition<TId, DerivedColumns<TParent, TOptions>>,
+  "primaryKey" | "partitionBy" | "description"
+> &
+  FieldFromOptions<TOptions, "primaryKey", DatasetPrimaryKey> &
   FieldFromOptions<TOptions, "partitionBy", readonly string[]> &
   FieldFromOptions<TOptions, "description", string>
 
+type CheckedDeriveDatasetOptions<
+  TParent extends DatasetDefinition,
+  TOptions extends DeriveDatasetOptions<TParent>,
+> = TOptions & {
+  readonly primaryKey?: DatasetPrimaryKey<PrimaryKeyColumnNameOf<DerivedColumns<TParent, TOptions>>>
+}
+
 export function col<const TName extends string, const TType extends DatasetColumnType>(
   name: TName,
   type: TType
@@ -130,12 +163,19 @@ function assertDatasetId(id: string): void {
 }
 
 function createDatasetDefinition(id: string, options: DefineDatasetOptions): DatasetDefinition {
-  const definition: DatasetDefinition = {
+  const definition: unknown = {
     kind: "dataset",
     id,
     schema: {
       columns: [...options.schema],
     },
+    ...(options.primaryKey !== undefined
+      ? {
+          primaryKey: Array.isArray(options.primaryKey)
+            ? [...options.primaryKey]
+            : options.primaryKey,
+        }
+      : {}),
     ...(options.partitionBy !== undefined ? { partitionBy: [...options.partitionBy] } : {}),
     ...(options.description !== undefined ? { description: options.description } : {}),
   }
@@ -189,6 +229,7 @@ function deriveDatasetDefinition(
 
   return createDatasetDefinition(id, {
     schema: [...pickedColumns, ...(options.add ?? [])],
+    ...(options.primaryKey !== undefined ? { primaryKey: options.primaryKey } : {}),
     ...(options.partitionBy !== undefined ? { partitionBy: options.partitionBy } : {}),
     ...(options.description !== undefined ? { description: options.description } : {}),
   })
@@ -203,7 +244,10 @@ function createDatasetDeriveBuilder<TId extends string>(id: TId) {
   function derive<
     const TParent extends DatasetDefinition,
     const TOptions extends DeriveDatasetOptions<TParent>,
-  >(parent: TParent, options: TOptions): DerivedDatasetDefinitionResult<TId, TParent, TOptions>
+  >(
+    parent: TParent,
+    options: CheckedDeriveDatasetOptions<TParent, TOptions>
+  ): DerivedDatasetDefinitionResult<TId, TParent, TOptions>
   function derive(
     parent: DatasetDefinition,
     options?: DeriveDatasetOptions<DatasetDefinition>
@@ -220,7 +264,7 @@ export function defineDataset<const TId extends string>(
 export function defineDataset<
   const TId extends string,
   const TOptions extends DefineDatasetOptions,
->(id: TId, options: TOptions): DatasetDefinitionResult<TId, TOptions>
+>(id: TId, options: CheckedDefineDatasetOptions<TOptions>): DatasetDefinitionResult<TId, TOptions>
 export function defineDataset(
   id: string,
   options?: DefineDatasetOptions

package/src/datasets/changes.ts

@@ -0,0 +1,13 @@
+export type MergeChange<Row, Key> =
+  | { readonly kind: "upsert"; readonly row: Row }
+  | { readonly kind: "delete"; readonly key: Key }
+
+export const change = {
+  upsert<const Row extends object>(row: Row): { readonly kind: "upsert"; readonly row: Row } {
+    return { kind: "upsert", row }
+  },
+
+  delete<const Key extends object>(key: Key): { readonly kind: "delete"; readonly key: Key } {
+    return { kind: "delete", key }
+  },
+}

package/src/datasets/index.ts

@@ -1,4 +1,6 @@
 export { col, defineDataset } from "./builders"
+export type { MergeChange } from "./changes"
+export { change } from "./changes"
 export { DatasetValidationError } from "./errors"
 export type {
   DatasetColumnDefinition,
@@ -8,6 +10,7 @@ export type {
   DatasetColumnTypeOf,
   DatasetColumnUnionOf,
   DatasetDefinition,
+  DatasetPrimaryKey,
   DatasetSchema,
 } from "./types"
 export { getDatasetRowValidationError, isDatasetDefinition } from "./validation"

package/src/datasets/types.ts

@@ -24,6 +24,10 @@ export interface DatasetSchema<
   readonly columns: TColumns
 }
 
+export type DatasetPrimaryKey<TColumnName extends string = string> =
+  | TColumnName
+  | readonly [TColumnName, TColumnName, ...TColumnName[]]
+
 export interface DatasetDefinition<
   TId extends string = string,
   TColumns extends readonly DatasetColumnDefinition[] = readonly DatasetColumnDefinition[],
@@ -31,6 +35,7 @@ export interface DatasetDefinition<
   readonly kind: "dataset"
   readonly id: TId
   readonly schema: DatasetSchema<TColumns>
+  readonly primaryKey?: DatasetPrimaryKey
   readonly partitionBy?: readonly string[]
   readonly description?: string
 }

package/src/datasets/validation.ts

@@ -1,5 +1,5 @@
 import { isFileRef } from "../blob-storage"
-import { isJsonValue } from "../json"
+import { isJsonValue, isPlainRecord } from "../json"
 import { isDecimalString } from "../ontology/decimal"
 import { DatasetValidationError } from "./errors"
 import type {
@@ -25,15 +25,6 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value)
 }
 
-function isPlainObject(value: unknown): value is Record<string, unknown> {
-  if (!isRecord(value)) {
-    return false
-  }
-
-  const prototype = Object.getPrototypeOf(value)
-  return prototype === Object.prototype || prototype === null
-}
-
 function isValidDateValue(value: unknown): boolean {
   return value instanceof Date && !Number.isNaN(value.getTime())
 }
@@ -128,6 +119,53 @@ function assertDatasetSchema(
   }
 }
 
+function assertDatasetPrimaryKey(
+  primaryKey: unknown,
+  schema: DatasetSchema,
+  createError: (message: string) => Error
+): void {
+  let keyColumns: readonly unknown[]
+  if (typeof primaryKey === "string") {
+    keyColumns = [primaryKey]
+  } else if (Array.isArray(primaryKey)) {
+    if (primaryKey.length < 2) {
+      throw createError(
+        "Dataset primaryKey arrays must contain at least two column names. Use a string for a single-column key."
+      )
+    }
+    keyColumns = primaryKey
+  } else {
+    throw createError(
+      "Dataset primaryKey must be a column name or an array of at least two column names."
+    )
+  }
+
+  const columnsByName = new Map(schema.columns.map((column) => [column.name, column] as const))
+  const seenColumnNames = new Set<string>()
+
+  for (const columnName of keyColumns) {
+    if (typeof columnName !== "string" || columnName.trim().length === 0) {
+      throw createError("Dataset primaryKey columns must be non-empty strings.")
+    }
+
+    if (seenColumnNames.has(columnName)) {
+      throw createError(`Dataset primaryKey contains duplicate column '${columnName}'.`)
+    }
+    seenColumnNames.add(columnName)
+
+    const column = columnsByName.get(columnName)
+    if (column === undefined) {
+      throw createError(`Dataset primaryKey column '${columnName}' is not declared in the schema.`)
+    }
+    if (column.type !== "string") {
+      throw createError(`Dataset primaryKey column '${columnName}' must have type 'string'.`)
+    }
+    if (column.nullable === true) {
+      throw createError(`Dataset primaryKey column '${columnName}' must not be nullable.`)
+    }
+  }
+}
+
 export function assertDatasetDefinition(
   definition: unknown,
   createError: (message: string) => Error = (message) => new DatasetValidationError(message)
@@ -143,6 +181,10 @@ export function assertDatasetDefinition(
   assertNonEmptyString(definition.id, "Dataset id", createError)
   assertDatasetSchema(definition.schema, createError)
 
+  if (definition.primaryKey !== undefined) {
+    assertDatasetPrimaryKey(definition.primaryKey, definition.schema, createError)
+  }
+
   if (definition.partitionBy !== undefined) {
     if (!Array.isArray(definition.partitionBy)) {
       throw createError("Dataset partitionBy must be an array of column names.")
@@ -176,7 +218,7 @@ export function getDatasetRowValidationError(
   dataset: DatasetDefinition,
   options?: { readonly columns?: Iterable<string> }
 ): string | null {
-  if (!isPlainObject(row)) {
+  if (!isPlainRecord(row)) {
     return `Dataset '${dataset.id}' rows must be plain objects.`
   }