@danypops/vehicle-core 0.7.0 → 0.9.0

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export * from "./atomic-json.js";
+export * from "./vehicle-approvals.js";
 export * from "./vehicle-contract.js";
 export * from "./vehicle-errors.js";
 export * from "./vehicle-jobs.js";
+export * from "./vehicle-watchers.js";

package/dist/index.js

@@ -1,4 +1,6 @@
 export * from "./atomic-json.js";
+export * from "./vehicle-approvals.js";
 export * from "./vehicle-contract.js";
 export * from "./vehicle-errors.js";
 export * from "./vehicle-jobs.js";
+export * from "./vehicle-watchers.js";

package/dist/vehicle-approvals.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Wire-level shapes for the Approval Gate: a pending human/authority decision
+ * that stands between a gated-effect invoke() and its handler actually
+ * running. Kept in vehicle-core (runtime-neutral, zero dependencies) --
+ * the actual signing/verification authority (HmacApprovalAuthority) needs
+ * node:crypto and lives in vehicle-server instead, the same split
+ * atomic-json.ts already uses for fs access.
+ */
+import type { VehicleEffect, VehiclePrincipal } from "./vehicle-contract.js";
+/** Set once at registry-configuration time (VehicleRegistry.configureApprovals()); never on a per-invoke basis. */
+export declare const DEFAULT_APPROVAL_EFFECTS: readonly VehicleEffect[];
+/** How long a request stays resolvable before it lapses and must be re-requested. */
+export declare const DEFAULT_APPROVAL_TIMEOUT_MS: number;
+/** Emitted (as a Vehicle Event) the moment a gated-effect invoke() has no valid capability -- durable-first, before any interactive prompt is attempted. */
+export interface VehicleApprovalRequest {
+    readonly requestId: string;
+    readonly operationName: string;
+    readonly operationVersion: number;
+    readonly effect: VehicleEffect;
+    readonly principal?: VehiclePrincipal;
+    readonly requestedAt: number;
+    readonly expiresAt: number;
+    /** sha256 hex of the exact input the gated invoke() attempted -- a minted capability is scoped to this input, not just the operation. */
+    readonly inputHash: string;
+}
+export type VehicleApprovalDecision = "granted" | "denied";
+/** Emitted once vehicle.approval.resolve settles a request, whichever way. */
+export interface VehicleApprovalOutcome {
+    readonly requestId: string;
+    readonly decision: VehicleApprovalDecision;
+    readonly decidedAt: number;
+    readonly decidedBy?: string;
+}
+/**
+ * The real authority behind an approvalCapability -- replaces today's
+ * "any non-empty string satisfies it" rubber stamp. mint() is called only
+ * from inside vehicle.approval.resolve once a decision is actually made;
+ * verify() is called from invoke() itself against whatever capability the
+ * caller presents. A capability is scoped to the exact operation+input it
+ * was minted for and expires with its originating request -- presenting a
+ * capability minted for a different operation, a different input, or one
+ * already consumed (single-use) must fail verify().
+ */
+export interface VehicleApprovalAuthority {
+    mint(request: Pick<VehicleApprovalRequest, "requestId" | "operationName" | "operationVersion" | "expiresAt" | "inputHash">): string;
+    verify(capability: string, operationName: string, operationVersion: number, inputHash: string): boolean;
+}
+/** Built into every VehicleRegistry once configureApprovals() is called -- never registered unconditionally, so a Vehicle that never opts in has zero manifest/shape change. */
+export declare const vehicleApprovalRequestedEvent: import("./vehicle-contract.js").VehicleEvent<VehicleApprovalRequest>;
+export declare const vehicleApprovalResolvedEvent: import("./vehicle-contract.js").VehicleEvent<VehicleApprovalOutcome>;

package/dist/vehicle-approvals.js

@@ -0,0 +1,75 @@
+import { defineVehicleEvent, defineVehicleSchema } from "./vehicle-contract.js";
+/** Set once at registry-configuration time (VehicleRegistry.configureApprovals()); never on a per-invoke basis. */
+export const DEFAULT_APPROVAL_EFFECTS = ["destructive", "open-world"];
+/** How long a request stays resolvable before it lapses and must be re-requested. */
+export const DEFAULT_APPROVAL_TIMEOUT_MS = 5 * 60_000;
+const requestedPayloadSchema = defineVehicleSchema({
+    jsonSchema: {
+        type: "object",
+        properties: {
+            requestId: { type: "string" },
+            operationName: { type: "string" },
+            operationVersion: { type: "number" },
+            effect: { type: "string" },
+            requestedAt: { type: "number" },
+            expiresAt: { type: "number" },
+            inputHash: { type: "string" },
+        },
+        required: ["requestId", "operationName", "operationVersion", "effect", "requestedAt", "expiresAt", "inputHash"],
+        additionalProperties: true,
+    },
+    safeParse(value) {
+        if (typeof value !== "object" || value === null)
+            return { success: false, issues: [{ path: [], message: "input must be an object" }] };
+        const row = value;
+        if (typeof row.requestId !== "string" ||
+            typeof row.operationName !== "string" ||
+            typeof row.operationVersion !== "number" ||
+            typeof row.effect !== "string" ||
+            typeof row.requestedAt !== "number" ||
+            typeof row.expiresAt !== "number" ||
+            typeof row.inputHash !== "string") {
+            return { success: false, issues: [{ path: [], message: "invalid approval request payload" }] };
+        }
+        return { success: true, value: row };
+    },
+});
+const resolvedPayloadSchema = defineVehicleSchema({
+    jsonSchema: {
+        type: "object",
+        properties: {
+            requestId: { type: "string" },
+            decision: { type: "string", enum: ["granted", "denied"] },
+            decidedAt: { type: "number" },
+            decidedBy: { type: "string" },
+        },
+        required: ["requestId", "decision", "decidedAt"],
+        additionalProperties: true,
+    },
+    safeParse(value) {
+        if (typeof value !== "object" || value === null)
+            return { success: false, issues: [{ path: [], message: "input must be an object" }] };
+        const row = value;
+        if (typeof row.requestId !== "string" ||
+            (row.decision !== "granted" && row.decision !== "denied") ||
+            typeof row.decidedAt !== "number") {
+            return { success: false, issues: [{ path: [], message: "invalid approval outcome payload" }] };
+        }
+        return { success: true, value: row };
+    },
+});
+/** Built into every VehicleRegistry once configureApprovals() is called -- never registered unconditionally, so a Vehicle that never opts in has zero manifest/shape change. */
+export const vehicleApprovalRequestedEvent = defineVehicleEvent({
+    name: "vehicle.approval.requested",
+    version: 1,
+    description: "A gated-effect operation was invoked without a valid approval capability.",
+    payload: requestedPayloadSchema,
+    maxPayloadBytes: 16_384,
+});
+export const vehicleApprovalResolvedEvent = defineVehicleEvent({
+    name: "vehicle.approval.resolved",
+    version: 1,
+    description: "A pending approval request was granted or denied.",
+    payload: resolvedPayloadSchema,
+    maxPayloadBytes: 4_096,
+});

package/dist/vehicle-watchers.d.ts

@@ -0,0 +1,60 @@
+/**
+ * "Watch a changing resource, get notified" -- lifted near-verbatim from
+ * Lector's own `WatchRegistry` (packages/lector/src/domain/watch-registry.ts),
+ * generalized past Lector's own workspace/pattern vocabulary (`workspaceId`
+ * -> `scope`, `pattern` -> `resource`) into a shared Vehicle primitive.
+ * Confirmed independently reinvented three-plus times across this house's
+ * own ecosystem before this existed: Lector's own registry, Lector's CLI
+ * (a second, non-resilient reimplementation of the same watch/subscribe
+ * shape), and Papyrus's TaskOverlay/NoteOverlay (each hand-rolling the same
+ * ensurePushChannel()+poll dance independently).
+ *
+ * Pure, in-memory bookkeeping only -- no filesystem, network, or PushChannel
+ * I/O here. Matching pattern/resource against a real changed resource is a
+ * provider's own job, not this registry's; this only tracks which topic a
+ * given (scope, resource) pair publishes under, and bounds how many watches
+ * one scope can accumulate.
+ */
+/** Matches WatchRegistry's own historical default (Lector's MAX_WATCHES_PER_WORKSPACE). */
+export declare const DEFAULT_MAX_WATCHES_PER_SCOPE = 32;
+export interface WatchRegistration {
+    readonly watchId: string;
+    readonly scope: string;
+    readonly resource: string;
+    readonly topic: string;
+}
+/** Raised when a scope already has its configured maximum of registrations -- fails closed, the same bounded-resource discipline every other Vehicle capability already applies, rather than letting one scope accumulate unbounded watch state. */
+export declare class WatchLimitExceeded extends Error {
+    readonly scope: string;
+    readonly max: number;
+    constructor(scope: string, max: number);
+}
+export interface WatchRegistryOptions {
+    /** Defaults to DEFAULT_MAX_WATCHES_PER_SCOPE. */
+    readonly maxWatchesPerScope?: number;
+}
+export declare class WatchRegistry {
+    private readonly byId;
+    private readonly byScope;
+    private readonly maxWatchesPerScope;
+    constructor(options?: WatchRegistryOptions);
+    add(scope: string, resource: string, watchId: string, topic: string): WatchRegistration;
+    /** The removed registration, or undefined if watchId was already unknown -- idempotent, like the rest of Vehicle's own unregister-shaped operations. Returns the registration itself (not just a boolean) so a caller can tell which scope lost its last watch without a separate lookup. */
+    remove(watchId: string): WatchRegistration | undefined;
+    /** False once a scope has zero remaining registrations -- a provider's own signal to release whatever underlying watch/subscription resource that scope was backing. */
+    hasAnyFor(scope: string): boolean;
+    registrationsFor(scope: string): readonly WatchRegistration[];
+}
+/**
+ * The wire topic name a watch's changes publish under -- one shared naming
+ * function so a provider's publish() call and a subscriber's connectPushChannel()
+ * topic can never drift apart, the same role vehicleEventTopic() plays for
+ * Vehicle Events' own declared, fixed-schema event types. Deliberately a
+ * separate function/namespace from vehicleEventTopic(): a watch's topic is
+ * per-watch-instance-dynamic (one new topic per watchId), not a small fixed
+ * set of declared event types, so it doesn't fit Vehicle Events' own
+ * name@version schema-declaration model -- it reuses the same PushChannel
+ * transport substrate Vehicle Events made available generically, not the
+ * declared-event-type layer itself.
+ */
+export declare function vehicleWatchTopic(watchId: string): string;

package/dist/vehicle-watchers.js

@@ -0,0 +1,85 @@
+/**
+ * "Watch a changing resource, get notified" -- lifted near-verbatim from
+ * Lector's own `WatchRegistry` (packages/lector/src/domain/watch-registry.ts),
+ * generalized past Lector's own workspace/pattern vocabulary (`workspaceId`
+ * -> `scope`, `pattern` -> `resource`) into a shared Vehicle primitive.
+ * Confirmed independently reinvented three-plus times across this house's
+ * own ecosystem before this existed: Lector's own registry, Lector's CLI
+ * (a second, non-resilient reimplementation of the same watch/subscribe
+ * shape), and Papyrus's TaskOverlay/NoteOverlay (each hand-rolling the same
+ * ensurePushChannel()+poll dance independently).
+ *
+ * Pure, in-memory bookkeeping only -- no filesystem, network, or PushChannel
+ * I/O here. Matching pattern/resource against a real changed resource is a
+ * provider's own job, not this registry's; this only tracks which topic a
+ * given (scope, resource) pair publishes under, and bounds how many watches
+ * one scope can accumulate.
+ */
+/** Matches WatchRegistry's own historical default (Lector's MAX_WATCHES_PER_WORKSPACE). */
+export const DEFAULT_MAX_WATCHES_PER_SCOPE = 32;
+/** Raised when a scope already has its configured maximum of registrations -- fails closed, the same bounded-resource discipline every other Vehicle capability already applies, rather than letting one scope accumulate unbounded watch state. */
+export class WatchLimitExceeded extends Error {
+    scope;
+    max;
+    constructor(scope, max) {
+        super(`scope "${scope}" already has ${max} active watches -- unwatch one before adding another`);
+        this.scope = scope;
+        this.max = max;
+        this.name = "WatchLimitExceeded";
+    }
+}
+export class WatchRegistry {
+    byId = new Map();
+    byScope = new Map();
+    maxWatchesPerScope;
+    constructor(options = {}) {
+        this.maxWatchesPerScope = options.maxWatchesPerScope ?? DEFAULT_MAX_WATCHES_PER_SCOPE;
+    }
+    add(scope, resource, watchId, topic) {
+        const existing = this.byScope.get(scope) ?? new Set();
+        if (existing.size >= this.maxWatchesPerScope)
+            throw new WatchLimitExceeded(scope, this.maxWatchesPerScope);
+        const registration = { watchId, scope, resource, topic };
+        existing.add(watchId);
+        this.byScope.set(scope, existing);
+        this.byId.set(watchId, registration);
+        return registration;
+    }
+    /** The removed registration, or undefined if watchId was already unknown -- idempotent, like the rest of Vehicle's own unregister-shaped operations. Returns the registration itself (not just a boolean) so a caller can tell which scope lost its last watch without a separate lookup. */
+    remove(watchId) {
+        const registration = this.byId.get(watchId);
+        if (!registration)
+            return undefined;
+        this.byId.delete(watchId);
+        const scopeWatches = this.byScope.get(registration.scope);
+        scopeWatches?.delete(watchId);
+        if (scopeWatches?.size === 0)
+            this.byScope.delete(registration.scope);
+        return registration;
+    }
+    /** False once a scope has zero remaining registrations -- a provider's own signal to release whatever underlying watch/subscription resource that scope was backing. */
+    hasAnyFor(scope) {
+        return (this.byScope.get(scope)?.size ?? 0) > 0;
+    }
+    registrationsFor(scope) {
+        const ids = this.byScope.get(scope);
+        if (!ids)
+            return [];
+        return Array.from(ids, (id) => this.byId.get(id)).filter((registration) => registration !== undefined);
+    }
+}
+/**
+ * The wire topic name a watch's changes publish under -- one shared naming
+ * function so a provider's publish() call and a subscriber's connectPushChannel()
+ * topic can never drift apart, the same role vehicleEventTopic() plays for
+ * Vehicle Events' own declared, fixed-schema event types. Deliberately a
+ * separate function/namespace from vehicleEventTopic(): a watch's topic is
+ * per-watch-instance-dynamic (one new topic per watchId), not a small fixed
+ * set of declared event types, so it doesn't fit Vehicle Events' own
+ * name@version schema-declaration model -- it reuses the same PushChannel
+ * transport substrate Vehicle Events made available generically, not the
+ * declared-event-type layer itself.
+ */
+export function vehicleWatchTopic(watchId) {
+    return `vehicle-watch:${watchId}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@danypops/vehicle-core",
-	"version": "0.7.0",
+	"version": "0.9.0",
 	"description": "Vehicle's runtime-neutral wire contract: operation descriptors, schema codecs, failure shapes. Zero runtime dependencies, zero Bun-specific code -- the one thing every Vehicle client and server package depends on.",
 	"license": "MIT",
 	"type": "module",

package/src/index.ts

@@ -1,4 +1,6 @@
 export * from "./atomic-json.js";
+export * from "./vehicle-approvals.js";
 export * from "./vehicle-contract.js";
 export * from "./vehicle-errors.js";
 export * from "./vehicle-jobs.js";
+export * from "./vehicle-watchers.js";

package/src/vehicle-approvals.ts

@@ -0,0 +1,130 @@
+/**
+ * Wire-level shapes for the Approval Gate: a pending human/authority decision
+ * that stands between a gated-effect invoke() and its handler actually
+ * running. Kept in vehicle-core (runtime-neutral, zero dependencies) --
+ * the actual signing/verification authority (HmacApprovalAuthority) needs
+ * node:crypto and lives in vehicle-server instead, the same split
+ * atomic-json.ts already uses for fs access.
+ */
+import type { VehicleEffect, VehiclePrincipal } from "./vehicle-contract.js";
+import { defineVehicleEvent, defineVehicleSchema } from "./vehicle-contract.js";
+
+/** Set once at registry-configuration time (VehicleRegistry.configureApprovals()); never on a per-invoke basis. */
+export const DEFAULT_APPROVAL_EFFECTS: readonly VehicleEffect[] = ["destructive", "open-world"];
+
+/** How long a request stays resolvable before it lapses and must be re-requested. */
+export const DEFAULT_APPROVAL_TIMEOUT_MS = 5 * 60_000;
+
+/** Emitted (as a Vehicle Event) the moment a gated-effect invoke() has no valid capability -- durable-first, before any interactive prompt is attempted. */
+export interface VehicleApprovalRequest {
+	readonly requestId: string;
+	readonly operationName: string;
+	readonly operationVersion: number;
+	readonly effect: VehicleEffect;
+	readonly principal?: VehiclePrincipal;
+	readonly requestedAt: number;
+	readonly expiresAt: number;
+	/** sha256 hex of the exact input the gated invoke() attempted -- a minted capability is scoped to this input, not just the operation. */
+	readonly inputHash: string;
+}
+
+export type VehicleApprovalDecision = "granted" | "denied";
+
+/** Emitted once vehicle.approval.resolve settles a request, whichever way. */
+export interface VehicleApprovalOutcome {
+	readonly requestId: string;
+	readonly decision: VehicleApprovalDecision;
+	readonly decidedAt: number;
+	readonly decidedBy?: string;
+}
+
+/**
+ * The real authority behind an approvalCapability -- replaces today's
+ * "any non-empty string satisfies it" rubber stamp. mint() is called only
+ * from inside vehicle.approval.resolve once a decision is actually made;
+ * verify() is called from invoke() itself against whatever capability the
+ * caller presents. A capability is scoped to the exact operation+input it
+ * was minted for and expires with its originating request -- presenting a
+ * capability minted for a different operation, a different input, or one
+ * already consumed (single-use) must fail verify().
+ */
+export interface VehicleApprovalAuthority {
+	mint(request: Pick<VehicleApprovalRequest, "requestId" | "operationName" | "operationVersion" | "expiresAt" | "inputHash">): string;
+	verify(capability: string, operationName: string, operationVersion: number, inputHash: string): boolean;
+}
+
+const requestedPayloadSchema = defineVehicleSchema<VehicleApprovalRequest>({
+	jsonSchema: {
+		type: "object",
+		properties: {
+			requestId: { type: "string" },
+			operationName: { type: "string" },
+			operationVersion: { type: "number" },
+			effect: { type: "string" },
+			requestedAt: { type: "number" },
+			expiresAt: { type: "number" },
+			inputHash: { type: "string" },
+		},
+		required: ["requestId", "operationName", "operationVersion", "effect", "requestedAt", "expiresAt", "inputHash"],
+		additionalProperties: true,
+	},
+	safeParse(value) {
+		if (typeof value !== "object" || value === null) return { success: false, issues: [{ path: [], message: "input must be an object" }] };
+		const row = value as Record<string, unknown>;
+		if (
+			typeof row.requestId !== "string" ||
+			typeof row.operationName !== "string" ||
+			typeof row.operationVersion !== "number" ||
+			typeof row.effect !== "string" ||
+			typeof row.requestedAt !== "number" ||
+			typeof row.expiresAt !== "number" ||
+			typeof row.inputHash !== "string"
+		) {
+			return { success: false, issues: [{ path: [], message: "invalid approval request payload" }] };
+		}
+		return { success: true, value: row as unknown as VehicleApprovalRequest };
+	},
+});
+
+const resolvedPayloadSchema = defineVehicleSchema<VehicleApprovalOutcome>({
+	jsonSchema: {
+		type: "object",
+		properties: {
+			requestId: { type: "string" },
+			decision: { type: "string", enum: ["granted", "denied"] },
+			decidedAt: { type: "number" },
+			decidedBy: { type: "string" },
+		},
+		required: ["requestId", "decision", "decidedAt"],
+		additionalProperties: true,
+	},
+	safeParse(value) {
+		if (typeof value !== "object" || value === null) return { success: false, issues: [{ path: [], message: "input must be an object" }] };
+		const row = value as Record<string, unknown>;
+		if (
+			typeof row.requestId !== "string" ||
+			(row.decision !== "granted" && row.decision !== "denied") ||
+			typeof row.decidedAt !== "number"
+		) {
+			return { success: false, issues: [{ path: [], message: "invalid approval outcome payload" }] };
+		}
+		return { success: true, value: row as unknown as VehicleApprovalOutcome };
+	},
+});
+
+/** Built into every VehicleRegistry once configureApprovals() is called -- never registered unconditionally, so a Vehicle that never opts in has zero manifest/shape change. */
+export const vehicleApprovalRequestedEvent = defineVehicleEvent<VehicleApprovalRequest>({
+	name: "vehicle.approval.requested",
+	version: 1,
+	description: "A gated-effect operation was invoked without a valid approval capability.",
+	payload: requestedPayloadSchema,
+	maxPayloadBytes: 16_384,
+});
+
+export const vehicleApprovalResolvedEvent = defineVehicleEvent<VehicleApprovalOutcome>({
+	name: "vehicle.approval.resolved",
+	version: 1,
+	description: "A pending approval request was granted or denied.",
+	payload: resolvedPayloadSchema,
+	maxPayloadBytes: 4_096,
+});

package/src/vehicle-watchers.ts

@@ -0,0 +1,103 @@
+/**
+ * "Watch a changing resource, get notified" -- lifted near-verbatim from
+ * Lector's own `WatchRegistry` (packages/lector/src/domain/watch-registry.ts),
+ * generalized past Lector's own workspace/pattern vocabulary (`workspaceId`
+ * -> `scope`, `pattern` -> `resource`) into a shared Vehicle primitive.
+ * Confirmed independently reinvented three-plus times across this house's
+ * own ecosystem before this existed: Lector's own registry, Lector's CLI
+ * (a second, non-resilient reimplementation of the same watch/subscribe
+ * shape), and Papyrus's TaskOverlay/NoteOverlay (each hand-rolling the same
+ * ensurePushChannel()+poll dance independently).
+ *
+ * Pure, in-memory bookkeeping only -- no filesystem, network, or PushChannel
+ * I/O here. Matching pattern/resource against a real changed resource is a
+ * provider's own job, not this registry's; this only tracks which topic a
+ * given (scope, resource) pair publishes under, and bounds how many watches
+ * one scope can accumulate.
+ */
+
+/** Matches WatchRegistry's own historical default (Lector's MAX_WATCHES_PER_WORKSPACE). */
+export const DEFAULT_MAX_WATCHES_PER_SCOPE = 32;
+
+export interface WatchRegistration {
+	readonly watchId: string;
+	readonly scope: string;
+	readonly resource: string;
+	readonly topic: string;
+}
+
+/** Raised when a scope already has its configured maximum of registrations -- fails closed, the same bounded-resource discipline every other Vehicle capability already applies, rather than letting one scope accumulate unbounded watch state. */
+export class WatchLimitExceeded extends Error {
+	constructor(
+		readonly scope: string,
+		readonly max: number,
+	) {
+		super(`scope "${scope}" already has ${max} active watches -- unwatch one before adding another`);
+		this.name = "WatchLimitExceeded";
+	}
+}
+
+export interface WatchRegistryOptions {
+	/** Defaults to DEFAULT_MAX_WATCHES_PER_SCOPE. */
+	readonly maxWatchesPerScope?: number;
+}
+
+export class WatchRegistry {
+	private readonly byId = new Map<string, WatchRegistration>();
+	private readonly byScope = new Map<string, Set<string>>();
+	private readonly maxWatchesPerScope: number;
+
+	constructor(options: WatchRegistryOptions = {}) {
+		this.maxWatchesPerScope = options.maxWatchesPerScope ?? DEFAULT_MAX_WATCHES_PER_SCOPE;
+	}
+
+	add(scope: string, resource: string, watchId: string, topic: string): WatchRegistration {
+		const existing = this.byScope.get(scope) ?? new Set();
+		if (existing.size >= this.maxWatchesPerScope) throw new WatchLimitExceeded(scope, this.maxWatchesPerScope);
+		const registration: WatchRegistration = { watchId, scope, resource, topic };
+		existing.add(watchId);
+		this.byScope.set(scope, existing);
+		this.byId.set(watchId, registration);
+		return registration;
+	}
+
+	/** The removed registration, or undefined if watchId was already unknown -- idempotent, like the rest of Vehicle's own unregister-shaped operations. Returns the registration itself (not just a boolean) so a caller can tell which scope lost its last watch without a separate lookup. */
+	remove(watchId: string): WatchRegistration | undefined {
+		const registration = this.byId.get(watchId);
+		if (!registration) return undefined;
+		this.byId.delete(watchId);
+		const scopeWatches = this.byScope.get(registration.scope);
+		scopeWatches?.delete(watchId);
+		if (scopeWatches?.size === 0) this.byScope.delete(registration.scope);
+		return registration;
+	}
+
+	/** False once a scope has zero remaining registrations -- a provider's own signal to release whatever underlying watch/subscription resource that scope was backing. */
+	hasAnyFor(scope: string): boolean {
+		return (this.byScope.get(scope)?.size ?? 0) > 0;
+	}
+
+	registrationsFor(scope: string): readonly WatchRegistration[] {
+		const ids = this.byScope.get(scope);
+		if (!ids) return [];
+		return Array.from(ids, (id) => this.byId.get(id)).filter(
+			(registration): registration is WatchRegistration => registration !== undefined,
+		);
+	}
+}
+
+/**
+ * The wire topic name a watch's changes publish under -- one shared naming
+ * function so a provider's publish() call and a subscriber's connectPushChannel()
+ * topic can never drift apart, the same role vehicleEventTopic() plays for
+ * Vehicle Events' own declared, fixed-schema event types. Deliberately a
+ * separate function/namespace from vehicleEventTopic(): a watch's topic is
+ * per-watch-instance-dynamic (one new topic per watchId), not a small fixed
+ * set of declared event types, so it doesn't fit Vehicle Events' own
+ * name@version schema-declaration model -- it reuses the same PushChannel
+ * transport substrate Vehicle Events made available generically, not the
+ * declared-event-type layer itself.
+ */
+export function vehicleWatchTopic(watchId: string): string {
+	return `vehicle-watch:${watchId}`;
+}