@danypops/vehicle-core 0.6.0 → 0.7.0

package/dist/atomic-json.d.ts

@@ -29,6 +29,8 @@ export interface AtomicJsonWriteOptions {
     readonly mode?: number;
     /** Pretty-prints with 2-space indentation (matching JSON.stringify(value, null, 2)) for a human-editable file. Defaults to false (compact). */
     readonly pretty?: boolean;
+    /** Appends a trailing "\n" -- the common POSIX text-file convention. Defaults to false (exact JSON.stringify output, unchanged). */
+    readonly trailingNewline?: boolean;
 }
 export interface AtomicJsonWriterOptions {
     readonly fs: AtomicJsonFsAdapter;

package/dist/atomic-json.js

@@ -71,6 +71,8 @@ export function createAtomicJsonWriter(options) {
             }
             if (serialized === undefined)
                 throw new Error(`atomic-json: value for ${filePath} is not JSON-serializable`);
+            if (options?.trailingNewline)
+                serialized += "\n";
             const { dir, base } = dirAndBase(filePath);
             const tempPath = `${dir}/.${base}.${pid()}.${now()}.${random()}.tmp`;
             await fsAdapter.writeFile(tempPath, serialized, options?.mode);

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/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@danypops/vehicle-core",
-	"version": "0.6.0",
+	"version": "0.7.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/atomic-json.ts

@@ -31,6 +31,8 @@ export interface AtomicJsonWriteOptions {
 	readonly mode?: number;
 	/** Pretty-prints with 2-space indentation (matching JSON.stringify(value, null, 2)) for a human-editable file. Defaults to false (compact). */
 	readonly pretty?: boolean;
+	/** Appends a trailing "\n" -- the common POSIX text-file convention. Defaults to false (exact JSON.stringify output, unchanged). */
+	readonly trailingNewline?: boolean;
 }
 
 export interface AtomicJsonWriterOptions {
@@ -118,6 +120,7 @@ export function createAtomicJsonWriter(options: AtomicJsonWriterOptions): Atomic
 				throw new Error(`atomic-json: value for ${filePath} is not JSON-serializable`, { cause: error });
 			}
 			if (serialized === undefined) throw new Error(`atomic-json: value for ${filePath} is not JSON-serializable`);
+			if (options?.trailingNewline) serialized += "\n";
 			const { dir, base } = dirAndBase(filePath);
 			const tempPath = `${dir}/.${base}.${pid()}.${now()}.${random()}.tmp`;
 			await fsAdapter.writeFile(tempPath, serialized, options?.mode);

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 {