@hasna/events 0.1.14 → 0.1.15

package/fixtures/hasna.app_event.v1.json

@@ -0,0 +1,108 @@
+{
+  "event_id": "evt_fixture_todo_completed_01",
+  "event_type": "todos.task.completed",
+  "schema_version": "hasna.app_event.v1",
+  "source": {
+    "app": "open-todos",
+    "version": "0.0.0-fixture",
+    "machine": "fixture.local"
+  },
+  "occurred_at": "2026-07-29T12:00:00.000Z",
+  "severity": "notice",
+  "idempotency": {
+    "dedupe_key": "fixture:interop-project:todo-42:completed:v1",
+    "replay_safe": true
+  },
+  "correlation": {
+    "correlation_id": "corr_fixture_interop_project_01",
+    "causation_id": "evt_fixture_todo_created_01"
+  },
+  "subject": {
+    "kind": "task",
+    "id": "todo_fixture_42",
+    "uri": "hasna://todos/tasks/todo_fixture_42"
+  },
+  "actor": {
+    "kind": "service",
+    "id": "open-todos",
+    "name": "Todos fixture producer"
+  },
+  "project_mappings": {
+    "canonical_id": "project_fixture_interop",
+    "slug": "interop-fixture",
+    "repository": "https://example.invalid/hasna/interop-fixture",
+    "workspace": "workspace_fixture_interop",
+    "external_ids": {
+      "todos": "project_fixture_interop",
+      "conversations": "conversation_fixture_17",
+      "mementos": "memento_fixture_09",
+      "projects": "project_fixture_interop",
+      "codewith": "mailbox_fixture_interop"
+    }
+  },
+  "summary": "Interop fixture task completed successfully.",
+  "data": {
+    "task_status": "completed",
+    "task_title": "Verify app-event interoperability",
+    "conversation_id": "conversation_fixture_17",
+    "memento_id": "memento_fixture_09",
+    "mailbox_topic": "project.activity",
+    "render_hint": {
+      "component": "StatusBadge",
+      "tone": "success"
+    }
+  },
+  "resource_refs": [
+    {
+      "kind": "task",
+      "id": "todo_fixture_42",
+      "uri": "hasna://todos/tasks/todo_fixture_42",
+      "source_package": "@hasna/todos",
+      "external_id": "todo_fixture_42"
+    },
+    {
+      "kind": "conversation",
+      "id": "conversation_fixture_17",
+      "uri": "hasna://conversations/conversation_fixture_17"
+    },
+    {
+      "kind": "memento",
+      "id": "memento_fixture_09",
+      "uri": "hasna://mementos/memento_fixture_09"
+    },
+    {
+      "kind": "render",
+      "id": "project_fixture_interop_status",
+      "uri": "hasna://projects/project_fixture_interop/render/status"
+    }
+  ],
+  "evidence_refs": [
+    {
+      "kind": "test_result",
+      "id": "evidence_fixture_interop_01",
+      "uri": "artifact://interop-fixture/test-report.json",
+      "redaction": "none"
+    }
+  ],
+  "sensitivity": {
+    "classification": "internal",
+    "contains_personal_data": false
+  },
+  "redaction": {
+    "state": "none",
+    "fields": [],
+    "safe_for_logs": true
+  },
+  "delivery": {
+    "intent": "notification",
+    "mode": "at_least_once",
+    "targets": [
+      "todos",
+      "conversations",
+      "mementos",
+      "projects-json-render",
+      "codewith-mailbox"
+    ],
+    "agent_conversation_injection": false
+  }
+}

package/hasna.contract.json

@@ -0,0 +1,70 @@
+{
+  "schema": "hasna.service_contract.v1",
+  "name": "events",
+  "class": "library",
+  "contractVersion": "v1",
+  "kitVersion": "0.8.5",
+  "description": "Shared event envelopes, local channels, replay, and delivery transports for Hasna open-source apps. Library class: SDK exports are the primary surface and the local `events` CLI is the operator seam. The default compatibility store remains user-owned JSON; opt-in durable delivery uses a Node-safe filesystem spool plus a Bun SQLite outbox under the same caller-selected data directory. The package provisions no remote infrastructure.",
+  "bins": [
+    "events"
+  ],
+  "hosting": [
+    "user-hosted"
+  ],
+  "serviceSurfaces": [
+    {
+      "name": "package-sdk",
+      "kind": "sdk",
+      "status": "supported",
+      "authMode": "none",
+      "exportSubpath": "."
+    },
+    {
+      "name": "durable-spool-sdk",
+      "kind": "sdk",
+      "status": "supported",
+      "authMode": "none",
+      "exportSubpath": "./durable-spool"
+    },
+    {
+      "name": "durable-delivery-sdk",
+      "kind": "sdk",
+      "status": "supported",
+      "authMode": "none",
+      "exportSubpath": "./durable"
+    },
+    {
+      "name": "durable-worker-sdk",
+      "kind": "sdk",
+      "status": "supported",
+      "authMode": "none",
+      "exportSubpath": "./durable-worker"
+    },
+    {
+      "name": "events-cli",
+      "kind": "cli",
+      "status": "supported",
+      "bin": "events",
+      "authMode": "local-only"
+    }
+  ],
+  "metadata": {
+    "release": {
+      "artifactScan": {
+        "script": "artifact-scan"
+      }
+    },
+    "conformance": {
+      "waivedSurfaces": [
+        {
+          "kind": "api",
+          "reason": "Embedded library plus a local CLI; it owns no HTTP service boundary and ships no serve bin."
+        },
+        {
+          "kind": "mcp",
+          "reason": "Embedded library; MCP execution belongs to the applications that consume these envelopes."
+        }
+      ]
+    }
+  }
+}

package/package.json

@@ -1,57 +1,85 @@
 {
   "name": "@hasna/events",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "description": "Shared event envelopes, local channels, replay, and delivery transports for Hasna open-source apps",
   "type": "module",
   "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
+  "types": "./types/index.d.ts",
   "bin": {
     "events": "dist/cli/index.js",
     "hasna-events": "dist/cli/index.js"
   },
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
+      "types": "./types/index.d.ts",
       "import": "./dist/index.js"
     },
     "./storage": {
-      "types": "./dist/storage.d.ts",
+      "types": "./types/storage.d.ts",
       "import": "./dist/storage.js"
     },
+    "./durable": {
+      "types": "./types/durable.d.ts",
+      "import": "./dist/durable.js"
+    },
+    "./durable-spool": {
+      "types": "./types/durable-spool.d.ts",
+      "import": "./dist/durable-spool.js"
+    },
+    "./durable-worker": {
+      "types": "./types/durable-worker.d.ts",
+      "import": "./dist/durable-worker.js"
+    },
     "./signing": {
-      "types": "./dist/signing.d.ts",
+      "types": "./types/signing.d.ts",
       "import": "./dist/signing.js"
     },
     "./filter": {
-      "types": "./dist/filter.d.ts",
+      "types": "./types/filter.d.ts",
       "import": "./dist/filter.js"
     },
     "./transports": {
-      "types": "./dist/transports.d.ts",
+      "types": "./types/transports.d.ts",
       "import": "./dist/transports.js"
     },
     "./catalog": {
-      "types": "./dist/catalog.d.ts",
+      "types": "./types/catalog.d.ts",
       "import": "./dist/catalog.js"
     },
+    "./app-event": {
+      "types": "./types/app-event.d.ts",
+      "import": "./dist/app-event.js"
+    },
+    "./schemas/hasna.app_event.v1.json": "./schemas/hasna.app_event.v1.json",
+    "./fixtures/hasna.app_event.v1.json": "./fixtures/hasna.app_event.v1.json",
     "./commander": {
-      "types": "./dist/commander.d.ts",
+      "types": "./types/commander.d.ts",
       "import": "./dist/commander.js"
     },
     "./cli": {
-      "types": "./dist/cli/index.d.ts",
+      "types": "./types/cli/index.d.ts",
       "import": "./dist/cli/index.js"
     }
   },
   "files": [
     "dist",
+    "types",
+    "schemas",
+    "fixtures",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "hasna.contract.json"
   ],
   "scripts": {
-    "build": "rm -rf dist && bun build src/cli/index.ts --outdir dist/cli --target bun && bun build src/index.ts src/storage.ts src/signing.ts src/filter.ts src/transports.ts src/types.ts src/commander.ts src/catalog.ts --outdir dist --target bun && tsc -p tsconfig.build.json --emitDeclarationOnly --outDir dist",
+    "build": "bun run build:runtime && bun run build:types",
+    "build:runtime": "rm -rf dist && bun build src/cli/index.ts --outdir dist/cli --target bun && bun build src/index.ts src/storage.ts src/signing.ts src/filter.ts src/transports.ts src/types.ts src/commander.ts src/catalog.ts src/app-event.ts src/durable.ts src/durable-worker.ts --root src --outdir dist --target bun && bun build src/durable-spool.ts --root src --outdir dist --target node",
+    "build:types": "rm -rf types && tsc -p tsconfig.build.json --emitDeclarationOnly --outDir types",
+    "generated-artifacts:check": "bun run build && test -z \"$(git status --porcelain --untracked-files=all -- dist types)\"",
+    "contract:check": "contracts repo-conformance .",
+    "artifact-scan": "bun scripts/artifact-scan.ts",
     "typecheck": "tsc --noEmit",
     "test": "bun test",
+    "prepack": "bun run build && bun run artifact-scan",
     "prepublishOnly": "bun run test && bun run build"
   },
   "keywords": [
@@ -75,7 +103,8 @@
     "url": "https://github.com/hasna/events/issues"
   },
   "engines": {
-    "bun": ">=1.0.0"
+    "bun": ">=1.0.0",
+    "node": ">=20.0.0"
   },
   "author": "Hasna",
   "license": "Apache-2.0",
@@ -83,6 +112,7 @@
     "commander": "^13.1.0"
   },
   "devDependencies": {
+    "@hasna/contracts": "0.8.5",
     "@types/bun": "latest",
     "typescript": "^5.7.3"
   }

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/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>;