@hasna/events 0.1.13 → 0.1.15

package/schemas/hasna.app_event.v1.json

@@ -0,0 +1,186 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.hasna.com/hasna.app_event.v1.json",
+  "title": "hasna.app_event.v1",
+  "description": "Versioned cross-app event profile carried by @hasna/events.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "event_id",
+    "event_type",
+    "schema_version",
+    "source",
+    "occurred_at",
+    "severity",
+    "idempotency",
+    "correlation",
+    "subject",
+    "actor",
+    "project_mappings",
+    "summary",
+    "data",
+    "resource_refs",
+    "evidence_refs",
+    "sensitivity",
+    "redaction",
+    "delivery"
+  ],
+  "properties": {
+    "event_id": { "type": "string", "minLength": 1, "maxLength": 200 },
+    "event_type": { "type": "string", "minLength": 1, "maxLength": 200 },
+    "schema_version": { "const": "hasna.app_event.v1" },
+    "source": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["app", "version", "machine"],
+      "properties": {
+        "app": { "type": "string", "minLength": 1, "maxLength": 200 },
+        "version": { "type": "string", "minLength": 1, "maxLength": 100 },
+        "machine": { "type": "string", "minLength": 1, "maxLength": 200 }
+      }
+    },
+    "occurred_at": { "type": "string", "format": "date-time" },
+    "severity": { "enum": ["debug", "info", "notice", "warning", "error", "critical"] },
+    "idempotency": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["dedupe_key", "replay_safe"],
+      "properties": {
+        "dedupe_key": { "type": "string", "minLength": 1, "maxLength": 512 },
+        "replay_safe": { "type": "boolean" },
+        "replay_of_event_id": { "type": "string", "minLength": 1, "maxLength": 200 }
+      }
+    },
+    "correlation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["correlation_id"],
+      "properties": {
+        "correlation_id": { "type": "string", "minLength": 1, "maxLength": 200 },
+        "causation_id": { "type": "string", "minLength": 1, "maxLength": 200 },
+        "trace_id": { "type": "string", "minLength": 1, "maxLength": 200 }
+      }
+    },
+    "subject": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "id"],
+      "properties": {
+        "kind": { "type": "string", "minLength": 1, "maxLength": 100 },
+        "id": { "type": "string", "minLength": 1, "maxLength": 200 },
+        "uri": { "type": "string", "minLength": 1, "maxLength": 2048, "format": "uri-reference" }
+      }
+    },
+    "actor": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "id"],
+      "properties": {
+        "kind": { "enum": ["agent", "human", "service", "model", "workflow", "system"] },
+        "id": { "type": "string", "minLength": 1, "maxLength": 200 },
+        "name": { "type": "string", "minLength": 1, "maxLength": 200 }
+      }
+    },
+    "project_mappings": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["canonical_id", "external_ids"],
+      "properties": {
+        "canonical_id": { "type": "string", "minLength": 1, "maxLength": 200 },
+        "slug": { "type": "string", "minLength": 1, "maxLength": 200 },
+        "repository": { "type": "string", "minLength": 1, "maxLength": 2048, "format": "uri-reference" },
+        "workspace": { "type": "string", "minLength": 1, "maxLength": 2048 },
+        "external_ids": {
+          "type": "object",
+          "maxProperties": 16,
+          "propertyNames": { "minLength": 1 },
+          "additionalProperties": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "summary": { "type": "string", "minLength": 1, "maxLength": 512 },
+    "data": {
+      "type": "object",
+      "description": "Bounded to 32768 serialized UTF-8 bytes by the runtime validator.",
+      "x-max-utf8-bytes": 32768
+    },
+    "resource_refs": {
+      "type": "array",
+      "maxItems": 32,
+      "items": { "$ref": "#/$defs/resource_ref" }
+    },
+    "evidence_refs": {
+      "type": "array",
+      "maxItems": 32,
+      "items": { "$ref": "#/$defs/evidence_ref" }
+    },
+    "sensitivity": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["classification", "contains_personal_data"],
+      "properties": {
+        "classification": { "enum": ["public", "internal", "confidential", "restricted"] },
+        "contains_personal_data": { "type": "boolean" }
+      }
+    },
+    "redaction": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["state", "fields", "safe_for_logs"],
+      "properties": {
+        "state": { "enum": ["none", "partial", "full"] },
+        "fields": {
+          "type": "array",
+          "maxItems": 32,
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "safe_for_logs": { "type": "boolean" }
+      }
+    },
+    "delivery": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["intent", "mode", "targets", "agent_conversation_injection"],
+      "properties": {
+        "intent": { "enum": ["notification", "state_sync", "audit", "command"] },
+        "mode": { "enum": ["at_most_once", "at_least_once"] },
+        "targets": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 16,
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "agent_conversation_injection": {
+          "const": false,
+          "description": "Event text is untrusted data and must not be injected into agent conversations."
+        }
+      }
+    }
+  },
+  "$defs": {
+    "resource_ref": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "id"],
+      "properties": {
+        "kind": { "type": "string", "minLength": 1, "maxLength": 100 },
+        "id": { "type": "string", "minLength": 1, "maxLength": 200 },
+        "uri": { "type": "string", "minLength": 1, "maxLength": 2048, "format": "uri-reference" },
+        "source_package": { "type": "string", "minLength": 1, "maxLength": 200 },
+        "external_id": { "type": "string", "minLength": 1, "maxLength": 200 }
+      }
+    },
+    "evidence_ref": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "id", "uri", "redaction"],
+      "properties": {
+        "kind": { "type": "string", "minLength": 1, "maxLength": 100 },
+        "id": { "type": "string", "minLength": 1, "maxLength": 200 },
+        "uri": { "type": "string", "minLength": 1, "maxLength": 2048, "format": "uri-reference" },
+        "sha256": { "type": "string", "pattern": "^[a-fA-F0-9]{64}$" },
+        "redaction": { "enum": ["none", "partial", "full"] }
+      }
+    }
+  }
+}

package/types/app-event.d.ts

@@ -0,0 +1,130 @@
+import type { EventData, EventEnvelope, EventInput, EventSeverity } from "./types.js";
+/** Stable wire-profile identifier for cross-app events. */
+export declare const APP_EVENT_V1_SCHEMA_VERSION: "hasna.app_event.v1";
+export declare const APP_EVENT_V1_METADATA_KEY: "app_event";
+export declare const APP_EVENT_V1_MAX_SUMMARY_LENGTH = 512;
+export declare const APP_EVENT_V1_MAX_DATA_BYTES: number;
+export declare const APP_EVENT_V1_MAX_REFS = 32;
+export declare const APP_EVENT_V1_MAX_TARGETS = 16;
+export type AppEventActorKind = "agent" | "human" | "service" | "model" | "workflow" | "system";
+export type AppEventSensitivity = "public" | "internal" | "confidential" | "restricted";
+export type AppEventRedactionState = "none" | "partial" | "full";
+export type AppEventDeliveryIntent = "notification" | "state_sync" | "audit" | "command";
+export type AppEventDeliveryMode = "at_most_once" | "at_least_once";
+export interface AppEventSource {
+    app: string;
+    version: string;
+    machine: string;
+}
+export interface AppEventIdempotency {
+    dedupe_key: string;
+    replay_safe: boolean;
+    replay_of_event_id?: string;
+}
+export interface AppEventCorrelation {
+    correlation_id: string;
+    causation_id?: string;
+    trace_id?: string;
+}
+export interface AppEventSubject {
+    kind: string;
+    id: string;
+    uri?: string;
+}
+export interface AppEventActor {
+    kind: AppEventActorKind;
+    id: string;
+    name?: string;
+}
+export interface AppEventProjectMappings {
+    canonical_id: string;
+    slug?: string;
+    repository?: string;
+    workspace?: string;
+    external_ids: Record<string, string>;
+}
+/** Dependency-free structural mirror of a hasna.resource_ref pointer. */
+export interface AppEventResourceRef {
+    kind: string;
+    id: string;
+    uri?: string;
+    source_package?: string;
+    external_id?: string;
+}
+/** Dependency-free structural mirror of a hasna.evidence_ref pointer. */
+export interface AppEventEvidenceRef {
+    kind: string;
+    id: string;
+    uri: string;
+    sha256?: string;
+    redaction: AppEventRedactionState;
+}
+export interface AppEventSensitivityPolicy {
+    classification: AppEventSensitivity;
+    contains_personal_data: boolean;
+}
+export interface AppEventRedaction {
+    state: AppEventRedactionState;
+    fields: string[];
+    safe_for_logs: boolean;
+}
+export interface AppEventDelivery {
+    intent: AppEventDeliveryIntent;
+    mode: AppEventDeliveryMode;
+    targets: string[];
+    /** Untrusted event text is data, never an instruction to an agent. */
+    agent_conversation_injection: false;
+}
+/**
+ * Cross-app wire profile carried by the existing @hasna/events envelope.
+ * Use {@link appEventV1ToEventInput}; this profile does not define another bus.
+ */
+export interface AppEventV1<TData extends EventData = EventData> {
+    event_id: string;
+    event_type: string;
+    schema_version: typeof APP_EVENT_V1_SCHEMA_VERSION;
+    source: AppEventSource;
+    occurred_at: string;
+    severity: EventSeverity;
+    idempotency: AppEventIdempotency;
+    correlation: AppEventCorrelation;
+    subject: AppEventSubject;
+    actor: AppEventActor;
+    project_mappings: AppEventProjectMappings;
+    summary: string;
+    data: TData;
+    resource_refs: AppEventResourceRef[];
+    evidence_refs: AppEventEvidenceRef[];
+    sensitivity: AppEventSensitivityPolicy;
+    redaction: AppEventRedaction;
+    delivery: AppEventDelivery;
+}
+export interface AppEventValidationIssue {
+    path: string;
+    message: string;
+}
+export type AppEventValidationResult = {
+    ok: true;
+} | {
+    ok: false;
+    issues: AppEventValidationIssue[];
+};
+export declare class AppEventValidationError extends Error {
+    readonly issues: AppEventValidationIssue[];
+    constructor(issues: AppEventValidationIssue[]);
+}
+export declare class AppEventReplaySafetyError extends Error {
+    readonly eventId: string;
+    constructor(eventId: string);
+}
+export declare function validateAppEventV1(value: unknown): AppEventValidationResult;
+export declare function assertAppEventV1<TData extends EventData = EventData>(value: unknown): asserts value is AppEventV1<TData>;
+export declare function assertAppEventV1ReplaySafe(event: AppEventV1): void;
+export declare function appEventV1ReplayIdentity(event: AppEventV1): {
+    eventId: string;
+    dedupeKey: string;
+};
+/** Map the profile onto the existing @hasna/events envelope without another transport or store. */
+export declare function appEventV1ToEventInput<TData extends EventData>(event: AppEventV1<TData>): EventInput<TData>;
+/** Reconstruct a profile from an @hasna/events envelope produced by the adapter. */
+export declare function appEventV1FromEventEnvelope<TData extends EventData = EventData>(envelope: EventEnvelope<TData>): AppEventV1<TData>;

package/types/catalog.d.ts

@@ -0,0 +1,136 @@
+import type { EventData, EventEnvelope } from "./types.js";
+export interface EventValidationIssue {
+    path: string;
+    message: string;
+}
+export type EventValidationResult = {
+    ok: true;
+} | {
+    ok: false;
+    issues: EventValidationIssue[];
+};
+export type EventDataValidator = (data: EventData, event: EventEnvelope) => EventValidationResult;
+export interface EventTypeDefinition {
+    /** Envelope `type` string this definition binds, e.g. `release.published`. */
+    type: string;
+    /** `@hasna/contracts` schema id the payload mirrors, e.g. `hasna.release.v1`. */
+    contractSchemaId?: string;
+    description?: string;
+    validate: EventDataValidator;
+}
+export declare class EventValidationError extends Error {
+    readonly eventType: string;
+    readonly issues: EventValidationIssue[];
+    constructor(eventType: string, issues: EventValidationIssue[]);
+}
+export declare class EventTypeCatalog {
+    private definitions;
+    register(definition: EventTypeDefinition): this;
+    unregister(type: string): boolean;
+    has(type: string): boolean;
+    get(type: string): EventTypeDefinition | undefined;
+    list(): EventTypeDefinition[];
+    /**
+     * Validate an event against its registered definition. Events whose type is
+     * NOT registered always pass: free-form types stay untouched.
+     */
+    validateEvent(event: EventEnvelope): EventValidationResult;
+    /** Like {@link validateEvent} but throws {@link EventValidationError}. */
+    assertEventValid(event: EventEnvelope): void;
+}
+/** Shared default catalog used by `EventsClient` when none is provided. */
+export declare const defaultEventTypeCatalog: EventTypeCatalog;
+export declare const DISTRIBUTION_EVENT_TYPES: {
+    readonly releasePublished: "release.published";
+    readonly rolloutStarted: "release.rollout.started";
+    readonly rolloutCompleted: "release.rollout.completed";
+    readonly rolloutFailed: "release.rollout.failed";
+    readonly appInstalled: "app.installed";
+    readonly announcementSent: "announcement.sent";
+    readonly feedbackCreated: "feedback.created";
+    readonly feedbackTriaged: "feedback.triaged";
+};
+export type DistributionEventType = (typeof DISTRIBUTION_EVENT_TYPES)[keyof typeof DISTRIBUTION_EVENT_TYPES];
+/** Contracts schema id each distribution event payload mirrors. */
+export declare const DISTRIBUTION_EVENT_CONTRACT_SCHEMAS: Record<DistributionEventType, string>;
+export type PublishPath = "skill" | "ci" | "backfilled";
+export type RolloutAction = "install" | "update" | "rollback" | "freeze-blocked";
+/** Payload for `release.published`; mirrors `hasna.release.v1` key fields. */
+export type ReleasePublishedData = {
+    appId: string;
+    package: string;
+    version: string;
+    gitSha?: string;
+    publishedAt?: string;
+    publishPath?: PublishPath;
+    changelogRef?: string;
+    [key: string]: unknown;
+};
+/** Payload for `release.rollout.*`; mirrors `hasna.rollout_record.v1` key fields. */
+export type RolloutData = {
+    appId: string;
+    package: string;
+    version: string;
+    machine: string;
+    action?: RolloutAction;
+    result?: string;
+    error?: string;
+    [key: string]: unknown;
+};
+/** Payload for `app.installed`; mirrors `hasna.rollout_record.v1` (action install). */
+export type AppInstalledData = {
+    appId: string;
+    package: string;
+    version: string;
+    machine: string;
+    [key: string]: unknown;
+};
+/** Payload for `announcement.sent`; mirrors `hasna.announcement.v1` key fields. */
+export type AnnouncementSentData = {
+    campaignId: string;
+    appId?: string;
+    audienceId?: string;
+    releaseId?: string;
+    channels?: string[];
+    [key: string]: unknown;
+};
+/** Payload for `feedback.created`. */
+export type FeedbackCreatedData = {
+    feedbackId: string;
+    appId?: string;
+    source?: string;
+    summary?: string;
+    severity?: string;
+    [key: string]: unknown;
+};
+/** Payload for `feedback.triaged`. */
+export type FeedbackTriagedData = {
+    feedbackId: string;
+    disposition: string;
+    appId?: string;
+    triagedBy?: string;
+    [key: string]: unknown;
+};
+export type DistributionEventDataMap = {
+    "release.published": ReleasePublishedData;
+    "release.rollout.started": RolloutData;
+    "release.rollout.completed": RolloutData;
+    "release.rollout.failed": RolloutData;
+    "app.installed": AppInstalledData;
+    "announcement.sent": AnnouncementSentData;
+    "feedback.created": FeedbackCreatedData;
+    "feedback.triaged": FeedbackTriagedData;
+};
+export declare const validateReleasePublishedData: EventDataValidator;
+export declare const validateRolloutData: EventDataValidator;
+export declare const validateAppInstalledData: EventDataValidator;
+export declare const validateAnnouncementSentData: EventDataValidator;
+export declare const validateFeedbackCreatedData: EventDataValidator;
+export declare const validateFeedbackTriagedData: EventDataValidator;
+/** Fresh definitions for every distribution event type. */
+export declare function createDistributionEventDefinitions(): EventTypeDefinition[];
+/**
+ * Register the distribution event types on a catalog (the shared default
+ * catalog when omitted). Opt-in: nothing is registered until this is called.
+ */
+export declare function registerDistributionEventTypes(catalog?: EventTypeCatalog): EventTypeCatalog;

package/{dist → types}/commander.d.ts

@@ -7,7 +7,21 @@ export interface RegisterEventsCommandsOptions {
     createClient?: () => EventsClient;
     channelsCommandName?: string;
     eventsCommandName?: string;
+    /**
+     * Default row cap applied to `events list` when the caller does not pass an
+     * explicit `--limit`. Guards against dumping the entire event store (a
+     * usability/performance hazard for hosts with large stores). Pass `--limit 0`
+     * to opt out and list every recorded event. Defaults to
+     * {@link DEFAULT_EVENT_LIST_LIMIT}.
+     */
+    defaultEventListLimit?: number;
 }
+/**
+ * Sane default number of most-recent events returned by `events list` when the
+ * host does not configure {@link RegisterEventsCommandsOptions.defaultEventListLimit}
+ * and the user does not pass an explicit `--limit`.
+ */
+export declare const DEFAULT_EVENT_LIST_LIMIT = 100;
 export declare function registerChannelCommands(program: CommanderLike, options: RegisterEventsCommandsOptions): CommanderCommandLike;
 export declare function registerEventCommands(program: CommanderLike, options: RegisterEventsCommandsOptions): CommanderCommandLike;
 export declare function registerEventsCommands(program: CommanderLike, options: RegisterEventsCommandsOptions): void;

package/types/durable-spool.d.ts

@@ -0,0 +1,30 @@
+import type { EventEnvelope, EventInput } from "./types.js";
+export interface DurableEventSpoolOptions {
+    dataDir: string;
+}
+export interface DurableSpoolEnqueueResult<TData extends Record<string, unknown> = Record<string, unknown>> {
+    event: EventEnvelope<TData>;
+    stored: boolean;
+    deduped: boolean;
+}
+export interface DurableSpoolRecoveryOptions {
+    olderThanMs?: number;
+}
+export interface DurableSpoolRecoveryResult {
+    recovered: number;
+    deduped: number;
+    cleaned: number;
+}
+export declare class DurableEventSpool {
+    readonly dataDir: string;
+    readonly inboxDir: string;
+    constructor(options: DurableEventSpoolOptions);
+    enqueue<TData extends Record<string, unknown>>(input: EventInput<TData>): Promise<DurableSpoolEnqueueResult<TData>>;
+    recover(options?: DurableSpoolRecoveryOptions): Promise<DurableSpoolRecoveryResult>;
+    close(): Promise<void>;
+    private pathFor;
+    private assertSameIdentity;
+    private ensureInbox;
+    private syncInbox;
+    private syncDirectory;
+}

package/types/durable-worker.d.ts

@@ -0,0 +1,27 @@
+import { DurableEventsBroker, type DurableDrainResult, type DurableSpoolImportResult } from "./durable.js";
+export interface DurableWorkerOptions {
+    broker: DurableEventsBroker;
+    signal: AbortSignal;
+    workerId?: string;
+    limit?: number;
+    leaseMs?: number;
+    debounceMs?: number;
+    reconcileMs?: number;
+    watchRestartMs?: number;
+    onCycle?: (cycle: DurableWorkerCycle) => void | Promise<void>;
+}
+export interface DurableWorkerCycle {
+    imported: DurableSpoolImportResult;
+    drained: DurableDrainResult;
+}
+export interface DurableWorkerResult {
+    workerId: string;
+    cycles: number;
+    imported: number;
+    deduped: number;
+    delivered: number;
+    retried: number;
+    dead: number;
+    lost: number;
+}
+export declare function runDurableWorker(options: DurableWorkerOptions): Promise<DurableWorkerResult>;

package/types/durable.d.ts

@@ -0,0 +1,112 @@
+import { type TransportDispatchOptions } from "./transports.js";
+import type { ChannelConfig, DeliveryResult, EventEnvelope, EventInput } from "./types.js";
+export interface DurableEventsBrokerOptions extends TransportDispatchOptions {
+    dataDir: string;
+    databaseName?: string;
+    now?: () => Date;
+}
+export interface DurableEnqueueOptions {
+    dedupe?: boolean;
+}
+export interface DurableEnqueueResult<TData extends Record<string, unknown> = Record<string, unknown>> {
+    event: EventEnvelope<TData>;
+    deduped: boolean;
+    queued: number;
+}
+export interface DurableDrainOptions {
+    workerId?: string;
+    limit?: number;
+    leaseMs?: number;
+}
+export interface DurableDrainResult {
+    workerId: string;
+    claimed: number;
+    delivered: number;
+    retried: number;
+    dead: number;
+    lost: number;
+    deliveries: DeliveryResult[];
+}
+export interface DurableSpoolImportOptions {
+    limit?: number;
+}
+export interface DurableSpoolImportResult {
+    scanned: number;
+    imported: number;
+    deduped: number;
+    queued: number;
+}
+export interface DurableRetryDeadOptions {
+    eventId?: string;
+    channelId?: string;
+    limit?: number;
+}
+export interface DurableRetryDeadResult {
+    matched: number;
+    requeued: number;
+}
+export type DurableOutboxStatus = "pending" | "leased" | "delivered" | "dead";
+export interface DurableEventsStatus {
+    service: "events";
+    storage: "local-sqlite";
+    schemaVersion: number;
+    databasePath: string;
+    counts: {
+        channels: number;
+        enabledChannels: number;
+        events: number;
+        pending: number;
+        leased: number;
+        delivered: number;
+        dead: number;
+    };
+    safety: {
+        statusOmitsEventPayloads: true;
+        databasePersistsEventEnvelopes: true;
+        includesResolvedSecrets: false;
+        inlineWebhookSecretsAllowed: false;
+    };
+}
+export interface DurableDeliveryJob {
+    id: string;
+    event: EventEnvelope;
+    channel: ChannelConfig;
+    attempt: number;
+    workerId: string;
+}
+export interface DurableSettleResult {
+    status: "delivered" | "retry" | "dead" | "lost";
+    delivery?: DeliveryResult;
+}
+export declare function defaultWebhookSecretResolver(reference: string): string | undefined;
+export declare class DurableEventsBroker {
+    readonly dataDir: string;
+    readonly databasePath: string;
+    private readonly db;
+    private readonly now;
+    private readonly transportOptions;
+    constructor(options: DurableEventsBrokerOptions);
+    close(): void;
+    addChannel(input: Omit<ChannelConfig, "createdAt" | "updatedAt"> & Partial<Pick<ChannelConfig, "createdAt" | "updatedAt">>): ChannelConfig;
+    listChannels(): ChannelConfig[];
+    enqueue<TData extends Record<string, unknown>>(input: EventInput<TData>, options?: DurableEnqueueOptions): DurableEnqueueResult<TData>;
+    drain(options?: DurableDrainOptions): Promise<DurableDrainResult>;
+    importSpool(options?: DurableSpoolImportOptions): DurableSpoolImportResult;
+    retryDead(options?: DurableRetryDeadOptions): DurableRetryDeadResult;
+    status(): DurableEventsStatus;
+    nextWakeAt(): number | undefined;
+    private claim;
+    private settle;
+    private completeOutbox;
+    private findEvent;
+    private queueMatchingChannels;
+    private count;
+    private immediate;
+    private ensureSchema;
+    private createSchemaV1;
+    private assertSchemaV1;
+    private readSchemaVersion;
+    private applicationSchemaObjects;
+    private assertEmptyApplicationSchema;
+    private secureDatabaseFiles;
+}