@mulmoclaude/core 3.5.0 → 3.7.0

package/dist/collection/server/publishProject.d.ts

@@ -0,0 +1,86 @@
+import { CollectionSchema } from '../core/schema';
+import { AuthoredApp } from './publishManifest';
+/** Who and when. Threaded in rather than read from a clock inside the
+ *  projection so the projection stays pure and the tests can assert on an
+ *  exact document. */
+export interface PublishStamp {
+    /** The publisher's Firebase uid. The rules require `owner ==
+     *  request.auth.uid` on CREATE and `owner` unchanged on UPDATE, so this is
+     *  used only when the app document does not exist yet. */
+    uid: string;
+    /** The publisher's verified email — the principal the roster is keyed by. */
+    email: string;
+    /** Wall-clock millis of this publish. */
+    publishedAt: number;
+    /** The git commit the declaration was read from, when the host could
+     *  resolve one. Absent is a normal state (a dirty tree, a repository
+     *  without git), and absent is more honest than a fabricated value. */
+    commit?: string | undefined;
+}
+/** One collection's published schema document (`apps/{aid}/collections/{cid}`).
+ *
+ *  The rules never read `publishedSchema` — `schemaRead` gates the whole
+ *  document and stops there. It is here for the CLIENTS: a member's host
+ *  renders from it, and a public webview has no other way to know the fields.
+ *  The whole schema is published rather than a projection of it, because
+ *  every attempt to guess "the part a view needs" is a guess about a view
+ *  that has not been written yet. */
+export interface PublishedSchemaDoc extends Record<string, unknown> {
+    publishedSchema: CollectionSchema;
+    publishedAt: number;
+    publishedBy: string;
+    publishedCommit?: string;
+}
+/** The public settings document (`apps/{aid}/config/public`).
+ *
+ *  `allow read: if true` — this is the one document an anonymous visitor can
+ *  read, and it is the reason `apps/{aid}` itself is reader-only: a
+ *  participant reading the app document would see their classmates'
+ *  addresses. So the roster is NOT here, and neither is `owner`. What is here
+ *  is what a public form needs in order to render itself and to tell a visitor
+ *  "this closed yesterday" instead of failing a write with no explanation. */
+export interface PublishedConfigDoc extends Record<string, unknown> {
+    name?: string;
+    enabled: boolean;
+    read: string[];
+    submit: Record<string, Record<string, unknown>>;
+    publishedAt: number;
+}
+/** Everything one publish writes. Separate documents because they live at
+ *  separate paths with separate rules — and in the order given: the app
+ *  document authorizes the other two, so it goes first. */
+export interface PublishedApp {
+    app: Record<string, unknown>;
+    schemas: {
+        cid: string;
+        doc: PublishedSchemaDoc;
+    }[];
+    config: PublishedConfigDoc;
+}
+/** The document id under `apps/{aid}/config`. One document, named, rather than
+ *  a spread of them: a second public document is a second thing to keep in
+ *  step, and nothing yet needs one. */
+export declare const PUBLIC_CONFIG_DOC = "public";
+/** Project the authored declaration into the documents publish writes.
+ *
+ *  `existing` is the app document as it is in Firestore right now, or null on
+ *  a first publish. Two things need it, both required by the rules:
+ *    - `owner` must be UNCHANGED on update. Re-stamping the publisher's uid
+ *      would be refused for any app whose owner ever signed in as a different
+ *      account, and would silently transfer ownership if it were not.
+ *    - `previousPublished` is that document, so a rollback has something to
+ *      put back.
+ *
+ *  Pure: no clock, no filesystem, no Firestore. Everything variable arrives as
+ *  a parameter, which is what makes the conversion table testable as a table. */
+export declare function projectApp(authored: AuthoredApp, schemas: {
+    cid: string;
+    schema: CollectionSchema;
+}[], stamp: PublishStamp, existing: Record<string, unknown> | null): PublishedApp;
+/** The app documents' parent path — the `FirestoreDocs` seam takes a
+ *  collection path plus a document id, and the app document's id is the aid. */
+export declare const APPS_COLLECTION = "apps";
+/** The collection (schema) documents' parent path. */
+export declare const appSchemasPath: (aid: string) => string;
+/** The public-config documents' parent path. */
+export declare const appConfigPath: (aid: string) => string;

package/dist/collection/server/validate.d.ts

@@ -8,6 +8,18 @@ export interface RecordIssue {
     /** Human-readable problem, written to be actionable by the LLM. */
     problem: string;
 }
+/** Don't flood the result; the first batch is enough to act on. Exported
+ *  because a caller that REPORTS a count has to know the count is a floor —
+ *  `publish` presents a full batch as "at least N" rather than as a total. */
+export declare const MAX_RECORD_ISSUES = 25;
+/** The `file` of the pseudo-issue reported when the backend could not be read
+ *  at all.
+ *
+ *  Exported because it is a DIFFERENT KIND of answer from "this record is
+ *  invalid", and a caller that treats the two alike gets it wrong in the
+ *  direction that matters: `publish` lets the user override invalid records,
+ *  and overriding this one would mean publishing without ever having looked. */
+export declare const STORE_UNREADABLE = "(store)";
 export declare function validateCollectionRecords(collection: LoadedCollection, opts?: {
     workspaceRoot?: string | undefined;
 }): Promise<RecordIssue[]>;

package/dist/collection-watchers/index.cjs

@@ -3,8 +3,8 @@ const require_root = require("../root-rPH6FGDT.cjs");
 const require_calendarGrid = require("../calendarGrid-DGILaVxI.cjs");
 const require_promptSafety = require("../promptSafety-NNGViiCr.cjs");
 require("../collection/index.cjs");
-const require_discovery = require("../discovery-Ck4AqikY.cjs");
-const require_server = require("../server-5EMj3naj.cjs");
+const require_store = require("../store-5_P_NsGa.cjs");
+const require_server = require("../server-CWZyg8fn.cjs");
 const require_notifier = require("../notifier-DZJj0sOh.cjs");
 let node_fs_promises = require("node:fs/promises");
 //#region src/collection-watchers/config.ts
@@ -133,16 +133,28 @@ function resolveDisplayLabel(schema, item, itemId) {
 	const label = require_calendarGrid.fieldText(item[displayField]).trim();
 	return label.length > 0 ? label : itemId;
 }
+/** The scope a collection's bells belong to.
+*
+*  A shared collection's `appId` wins over the call's `workspaceRoot`: the
+*  root is where this host happens to have the repository checked out, which
+*  is exactly the fact that must NOT reach the identity. A local collection is
+*  unchanged — its root is present only when the call carried an explicit one,
+*  so a single-workspace host's ids stay byte-identical to what it has already
+*  written to `active.json`. */
+function bellScopeOf(collection, ioOpts) {
+	return collection.appId === void 0 ? { root: ioOpts.workspaceRoot } : { aid: collection.appId };
+}
+var scopedLegacyId = (slug, itemId, scope) => completionLegacyId(slug, itemId, scope.root, scope.aid);
 /** Every active bell entry whose key matches this (slug, itemId).
 *  Returns multiple when defensive cleanup is needed. Scans `listAll()`
 *  — cheap because the active set is bounded. */
-async function findActiveEntries(slug, itemId, root) {
+async function findActiveEntries(slug, itemId, scope) {
 	const adapter = requireAdapter();
-	const legacyId = completionLegacyId(slug, itemId, root);
+	const legacyId = scopedLegacyId(slug, itemId, scope);
 	return (await require_notifier.listAll()).filter((entry) => adapter.readEntry(entry.pluginData)?.legacyId === legacyId);
 }
-async function findActiveEntryIds(slug, itemId, root) {
-	return (await findActiveEntries(slug, itemId, root)).map((entry) => entry.id);
+async function findActiveEntryIds(slug, itemId, scope) {
+	return (await findActiveEntries(slug, itemId, scope)).map((entry) => entry.id);
 }
 var ensureLocks = /* @__PURE__ */ new Map();
 /** Bell priority for a record: the FIRST flagged value in `notifyWhen.in`
@@ -155,8 +167,8 @@ function notifyPriorityForItem(schema, item) {
 	const value = item[spec.field] === void 0 || item[spec.field] === null ? "" : String(item[spec.field]);
 	return spec.in.indexOf(value) === 0 ? "high" : "normal";
 }
-async function ensureItemNotification(slug, schema, itemId, displayLabel, priority, root) {
-	const legacyId = completionLegacyId(slug, itemId, root);
+async function ensureItemNotification(slug, schema, itemId, displayLabel, priority, scope) {
+	const legacyId = scopedLegacyId(slug, itemId, scope);
 	while (true) {
 		const inflight = ensureLocks.get(legacyId);
 		if (!inflight) break;
@@ -169,7 +181,7 @@ async function ensureItemNotification(slug, schema, itemId, displayLabel, priori
 		legacyId,
 		displayLabel,
 		priority,
-		root
+		scope
 	}) };
 	ensureLocks.set(legacyId, lock);
 	try {
@@ -182,8 +194,9 @@ async function ensureItemNotification(slug, schema, itemId, displayLabel, priori
 *  place (preserving id / position / createdAt) so a record whose flagged
 *  value changed while it stayed pending re-colours the bell without a
 *  clear+republish flicker. No-op when the stored priority already matches. */
-async function reconcileEntrySeverity(slug, itemId, entries, priority, root) {
+async function reconcileEntrySeverity(slug, itemId, entries, priority, scope) {
 	const adapter = requireAdapter();
+	const { root } = scope;
 	for (const entry of entries) {
 		const parsed = adapter.readEntry(entry.pluginData);
 		if (!parsed || parsed.priority === priority) continue;
@@ -200,12 +213,13 @@ async function reconcileEntrySeverity(slug, itemId, entries, priority, root) {
 		});
 	}
 }
-async function doEnsureItemNotification({ slug, schema, itemId, legacyId, displayLabel, priority, root }) {
+async function doEnsureItemNotification({ slug, schema, itemId, legacyId, displayLabel, priority, scope }) {
 	const adapter = requireAdapter();
+	const { root } = scope;
 	try {
-		const existing = await findActiveEntries(slug, itemId, root);
+		const existing = await findActiveEntries(slug, itemId, scope);
 		if (existing.length > 0) {
-			await reconcileEntrySeverity(slug, itemId, existing, priority, root);
+			await reconcileEntrySeverity(slug, itemId, existing, priority, scope);
 			return;
 		}
 		const navigateTarget = adapter.buildNavigateTarget(slug, itemId, root);
@@ -235,9 +249,18 @@ async function doEnsureItemNotification({ slug, schema, itemId, legacyId, displa
 /** Idempotently clear EVERY bell entry that matches this (slug, itemId).
 *  Silent no-op when nothing matches. The "every" is defensive: if a
 *  duplicate ever slips through, this drains the lot. */
-async function clearItemNotification(slug, itemId, root) {
+async function clearItemNotification(slug, itemId, root, aid) {
+	await clearScoped(slug, itemId, {
+		root,
+		aid
+	});
+}
+/** The scoped form every internal caller uses. `clearItemNotification` keeps
+*  its positional `(slug, itemId, root?)` shape because it is public API
+*  (MulmoTerminal calls it); `aid` is additive. */
+async function clearScoped(slug, itemId, scope) {
 	try {
-		const ids = await findActiveEntryIds(slug, itemId, root);
+		const ids = await findActiveEntryIds(slug, itemId, scope);
 		for (const entryId of ids) await require_notifier.clear(entryId);
 	} catch (err) {
 		log().warn("notify clear failed", {
@@ -257,19 +280,19 @@ async function clearItemNotification(slug, itemId, root) {
 *  `{ workspaceRoot: <tmpdir> }` so the check accepts a fixture dataDir. */
 async function reconcileItem(collection, itemId, ioOpts = {}, now = evalNow()) {
 	const { slug, schema } = collection;
-	const root = ioOpts.workspaceRoot;
+	const scope = bellScopeOf(collection, ioOpts);
 	if (!schema.completionField) {
-		await clearItemNotification(slug, itemId, root);
+		await clearScoped(slug, itemId, scope);
 		return;
 	}
-	const item = await require_discovery.storeFor(collection, ioOpts).read(itemId);
+	const item = await require_store.storeFor(collection, ioOpts).read(itemId);
 	if (item === null) {
-		await clearItemNotification(slug, itemId, root);
+		await clearScoped(slug, itemId, scope);
 		return;
 	}
 	await require_server.maybeSpawnSuccessor(collection, item, itemId, ioOpts);
 	if (require_promptSafety.itemIsDone(schema, item)) {
-		await clearItemNotification(slug, itemId, root);
+		await clearScoped(slug, itemId, scope);
 		return;
 	}
 	if (schema.triggerField) {
@@ -281,15 +304,15 @@ async function reconcileItem(collection, itemId, ioOpts = {}, now = evalNow()) {
 			triggerField: schema.triggerField
 		});
 		if (due !== true) {
-			await clearItemNotification(slug, itemId, root);
+			await clearScoped(slug, itemId, scope);
 			return;
 		}
 	}
 	if (!require_promptSafety.whenMatches(schema.notifyWhen, item)) {
-		await clearItemNotification(slug, itemId, root);
+		await clearScoped(slug, itemId, scope);
 		return;
 	}
-	await ensureItemNotification(slug, schema, itemId, resolveDisplayLabel(schema, item, itemId), notifyPriorityForItem(schema, item), root);
+	await ensureItemNotification(slug, schema, itemId, resolveDisplayLabel(schema, item, itemId), notifyPriorityForItem(schema, item), scope);
 }
 /** Boot-time reconcile: walk every record of the collection once (through
 *  its store) and reconcile it. Catches up changes that happened while the
@@ -301,7 +324,7 @@ async function reconcileAllItems(collection, ioOpts = {}, now = evalNow()) {
 	if (!schema.completionField) return;
 	let items;
 	try {
-		items = await require_discovery.storeFor(collection, ioOpts).list();
+		items = await require_store.storeFor(collection, ioOpts).list();
 	} catch (err) {
 		log().warn("reconcile list failed", {
 			slug,
@@ -335,7 +358,7 @@ async function reconcileAllItems(collection, ioOpts = {}, now = evalNow()) {
 *    ever clear, while the reconcile publishes a second rooted one beside it.
 *    Clearing converges — the record republishes rooted if still pending. */
 function sweepVerdict(entry, ownRoot) {
-	if (entry.aid !== void 0) return "skip";
+	if (entry.aid !== void 0) return "shared";
 	if (entry.root === ownRoot) return "mine";
 	if (entry.root === void 0) return "drop-legacy";
 	return "skip";
@@ -345,12 +368,40 @@ function sweepVerdict(entry, ownRoot) {
 *  `notifyWhen`. The reverse of the reconcile invariant, applied to an entry
 *  whose record the forward pass can never walk to (a delete leaves a bell that
 *  a walk over the SURVIVING records cannot clear). */
-async function isStaleEntry(slug, itemId, opts) {
-	const collection = await require_discovery.loadCollection(slug, opts);
+async function isStaleEntry(slug, itemId, opts, aid) {
+	const collection = await require_store.loadCollection(slug, opts);
+	if (aid !== void 0 && collection?.appId !== aid) return false;
 	if (!collection || !collection.schema.completionField) return true;
-	const item = await require_discovery.storeFor(collection, opts).read(itemId);
+	return recordNoLongerBells(collection, itemId, opts);
+}
+/** The record half of the staleness question: gone, done, or outside
+*  `notifyWhen`. Split out so the caller stays one decision — WHOSE entry this
+*  is — and this one stays the other. */
+async function recordNoLongerBells(collection, itemId, opts) {
+	const item = await require_store.storeFor(collection, opts).read(itemId);
 	return item === null || require_promptSafety.itemIsDone(collection.schema, item) || !require_promptSafety.whenMatches(collection.schema.notifyWhen, item);
 }
+/** One entry's fate: whose it is (`sweepVerdict`), then — when it is this
+*  sweep's to judge — whether its record still justifies the bell. Extracted so
+*  the loop above stays a walk and this stays the decision. */
+async function sweepOneEntry(entryId, parsed, ownRoot, opts) {
+	const verdict = sweepVerdict(parsed, ownRoot);
+	if (verdict === "skip") return;
+	if (verdict === "drop-legacy") {
+		await require_notifier.clear(entryId);
+		return;
+	}
+	const { slug, itemId } = parsed;
+	try {
+		if (await isStaleEntry(slug, itemId, opts, verdict === "shared" ? parsed.aid : void 0)) await require_notifier.clear(entryId);
+	} catch (err) {
+		log().warn("sweep entry failed", {
+			slug,
+			itemId,
+			error: errMsg(err)
+		});
+	}
+}
 async function sweepStaleActiveEntries(opts = {}) {
 	const adapter = requireAdapter();
 	let entries;
@@ -366,22 +417,7 @@ async function sweepStaleActiveEntries(opts = {}) {
 		if (!own) continue;
 		const parsed = parseCompletionLegacyId(own.legacyId);
 		if (!parsed) continue;
-		const verdict = sweepVerdict(parsed, ownRoot);
-		if (verdict === "skip") continue;
-		if (verdict === "drop-legacy") {
-			await require_notifier.clear(entry.id);
-			continue;
-		}
-		const { slug, itemId } = parsed;
-		try {
-			if (await isStaleEntry(slug, itemId, opts)) await require_notifier.clear(entry.id);
-		} catch (err) {
-			log().warn("sweep entry failed", {
-				slug,
-				itemId,
-				error: errMsg(err)
-			});
-		}
+		await sweepOneEntry(entry.id, parsed, ownRoot, opts);
 	}
 }
 /** Test-only: clear the per-key in-flight locks. */
@@ -415,7 +451,7 @@ var WATCHER_ROOT_CONFLICT = "WATCHER_ROOT_CONFLICT";
 *  is a comparison, and under an explicit-root binding there is no default to
 *  read, which is not an error here. */
 function effectiveRoot(opts) {
-	const root = opts?.workspaceRoot ?? require_discovery.peekWorkspaceRoot() ?? void 0;
+	const root = opts?.workspaceRoot ?? require_store.peekWorkspaceRoot() ?? void 0;
 	return root === void 0 ? void 0 : require_root.canonicalRoot(root);
 }
 /** The discovery options a generation runs under, with an explicit root put in
@@ -591,9 +627,58 @@ async function _tickTimeTriggersForTesting(now, workspaceRoot) {
 async function tickTimeTriggers(gen, now = evalNow()) {
 	for (const entry of gen.watchers.values()) {
 		const { schema } = entry.collection;
+		if (cannotReportChanges(gen, entry.collection)) continue;
 		if (!schema.triggerField && !schema.spawn) continue;
 		await reconcileAllItems(entry.collection, gen.discoveryOpts, now);
 	}
+	await tickUnwatchedCollections(gen, now);
+}
+/** True when the collection's store implements no `watch` — nothing will ever
+*  tell this module its records moved, so the clock tick is its only change
+*  detection. A capability question, deliberately not a backend one: the day a
+*  shared collection's store grows an `onSnapshot` watch, it stops being
+*  special here with no edit to this file. */
+function cannotReportChanges(gen, collection) {
+	return require_store.storeFor(collection, gen.discoveryOpts).watch === void 0;
+}
+/** True when a schema declares behaviour that only a reconcile pass can
+*  produce: bells (`completionField`), date-triggered bells (`triggerField`),
+*  or recurrence successors (`spawn`). */
+function needsReconcilePass(schema) {
+	return Boolean(schema.completionField ?? schema.triggerField ?? schema.spawn);
+}
+/** One unwatched collection's reconcile pass. Extracted so the single-flight
+*  callback doesn't close over loop state.
+*
+*  `reconcileAllItems` already swallows a failing store read (it logs and
+*  returns), so a closed session or a denied rule surfaces there, not as a
+*  rejection here. This catch is only for the unexpected — it must not let one
+*  collection's fault abort the rest of the tick. */
+async function reconcileUnwatched(gen, collection, now) {
+	try {
+		await runSingleFlight(gen.collectionSlots, collection.slug, () => reconcileAllItems(collection, gen.discoveryOpts, now));
+	} catch (err) {
+		log().warn("unwatched collection reconcile failed", {
+			slug: collection.slug,
+			error: errMsg(err)
+		});
+	}
+}
+/** Stand in for the store-change path (2) on backends that don't have one.
+*
+*  Gated on `needsReconcilePass` so a collection declaring none of it costs
+*  nothing: unlike the local backends, every pass here is a network round trip.
+*
+*  A collection that DROPS OUT of eligibility (its `completionField` edited
+*  away, or the collection removed) is not this pass's problem — `syncWatchers`
+*  already sweeps on a changed schema and on a vanished slug, and the sweep is
+*  what clears bells the declaration no longer justifies. */
+async function tickUnwatchedCollections(gen, now) {
+	if (require_store.firestoreHandle() === null) return;
+	const pending = [...gen.watchers.values()].map((entry) => entry.collection).filter((collection) => cannotReportChanges(gen, collection) && needsReconcilePass(collection.schema));
+	if (pending.length === 0) return;
+	for (const collection of pending) await reconcileUnwatched(gen, collection, now);
+	await sweepStaleActiveEntries(gen.discoveryOpts);
 }
 /** Reconcile the watcher set against the currently-discovered
 *  collections. Adds watchers for new slugs (with a boot reconcile of
@@ -603,7 +688,7 @@ async function tickTimeTriggers(gen, now = evalNow()) {
 async function syncWatchers(gen) {
 	let collections;
 	try {
-		collections = await require_discovery.discoverCollections(gen.discoveryOpts);
+		collections = await require_store.discoverCollections(gen.discoveryOpts);
 	} catch (err) {
 		log().warn("watcher discover failed", { error: errMsg(err) });
 		return false;
@@ -634,7 +719,13 @@ function stopVanishedWatchers(gen, liveSlugs) {
 *  modes. The mounted fs.watch is bound to the OLD location, so it must
 *  be remounted, not just re-reconciled. */
 function storagePathChanged(previous, next) {
-	return previous.dataSource?.path !== next.dataSource?.path || previous.dataPath !== next.dataPath || previous.storage?.path !== next.storage?.path;
+	return previous.dataSource?.path !== next.dataSource?.path || previous.dataPath !== next.dataPath || previous.storage?.type !== next.storage?.type || storageFilePath(previous.storage) !== storageFilePath(next.storage);
+}
+/** The on-disk path of a storage backend, or undefined when it has none (a
+*  shared collection keeps its records off this filesystem, so there is no
+*  mount to move — only a `type` change matters for it). */
+function storageFilePath(storage) {
+	return storage?.type === "sqlite" ? storage.path : void 0;
 }
 /** Re-reconcile already-watched collections whose schema changed since
 *  the last tick. New collections fall through to `startNewWatchers`. */
@@ -697,7 +788,7 @@ async function startWatcherFor(gen, collection) {
 	const { slug } = collection;
 	try {
 		await reconcileAllItems(collection, gen.discoveryOpts);
-		const store = require_discovery.storeFor(collection, gen.discoveryOpts);
+		const store = require_store.storeFor(collection, gen.discoveryOpts);
 		const unsubscribe = store.watch ? await store.watch((change) => {
 			handleStoreChange(gen, slug, change).catch((err) => {
 				log().warn("store change handling failed", {
@@ -751,7 +842,7 @@ async function handleStoreChange(gen, slug, change) {
 *  re-run. */
 function scheduleCollectionReconcile(gen, slug) {
 	return runSingleFlight(gen.collectionSlots, slug, async () => {
-		const collection = await require_discovery.loadCollection(slug, gen.discoveryOpts);
+		const collection = await require_store.loadCollection(slug, gen.discoveryOpts);
 		if (!collection) return;
 		await reconcileAllItems(collection, gen.discoveryOpts);
 		await sweepStaleActiveEntries(gen.discoveryOpts);
@@ -829,7 +920,7 @@ async function publishItemChange(gen, collection, itemId) {
 }
 async function itemFileExists(dataDir, itemId) {
 	try {
-		await (0, node_fs_promises.access)(require_discovery.itemFilePath(dataDir, itemId));
+		await (0, node_fs_promises.access)(require_store.itemFilePath(dataDir, itemId));
 		return true;
 	} catch {
 		return false;
@@ -844,9 +935,9 @@ async function itemFileExists(dataDir, itemId) {
 *  would be a guess. Undefined in a single-workspace host, which is exactly
 *  what the payload contract means by "the host's configured root". */
 function safePublish(gen, payload) {
-	const enriched = require_discovery.collectionChangePayload(payload, gen.discoveryOpts.workspaceRoot);
+	const enriched = require_store.collectionChangePayload(payload, gen.discoveryOpts.workspaceRoot);
 	try {
-		require_discovery.publishCollectionChange(enriched);
+		require_store.publishCollectionChange(enriched);
 	} catch (err) {
 		log().warn("collection change publish failed", {
 			slug: enriched.slug,