@electric-ax/agents-server 0.4.20 → 0.5.1

package/dist/index.js

@@ -8,7 +8,7 @@ import postgres from "postgres";
 import { and, desc, eq, inArray, lt, ne, sql } from "drizzle-orm";
 import { bigint, bigserial, boolean, check, index, integer, jsonb, pgTable, primaryKey, serial, text, timestamp, unique } from "drizzle-orm/pg-core";
 import { createHash, createPrivateKey, createPublicKey, generateKeyPairSync, randomUUID, sign } from "node:crypto";
-import { COMPOSER_INPUT_MESSAGE_TYPE, appendPathToUrl, assertTags, buildEventSourceManifestEntry, buildTagsIndex, canonicalPgSyncOptions, entityStateSchema, eventSourceSubscriptionManifestKey, getCronStreamPath, getCronStreamPathFromSpec, getEntitiesStreamPath, getNextCronFireAt, getPgSyncStreamPath, getSharedStateStreamPath, getWebhookStreamPath, hashString, manifestChildKey, manifestSharedStateKey, manifestSourceKey, normalizeTags, parseCronStreamPath, resolveCronScheduleSpec, resolveEventSourceSubscription, sourceRefForPgSync, sourceRefForTags, validateComposerInputPayload, validateSlashCommandDefinitions, verifyWebhookSignature } from "@electric-ax/agents-runtime";
+import { COMMENTS_CONTRACT, COMPOSER_INPUT_MESSAGE_TYPE, appendPathToUrl, assertTags, buildTagsIndex, buildWebhookSourceManifestEntry, canonicalPgSyncOptions, entityStateSchema, getCronStreamPath, getCronStreamPathFromSpec, getEntitiesStreamPath, getNextCronFireAt, getPgSyncStreamPath, getSharedStateStreamPath, getWebhookStreamPath, hashString, manifestChildKey, manifestSharedStateKey, manifestSourceKey, normalizeTags, parseCronStreamPath, resolveCronScheduleSpec, resolveWebhookSourceSubscription, sourceRefForPgSync, sourceRefForTags, validateComposerInputPayload, validateSlashCommandDefinitions, verifyWebhookSignature, webhookSourceSubscriptionManifestKey } from "@electric-ax/agents-runtime";
 import { DurableStream, DurableStreamError, FetchError, IdempotentProducer } from "@durable-streams/client";
 import { ShapeStream, isChangeMessage, isControlMessage } from "@electric-sql/client";
 import pino from "pino";
@@ -50,6 +50,7 @@ const entityTypes = pgTable(`entity_types`, {
 	creationSchema: jsonb(`creation_schema`),
 	inboxSchemas: jsonb(`inbox_schemas`),
 	stateSchemas: jsonb(`state_schemas`),
+	externallyWritableCollections: jsonb(`externally_writable_collections`).$type(),
 	slashCommands: jsonb(`slash_commands`),
 	serveEndpoint: text(`serve_endpoint`),
 	defaultDispatchPolicy: jsonb(`default_dispatch_policy`),
@@ -837,6 +838,7 @@ var PostgresRegistry = class {
 			creationSchema: et.creation_schema ?? null,
 			inboxSchemas: et.inbox_schemas ?? null,
 			stateSchemas: et.state_schemas ?? null,
+			externallyWritableCollections: et.externally_writable_collections ?? null,
 			slashCommands: et.slash_commands ?? null,
 			serveEndpoint: et.serve_endpoint ?? null,
 			defaultDispatchPolicy: et.default_dispatch_policy ?? null,
@@ -850,6 +852,7 @@ var PostgresRegistry = class {
 				creationSchema: et.creation_schema ?? null,
 				inboxSchemas: et.inbox_schemas ?? null,
 				stateSchemas: et.state_schemas ?? null,
+				externallyWritableCollections: et.externally_writable_collections ?? null,
 				slashCommands: et.slash_commands ?? null,
 				serveEndpoint: et.serve_endpoint ?? null,
 				defaultDispatchPolicy: et.default_dispatch_policy ?? null,
@@ -868,6 +871,7 @@ var PostgresRegistry = class {
 			creationSchema: et.creation_schema ?? null,
 			inboxSchemas: et.inbox_schemas ?? null,
 			stateSchemas: et.state_schemas ?? null,
+			externallyWritableCollections: et.externally_writable_collections ?? null,
 			slashCommands: et.slash_commands ?? null,
 			serveEndpoint: et.serve_endpoint ?? null,
 			defaultDispatchPolicy: et.default_dispatch_policy ?? null,
@@ -895,6 +899,7 @@ var PostgresRegistry = class {
 			creationSchema: et.creation_schema ?? null,
 			inboxSchemas: et.inbox_schemas ?? null,
 			stateSchemas: et.state_schemas ?? null,
+			externallyWritableCollections: et.externally_writable_collections ?? null,
 			slashCommands: et.slash_commands ?? null,
 			serveEndpoint: et.serve_endpoint ?? null,
 			defaultDispatchPolicy: et.default_dispatch_policy ?? null,
@@ -1339,7 +1344,6 @@ var PostgresRegistry = class {
 			set: {
 				options: row.options,
 				streamUrl: row.streamUrl,
-				initialSnapshotComplete: false,
 				lastTouchedAt: new Date(),
 				updatedAt: new Date()
 			}
@@ -1378,6 +1382,9 @@ var PostgresRegistry = class {
 			updatedAt: new Date()
 		}).where(this.pgSyncBridgeWhere(sourceRef));
 	}
+	async deletePgSyncBridge(sourceRef) {
+		await this.db.delete(pgSyncBridges).where(this.pgSyncBridgeWhere(sourceRef));
+	}
 	async upsertEntityBridge(row) {
 		await this.db.insert(entityBridges).values({
 			tenantId: this.tenantId,
@@ -1540,6 +1547,7 @@ var PostgresRegistry = class {
 			creation_schema: row.creationSchema,
 			inbox_schemas: row.inboxSchemas,
 			state_schemas: row.stateSchemas,
+			externally_writable_collections: row.externallyWritableCollections ?? void 0,
 			slash_commands: row.slashCommands ?? void 0,
 			serve_endpoint: row.serveEndpoint ?? void 0,
 			default_dispatch_policy: row.defaultDispatchPolicy ?? void 0,
@@ -3258,9 +3266,6 @@ function assertSharedSandboxColocated(key, chosenIsRemote, dispatchPolicy) {
 function isRecord$1(value) {
 	return typeof value === `object` && value !== null && !Array.isArray(value);
 }
-function getPgSyncManifestStreamPath(sourceRef) {
-	return `/_electric/pg-sync/${sourceRef}`;
-}
 function extractManifestSourceUrl(manifest) {
 	if (!manifest) return void 0;
 	if (manifest.kind === `child` || manifest.kind === `observe`) return typeof manifest.entity_url === `string` ? manifest.entity_url : void 0;
@@ -3273,7 +3278,7 @@ function extractManifestSourceUrl(manifest) {
 		}
 		if (manifest.sourceType === `entities`) return typeof manifest.sourceRef === `string` ? `/_entities/${manifest.sourceRef}` : void 0;
 		if (manifest.sourceType === `db`) return typeof manifest.sourceRef === `string` ? getSharedStateStreamPath(manifest.sourceRef) : void 0;
-		if (manifest.sourceType === `pgSync`) return typeof manifest.sourceRef === `string` ? getPgSyncManifestStreamPath(manifest.sourceRef) : void 0;
+		if (manifest.sourceType === `pgSync`) return typeof config?.streamUrl === `string` ? config.streamUrl : void 0;
 		if (manifest.sourceType === `webhook`) {
 			if (typeof config?.streamUrl === `string`) return config.streamUrl;
 			if (typeof config?.endpointKey === `string`) return getWebhookStreamPath(config.endpointKey, typeof config.bucket === `string` ? config.bucket : void 0);
@@ -3469,6 +3474,7 @@ var EntityManager = class {
 			creation_schema: req.creation_schema,
 			inbox_schemas: req.inbox_schemas,
 			state_schemas: req.state_schemas,
+			externally_writable_collections: req.externally_writable_collections,
 			slash_commands: req.slash_commands,
 			serve_endpoint: req.serve_endpoint,
 			default_dispatch_policy: defaultDispatchPolicy,
@@ -4564,6 +4570,40 @@ var EntityManager = class {
 			throw err;
 		}
 	}
+	async writeCollection(entityUrl, collection, req) {
+		const entity = await this.registry.getEntity(entityUrl);
+		if (!entity) throw new ElectricAgentsError(ErrCodeNotFound, `Entity not found`, 404);
+		const { externallyWritableCollections } = await this.getEffectiveSchemas(entity);
+		const config = externallyWritableCollections?.[collection];
+		if (!config) throw new ElectricAgentsError(ErrCodeUnauthorized, `Collection "${collection}" is not writable`, 403);
+		const allowedOperations = config.operations ?? [`insert`];
+		if (!allowedOperations.includes(req.operation)) throw new ElectricAgentsError(ErrCodeUnauthorized, `Operation "${req.operation}" is not allowed on collection "${collection}"`, 403);
+		if (rejectsNormalWrites(entity.status)) throw new ElectricAgentsError(ErrCodeNotRunning, `Entity is not accepting writes`, 409);
+		if (this.isForkWorkLockedEntity(entityUrl)) this.assertEntityNotForkWorkLocked(entityUrl);
+		if (req.operation !== `delete` && (req.value === void 0 || req.value === null)) throw new ElectricAgentsError(ErrCodeInvalidRequest, `value is required for ${req.operation}`, 400);
+		if (req.operation !== `insert` && !req.key) throw new ElectricAgentsError(ErrCodeInvalidRequest, `key is required for ${req.operation}`, 400);
+		const key = req.key ?? `${collection}-${randomUUID()}`;
+		const event = {
+			type: config.type,
+			key,
+			headers: {
+				operation: req.operation,
+				timestamp: new Date().toISOString(),
+				principal: req.principal
+			}
+		};
+		if (req.operation !== `delete`) event.value = req.value;
+		const validationError = await this.validateWriteEvent(entity, event);
+		if (validationError) throw new ElectricAgentsError(validationError.code, validationError.message, validationError.status);
+		const encoded = this.encodeChangeEvent(event);
+		try {
+			await this.streamClient.append(entity.streams.main, encoded);
+		} catch (err) {
+			if (this.isClosedStreamError(err)) throw new ElectricAgentsError(ErrCodeNotRunning, `Entity is stopped`, 409);
+			throw err;
+		}
+		return { key };
+	}
 	async updateInboxMessage(entityUrl, key, req) {
 		const entity = await this.registry.getEntity(entityUrl);
 		if (!entity) throw new ElectricAgentsError(ErrCodeNotFound, `Entity not found`, 404);
@@ -4830,7 +4870,7 @@ var EntityManager = class {
 		await this.writeManifestEntry(entityUrl, manifestKey, `delete`, void 0, { txid });
 		return { txid };
 	}
-	async upsertEventSourceSubscription(entityUrl, req) {
+	async upsertWebhookSourceSubscription(entityUrl, req) {
 		const manifestKey = req.subscription.manifestKey;
 		const txid = randomUUID();
 		await this.writeManifestEntry(entityUrl, manifestKey, `upsert`, req.manifest, { txid });
@@ -4852,8 +4892,20 @@ var EntityManager = class {
 			subscription: req.subscription
 		};
 	}
-	async deleteEventSourceSubscription(entityUrl, req) {
-		const manifestKey = eventSourceSubscriptionManifestKey(req.id);
+	async deleteWebhookSourceSubscription(entityUrl, req) {
+		const manifestKey = webhookSourceSubscriptionManifestKey(req.id);
+		const txid = randomUUID();
+		await this.writeManifestEntry(entityUrl, manifestKey, `delete`, void 0, { txid });
+		await this.wakeRegistry.unregisterByManifestKey(entityUrl, manifestKey, this.tenantId);
+		return { txid };
+	}
+	/**
+	* Stop this entity observing a pg-sync source: drop its manifest entry and
+	* the wake it anchors. The shared pg-sync bridge (keyed by sourceRef, not by
+	* subscriber) is intentionally left running for any other observers.
+	*/
+	async deletePgSyncObservation(entityUrl, req) {
+		const manifestKey = `source:pgSync:${req.sourceRef}`;
 		const txid = randomUUID();
 		await this.writeManifestEntry(entityUrl, manifestKey, `delete`, void 0, { txid });
 		await this.wakeRegistry.unregisterByManifestKey(entityUrl, manifestKey, this.tenantId);
@@ -5256,7 +5308,8 @@ var EntityManager = class {
 	async getEffectiveSchemas(entity) {
 		if (!entity.type) return {
 			inboxSchemas: entity.inbox_schemas,
-			stateSchemas: entity.state_schemas
+			stateSchemas: entity.state_schemas,
+			externallyWritableCollections: void 0
 		};
 		const latestType = await this.registry.getEntityType(entity.type);
 		return {
@@ -5267,7 +5320,8 @@ var EntityManager = class {
 			stateSchemas: latestType?.state_schemas ? {
 				...entity.state_schemas ?? {},
 				...latestType.state_schemas
-			} : entity.state_schemas
+			} : entity.state_schemas,
+			externallyWritableCollections: latestType?.externally_writable_collections
 		};
 	}
 	isClosedStreamError(err) {
@@ -5957,9 +6011,13 @@ var Scheduler = class {
 
 //#endregion
 //#region src/pg-sync-bridge-manager.ts
-const PG_SYNC_ELECTRIC_SHAPE_URL = process.env.ELECTRIC_AGENTS_PG_SYNC_ELECTRIC_URL ?? `http://localhost:3000/v1/shape`;
+/** Registration was rejected because the source itself is invalid — map to a 4xx. */
+var PgSyncSourceValidationError = class extends Error {
+	name = `PgSyncSourceValidationError`;
+};
 const DEFAULT_RETRY_INITIAL_DELAY_MS = 1e3;
 const DEFAULT_RETRY_MAX_DELAY_MS = 3e4;
+const DEFAULT_PROBE_TIMEOUT_MS = 1e4;
 function buildElectricShapeParams(options) {
 	return {
 		table: options.table,
@@ -5979,6 +6037,31 @@ function buildElectricShapeParams(options) {
 		...options.metadata?.wakeId ? { electric_agents_wake_id: options.metadata.wakeId } : {}
 	};
 }
+/**
+* Build the one-shot URL used to validate a shape source at registration
+* time. Approximates the query-param encoding of the Electric TS client
+* (arrays comma-joined, where-clause params as `params[n]`) — unlike the
+* client it does not quote column identifiers, so probe and stream encoding
+* can diverge for exotic column names.
+*/
+function buildShapeProbeUrl(sourceUrl, options) {
+	let url;
+	try {
+		url = new URL(sourceUrl);
+	} catch {
+		throw new PgSyncSourceValidationError(`pgSync url "${sourceUrl}" is not a valid URL`);
+	}
+	if (url.protocol !== `http:` && url.protocol !== `https:`) throw new PgSyncSourceValidationError(`pgSync url "${sourceUrl}" must be an HTTP(S) Electric shape endpoint, not a database connection string`);
+	for (const [key, value] of Object.entries(buildElectricShapeParams(options))) {
+		if (value === void 0 || value === null) continue;
+		if (Array.isArray(value)) if (key === `params`) value.forEach((item, index$1) => url.searchParams.set(`params[${index$1 + 1}]`, String(item)));
+		else url.searchParams.set(key, value.join(`,`));
+		else if (typeof value === `object`) for (const [k, v] of Object.entries(value)) url.searchParams.set(`${key}[${k}]`, String(v));
+		else url.searchParams.set(key, String(value));
+	}
+	url.searchParams.set(`offset`, `now`);
+	return url;
+}
 function jsonSafe(value) {
 	if (typeof value === `bigint`) return value.toString();
 	if (value === null || typeof value !== `object`) return value;
@@ -6000,37 +6083,19 @@ function rowKeyForMessage(message) {
 	const candidate = headers.key ?? headers.rowKey ?? message.value?.id ?? message.value?.key ?? message.old_value?.id ?? message.old_value?.key;
 	return candidate === void 0 ? void 0 : stableJson(candidate);
 }
-function pgSyncMessageToDurableEvent(message, optionsOrSourceRef) {
+function pgSyncMessageToDurableEvent(message) {
 	const operation = message.headers.operation;
 	if (operation !== `insert` && operation !== `update` && operation !== `delete`) return null;
-	const sourceRef = typeof optionsOrSourceRef === `string` ? optionsOrSourceRef : sourceRefForPgSync(optionsOrSourceRef);
-	const rowKey = rowKeyForMessage(message);
-	const offset = message.headers.offset;
-	if (typeof offset !== `string` || offset.length === 0) return null;
-	const messageKeyPart = offset;
-	const messageKey = `${sourceRef}:${operation}:${messageKeyPart}`;
-	const timestamp$1 = new Date().toISOString();
-	const oldValue = message.old_value;
-	const safeValue = jsonSafe(message.value);
-	const safeOldValue = jsonSafe(oldValue);
-	const safeHeaders = jsonSafe(message.headers);
+	const key = message.key ?? (typeof message.headers.key === `string` ? message.headers.key : void 0) ?? rowKeyForMessage(message);
+	if (!key) return null;
+	const safeMessage = jsonSafe(message);
 	return {
 		type: `pg_sync_change`,
-		key: messageKey,
-		value: {
-			key: messageKey,
-			table: typeof optionsOrSourceRef === `string` ? void 0 : optionsOrSourceRef.table,
-			operation,
-			...rowKey !== void 0 ? { rowKey } : {},
-			...message.value !== void 0 ? { value: safeValue } : {},
-			...oldValue !== void 0 ? { oldValue: safeOldValue } : {},
-			headers: safeHeaders,
-			...typeof offset === `string` ? { offset } : {},
-			receivedAt: timestamp$1
-		},
+		key,
+		value: safeMessage,
 		headers: {
-			operation,
-			timestamp: timestamp$1
+			...jsonSafe(message.headers),
+			operation
 		}
 	};
 }
@@ -6120,13 +6185,13 @@ var PgSyncBridge = class {
 					}
 					if (!isChangeMessage(message)) continue;
 					if (!this.skipChangesUntilUpToDate) {
-						const event = pgSyncMessageToDurableEvent(message, this.options);
+						const event = pgSyncMessageToDurableEvent(message);
 						if (event) {
 							if (!this.producer) throw new Error(`pg-sync producer is not started`);
 							await this.producer.append(JSON.stringify(event));
 							await this.producer.flush?.();
 							await this.evaluateWakes?.(this.streamUrl, event);
-						}
+						} else serverLog.warn(`[pg-sync-bridge] dropped change message for ${this.sourceRef} (unknown operation or missing row key):`, message.headers);
 					}
 					await this.persistCursor(stream);
 					this.retryAttempt = 0;
@@ -6175,13 +6240,15 @@ var PgSyncBridge = class {
 var PgSyncBridgeManager = class {
 	bridges = new Map();
 	starting = new Map();
-	url;
 	retry;
+	fetchFn;
+	probeTimeoutMs;
 	constructor(streamClient, evaluateWakes, registry, options = {}) {
 		this.streamClient = streamClient;
 		this.evaluateWakes = evaluateWakes;
 		this.registry = registry;
-		this.url = options.url ?? PG_SYNC_ELECTRIC_SHAPE_URL;
+		this.fetchFn = options.fetchFn;
+		this.probeTimeoutMs = options.probeTimeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS;
 		this.retry = {
 			initialDelayMs: options.retry?.initialDelayMs ?? DEFAULT_RETRY_INITIAL_DELAY_MS,
 			maxDelayMs: options.retry?.maxDelayMs ?? DEFAULT_RETRY_MAX_DELAY_MS,
@@ -6192,9 +6259,16 @@ var PgSyncBridgeManager = class {
 	async start() {
 		const rows = await this.registry?.listPgSyncBridges?.();
 		if (!rows) return;
-		await Promise.all(rows.map((row) => this.ensureBridge(row).catch((error) => {
-			serverLog.warn(`[pg-sync-bridge] failed to start ${row.sourceRef}:`, error);
-		})));
+		await Promise.all(rows.map(async (row) => {
+			if (!row.options.url) {
+				serverLog.warn(`[pg-sync-bridge] deleting registration ${row.sourceRef}: it predates required source URLs; re-register the observation with an explicit Electric shape URL`);
+				await this.registry?.deletePgSyncBridge?.(row.sourceRef);
+				return;
+			}
+			await this.ensureBridge(row).catch((error) => {
+				serverLog.warn(`[pg-sync-bridge] failed to start ${row.sourceRef}:`, error);
+			});
+		}));
 	}
 	async register(options, metadata) {
 		const mergedMetadata = {
@@ -6208,6 +6282,7 @@ var PgSyncBridgeManager = class {
 		const resolvedSource = this.resolveSource(canonicalOptions);
 		const sourceRef = sourceRefForPgSync(canonicalOptions);
 		const streamUrl = getPgSyncStreamPath(sourceRef, this.registry?.tenantId);
+		if (!this.bridges.has(sourceRef) && !this.starting.has(sourceRef)) await this.probeSource(resolvedSource, canonicalOptions);
 		const row = await this.registry?.upsertPgSyncBridge({
 			sourceRef,
 			options: canonicalOptions,
@@ -6248,7 +6323,32 @@ var PgSyncBridgeManager = class {
 		await start;
 	}
 	resolveSource(options) {
-		return { url: options.url ?? this.url };
+		if (!options.url) throw new PgSyncSourceValidationError(`pgSync source url is required; no server default is configured`);
+		return { url: options.url };
+	}
+	/**
+	* One-shot fetch of the shape log before a bridge is created, so a bad
+	* URL or rejected shape fails the registration instead of dying silently
+	* in the bridge's retry loop.
+	*/
+	async probeSource(source, options) {
+		const probeUrl = buildShapeProbeUrl(source.url, options);
+		const fetchFn = this.fetchFn ?? globalThis.fetch;
+		let response;
+		try {
+			response = await fetchFn(probeUrl, { signal: AbortSignal.timeout(this.probeTimeoutMs) });
+		} catch (error) {
+			throw new PgSyncSourceValidationError(`pgSync source at ${source.url} is unreachable: ${error instanceof Error ? error.message : String(error)}`);
+		}
+		if (!response.ok) {
+			const body = (await response.text().catch(() => `<failed to read body>`)).slice(0, 500);
+			throw new PgSyncSourceValidationError(`pgSync source at ${source.url} rejected the shape request (${response.status})${body ? `: ${body}` : ``}`);
+		}
+		if (!response.headers.get(`electric-handle`)) {
+			const suggestion = new URL(source.url);
+			suggestion.pathname = `/v1/shape`;
+			throw new PgSyncSourceValidationError(`pgSync source at ${source.url} responded but is not a shape log (missing electric-handle header) — the Electric shape API is usually served at ${suggestion.origin}/v1/shape`);
+		}
 	}
 	async stop() {
 		await Promise.allSettled(this.starting.values());
@@ -7210,6 +7310,7 @@ var WakeRegistry = class {
 		};
 		if (value && `value` in value) change.value = value.value;
 		if (value && `oldValue` in value) change.oldValue = value.oldValue;
+		else if (value && `old_value` in value) change.oldValue = value.old_value;
 		if (eventType === `inbox`) {
 			if (typeof value?.from === `string`) change.from = value.from;
 			if (typeof value?.from_principal === `string`) change.from_principal = value.from_principal;
@@ -8505,6 +8606,15 @@ const spawnBodySchema = Type.Object({
 		manifestKey: Type.Optional(Type.String())
 	}))
 });
+const writeCollectionBodySchema = Type.Object({
+	operation: Type.Union([
+		Type.Literal(`insert`),
+		Type.Literal(`update`),
+		Type.Literal(`delete`)
+	]),
+	key: Type.Optional(Type.String()),
+	value: Type.Optional(Type.Record(Type.String(), Type.Unknown()))
+}, { additionalProperties: false });
 const sendBodySchema = Type.Object({
 	payload: Type.Optional(Type.Unknown()),
 	key: Type.Optional(Type.String()),
@@ -8614,8 +8724,8 @@ const subscriptionLifetimeSchema = Type.Union([
 	}),
 	Type.Object({ kind: Type.Literal(`manual`) })
 ]);
-const eventSourceSubscriptionBodySchema = Type.Object({
-	sourceKey: Type.String(),
+const webhookSourceSubscriptionBodySchema = Type.Object({
+	webhookKey: Type.String(),
 	bucketKey: Type.Optional(Type.String()),
 	params: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
 	filterKey: Type.Optional(Type.String()),
@@ -8637,6 +8747,7 @@ entitiesRouter.head(`/:type/:instanceId`, withExistingEntity, withEntityPermissi
 entitiesRouter.delete(`/:type/:instanceId`, withExistingEntity, withEntityPermission(`delete`), killEntity);
 entitiesRouter.post(`/:type/:instanceId/signal`, withExistingEntity, withSchema(signalBodySchema), withEntityPermission(`signal`), signalEntity);
 entitiesRouter.post(`/:type/:instanceId/send`, withExistingEntity, withSchema(sendBodySchema), withEntityPermission(`write`), sendEntity);
+entitiesRouter.post(`/:type/:instanceId/collections/:collection`, withExistingEntity, withSchema(writeCollectionBodySchema), withEntityPermission(`write`), writeCollection);
 entitiesRouter.post(`/:type/:instanceId/attachments`, withExistingEntity, withEntityPermission(`write`), createAttachment);
 entitiesRouter.get(`/:type/:instanceId/attachments/:attachmentId`, withExistingEntity, withEntityPermission(`read`), readAttachment);
 entitiesRouter.delete(`/:type/:instanceId/attachments/:attachmentId`, withExistingEntity, withEntityPermission(`write`), deleteAttachment);
@@ -8647,8 +8758,9 @@ entitiesRouter.post(`/:type/:instanceId/tags/:tagKey`, withExistingEntity, withS
 entitiesRouter.delete(`/:type/:instanceId/tags/:tagKey`, withExistingEntity, withEntityPermission(`write`), deleteTag);
 entitiesRouter.put(`/:type/:instanceId/schedules/:scheduleId`, withExistingEntity, withSchema(scheduleBodySchema), withEntityPermission(`schedule`), upsertSchedule);
 entitiesRouter.delete(`/:type/:instanceId/schedules/:scheduleId`, withExistingEntity, withEntityPermission(`schedule`), deleteSchedule);
-entitiesRouter.put(`/:type/:instanceId/event-source-subscriptions/:subscriptionId`, withExistingEntity, withSchema(eventSourceSubscriptionBodySchema), withEntityPermission(`write`), upsertEventSourceSubscription);
-entitiesRouter.delete(`/:type/:instanceId/event-source-subscriptions/:subscriptionId`, withExistingEntity, withEntityPermission(`write`), deleteEventSourceSubscription);
+entitiesRouter.put(`/:type/:instanceId/webhook-source-subscriptions/:subscriptionId`, withExistingEntity, withSchema(webhookSourceSubscriptionBodySchema), withEntityPermission(`write`), upsertWebhookSourceSubscription);
+entitiesRouter.delete(`/:type/:instanceId/webhook-source-subscriptions/:subscriptionId`, withExistingEntity, withEntityPermission(`write`), deleteWebhookSourceSubscription);
+entitiesRouter.delete(`/:type/:instanceId/pg-sync-observations/:sourceRef`, withExistingEntity, withEntityPermission(`write`), deletePgSyncObservation);
 entitiesRouter.get(`/:type/:instanceId/grants`, withExistingEntity, withEntityPermission(`manage`), listEntityPermissionGrants);
 entitiesRouter.post(`/:type/:instanceId/grants`, withExistingEntity, withSchema(entityPermissionGrantInputSchema), withEntityPermission(`manage`), createEntityPermissionGrant);
 entitiesRouter.delete(`/:type/:instanceId/grants/:grantId`, withExistingEntity, withEntityPermission(`manage`), deleteEntityPermissionGrant);
@@ -8899,22 +9011,22 @@ async function deleteSchedule(request, ctx) {
 	const result = await ctx.entityManager.deleteSchedule(entityUrl, { id: decodeURIComponent(request.params.scheduleId) });
 	return json(result);
 }
-async function upsertEventSourceSubscription(request, ctx) {
-	const principalMutationError = rejectPrincipalEntityMutation(request, `subscribed to event sources`);
+async function upsertWebhookSourceSubscription(request, ctx) {
+	const principalMutationError = rejectPrincipalEntityMutation(request, `subscribed to webhook sources`);
 	if (principalMutationError) return principalMutationError;
-	const catalog = ctx.eventSources;
-	if (!catalog) return apiError(404, ErrCodeNotFound, `No event source catalog is configured`);
+	const catalog = ctx.webhookSources;
+	if (!catalog) return apiError(404, ErrCodeNotFound, `No webhook source catalog is configured`);
 	const { entityUrl } = requireExistingEntityRoute(request);
 	const parsed = routeBody(request);
-	const source = await catalog.getEventSource(parsed.sourceKey);
-	if (!source) return apiError(404, ErrCodeNotFound, `Event source "${parsed.sourceKey}" not found`);
+	const source = await catalog.getWebhookSource(parsed.webhookKey);
+	if (!source) return apiError(404, ErrCodeNotFound, `Webhook source "${parsed.webhookKey}" not found`);
 	if (parsed.lifetime?.kind === `expires_at`) {
 		const expiresAt = new Date(parsed.lifetime.at);
 		if (Number.isNaN(expiresAt.getTime())) return apiError(400, ErrCodeInvalidRequest, `Invalid expires_at lifetime timestamp`);
 	}
 	let resolved;
 	try {
-		resolved = resolveEventSourceSubscription({
+		resolved = resolveWebhookSourceSubscription({
 			contract: source,
 			entityUrl,
 			request: {
@@ -8926,18 +9038,25 @@ async function upsertEventSourceSubscription(request, ctx) {
 	} catch (error) {
 		return apiError(400, ErrCodeInvalidRequest, error instanceof Error ? error.message : String(error));
 	}
-	await ctx.ensureEventSourceWakeSource?.(resolved.subscription.sourceUrl);
-	const result = await ctx.entityManager.upsertEventSourceSubscription(entityUrl, {
+	await ctx.ensureWebhookSourceWakeSource?.(resolved.subscription.sourceUrl);
+	const result = await ctx.entityManager.upsertWebhookSourceSubscription(entityUrl, {
 		subscription: resolved.subscription,
-		manifest: buildEventSourceManifestEntry(resolved)
+		manifest: buildWebhookSourceManifestEntry(resolved)
 	});
 	return json(result);
 }
-async function deleteEventSourceSubscription(request, ctx) {
-	const principalMutationError = rejectPrincipalEntityMutation(request, `unsubscribed from event sources`);
+async function deleteWebhookSourceSubscription(request, ctx) {
+	const principalMutationError = rejectPrincipalEntityMutation(request, `unsubscribed from webhook sources`);
+	if (principalMutationError) return principalMutationError;
+	const { entityUrl } = requireExistingEntityRoute(request);
+	const result = await ctx.entityManager.deleteWebhookSourceSubscription(entityUrl, { id: decodeURIComponent(request.params.subscriptionId) });
+	return json(result);
+}
+async function deletePgSyncObservation(request, ctx) {
+	const principalMutationError = rejectPrincipalEntityMutation(request, `unobserved a pg-sync source`);
 	if (principalMutationError) return principalMutationError;
 	const { entityUrl } = requireExistingEntityRoute(request);
-	const result = await ctx.entityManager.deleteEventSourceSubscription(entityUrl, { id: decodeURIComponent(request.params.subscriptionId) });
+	const result = await ctx.entityManager.deletePgSyncObservation(entityUrl, { sourceRef: decodeURIComponent(request.params.sourceRef) });
 	return json(result);
 }
 function tagResponseBody(entity) {
@@ -9035,6 +9154,23 @@ async function sendEntity(request, ctx) {
 	const result = await ctx.entityManager.send(entityUrl, sendReq);
 	return json(result);
 }
+async function writeCollection(request, ctx) {
+	const parsed = routeBody(request);
+	await ctx.entityManager.ensurePrincipal(ctx.principal);
+	const { entityUrl } = requireExistingEntityRoute(request);
+	const collection = request.params.collection;
+	const result = await ctx.entityManager.writeCollection(entityUrl, collection, {
+		operation: parsed.operation,
+		key: parsed.key,
+		value: parsed.value,
+		principal: {
+			url: ctx.principal.url,
+			kind: ctx.principal.kind,
+			id: ctx.principal.id
+		}
+	});
+	return json(result, { status: parsed.operation === `insert` ? 201 : 200 });
+}
 async function createAttachment(request, ctx) {
 	const principalMutationError = rejectPrincipalEntityMutation(request, `given attachments`);
 	if (principalMutationError) return principalMutationError;
@@ -9132,8 +9268,13 @@ async function spawnEntity(request, ctx) {
 		headers: { "x-write-token": entity.write_token }
 	});
 }
-function getEntity(request) {
-	return json(toPublicEntity(requireExistingEntityRoute(request).entity));
+async function getEntity(request, ctx) {
+	const { entity } = requireExistingEntityRoute(request);
+	const entityType = entity.type ? await ctx.entityManager.registry.getEntityType(entity.type) : null;
+	return json({
+		...toPublicEntity(entity),
+		...entityType?.externally_writable_collections && { externally_writable_collections: entityType.externally_writable_collections }
+	});
 }
 function headEntity() {
 	return status(200);
@@ -9168,6 +9309,16 @@ async function signalEntity(request, ctx) {
 //#region src/routing/entity-types-router.ts
 const jsonObjectSchema = Type.Record(Type.String(), Type.Unknown());
 const schemaMapSchema = Type.Record(Type.String(), jsonObjectSchema);
+const externallyWritableCollectionsSchema = Type.Record(Type.String(), Type.Object({
+	type: Type.String(),
+	contract: Type.Optional(Type.String()),
+	operations: Type.Optional(Type.Array(Type.Union([
+		Type.Literal(`insert`),
+		Type.Literal(`update`),
+		Type.Literal(`delete`)
+	]))),
+	principalColumn: Type.Optional(Type.String())
+}, { additionalProperties: false }));
 const slashCommandArgumentSchema = Type.Object({
 	name: Type.String(),
 	type: Type.Union([
@@ -9198,7 +9349,8 @@ const registerEntityTypeBodySchema = Type.Object({
 	slash_commands: Type.Optional(Type.Array(slashCommandSchema)),
 	serve_endpoint: Type.Optional(Type.String()),
 	default_dispatch_policy: Type.Optional(dispatchPolicySchema),
-	permission_grants: Type.Optional(Type.Array(typePermissionGrantInputSchema))
+	permission_grants: Type.Optional(Type.Array(typePermissionGrantInputSchema)),
+	externally_writable_collections: Type.Optional(externallyWritableCollectionsSchema)
 }, { additionalProperties: false });
 const amendEntityTypeSchemasBodySchema = Type.Object({
 	inbox_schemas: Type.Optional(schemaMapSchema),
@@ -9329,7 +9481,20 @@ function parseExpiresAt(value) {
 	if (Number.isNaN(expiresAt.getTime())) throw new ElectricAgentsError(ErrCodeInvalidRequest, `Invalid expires_at timestamp`, 400);
 	return expiresAt;
 }
+/**
+* The `comments` collection name is reserved for the canonical comments
+* contract: the UI keys its comment affordances on it, so a divergent
+* collection registered under that name (or the contract mounted under
+* another name) would break that assumption silently.
+*/
+function validateExternallyWritableCollections(collections) {
+	for (const [name, config] of Object.entries(collections ?? {})) {
+		if (name === `comments` && config.contract !== COMMENTS_CONTRACT) throw new ElectricAgentsError(ErrCodeInvalidRequest, `The externally-writable collection name "comments" is reserved for the "${COMMENTS_CONTRACT}" contract`, 400);
+		if (config.contract === COMMENTS_CONTRACT && name !== `comments`) throw new ElectricAgentsError(ErrCodeInvalidRequest, `The "${COMMENTS_CONTRACT}" contract must be registered under the collection name "comments"`, 400);
+	}
+}
 function normalizeEntityTypeRequest(parsed) {
+	validateExternallyWritableCollections(parsed.externally_writable_collections);
 	const serveEndpoint = rewriteLoopbackWebhookUrl(parsed.serve_endpoint);
 	return {
 		name: parsed.name ?? ``,
@@ -9343,7 +9508,8 @@ function normalizeEntityTypeRequest(parsed) {
 			type: `webhook`,
 			url: serveEndpoint
 		}] } : void 0),
-		permission_grants: parsed.permission_grants
+		permission_grants: parsed.permission_grants,
+		externally_writable_collections: parsed.externally_writable_collections
 	};
 }
 function toPublicEntityType(entityType) {
@@ -9356,7 +9522,7 @@ function toPublicEntityType(entityType) {
 //#endregion
 //#region src/routing/pg-sync-router.ts
 const pgSyncOptionsSchema = Type.Object({
-	url: Type.Optional(Type.String()),
+	url: Type.String(),
 	table: Type.String(),
 	columns: Type.Optional(Type.Array(Type.String())),
 	where: Type.Optional(Type.String()),
@@ -9378,6 +9544,7 @@ const pgSyncRouter = Router({ base: `/_electric/pg-sync` });
 pgSyncRouter.post(`/register`, withSchema(pgSyncRegisterBodySchema), registerPgSync);
 async function registerPgSync(request, ctx) {
 	const { options, metadata } = routeBody(request);
+	if (options.url.trim() === ``) return apiError(400, ErrCodeInvalidRequest, `pgSync url must be non-empty`);
 	if (options.table.trim() === ``) return apiError(400, ErrCodeInvalidRequest, `pgSync table must be non-empty`);
 	if (!ctx.pgSyncBridgeManager) return apiError(503, ErrCodeInvalidRequest, `pgSync bridge manager is not configured`);
 	try {
@@ -9392,6 +9559,8 @@ async function registerPgSync(request, ctx) {
 		const result = await ctx.pgSyncBridgeManager.register(options, requestMetadata$1);
 		return json(result);
 	} catch (error) {
+		if (error instanceof PgSyncSourceValidationError) return apiError(400, ErrCodeInvalidRequest, error.message);
+		serverLog.error(`[pg-sync] registration failed for table "${options.table}":`, error);
 		return apiError(500, ErrCodeInvalidRequest, `pgSync registration failed: ${error instanceof Error ? error.message : String(error)}`);
 	}
 }
@@ -9916,7 +10085,7 @@ const wakeCallbackBodySchema = Type.Object({
 const DS_SUBSCRIPTION_CALLBACK_PREFIX = `ds-subscription:`;
 const internalRouter = Router({ base: `/_electric` });
 internalRouter.get(`/health`, () => json({ status: `ok` }));
-internalRouter.get(`/event-sources`, listEventSources);
+internalRouter.get(`/webhook-sources`, listWebhookSources);
 internalRouter.post(`/wake`, withSchema(wakeRegistrationBodySchema), registerWake);
 internalRouter.post(`/subscription-webhooks/:subscriptionId`, subscriptionWebhook);
 internalRouter.post(`/wake-callbacks/:consumerId`, wakeCallback);
@@ -10038,11 +10207,11 @@ async function registerWake(request, ctx) {
 	await ctx.entityManager.registerWake(opts);
 	return status(204);
 }
-async function listEventSources(_request, ctx) {
-	const eventSources = ctx.eventSources ? await ctx.eventSources.listEventSources() : [];
-	return json({ eventSources: eventSources.filter(isAgentVisibleEventSource) });
+async function listWebhookSources(_request, ctx) {
+	const webhookSources = ctx.webhookSources ? await ctx.webhookSources.listWebhookSources() : [];
+	return json({ webhookSources: webhookSources.filter(isAgentVisibleWebhookSource) });
 }
-function isAgentVisibleEventSource(source) {
+function isAgentVisibleWebhookSource(source) {
 	return source.agentVisible === true && source.status === `active`;
 }
 async function subscriptionWebhook(request, ctx) {

package/drizzle/0016_entity_type_externally_writable_collections.sql

@@ -0,0 +1 @@
+ALTER TABLE "entity_types" ADD COLUMN "externally_writable_collections" jsonb;

package/drizzle/meta/_journal.json

@@ -113,6 +113,13 @@
       "when": 1779728400000,
       "tag": "0015_pg_sync_bridges",
       "breakpoints": true
+    },
+    {
+      "idx": 16,
+      "version": "7",
+      "when": 1781200000000,
+      "tag": "0016_entity_type_externally_writable_collections",
+      "breakpoints": true
     }
   ]
 }