@camstack/addon-waste-collections 0.1.37 → 0.1.38

package/dist/waste-collections.addon.js

@@ -6005,7 +6005,7 @@ var ZodIssueCode = {
 var ZodFirstPartyTypeKind;
 ZodFirstPartyTypeKind || (ZodFirstPartyTypeKind = {});
 //#endregion
-//#region ../types/dist/sleep-AEnTN3b4.mjs
+//#region ../types/dist/sleep-CQP-REJp.mjs
 /**
 * The audio chunk plane's byte format, and the ONE expansion from a coded
 * window to float samples (D455).
@@ -6369,6 +6369,59 @@ Object.fromEntries([
 function isValuelessField(field) {
 	return field.type === "separator" || field.type === "info" || field.type === "qr-code" || field.type === "button" || field.type === "object-array" || field.type === "widget" || field.type === "addon-action-button" || field.type === "device-action-button" || field.type === "account-sign-in" || field.type === "secret-presence";
 }
+/**
+* Base collector: flatten a hydrated `ConfigUISchemaWithValues` into
+* `key → { value, default }`, recursing through `group` and `sub-tabs`
+* layout fields. Keeping `value` and `default` SEPARATE (rather than
+* pre-resolving) lets callers both read the effective value AND detect
+* overrides (`value` differs from `default`). Structural over `unknown`;
+* malformed input yields an empty map, never throws.
+*/
+function collectHydratedFieldEntries(schema) {
+	const out = /* @__PURE__ */ new Map();
+	if (typeof schema !== "object" || schema === null) return out;
+	const sections = schema.sections;
+	if (!Array.isArray(sections)) return out;
+	for (const section of sections) if (typeof section === "object" && section !== null) collectFieldEntriesInto(section.fields, out);
+	return out;
+}
+/** Recursive field walker for {@link collectHydratedFieldEntries}. */
+function collectFieldEntriesInto(fields, into) {
+	if (!Array.isArray(fields)) return;
+	for (const field of fields) {
+		if (typeof field !== "object" || field === null) continue;
+		const type = field.type;
+		if (type === "group") {
+			collectFieldEntriesInto(field.fields, into);
+			continue;
+		}
+		if (type === "sub-tabs") {
+			const tabs = field.tabs;
+			if (Array.isArray(tabs)) {
+				for (const tab of tabs) if (typeof tab === "object" && tab !== null) collectFieldEntriesInto(tab.fields, into);
+			}
+			continue;
+		}
+		const key = field.key;
+		if (typeof key !== "string" || key.length === 0) continue;
+		if (!("value" in field)) continue;
+		into.set(key, {
+			value: field.value,
+			default: field.default
+		});
+	}
+}
+/**
+* Flatten a hydrated settings payload into `key → EFFECTIVE value`
+* (`value ?? default`). The read-side inverse of `hydrateSchema` for the
+* common "just give me the resolved values" case. Built on
+* {@link collectHydratedFieldEntries}.
+*/
+function collectHydratedFieldValues(schema) {
+	const out = /* @__PURE__ */ new Map();
+	for (const [key, entry] of collectHydratedFieldEntries(schema)) out.set(key, entry.value ?? entry.default);
+	return out;
+}
 function hydrateSchema(schema, values, options = {}) {
 	return {
 		...schema.tabs ? { tabs: [...schema.tabs] } : {},
@@ -7749,6 +7802,21 @@ var SCOPED_SETTINGS_SCOPES = [
 	"device-defaults",
 	"node"
 ];
+/** The one refusal of a key a scope did not declare. */
+function assertDeclaredKeys(keys, declared) {
+	const undeclared = keys.filter((key) => !declared.has(key));
+	if (undeclared.length > 0) throw new Error(`scoped settings: [${undeclared.join(", ")}] not declared for this scope (declared: [${[...declared].join(", ")}])`);
+}
+/** Build the handle over an addon's scoped read, write and unset. */
+function createScopedSettings(deps) {
+	return {
+		async get() {
+			return deps.schema.parse(await deps.read());
+		},
+		patch: (patch) => deps.write(Object.fromEntries(Object.entries(patch))),
+		unset: (keys) => deps.unset(keys)
+	};
+}
 /** A write to a secret path could not be stored in the keychain, so it was refused. */
 var KeychainWriteRefusedError = class extends Error {
 	fieldPath;
@@ -8324,7 +8392,16 @@ function createHandle(raw, opts) {
 				return blob;
 			}
 		},
-		writeAddonStore: writeAddon
+		writeAddonStore: writeAddon,
+		removeClearedKeys: (keys) => serialize("addon", async () => {
+			const stored = await readStoredAddonBlob(raw);
+			index.seen("addon", stored);
+			const removable = keys.filter((key) => collectSecretMarkerRefs(stored[key]).length === 0);
+			if (removable.length === 0) return;
+			const patch = Object.fromEntries(removable.map((key) => [key, void 0]));
+			await raw.writeAddonStore(patch);
+			index.wrote("addon", patch);
+		})
 	};
 }
 /** The context the addon sees, plus the private raw view and write outcome. */
@@ -8869,6 +8946,151 @@ var BaseAddon = class {
 		}
 	}
 	/**
+	* Hook: values layered over the stored ones when the FORM of one scope is served
+	* ({@link getScopedSettings}) — a preview that derives dependent options without writing.
+	* Never applied to {@link ScopedSettings.get} or to a write. `null` ⇒ no overlay.
+	*/
+	async scopedSettingsOverlay(_scope, _cap, _nodeId) {
+		return null;
+	}
+	/**
+	* Hook: a write of one scope changed stored values (not called when the store reports no change,
+	* e.g. the write-back of a stored secret). `keys` are the bare field keys of the write, node keys included.
+	*/
+	async onScopedSettingsChanged(_scope, _cap, _keys) {}
+	/** Typed handle over the CLUSTER settings `cap` declares (`clusterSettingsSchema`). */
+	clusterSettings(cap, schema) {
+		return this.scopedHandle("cluster", cap, schema);
+	}
+	/** Typed handle over the fleet defaults of the per-device settings `cap` declares. */
+	deviceDefaults(cap, schema) {
+		return this.scopedHandle("device-defaults", cap, schema);
+	}
+	/**
+	* Typed handle over the settings `cap` owns PER NODE. `nodeId` omitted ⇒ the local node. A node
+	* with no row yields the schema defaults — never a bare-key fallback.
+	*/
+	nodeSettings(cap, schema, nodeId) {
+		return this.scopedHandle("node", cap, schema, nodeId);
+	}
+	/**
+	* {@link state} for a value that is kept per node: stored under `<key>@<nodeId>`, and the
+	* settings store carries `nodeId` in the row data (D986 §1), so a forgotten node's rows go in one
+	* central delete. `nodeId` omitted ⇒ the local node.
+	*/
+	nodeState(key, schema, fallback, nodeId) {
+		this._declaredStateKeys.add(key);
+		return createDurableState({
+			key: nodeScopedKey(key, nodeId ?? this._ctx?.kernel?.localNodeId ?? ""),
+			schema,
+			fallback,
+			read: async () => this.resolveStoredSecrets(await this.readAddonStoreWithRetry()),
+			write: async (patch) => {
+				await this._ctx?.settings?.writeAddonStore(patch);
+			},
+			onParseError: (k, e) => this._ctx?.logger?.warn?.(`durable-state: stored "${k}" failed validation — using fallback`, { meta: {
+				addonId: this._ctx?.id,
+				key: k,
+				error: String(e)
+			} })
+		});
+	}
+	/** The loaded schema `cap` declares for `scope`, or `null`. */
+	async declaredScopedSchema(scope, cap) {
+		await this.loadScopedSchemas(cap);
+		return this.loadedScopedSchemas(cap).find((entry) => entry.scope === scope)?.schema ?? null;
+	}
+	async requireScopedSchema(scope, cap) {
+		const schema = await this.declaredScopedSchema(scope, cap);
+		if (schema === null) throw new Error(`${this.constructor.name}: cap "${cap}" declares no ${scope} settings`);
+		return schema;
+	}
+	scopedKeys(schema) {
+		return new Set(schema.sections.flatMap((section) => collectValueFieldKeys(section.fields)));
+	}
+	/** `store` narrowed to the keys `schema` declares. */
+	narrowToScope(store, schema) {
+		const keys = this.scopedKeys(schema);
+		return Object.fromEntries(Object.entries(store).filter(([key]) => keys.has(key)));
+	}
+	scopedHandle(scope, cap, schema, nodeId) {
+		return createScopedSettings({
+			schema,
+			read: async () => {
+				const declared = await this.requireScopedSchema(scope, cap);
+				const stored = this.narrowToScope(await this.resolveGlobalStore(nodeId, cap), declared);
+				const effective = collectHydratedFieldValues(hydrateSchema(declared, stored));
+				return {
+					...Object.fromEntries([...effective].filter(([, value]) => value !== void 0)),
+					...stored
+				};
+			},
+			write: (patch) => this.writeScoped(scope, cap, patch, nodeId),
+			unset: (keys) => this.unsetScoped(scope, cap, keys, nodeId)
+		});
+	}
+	/** The one write path of the scoped API: declared keys only, then the global patch. */
+	async writeScoped(scope, cap, patch, nodeId) {
+		assertDeclaredKeys(Object.keys(patch), this.scopedKeys(await this.requireScopedSchema(scope, cap)));
+		if (await this.applyGlobalPatch(patch, scope === "node" ? nodeId : void 0, cap)) await this.onScopedSettingsChanged(scope, cap, Object.keys(patch));
+	}
+	/**
+	* Remove declared keys of one scope. A secret goes through {@link clearSecrets} — its keychain
+	* value is released exactly as there — and the emptied row is then removed; every other key is
+	* removed by an `undefined` patch (which a secret transform would read as "keep").
+	*/
+	async unsetScoped(scope, cap, keys, nodeId) {
+		assertDeclaredKeys(keys, this.scopedKeys(await this.requireScopedSchema(scope, cap)));
+		const target = scope === "node" ? nodeId : void 0;
+		const tree = this.addonSecretTree();
+		const secretKeys = keys.filter((key) => tree.has(key));
+		const plainKeys = keys.filter((key) => !tree.has(key));
+		let changed = false;
+		if (plainKeys.length > 0) {
+			const patch = Object.fromEntries(plainKeys.map((key) => [key, void 0]));
+			changed = await this.applyGlobalPatch(patch, target, cap) || changed;
+		}
+		if (secretKeys.length > 0) {
+			await this.clearSecretKeys(secretKeys, target, cap);
+			const node = normalizeNodeId(target ?? this._ctx?.kernel?.localNodeId);
+			const rows = secretKeys.map((key) => scope === "node" ? nodeScopedKey(key, node) : key);
+			if (this._secretSettings !== null) await this._secretSettings.removeClearedKeys(rows);
+			else await this._ctx?.settings?.writeAddonStore(Object.fromEntries(rows.map((row) => [row, void 0])));
+			changed = true;
+		}
+		if (changed) await this.onScopedSettingsChanged(scope, cap, [...keys]);
+	}
+	/**
+	* The hydrated form of one scope of one capability's settings (any
+	* {@link scopedSettingsOverlay} applied), or `null` when the capability declares nothing there.
+	*/
+	async getScopedSettings(scope, cap, nodeId) {
+		const schema = await this.declaredScopedSchema(scope, cap);
+		if (schema === null) return null;
+		const stored = this.narrowToScope(await this.readRawProjectedStore(nodeId, cap), schema);
+		const overlay = await this.scopedSettingsOverlay(scope, cap, nodeId);
+		return hydrateSchema(schema, overlay ? await this.overlayKeepingMarkers(stored, overlay) : stored, { inlineSecretsAsViews: true });
+	}
+	/** The OPERATOR's write of declared keys of one scope (D787 secret semantics). */
+	async updateScopedSettings(scope, cap, patch, nodeId) {
+		this._operatorWriteDepth++;
+		try {
+			await this.writeScoped(scope, cap, patch, nodeId);
+		} finally {
+			this._operatorWriteDepth--;
+		}
+	}
+	/**
+	* The effective values (`stored ?? default`) of one scope, a secret as its `set` view — never
+	* its value. `null` when the capability declares nothing for the scope.
+	*/
+	async readScopedValues(scope, cap, nodeId) {
+		const schema = await this.declaredScopedSchema(scope, cap);
+		if (schema === null) return null;
+		const form = hydrateSchema(schema, this.narrowToScope(await this.readRawProjectedStore(nodeId, cap), schema), { inlineSecretsAsViews: true });
+		return Object.fromEntries([...collectHydratedFieldValues(form)].filter(([, value]) => value !== void 0));
+	}
+	/**
 	* What the create wizard and the integration edit page render for one instance: the addon's
 	* per-instance schema when it declares one, else its global schema (what they always showed).
 	*/
@@ -9020,6 +9242,9 @@ var BaseAddon = class {
 	* a keychain (an older kernel) it writes `''`, as such code always did.
 	*/
 	async clearSecrets(keys, nodeId) {
+		await this.clearSecretKeys(keys, nodeId);
+	}
+	async clearSecretKeys(keys, nodeId, cap) {
 		const tree = this.addonSecretTree();
 		const keychain = this._ctx?.secrets !== void 0;
 		const stored = keychain ? await this.readAddonStoreWithRetry() : {};
@@ -9032,25 +9257,27 @@ var BaseAddon = class {
 			const keychainStored = tree.has(key) || collectSecretMarkerRefs(stored[key]).length > 0;
 			patch[key] = keychain && keychainStored ? SECRET_CLEAR : "";
 		}
-		await this.applyGlobalPatch(patch, nodeId);
+		await this.applyGlobalPatch(patch, nodeId, cap);
 	}
-	async applyGlobalPatch(barePatch, nodeId) {
-		await this.loadScopedSchemas();
-		const keys = this.perNodeKeys();
+	/** Resolves `true` when the write changed stored values. */
+	async applyGlobalPatch(barePatch, nodeId, cap) {
+		await this.loadScopedSchemas(cap);
+		const keys = this.perNodeKeys(cap);
 		const localNode = normalizeNodeId(this._ctx?.kernel?.localNodeId);
 		const target = normalizeNodeId(nodeId ?? this._ctx?.kernel?.localNodeId);
 		const scoped = keys.size > 0 ? scopePatch(barePatch, keys, target) : barePatch;
 		const handle = this._secretSettings;
 		if (handle !== null) {
 			const { changed } = await handle.writeAddonStore(scoped);
-			if (!changed) return;
+			if (!changed) return false;
 		} else await this._ctx?.settings?.writeAddonStore(scoped);
-		if (target !== localNode) return;
+		if (target !== localNode) return true;
 		await this.resolveConfig();
 		await this.onConfigChanged();
 		this.emitLifecycle(EventCategory.AddonUpdated, { level: "global" });
 		const legacy = this.globalSettingsSchema();
 		this.maybeAutoRestart(Object.keys(barePatch), [...legacy === null ? [] : [legacy], ...this.loadedScopedSchemas().map((entry) => entry.schema)]);
+		return true;
 	}
 	/**
 	* The set of field keys the global settings schema declares `perNode: true`
@@ -44885,6 +45112,8 @@ var SettingsSchemaWithValuesSchema = object({
 });
 /** Patch object — keys are field names, values are the new field values. */
 var SettingsPatchSchema = record(string(), unknown());
+/** The scope of a scoped-settings call (D986): where the capability declared the values. */
+var ScopedSettingsScopeSchema = _enum(SCOPED_SETTINGS_SCOPES);
 /** Standard success response for update operations. */
 var SettingsUpdateResultSchema = object({ success: literal(true) });
 method(object({
@@ -44900,6 +45129,25 @@ method(object({
 	kind: "mutation",
 	auth: "admin"
 }), method(object({
+	addonId: string(),
+	cap: string(),
+	scope: ScopedSettingsScopeSchema,
+	nodeId: string().optional()
+}), SettingsSchemaWithValuesSchema.nullable()), method(object({
+	addonId: string(),
+	cap: string(),
+	scope: ScopedSettingsScopeSchema,
+	nodeId: string().optional(),
+	patch: SettingsPatchSchema
+}), SettingsUpdateResultSchema, {
+	kind: "mutation",
+	auth: "admin"
+}), method(object({
+	addonId: string(),
+	cap: string(),
+	scope: ScopedSettingsScopeSchema,
+	nodeId: string().optional()
+}), record(string(), unknown()).nullable()), method(object({
 	addonId: string(),
 	nodeId: string().optional()
 }), SettingsSchemaWithValuesSchema.nullable()), method(object({
@@ -76788,6 +77036,20 @@ Object.freeze({
 		access: "view",
 		role: "admin"
 	},
+	"addonSettings.getScopedSettings": {
+		capName: "addon-settings",
+		capScope: "system",
+		addonId: null,
+		access: "view",
+		role: "admin"
+	},
+	"addonSettings.readScopedValues": {
+		capName: "addon-settings",
+		capScope: "system",
+		addonId: null,
+		access: "view",
+		role: "admin"
+	},
 	"addonSettings.unsetStoredSettingsKeys": {
 		capName: "addon-settings",
 		capScope: "system",
@@ -76809,6 +77071,13 @@ Object.freeze({
 		access: "create",
 		role: "admin"
 	},
+	"addonSettings.updateScopedSettings": {
+		capName: "addon-settings",
+		capScope: "system",
+		addonId: null,
+		access: "create",
+		role: "admin"
+	},
 	"addonWidgets.listWidgets": {
 		capName: "addon-widgets",
 		capScope: "system",
@@ -91427,42 +91696,6 @@ async function copySourcesToRecords(ports) {
 		}
 	};
 }
-/** The `waste-collections` catalogue (D987): offered to the engine when the addon initialises. */
-var ADDON_MIGRATIONS = [{
-	meta: {
-		id: "waste-collections/2026-11-06-sources-from-settings-and-argsjson",
-		owner: "waste-collections",
-		level: "addon-state",
-		seq: 1,
-		dependsOn: [],
-		store: "settings",
-		scope: "cluster",
-		onFailure: "tolerate",
-		bodyKind: "procedure",
-		description: "Copy the addon-level sources setting (typed args, or a legacy argsJson string) into waste-source records, credentials in the keychain, each read back; an existing record is never overwritten",
-		fixtureMark: "the credential of a legacy argsJson row, read back from its record"
-	},
-	procedure: copySourcesToRecords
-}];
-//#endregion
-//#region src/python-paths.ts
-/**
-* Locate the addon's bundled `python/` dir at runtime (deployed package
-* root or workspace package root). Same candidate walk as detection-pipeline.
-*/
-function resolvePythonDir(fromModuleUrl = require("url").pathToFileURL(__filename).href) {
-	const here = (0, node_path.dirname)((0, node_url.fileURLToPath)(fromModuleUrl));
-	const candidates = [
-		(0, node_path.join)(here, "../python"),
-		(0, node_path.join)(here, "../../python"),
-		(0, node_path.join)(here, "python")
-	];
-	for (const c of candidates) if ((0, node_fs.existsSync)((0, node_path.join)(c, "fetch_source.py"))) return c;
-	throw new Error(`addon-waste-collections: python/ dir not found. Searched:\n${candidates.join("\n")}`);
-}
-function resolveFetchScript(fromModuleUrl = require("url").pathToFileURL(__filename).href) {
-	return (0, node_path.join)(resolvePythonDir(fromModuleUrl), "fetch_source.py");
-}
 //#endregion
 //#region src/waste-source-record-kinds.ts
 var WASTE_COLLECTIONS_OWNER = "waste-collections";
@@ -91508,6 +91741,202 @@ var plainWasteSourceKind = defineEntryKind("waste-source", {
 	writeTrigger: WRITE_TRIGGER
 });
 //#endregion
+//#region src/waste-source-store.ts
+/**
+* A stored body as a source. A row read while the keychain is locked still carries its markers
+* in `args`; the config schema keeps them, so the source lists and its fetch refuses by name.
+*/
+function rowToSource(id, data) {
+	const parsed = WasteSourceConfigSchema.safeParse({
+		id,
+		label: data.name,
+		module: data.module,
+		args: data.args,
+		enabled: data.enabled
+	});
+	return parsed.success ? parsed.data : null;
+}
+function bodyOf(source) {
+	const { id, label, module, args, enabled } = source;
+	const body = {
+		name: label,
+		module,
+		args,
+		enabled
+	};
+	const parsed = wasteSourceEntryKind.schema.safeParse(body);
+	if (!parsed.success) throw new Error(`invalid waste source '${id}': ${parsed.error.message}`);
+	return parsed.data;
+}
+/**
+* While the sources migration has not landed: every record, plus the legacy rows that have no
+* record yet (a read-only view of those). A legacy row leaves the view as soon as a record has
+* its id, so the two never diverge; writes go to the records.
+*/
+function withUnmigratedLegacyRows(records, legacy) {
+	const have = new Set(records.map((r) => r.id));
+	return [...records, ...legacy.filter((r) => !have.has(r.id))];
+}
+var WasteSourceStore = class WasteSourceStore {
+	kind;
+	constructor(kind) {
+		this.kind = kind;
+	}
+	static of(records, kind = wasteSourceEntryKind) {
+		return new WasteSourceStore(records.kind(kind));
+	}
+	/** The record ids, whatever their content. */
+	async listIds() {
+		return (await this.kind.query({ limit: 1e3 })).records.map((record) => record.id);
+	}
+	/** One source with its credentials resolved; markers stay where the keychain cannot serve. */
+	async readResolved(id) {
+		const stored = await this.kind.get(id);
+		if (stored === null) return null;
+		let data = stored.data;
+		try {
+			const resolved = await this.kind.getResolved(id);
+			if (resolved !== null) data = resolved.data;
+		} catch (err) {
+			if (!(err instanceof RecordSecretUnavailableError)) throw err;
+		}
+		return rowToSource(id, data);
+	}
+	async listResolved() {
+		const out = [];
+		for (const id of await this.listIds()) {
+			const row = await this.readResolved(id);
+			if (row !== null) out.push(row);
+		}
+		return out;
+	}
+	/** Create the record when the id is free; an existing record is never touched. */
+	async putIfAbsent(source) {
+		if (await this.kind.get(source.id) !== null) return false;
+		await this.kind.put({
+			id: source.id,
+			data: bodyOf(source)
+		}, { ifRev: 0 });
+		return true;
+	}
+	/**
+	* Make the records equal `sources`. A source whose credential the keychain did not serve is
+	* left exactly as stored: rewriting it would save a marker as the credential.
+	*/
+	async replaceAll(sources) {
+		const nextIds = new Set(sources.map((s) => s.id));
+		for (const id of await this.listIds()) if (!nextIds.has(id)) await this.kind.delete(id);
+		for (const source of sources) {
+			if (hasUnresolvedCredential(source.args)) continue;
+			await this.kind.put({
+				id: source.id,
+				data: bodyOf(source)
+			});
+		}
+	}
+};
+//#endregion
+//#region src/migrations/ports.ts
+var PAGE = 1e3;
+/**
+* The sources migration's ports over {@link MigrationApiV1}, and nothing else (planning#447): the
+* addon's own settings store, its keychain handle and its `waste-source` record kind.
+*/
+function wasteSourcePortsOver(api, kind) {
+	const handle = api.records.kind(kind);
+	const secrets = { resolve: async (refs) => {
+		const { values } = await api.secrets.resolve({ refs: [...refs] });
+		return Object.fromEntries(refs.map((ref) => {
+			const value = values[ref];
+			return [ref, value === null || value === void 0 ? { kind: "missing" } : {
+				kind: "value",
+				value,
+				version: 0
+			}];
+		}));
+	} };
+	const readStored = async (key) => {
+		let store;
+		try {
+			store = (await api.settings.read({})).store;
+		} catch (err) {
+			return {
+				kind: "unreadable",
+				reason: "store-read-failed",
+				error: err instanceof Error ? err.message : String(err)
+			};
+		}
+		if (!Object.hasOwn(store, key)) return { kind: "absent" };
+		const { value } = await resolveSecretMarkers(store[key], secrets, { unresolved: "keep-marker" });
+		return {
+			kind: "present",
+			value
+		};
+	};
+	const asRow = (row) => rowToSource(row.id, row.data);
+	return {
+		readStored,
+		listSourceIds: async () => (await handle.query({ limit: PAGE })).records.map((row) => row.id),
+		putSource: async (source) => {
+			if (await handle.get({ id: source.id }) !== null) return;
+			await handle.put({
+				id: source.id,
+				data: bodyOf(source),
+				ifRev: 0
+			});
+		},
+		readSource: async (id) => {
+			const stored = await handle.get({ id });
+			if (stored === null) return null;
+			try {
+				return asRow(await handle.getResolved({ id }) ?? stored);
+			} catch (err) {
+				if (!(err instanceof RecordSecretUnavailableError)) throw err;
+				return asRow(stored);
+			}
+		},
+		warn: (message) => {
+			api.log.warn({ message });
+		}
+	};
+}
+/** The `waste-collections` catalogue (D987): offered to the engine when the addon initialises. */
+var ADDON_MIGRATIONS = [{
+	meta: {
+		id: "waste-collections/2026-11-06-sources-from-settings-and-argsjson",
+		owner: "waste-collections",
+		level: "addon-state",
+		seq: 1,
+		dependsOn: [],
+		store: "settings",
+		scope: "cluster",
+		onFailure: "tolerate",
+		bodyKind: "procedure",
+		description: "Copy the addon-level sources setting (typed args, or a legacy argsJson string) into waste-source records, credentials in the keychain, each read back; an existing record is never overwritten",
+		fixtureMark: "the credential of a legacy argsJson row, read back from its record"
+	},
+	procedure: copySourcesToRecords
+}];
+//#endregion
+//#region src/python-paths.ts
+/**
+* Locate the addon's bundled `python/` dir at runtime (deployed package
+* root or workspace package root). Same candidate walk as detection-pipeline.
+*/
+function resolvePythonDir(fromModuleUrl = require("url").pathToFileURL(__filename).href) {
+	const here = (0, node_path.dirname)((0, node_url.fileURLToPath)(fromModuleUrl));
+	const candidates = [
+		(0, node_path.join)(here, "../python"),
+		(0, node_path.join)(here, "../../python"),
+		(0, node_path.join)(here, "python")
+	];
+	for (const c of candidates) if ((0, node_fs.existsSync)((0, node_path.join)(c, "fetch_source.py"))) return c;
+	throw new Error(`addon-waste-collections: python/ dir not found. Searched:\n${candidates.join("\n")}`);
+}
+function resolveFetchScript(fromModuleUrl = require("url").pathToFileURL(__filename).href) {
+	return (0, node_path.join)(resolvePythonDir(fromModuleUrl), "fetch_source.py");
+}
+//#endregion
 //#region src/seal-plaintext.ts
 /**
 * A credential an older version stored as plain text in a `waste-source` record is moved into the
@@ -177683,101 +178112,6 @@ function allocateSourceId(label, existingIds) {
 	throw new Error("could not allocate a unique source id");
 }
 //#endregion
-//#region src/waste-source-store.ts
-/**
-* A stored body as a source. A row read while the keychain is locked still carries its markers
-* in `args`; the config schema keeps them, so the source lists and its fetch refuses by name.
-*/
-function rowToSource(id, data) {
-	const parsed = WasteSourceConfigSchema.safeParse({
-		id,
-		label: data.name,
-		module: data.module,
-		args: data.args,
-		enabled: data.enabled
-	});
-	return parsed.success ? parsed.data : null;
-}
-function bodyOf(source) {
-	const { id, label, module, args, enabled } = source;
-	const body = {
-		name: label,
-		module,
-		args,
-		enabled
-	};
-	const parsed = wasteSourceEntryKind.schema.safeParse(body);
-	if (!parsed.success) throw new Error(`invalid waste source '${id}': ${parsed.error.message}`);
-	return parsed.data;
-}
-/**
-* While the sources migration has not landed: every record, plus the legacy rows that have no
-* record yet (a read-only view of those). A legacy row leaves the view as soon as a record has
-* its id, so the two never diverge; writes go to the records.
-*/
-function withUnmigratedLegacyRows(records, legacy) {
-	const have = new Set(records.map((r) => r.id));
-	return [...records, ...legacy.filter((r) => !have.has(r.id))];
-}
-var WasteSourceStore = class WasteSourceStore {
-	kind;
-	constructor(kind) {
-		this.kind = kind;
-	}
-	static of(records, kind = wasteSourceEntryKind) {
-		return new WasteSourceStore(records.kind(kind));
-	}
-	/** The record ids, whatever their content. */
-	async listIds() {
-		return (await this.kind.query({ limit: 1e3 })).records.map((record) => record.id);
-	}
-	/** One source with its credentials resolved; markers stay where the keychain cannot serve. */
-	async readResolved(id) {
-		const stored = await this.kind.get(id);
-		if (stored === null) return null;
-		let data = stored.data;
-		try {
-			const resolved = await this.kind.getResolved(id);
-			if (resolved !== null) data = resolved.data;
-		} catch (err) {
-			if (!(err instanceof RecordSecretUnavailableError)) throw err;
-		}
-		return rowToSource(id, data);
-	}
-	async listResolved() {
-		const out = [];
-		for (const id of await this.listIds()) {
-			const row = await this.readResolved(id);
-			if (row !== null) out.push(row);
-		}
-		return out;
-	}
-	/** Create the record when the id is free; an existing record is never touched. */
-	async putIfAbsent(source) {
-		if (await this.kind.get(source.id) !== null) return false;
-		await this.kind.put({
-			id: source.id,
-			data: bodyOf(source)
-		}, { ifRev: 0 });
-		return true;
-	}
-	/**
-	* Make the records equal `sources`. A source whose credential the keychain did not serve is
-	* left exactly as stored: rewriting it would save a marker as the credential.
-	*/
-	async replaceAll(sources) {
-		const nextIds = new Set(sources.map((s) => s.id));
-		for (const id of await this.listIds()) if (!nextIds.has(id)) await this.kind.delete(id);
-		for (const source of sources) {
-			if (hasUnresolvedCredential(source.args)) continue;
-			await this.kind.put({
-				id: source.id,
-				data: bodyOf(source)
-			});
-		}
-	}
-};
-//#endregion
 //#region src/waste-source-instances.ts
 /**
 * The waste sources as `integration-instances` (planning#440 step 6): one instance per
@@ -178138,7 +178472,7 @@ var WasteCollectionsAddon = class extends BaseAddon {
 		if (!plainBoot) await records.declare({ "waste-source": wasteSourceEntryKind });
 		const store = WasteSourceStore.of(records, plainBoot ? plainWasteSourceKind : wasteSourceEntryKind);
 		this.sourceStore = store;
-		await this.migrateLegacySources(store);
+		await this.migrateLegacySources(plainBoot ? plainWasteSourceKind : wasteSourceEntryKind);
 		this.activeSources = await this.loadPersistedSources();
 		const instances = plainBoot ? null : new WasteSourceInstances(records, {
 			onChanged: (id, change) => this.onInstanceChanged(id, change),
@@ -178220,16 +178554,8 @@ var WasteCollectionsAddon = class extends BaseAddon {
 	* fails leaves the settings where they are and is logged by id: the sources stay unavailable
 	* until it lands, never half-copied.
 	*/
-	async migrateLegacySources(store) {
-		const report = await this.runMigrations(defineAddonMigrations(ADDON_MIGRATIONS, {
-			readStored: (key) => this.readStoredGlobalKey(key),
-			listSourceIds: () => store.listIds(),
-			putSource: async (source) => {
-				await store.putIfAbsent(source);
-			},
-			readSource: (id) => store.readResolved(id),
-			warn: (message) => this.ctx.logger.warn(message)
-		}));
+	async migrateLegacySources(kind) {
+		const report = await this.runMigrations(ADDON_MIGRATIONS, (api) => wasteSourcePortsOver(api, kind));
 		this.legacyServed = !report.declared || report.failed.includes("waste-collections/2026-11-06-sources-from-settings-and-argsjson") || report.blocked.includes("waste-collections/2026-11-06-sources-from-settings-and-argsjson");
 		if (this.legacyServed) this.ctx.logger.warn("waste-collections: the sources migration has not landed - the legacy sources not yet in records are served read-only beside the records until it does", { meta: {
 			declared: report.declared,