@mulmoclaude/core 0.2.9 → 0.2.10

package/dist/feeds/server/retrievers/index.d.ts

@@ -0,0 +1,12 @@
+import { CollectionItem, CollectionSchema } from '../../../collection/index.js';
+import { DeclarativeIngestSpec } from '../../ingestTypes.js';
+import { FeedState } from '../state.js';
+export interface RetrieveResult {
+    /** Projected records, keyed by primaryKey (the engine upserts them). */
+    items: CollectionItem[];
+    /** Updated retriever cursor to persist (incremental fetches). */
+    cursor: Record<string, string>;
+}
+export type RetrieveFn = (ingest: DeclarativeIngestSpec, schema: CollectionSchema, state: FeedState) => Promise<RetrieveResult>;
+export declare function registerRetriever(kind: string, retriever: RetrieveFn): void;
+export declare function getRetriever(kind: string): RetrieveFn | undefined;

package/dist/feeds/server/retrievers/rss.d.ts

@@ -0,0 +1,3 @@
+import { RetrieveFn } from './index.js';
+declare const retrieveRss: RetrieveFn;
+export { retrieveRss };

package/dist/feeds/server/scheduledRefresh.d.ts

@@ -1,6 +1,6 @@
 import { SystemTaskDef } from '../../scheduler/adapter.js';
 export declare const FEED_REFRESH_TASK_ID = "system:feed-refresh";
-export declare const DEFAULT_FEED_REFRESH_INTERVAL_MS = 3600000;
+export declare const DEFAULT_FEED_REFRESH_INTERVAL_MS: number;
 /**
  * The hourly "refresh due collections" task, shared by every host.
  *

package/dist/file-change/index.cjs

@@ -0,0 +1,72 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_rolldown_runtime = require("../rolldown-runtime-D6vf50IK.cjs");
+let node_path = require("node:path");
+node_path = require_rolldown_runtime.__toESM(node_path, 1);
+let node_fs_promises = require("node:fs/promises");
+//#region src/file-change/index.ts
+var config = null;
+/** Wire the publisher to a host. Call once at startup, before any write route. */
+function configureFileChangePublisher(cfg) {
+	config = cfg;
+}
+/** Clear the binding — test-only. */
+function resetFileChangePublisher() {
+	config = null;
+}
+/** The plugin-scoped live-refresh channel a View subscribes to. */
+function pluginFileChannel(scope, posixPath) {
+	return `plugin:${scope}:file:${posixPath}`;
+}
+/** Publish a file-change for a workspace-relative path: the primary channel (if any)
+*  + every matching plugin scope, with the post-write mtime. No-op until configured. */
+async function publishFileChange(relativePath) {
+	const cfg = config;
+	if (!cfg) return;
+	const root = node_path.default.resolve(cfg.workspaceRoot) + node_path.default.sep;
+	const absPath = node_path.default.join(root, relativePath);
+	if (!absPath.startsWith(root)) {
+		cfg.warn?.("ignoring file-change for path outside workspace", { path: relativePath });
+		return;
+	}
+	let mtimeMs;
+	try {
+		({mtimeMs} = await (0, node_fs_promises.stat)(absPath));
+	} catch (err) {
+		cfg.warn?.("stat failed; falling back to Date.now()", {
+			path: relativePath,
+			error: errMsg(err)
+		});
+		mtimeMs = Date.now();
+	}
+	const posixPath = cfg.toPosix(relativePath);
+	const payload = {
+		path: posixPath,
+		mtimeMs
+	};
+	if (cfg.primaryChannel) safePublish(cfg, cfg.primaryChannel(posixPath), payload, "primary publish failed");
+	for (const { scope, matches } of cfg.pluginScopes ?? []) {
+		if (!matches(posixPath)) continue;
+		safePublish(cfg, pluginFileChannel(scope, posixPath), payload, `${scope} plugin forward failed`);
+	}
+	cfg.onPublished?.(posixPath, payload);
+}
+function safePublish(cfg, channel, payload, failMsg) {
+	try {
+		cfg.publish(channel, payload);
+	} catch (err) {
+		cfg.warn?.(`${failMsg}; subscribers will miss this event`, {
+			channel,
+			error: errMsg(err)
+		});
+	}
+}
+function errMsg(err) {
+	return err instanceof Error ? err.message : String(err);
+}
+//#endregion
+exports.configureFileChangePublisher = configureFileChangePublisher;
+exports.pluginFileChannel = pluginFileChannel;
+exports.publishFileChange = publishFileChange;
+exports.resetFileChangePublisher = resetFileChangePublisher;
+
+//# sourceMappingURL=index.cjs.map

package/dist/file-change/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":[],"sources":["../../src/file-change/index.ts"],"sourcesContent":["// @mulmoclaude/core/file-change — shared \"this workspace file changed\"\n// broadcaster. A host write route calls `publishFileChange(relPath)` after a\n// successful write; subscribed UI tabs refetch. Extracted so MulmoClaude and\n// MulmoTerminal forward to the SAME plugin-scoped channels (the live-refresh\n// contract the markdown/html Views subscribe to) without duplicating the logic.\n//\n// Everything host-specific is INJECTED via `configureFileChangePublisher` (the\n// pubsub, the workspace root, the path→posix normaliser, the host's own primary\n// channel, the plugin-scope matchers, and any side-effect), so this package owns\n// only the orchestration + the `plugin:<scope>:file:<path>` channel format and\n// touches neither host's pubsub-channel config nor its frontend subscribers.\nimport { stat } from \"node:fs/promises\";\nimport path from \"node:path\";\n\n/** Payload published on every file-change channel. `mtimeMs` is the post-write\n *  modified time — monotonic, suitable for cache-busting (`?v=`) and out-of-order\n *  drops. */\nexport interface FileChannelPayload {\n  path: string;\n  mtimeMs: number;\n}\n\n/** A plugin View that wants live-refresh: when `matches(posixPath)` is true, the\n *  change is forwarded to `plugin:<scope>:file:<path>` (the channel the View's\n *  runtime subscribes to). */\nexport interface FileChangeScope {\n  scope: string;\n  matches: (posixPath: string) => boolean;\n}\n\nexport interface FileChangePublisherConfig {\n  /** Host pubsub publish. */\n  publish: (channel: string, payload: FileChannelPayload) => void;\n  /** Workspace root — joined with the relative path to stat the post-write mtime. */\n  workspaceRoot: string;\n  /** Normalise a workspace-relative path to POSIX (drives both `payload.path` and\n   *  every channel suffix, so they can't drift on mixed separators). */\n  toPosix: (relativePath: string) => string;\n  /** The host's primary file channel (e.g. a Files explorer's `file:<path>`).\n   *  Omit when the host has no general file subscriber (e.g. MulmoTerminal). */\n  primaryChannel?: (posixPath: string) => string;\n  /** Plugin Views to forward to. */\n  pluginScopes?: FileChangeScope[];\n  /** Optional side-effect after publishing (e.g. a topic-index regen). Receives the\n   *  posix path + payload; may itself call `publishFileChange` for derived files. */\n  onPublished?: (posixPath: string, payload: FileChannelPayload) => void;\n  /** Optional warn logger; a publish/stat failure logs but never throws (callers\n   *  fire-and-forget, so a throw would be an unhandled rejection). */\n  warn?: (message: string, data?: Record<string, unknown>) => void;\n}\n\nlet config: FileChangePublisherConfig | null = null;\n\n/** Wire the publisher to a host. Call once at startup, before any write route. */\nexport function configureFileChangePublisher(cfg: FileChangePublisherConfig): void {\n  config = cfg;\n}\n\n/** Clear the binding — test-only. */\nexport function resetFileChangePublisher(): void {\n  config = null;\n}\n\n/** The plugin-scoped live-refresh channel a View subscribes to. */\nexport function pluginFileChannel(scope: string, posixPath: string): string {\n  return `plugin:${scope}:file:${posixPath}`;\n}\n\n/** Publish a file-change for a workspace-relative path: the primary channel (if any)\n *  + every matching plugin scope, with the post-write mtime. No-op until configured. */\nexport async function publishFileChange(relativePath: string): Promise<void> {\n  const cfg = config;\n  if (!cfg) return;\n  // `relativePath` comes from the host's write routes. Contain it before doing\n  // anything: a path that escapes the workspace is dropped entirely — we\n  // neither stat an arbitrary file nor broadcast an out-of-workspace path to\n  // subscribers or host side-effects. Defence-in-depth, since this is the\n  // shared package both hosts use. `root` carries a trailing separator and the\n  // guard is a single `startsWith` early-return — the canonical containment\n  // shape (so the check is unambiguous for both readers and static analysis).\n  const root = path.resolve(cfg.workspaceRoot) + path.sep;\n  const absPath = path.join(root, relativePath);\n  if (!absPath.startsWith(root)) {\n    cfg.warn?.(\"ignoring file-change for path outside workspace\", { path: relativePath });\n    return;\n  }\n  let mtimeMs: number;\n  try {\n    ({ mtimeMs } = await stat(absPath));\n  } catch (err) {\n    cfg.warn?.(\"stat failed; falling back to Date.now()\", { path: relativePath, error: errMsg(err) });\n    mtimeMs = Date.now();\n  }\n  const posixPath = cfg.toPosix(relativePath);\n  const payload: FileChannelPayload = { path: posixPath, mtimeMs };\n\n  if (cfg.primaryChannel) {\n    safePublish(cfg, cfg.primaryChannel(posixPath), payload, \"primary publish failed\");\n  }\n  for (const { scope, matches } of cfg.pluginScopes ?? []) {\n    if (!matches(posixPath)) continue;\n    safePublish(cfg, pluginFileChannel(scope, posixPath), payload, `${scope} plugin forward failed`);\n  }\n  cfg.onPublished?.(posixPath, payload);\n}\n\nfunction safePublish(cfg: FileChangePublisherConfig, channel: string, payload: FileChannelPayload, failMsg: string): void {\n  try {\n    cfg.publish(channel, payload);\n  } catch (err) {\n    cfg.warn?.(`${failMsg}; subscribers will miss this event`, { channel, error: errMsg(err) });\n  }\n}\n\nfunction errMsg(err: unknown): string {\n  return err instanceof Error ? err.message : String(err);\n}\n"],"mappings":";;;;;;AAmDA,IAAI,SAA2C;;AAG/C,SAAgB,6BAA6B,KAAsC;CACjF,SAAS;AACX;;AAGA,SAAgB,2BAAiC;CAC/C,SAAS;AACX;;AAGA,SAAgB,kBAAkB,OAAe,WAA2B;CAC1E,OAAO,UAAU,MAAM,QAAQ;AACjC;;;AAIA,eAAsB,kBAAkB,cAAqC;CAC3E,MAAM,MAAM;CACZ,IAAI,CAAC,KAAK;CAQV,MAAM,OAAO,UAAA,QAAK,QAAQ,IAAI,aAAa,IAAI,UAAA,QAAK;CACpD,MAAM,UAAU,UAAA,QAAK,KAAK,MAAM,YAAY;CAC5C,IAAI,CAAC,QAAQ,WAAW,IAAI,GAAG;EAC7B,IAAI,OAAO,mDAAmD,EAAE,MAAM,aAAa,CAAC;EACpF;CACF;CACA,IAAI;CACJ,IAAI;EACF,CAAC,CAAE,WAAY,OAAA,GAAA,iBAAA,KAAA,CAAW,OAAO;CACnC,SAAS,KAAK;EACZ,IAAI,OAAO,2CAA2C;GAAE,MAAM;GAAc,OAAO,OAAO,GAAG;EAAE,CAAC;EAChG,UAAU,KAAK,IAAI;CACrB;CACA,MAAM,YAAY,IAAI,QAAQ,YAAY;CAC1C,MAAM,UAA8B;EAAE,MAAM;EAAW;CAAQ;CAE/D,IAAI,IAAI,gBACN,YAAY,KAAK,IAAI,eAAe,SAAS,GAAG,SAAS,wBAAwB;CAEnF,KAAK,MAAM,EAAE,OAAO,aAAa,IAAI,gBAAgB,CAAC,GAAG;EACvD,IAAI,CAAC,QAAQ,SAAS,GAAG;EACzB,YAAY,KAAK,kBAAkB,OAAO,SAAS,GAAG,SAAS,GAAG,MAAM,uBAAuB;CACjG;CACA,IAAI,cAAc,WAAW,OAAO;AACtC;AAEA,SAAS,YAAY,KAAgC,SAAiB,SAA6B,SAAuB;CACxH,IAAI;EACF,IAAI,QAAQ,SAAS,OAAO;CAC9B,SAAS,KAAK;EACZ,IAAI,OAAO,GAAG,QAAQ,qCAAqC;GAAE;GAAS,OAAO,OAAO,GAAG;EAAE,CAAC;CAC5F;AACF;AAEA,SAAS,OAAO,KAAsB;CACpC,OAAO,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG;AACxD"}

package/dist/file-change/index.d.ts

@@ -0,0 +1,43 @@
+/** Payload published on every file-change channel. `mtimeMs` is the post-write
+ *  modified time — monotonic, suitable for cache-busting (`?v=`) and out-of-order
+ *  drops. */
+export interface FileChannelPayload {
+    path: string;
+    mtimeMs: number;
+}
+/** A plugin View that wants live-refresh: when `matches(posixPath)` is true, the
+ *  change is forwarded to `plugin:<scope>:file:<path>` (the channel the View's
+ *  runtime subscribes to). */
+export interface FileChangeScope {
+    scope: string;
+    matches: (posixPath: string) => boolean;
+}
+export interface FileChangePublisherConfig {
+    /** Host pubsub publish. */
+    publish: (channel: string, payload: FileChannelPayload) => void;
+    /** Workspace root — joined with the relative path to stat the post-write mtime. */
+    workspaceRoot: string;
+    /** Normalise a workspace-relative path to POSIX (drives both `payload.path` and
+     *  every channel suffix, so they can't drift on mixed separators). */
+    toPosix: (relativePath: string) => string;
+    /** The host's primary file channel (e.g. a Files explorer's `file:<path>`).
+     *  Omit when the host has no general file subscriber (e.g. MulmoTerminal). */
+    primaryChannel?: (posixPath: string) => string;
+    /** Plugin Views to forward to. */
+    pluginScopes?: FileChangeScope[];
+    /** Optional side-effect after publishing (e.g. a topic-index regen). Receives the
+     *  posix path + payload; may itself call `publishFileChange` for derived files. */
+    onPublished?: (posixPath: string, payload: FileChannelPayload) => void;
+    /** Optional warn logger; a publish/stat failure logs but never throws (callers
+     *  fire-and-forget, so a throw would be an unhandled rejection). */
+    warn?: (message: string, data?: Record<string, unknown>) => void;
+}
+/** Wire the publisher to a host. Call once at startup, before any write route. */
+export declare function configureFileChangePublisher(cfg: FileChangePublisherConfig): void;
+/** Clear the binding — test-only. */
+export declare function resetFileChangePublisher(): void;
+/** The plugin-scoped live-refresh channel a View subscribes to. */
+export declare function pluginFileChannel(scope: string, posixPath: string): string;
+/** Publish a file-change for a workspace-relative path: the primary channel (if any)
+ *  + every matching plugin scope, with the post-write mtime. No-op until configured. */
+export declare function publishFileChange(relativePath: string): Promise<void>;

package/dist/ingestTypes-DDOVhOYC.cjs

@@ -0,0 +1,32 @@
+const require_deriveAll = require("./deriveAll-VRWrs3SF.cjs");
+require("./collection/index.cjs");
+//#region src/feeds/ingestTypes.ts
+var AGENT_INGEST_KIND = "agent";
+var FEED_SCHEDULE_SET = new Set(require_deriveAll.FEED_SCHEDULES);
+function isFeedSchedule(value) {
+	return typeof value === "string" && FEED_SCHEDULE_SET.has(value);
+}
+/** Default cap on stored records per feed when `ingest.maxItems` is
+*  omitted. Keeps high-volume feeds (news / podcasts) bounded. */
+var DEFAULT_FEED_MAX_ITEMS = 100;
+//#endregion
+Object.defineProperty(exports, "AGENT_INGEST_KIND", {
+	enumerable: true,
+	get: function() {
+		return AGENT_INGEST_KIND;
+	}
+});
+Object.defineProperty(exports, "DEFAULT_FEED_MAX_ITEMS", {
+	enumerable: true,
+	get: function() {
+		return DEFAULT_FEED_MAX_ITEMS;
+	}
+});
+Object.defineProperty(exports, "isFeedSchedule", {
+	enumerable: true,
+	get: function() {
+		return isFeedSchedule;
+	}
+});
+
+//# sourceMappingURL=ingestTypes-DDOVhOYC.cjs.map

package/dist/ingestTypes-DDOVhOYC.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"ingestTypes-DDOVhOYC.cjs","names":[],"sources":["../src/feeds/ingestTypes.ts"],"sourcesContent":["// Declarative retrieval config for the \"Feeds\" mechanism. A Feed is a\n// CollectionSchema plus this `ingest` block, registered as data (NOT as\n// a skill) under `<workspace>/feeds/<slug>/schema.json`. The host's\n// retrieval engine reads it to periodically refill the collection's\n// records via the shared collections io layer.\n//\n// The ingest vocab (INGEST_KINDS / FEED_SCHEDULES + their literal-union types)\n// lives in the sibling `../collection` subpath alongside the schema contract, so\n// the package's schema validator can enforce it. Re-exported here so the feeds\n// engine's existing importers resolve them unchanged.\nimport { type CollectionIngest, INGEST_KINDS, FEED_SCHEDULES, type IngestKind, type FeedSchedule } from \"../collection/index.js\";\n//\n// Two flavours: the declarative kinds (`rss`/`atom`/`http-json`) fetch-and-map,\n// and `agent` dispatches a hidden worker. The `code` kind (LLM-generated\n// deterministic transform) is still reserved for a future retriever.\n\n// The agent ingest kind. Defined HERE (not imported from `../collection`) on\n// purpose: the engine only needs the literal to branch, and re-importing it as a\n// VALUE keeps this module free of a value dependency on the collection vocab.\n// Core owns its own copy for the schema validator; this matches the same literal.\nexport const AGENT_INGEST_KIND = \"agent\" as const;\nexport type AgentIngestKind = typeof AGENT_INGEST_KIND;\n\nexport { INGEST_KINDS, FEED_SCHEDULES, type IngestKind, type FeedSchedule };\n\nconst FEED_SCHEDULE_SET: ReadonlySet<string> = new Set(FEED_SCHEDULES);\n\nexport function isFeedSchedule(value: unknown): value is FeedSchedule {\n  return typeof value === \"string\" && FEED_SCHEDULE_SET.has(value);\n}\n\n/** Default cap on stored records per feed when `ingest.maxItems` is\n *  omitted. Keeps high-volume feeds (news / podcasts) bounded. */\nexport const DEFAULT_FEED_MAX_ITEMS = 100;\n\n/** Declarative field map: target collection field name → source path\n *  into the raw item (dot/bracket path, e.g. `\"title\"` or\n *  `\"data.name\"`). */\nexport type IngestFieldMap = Record<string, string>;\n\n/** Declarative retrieval (`rss`/`atom`/`http-json`): the host fetches `url`\n *  and projects each item through `map`. The canonical schema (in\n *  `../collection`) only promises the minimal `CollectionIngest`; this\n *  feeds-only subtype narrows those + adds the retrieval fields the engine\n *  needs. */\nexport interface DeclarativeIngestSpec extends CollectionIngest {\n  /** Which declarative retriever handles this feed. */\n  kind: IngestKind;\n  /** Endpoint to fetch (http/https). */\n  url: string;\n  /** Refresh cadence. */\n  schedule: FeedSchedule;\n  /** `http-json` only: dot/bracket path to the array of items in the\n   *  response (e.g. `\"hourly[]\"` or `\"data.results[]\"`). Ignored for\n   *  `rss`/`atom`, which yield items natively. */\n  itemsAt?: string;\n  /** target field → source path. Projects each raw item into a record\n   *  whose keys match the schema's `fields`. */\n  map: IngestFieldMap;\n  /** Optional source path used to derive the primaryKey value when the\n   *  mapped record's primaryKey is empty (e.g. `\"feedId\"`). Falls back\n   *  to a content hash of the record. */\n  idFrom?: string;\n  /** Cap on stored records. After each fetch the feed keeps only the\n   *  newest `maxItems` (ordered by the schema's first `date` field) and\n   *  deletes the rest. Defaults to {@link DEFAULT_FEED_MAX_ITEMS} when\n   *  omitted; `0` disables the cap (keep everything). Pruning is skipped\n   *  when the schema has no `date` field to order by. */\n  maxItems?: number;\n}\n\n/** Agent-performed retrieval (`kind: \"agent\"`). No `url`/`map`: the host seeds\n *  a hidden background worker (origin `system`) in `role` with `template` + a\n *  summary of every record, and the worker edits the records itself via the\n *  collections io layer. Valid on any collection (primarily skill-backed). */\nexport interface AgentIngestSpec extends CollectionIngest {\n  kind: AgentIngestKind;\n  /** Refresh cadence (same vocabulary as declarative feeds). */\n  schedule: FeedSchedule;\n  /** Role id the scheduled hidden worker runs in. */\n  role: string;\n  /** Skill-relative template path (under `templates/`) seeding the worker. */\n  template: string;\n}\n\n/** The `ingest` block carried on a `CollectionSchema`, discriminated on `kind`. */\nexport type IngestSpec = DeclarativeIngestSpec | AgentIngestSpec;\n"],"mappings":";;;AAoBA,IAAa,oBAAoB;AAKjC,IAAM,oBAAyC,IAAI,IAAI,kBAAA,cAAc;AAErE,SAAgB,eAAe,OAAuC;CACpE,OAAO,OAAO,UAAU,YAAY,kBAAkB,IAAI,KAAK;AACjE;;;AAIA,IAAa,yBAAyB"}

package/dist/notifier/engine.d.ts

@@ -0,0 +1,72 @@
+import { WriteJson } from './store.js';
+import { NotifierEntry, NotifierEvent, NotifierHistoryEntry, NotifierSeverity, PublishInput } from './types.js';
+export { NOTIFIER_LIMITS, validatePublishInput } from './validate.js';
+/** Minimal logger the engine needs. The host passes its structured
+ *  logger; absent one, failures are swallowed (the engine never throws
+ *  on a fan-out/persist-best-effort path). */
+export interface NotifierLogger {
+    warn: (message: string, data?: Record<string, unknown>) => void;
+    error: (message: string, data?: Record<string, unknown>) => void;
+}
+export interface NotifierConfig {
+    /** Atomic JSON writer (the host's `writeJsonAtomic`). */
+    writeJson: WriteJson;
+    /** Fan-out sink — the host binds this to `pubsub.publish(channel, event)`. */
+    publishEvent: (event: NotifierEvent) => void;
+    /** Optional logger. */
+    log?: NotifierLogger;
+}
+/** Wire the engine's I/O deps. Call once at startup, before the first
+ *  mutation. Does NOT set file paths — those are set independently via
+ *  `setNotifierFilePaths` so a host can bind production paths at module
+ *  load and a test can override them without re-supplying the deps. */
+export declare function configureNotifier(injected: NotifierConfig): void;
+type NotifierEventListener = (event: NotifierEvent) => void;
+/** Register an in-process listener for engine events. Returns an
+ *  unsubscribe function the caller can use during teardown. */
+export declare function onEvent(listener: NotifierEventListener): () => void;
+/** Point the engine at its active/history files. Resets the write
+ *  queue, so callers must not have in-flight mutations. The host calls
+ *  this once with the workspace paths; tests call it per-case with temp
+ *  files. */
+export declare function setNotifierFilePaths(paths: {
+    active: string;
+    history: string;
+}): void;
+/** Test-only: clear config + queue so each suite starts clean. */
+export declare function resetNotifier(): void;
+export declare function publish<TPluginData = unknown>(input: PublishInput<TPluginData>): Promise<{
+    id: string;
+}>;
+export declare function clear(entryId: string): Promise<void>;
+export declare function cancel(entryId: string): Promise<void>;
+/** In-place update for an active entry. Only the fields present on
+ *  `patch` are rewritten; `id`, `pluginPkg`, `lifecycle`, and
+ *  `createdAt` stay fixed. Emits a single `"updated"` event with the
+ *  post-mutation entry — no history record is written because the
+ *  entry is still active, just with refreshed content.
+ *
+ *  No-ops (no throw) when the id is unknown, the entry belongs to a
+ *  different plugin, or the merged shape would violate
+ *  `validatePublishInput`. The silent skip matches `clearForPlugin`'s
+ *  isolation semantics; validation failures are logged for diagnosis. */
+export declare function updateForPlugin<TPluginData = unknown>(pluginPkg: string, entryId: string, patch: {
+    severity?: NotifierSeverity;
+    title?: string;
+    body?: string;
+    navigateTarget?: string;
+    pluginData?: TPluginData;
+}): Promise<void>;
+/** Plugin-scoped point lookup. Returns the entry by id, but only if it
+ *  belongs to the caller's plugin; otherwise undefined. Cross-plugin
+ *  reads return undefined for isolation — same property as
+ *  `clearForPlugin` / `updateForPlugin`. */
+export declare function getForPlugin(pluginPkg: string, entryId: string): Promise<NotifierEntry | undefined>;
+/** Plugin-scoped clear. Same as `clear` but no-ops if the entry's
+ *  `pluginPkg` doesn't match the caller's, so a plugin can't dismiss
+ *  another plugin's notification by guessing or scraping its id. */
+export declare function clearForPlugin(pluginPkg: string, entryId: string): Promise<void>;
+export declare function get(entryId: string): Promise<NotifierEntry | undefined>;
+export declare function listFor(pluginPkg: string): Promise<NotifierEntry[]>;
+export declare function listAll(): Promise<NotifierEntry[]>;
+export declare function listHistory(): Promise<NotifierHistoryEntry[]>;

package/dist/notifier/index.cjs

@@ -0,0 +1,21 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_notifier = require("../notifier-bS8IEeLA.cjs");
+exports.HISTORY_CAP = require_notifier.HISTORY_CAP;
+exports.NOTIFIER_LIFECYCLES = require_notifier.NOTIFIER_LIFECYCLES;
+exports.NOTIFIER_LIMITS = require_notifier.NOTIFIER_LIMITS;
+exports.NOTIFIER_SEVERITIES = require_notifier.NOTIFIER_SEVERITIES;
+exports.cancel = require_notifier.cancel;
+exports.clear = require_notifier.clear;
+exports.clearForPlugin = require_notifier.clearForPlugin;
+exports.configureNotifier = require_notifier.configureNotifier;
+exports.get = require_notifier.get;
+exports.getForPlugin = require_notifier.getForPlugin;
+exports.listAll = require_notifier.listAll;
+exports.listFor = require_notifier.listFor;
+exports.listHistory = require_notifier.listHistory;
+exports.onEvent = require_notifier.onEvent;
+exports.publish = require_notifier.publish;
+exports.resetNotifier = require_notifier.resetNotifier;
+exports.setNotifierFilePaths = require_notifier.setNotifierFilePaths;
+exports.updateForPlugin = require_notifier.updateForPlugin;
+exports.validatePublishInput = require_notifier.validatePublishInput;

package/dist/notifier/index.d.ts

@@ -0,0 +1,3 @@
+export * from './types.js';
+export * from './engine.js';
+export type { WriteJson } from './store.js';

package/dist/notifier/store.d.ts

@@ -0,0 +1,18 @@
+import { NotifierFile, NotifierHistoryFile } from './types.js';
+/** Injected atomic JSON writer — the host's `writeJsonAtomic`. */
+export type WriteJson = (filePath: string, data: unknown) => Promise<void>;
+/** Read the active-entries file. Returns an empty store when the file
+ *  doesn't exist yet (first ever call on a fresh workspace). Any other
+ *  read or parse failure throws — the caller has to decide whether to
+ *  surface or recover, since silently treating "malformed file" as
+ *  "no entries" would lose data. */
+export declare function loadActive(filePath: string): Promise<NotifierFile>;
+/** Write the active-entries file via the injected atomic writer so a
+ *  half-written file is never visible to readers. The caller serialises
+ *  writes (engine.ts queues mutations) — this function makes no
+ *  concurrency guarantees of its own. */
+export declare function saveActive(writeJson: WriteJson, filePath: string, state: NotifierFile): Promise<void>;
+/** Read the history file. Empty array on first run. Same parse-error
+ *  policy as `loadActive`. */
+export declare function loadHistory(filePath: string): Promise<NotifierHistoryFile>;
+export declare function saveHistory(writeJson: WriteJson, filePath: string, state: NotifierHistoryFile): Promise<void>;

package/dist/notifier/types.d.ts

@@ -0,0 +1,118 @@
+/** Two notification shapes, distinguished by who fires the close call:
+ *
+ *    `fyi`    — informational. The host (bell panel) clears it when the
+ *               user dismisses the row. No deep-link target.
+ *    `action` — pending obligation. The plugin clears it when the
+ *               underlying domain state changes (the user paid the tax,
+ *               viewed the digest, etc.). The bell row navigates to
+ *               `navigateTarget` on click.
+ *
+ *  The engine reads `lifecycle` only to enforce two publish-time rules
+ *  (everything downstream — pubsub fan-out, persistence, history — is
+ *  lifecycle-blind):
+ *
+ *    1. `action` requires a non-empty `navigateTarget`. Without one,
+ *       clicking the row does nothing and the entry is a degraded fyi.
+ *    2. `action` cannot use `info` severity. A low-priority obligation
+ *       is incoherent — fyi if it's a ping, `nudge`/`urgent` if it's a
+ *       real obligation worth a landing page.
+ *
+ *  Both rules are mirrored in the HTTP layer so plugin-runtime callers
+ *  and HTTP callers hit the same wall. */
+export declare const NOTIFIER_LIFECYCLES: readonly ["fyi", "action"];
+export type NotifierLifecycle = (typeof NOTIFIER_LIFECYCLES)[number];
+/** Severity drives badge color (gray / amber / red, worst-wins) and
+ *  in a future iteration channel routing. Mostly stored verbatim by
+ *  the engine; the one engine-visible interaction is the rule that
+ *  `action` lifecycle cannot pair with `info` severity (see
+ *  `NotifierLifecycle` above). */
+export declare const NOTIFIER_SEVERITIES: readonly ["info", "nudge", "urgent"];
+export type NotifierSeverity = (typeof NOTIFIER_SEVERITIES)[number];
+export interface NotifierEntry<TPluginData = unknown> {
+    /** Engine-assigned UUID. Generated synchronously inside `publish()`
+     *  so the caller can use it before persistence completes. */
+    id: string;
+    /** Plugin namespace (e.g. `"encore"`, `"debug__system"`). The
+     *  engine never inspects it — used only for `listFor()` filtering
+     *  and as a UI grouping key. */
+    pluginPkg: string;
+    severity: NotifierSeverity;
+    lifecycle?: NotifierLifecycle;
+    title: string;
+    body?: string;
+    /** Optional in-app deep-link target (relative URL). The bell popup
+     *  routes here on row click, with `&notificationId=<id>` appended
+     *  so the landing page can identify which entry to clear. The
+     *  engine doesn't read this — it's a UI hint stored on the entry. */
+    navigateTarget?: string;
+    /** Opaque to the engine. Round-trips through JSON unchanged; only
+     *  the originating plugin's UI knows the shape. */
+    pluginData?: TPluginData;
+    /** ISO-8601 timestamp set at `publish()` time. */
+    createdAt: string;
+}
+/** A history entry — a `NotifierEntry` after it has been cleared or
+ *  cancelled, with the terminal type and timestamp recorded. The
+ *  bell popup's "History" section renders these read-only. */
+export interface NotifierHistoryEntry<TPluginData = unknown> extends NotifierEntry<TPluginData> {
+    terminalType: "cleared" | "cancelled";
+    terminalAt: string;
+}
+/** Caller-supplied input for `publish()`. The engine fills in `id`
+ *  and `createdAt`; everything else flows through verbatim.
+ *
+ *  Two publish-time rules apply to `action` lifecycle (see
+ *  `NotifierLifecycle`):
+ *
+ *    - `navigateTarget` MUST be a non-empty string.
+ *    - `severity` MUST NOT be `"info"`.
+ *
+ *  Violations cause `publish()` to throw. Currently expressed as
+ *  runtime validation rather than a discriminated-union type, so the
+ *  fields below are all individually optional / loose at the
+ *  type-level. */
+export interface PublishInput<TPluginData = unknown> {
+    pluginPkg: string;
+    severity: NotifierSeverity;
+    title: string;
+    body?: string;
+    lifecycle?: NotifierLifecycle;
+    navigateTarget?: string;
+    pluginData?: TPluginData;
+}
+/** On-disk shape of `~/mulmoclaude/data/notifier/active.json`. Holds
+ *  only entries that haven't been cleared or cancelled — the file is
+ *  a snapshot, not an event log. */
+export interface NotifierFile {
+    entries: Record<string, NotifierEntry>;
+}
+/** On-disk shape of `~/mulmoclaude/data/notifier/history.json`. Array
+ *  of terminated entries newest-first, capped at `HISTORY_CAP` with
+ *  FIFO eviction (push at index 0, slice from the tail). */
+export interface NotifierHistoryFile {
+    entries: NotifierHistoryEntry[];
+}
+/** History size cap. The bell popup's History section renders this
+ *  many entries; older ones fall off when new terminations land. */
+export declare const HISTORY_CAP = 50;
+/** Pub-sub event published on the host's notifier channel after every
+ *  successful state change. Discriminated union — subscribers switch
+ *  on `type` to keep TypeScript narrowing the rest of the payload.
+ *
+ *  `updated` carries the post-mutation entry — the receiver swaps
+ *  the matching `id` in their local active set. Reserved for in-
+ *  place edits via `updateForPlugin`; no history record is written
+ *  because the entry is still active, just with refreshed content. */
+export type NotifierEvent = {
+    type: "published";
+    entry: NotifierEntry;
+} | {
+    type: "cleared";
+    id: string;
+} | {
+    type: "cancelled";
+    id: string;
+} | {
+    type: "updated";
+    entry: NotifierEntry;
+};

package/dist/notifier/validate.d.ts

@@ -0,0 +1,17 @@
+import { PublishInput } from './types.js';
+/** Hard caps on publish-input fields. The engine reads each entry on
+ *  every list/get call (no in-memory cache), so unbounded fields hurt
+ *  every reader. Caps chosen to be generous for legitimate UX copy
+ *  while bounding active.json growth: a notification fundamentally is
+ *  a short blurb, not a document. */
+export declare const NOTIFIER_LIMITS: {
+    readonly titleMax: 200;
+    readonly bodyMax: 4000;
+    readonly navigateTargetMax: 1000;
+    readonly pluginDataMaxBytes: number;
+};
+/** Validate a `PublishInput`. Returns `null` if OK, or a
+ *  human-readable error string. Order matters — shape/size errors are
+ *  reported before lifecycle/severity coherence errors so the message
+ *  the caller sees points at the most fundamental problem first. */
+export declare function validatePublishInput(input: PublishInput): string | null;