@graphvideo/kernel 1.0.0

package/dist/internal-access.d.ts

@@ -0,0 +1,3 @@
+/** Runtime-only capabilities. This module is deliberately not exported by the package entrypoint. */
+export declare const nodeRuntimeCapability: unique symbol;
+export declare const changeContextCapability: unique symbol;

package/dist/node.d.ts

@@ -0,0 +1,99 @@
+import type { Info, InfoEnvelope, ChangeRecord, DomainChangeContext, WorldChangeContext } from './types';
+import type { NodeStateSnapshot, EncodedValue, RuntimeIdKind } from './observation';
+import { ChangeContextImpl } from './context';
+import { changeContextCapability, nodeRuntimeCapability } from './internal-access';
+export { ChangeContextImpl };
+export type NodeStatus = 'IDLE' | 'RUNNING' | 'ERROR' | 'ABORTED';
+export type Disposer = () => void | Promise<void>;
+/**
+ * Minimal Graph Node Base Class
+ */
+export declare abstract class Node<S = any, C extends DomainChangeContext<S> = DomainChangeContext<S>> {
+    readonly id: string;
+    name: string;
+    readonly factoryKey: string;
+    isWorldNode: boolean;
+    status: NodeStatus;
+    executionCount: number;
+    lastActiveTime: number;
+    lastErrorMessage: string | null;
+    protected state: S;
+    private regionVersions;
+    private globalVersion;
+    private readonly mailbox;
+    private drainingMailbox;
+    private activeChangeId;
+    private disposers;
+    private abortController;
+    private kernel;
+    constructor(id: string, name: string, initialState?: S, factoryKey?: string);
+    getState(): Readonly<S>;
+    getStateRegionVersions(): Readonly<Record<string, number>>;
+    getGlobalStateVersion(): number;
+    getMailboxSize(): number;
+    getActiveChangeId(): string | undefined;
+    _restoreStateSnapshot(capability: typeof nodeRuntimeCapability, snapshot: NodeStateSnapshot, decodedState: unknown): void;
+    /** @internal Runtime ownership boundary. Domain nodes cannot reach the engine directly. */
+    _mountKernel(capability: typeof nodeRuntimeCapability, kernel: unknown): void;
+    /** @internal Runtime ownership boundary. */
+    _unmountKernel(capability: typeof nodeRuntimeCapability, kernel: unknown): void;
+    _enqueueMailbox(capability: typeof nodeRuntimeCapability, info: Info, envelope?: InfoEnvelope, options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    _drainMailbox(capability: typeof nodeRuntimeCapability): Promise<void>;
+    private runWithinChangeContext;
+    protected createChangeContext(info: Info, changeId: string, envelope?: InfoEnvelope, signal?: AbortSignal): ChangeContextImpl<S>;
+    get stateVersion(): number;
+    commitStateFromChange(capability: typeof changeContextCapability, changeId: string, patch: Partial<S>, causeInfo?: Info): void;
+    _sendFromChange(capability: typeof changeContextCapability, info: Info, target: Node<any> | string, options?: {
+        infoId?: string;
+        causedByChangeId?: string;
+        causeInfoId?: string;
+        submissionId?: string;
+        signal?: AbortSignal;
+    }): void;
+    protected change(_info: Info, _ctx: C): void | Promise<void>;
+    runtimeNow(): number;
+    runtimeMonotonicNow(): number;
+    runtimeId(kind: RuntimeIdKind): string;
+    encodeTraceValue(field: string, value: unknown): EncodedValue;
+    runtimeValueRef(kind: string, value: unknown): string;
+    recordChangeStarted(input: {
+        changeId: string;
+        nodeId: string;
+        causeInfoId: string;
+        causeInfoType: string;
+        stateVersionBefore: number;
+    }): void;
+    recordChange(record: ChangeRecord): void;
+    recordEffectRequested(input: {
+        effectId: string;
+        changeId: string;
+        nodeId: string;
+        name?: string;
+        adapterId?: string;
+        requestRef?: string;
+    }): void;
+    recordEffectObserved(input: {
+        effectId: string;
+        changeId: string;
+        nodeId: string;
+        name?: string;
+        status: 'succeeded' | 'failed';
+        adapterId?: string;
+        requestRef?: string;
+        observationRef?: string;
+    }): void;
+    onMount(): void;
+    onUnmount(): void;
+    registerDisposer(disposer: Disposer): void;
+    dispose(): Promise<void>;
+    abort(reason?: string): void;
+    reset(): void;
+}
+/**
+ * WorldNode Base Class
+ */
+export declare abstract class WorldNode<S = any, C extends WorldChangeContext<S> = WorldChangeContext<S>> extends Node<S, C> {
+    isWorldNode: boolean;
+}

package/dist/observation.d.ts

@@ -0,0 +1,204 @@
+import type { ChangeRecord, InfoEnvelope } from './types';
+export declare const traceSchemaVersion: 2;
+export type TraceId = string;
+export type RunId = string;
+export type EventId = string;
+export type RuntimeIdKind = 'trace' | 'run' | 'event' | 'info' | 'info-root' | 'send' | 'change' | 'effect' | 'snapshot' | 'submission' | 'task';
+export interface Clock {
+    now(): number;
+    monotonicNow(): number;
+}
+export interface IdProvider {
+    nextId(kind: RuntimeIdKind): string;
+}
+export interface RandomSource {
+    next(): number;
+}
+export declare const systemClock: Clock;
+export declare const systemRandomSource: RandomSource;
+export declare class TimeRandomIdProvider implements IdProvider {
+    private clock;
+    private randomSource;
+    private counter;
+    constructor(clock?: Clock, randomSource?: RandomSource);
+    nextId(kind: RuntimeIdKind): string;
+}
+export type EncodedValue = {
+    $type: 'primitive';
+    value: string | number | boolean | null | undefined;
+} | {
+    $type: 'array';
+    value: EncodedValue[];
+} | {
+    $type: 'object';
+    value: Record<string, EncodedValue>;
+} | {
+    $type: 'map';
+    entries: Array<[EncodedValue, EncodedValue]>;
+} | {
+    $type: 'set';
+    values: EncodedValue[];
+} | {
+    $type: 'bytes';
+    value: string;
+    byteLength: number;
+} | {
+    $type: 'ref';
+    kind: string;
+    summary: string;
+    id?: string;
+} | {
+    $type: 'truncated';
+    originalType: string;
+    summary: string;
+    byteLength?: number;
+};
+export interface ValueCodecOptions {
+    maxDepth?: number;
+    maxBytes?: number;
+    maxArrayLength?: number;
+    rootPath?: string[];
+    redactedKeys?: readonly string[];
+}
+export declare class ValueCodec {
+    private defaultOptions;
+    constructor(defaultOptions?: ValueCodecOptions);
+    encode(value: unknown, options?: ValueCodecOptions): EncodedValue;
+    private _encodeValue;
+    decode(encoded: EncodedValue): any;
+}
+export declare const defaultValueCodec: ValueCodec;
+export declare function fnv1a32(str: string): string;
+export interface StateDelta {
+    readonly ordinal: number;
+    readonly field: string;
+    readonly before: EncodedValue;
+    readonly after: EncodedValue;
+}
+export interface NodeStateSnapshot {
+    readonly nodeId: string;
+    readonly factoryKey: string;
+    readonly state: EncodedValue;
+    readonly globalVersion: number;
+    readonly regionVersions: Record<string, number>;
+}
+export interface StateSnapshot {
+    readonly snapshotId: string;
+    readonly traceId: TraceId;
+    readonly runId: RunId;
+    readonly capturedAt: number;
+    readonly reason: 'initial' | 'mounted' | 'checkpoint' | 'manual';
+    readonly nodes: NodeStateSnapshot[];
+}
+export interface TraceEventBase {
+    readonly schemaVersion: typeof traceSchemaVersion;
+    readonly traceId: TraceId;
+    readonly runId: RunId;
+    readonly eventId: EventId;
+    readonly sequence: number;
+    readonly timestamp: number;
+}
+export type TraceEventPayload = {
+    type: 'TraceStarted';
+    graphFingerprint?: string;
+    runtimeVersion: string;
+} | {
+    type: 'GraphMounted';
+    nodeIds: string[];
+    nodeFactories: Record<string, string>;
+} | {
+    type: 'StateSnapshotCaptured';
+    snapshot: StateSnapshot;
+} | {
+    type: 'StateSnapshotRestored';
+    snapshotId: string;
+    nodeIds: string[];
+} | {
+    type: 'InfoEmitted';
+    envelope: InfoEnvelope;
+} | {
+    type: 'InfoDelivered';
+    envelope: InfoEnvelope;
+} | {
+    type: 'BoundaryOutputCaptured';
+    fragmentId: string;
+    envelope: InfoEnvelope;
+} | {
+    type: 'FragmentBoundaryViolation';
+    fragmentId: string;
+    sourceNodeId: string;
+    targetNodeId: string;
+    infoType: string;
+} | {
+    type: 'ChangeStarted';
+    changeId: string;
+    nodeId: string;
+    causeInfoId: string;
+    causeInfoType: string;
+    stateVersionBefore: number;
+} | {
+    type: 'StateDeltaCommitted';
+    changeId: string;
+    nodeId: string;
+    stateVersionAfter: number;
+    deltas: StateDelta[];
+} | {
+    type: 'EffectRequested';
+    effectId: string;
+    changeId: string;
+    nodeId: string;
+    name?: string;
+    adapterId?: string;
+    requestRef?: string;
+} | {
+    type: 'WorldEffectRejected';
+    fragmentId: string;
+    effectId: string;
+    changeId: string;
+    nodeId: string;
+    name?: string;
+    adapterId?: string;
+    requestRef?: string;
+} | {
+    type: 'EffectObserved';
+    effectId: string;
+    changeId: string;
+    nodeId: string;
+    name?: string;
+    status: 'succeeded' | 'failed';
+    adapterId?: string;
+    requestRef?: string;
+    observationRef?: string;
+} | {
+    type: 'ChangeCompleted';
+    record: ChangeRecord;
+} | {
+    type: 'TraceCompleted';
+    status: 'completed' | 'failed';
+    error?: string;
+};
+export type TraceEvent = TraceEventBase & TraceEventPayload;
+export interface TraceStore {
+    append(event: TraceEvent): Promise<void> | void;
+    getEvents?(traceId?: string): Promise<TraceEvent[]> | TraceEvent[];
+}
+export declare class MemoryTraceStore implements TraceStore {
+    private events;
+    append(event: TraceEvent): void;
+    getEvents(): TraceEvent[];
+    clear(): void;
+}
+export declare class TraceSession {
+    readonly traceId: string;
+    readonly runId: string;
+    private idProvider;
+    private clock;
+    private traceStore?;
+    sequence: number;
+    readonly events: TraceEvent[];
+    readonly records: ChangeRecord[];
+    constructor(traceId: string, runId: string, idProvider: IdProvider, clock: Clock, traceStore?: TraceStore | undefined);
+    record(payload: TraceEventPayload): TraceEvent;
+    recordChange(record: ChangeRecord): void;
+}
+export declare function applyStateDeltas(encodedState: EncodedValue, deltas: readonly StateDelta[]): EncodedValue;

package/dist/runtime.d.ts

@@ -0,0 +1,121 @@
+import type { Node } from './node';
+import type { Info, InfoEnvelope, ChangeRecord, Probe, GraphProjection, InjectionResult } from './types';
+import type { Clock, IdProvider, RandomSource, ValueCodec, ValueCodecOptions, TraceStore, RuntimeIdKind, StateSnapshot, EncodedValue, TraceEvent } from './observation';
+import { TraceSession } from './observation';
+import type { KernelSchedulerSnapshot } from './scheduler';
+import type { KernelDeliveryOptions } from './delivery';
+export interface KernelRuntimeOptions {
+    clock?: Clock;
+    idProvider?: IdProvider;
+    randomSource?: RandomSource;
+    valueCodec?: ValueCodec;
+    valueCodecOptions?: ValueCodecOptions;
+    traceStore?: TraceStore;
+    stateSnapshots?: {
+        captureInitial?: boolean;
+        everyChanges?: number;
+    };
+}
+/**
+ * Pure In-Process Kernel Runtime Execution Engine
+ */
+export declare class KernelRuntime {
+    readonly nodes: Map<string, Node<any>>;
+    readonly envelopes: InfoEnvelope[];
+    readonly probes: Probe[];
+    readonly clock: Clock;
+    readonly idProvider: IdProvider;
+    readonly randomSource: RandomSource;
+    readonly valueCodec: ValueCodec;
+    readonly valueCodecOptions: ValueCodecOptions;
+    readonly traceStore?: TraceStore;
+    readonly traceSession: TraceSession;
+    logicalClock: number;
+    pendingDeliveryCount: number;
+    activeChangeIds: Set<string>;
+    scheduledGraphMicrotaskCount: number;
+    schedulerListeners: Set<(state: KernelSchedulerSnapshot) => void>;
+    scheduledMailboxNodeIds: Set<string>;
+    projectionListeners: Set<(projection: GraphProjection) => void>;
+    projectionRevision: number;
+    private readonly submissions;
+    captureInitialStateSnapshot: boolean;
+    initialStateSnapshotCaptured: boolean;
+    private isDisposed;
+    constructor(options?: KernelRuntimeOptions);
+    now(): number;
+    monotonicNow(): number;
+    nextId(kind: RuntimeIdKind): string;
+    mount(...nodes: Node<any>[]): this;
+    unmount(...nodeIds: string[]): this;
+    getNode<T extends Node<any> = Node<any>>(id: string): T | undefined;
+    getNodes(): Node<any>[];
+    /** @internal Called only by a Node's active ChangeContext. */
+    _deliverSendFromChange(source: Node<any>, info: Info, target: Node<any> | string, options?: KernelDeliveryOptions): void;
+    injectRootInfo(target: Node<any>, info: Info, options?: {
+        signal?: AbortSignal;
+        submissionId?: string;
+    }): string;
+    inject(input: {
+        submissionId: string;
+        targetNodeId: string;
+        info: Info;
+        signal?: AbortSignal;
+    }): Promise<InjectionResult>;
+    cancel(submissionId: string): boolean;
+    waitForSubmission(submissionId: string): Promise<void>;
+    trackSubmissionDeliveryEnqueued(submissionId?: string): void;
+    trackSubmissionDeliverySettled(submissionId?: string, error?: unknown): void;
+    snapshot(): StateSnapshot;
+    publishSchedulerState(): void;
+    readProjection(): GraphProjection;
+    subscribeProjection(listener: (projection: GraphProjection) => void): () => void;
+    publishProjection(): void;
+    getSchedulerSnapshot(): KernelSchedulerSnapshot;
+    subscribeScheduler(listener: (state: KernelSchedulerSnapshot) => void): () => void;
+    scheduleMicrotask<T>(task: () => T | Promise<T>): Promise<T>;
+    waitForQuiescence(options?: {
+        signal?: AbortSignal;
+    }): Promise<KernelSchedulerSnapshot>;
+    captureStateSnapshot(reason?: StateSnapshot['reason'], nodeIds?: readonly string[]): StateSnapshot;
+    restoreStateSnapshot(snapshot: StateSnapshot): void;
+    ensureInitialStateSnapshot(): void;
+    encodeTraceValue(nodeId: string, field: string, value: unknown): EncodedValue;
+    recordValueRef(kind: string, value: unknown): string;
+    beginChangeExecution(changeId: string): void;
+    endChangeExecution(changeId: string): void;
+    recordChangeStarted(input: {
+        changeId: string;
+        nodeId: string;
+        causeInfoId: string;
+        causeInfoType: string;
+        stateVersionBefore: number;
+    }): void;
+    get causalRecords(): readonly ChangeRecord[];
+    get events(): readonly TraceEvent[];
+    recordChange(record: ChangeRecord): void;
+    recordEffectRequested(input: {
+        effectId: string;
+        changeId: string;
+        nodeId: string;
+        name?: string;
+        adapterId?: string;
+        requestRef?: string;
+    }): void;
+    recordEffectObserved(input: {
+        effectId: string;
+        changeId: string;
+        nodeId: string;
+        name?: string;
+        status: 'succeeded' | 'failed';
+        adapterId?: string;
+        requestRef?: string;
+        observationRef?: string;
+    }): void;
+    addProbe(probe: Probe): this;
+    removeProbe(probe: Probe): this;
+    dispose(): Promise<void>;
+    private createSubmission;
+    private settleSubmissionIfComplete;
+}
+export declare function createKernelRuntime(options?: KernelRuntimeOptions): KernelRuntime;

package/dist/scheduler.d.ts

@@ -0,0 +1,20 @@
+export interface KernelSchedulerSnapshot {
+    readonly pendingDeliveries: number;
+    readonly activeChanges: number;
+    readonly scheduledGraphMicrotasks: number;
+    readonly isQuiescent: boolean;
+}
+export declare function schedulerCancellationError(signal: AbortSignal): Error;
+export interface SchedulerKernelContext {
+    pendingDeliveryCount: number;
+    activeChangeIds: Set<string>;
+    scheduledGraphMicrotaskCount: number;
+    schedulerListeners: Set<(state: KernelSchedulerSnapshot) => void>;
+}
+export declare function computeSchedulerSnapshot(ctx: SchedulerKernelContext): KernelSchedulerSnapshot;
+export declare function subscribeSchedulerHelper(ctx: SchedulerKernelContext, listener: (state: KernelSchedulerSnapshot) => void): () => void;
+export declare function publishSchedulerStateHelper(ctx: SchedulerKernelContext): void;
+export declare function scheduleGraphMicrotaskHelper<T>(ctx: SchedulerKernelContext, task: () => T | Promise<T>): Promise<T>;
+export declare function waitForQuiescenceHelper(ctx: SchedulerKernelContext, options?: {
+    signal?: AbortSignal;
+}): Promise<KernelSchedulerSnapshot>;

package/dist/snapshot.d.ts

@@ -0,0 +1,14 @@
+import type { Node } from './node';
+import type { StateSnapshot, EncodedValue, ValueCodec, ValueCodecOptions, TraceSession, RuntimeIdKind } from './observation';
+export { applyStateDeltas } from './observation';
+export interface SnapshotKernelContext {
+    nodes: Map<string, Node<any>>;
+    valueCodec: ValueCodec;
+    valueCodecOptions: ValueCodecOptions;
+    traceSession: TraceSession;
+    now(): number;
+    nextId(kind: RuntimeIdKind): string;
+}
+export declare function encodeTraceValueHelper(ctx: SnapshotKernelContext, nodeId: string, field: string, value: unknown): EncodedValue;
+export declare function captureStateSnapshotHelper(ctx: SnapshotKernelContext, reason?: StateSnapshot['reason'], nodeIds?: readonly string[]): StateSnapshot;
+export declare function restoreStateSnapshotHelper(ctx: SnapshotKernelContext, snapshot: StateSnapshot): void;

package/dist/types.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Minimal Kernel Types & DTOs
+ */
+export interface Info {
+    readonly type: string;
+    [key: string]: unknown;
+}
+export interface InfoEnvelope<TInfo = Info> {
+    readonly infoId: string;
+    readonly senderNodeId: string;
+    readonly targetNodeId: string;
+    readonly causedByChangeId?: string;
+    readonly causeInfoId?: string;
+    readonly submissionId?: string;
+    readonly sequence: number;
+    readonly timestamp: number;
+    readonly payload: TInfo;
+}
+export interface SpanRecord {
+    readonly name: string;
+    readonly durationMs: number;
+    readonly timestamp: number;
+}
+export interface ChangeRecord {
+    readonly changeId: string;
+    readonly nodeId: string;
+    readonly causeInfoId: string;
+    readonly causeInfoType: string;
+    readonly causedByChangeId?: string;
+    readonly stateVersionBefore: number;
+    readonly stateVersionAfter: number;
+    readonly reads: string[];
+    readonly writes: string[];
+    readonly stateDeltas?: import('./observation').StateDelta[];
+    readonly spans: SpanRecord[];
+    readonly durationMs: number;
+    readonly timestamp: number;
+    readonly error?: string;
+}
+export interface DomainChangeContext<S = any> {
+    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, targetNodeId: string): void;
+    span<T>(name: string, action: () => Promise<T> | T): Promise<T>;
+}
+export interface WorldChangeContext<S = any> extends DomainChangeContext<S> {
+    effectAdapter<Request, Observation>(adapter: import('./effects').EffectAdapter<Request, Observation>, request: Request, options?: {
+        signal?: AbortSignal;
+    }): Promise<Observation>;
+}
+export type ChangeContext<S = any> = DomainChangeContext<S>;
+export interface Probe {
+    onTraceEvent?(event: import('./observation').TraceEvent): void;
+    onChangeRecord?(record: ChangeRecord): void;
+}
+export interface GraphProjectionNode {
+    readonly nodeId: string;
+    readonly state: any;
+    readonly version: number;
+    readonly status?: string;
+}
+export interface GraphProjection {
+    readonly revision: number;
+    readonly nodes: GraphProjectionNode[];
+    readonly scheduler: {
+        readonly pendingDeliveries: number;
+        readonly activeChanges: number;
+        readonly scheduledGraphMicrotasks: number;
+    };
+}
+export interface InjectionResult {
+    readonly status: 'accepted' | 'rejected';
+    readonly submissionId: string;
+    readonly reason?: string;
+}
+export interface GraphSyscallRequestMap {
+    'graph.injectRootInfo': {
+        input: {
+            targetNodeId: string;
+            info: Info;
+            submissionId?: string;
+        };
+        output: InjectionResult & {
+            projection: GraphProjection;
+        };
+    };
+    'graph.cancel': {
+        input: {
+            submissionId: string;
+        };
+        output: {
+            cancelled: boolean;
+        };
+    };
+    'graph.projection.read': {
+        input: Record<string, never>;
+        output: {
+            projection: GraphProjection;
+        };
+    };
+}
+export interface GraphSyscallEventMap {
+    'graph.projection.updated': {
+        projection: GraphProjection;
+    };
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@graphvideo/kernel",
+  "version": "1.0.0",
+  "description": "Zero-business-semantics causal graph microkernel for GraphFramework",
+  "license": "Apache-2.0",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:vd249175-cpu/GSDK.git",
+    "directory": "kernel"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs"
+    },
+    "./effect-harness": {
+      "types": "./dist/effect-harness.d.ts",
+      "import": "./dist/effect-harness.mjs"
+    }
+  },
+  "files": [
+    "dist"
+  ]
+}