@sixb/core 0.1.15 → 0.1.17

package/src/runtime/internal.ts

@@ -20,4 +20,5 @@ export {
   registerOntologyMutationRuntime,
   shareOntologyMutationRuntime,
 } from "./ontology-mutations"
+export { setApiPublicOrigin } from "./public-origin"
 export type { SixbHostContext, SixbRuntimeContext } from "./types"

package/src/runtime/public-origin.ts

@@ -0,0 +1,33 @@
+/**
+ * The origin the API is reachable at from outside, for features that hand out absolute URLs a
+ * third party will fetch. It is deployment topology, not app configuration: the API server
+ * records the `publicOrigin` it was started with, and the CLI records `SIXB_API_PUBLIC_ORIGIN`
+ * for worker processes. A process that never learns it cannot issue such URLs.
+ */
+
+const apiPublicOrigins = new WeakMap<object, string>()
+
+/** Record where the API is reachable. A host served by several servers keeps the latest one. */
+export function setApiPublicOrigin(host: object, origin: string): void {
+  apiPublicOrigins.set(host, normalizeOrigin(origin))
+}
+
+export function getApiPublicOrigin(host: object): string | undefined {
+  return apiPublicOrigins.get(host)
+}
+
+function normalizeOrigin(value: string): string {
+  let url: URL
+  try {
+    url = new URL(value)
+  } catch {
+    throw new Error(`[Sixb] Invalid API public origin: '${value}'.`)
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new Error("[Sixb] The API public origin must use http or https.")
+  }
+  if (url.pathname !== "/" || url.search || url.hash) {
+    throw new Error("[Sixb] The API public origin must be an origin, not a full URL.")
+  }
+  return url.origin
+}

package/src/runtime/sixb.ts

@@ -65,6 +65,7 @@ export interface SixbDependencies {
   readonly connectorService: ConnectorService
   readonly connectorConnections?: ConnectorConnectionProcess
   readonly blobStorage: BlobStorage
+  readonly apiPublicOrigin: () => string | undefined
   readonly lakeStorage: LakeStorage
 }
 
@@ -129,13 +130,23 @@ function createExecutionFacades<TParams extends Record<string, unknown>>(
       dependencies.definitions.models,
       dependencies.sandbox
     ),
-    models: createModelsRuntime(runtime, execution, dependencies.definitions.models),
+    models: createModelsRuntime(
+      runtime,
+      execution,
+      dependencies.definitions.models,
+      dependencies.blobStorage
+    ),
     aiUsage: createAiUsageRuntime(runtime, dependencies.definitions.security),
     events: createEventsRuntime(runtime),
     logs: createLogsRuntime(runtime, dependencies.logging),
     schedules: createSchedulesRuntime(runtime, dependencies.definitions.schedules),
     shares: createSharesRuntime(runtime, execution, dependencies.definitions.shares),
     connector: createConnectorRuntime(runtime, execution, dependencies.connectorService),
-    blobs: createBlobsRuntime(runtime, execution, dependencies.blobStorage),
+    blobs: createBlobsRuntime(
+      runtime,
+      execution,
+      dependencies.blobStorage,
+      dependencies.apiPublicOrigin
+    ),
   }
 }

package/src/runtime/types.ts

@@ -16,7 +16,7 @@ import type { Broker } from "../broker"
 import type { DomainEventLog } from "../events"
 import type { RuntimeAuthorization } from "../execution"
 import type { AuthorizedObjectReader } from "../execution/authorized-object-reader"
-import type { EmbeddingModelCatalog } from "../models"
+import type { EmbeddingModelCatalog, RerankingModelCatalog, RerankingModelRef } from "../models"
 import type { ModelExecutionSession } from "../models/execution/session"
 import type {
   ObjectQuery,
@@ -58,6 +58,7 @@ import type { ActionRunRecord, ObjectLinkRow, Storage } from "../storage"
  */
 export interface SixbHostContext {
   readonly embeddingModels?: EmbeddingModelCatalog
+  readonly rerankingModels?: RerankingModelCatalog
   readonly projectId: string
   readonly broker: Broker
   readonly ontology: OntologyRegistry
@@ -414,6 +415,12 @@ export type ObjectQueryFacetBucket = {
   count: number
 }
 
+/** Total and facet buckets are calculated from the same matching set. */
+export type ObjectQueryFacetsResult = {
+  total: number
+  facets: ObjectQueryFacetResult[]
+}
+
 export type ObjectQueryFacetResult = {
   propertyId: string
   buckets: ObjectQueryFacetBucket[]
@@ -669,6 +676,9 @@ export interface ObjectQueryBuilder<
     options: { k: number }
   ): ObjectQueryBuilder<TObjectType, TRow>
 
+  /** Reorder up to 100 vector candidates with an explicitly registered server-side model. */
+  rerank(options: { model: RerankingModelRef }): ObjectQueryBuilder<TObjectType, TRow>
+
   /** Follow an outgoing link and make the linked object type the current result type. */
   traverse<TLinkToken extends LinkToken<TObjectType["id"], string, LinkTargetObjectTypeIdValue>>(
     link: TLinkToken,
@@ -750,7 +760,7 @@ export interface ObjectQueryBuilder<
   exists(): Promise<boolean>
 
   /** Count matching objects by configured facetable properties. */
-  facets(input: readonly ObjectQueryFacetInput<TObjectType>[]): Promise<ObjectQueryFacetResult[]>
+  facets(input: readonly ObjectQueryFacetInput<TObjectType>[]): Promise<ObjectQueryFacetsResult>
 
   /** Execute this query with an outer limit of one and return the first object. */
   first(): Promise<Simplify<TRow> | null>

package/src/storage/ai-cost/analytics.ts

@@ -68,6 +68,7 @@ export interface AiAccountingAggregateFragment {
     readonly cacheWriteInputTokens: AiAccountingUsageMeterFragment
     readonly textOutputTokens: AiAccountingUsageMeterFragment
     readonly reasoningOutputTokens: AiAccountingUsageMeterFragment
+    readonly audioDurationMs: AiAccountingUsageMeterFragment
   }
   readonly costs: {
     readonly amount?: AiMoney
@@ -406,6 +407,7 @@ const AGGREGATE_USAGE_FIELDS = [
   "cacheWriteInputTokens",
   "textOutputTokens",
   "reasoningOutputTokens",
+  "audioDurationMs",
 ] as const
 
 type AggregateUsageField = (typeof AGGREGATE_USAGE_FIELDS)[number]

package/src/storage/ai-cost/codec.ts

@@ -110,7 +110,8 @@ function billableMeter(value: unknown): AiBillableMeter {
     value !== "tokens.input.cacheWrite1h" &&
     value !== "tokens.output.total" &&
     value !== "tokens.output.text" &&
-    value !== "tokens.output.reasoning"
+    value !== "tokens.output.reasoning" &&
+    value !== "audio.input.milliseconds"
   ) {
     throw invalidDetails()
   }

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

@@ -6,6 +6,7 @@ import type {
 
 /** Token meters supported by deterministic local rate cards. */
 export type AiBillableMeter =
+  | "audio.input.milliseconds"
   | "tokens.input.total"
   | "tokens.input.uncached"
   | "tokens.input.cacheRead"

package/src/storage/ai-cost/validation.ts

@@ -15,8 +15,8 @@ import type {
 } from "./types"
 
 const SIGNED_INT64_MAX = 9_223_372_036_854_775_807n
-const TOKENS_PER_MILLION = 1_000_000n
-const HALF_MILLION = TOKENS_PER_MILLION / 2n
+const UNITS_PER_MILLION = 1_000_000n
+const HALF_MILLION = UNITS_PER_MILLION / 2n
 const MAX_NUMERIC_TEXT_LENGTH = 128
 const METER_ORDER: Readonly<Record<AiBillableMeter, number>> = {
   "tokens.input.total": 0,
@@ -28,6 +28,7 @@ const METER_ORDER: Readonly<Record<AiBillableMeter, number>> = {
   "tokens.output.total": 6,
   "tokens.output.text": 7,
   "tokens.output.reasoning": 8,
+  "audio.input.milliseconds": 9,
 }
 const METERS = new Set(Object.keys(METER_ORDER) as AiBillableMeter[])
 const UNPRICEABLE_REASONS = new Set<AiUnpriceableReason>([
@@ -120,11 +121,7 @@ export function aiModelCallCostMatchesUsage(
     const components = new Map(
       record.estimate.components.map((component) => [component.meter, component])
     )
-    if (
-      !inputComponentsMatchUsage(components, usage) ||
-      !outputComponentsMatchUsage(components, usage)
-    )
-      return false
+    if (!componentsMatchUsage(components, usage)) return false
   }
   if (record.status === "unpriceable") return true
   if (record.components.length === 0 && isExternalValuationSource(record.priceSource.sourceId)) {
@@ -133,6 +130,22 @@ export function aiModelCallCostMatchesUsage(
 
   const usage = normalizeAiModelCallUsage(usageRecord.usage)
   const components = new Map(record.components.map((component) => [component.meter, component]))
+  return componentsMatchUsage(components, usage)
+}
+
+function componentsMatchUsage(
+  components: ReadonlyMap<AiBillableMeter, AiCostComponent>,
+  usage: AiModelCallUsage
+): boolean {
+  const audio = components.get("audio.input.milliseconds")
+  if (audio) {
+    return (
+      components.size === 1 &&
+      usage.audioDurationMs !== undefined &&
+      BigInt(audio.quantity) === BigInt(usage.audioDurationMs)
+    )
+  }
+
   return (
     inputComponentsMatchUsage(components, usage) && outputComponentsMatchUsage(components, usage)
   )
@@ -362,7 +375,7 @@ function calculateComponent(
 ): AiCostComponent {
   const normalizedQuantity = parseQuantity(quantity, `${meter} quantity`)
   const rate = parseNonnegativeInt64(rateAmountNanosPerMillion, `${meter} rate`)
-  const charge = (normalizedQuantity * rate + HALF_MILLION) / TOKENS_PER_MILLION
+  const charge = (normalizedQuantity * rate + HALF_MILLION) / UNITS_PER_MILLION
   assertSignedInt64(charge, `${meter} charge`)
   return {
     meter,

package/src/storage/ai-limits/in-memory.ts

@@ -8,6 +8,7 @@ import {
   AiLimitOperationLock,
   aiLimitAccountingEntryAppliesToSubject,
   aiLimitAmountKey,
+  aiLimitMeterApplies,
   aiLimitPolicyDimensionKey,
   aiLimitQuantityFromAmount,
   aiLimitReservationBuckets,
@@ -227,7 +228,12 @@ export class InMemoryAiLimitStorage implements AiLimitStorage {
       const unavailablePolicies: AiLimitPolicyStatus[] = []
       const unavailableReasons = new Set<"missingEstimate" | "incompleteAccounting">()
       for (const policy of enabledPolicies) {
-        if (!subjectKeys.has(aiLimitSubjectKey(policy.subject))) continue
+        if (
+          !subjectKeys.has(aiLimitSubjectKey(policy.subject)) ||
+          !aiLimitMeterApplies(policy.limit.meter, request.modelKind)
+        ) {
+          continue
+        }
         const limit = normalizeAiLimitAmount(policy.limit)
         const estimate = estimates.get(aiLimitAmountKey(limit))
         const status = await this.policyStatus(policy, request.period)
@@ -268,7 +274,8 @@ export class InMemoryAiLimitStorage implements AiLimitStorage {
       const buckets = aiLimitReservationBuckets(
         enabledPolicies,
         request.subjects,
-        request.estimates
+        request.estimates,
+        request.modelKind
       )
       if (buckets.length === 0) return { status: "notRequired" }
       for (const bucket of buckets) {
@@ -601,6 +608,7 @@ export class InMemoryAiLimitStorage implements AiLimitStorage {
       attempt: record.attempt,
       callId: record.callId,
       occurredAt: new Date(record.occurredAt),
+      ...(record.modelKind === undefined ? {} : { modelKind: record.modelKind }),
       ...(record.usage.totalTokens === undefined ? {} : { totalTokens: record.usage.totalTokens }),
       requesterGroupIds: [...record.requesterGroupIds],
       ...(requester?.type === "user" || requester?.type === "serviceAccount"

package/src/storage/ai-limits/provider.ts

@@ -1,7 +1,9 @@
+import type { ModelKind } from "../../models/definitions"
 import type { AiMoney } from "../ai-cost"
 import { AiLimitStorageError } from "./errors"
 import { aiLimitCalendarMonth } from "./period"
 import type {
+  AiLimitMeter,
   AiLimitPeriod,
   AiLimitPolicy,
   AiLimitQuantity,
@@ -16,6 +18,20 @@ import type {
 
 const SIGNED_INT64_MAX = 9_223_372_036_854_775_807n
 
+// These calls are billed per audio second or per search, and their providers report no tokens.
+// Token limits neither admit nor count them; cost limits still do.
+const TOKENLESS_MODEL_KINDS: ReadonlySet<ModelKind> = new Set(["transcription", "reranking"])
+
+/** @internal Whether a limit meter governs calls of this kind. Unclassified calls are metered. */
+export function aiLimitMeterApplies(
+  meter: AiLimitMeter,
+  modelKind: ModelKind | undefined
+): boolean {
+  return (
+    meter !== "tokens.total" || modelKind === undefined || !TOKENLESS_MODEL_KINDS.has(modelKind)
+  )
+}
+
 /** @internal Serialize compound limit operations, including within an existing transaction. */
 export class AiLimitOperationLock {
   private tail: Promise<void> = Promise.resolve()
@@ -55,6 +71,7 @@ export interface AiLimitAccountingEntry {
   readonly attempt: number
   readonly callId: string
   readonly occurredAt: Date
+  readonly modelKind?: ModelKind
   readonly totalTokens?: number
   readonly requesterGroupIds: readonly string[]
   readonly requester?:
@@ -228,6 +245,7 @@ export function normalizeReserveAiModelCall(input: ReserveAiModelCallInput): {
   readonly identity: AiModelCallReservationIdentity
   readonly subjects: readonly AiLimitSubject[]
   readonly estimates: readonly AiLimitQuantity[]
+  readonly modelKind?: ModelKind
   readonly period: AiLimitPeriod
   readonly reservedAt: Date
 } {
@@ -237,6 +255,7 @@ export function normalizeReserveAiModelCall(input: ReserveAiModelCallInput): {
     identity,
     subjects: normalizeAiLimitSubjects(input.subjects),
     estimates: normalizeAiLimitQuantities(input.estimates, "estimates"),
+    ...(input.modelKind === undefined ? {} : { modelKind: input.modelKind }),
     period: aiLimitCalendarMonth(reservedAt),
     reservedAt,
   }
@@ -297,13 +316,16 @@ export function aiLimitReservationRequestKey(
       const amount = normalizeAiLimitAmount(quantity)
       return [amount.meter, amount.currency, amount.amount.toString()]
     }),
+    // Appended only when present, so keys of reservations made before model kinds stay valid.
+    ...(request.modelKind === undefined ? [] : [request.modelKind]),
   ])
 }
 
 export function aiLimitReservationBuckets(
   policies: readonly AiLimitPolicy[],
   subjects: readonly AiLimitSubject[],
-  estimates: readonly AiLimitQuantity[]
+  estimates: readonly AiLimitQuantity[],
+  modelKind?: ModelKind
 ): readonly AiLimitReservationBucket[] {
   const subjectKeys = new Set(subjects.map(aiLimitSubjectKey))
   const estimatesByDimension = new Map(
@@ -313,7 +335,11 @@ export function aiLimitReservationBuckets(
     })
   )
   return policies
-    .filter((policy) => subjectKeys.has(aiLimitSubjectKey(policy.subject)))
+    .filter(
+      (policy) =>
+        subjectKeys.has(aiLimitSubjectKey(policy.subject)) &&
+        aiLimitMeterApplies(policy.limit.meter, modelKind)
+    )
     .flatMap((policy) => {
       const estimate = estimatesByDimension.get(
         aiLimitAmountKey(normalizeAiLimitAmount(policy.limit))
@@ -357,6 +383,7 @@ export function resolveAiLimitActual(
   let accountingStatus: ResolvedAiLimitActual["accountingStatus"] = "complete"
   for (const entry of entries) {
     if (dimension.meter === "tokens.total") {
+      if (!aiLimitMeterApplies(dimension.meter, entry.modelKind)) continue
       if (entry.totalTokens === undefined) {
         accountingStatus = "unavailable"
       } else {

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

@@ -1,3 +1,4 @@
+import type { ModelKind } from "../../models/definitions"
 import type { AiMoney } from "../ai-cost"
 
 /** A project-wide, group, or durable requester identity charged for AI model calls. */
@@ -129,6 +130,8 @@ export interface ReserveAiModelCallInput extends AiModelCallReservationIdentity
   /** The project subject is always added, even when omitted here. */
   readonly subjects: readonly AiLimitSubject[]
   readonly estimates: readonly AiLimitQuantity[]
+  /** Transcription and reranking calls are outside token limits; see `aiLimitMeterApplies`. */
+  readonly modelKind?: ModelKind
   readonly reservedAt?: Date
 }
 

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

@@ -19,6 +19,14 @@ export function normalizeAiModelCallRecord(input: RecordAiModelCallInput): AiMod
   }
   assertNonBlank(input.responseId, "responseId")
 
+  if (
+    input.modelKind !== undefined &&
+    !["language", "image", "video", "embedding", "decision", "transcription", "reranking"].includes(
+      input.modelKind
+    )
+  ) {
+    throw new TypeError("[Sixb] AI model kind is invalid.")
+  }
   const occurredAt = cloneValidDate(input.occurredAt, "occurredAt")
   const recordedAt = cloneValidDate(input.recordedAt ?? new Date(), "recordedAt")
   const requesterGroupIds = normalizeRequesterGroupIds(input.requesterGroupIds)
@@ -37,6 +45,7 @@ export function normalizeAiModelCallRecord(input: RecordAiModelCallInput): AiMod
       ? {}
       : { providerIds: normalizeModelProviderIds(input.providerIds) }),
     requestedModelId: input.requestedModelId,
+    ...(input.modelKind === undefined ? {} : { modelKind: input.modelKind }),
     ...(requestedReasoning === undefined ? {} : { requestedReasoning }),
     ...(input.responseModelId === undefined ? {} : { responseModelId: input.responseModelId }),
     responseId: input.responseId,

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

@@ -1,11 +1,13 @@
 import type { ReadonlyJsonObject } from "../../json"
 import type { ModelReasoning } from "../../models/language-model"
 
-/** How much normalized token usage a provider reported for one model call. */
+/** Coverage of normalized usage. Complete means both token totals are known; duration alone is partial. */
 export type AiUsageReportingStatus = "complete" | "partial" | "unavailable"
 
-/** Provider-neutral token counts accepted at the model-call boundary. */
+/** Provider-neutral usage accepted at the model-call boundary. */
 export interface AiModelCallUsageInput {
+  /** Audio content duration in milliseconds, rounded to the nearest millisecond. Not billed duration. */
+  readonly audioDurationMs?: number
   readonly inputTokens?: number
   readonly outputTokens?: number
   readonly uncachedInputTokens?: number
@@ -15,7 +17,7 @@ export interface AiModelCallUsageInput {
   readonly reasoningOutputTokens?: number
 }
 
-/** Normalized token counts for one completed model call. Details overlap their input/output totals. */
+/** Normalized usage for one completed model call. Token details overlap their input/output totals. */
 export interface AiModelCallUsage extends AiModelCallUsageInput {
   /** Present only when both input and output totals are known. */
   readonly totalTokens?: number
@@ -32,6 +34,8 @@ export interface AiUsageExecutionSummary {
 
 /** Input for an idempotent model-call ledger append. */
 export interface RecordAiModelCallInput {
+  /** Absent for historical calls whose kind was not captured. */
+  readonly modelKind?: import("../../models/definitions").ModelKind
   readonly providerIds?: import("../../models/events").ModelProviderIds
   readonly id: string
   readonly projectId: string
@@ -89,7 +93,7 @@ export interface GetLatestAiModelCallForExecutionInput {
   readonly executionId: string
 }
 
-/** Durable, provider-neutral accounting for completed language-model calls. */
+/** Durable, provider-neutral accounting for completed model calls. */
 export interface AiUsageStorage {
   /**
    * Append one model-call record idempotently. The identity is project, execution ID, attempt, call

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

@@ -8,6 +8,7 @@ const USAGE_FIELDS = [
   "cacheWriteInputTokens",
   "textOutputTokens",
   "reasoningOutputTokens",
+  "audioDurationMs",
 ] as const
 
 type AiUsageField = (typeof USAGE_FIELDS)[number]
@@ -30,6 +31,7 @@ export function normalizeAiModelCallUsage(input: AiModelCallUsageInput): AiModel
         : "unavailable"
 
   return {
+    ...(input.audioDurationMs === undefined ? {} : { audioDurationMs: input.audioDurationMs }),
     ...(input.inputTokens === undefined ? {} : { inputTokens: input.inputTokens }),
     ...(input.outputTokens === undefined ? {} : { outputTokens: input.outputTokens }),
     ...(totalTokens === undefined ? {} : { totalTokens }),

package/src/storage/file-download-grants/in-memory.ts

@@ -0,0 +1,73 @@
+import { cloneFileDownloadGrantRecord } from "./record"
+import type {
+  DeleteExpiredFileDownloadGrantsInput,
+  FileDownloadGrantRecord,
+  FileDownloadGrantStorage,
+  FindFileDownloadGrantInput,
+  RevokeFileDownloadGrantInput,
+} from "./types"
+
+export class InMemoryFileDownloadGrantStorage implements FileDownloadGrantStorage {
+  private rows = new Map<string, FileDownloadGrantRecord>()
+
+  async create(record: FileDownloadGrantRecord): Promise<void> {
+    const duplicate = [...this.rows.values()].some(
+      (current) =>
+        current.projectId === record.projectId &&
+        (current.id === record.id || current.tokenHash === record.tokenHash)
+    )
+    if (duplicate) {
+      throw new Error(`[Sixb] File download grant '${record.id}' conflicts with an existing one.`)
+    }
+    this.rows.set(rowKey(record.projectId, record.id), cloneFileDownloadGrantRecord(record))
+  }
+
+  async findByTokenHash(
+    input: FindFileDownloadGrantInput
+  ): Promise<FileDownloadGrantRecord | null> {
+    for (const record of this.rows.values()) {
+      if (record.projectId === input.projectId && record.tokenHash === input.tokenHash) {
+        return cloneFileDownloadGrantRecord(record)
+      }
+    }
+    return null
+  }
+
+  async revoke(input: RevokeFileDownloadGrantInput): Promise<FileDownloadGrantRecord | null> {
+    const key = rowKey(input.projectId, input.id)
+    const current = this.rows.get(key)
+    if (!current) return null
+    if (!current.revokedAt) {
+      this.rows.set(key, { ...current, revokedAt: new Date(input.revokedAt) })
+    }
+    return cloneFileDownloadGrantRecord(this.rows.get(key) as FileDownloadGrantRecord)
+  }
+
+  async deleteExpired(input: DeleteExpiredFileDownloadGrantsInput): Promise<number> {
+    const expired = [...this.rows.entries()]
+      .filter(
+        ([, record]) =>
+          record.projectId === input.projectId &&
+          record.expiresAt.getTime() < input.expiredBefore.getTime()
+      )
+      .slice(0, input.limit)
+    for (const [key] of expired) this.rows.delete(key)
+    return expired.length
+  }
+
+  snapshot(): ReadonlyMap<string, FileDownloadGrantRecord> {
+    return new Map(
+      [...this.rows].map(([key, record]) => [key, cloneFileDownloadGrantRecord(record)])
+    )
+  }
+
+  restore(snapshot: ReadonlyMap<string, FileDownloadGrantRecord>): void {
+    this.rows = new Map(
+      [...snapshot].map(([key, record]) => [key, cloneFileDownloadGrantRecord(record)])
+    )
+  }
+}
+
+function rowKey(projectId: string, id: string): string {
+  return `${projectId}\0${id}`
+}

package/src/storage/file-download-grants/index.ts

@@ -0,0 +1,8 @@
+export { InMemoryFileDownloadGrantStorage } from "./in-memory"
+export type {
+  DeleteExpiredFileDownloadGrantsInput,
+  FileDownloadGrantRecord,
+  FileDownloadGrantStorage,
+  FindFileDownloadGrantInput,
+  RevokeFileDownloadGrantInput,
+} from "./types"

package/src/storage/file-download-grants/record.ts

@@ -0,0 +1,47 @@
+import { isFileRef } from "../../blob-storage"
+import type { FileDownloadGrantRecord } from "./types"
+
+/**
+ * Rebuilds a grant from a provider row with camelCase keys. `file` may arrive parsed (jsonb) or
+ * as text (SQLite), and timestamps as `Date` or ISO text. Fails closed on corruption: a grant that
+ * cannot be read must not serve a file.
+ */
+export function parseFileDownloadGrantRow(row: {
+  readonly [column: string]: unknown
+}): FileDownloadGrantRecord {
+  const id = text(row.id, "id", String(row.id))
+  const file = typeof row.file === "string" ? JSON.parse(row.file) : row.file
+  if (!isFileRef(file)) throw corrupt(id, "file is not a file reference")
+
+  return {
+    id,
+    projectId: text(row.projectId, "projectId", id),
+    tokenHash: text(row.tokenHash, "tokenHash", id),
+    file,
+    executionId: text(row.executionId, "executionId", id),
+    createdAt: date(row.createdAt, "createdAt", id),
+    expiresAt: date(row.expiresAt, "expiresAt", id),
+    ...(row.revokedAt == null ? {} : { revokedAt: date(row.revokedAt, "revokedAt", id) }),
+  }
+}
+
+export function cloneFileDownloadGrantRecord(
+  record: FileDownloadGrantRecord
+): FileDownloadGrantRecord {
+  return structuredClone(record)
+}
+
+function text(value: unknown, column: string, id: string): string {
+  if (typeof value !== "string" || value.length === 0) throw corrupt(id, `${column} is not text`)
+  return value
+}
+
+function date(value: unknown, column: string, id: string): Date {
+  const parsed = value instanceof Date || typeof value === "string" ? new Date(value) : null
+  if (!parsed || !Number.isFinite(parsed.getTime())) throw corrupt(id, `${column} is not a date`)
+  return parsed
+}
+
+function corrupt(id: string, reason: string): Error {
+  return new Error(`[Sixb] Stored file download grant '${id}' is invalid: ${reason}.`)
+}

package/src/storage/file-download-grants/types.ts

@@ -0,0 +1,48 @@
+import type { FileRef } from "../../blob-storage"
+
+/**
+ * One download URL issued by `blobs.createDownloadUrl()`. Each call issues its own grant, so URLs
+ * for the same file expire and are revoked independently.
+ */
+export interface FileDownloadGrantRecord {
+  readonly id: string
+  readonly projectId: string
+  /** SHA-256 hex of the URL token. The token itself is never stored. */
+  readonly tokenHash: string
+  /** The file the URL serves, without `logicalPath`: serving the bytes does not need it. */
+  readonly file: FileRef
+  /** The execution that issued the URL, so an exposure can be traced back to its cause. */
+  readonly executionId: string
+  readonly createdAt: Date
+  readonly expiresAt: Date
+  readonly revokedAt?: Date
+}
+
+export interface FindFileDownloadGrantInput {
+  readonly projectId: string
+  readonly tokenHash: string
+}
+
+export interface RevokeFileDownloadGrantInput {
+  readonly projectId: string
+  readonly id: string
+  readonly revokedAt: Date
+}
+
+export interface DeleteExpiredFileDownloadGrantsInput {
+  readonly projectId: string
+  readonly expiredBefore: Date
+  readonly limit: number
+}
+
+/** Persistence only: token generation, expiry, and revocation checks live in Core. */
+export interface FileDownloadGrantStorage {
+  /** `(projectId, id)` and `(projectId, tokenHash)` are each unique. */
+  create(record: FileDownloadGrantRecord): Promise<void>
+  /** Returns expired and revoked grants too; the caller decides whether one still serves. */
+  findByTokenHash(input: FindFileDownloadGrantInput): Promise<FileDownloadGrantRecord | null>
+  /** Keeps the first revocation. Returns the grant, or `null` when it does not exist. */
+  revoke(input: RevokeFileDownloadGrantInput): Promise<FileDownloadGrantRecord | null>
+  /** Deletes up to `limit` grants that expired before `expiredBefore`, and returns the count. */
+  deleteExpired(input: DeleteExpiredFileDownloadGrantsInput): Promise<number>
+}