was-teaching-server 0.9.1 → 0.11.0

package/src/types.ts

@@ -41,6 +41,13 @@ import type {
   BlindedIndexQuery,
   BlindedIndexQueryPage
 } from './lib/blindedIndex.js'
+import type {
+  EqualityQuery,
+  EqualityQueryPage,
+  EqualityCandidate,
+  EqualityValue,
+  NormalizedIndexDeclaration
+} from './lib/equalityIndex.js'
 
 // The shared WAS wire model now lives in `@interop/storage-core`. Import the
 // shapes referenced by the `StorageBackend` contract below, and re-export the
@@ -64,6 +71,17 @@ import type {
 // contract (`queryByBlindedIndex`) from this one module.
 export type { BlindedIndexQuery, BlindedIndexQueryPage }
 
+// Surface the equality-index query shapes referenced by the `StorageBackend`
+// contract (`queryByEquality` / `findEqualityUniqueViolation`) from this one
+// module, alongside the blinded-index ones.
+export type {
+  EqualityQuery,
+  EqualityQueryPage,
+  EqualityCandidate,
+  EqualityValue,
+  NormalizedIndexDeclaration
+}
+
 // Surface the reused @interop/data-integrity-core types from this one module.
 export type {
   IDID,
@@ -91,6 +109,7 @@ export type {
   ResourceSummary,
   CollectionResourcesList,
   CollectionDescription,
+  CollectionIndexDeclaration,
   CollectionEncryption,
   CollectionEncryptionEpoch,
   CollectionEncryptionRecipient,
@@ -608,12 +627,30 @@ export interface StorageBackend {
    * (see `lib/blindedIndex.ts`). Conflicts require `unique: true` on both
    * sides, and a document keeping its own unique attribute across an update
    * never self-conflicts.
+   *
+   * A backend carrying the `equality-query` feature enforces the analogous
+   * plaintext unique-attribute invariant when the request layer passes
+   * `uniqueIndexes` (the target Collection's normalized `unique: true`
+   * declarations, resolved from its control-plane description): a write whose
+   * extracted value for a `unique` content-sourced attribute is already claimed
+   * by a different live Resource in the same Collection rejects with
+   * `UniqueAttributeConflictError` (409), evaluated atomically with the write
+   * (see `lib/equalityIndex.ts`). Unlike the blinded invariant this is
+   * Collection-level, so a conflict does not require the other side to opt in.
    */
   writeResource(options: {
     spaceId: string
     collectionId: string
     resourceId: string
     input: ResourceInput
+    /**
+     * The target Collection's normalized `unique: true` index declarations,
+     * passed by the request layer only when the Collection declares any. The
+     * backend enforces the plaintext unique-attribute claim atomically with the
+     * write (409 `UniqueAttributeConflictError`), for the content-sourced
+     * entries a content write can claim.
+     */
+    uniqueIndexes?: NormalizedIndexDeclaration[]
     /**
      * DID of the party whose capability invocation authorized this write (the
      * signing key's DID, fragment stripped). Recorded as the Resource's
@@ -645,7 +682,9 @@ export interface StorageBackend {
    * Deletes a Resource. When `ifMatch` is supplied (`conditional-writes`), the
    * delete proceeds only if the Resource's current ETag matches, evaluated
    * atomically with the removal; a mismatch rejects with `precondition-failed`
-   * (412). Without it, the delete is unconditional and idempotent.
+   * (412). Without it, the delete is unconditional and idempotent. Deleting a
+   * Resource cascade-deletes any chunks stored under it (the `chunked-streams`
+   * feature), so chunks never outlive their parent.
    */
   deleteResource(options: {
     spaceId: string
@@ -683,6 +722,15 @@ export interface StorageBackend {
     collectionId: string
     resourceId: string
     custom: ResourceMetadataCustom | Record<string, unknown>
+    /**
+     * The target Collection's normalized `unique: true` index declarations,
+     * passed by the request layer only when the Collection declares any. The
+     * backend enforces the plaintext unique-attribute claim atomically with the
+     * metadata write (409 `UniqueAttributeConflictError`), for the
+     * custom-sourced entries a metadata write can claim (see
+     * `lib/equalityIndex.ts`).
+     */
+    uniqueIndexes?: NormalizedIndexDeclaration[]
     /**
      * The client-declared key epoch (the `key-epochs` feature), a sibling of
      * `custom`. Unlike `custom` (full replacement), an OMITTED `epoch`
@@ -694,6 +742,81 @@ export interface StorageBackend {
     ifNoneMatch?: boolean
   }): Promise<{ metaVersion: number } | undefined>
 
+  /**
+   * Writes one chunk of a chunked Resource (the `chunked-streams` feature),
+   * keyed by `(spaceId, collectionId, resourceId, chunkIndex)`. The chunk body
+   * is opaque bytes + content-type -- stored exactly like a binary Resource
+   * representation (same upload cap / quota guards); the server never parses
+   * it. The parent Resource MUST already exist: writing a chunk of an absent
+   * Resource rejects with `ResourceNotFoundError` (404), so orphan chunks
+   * cannot accumulate. An upsert per chunk, bumping the chunk's own monotonic
+   * `version` (its ETag validator, independent of the parent's); an `ifMatch` /
+   * `ifNoneMatch` precondition is evaluated on that chunk version atomically
+   * with the write (`precondition-failed` 412 on mismatch).
+   */
+  writeChunk(options: {
+    spaceId: string
+    collectionId: string
+    resourceId: string
+    chunkIndex: number
+    input: ResourceInput
+    ifMatch?: string
+    ifNoneMatch?: boolean
+  }): Promise<{ version: number }>
+  /** Reads a chunk's bytes; rejects with `ResourceNotFoundError` when absent. */
+  getChunk(options: {
+    spaceId: string
+    collectionId: string
+    resourceId: string
+    chunkIndex: number
+  }): Promise<ResourceResult>
+  /**
+   * Reads a chunk's stored content-type / size / version (the HEAD payload
+   * headers). Resolves `undefined` when the chunk is absent.
+   */
+  getChunkMetadata(options: {
+    spaceId: string
+    collectionId: string
+    resourceId: string
+    chunkIndex: number
+  }): Promise<
+    { contentType: string; size: number; version?: number } | undefined
+  >
+  /**
+   * Deletes one chunk. Resolves `true` when a chunk was removed and `false`
+   * when none was stored at that index (the handler 404s on `false` -- unlike
+   * `deleteResource`, chunk deletes are not silently idempotent, mirroring the
+   * EDV chunk contract). An `ifMatch` precondition is evaluated atomically
+   * with the removal (`precondition-failed` 412 on mismatch).
+   */
+  deleteChunk(options: {
+    spaceId: string
+    collectionId: string
+    resourceId: string
+    chunkIndex: number
+    ifMatch?: string
+  }): Promise<boolean>
+  /**
+   * Lists a Resource's stored chunks in ascending `index` order -- the
+   * discovery/reassembly listing (the server never reassembles; a reader
+   * learns the chunk set here). Resolves an empty listing when the Resource
+   * has no chunks (including when the Resource itself is absent -- existence
+   * is the parent routes' concern).
+   */
+  listChunks(options: {
+    spaceId: string
+    collectionId: string
+    resourceId: string
+  }): Promise<{
+    count: number
+    chunks: Array<{
+      index: number
+      size: number
+      contentType: string
+      version?: number
+    }>
+  }>
+
   /**
    * OPTIONAL replication change feed (the `changes` query profile.
    * Returns the Collection's JSON-document
@@ -777,6 +900,57 @@ export interface StorageBackend {
     cursor?: string
   }): Promise<{ count: number } | BlindedIndexQueryPage>
 
+  /**
+   * OPTIONAL plaintext equality query (the `equality` query profile; the
+   * `equality-query` feature token). Evaluates an equality query -- `equals`
+   * (OR across elements of an AND within each element's `{name: value}` pairs)
+   * or `has` (every named attribute present with an indexable value) -- over
+   * the attributes the server extracts from the Collection's live Resources per
+   * the `indexes` declaration. `indexes` is the NORMALIZED declaration array:
+   * the request layer resolves it from the control-plane description (a
+   * data-plane backend does not hold the description) and passes it in. Matching
+   * is strict JSON equality (no coercion); a content-sourced attribute reads a
+   * JSON Resource's stored content, a custom-sourced one reads the `custom`
+   * metadata object (so blobs are queryable too). With `count`, resolves only
+   * the match total; otherwise a page of matching documents (`{ id, data?,
+   * custom? }`) in ascending `resourceId` order, paginated with the standard
+   * opaque cursor (`cursor` present iff `hasMore`; a malformed one rejects with
+   * `invalid-cursor` 400). Both first-party backends answer through
+   * `lib/equalityIndex.ts` so semantics cannot drift.
+   *
+   * OPTIONAL: a backend that omits this method does not serve the profile, and
+   * the request layer returns `unsupported-operation` (501). The Space and
+   * Collection are guaranteed to exist by the request layer.
+   */
+  queryByEquality?(options: {
+    spaceId: string
+    collectionId: string
+    query: EqualityQuery
+    indexes: NormalizedIndexDeclaration[]
+    count?: boolean
+    limit?: number
+    cursor?: string
+  }): Promise<{ count: number } | EqualityQueryPage>
+
+  /**
+   * OPTIONAL declare-time uniqueness scan for the `equality` profile: given the
+   * Collection's normalized `unique: true` declarations, scans its already-
+   * stored live Resources for two DIFFERENT Resources that claim the same
+   * `(name, value)`, resolving the first such `{ name, value }` or `undefined`
+   * when none exists. The request layer runs it when a Collection update ADDS a
+   * unique claim, rejecting a found violation with `id-conflict` (409) so a
+   * unique claim is never acknowledged over already-conflicting data.
+   *
+   * OPTIONAL: paired with `queryByEquality` on backends carrying the
+   * `equality-query` feature. The Space and Collection are guaranteed to exist
+   * by the request layer.
+   */
+  findEqualityUniqueViolation?(options: {
+    spaceId: string
+    collectionId: string
+    indexes: NormalizedIndexDeclaration[]
+  }): Promise<{ name: string; value: EqualityValue } | undefined>
+
   /**
    * Access-control policy documents. The level is selected by which ids are
    * present: Space (`spaceId`), Collection (`+ collectionId`), or Resource