@mulmoclaude/core 3.6.0 → 3.10.0

package/dist/{discovery-CdkaURVY.js → discovery-B9zdNkgW.js}

@@ -1,15 +1,16 @@
 import { a as isErrorWithCode, l as isUnknownArray, r as hasNumberProp, s as isRecord } from "./dist-D8zokgGo.js";
 import { n as writeFileAtomic, t as canonicalRoot } from "./root-BMroU_mB.js";
-import { A as AGENT_INGEST_KIND, C as sharedCollectionKey, D as isSafeRecordId, I as isReadOnlySchema, L as storageKindFor, M as FEED_SCHEDULES, N as INGEST_KINDS, O as isSafeSlug, R as fieldText, T as SAFE_SLUG_PATTERN, b as localCollectionKeyOf, j as COMPUTED_TYPES, w as SAFE_RECORD_ID_PATTERN, y as isValidCollectionName, z as fieldTextOrNull } from "./calendarGrid-CQ8MVSRb.js";
+import { A as isSafeSlug, B as fieldText, D as SAFE_SLUG_PATTERN, E as SAFE_RECORD_ID_PATTERN, F as INGEST_KINDS, M as AGENT_INGEST_KIND, N as COMPUTED_TYPES, P as FEED_SCHEDULES, R as isReadOnlySchema, S as localCollectionKeyOf, T as sharedCollectionKey, V as fieldTextOrNull, k as isSafeRecordId, t as newItemId, x as isValidCollectionName, z as storageKindFor } from "./itemId-DfTm08jm.js";
 import { n as projectRecordFields } from "./project-B0j_Vf_Q.js";
+import { n as backoffDelayMs, r as classifyListenerError } from "./listen-D5av7GzB.js";
 import { n as isSafeCustomViewI18nPath, r as isSafeCustomViewPath, t as isSafeActionTemplatePath } from "./templatePath-k_WNbL_Q.js";
 import { readFileSync, realpathSync, watch } from "node:fs";
 import path from "node:path";
 import { createHash, randomBytes } from "node:crypto";
 import { lstat, mkdir, open, readFile, readdir, rename, stat, unlink, writeFile } from "node:fs/promises";
+import { z } from "zod";
 import { tmpdir } from "node:os";
 import iconv from "iconv-lite";
-import { z } from "zod";
 //#region src/host/hostSlot.ts
 function createHostSlot(name) {
 	let current = null;
@@ -104,6 +105,7 @@ function collectionChangeKey(payload, fallbackRoot) {
 var hostSlot = createHostSlot("@mulmoclaude/core/collection/server: configureCollectionHost()");
 var changePublisher = null;
 var firestoreAccessor = null;
+var sharedCollectionsSupported = false;
 /** Wire the engine to a host. Call once at server startup, before any
 *  collection storage operation. Re-binding to a *different* host throws —
 *  silently redirecting later filesystem operations to another workspace
@@ -127,6 +129,39 @@ function setCollectionChangePublisher(publish) {
 function publishCollectionChange(payload) {
 	changePublisher?.(payload);
 }
+/** Does this host serve SHARED (firestore-backed) collections at all?
+*
+*  Opt-in, and `false` until a host says otherwise, because the default has to
+*  be the safe one: a host that cannot reach Firestore must not accept a
+*  shared schema and then report the collection as empty.
+*
+*  WHY A CAPABILITY AND NOT A HOST CHECK. The engine must not know which host
+*  it is running in. The rule being expressed — shared collections live in a
+*  PROJECT REPOSITORY, not in a single managed workspace where one roster
+*  would govern every unrelated collection beside it — is a property the host
+*  knows about ITSELF. Asking the engine to test for a particular host's
+*  workspace would put a host's name in shared code and make every change to
+*  a one-host feature a change to this package.
+*
+*  WHY NOT A FIELD ON `CollectionHost`. Same reason the accessor below is not
+*  one: `configureCollectionHost` is a ONE-SHOT binding a host sets at startup
+*  and cannot re-bind, so a suite exercising this engine could not turn the
+*  capability on for itself without owning the whole host. This is the same
+*  concern as the accessor and belongs beside it.
+*
+*  NOT DERIVED FROM THE ACCESSOR. "Has a session right now" and "serves shared
+*  collections at all" are different questions: the accessor answers null
+*  between connections, and a collection must not stop being ACCEPTABLE
+*  because nobody is signed in — that would turn "connect first" into "this
+*  schema is invalid". */
+function setSharedCollectionsSupport(supported) {
+	sharedCollectionsSupported = supported;
+}
+/** Whether the host declared support. Consulted from the schema ACCEPTANCE
+*  gate, whose contract is to return a reason rather than raise. */
+function hostSupportsSharedCollections() {
+	return sharedCollectionsSupported;
+}
 /** Wire the accessor for the host's authenticated Firestore session.
 *
 *  Separate from `configureCollectionHost` for the same reason
@@ -417,8 +452,32 @@ async function guarded(key, email, run) {
 *  older version) can hold anything, so a non-object is dropped rather than
 *  surfaced as a broken record — the same fail-soft the file store applies to
 *  an unparseable `.json`. */
-function toItem(data) {
-	return isRecord(data) ? data : null;
+/** A stored document as a record — with its identity taken from the DOCUMENT
+*  ID, never from the document's own fields.
+*
+*  This is the one place a shared record's identity is decided, and it is
+*  decided against the field the writer supplied on purpose.
+*
+*  The rules can constrain the document id (`idFrom` pins it to the
+*  submitter's uid, or to uid+field) and they CANNOT constrain the value of a
+*  field: `validateOk` checks which keys are present, `keyFieldsOk` checks a
+*  declared enum, and nothing compares `request.resource.data[primaryKey]`
+*  with the path being written. So a public submitter writing at their one
+*  permitted document id could put ANY value in the primary-key field —
+*  another member's record id, or a duplicate — and every reader would take it
+*  as the record's identity. Overwriting it here makes that unreachable rather
+*  than merely discouraged, and it costs nothing: for a record written through
+*  this store the two already agree, because `firestoreWrite` writes at the id
+*  it was given.
+*
+*  It also removes the reason a submit path would have had to accept the
+*  primary key as a `createField` at all — a submission that cannot name its
+*  own id is exactly right when the id is the thing being assigned. */
+function toItem(data, docId, primaryKey) {
+	return isRecord(data) ? {
+		...data,
+		[primaryKey]: docId
+	} : null;
 }
 /** Record ids are validated with the SAME helper every other backend uses.
 *  Firestore would accept ids the file store refuses, but a record should stay
@@ -429,9 +488,9 @@ function withSafeId(itemId, onInvalid, run) {
 	if (safeId === null) return onInvalid();
 	return run(safeId, requireHandle());
 }
-async function firestoreList(key) {
+async function firestoreList(key, primaryKey) {
 	const { docs, email } = requireHandle();
-	return (await guarded(key, email, () => docs.list(sharedItemsPath(key)))).map((entry) => toItem(entry.data)).filter((item) => item !== null);
+	return (await guarded(key, email, () => docs.list(sharedItemsPath(key)))).map((entry) => toItem(entry.data, entry.id, primaryKey)).filter((item) => item !== null);
 }
 /** Paging is emulated over a full ordered read rather than pushed into
 *  Firestore: `offset` has no server-side form there (the cursor API needs the
@@ -439,7 +498,7 @@ async function firestoreList(key) {
 *  `total` needs the full count anyway. Hence `nativePaging: false` — the
 *  capability is honest about the cost. */
 async function firestorePage(key, primaryKey, opts) {
-	const items = await firestoreList(key);
+	const items = await firestoreList(key, primaryKey);
 	const offset = Math.max(0, opts.offset ?? 0);
 	return {
 		items: projectItemFields(opts.limit === void 0 ? items.slice(offset) : items.slice(offset, offset + Math.max(0, opts.limit)), opts.fields, primaryKey),
@@ -447,8 +506,8 @@ async function firestorePage(key, primaryKey, opts) {
 		truncated: false
 	};
 }
-async function firestoreRead(key, itemId) {
-	return withSafeId(itemId, () => Promise.resolve(null), async (safeId, { docs, email }) => toItem(await guarded(key, email, () => docs.get(sharedItemsPath(key), safeId))));
+async function firestoreRead(key, itemId, primaryKey) {
+	return withSafeId(itemId, () => Promise.resolve(null), async (safeId, { docs, email }) => toItem(await guarded(key, email, () => docs.get(sharedItemsPath(key), safeId)), safeId, primaryKey));
 }
 /** Publish the "records changed" ping for a shared collection.
 *
@@ -499,6 +558,111 @@ async function firestoreDelete(key, itemId, opts) {
 		};
 	});
 }
+/** Deliver one snapshot's changes.
+*
+*  THE FIRST SNAPSHOT IS ONE COLLECTION-LEVEL REPORT, not N per-record ones.
+*  `onSnapshot` hands over the collection's current contents immediately, as a
+*  snapshot in which every existing document reads as `added`.
+*
+*  Dropping it is wrong. There is a GAP on either side of a subscription — the
+*  boot reconcile finishes before the listener arms, and a listener that died
+*  is re-armed after a backoff — and a record that moved inside one of those
+*  gaps appears only in that first snapshot. Since this backend now HAS a
+*  `watch`, the watcher's periodic re-derivation no longer covers it, so a
+*  dropped first snapshot means stale bells and stale views until that record
+*  happens to change again. That is exactly the failure this step was supposed
+*  to remove.
+*
+*  Announcing every record individually is also wrong: it is a refresh storm
+*  to every open view, on every mount and every reconnect. `{ kind: "collection" }`
+*  says the same thing in one event — the watcher answers it with a full
+*  re-derivation plus a sweep, which is precisely "work out what changed while
+*  I was not listening".
+*
+*  A change this process made itself also arrives here — the write path has
+*  already published for it, so the record is reconciled twice. Harmless
+*  (reconciling is idempotent) and left alone: suppressing it would mean
+*  tracking our own in-flight writes, and getting that wrong loses a real
+*  change rather than a duplicate one. */
+function deliverSnapshot(run, ids, initial) {
+	if (run.stopped) return;
+	if (initial) {
+		run.onChange({ kind: "collection" });
+		return;
+	}
+	for (const itemId of ids) run.onChange({
+		kind: "item",
+		itemId
+	});
+}
+/** A listener died. Firestore never revives one on its own, so the choice is
+*  re-subscribe or go dark.
+*
+*  NO OVERALL RETRY WINDOW, unlike `hostRunner`'s listener. There, giving up
+*  escalates to a lifecycle owner that can re-authenticate; here there is
+*  nobody above to escalate to — the watcher registers a mounted collection
+*  once and never re-arms it, so "give up" means this collection serves stale
+*  data until the server restarts. A capped 30s re-subscribe is cheap and
+*  makes recovery automatic when the session comes back.
+*
+*  A FATAL error still stops: `permission-denied` is what a revoked membership
+*  looks like, and re-listening cannot restore a grant. It is logged as such
+*  rather than retried in silence. */
+function handleWatchError(run, error) {
+	if (run.stopped) return;
+	if (classifyListenerError(error) === "fatal") {
+		log.warn("collections", "shared collection listener stopped", {
+			aid: run.key.aid,
+			cid: run.key.cid,
+			error: isRecord(error) && typeof error.message === "string" ? error.message : String(error),
+			detail: "live updates for this collection are off until the server re-syncs; a revoked membership looks exactly like this"
+		});
+		return;
+	}
+	run.retryTimer = setTimeout(() => subscribeShared(run), backoffDelayMs(run.attempt));
+	run.attempt += 1;
+}
+/** (Re-)arm the listener. The handle is fetched HERE rather than captured: a
+*  retry may land after the session was replaced, and listening through a
+*  closed session's handle would fail forever. */
+function subscribeShared(run) {
+	run.retryTimer = null;
+	if (run.stopped) return;
+	const handle = firestoreHandle();
+	if (handle === null) {
+		run.retryTimer = setTimeout(() => subscribeShared(run), backoffDelayMs(run.attempt));
+		run.attempt += 1;
+		return;
+	}
+	run.detach = handle.docs.watch(sharedItemsPath(run.key), (ids, meta) => {
+		run.attempt = 0;
+		deliverSnapshot(run, ids, meta.initial);
+	}, (error) => handleWatchError(run, error));
+}
+/** Subscribe to a shared collection's records.
+*
+*  Returns `null` when there is no session: the watcher reads that as "has a
+*  watch but could not arm it", leaves the collection unmounted and retries on
+*  the next sync tick — which is the right channel for a connection that has
+*  not happened yet. Arming a dead listener instead would mark the slug mounted
+*  forever. */
+function armSharedWatch(key, onChange) {
+	if (firestoreHandle() === null) return null;
+	const run = {
+		key,
+		onChange,
+		stopped: false,
+		detach: () => {},
+		retryTimer: null,
+		attempt: 0
+	};
+	subscribeShared(run);
+	return () => {
+		run.stopped = true;
+		if (run.retryTimer !== null) clearTimeout(run.retryTimer);
+		run.detach();
+	};
+}
 /** The store factory registered for `storage.type === "firestore"`.
 *  Synchronous and connection-agnostic by contract — see the header. */
 function firestoreStoreFor(collection, opts) {
@@ -513,14 +677,15 @@ function firestoreStoreFor(collection, opts) {
 			nativeQuery: false,
 			nativePaging: false
 		},
-		list: async () => firestoreList(keyOf(collection)),
+		list: async () => firestoreList(keyOf(collection), primaryKey),
 		page: async (pageOpts = {}) => firestorePage(keyOf(collection), primaryKey, pageOpts),
-		read: async (itemId) => firestoreRead(keyOf(collection), itemId),
+		read: async (itemId) => firestoreRead(keyOf(collection), itemId, primaryKey),
 		write: async (itemId, item, writeOpts = {}) => firestoreWrite(keyOf(collection), itemId, item, {
 			...ioOpts,
 			refuseOverwrite: writeOpts.refuseOverwrite
 		}),
-		delete: async (itemId) => firestoreDelete(keyOf(collection), itemId, ioOpts)
+		delete: async (itemId) => firestoreDelete(keyOf(collection), itemId, ioOpts),
+		watch: async (onChange) => armSharedWatch(keyOf(collection), onChange)
 	};
 }
 //#endregion
@@ -810,11 +975,13 @@ async function deleteItem(dataDir, itemId, opts = {}) {
 		throw err;
 	}
 }
-/** Generate a short random hex id. Used by POST when the form doesn't
-*  carry a primary-key value (UI shortcut — Claude normally derives a
-*  semantic id from the record's name). */
+/** Generate a record id. Used by POST when the form doesn't carry a
+*  primary-key value (UI shortcut — Claude normally derives a semantic
+*  id from the record's name). Delegates to the isomorphic generator, so
+*  the id the UI pre-fills and the id a blank-id POST mints stay the
+*  same thing rather than two implementations that have to agree. */
 function generateItemId() {
-	return randomBytes(4).toString("hex");
+	return newItemId();
 }
 /** The item id a CREATE should use for `schema`, or null when the
 *  caller should generate one. A singleton collection pins every
@@ -2972,6 +3139,10 @@ function acceptStorageSchema(storage, opts) {
 			storageFile
 		};
 	}
+	if (!hostSupportsSharedCollections()) return {
+		ok: false,
+		reason: "this host does not support shared collections — they live in a project repository, not a managed workspace"
+	};
 	const manifest = loadAppManifest(opts.workspaceRoot);
 	if (!manifest.ok) return {
 		ok: false,
@@ -3130,6 +3301,6 @@ function toDetail(collection) {
 	};
 }
 //#endregion
-export { collectionsRegistriesConfigPath as $, readItem as A, SCHEMA_FILE as B, CollectionQueryZ as C, generateItemId as D, deleteItem as E, loadAppManifest as F, safeRecordId as G, itemFilePath as H, parseAppManifest as I, isBackendUnavailable as J, safeSlugName as K, sharedItemsPath as L, writeItem as M, APP_MANIFEST_FILE as N, isRegularFile as O, appManifestReason as P, collectionChangePayload as Q, pageFromFullRead as R, compileJsonlQuery as S, MAX_QUERY_ROWS as T, resolveDataDir as U, isContainedInRoot as V, resolveTemplatePath as W, archiveDir as X, COLLECTION_ROOT_REQUIRED as Y, collectionChangeKey as Z, dedupeByRecordId as _, toDetail as a, log as at, queryCsv as b, resolveMutateSet as c, publishCollectionChange as ct, storeFor as d, sharedCollectionChangePayload as dt, configureCollectionHost as et, checkpointSqliteDatabase as f, skillsStagingDir as ft, decodeCsvRecordId as g, csvRowToItem as h, createHostSlot as ht, resolvePrimaryField as i, localCollectionKey as it, resolveCreateItemId as j, listItems as k, collectionWritable as l, setCollectionChangePublisher as lt, cacheDir as m, createForwardingLogger as mt, discoverCollections as n, getWorkspaceRoot as nt, toSummary as o, peekWorkspaceRoot as ot, MAX_CSV_ROWS as p, stagingSkillDir as pt, BackendUnavailableError as q, loadCollection as r, isPresetSlug as rt, CollectionSchemaZ as s, projectSkillsDir as st, acceptParsedSchema as t, firestoreHandle as tt, readOnlyRefusal as u, setFirestoreAccessor as ut, encodeCsvRecordId as v, DEFAULT_QUERY_ROWS as w, compileCsvQuery as x, normalizeCsvValue as y, projectItemFields as z };
+export { collectionsRegistriesConfigPath as $, readItem as A, SCHEMA_FILE as B, CollectionQueryZ as C, generateItemId as D, deleteItem as E, loadAppManifest as F, safeRecordId as G, itemFilePath as H, parseAppManifest as I, isBackendUnavailable as J, safeSlugName as K, sharedItemsPath as L, writeItem as M, APP_MANIFEST_FILE as N, isRegularFile as O, appManifestReason as P, collectionChangePayload as Q, pageFromFullRead as R, compileJsonlQuery as S, MAX_QUERY_ROWS as T, resolveDataDir as U, isContainedInRoot as V, resolveTemplatePath as W, archiveDir as X, COLLECTION_ROOT_REQUIRED as Y, collectionChangeKey as Z, dedupeByRecordId as _, createHostSlot as _t, toDetail as a, localCollectionKey as at, queryCsv as b, resolveMutateSet as c, projectSkillsDir as ct, storeFor as d, setFirestoreAccessor as dt, configureCollectionHost as et, checkpointSqliteDatabase as f, setSharedCollectionsSupport as ft, decodeCsvRecordId as g, createForwardingLogger as gt, csvRowToItem as h, stagingSkillDir as ht, resolvePrimaryField as i, isPresetSlug as it, resolveCreateItemId as j, listItems as k, collectionWritable as l, publishCollectionChange as lt, cacheDir as m, skillsStagingDir as mt, discoverCollections as n, getWorkspaceRoot as nt, toSummary as o, log as ot, MAX_CSV_ROWS as p, sharedCollectionChangePayload as pt, BackendUnavailableError as q, loadCollection as r, hostSupportsSharedCollections as rt, CollectionSchemaZ as s, peekWorkspaceRoot as st, acceptParsedSchema as t, firestoreHandle as tt, readOnlyRefusal as u, setCollectionChangePublisher as ut, encodeCsvRecordId as v, DEFAULT_QUERY_ROWS as w, compileCsvQuery as x, normalizeCsvValue as y, projectItemFields as z };
 
-//# sourceMappingURL=discovery-CdkaURVY.js.map
+//# sourceMappingURL=discovery-B9zdNkgW.js.map