@zhin.js/harness 0.0.0-stage → 0.0.0

package/lib/index.d.ts

@@ -0,0 +1,8 @@
+export * from './contracts.js';
+export * from './authority.js';
+export * from './budget.js';
+export * from './guard.js';
+export * from './journal.js';
+export * from './mailbox.js';
+export * from './harness.js';
+export * from './policies/index.js';

package/lib/index.js

@@ -0,0 +1,8 @@
+export * from './contracts.js';
+export * from './authority.js';
+export * from './budget.js';
+export * from './guard.js';
+export * from './journal.js';
+export * from './mailbox.js';
+export * from './harness.js';
+export * from './policies/index.js';

package/lib/journal.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Engagement journal implementations (ADR 0048 §3.5).
+ *
+ * Depends on `contracts.ts` only. The database store targets a narrow query
+ * interface (`EngagementJournalDatabase`) that `@zhin.js/database` satisfies,
+ * so the host registers `ENGAGEMENT_EVENT_MODEL` and passes its database in.
+ */
+import { type BoardEntry, type BoardReadFilter, type EngagementEvent, type EngagementId, type EngagementJournal, type EngagementSummary, type JournalRecord, type JournalRetention } from './contracts.js';
+export interface JournalOptions {
+    readonly retention?: JournalRetention;
+}
+type AppendInput = Omit<EngagementEvent, 'seq'>;
+/** Reconstructs blackboard entries from a sequence of journal records. */
+export declare function reconstructBoardFromEvents(records: readonly JournalRecord[], filter?: BoardReadFilter): readonly BoardEntry[];
+/** Pure helper that summarizes an engagement's journal records into a collaboration graph and metrics. */
+export declare function summarizeEngagementEvents(engagementId: EngagementId, records: readonly JournalRecord[]): EngagementSummary;
+export declare class InMemoryEngagementJournal implements EngagementJournal {
+    #private;
+    constructor(options?: JournalOptions);
+    append(event: AppendInput): Promise<EngagementEvent>;
+    read(engagementId: EngagementId): Promise<readonly EngagementEvent[]>;
+    prune(now: number): Promise<number>;
+    listEngagements(limit?: number): Promise<readonly EngagementId[]>;
+    summarize(engagementId: EngagementId): Promise<EngagementSummary | undefined>;
+    compact(engagementId: EngagementId): Promise<void>;
+}
+export declare const ENGAGEMENT_EVENTS_TABLE = "engagement_events";
+/**
+ * Table schema. `id` (`<engagement_id>:<seq>`) is the primary key and therefore
+ * the unique (engagement_id, seq) constraint: `@zhin.js/database` column
+ * definitions have no composite unique key.
+ */
+export declare const ENGAGEMENT_EVENT_MODEL: {
+    id: {
+        type: "text";
+        primary: boolean;
+        nullable: boolean;
+    };
+    engagement_id: {
+        type: "text";
+        nullable: boolean;
+    };
+    seq: {
+        type: "integer";
+        nullable: boolean;
+    };
+    at: {
+        type: "bigint";
+        nullable: boolean;
+    };
+    type: {
+        type: "text";
+        nullable: boolean;
+    };
+    data: {
+        type: "text";
+        nullable: boolean;
+    };
+};
+/** Registers the table on a `@zhin.js/database` instance. */
+export declare function defineEngagementEventModel(database: Readonly<{
+    define(name: string, definition: unknown): unknown;
+}>): void;
+/** The slice of `@zhin.js/database`'s `Database` the journal uses. */
+export interface EngagementJournalDatabase {
+    select(table: string, fields: string[]): {
+        where(condition: Record<string, unknown>): PromiseLike<Record<string, unknown>[]>;
+    };
+    insert(table: string, row: Record<string, unknown>): PromiseLike<unknown>;
+    delete(table: string, condition: Record<string, unknown>): PromiseLike<unknown>;
+}
+export interface DatabaseJournalOptions extends JournalOptions {
+    /** Bounded retries when another process wins a seq (default 5). */
+    readonly maxConflictRetries?: number;
+}
+export declare class DatabaseEngagementJournal implements EngagementJournal {
+    #private;
+    constructor(database: EngagementJournalDatabase, options?: DatabaseJournalOptions);
+    append(event: AppendInput): Promise<EngagementEvent>;
+    read(engagementId: EngagementId): Promise<readonly EngagementEvent[]>;
+    prune(now: number): Promise<number>;
+    listEngagements(limit?: number): Promise<readonly EngagementId[]>;
+    summarize(engagementId: EngagementId): Promise<EngagementSummary | undefined>;
+    compact(engagementId: EngagementId): Promise<void>;
+}
+export {};