@hasna/instructions 0.6.1 → 0.7.0

package/README.md

@@ -18,9 +18,15 @@ bun add --global @hasna/instructions
 
 ```bash
 instructions --help
-instructions init
+
+# Hosted-by-default: resolves the approved key and uses
+# https://api.hasna.com/instructions/v1.
+instructions status
 instructions list
-instructions profile resolve
+
+# Explicit on-box SQLite mode; there is never an implicit fallback.
+HASNA_INSTRUCTIONS_LOCAL=1 instructions init
+HASNA_INSTRUCTIONS_LOCAL=1 instructions list
 ```
 
 ## Migrating from `@hasna/configs`
@@ -29,6 +35,19 @@ This package was formerly `@hasna/configs`. The `configs` CLI alias and
 `configs-mcp` alias remain available for existing integrations; new usage can
 use the `instructions` names.
 
+Historical on-box rows can be migrated without overwriting the current store:
+
+```bash
+export HASNA_INSTRUCTIONS_LOCAL=1
+instructions migrate-legacy --confirm-local --json          # no-write plan
+instructions migrate-legacy --confirm-local --apply --json  # backup + transaction
+```
+
+The source defaults to `~/.hasna/configs/configs.db`; the destination defaults
+to the current `instructions.db`. A non-empty destination is refused unless
+`--merge-preserve-destination` is explicit, and that merge never overwrites an
+existing row.
+
 ## CLI Usage
 
 ```bash
@@ -109,8 +128,9 @@ instructions-mcp --http          # http://127.0.0.1:8807/mcp
 MCP_HTTP=1 instructions-mcp
 ```
 
-Health: `GET http://127.0.0.1:8807/health`. MCP is also mounted on
-`instructions-serve` at `/mcp`.
+Health: `GET http://127.0.0.1:8807/health`. The production
+`instructions-serve` process deliberately does **not** mount MCP; local MCP and
+the authenticated `/v1` service remain separate authorities.
 
 ## HTTP API server (`instructions-serve`)
 
@@ -120,14 +140,20 @@ instructions-serve
 
 Surfaces:
 
-- `GET /health`, `GET /ready`, `GET /version` → `{ status, version, mode }`
+- `GET /health`, `GET /ready`, `GET /version` → `{ status, version, backend }`
 - `GET /openapi.json`, `GET /v1/openapi.json` → the OpenAPI 3.1 document the SDK
   is generated from.
 - `/v1/*` — versioned cloud API (configs, profiles, snapshots, stats).
 - No `/api/*` — the former local REST surface is not mounted (the removed
   bundled dashboard was its only consumer).
 
-### Server data backend (postgresql)
+### Server data backend (PostgreSQL, fail closed)
+
+`instructions-serve` requires `HASNA_INSTRUCTIONS_DATABASE_URL` (or its documented
+alias) for a usable `/v1` service. Without a DSN, `/health` remains a liveness
+probe but reports `backend: "unconfigured"`; `/ready` returns 503 and `/v1`
+returns a stable unavailable error. It never exposes local SQLite over the
+service boundary.
 
 When `HASNA_INSTRUCTIONS_DATABASE_URL` is set the `/v1` API reads/writes the
 shared Postgres **directly** (no local sync/cache in the service) and every
@@ -150,6 +176,16 @@ they resolve `HASNA_INSTRUCTIONS_API_KEY` (or the Keychain / credentials-file
 tiers) through the one `@hasna/contracts` client resolver, and the authority
 defaults to the fleet gateway `https://api.hasna.com/instructions`.
 
+Collection responses are producer-bounded with `limit`/`cursor` envelopes.
+Current clients follow every page; `view=identity` returns an allowlisted
+metadata-only projection for configs, profiles, and machines, without loading
+instruction content or private profile fields. Retryable create and binding
+writes may send `Idempotency-Key`; PostgreSQL stores the authenticated
+principal, operation, canonical request digest, and first committed response in
+the same transaction as the domain mutation. A same-body retry replays that
+response, while key reuse with different bytes returns
+`409 IDEMPOTENCY_KEY_REUSED`.
+
 ## SDK
 
 The importable module ships INSIDE `@hasna/instructions` at the `./sdk` export
@@ -215,6 +251,87 @@ transport is decided by what resolves, never by a mode word.
 Clients never hold a database DSN. The raw Postgres connection is a server-only
 concern (`instructions-serve`), selected by `HASNA_INSTRUCTIONS_DATABASE_URL`.
 
+
+
+## Domain export and import
+
+`instructions export` writes a restorable Instructions domain archive v2. The
+archive contains config content and every retained config snapshot, profiles,
+ordered profile membership and config-binding metadata, profile asset bindings,
+and registered machines. Relationships are recorded by stable config/profile
+slugs and machine hostnames, so import can map them safely onto destination IDs.
+
+```bash
+instructions export --output ./instructions-domain.tar.gz
+instructions import ./instructions-domain.tar.gz # exact recovery into an empty destination
+```
+
+V2 is deliberately a recovery format, not a merge format. Import validates the
+complete archive and requires a destination with zero configs, profiles, and
+machines before the first mutation. `--overwrite` is rejected for v2 before
+destination inspection or mutation. Any validation, mutation, or readback
+failure throws and makes the CLI exit nonzero; discard that attempted
+destination and retry from a newly empty database.
+
+The manifest contains deterministic per-collection counts and SHA-256 logical
+hashes for pre/post deployment comparison without placing instruction content
+in logs. Exact deployment integrity includes config `created_at`, `updated_at`,
+and `synced_at`; snapshot `created_at`; profile `created_at` and `updated_at`;
+and machine `created_at` plus the exact `last_applied_at` value. After recovery,
+import reads the complete domain back through `ConfigStore` and verifies every
+field that interface can reproduce: config data and versions, retained snapshot
+contents, profiles, ordered bindings, asset mappings, machines, and whether a
+machine was ever applied.
+
+`ConfigStore` cannot assign archived config/profile/snapshot/machine creation or
+update timestamps, nor an exact machine `last_applied_at`; generated destination
+IDs are also intentionally remapped by stable slugs and hostnames. These values
+remain protected in the archive's exact integrity hashes but are not recreated
+by recovery. ConfigStore also has no cross-entity transaction, so an operational
+failure may leave a partial destination; the nonzero result is terminal and that
+destination must not be reused. Legacy v1 config-only archives remain importable,
+including their historical skip/overwrite conflict behavior.
+
+API keys and idempotency receipts are intentionally excluded: they are security
+and transport state that must be provisioned independently. Feedback is also
+excluded because it is product telemetry, not part of the Instructions
+configuration domain.
+
+## Native S3 backup storage
+
+S3 is an **adjunct immutable backup plane**, never a database selector. SQLite
+remains the explicit local authority and PostgreSQL remains the hosted `/v1`
+authority. Setting S3 variables alone never opens SQLite, never selects HTTP,
+and never changes CRUD routing.
+
+```bash
+export HASNA_INSTRUCTIONS_S3_BUCKET=your-private-bucket
+export HASNA_INSTRUCTIONS_AWS_REGION=us-east-1
+# Optional: HASNA_INSTRUCTIONS_S3_PREFIX (default: instructions/)
+# Optional local/S3-compatible endpoint and explicit static credentials.
+
+instructions storage status --json
+instructions export --output ./instructions-backup.tar.gz
+instructions storage backup push ./instructions-backup.tar.gz   --id 2026-09-15-pre-deploy --dry-run --json
+instructions storage backup push ./instructions-backup.tar.gz   --id 2026-09-15-pre-deploy --json
+instructions storage backup verify 2026-09-15-pre-deploy --json
+instructions storage backup pull 2026-09-15-pre-deploy   --output ./restored-instructions.tar.gz --json
+```
+
+Each backup uses traversal-safe deterministic keys, an atomically created
+payload, and an atomically created manifest containing SHA-256, byte size,
+content type, and creation time. Native S3 creation uses `If-None-Match: *`;
+concurrent different-byte writers cannot replace the winner, identical replay
+is idempotent, and an injected store without conditional-create support fails
+closed. Pulls verify the payload before an owner-only local file is written.
+Production backup buckets must enable versioning, encryption, public-access
+blocking, and S3 Object Lock with a default retention period. AWS runtime
+credentials may come from Bun's standard AWS chain (including an ECS task role);
+explicit static credentials are optional and must be a complete pair. Status
+never prints credential values or the bucket name.
+
+The public importable surface is available at `@hasna/instructions/storage`.
+
 ## Data Directory
 
 Local data (the SQLite store and backups) lives under the configs store home,

package/dist/chunks/{apply-ynfn1av7.js → apply-7svah2qm.js}

@@ -3,20 +3,22 @@ import {
   applyConfig,
   applyConfigs,
   applyConfigsWithReport,
+  compactPathForConfigHome,
   expandPath,
   getConfigHome,
   normalizeTargetPath,
   previewConfigs
-} from "./index-axhwg61p.js";
-import"./index-v7dkb384.js";
+} from "./index-fwbs6tma.js";
+import"./index-4pfq42t5.js";
 import"./index-35z65jsa.js";
-import"./index-pkscjnj5.js";
+import"./index-3djthcm6.js";
 import"./index-nnwp92tk.js";
 export {
   previewConfigs,
   normalizeTargetPath,
   getConfigHome,
   expandPath,
+  compactPathForConfigHome,
   applyConfigsWithReport,
   applyConfigs,
   applyConfig

package/dist/chunks/{apply-sfzja1f3.js → apply-jp13sa1e.js}

@@ -3,19 +3,22 @@ import {
   applyConfig,
   applyConfigs,
   applyConfigsWithReport,
+  compactPathForConfigHome,
   expandPath,
   getConfigHome,
   normalizeTargetPath,
   previewConfigs
-} from "./index-e9epbsvs.js";
-import"./index-1hpwskwd.js";
-import"./index-pkscjnj5.js";
+} from "./index-z3ma4aqk.js";
+import"./index-7m4j8a33.js";
+import"./index-n3fjspr0.js";
+import"./index-fpeyzn3n.js";
 import"./index-bsan4c16.js";
 export {
   previewConfigs,
   normalizeTargetPath,
   getConfigHome,
   expandPath,
+  compactPathForConfigHome,
   applyConfigsWithReport,
   applyConfigs,
   applyConfig

package/dist/chunks/database-wstmr56z.js

@@ -0,0 +1,23 @@
+// @bun
+import {
+  getDatabase,
+  insertFeedback,
+  resetDatabase,
+  resetLocalDatabase
+} from "./index-5d7zdftc.js";
+import {
+  now,
+  slugify,
+  uuid
+} from "./index-ma2xmp6c.js";
+import"./index-fpeyzn3n.js";
+import"./index-bsan4c16.js";
+export {
+  uuid,
+  slugify,
+  resetLocalDatabase,
+  resetDatabase,
+  now,
+  insertFeedback,
+  getDatabase
+};

package/dist/chunks/{index-85n5wnd8.js → index-1cnyjnd7.js}

@@ -1,10 +1,11 @@
 // @bun
 import {
   applyConfigsWithReport,
+  compactPathForConfigHome,
   expandPath,
   getConfigHome,
   normalizeTargetPath
-} from "./index-e9epbsvs.js";
+} from "./index-z3ma4aqk.js";
 import {
   applyTransform,
   detectMachineContext,
@@ -15,7 +16,7 @@ import {
   resolveConfigStore,
   retiredOrUnsupportedAgentReason,
   templateizeMachineContent
-} from "./index-1hpwskwd.js";
+} from "./index-7m4j8a33.js";
 
 // src/lib/sync.ts
 import { existsSync as existsSync2, readdirSync as readdirSync2, readFileSync as readFileSync2 } from "fs";
@@ -24,7 +25,6 @@ import { basename, extname, join as join2 } from "path";
 // src/lib/sync-dir.ts
 import { existsSync, readdirSync, readFileSync, statSync } from "fs";
 import { join, relative } from "path";
-import { homedir } from "os";
 var SKIP = [".db", ".db-shm", ".db-wal", ".log", ".lock", ".DS_Store", "node_modules", ".git"];
 function shouldSkip(p) {
   return SKIP.some((s) => p.includes(s));
@@ -36,7 +36,6 @@ async function syncFromDir(dir, opts = {}) {
     return { added: 0, updated: 0, unchanged: 0, skipped: [`Not found: ${absDir}`] };
   const files = opts.recursive !== false ? walkDir(absDir) : readdirSync(absDir).map((f) => join(absDir, f)).filter((f) => statSync(f).isFile());
   const result = { added: 0, updated: 0, unchanged: 0, skipped: [] };
-  const home = homedir();
   const allConfigs = await store.listConfigs();
   for (const file of files) {
     if (shouldSkip(file)) {
@@ -49,7 +48,7 @@ async function syncFromDir(dir, opts = {}) {
         result.skipped.push(file + " (too large)");
         continue;
       }
-      const targetPath = file.replace(home, "~");
+      const targetPath = compactPathForConfigHome(file);
       const redacted = redactContent(content, redactFormatForTarget(targetPath, detectFormat(file)));
       const existing = allConfigs.find((c) => c.target_path === targetPath);
       if (!existing) {
@@ -71,9 +70,8 @@ async function syncFromDir(dir, opts = {}) {
 }
 async function syncToDir(dir, opts = {}) {
   const store = opts.store ?? resolveConfigStore();
-  const home = homedir();
   const absDir = expandPath(dir);
-  const normalized = dir.startsWith("~/") ? dir : absDir.replace(home, "~");
+  const normalized = dir.startsWith("~/") ? dir : compactPathForConfigHome(absDir);
   const configs = (await store.listConfigs()).filter((c) => c.target_path && (c.target_path.startsWith(normalized) || c.target_path.startsWith(absDir)));
   const result = { added: 0, updated: 0, unchanged: 0, skipped: [] };
   for (const config of configs) {

package/dist/chunks/{index-pkscjnj5.js → index-3djthcm6.js}

@@ -28,7 +28,6 @@ var ASSET_DESTINATION_STRATEGIES = ["emit-file", "install-local", "install-marke
 var ASSET_SCOPES = ["global", "project", "session"];
 var ASSET_UNINSTALL_POLICIES = ["remove-managed", "retain"];
 var ASSET_ROLLBACK_POLICIES = ["snapshot", "installer-receipt", "none"];
-
 class ConfigNotFoundError extends Error {
   constructor(id) {
     super(`Config not found: ${id}`);

package/dist/chunks/{index-v7dkb384.js → index-4pfq42t5.js}

@@ -15,7 +15,7 @@ import {
   isTemplate,
   renderTemplate,
   renderTemplatePreview
-} from "./index-pkscjnj5.js";
+} from "./index-3djthcm6.js";
 import {
   __export,
   __require
@@ -203,6 +203,7 @@ import { randomUUID } from "crypto";
 // src/lib/compact-output.ts
 var DEFAULT_LIST_LIMIT = 20;
 var MAX_LIST_LIMIT = 100;
+var MAX_LIST_CURSOR = 1e5;
 function parseLimit(value, fallback = DEFAULT_LIST_LIMIT, max = MAX_LIST_LIMIT) {
   const parsed = typeof value === "number" ? value : Number.parseInt(String(value ?? ""), 10);
   if (!Number.isFinite(parsed) || parsed <= 0)
@@ -213,7 +214,7 @@ function parseCursor(value) {
   const parsed = typeof value === "number" ? value : Number.parseInt(String(value ?? ""), 10);
   if (!Number.isFinite(parsed) || parsed < 0)
     return 0;
-  return Math.floor(parsed);
+  return Math.min(Math.floor(parsed), MAX_LIST_CURSOR);
 }
 function paginate(items, opts = {}) {
   const limit = parseLimit(opts.limit, opts.defaultLimit ?? DEFAULT_LIST_LIMIT, opts.maxLimit ?? MAX_LIST_LIMIT);
@@ -720,7 +721,7 @@ function optionalString(value, label) {
   return requiredString(value, label);
 }
 
-// ../contracts/dist/client/transport.js
+// ../../node_modules/.bun/@hasna+contracts@1.0.2+e8014c875821e0be/node_modules/@hasna/contracts/dist/client/transport.js
 import { createRequire } from "module";
 function envToken(name) {
   return name.toUpperCase().replace(/-/g, "_");
@@ -754,7 +755,7 @@ var AUTHORITY_OVERRIDE_HEADERS = new Set([
   "x-original-host"
 ]);
 
-// ../contracts/dist/client/storage.js
+// ../../node_modules/.bun/@hasna+contracts@1.0.2+e8014c875821e0be/node_modules/@hasna/contracts/dist/client/storage.js
 import { isIP } from "net";
 import { spawnSync } from "child_process";
 import { closeSync, fstatSync, openSync, readFileSync } from "fs";
@@ -2032,11 +2033,11 @@ function announceLocalInstructionsMode(write = (line) => process.stderr.write(`$
 }
 
 // src/data/config-store.ts
-function parseBoundedPagePayload(value, label) {
+function parseBoundedPagePayload(value, label, expected) {
   const page = value;
   const consumed = Number(page?.cursor) + (page?.items?.length ?? 0);
   const complete = Boolean(page && Number.isSafeInteger(page.total) && consumed >= Number(page.total));
-  if (!page || !Array.isArray(page.items) || !Number.isSafeInteger(page.total) || Number(page.total) < 0 || !Number.isSafeInteger(page.limit) || Number(page.limit) < 1 || !Number.isSafeInteger(page.cursor) || Number(page.cursor) < 0 || page.items.length > Number(page.limit) || typeof page.has_more !== "boolean" || typeof page.complete !== "boolean" || page.truncated !== false || page.next_cursor !== null && !Number.isSafeInteger(page.next_cursor) || page.complete !== complete || page.has_more !== !complete || page.next_cursor !== (complete ? null : consumed)) {
+  if (!page || !Array.isArray(page.items) || !Number.isSafeInteger(page.total) || Number(page.total) < 0 || !Number.isSafeInteger(page.limit) || Number(page.limit) < 1 || !Number.isSafeInteger(page.cursor) || Number(page.cursor) < 0 || page.items.length > Number(page.limit) || typeof page.has_more !== "boolean" || typeof page.complete !== "boolean" || page.truncated !== false || page.next_cursor !== null && !Number.isSafeInteger(page.next_cursor) || page.complete !== complete || page.has_more !== !complete || page.next_cursor !== (complete ? null : consumed) || expected !== undefined && Number(page.cursor) !== expected.cursor) {
     throw new Error(`${label} returned an invalid or truncated bounded-read envelope`);
   }
   return {
@@ -2048,7 +2049,7 @@ function parseBoundedOrLegacyPage(value, legacyItems, options, label) {
   if (value && typeof value === "object") {
     const candidate = value;
     if ("items" in candidate || "total" in candidate || "complete" in candidate || "truncated" in candidate || "next_cursor" in candidate) {
-      return parseBoundedPagePayload(value, label);
+      return parseBoundedPagePayload(value, label, normalizeBoundedReadOptions(options));
     }
   }
   if (!Array.isArray(legacyItems)) {
@@ -2058,13 +2059,72 @@ function parseBoundedOrLegacyPage(value, legacyItems, options, label) {
   const page = boundedReadPage(legacyItems.slice(normalized.cursor, normalized.cursor + normalized.limit), legacyItems.length, normalized);
   return { ...page, source_bounded: false };
 }
+
+class CollectionChangedWhilePagingError extends Error {
+  constructor(label, detail) {
+    super(`${label} changed while paging: ${detail}`);
+    this.name = "CollectionChangedWhilePagingError";
+  }
+}
+var COLLECTION_READ_ATTEMPTS = 2;
+async function aggregateBoundedCollection(label, readPage, identity, options = {}) {
+  let lastError = null;
+  for (let attempt = 0;attempt < COLLECTION_READ_ATTEMPTS; attempt += 1) {
+    try {
+      const items = [];
+      const seen = new Set;
+      let expectedTotal = null;
+      let cursor = 0;
+      let previousIdentity = null;
+      while (true) {
+        const page = await readPage(cursor);
+        if (page.cursor !== cursor) {
+          throw new CollectionChangedWhilePagingError(label, `server returned cursor ${page.cursor} for requested cursor ${cursor}`);
+        }
+        if (expectedTotal === null)
+          expectedTotal = page.total;
+        else if (page.total !== expectedTotal) {
+          throw new CollectionChangedWhilePagingError(label, `total changed from ${expectedTotal} to ${page.total}`);
+        }
+        for (const item of page.items) {
+          const key = identity(item);
+          if (!key)
+            throw new CollectionChangedWhilePagingError(label, "an item had no stable identity");
+          if (seen.has(key))
+            throw new CollectionChangedWhilePagingError(label, `duplicate identity ${key}`);
+          if (options.requireAscendingIdentity && page.source_bounded && previousIdentity !== null && key <= previousIdentity) {
+            throw new CollectionChangedWhilePagingError(label, `identity order was not strictly increasing at ${key}`);
+          }
+          seen.add(key);
+          previousIdentity = key;
+          items.push(item);
+        }
+        if (page.complete) {
+          if (items.length !== expectedTotal) {
+            throw new CollectionChangedWhilePagingError(label, `received ${items.length} unique rows for total ${expectedTotal}`);
+          }
+          return items;
+        }
+        if (page.next_cursor === null || page.next_cursor <= cursor) {
+          throw new CollectionChangedWhilePagingError(label, `cursor did not advance from ${cursor}`);
+        }
+        cursor = page.next_cursor;
+      }
+    } catch (error) {
+      if (!(error instanceof CollectionChangedWhilePagingError))
+        throw error;
+      lastError = error;
+    }
+  }
+  throw lastError ?? new CollectionChangedWhilePagingError(label, "read did not stabilize");
+}
 function isNotFoundHttpError2(err) {
   return typeof err === "object" && err !== null && err.name === "HasnaHttpError" && err.status === 404;
 }
 var localStoreModulePromise = null;
 function localStoreModule() {
   if (!localStoreModulePromise)
-    localStoreModulePromise = import("./local-a9nen65z.js");
+    localStoreModulePromise = import("./local-5wvv5xv3.js");
   return localStoreModulePromise;
 }
 
@@ -2112,15 +2172,7 @@ class LocalConfigStore {
     return (await localStoreModule()).pruneSnapshots(configId, keep, this.db);
   }
   async listProfiles() {
-    const profiles = [];
-    let cursor = 0;
-    while (true) {
-      const page = await this.listProfilesPage({ limit: 100, cursor });
-      profiles.push(...page.items);
-      if (page.complete)
-        return profiles;
-      cursor = page.next_cursor;
-    }
+    return aggregateBoundedCollection("profile list", (cursor) => this.listProfilesPage({ limit: 100, cursor }), (profile) => profile.id);
   }
   async listProfilesPage(options = {}) {
     return (await localStoreModule()).listProfilesPage(options, this.db);
@@ -2129,15 +2181,7 @@ class LocalConfigStore {
     return (await localStoreModule()).getProfile(idOrSlug, this.db);
   }
   async getProfileConfigs(idOrSlug) {
-    const configs = [];
-    let cursor = 0;
-    while (true) {
-      const page = await this.getProfileConfigsPage(idOrSlug, { limit: 100, cursor });
-      configs.push(...page.items);
-      if (page.complete)
-        return configs;
-      cursor = page.next_cursor;
-    }
+    return aggregateBoundedCollection("profile membership", (cursor) => this.getProfileConfigsPage(idOrSlug, { limit: 100, cursor }), (config) => config.id);
   }
   async getProfileConfigsPage(idOrSlug, options = {}) {
     return (await localStoreModule()).getProfileConfigsPage(idOrSlug, options, this.db);
@@ -2218,7 +2262,8 @@ class CloudConfigStore {
       throw err;
     }
   }
-  async listConfigs(filter = {}) {
+  async listConfigsPageRemote(filter, options) {
+    const normalized = normalizeBoundedReadOptions(options);
     const params = new URLSearchParams;
     if (filter.category)
       params.set("category", filter.category);
@@ -2228,16 +2273,21 @@ class CloudConfigStore {
       params.set("kind", filter.kind);
     if (filter.search)
       params.set("search", filter.search);
-    const qs = params.toString();
-    const { data } = await this.request("GET", `/configs${qs ? `?${qs}` : ""}`);
-    let configs = data?.configs ?? [];
+    params.set("limit", String(normalized.limit));
+    params.set("cursor", String(normalized.cursor));
+    const { data } = await this.request("GET", `/configs?${params.toString()}`);
+    return parseBoundedOrLegacyPage(data, data?.configs, normalized, "config list");
+  }
+  async listConfigs(filter = {}) {
+    const configs = await aggregateBoundedCollection("config list", (cursor) => this.listConfigsPageRemote(filter, { limit: 100, cursor }), (config) => config.id, { requireAscendingIdentity: true });
+    let filtered = configs;
     if (filter.tags && filter.tags.length > 0) {
-      configs = configs.filter((c) => filter.tags.every((t) => c.tags.includes(t)));
+      filtered = filtered.filter((config) => filter.tags.every((tag) => config.tags.includes(tag)));
     }
     if (filter.is_template !== undefined) {
-      configs = configs.filter((c) => c.is_template === filter.is_template);
+      filtered = filtered.filter((config) => config.is_template === filter.is_template);
     }
-    return configs;
+    return filtered;
   }
   async getConfig(idOrSlug) {
     const { status, data } = await this.request("GET", `/configs/${encodeURIComponent(idOrSlug)}`, undefined, { allow404: true });
@@ -2268,8 +2318,11 @@ class CloudConfigStore {
     return data ?? { total: 0 };
   }
   async listSnapshots(configId) {
-    const { data } = await this.request("GET", `/configs/${encodeURIComponent(configId)}/snapshots`);
-    return data?.snapshots ?? [];
+    return aggregateBoundedCollection("snapshot list", async (cursor) => {
+      const normalized = normalizeBoundedReadOptions({ limit: 100, cursor });
+      const { data } = await this.request("GET", `/configs/${encodeURIComponent(configId)}/snapshots?limit=${normalized.limit}&cursor=${normalized.cursor}`);
+      return parseBoundedOrLegacyPage(data, data?.snapshots, normalized, "snapshot list");
+    }, (snapshot) => snapshot.id);
   }
   async getSnapshot(id) {
     const { status, data } = await this.request("GET", `/snapshots/${encodeURIComponent(id)}`, undefined, { allow404: true });
@@ -2292,15 +2345,7 @@ class CloudConfigStore {
     return data?.pruned ?? 0;
   }
   async listProfiles() {
-    const profiles = [];
-    let cursor = 0;
-    while (true) {
-      const page = await this.listProfilesPage({ limit: 100, cursor });
-      profiles.push(...page.items);
-      if (page.complete)
-        return profiles;
-      cursor = page.next_cursor;
-    }
+    return aggregateBoundedCollection("profile list", (cursor) => this.listProfilesPage({ limit: 100, cursor }), (profile) => profile.id, { requireAscendingIdentity: true });
   }
   async listProfilesPage(options = {}) {
     const normalized = normalizeBoundedReadOptions(options);
@@ -2324,15 +2369,7 @@ class CloudConfigStore {
     return profile;
   }
   async getProfileConfigs(idOrSlug) {
-    const configs = [];
-    let cursor = 0;
-    while (true) {
-      const page = await this.getProfileConfigsPage(idOrSlug, { limit: 100, cursor });
-      configs.push(...page.items);
-      if (page.complete)
-        return configs;
-      cursor = page.next_cursor;
-    }
+    return aggregateBoundedCollection("profile membership", (cursor) => this.getProfileConfigsPage(idOrSlug, { limit: 100, cursor }), (config) => config.id);
   }
   async getProfileConfigsPage(idOrSlug, options = {}) {
     const normalized = normalizeBoundedReadOptions(options);
@@ -2346,20 +2383,26 @@ class CloudConfigStore {
     return parseBoundedOrLegacyPage(data.configs, data.profile.configs, normalized, "profile membership");
   }
   async getProfileConfigBindings(idOrSlug) {
-    const { status, data } = await this.requestProfileRoute(idOrSlug, (profileId) => `/profiles/${encodeURIComponent(profileId)}/bindings`, (value) => Array.isArray(value?.bindings));
-    if (status === 404) {
-      const profile = await this.getProfile(idOrSlug);
-      const configs = await this.getProfileConfigs(idOrSlug);
-      return configs.map((config, sort_order) => ({
-        profile_id: profile.id,
-        config_id: config.id,
-        sort_order,
-        binding: legacyProfileConfigBinding()
-      }));
-    }
-    if (!data || !Array.isArray(data.bindings))
-      throw new ProfileNotFoundError(idOrSlug);
-    return data.bindings;
+    let routeMissing = false;
+    const bindings = await aggregateBoundedCollection("profile config bindings", async (cursor) => {
+      const normalized = normalizeBoundedReadOptions({ limit: 100, cursor });
+      const { status, data } = await this.requestProfileRoute(idOrSlug, (profileId) => `/profiles/${encodeURIComponent(profileId)}/bindings?limit=${normalized.limit}&cursor=${normalized.cursor}`, (value) => Boolean(value && (Array.isArray(value.bindings) || Array.isArray(value.items))));
+      if (status === 404) {
+        routeMissing = true;
+        return { ...boundedReadPage([], 0, normalized), source_bounded: false };
+      }
+      return parseBoundedOrLegacyPage(data, data?.bindings, normalized, "profile config bindings");
+    }, (binding) => `${binding.profile_id}\x00${binding.config_id}`);
+    if (!routeMissing)
+      return bindings;
+    const profile = await this.getProfile(idOrSlug);
+    const configs = await this.getProfileConfigs(idOrSlug);
+    return configs.map((config, sort_order) => ({
+      profile_id: profile.id,
+      config_id: config.id,
+      sort_order,
+      binding: legacyProfileConfigBinding()
+    }));
   }
   async requestProfileRoute(idOrSlug, pathForId, isUsable) {
     const attempted = new Set;
@@ -2417,14 +2460,20 @@ class CloudConfigStore {
     await this.request("DELETE", `/profiles/${encodeURIComponent(profileIdOrSlug)}/configs/${encodeURIComponent(configId)}`, undefined, { allow404: true });
   }
   async getProfileAssetBindings(profileIdOrSlug) {
-    const { status, data } = await this.requestProfileRoute(profileIdOrSlug, (profileId) => `/profiles/${encodeURIComponent(profileId)}/assets`, (value) => Array.isArray(value?.assets));
-    if (status === 404) {
-      await this.getProfile(profileIdOrSlug);
-      return [];
-    }
-    if (!data || !Array.isArray(data.assets))
-      throw new ProfileNotFoundError(profileIdOrSlug);
-    return data.assets;
+    let routeMissing = false;
+    const assets = await aggregateBoundedCollection("profile asset bindings", async (cursor) => {
+      const normalized = normalizeBoundedReadOptions({ limit: 100, cursor });
+      const { status, data } = await this.requestProfileRoute(profileIdOrSlug, (profileId) => `/profiles/${encodeURIComponent(profileId)}/assets?limit=${normalized.limit}&cursor=${normalized.cursor}`, (value) => Boolean(value && (Array.isArray(value.assets) || Array.isArray(value.items))));
+      if (status === 404) {
+        routeMissing = true;
+        return { ...boundedReadPage([], 0, normalized), source_bounded: false };
+      }
+      return parseBoundedOrLegacyPage(data, data?.assets, normalized, "profile asset bindings");
+    }, (asset) => `${asset.profile_id}\x00${asset.binding.assetKey}`);
+    if (!routeMissing)
+      return assets;
+    await this.getProfile(profileIdOrSlug);
+    return [];
   }
   async addAssetToProfile(profileIdOrSlug, sourceConfigId, binding) {
     const { data } = await this.request("POST", `/profiles/${encodeURIComponent(profileIdOrSlug)}/assets`, { source_config_id: sourceConfigId, binding }, { idempotent: true });
@@ -2494,8 +2543,11 @@ class CloudConfigStore {
     await this.request("POST", "/machines/applied", { hostname });
   }
   async listMachines() {
-    const { data } = await this.request("GET", "/machines");
-    return data?.machines ?? [];
+    return aggregateBoundedCollection("machine list", async (cursor) => {
+      const normalized = normalizeBoundedReadOptions({ limit: 100, cursor });
+      const { data } = await this.request("GET", `/machines?limit=${normalized.limit}&cursor=${normalized.cursor}`);
+      return parseBoundedOrLegacyPage(data, data?.machines, normalized, "machine list");
+    }, (machine) => machine.id, { requireAscendingIdentity: true });
   }
   async sendFeedback(input) {
     await this.request("POST", "/feedback", {