@camstack/addon-post-analysis 1.2.71 → 1.2.72

package/dist/pipeline-analytics/index.mjs

@@ -1,4 +1,4 @@
-import { $ as readDeviceStateFrom, A as TimelapseRuleInputSchema, B as customAction, C as NcSnoozeSchema, Ct as unknown, D as RECORDING_EXPORT_MAX_READ_BYTES, E as OpsLogEntrySchema, F as alarmPanelCapability, G as faceGalleryCapability, H as deriveRecordingMode, I as assertTimelapseCadences, J as isScheduleActive, L as audioMetricsCapability, M as TimelapseRuleSchema, N as TrackSourceSchema, O as RetrainStatusSchema, P as addonWidgetsSourceCapability, Q as plateGalleryCapability, R as buildEventKindDescriptor, S as NcSnoozeInputSchema, St as string, T as NcTaxonomySchema, V as defineCustomActions, W as encodeVectorBase64, X as notificationRulesCapability, Y as kebabToCamel, Z as pipelineAnalyticsCapability, _ as NcRuleInputSchema, _t as literal, at as errMsg, b as NcRuleTargetSchema, bt as partialRecord, c as EVENT_PAD_MS, ct as createEvent, d as NC_ALARM_SYSTEM_EVENT_KINDS, dt as nodePin, et as readTimelapseGeneratedAt, f as NC_CONDITION_CATALOG, ft as sleep, g as NcConditionDescriptorSchema, gt as discriminatedUnion, h as NC_TAXONOMY, ht as boolean, i as DETECTION_MACRO_CLASSES, it as zoneAnalyticsCapability, j as TimelapseRulePatchSchema, k as TIMELAPSE_DENSE_FLOOR_SEC, l as LabelAttributionSchema, lt as hydrateSchema, mt as array, n as DEFAULT_EVENT_COLOR, nt as vectorDimFromBase64, o as DeclaredDevices, ot as BaseAddon, p as NC_DEFAULT_SNOOZE_MINUTES, pt as _enum, q as isDetectionMacroClass, rt as videoclipsCapability, s as EVENT_KIND_BY_CAP, st as DeviceType, t as BaseDevice, tt as subKindsOf, u as MACRO_LABELS, ut as isDeviceScopedCap, v as NcRulePatchSchema, vt as number, w as NcSnoozeSuppressedSchema, wt as EventCategory, x as NcScheduleSchema, xt as record, y as NcRuleSchema, yt as object, z as cosineSimilarity } from "../dist-B--dE3Ry.mjs";
+import { $ as readDeviceStateFrom, A as TimelapseRuleInputSchema, B as customAction, C as NcSnoozeSchema, Ct as unknown, D as RECORDING_EXPORT_MAX_READ_BYTES, E as OpsLogEntrySchema, F as alarmPanelCapability, G as faceGalleryCapability, H as deriveRecordingMode, I as assertTimelapseCadences, J as isScheduleActive, L as audioMetricsCapability, M as TimelapseRuleSchema, N as TrackSourceSchema, O as RetrainStatusSchema, P as addonWidgetsSourceCapability, Q as plateGalleryCapability, R as buildEventKindDescriptor, S as NcSnoozeInputSchema, St as string, T as NcTaxonomySchema, V as defineCustomActions, W as encodeVectorBase64, X as notificationRulesCapability, Y as kebabToCamel, Z as pipelineAnalyticsCapability, _ as NcRuleInputSchema, _t as literal, at as errMsg, b as NcRuleTargetSchema, bt as partialRecord, c as EVENT_PAD_MS, ct as createEvent, d as NC_ALARM_SYSTEM_EVENT_KINDS, dt as nodePin, et as readTimelapseGeneratedAt, f as NC_CONDITION_CATALOG, ft as sleep, g as NcConditionDescriptorSchema, gt as discriminatedUnion, h as NC_TAXONOMY, ht as boolean, i as DETECTION_MACRO_CLASSES, it as zoneAnalyticsCapability, j as TimelapseRulePatchSchema, k as TIMELAPSE_DENSE_FLOOR_SEC, l as LabelAttributionSchema, lt as hydrateSchema, mt as array, n as DEFAULT_EVENT_COLOR, nt as vectorDimFromBase64, o as DeclaredDevices, ot as BaseAddon, p as NC_DEFAULT_SNOOZE_MINUTES, pt as _enum, q as isDetectionMacroClass, rt as videoclipsCapability, s as EVENT_KIND_BY_CAP, st as DeviceType, t as BaseDevice, tt as subKindsOf, u as MACRO_LABELS, ut as isDeviceScopedCap, v as NcRulePatchSchema, vt as number, w as NcSnoozeSuppressedSchema, wt as EventCategory, x as NcScheduleSchema, xt as record, y as NcRuleSchema, yt as object, z as cosineSimilarity } from "../dist-6te1200B.mjs";
 import { t as __exportAll } from "../embedding-encoder/index.mjs";
 import * as fs from "node:fs";
 import { promises } from "node:fs";
@@ -1573,6 +1573,401 @@ var NC_ALARM_DECLARATION = {
 	DeviceClass: NcAlarmPanelDevice
 };
 //#endregion
+//#region src/notification-center/artifact-index.ts
+var NC_ARTIFACTS_COLLECTION = "notification-center:artifacts";
+var NcArtifactKindSchema = _enum([
+	"timelapse",
+	"timelapse-preview",
+	"summary-mosaic"
+]);
+/**
+* How the viewer should DRAW it. Derived from the mime once, here, so no client
+* has to carry a mime table — and so a GIF that degraded to a JPEG is drawn as
+* the JPEG it actually is.
+*/
+var NcArtifactMediaTypeSchema = _enum([
+	"image",
+	"gif",
+	"video"
+]);
+/** The relative hub path of the authenticated bytes route for an artefact id. */
+var NC_ARTIFACT_READ_PREFIX = "nc-artifact-read";
+var NcArtifactRecordSchema = object({
+	/** The `NcArtifactStore` id — the same id the bytes route resolves. */
+	id: string().min(1),
+	kind: NcArtifactKindSchema,
+	mediaType: NcArtifactMediaTypeSchema,
+	mime: string().min(1),
+	sizeBytes: number().int().nonnegative(),
+	/** When the artefact was PRODUCED. */
+	createdAt: number().int(),
+	/** What the content is ABOUT (window end / event time). The sort key: a
+	*  timelapse rendered at 06:05 is about the night before, and a list ordered
+	*  by production time puts it in the wrong morning. */
+	capturedAt: number().int(),
+	/** After this the bytes are gone. Derived from the retained shelf's own age
+	*  bound — never a second retention policy. */
+	expiresAt: number().int(),
+	/** The camera the artefact is FILED under. Null only if it belongs to none. */
+	deviceId: number().int().nullable(),
+	/** Every camera the artefact covers, for display. */
+	deviceIds: array(number().int()),
+	ruleId: string().optional(),
+	ruleName: string().optional(),
+	title: string().optional(),
+	/** A companion still for a video artefact (a timelapse's preview frame) —
+	*  what a list renders as the thumbnail. */
+	posterArtifactId: string().optional(),
+	/** RELATIVE hub path of the authenticated bytes route. Relative on purpose:
+	*  the viewer already holds the hub origin it is authenticated against, and
+	*  only the SIGNED plane needs to guess which host a stranger can reach. */
+	downloadPath: string().min(1)
+});
+var NcArtifactQuerySchema = object({
+	kinds: array(NcArtifactKindSchema).optional(),
+	deviceIds: array(number().int()).optional(),
+	ruleId: string().optional(),
+	/** Inclusive `capturedAt` window. */
+	fromMs: number().int().optional(),
+	toMs: number().int().optional(),
+	limit: number().int().min(1).max(200).default(50),
+	offset: number().int().min(0).default(0)
+});
+var NC_ARTIFACTS_COLUMNS = [
+	{
+		name: "id",
+		type: "TEXT",
+		primaryKey: true,
+		notNull: true
+	},
+	{
+		name: "kind",
+		type: "TEXT",
+		notNull: true
+	},
+	{
+		name: "deviceId",
+		type: "INTEGER"
+	},
+	{
+		name: "ruleId",
+		type: "TEXT"
+	},
+	(
+	/** `''` for a global artefact — see the header note on visibility. */
+	{
+		name: "ownerUserId",
+		type: "TEXT",
+		notNull: true
+	}),
+	{
+		name: "capturedAt",
+		type: "INTEGER",
+		notNull: true
+	},
+	{
+		name: "expiresAt",
+		type: "INTEGER",
+		notNull: true
+	},
+	(
+	/** The FULL record (Zod-validated on read) — the scalars above are indexed
+	*  projections only. */
+	{
+		name: "record",
+		type: "JSON",
+		notNull: true
+	})
+];
+var NC_ARTIFACTS_INDEXES = [
+	{
+		name: "idx_nc_artifacts_captured",
+		columns: ["capturedAt"]
+	},
+	{
+		name: "idx_nc_artifacts_device",
+		columns: ["deviceId", "capturedAt"]
+	},
+	{
+		name: "idx_nc_artifacts_kind",
+		columns: ["kind", "capturedAt"]
+	},
+	{
+		name: "idx_nc_artifacts_expires",
+		columns: ["expiresAt"]
+	}
+];
+/** Upper bound for a half-open `whereBetween` — the store has no `>=`. */
+var TIME_MAX = 864e13;
+var TIME_MIN = -864e13;
+/** Prune scan ceiling — the index is bounded by the shelf it mirrors (2000
+*  entries by default), so this only has to be comfortably above it. */
+var NC_ARTIFACT_PRUNE_SCAN_LIMIT = 2e4;
+/** `image/gif` → `gif`. Keyed on what the bytes ARE, never on what was asked
+*  for: a GIF that degraded to a still must be drawn as a still. */
+function mediaTypeForMime(mime) {
+	if (mime === "image/gif") return "gif";
+	if (mime.startsWith("video/")) return "video";
+	return "image";
+}
+/** The relative hub path an authenticated client fetches the bytes from. */
+function artifactDownloadPath(addonId, artifactId) {
+	return `/addon/${addonId}/${NC_ARTIFACT_READ_PREFIX}/${artifactId}`;
+}
+var NcArtifactIndex = class {
+	store;
+	logger;
+	addonId;
+	retentionMs;
+	now;
+	constructor(deps) {
+		this.store = deps.store;
+		this.logger = deps.logger;
+		this.addonId = deps.addonId;
+		this.retentionMs = deps.retentionMs;
+		this.now = deps.now ?? (() => Date.now());
+	}
+	static async declare(store) {
+		await store.declareCollection.mutate({
+			collection: NC_ARTIFACTS_COLLECTION,
+			columns: [...NC_ARTIFACTS_COLUMNS],
+			indexes: [...NC_ARTIFACTS_INDEXES]
+		});
+	}
+	/**
+	* Record one retained artefact. Returns the row as the viewer will see it, or
+	* null when the write failed — and a failure is LOGGED, per camera: an
+	* artefact silently absent from the index reads to an operator as an artefact
+	* that was never produced.
+	*/
+	async record(input) {
+		const createdAt = this.now();
+		const record = NcArtifactRecordSchema.parse({
+			id: input.id,
+			kind: input.kind,
+			mediaType: mediaTypeForMime(input.mime),
+			mime: input.mime,
+			sizeBytes: input.sizeBytes,
+			createdAt,
+			capturedAt: input.capturedAt,
+			expiresAt: createdAt + this.retentionMs,
+			deviceId: input.deviceId,
+			deviceIds: [...input.deviceIds],
+			...input.ruleId !== void 0 ? { ruleId: input.ruleId } : {},
+			...input.ruleName !== void 0 ? { ruleName: input.ruleName } : {},
+			...input.title !== void 0 ? { title: input.title } : {},
+			...input.posterArtifactId !== void 0 ? { posterArtifactId: input.posterArtifactId } : {},
+			downloadPath: artifactDownloadPath(this.addonId, input.id)
+		});
+		try {
+			await this.store.set.mutate({
+				collection: NC_ARTIFACTS_COLLECTION,
+				key: record.id,
+				value: {
+					kind: record.kind,
+					deviceId: record.deviceId,
+					ruleId: record.ruleId ?? "",
+					ownerUserId: input.ownerUserId ?? "",
+					capturedAt: record.capturedAt,
+					expiresAt: record.expiresAt,
+					record
+				}
+			});
+			return record;
+		} catch (err) {
+			this.logger.warn("artifact not indexed — it will not appear in the viewer", {
+				...record.deviceId !== null ? { tags: { deviceId: record.deviceId } } : {},
+				meta: {
+					artifactId: record.id,
+					kind: record.kind,
+					error: String(err)
+				}
+			});
+			return null;
+		}
+	}
+	/**
+	* One page, newest `capturedAt` first.
+	*
+	* Expiry is a PREDICATE, not a post-filter: a row whose bytes the shelf has
+	* already swept must not consume a slot of the page the caller asked for.
+	*/
+	async list(query, viewer) {
+		const filter = this.buildFilter(query, viewer);
+		try {
+			const [rows, total] = await Promise.all([this.store.query.query({
+				collection: NC_ARTIFACTS_COLLECTION,
+				filter: {
+					...filter,
+					orderBy: {
+						field: "capturedAt",
+						direction: "desc"
+					},
+					limit: query.limit,
+					offset: query.offset
+				}
+			}), this.store.count.query({
+				collection: NC_ARTIFACTS_COLLECTION,
+				filter
+			})]);
+			const artifacts = this.parseRows(rows);
+			return {
+				artifacts,
+				total,
+				hasMore: query.offset + artifacts.length < total
+			};
+		} catch (err) {
+			this.logger.warn("artifact index query failed", { meta: { error: String(err) } });
+			return {
+				artifacts: [],
+				total: 0,
+				hasMore: false
+			};
+		}
+	}
+	/**
+	* One artefact by id, or null when it does not exist, has expired, or belongs
+	* to another user. All three answer the same way ON PURPOSE — a surface that
+	* distinguishes "not yours" from "not there" tells a caller what other people
+	* own.
+	*/
+	async get(artifactId, viewer) {
+		const row = await this.readRow(artifactId);
+		if (row === null) return null;
+		if (row.record.expiresAt <= this.now()) return null;
+		if (!viewer.isAdmin && row.ownerUserId !== "" && row.ownerUserId !== viewer.userId) return null;
+		return row.record;
+	}
+	/**
+	* Resolve an id for the BYTES route — visibility-free by design.
+	*
+	* The route is served `authenticated`, so the hub has already established a
+	* principal; what this answers is only "is this id an indexed artefact, and is
+	* it still meant to exist". Per-user artefact scoping on the byte route would
+	* be a second authorization model layered on an unguessable id, and this repo
+	* has one of those already (`data-plane-access.ts`): a plane serving ONE item
+	* the caller had to be told about is `authenticated`.
+	*/
+	async resolve(artifactId) {
+		return (await this.readRow(artifactId))?.record ?? null;
+	}
+	/** One row by primary key, parsed. Null when absent or no longer valid. */
+	async readRow(artifactId) {
+		let raw;
+		try {
+			raw = await this.store.get.query({
+				collection: NC_ARTIFACTS_COLLECTION,
+				key: artifactId
+			});
+		} catch (err) {
+			this.logger.warn("artifact index lookup failed", { meta: {
+				artifactId,
+				error: String(err)
+			} });
+			return null;
+		}
+		if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return null;
+		const row = { ...raw };
+		const parsed = NcArtifactRecordSchema.safeParse(row["record"]);
+		if (!parsed.success) return null;
+		const owner = row["ownerUserId"];
+		return {
+			record: parsed.data,
+			ownerUserId: typeof owner === "string" ? owner : ""
+		};
+	}
+	/**
+	* Drop rows whose bytes are gone, in ONE `deleteWhere` rather than an N+1
+	* drain.
+	*
+	* TWO halves, and only one of them is safe everywhere:
+	*
+	* - **Expired rows** are time-based and node-independent. Always swept.
+	* - **Orphans** — rows whose file a byte/count bound took before the age bound
+	*   did — are found by reconciling against the shelf. That reconcile is only
+	*   valid for a caller whose shelf holds the bytes for the WHOLE index, and
+	*   the index is CENTRAL while the shelf is local: a second node running this
+	*   with its own (empty) shelf would read every row as an orphan and delete
+	*   the entire library. Hence `keptIds: null` — a caller that is not the
+	*   producing node states so, and the destructive half becomes unreachable
+	*   rather than merely un-called.
+	*
+	* @param keptIds the ids the caller's shelf holds, or `null` when this node is
+	*                not the one that produces artefacts.
+	*/
+	async prune(keptIds) {
+		let removed = 0;
+		try {
+			const expired = await this.store.deleteWhere.mutate({
+				collection: NC_ARTIFACTS_COLLECTION,
+				filter: { whereBetween: { expiresAt: [TIME_MIN, this.now() - 1] } }
+			});
+			removed += expired.deleted;
+			if (keptIds === null) {
+				if (removed > 0) this.logger.debug("artifact index pruned (expired only)", { meta: { removed } });
+				return removed;
+			}
+			const alive = new Set(keptIds);
+			const orphans = (await this.store.query.query({
+				collection: NC_ARTIFACTS_COLLECTION,
+				filter: { limit: NC_ARTIFACT_PRUNE_SCAN_LIMIT }
+			})).map((r) => r.id).filter((id) => !alive.has(id));
+			for (const id of orphans) {
+				await this.store.delete.mutate({
+					collection: NC_ARTIFACTS_COLLECTION,
+					key: id
+				});
+				removed += 1;
+			}
+			if (removed > 0) this.logger.debug("artifact index pruned", { meta: {
+				removed,
+				expired: expired.deleted,
+				orphaned: orphans.length
+			} });
+			return removed;
+		} catch (err) {
+			this.logger.warn("artifact index prune failed", { meta: { error: String(err) } });
+			return removed;
+		}
+	}
+	/** The visibility predicate: a caller sees global artefacts plus his own; an
+	*  admin sees every one. */
+	visibility(viewer) {
+		if (viewer.isAdmin) return {};
+		return { whereIn: { ownerUserId: ["", viewer.userId] } };
+	}
+	buildFilter(query, viewer) {
+		const whereIn = { ...this.visibility(viewer).whereIn };
+		if (query.kinds !== void 0 && query.kinds.length > 0) whereIn["kind"] = [...query.kinds];
+		if (query.deviceIds !== void 0 && query.deviceIds.length > 0) whereIn["deviceId"] = [...query.deviceIds];
+		const whereBetween = {
+			capturedAt: [query.fromMs ?? TIME_MIN, query.toMs ?? TIME_MAX],
+			expiresAt: [this.now(), TIME_MAX]
+		};
+		return {
+			...query.ruleId !== void 0 ? { where: { ruleId: query.ruleId } } : {},
+			...Object.keys(whereIn).length > 0 ? { whereIn } : {},
+			whereBetween
+		};
+	}
+	/** Parse the JSON column, skipping rows that no longer validate. A degraded
+	*  row must never cost the whole page. */
+	parseRows(rows) {
+		const out = [];
+		let skipped = 0;
+		for (const row of rows) {
+			const parsed = NcArtifactRecordSchema.safeParse(row.data["record"]);
+			if (!parsed.success) {
+				skipped += 1;
+				continue;
+			}
+			out.push(parsed.data);
+		}
+		if (skipped > 0) this.logger.warn("artifact index rows skipped as invalid", { meta: { skipped } });
+		return out;
+	}
+};
+//#endregion
 //#region ../types/dist/node.mjs
 var node_exports = /* @__PURE__ */ __exportAll({
 	FilesystemStorageProvider: () => FilesystemStorageProvider,
@@ -1963,6 +2358,61 @@ var NcArtifactPlane = class {
 		}
 	}
 	/**
+	* Publish bytes AND file them in the viewer's browsable index (task #36).
+	*
+	* Two differences from {@link publish}, both deliberate:
+	*
+	* 1. **The bytes are stored FIRST, and stored even when no public base URL
+	*    exists.** `publish` returns early on a loopback-only install because a
+	*    signed link nobody can open is worth nothing — but the VIEWER reaches
+	*    the hub directly over its own session, so an install with no tunnel
+	*    still gets a full artifact library. Making the index depend on a
+	*    reachable public address would have made the feature absent exactly on
+	*    the installs that are LAN-only.
+	* 2. **It answers the artefact id**, so a caller can link one artefact to
+	*    another — a timelapse's poster is its preview frame, and the video row
+	*    cannot name it without knowing the id the preview got.
+	*
+	* Never throws, for the same reason `publish` does not: an artefact library
+	* is an enhancement and must never cost a notification.
+	*/
+	async publishIndexed(bytes, mime, meta) {
+		let artifactId = null;
+		try {
+			const index = this.deps.index;
+			const stored = await this.deps.store.put(bytes, mime, { retain: index !== void 0 });
+			if (index !== void 0) artifactId = (await index.record({
+				...meta,
+				id: stored.id,
+				mime,
+				sizeBytes: stored.bytes
+			}))?.id ?? null;
+			const baseUrl = await this.resolveBaseUrl();
+			return {
+				url: baseUrl === null ? null : buildArtifactUrl({
+					baseUrl,
+					routePrefix: this.deps.routePrefix,
+					id: stored.id,
+					secret: this.deps.secret,
+					expMs: this.now() + (this.deps.ttlMs ?? DEFAULT_TTL_MS)
+				}),
+				artifactId
+			};
+		} catch (err) {
+			this.deps.logger.warn("indexed artifact publish failed — shipping bytes only", {
+				...meta.deviceId !== null ? { tags: { deviceId: meta.deviceId } } : {},
+				meta: {
+					kind: meta.kind,
+					error: String(err)
+				}
+			});
+			return {
+				url: null,
+				artifactId
+			};
+		}
+	}
+	/**
 	* Absolutize a path against the SAME base URL an artifact link would use.
 	*
 	* For links this plane does not host but a RECIPIENT still has to open — a
@@ -2028,6 +2478,124 @@ var NcArtifactPlane = class {
 	}
 };
 //#endregion
+//#region src/notification-center/artifact-read-plane.ts
+/**
+* Parse a single-range `Range` header against a known length.
+*
+* Returns `null` when there is nothing to honour (absent, malformed, multi-range
+* — all of which mean "send the whole thing"), and `'unsatisfiable'` when the
+* client asked for a range that cannot exist, which is a 416 and not a 200.
+*/
+function parseByteRange(header, length) {
+	if (header === void 0) return null;
+	const match = /^bytes=(\d*)-(\d*)$/.exec(header.trim());
+	if (match === null) return null;
+	const rawStart = match[1] ?? "";
+	const rawEnd = match[2] ?? "";
+	if (rawStart === "" && rawEnd === "") return null;
+	if (length === 0) return "unsatisfiable";
+	if (rawStart === "") {
+		const suffix = Number(rawEnd);
+		if (suffix === 0) return "unsatisfiable";
+		return {
+			start: Math.max(0, length - suffix),
+			end: length - 1
+		};
+	}
+	const start = Number(rawStart);
+	if (start >= length) return "unsatisfiable";
+	const end = rawEnd === "" ? length - 1 : Math.min(Number(rawEnd), length - 1);
+	if (end < start) return "unsatisfiable";
+	return {
+		start,
+		end
+	};
+}
+/** The last path segment, percent-decoded. */
+function artifactIdFrom(req) {
+	const url = new URL(req.url ?? "/", "http://placeholder");
+	try {
+		return decodeURIComponent(url.pathname.split("/").filter(Boolean).pop() ?? "");
+	} catch {
+		return "";
+	}
+}
+var NcArtifactReadPlane = class {
+	deps;
+	constructor(deps) {
+		this.deps = deps;
+	}
+	handler = async (req, res) => {
+		const artifactId = artifactIdFrom(req);
+		const record = await this.deps.index.resolve(artifactId);
+		if (record === null) {
+			this.refuse(res, 404, "not found");
+			return;
+		}
+		const found = await this.deps.store.read(artifactId);
+		if (found === null) {
+			this.deps.logger.warn("artifact bytes gone — index row outlived the shelf", {
+				...record.deviceId !== null ? { tags: { deviceId: record.deviceId } } : {},
+				meta: {
+					artifactId,
+					kind: record.kind,
+					expiresAt: record.expiresAt
+				}
+			});
+			this.refuse(res, 404, "not found");
+			return;
+		}
+		if (req.method === "HEAD") {
+			res.writeHead(200, this.baseHeaders(record, found.bytes.byteLength, found.mime));
+			res.end();
+			return;
+		}
+		const range = parseByteRange(headerOf(req, "range"), found.bytes.byteLength);
+		if (range === "unsatisfiable") {
+			res.writeHead(416, {
+				"content-range": `bytes */${found.bytes.byteLength}`,
+				"content-type": "text/plain"
+			});
+			res.end("range not satisfiable");
+			return;
+		}
+		if (range === null) {
+			res.writeHead(200, this.baseHeaders(record, found.bytes.byteLength, found.mime));
+			res.end(found.bytes);
+			return;
+		}
+		const slice = found.bytes.subarray(range.start, range.end + 1);
+		res.writeHead(206, {
+			...this.baseHeaders(record, slice.byteLength, found.mime),
+			"content-range": `bytes ${range.start}-${range.end}/${found.bytes.byteLength}`
+		});
+		res.end(slice);
+	};
+	baseHeaders(record, length, mime) {
+		return {
+			"content-type": mime,
+			"content-length": String(length),
+			"accept-ranges": "bytes",
+			"cache-control": "private, max-age=3600",
+			"content-disposition": `inline; filename="${filenameFor(record)}"`
+		};
+	}
+	refuse(res, status, body) {
+		res.writeHead(status, { "content-type": "text/plain" });
+		res.end(body);
+	}
+};
+/** A name a client will accept, from what the artefact IS. */
+function filenameFor(record) {
+	const ext = record.mime === "video/mp4" ? "mp4" : record.mime === "image/gif" ? "gif" : record.mime === "image/png" ? "png" : "jpg";
+	return `${record.kind}-${record.capturedAt}.${ext}`;
+}
+function headerOf(req, name) {
+	const value = req.headers[name];
+	if (Array.isArray(value)) return value[0];
+	return value;
+}
+//#endregion
 //#region src/notification-center/artifact-store.ts
 /**
 * NcArtifactStore — the bytes behind a signed notification-artifact URL.
@@ -2042,9 +2610,25 @@ var NcArtifactPlane = class {
 * bites first, the oldest artifacts go. A sweep on boot clears whatever a crash
 * left behind — the directory is disposable by construction, so a lost file is
 * a 404 on one link, never a corrupt state.
+*
+* ## The retained shelf (`kept/`)
+*
+* Task #36 gave the viewer a browsable artifact index, and an index whose bytes
+* evaporate in six hours is an index of 404s. So a `put` may ask to be RETAINED:
+* the bytes then land on a second shelf inside the same directory with its OWN
+* three bounds (age, count, and — because a timelapse mp4 is megabytes — total
+* BYTES). It is still a scratch, just a longer one: the index row carries an
+* `expiresAt` derived from the same age bound, so "gone" is a state the viewer
+* is told about rather than a surprise 404.
+*
+* The shelf is a subdirectory ON PURPOSE. The scratch's `list()` skips
+* non-files, so the two shelves cannot sweep each other, and neither bound had
+* to learn about the other's entries.
 */
 var DEFAULT_MAX_AGE_MS = 6 * 36e5;
 var DEFAULT_MAX_ENTRIES = 500;
+/** The retained shelf's subdirectory name, inside the scratch directory. */
+var KEPT_SUBDIR = "kept";
 /** `image/jpeg` → `jpg`, so a fetched link has a name a client will accept. */
 function extensionFor(mime) {
 	if (mime === "image/jpeg") return "jpg";
@@ -2058,6 +2642,10 @@ var NcArtifactStore = class {
 	now;
 	maxAgeMs;
 	maxEntries;
+	keptMaxAgeMs;
+	keptMaxEntries;
+	keptMaxBytes;
+	keptDir;
 	/** id → mime, so the route can answer with the right content-type without
 	*  re-deriving it from the extension on every request. */
 	mimeById = /* @__PURE__ */ new Map();
@@ -2066,17 +2654,32 @@ var NcArtifactStore = class {
 		this.now = options.now ?? (() => Date.now());
 		this.maxAgeMs = options.maxAgeMs ?? DEFAULT_MAX_AGE_MS;
 		this.maxEntries = options.maxEntries ?? DEFAULT_MAX_ENTRIES;
+		this.keptMaxAgeMs = options.keptMaxAgeMs ?? 12096e5;
+		this.keptMaxEntries = options.keptMaxEntries ?? 2e3;
+		this.keptMaxBytes = options.keptMaxBytes ?? 2147483648;
+		this.keptDir = path.join(options.dir, KEPT_SUBDIR);
+	}
+	/** How long a retained artifact stays fetchable — the index's `expiresAt`
+	*  is derived from this, so the two can never disagree. */
+	get retentionMs() {
+		return this.keptMaxAgeMs;
 	}
 	/** Create the directory and sweep whatever a previous run left behind. */
 	async start() {
 		await promises.mkdir(this.options.dir, { recursive: true });
 		await this.sweep();
 	}
-	/** Persist bytes and return the artifact handle (never throws on sweep). */
-	async put(bytes, mime) {
+	/**
+	* Persist bytes and return the artifact handle (never throws on sweep).
+	*
+	* The retained shelf is created LAZILY: an install that never produces a
+	* browsable artifact keeps a directory that is empty when it is empty.
+	*/
+	async put(bytes, mime, options = {}) {
 		const id = `${this.now()}-${randomUUID()}`;
-		const file = path.join(this.options.dir, `${id}.${extensionFor(mime)}`);
-		await promises.mkdir(this.options.dir, { recursive: true });
+		const dir = options.retain === true ? this.keptDir : this.options.dir;
+		const file = path.join(dir, `${id}.${extensionFor(mime)}`);
+		await promises.mkdir(dir, { recursive: true });
 		await promises.writeFile(file, bytes);
 		this.mimeById.set(id, mime);
 		await this.sweep();
@@ -2089,7 +2692,7 @@ var NcArtifactStore = class {
 	/** Read an artifact's bytes + mime, or null when it is gone (expired/swept). */
 	async read(id) {
 		if (!/^[0-9]+-[0-9a-f-]{36}$/i.test(id)) return null;
-		const found = (await this.list()).find((e) => e.id === id);
+		const found = [...await this.list(this.options.dir), ...await this.list(this.keptDir)].find((e) => e.id === id);
 		if (!found) return null;
 		try {
 			return {
@@ -2100,6 +2703,10 @@ var NcArtifactStore = class {
 			return null;
 		}
 	}
+	/** The ids still on the retained shelf — what the index reconciles against. */
+	async keptIds() {
+		return (await this.list(this.keptDir)).map((e) => e.id);
+	}
 	/** Delete every artifact (operator cleanup / shutdown). */
 	async clear() {
 		await promises.rm(this.options.dir, {
@@ -2108,13 +2715,39 @@ var NcArtifactStore = class {
 		}).catch(() => {});
 		this.mimeById.clear();
 	}
-	/** Age- then count-bounded prune. Best-effort: a failed unlink is logged once. */
+	/** Prune both shelves under their own bounds. Best-effort: a failed unlink is
+	*  logged once and the rest of the sweep still runs. */
 	async sweep() {
-		const entries = await this.list();
-		const cutoff = this.now() - this.maxAgeMs;
+		await this.sweepShelf(await this.list(this.options.dir), {
+			maxAgeMs: this.maxAgeMs,
+			maxEntries: this.maxEntries
+		});
+		await this.sweepShelf(await this.list(this.keptDir), {
+			maxAgeMs: this.keptMaxAgeMs,
+			maxEntries: this.keptMaxEntries,
+			maxBytes: this.keptMaxBytes
+		});
+	}
+	/**
+	* Age first, then count, then total bytes — newest always survives.
+	*
+	* The newest entry is never swept by the byte bound even when it alone
+	* exceeds it: a shelf that deletes what it has just written can serve
+	* nothing, and the caller has already paid for the render.
+	*/
+	async sweepShelf(entries, bounds) {
+		const cutoff = this.now() - bounds.maxAgeMs;
 		const doomed = entries.filter((e) => e.mtimeMs < cutoff);
-		const survivors = entries.filter((e) => e.mtimeMs >= cutoff).toSorted((a, b) => b.mtimeMs - a.mtimeMs);
-		doomed.push(...survivors.slice(this.maxEntries));
+		const fresh = entries.filter((e) => e.mtimeMs >= cutoff).toSorted((a, b) => b.mtimeMs - a.mtimeMs);
+		doomed.push(...fresh.slice(bounds.maxEntries));
+		const maxBytes = bounds.maxBytes;
+		if (maxBytes !== void 0) {
+			let running = 0;
+			for (const [i, e] of fresh.slice(0, bounds.maxEntries).entries()) {
+				running += e.sizeBytes;
+				if (running > maxBytes && i > 0) doomed.push(e);
+			}
+		}
 		for (const e of doomed) try {
 			await promises.rm(e.file, { force: true });
 			this.mimeById.delete(e.id);
@@ -2125,23 +2758,24 @@ var NcArtifactStore = class {
 			} });
 		}
 	}
-	async list() {
+	async list(dir) {
 		let names;
 		try {
-			names = await promises.readdir(this.options.dir);
+			names = await promises.readdir(dir);
 		} catch {
 			return [];
 		}
 		const out = [];
 		for (const name of names) {
-			const file = path.join(this.options.dir, name);
+			const file = path.join(dir, name);
 			try {
 				const st = await promises.stat(file);
 				if (!st.isFile()) continue;
 				out.push({
 					id: name.slice(0, name.lastIndexOf(".")),
 					file,
-					mtimeMs: st.mtimeMs
+					mtimeMs: st.mtimeMs,
+					sizeBytes: st.size
 				});
 			} catch {}
 		}
@@ -10005,7 +10639,15 @@ var NcSummaryProducer = class {
 		}
 		const bytes = new Uint8Array(rendered.jpeg.byteLength);
 		bytes.set(rendered.jpeg);
-		const url = await this.deps.publish(bytes, "image/jpeg");
+		const { url } = await this.deps.publish(bytes, "image/jpeg", {
+			kind: "summary-mosaic",
+			deviceId: rule.deviceIds[0] ?? null,
+			deviceIds: [...new Set(tiles.map((t) => t.candidate.deviceId))],
+			capturedAt: window.endMs,
+			ruleId: rule.id,
+			ruleName: rule.name,
+			...rule.ownerUserId !== void 0 ? { ownerUserId: rule.ownerUserId } : {}
+		});
 		if (url === null) {
 			this.deps.logger.warn("summary mosaic not published: no reachable public endpoint", { meta: { ruleId: rule.id } });
 			return {
@@ -10999,7 +11641,7 @@ function unknownNcTextKeys(keys, bundles = NC_TEXT_BUNDLES) {
 * durable document stays the sparse map its schema describes.
 */
 function applyNcTextOverridePatch(current, language, patch) {
-	const next = { ...current[language] ?? {} };
+	const next = { ...current[language] };
 	for (const [key, value] of Object.entries(patch)) {
 		if (value === null || value.trim().length === 0) {
 			delete next[key];
@@ -11567,7 +12209,7 @@ var TimelapseRenderer = class {
 			}
 		});
 		const finished = await this.awaitReady(queued, tags);
-		const published = await this.publish(finished.id, deviceId, tags, request.previewText, request.previewMode ?? "image");
+		const published = await this.publish(finished.id, request, tags);
 		const downloadUrl = await this.ports.resolveDownloadUrl?.({ exportId: finished.id }).catch(() => null);
 		return {
 			exportId: finished.id,
@@ -11619,7 +12261,9 @@ var TimelapseRenderer = class {
 	* notification, not a failed window — and failing here would leave the pair
 	* unstamped and re-render the same eight hours on the next tick.
 	*/
-	async publish(exportId, deviceId, tags, previewText, previewMode) {
+	async publish(exportId, request, tags) {
+		const { deviceId, previewText } = request;
+		const previewMode = request.previewMode ?? "image";
 		const publish = this.ports.publishArtifact;
 		const none = {
 			video: null,
@@ -11639,7 +12283,11 @@ var TimelapseRenderer = class {
 				...previewText !== void 0 ? {
 					previewText,
 					previewMode
-				} : {}
+				} : {},
+				capturedAt: request.window.endMs,
+				ruleId: request.ruleId,
+				ruleName: request.ruleName,
+				...request.ownerUserId !== void 0 ? { ownerUserId: request.ownerUserId } : {}
 			});
 			if (set.video === null) this.ports.logger.warn("timelapse artifact could not be published — link-less delivery", {
 				tags,
@@ -11995,7 +12643,8 @@ var TimelapseScheduler = class {
 					...rule.previewText !== void 0 ? { text: rule.previewText } : {}
 				}),
 				previewMode: rule.previewMode,
-				...rule.reportClasses !== void 0 ? { reportClasses: rule.reportClasses } : {}
+				...rule.reportClasses !== void 0 ? { reportClasses: rule.reportClasses } : {},
+				...rule.ownerUserId !== void 0 ? { ownerUserId: rule.ownerUserId } : {}
 			});
 			const rows = buildTimelapseOutboxInputs({
 				texts: this.texts,
@@ -13311,6 +13960,7 @@ var NotificationCenter = class NotificationCenter {
 		await TimelapseStore.declare(store);
 		await NcSummaryStore.declare(store);
 		await NcTextCatalogStore.declare(store);
+		await NcArtifactIndex.declare(store);
 	}
 	/**
 	* Load rules (every node — the cap provider serves CRUD from any node).
@@ -15368,7 +16018,23 @@ var ncActions = defineCustomActions({
 	}), NcTextCatalogViewSchema, {
 		kind: "mutation",
 		auth: "admin"
-	})
+	}),
+	/**
+	* One page of artefacts, newest `capturedAt` first.
+	*
+	* `deviceIds` filters on the camera an artefact is FILED under. A digest
+	* spans cameras and is filed under its rule's first one (the same camera its
+	* outbox row uses); to ask "everything this digest produced" use `ruleId`.
+	*/
+	"nc.listArtifacts": customAction(NcArtifactQuerySchema, object({
+		artifacts: array(NcArtifactRecordSchema),
+		/** Rows matching the filter, not rows on this page. */
+		total: number().int().nonnegative(),
+		hasMore: boolean()
+	}), { caller: "required" }),
+	/** One artefact's metadata. `null` for unknown, expired AND not-yours alike —
+	*  a surface that distinguishes them reports what other people own. */
+	"nc.getArtifact": customAction(object({ artifactId: string().min(1) }), object({ artifact: NcArtifactRecordSchema.nullable() }), { caller: "required" })
 });
 /** Fail-closed caller resolution — an absent forwarded caller is NEVER admin. */
 function requireCaller(caller) {
@@ -15418,6 +16084,12 @@ function makeNcActionHandlers(deps) {
 		if (sum === void 0) throw new Error("this node does not host the summary producer — use the hub");
 		return sum;
 	};
+	/** The artefact index, or an honest refusal. */
+	const requireArtifacts = () => {
+		const index = deps.artifacts;
+		if (index === void 0) throw new Error("this node does not host the notification artifact index — use the hub");
+		return index;
+	};
 	/** The text catalog editor, or an honest refusal. */
 	const requireTexts = () => {
 		const editor = deps.texts;
@@ -15729,7 +16401,26 @@ function makeNcActionHandlers(deps) {
 			return input.language === void 0 ? texts.view() : texts.view(input.language);
 		},
 		"nc.setLanguage": async (input) => requireTexts().setLanguage(input.language),
-		"nc.setTextOverrides": async (input) => requireTexts().setOverrides(input.language, input.overrides)
+		"nc.setTextOverrides": async (input) => requireTexts().setOverrides(input.language, input.overrides),
+		"nc.listArtifacts": async (input, caller) => {
+			const c = requireCaller(caller);
+			const page = await requireArtifacts().list(input, {
+				userId: c.userId,
+				isAdmin: c.isAdmin
+			});
+			return {
+				artifacts: [...page.artifacts],
+				total: page.total,
+				hasMore: page.hasMore
+			};
+		},
+		"nc.getArtifact": async (input, caller) => {
+			const c = requireCaller(caller);
+			return { artifact: await requireArtifacts().get(input.artifactId, {
+				userId: c.userId,
+				isAdmin: c.isAdmin
+			}) };
+		}
 	};
 }
 //#endregion
@@ -15783,7 +16474,8 @@ var PREVIEW_FALLBACK_NAME = "timelapse-preview.jpg";
 *          member has a logged reason. It never rejects.
 */
 function buildTimelapseArtifactPublisher(ports) {
-	return async ({ exportId, deviceId, previewText, previewMode }) => {
+	return async (request) => {
+		const { exportId, deviceId, previewText, previewMode } = request;
 		const tags = { deviceId };
 		const none = {
 			video: null,
@@ -15814,15 +16506,32 @@ function buildTimelapseArtifactPublisher(ports) {
 			return none;
 		}
 		const mp4 = Buffer$1.from(read.base64, "base64");
+		const capturedAt = request.capturedAt ?? Date.now();
+		const common = {
+			deviceId,
+			deviceIds: [deviceId],
+			capturedAt,
+			...request.ruleId !== void 0 ? { ruleId: request.ruleId } : {},
+			...request.ruleName !== void 0 ? { ruleName: request.ruleName } : {},
+			...request.ownerUserId !== void 0 ? { ownerUserId: request.ownerUserId } : {}
+		};
 		const preview = await publishPreview(ports, {
 			mp4,
 			deviceId,
 			tags,
 			previewText,
-			previewMode: previewMode ?? "image"
+			previewMode: previewMode ?? "image",
+			meta: {
+				...common,
+				kind: "timelapse-preview"
+			}
 		});
 		try {
-			const url = await ports.publish(mp4, read.contentType);
+			const { url } = await ports.publish(mp4, read.contentType, {
+				...common,
+				kind: "timelapse",
+				...preview.artifactId !== null ? { posterArtifactId: preview.artifactId } : {}
+			});
 			if (url === null) {
 				ports.logger.warn("timelapse artifact not published: no reachable public endpoint", {
 					tags,
@@ -15830,7 +16539,7 @@ function buildTimelapseArtifactPublisher(ports) {
 				});
 				return {
 					video: null,
-					preview
+					preview: preview.ref
 				};
 			}
 			ports.logger.info("timelapse artifact published", {
@@ -15839,7 +16548,7 @@ function buildTimelapseArtifactPublisher(ports) {
 					exportId,
 					bytes: read.bytes,
 					name: read.name,
-					preview: preview !== null
+					preview: preview.ref !== null
 				}
 			});
 			return {
@@ -15848,7 +16557,7 @@ function buildTimelapseArtifactPublisher(ports) {
 					mime: read.contentType,
 					name: read.name
 				},
-				preview
+				preview: preview.ref
 			};
 		} catch (err) {
 			ports.logger.warn("timelapse artifact not published: artifact plane refused the bytes", {
@@ -15860,18 +16569,22 @@ function buildTimelapseArtifactPublisher(ports) {
 			});
 			return {
 				video: null,
-				preview
+				preview: preview.ref
 			};
 		}
 	};
 }
+var NO_PREVIEW = {
+	ref: null,
+	artifactId: null
+};
 /**
 * The preview half. Best-effort at every step and never throws: the picture is
 * an enhancement, the video is the notification.
 */
 async function publishPreview(ports, input) {
 	const render = ports.renderPreview;
-	if (render === void 0 || input.previewText === void 0) return null;
+	if (render === void 0 || input.previewText === void 0) return NO_PREVIEW;
 	try {
 		const rendered = await render({
 			mp4: input.mp4,
@@ -15879,23 +16592,29 @@ async function publishPreview(ports, input) {
 			deviceId: input.deviceId,
 			mode: input.previewMode
 		});
-		if (rendered === null) return null;
-		const url = await ports.publish(rendered.bytes, rendered.mime);
+		if (rendered === null) return NO_PREVIEW;
+		const { url, artifactId } = await ports.publish(rendered.bytes, rendered.mime, input.meta);
 		if (url === null) {
 			ports.logger.warn("timelapse preview not published: no reachable public endpoint", { tags: input.tags });
-			return null;
+			return {
+				ref: null,
+				artifactId
+			};
 		}
 		return {
-			url,
-			mime: rendered.mime,
-			name: PREVIEW_NAME_BY_MIME[rendered.mime] ?? PREVIEW_FALLBACK_NAME
+			ref: {
+				url,
+				mime: rendered.mime,
+				name: PREVIEW_NAME_BY_MIME[rendered.mime] ?? PREVIEW_FALLBACK_NAME
+			},
+			artifactId
 		};
 	} catch (err) {
 		ports.logger.warn("timelapse preview not published: publish threw", {
 			tags: input.tags,
 			meta: { error: String(err) }
 		});
-		return null;
+		return NO_PREVIEW;
 	}
 }
 /** Title size as a fraction of the frame WIDTH — so it reads the same on a
@@ -16382,6 +17101,10 @@ function startAlarmPanelConvergence(ports) {
 * `data-plane-access.spec.ts` asserts they still match the constants their
 * handlers register with — a mirror nothing checks is a lie waiting to happen.
 */
+/** The artefact read route's prefix, imported rather than mirrored: it is
+*  ALSO the prefix `artifactDownloadPath` writes into every index row, and two
+*  copies of that string is a 404 nobody would find. */
+var NC_ARTIFACT_READ_PREFIX_REF = NC_ARTIFACT_READ_PREFIX;
 var TRAINING_EXPORT_PREFIX_REF = "training-export";
 var RETRAIN_EXPORT_PREFIX_REF = "retrain-export";
 var DEBUG_EXPORT_PREFIX_REF = "debug-export";
@@ -16397,6 +17120,14 @@ var PIPELINE_ANALYTICS_PLANE_ACCESS = {
 	"nc-action": "public",
 	/** Self-authenticating single-use artifact token (D47). */
 	"nc-artifact": "public",
+	/**
+	* The VIEWER's read of the same bytes (task #36). One indexed artefact by an
+	* unguessable id the caller was handed by `nc.listArtifacts` — the rule above,
+	* applied unchanged. It is deliberately NOT the `public` signed plane: the
+	* viewer holds a session, and pre-minting a 24 h signed link for every
+	* artefact a user might scroll to is a link-leak surface for no gain.
+	*/
+	[NC_ARTIFACT_READ_PREFIX_REF]: "authenticated",
 	/** Every frame behind a marked selection — a corpus, not an item. */
 	[TRAINING_EXPORT_PREFIX_REF]: "admin",
 	[RETRAIN_EXPORT_PREFIX_REF]: "admin",
@@ -41339,6 +42070,15 @@ var REBUILD_FALLBACK_NODE_ID = "hub";
 */
 var TIMELAPSE_TRACK_QUERY_LIMIT = 2e3;
 var PIPELINE_ANALYTICS_ADDON_ID = "pipeline-analytics";
+/** Artefact index ⇄ shelf reconcile cadence. Hourly: the two only drift on the
+*  bounds' own timescale (14 days / 2000 entries / 2 GiB). */
+var NC_ARTIFACT_PRUNE_INTERVAL_MS = 36e5;
+/** What a publish answers on a node whose artifact plane never came up: no
+*  link, no index row — and, exactly as before, bytes-only delivery. */
+var NO_PUBLICATION = {
+	url: null,
+	artifactId: null
+};
 /**
 * The FULL action catalog for this addon.
 *
@@ -41620,6 +42360,12 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 	*  data-plane handle. Null until served / when the facility is absent. */
 	ncArtifactPlane = null;
 	ncArtifactDataPlane = null;
+	/** The viewer's artefact library (task #36): the index, its authenticated
+	*  bytes route, and the store the two share. Null until served. */
+	ncArtifactIndex = null;
+	ncArtifactStore = null;
+	ncArtifactReadDataPlane = null;
+	ncArtifactPruneTimer = null;
 	/**
 	* Roadmap 4b: ONE cut of an event, in every container the rule asked for.
 	*
@@ -41806,6 +42552,31 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 	* Best-effort at every step: no facility, no secret or no reachable base URL
 	* ⇒ no plane, and the dispatcher keeps shipping bytes exactly as before.
 	*/
+	/**
+	* Reconcile the artefact index against the shelf that holds the bytes.
+	*
+	* Hourly, because the two drift only on the bounds' timescale: a row expires
+	* on the shelf's own age bound (14 d) or its file is evicted by the count/byte
+	* bound. Without this, a list eventually serves rows whose bytes 404 — and a
+	* broken tile is the one failure an operator DOES report.
+	*/
+	startNcArtifactPrune() {
+		if (this.ncArtifactPruneTimer !== null) return;
+		const run = async () => {
+			const index = this.ncArtifactIndex;
+			const store = this.ncArtifactStore;
+			if (index === null || store === null) return;
+			try {
+				await store.sweep();
+				await index.prune(this.isPostProcessingNode ? await store.keptIds() : null);
+			} catch (err) {
+				this.ctx.logger.warn("nc artifact prune failed", { meta: { error: errMsg(err) } });
+			}
+		};
+		run();
+		this.ncArtifactPruneTimer = setInterval(() => void run(), NC_ARTIFACT_PRUNE_INTERVAL_MS);
+		this.ncArtifactPruneTimer.unref?.();
+	}
 	async serveNcArtifactPlane() {
 		try {
 			const secretState = this.state("ncArtifactSecret", NcArtifactSecretSchema, "");
@@ -41819,9 +42590,18 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 				logger: this.ctx.logger.child("nc-artifacts")
 			});
 			await store.start();
+			this.ncArtifactStore = store;
+			const index = new NcArtifactIndex({
+				store: this.ctx.api.settingsStore,
+				logger: this.ctx.logger.child("nc-artifacts"),
+				addonId: this.ctx.id,
+				retentionMs: store.retentionMs
+			});
+			this.ncArtifactIndex = index;
 			const plane = new NcArtifactPlane({
 				store,
 				secret,
+				index,
 				logger: this.ctx.logger.child("nc-artifacts"),
 				routePrefix: `/addon/${this.ctx.id}/nc-artifact`,
 				listEndpoints: () => this.ncEndpoints()
@@ -41832,7 +42612,23 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 				handler: plane.handler
 			}) ?? null;
 			this.ncArtifactPlane = this.ncArtifactDataPlane !== null ? plane : null;
-			this.ctx.logger.info("nc-artifact data-plane served", { meta: { served: this.ncArtifactPlane !== null } });
+			const readPlane = new NcArtifactReadPlane({
+				index,
+				store,
+				logger: this.ctx.logger.child("nc-artifacts")
+			});
+			this.ncArtifactReadDataPlane = await this.ctx.dataPlane?.serve({
+				prefix: NC_ARTIFACT_READ_PREFIX_REF,
+				access: planeAccess(NC_ARTIFACT_READ_PREFIX_REF),
+				handler: readPlane.handler
+			}) ?? null;
+			this.startNcArtifactPrune();
+			this.ctx.logger.info("nc-artifact data-plane served", { meta: {
+				served: this.ncArtifactPlane !== null,
+				libraryServed: this.ncArtifactReadDataPlane !== null,
+				libraryAccess: planeAccess(NC_ARTIFACT_READ_PREFIX_REF),
+				retentionDays: Math.round(store.retentionMs / 864e5)
+			} });
 		} catch (err) {
 			this.ctx.logger.warn("nc-artifact data-plane failed to serve", { meta: { error: errMsg(err) } });
 		}
@@ -42280,7 +43076,8 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 				store: center.summaryStore,
 				runNow: (input) => center.runSummaryNow(input)
 			},
-			texts: center.textCatalogEditor
+			texts: center.textCatalogEditor,
+			...this.ncArtifactIndex !== null ? { artifacts: this.ncArtifactIndex } : {}
 		});
 	}
 	/** Declare typed collections up-front so the first insert doesn't race with
@@ -43069,7 +43866,7 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 				timestamp,
 				data: jpeg
 			}),
-			publish: async (bytes, mime) => await this.ncArtifactPlane?.publish(bytes, mime) ?? null
+			publish: async (bytes, mime, meta) => await this.ncArtifactPlane?.publishIndexed(bytes, mime, meta) ?? NO_PUBLICATION
 		};
 	}
 	/**
@@ -43142,7 +43939,7 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 			publishArtifact: buildTimelapseArtifactPublisher({
 				logger: this.ctx.logger.child("Timelapse"),
 				readExportBytes: ({ exportId }) => api.recordingExport.readExportBytes.query({ exportId }),
-				publish: async (bytes, mime) => await this.ncArtifactPlane?.publish(bytes, mime) ?? null,
+				publish: async (bytes, mime, meta) => await this.ncArtifactPlane?.publishIndexed(bytes, mime, meta) ?? NO_PUBLICATION,
 				renderPreview: async ({ mode, ...input }) => {
 					const previewPorts = {
 						logger: this.ctx.logger.child("Timelapse"),
@@ -43809,6 +44606,14 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 		this.retrainExportDataPlane = null;
 		await this.debugExportDataPlane?.dispose();
 		this.debugExportDataPlane = null;
+		if (this.ncArtifactPruneTimer !== null) {
+			clearInterval(this.ncArtifactPruneTimer);
+			this.ncArtifactPruneTimer = null;
+		}
+		await this.ncArtifactReadDataPlane?.dispose();
+		this.ncArtifactReadDataPlane = null;
+		this.ncArtifactIndex = null;
+		this.ncArtifactStore = null;
 	}
 	async handleInferenceResult(data) {
 		if (this.shuttingDown) return;