@graphvideo/kernel 1.0.0

package/dist/context.d.ts

@@ -0,0 +1,28 @@
+import type { Info, InfoEnvelope, SpanRecord, WorldChangeContext } from './types';
+import type { StateDelta } from './observation';
+import type { EffectAdapter } from './effects';
+import type { Node } from './node';
+/**
+ * Controlled Causal Context Implementation (ChangeContextImpl)
+ */
+export declare class ChangeContextImpl<S = any> implements WorldChangeContext<S> {
+    private node;
+    private readonly rawInfo;
+    private readonly changeId;
+    private readonly envelope?;
+    private readonly signal?;
+    readonly reads: Set<string>;
+    readonly writes: Set<string>;
+    readonly spans: SpanRecord[];
+    readonly stateDeltas: StateDelta[];
+    private readonly traceValues;
+    constructor(node: Node<S, any>, rawInfo: Info, changeId: string, envelope?: InfoEnvelope | undefined, signal?: AbortSignal | undefined);
+    read<K extends keyof S>(key: K): S[K];
+    write<K extends keyof S>(key: K, value: S[K]): void;
+    patchState(patch: Partial<S>): void;
+    send(info: Info, target: string): void;
+    effectAdapter<Request, Observation>(adapter: EffectAdapter<Request, Observation>, request: Request, options?: {
+        signal?: AbortSignal;
+    }): Promise<Observation>;
+    span<T>(name: string, action: () => Promise<T> | T): Promise<T>;
+}

package/dist/delivery.d.ts

@@ -0,0 +1,36 @@
+import type { Node } from './node';
+import type { Info, InfoEnvelope, Probe } from './types';
+import type { TraceSession, RuntimeIdKind } from './observation';
+export interface KernelDeliveryOptions {
+    infoId?: string;
+    causedByChangeId?: string;
+    causeInfoId?: string;
+    submissionId?: string;
+    signal?: AbortSignal;
+}
+export interface DeliveryKernelContext {
+    nodes: Map<string, Node<any>>;
+    envelopes: InfoEnvelope[];
+    probes: Probe[];
+    traceSession: TraceSession;
+    logicalClock: number;
+    pendingDeliveryCount: number;
+    scheduledMailboxNodeIds: Set<string>;
+    mount(...nodes: Node<any>[]): any;
+    ensureInitialStateSnapshot(): void;
+    publishSchedulerState(): void;
+    now(): number;
+    nextId(kind: RuntimeIdKind): string;
+    trackSubmissionDeliveryEnqueued(submissionId?: string): void;
+    trackSubmissionDeliverySettled(submissionId?: string, error?: unknown): void;
+}
+export declare function deliverSendNowHelper(ctx: DeliveryKernelContext, source: Node<any>, info: Info, target: Node<any> | string, options?: KernelDeliveryOptions): void;
+export declare function injectRootInfoNowHelper(ctx: DeliveryKernelContext, target: Node<any>, info: Info, options?: {
+    signal?: AbortSignal;
+    submissionId?: string;
+}): void;
+export declare function enqueueMailboxDeliveryHelper(ctx: DeliveryKernelContext, target: Node<any>, info: Info, envelope: InfoEnvelope, options: {
+    signal?: AbortSignal;
+}): void;
+export declare function scheduleMailboxDrainHelper(ctx: DeliveryKernelContext, target: Node<any>): void;
+export declare function settleMailboxDeliveryHelper(ctx: DeliveryKernelContext, submissionId?: string, error?: unknown): void;

package/dist/effect-harness.d.ts

@@ -0,0 +1,51 @@
+import type { Clock } from './observation';
+import { ValueCodec, type EncodedValue, type ValueCodecOptions } from './observation';
+import type { EffectAdapter } from './effects';
+export interface EffectFixture<Request> {
+    readonly schemaVersion: 1;
+    readonly fixtureId: string;
+    readonly request: Request;
+    readonly expectedObservation?: EncodedValue;
+}
+export interface EffectHarnessRecord {
+    readonly schemaVersion: 1;
+    readonly fixtureId: string;
+    readonly executionId: string;
+    readonly adapterId: string;
+    readonly request: EncodedValue;
+    readonly observation?: EncodedValue;
+    readonly transportMetadata: readonly EncodedValue[];
+    readonly rawSummaries: readonly {
+        readonly kind: string;
+        readonly text: string;
+        readonly redacted: boolean;
+    }[];
+    readonly startedAt: number;
+    readonly completedAt: number;
+    readonly durationMs: number;
+    readonly status: 'succeeded' | 'failed';
+    readonly expectedMatched?: boolean;
+    readonly error?: string;
+}
+export interface EffectHarnessResult<Observation> {
+    readonly record: EffectHarnessRecord;
+    readonly observation?: Observation;
+}
+export interface EffectHarnessOptions {
+    readonly clock?: Clock;
+    readonly valueCodec?: ValueCodec;
+    readonly valueCodecOptions?: ValueCodecOptions;
+    readonly maxFixtureBytes?: number;
+    readonly maxRawSummaryCharacters?: number;
+}
+export declare class EffectHarness {
+    private readonly clock;
+    private readonly valueCodec;
+    private readonly valueCodecOptions;
+    private readonly maxFixtureBytes;
+    private readonly maxRawSummaryCharacters;
+    constructor(options?: EffectHarnessOptions);
+    run<Request, Observation>(adapter: EffectAdapter<Request, Observation>, fixture: EffectFixture<Request>, options?: {
+        signal?: AbortSignal;
+    }): Promise<EffectHarnessResult<Observation>>;
+}

package/dist/effect-harness.mjs

@@ -0,0 +1,191 @@
+//#region kernel/src/observation.ts
+var e = {
+	now: () => Date.now(),
+	monotonicNow: () => typeof performance < "u" ? performance.now() : Date.now()
+}, t = class {
+	defaultOptions;
+	constructor(e = {}) {
+		this.defaultOptions = e;
+	}
+	encode(e, t = {}) {
+		let n = {
+			...this.defaultOptions,
+			...t
+		};
+		return this._encodeValue(e, n.maxDepth ?? 8, n.rootPath ?? [], n);
+	}
+	_encodeValue(e, t, n, r) {
+		if (e == null) return {
+			$type: "primitive",
+			value: e
+		};
+		let i = typeof e;
+		if (i === "string" || i === "number" || i === "boolean") return {
+			$type: "primitive",
+			value: e
+		};
+		if (i === "bigint" || i === "symbol" || i === "function") return {
+			$type: "ref",
+			kind: i,
+			summary: String(e)
+		};
+		if (t <= 0) return {
+			$type: "truncated",
+			originalType: i,
+			summary: "[Max Depth Reached]"
+		};
+		if (e instanceof Map) {
+			let i = [];
+			for (let [a, o] of e.entries()) i.push([this._encodeValue(a, t - 1, [...n, String(a)], r), this._encodeValue(o, t - 1, [...n, String(a)], r)]);
+			return {
+				$type: "map",
+				entries: i
+			};
+		}
+		if (e instanceof Set) return {
+			$type: "set",
+			values: Array.from(e.values()).map((e, i) => this._encodeValue(e, t - 1, [...n, String(i)], r))
+		};
+		if (Array.isArray(e)) {
+			let i = r.maxArrayLength ?? 100;
+			return {
+				$type: "array",
+				value: e.slice(0, i).map((e, i) => this._encodeValue(e, t - 1, [...n, String(i)], r))
+			};
+		}
+		if (e instanceof Uint8Array || typeof Buffer < "u" && Buffer.isBuffer(e)) return {
+			$type: "bytes",
+			value: typeof Buffer < "u" ? Buffer.from(e).toString("base64") : "",
+			byteLength: e.byteLength
+		};
+		if (i === "object") {
+			let i = {}, a = e, o = Object.keys(a);
+			for (let e of o) i[e] = r.redactedKeys?.includes(e) ? {
+				$type: "ref",
+				kind: "redacted",
+				summary: "[REDACTED]"
+			} : this._encodeValue(a[e], t - 1, [...n, e], r);
+			return {
+				$type: "object",
+				value: i
+			};
+		}
+		return {
+			$type: "primitive",
+			value: String(e)
+		};
+	}
+	decode(e) {
+		if (!e || typeof e != "object") return e;
+		switch (e.$type) {
+			case "primitive": return e.value;
+			case "array": return e.value.map((e) => this.decode(e));
+			case "map": {
+				let t = /* @__PURE__ */ new Map();
+				for (let [n, r] of e.entries) t.set(this.decode(n), this.decode(r));
+				return t;
+			}
+			case "set": {
+				let t = /* @__PURE__ */ new Set();
+				for (let n of e.values) t.add(this.decode(n));
+				return t;
+			}
+			case "object": {
+				let t = {};
+				for (let [n, r] of Object.entries(e.value)) t[n] = this.decode(r);
+				return t;
+			}
+			case "bytes": return typeof Buffer < "u" ? Buffer.from(e.value, "base64") : e.value;
+			case "ref":
+			case "truncated": return e.summary;
+			default: return e;
+		}
+	}
+};
+new t();
+//#endregion
+//#region kernel/src/effect-harness.ts
+var n = 65536, r = 2048, i = class {
+	clock;
+	valueCodec;
+	valueCodecOptions;
+	maxFixtureBytes;
+	maxRawSummaryCharacters;
+	constructor(i = {}) {
+		if (this.clock = i.clock ?? e, this.valueCodec = i.valueCodec ?? new t(), this.valueCodecOptions = i.valueCodecOptions ?? {}, this.maxFixtureBytes = i.maxFixtureBytes ?? n, this.maxRawSummaryCharacters = i.maxRawSummaryCharacters ?? r, !Number.isSafeInteger(this.maxFixtureBytes) || this.maxFixtureBytes <= 0) throw Error("EffectHarness maxFixtureBytes 必须是正安全整数");
+		if (!Number.isSafeInteger(this.maxRawSummaryCharacters) || this.maxRawSummaryCharacters <= 0) throw Error("EffectHarness maxRawSummaryCharacters 必须是正安全整数");
+	}
+	async run(e, t, n = {}) {
+		if (!e.id.trim()) throw Error("EffectAdapter id 不能为空");
+		if (t.schemaVersion !== 1) throw Error(`EffectFixture schemaVersion 不支持: ${t.schemaVersion}`);
+		if (!t.fixtureId.trim()) throw Error("EffectFixture fixtureId 不能为空");
+		if (n.signal?.aborted) throw n.signal.reason ?? /* @__PURE__ */ Error("Effect 已取消");
+		let r = this.valueCodec.encode(t.request, {
+			...this.valueCodecOptions,
+			maxBytes: Math.min(this.valueCodecOptions.maxBytes ?? this.maxFixtureBytes, this.maxFixtureBytes),
+			rootPath: ["fixture", "request"]
+		}), i = [], a = [], o = this.clock.now(), s = this.clock.monotonicNow(), c = `${t.fixtureId}/${e.id}`, l = {
+			clock: this.clock,
+			signal: n.signal,
+			recordTransport: (e) => {
+				i.push(this.valueCodec.encode(e, {
+					...this.valueCodecOptions,
+					maxBytes: this.maxFixtureBytes,
+					rootPath: ["transportMetadata", String(i.length)]
+				}));
+			},
+			recordRawSummary: (e) => {
+				if (!e.kind.trim()) throw Error("Effect raw summary kind 不能为空");
+				if (e.text.length > this.maxRawSummaryCharacters) throw Error(`Effect raw summary 超过 ${this.maxRawSummaryCharacters} 字符限制`);
+				a.push({
+					kind: e.kind,
+					text: e.text,
+					redacted: e.redacted ?? !1
+				});
+			}
+		};
+		try {
+			let n = await e.execute(t.request, l), u = this.valueCodec.encode(n, {
+				...this.valueCodecOptions,
+				maxBytes: this.maxFixtureBytes,
+				rootPath: ["fixture", "observation"]
+			}), d = this.clock.now(), f = this.clock.monotonicNow() - s;
+			return {
+				observation: n,
+				record: {
+					schemaVersion: 1,
+					fixtureId: t.fixtureId,
+					executionId: c,
+					adapterId: e.id,
+					request: r,
+					observation: u,
+					transportMetadata: i,
+					rawSummaries: a,
+					startedAt: o,
+					completedAt: d,
+					durationMs: f,
+					status: "succeeded",
+					...t.expectedObservation === void 0 ? {} : { expectedMatched: JSON.stringify(u) === JSON.stringify(t.expectedObservation) }
+				}
+			};
+		} catch (n) {
+			let l = this.clock.now();
+			return { record: {
+				schemaVersion: 1,
+				fixtureId: t.fixtureId,
+				executionId: c,
+				adapterId: e.id,
+				request: r,
+				transportMetadata: i,
+				rawSummaries: a,
+				startedAt: o,
+				completedAt: l,
+				durationMs: this.clock.monotonicNow() - s,
+				status: "failed",
+				error: n instanceof Error ? n.message : String(n)
+			} };
+		}
+	}
+};
+//#endregion
+export { i as EffectHarness };

package/dist/effects.d.ts

@@ -0,0 +1,16 @@
+import type { Clock } from './observation';
+/** Optional diagnostics are supplied only by an explicit test harness. */
+export interface EffectContext {
+    readonly clock: Clock;
+    readonly signal?: AbortSignal;
+    recordTransport?(metadata: unknown): void;
+    recordRawSummary?(summary: {
+        readonly kind: string;
+        readonly text: string;
+        readonly redacted?: boolean;
+    }): void;
+}
+export interface EffectAdapter<Request = unknown, Observation = unknown> {
+    readonly id: string;
+    execute(request: Request, context: EffectContext): Promise<Observation>;
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from './types';
+export * from './node';
+export * from './context';
+export * from './observation';
+export * from './effects';
+export * from './scheduler';
+export * from './runtime';
+export * from './effect-harness';