@danypops/vehicle-core 0.6.1 → 0.8.0

package/dist/index.d.ts

@@ -2,3 +2,4 @@ export * from "./atomic-json.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

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

package/dist/vehicle-contract.d.ts

@@ -182,8 +182,59 @@ export interface VehicleManifestOperation extends VehicleOperationDescriptor {
     readonly available: boolean;
     readonly unavailableReason?: string;
 }
+/**
+ * A named, schema'd event type a provider declares as part of its
+ * manifest -- the typed alternative to a raw PushChannel.publish(topic,
+ * payload) call with a hand-invented topic string. Confirmed independently
+ * reinvented three-plus times across Papyrus and Lector before this
+ * existed (see this task's own body). No `available` flag the way an
+ * operation has one: an event type, once declared, is always emittable --
+ * there's no credential-gated "this event is currently unavailable"
+ * concept the way a live external-service-backed operation can have.
+ */
+export interface VehicleEventDescriptor {
+    readonly name: string;
+    readonly version: number;
+    readonly description: string;
+    readonly payloadSchema: JsonSchema;
+    /** Same bounded-resource discipline as an operation's own maxRequestBytes/maxResponseBytes -- required, never silently defaulted. */
+    readonly maxPayloadBytes: number;
+}
+export interface VehicleEvent<Payload> {
+    readonly descriptor: VehicleEventDescriptor;
+    readonly payload: VehicleSchemaCodec<Payload>;
+}
+export interface DefineVehicleEventOptions<Payload> {
+    readonly name: string;
+    readonly version: number;
+    readonly description: string;
+    readonly payload: VehicleSchemaCodec<Payload>;
+    readonly maxPayloadBytes: number;
+}
+export declare function defineVehicleEvent<Payload>(options: DefineVehicleEventOptions<Payload>): VehicleEvent<Payload>;
+export type VehicleManifestEvent = VehicleEventDescriptor;
+export type VehicleEventHandler<Payload> = (payload: Payload) => void;
+export interface VehicleSubscription {
+    close(): void;
+}
+/**
+ * The wire topic name a bridge (bridgeVehicleEventsToPushChannel, in
+ * vehicle-server) publishes an event under, and a subscriber
+ * (RemoteVehicleClient.subscribe()) subscribes to -- one shared naming
+ * function in vehicle-core so both sides can never drift apart on the
+ * convention, the same failure mode this primitive exists to prevent
+ * providers from reinventing per-project.
+ */
+export declare function vehicleEventTopic(name: string, version: number): string;
+/**
+ * `events` is optional purely for backward compatibility with every
+ * hand-authored VehicleManifest test fixture across the ecosystem that
+ * predates this field -- a real VehicleRegistry.manifest() always
+ * populates it (as [] when no events are declared), never omits it.
+ */
 export interface VehicleManifest extends VehicleManifestIdentity {
     readonly operations: readonly VehicleManifestOperation[];
+    readonly events?: readonly VehicleManifestEvent[];
 }
 export interface VehicleClient {
     manifest(): Promise<VehicleManifest>;

package/dist/vehicle-contract.js

@@ -69,6 +69,40 @@ export function extractVehicleContent(output) {
     }
     return blocks;
 }
+function validateEventMetadata(options) {
+    if (!options.name.trim())
+        throw new Error("Vehicle event name must not be empty");
+    if (!Number.isInteger(options.version) || options.version < 1) {
+        throw new Error("Vehicle event version must be a positive integer");
+    }
+    if (!options.description.trim())
+        throw new Error("Vehicle event description must not be empty");
+    if (!Number.isSafeInteger(options.maxPayloadBytes) || options.maxPayloadBytes < 1) {
+        throw new Error("Vehicle event maxPayloadBytes must be a positive integer");
+    }
+}
+export function defineVehicleEvent(options) {
+    validateEventMetadata(options);
+    const descriptor = Object.freeze({
+        name: options.name,
+        version: options.version,
+        description: options.description,
+        payloadSchema: cloneJson(options.payload.jsonSchema),
+        maxPayloadBytes: options.maxPayloadBytes,
+    });
+    return Object.freeze({ descriptor, payload: options.payload });
+}
+/**
+ * The wire topic name a bridge (bridgeVehicleEventsToPushChannel, in
+ * vehicle-server) publishes an event under, and a subscriber
+ * (RemoteVehicleClient.subscribe()) subscribes to -- one shared naming
+ * function in vehicle-core so both sides can never drift apart on the
+ * convention, the same failure mode this primitive exists to prevent
+ * providers from reinventing per-project.
+ */
+export function vehicleEventTopic(name, version) {
+    return `vehicle-event:${name}@${version}`;
+}
 export function defineVehicleOperation(options) {
     validateOperationMetadata(options);
     const descriptor = Object.freeze({

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.6.1",
+	"version": "0.8.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

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

package/src/vehicle-contract.ts

@@ -246,8 +246,90 @@ export interface VehicleManifestOperation extends VehicleOperationDescriptor {
 	readonly unavailableReason?: string;
 }
 
+/**
+ * A named, schema'd event type a provider declares as part of its
+ * manifest -- the typed alternative to a raw PushChannel.publish(topic,
+ * payload) call with a hand-invented topic string. Confirmed independently
+ * reinvented three-plus times across Papyrus and Lector before this
+ * existed (see this task's own body). No `available` flag the way an
+ * operation has one: an event type, once declared, is always emittable --
+ * there's no credential-gated "this event is currently unavailable"
+ * concept the way a live external-service-backed operation can have.
+ */
+export interface VehicleEventDescriptor {
+	readonly name: string;
+	readonly version: number;
+	readonly description: string;
+	readonly payloadSchema: JsonSchema;
+	/** Same bounded-resource discipline as an operation's own maxRequestBytes/maxResponseBytes -- required, never silently defaulted. */
+	readonly maxPayloadBytes: number;
+}
+
+export interface VehicleEvent<Payload> {
+	readonly descriptor: VehicleEventDescriptor;
+	readonly payload: VehicleSchemaCodec<Payload>;
+}
+
+export interface DefineVehicleEventOptions<Payload> {
+	readonly name: string;
+	readonly version: number;
+	readonly description: string;
+	readonly payload: VehicleSchemaCodec<Payload>;
+	readonly maxPayloadBytes: number;
+}
+
+function validateEventMetadata<Payload>(options: DefineVehicleEventOptions<Payload>): void {
+	if (!options.name.trim()) throw new Error("Vehicle event name must not be empty");
+	if (!Number.isInteger(options.version) || options.version < 1) {
+		throw new Error("Vehicle event version must be a positive integer");
+	}
+	if (!options.description.trim()) throw new Error("Vehicle event description must not be empty");
+	if (!Number.isSafeInteger(options.maxPayloadBytes) || options.maxPayloadBytes < 1) {
+		throw new Error("Vehicle event maxPayloadBytes must be a positive integer");
+	}
+}
+
+export function defineVehicleEvent<Payload>(options: DefineVehicleEventOptions<Payload>): VehicleEvent<Payload> {
+	validateEventMetadata(options);
+	const descriptor: VehicleEventDescriptor = Object.freeze({
+		name: options.name,
+		version: options.version,
+		description: options.description,
+		payloadSchema: cloneJson(options.payload.jsonSchema),
+		maxPayloadBytes: options.maxPayloadBytes,
+	});
+	return Object.freeze({ descriptor, payload: options.payload });
+}
+
+export type VehicleManifestEvent = VehicleEventDescriptor;
+
+export type VehicleEventHandler<Payload> = (payload: Payload) => void;
+
+export interface VehicleSubscription {
+	close(): void;
+}
+
+/**
+ * The wire topic name a bridge (bridgeVehicleEventsToPushChannel, in
+ * vehicle-server) publishes an event under, and a subscriber
+ * (RemoteVehicleClient.subscribe()) subscribes to -- one shared naming
+ * function in vehicle-core so both sides can never drift apart on the
+ * convention, the same failure mode this primitive exists to prevent
+ * providers from reinventing per-project.
+ */
+export function vehicleEventTopic(name: string, version: number): string {
+	return `vehicle-event:${name}@${version}`;
+}
+
+/**
+ * `events` is optional purely for backward compatibility with every
+ * hand-authored VehicleManifest test fixture across the ecosystem that
+ * predates this field -- a real VehicleRegistry.manifest() always
+ * populates it (as [] when no events are declared), never omits it.
+ */
 export interface VehicleManifest extends VehicleManifestIdentity {
 	readonly operations: readonly VehicleManifestOperation[];
+	readonly events?: readonly VehicleManifestEvent[];
 }
 
 export interface VehicleClient {

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}`;
+}