@hasna/instructions 0.4.33 → 0.4.35

package/dist/cli/index.js

@@ -47,7 +47,7 @@ var __export = (target, all) => {
 var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
 var __require = import.meta.require;
 
-// node_modules/commander/lib/error.js
+// ../../node_modules/.bun/commander@13.1.0/node_modules/commander/lib/error.js
 var require_error = __commonJS((exports) => {
   class CommanderError extends Error {
     constructor(exitCode, code, message) {
@@ -71,7 +71,7 @@ var require_error = __commonJS((exports) => {
   exports.InvalidArgumentError = InvalidArgumentError;
 });
 
-// node_modules/commander/lib/argument.js
+// ../../node_modules/.bun/commander@13.1.0/node_modules/commander/lib/argument.js
 var require_argument = __commonJS((exports) => {
   var { InvalidArgumentError } = require_error();
 
@@ -150,7 +150,7 @@ var require_argument = __commonJS((exports) => {
   exports.humanReadableArgName = humanReadableArgName;
 });
 
-// node_modules/commander/lib/help.js
+// ../../node_modules/.bun/commander@13.1.0/node_modules/commander/lib/help.js
 var require_help = __commonJS((exports) => {
   var { humanReadableArgName } = require_argument();
 
@@ -500,7 +500,7 @@ ${itemIndentStr}`);
   exports.stripColor = stripColor;
 });
 
-// node_modules/commander/lib/option.js
+// ../../node_modules/.bun/commander@13.1.0/node_modules/commander/lib/option.js
 var require_option = __commonJS((exports) => {
   var { InvalidArgumentError } = require_error();
 
@@ -678,7 +678,7 @@ var require_option = __commonJS((exports) => {
   exports.DualOptions = DualOptions;
 });
 
-// node_modules/commander/lib/suggestSimilar.js
+// ../../node_modules/.bun/commander@13.1.0/node_modules/commander/lib/suggestSimilar.js
 var require_suggestSimilar = __commonJS((exports) => {
   var maxDistance = 3;
   function editDistance(a, b) {
@@ -751,7 +751,7 @@ var require_suggestSimilar = __commonJS((exports) => {
   exports.suggestSimilar = suggestSimilar;
 });
 
-// node_modules/commander/lib/command.js
+// ../../node_modules/.bun/commander@13.1.0/node_modules/commander/lib/command.js
 var require_command = __commonJS((exports) => {
   var EventEmitter = __require("events").EventEmitter;
   var childProcess = __require("child_process");
@@ -993,7 +993,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
         this._exitCallback = (err) => {
           if (err.code !== "commander.executeSubCommandAsync") {
             throw err;
-          }
+          } else {}
         };
       }
       return this;
@@ -2061,7 +2061,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
   exports.useColor = useColor;
 });
 
-// node_modules/commander/index.js
+// ../../node_modules/.bun/commander@13.1.0/node_modules/commander/index.js
 var require_commander = __commonJS((exports) => {
   var { Argument } = require_argument();
   var { Command } = require_command();
@@ -2136,6 +2136,30 @@ var init_types = __esm(() => {
   };
 });
 
+// src/lib/retired-storage-mode.ts
+function firstDefinedEnvKey(env, keys) {
+  for (const key of keys) {
+    if (Object.hasOwn(env, key) && env[key] !== undefined)
+      return key;
+  }
+  return null;
+}
+function assertNoLegacyStorageMode(env = process.env) {
+  const legacyKey = firstDefinedEnvKey(env, LEGACY_STORAGE_MODE_KEYS);
+  if (!legacyKey)
+    return;
+  throw new Error(`${legacyKey} was removed. Deployment modes no longer exist: delete the storage-mode variable. ` + `The client uses the local SQLite store, or the HTTP API selected by ` + `HASNA_INSTRUCTIONS_API_URL + HASNA_INSTRUCTIONS_API_KEY. ` + `On the server, set HASNA_INSTRUCTIONS_DATABASE_URL to select the postgresql backend, ` + `or leave it unset for sqlite.`);
+}
+var LEGACY_STORAGE_MODE_KEYS;
+var init_retired_storage_mode = __esm(() => {
+  LEGACY_STORAGE_MODE_KEYS = [
+    "HASNA_INSTRUCTIONS_STORAGE_MODE",
+    "HASNA_INSTRUCTIONS_MODE",
+    "INSTRUCTIONS_STORAGE_MODE",
+    "INSTRUCTIONS_MODE"
+  ];
+});
+
 // src/db/database.ts
 import { Database } from "bun:sqlite";
 import { existsSync as existsSync2, mkdirSync, rmSync } from "fs";
@@ -2162,8 +2186,9 @@ function slugify(name) {
 function getDatabase(path) {
   if (_db)
     return _db;
+  assertNoLegacyStorageMode();
   if (!path && process.env["HASNA_INSTRUCTIONS_API_URL"] && process.env["HASNA_INSTRUCTIONS_API_KEY"]) {
-    throw new Error("instructions is in self_hosted (cloud) mode: this command is not wired to the cloud API yet. " + "Unset HASNA_INSTRUCTIONS_API_URL / HASNA_INSTRUCTIONS_API_KEY to use it against the local store.");
+    throw new Error("instructions is using the HTTP API transport (HASNA_INSTRUCTIONS_API_URL set): this command is not wired to the API yet. " + "Unset HASNA_INSTRUCTIONS_API_URL / HASNA_INSTRUCTIONS_API_KEY to use it against the local store.");
   }
   const dbPath = path || getDbPath();
   const db = new Database(dbPath);
@@ -2244,6 +2269,7 @@ function insertFeedback(input, db) {
 }
 var MIGRATIONS, _db = null;
 var init_database = __esm(() => {
+  init_retired_storage_mode();
   MIGRATIONS = [
     `
   CREATE TABLE IF NOT EXISTS configs (
@@ -3037,7 +3063,7 @@ Policy reference: \`${CODEWITH_SHARED_TODOS_STORAGE_POLICY_REFERENCE}\`
 `;
 });
 
-// node_modules/zod/v3/helpers/util.js
+// ../../node_modules/.bun/zod@3.25.76/node_modules/zod/v3/helpers/util.js
 var util, objectUtil, ZodParsedType, getParsedType = (data) => {
   const t = typeof data;
   switch (t) {
@@ -3168,7 +3194,7 @@ var init_util = __esm(() => {
   ]);
 });
 
-// node_modules/zod/v3/ZodError.js
+// ../../node_modules/.bun/zod@3.25.76/node_modules/zod/v3/ZodError.js
 var ZodIssueCode, quotelessJson = (obj) => {
   const json = JSON.stringify(obj, null, 2);
   return json.replace(/"([^"]+)":/g, "$1:");
@@ -3289,7 +3315,7 @@ var init_ZodError = __esm(() => {
   };
 });
 
-// node_modules/zod/v3/locales/en.js
+// ../../node_modules/.bun/zod@3.25.76/node_modules/zod/v3/locales/en.js
 var errorMap = (issue, _ctx) => {
   let message;
   switch (issue.code) {
@@ -3396,7 +3422,7 @@ var init_en = __esm(() => {
   en_default = errorMap;
 });
 
-// node_modules/zod/v3/errors.js
+// ../../node_modules/.bun/zod@3.25.76/node_modules/zod/v3/errors.js
 function setErrorMap(map) {
   overrideErrorMap = map;
 }
@@ -3409,7 +3435,7 @@ var init_errors = __esm(() => {
   overrideErrorMap = en_default;
 });
 
-// node_modules/zod/v3/helpers/parseUtil.js
+// ../../node_modules/.bun/zod@3.25.76/node_modules/zod/v3/helpers/parseUtil.js
 function addIssueToContext(ctx, issueData) {
   const overrideMap = getErrorMap();
   const issue = makeIssue({
@@ -3514,10 +3540,10 @@ var init_parseUtil = __esm(() => {
   });
 });
 
-// node_modules/zod/v3/helpers/typeAliases.js
+// ../../node_modules/.bun/zod@3.25.76/node_modules/zod/v3/helpers/typeAliases.js
 var init_typeAliases = () => {};
 
-// node_modules/zod/v3/helpers/errorUtil.js
+// ../../node_modules/.bun/zod@3.25.76/node_modules/zod/v3/helpers/errorUtil.js
 var errorUtil;
 var init_errorUtil = __esm(() => {
   (function(errorUtil2) {
@@ -3526,7 +3552,7 @@ var init_errorUtil = __esm(() => {
   })(errorUtil || (errorUtil = {}));
 });
 
-// node_modules/zod/v3/types.js
+// ../../node_modules/.bun/zod@3.25.76/node_modules/zod/v3/types.js
 class ParseInputLazyPath {
   constructor(parent, value, path, key) {
     this._cachedPath = [];
@@ -6877,7 +6903,7 @@ var init_types2 = __esm(() => {
   NEVER = INVALID;
 });
 
-// node_modules/zod/v3/external.js
+// ../../node_modules/.bun/zod@3.25.76/node_modules/zod/v3/external.js
 var exports_external = {};
 __export(exports_external, {
   void: () => voidType,
@@ -6997,7 +7023,7 @@ var init_external = __esm(() => {
   init_ZodError();
 });
 
-// node_modules/zod/index.js
+// ../../node_modules/.bun/zod@3.25.76/node_modules/zod/index.js
 var init_zod = __esm(() => {
   init_external();
   init_external();
@@ -7189,7 +7215,7 @@ var init_redact = __esm(() => {
   VALUE_PATTERNS = [
     { re: /npm_[A-Za-z0-9]{36,}/, reason: "npm token" },
     { re: /gh[pousr]_[A-Za-z0-9_]{36,}/, reason: "GitHub token" },
-    { re: /sk-ant-[A-Za-z0-9\-_]{40,}/, reason: "Anthropic API key" },
+    { re: /sk[-]ant-[A-Za-z0-9\-_]{40,}/, reason: "Anthropic API key" },
     { re: /sk-[A-Za-z0-9]{48,}/, reason: "OpenAI API key" },
     { re: /xoxb-[0-9]+-[A-Za-z0-9\-]+/, reason: "Slack bot token" },
     { re: /AIza[0-9A-Za-z\-_]{35}/, reason: "Google API key" },
@@ -13337,16 +13363,17 @@ function formatCliError(err, env = process.env) {
   return err instanceof Error ? err.message : String(err);
 }
 function resolveCloudConfig(env = process.env) {
+  assertNoLegacyStorageMode(env);
   const apiUrl = env[API_URL_ENV]?.trim();
   const apiKey = env[API_KEY_ENV]?.trim();
   if (!apiUrl && !apiKey)
     return null;
   if (!apiUrl || !apiKey) {
-    throw new Error(`API mode requires BOTH ${API_URL_ENV} and ${API_KEY_ENV}; only ` + `${apiUrl ? API_URL_ENV : API_KEY_ENV} is set. Set both to use the cloud API, ` + `or unset both to use the local store.`);
+    throw new Error(`API mode requires BOTH ${API_URL_ENV} and ${API_KEY_ENV}; only ` + `${apiUrl ? API_URL_ENV : API_KEY_ENV} is set. Set both to use the HTTP API, ` + `or unset both to use the local store.`);
   }
   return { apiUrl, apiKey };
 }
-function isCloudMode(env = process.env) {
+function isApiTransport(env = process.env) {
   return resolveCloudConfig(env) !== null;
 }
 
@@ -13832,6 +13859,7 @@ var init_config_store = __esm(() => {
   init_types();
   init_bounded_read();
   init_instruction_graph();
+  init_retired_storage_mode();
   CloudHttpError = class CloudHttpError extends Error {
     status;
     body;
@@ -15377,15 +15405,16 @@ var init_package_manager_guard = __esm(() => {
   TOKEN_VALUE_PATTERNS = [
     { re: /npm_[A-Za-z0-9]{36,}/, rule: "literal-npm-token", detail: "literal npm token-like value" },
     { re: /gh[pousr]_[A-Za-z0-9_]{36,}/, rule: "literal-github-token", detail: "literal GitHub token-like value" },
-    { re: /sk-ant-[A-Za-z0-9\-_]{40,}/, rule: "literal-anthropic-key", detail: "literal Anthropic key-like value" },
+    { re: /sk[-]ant-[A-Za-z0-9\-_]{40,}/, rule: "literal-anthropic-key", detail: "literal Anthropic key-like value" },
     { re: /sk-[A-Za-z0-9]{48,}/, rule: "literal-openai-key", detail: "literal OpenAI key-like value" },
     { re: /AKIA[0-9A-Z]{16}/, rule: "literal-aws-access-key", detail: "literal AWS access-key-like value" },
     { re: /xoxb-[0-9]+-[A-Za-z0-9-]+/, rule: "literal-slack-token", detail: "literal Slack token-like value" }
   ];
 });
 
-// node_modules/@hasna/events/dist/commander.js
+// ../../node_modules/.bun/@hasna+events@0.1.15/node_modules/@hasna/events/dist/commander.js
 import { chmod, mkdir, readFile, rename, writeFile } from "fs/promises";
+import { Buffer as Buffer2 } from "buffer";
 import { existsSync } from "fs";
 import { homedir } from "os";
 import { join } from "path";
@@ -15401,29 +15430,83 @@ function getPathValue(input, path) {
     return;
   }, input);
 }
-function wildcardToRegExp(pattern) {
-  const escaped = pattern.replace(/[|\\{}()[\]^$+?.]/g, "\\$&").replace(/\*/g, ".*");
-  return new RegExp(`^${escaped}$`);
+function getFieldValues(input, path) {
+  const values = [];
+  const push = (value) => {
+    if (!values.some((item) => Object.is(item, value)))
+      values.push(value);
+  };
+  if (path.includes(".") && path in input)
+    push(input[path]);
+  const nestedValue = getPathValue(input, path);
+  if (nestedValue !== undefined || !path.includes("."))
+    push(nestedValue);
+  return values;
+}
+function wildcardToRegExp(pattern, options = {}) {
+  let body = "";
+  for (let index = 0;index < pattern.length; index += 1) {
+    const char = pattern[index];
+    if (char === "*") {
+      if (pattern[index + 1] === "*") {
+        body += ".*";
+        index += 1;
+      } else {
+        body += options.segmentSafe ? "[^/]*" : ".*";
+      }
+    } else {
+      body += char.replace(/[|\\{}()[\]^$+?.]/g, "\\$&");
+    }
+  }
+  return new RegExp(`^${body}$`);
 }
-function matchString(value, matcher) {
+function matchString(value, matcher, options = {}) {
   if (matcher === undefined)
     return true;
   if (value === undefined)
     return false;
   const matchers = Array.isArray(matcher) ? matcher : [matcher];
-  return matchers.some((item) => wildcardToRegExp(item).test(value));
+  return matchers.some((item) => wildcardToRegExp(item, options).test(value));
 }
 function matchRecord(input, matcher) {
   if (!matcher)
     return true;
   return Object.entries(matcher).every(([path, expected]) => {
-    const actual = getPathValue(input, path);
-    if (typeof expected === "string" || Array.isArray(expected)) {
-      return matchString(actual === undefined ? undefined : String(actual), expected);
-    }
-    return actual === expected;
+    const actualValues = getFieldValues(input, path);
+    return matchField(actualValues, expected, path);
   });
 }
+function matchField(actualValues, expected, path) {
+  if (isNegativeMatcher(expected)) {
+    return !actualValues.some((actual) => matchPositiveField(actual, expected.not, path));
+  }
+  return actualValues.some((actual) => matchPositiveField(actual, expected, path));
+}
+function matchPositiveField(actual, expected, path) {
+  if (typeof expected === "string" || Array.isArray(expected)) {
+    return stringCandidates(actual).some((candidate) => matchString(candidate, expected, {
+      segmentSafe: path.endsWith("_path") || path.endsWith(".path")
+    }));
+  }
+  if (Array.isArray(actual)) {
+    return actual.some((item) => item === expected);
+  }
+  return actual === expected;
+}
+function stringCandidates(actual) {
+  if (actual === undefined)
+    return [];
+  if (Array.isArray(actual)) {
+    return actual.flatMap((item) => isPrimitiveFieldValue(item) ? [String(item)] : []);
+  }
+  return [String(actual)];
+}
+function isPrimitiveFieldValue(value) {
+  return value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+}
+function isNegativeMatcher(value) {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value) && "not" in value);
+}
 function eventMatchesFilter(event, filter) {
   return matchString(event.source, filter.source) && matchString(event.type, filter.type) && matchString(event.subject, filter.subject) && matchString(event.severity, filter.severity) && matchRecord(event.data, filter.data) && matchRecord(event.metadata, filter.metadata);
 }
@@ -15436,16 +15519,29 @@ function channelMatchesEvent(channel, event) {
 }
 var HASNA_EVENTS_DIR_ENV = "HASNA_EVENTS_DIR";
 var HASNA_EVENTS_HOME_ENV = "HASNA_EVENTS_HOME";
+var LOCAL_JSON_EVENT_CURSOR_PREFIX = "local-json-v1:";
+var DEFAULT_EVENT_PAGE_LIMIT = 100;
+var MAX_EVENT_PAGE_LIMIT = 1000;
 function getEventsDataDir(override) {
   return override || process.env[HASNA_EVENTS_DIR_ENV] || process.env[HASNA_EVENTS_HOME_ENV] || join(homedir(), ".hasna", "events");
 }
+function getActiveEventsDirEnv() {
+  if (process.env[HASNA_EVENTS_DIR_ENV])
+    return HASNA_EVENTS_DIR_ENV;
+  if (process.env[HASNA_EVENTS_HOME_ENV])
+    return HASNA_EVENTS_HOME_ENV;
+  return null;
+}
+
 class JsonEventsStore {
   dataDir;
+  runtime;
   channelsPath;
   eventsPath;
   deliveriesPath;
   constructor(dataDir = getEventsDataDir()) {
     this.dataDir = dataDir;
+    this.runtime = localJsonRuntime(dataDir);
     this.channelsPath = join(dataDir, "channels.json");
     this.eventsPath = join(dataDir, "events.json");
     this.deliveriesPath = join(dataDir, "deliveries.json");
@@ -15493,13 +15589,58 @@ class JsonEventsStore {
     await this.writeJson(this.eventsPath, events);
     return event;
   }
-  async listEvents() {
+  async appendEventOnce(event, options = {}) {
     await this.init();
-    return this.readJson(this.eventsPath, []);
+    const events = await this.readJson(this.eventsPath, []);
+    const dedupe = options.dedupe !== false;
+    if (dedupe) {
+      const existing = findEventByIdentity(events, { id: event.id, dedupeKey: event.dedupeKey });
+      if (existing) {
+        return {
+          event: existing,
+          stored: false,
+          deduped: true,
+          identity: { id: existing.id, dedupeKey: existing.dedupeKey }
+        };
+      }
+    }
+    events.push(event);
+    await this.writeJson(this.eventsPath, events);
+    return {
+      event,
+      stored: true,
+      deduped: false,
+      identity: { id: event.id, dedupeKey: event.dedupeKey }
+    };
+  }
+  async listEvents(options = {}) {
+    await this.init();
+    const events = await this.readJson(this.eventsPath, []);
+    return queryEvents(events, options);
+  }
+  async listEventsPage(options = {}) {
+    await this.init();
+    const events = await this.readJson(this.eventsPath, []);
+    const queried = queryEvents(events, {
+      eventId: options.eventId,
+      source: options.source,
+      type: options.type
+    });
+    const offset = decodeLocalJsonEventCursor(options.cursor, options);
+    const limit = normalizeEventPageLimit(options.limit);
+    const pageEvents = queried.slice(offset, offset + limit);
+    const nextOffset = offset + pageEvents.length;
+    const hasMore = nextOffset < queried.length;
+    return {
+      events: pageEvents,
+      cursor: options.cursor,
+      nextCursor: hasMore ? encodeLocalJsonEventCursor(nextOffset, options) : undefined,
+      hasMore
+    };
   }
   async findEventByIdentity(identity) {
     const events = await this.listEvents();
-    return events.find((event) => identity.id !== undefined && event.id === identity.id || identity.dedupeKey !== undefined && event.dedupeKey === identity.dedupeKey);
+    return findEventByIdentity(events, identity);
   }
   async appendDelivery(result) {
     await this.init();
@@ -15550,6 +15691,130 @@ class JsonEventsStore {
     });
   }
 }
+function localJsonRuntime(dataDir = getEventsDataDir()) {
+  return {
+    mode: "local-files",
+    name: "json-events-store",
+    remote: false,
+    localFiles: true,
+    localSqlite: false,
+    postgres: false,
+    s3: false,
+    aws: false,
+    durable: true,
+    idempotency: "best-effort-local",
+    replayCursors: true,
+    description: `Local JSON files in ${dataDir}; no SQLite, Postgres, S3, or AWS runtime is configured by this store.`
+  };
+}
+function encodeLocalJsonEventCursor(offset, options = {}) {
+  if (!Number.isInteger(offset) || offset < 0)
+    throw new Error(`Invalid event cursor offset: ${offset}`);
+  const payload = {
+    offset,
+    eventId: options.eventId,
+    source: options.source,
+    type: options.type
+  };
+  return `${LOCAL_JSON_EVENT_CURSOR_PREFIX}${Buffer2.from(JSON.stringify(payload), "utf-8").toString("base64url")}`;
+}
+function decodeLocalJsonEventCursor(cursor, options = {}) {
+  if (!cursor)
+    return 0;
+  if (!cursor.startsWith(LOCAL_JSON_EVENT_CURSOR_PREFIX))
+    throw new Error(`Invalid local JSON event cursor: ${cursor}`);
+  const rawPayload = cursor.slice(LOCAL_JSON_EVENT_CURSOR_PREFIX.length);
+  let payload;
+  try {
+    payload = JSON.parse(Buffer2.from(rawPayload, "base64url").toString("utf-8"));
+  } catch {
+    throw new Error(`Invalid local JSON event cursor: ${cursor}`);
+  }
+  const offset = payload.offset;
+  if (!Number.isInteger(offset) || offset < 0)
+    throw new Error(`Invalid local JSON event cursor: ${cursor}`);
+  assertCursorFilter("eventId", payload.eventId, options.eventId);
+  assertCursorFilter("source", payload.source, options.source);
+  assertCursorFilter("type", payload.type, options.type);
+  return offset;
+}
+function normalizeEventPageLimit(limit) {
+  if (limit === undefined)
+    return DEFAULT_EVENT_PAGE_LIMIT;
+  if (!Number.isInteger(limit) || limit < 1)
+    throw new Error(`Event page limit must be a positive integer, got ${limit}`);
+  return Math.min(limit, MAX_EVENT_PAGE_LIMIT);
+}
+function queryEvents(events, options) {
+  let rows = events;
+  if (options.eventId)
+    rows = rows.filter((event) => event.id === options.eventId);
+  if (options.source)
+    rows = rows.filter((event) => event.source === options.source);
+  if (options.type)
+    rows = rows.filter((event) => event.type === options.type);
+  if (options.cursor) {
+    const offset = decodeLocalJsonEventCursor(options.cursor, options);
+    rows = rows.slice(offset);
+  }
+  if (options.limit !== undefined)
+    rows = rows.slice(0, normalizeEventPageLimit(options.limit));
+  return rows;
+}
+function assertCursorFilter(name, cursorValue, optionValue) {
+  if (cursorValue !== optionValue)
+    throw new Error(`Local JSON event cursor ${name} filter mismatch`);
+}
+function findEventByIdentity(events, identity) {
+  return events.find((event) => identity.id !== undefined && event.id === identity.id || identity.dedupeKey !== undefined && event.dedupeKey === identity.dedupeKey);
+}
+async function getEventsStatus(dataDir) {
+  const store = new JsonEventsStore(dataDir);
+  await store.init();
+  const [channels, events, deliveries] = await Promise.all([
+    store.listChannels(),
+    store.listEvents(),
+    store.listDeliveries()
+  ]);
+  const transports = channels.reduce((counts, channel) => {
+    counts[channel.transport] = (counts[channel.transport] ?? 0) + 1;
+    return counts;
+  }, {});
+  return {
+    service: "events",
+    schemaVersion: "1.0",
+    dataDir: store.dataDir,
+    storage: store.runtime,
+    env: {
+      primary: HASNA_EVENTS_DIR_ENV,
+      fallback: HASNA_EVENTS_HOME_ENV,
+      active: getActiveEventsDirEnv()
+    },
+    files: {
+      channels: statusFile(store.dataDir, "channels.json", channels.length),
+      events: statusFile(store.dataDir, "events.json", events.length),
+      deliveries: statusFile(store.dataDir, "deliveries.json", deliveries.length)
+    },
+    counts: {
+      channels: channels.length,
+      enabledChannels: channels.filter((channel) => channel.enabled).length,
+      disabledChannels: channels.filter((channel) => !channel.enabled).length,
+      events: events.length,
+      deliveries: deliveries.length
+    },
+    transports,
+    safety: {
+      includesEventPayloads: false,
+      includesWebhookSecrets: false,
+      listOutputsRedactSecrets: true,
+      statusOutputIsMetadataOnly: true
+    }
+  };
+}
+function statusFile(dataDir, fileName, records) {
+  const path = join(dataDir, fileName);
+  return { path, exists: existsSync(path), records };
+}
 var DEFAULT_SIGNATURE_TOLERANCE_MS = 5 * 60 * 1000;
 function buildSignatureBase(timestamp, body) {
   return `${timestamp}.${body}`;
@@ -15564,21 +15829,27 @@ function now() {
 function truncate(value, max = 4096) {
   return value.length > max ? `${value.slice(0, max)}...` : value;
 }
-function buildWebhookRequest(event, channel) {
+function buildWebhookRequest(event, channel, options = {}) {
   if (!channel.webhook)
     throw new Error(`Channel ${channel.id} has no webhook config`);
+  for (const name of Object.keys(channel.webhook.headers ?? {})) {
+    if (/^x-hasna-/i.test(name)) {
+      throw new Error(`Webhook header ${name} is reserved for signed delivery metadata`);
+    }
+  }
   const body = JSON.stringify(event);
-  const timestamp = event.time;
+  const timestamp = options.timestamp ?? new Date().toISOString();
   const headers = {
     "Content-Type": "application/json",
     "User-Agent": "@hasna/events",
     "X-Hasna-Event-Id": event.id,
     "X-Hasna-Event-Type": event.type,
-    "X-Hasna-Timestamp": timestamp,
-    ...channel.webhook.headers
+    ...channel.webhook.headers,
+    "X-Hasna-Timestamp": timestamp
   };
-  if (channel.webhook.secret) {
-    headers["X-Hasna-Signature"] = signPayload(channel.webhook.secret, timestamp, body);
+  const secret = options.secret ?? channel.webhook.secret;
+  if (secret) {
+    headers["X-Hasna-Signature"] = signPayload(secret, timestamp, body);
   }
   return { body, headers };
 }
@@ -15586,7 +15857,21 @@ async function dispatchWebhook(event, channel, options = {}) {
   if (!channel.webhook)
     throw new Error(`Channel ${channel.id} has no webhook config`);
   const startedAt = now();
-  const { body, headers } = buildWebhookRequest(event, channel);
+  let secret = channel.webhook.secret;
+  if (channel.webhook.secretRef) {
+    if (!options.secretResolver) {
+      return failedAttempt(startedAt, "Webhook secret reference has no runtime resolver");
+    }
+    try {
+      secret = await options.secretResolver(channel.webhook.secretRef);
+    } catch {
+      return failedAttempt(startedAt, "Webhook secret reference could not be resolved");
+    }
+    if (!secret)
+      return failedAttempt(startedAt, "Webhook secret reference could not be resolved");
+  }
+  const timestamp = (options.now?.() ?? new Date).toISOString();
+  const { body, headers } = buildWebhookRequest(event, channel, { secret, timestamp });
   const controller = new AbortController;
   const timeout = setTimeout(() => controller.abort(), channel.webhook.timeoutMs ?? 15000);
   try {
@@ -15618,6 +15903,15 @@ async function dispatchWebhook(event, channel, options = {}) {
     clearTimeout(timeout);
   }
 }
+function failedAttempt(startedAt, error) {
+  return {
+    attempt: 1,
+    status: "failed",
+    startedAt,
+    completedAt: now(),
+    error
+  };
+}
 async function dispatchCommand(event, channel) {
   if (!channel.command)
     throw new Error(`Channel ${channel.id} has no command config`);
@@ -15706,6 +16000,90 @@ function createDeliveryResult(event, channel, attempts) {
     completedAt: attempts.at(-1)?.completedAt ?? now()
   };
 }
+
+class EventValidationError extends Error {
+  eventType;
+  issues;
+  constructor(eventType, issues) {
+    const detail = issues.map((issue) => `${issue.path || "<root>"}: ${issue.message}`).join("; ");
+    super(`Event validation failed for type "${eventType}": ${detail}`);
+    this.name = "EventValidationError";
+    this.eventType = eventType;
+    this.issues = issues;
+  }
+}
+
+class EventTypeCatalog {
+  definitions = new Map;
+  register(definition) {
+    this.definitions.set(definition.type, definition);
+    return this;
+  }
+  unregister(type) {
+    return this.definitions.delete(type);
+  }
+  has(type) {
+    return this.definitions.has(type);
+  }
+  get(type) {
+    return this.definitions.get(type);
+  }
+  list() {
+    return [...this.definitions.values()];
+  }
+  validateEvent(event) {
+    const definition = this.definitions.get(event.type);
+    if (!definition)
+      return { ok: true };
+    return definition.validate(event.data, event);
+  }
+  assertEventValid(event) {
+    const result = this.validateEvent(event);
+    if (!result.ok) {
+      throw new EventValidationError(event.type, result.issues);
+    }
+  }
+}
+var defaultEventTypeCatalog = new EventTypeCatalog;
+var APP_EVENT_V1_MAX_DATA_BYTES = 32 * 1024;
+function redactPaths(event, paths, replacement = "[REDACTED]") {
+  if (paths.length === 0)
+    return event;
+  const copy = structuredClone(event);
+  for (const path of paths) {
+    setPath(copy, path, replacement);
+  }
+  return copy;
+}
+function redactSensitiveKeys(event, replacement = "[REDACTED]") {
+  return redactValue(event, replacement);
+}
+function shouldRedactKey(key) {
+  return /secret|token|password|api[_-]?key|authorization/i.test(key);
+}
+function redactValue(value, replacement) {
+  if (Array.isArray(value))
+    return value.map((item) => redactValue(item, replacement));
+  if (!value || typeof value !== "object")
+    return value;
+  return Object.fromEntries(Object.entries(value).map(([key, item]) => [
+    key,
+    shouldRedactKey(key) ? replacement : redactValue(item, replacement)
+  ]));
+}
+function setPath(input, path, replacement) {
+  const parts = path.split(".");
+  let cursor = input;
+  for (const part of parts.slice(0, -1)) {
+    const next = cursor[part];
+    if (!next || typeof next !== "object")
+      return;
+    cursor = next;
+  }
+  const last = parts.at(-1);
+  if (last && last in cursor)
+    cursor[last] = replacement;
+}
 function createEvent(input) {
   return {
     id: input.id ?? randomUUID2(),
@@ -15726,10 +16104,18 @@ class EventsClient {
   store;
   redactors;
   transportOptions;
+  catalog;
+  validateCatalogTypes;
   constructor(options = {}) {
     this.store = options.store ?? new JsonEventsStore(options.dataDir);
     this.redactors = options.redactors ?? [];
-    this.transportOptions = { fetchImpl: options.fetchImpl };
+    this.transportOptions = {
+      fetchImpl: options.fetchImpl,
+      secretResolver: options.secretResolver,
+      now: options.now
+    };
+    this.catalog = options.catalog ?? defaultEventTypeCatalog;
+    this.validateCatalogTypes = options.validateCatalogTypes ?? false;
   }
   async addChannel(input) {
     const timestamp = new Date().toISOString();
@@ -15747,18 +16133,40 @@ class EventsClient {
   }
   async emit(input, options = {}) {
     const event = options.redactSensitiveData === false ? createEvent(input) : redactSensitiveKeys(createEvent(input));
-    if (options.dedupe !== false) {
-      const existing = await this.store.findEventByIdentity({ id: input.id, dedupeKey: event.dedupeKey });
-      if (existing) {
-        return { event: existing, deliveries: [], deduped: true };
-      }
-    }
-    await this.store.appendEvent(event);
-    const deliveries = options.deliver === false ? [] : await this.deliver(event);
-    return { event, deliveries, deduped: false };
-  }
-  async listEvents() {
-    return this.store.listEvents();
+    if (options.validate ?? this.validateCatalogTypes) {
+      this.catalog.assertEventValid(event);
+    }
+    const append = await this.appendEvent(event, { dedupe: options.dedupe !== false });
+    if (append.deduped) {
+      return { event: append.event, deliveries: [], deduped: true };
+    }
+    const deliveries = options.deliver === false ? [] : await this.deliver(append.event);
+    return { event: append.event, deliveries, deduped: false };
+  }
+  async listEvents(options = {}) {
+    if (Object.keys(options).length === 0)
+      return this.store.listEvents();
+    return queryClientEvents(await this.store.listEvents(), options);
+  }
+  async listEventsPage(options = {}) {
+    if (this.store.listEventsPage)
+      return this.store.listEventsPage(options);
+    const events = queryClientEvents(await this.store.listEvents(), {
+      eventId: options.eventId,
+      source: options.source,
+      type: options.type
+    });
+    const offset = decodeLocalJsonEventCursor(options.cursor, options);
+    const limit = normalizeEventPageLimit(options.limit);
+    const pageEvents = events.slice(offset, offset + limit);
+    const nextOffset = offset + pageEvents.length;
+    const hasMore = nextOffset < events.length;
+    return {
+      events: pageEvents,
+      cursor: options.cursor,
+      nextCursor: hasMore ? encodeLocalJsonEventCursor(nextOffset, options) : undefined,
+      hasMore
+    };
   }
   async listDeliveries() {
     return this.store.listDeliveries();
@@ -15775,7 +16183,7 @@ class EventsClient {
     }
     return deliveries;
   }
-  async testChannel(id, input = {}) {
+  async matchChannel(id, input = {}) {
     const channel = await this.store.getChannel(id);
     if (!channel)
       throw new Error(`Channel not found: ${id}`);
@@ -15792,28 +16200,71 @@ class EventsClient {
       time: input.time,
       id: input.id
     });
+    const matched = channelMatchesEvent(channel, event);
+    return {
+      channelId: channel.id,
+      matched,
+      event,
+      filters: channel.filters,
+      reason: matched ? undefined : channel.enabled ? "event did not match channel filters" : "channel is disabled"
+    };
+  }
+  async testChannel(id, input = {}, options = {}) {
+    const channel = await this.store.getChannel(id);
+    if (!channel)
+      throw new Error(`Channel not found: ${id}`);
+    const match = await this.matchChannel(id, input);
+    const event = match.event;
+    if (options.honorFilters && !match.matched) {
+      const timestamp = new Date().toISOString();
+      const result2 = createDeliveryResult(event, channel, [{
+        attempt: 1,
+        status: "skipped",
+        startedAt: timestamp,
+        completedAt: timestamp,
+        error: match.reason
+      }]);
+      result2.metadata = { reason: "filter_mismatch" };
+      await this.store.appendDelivery(result2);
+      return result2;
+    }
     const eventForChannel = await this.applyRedaction(event, channel);
     const result = await this.deliverWithRetry(eventForChannel, channel);
     await this.store.appendDelivery(result);
     return result;
   }
   async replay(options = {}) {
-    const events = (await this.store.listEvents()).filter((event) => {
-      if (options.eventId && event.id !== options.eventId)
-        return false;
-      if (options.source && event.source !== options.source)
-        return false;
-      if (options.type && event.type !== options.type)
-        return false;
-      return true;
-    });
+    const page = options.cursor || options.limit !== undefined ? await this.listEventsPage(options) : { events: await this.listEvents(options), hasMore: false };
     if (options.dryRun)
-      return { events, deliveries: [] };
+      return { events: page.events, deliveries: [], cursor: page.cursor, nextCursor: page.nextCursor, hasMore: page.hasMore };
     const deliveries = [];
-    for (const event of events) {
+    for (const event of page.events) {
       deliveries.push(...await this.deliver(event));
     }
-    return { events, deliveries };
+    return { events: page.events, deliveries, cursor: page.cursor, nextCursor: page.nextCursor, hasMore: page.hasMore };
+  }
+  async appendEvent(event, options) {
+    if (this.store.appendEventOnce) {
+      return this.store.appendEventOnce(event, { dedupe: options.dedupe });
+    }
+    if (options.dedupe) {
+      const existing = await this.store.findEventByIdentity({ id: event.id, dedupeKey: event.dedupeKey });
+      if (existing) {
+        return {
+          event: existing,
+          stored: false,
+          deduped: true,
+          identity: { id: existing.id, dedupeKey: existing.dedupeKey }
+        };
+      }
+    }
+    const stored = await this.store.appendEvent(event);
+    return {
+      event: stored,
+      stored: true,
+      deduped: false,
+      identity: { id: stored.id, dedupeKey: stored.dedupeKey }
+    };
   }
   async applyRedaction(event, channel) {
     let next = redactPaths(event, channel.redact?.paths ?? [], channel.redact?.replacement ?? "[REDACTED]");
@@ -15840,15 +16291,6 @@ class EventsClient {
     return createDeliveryResult(event, channel, attempts);
   }
 }
-function redactPaths(event, paths, replacement = "[REDACTED]") {
-  if (paths.length === 0)
-    return event;
-  const copy = structuredClone(event);
-  for (const path of paths) {
-    setPath(copy, path, replacement);
-  }
-  return copy;
-}
 function sanitizeChannelForOutput(channel) {
   const copy = structuredClone(channel);
   if (copy.webhook?.secret)
@@ -15861,34 +16303,19 @@ function sanitizeChannelForOutput(channel) {
 function sanitizeChannelsForOutput(channels) {
   return channels.map(sanitizeChannelForOutput);
 }
-function redactSensitiveKeys(event, replacement = "[REDACTED]") {
-  return redactValue(event, replacement);
-}
-function shouldRedactKey(key) {
-  return /secret|token|password|api[_-]?key|authorization/i.test(key);
-}
-function redactValue(value, replacement) {
-  if (Array.isArray(value))
-    return value.map((item) => redactValue(item, replacement));
-  if (!value || typeof value !== "object")
-    return value;
-  return Object.fromEntries(Object.entries(value).map(([key, item]) => [
-    key,
-    shouldRedactKey(key) ? replacement : redactValue(item, replacement)
-  ]));
-}
-function setPath(input, path, replacement) {
-  const parts = path.split(".");
-  let cursor = input;
-  for (const part of parts.slice(0, -1)) {
-    const next = cursor[part];
-    if (!next || typeof next !== "object")
-      return;
-    cursor = next;
-  }
-  const last = parts.at(-1);
-  if (last && last in cursor)
-    cursor[last] = replacement;
+function queryClientEvents(events, options) {
+  let rows = events;
+  if (options.eventId)
+    rows = rows.filter((event) => event.id === options.eventId);
+  if (options.source)
+    rows = rows.filter((event) => event.source === options.source);
+  if (options.type)
+    rows = rows.filter((event) => event.type === options.type);
+  if (options.cursor)
+    rows = rows.slice(decodeLocalJsonEventCursor(options.cursor, options));
+  if (options.limit !== undefined)
+    rows = rows.slice(0, normalizeEventPageLimit(options.limit));
+  return rows;
 }
 function normalizeTime(value) {
   if (!value)
@@ -15902,6 +16329,77 @@ function normalizeRetryPolicy(policy) {
     multiplier: Math.max(1, policy?.multiplier ?? 2)
   };
 }
+function parseFieldMatchers(values, label, typed = false) {
+  if (!values?.length)
+    return;
+  const result = {};
+  for (const value of values) {
+    const parsed = parseMatcherExpression(value, label);
+    const path = parsed.path;
+    if (path in result)
+      throw new Error(`Duplicate ${label} filter path: ${path}`);
+    const matcherValue = typed ? parseTypedMatcherValue(parsed.rawValue, label) : parsed.rawValue;
+    result[path] = parsed.negated ? { not: matcherValue } : matcherValue;
+  }
+  return result;
+}
+function parseFilterOptions(options) {
+  const filter2 = {};
+  if (options.source)
+    filter2.source = options.source;
+  if (options.type)
+    filter2.type = options.type;
+  if (options.subject)
+    filter2.subject = options.subject;
+  if (options.severity)
+    filter2.severity = options.severity;
+  const data = mergeMatchers(parseFieldMatchers(options.data, "data"), parseFieldMatchers(options.dataJson, "data-json", true));
+  const metadata = mergeMatchers(parseFieldMatchers(options.metadata, "metadata"), parseFieldMatchers(options.metadataJson, "metadata-json", true));
+  if (Object.keys(data).length > 0)
+    filter2.data = data;
+  if (Object.keys(metadata).length > 0)
+    filter2.metadata = metadata;
+  return Object.keys(filter2).length > 0 ? [filter2] : undefined;
+}
+function mergeMatchers(...records) {
+  const result = {};
+  for (const record of records) {
+    if (!record)
+      continue;
+    for (const [path, value] of Object.entries(record)) {
+      if (path in result)
+        throw new Error(`Duplicate filter path: ${path}`);
+      result[path] = value;
+    }
+  }
+  return result;
+}
+function parseTypedMatcherValue(value, label) {
+  const parsed = JSON.parse(value);
+  if (parsed === null || typeof parsed === "string" || typeof parsed === "number" || typeof parsed === "boolean" || Array.isArray(parsed) && parsed.every((item) => typeof item === "string")) {
+    return parsed;
+  }
+  throw new Error(`${label} filter JSON values must be string, string[], number, boolean, or null`);
+}
+function parseMatcherExpression(value, label) {
+  const negativeSeparator = value.indexOf("!=");
+  if (negativeSeparator > 0) {
+    return {
+      path: value.slice(0, negativeSeparator),
+      rawValue: value.slice(negativeSeparator + 2),
+      negated: true
+    };
+  }
+  const separator = value.indexOf("=");
+  if (separator <= 0)
+    throw new Error(`Invalid ${label} filter, expected path=value or path!=value: ${value}`);
+  return {
+    path: value.slice(0, separator),
+    rawValue: value.slice(separator + 1),
+    negated: false
+  };
+}
+var DEFAULT_EVENT_LIST_LIMIT = 100;
 function parseJsonObject(value, fallback) {
   if (!value)
     return fallback;
@@ -15923,18 +16421,6 @@ function parseHeaders(values) {
   }
   return headers;
 }
-function parseFilter(options) {
-  const filter2 = {};
-  if (options.source)
-    filter2.source = options.source;
-  if (options.type)
-    filter2.type = options.type;
-  if (options.subject)
-    filter2.subject = options.subject;
-  if (options.severity)
-    filter2.severity = options.severity;
-  return Object.keys(filter2).length > 0 ? [filter2] : undefined;
-}
 function createClient(options) {
   if (options.createClient)
     return options.createClient();
@@ -15946,22 +16432,30 @@ function print(value, json, text) {
   else
     console.log(text);
 }
+function fail(error, json) {
+  const message = error instanceof Error ? error.message : String(error);
+  if (json)
+    console.log(JSON.stringify({ error: message }, null, 2));
+  else
+    console.error(message);
+  process.exitCode = 1;
+}
 function hasJsonOption(options) {
   return Boolean(options?.json || options?.opts?.().json || options?.optsWithGlobals?.().json || options?.parent?.opts?.().json || options?.parent?.optsWithGlobals?.().json);
 }
 function wantsJson(actionOptions, command) {
   return hasJsonOption(actionOptions) || hasJsonOption(command);
 }
-function registerWebhookCommands(program, options) {
-  const webhooks = program.command(options.webhooksCommandName ?? "webhooks").description("Manage Hasna event webhook subscriptions");
-  webhooks.command("add").description("Add or replace a webhook or command subscription").argument("<target>", "Webhook URL or command binary").requiredOption("--id <id>", "Subscription/channel identifier").option("--transport <kind>", "Transport kind: webhook or command", "webhook").option("--name <name>", "Display name").option("--type <pattern>", "Event type filter, e.g. todos.task.*").option("--source <pattern>", "Event source filter").option("--subject <pattern>", "Event subject filter").option("--severity <pattern>", "Event severity filter").option("--secret <secret>", "Webhook HMAC secret").option("--header <name=value...>", "Webhook header", collectValues, []).option("--arg <arg...>", "Command argument", collectValues, []).option("--timeout-ms <ms>", "Transport timeout in milliseconds", parseNumber).option("--retry-attempts <n>", "Maximum delivery attempts", parseNumber).option("--retry-backoff-ms <ms>", "Initial retry backoff in milliseconds", parseNumber).option("--redact <path...>", "Event field path to redact before delivery", collectValues, []).option("--disabled", "Create channel disabled", false).option("-j, --json", "Print JSON output", false).action(async (target, actionOptions, command) => {
+function registerChannelCommands(program, options) {
+  const channels = program.command(options.channelsCommandName ?? "channels").description("Manage Hasna event channels");
+  channels.command("add").description("Add or replace a channel").argument("<target>", "Webhook URL or command binary").requiredOption("--id <id>", "Channel identifier").option("--transport <kind>", "Transport kind: webhook or command", "webhook").option("--name <name>", "Display name").option("--type <pattern>", "Event type filter, e.g. todos.task.*").option("--source <pattern>", "Event source filter").option("--subject <pattern>", "Event subject filter").option("--severity <pattern>", "Event severity filter").option("--data <path=value...>", "Event data field filter; string values, path!=value negatives, array-member matching, dot paths, * segment wildcard, ** recursive wildcard", collectValues, []).option("--metadata <path=value...>", "Event metadata field filter; string values, path!=value negatives, array-member matching, dot paths, * segment wildcard, ** recursive wildcard", collectValues, []).option("--data-json <path=json...>", "Event data field filter with typed JSON value; path!=json negatives supported", collectValues, []).option("--metadata-json <path=json...>", "Event metadata field filter with typed JSON value; path!=json negatives supported", collectValues, []).option("--secret <secret>", "Webhook HMAC secret").option("--header <name=value...>", "Webhook header", collectValues, []).option("--arg <arg...>", "Command argument", collectValues, []).option("--timeout-ms <ms>", "Transport timeout in milliseconds", parseNumber).option("--retry-attempts <n>", "Maximum delivery attempts", parseNumber).option("--retry-backoff-ms <ms>", "Initial retry backoff in milliseconds", parseNumber).option("--redact <path...>", "Event field path to redact before delivery", collectValues, []).option("--disabled", "Create channel disabled", false).option("-j, --json", "Print JSON output", false).action(async (target, actionOptions, command) => {
     const timestamp = new Date().toISOString();
     const channel = {
       id: actionOptions.id,
       name: actionOptions.name,
       enabled: !actionOptions.disabled,
       transport: actionOptions.transport,
-      filters: parseFilter(actionOptions),
+      filters: parseFilterOptions(actionOptions),
       retry: actionOptions.retryAttempts || actionOptions.retryBackoffMs ? { maxAttempts: actionOptions.retryAttempts, backoffMs: actionOptions.retryBackoffMs } : undefined,
       redact: actionOptions.redact?.length ? { paths: actionOptions.redact } : undefined,
       createdAt: timestamp,
@@ -15977,35 +16471,61 @@ function registerWebhookCommands(program, options) {
     const saved = await createClient(options).addChannel(channel);
     print(sanitizeChannelForOutput(saved), wantsJson(actionOptions, command), `Added ${saved.transport} channel ${saved.id}`);
   });
-  webhooks.command("list").description("List configured subscriptions").option("-j, --json", "Print JSON output", false).action(async (actionOptions, command) => {
-    const channels = await createClient(options).listChannels();
+  channels.command("list").description("List configured channels").option("-j, --json", "Print JSON output", false).action(async (actionOptions, command) => {
+    const channels2 = await createClient(options).listChannels();
     if (wantsJson(actionOptions, command)) {
-      console.log(JSON.stringify(sanitizeChannelsForOutput(channels), null, 2));
+      console.log(JSON.stringify(sanitizeChannelsForOutput(channels2), null, 2));
       return;
     }
-    if (!channels.length) {
+    if (!channels2.length) {
       console.log("No channels configured.");
       return;
     }
-    for (const channel of channels) {
+    for (const channel of channels2) {
       console.log(`${channel.id}	${channel.enabled ? "enabled" : "disabled"}	${channel.transport}	${channel.webhook?.url ?? channel.command?.command ?? channel.transport}`);
     }
   });
-  webhooks.command("remove").description("Remove a subscription").argument("<id>", "Subscription/channel identifier").option("-j, --json", "Print JSON output", false).action(async (id, actionOptions, command) => {
+  channels.command("status").description("Show events channel storage status").option("-j, --json", "Print JSON output", false).action(async (actionOptions, command) => {
+    const status = await getEventsStatus(options.dataDir);
+    print(status, wantsJson(actionOptions, command), `events dataDir: ${status.dataDir}`);
+  });
+  channels.command("remove").description("Remove a channel").argument("<id>", "Channel identifier").option("-j, --json", "Print JSON output", false).action(async (id, actionOptions, command) => {
     const removed = await createClient(options).removeChannel(id);
     print({ removed }, wantsJson(actionOptions, command), removed ? `Removed ${id}` : `Channel not found: ${id}`);
   });
-  webhooks.command("test").description("Send a test event to one subscription").argument("<id>", "Subscription/channel identifier").option("--type <type>", "Event type", "events.test").option("--subject <subject>", "Event subject").option("--message <message>", "Event message", "Hasna events test delivery").option("--data <json>", "Event data JSON object").option("-j, --json", "Print JSON output", false).action(async (id, actionOptions, command) => {
-    const result = await createClient(options).testChannel(id, {
-      source: options.source,
-      type: actionOptions.type,
-      subject: actionOptions.subject ?? id,
-      message: actionOptions.message,
-      data: parseJsonObject(actionOptions.data, { test: true })
-    });
-    print(result, wantsJson(actionOptions, command), `${result.status}: ${result.channelId}`);
+  channels.command("test").description("Send a test event to one channel").argument("<id>", "Channel identifier").option("--source <source>", "Event source override").option("--type <type>", "Event type", "events.test").option("--subject <subject>", "Event subject").option("--message <message>", "Event message", "Hasna events test delivery").option("--data <json>", "Event data JSON object").option("--metadata <json>", "Event metadata JSON object").option("--honor-filters", "Skip delivery when the sample event does not match channel filters", false).option("-j, --json", "Print JSON output", false).action(async (id, actionOptions, command) => {
+    const json = wantsJson(actionOptions, command);
+    try {
+      const result = await createClient(options).testChannel(id, {
+        source: actionOptions.source ?? options.source,
+        type: actionOptions.type,
+        subject: actionOptions.subject ?? id,
+        message: actionOptions.message,
+        data: parseJsonObject(actionOptions.data, { test: true }),
+        metadata: parseJsonObject(actionOptions.metadata, {})
+      }, { honorFilters: actionOptions.honorFilters });
+      print(result, json, `${result.status}: ${result.channelId}`);
+    } catch (error) {
+      fail(error, json);
+    }
+  });
+  channels.command("match").description("Check whether a sample event matches one channel without delivering").argument("<id>", "Channel identifier").option("--source <source>", "Event source override").option("--type <type>", "Event type", "events.test").option("--subject <subject>", "Event subject").option("--message <message>", "Event message", "Hasna events match preview").option("--data <json>", "Event data JSON object").option("--metadata <json>", "Event metadata JSON object").option("-j, --json", "Print JSON output", false).action(async (id, actionOptions, command) => {
+    const json = wantsJson(actionOptions, command);
+    try {
+      const result = await createClient(options).matchChannel(id, {
+        source: actionOptions.source ?? options.source,
+        type: actionOptions.type,
+        subject: actionOptions.subject ?? id,
+        message: actionOptions.message,
+        data: parseJsonObject(actionOptions.data, { test: true }),
+        metadata: parseJsonObject(actionOptions.metadata, {})
+      });
+      print(result, json, `${result.matched ? "matched" : "skipped"}: ${result.channelId}`);
+    } catch (error) {
+      fail(error, json);
+    }
   });
-  return webhooks;
+  return channels;
 }
 function registerEventCommands(program, options) {
   const events = program.command(options.eventsCommandName ?? "events").description("Emit, list, and replay Hasna events");
@@ -16022,7 +16542,8 @@ function registerEventCommands(program, options) {
     }, { deliver: actionOptions.deliver, dedupe: actionOptions.dedupe });
     print(result, wantsJson(actionOptions, command), `${result.deduped ? "Deduped" : "Emitted"} ${result.event.id} to ${result.deliveries.length} channel(s)`);
   });
-  events.command("list").description("List recorded events").option("--source <source>", "Filter by source").option("--type <type>", "Filter by type").option("--limit <n>", "Limit results", parseNumber).option("-j, --json", "Print JSON output", false).action(async (actionOptions, command) => {
+  const defaultListLimit = options.defaultEventListLimit ?? DEFAULT_EVENT_LIST_LIMIT;
+  events.command("list").description("List recorded events").option("--source <source>", "Filter by source").option("--type <type>", "Filter by type").option("--limit <n>", `Limit to the most recent <n> events (default ${defaultListLimit}; use 0 for all)`, parseNumber, defaultListLimit).option("-j, --json", "Print JSON output", false).action(async (actionOptions, command) => {
     let rows = await createClient(options).listEvents();
     if (actionOptions.source)
       rows = rows.filter((event) => event.source === actionOptions.source);
@@ -16041,19 +16562,21 @@ function registerEventCommands(program, options) {
     for (const event of rows)
       console.log(`${event.time}	${event.id}	${event.source}	${event.type}	${event.severity}`);
   });
-  events.command("replay").description("Replay recorded events").option("--id <id>", "Replay one event id").option("--source <source>", "Filter by source").option("--type <type>", "Filter by type").option("--dry-run", "Preview without delivery", false).option("-j, --json", "Print JSON output", false).action(async (actionOptions, command) => {
+  events.command("replay").description("Replay recorded events").option("--id <id>", "Replay one event id").option("--source <source>", "Filter by source").option("--type <type>", "Filter by type").option("--cursor <cursor>", "Opaque replay cursor from a previous page").option("--limit <n>", "Maximum events to replay", parseNumber).option("--dry-run", "Preview without delivery", false).option("-j, --json", "Print JSON output", false).action(async (actionOptions, command) => {
     const result = await createClient(options).replay({
       eventId: actionOptions.id,
       source: actionOptions.source,
       type: actionOptions.type,
+      cursor: actionOptions.cursor,
+      limit: actionOptions.limit,
       dryRun: actionOptions.dryRun
     });
-    print(result, wantsJson(actionOptions, command), `Replayed ${result.events.length} event(s), ${result.deliveries.length} delivery result(s)`);
+    print(result, wantsJson(actionOptions, command), replaySummary(result.events.length, result.deliveries.length, result.nextCursor));
   });
   return events;
 }
 function registerEventsCommands(program, options) {
-  registerWebhookCommands(program, options);
+  registerChannelCommands(program, options);
   registerEventCommands(program, options);
 }
 function parseNumber(value) {
@@ -16066,8 +16589,12 @@ function collectValues(value, previous) {
   previous.push(value);
   return previous;
 }
+function replaySummary(events, deliveries, nextCursor) {
+  const suffix = nextCursor ? `, next cursor: ${nextCursor}` : "";
+  return `Replayed ${events} event(s), ${deliveries} delivery result(s)${suffix}`;
+}
 
-// node_modules/commander/esm.mjs
+// ../../node_modules/.bun/commander@13.1.0/node_modules/commander/esm.mjs
 var import__ = __toESM(require_commander(), 1);
 var {
   program,
@@ -18384,10 +18911,10 @@ program.command("import <file>").description("Import configs from a tar.gz bundl
 });
 program.command("whoami").description("Show setup summary").action(async () => {
   const store = resolveConfigStore();
-  const dbPath = isCloudMode() ? `${process.env["HASNA_INSTRUCTIONS_API_URL"]}/v1 (self_hosted)` : process.env["HASNA_INSTRUCTIONS_DB_PATH"] || join16(homedir8(), ".hasna", "instructions", "instructions.db");
+  const dbPath = isApiTransport() ? `${process.env["HASNA_INSTRUCTIONS_API_URL"]}/v1` : process.env["HASNA_INSTRUCTIONS_DB_PATH"] || join16(homedir8(), ".hasna", "instructions", "instructions.db");
   const stats = await store.getConfigStats();
   console.log(chalk.bold("@hasna/instructions") + chalk.dim(" v" + pkg.version));
-  console.log(chalk.cyan(isCloudMode() ? "API:" : "DB:") + " " + dbPath);
+  console.log(chalk.cyan(isApiTransport() ? "API:" : "DB:") + " " + dbPath);
   console.log(chalk.cyan("Total configs:") + " " + (stats["total"] || 0));
   console.log();
   console.log(chalk.bold("By category:"));
@@ -19229,9 +19756,9 @@ DB stats:`));
     if (count > 0)
       console.log(`  ${key.padEnd(18)} ${count}`);
   }
-  const location = isCloudMode() ? `${process.env["HASNA_INSTRUCTIONS_API_URL"]}/v1 (self_hosted)` : process.env["HASNA_INSTRUCTIONS_DB_PATH"] || join16(homedir8(), ".hasna", "instructions", "instructions.db");
+  const location = isApiTransport() ? `${process.env["HASNA_INSTRUCTIONS_API_URL"]}/v1` : process.env["HASNA_INSTRUCTIONS_DB_PATH"] || join16(homedir8(), ".hasna", "instructions", "instructions.db");
   console.log(chalk.dim(`
-${isCloudMode() ? "API" : "DB"}: ${location}`));
+${isApiTransport() ? "API" : "DB"}: ${location}`));
 });
 program.command("status").description("Health check: total configs, drift from disk, unredacted secrets").option("--json", "output metadata-only JSON").action(async (opts) => {
   const status = await getConfigsStatus(resolveConfigStore());
@@ -19272,7 +19799,7 @@ program.command("doctor").description("Validate configs: syntax, permissions, mi
   const store = resolveConfigStore();
   let issues = 0;
   const pass = (msg) => console.log(chalk.green("  \u2713 ") + msg);
-  const fail = (msg) => {
+  const fail2 = (msg) => {
     issues++;
     console.log(chalk.red("  \u2717 ") + msg);
   };
@@ -19282,9 +19809,9 @@ program.command("doctor").description("Validate configs: syntax, permissions, mi
   console.log(chalk.cyan("Known files on disk:"));
   for (const k of KNOWN_CONFIGS) {
     if (k.rulesDir) {
-      existsSync16(expandPath(k.rulesDir)) ? pass(`${k.rulesDir}/ exists`) : k.optional ? skip(`${k.rulesDir}/ (optional)`) : fail(`${k.rulesDir}/ not found`);
+      existsSync16(expandPath(k.rulesDir)) ? pass(`${k.rulesDir}/ exists`) : k.optional ? skip(`${k.rulesDir}/ (optional)`) : fail2(`${k.rulesDir}/ not found`);
     } else {
-      existsSync16(expandPath(k.path)) ? pass(k.path) : k.optional ? skip(`${k.path} (optional)`) : fail(`${k.path} not found`);
+      existsSync16(expandPath(k.path)) ? pass(k.path) : k.optional ? skip(`${k.path} (optional)`) : fail2(`${k.path} not found`);
     }
   }
   const allConfigs = await store.listConfigs();
@@ -19297,7 +19824,7 @@ Stored configs (${allConfigs.length}):`));
         JSON.parse(c.content);
         validCount++;
       } catch {
-        fail(`${c.slug}: invalid JSON`);
+        fail2(`${c.slug}: invalid JSON`);
       }
     } else {
       validCount++;
@@ -19309,13 +19836,13 @@ Stored configs (${allConfigs.length}):`));
     const found = scanSecrets(c.content, c.format);
     secretCount += found.length;
   }
-  secretCount === 0 ? pass("No unredacted secrets") : fail(`${secretCount} unredacted secret(s) \u2014 run \`configs scan --fix\``);
+  secretCount === 0 ? pass("No unredacted secrets") : fail2(`${secretCount} unredacted secret(s) \u2014 run \`configs scan --fix\``);
   const duplicateTargets = findDuplicateTargetPathGroups(allConfigs);
   if (duplicateTargets.length === 0) {
     pass("No target path is claimed by more than one config");
   } else {
     const rowCount = duplicateTargets.reduce((total, group) => total + group.configs.length, 0);
-    fail(`${duplicateTargets.length} target path(s) claimed by more than one config (${rowCount} rows) \u2014 apply order between them is undefined`);
+    fail2(`${duplicateTargets.length} target path(s) claimed by more than one config (${rowCount} rows) \u2014 apply order between them is undefined`);
     for (const group of duplicateTargets) {
       console.log(chalk.yellow(`      ${group.target_path}`));
       for (const c of group.configs) {
@@ -19329,7 +19856,7 @@ Stored configs (${allConfigs.length}):`));
     pass("No reference config name is claimed by more than one row");
   } else {
     const rowCount = duplicateReferenceNames.reduce((total, group) => total + group.configs.length, 0);
-    fail(`${duplicateReferenceNames.length} reference name(s) claimed by more than one row (${rowCount} rows) \u2014 only one is live in the next render`);
+    fail2(`${duplicateReferenceNames.length} reference name(s) claimed by more than one row (${rowCount} rows) \u2014 only one is live in the next render`);
     for (const group of duplicateReferenceNames) {
       console.log(chalk.yellow(`      ${group.name}`));
       for (const c of group.configs) {