@ebbjs/storage 0.3.0 → 1.1.0

package/dist/indexeddb/index.d.ts

@@ -122,9 +122,10 @@ interface MembershipLink {
  * handled by the DirtyTracker.
  *
  * ## Merge Semantics
- * - **put** — full entity replacement
- * - **patch** — field-level Last-Writer-Wins (LWW): higher HLC wins; tiebreak by lexicographic `update_id`
- * - **delete** — soft delete (sets `deleted_hlc`); patch-on-deleted is ignored
+ * - **merge** — Last-Writer-Wins (LWW) at the component's field: higher HLC wins; tiebreak by lexicographic `update_id`
+ * - **replace** — the component's field is set whole; the first write to an absent row creates it
+ * - **drop** — the component's field is removed; the row survives
+ * - **delete** — soft delete (sets `deleted_hlc`); the row keeps its type
  *
  * A field value is either a leaf merged by the LWW rule above, or a
  * `{ map }` of nested field values merged key by key under the same
@@ -136,6 +137,9 @@ interface MembershipLink {
  * - `get(id)` — returns entity by ID, materializes if dirty
  * - `set(entity)` — directly sets an entity (bypasses materialization)
  * - `query(type)` — returns all materialized entities of a type
+ * - `queryByComponent(component)` — returns the live ids carrying that
+ *   `<model>/<field>` component in ascending order, materializing dirty rows
+ *   of the component's model first
  * - `queryByRelationship({ as, type, targetId })` — returns the distinct
  *   source ids indexed under that triple in ascending order,
  *   materializing dirty relationship rows first
@@ -154,6 +158,18 @@ interface EntityStore {
     get(id: string): Promise<Entity | null>;
     set(entity: Entity): Promise<void>;
     query(type: string): Promise<readonly Entity[]>;
+    /**
+     * Live rows currently carrying `component` (`<model>/<field>`), ascending by
+     * id. Existence is the set of present fields on a row, so this is an index
+     * read rather than a row filter; a tombstoned row's components are not
+     * existence.
+     *
+     * The dirty rows materialized first are the component prefix's model. That is
+     * the current `<model>/<field>` addressing rule (#797); a component namespace
+     * that is not the row's model (#805's `ebb/*` components on ordinary rows)
+     * has to decode the model differently and revisit this step.
+     */
+    queryByComponent(component: string): Promise<readonly string[]>;
     queryByRelationship(query: RelationshipIndexQuery): Promise<readonly string[]>;
     queryByRelationshipSource(query: RelationshipSourceQuery): Promise<readonly RelationshipLink[]>;
     queryByMembership(groupId: string): Promise<readonly string[]>;
@@ -229,44 +245,51 @@ interface CursorStore {
  * `conflicted` is a terminal-until-resolved hold: a catch-up pass
  * classified the Action as a loser, so it is structurally excluded from
  * `pending()` and never submitted. The application resolves it by
- * retrying (back to `pending`) or discarding (removed).
+ * sending the Action unchanged (back to `pending`) or clearing it
+ * (removed).
  */
 type OutboxStatus = "pending" | "acknowledged" | "error" | "conflicted";
 /**
  * One side of a contested slot: the buffered local write, or the value
  * the server holds once the catch-up window is applied. A leaf carries
- * its LWW triple; a whole-field map replacement has no single leaf, so
+ * its LWW triple; a whole-component map replacement has no single leaf, so
  * `update_id` / `hlc` are absent and `value` is the projected map. A
- * field an inbound `put` or `delete` reverted also has no triple, and
+ * component an inbound `merge` or `delete` reverted also has no triple, and
  * `value` is `undefined` because the server holds no value.
  */
 interface ConflictSide {
     /** Projected leaf or map value. `undefined` when the server holds nothing. */
     readonly value: unknown;
-    /** `update_id` of the FieldValue; absent for a map side or a reverted field. */
+    /** `update_id` of the FieldValue; absent for a map side or a reverted component. */
     readonly update_id?: string;
-    /** HLC carried by the FieldValue; absent for a map side or a reverted field. */
+    /** HLC carried by the FieldValue; absent for a map side or a reverted component. */
     readonly hlc?: string;
 }
 /**
- * One contested position on a losing Action: a field plus the map-key
- * path from the field root to the position. `path` is empty for a plain
- * leaf field, an entity-level touch that overlaps no position, or a
- * field an inbound `put` / `delete` reverted. Concurrent writes to
+ * One contested position on a losing Action: a component plus the map-key
+ * path from the component's value root to the position. `path` is empty for a
+ * plain leaf component, an entity-level touch that overlaps no position, or a
+ * component an inbound `merge` / `delete` reverted. Concurrent writes to
  * different keys are different slots and so are not conflicts.
  */
 interface ConflictSlot {
     /** The `subject_id` of the Update that carried the write. */
     readonly subjectId: string;
-    /** The field name on that subject. */
-    readonly field: string;
-    /** Ordered map keys from the field root to the position; empty at the root. */
+    /** The `<model>/<field>` component name on that subject. */
+    readonly component: string;
+    /** Ordered map keys from the component root to the position; empty at the root. */
     readonly path: readonly string[];
     /** The buffered local value at the position. */
     readonly local: ConflictSide;
     /** The value the server holds at the position after the missed window. */
     readonly remote: ConflictSide;
 }
+/** One missed Action that out-dated a buffered write and made it a conflict. */
+interface ConflictRemoteAction {
+    readonly actorId: string;
+    readonly actionId: string;
+    readonly gsn: number;
+}
 /**
  * The before/after entity rows for one losing subject. `before` is the
  * row as the client had it immediately before the catch-up window was
@@ -278,7 +301,8 @@ interface ConflictSlot {
  */
 interface ConflictSubjectState {
     readonly subjectId: string;
-    readonly subjectType: string;
+    /** The model the row is committed under. */
+    readonly model: string;
     readonly before: Entity | null;
     readonly after: Entity | null;
 }
@@ -305,6 +329,18 @@ interface OutboxConflict {
      * application reads that as "nothing of mine would be lost".
      */
     readonly slots: readonly ConflictSlot[];
+    /**
+     * The looser of the losing subjects' declared scopes: `"entity"` when
+     * any losing subject declared entity scope, else `"field"`. The union is
+     * spelled inline so storage stays independent of the schema package.
+     */
+    readonly scope: "field" | "component" | "entity";
+    /**
+     * The concurrent missed Actions that touched the losing subjects,
+     * deduped by action id, in window order. The remote half of the
+     * report an application builds a policy from.
+     */
+    readonly remoteActions: readonly ConflictRemoteAction[];
     /** The catch-up pass that produced this entry. */
     readonly catchUpId: string;
     /**
@@ -353,10 +389,9 @@ interface OutboxEntry {
 interface OutboxStore {
     put(entry: OutboxEntry): Promise<void>;
     /**
-     * Persist `entry` and delete `deleteId` in one durable operation. Used
-     * to resolve a conflict by retrying: the fresh re-assert must never
-     * exist without the conflicted row being gone, nor the row be gone
-     * without the re-assert persisted.
+     * Persist `entry` and delete `deleteId` in one durable operation: the
+     * replacement must never exist without the replaced row being gone,
+     * nor the row be gone without the replacement persisted.
      */
     putAndDelete(entry: OutboxEntry, deleteId: string): Promise<void>;
     list(): Promise<readonly OutboxEntry[]>;