@sixb/core 0.1.16 → 0.1.18

package/src/ontology/docs.ts

@@ -0,0 +1,196 @@
+/**
+ * Where each object type's Agent reference doc lives, and which hand-written docs and scripts are
+ * mounted next to it.
+ *
+ * The generated doc of a type mirrors the `ontology/` module that defines it:
+ * `billing/invoice.ts` → `billing/invoice.md`. A module that defines several types gets a folder,
+ * one doc per type: `billing.ts` → `billing/Invoice.md`, `billing/Customer.md`.
+ *
+ * Hand-written docs are notes when they sit at a type's doc path or next to a module exporting the
+ * type (`billing.md` for every type of `billing.ts`), compared without case. Notes are appended to
+ * the doc of each visible type they belong to, so a reader never receives the notes of types it
+ * cannot see. Any other hand-written doc is mounted as written, for every reader.
+ */
+
+import type { AgentProjectFile } from "../agents/skills"
+import { RuntimeError } from "../runtime/errors"
+import type { ObjectType } from "./types"
+
+/** Hand-written Markdown under `ontology/`. */
+export interface OntologyDoc {
+  /** POSIX path relative to `ontology/`. */
+  readonly path: string
+  readonly contents: string
+}
+
+/** The Agent's files under `ontology/`, as createSixb() discovers them. */
+export interface OntologyDocsInput {
+  /** Each module, by POSIX path relative to `ontology/`, with the object types it exports. */
+  readonly modules: readonly { readonly path: string; readonly objectTypeIds: readonly string[] }[]
+  readonly docs: readonly OntologyDoc[]
+  /** Every file in a `scripts/` directory under `ontology/`, mounted as written. */
+  readonly scripts: readonly AgentProjectFile[]
+}
+
+/** Paths are POSIX and relative to `ontology/`. */
+export interface OntologyDocsCatalog {
+  /** Path of the doc generated for this object type. */
+  docPathFor(objectTypeId: string): string
+  /** The team's notes for this type, appended to its doc. Sorted by path. */
+  notesFor(objectTypeId: string): readonly OntologyDoc[]
+  /** Hand-written docs that belong to no object type, mounted for every reader. */
+  listDocs(): readonly OntologyDoc[]
+  listScripts(): readonly AgentProjectFile[]
+  /** Whether a link declares any type (`*`) as its target. Readers' views expand it. */
+  isWildcardLink(objectTypeId: string, linkId: string): boolean
+}
+
+/** Resolve every registered object type's doc path, rejecting two files that would share one. */
+export function createOntologyDocsCatalog(input: {
+  readonly objectTypes: readonly ObjectType[]
+  readonly docs?: OntologyDocsInput
+}): OntologyDocsCatalog {
+  const modules = input.docs?.modules ?? []
+  const scripts = Object.freeze([...(input.docs?.scripts ?? [])])
+  // Sandboxes may sit on a case-insensitive filesystem, where `Invoice.md` overwrites `invoice.md`.
+  const claimedPaths = new Map<string, string>(
+    scripts.map((script) => [script.path.toLowerCase(), `script 'ontology/${script.path}'`])
+  )
+  const claim = (path: string, owner: string) => {
+    const claimedBy = claimedPaths.get(path.toLowerCase())
+    if (claimedBy !== undefined) {
+      throw new RuntimeError(
+        `[Sixb] The ${owner} at 'ontology/${path}' collides with ${claimedBy}, which only differs ` +
+          "by case or not at all. Rename one of them."
+      )
+    }
+    claimedPaths.set(path.toLowerCase(), `the ${owner}`)
+  }
+
+  const docPathByType = new Map<string, string>()
+  // A hand-written doc at a type's doc path, or next to any module that exports the type, is
+  // notes for that type. Several types share the notes of a module that exports all of them.
+  const typeIdsByNotesPath = new Map<string, Set<string>>()
+  const addNotesPath = (path: string, objectTypeIds: readonly string[]) => {
+    const typeIds = typeIdsByNotesPath.get(path.toLowerCase()) ?? new Set<string>()
+    for (const objectTypeId of objectTypeIds) typeIds.add(objectTypeId)
+    typeIdsByNotesPath.set(path.toLowerCase(), typeIds)
+  }
+  for (const objectType of input.objectTypes) {
+    const path = docPathFor(objectType.id, modules)
+    claim(path, `doc of object type '${objectType.id}'`)
+    docPathByType.set(objectType.id, path)
+    addNotesPath(path, [objectType.id])
+  }
+  for (const module of modules) {
+    if (module.objectTypeIds.length > 0) {
+      addNotesPath(`${withoutExtension(module.path)}.md`, module.objectTypeIds)
+    }
+  }
+
+  const notesByType = new Map<string, OntologyDoc[]>()
+  const docs: OntologyDoc[] = []
+  const docPaths = new Map<string, string>()
+  for (const doc of input.docs?.docs ?? []) {
+    const sameName = docPaths.get(doc.path.toLowerCase())
+    if (sameName !== undefined) {
+      throw new RuntimeError(
+        `[Sixb] The ontology docs 'ontology/${sameName}' and 'ontology/${doc.path}' only differ ` +
+          "by case. Rename one of them."
+      )
+    }
+    docPaths.set(doc.path.toLowerCase(), doc.path)
+
+    const objectTypeIds = typeIdsByNotesPath.get(doc.path.toLowerCase())
+    if (objectTypeIds === undefined) {
+      docs.push(doc)
+      continue
+    }
+    for (const objectTypeId of objectTypeIds) {
+      notesByType.set(objectTypeId, [...(notesByType.get(objectTypeId) ?? []), doc])
+    }
+  }
+  for (const notes of notesByType.values()) notes.sort(byPath)
+  Object.freeze(docs)
+
+  const wildcardLinks = new Set(
+    input.objectTypes.flatMap((objectType) =>
+      objectType.links
+        .filter((link) => link.targetObjectTypeId === "*")
+        .map((link) => linkKey(objectType.id, link.id))
+    )
+  )
+
+  return Object.freeze({
+    docPathFor: (objectTypeId: string) => {
+      const path = docPathByType.get(objectTypeId)
+      if (path === undefined) {
+        throw new RuntimeError(`[Sixb] Object type '${objectTypeId}' is not registered.`)
+      }
+      return path
+    },
+    notesFor: (objectTypeId: string) => notesByType.get(objectTypeId) ?? [],
+    listDocs: () => docs,
+    listScripts: () => scripts,
+    isWildcardLink: (objectTypeId: string, linkId: string) =>
+      wildcardLinks.has(linkKey(objectTypeId, linkId)),
+  })
+}
+
+/**
+ * The module that defines a type, among those exporting it: the one named after the type
+ * (`email-thread.ts` for `EmailThread`), else any module but an `index`, else the one exporting the
+ * fewest types, else the first by path. Re-exporting barrels never take a type from its module.
+ */
+function docPathFor(objectTypeId: string, modules: OntologyDocsInput["modules"]): string {
+  const rank = (module: OntologyDocsInput["modules"][number]) => {
+    const name = basename(withoutExtension(module.path))
+    return [
+      kebabCase(name) === kebabCase(objectTypeId) ? 0 : 1,
+      name === "index" ? 1 : 0,
+      module.objectTypeIds.length,
+    ]
+  }
+  let owner: OntologyDocsInput["modules"][number] | undefined
+  for (const module of modules) {
+    if (!module.objectTypeIds.includes(objectTypeId)) continue
+    if (owner === undefined || compareRanks(rank(module), rank(owner)) < 0) owner = module
+  }
+
+  const fileName = `${objectTypeId.replaceAll(/[^A-Za-z0-9._-]/g, "_")}.md`
+  if (owner === undefined) return fileName
+  const base = withoutExtension(owner.path)
+  return owner.objectTypeIds.length === 1 ? `${base}.md` : `${base}/${fileName}`
+}
+
+function compareRanks(left: readonly number[], right: readonly number[]): number {
+  for (const [index, value] of left.entries()) {
+    const difference = value - (right[index] ?? 0)
+    if (difference !== 0) return difference
+  }
+  return 0
+}
+
+function kebabCase(name: string): string {
+  return name
+    .replaceAll(/([a-z0-9])([A-Z])/g, "$1-$2")
+    .replaceAll(/([A-Z]+)([A-Z][a-z])/g, "$1-$2")
+    .replaceAll(/[\s_]+/g, "-")
+    .toLowerCase()
+}
+
+function withoutExtension(path: string): string {
+  return path.replace(/\.[^./]+$/, "")
+}
+
+function basename(path: string): string {
+  return path.slice(path.lastIndexOf("/") + 1)
+}
+
+function linkKey(objectTypeId: string, linkId: string): string {
+  return JSON.stringify([objectTypeId, linkId])
+}
+
+function byPath(left: OntologyDoc, right: OntologyDoc): number {
+  return left.path < right.path ? -1 : left.path > right.path ? 1 : 0
+}

package/src/ontology/index.ts

@@ -47,8 +47,10 @@ export type {
   ObjectLink,
   ObjectLinkTargetMetadata,
   ObjectLinkTargetType,
+  ObjectQueryIndexDefinition,
   ObjectSchema,
   ObjectType,
+  ObjectTypeQueryMetadata,
   ObjectTypeSearchMetadata,
   ObjectVectorSearchProfile,
   Ontology,

package/src/ontology/inference/index.ts

@@ -211,6 +211,31 @@ export type InferObjectProperties<
         }
       >
 
+/**
+ * Property values as a principal reads them. A marked property may be redacted, so it is optional
+ * even when required; writes keep {@link InferObjectProperties}.
+ */
+export type InferObjectReadProperties<
+  TObjectType extends { properties: readonly Property[] },
+  TValueTypes extends readonly ValueType[] = RegisteredValueTypes,
+> = string extends TObjectType["properties"][number]["id"]
+  ? Record<string, unknown>
+  : Simplify<
+      {
+        [TProp in TObjectType["properties"][number] as TProp extends { required: true }
+          ? TProp extends { markings: readonly string[] }
+            ? never
+            : TProp["id"]
+          : never]: InferPropertyValue<TProp, TValueTypes>
+      } & {
+        [TProp in TObjectType["properties"][number] as TProp extends { required: true }
+          ? TProp extends { markings: readonly string[] }
+            ? TProp["id"]
+            : never
+          : TProp["id"]]?: InferPropertyValue<TProp, TValueTypes>
+      }
+    >
+
 /** Useful for APIs that should only accept telemetry-mode properties. */
 export type InferTelemetryPropertyIds<TObjectType extends { properties: readonly Property[] }> =
   Extract<TObjectType["properties"][number], { mode: "telemetry" }>["id"]

package/src/ontology/internal.ts

@@ -1,3 +1,9 @@
+export type {
+  OntologyDocsIndexEntry,
+  RenderedOntologyDocs,
+  RenderOntologyDocsInput,
+} from "./docs-markdown"
+export { renderOntologyDocs } from "./docs-markdown"
 export { schemaFieldsToJsonSchema, schemaRecordToJsonSchema } from "./json-schema"
 export { resolvePropertyQueryCapabilities } from "./query-capabilities"
 export { validateSchemaOrRefValue } from "./refs"
@@ -26,6 +32,7 @@ export {
 } from "./validation/properties"
 export { validateQueryMetadata } from "./validation/query"
 export {
+  assertValidFileRefs,
   isRecord,
   resolveValueTypeRef,
   resolveValueTypeSchema,

package/src/ontology/query-capabilities.ts

@@ -123,7 +123,7 @@ export function resolvePropertyQueryCapabilities(
   }
 }
 
-function resolveQuerySchema(
+export function resolveQuerySchema(
   schema: Schema,
   valueTypesById: ReadonlyMap<string, ValueType>,
   seen = new Set<string>()

package/src/ontology/tokens.ts

@@ -1,4 +1,4 @@
-import type { InferObjectProperties } from "./inference"
+import type { InferObjectProperties, InferObjectReadProperties } from "./inference"
 import {
   createLinkPathSelection,
   type LinkPathSelectionBuilder,
@@ -75,7 +75,10 @@ export type ObjectTypeWithPropertyTokens<TObjectType extends ObjectType = Object
  */
 export type ObjectPropertiesMetadata<TObjectType extends ObjectType> = {
   readonly [objectPropertiesBrand]?: string extends TObjectType["id"]
-    ? { readonly properties: Record<string, unknown> }
+    ? {
+        readonly properties: Record<string, unknown>
+        readonly readProperties: Record<string, unknown>
+      }
     : ObjectPropertiesCarrier<TObjectType>
 }
 
@@ -91,6 +94,7 @@ export type ObjectPropertiesMetadata<TObjectType extends ObjectType> = {
  */
 interface ObjectPropertiesCarrier<in out TObjectType extends ObjectType> {
   readonly properties: InferObjectProperties<TObjectType>
+  readonly readProperties: InferObjectReadProperties<TObjectType>
 }
 
 /**
@@ -103,6 +107,13 @@ export type ObjectTypeProperties<TObjectType extends ObjectTypeWithPropertyToken
   TObjectType[typeof objectPropertiesBrand]
 >["properties"]
 
+/**
+ * The property values of an object type as a read returns them: a marked property is optional,
+ * because a reader without clearance receives it redacted.
+ */
+export type ObjectTypeReadProperties<TObjectType extends ObjectTypeWithPropertyTokens> =
+  NonNullable<TObjectType[typeof objectPropertiesBrand]>["readProperties"]
+
 /**
  * Object type with property tokens (`p.*`) and link tokens (`l.*`).
  *

package/src/ontology/types.ts

@@ -284,6 +284,11 @@ export interface Property {
   semanticType?: QuantitativeTypeId
   /** Query/indexing metadata for this property. */
   query?: PropertyQueryMetadata
+  /**
+   * Marking ids. A principal receives this property only when its roles clear every marking;
+   * otherwise the value is omitted and listed in the object's `redactions`.
+   */
+  markings?: readonly string[]
 }
 
 /**
@@ -360,6 +365,25 @@ export interface Interface {
   links: ObjectLink[]
 }
 
+/** Compound query shapes prepared by the storage provider, in addition to property flags. */
+export type ObjectQueryIndexDefinition =
+  | {
+      kind: "sort"
+      fields: readonly { propertyId: string; direction?: "asc" | "desc" }[]
+      /** String equality filters preceding the ordered fields. */
+      filters?: readonly string[]
+    }
+  | {
+      kind: "text"
+      propertyId: string
+      /** String filters/facets commonly combined with this substring search. */
+      filters?: readonly string[]
+    }
+
+export interface ObjectTypeQueryMetadata {
+  indexes?: readonly ObjectQueryIndexDefinition[]
+}
+
 /**
  * Canonical ontology node for a real-world asset, system, concept, or process.
  *
@@ -413,6 +437,8 @@ export interface ObjectType {
 
   properties: Property[]
   links: ObjectLink[]
+  /** Query index declarations, prepared automatically after storage migrations. */
+  query?: ObjectTypeQueryMetadata
   /** Search profile for this object type. */
   search?: ObjectTypeSearchMetadata
 }

package/src/ontology/validation/index.ts

@@ -24,6 +24,7 @@ export {
 } from "./properties"
 export { validateQueryMetadata } from "./query"
 export {
+  assertValidFileRefs,
   isRecord,
   resolveValueTypeRef,
   resolveValueTypeSchema,

package/src/ontology/validation/query.ts

@@ -7,6 +7,8 @@ import {
   isFilterableSchema,
   isSortableSchema,
   isTextSchema,
+  queryScalarKindForSchema,
+  resolveQuerySchema,
 } from "../query-capabilities"
 
 type QueryFeature = "filterable" | "sortable" | "text" | "exact" | "facet"
@@ -27,6 +29,7 @@ export function validateQueryMetadata(
     }
 
     validateObjectSearchMetadata(typeId, objectType, valueTypesById)
+    validateQueryIndexes(typeId, objectType, valueTypesById)
   }
 }
 
@@ -250,3 +253,57 @@ function resolveSchema(
   seenValueTypeIds.add(schema.valueTypeId)
   return resolveSchema(resolved, valueTypesById, path, seenValueTypeIds)
 }
+
+function validateQueryIndexes(
+  typeId: string,
+  objectType: ObjectType,
+  valueTypes: ReadonlyMap<string, ValueType>
+): void {
+  for (const index of objectType.query?.indexes ?? []) {
+    const fields =
+      index.kind === "sort" ? index.fields.map((field) => field.propertyId) : [index.propertyId]
+    const filters = index.filters ?? []
+    if (
+      !fields.length ||
+      fields.length + filters.length > 8 ||
+      new Set([...fields, ...filters]).size !== fields.length + filters.length
+    )
+      throw new OntologyValidationError(
+        `[Sixb] Query index on '${typeId}' requires one to eight distinct properties`
+      )
+    if (index.kind === "text" && filters.length > 4)
+      throw new OntologyValidationError(
+        `[Sixb] Text query index on '${typeId}' accepts at most four filters`
+      )
+    for (const id of [...fields, ...filters]) {
+      const property = objectType.properties.find((property) => property.id === id)
+      if (!property)
+        throw new OntologyValidationError(
+          `[Sixb] Query index on '${typeId}' references unknown property '${id}'`
+        )
+      if (property.mode === "telemetry")
+        throw new OntologyValidationError(
+          `[Sixb] Query indexes cannot include telemetry property '${typeId}.${id}'`
+        )
+      const flag = filters.includes(id) ? "filterable" : index.kind === "sort" ? "sortable" : "text"
+      assertPropertyQueryFlag(typeId, property, flag, "query.indexes")
+      if (filters.includes(id)) {
+        const schema = resolveQuerySchema(property.schema, valueTypes)
+        if (!schema || queryScalarKindForSchema(schema) !== "string")
+          throw new OntologyValidationError(
+            `[Sixb] Query index filters must be strings: '${typeId}.${id}'`
+          )
+      }
+    }
+    if (
+      index.kind === "sort" &&
+      index.fields.some(
+        (field) =>
+          field.direction !== undefined && field.direction !== "asc" && field.direction !== "desc"
+      )
+    )
+      throw new OntologyValidationError(
+        `[Sixb] Query index direction must be asc or desc on '${typeId}'`
+      )
+  }
+}

package/src/ontology/validation/schema.ts

@@ -1,4 +1,4 @@
-import { isFileRef } from "../../blob-storage/validation"
+import { isFileRef, isValidFileRef } from "../../blob-storage/validation"
 import { withFailureMessage } from "../../errors/failure-message"
 import type { ObjectFieldSchema, Schema, ValueType, ValueTypeRefSchema } from ".."
 import { isDecimalString } from "../decimal"
@@ -201,6 +201,31 @@ export function validateSchemaValue(
   }
 }
 
+/**
+ * Reject a value from a caller that holds a file reference whose `mediaType` is not exactly one
+ * media type, anywhere inside it. Call it where caller input is accepted, after
+ * `validateSchemaValue`; that validator also re-checks stored state, which must keep loading
+ * references written before the rule.
+ */
+export function assertValidFileRefs(value: unknown, path: string): void {
+  if (isFileRef(value)) {
+    if (!isValidFileRef(value)) {
+      throw withFailureMessage(
+        new OntologyValidationError(
+          `[Sixb] Property ${path}.mediaType must be one media type, such as "application/pdf"`
+        ),
+        `Property ${path}.mediaType must be one media type, such as "application/pdf".`
+      )
+    }
+    return
+  }
+  if (Array.isArray(value)) {
+    for (const [index, item] of value.entries()) assertValidFileRefs(item, `${path}[${index}]`)
+  } else if (isRecord(value)) {
+    for (const [key, item] of Object.entries(value)) assertValidFileRefs(item, `${path}.${key}`)
+  }
+}
+
 function validateFieldValue(
   field: ObjectFieldSchema,
   value: unknown,

package/src/query.ts

@@ -6,6 +6,8 @@
  * top of this module.
  */
 
+export type { ModelRef } from "./models/catalog"
+export type { RerankingModelDefinition, RerankingModelRef } from "./models/reranking-model"
 export type { ObjectQueryPlanningIssue } from "./objects/query/errors"
 export {
   ObjectQueryExecutionError,
@@ -29,6 +31,7 @@ export type {
   ObjectQueryPredicateNot,
   ObjectQueryProject,
   ObjectQueryRefs,
+  ObjectQueryRerank,
   ObjectQueryResultShape,
   ObjectQuerySet,
   ObjectQuerySetOperation,
@@ -68,6 +71,7 @@ export type {
   ObjectQueryFacetBucket,
   ObjectQueryFacetInput,
   ObjectQueryFacetResult,
+  ObjectQueryFacetsResult,
   ObjectQueryListOptions,
   ObjectQueryRow,
   ObjectWhereBuilder,

package/src/queues/in-memory.ts

@@ -109,11 +109,16 @@ function eligibleAt(record: QueueRecord): number {
   return Math.max(record.availableAtMs, record.leaseExpiryMs ?? -Infinity)
 }
 
+// Largest delay `setTimeout` accepts; a waiting claim that wakes early just waits again.
+const MAX_TIMER_DELAY_MS = 2_147_483_647
+
 interface QueueLane {
   // Terminal records remain here for caller-id deduplication, never in the delivery indexes.
   readonly records: Map<string, QueueRecord>
   readonly ready: IndexedHeap<QueueRecord>
   readonly waiting: IndexedHeap<QueueRecord>
+  /** Wakes claims waiting on this lane. */
+  readonly waiters: Set<() => void>
 }
 
 function toClaimedQueueJob<TQueueJob extends QueueJob>(
@@ -175,6 +180,27 @@ class InMemoryQueueStore {
       lane.ready.delete(record)
       lane.waiting.set(record)
     }
+    // Any change can make a job claimable or move the next due time; waiters look again.
+    for (const wake of lane.waiters) wake()
+  }
+
+  /** Resolves when the lane changes, its next delayed job or lease comes due, or `signal` aborts. */
+  waitForWork(projectId: string, queueId: string, signal: AbortSignal): Promise<void> {
+    const lane = this.lane(projectId, queueId)
+    const next = lane.waiting.peek()
+    const dueInMs = next ? eligibleAt(next) - Date.now() : MAX_TIMER_DELAY_MS
+    return new Promise((resolve) => {
+      // Always armed: like a blocking read on a socket, a waiting claim keeps its process alive.
+      const timer = setTimeout(wake, Math.min(dueInMs, MAX_TIMER_DELAY_MS))
+      function wake(): void {
+        clearTimeout(timer)
+        lane.waiters.delete(wake)
+        signal.removeEventListener("abort", wake)
+        resolve()
+      }
+      lane.waiters.add(wake)
+      signal.addEventListener("abort", wake, { once: true })
+    })
   }
 
   takeReady<TQueueJob extends QueueJob>(
@@ -216,6 +242,7 @@ class InMemoryQueueStore {
         waiting: new IndexedHeap(
           (left, right) => eligibleAt(left) - eligibleAt(right) || left.sequence - right.sequence
         ),
+        waiters: new Set(),
       }
       queues.set(queueId, lane)
     }
@@ -263,6 +290,7 @@ class InMemoryQueue<TQueueJob extends QueueJob, TFailureCode extends SixbErrorCo
     workerId: string
     limit?: number
     leaseMs?: number
+    signal?: AbortSignal
   }): Promise<readonly ClaimedQueueJob<TQueueJob>[]> {
     assertNonEmpty(params.projectId, "projectId")
     assertNonEmpty(params.workerId, "workerId")
@@ -275,27 +303,34 @@ class InMemoryQueue<TQueueJob extends QueueJob, TFailureCode extends SixbErrorCo
     const leaseMs = params.leaseMs ?? 30_000
     assertPositiveNumber(leaseMs, "leaseMs")
 
-    const now = Date.now()
-    const claimedAt = new Date(now).toISOString()
-    // Validate before removing candidates, and cache the same millisecond precision we return.
-    const leaseExpiry = new Date(now + leaseMs)
-    const leaseExpiresAt = leaseExpiry.toISOString()
-    const claimable = this.store.takeReady<TQueueJob>(params.projectId, this.queueId, now, limit)
-
-    return claimable.map((record) => {
-      // Attempts count claims so redelivery after lease expiry or retry is visible to workers.
-      record.job = {
-        ...record.job,
-        attempt: record.job.attempt + 1,
+    for (;;) {
+      if (params.signal?.aborted) return []
+      const now = Date.now()
+      const claimedAt = new Date(now).toISOString()
+      // Validate before removing candidates, and cache the same millisecond precision we return.
+      const leaseExpiry = new Date(now + leaseMs)
+      const leaseExpiresAt = leaseExpiry.toISOString()
+      const claimable = this.store.takeReady<TQueueJob>(params.projectId, this.queueId, now, limit)
+      if (claimable.length === 0 && params.signal) {
+        await this.store.waitForWork(params.projectId, this.queueId, params.signal)
+        continue
       }
-      record.leaseId = randomUUID()
-      record.claimedAt = claimedAt
-      record.leaseExpiresAt = leaseExpiresAt
-      record.leaseExpiryMs = leaseExpiry.getTime()
-      this.store.schedule(params.projectId, record, now)
 
-      return toClaimedQueueJob(record)
-    })
+      return claimable.map((record) => {
+        // Attempts count claims so redelivery after lease expiry or retry is visible to workers.
+        record.job = {
+          ...record.job,
+          attempt: record.job.attempt + 1,
+        }
+        record.leaseId = randomUUID()
+        record.claimedAt = claimedAt
+        record.leaseExpiresAt = leaseExpiresAt
+        record.leaseExpiryMs = leaseExpiry.getTime()
+        this.store.schedule(params.projectId, record, now)
+
+        return toClaimedQueueJob(record)
+      })
+    }
   }
 
   async complete(params: { projectId: string; jobId: string; leaseId: string }): Promise<void> {

package/src/queues/types.ts

@@ -82,12 +82,16 @@ export interface Queue<
    *
    * `leaseMs` is the visibility timeout for this claim. If the lease expires
    * before the job is acknowledged, the job may be delivered again.
+   *
+   * Without `signal`, returns at once, possibly empty. With `signal`, waits for work instead:
+   * it resolves once it claims at least one job, and empty only after `signal` aborts.
    */
   claim(params: {
     projectId: string
     workerId: string
     limit?: number
     leaseMs?: number
+    signal?: AbortSignal
   }): Promise<readonly ClaimedQueueJob<TQueueJob>[]>
 
   /** Acknowledges successful processing and removes the claimed job from delivery. */