@sixb/core 0.1.20 → 0.1.22

package/src/storage/ai-usage/record.ts

@@ -1,8 +1,16 @@
 import { normalizeRequesterGroupIds } from "../../auth/attribution"
+import { isValidFileRef } from "../../blob-storage/validation"
 import { assertJsonValue, isPlainRecord } from "../../json"
+import { MODEL_KINDS } from "../../models/definitions"
 import { normalizeModelProviderIds } from "../../models/events"
 import { isModelReasoning } from "../../models/language-model"
-import type { AiModelCallUsageRecord, RecordAiModelCallInput } from "./types"
+import { AiUsageStorageError } from "./errors"
+import type {
+  AiModelCallFilesRecord,
+  AiModelCallUsageRecord,
+  RecordAiModelCallFilesInput,
+  RecordAiModelCallInput,
+} from "./types"
 import { normalizeAiModelCallUsage } from "./usage"
 
 /** Validate and defensively snapshot one provider-neutral model-call ledger input. */
@@ -19,12 +27,7 @@ export function normalizeAiModelCallRecord(input: RecordAiModelCallInput): AiMod
   }
   assertNonBlank(input.responseId, "responseId")
 
-  if (
-    input.modelKind !== undefined &&
-    !["language", "image", "video", "embedding", "decision", "transcription", "reranking"].includes(
-      input.modelKind
-    )
-  ) {
+  if (input.modelKind !== undefined && !MODEL_KINDS.includes(input.modelKind)) {
     throw new TypeError("[Sixb] AI model kind is invalid.")
   }
   const occurredAt = cloneValidDate(input.occurredAt, "occurredAt")
@@ -56,6 +59,40 @@ export function normalizeAiModelCallRecord(input: RecordAiModelCallInput): AiMod
   }
 }
 
+/** Validate and defensively snapshot the files one model call produced. */
+export function normalizeAiModelCallFilesRecord(
+  input: RecordAiModelCallFilesInput
+): AiModelCallFilesRecord {
+  assertNonBlank(input.projectId, "projectId")
+  assertAiUsageExecutionId(input.executionId)
+  assertNonBlank(input.callId, "callId")
+  if (!Array.isArray(input.files) || input.files.length === 0) {
+    throw new TypeError("[Sixb] AI model-call files must be a nonempty array.")
+  }
+  if (!input.files.every(isValidFileRef)) {
+    throw new TypeError("[Sixb] AI model-call files must be valid FileRefs.")
+  }
+  return {
+    projectId: input.projectId,
+    executionId: input.executionId,
+    callId: input.callId,
+    files: structuredClone(input.files),
+    recordedAt: cloneValidDate(input.recordedAt ?? new Date(), "recordedAt"),
+  }
+}
+
+/** A call's files belong to the execution that first recorded them. */
+export function assertSameCallExecution(
+  existing: AiModelCallFilesRecord,
+  input: Pick<AiModelCallFilesRecord, "executionId" | "callId">
+): AiModelCallFilesRecord {
+  if (existing.executionId === input.executionId) return existing
+  throw new AiUsageStorageError(
+    "duplicate_id",
+    `[Sixb] AI model call '${input.callId}' already has files from another execution.`
+  )
+}
+
 function cloneRequestedReasoning(
   reasoning: RecordAiModelCallInput["requestedReasoning"]
 ): RecordAiModelCallInput["requestedReasoning"] {

package/src/storage/ai-usage/types.ts

@@ -1,3 +1,4 @@
+import type { FileRef } from "../../blob-storage/types"
 import type { ReadonlyJsonObject } from "../../json"
 import type { ModelReasoning } from "../../models/language-model"
 
@@ -15,6 +16,14 @@ export interface AiModelCallUsageInput {
   readonly cacheWriteInputTokens?: number
   readonly textOutputTokens?: number
   readonly reasoningOutputTokens?: number
+  /** Output tokens that encode generated images, within outputTokens. */
+  readonly imageOutputTokens?: number
+  /** Output tokens that encode generated audio, within outputTokens. */
+  readonly audioOutputTokens?: number
+  /** Images the call returned. */
+  readonly outputImages?: number
+  /** Input characters, counted by the provider's own billing rule. */
+  readonly inputCharacters?: number
 }
 
 /** Normalized usage for one completed model call. Token details overlap their input/output totals. */
@@ -93,6 +102,27 @@ export interface GetLatestAiModelCallForExecutionInput {
   readonly executionId: string
 }
 
+/**
+ * The files one completed call produced, recorded once they are stored. The execution that made
+ * the call decides who may read them.
+ */
+export interface AiModelCallFilesRecord {
+  readonly projectId: string
+  readonly executionId: string
+  readonly callId: string
+  readonly files: readonly FileRef[]
+  readonly recordedAt: Date
+}
+
+export type RecordAiModelCallFilesInput = Omit<AiModelCallFilesRecord, "recordedAt"> & {
+  readonly recordedAt?: Date
+}
+
+export interface GetAiModelCallFilesInput {
+  readonly projectId: string
+  readonly callId: string
+}
+
 /** Durable, provider-neutral accounting for completed model calls. */
 export interface AiUsageStorage {
   /**
@@ -117,4 +147,12 @@ export interface AiUsageStorage {
   summarizeExecutions(
     input: SummarizeAiUsageExecutionsInput
   ): Promise<readonly AiUsageExecutionSummary[]>
+
+  /**
+   * Record the files a call produced, once per project and call ID. Recording the same call again
+   * returns the first record; naming another execution for it is refused.
+   */
+  recordModelCallFiles(input: RecordAiModelCallFilesInput): Promise<AiModelCallFilesRecord>
+
+  getModelCallFiles(input: GetAiModelCallFilesInput): Promise<AiModelCallFilesRecord | null>
 }

package/src/storage/ai-usage/usage.ts

@@ -1,6 +1,7 @@
 import type { AiModelCallUsage, AiModelCallUsageInput } from "./types"
 
-const USAGE_FIELDS = [
+/** Every count a model call can report. */
+export const AI_USAGE_FIELDS = [
   "inputTokens",
   "outputTokens",
   "uncachedInputTokens",
@@ -9,7 +10,12 @@ const USAGE_FIELDS = [
   "textOutputTokens",
   "reasoningOutputTokens",
   "audioDurationMs",
+  "imageOutputTokens",
+  "audioOutputTokens",
+  "outputImages",
+  "inputCharacters",
 ] as const
+const USAGE_FIELDS = AI_USAGE_FIELDS
 
 type AiUsageField = (typeof USAGE_FIELDS)[number]
 
@@ -48,6 +54,14 @@ export function normalizeAiModelCallUsage(input: AiModelCallUsageInput): AiModel
     ...(input.reasoningOutputTokens === undefined
       ? {}
       : { reasoningOutputTokens: input.reasoningOutputTokens }),
+    ...(input.imageOutputTokens === undefined
+      ? {}
+      : { imageOutputTokens: input.imageOutputTokens }),
+    ...(input.audioOutputTokens === undefined
+      ? {}
+      : { audioOutputTokens: input.audioOutputTokens }),
+    ...(input.outputImages === undefined ? {} : { outputImages: input.outputImages }),
+    ...(input.inputCharacters === undefined ? {} : { inputCharacters: input.inputCharacters }),
     reportingStatus,
   }
 }

package/src/storage/artifacts/errors.ts

@@ -0,0 +1,28 @@
+import type { Principal } from "../../auth"
+
+export type ArtifactStorageErrorCode =
+  | "artifact_exists"
+  | "artifact_not_found"
+  | "artifact_kind_mismatch"
+  | "artifact_moved"
+  | "artifact_state_full"
+
+/** The version an artifact had moved on to, and who published it, when a publish found it moved. */
+export interface ArtifactLatestVersion {
+  readonly version: number
+  readonly author: Principal
+}
+
+/** Error for artifact-storage invariants. Callers branch on `code` rather than message text. */
+export class ArtifactStorageError extends Error {
+  readonly name = "ArtifactStorageError"
+
+  constructor(
+    readonly code: ArtifactStorageErrorCode,
+    message: string,
+    /** With `artifact_moved`: the latest version, which the publish was not based on. */
+    readonly latest?: ArtifactLatestVersion
+  ) {
+    super(message)
+  }
+}

package/src/storage/artifacts/in-memory.ts

@@ -0,0 +1,388 @@
+import { type Principal, principalsEqual } from "../../auth"
+import { paginate } from "../pagination"
+import { artifactStateBytes, artifactStorageErrors, checkArtifactStateWrite } from "./record"
+import type {
+  ArtifactFrameGrantRecord,
+  ArtifactRecord,
+  ArtifactStateEntry,
+  ArtifactStateKeyInput,
+  ArtifactStateScope,
+  ArtifactStorage,
+  ArtifactVersionInput,
+  ArtifactVersionRecord,
+  CopyArtifactInput,
+  CreateArtifactInput,
+  DeleteArtifactInput,
+  DeleteArtifactVersionsByOriginInput,
+  DeleteExpiredArtifactFrameGrantsInput,
+  FindArtifactFrameGrantInput,
+  GetArtifactInput,
+  GetArtifactVersionInput,
+  ListArtifactsInput,
+  ListArtifactsResult,
+  ListArtifactVersionsInput,
+  ListArtifactVersionsResult,
+  ListReferencingVersionsInput,
+  PublishArtifactVersionInput,
+  PublishedArtifactVersion,
+  SetArtifactStateInput,
+} from "./types"
+
+interface StoredArtifact {
+  readonly record: ArtifactRecord
+  /** Oldest first. */
+  readonly versions: readonly ArtifactVersionRecord[]
+  /** The number the next version gets; it only grows, so a deleted number is never reused. */
+  readonly nextVersion: number
+  /** The threads it is shared in, by id. */
+  readonly threads: ReadonlyMap<string, ThreadLink>
+}
+
+interface ThreadLink {
+  /** When it was first shared there. */
+  readonly sharedAt: Date
+  /** Copied for the thread: shared there whatever versions it keeps. */
+  readonly copied: boolean
+}
+
+interface InMemoryArtifactSnapshot {
+  readonly artifacts: ReadonlyMap<string, StoredArtifact>
+  readonly frameGrants: ReadonlyMap<string, ArtifactFrameGrantRecord>
+  readonly state: ReadonlyMap<string, ReadonlyMap<string, ArtifactStateEntry>>
+}
+
+export class InMemoryArtifactStorage implements ArtifactStorage {
+  private artifacts = new Map<string, StoredArtifact>()
+  private frameGrants = new Map<string, ArtifactFrameGrantRecord>()
+  /** By artifact and reader, then by key. */
+  private state = new Map<string, Map<string, ArtifactStateEntry>>()
+
+  async create(input: CreateArtifactInput): Promise<PublishedArtifactVersion> {
+    const key = artifactKey(input.projectId, input.id)
+    if (this.artifacts.has(key)) throw artifactStorageErrors.exists(input.id)
+    const version = versionRecord(input.projectId, input.id, 1, input.version)
+    const record: ArtifactRecord = {
+      projectId: input.projectId,
+      id: input.id,
+      kind: input.kind,
+      title: version.title,
+      owner: { ...input.owner },
+      latestVersion: 1,
+      createdAt: new Date(version.createdAt),
+      updatedAt: new Date(version.createdAt),
+    }
+    this.artifacts.set(key, {
+      record,
+      versions: [version],
+      nextVersion: 2,
+      threads: sharedIn(new Map(), version),
+    })
+    return published(record, version)
+  }
+
+  async publish(input: PublishArtifactVersionInput): Promise<PublishedArtifactVersion> {
+    const key = artifactKey(input.projectId, input.artifactId)
+    const stored = this.artifacts.get(key)
+    if (!stored) throw artifactStorageErrors.notFound(input.artifactId)
+    if (stored.record.kind !== input.kind) {
+      throw artifactStorageErrors.kindMismatch(input.artifactId, stored.record.kind, input.kind)
+    }
+    const latest = stored.versions.find(
+      (candidate) => candidate.version === stored.record.latestVersion
+    )
+    if (input.baseVersion !== undefined && latest && latest.version !== input.baseVersion) {
+      throw artifactStorageErrors.moved(input.artifactId, input.baseVersion, {
+        version: latest.version,
+        author: structuredClone(latest.author),
+      })
+    }
+    const version = versionRecord(
+      input.projectId,
+      input.artifactId,
+      stored.nextVersion,
+      input.version
+    )
+    const record: ArtifactRecord = {
+      ...stored.record,
+      title: version.title,
+      latestVersion: version.version,
+      updatedAt: new Date(version.createdAt),
+    }
+    this.artifacts.set(key, {
+      record,
+      versions: [...stored.versions, version],
+      nextVersion: stored.nextVersion + 1,
+      threads: sharedIn(stored.threads, version),
+    })
+    return published(record, version)
+  }
+
+  async get(input: GetArtifactInput): Promise<ArtifactRecord | null> {
+    const stored = this.artifacts.get(artifactKey(input.projectId, input.id))
+    return stored ? structuredClone(stored.record) : null
+  }
+
+  async list(input: ListArtifactsInput): Promise<ListArtifactsResult> {
+    const matching = [...this.artifacts.values()]
+      .filter(
+        ({ record, threads }) =>
+          record.projectId === input.projectId &&
+          (!input.owner || principalsEqual(record.owner, input.owner)) &&
+          (input.kind === undefined || record.kind === input.kind) &&
+          (input.threadId === undefined || threads.has(input.threadId))
+      )
+      .map(({ record }) => record)
+      .sort(
+        (left, right) =>
+          right.updatedAt.getTime() - left.updatedAt.getTime() || left.id.localeCompare(right.id)
+      )
+    const { page, hasMore, total } = paginate(matching, input)
+    return { artifacts: structuredClone(page), hasMore, total }
+  }
+
+  async getVersion(input: GetArtifactVersionInput): Promise<ArtifactVersionRecord | null> {
+    const stored = this.artifacts.get(artifactKey(input.projectId, input.artifactId))
+    const version = stored?.versions.find((candidate) => candidate.version === input.version)
+    return version ? structuredClone(version) : null
+  }
+
+  async listVersions(input: ListArtifactVersionsInput): Promise<ListArtifactVersionsResult> {
+    const stored = this.artifacts.get(artifactKey(input.projectId, input.artifactId))
+    const newestFirst = [...(stored?.versions ?? [])].reverse()
+    const { page, hasMore, total } = paginate(newestFirst, input)
+    return { versions: structuredClone(page), hasMore, total }
+  }
+
+  async listThreadIds(input: GetArtifactInput): Promise<string[]> {
+    const stored = this.artifacts.get(artifactKey(input.projectId, input.id))
+    // Code-unit order, as SQLite compares text.
+    return [...(stored?.threads.keys() ?? [])].sort((left, right) => (left < right ? -1 : 1))
+  }
+
+  async copy(input: CopyArtifactInput): Promise<ArtifactRecord> {
+    const source = this.artifacts.get(artifactKey(input.projectId, input.sourceId))
+    if (!source) throw artifactStorageErrors.notFound(input.sourceId)
+
+    const key = artifactKey(input.projectId, input.id)
+    if (this.artifacts.has(key)) throw artifactStorageErrors.exists(input.id)
+
+    const record: ArtifactRecord = { ...source.record, id: input.id, owner: { ...input.owner } }
+    const versions = source.versions.map(({ origin: _origin, ...version }) =>
+      structuredClone({ ...version, artifactId: input.id })
+    )
+    const sharedAt = new Date(input.copiedAt ?? new Date())
+    this.artifacts.set(key, {
+      record,
+      versions,
+      nextVersion: source.nextVersion,
+      threads: new Map([[input.threadId, { sharedAt, copied: true }]]),
+    })
+    return structuredClone(record)
+  }
+
+  async listReferencingVersions(
+    input: ListReferencingVersionsInput
+  ): Promise<ArtifactVersionRecord[]> {
+    const prefix = `artifact:${input.artifactId}`
+    const referencing: ArtifactVersionRecord[] = []
+    for (const stored of this.artifacts.values()) {
+      if (stored.record.projectId !== input.projectId) continue
+      const latest = stored.versions.find(
+        (candidate) => candidate.version === stored.record.latestVersion
+      )
+      if (latest?.references.some((reference) => refersTo(reference.address, prefix))) {
+        referencing.push(structuredClone(latest))
+      }
+    }
+    // Code-unit order, as SQLite compares text.
+    return referencing.sort((left, right) => (left.artifactId < right.artifactId ? -1 : 1))
+  }
+
+  async createFrameGrant(record: ArtifactFrameGrantRecord): Promise<void> {
+    if (!this.artifacts.has(artifactKey(record.projectId, record.artifactId))) {
+      throw artifactStorageErrors.notFound(record.artifactId)
+    }
+    this.frameGrants.set(artifactKey(record.projectId, record.tokenHash), structuredClone(record))
+  }
+
+  async findFrameGrant(
+    input: FindArtifactFrameGrantInput
+  ): Promise<ArtifactFrameGrantRecord | null> {
+    const grant = this.frameGrants.get(artifactKey(input.projectId, input.tokenHash))
+    return grant ? structuredClone(grant) : null
+  }
+
+  async deleteExpiredFrameGrants(input: DeleteExpiredArtifactFrameGrantsInput): Promise<number> {
+    let deleted = 0
+    for (const [key, grant] of this.frameGrants) {
+      if (deleted >= input.limit) break
+      if (grant.projectId !== input.projectId || grant.expiresAt >= input.expiredBefore) continue
+      this.frameGrants.delete(key)
+      deleted += 1
+    }
+    return deleted
+  }
+
+  async getState(input: ArtifactStateKeyInput): Promise<ArtifactStateEntry | null> {
+    const entry = this.state.get(stateKey(input))?.get(input.key)
+    return entry ? structuredClone(entry) : null
+  }
+
+  async setState(input: SetArtifactStateInput): Promise<void> {
+    if (!this.artifacts.has(artifactKey(input.projectId, input.artifactId))) {
+      throw artifactStorageErrors.notFound(input.artifactId)
+    }
+    const kept = this.state.get(stateKey(input)) ?? new Map<string, ArtifactStateEntry>()
+    const others = [...kept.values()].filter((entry) => entry.key !== input.key)
+    const sizeBytes = artifactStateBytes(input.value)
+    checkArtifactStateWrite({
+      key: input.key,
+      valueBytes: sizeBytes,
+      others: {
+        keys: others.length,
+        bytes: others.reduce((total, entry) => total + entry.sizeBytes, 0),
+      },
+    })
+    kept.set(input.key, {
+      key: input.key,
+      value: input.value,
+      sizeBytes,
+      updatedAt: new Date(input.updatedAt),
+    })
+    this.state.set(stateKey(input), kept)
+  }
+
+  async deleteState(input: ArtifactStateKeyInput): Promise<boolean> {
+    return this.state.get(stateKey(input))?.delete(input.key) ?? false
+  }
+
+  async listState(input: ArtifactStateScope): Promise<ArtifactStateEntry[]> {
+    const kept = [...(this.state.get(stateKey(input))?.values() ?? [])]
+    // Code-unit order, as SQLite compares text.
+    return structuredClone(kept.sort((left, right) => (left.key < right.key ? -1 : 1)))
+  }
+
+  async clearState(input: ArtifactStateScope): Promise<number> {
+    const count = this.state.get(stateKey(input))?.size ?? 0
+    this.state.delete(stateKey(input))
+    return count
+  }
+
+  async delete(input: DeleteArtifactInput): Promise<boolean> {
+    return this.deleteArtifact(artifactKey(input.projectId, input.id))
+  }
+
+  async deleteVersionsByOrigin(input: DeleteArtifactVersionsByOriginInput): Promise<number> {
+    let deleted = 0
+    for (const [key, stored] of this.artifacts) {
+      if (stored.record.projectId !== input.projectId) continue
+      const remaining = stored.versions.filter((version) => version.origin?.runId !== input.runId)
+      if (remaining.length === stored.versions.length) continue
+      deleted += stored.versions.length - remaining.length
+      const latest = remaining.at(-1)
+      if (!latest) {
+        this.deleteArtifact(key)
+        continue
+      }
+
+      // A run publishes from one thread: the link stays only if a version from it remains.
+      const threadId = stored.versions.find((version) => version.origin?.runId === input.runId)
+        ?.origin?.threadId
+      const threads = new Map(stored.threads)
+      if (
+        threadId &&
+        !threads.get(threadId)?.copied &&
+        !remaining.some((version) => version.origin?.threadId === threadId)
+      ) {
+        threads.delete(threadId)
+      }
+
+      this.artifacts.set(key, {
+        ...stored,
+        record: {
+          ...stored.record,
+          title: latest.title,
+          latestVersion: latest.version,
+          updatedAt: new Date(latest.createdAt),
+        },
+        versions: remaining,
+        threads,
+      })
+    }
+    return deleted
+  }
+
+  snapshot(): InMemoryArtifactSnapshot {
+    return structuredClone({
+      artifacts: this.artifacts,
+      frameGrants: this.frameGrants,
+      state: this.state,
+    })
+  }
+
+  restore(snapshot: InMemoryArtifactSnapshot): void {
+    const restored = structuredClone(snapshot)
+    this.artifacts = new Map(restored.artifacts)
+    this.frameGrants = new Map(restored.frameGrants)
+    this.state = new Map([...restored.state].map(([key, kept]) => [key, new Map(kept)]))
+  }
+
+  /**
+   * Deletes an artifact with its frame grants and what it keeps for its readers, as the SQL
+   * providers' cascade does.
+   */
+  private deleteArtifact(key: string): boolean {
+    for (const [grantKey, grant] of this.frameGrants) {
+      if (artifactKey(grant.projectId, grant.artifactId) === key) this.frameGrants.delete(grantKey)
+    }
+    for (const kept of this.state.keys()) {
+      if (kept.startsWith(`${key}\0`)) this.state.delete(kept)
+    }
+    return this.artifacts.delete(key)
+  }
+}
+
+function versionRecord(
+  projectId: string,
+  artifactId: string,
+  version: number,
+  input: ArtifactVersionInput
+): ArtifactVersionRecord {
+  return structuredClone({ ...input, projectId, artifactId, version })
+}
+
+/** The links an artifact has once this version is stored: its origin's thread among them. */
+function sharedIn(
+  threads: ReadonlyMap<string, ThreadLink>,
+  version: ArtifactVersionRecord
+): ReadonlyMap<string, ThreadLink> {
+  const threadId = version.origin?.threadId
+  if (!threadId || threads.has(threadId)) return threads
+
+  return new Map(threads).set(threadId, { sharedAt: new Date(version.createdAt), copied: false })
+}
+
+function published(
+  record: ArtifactRecord,
+  version: ArtifactVersionRecord
+): PublishedArtifactVersion {
+  return structuredClone({ artifact: record, version })
+}
+
+function artifactKey(projectId: string, id: string): string {
+  return `${projectId}\0${id}`
+}
+
+/** An artifact's key, then its reader's. */
+function stateKey(scope: {
+  readonly projectId: string
+  readonly artifactId: string
+  readonly principal: Principal
+}): string {
+  return `${artifactKey(scope.projectId, scope.artifactId)}\0${scope.principal.type}\0${scope.principal.id}`
+}
+
+/** Whether an address names the artifact `artifact:<id>` is, at any version, file, or part. */
+function refersTo(address: string, prefix: string): boolean {
+  return address.startsWith(prefix) && /^(?:$|[@/#])/.test(address.slice(prefix.length))
+}

package/src/storage/artifacts/index.ts

@@ -0,0 +1,35 @@
+export type { ArtifactLatestVersion, ArtifactStorageErrorCode } from "./errors"
+export { ArtifactStorageError } from "./errors"
+export { InMemoryArtifactStorage } from "./in-memory"
+export type {
+  ArtifactFile,
+  ArtifactFrameGrantRecord,
+  ArtifactFrameTarget,
+  ArtifactKind,
+  ArtifactOrigin,
+  ArtifactOutline,
+  ArtifactRecord,
+  ArtifactReference,
+  ArtifactStateEntry,
+  ArtifactStateKeyInput,
+  ArtifactStateScope,
+  ArtifactStorage,
+  ArtifactVersionInput,
+  ArtifactVersionRecord,
+  CopyArtifactInput,
+  CreateArtifactInput,
+  DeleteArtifactInput,
+  DeleteArtifactVersionsByOriginInput,
+  DeleteExpiredArtifactFrameGrantsInput,
+  FindArtifactFrameGrantInput,
+  GetArtifactInput,
+  GetArtifactVersionInput,
+  ListArtifactsInput,
+  ListArtifactsResult,
+  ListArtifactVersionsInput,
+  ListArtifactVersionsResult,
+  ListReferencingVersionsInput,
+  PublishArtifactVersionInput,
+  PublishedArtifactVersion,
+  SetArtifactStateInput,
+} from "./types"