@sovereignbase/convergent-replicated-struct 0.0.0

package/dist/index.cjs

@@ -0,0 +1,409 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } var _class;/*
+ * Copyright 2026 Sovereignbase
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+
+// src/OOStruct/class.ts
+var _uuid = require('uuid');
+
+// src/.errors/class.ts
+var OOStructError = class extends Error {
+  /**
+   * The semantic error code for the failure.
+   */
+  
+  /**
+   * Creates a typed OO-Struct error.
+   *
+   * @param code - The semantic error code.
+   * @param message - An optional human-readable detail message.
+   */
+  constructor(code, message) {
+    const detail = _nullishCoalesce(message, () => ( code));
+    super(`{@sovereignbase/observed-overwrite-struct} ${detail}`);
+    this.code = code;
+    this.name = "OOStructError";
+  }
+};
+
+// src/OOStruct/parseSnapshotEntryToStateEntry/index.ts
+var _utils = require('@sovereignbase/utils');
+function parseSnapshotEntryToStateEntry(defaultValue, snapshotEntry) {
+  if (_utils.prototype.call(void 0, snapshotEntry) !== "record" || !Object.hasOwn(snapshotEntry, "__value") || !_utils.isUuidV7.call(void 0, snapshotEntry.__uuidv7) || !_utils.isUuidV7.call(void 0, snapshotEntry.__after) || !Array.isArray(snapshotEntry.__overwrites))
+    return false;
+  const [cloned, copiedValue] = _utils.safeStructuredClone.call(void 0, snapshotEntry.__value);
+  if (!cloned || _utils.prototype.call(void 0, copiedValue) !== _utils.prototype.call(void 0, defaultValue))
+    return false;
+  const overwrites = /* @__PURE__ */ new Set([]);
+  for (const overwrite of snapshotEntry.__overwrites) {
+    if (!_utils.isUuidV7.call(void 0, overwrite) || overwrite === snapshotEntry.__uuidv7)
+      continue;
+    overwrites.add(overwrite);
+  }
+  if (!overwrites.has(snapshotEntry.__after)) return false;
+  return {
+    __uuidv7: snapshotEntry.__uuidv7,
+    __value: copiedValue,
+    __after: snapshotEntry.__after,
+    __overwrites: overwrites
+  };
+}
+
+// src/OOStruct/parseStateEntryToSnapshotEntry/index.ts
+function parseStateEntryToSnapshotEntry(stateEntry) {
+  return {
+    __uuidv7: stateEntry.__uuidv7,
+    __value: structuredClone(stateEntry.__value),
+    __after: stateEntry.__after,
+    __overwrites: Array.from(stateEntry.__overwrites)
+  };
+}
+
+// src/OOStruct/class.ts
+
+var OOStruct = (_class = class _OOStruct {
+  __init() {this.__eventTarget = new EventTarget()}
+  
+  
+  
+  /**
+   * Creates a replica from default values and an optional snapshot.
+   *
+   * @param defaults - The default field values that define the struct shape.
+   * @param snapshot - An optional serialized snapshot used for hydration.
+   * @throws {OOStructError} Thrown when the default values are not supported by `structuredClone`.
+   */
+  constructor(defaults, snapshot) {;_class.prototype.__init.call(this);
+    const [cloned, copiedDefaults] = _utils.safeStructuredClone.call(void 0, defaults);
+    if (!cloned)
+      throw new OOStructError(
+        "DEFAULTS_NOT_CLONEABLE",
+        "Default values must be supported by structuredClone."
+      );
+    this.__defaults = copiedDefaults;
+    this.__state = {};
+    this.__live = {};
+    const snapshotIsObject = snapshot && _utils.prototype.call(void 0, snapshot) === "record";
+    for (const key of Object.keys(this.__defaults)) {
+      const defaultValue = this.__defaults[key];
+      if (snapshotIsObject && Object.hasOwn(snapshot, key)) {
+        const valid = parseSnapshotEntryToStateEntry(
+          defaultValue,
+          snapshot[key]
+        );
+        if (valid) {
+          this.__live[key] = valid.__value;
+          this.__state[key] = valid;
+          continue;
+        }
+      }
+      this.__live[key] = defaultValue;
+      const root = _uuid.v7.call(void 0, );
+      this.__state[key] = {
+        __uuidv7: _uuid.v7.call(void 0, ),
+        __after: root,
+        __value: defaultValue,
+        __overwrites: /* @__PURE__ */ new Set([root])
+      };
+    }
+  }
+  /**CRUD*/
+  /**
+   * Creates a new replica.
+   *
+   * @param defaults - The default field values that define the struct shape.
+   * @param snapshot - An optional serialized snapshot used for hydration.
+   * @returns A new OO-Struct replica.
+   */
+  static create(defaults, snapshot) {
+    return new _OOStruct(defaults, snapshot);
+  }
+  /**
+   * Reads the current value of a field.
+   *
+   * @param key - The field key to read.
+   * @returns A cloned copy of the field's current value.
+   */
+  read(key) {
+    return structuredClone(this.__live[key]);
+  }
+  /**
+   * Overwrites a field with a new value.
+   *
+   * @param key - The field key to overwrite.
+   * @param value - The next value for the field.
+   * @throws {OOStructError} Thrown when the value is not supported by `structuredClone`.
+   * @throws {OOStructError} Thrown when the value runtime type does not match the default value runtime type.
+   */
+  update(key, value) {
+    const [cloned, copiedValue] = _utils.safeStructuredClone.call(void 0, value);
+    if (!cloned)
+      throw new OOStructError(
+        "VALUE_NOT_CLONEABLE",
+        "Updated values must be supported by structuredClone."
+      );
+    if (_utils.prototype.call(void 0, copiedValue) !== _utils.prototype.call(void 0, this.__defaults[key]))
+      throw new OOStructError(
+        "VALUE_TYPE_MISMATCH",
+        "Updated value must match the default value runtime type."
+      );
+    const delta = {};
+    const change = {};
+    delta[key] = this.overwriteAndReturnSnapshotEntry(key, copiedValue);
+    change[key] = structuredClone(copiedValue);
+    this.__eventTarget.dispatchEvent(
+      new CustomEvent("delta", { detail: delta })
+    );
+    this.__eventTarget.dispatchEvent(
+      new CustomEvent("change", { detail: change })
+    );
+  }
+  /**
+   * Resets one field or the entire struct back to default values.
+   *
+   * @param key - The optional field key to reset. When omitted, every field is reset.
+   */
+  delete(key) {
+    const delta = {};
+    const change = {};
+    if (key !== void 0) {
+      if (!Object.hasOwn(this.__defaults, key)) return;
+      const value = this.__defaults[key];
+      delta[key] = this.overwriteAndReturnSnapshotEntry(key, value);
+      change[key] = structuredClone(value);
+    } else {
+      for (const [key2, value] of Object.entries(this.__defaults)) {
+        delta[key2] = this.overwriteAndReturnSnapshotEntry(
+          key2,
+          value
+        );
+        change[key2] = structuredClone(value);
+      }
+    }
+    this.__eventTarget.dispatchEvent(
+      new CustomEvent("delta", { detail: delta })
+    );
+    this.__eventTarget.dispatchEvent(
+      new CustomEvent("change", { detail: change })
+    );
+  }
+  /**MAGS*/
+  /**
+   * Merges an incoming delta into the current replica.
+   *
+   * @param replica - The incoming partial snapshot projection to merge.
+   */
+  merge(replica) {
+    if (!replica || typeof replica !== "object" || Array.isArray(replica))
+      return;
+    const delta = {};
+    const change = {};
+    let hasDelta = false;
+    let hasChange = false;
+    for (const [key, value] of Object.entries(replica)) {
+      if (!Object.hasOwn(this.__state, key)) continue;
+      const candidate = parseSnapshotEntryToStateEntry(
+        this.__defaults[key],
+        value
+      );
+      if (!candidate) continue;
+      const target = this.__state[key];
+      const current = { ...target };
+      let frontier = "";
+      for (const overwrite of target.__overwrites) {
+        if (frontier < overwrite) frontier = overwrite;
+      }
+      for (const overwrite of candidate.__overwrites) {
+        if (overwrite <= frontier || target.__overwrites.has(overwrite))
+          continue;
+        target.__overwrites.add(overwrite);
+      }
+      if (target.__overwrites.has(candidate.__uuidv7)) continue;
+      if (current.__uuidv7 === candidate.__uuidv7) {
+        if (current.__after < candidate.__after) {
+          target.__value = candidate.__value;
+          target.__after = candidate.__after;
+          target.__overwrites.add(candidate.__after);
+          this.__live[key] = candidate.__value;
+          change[key] = structuredClone(candidate.__value);
+          hasChange = true;
+        } else {
+          delta[key] = this.overwriteAndReturnSnapshotEntry(
+            key,
+            current.__value
+          );
+          hasDelta = true;
+        }
+        continue;
+      }
+      if (current.__uuidv7 === candidate.__after || target.__overwrites.has(current.__uuidv7) || candidate.__uuidv7 > current.__uuidv7) {
+        target.__uuidv7 = candidate.__uuidv7;
+        target.__value = candidate.__value;
+        target.__after = candidate.__after;
+        target.__overwrites.add(candidate.__after);
+        target.__overwrites.add(current.__uuidv7);
+        this.__live[key] = candidate.__value;
+        change[key] = structuredClone(candidate.__value);
+        hasChange = true;
+        continue;
+      }
+      target.__overwrites.add(candidate.__uuidv7);
+      delta[key] = parseStateEntryToSnapshotEntry(target);
+      hasDelta = true;
+    }
+    if (hasDelta)
+      this.__eventTarget.dispatchEvent(
+        new CustomEvent("delta", { detail: delta })
+      );
+    if (hasChange)
+      this.__eventTarget.dispatchEvent(
+        new CustomEvent("change", { detail: change })
+      );
+  }
+  /**
+   * Emits the current acknowledgement frontier for each field.
+   */
+  acknowledge() {
+    const ack = {};
+    for (const [key, value] of Object.entries(this.__state)) {
+      let max = "";
+      for (const overwrite of value.__overwrites) {
+        if (max < overwrite) max = overwrite;
+      }
+      ack[key] = max;
+    }
+    this.__eventTarget.dispatchEvent(new CustomEvent("ack", { detail: ack }));
+  }
+  /**
+   * Removes overwritten identifiers that every provided frontier has acknowledged.
+   *
+   * @param frontiers - A collection of acknowledgement frontiers to compact against.
+   */
+  garbageCollect(frontiers) {
+    if (!Array.isArray(frontiers) || frontiers.length < 1) return;
+    const smallestAcknowledgementsPerKey = {};
+    for (const frontier of frontiers) {
+      for (const [key, value] of Object.entries(frontier)) {
+        if (!Object.hasOwn(this.__state, key) || !_utils.isUuidV7.call(void 0, value)) continue;
+        const current = smallestAcknowledgementsPerKey[key];
+        if (typeof current === "string" && current <= value) continue;
+        smallestAcknowledgementsPerKey[key] = value;
+      }
+    }
+    for (const [key, value] of Object.entries(smallestAcknowledgementsPerKey)) {
+      const target = this.__state[key];
+      const smallest = value;
+      for (const uuidv72 of target.__overwrites) {
+        if (uuidv72 === target.__after || uuidv72 > smallest) continue;
+        target.__overwrites.delete(uuidv72);
+      }
+    }
+  }
+  /**
+   * Emits a serialized snapshot of the current replica state.
+   */
+  snapshot() {
+    const snapshot = {};
+    for (const [key, value] of Object.entries(this.__state)) {
+      snapshot[key] = parseStateEntryToSnapshotEntry(
+        value
+      );
+    }
+    this.__eventTarget.dispatchEvent(
+      new CustomEvent("snapshot", { detail: snapshot })
+    );
+  }
+  /**ADDITIONAL*/
+  /**
+   * Returns the struct field keys.
+   *
+   * @returns The field keys in the current replica.
+   */
+  keys() {
+    return Object.keys(this.__live);
+  }
+  /**
+   * Returns cloned copies of the current field values.
+   *
+   * @returns The current field values.
+   */
+  values() {
+    return Object.values(this.__live).map(
+      (value) => structuredClone(value)
+    );
+  }
+  /**
+   * Returns cloned key-value pairs for the current replica state.
+   *
+   * @returns The current field entries.
+   */
+  entries() {
+    return Object.entries(this.__live).map(([key, value]) => [
+      key,
+      structuredClone(value)
+    ]);
+  }
+  /**EVENTS*/
+  /**
+   * Registers an event listener.
+   *
+   * @param type - The event type to listen for.
+   * @param listener - The listener to register.
+   * @param options - Listener registration options.
+   */
+  addEventListener(type, listener, options) {
+    this.__eventTarget.addEventListener(
+      type,
+      listener,
+      options
+    );
+  }
+  /**
+   * Removes an event listener.
+   *
+   * @param type - The event type to stop listening for.
+   * @param listener - The listener to remove.
+   * @param options - Listener removal options.
+   */
+  removeEventListener(type, listener, options) {
+    this.__eventTarget.removeEventListener(
+      type,
+      listener,
+      options
+    );
+  }
+  /**HELPERS*/
+  /**
+   * Overwrites a field and returns the serialized delta entry for that overwrite.
+   *
+   * @param key - The field key to overwrite.
+   * @param value - The next value for the field.
+   * @returns The serialized snapshot entry for the new winning value.
+   */
+  overwriteAndReturnSnapshotEntry(key, value) {
+    const target = this.__state[key];
+    const old = { ...target };
+    target.__uuidv7 = _uuid.v7.call(void 0, );
+    target.__value = value;
+    target.__after = old.__uuidv7;
+    target.__overwrites.add(old.__uuidv7);
+    this.__live[key] = value;
+    return parseStateEntryToSnapshotEntry(target);
+  }
+}, _class);
+
+
+exports.OOStruct = OOStruct;
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["c:\\Users\\jorts\\convergent-replicated-struct\\dist\\index.cjs"],"names":[],"mappings":"AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,4BAAmC;AACnC;AACA;AACA,IAAI,cAAc,EAAE,MAAM,QAAQ,MAAM;AACxC;AACA;AACA;AACA,EAAE;AACF;AACA;AACA;AACA;AACA;AACA;AACA,EAAE,WAAW,CAAC,IAAI,EAAE,OAAO,EAAE;AAC7B,IAAI,MAAM,OAAO,mBAAE,OAAQ,UAAG,MAAI;AAClC,IAAI,KAAK,CAAC,CAAC,2CAA2C,EAAE,MAAM,CAAC,CAAA;AACA,IAAA;AACA,IAAA;AACA,EAAA;AACA;AACA;AACA;AACA;AACA;AACA,EAAA;AACA,IAAA;AACA,EAAA;AACA,EAAA;AACA,IAAA;AACA,EAAA;AACA,EAAA;AACA,IAAA;AACA,MAAA;AACA,IAAA;AACA,EAAA;AACA,EAAA;AACA,EAAA;AACA,IAAA;AACA,IAAA;AACA,IAAA;AACA,IAAA;AACA,EAAA;AACA;AACA;AACA;AACA;AACA,EAAA;AACA,IAAA;AACA,IAAA;AACA,IAAA;AACA,IAAA;AACA,EAAA;AACA;AACA;AACA;AACA;AACA;AACA,iBAAA;AACA,EAAA;AACA,EAAA;AACA,EAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,EAAA;AACA,IAAA;AACA,IAAA;AACA,MAAA;AACA,QAAA;AACA,QAAA;AACA,MAAA;AACA,IAAA;AACA,IAAA;AACA,IAAA;AACA,IAAA;AACA,IAAA;AACA,MAAA;AACA,MAAA;AACA,QAAA;AACA,UAAA;AACA,UAAA;AACA,QAAA;AACA,QAAA;AACA,UAAA;AACA,UAAA;AACA,UAAA;AACA,QAAA;AACA,MAAA;AACA,MAAA;AACA,MAAA;AACA,MAAA;AACA,QAAA;AACA,QAAA;AACA,QAAA;AACA,QAAA;AACA,MAAA;AACA,IAAA;AACA,EAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,EAAA;AACA,IAAA;AACA,EAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,EAAA;AACA,IAAA;AACA,EAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,EAAA;AACA,IAAA;AACA,IAAA;AACA,MAAA;AACA,QAAA;AACA,QAAA;AACA,MAAA;AACA,IAAA;AACA,MAAA;AACA,QAAA;AACA,QAAA;AACA,MAAA;AACA,IAAA;AACA,IAAA;AACA,IAAA;AACA,IAAA;AACA,IAAA;AACA,MAAA;AACA,IAAA;AACA,IAAA;AACA,MAAA;AACA,IAAA;AACA,EAAA;AACA;AACA;AACA;AACA;AACA;AACA,EAAA;AACA,IAAA;AACA,IAAA;AACA,IAAA;AACA,MAAA;AACA,MAAA;AACA,MAAA;AACA,MAAA;AACA,IAAA;AACA,MAAA;AACA,QAAA;AACA,UAAA;AACA,UAAA;AACA,QAAA;AACA,QAAA;AACA,MAAA;AACA,IAAA;AACA,IAAA;AACA,MAAA;AACA,IAAA;AACA,IAAA;AACA,MAAA;AACA,IAAA;AACA,EAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,EAAA;AACA,IAAA;AACA,MAAA;AACA,IAAA;AACA,IAAA;AACA,IAAA;AACA,IAAA;AACA,IAAA;AACA,MAAA;AACA,MAAA;AACA,QAAA;AACA,QAAA;AACA,MAAA;AACA,MAAA;AACA,MAAA;AACA,MAAA;AACA,MAAA;AACA,MAAA;AACA,QAAA;AACA,MAAA;AACA,MAAA;AACA,QAAA;AACA,UAAA;AACA,QAAA;AACA,MAAA;AACA,MAAA;AACA,MAAA;AACA,QAAA;AACA,UAAA;AACA,UAAA;AACA,UAAA;AACA,UAAA;AACA,UAAA;AACA,UAAA;AACA,QAAA;AACA,UAAA;AACA,YAAA;AACA,YAAA;AACA,UAAA;AACA,UAAA;AACA,QAAA;AACA,QAAA;AACA,MAAA;AACA,MAAA;AACA,QAAA;AACA,QAAA;AACA,QAAA;AACA,QAAA;AACA,QAAA;AACA,QAAA;AACA,QAAA;AACA,QAAA;AACA,QAAA;AACA,MAAA;AACA,MAAA;AACA,MAAA;AACA,MAAA;AACA,IAAA;AACA,IAAA;AACA,MAAA;AACA,QAAA;AACA,MAAA;AACA,IAAA;AACA,MAAA;AACA,QAAA;AACA,MAAA;AACA,EAAA;AACA;AACA;AACA;AACA,EAAA;AACA,IAAA;AACA,IAAA;AACA,MAAA;AACA,MAAA;AACA,QAAA;AACA,MAAA;AACA,MAAA;AACA,IAAA;AACA,IAAA;AACA,EAAA;AACA;AACA;AACA;AACA;AACA;AACA,EAAA;AACA,IAAA;AACA,IAAA;AACA,IAAA;AACA,MAAA;AACA,QAAA;AACA,QAAA;AACA,QAAA;AACA,QAAA;AACA,MAAA;AACA,IAAA;AACA,IAAA;AACA,MAAA;AACA,MAAA;AACA,MAAA;AACA,QAAA;AACA,QAAA;AACA,MAAA;AACA,IAAA;AACA,EAAA;AACA;AACA;AACA;AACA,EAAA;AACA,IAAA;AACA,IAAA;AACA,MAAA;AACA,QAAA;AACA,MAAA;AACA,IAAA;AACA,IAAA;AACA,MAAA;AACA,IAAA;AACA,EAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,EAAA;AACA,IAAA;AACA,EAAA;AACA;AACA;AACA;AACA;AACA;AACA,EAAA;AACA,IAAA;AACA,MAAA;AACA,IAAA;AACA,EAAA;AACA;AACA;AACA;AACA;AACA;AACA,EAAA;AACA,IAAA;AACA,MAAA;AACA,MAAA;AACA,IAAA;AACA,EAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,EAAA;AACA,IAAA;AACA,MAAA;AACA,MAAA;AACA,MAAA;AACA,IAAA;AACA,EAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,EAAA;AACA,IAAA;AACA,MAAA;AACA,MAAA;AACA,MAAA;AACA,IAAA;AACA,EAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,EAAA;AACA,IAAA;AACA,IAAA;AACA,IAAA;AACA,IAAA;AACA,IAAA;AACA,IAAA;AACA,IAAA;AACA,IAAA;AACA,EAAA;AACA;AACA;AACA;AACA","file":"C:\\Users\\jorts\\convergent-replicated-struct\\dist\\index.cjs","sourcesContent":[null]}

package/dist/index.d.cts

@@ -0,0 +1,226 @@
+/**Replica State*/
+/**
+ * Represents the internal replicated state for a single field.
+ */
+type OOStructStateEntry<V> = {
+    /**
+     * The identifier of the current winning value.
+     */
+    __uuidv7: string;
+    /**
+     * The current winning value.
+     */
+    __value: V;
+    /**
+     * The predecessor identifier for the current winning value.
+     */
+    __after: string;
+    /**
+     * Identifiers known to have been overwritten for the field.
+     */
+    __overwrites: Set<string>;
+};
+/**
+ * Represents the internal replicated state of an OO-Struct replica.
+ */
+type OOStructState<T extends Record<string, unknown>> = {
+    [K in keyof T]: OOStructStateEntry<T[K]>;
+};
+/**Serlialized projection of replica state*/
+/**
+ * Represents the serialized state for a single field.
+ */
+type OOStructSnapshotEntry<V> = {
+    /**
+     * The identifier of the current winning value.
+     */
+    __uuidv7: string;
+    /**
+     * The serialized current winning value.
+     */
+    __value: V;
+    /**
+     * The predecessor identifier for the current winning value.
+     */
+    __after: string;
+    /**
+     * Serialized overwritten identifiers for the field.
+     */
+    __overwrites: Array<string>;
+};
+/**
+ * Represents a serialized snapshot of the full replica state.
+ */
+type OOStructSnapshot<T extends Record<string, unknown>> = {
+    [K in keyof T]: OOStructSnapshotEntry<T[K]>;
+};
+/**Resolved projection of replica state*/
+/**
+ * Represents visible field values that changed during a local operation or merge.
+ */
+type OOStructChange<T extends Record<string, unknown>> = Partial<T>;
+/**(T)*/
+/**A "report" on what the replica has seen*/
+/**
+ * Represents the acknowledgement frontier for a set of field keys.
+ */
+type OOStructAcknowledgementFrontier<K extends string> = Record<K, string>;
+/**Partial changes to gossip*/
+/**
+ * Represents a partial serialized state projection exchanged between replicas.
+ */
+type OOStructDelta<T extends Record<string, unknown>> = Partial<OOStructSnapshot<T>>;
+/**
+ * Represents the current acknowledgement frontier emitted by a replica.
+ */
+type OOStructAck<T extends Record<string, unknown>> = Partial<OOStructAcknowledgementFrontier<Extract<keyof T, string>>>;
+/***/
+/**
+ * Maps OO-Struct event names to their event payload shapes.
+ */
+type OOStructEventMap<T extends Record<string, unknown>> = {
+    /** STATE / PROJECTION */
+    snapshot: OOStructSnapshot<T>;
+    change: OOStructChange<T>;
+    /** GOSSIP / PROTOCOL */
+    delta: OOStructDelta<T>;
+    ack: OOStructAck<T>;
+};
+/**
+ * Represents a strongly typed OO-Struct event listener.
+ */
+type OOStructEventListener<T extends Record<string, unknown>, K extends keyof OOStructEventMap<T>> = ((event: CustomEvent<OOStructEventMap<T>[K]>) => void) | {
+    handleEvent(event: CustomEvent<OOStructEventMap<T>[K]>): void;
+};
+/**
+ * Resolves an event name to its corresponding listener type.
+ */
+type OOStructEventListenerFor<T extends Record<string, unknown>, K extends string> = K extends keyof OOStructEventMap<T> ? OOStructEventListener<T, K> : EventListenerOrEventListenerObject;
+
+/**
+ * Represents an observed-overwrite struct replica.
+ *
+ * The struct shape is fixed by the provided default values.
+ */
+declare class OOStruct<T extends Record<string, unknown>> {
+    private readonly __eventTarget;
+    private readonly __defaults;
+    private readonly __state;
+    private __live;
+    /**
+     * Creates a replica from default values and an optional snapshot.
+     *
+     * @param defaults - The default field values that define the struct shape.
+     * @param snapshot - An optional serialized snapshot used for hydration.
+     * @throws {OOStructError} Thrown when the default values are not supported by `structuredClone`.
+     */
+    constructor(defaults: {
+        [K in keyof T]: T[K];
+    }, snapshot?: OOStructSnapshot<T>);
+    /**CRUD*/
+    /**
+     * Creates a new replica.
+     *
+     * @param defaults - The default field values that define the struct shape.
+     * @param snapshot - An optional serialized snapshot used for hydration.
+     * @returns A new OO-Struct replica.
+     */
+    static create<T extends Record<string, unknown>>(defaults: {
+        [K in keyof T]: T[K];
+    }, snapshot?: OOStructSnapshot<T>): OOStruct<T>;
+    /**
+     * Reads the current value of a field.
+     *
+     * @param key - The field key to read.
+     * @returns A cloned copy of the field's current value.
+     */
+    read<K extends keyof T>(key: K): T[K];
+    /**
+     * Overwrites a field with a new value.
+     *
+     * @param key - The field key to overwrite.
+     * @param value - The next value for the field.
+     * @throws {OOStructError} Thrown when the value is not supported by `structuredClone`.
+     * @throws {OOStructError} Thrown when the value runtime type does not match the default value runtime type.
+     */
+    update<K extends keyof T>(key: K, value: T[K]): void;
+    /**
+     * Resets one field or the entire struct back to default values.
+     *
+     * @param key - The optional field key to reset. When omitted, every field is reset.
+     */
+    delete<K extends keyof T>(key?: K): void;
+    /**MAGS*/
+    /**
+     * Merges an incoming delta into the current replica.
+     *
+     * @param replica - The incoming partial snapshot projection to merge.
+     */
+    merge<K extends keyof T>(replica: OOStructDelta<T>): void;
+    /**
+     * Emits the current acknowledgement frontier for each field.
+     */
+    acknowledge<K extends Extract<keyof T, string>>(): void;
+    /**
+     * Removes overwritten identifiers that every provided frontier has acknowledged.
+     *
+     * @param frontiers - A collection of acknowledgement frontiers to compact against.
+     */
+    garbageCollect<K extends Extract<keyof T, string>>(frontiers: Array<OOStructAck<T>>): void;
+    /**
+     * Emits a serialized snapshot of the current replica state.
+     */
+    snapshot(): void;
+    /**ADDITIONAL*/
+    /**
+     * Returns the struct field keys.
+     *
+     * @returns The field keys in the current replica.
+     */
+    keys<K extends keyof T>(): Array<K>;
+    /**
+     * Returns cloned copies of the current field values.
+     *
+     * @returns The current field values.
+     */
+    values<K extends keyof T>(): Array<T[K]>;
+    /**
+     * Returns cloned key-value pairs for the current replica state.
+     *
+     * @returns The current field entries.
+     */
+    entries<K extends keyof T>(): Array<[K, T[K]]>;
+    /**EVENTS*/
+    /**
+     * Registers an event listener.
+     *
+     * @param type - The event type to listen for.
+     * @param listener - The listener to register.
+     * @param options - Listener registration options.
+     */
+    addEventListener<K extends keyof OOStructEventMap<T>>(type: K, listener: OOStructEventListenerFor<T, K> | null, options?: boolean | AddEventListenerOptions): void;
+    /**
+     * Removes an event listener.
+     *
+     * @param type - The event type to stop listening for.
+     * @param listener - The listener to remove.
+     * @param options - Listener removal options.
+     */
+    removeEventListener<K extends keyof OOStructEventMap<T>>(type: K, listener: OOStructEventListenerFor<T, K> | null, options?: boolean | EventListenerOptions): void;
+    /**HELPERS*/
+    /**
+     * Overwrites a field and returns the serialized delta entry for that overwrite.
+     *
+     * @param key - The field key to overwrite.
+     * @param value - The next value for the field.
+     * @returns The serialized snapshot entry for the new winning value.
+     */
+    private overwriteAndReturnSnapshotEntry;
+}
+
+/**
+ * Error codes thrown by {@link OOStruct}.
+ */
+type OOStructErrorCode = 'DEFAULTS_NOT_CLONEABLE' | 'VALUE_NOT_CLONEABLE' | 'VALUE_TYPE_MISMATCH';
+
+export { OOStruct, type OOStructAck, type OOStructAcknowledgementFrontier, type OOStructChange, type OOStructDelta, type OOStructErrorCode, type OOStructEventListener, type OOStructEventListenerFor, type OOStructEventMap, type OOStructSnapshot, type OOStructSnapshotEntry, type OOStructState, type OOStructStateEntry };