@sixb/core 0.1.21 → 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

@@ -1,7 +1,17 @@
+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 {
@@ -9,7 +19,9 @@ export class ArtifactStorageError extends Error {
 
   constructor(
     readonly code: ArtifactStorageErrorCode,
-    message: string
+    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

@@ -1,12 +1,16 @@
-import { principalsEqual } from "../../auth"
+import { type Principal, principalsEqual } from "../../auth"
 import { paginate } from "../pagination"
-import { artifactStorageErrors } from "./record"
+import { artifactStateBytes, artifactStorageErrors, checkArtifactStateWrite } from "./record"
 import type {
   ArtifactFrameGrantRecord,
   ArtifactRecord,
+  ArtifactStateEntry,
+  ArtifactStateKeyInput,
+  ArtifactStateScope,
   ArtifactStorage,
   ArtifactVersionInput,
   ArtifactVersionRecord,
+  CopyArtifactInput,
   CreateArtifactInput,
   DeleteArtifactInput,
   DeleteArtifactVersionsByOriginInput,
@@ -21,6 +25,7 @@ import type {
   ListReferencingVersionsInput,
   PublishArtifactVersionInput,
   PublishedArtifactVersion,
+  SetArtifactStateInput,
 } from "./types"
 
 interface StoredArtifact {
@@ -29,16 +34,28 @@ interface StoredArtifact {
   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)
@@ -54,7 +71,12 @@ export class InMemoryArtifactStorage implements ArtifactStorage {
       createdAt: new Date(version.createdAt),
       updatedAt: new Date(version.createdAt),
     }
-    this.artifacts.set(key, { record, versions: [version], nextVersion: 2 })
+    this.artifacts.set(key, {
+      record,
+      versions: [version],
+      nextVersion: 2,
+      threads: sharedIn(new Map(), version),
+    })
     return published(record, version)
   }
 
@@ -65,6 +87,15 @@ export class InMemoryArtifactStorage implements ArtifactStorage {
     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,
@@ -81,6 +112,7 @@ export class InMemoryArtifactStorage implements ArtifactStorage {
       record,
       versions: [...stored.versions, version],
       nextVersion: stored.nextVersion + 1,
+      threads: sharedIn(stored.threads, version),
     })
     return published(record, version)
   }
@@ -93,12 +125,11 @@ export class InMemoryArtifactStorage implements ArtifactStorage {
   async list(input: ListArtifactsInput): Promise<ListArtifactsResult> {
     const matching = [...this.artifacts.values()]
       .filter(
-        ({ record, versions }) =>
+        ({ record, threads }) =>
           record.projectId === input.projectId &&
           (!input.owner || principalsEqual(record.owner, input.owner)) &&
           (input.kind === undefined || record.kind === input.kind) &&
-          (input.originThreadId === undefined ||
-            versions.some((version) => version.origin?.threadId === input.originThreadId))
+          (input.threadId === undefined || threads.has(input.threadId))
       )
       .map(({ record }) => record)
       .sort(
@@ -122,6 +153,33 @@ export class InMemoryArtifactStorage implements ArtifactStorage {
     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[]> {
@@ -165,6 +223,51 @@ export class InMemoryArtifactStorage implements ArtifactStorage {
     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))
   }
@@ -181,6 +284,19 @@ export class InMemoryArtifactStorage implements ArtifactStorage {
         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: {
@@ -190,26 +306,38 @@ export class InMemoryArtifactStorage implements ArtifactStorage {
           updatedAt: new Date(latest.createdAt),
         },
         versions: remaining,
+        threads,
       })
     }
     return deleted
   }
 
   snapshot(): InMemoryArtifactSnapshot {
-    return structuredClone({ artifacts: this.artifacts, frameGrants: this.frameGrants })
+    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, as the SQL providers' cascade does. */
+  /**
+   * 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)
   }
 }
@@ -223,6 +351,17 @@ function versionRecord(
   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
@@ -234,6 +373,15 @@ 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

@@ -1,4 +1,4 @@
-export type { ArtifactStorageErrorCode } from "./errors"
+export type { ArtifactLatestVersion, ArtifactStorageErrorCode } from "./errors"
 export { ArtifactStorageError } from "./errors"
 export { InMemoryArtifactStorage } from "./in-memory"
 export type {
@@ -10,9 +10,13 @@ export type {
   ArtifactOutline,
   ArtifactRecord,
   ArtifactReference,
+  ArtifactStateEntry,
+  ArtifactStateKeyInput,
+  ArtifactStateScope,
   ArtifactStorage,
   ArtifactVersionInput,
   ArtifactVersionRecord,
+  CopyArtifactInput,
   CreateArtifactInput,
   DeleteArtifactInput,
   DeleteArtifactVersionsByOriginInput,
@@ -27,4 +31,5 @@ export type {
   ListReferencingVersionsInput,
   PublishArtifactVersionInput,
   PublishedArtifactVersion,
+  SetArtifactStateInput,
 } from "./types"

package/src/storage/artifacts/record.ts

@@ -1,15 +1,17 @@
 import { isArtifactKind } from "../../artifacts/kinds"
+import { ARTIFACT_STATE_LIMITS } from "../../artifacts/limits"
 import type { ArtifactOutline } from "../../artifacts/outline"
 import type { ArtifactReference } from "../../artifacts/references"
 import type { Principal } from "../../auth"
 import { isFileRef } from "../../blob-storage"
-import { ArtifactStorageError } from "./errors"
+import { type ArtifactLatestVersion, ArtifactStorageError } from "./errors"
 import type {
   ArtifactFile,
   ArtifactFrameGrantRecord,
   ArtifactFrameTarget,
   ArtifactKind,
   ArtifactRecord,
+  ArtifactStateEntry,
   ArtifactVersionRecord,
 } from "./types"
 
@@ -82,6 +84,57 @@ export function parseArtifactFrameGrantRow(row: Row): ArtifactFrameGrantRecord {
   }
 }
 
+export function parseArtifactStateRow(row: Row): ArtifactStateEntry {
+  const key = text(row.key, "key", "artifact state")
+  const where = `artifact state '${key}'`
+  const sizeBytes = Number(row.sizeBytes)
+  if (!Number.isSafeInteger(sizeBytes) || sizeBytes < 0) {
+    throw corrupt(where, "sizeBytes is not a byte count")
+  }
+  return {
+    key,
+    value: text(row.value, "value", where),
+    sizeBytes,
+    updatedAt: date(row.updatedAt, "updatedAt", where),
+  }
+}
+
+/** A value's UTF-8 bytes, which a reader's state limits count. */
+export function artifactStateBytes(value: string): number {
+  return new TextEncoder().encode(value).byteLength
+}
+
+/**
+ * Throws `artifact_state_full` when a value would take a reader past `ARTIFACT_STATE_LIMITS`.
+ * `others` is what the reader keeps under every other key, so replacing a value counts once.
+ */
+export function checkArtifactStateWrite(input: {
+  readonly key: string
+  readonly valueBytes: number
+  readonly others: { readonly keys: number; readonly bytes: number }
+}): void {
+  const limits = ARTIFACT_STATE_LIMITS
+  if (input.valueBytes > limits.maxValueBytes) {
+    throw artifactStorageErrors.stateFull(
+      `[Sixb] '${input.key}' is ${kilobytes(input.valueBytes)}; a page keeps at most ${kilobytes(limits.maxValueBytes)} under one key.`
+    )
+  }
+  if (input.others.keys + 1 > limits.maxKeys) {
+    throw artifactStorageErrors.stateFull(
+      `[Sixb] A page keeps at most ${limits.maxKeys} keys for each reader: delete one before keeping '${input.key}'.`
+    )
+  }
+  if (input.others.bytes + input.valueBytes > limits.maxBytes) {
+    throw artifactStorageErrors.stateFull(
+      `[Sixb] A page keeps at most ${kilobytes(limits.maxBytes)} for each reader; '${input.key}' would take it to ${kilobytes(input.others.bytes + input.valueBytes)}.`
+    )
+  }
+}
+
+function kilobytes(bytes: number): string {
+  return `${Math.ceil(bytes / 1024).toLocaleString("en-US")} KB`
+}
+
 /** The errors every provider raises, with one wording. */
 export const artifactStorageErrors = {
   exists: (id: string) =>
@@ -93,6 +146,13 @@ export const artifactStorageErrors = {
       "artifact_kind_mismatch",
       `[Sixb] Artifact '${id}' is a ${kind}; it cannot take a ${requested} version.`
     ),
+  moved: (id: string, baseVersion: number, latest: ArtifactLatestVersion) =>
+    new ArtifactStorageError(
+      "artifact_moved",
+      `[Sixb] Artifact '${id}' is at version ${latest.version}, not version ${baseVersion}, which this publish was based on.`,
+      latest
+    ),
+  stateFull: (message: string) => new ArtifactStorageError("artifact_state_full", message),
 }
 
 function files(value: unknown, where: string): ArtifactFile[] {