@nixxie-cms/core 1.0.3 → 2.0.0

package/src/types/context.ts

@@ -3,7 +3,7 @@ import type { DocumentNode, ExecutionResult, GraphQLSchema } from 'graphql'
 import type { TypedDocumentNode } from '@graphql-typed-document-node/core'
 import type { InitialisedList } from '../lib/core/initialise-lists'
 import type { SessionStrategy } from './session'
-import type { BaseNixxieTypeInfo, BaseListTypeInfo } from './type-info'
+import type { BaseNixxieTypeInfo, BaseCollectionTypeInfo } from './type-info'
 import type { MaybePromise } from './utils'
 
 // ── Email service types (defined here so @nixxie-cms/email can implement without circular deps) ──
@@ -94,20 +94,41 @@ export type NixxieEmailService = {
   close(): Promise<void>
 }
 
+// ── Service lifecycle ──
+
+/**
+ * Optional lifecycle hook for runtime services. When a service object exposes `init`,
+ * core calls it once with a sudo context after the database connects — this is how
+ * database-backed service stores (audit, versioning, workflow, jobs history, webhook
+ * subscriptions) get access to `context.prisma` without a circular boot dependency.
+ */
+export type NixxieInitableService = {
+  init?(context: NixxieContext): MaybePromise<void>
+}
+
 // ── Jobs service ──
 
 export type NixxieJobDefinition = {
   name: string
-  /** Cron expression or interval in milliseconds */
-  schedule: string | number
+  /**
+   * Cron expression or interval in milliseconds.
+   * Omit when `runAt` is set (one-time job). One of `schedule` or `runAt` is required.
+   */
+  schedule?: string | number
+  /** Run once at this time instead of on a schedule. Times in the past run immediately. */
+  runAt?: Date
   /** Handler function invoked on each tick */
-  handler: (ctx: { jobId: string; scheduledAt: Date }) => Promise<void> | void
+  handler: (ctx: { jobId: string; scheduledAt: Date; attempt: number }) => Promise<void> | void
   /** Immediately run the job once on registration */
   runImmediately?: boolean
   /** Disable job without removing the definition */
   enabled?: boolean
   /** Milliseconds before a running job is considered stuck */
   timeout?: number
+  /** Number of retry attempts after a failed run (0 = no retries) */
+  retries?: number
+  /** Base delay in milliseconds between retries (doubles each attempt) */
+  retryDelay?: number
 }
 
 export type NixxieJobStatus = 'idle' | 'running' | 'error' | 'disabled'
@@ -121,7 +142,7 @@ export type NixxieJobInfo = {
   runs: number
 }
 
-export type NixxieJobsService = {
+export type NixxieJobsService = NixxieInitableService & {
   /** Register a job definition. Call before start() or at any time for hot-registration. */
   define(job: NixxieJobDefinition): void
   /** Remove a registered job by name. */
@@ -215,7 +236,7 @@ export type NixxieAuditRecord = NixxieAuditEntry & {
   timestamp: Date
 }
 
-export type NixxieAuditService = {
+export type NixxieAuditService = NixxieInitableService & {
   /** Log an audit event. */
   log(entry: NixxieAuditEntry): Promise<NixxieAuditRecord>
   /** Query the audit log. */
@@ -261,9 +282,13 @@ export type NixxieWebhookSubscribeOptions = {
   retries?: number
 }
 
-export type NixxieWebhooksService = {
+export type NixxieWebhooksService = NixxieInitableService & {
   /** Register a webhook endpoint for an event. Returns the subscription ID. */
-  subscribe(event: string, url: string, options?: NixxieWebhookSubscribeOptions): Promise<NixxieWebhookSubscription>
+  subscribe(
+    event: string,
+    url: string,
+    options?: NixxieWebhookSubscribeOptions
+  ): Promise<NixxieWebhookSubscription>
   /** Remove a subscription by ID. */
   unsubscribe(id: string): Promise<void>
   /** Fire an event, delivering to all matching subscribers. */
@@ -316,7 +341,11 @@ export type NixxieRateLimitService = {
 
 // ── Health service ──
 
-export type NixxieHealthCheckFn = () => Promise<{ ok: boolean; message?: string; details?: unknown }>
+export type NixxieHealthCheckFn = () => Promise<{
+  ok: boolean
+  message?: string
+  details?: unknown
+}>
 
 export type NixxieHealthCheckResult = {
   name: string
@@ -396,7 +425,11 @@ export type NixxieSignedUrlOptions = {
 /** Pluggable blob storage. Implemented by @nixxie-cms/storage (local, S3, GCS, Azure). */
 export type NixxieStorageService = {
   /** Store a file and return its key + URL. */
-  put(key: string, data: Buffer | Uint8Array | string, options?: NixxiePutOptions): Promise<NixxieStoredFile>
+  put(
+    key: string,
+    data: Buffer | Uint8Array | string,
+    options?: NixxiePutOptions
+  ): Promise<NixxieStoredFile>
   /** Read a file's bytes. Resolves undefined when the key does not exist. */
   get(key: string): Promise<Buffer | undefined>
   /** Delete a file. No-op if it does not exist. */
@@ -449,7 +482,10 @@ export type NixxieSearchService = {
   /** Remove a document from an index by id. */
   remove(indexName: string, id: string): Promise<void>
   /** Run a search against an index. */
-  search<T = NixxieSearchDocument>(indexName: string, query: NixxieSearchQuery): Promise<NixxieSearchResults<T>>
+  search<T = NixxieSearchDocument>(
+    indexName: string,
+    query: NixxieSearchQuery
+  ): Promise<NixxieSearchResults<T>>
   /** Delete every document in an index. */
   clear(indexName: string): Promise<void>
   /** Gracefully close any open connections. */
@@ -526,11 +562,506 @@ export type NixxieAiService = {
   embedMany(texts: string[]): Promise<number[][]>
 }
 
+// ── AI RAG service (retrieval-augmented knowledge base) ──
+
+/** A source document stored in the knowledge base that the assistant is trained on. */
+export type NixxieRagDocumentInput = {
+  /** Short title/label for the document. */
+  title?: string
+  /** The body the assistant learns from. */
+  content: string
+  /** Origin of the content (URL, filename, list:itemId, …) — shown in citations. */
+  source?: string
+  /** Free-form tags used to scope retrieval (e.g. ['billing', 'public']). */
+  tags?: string[]
+  /** Arbitrary structured metadata returned alongside citations. */
+  metadata?: Record<string, unknown>
+}
+
+export type NixxieRagDocument = NixxieRagDocumentInput & {
+  id: string
+  /** Indexing lifecycle of the document's chunks. */
+  status: 'pending' | 'indexing' | 'indexed' | 'error' | 'disabled'
+  /** Number of chunks currently indexed for this document. */
+  chunkCount: number
+  /** Last error encountered while indexing, if any. */
+  error?: string
+  createdAt: Date
+  updatedAt: Date
+  indexedAt?: Date
+}
+
+export type NixxieRagDocumentQuery = {
+  take?: number
+  skip?: number
+  /** Only return documents matching ALL of these tags. */
+  tags?: string[]
+  status?: NixxieRagDocument['status']
+  /** Substring match against title/content/source. */
+  search?: string
+}
+
+/** A retrieved chunk with its similarity score, used to ground answers. */
+export type NixxieRagChunk = {
+  id: string
+  documentId: string
+  title?: string
+  source?: string
+  /** The chunk text. */
+  content: string
+  /** Cosine similarity to the query in [0, 1] (higher is more relevant). */
+  score: number
+  tags?: string[]
+  metadata?: Record<string, unknown>
+}
+
+export type NixxieRagRetrieveOptions = {
+  /** Number of chunks to return. Defaults to the configured `retrieval.topK`. */
+  topK?: number
+  /** Drop chunks scoring below this threshold. Defaults to `retrieval.minScore`. */
+  minScore?: number
+  /** Restrict retrieval to documents carrying ALL of these tags. */
+  tags?: string[]
+}
+
+/** A single source the answer was grounded on. */
+export type NixxieRagCitation = {
+  documentId: string
+  chunkId: string
+  title?: string
+  source?: string
+  score: number
+  /** Short excerpt of the cited chunk. */
+  snippet: string
+}
+
+export type NixxieRagAskOptions = NixxieRagRetrieveOptions & {
+  /** Override the generation model for this call. */
+  model?: string
+  /** Override sampling temperature for this call. */
+  temperature?: number
+  /** Override max output tokens for this call. */
+  maxTokens?: number
+  /** Append an extra instruction to the system prompt for this call. */
+  systemSuffix?: string
+  /** Pre-retrieved chunks to use instead of running retrieval (advanced). */
+  context?: NixxieRagChunk[]
+  /** Per-call override of the hallucination guard. */
+  guard?: boolean
+}
+
+/** The grounded answer returned by `ask`/`chat`. */
+export type NixxieRagAnswer = {
+  /** The assistant's answer text. */
+  text: string
+  /** The sources the answer was grounded on. */
+  sources: NixxieRagCitation[]
+  /** Whether the answer passed the grounding/hallucination check. */
+  grounded: boolean
+  /** True when the assistant refused because no relevant context was found. */
+  refused: boolean
+  model: string
+  usage?: { inputTokens?: number; outputTokens?: number }
+}
+
+/** A streamed token or lifecycle event from `stream`. */
+export type NixxieRagStreamEvent =
+  | { type: 'sources'; sources: NixxieRagCitation[] }
+  | { type: 'token'; token: string }
+  | { type: 'done'; answer: NixxieRagAnswer }
+  | { type: 'error'; error: string }
+
+export type NixxieRagIndexStats = {
+  /** Documents processed this run. */
+  documents: number
+  /** Chunks (re)embedded this run. */
+  chunks: number
+  /** Documents that failed to index. */
+  errors: number
+  /** Wall-clock duration in milliseconds. */
+  durationMs: number
+}
+
+/**
+ * A custom, RAG-trained assistant backed by a knowledge-base collection.
+ * Implemented by @nixxie-cms/ai-rag. Add/remove/retrieve KB content, (re)index it
+ * into embeddings, and ask grounded, citation-backed questions with hallucination guarding.
+ */
+export type NixxieAiRagService = NixxieInitableService & {
+  // ── Knowledge-base content ──
+  /** Add a document to the knowledge base (queued for indexing). */
+  addDocument(doc: NixxieRagDocumentInput): Promise<NixxieRagDocument>
+  /** Add many documents in one call. */
+  addDocuments(docs: NixxieRagDocumentInput[]): Promise<NixxieRagDocument[]>
+  /** Fetch a single document by id. */
+  getDocument(id: string): Promise<NixxieRagDocument | undefined>
+  /** List documents in the knowledge base. */
+  listDocuments(query?: NixxieRagDocumentQuery): Promise<NixxieRagDocument[]>
+  /** Patch a document's content/metadata (re-queues it for indexing). */
+  updateDocument(id: string, patch: Partial<NixxieRagDocumentInput>): Promise<NixxieRagDocument>
+  /** Remove a document and all of its indexed chunks. */
+  removeDocument(id: string): Promise<void>
+
+  // ── Indexing ──
+  /** (Re)index a single document now. */
+  index(documentId: string): Promise<void>
+  /** (Re)index documents. Pass `{ force: true }` to rebuild already-indexed docs. */
+  reindex(options?: { force?: boolean; tags?: string[] }): Promise<NixxieRagIndexStats>
+  /** Index every document still pending/changed. */
+  indexPending(): Promise<NixxieRagIndexStats>
+
+  // ── Retrieval & chat ──
+  /** Return the most relevant chunks for a query (no generation). */
+  retrieve(query: string, options?: NixxieRagRetrieveOptions): Promise<NixxieRagChunk[]>
+  /** Ask a one-shot question and get a grounded, cited answer. */
+  ask(question: string, options?: NixxieRagAskOptions): Promise<NixxieRagAnswer>
+  /** Multi-turn chat; the latest user turn drives retrieval. */
+  chat(messages: NixxieAiMessage[], options?: NixxieRagAskOptions): Promise<NixxieRagAnswer>
+  /** Streamed variant of `chat`, yielding sources, then tokens, then the final answer. */
+  stream(
+    messages: NixxieAiMessage[],
+    options?: NixxieRagAskOptions
+  ): AsyncIterable<NixxieRagStreamEvent>
+
+  /** Gracefully stop background indexing and flush pending work. */
+  close(): Promise<void>
+}
+
+// ── Versioning service ──
+
+export type NixxieVersionEntry = {
+  /** Collection name (e.g. 'Post') */
+  resource: string
+  /** ID of the item this snapshot belongs to */
+  resourceId: string
+  /** Snapshot of the item's data at this point in time */
+  data: Record<string, unknown>
+  /** Optional human label (e.g. 'before publish') */
+  label?: string
+  /** Who created the snapshot */
+  actor?: {
+    id?: string
+    label?: string
+  }
+  /** Arbitrary extra context */
+  meta?: Record<string, unknown>
+}
+
+export type NixxieVersionRecord = NixxieVersionEntry & {
+  id: string
+  /** Monotonically increasing version number, scoped to resource + resourceId (starts at 1). */
+  version: number
+  createdAt: Date
+}
+
+export type NixxieVersionQuery = {
+  take?: number
+  skip?: number
+}
+
+export type NixxieVersionDiff = {
+  fromVersion: number
+  toVersion: number
+  /** Per-field differences between the two versions. */
+  changes: Record<string, { from: unknown; to: unknown }>
+}
+
+/** Content revision history. Implemented by @nixxie-cms/versioning. */
+export type NixxieVersioningService = NixxieInitableService & {
+  /** Record a new snapshot of an item's data. Returns the created version record. */
+  snapshot(entry: NixxieVersionEntry): Promise<NixxieVersionRecord>
+  /** List versions for an item, newest first. */
+  list(
+    resource: string,
+    resourceId: string,
+    query?: NixxieVersionQuery
+  ): Promise<NixxieVersionRecord[]>
+  /** Fetch a single version by its ID. */
+  get(versionId: string): Promise<NixxieVersionRecord | undefined>
+  /** Get the most recent version for an item. */
+  latest(resource: string, resourceId: string): Promise<NixxieVersionRecord | undefined>
+  /**
+   * Restore an older version: copies its data into a brand-new snapshot
+   * (so history is never lost) and returns that new record. The caller is
+   * responsible for writing `record.data` back to the live item.
+   */
+  restore(versionId: string): Promise<NixxieVersionRecord>
+  /** Compute a field-level diff between two versions of the same item. */
+  diff(fromVersionId: string, toVersionId: string): Promise<NixxieVersionDiff>
+  /** Keep only the newest `keep` versions of an item, deleting the rest. Returns the number deleted. */
+  prune(resource: string, resourceId: string, keep: number): Promise<number>
+  /** Gracefully shut down (flush pending writes). */
+  close(): Promise<void>
+}
+
+// ── Workflow service ──
+
+export type NixxieWorkflowState = string
+
+export type NixxieWorkflowTransition = {
+  /** The state(s) this transition can start from. */
+  from: NixxieWorkflowState | NixxieWorkflowState[]
+  /** The state this transition moves to. */
+  to: NixxieWorkflowState
+  /** Optional action name (e.g. 'submit', 'approve', 'reject'). */
+  name?: string
+  /**
+   * Optional guard evaluated before the transition is recorded.
+   * Return `false` to block it, or a string to block it with a custom error message.
+   */
+  when?: (args: {
+    resource: string
+    resourceId: string
+    from: NixxieWorkflowState
+    to: NixxieWorkflowState
+    actor?: NixxieWorkflowActor
+    meta?: Record<string, unknown>
+  }) => MaybePromise<boolean | string>
+}
+
+export type NixxieWorkflowDefinition = {
+  name: string
+  /** State assigned to items that have no recorded state yet. */
+  initial: NixxieWorkflowState
+  /** All valid states. */
+  states: NixxieWorkflowState[]
+  /** Allowed transitions between states. */
+  transitions: NixxieWorkflowTransition[]
+}
+
+export type NixxieWorkflowActor = {
+  id?: string
+  label?: string
+}
+
+export type NixxieWorkflowTransitionInput = {
+  actor?: NixxieWorkflowActor
+  meta?: Record<string, unknown>
+}
+
+export type NixxieWorkflowHistoryEntry = {
+  id: string
+  resource: string
+  resourceId: string
+  /** Previous state, or null for the first transition. */
+  from: NixxieWorkflowState | null
+  to: NixxieWorkflowState
+  actor?: NixxieWorkflowActor
+  meta?: Record<string, unknown>
+  at: Date
+}
+
+/** Editorial state machine (draft → review → published, etc). Implemented by @nixxie-cms/workflow. */
+export type NixxieWorkflowService = NixxieInitableService & {
+  /** The workflow definition this service enforces. */
+  definition(): NixxieWorkflowDefinition
+  /** Current state of an item (returns the initial state if none recorded). */
+  getState(resource: string, resourceId: string): Promise<NixxieWorkflowState>
+  /**
+   * Move an item to `to`, enforcing that a transition from its current state is allowed.
+   * Throws if the transition is not permitted.
+   */
+  transition(
+    resource: string,
+    resourceId: string,
+    to: NixxieWorkflowState,
+    input?: NixxieWorkflowTransitionInput
+  ): Promise<NixxieWorkflowHistoryEntry>
+  /** Force a state without checking transition rules (e.g. migrations / admin override). */
+  setState(
+    resource: string,
+    resourceId: string,
+    to: NixxieWorkflowState,
+    input?: NixxieWorkflowTransitionInput
+  ): Promise<NixxieWorkflowHistoryEntry>
+  /** Whether a direct transition from `from` to `to` is allowed. */
+  can(from: NixxieWorkflowState, to: NixxieWorkflowState): boolean
+  /** States reachable from `from` in a single transition. */
+  available(from: NixxieWorkflowState): NixxieWorkflowState[]
+  /** Transition history for an item, newest first. */
+  history(
+    resource: string,
+    resourceId: string,
+    take?: number
+  ): Promise<NixxieWorkflowHistoryEntry[]>
+  /** Gracefully shut down (flush pending writes). */
+  close(): Promise<void>
+}
+
+// ── API keys service ──
+
+export type NixxieApiKeyIssueOptions = {
+  /** Human-friendly name for the key. */
+  name: string
+  /** Permission scopes granted to the key. */
+  scopes?: string[]
+  /** Optional expiry. Omit for a non-expiring key. */
+  expiresAt?: Date
+  /** Arbitrary extra context. */
+  meta?: Record<string, unknown>
+}
+
+export type NixxieApiKeyRecord = {
+  id: string
+  name: string
+  scopes: string[]
+  /** Short, non-secret prefix used to identify the key in UIs and logs. */
+  prefix: string
+  createdAt: Date
+  expiresAt?: Date
+  lastUsedAt?: Date
+  revokedAt?: Date
+  meta?: Record<string, unknown>
+}
+
+export type NixxieApiKeyIssued = {
+  record: NixxieApiKeyRecord
+  /** The full plaintext key. Shown ONCE at issue time — only its hash is stored. */
+  key: string
+}
+
+export type NixxieApiKeyVerifyResult =
+  | { valid: true; record: NixxieApiKeyRecord }
+  | { valid: false; reason: 'not-found' | 'revoked' | 'expired' | 'missing-scope' }
+
+/** Scoped, revocable machine-to-machine access tokens. Implemented by @nixxie-cms/api-keys. */
+export type NixxieApiKeysService = {
+  /** Issue a new key. The plaintext value is returned once and never stored. */
+  issue(options: NixxieApiKeyIssueOptions): Promise<NixxieApiKeyIssued>
+  /** Verify a plaintext key, checking revocation and expiry. Updates `lastUsedAt` on success. */
+  verify(key: string): Promise<NixxieApiKeyVerifyResult>
+  /** Verify a key and require that it holds every one of `scopes`. */
+  authorize(key: string, scopes: string[]): Promise<NixxieApiKeyVerifyResult>
+  /** Revoke a key by ID. */
+  revoke(id: string): Promise<void>
+  /** List all key records (never includes the plaintext key). */
+  list(): Promise<NixxieApiKeyRecord[]>
+  /** Fetch a single key record by ID. */
+  get(id: string): Promise<NixxieApiKeyRecord | undefined>
+  /** Gracefully shut down (flush pending writes). */
+  close(): Promise<void>
+}
+
+// ── Logger service ──
+
+export type NixxieLogLevel = 'debug' | 'info' | 'warn' | 'error' | 'fatal'
+
+export type NixxieLogFields = Record<string, unknown>
+
+export type NixxieLogRecord = {
+  level: NixxieLogLevel
+  message: string
+  /** ISO-8601 timestamp. */
+  time: string
+  /** Bound + per-call structured fields merged together. */
+  fields: NixxieLogFields
+}
+
+/** Receives every emitted log record (e.g. console JSON, a file, an external sink). */
+export type NixxieLogSink = (record: NixxieLogRecord) => void
+
+/** Structured, level-aware logging with bound child loggers. Implemented by @nixxie-cms/logger. */
+export type NixxieLoggerService = {
+  debug(message: string, fields?: NixxieLogFields): void
+  info(message: string, fields?: NixxieLogFields): void
+  warn(message: string, fields?: NixxieLogFields): void
+  error(message: string, fields?: NixxieLogFields): void
+  fatal(message: string, fields?: NixxieLogFields): void
+  /** Emit at an explicit level. */
+  log(level: NixxieLogLevel, message: string, fields?: NixxieLogFields): void
+  /**
+   * Create a child logger that always includes the given bound fields
+   * (e.g. `{ requestId }`). Children inherit the parent's level and sinks.
+   */
+  child(bindings: NixxieLogFields): NixxieLoggerService
+  /** The current minimum level; records below it are dropped. */
+  readonly level: NixxieLogLevel
+}
+
+// ── Backup service ──
+
+export type NixxieBackupFormat = 'json' | 'ndjson'
+
+export type NixxieBackupCollection = {
+  collection: string
+  items: Record<string, unknown>[]
+}
+
+export type NixxieBackupArchive = {
+  version: 1
+  createdAt: string
+  collections: NixxieBackupCollection[]
+}
+
+export type NixxieBackupExportOptions = {
+  /** Collections to include. Omit to export every collection the data source exposes. */
+  collections?: string[]
+}
+
+export type NixxieBackupImportMode = 'create' | 'upsert'
+
+export type NixxieBackupImportOptions = {
+  /** 'create' (default) always inserts; 'upsert' updates existing items by id. */
+  mode?: NixxieBackupImportMode
+  /** Restrict the import to these collections. */
+  collections?: string[]
+  /** Continue past individual item failures instead of throwing. */
+  continueOnError?: boolean
+}
+
+export type NixxieBackupImportResult = {
+  created: number
+  updated: number
+  skipped: number
+  errors: { collection: string; id?: string; error: string }[]
+}
+
+/**
+ * Abstraction over the live data store, supplied by the host app (typically built
+ * from a NixxieContext). Lets the backup service read and write content without
+ * being coupled to Prisma or the GraphQL layer.
+ */
+export type NixxieBackupDataSource = {
+  /** Names of the collections available for export/import. */
+  collections(): string[] | Promise<string[]>
+  /** Read every item of a collection. */
+  read(collection: string): Promise<Record<string, unknown>[]>
+  /** Write items into a collection, honouring the requested mode. */
+  write(
+    collection: string,
+    items: Record<string, unknown>[],
+    mode: NixxieBackupImportMode
+  ): Promise<
+    Omit<NixxieBackupImportResult, 'errors'> & { errors: { id?: string; error: string }[] }
+  >
+  /** Count items in a collection (used by `seed` to detect non-empty targets). */
+  count(collection: string): Promise<number>
+}
+
+/** Content export / import / seed. Implemented by @nixxie-cms/backup. */
+export type NixxieBackupService = {
+  /** Read the data source into an in-memory archive. */
+  export(options?: NixxieBackupExportOptions): Promise<NixxieBackupArchive>
+  /** Serialize an archive to a string in the given format (default 'json'). */
+  serialize(archive: NixxieBackupArchive, format?: NixxieBackupFormat): string
+  /** Parse a serialized archive back into structured form. */
+  parse(text: string, format?: NixxieBackupFormat): NixxieBackupArchive
+  /** Write an archive into the data source. */
+  import(
+    archive: NixxieBackupArchive,
+    options?: NixxieBackupImportOptions
+  ): Promise<NixxieBackupImportResult>
+  /** Import an archive, but only into collections that are currently empty. */
+  seed(archive: NixxieBackupArchive): Promise<NixxieBackupImportResult>
+  /** Gracefully shut down. */
+  close(): Promise<void>
+}
+
 // ── Context ──
 
 export type NixxieContext<TypeInfo extends BaseNixxieTypeInfo = BaseNixxieTypeInfo> = {
   db: NixxieDbAPI<TypeInfo['lists']>
-  query: NixxieListsAPI<TypeInfo['lists']>
+  query: NixxieCollectionsAPI<TypeInfo['lists']>
   graphql: NixxieGraphQLAPI
   prisma: TypeInfo['prisma']
   /** Runtime services configured in nixxie.ts — available everywhere context is available */
@@ -546,6 +1077,12 @@ export type NixxieContext<TypeInfo extends BaseNixxieTypeInfo = BaseNixxieTypeIn
     search: NixxieSearchService | null
     notifications: NixxieNotificationsService | null
     ai: NixxieAiService | null
+    aiRag: NixxieAiRagService | null
+    versioning: NixxieVersioningService | null
+    workflow: NixxieWorkflowService | null
+    apiKeys: NixxieApiKeysService | null
+    logger: NixxieLoggerService | null
+    backup: NixxieBackupService | null
   }
   transaction: <T>(
     f: (context: NixxieContext<TypeInfo>) => MaybePromise<T>,
@@ -584,57 +1121,57 @@ export type NixxieContext<TypeInfo extends BaseNixxieTypeInfo = BaseNixxieTypeIn
 
 // List item API
 
-type UniqueWhereInput<ListTypeInfo extends BaseListTypeInfo> =
-  false extends ListTypeInfo['isSingleton']
-    ? { readonly where: ListTypeInfo['inputs']['uniqueWhere'] }
-    : { readonly where?: ListTypeInfo['inputs']['uniqueWhere'] }
+type UniqueWhereInput<CollectionTypeInfo extends BaseCollectionTypeInfo> =
+  false extends CollectionTypeInfo['isSingleton']
+    ? { readonly where: CollectionTypeInfo['inputs']['uniqueWhere'] }
+    : { readonly where?: CollectionTypeInfo['inputs']['uniqueWhere'] }
 
-type ListAPI<ListTypeInfo extends BaseListTypeInfo> = {
+type CollectionAPI<CollectionTypeInfo extends BaseCollectionTypeInfo> = {
   findMany(
     args?: {
-      readonly where?: ListTypeInfo['inputs']['where']
+      readonly where?: CollectionTypeInfo['inputs']['where']
       readonly take?: number
       readonly skip?: number
       readonly orderBy?:
-        | ListTypeInfo['inputs']['orderBy']
-        | readonly ListTypeInfo['inputs']['orderBy'][]
-      readonly cursor?: ListTypeInfo['inputs']['uniqueWhere']
+        | CollectionTypeInfo['inputs']['orderBy']
+        | readonly CollectionTypeInfo['inputs']['orderBy'][]
+      readonly cursor?: CollectionTypeInfo['inputs']['uniqueWhere']
     } & ResolveFields
   ): Promise<readonly Record<string, any>[]>
-  findOne(args: UniqueWhereInput<ListTypeInfo> & ResolveFields): Promise<Record<string, any>>
-  count(args?: { readonly where?: ListTypeInfo['inputs']['where'] }): Promise<number>
+  findOne(args: UniqueWhereInput<CollectionTypeInfo> & ResolveFields): Promise<Record<string, any>>
+  count(args?: { readonly where?: CollectionTypeInfo['inputs']['where'] }): Promise<number>
   updateOne(
-    args: UniqueWhereInput<ListTypeInfo> & {
-      readonly data: ListTypeInfo['inputs']['update']
+    args: UniqueWhereInput<CollectionTypeInfo> & {
+      readonly data: CollectionTypeInfo['inputs']['update']
     } & ResolveFields
   ): Promise<Record<string, any>>
   updateMany(
     args: {
-      readonly data: readonly (UniqueWhereInput<ListTypeInfo> & {
-        readonly data: ListTypeInfo['inputs']['update']
+      readonly data: readonly (UniqueWhereInput<CollectionTypeInfo> & {
+        readonly data: CollectionTypeInfo['inputs']['update']
       })[]
     } & ResolveFields
   ): Promise<Record<string, any>[]>
   createOne(
-    args: { readonly data: ListTypeInfo['inputs']['create'] } & ResolveFields
+    args: { readonly data: CollectionTypeInfo['inputs']['create'] } & ResolveFields
   ): Promise<Record<string, any>>
   createMany(
     args: {
-      readonly data: readonly ListTypeInfo['inputs']['create'][]
+      readonly data: readonly CollectionTypeInfo['inputs']['create'][]
     } & ResolveFields
   ): Promise<Record<string, any>[]>
   deleteOne(
-    args: UniqueWhereInput<ListTypeInfo> & ResolveFields
+    args: UniqueWhereInput<CollectionTypeInfo> & ResolveFields
   ): Promise<Record<string, any> | null>
   deleteMany(
     args: {
-      readonly where: readonly ListTypeInfo['inputs']['uniqueWhere'][]
+      readonly where: readonly CollectionTypeInfo['inputs']['uniqueWhere'][]
     } & ResolveFields
   ): Promise<Record<string, any>[]>
 }
 
-export type NixxieListsAPI<ListsTypeInfo extends Record<string, BaseListTypeInfo>> = {
-  [Key in keyof ListsTypeInfo]: ListAPI<ListsTypeInfo[Key]>
+export type NixxieCollectionsAPI<ListsTypeInfo extends Record<string, BaseCollectionTypeInfo>> = {
+  [Key in keyof ListsTypeInfo]: CollectionAPI<ListsTypeInfo[Key]>
 }
 
 type ResolveFields = {
@@ -644,41 +1181,41 @@ type ResolveFields = {
   readonly query?: string
 }
 
-type DbAPI<ListTypeInfo extends BaseListTypeInfo> = {
+type DbAPI<CollectionTypeInfo extends BaseCollectionTypeInfo> = {
   findMany(args?: {
-    readonly where?: ListTypeInfo['inputs']['where']
+    readonly where?: CollectionTypeInfo['inputs']['where']
     readonly take?: number
     readonly skip?: number
     readonly orderBy?:
-      | ListTypeInfo['inputs']['orderBy']
-      | readonly ListTypeInfo['inputs']['orderBy'][]
-    readonly cursor?: ListTypeInfo['inputs']['uniqueWhere']
-  }): Promise<readonly ListTypeInfo['item'][]>
-  findOne(args: UniqueWhereInput<ListTypeInfo>): Promise<ListTypeInfo['item'] | null>
-  count(args?: { readonly where?: ListTypeInfo['inputs']['where'] }): Promise<number>
+      | CollectionTypeInfo['inputs']['orderBy']
+      | readonly CollectionTypeInfo['inputs']['orderBy'][]
+    readonly cursor?: CollectionTypeInfo['inputs']['uniqueWhere']
+  }): Promise<readonly CollectionTypeInfo['item'][]>
+  findOne(args: UniqueWhereInput<CollectionTypeInfo>): Promise<CollectionTypeInfo['item'] | null>
+  count(args?: { readonly where?: CollectionTypeInfo['inputs']['where'] }): Promise<number>
   updateOne(
-    args: UniqueWhereInput<ListTypeInfo> & {
-      readonly data: ListTypeInfo['inputs']['update']
+    args: UniqueWhereInput<CollectionTypeInfo> & {
+      readonly data: CollectionTypeInfo['inputs']['update']
     }
-  ): Promise<ListTypeInfo['item']>
+  ): Promise<CollectionTypeInfo['item']>
   updateMany(args: {
-    readonly data: readonly (UniqueWhereInput<ListTypeInfo> & {
-      readonly data: ListTypeInfo['inputs']['update']
+    readonly data: readonly (UniqueWhereInput<CollectionTypeInfo> & {
+      readonly data: CollectionTypeInfo['inputs']['update']
     })[]
-  }): Promise<ListTypeInfo['item'][]>
+  }): Promise<CollectionTypeInfo['item'][]>
   createOne(args: {
-    readonly data: ListTypeInfo['inputs']['create']
-  }): Promise<ListTypeInfo['item']>
+    readonly data: CollectionTypeInfo['inputs']['create']
+  }): Promise<CollectionTypeInfo['item']>
   createMany(args: {
-    readonly data: readonly ListTypeInfo['inputs']['create'][]
-  }): Promise<ListTypeInfo['item'][]>
-  deleteOne(args: UniqueWhereInput<ListTypeInfo>): Promise<ListTypeInfo['item']>
+    readonly data: readonly CollectionTypeInfo['inputs']['create'][]
+  }): Promise<CollectionTypeInfo['item'][]>
+  deleteOne(args: UniqueWhereInput<CollectionTypeInfo>): Promise<CollectionTypeInfo['item']>
   deleteMany(args: {
-    readonly where: readonly ListTypeInfo['inputs']['uniqueWhere'][]
-  }): Promise<ListTypeInfo['item'][]>
+    readonly where: readonly CollectionTypeInfo['inputs']['uniqueWhere'][]
+  }): Promise<CollectionTypeInfo['item'][]>
 }
 
-export type NixxieDbAPI<ListsTypeInfo extends Record<string, BaseListTypeInfo>> = {
+export type NixxieDbAPI<ListsTypeInfo extends Record<string, BaseCollectionTypeInfo>> = {
   [Key in keyof ListsTypeInfo]: DbAPI<ListsTypeInfo[Key]>
 }