zeitlich 0.2.45 → 0.2.46

package/src/lib/thread/test-utils.ts

@@ -0,0 +1,228 @@
+/**
+ * In-memory fakes used by the thread-storage unit tests.
+ *
+ * Lives outside `*.test.ts` so multiple test files can share the
+ * same fake without copy/pasting. Not exported from the package — kept
+ * inside `src/lib/thread` so type imports work and the test runner
+ * picks it up directly.
+ */
+
+import type Redis from "ioredis";
+import type { ColdThreadStore, ThreadSnapshot } from "./cold-store";
+
+type Value = string | string[];
+
+/**
+ * Minimal in-memory Redis stub covering the commands the thread
+ * manager + snapshot helpers use: get/set/del/exists/expire,
+ * lrange/rpush/llen/ltrim, and the `eval`-based idempotent-append Lua
+ * script. Behaviour matches Redis closely enough for unit tests; TTLs
+ * are stored but never expire automatically.
+ */
+export function createFakeRedis(): Redis & {
+  _store: Map<string, Value>;
+  _ttls: Map<string, number>;
+} {
+  const store = new Map<string, Value>();
+  const ttls = new Map<string, number>();
+
+  const isList = (k: string): boolean => Array.isArray(store.get(k));
+  const ensureList = (k: string): string[] => {
+    const v = store.get(k);
+    if (v === undefined) {
+      const fresh: string[] = [];
+      store.set(k, fresh);
+      return fresh;
+    }
+    if (!Array.isArray(v)) throw new Error(`WRONGTYPE: ${k} is not a list`);
+    return v;
+  };
+
+  const fake = {
+    async get(key: string): Promise<string | null> {
+      const v = store.get(key);
+      if (v === undefined) return null;
+      if (Array.isArray(v)) throw new Error(`WRONGTYPE: ${key} is a list`);
+      return v;
+    },
+    async set(
+      key: string,
+      value: string,
+      ..._rest: (string | number)[]
+    ): Promise<"OK"> {
+      // NX guard: when the args contain "NX" and the key already exists,
+      // Redis returns null. We follow the same contract for tests that
+      // need it; existing call sites use this for compare-and-set.
+      const rest = _rest.map((x) => (typeof x === "string" ? x.toUpperCase() : x));
+      if (rest.includes("NX") && store.has(key)) {
+        return null as unknown as "OK";
+      }
+      store.set(key, String(value));
+      const exIdx = rest.indexOf("EX");
+      if (exIdx >= 0 && typeof _rest[exIdx + 1] === "number") {
+        ttls.set(key, _rest[exIdx + 1] as number);
+      }
+      return "OK";
+    },
+    async del(...keys: string[]): Promise<number> {
+      let removed = 0;
+      for (const k of keys) {
+        if (store.delete(k)) removed++;
+        ttls.delete(k);
+      }
+      return removed;
+    },
+    async exists(...keys: string[]): Promise<number> {
+      return keys.reduce((acc, k) => acc + (store.has(k) ? 1 : 0), 0);
+    },
+    async expire(key: string, ttl: number): Promise<number> {
+      if (!store.has(key)) return 0;
+      ttls.set(key, ttl);
+      return 1;
+    },
+    async lrange(key: string, start: number, end: number): Promise<string[]> {
+      if (!store.has(key)) return [];
+      if (!isList(key)) return [];
+      const list = store.get(key) as string[];
+      const last = end === -1 ? list.length - 1 : end;
+      return list.slice(start, last + 1);
+    },
+    async rpush(key: string, ...values: string[]): Promise<number> {
+      const list = ensureList(key);
+      list.push(...values);
+      return list.length;
+    },
+    async llen(key: string): Promise<number> {
+      if (!store.has(key)) return 0;
+      const list = store.get(key) as string[];
+      return list.length;
+    },
+    async ltrim(key: string, start: number, end: number): Promise<"OK"> {
+      if (!store.has(key)) return "OK";
+      const list = store.get(key) as string[];
+      const last = end === -1 ? list.length - 1 : end;
+      store.set(key, list.slice(start, last + 1));
+      return "OK";
+    },
+    async eval(
+      _script: string,
+      numKeys: number,
+      ...args: (string | number)[]
+    ): Promise<number> {
+      // Mirrors APPEND_IDEMPOTENT_SCRIPT in src/lib/thread/manager.ts.
+      const keys = args.slice(0, numKeys) as string[];
+      const argv = args.slice(numKeys) as string[];
+      const dedupKey = keys[0];
+      const listKey = keys[1];
+      const ttl = Number(argv[0]);
+      const messages = argv.slice(1);
+      if (dedupKey === undefined || listKey === undefined) {
+        throw new Error("eval stub: missing keys");
+      }
+      if (store.has(dedupKey)) return 0;
+      const list = ensureList(listKey);
+      list.push(...messages);
+      ttls.set(listKey, ttl);
+      store.set(dedupKey, "1");
+      ttls.set(dedupKey, ttl);
+      return 1;
+    },
+    // Chainable pipeline stub. Defers each command to the underlying
+    // sync fake methods on `.exec()`, so TTL tracking and store
+    // semantics stay identical to the non-pipelined path. `fake` is
+    // typed as `Redis` after the cast below, so we narrow it back to
+    // the concrete impl shape here to avoid Redis's callback overloads.
+    pipeline(): FakePipeline {
+      const impl = fake as unknown as {
+        set: (key: string, value: string, ...rest: (string | number)[]) => Promise<"OK">;
+        del: (...keys: string[]) => Promise<number>;
+        rpush: (key: string, ...values: string[]) => Promise<number>;
+        expire: (key: string, ttl: number) => Promise<number>;
+      };
+      const ops: Array<() => Promise<unknown>> = [];
+      const chain: FakePipeline = {
+        set: (...args) => {
+          const [key, value, ...rest] = args as [string, string, ...(string | number)[]];
+          ops.push(() => impl.set(key, value, ...rest));
+          return chain;
+        },
+        del: (...keys) => {
+          ops.push(() => impl.del(...keys));
+          return chain;
+        },
+        rpush: (key, ...values) => {
+          ops.push(() => impl.rpush(key, ...values));
+          return chain;
+        },
+        expire: (key, ttl) => {
+          ops.push(() => impl.expire(key, ttl));
+          return chain;
+        },
+        exec: async () => {
+          const results: Array<[Error | null, unknown]> = [];
+          for (const op of ops) {
+            try {
+              results.push([null, await op()]);
+            } catch (e) {
+              results.push([e as Error, null]);
+            }
+          }
+          return results;
+        },
+      };
+      return chain;
+    },
+    _store: store,
+    _ttls: ttls,
+  } as unknown as Redis & {
+    _store: Map<string, Value>;
+    _ttls: Map<string, number>;
+  };
+
+  return fake;
+}
+
+/** Minimal chainable surface used by the fake-redis pipeline stub. */
+interface FakePipeline {
+  set: (...args: (string | number)[]) => FakePipeline;
+  del: (...keys: string[]) => FakePipeline;
+  rpush: (key: string, ...values: string[]) => FakePipeline;
+  expire: (key: string, ttl: number) => FakePipeline;
+  exec: () => Promise<Array<[Error | null, unknown]>>;
+}
+
+/**
+ * In-memory `ColdThreadStore` used by the tiered manager tests. Spies
+ * on read/write/delete call counts so tests can assert idempotency
+ * and call sequencing.
+ */
+export function createMemoryColdStore(): ColdThreadStore & {
+  _snapshots: Map<string, ThreadSnapshot>;
+  _calls: { read: number; write: number; delete: number };
+} {
+  const snapshots = new Map<string, ThreadSnapshot>();
+  const calls = { read: 0, write: 0, delete: 0 };
+  const compositeKey = (threadKey: string, threadId: string): string =>
+    `${threadKey}::${threadId}`;
+  return {
+    async read(threadKey: string, threadId: string) {
+      calls.read++;
+      return snapshots.get(compositeKey(threadKey, threadId)) ?? null;
+    },
+    async write(threadKey: string, threadId: string, snapshot: ThreadSnapshot) {
+      calls.write++;
+      // Clone to mirror real-world serialization (S3 round-trips
+      // through JSON).
+      snapshots.set(
+        compositeKey(threadKey, threadId),
+        JSON.parse(JSON.stringify(snapshot)) as ThreadSnapshot
+      );
+    },
+    async delete(threadKey: string, threadId: string) {
+      calls.delete++;
+      snapshots.delete(compositeKey(threadKey, threadId));
+    },
+    _snapshots: snapshots,
+    _calls: calls,
+  };
+}

package/src/lib/thread/tiered.test.ts

@@ -0,0 +1,281 @@
+import { describe, expect, it, beforeEach } from "vitest";
+import type Redis from "ioredis";
+import { createTieredThreadManager } from "./tiered";
+import { createThreadManager } from "./manager";
+import {
+  getThreadDedupKey,
+  getThreadListKey,
+  getThreadMetaKey,
+  getThreadStateKey,
+} from "./keys";
+import type { PersistedThreadState } from "../state/types";
+import { createFakeRedis, createMemoryColdStore } from "./test-utils";
+
+interface TestMsg {
+  id: string;
+  text: string;
+}
+
+const sampleState: PersistedThreadState = {
+  tasks: [
+    [
+      "t1",
+      {
+        id: "t1",
+        subject: "do thing",
+        description: "do it",
+        activeForm: "doing",
+        status: "pending",
+        metadata: {},
+        blockedBy: [],
+        blocks: [],
+      },
+    ],
+  ],
+  custom: { counter: 7 },
+};
+
+function makeTiered(
+  redis: Redis,
+  threadId: string,
+  coldStore?: ReturnType<typeof createMemoryColdStore>,
+  ttlSeconds?: number
+) {
+  return createTieredThreadManager<TestMsg>({
+    redis,
+    threadId,
+    idOf: (m) => m.id,
+    ...(coldStore && { coldStore }),
+    ...(ttlSeconds !== undefined && { ttlSeconds }),
+  });
+}
+
+describe("createTieredThreadManager — no cold store", () => {
+  it("hydrate is a no-op when no cold store is wired", async () => {
+    const redis = createFakeRedis();
+    const tm = makeTiered(redis, "t-1");
+    await tm.hydrate();
+    expect(await redis.exists(getThreadMetaKey("messages", "t-1"))).toBe(0);
+  });
+
+  it("flush is a no-op when no cold store is wired", async () => {
+    const redis = createFakeRedis();
+    const tm = makeTiered(redis, "t-1");
+    await tm.initialize();
+    await tm.append([{ id: "m1", text: "hello" }]);
+    await tm.flush();
+    expect(await tm.load()).toEqual([{ id: "m1", text: "hello" }]);
+  });
+
+  it("delegates all BaseThreadManager ops to the underlying Redis manager", async () => {
+    const redis = createFakeRedis();
+    const tm = makeTiered(redis, "t-1");
+    await tm.initialize();
+    await tm.append([
+      { id: "m1", text: "a" },
+      { id: "m2", text: "b" },
+    ]);
+    await tm.saveState(sampleState);
+
+    expect(await tm.length()).toBe(2);
+    expect(await tm.loadState()).toEqual(sampleState);
+    expect(await tm.load()).toEqual([
+      { id: "m1", text: "a" },
+      { id: "m2", text: "b" },
+    ]);
+
+    await tm.truncateFromId("m2");
+    expect(await tm.load()).toEqual([{ id: "m1", text: "a" }]);
+  });
+});
+
+describe("createTieredThreadManager — with cold store", () => {
+  let redis: Redis;
+  let cold: ReturnType<typeof createMemoryColdStore>;
+
+  beforeEach(() => {
+    redis = createFakeRedis();
+    cold = createMemoryColdStore();
+  });
+
+  it("flush writes messages + state + dedupIds to the cold store", async () => {
+    const tm = makeTiered(redis, "t-1", cold);
+    await tm.initialize();
+    await tm.append([{ id: "m1", text: "hello" }]);
+    await tm.append([{ id: "m2", text: "world" }]);
+    await tm.saveState(sampleState);
+
+    await tm.flush({ deleteHot: false });
+
+    const snap = cold._snapshots.get("messages::t-1");
+    expect(snap).toBeDefined();
+    if (!snap) throw new Error("expected snapshot");
+    expect(snap.v).toBe(1);
+    expect(snap.messages.map((raw) => JSON.parse(raw) as TestMsg)).toEqual([
+      { id: "m1", text: "hello" },
+      { id: "m2", text: "world" },
+    ]);
+    expect(snap.state).toEqual(sampleState);
+    expect(snap.dedupIds).toEqual(["m1", "m2"]);
+  });
+
+  it("flush is a no-op when the thread is cold (no hot tier present)", async () => {
+    const tm = makeTiered(redis, "t-1", cold);
+    await tm.flush();
+    expect(cold._calls.write).toBe(0);
+    expect(cold._snapshots.size).toBe(0);
+  });
+
+  it("defaults to deleting the hot tier after a successful flush", async () => {
+    const tm = makeTiered(redis, "t-1", cold);
+    await tm.initialize();
+    await tm.append([{ id: "m1", text: "hello" }]);
+    await tm.saveState(sampleState);
+
+    await tm.flush();
+
+    expect(await redis.exists(getThreadListKey("messages", "t-1"))).toBe(0);
+    expect(await redis.exists(getThreadMetaKey("messages", "t-1"))).toBe(0);
+    expect(await redis.exists(getThreadStateKey("messages", "t-1"))).toBe(0);
+    expect(await redis.exists(getThreadDedupKey("t-1", "m1"))).toBe(0);
+  });
+
+  it("flush({ deleteHot: false }) leaves the hot tier intact", async () => {
+    const tm = makeTiered(redis, "t-1", cold);
+    await tm.initialize();
+    await tm.append([{ id: "m1", text: "hello" }]);
+
+    await tm.flush({ deleteHot: false });
+
+    expect(await tm.load()).toEqual([{ id: "m1", text: "hello" }]);
+  });
+
+  it("hydrate restores messages + state + dedup markers from the cold store", async () => {
+    // Seed the cold store via a separate manager instance.
+    const seed = makeTiered(redis, "t-1", cold);
+    await seed.initialize();
+    await seed.append([
+      { id: "m1", text: "a" },
+      { id: "m2", text: "b" },
+    ]);
+    await seed.saveState(sampleState);
+    await seed.flush(); // archives + drops hot tier
+
+    expect(await redis.exists(getThreadMetaKey("messages", "t-1"))).toBe(0);
+
+    // Restore into a fresh manager on the same Redis.
+    const restored = makeTiered(redis, "t-1", cold);
+    await restored.hydrate();
+
+    expect(await restored.load()).toEqual([
+      { id: "m1", text: "a" },
+      { id: "m2", text: "b" },
+    ]);
+    expect(await restored.loadState()).toEqual(sampleState);
+
+    // Re-append m1 — should be skipped because dedup keys were re-primed.
+    await restored.append([{ id: "m1", text: "a" }]);
+    expect(await restored.length()).toBe(2);
+  });
+
+  it("hydrate is idempotent — no-op when the thread is already hot", async () => {
+    const tm = makeTiered(redis, "t-1", cold);
+    await tm.initialize();
+    await tm.append([{ id: "existing", text: "in redis" }]);
+
+    // Pre-seed the cold store with different content.
+    await cold.write("messages", "t-1", {
+      v: 1,
+      messages: [JSON.stringify({ id: "from-cold", text: "different" })],
+      state: sampleState,
+      dedupIds: ["from-cold"],
+    });
+
+    await tm.hydrate();
+
+    expect(await tm.load()).toEqual([{ id: "existing", text: "in redis" }]);
+  });
+
+  it("hydrate is a no-op when nothing is archived in the cold store", async () => {
+    const tm = makeTiered(redis, "t-1", cold);
+    await tm.hydrate();
+    expect(await redis.exists(getThreadMetaKey("messages", "t-1"))).toBe(0);
+    expect(cold._calls.read).toBe(1);
+  });
+
+  it("flush → hydrate is a full round-trip for an empty thread", async () => {
+    const tm = makeTiered(redis, "t-1", cold);
+    await tm.initialize();
+    await tm.flush();
+
+    const restored = makeTiered(redis, "t-1", cold);
+    await restored.hydrate();
+    expect(await restored.load()).toEqual([]);
+    expect(await restored.length()).toBe(0);
+  });
+
+  it("repeated flushes converge (idempotent cold writes)", async () => {
+    const tm = makeTiered(redis, "t-1", cold);
+    await tm.initialize();
+    await tm.append([{ id: "m1", text: "hello" }]);
+    await tm.flush({ deleteHot: false });
+    await tm.flush({ deleteHot: false });
+    expect(cold._calls.write).toBe(2);
+    const snap = cold._snapshots.get("messages::t-1");
+    if (!snap) throw new Error("expected snapshot");
+    expect(snap.messages).toHaveLength(1);
+  });
+
+  it("repeated hydrates converge (only the first one writes Redis)", async () => {
+    await cold.write("messages", "t-1", {
+      v: 1,
+      messages: [JSON.stringify({ id: "m1", text: "hello" })],
+      state: null,
+      dedupIds: ["m1"],
+    });
+    const tm = makeTiered(redis, "t-1", cold);
+    await tm.hydrate();
+    await tm.hydrate();
+    expect(await tm.load()).toEqual([{ id: "m1", text: "hello" }]);
+  });
+
+  it("fork from a hydrated source preserves messages in the new thread", async () => {
+    // Archive a source thread into cold storage and drop its hot tier.
+    const seed = makeTiered(redis, "src", cold);
+    await seed.initialize();
+    await seed.append([{ id: "m1", text: "a" }]);
+    await seed.append([{ id: "m2", text: "b" }]);
+    await seed.flush();
+
+    // Hydrate source (mirrors what session.ts does for mode:"fork")
+    // then fork into a new thread on the same Redis.
+    const src = makeTiered(redis, "src", cold);
+    await src.hydrate();
+    await src.fork("forked");
+
+    const target = createThreadManager<TestMsg>({
+      redis,
+      threadId: "forked",
+      idOf: (m) => m.id,
+    });
+    expect(await target.load()).toEqual([
+      { id: "m1", text: "a" },
+      { id: "m2", text: "b" },
+    ]);
+  });
+
+  it("honors a custom ttlSeconds when restoring", async () => {
+    await cold.write("messages", "t-1", {
+      v: 1,
+      messages: [JSON.stringify({ id: "m1", text: "hi" })],
+      state: null,
+      dedupIds: ["m1"],
+    });
+    const tm = makeTiered(redis, "t-1", cold, 60);
+    await tm.hydrate();
+    const ttls = (redis as unknown as { _ttls: Map<string, number> })._ttls;
+    expect(ttls.get(getThreadMetaKey("messages", "t-1"))).toBe(60);
+    expect(ttls.get(getThreadListKey("messages", "t-1"))).toBe(60);
+    expect(ttls.get(getThreadDedupKey("t-1", "m1"))).toBe(60);
+  });
+});

package/src/lib/thread/tiered.ts

@@ -0,0 +1,135 @@
+/**
+ * Tiered thread manager: Redis hot tier + pluggable cold tier.
+ *
+ * Wraps {@link createThreadManager} (Redis-only) and adds two
+ * session-boundary operations:
+ *
+ * - `hydrate()` — when the thread is cold (no meta key in Redis),
+ *   restore the latest {@link ThreadSnapshot} from the cold store.
+ *   Idempotent; no-op when the thread is already hot or when no
+ *   snapshot exists.
+ * - `flush({ deleteHot })` — write the current Redis state out to the
+ *   cold store as one snapshot, then (by default) `DEL` the hot-tier
+ *   keys so idle threads don't sit in Redis memory.
+ *
+ * All other operations (`append`, `load`, `fork`, `replaceAll`,
+ * `truncateFromId`, state I/O) delegate unchanged to the underlying
+ * Redis manager, so adapters and tests that use the
+ * `BaseThreadManager<T>` interface keep working with zero changes.
+ */
+
+import { createThreadManager } from "./manager";
+import { THREAD_TTL_SECONDS } from "./keys";
+import type { BaseThreadManager, ThreadManagerConfig } from "./types";
+import type { ColdThreadStore } from "./cold-store";
+import {
+  applySnapshot,
+  clearHotTier,
+  encodeSnapshot,
+} from "./snapshot";
+
+/** Configuration for {@link createTieredThreadManager}. */
+export interface TieredThreadManagerConfig<T> extends ThreadManagerConfig<T> {
+  /**
+   * Cold-tier archive. When omitted, `hydrate()` and `flush()` are
+   * no-ops and the manager behaves identically to
+   * {@link createThreadManager}.
+   */
+  coldStore?: ColdThreadStore;
+}
+
+/** Options for {@link TieredThreadManager.flush}. */
+export interface FlushOptions {
+  /**
+   * Delete the hot-tier Redis keys after a successful cold-tier
+   * write. Defaults to `true` when a cold store is configured —
+   * Redis is just a cache and a future continue/fork will
+   * re-hydrate in a single round-trip.
+   *
+   * Set to `false` to keep the hot tier warm (useful for tests or
+   * for "hot-after-flush" use cases where another session is expected
+   * to pick the thread up immediately).
+   */
+  deleteHot?: boolean;
+}
+
+/**
+ * Extension of {@link BaseThreadManager} with the two cold-tier
+ * lifecycle methods.
+ */
+export interface TieredThreadManager<T> extends BaseThreadManager<T> {
+  /**
+   * Restore the latest cold-tier snapshot into Redis when the thread
+   * is cold. Idempotent — safe to call from a retried activity.
+   */
+  hydrate(): Promise<void>;
+  /**
+   * Write the current Redis state to the cold tier and (optionally)
+   * drop the hot-tier keys. Idempotent — last-writer-wins on the
+   * cold side.
+   */
+  flush(opts?: FlushOptions): Promise<void>;
+}
+
+/**
+ * Build a thread manager backed by Redis (hot) and an optional
+ * pluggable cold store. See module docstring for the lifecycle
+ * semantics.
+ */
+export function createTieredThreadManager<T>(
+  config: TieredThreadManagerConfig<T>
+): TieredThreadManager<T> {
+  const {
+    redis,
+    threadId,
+    key = "messages",
+    coldStore,
+    idOf,
+    deserialize = (raw: string): T => JSON.parse(raw) as T,
+    ttlSeconds = THREAD_TTL_SECONDS,
+  } = config;
+
+  const base = createThreadManager<T>(config);
+
+  // Snapshot-time `idOf` operates on raw Redis strings — we deserialize
+  // here and forward to the configured (deserialized) `idOf`.
+  const rawIdOf = idOf
+    ? (raw: string): string => idOf(deserialize(raw))
+    : undefined;
+
+  return Object.assign(base, {
+    async hydrate(): Promise<void> {
+      if (!coldStore) return;
+      const snapshot = await coldStore.read(key, threadId);
+      if (!snapshot) return;
+      await applySnapshot({
+        redis,
+        threadKey: key,
+        threadId,
+        snapshot,
+        ttlSeconds,
+      });
+    },
+
+    async flush(opts?: FlushOptions): Promise<void> {
+      if (!coldStore) return;
+      const snapshot = await encodeSnapshot({
+        redis,
+        threadKey: key,
+        threadId,
+        ...(rawIdOf ? { idOf: rawIdOf } : {}),
+      });
+      if (!snapshot) return;
+      await coldStore.write(key, threadId, snapshot);
+      const deleteHot = opts?.deleteHot ?? true;
+      if (deleteHot) {
+        await clearHotTier({
+          redis,
+          threadKey: key,
+          threadId,
+          dedupIds: snapshot.dedupIds,
+        });
+      }
+    },
+  });
+}

package/src/lib/thread/types.ts

@@ -14,6 +14,17 @@ export interface ThreadManagerConfig<T> {
    * When provided, `append` uses an atomic Lua script to skip duplicate writes.
    */
   idOf?: (message: T) => string;
+  /**
+   * TTL (in seconds) applied to every Redis key the manager writes
+   * (the list, the meta marker, the state slice, and dedup markers).
+   *
+   * Defaults to {@link THREAD_TTL_SECONDS} (90 days) for back-compat.
+   * When the consumer pairs the thread manager with a durable cold
+   * tier (see `createTieredThreadManager`), a much shorter TTL — e.g.
+   * a few hours — is usually more appropriate since the cold tier is
+   * the source of truth and Redis is just a hot cache.
+   */
+  ttlSeconds?: number;
 }
 
 /** Generic thread manager for any message type */
@@ -26,6 +37,11 @@ export interface BaseThreadManager<T> {
    * Append messages to the thread.
    * When `idOf` is configured, appends are idempotent — retries with the
    * same message ids are atomically skipped via a Redis Lua script.
+   *
+   * Caveat with tiered storage: multi-message batches write one composite
+   * dedup key (`"m1:m2"`); snapshots only persist per-message keys, so a
+   * batch retried after `flush` → `hydrate` will not be deduped. Adapter
+   * helpers all single-append and are unaffected.
    */
   append(messages: T[]): Promise<void>;
   /**