@synnaxlabs/client 0.57.2 → 0.58.0

package/dist/testutil.js.map

@@ -1 +1 @@
-{"version":3,"file":"testutil.js","names":[],"sources":["../src/testutil/client.ts","../src/testutil/access.ts","../src/testutil/channels.ts","../src/testutil/connection.ts","../src/testutil/panels.ts","../src/testutil/proxy.ts","../src/testutil/query.ts","../src/testutil/telem.ts"],"sourcesContent":["// Copyright 2026 Synnax Labs, Inc.\n//\n// Use of this software is governed by the Business Source License included in the file\n// licenses/BSL.txt.\n//\n// As of the Change Date specified in that file, in accordance with the Business Source\n// License, use of this software will be governed by the Apache License, Version 2.0,\n// included in the file licenses/APL.txt.\n\nimport { TimeSpan } from \"@synnaxlabs/x\";\nimport { afterAll } from \"vitest\";\n\nimport Synnax, { type SynnaxParams } from \"@/client\";\n\nexport const TEST_CLIENT_PARAMS: SynnaxParams = {\n  host: \"localhost\",\n  port: 9090,\n  username: \"synnax\",\n  password: \"seldon\",\n  retry: {\n    maxRetries: 4,\n    baseInterval: TimeSpan.seconds(1),\n    scale: 1.5,\n  },\n};\n\n// A hook registered mid-test is silently dropped by vitest, so per-client afterAll\n// calls leak clients created inside test bodies. This module-level hook registers\n// during spec collection (import time) and covers every call site.\nconst openClients: Synnax[] = [];\n// Awaited so every close finishes before vitest tears down the worker; a close\n// still in flight at teardown races its logging against the closing RPC channel.\nafterAll(async () => {\n  const results = await Promise.allSettled(openClients.map((client) => client.close()));\n  const failures = results.filter((result) => result.status === \"rejected\");\n  if (failures.length > 0)\n    throw new AggregateError(\n      failures.map((failure) => failure.reason),\n      \"failed to close test clients\",\n    );\n});\n\n/**\n * Creates a client connected to the local test cluster. The client is closed\n * automatically once every test in the current spec file has finished, so callers do\n * not need to close it themselves.\n */\nexport const createTestClient = (params?: Partial<SynnaxParams>): Synnax => {\n  const client = new Synnax({ ...TEST_CLIENT_PARAMS, ...params });\n  openClients.push(client);\n  return client;\n};\n","// Copyright 2026 Synnax Labs, Inc.\n//\n// Use of this software is governed by the Business Source License included in the file\n// licenses/BSL.txt.\n//\n// As of the Change Date specified in that file, in accordance with the Business Source\n// License, use of this software will be governed by the Apache License, Version 2.0,\n// included in the file licenses/APL.txt.\n\nimport { array, errors, id } from \"@synnaxlabs/x\";\n\nimport { policy } from \"@/access/policy\";\nimport { role } from \"@/access/role\";\nimport type Synnax from \"@/client\";\nimport { AccessDeniedError, NotFoundError } from \"@/errors\";\nimport { createTestClient } from \"@/testutil/client\";\nimport { user } from \"@/user\";\n\n/** Reports whether the error, or any error in its cause chain, is an access denial. */\nconst isDenial = (err: unknown): boolean =>\n  AccessDeniedError.matches(err) ||\n  (err instanceof Error && err.cause != null && isDenial(err.cause));\n\n/**\n * Connects as a new user and primes its policy cache. Denials are tolerated: the Core\n * refuses restricted subjects by design, and the change-stream refusal logs after\n * teardown, which vitest counts as an unhandled error.\n */\nconst connectAs = async (username: string, key: user.Key) => {\n  const client = createTestClient({\n    username,\n    password: \"test\",\n    onInternalError: (err) => {\n      if (!isDenial(err)) console.error(err);\n    },\n  });\n  try {\n    await client.access.policies.retrieveForSubject(user.ontologyID(key));\n  } catch (err) {\n    if (!isDenial(err)) throw errors.fromUnknown(err);\n  }\n  return client;\n};\n\nconst createUser = async (client: Synnax) => {\n  const username = id.create();\n  const u = await client.users.create({\n    username,\n    password: \"test\",\n    firstName: \"test\",\n    lastName: \"test\",\n  });\n  return { username, key: u.key };\n};\n\n/**\n * Creates a client authenticated as a new user holding a role that carries the\n * policies. Pass several to grant different actions on different objects, which one\n * policy cannot express.\n */\nexport const createTestClientWithPolicy = async (\n  client: Synnax,\n  pol: policy.New | policy.New[],\n) => {\n  const u = await createUser(client);\n  const policies = await Promise.all(\n    array.toArray(pol).map(async (p) => await client.access.policies.create(p)),\n  );\n  const r = await client.access.roles.create({\n    name: \"test\",\n    description: \"test\",\n  });\n  await client.ontology.addChildren(\n    role.ontologyID(r.key),\n    ...policies.map(({ key }) => policy.ontologyID(key)),\n  );\n  await client.access.roles.assign({ user: u.key, role: r.key });\n  return await connectAs(u.username, u.key);\n};\n\n/** The roles the Core provisions on startup. */\nexport const BUILT_IN_ROLES = [\n  \"Owner\",\n  \"Engineer\",\n  \"Host\",\n  \"Operator\",\n  \"Viewer\",\n] as const;\n\nexport type BuiltInRole = (typeof BUILT_IN_ROLES)[number];\n\n/**\n * Creates a client authenticated as a new user holding one of the Core's built-in\n * roles, for exercising a real role's permission set instead of a synthetic policy.\n * @param name - The built-in role to assign.\n * @throws {NotFoundError} if the Core provisions no role under the name.\n */\nexport const createTestClientWithRole = async (\n  client: Synnax,\n  name: BuiltInRole,\n): Promise<Synnax> => {\n  const roles = await client.access.roles.retrieve({});\n  const r = roles.find((r) => r.name === name);\n  if (r == null) throw new NotFoundError(`no built-in role named ${name}`);\n  const u = await createUser(client);\n  await client.access.roles.assign({ user: u.key, role: r.key });\n  return await connectAs(u.username, u.key);\n};\n\n/**\n * Caches one client per built-in role, so a spec covering many roles pays the user\n * creation cost once each. Construct one per spec file.\n */\nexport class RoleClients {\n  private readonly client: Synnax;\n  private readonly byRole = new Map<BuiltInRole, Promise<Synnax>>();\n\n  constructor(client: Synnax) {\n    this.client = client;\n  }\n\n  /** Returns a client authenticated as a user holding the role. */\n  async get(name: BuiltInRole): Promise<Synnax> {\n    const existing = this.byRole.get(name);\n    if (existing != null) return await existing;\n    const created = createTestClientWithRole(this.client, name);\n    this.byRole.set(name, created);\n    return await created;\n  }\n}\n","// Copyright 2026 Synnax Labs, Inc.\n//\n// Use of this software is governed by the Business Source License included in the file\n// licenses/BSL.txt.\n//\n// As of the Change Date specified in that file, in accordance with the Business Source\n// License, use of this software will be governed by the Apache License, Version 2.0,\n// included in the file licenses/APL.txt.\n\nimport { DataType, id } from \"@synnaxlabs/x\";\n\nimport { type channel } from \"@/channel\";\nimport type Synnax from \"@/client\";\n\nexport const newIndexedPair = async (\n  client: Synnax,\n): Promise<[channel.Channel, channel.Channel]> => {\n  const index = await client.channels.create({\n    leaseholder: 1,\n    name: id.create(),\n    dataType: DataType.TIMESTAMP,\n    isIndex: true,\n  });\n  const data = await client.channels.create({\n    leaseholder: 1,\n    name: id.create(),\n    dataType: DataType.FLOAT64,\n    index: index.key,\n  });\n  return [index, data];\n};\n\nexport const newIndexedBoolPair = async (\n  client: Synnax,\n): Promise<[channel.Channel, channel.Channel]> => {\n  const index = await client.channels.create({\n    leaseholder: 1,\n    name: id.create(),\n    dataType: DataType.TIMESTAMP,\n    isIndex: true,\n  });\n  const data = await client.channels.create({\n    leaseholder: 1,\n    name: id.create(),\n    dataType: DataType.BOOLEAN,\n    index: index.key,\n  });\n  return [index, data];\n};\n\nexport const newVirtualChannel = async (client: Synnax): Promise<channel.Channel> => {\n  const ch = await client.channels.create({\n    name: id.create(),\n    dataType: DataType.FLOAT64,\n    virtual: true,\n  });\n  return ch;\n};\n\nexport const newVirtualBoolChannel = async (\n  client: Synnax,\n): Promise<channel.Channel> => {\n  const ch = await client.channels.create({\n    name: id.create(),\n    dataType: DataType.BOOLEAN,\n    virtual: true,\n  });\n  return ch;\n};\n","// Copyright 2026 Synnax Labs, Inc.\n//\n// Use of this software is governed by the Business Source License included in the file\n// licenses/BSL.txt.\n//\n// As of the Change Date specified in that file, in accordance with the Business Source\n// License, use of this software will be governed by the Apache License, Version 2.0,\n// included in the file licenses/APL.txt.\n\nimport { TimeSpan } from \"@synnaxlabs/x\";\n\nimport { type connection } from \"@/connection\";\n\n/** Resolves once the handle's status satisfies the predicate. */\nexport const waitForStatus = async (\n  handle: connection.Handle,\n  predicate: (status: connection.Status) => boolean,\n  timeout: TimeSpan = TimeSpan.seconds(5),\n): Promise<connection.Status> => {\n  if (predicate(handle.status)) return handle.status;\n  return await new Promise<connection.Status>((resolve, reject) => {\n    const timer = setTimeout(() => {\n      detach();\n      reject(new Error(\"timed out waiting for connection status\"));\n    }, timeout.milliseconds);\n    const detach = handle.onChange((status) => {\n      if (!predicate(status)) return;\n      clearTimeout(timer);\n      detach();\n      resolve(status);\n    });\n  });\n};\n\n/**\n * Resolves once the handle's change stream is live, so every later cluster write\n * reaches the client's cache.\n */\nexport const waitForStreamLive = async (\n  handle: connection.Handle,\n  timeout?: TimeSpan,\n): Promise<connection.Status> =>\n  await waitForStatus(\n    handle,\n    ({ variant, details }) => variant === \"success\" && details.streamLive,\n    timeout,\n  );\n","// Copyright 2026 Synnax Labs, Inc.\n//\n// Use of this software is governed by the Business Source License included in the file\n// licenses/BSL.txt.\n//\n// As of the Change Date specified in that file, in accordance with the Business Source\n// License, use of this software will be governed by the Apache License, Version 2.0,\n// included in the file licenses/APL.txt.\n\nimport { id } from \"@synnaxlabs/x\";\n\nimport type Synnax from \"@/client\";\nimport { type ontology } from \"@/ontology\";\nimport { project } from \"@/project\";\n\n/**\n * Creates a throwaway project and returns its ontology ID. Panel creation requires a\n * parent, so tests that mint panels directly parent them here.\n */\nexport const createPanelParent = async (client: Synnax): Promise<ontology.ID> => {\n  const proj = await client.projects.create({\n    name: `project-${id.create()}`,\n    layout: {},\n  });\n  return project.ontologyID(proj.key);\n};\n","// Copyright 2026 Synnax Labs, Inc.\n//\n// Use of this software is governed by the Business Source License included in the file\n// licenses/BSL.txt.\n//\n// As of the Change Date specified in that file, in accordance with the Business Source\n// License, use of this software will be governed by the Apache License, Version 2.0,\n// included in the file licenses/APL.txt.\n\nimport { connect, createServer, type Socket } from \"node:net\";\n\nimport { type breaker, TimeSpan } from \"@synnaxlabs/x\";\n\nconst DEFAULT_TARGET = { host: \"localhost\", port: 9090 };\n\n/**\n * Retry policy for a client pointed at a severable proxy. A spec drives its own\n * retries, so the client's must finish well inside one assertion budget: the\n * default policy waits seconds per request and outlasts a single `expect.poll`\n * attempt, which reports as a timeout rather than the real answer.\n */\nexport const FAST_RETRY: breaker.Config = {\n  baseInterval: TimeSpan.milliseconds(10),\n  maxInterval: TimeSpan.milliseconds(50),\n  scale: 1.5,\n};\n\nexport interface SeverableProxyTarget {\n  host?: string;\n  port?: number;\n}\n\nexport interface SeverableProxy {\n  /** Port the proxy accepts connections on. Point the client here. */\n  port: number;\n  /** Drops every live connection and refuses new ones, as if the cluster died. */\n  sever: () => Promise<void>;\n  /** Accepts connections again on the same port. */\n  restore: () => Promise<void>;\n  /** Shuts the proxy down for good. */\n  close: () => Promise<void>;\n}\n\n/**\n * Creates a TCP proxy in front of the live test cluster so specs can simulate\n * cluster downtime without touching the cluster itself. Connect a client to\n * the returned port, then sever() and restore() the link.\n */\nexport const createSeverableProxy = async (\n  target: SeverableProxyTarget = {},\n): Promise<SeverableProxy> => {\n  const { host, port } = { ...DEFAULT_TARGET, ...target };\n  const sockets = new Set<Socket>();\n  let severed = false;\n  const server = createServer((downstream) => {\n    // A connection the kernel accepted before the sever is still delivered after it,\n    // and forwarding it would let a request through a severed link.\n    if (severed) {\n      downstream.destroy();\n      return;\n    }\n    const upstream = connect(port, host);\n    sockets.add(downstream).add(upstream);\n    const destroy = (): void => {\n      sockets.delete(downstream);\n      sockets.delete(upstream);\n      downstream.destroy();\n      upstream.destroy();\n    };\n    downstream.on(\"error\", destroy);\n    upstream.on(\"error\", destroy);\n    downstream.on(\"close\", destroy);\n    upstream.on(\"close\", destroy);\n    downstream.pipe(upstream);\n    upstream.pipe(downstream);\n  });\n  const listen = async (listenPort: number): Promise<void> =>\n    await new Promise((resolve, reject) => {\n      server.once(\"error\", reject);\n      server.listen(listenPort, () => {\n        server.removeListener(\"error\", reject);\n        resolve();\n      });\n    });\n  await listen(0);\n  const address = server.address();\n  if (address == null || typeof address === \"string\")\n    throw new Error(\"proxy failed to bind a port\");\n  const boundPort = address.port;\n  const sever = async (): Promise<void> => {\n    severed = true;\n    const closed = new Promise<void>((resolve) => server.close(() => resolve()));\n    sockets.forEach((socket) => socket.destroy());\n    sockets.clear();\n    await closed;\n  };\n  return {\n    port: boundPort,\n    sever,\n    restore: async () => {\n      severed = false;\n      await listen(boundPort);\n    },\n    close: sever,\n  };\n};\n","// Copyright 2026 Synnax Labs, Inc.\n//\n// Use of this software is governed by the Business Source License included in the file\n// licenses/BSL.txt.\n//\n// As of the Change Date specified in that file, in accordance with the Business Source\n// License, use of this software will be governed by the Apache License, Version 2.0,\n// included in the file licenses/APL.txt.\n\nimport { query } from \"@/query\";\n\nexport { isLive } from \"@/query/query\";\n\n/** Asserts the cached answer is live (present and not deleted) and returns it. */\nexport const expectLive = <D extends query.Data>(\n  value: query.Cached<D> | undefined,\n): D => {\n  if (!query.isLive<D>(value)) throw new Error(\"expected a live cached answer\");\n  return value;\n};\n\n/** Asserts the cached answer is a deletion and returns it. */\nexport const expectDeleted = <D extends query.Data>(\n  value: query.Cached<D> | undefined,\n): query.Deleted<D> => {\n  if (!query.Deleted.matches<D>(value)) throw new Error(\"expected a deleted answer\");\n  return value;\n};\n","// Copyright 2026 Synnax Labs, Inc.\n//\n// Use of this software is governed by the Business Source License included in the file\n// licenses/BSL.txt.\n//\n// As of the Change Date specified in that file, in accordance with the Business Source\n// License, use of this software will be governed by the Apache License, Version 2.0,\n// included in the file licenses/APL.txt.\n\nimport { DataType, type Series, TimeStamp } from \"@synnaxlabs/x\";\n\nimport { type framer } from \"@/framer\";\n\nexport const secondsLinspace = (start: number, n: number): TimeStamp[] =>\n  Array.from({ length: n }, (_, i) => start + i).map((n) => TimeStamp.seconds(n));\n\nconst isRaw = (dt: DataType): boolean => dt.isVariable || dt.equals(DataType.UINT8);\n\n/** Narrows every numeric series to float32, anchoring bigints on an offset. Mirrors\n * the transform the visualization layer injects for WebGL rendering. */\nexport const glTransform: framer.Transform = {\n  resolveDataType: (dt: DataType) => (isRaw(dt) ? dt : DataType.FLOAT32),\n  convert: (series: Series, offset) => {\n    if (isRaw(series.dataType)) return series;\n    if (offset == null && series.dataType.usesBigInt && series.length > 0)\n      offset = BigInt(series.data[0]);\n    return series.convert(DataType.FLOAT32, offset);\n  },\n};\n"],"mappings":"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"}
+{"version":3,"file":"testutil.js","names":[],"sources":["../src/testutil/client.ts","../src/testutil/access.ts","../src/testutil/channels.ts","../src/testutil/connection.ts","../src/testutil/panels.ts","../src/testutil/proxy.ts","../src/testutil/query.ts","../src/testutil/telem.ts"],"sourcesContent":["// Copyright 2026 Synnax Labs, Inc.\n//\n// Use of this software is governed by the Business Source License included in the file\n// licenses/BSL.txt.\n//\n// As of the Change Date specified in that file, in accordance with the Business Source\n// License, use of this software will be governed by the Apache License, Version 2.0,\n// included in the file licenses/APL.txt.\n\nimport { TimeSpan } from \"@synnaxlabs/x\";\nimport { afterAll, vi } from \"vitest\";\n\nimport Synnax, { type SynnaxParams } from \"@/client\";\n\nexport const TEST_CLIENT_PARAMS: SynnaxParams = {\n  host: \"localhost\",\n  port: 9090,\n  username: \"synnax\",\n  password: \"seldon\",\n  retry: {\n    maxRetries: 4,\n    baseInterval: TimeSpan.seconds(1),\n    scale: 1.5,\n  },\n};\n\n// A hook registered mid-test is silently dropped by vitest, so per-client afterAll\n// calls leak clients created inside test bodies. This module-level hook registers\n// during spec collection (import time) and covers every call site.\nconst openClients: Synnax[] = [];\n// Awaited so every close finishes before vitest tears down the worker; a close\n// still in flight at teardown races its logging against the closing RPC channel.\nafterAll(async () => {\n  const results = await Promise.allSettled(openClients.map((client) => client.close()));\n  const failures = results.filter((result) => result.status === \"rejected\");\n  if (failures.length > 0)\n    throw new AggregateError(\n      failures.map((failure) => failure.reason),\n      \"failed to close test clients\",\n    );\n});\n\n/**\n * Creates a client connected to the local test cluster. The client is closed\n * automatically once every test in the current spec file has finished, so callers do\n * not need to close it themselves.\n */\nexport const createTestClient = (params?: Partial<SynnaxParams>): Synnax => {\n  const client = new Synnax({ ...TEST_CLIENT_PARAMS, ...params });\n  openClients.push(client);\n  return client;\n};\n\n/** Spies on the client's unary send so specs can count requests on the wire. */\nexport const spyOnSend = (client: Synnax, field: \"transport\" = \"transport\") =>\n  vi.spyOn(client[field].unary, \"send\");\n","// Copyright 2026 Synnax Labs, Inc.\n//\n// Use of this software is governed by the Business Source License included in the file\n// licenses/BSL.txt.\n//\n// As of the Change Date specified in that file, in accordance with the Business Source\n// License, use of this software will be governed by the Apache License, Version 2.0,\n// included in the file licenses/APL.txt.\n\nimport { array, errors, id } from \"@synnaxlabs/x\";\n\nimport { policy } from \"@/access/policy\";\nimport { role } from \"@/access/role\";\nimport type Synnax from \"@/client\";\nimport { AccessDeniedError, NotFoundError } from \"@/errors\";\nimport { createTestClient } from \"@/testutil/client\";\nimport { user } from \"@/user\";\n\n/** Reports whether the error, or any error in its cause chain, is an access denial. */\nconst isDenial = (err: unknown): boolean =>\n  AccessDeniedError.matches(err) ||\n  (err instanceof Error && err.cause != null && isDenial(err.cause));\n\n/**\n * Connects as a new user and primes its policy cache. Denials are tolerated: the Core\n * refuses restricted subjects by design, and the change-stream refusal logs after\n * teardown, which vitest counts as an unhandled error.\n */\nconst connectAs = async (username: string, key: user.Key) => {\n  const client = createTestClient({\n    username,\n    password: \"test\",\n    onInternalError: (err) => {\n      if (!isDenial(err)) console.error(err);\n    },\n  });\n  try {\n    await client.access.policies.retrieveForSubject(user.ontologyID(key));\n  } catch (err) {\n    if (!isDenial(err)) throw errors.fromUnknown(err);\n  }\n  return client;\n};\n\nconst createUser = async (client: Synnax) => {\n  const username = id.create();\n  const u = await client.users.create({\n    username,\n    password: \"test\",\n    firstName: \"test\",\n    lastName: \"test\",\n  });\n  return { username, key: u.key };\n};\n\n/**\n * Creates a client authenticated as a new user holding a role that carries the\n * policies. Pass several to grant different actions on different objects, which one\n * policy cannot express.\n */\nexport const createTestClientWithPolicy = async (\n  client: Synnax,\n  pol: policy.New | policy.New[],\n) => {\n  const u = await createUser(client);\n  const policies = await Promise.all(\n    array.toArray(pol).map(async (p) => await client.access.policies.create(p)),\n  );\n  const r = await client.access.roles.create({\n    name: \"test\",\n    description: \"test\",\n  });\n  await client.ontology.addChildren(\n    role.ontologyID(r.key),\n    ...policies.map(({ key }) => policy.ontologyID(key)),\n  );\n  await client.access.roles.assign({ user: u.key, role: r.key });\n  return await connectAs(u.username, u.key);\n};\n\n/** The roles the Core provisions on startup. */\nexport const BUILT_IN_ROLES = [\n  \"Owner\",\n  \"Engineer\",\n  \"Host\",\n  \"Operator\",\n  \"Viewer\",\n] as const;\n\nexport type BuiltInRole = (typeof BUILT_IN_ROLES)[number];\n\n/**\n * Creates a client authenticated as a new user holding one of the Core's built-in\n * roles, for exercising a real role's permission set instead of a synthetic policy.\n * @param name - The built-in role to assign.\n * @throws {NotFoundError} if the Core provisions no role under the name.\n */\nexport const createTestClientWithRole = async (\n  client: Synnax,\n  name: BuiltInRole,\n): Promise<Synnax> => {\n  const roles = await client.access.roles.retrieve({});\n  const r = roles.find((r) => r.name === name);\n  if (r == null) throw new NotFoundError(`no built-in role named ${name}`);\n  const u = await createUser(client);\n  await client.access.roles.assign({ user: u.key, role: r.key });\n  return await connectAs(u.username, u.key);\n};\n\n/**\n * Caches one client per built-in role, so a spec covering many roles pays the user\n * creation cost once each. Construct one per spec file.\n */\nexport class RoleClients {\n  private readonly client: Synnax;\n  private readonly byRole = new Map<BuiltInRole, Promise<Synnax>>();\n\n  constructor(client: Synnax) {\n    this.client = client;\n  }\n\n  /** Returns a client authenticated as a user holding the role. */\n  async get(name: BuiltInRole): Promise<Synnax> {\n    const existing = this.byRole.get(name);\n    if (existing != null) return await existing;\n    const created = createTestClientWithRole(this.client, name);\n    this.byRole.set(name, created);\n    return await created;\n  }\n}\n","// Copyright 2026 Synnax Labs, Inc.\n//\n// Use of this software is governed by the Business Source License included in the file\n// licenses/BSL.txt.\n//\n// As of the Change Date specified in that file, in accordance with the Business Source\n// License, use of this software will be governed by the Apache License, Version 2.0,\n// included in the file licenses/APL.txt.\n\nimport { DataType, id } from \"@synnaxlabs/x\";\n\nimport { type channel } from \"@/channel\";\nimport type Synnax from \"@/client\";\n\nexport const newIndexedPair = async (\n  client: Synnax,\n): Promise<[channel.Channel, channel.Channel]> => {\n  const index = await client.channels.create({\n    leaseholder: 1,\n    name: id.create(),\n    dataType: DataType.TIMESTAMP,\n    isIndex: true,\n  });\n  const data = await client.channels.create({\n    leaseholder: 1,\n    name: id.create(),\n    dataType: DataType.FLOAT64,\n    index: index.key,\n  });\n  return [index, data];\n};\n\nexport const newIndexedBoolPair = async (\n  client: Synnax,\n): Promise<[channel.Channel, channel.Channel]> => {\n  const index = await client.channels.create({\n    leaseholder: 1,\n    name: id.create(),\n    dataType: DataType.TIMESTAMP,\n    isIndex: true,\n  });\n  const data = await client.channels.create({\n    leaseholder: 1,\n    name: id.create(),\n    dataType: DataType.BOOLEAN,\n    index: index.key,\n  });\n  return [index, data];\n};\n\nexport const newVirtualChannel = async (client: Synnax): Promise<channel.Channel> => {\n  const ch = await client.channels.create({\n    name: id.create(),\n    dataType: DataType.FLOAT64,\n    virtual: true,\n  });\n  return ch;\n};\n\nexport const newVirtualBoolChannel = async (\n  client: Synnax,\n): Promise<channel.Channel> => {\n  const ch = await client.channels.create({\n    name: id.create(),\n    dataType: DataType.BOOLEAN,\n    virtual: true,\n  });\n  return ch;\n};\n","// Copyright 2026 Synnax Labs, Inc.\n//\n// Use of this software is governed by the Business Source License included in the file\n// licenses/BSL.txt.\n//\n// As of the Change Date specified in that file, in accordance with the Business Source\n// License, use of this software will be governed by the Apache License, Version 2.0,\n// included in the file licenses/APL.txt.\n\nimport { TimeSpan } from \"@synnaxlabs/x\";\n\nimport { type connection } from \"@/connection\";\n\n/** Resolves once the handle's status satisfies the predicate. */\nexport const waitForStatus = async (\n  handle: connection.Handle,\n  predicate: (status: connection.Status) => boolean,\n  timeout: TimeSpan = TimeSpan.seconds(5),\n): Promise<connection.Status> => {\n  if (predicate(handle.status)) return handle.status;\n  return await new Promise<connection.Status>((resolve, reject) => {\n    const timer = setTimeout(() => {\n      detach();\n      reject(new Error(\"timed out waiting for connection status\"));\n    }, timeout.milliseconds);\n    const detach = handle.onChange((status) => {\n      if (!predicate(status)) return;\n      clearTimeout(timer);\n      detach();\n      resolve(status);\n    });\n  });\n};\n\n/**\n * Resolves once the handle's change stream is live, so every later cluster write\n * reaches the client's cache.\n */\nexport const waitForStreamLive = async (\n  handle: connection.Handle,\n  timeout?: TimeSpan,\n): Promise<connection.Status> =>\n  await waitForStatus(\n    handle,\n    ({ variant, details }) => variant === \"success\" && details.streamLive,\n    timeout,\n  );\n","// Copyright 2026 Synnax Labs, Inc.\n//\n// Use of this software is governed by the Business Source License included in the file\n// licenses/BSL.txt.\n//\n// As of the Change Date specified in that file, in accordance with the Business Source\n// License, use of this software will be governed by the Apache License, Version 2.0,\n// included in the file licenses/APL.txt.\n\nimport { id } from \"@synnaxlabs/x\";\n\nimport type Synnax from \"@/client\";\nimport { type ontology } from \"@/ontology\";\nimport { project } from \"@/project\";\n\n/**\n * Creates a throwaway project and returns its ontology ID. Panel creation requires a\n * parent, so tests that mint panels directly parent them here.\n */\nexport const createPanelParent = async (client: Synnax): Promise<ontology.ID> => {\n  const proj = await client.projects.create({\n    name: `project-${id.create()}`,\n    layout: {},\n  });\n  return project.ontologyID(proj.key);\n};\n","// Copyright 2026 Synnax Labs, Inc.\n//\n// Use of this software is governed by the Business Source License included in the file\n// licenses/BSL.txt.\n//\n// As of the Change Date specified in that file, in accordance with the Business Source\n// License, use of this software will be governed by the Apache License, Version 2.0,\n// included in the file licenses/APL.txt.\n\nimport { connect, createServer, type Socket } from \"node:net\";\n\nimport { type breaker, TimeSpan } from \"@synnaxlabs/x\";\n\nconst DEFAULT_TARGET = { host: \"localhost\", port: 9090 };\n\n/**\n * Retry policy for a client pointed at a severable proxy. A spec drives its own\n * retries, so the client's must finish well inside one assertion budget: the\n * default policy waits seconds per request and outlasts a single `expect.poll`\n * attempt, which reports as a timeout rather than the real answer.\n */\nexport const FAST_RETRY: breaker.Config = {\n  baseInterval: TimeSpan.milliseconds(10),\n  maxInterval: TimeSpan.milliseconds(50),\n  scale: 1.5,\n};\n\nexport interface SeverableProxyTarget {\n  host?: string;\n  port?: number;\n}\n\nexport interface SeverableProxy {\n  /** Port the proxy accepts connections on. Point the client here. */\n  port: number;\n  /** Drops every live connection and refuses new ones, as if the cluster died. */\n  sever: () => Promise<void>;\n  /**\n   * Silently kills every live WebSocket connection, modeling a half-open socket (NAT\n   * timeout, VPN drop, laptop sleep): the cluster side is destroyed while the client\n   * side is held open with its writes discarded, so no close or reset ever reaches the\n   * client. New connections still forward. Returns how many connections were\n   * blackholed.\n   */\n  blackholeStreams: () => number;\n  /** Accepts connections again on the same port. */\n  restore: () => Promise<void>;\n  /** Shuts the proxy down for good. */\n  close: () => Promise<void>;\n}\n\ninterface ProxiedPair {\n  downstream: Socket;\n  upstream: Socket;\n  /** Whether a WebSocket upgrade was observed on this connection. */\n  ws: boolean;\n}\n\n/**\n * Creates a TCP proxy in front of the live test cluster so specs can simulate\n * cluster downtime without touching the cluster itself. Connect a client to\n * the returned port, then sever() and restore() the link.\n */\nexport const createSeverableProxy = async (\n  target: SeverableProxyTarget = {},\n): Promise<SeverableProxy> => {\n  const { host, port } = { ...DEFAULT_TARGET, ...target };\n  const pairs = new Set<ProxiedPair>();\n  // Client-side sockets of blackholed connections: held open, silent, until the proxy\n  // is severed or closed.\n  const zombies = new Set<Socket>();\n  let severed = false;\n  const server = createServer((downstream) => {\n    // A connection the kernel accepted before the sever is still delivered after it,\n    // and forwarding it would let a request through a severed link.\n    if (severed) {\n      downstream.destroy();\n      return;\n    }\n    const upstream = connect(port, host);\n    const pair: ProxiedPair = { downstream, upstream, ws: false };\n    pairs.add(pair);\n    // The upgrade can arrive on any request of a pooled keep-alive connection, not just\n    // the first, so every chunk is sniffed until one is seen.\n    downstream.on(\"data\", (chunk: Buffer) => {\n      if (!pair.ws && /upgrade:\\s*websocket/i.test(chunk.toString(\"latin1\")))\n        pair.ws = true;\n    });\n    const destroy = (): void => {\n      pairs.delete(pair);\n      downstream.destroy();\n      upstream.destroy();\n    };\n    downstream.on(\"error\", destroy);\n    upstream.on(\"error\", destroy);\n    downstream.on(\"close\", destroy);\n    upstream.on(\"close\", destroy);\n    downstream.pipe(upstream);\n    upstream.pipe(downstream);\n  });\n  const listen = async (listenPort: number): Promise<void> =>\n    await new Promise((resolve, reject) => {\n      server.once(\"error\", reject);\n      server.listen(listenPort, () => {\n        server.removeListener(\"error\", reject);\n        resolve();\n      });\n    });\n  await listen(0);\n  const address = server.address();\n  if (address == null || typeof address === \"string\")\n    throw new Error(\"proxy failed to bind a port\");\n  const boundPort = address.port;\n  const sever = async (): Promise<void> => {\n    severed = true;\n    const closed = new Promise<void>((resolve) => server.close(() => resolve()));\n    pairs.forEach(({ downstream, upstream }) => {\n      downstream.destroy();\n      upstream.destroy();\n    });\n    pairs.clear();\n    zombies.forEach((socket) => socket.destroy());\n    zombies.clear();\n    await closed;\n  };\n  const blackholeStreams = (): number => {\n    let count = 0;\n    for (const pair of [...pairs]) {\n      if (!pair.ws) continue;\n      count += 1;\n      const { downstream, upstream } = pair;\n      downstream.unpipe(upstream);\n      upstream.unpipe(downstream);\n      for (const socket of [downstream, upstream]) {\n        socket.removeAllListeners(\"close\");\n        socket.removeAllListeners(\"error\");\n        socket.on(\"error\", () => {});\n      }\n      // Discard anything the client still writes so backpressure cannot close the\n      // socket on the proxy's behalf.\n      downstream.on(\"data\", () => {});\n      downstream.resume();\n      upstream.destroy();\n      pairs.delete(pair);\n      zombies.add(downstream);\n    }\n    return count;\n  };\n  return {\n    port: boundPort,\n    sever,\n    blackholeStreams,\n    restore: async () => {\n      severed = false;\n      await listen(boundPort);\n    },\n    close: sever,\n  };\n};\n","// Copyright 2026 Synnax Labs, Inc.\n//\n// Use of this software is governed by the Business Source License included in the file\n// licenses/BSL.txt.\n//\n// As of the Change Date specified in that file, in accordance with the Business Source\n// License, use of this software will be governed by the Apache License, Version 2.0,\n// included in the file licenses/APL.txt.\n\nimport { query } from \"@/query\";\n\nexport { isLive } from \"@/query/query\";\n\n/** Asserts the cached answer is live (present and not deleted) and returns it. */\nexport const expectLive = <D extends query.Data>(\n  value: query.Cached<D> | undefined,\n): D => {\n  if (!query.isLive<D>(value)) throw new Error(\"expected a live cached answer\");\n  return value;\n};\n\n/** Asserts the cached answer is a deletion and returns it. */\nexport const expectDeleted = <D extends query.Data>(\n  value: query.Cached<D> | undefined,\n): query.Deleted<D> => {\n  if (!query.Deleted.matches<D>(value)) throw new Error(\"expected a deleted answer\");\n  return value;\n};\n","// Copyright 2026 Synnax Labs, Inc.\n//\n// Use of this software is governed by the Business Source License included in the file\n// licenses/BSL.txt.\n//\n// As of the Change Date specified in that file, in accordance with the Business Source\n// License, use of this software will be governed by the Apache License, Version 2.0,\n// included in the file licenses/APL.txt.\n\nimport { DataType, type Series, TimeStamp } from \"@synnaxlabs/x\";\n\nimport { type framer } from \"@/framer\";\n\nexport const secondsLinspace = (start: number, n: number): TimeStamp[] =>\n  Array.from({ length: n }, (_, i) => start + i).map((n) => TimeStamp.seconds(n));\n\nconst isRaw = (dt: DataType): boolean => dt.isVariable || dt.equals(DataType.UINT8);\n\n/** Narrows every numeric series to float32, anchoring bigints on an offset. Mirrors\n * the transform the visualization layer injects for WebGL rendering. */\nexport const glTransform: framer.Transform = {\n  resolveDataType: (dt: DataType) => (isRaw(dt) ? dt : DataType.FLOAT32),\n  convert: (series: Series, offset) => {\n    if (isRaw(series.dataType)) return series;\n    if (offset == null && series.dataType.usesBigInt && series.length > 0)\n      offset = BigInt(series.data[0]);\n    return series.convert(DataType.FLOAT32, offset);\n  },\n};\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synnaxlabs/client",
-  "version": "0.57.2",
+  "version": "0.58.0",
   "description": "The Synnax Client Library",
   "keywords": [
     "synnax",
@@ -23,11 +23,11 @@
     "directory": "client/ts"
   },
   "dependencies": {
+    "@synnaxlabs/alamos": "^0.58.0",
+    "@synnaxlabs/freighter": "^0.58.0",
+    "@synnaxlabs/x": "^0.58.0",
     "immer": "^11.1.15",
-    "zod": "^4.4.3",
-    "@synnaxlabs/freighter": "^0.57.0",
-    "@synnaxlabs/x": "^0.57.1",
-    "@synnaxlabs/alamos": "^0.57.0"
+    "zod": "^4.5.4"
   },
   "peerDependencies": {
     "vitest": "^4.1.10"
@@ -38,16 +38,16 @@
     }
   },
   "devDependencies": {
-    "@vitest/coverage-v8": "^4.1.10",
-    "@types/node": "^26.1.2",
-    "eslint": "^10.8.0",
-    "typescript": "^7.0.2",
-    "vite": "^8.2.0",
-    "vitest": "^4.1.10",
     "@synnaxlabs/eslint-config": "^0.0.0",
     "@synnaxlabs/madge": "^0.0.0",
     "@synnaxlabs/tsconfig": "^0.0.0",
-    "@synnaxlabs/vite-plugin": "^0.0.0"
+    "@synnaxlabs/vite-plugin": "^0.0.0",
+    "@vitest/coverage-v8": "^4.1.10",
+    "@types/node": "^24.13.3",
+    "eslint": "^10.9.1",
+    "typescript": "^7.0.2",
+    "vite": "^8.2.0",
+    "vitest": "^4.1.10"
   },
   "type": "module",
   "files": [

package/src/access/policy/client.ts

@@ -132,8 +132,6 @@ export class Client extends query.Retriever<typeof retrieveMultiParamsZ, Key, Po
     return isMany ? res.policies : res.policies[0];
   }
 
-  async delete(key: Key, opts?: query.WriteOptions): Promise<void>;
-  async delete(keys: Key[], opts?: query.WriteOptions): Promise<void>;
   async delete(keys: Key | Key[], opts: query.WriteOptions = {}): Promise<void> {
     const keysArr = array.toArray(keys);
     const ids = ontologyID(keysArr);

package/src/arc/client.ts

@@ -120,24 +120,6 @@ const isTaskChild = (rel: ontology.Relationship, arcKey: Key): boolean =>
     to: { type: "task" },
   });
 
-const taskStatusZ = z.object({ details: z.object({ task: task.keyZ }) });
-
-// Task statuses may arrive under any status key; the referenced task lives in
-// the details, with the "task:<key>" status key as a fallback.
-const affectedTaskKeys = (
-  event: query.TableEvent<status.Key, status.Status>,
-): task.Key[] | null => {
-  const keys: task.Key[] = [];
-  if (event.variant === "set") {
-    const parsed = taskStatusZ.safeParse(event.value);
-    if (parsed.success) keys.push(parsed.data.details.task);
-  }
-  const [type, key] = event.key.split(":");
-  if (type === "task" && primitive.isNonZero(key) && !keys.includes(key))
-    keys.push(key);
-  return keys.length === 0 ? null : keys;
-};
-
 export interface ClientConfig {
   unary: UnaryClient;
   stream: StreamClient;
@@ -210,7 +192,7 @@ export class Client extends query.Retriever<
       compose: (record) => this.composeTask(record),
       equal: (a, b) => deep.equal(a.payload, b.payload),
       watch: [
-        query.deriveWatch(this.cfg.statusStore, (event) => affectedTaskKeys(event)),
+        query.deriveWatch(this.cfg.statusStore, (event) => task.affectedKeys(event)),
       ],
     });
     this.taskAnswers = cache.queries<Key, task.Task | null, task.Key, task.Task>({
@@ -473,7 +455,7 @@ export class Client extends query.Retriever<
     const cachedStatus = this.cfg.statusStore.get(task.statusKey(cached.key));
     const payload = cached.payload;
     if (cachedStatus == null) return this.cfg.tasks.sugar(payload);
-    const parsed = task.statusZ().safeParse(cachedStatus);
+    const parsed = task.defaultStatusZ.safeParse(cachedStatus);
     if (!parsed.success) return this.cfg.tasks.sugar(payload);
     return this.cfg.tasks.sugar({ ...payload, status: parsed.data });
   }

package/src/channel/client.ts

@@ -389,12 +389,14 @@ export class Client extends query.Retriever<
   private readonly cfg: ClientConfig;
   readonly writer: Writer;
   readonly store: query.Table<Key, Channel>;
+  private readonly byName: query.LookupIndex<Key, Channel>;
 
   constructor(cfg: ClientConfig) {
     const { writer, statuses, ranges, cache } = cfg;
     const statusStore = statuses.store;
     const aliasStore = ranges.aliases;
     const sugar = (payload: Payload): Channel => this.sugar(payload);
+    const byName = new query.LookupIndex<Key, Channel>((ch) => ch.name);
     const store = cache.createTable<Key, Channel>({
       name: "channels",
       equal: (a, b) => deep.equal(a.payload, b.payload),
@@ -406,6 +408,7 @@ export class Client extends query.Retriever<
         }),
         query.createDeleteListener(DELETE_CHANNEL_NAME, keyZ),
       ],
+      indexes: [byName],
     });
     const composed = cache.derive<Key, Channel, Channel>({
       name: "channel.composed",
@@ -461,6 +464,7 @@ export class Client extends query.Retriever<
     this.cfg = cfg;
     this.writer = writer;
     this.store = store;
+    this.byName = byName;
   }
 
   /**
@@ -541,6 +545,7 @@ export class Client extends query.Retriever<
 
   /**
    * Retrieves a channel from the database using the given key or name.
+   * @param params - The key or the name of the channel to retrieve.
    * @param options - Optional parameters to control the retrieval process.
    * @param options.dataTypes - Limits the query to only channels with the specified
    * data type.
@@ -571,8 +576,6 @@ export class Client extends query.Retriever<
    * @param options.notDataTypes - Limits the query to only channels without the
    * specified
    */
-  async retrieve(params: Key | string, options?: RetrieveOptions): Promise<Channel>;
-
   async retrieve(
     params: PrimitiveParams | Payload[],
     options?: RetrieveOptions,
@@ -640,7 +643,7 @@ export class Client extends query.Retriever<
     }
     const names = normalized;
     await this.writer.delete({ names });
-    const cached = this.store.get((ch) => names.includes(ch.name));
+    const cached = this.byName.get(names);
     if (cached.length > 0) this.store.delete(cached.map((ch) => ch.key));
   }
 
@@ -765,10 +768,11 @@ export class Client extends query.Retriever<
     const { key, rangeKey } = query;
     let ch = this.store.get(key);
     if (ch == null) {
-      const payloads = await this.execRetrieve([key]);
-      checkForMultipleOrNoResults("channel", key, payloads, true);
-      ch = this.sugar(stripComposed(payloads[0]));
-      this.store.set(key, ch);
+      // Through the table, so concurrent misses coalesce into one request. A plot
+      // panel resolves one channel per telemetry source, all in the same tick.
+      const fetched = await this.store.retrieve([key]);
+      checkForMultipleOrNoResults("channel", key, fetched, true);
+      [ch] = fetched;
     }
     // A cached calculated channel without a cached status is ambiguous: the
     // status may not exist, or may simply never have been fetched.
@@ -794,7 +798,7 @@ export class Client extends query.Retriever<
     const resolved: Channel[] = [];
     const missing: string[] = [];
     for (const name of new Set(names)) {
-      const matches = this.store.get((ch) => ch.name === name);
+      const matches = this.byName.get(name);
       if (matches.length > 1) return null;
       if (matches.length === 0) missing.push(name);
       else resolved.push(matches[0]);

package/src/device/client.ts

@@ -276,10 +276,6 @@ export class Client extends query.Retriever<
     return await super.retrieve(rest);
   }
 
-  async create(device: New): Promise<Device>;
-
-  async create(devices: New[]): Promise<Device[]>;
-
   async create<
     Properties extends z.ZodType<record.Unknown>,
     Make extends z.ZodType<string>,
@@ -424,10 +420,11 @@ export class Client extends query.Retriever<
   }
 
   private async fetchSingle(q: SingleQuery): Promise<Device> {
-    // A status-bearing hit needs both the record and its status cached.
+    // Status-bearing queries bypass the table, which never holds status.
     if (q.includeStatus !== true) {
-      const cached = this.store.get(q.key);
-      if (cached != null) return cached;
+      const devices = await this.store.retrieve([q.key]);
+      checkForMultipleOrNoResults("Device", q, devices, true);
+      return devices[0];
     }
     const devices = await this.execRetrieve(q);
     checkForMultipleOrNoResults("Device", q, devices, true);

package/src/framer/cache/cache.ts

@@ -49,6 +49,7 @@ export class Cache {
       instrumentation = DEFAULT_STATIC_PROPS.instrumentation,
       transform = DEFAULT_STATIC_PROPS.transform,
       staleEntryThreshold = DEFAULT_STATIC_PROPS.staleEntryThreshold,
+      staleCoverageThreshold = DEFAULT_STATIC_PROPS.staleCoverageThreshold,
     } = props;
     this.props = {
       dynamicBufferSize,
@@ -56,6 +57,7 @@ export class Cache {
       instrumentation,
       transform,
       staleEntryThreshold,
+      staleCoverageThreshold,
     };
     this.gcInterval = setInterval(() => this.gc(), gcInterval.milliseconds);
   }
@@ -70,11 +72,17 @@ export class Cache {
       throw new UnexpectedError(`get(${key}) called on a closed telemetry cache`);
     const existing = this.cache.get(key);
     if (existing != null) return existing;
-    const { dynamicBufferSize, transform, staleEntryThreshold } = this.props;
+    const {
+      dynamicBufferSize,
+      transform,
+      staleEntryThreshold,
+      staleCoverageThreshold,
+    } = this.props;
     const unary = new Unary({
       dynamicBufferSize,
       transform,
       staleEntryThreshold,
+      staleCoverageThreshold,
       instrumentation: this.props.instrumentation.child(`cache-${key}`),
     });
     this.cache.set(key, unary);

package/src/framer/cache/reader.ts

@@ -172,9 +172,11 @@ export class Reader {
           if (existing == null) grouped.set(key, [s]);
           else existing.push(s);
         });
-        channels.forEach((key) =>
-          cache.get(key).writeStatic(new MultiSeries(grouped.get(key) ?? [])),
-        );
+        channels.forEach((key) => {
+          const unary = cache.get(key);
+          unary.writeStatic(new MultiSeries(grouped.get(key) ?? []));
+          unary.markFetched(gap);
+        });
       }
     } catch (err) {
       failure = err;

package/src/framer/cache/static.ts

@@ -46,12 +46,19 @@ export interface StaticProps {
    * be marked as stale and subject to garbage collection.
    * @default TimeSpan.seconds(20) */
   staleEntryThreshold?: TimeSpan;
+  /**
+   * Sets how long a fetched span counts as answered before it is refetched. Bounds
+   * the refetch rate of spans that stay empty, as every refetch opens a short-lived
+   * iterator connection.
+   * @default TimeSpan.minutes(10) */
+  staleCoverageThreshold?: TimeSpan;
 }
 
 export const DEFAULT_STATIC_PROPS: Required<StaticProps> = {
   instrumentation: alamos.NOOP,
   transform: IDENTITY_TRANSFORM,
   staleEntryThreshold: TimeSpan.seconds(20),
+  staleCoverageThreshold: TimeSpan.minutes(10),
 };
 
 interface CacheEntry {
@@ -61,6 +68,13 @@ interface CacheEntry {
   addedAt: TimeStamp;
 }
 
+interface CoveredRange {
+  /** The fetched span, held even when the fetch returned no samples. */
+  range: TimeRange;
+  /** When the fetch completed. Coverage answers gaps until it goes stale. */
+  addedAt: TimeStamp;
+}
+
 /**
  * A cache for historical channel data that will not be modified after it is written.
  * Fetched and streamed entries are held apart because they measure position in
@@ -71,6 +85,9 @@ interface CacheEntry {
 export class Static {
   private fetched: CacheEntry[] = [];
   private streamed: CacheEntry[] = [];
+  // Sorted, non-overlapping spans already fetched, kept apart from the entries so a
+  // span that returned no samples still counts as answered and is not refetched.
+  private covered: CoveredRange[] = [];
   private readonly props: Required<StaticProps>;
 
   constructor(props: StaticProps) {
@@ -78,8 +95,14 @@ export class Static {
       instrumentation = DEFAULT_STATIC_PROPS.instrumentation,
       transform = DEFAULT_STATIC_PROPS.transform,
       staleEntryThreshold = DEFAULT_STATIC_PROPS.staleEntryThreshold,
+      staleCoverageThreshold = DEFAULT_STATIC_PROPS.staleCoverageThreshold,
     } = props;
-    this.props = { instrumentation, transform, staleEntryThreshold };
+    this.props = {
+      instrumentation,
+      transform,
+      staleEntryThreshold,
+      staleCoverageThreshold,
+    };
   }
 
   /**
@@ -98,6 +121,36 @@ export class Static {
     this.repairIntegrity(series, entries);
   }
 
+  /**
+   * Records tr as fetched, merging it into the covered set. A covered span counts
+   * as answered even when empty, so it is refetched once it goes stale, not per read.
+   */
+  markFetched(tr: TimeRange): void {
+    if (!tr.isValid || tr.span.isZero) return;
+    let { start, end } = tr;
+    // Live merges keep the oldest stamp so a rolling read cannot refresh its own
+    // coverage forever. Stale records drop, so a refetch restarts their clock.
+    let addedAt = TimeStamp.now();
+    const keep: CoveredRange[] = [];
+    for (const c of this.covered) {
+      if (!this.isLive(c)) continue;
+      if (c.range.end.before(start) || c.range.start.after(end)) keep.push(c);
+      else {
+        if (c.range.start.before(start)) start = c.range.start;
+        if (c.range.end.after(end)) end = c.range.end;
+        if (c.addedAt.before(addedAt)) addedAt = c.addedAt;
+      }
+    }
+    keep.push({ range: new TimeRange(start, end), addedAt });
+    keep.sort((a, b) => TimeRange.sort(a.range, b.range));
+    this.covered = keep;
+  }
+
+  // Coverage answers gaps only until it goes stale. gc merely prunes dead records.
+  private isLive(c: CoveredRange): boolean {
+    return TimeStamp.since(c.addedAt).lessThan(this.props.staleCoverageThreshold);
+  }
+
   // Containment, not overlap: a fetch stamped wider than the data it returned
   // (an uncommitted tail) must not evict streamed samples it did not replace.
   private evictStreamed(written: MultiSeries): void {
@@ -125,11 +178,12 @@ export class Static {
       entries.filter((e) => e.data.timeRange.overlapsWith(tr)).map((e) => e.data);
     const fetched = overlapping(this.fetched);
     const series = [...fetched, ...overlapping(this.streamed)];
-    if (fetched.length === 0) return { series: new MultiSeries(series), gaps: [tr] };
+    if (fetched.length === 0)
+      return { series: new MultiSeries(series), gaps: this.subtractCovered(tr) };
     const gaps: TimeRange[] = [];
     const pushGap = (start: TimeStamp, end: TimeStamp): void => {
       const gap = new TimeRange(start, end);
-      if (gap.isValid && !gap.span.isZero) gaps.push(gap);
+      if (gap.isValid && !gap.span.isZero) gaps.push(...this.subtractCovered(gap));
     };
     pushGap(tr.start, fetched[0].timeRange.start);
     for (let i = 1; i < fetched.length; i++)
@@ -138,6 +192,29 @@ export class Static {
     return { series: new MultiSeries(series), gaps };
   }
 
+  // Removes the covered portions of gap, returning the still-unanswered remainder.
+  private subtractCovered(gap: TimeRange): TimeRange[] {
+    let remaining = [gap];
+    for (const c of this.covered) {
+      if (!this.isLive(c)) continue;
+      const { range } = c;
+      const next: TimeRange[] = [];
+      for (const r of remaining) {
+        if (!range.overlapsWith(r)) {
+          next.push(r);
+          continue;
+        }
+        const before = new TimeRange(r.start, range.start);
+        const after = new TimeRange(range.end, r.end);
+        if (before.isValid && !before.span.isZero) next.push(before);
+        if (after.isValid && !after.span.isZero) next.push(after);
+      }
+      remaining = next;
+      if (remaining.length === 0) break;
+    }
+    return remaining;
+  }
+
   /**
    * Garbage collects the cache, removing any stale entries.
    * @returns metrics about the garbage collection.
@@ -158,6 +235,11 @@ export class Static {
       });
     this.fetched = collect(this.fetched);
     this.streamed = collect(this.streamed);
+    // The client cannot tell "no data yet" from "no data ever" (backfill is legal),
+    // so stale coverage re-opens an empty span to one cheap fetch per staleness
+    // window instead of one per read (space-heater mode). Series purging above is not
+    // affected.
+    this.covered = this.covered.filter((c) => this.isLive(c));
     return res;
   }
 
@@ -165,6 +247,7 @@ export class Static {
   close(): void {
     this.fetched = [];
     this.streamed = [];
+    this.covered = [];
   }
 
   private writeOne(series: Series, entries: CacheEntry[]): void {

package/src/framer/cache/unary.ts

@@ -70,6 +70,13 @@ export class Unary {
     this.static.write(series);
   }
 
+  /** Records tr as fetched so reads stop reporting it as a gap even when it holds no
+   * samples. Call after a fetch for tr completes. */
+  markFetched(tr: TimeRange): void {
+    this.checkOpen("markFetched");
+    this.static.markFetched(tr);
+  }
+
   /**
    * Reads cached data overlapping the given time range. The result includes the live
    * leading buffer when the data it actually holds overlaps the range, judged by the

package/src/framer/feed.ts

@@ -52,6 +52,7 @@ export class Feed {
       dynamicBufferSize,
       gcInterval,
       staleEntryThreshold,
+      staleCoverageThreshold,
       removalDelay,
       breaker,
       batchDebounce,
@@ -62,6 +63,7 @@ export class Feed {
       dynamicBufferSize,
       gcInterval,
       staleEntryThreshold,
+      staleCoverageThreshold,
       instrumentation: instrumentation?.child("cache"),
     });
     this.reader = new Reader({