@sixb/core 0.1.16 → 0.1.18

package/src/execution/authorized-object-reader.ts

@@ -2,12 +2,18 @@ import { assertNever } from "../assert-never"
 import { assertAuthorized, isAllowed } from "../authorization"
 import { AuthorizationError } from "../authorization/errors"
 import type { AuthorizationContext } from "../authorization/types"
-import type { EmbeddingModelCatalog } from "../models/catalog"
+import type { EmbeddingModelCatalog, RerankingModelCatalog } from "../models/catalog"
 import {
   type AuthorizedOntologySelection,
   type AuthorizedOntologyView,
   createAuthorizedOntologyView,
 } from "../objects/authorized-ontology-view"
+import {
+  createClearanceQueryAdmission,
+  type PropertyClearance,
+  redactObjectRow,
+  resolvePropertyClearance,
+} from "../objects/property-clearance"
 import {
   countObjects,
   type ExecuteObjectCountInput,
@@ -35,6 +41,8 @@ import {
 } from "../objects/query/selected-read-admission"
 import {
   type AdmittedObjectQuery,
+  composeObjectQueryAdmissions,
+  type ObjectQuerySemanticAdmission,
   validateObjectQuery,
   validateObjectQueryWithAdmission,
 } from "../objects/query/validate"
@@ -50,6 +58,7 @@ import type {
   ObjectFacetRequest,
   ObjectLinkRow,
   ObjectReadStorage,
+  ObjectRow,
   ObjectStorage,
 } from "../storage"
 import { assertObjectReadOutputWithinLimit, MAX_OBJECT_READ_FACETS } from "../storage"
@@ -87,11 +96,14 @@ class AuthorizedObjectReaderImpl {
   readonly #runtime: RuntimeReadAuthorization
   readonly #ontology: OntologyRegistry
   readonly #embeddingModels?: EmbeddingModelCatalog
+  readonly #rerankingModels?: RerankingModelCatalog
   #ontologyView?: AuthorizedOntologyView
   readonly #storage: ObjectReadStorage
   readonly #delegatedObjectTypeIds?: ReadonlySet<string>
   readonly #delegatedLinkDefinitions?: ReadonlySet<string>
   readonly #delegatedQueryAdmission?: SelectedObjectQueryAdmission
+  /** Marked properties this authority cannot read; absent when it reads every property. */
+  readonly #clearance?: PropertyClearance
 
   constructor(
     key: typeof readerConstructionKey,
@@ -99,6 +111,7 @@ class AuthorizedObjectReaderImpl {
       readonly scope: ExecutionScope
       readonly ontology: OntologyRegistry
       readonly embeddingModels?: EmbeddingModelCatalog
+      readonly rerankingModels?: RerankingModelCatalog
       readonly storage: ObjectReadStorage
       readonly authority: ResolvedExecutionAuthority
     }
@@ -111,6 +124,7 @@ class AuthorizedObjectReaderImpl {
     this.#authority = input.authority
     this.#ontology = input.ontology
     this.#embeddingModels = input.embeddingModels
+    this.#rerankingModels = input.rerankingModels
     this.#storage = input.storage
     this.#delegatedObjectTypeIds =
       input.authority.type === "delegated"
@@ -124,6 +138,7 @@ class AuthorizedObjectReaderImpl {
       input.authority.type === "delegated"
         ? createSelectedObjectQueryAdmission(input.authority.objectRead.scope)
         : undefined
+    this.#clearance = clearanceForAuthority(input.authority, input.ontology)
     this.#runtime = Object.freeze({
       projectId: input.scope.execution.projectId,
       runtimeAuthorization: input.scope.authorization,
@@ -167,12 +182,11 @@ class AuthorizedObjectReaderImpl {
       primaryId: input.primaryId,
     })
     this.#assertObjectTypesViewable([request.objectTypeId])
-    return detachReadResult(
-      await this.#storage.getByPrimaryId({
-        ...request,
-        projectId: this.#runtime.projectId,
-      })
-    )
+    const row = await this.#storage.getByPrimaryId({
+      ...request,
+      projectId: this.#runtime.projectId,
+    })
+    return detachReadResult(row && this.#redact(row))
   }
 
   async getByPrimaryIdBatch(
@@ -185,11 +199,12 @@ class AuthorizedObjectReaderImpl {
       })),
     })
     this.#assertObjectTypesViewable(request.items.map((item) => item.objectTypeId))
+    const rows = await this.#storage.getByPrimaryIdBatch({
+      ...request,
+      projectId: this.#runtime.projectId,
+    })
     return detachReadResult(
-      await this.#storage.getByPrimaryIdBatch({
-        ...request,
-        projectId: this.#runtime.projectId,
-      })
+      new Map([...rows].map(([key, row]) => [key, this.#redact(row)] as const))
     )
   }
 
@@ -200,6 +215,7 @@ class AuthorizedObjectReaderImpl {
       propertyId: input.propertyId,
     })
     this.#assertObjectTypesViewable([request.objectTypeId])
+    if (this.#hidesProperty(request)) return false
     if (this.#authority.type !== "delegated") return true
     const [readable] = await this.#storage.selectsObjectProperties({
       projectId: this.#runtime.projectId,
@@ -219,12 +235,15 @@ class AuthorizedObjectReaderImpl {
       })),
     })
     this.#assertObjectTypesViewable(request.items.map((item) => item.objectTypeId))
-    if (this.#authority.type !== "delegated") return request.items.map(() => true)
-    return detachReadResult(
-      await this.#storage.selectsObjectProperties({
-        ...request,
-        projectId: this.#runtime.projectId,
-      })
+    const selected =
+      this.#authority.type === "delegated"
+        ? await this.#storage.selectsObjectProperties({
+            ...request,
+            projectId: this.#runtime.projectId,
+          })
+        : request.items.map(() => true)
+    return request.items.map(
+      (item, index) => !this.#hidesProperty(item) && selected[index] === true
     )
   }
 
@@ -255,13 +274,12 @@ class AuthorizedObjectReaderImpl {
       return { objects: [], hasMore: false, total: 0 }
     }
 
-    return detachReadResult(
-      await this.#storage.list({
-        ...request,
-        ...(objectTypeId === undefined ? {} : { objectTypeId }),
-        projectId: this.#runtime.projectId,
-      })
-    )
+    const page = await this.#storage.list({
+      ...request,
+      ...(objectTypeId === undefined ? {} : { objectTypeId }),
+      projectId: this.#runtime.projectId,
+    })
+    return detachReadResult({ ...page, objects: page.objects.map((row) => this.#redact(row)) })
   }
 
   async listLinks(input: ListLinksInput): ReturnType<ObjectReadStorage["listLinks"]> {
@@ -315,17 +333,16 @@ class AuthorizedObjectReaderImpl {
     const query = snapshotAuthoredQuery(input.query)
     const includeTotal = snapshotReadValue(input.includeTotal)
     const executionQuery = this.#admitDelegatedQuery(query)?.query ?? query
-    return detachReadResult(
-      await executeObjectQuery(
-        {
-          query: executionQuery,
-          ...(includeTotal === undefined ? {} : { includeTotal }),
-          projectId: this.#runtime.projectId,
-          signal: input.signal,
-        },
-        this.#queryExecutorOptions()
-      )
+    const result = await executeObjectQuery(
+      {
+        query: executionQuery,
+        ...(includeTotal === undefined ? {} : { includeTotal }),
+        projectId: this.#runtime.projectId,
+        signal: input.signal,
+      },
+      this.#queryExecutorOptions()
     )
+    return detachReadResult({ ...result, objects: result.objects.map((row) => this.#redact(row)) })
   }
 
   async queryLinks(
@@ -375,7 +392,7 @@ class AuthorizedObjectReaderImpl {
     ) {
       throw new Error("[Sixb] Object storage returned a link page outside its authorized scope.")
     }
-    return result
+    return { ...result, objects: result.objects.map((row) => this.#redact(row)) }
   }
 
   async count(
@@ -447,6 +464,14 @@ class AuthorizedObjectReaderImpl {
     )
   }
 
+  /**
+   * Redact a row returned by a write. An upsert returns the merged effective row, which may hold
+   * marked values the writer never sent and cannot read.
+   */
+  redactWrittenRow<TRow extends ObjectRow>(row: TRow): TRow {
+    return this.#redact(row)
+  }
+
   /** Enforce the delegated response budget without exposing or recombining its limits. */
   assertVisibleOutputWithinLimit(value: unknown): void {
     if (this.#authority.type !== "delegated") return
@@ -461,6 +486,7 @@ class AuthorizedObjectReaderImpl {
   }
 
   #queryExecutorOptions() {
+    const admission = this.#executorAdmission()
     if (this.#authority.type === "delegated") {
       // The selected storage instance is the private execution capability. Passing the delegated
       // runtime token into the generic executor would either reject this admitted query or tempt a
@@ -469,19 +495,42 @@ class AuthorizedObjectReaderImpl {
         ontology: this.#ontology,
         storage: this.#storage,
         embeddingModels: this.#embeddingModels,
+        rerankingModels: this.#rerankingModels,
+        ...(admission === undefined ? {} : { admission }),
       }
     }
     return {
       ontology: this.#ontology,
       embeddingModels: this.#embeddingModels,
+      rerankingModels: this.#rerankingModels,
       storage: this.#storage,
       runtimeAuthorization: this.#runtime.runtimeAuthorization,
       ...(this.#runtime.authorization === undefined
         ? {}
         : { authorization: this.#runtime.authorization }),
+      ...(admission === undefined ? {} : { admission }),
     }
   }
 
+  /**
+   * The executor validates the query it runs, and that validation resolves default text fields.
+   * Every admission that narrows those fields must therefore apply there, not only beforehand.
+   */
+  #executorAdmission(): ObjectQuerySemanticAdmission | undefined {
+    const clearance = this.#clearance && createClearanceQueryAdmission(this.#clearance)
+    const selected = this.#delegatedQueryAdmission
+    if (selected && clearance) return composeObjectQueryAdmissions(selected, clearance)
+    return selected ?? clearance
+  }
+
+  #redact<TRow extends ObjectRow>(row: TRow): TRow {
+    return this.#clearance ? redactObjectRow(row, this.#clearance) : row
+  }
+
+  #hidesProperty(item: { readonly objectTypeId: string; readonly propertyId: string }): boolean {
+    return this.#clearance?.hiddenPropertyIds(item.objectTypeId).has(item.propertyId) ?? false
+  }
+
   #admitDelegatedQuery(query: ObjectQuery): AdmittedObjectQuery | undefined {
     if (!this.#delegatedQueryAdmission) return undefined
     return validateObjectQueryWithAdmission(
@@ -558,6 +607,7 @@ export function createAuthorizedObjectReader(input: {
   readonly scope: ExecutionScope
   readonly ontology: OntologyRegistry
   readonly embeddingModels?: EmbeddingModelCatalog
+  readonly rerankingModels?: RerankingModelCatalog
   readonly objectStorage: ObjectStorage
 }): AuthorizedObjectReader {
   const scope = captureExecutionScope(input.scope)
@@ -568,6 +618,7 @@ export function createAuthorizedObjectReader(input: {
     scope,
     ontology: input.ontology,
     embeddingModels: input.embeddingModels,
+    rerankingModels: input.rerankingModels,
     storage,
     authority,
   })
@@ -588,6 +639,24 @@ export function getAuthorizedOntologyView(reader: AuthorizedObjectReader): Autho
   return AuthorizedObjectReaderImpl.ontologyView(reader)
 }
 
+/**
+ * Unrestricted authority reads every property. A principal reads what its roles clear; delegated
+ * shared access carries no clearance, so no share can expose a marked property.
+ */
+function clearanceForAuthority(
+  authority: ResolvedExecutionAuthority,
+  ontology: OntologyRegistry
+): PropertyClearance | undefined {
+  switch (authority.type) {
+    case "unrestricted":
+      return undefined
+    case "principal":
+      return resolvePropertyClearance(ontology, authority.context.clearances ?? new Set())
+    case "delegated":
+      return resolvePropertyClearance(ontology, new Set())
+  }
+}
+
 function objectStorageForAuthority(
   authority: ResolvedExecutionAuthority,
   objectStorage: ObjectStorage

package/src/execution/scopes.ts

@@ -146,12 +146,8 @@ export function createTestingScope(input: {
 }
 
 function withoutSession(context: AuthorizationContext): AuthorizationContext {
-  return {
-    principal: context.principal,
-    groupIds: context.groupIds,
-    roleIds: context.roleIds,
-    grants: context.grants,
-  }
+  const { sessionId: _sessionId, ...withoutSessionId } = context
+  return withoutSessionId
 }
 
 function createRequestExecution(input: {

package/src/http/api-routes.ts

@@ -34,7 +34,8 @@ export const SIXB_API_ROUTES: readonly SixbApiRoute[] = [
   // Token and service-account management is bearer-capable so the CLI can authenticate with a
   // personal access token. It is NOT exposed to agents. The runtime still confines every operation
   // to the caller's own groups, and service-account tokens are rejected (only user principals may
-  // manage credentials).
+  // manage credentials). Creating a token is the exception: it takes a signed-in session, so no
+  // access token can mint one broader or longer-lived than itself.
   {
     operationId: "getAuthAccessManagementOptions",
     method: "GET",
@@ -53,7 +54,7 @@ export const SIXB_API_ROUTES: readonly SixbApiRoute[] = [
     operationId: "createAuthPersonalAccessToken",
     method: "POST",
     path: "/api/auth/access-tokens",
-    accessToken: true,
+    accessToken: false,
     agentApi: false,
   },
   {
@@ -95,7 +96,7 @@ export const SIXB_API_ROUTES: readonly SixbApiRoute[] = [
     operationId: "createAuthServiceAccountAccessToken",
     method: "POST",
     path: "/api/auth/service-accounts/:serviceAccountId/access-tokens",
-    accessToken: true,
+    accessToken: false,
     agentApi: false,
   },
   {

package/src/index.ts

@@ -21,10 +21,12 @@ export type {
   ObjectLinkTargetMetadata,
   ObjectLinkTargetType,
   ObjectPropertiesMetadata,
+  ObjectQueryIndexDefinition,
   ObjectRef,
   ObjectRefSchema,
   ObjectSchema,
   ObjectType,
+  ObjectTypeQueryMetadata,
   ObjectTypeSearchMetadata,
   ObjectTypeWithPropertyTokens,
   ObjectTypeWithTokens,
@@ -62,6 +64,7 @@ export {
   userRef,
   valueTypeRef,
 } from "./ontology"
+export type { OntologyDoc, OntologyDocsCatalog, OntologyDocsInput } from "./ontology/docs"
 
 // ── Actions ─────────────────────────────────────────────────
 
@@ -218,6 +221,7 @@ export {
 
 export type {
   InferObjectProperties,
+  InferObjectReadProperties,
   InferPropertySemanticType,
   InferPropertyUnit,
   InferPropertyValue,
@@ -462,6 +466,7 @@ export type {
   BreadthSelector,
   BreadthTarget,
   DefineGroupOptions,
+  DefineMarkingOptions,
   DefineMembershipPolicyOptions,
   DefineRoleOptions,
   EditGrant,
@@ -471,10 +476,13 @@ export type {
   GroupReference,
   ManageGrant,
   ManageGrantTarget,
+  MarkingDefinition,
   MembershipOperation,
   MembershipPolicyDefinition,
   ObserveGrant,
   ObserveGrantTarget,
+  RedactionReason,
+  Redactions,
   RegisteredSecurityDefinitions,
   RoleDefinition,
   RunGrant,
@@ -489,6 +497,7 @@ export {
   applications,
   can,
   defineGroup,
+  defineMarking,
   defineMembershipPolicy,
   defineRole,
   every,
@@ -536,6 +545,7 @@ export type {
   MigrationState,
   MigrationStatus,
   Storage,
+  StorageMigrationOptions,
   StorageMigrationResult,
   StorageMigrator,
   StorageSchemaCheck,
@@ -560,6 +570,7 @@ export type {
   BlobInfo,
   BlobStorage,
   FileRef,
+  OpenedFileRef,
 } from "./blob-storage"
 export {
   DEFAULT_SIMPLE_FILE_UPLOAD_BYTES,
@@ -576,6 +587,7 @@ export {
 export type {
   DatasetProducer,
   DatasetRow,
+  DatasetVersion,
   LakeStorage,
   LakeStorageWithSql,
 } from "./lake-storage"
@@ -886,9 +898,16 @@ export type {
   AgentThreadsRuntime,
   ExecutionAgentRunResult,
 } from "./agents/execution"
+export type { CreateFileDownloadUrlOptions, FileDownloadUrl } from "./blob-storage/download-urls"
 export type { BlobsRuntime } from "./blob-storage/execution"
 export type { ConnectorRuntime } from "./connectors/execution"
-export type { DatasetIngestInput, DatasetIngestResult, DatasetsRuntime } from "./datasets/execution"
+export type {
+  DatasetIngestInput,
+  DatasetIngestResult,
+  DatasetReadRowsInput,
+  DatasetRows,
+  DatasetsRuntime,
+} from "./datasets/execution"
 export type {
   SixbActionPhaseFailedContext,
   SixbErrorContext,
@@ -939,16 +958,20 @@ export type {
   BatchItemResult,
   CreateSixbOptions,
   DefinitionCatalog,
+  FileListPropertyToken,
+  FilePropertyToken,
   ListResult,
   ListResultWithoutTotal,
   ObjectByIdHandle,
   ObjectExpandBuilder,
   ObjectExpandOptions,
   ObjectExpansionSort,
+  ObjectFileHandle,
   ObjectQueryBuilder,
   ObjectQueryFacetBucket,
   ObjectQueryFacetInput,
   ObjectQueryFacetResult,
+  ObjectQueryFacetsResult,
   ObjectQueryListOptions,
   ObjectQueryRow,
   ObjectReadByIdHandle,
@@ -1020,6 +1043,9 @@ export type {
   AgentContextInput,
   AgentContextOrigin,
   AgentContextPart,
+  AgentContinuationPart,
+  AgentDefinitions,
+  AgentDefinitionsInput,
   AgentDescriptor,
   AgentFileDataProjection,
   AgentFileDataResolverInput,
@@ -1028,17 +1054,20 @@ export type {
   AgentMessagePart,
   AgentMessagePartType,
   AgentMessageRole,
+  AgentProjectFile,
   AgentProviderStatePart,
   AgentReasoning,
-  AgentReasoningLevel,
   AgentReasoningPart,
   AgentReference,
   AgentRequestErrorCode,
+  AgentSkillCatalog,
+  AgentSkillDefinition,
   AgentStepStartPart,
   AgentTextPart,
   AgentToolArtifact,
   AgentToolArtifactPutInput,
   AgentToolArtifacts,
+  AgentToolAttachments,
   AgentToolCallPart,
   AgentToolCallState,
   AgentToolCatalog,
@@ -1055,6 +1084,7 @@ export type {
   AgentToolRunBuilder,
   AgentToolRunContext,
   AgentToolRunInfo,
+  AgentToolRuntimeFacade,
   AgentToolTextContent,
   AgentUsageReference,
   InferAgentToolInput,
@@ -1120,6 +1150,15 @@ export type {
   ModelReportedCost,
   ModelRoute,
   ModelUsage,
+  RerankingModel,
+  RerankingModelCatalog,
+  RerankingModelDefinition,
+  RerankingModelEntry,
+  RerankingModelRef,
+  RerankingModelRequest,
+  RerankingModelResponseMetadata,
+  RerankingModelResult,
+  RerankingResult,
 } from "./models"
 export type {
   InferLanguageModelOutput,
@@ -1142,6 +1181,12 @@ export type {
   ActionParamDescriptor,
   ActionPhaseDescriptor,
 } from "./actions/descriptor"
+export type {
+  AudioModelsRuntime,
+  AudioTranscribeInput,
+  AudioTranscribeResult,
+  TranscriptionOutput,
+} from "./models/audio/types"
 export type { DecisionAnswerSchema, DecisionOutputShape } from "./models/decision/output"
 export { decisionOutput } from "./models/decision/output"
 export { question } from "./models/decision/questions"
@@ -1183,3 +1228,8 @@ export {
   isProjectionDefinition,
   isTelemetryProjectionDefinition,
 } from "./projections"
+export type {
+  ObjectQueryPreparationPlan,
+  ObjectQueryPreparationResult,
+} from "./storage/objects/query-preparation"
+export { prepareObjectQueries } from "./storage/objects/query-preparation"

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

@@ -29,6 +29,7 @@ import type {
   CommitDatasetWriteInput,
   DatasetCatalogState,
   DatasetChanges,
+  DatasetLatestVersionSummary,
   DatasetRow,
   DatasetRowChange,
   DatasetVersion,
@@ -36,6 +37,8 @@ import type {
   DatasetWriteMode,
   LakeStorage,
   LakeWriteSession,
+  LatestVersionsSince,
+  ListLatestVersionsSinceInput,
   ReadDatasetChangesInput,
   ReadDatasetRowsInput,
 } from "./types"
@@ -52,6 +55,16 @@ function cloneDatasetVersion(version: DatasetVersion): DatasetVersion {
   }
 }
 
+function latestVersionSummary(version: DatasetVersion): DatasetLatestVersionSummary {
+  return {
+    datasetId: version.datasetId,
+    versionId: version.versionId,
+    mode: version.mode,
+    createdAt: version.createdAt,
+    ...(version.rowCount !== undefined ? { rowCount: version.rowCount } : {}),
+  }
+}
+
 function cloneRow(row: DatasetRow): DatasetRow {
   return structuredClone(row)
 }
@@ -223,6 +236,9 @@ export class InMemoryLakeStorage implements LakeStorage {
   private readonly sequencesByVersionId = new Map<string, Map<string, DatasetSequenceState>>()
   private readonly latestVersionIdByDataset = new Map<string, string>()
   private readonly commitLocks = new Map<string, Promise<void>>()
+  /** Commit counter for listLatestVersionsSince; each dataset keeps the position of its latest. */
+  private commitPosition = 0
+  private readonly commitPositionByDataset = new Map<string, number>()
 
   async createDataset(definition: DatasetDefinition): Promise<DatasetDefinition> {
     assertDatasetId(definition.id)
@@ -287,15 +303,7 @@ export class InMemoryLakeStorage implements LakeStorage {
         return {
           datasetId,
           materialized: true,
-          latestVersion: latest
-            ? {
-                datasetId: latest.datasetId,
-                versionId: latest.versionId,
-                mode: latest.mode,
-                createdAt: latest.createdAt,
-                ...(latest.rowCount !== undefined ? { rowCount: latest.rowCount } : {}),
-              }
-            : null,
+          latestVersion: latest ? latestVersionSummary(latest) : null,
         }
       })
     )
@@ -362,6 +370,25 @@ export class InMemoryLakeStorage implements LakeStorage {
     return this.getVersion(datasetId, latestVersionId)
   }
 
+  async listLatestVersionsSince(
+    input: ListLatestVersionsSinceInput
+  ): Promise<LatestVersionsSince | null> {
+    const cursor = String(this.commitPosition)
+    if (input.cursor === null) return { cursor, versions: [] }
+    if (!/^\d+$/.test(input.cursor) || Number(input.cursor) > this.commitPosition) return null
+
+    const after = Number(input.cursor)
+    const datasetIds = input.datasetIds ? new Set(input.datasetIds) : null
+    const versions: DatasetLatestVersionSummary[] = []
+    for (const [datasetId, position] of this.commitPositionByDataset) {
+      if (position <= after || (datasetIds && !datasetIds.has(datasetId))) continue
+      // This provider never commits schema-only versions, so the latest version carries data.
+      const latest = await this.getLatestVersion(datasetId)
+      if (latest) versions.push(latestVersionSummary(latest))
+    }
+    return { cursor, versions }
+  }
+
   async getVersion(datasetId: string, versionId: string): Promise<DatasetVersion | null> {
     const versions = this.versionsByDataset.get(datasetId) ?? []
     const version = versions.find((candidate) => candidate.versionId === versionId)
@@ -564,6 +591,7 @@ export class InMemoryLakeStorage implements LakeStorage {
         visibleRows.map((row) => cloneRow(row))
       )
       this.latestVersionIdByDataset.set(options.merge.dataset.id, versionId)
+      this.commitPositionByDataset.set(options.merge.dataset.id, ++this.commitPosition)
       if (ordered) this.sequencesByVersionId.set(versionId, ordered.states)
 
       return { outcome: "created", version: cloneDatasetVersion(version) }
@@ -636,6 +664,7 @@ export class InMemoryLakeStorage implements LakeStorage {
       visibleRows.map((row) => cloneRow(row))
     )
     this.latestVersionIdByDataset.set(options.write.dataset.id, versionId)
+    this.commitPositionByDataset.set(options.write.dataset.id, ++this.commitPosition)
 
     return { ...cloneDatasetVersion(version), outcome: "created" }
   }

package/src/lake-storage/index.ts

@@ -69,6 +69,8 @@ export type {
   LakeStandardId,
   LakeStorage,
   LakeWriteSession,
+  LatestVersionsSince,
+  ListLatestVersionsSinceInput,
   ReadDatasetChangesInput,
   ReadDatasetRowsInput,
 } from "./types"

package/src/lake-storage/types.ts

@@ -53,6 +53,24 @@ export interface DatasetCatalogState {
   readonly latestVersion?: DatasetLatestVersionSummary | null
 }
 
+export interface ListLatestVersionsSinceInput {
+  /** A cursor returned by an earlier call, or null to start at the lake's current position. */
+  readonly cursor: string | null
+  /** Report only these datasets. Omit to report every dataset. */
+  readonly datasetIds?: readonly string[]
+}
+
+export interface LatestVersionsSince {
+  /** Opaque position to pass to the next call. */
+  readonly cursor: string
+  /**
+   * The newest data-bearing (non-`schema`) version of each dataset that committed one after the
+   * input cursor and up to the returned one, in no particular order. A provider may stop short of
+   * its newest commit to bound one call; the next call continues. Empty for a null input cursor.
+   */
+  readonly versions: readonly DatasetLatestVersionSummary[]
+}
+
 export interface BeginDatasetWriteInput {
   readonly dataset: DatasetDefinition
   readonly mode?: DatasetWriteMode
@@ -170,6 +188,18 @@ export interface LakeStorage {
 
   getLatestVersion(datasetId: string): Promise<DatasetVersion | null>
   getVersion(datasetId: string, versionId: string): Promise<DatasetVersion | null>
+
+  /**
+   * Change feed: which datasets committed data since a cursor. Consumers that must not miss a
+   * commit, such as projection reconciliation, poll it instead of reading every dataset's latest
+   * version. Its cost must not grow with the lake's history: an idle read should be about as
+   * cheap as one metadata lookup.
+   *
+   * Null means the cursor is no longer a position in this lake (for example, the catalog was
+   * recreated or the cursor's commit expired): read current state, then restart from null.
+   */
+  listLatestVersionsSince(input: ListLatestVersionsSinceInput): Promise<LatestVersionsSince | null>
+
   /** Explicit immutable-version reads have stable physical order and stable offset semantics. */
   readRows(input: ReadDatasetRowsInput): AsyncIterable<DatasetRow>