@obversa/api 0.1.0

package/dist/graph-plan.d.ts

@@ -0,0 +1,140 @@
+import type { ExecutionTarget } from './contracts.js';
+export type { ExecutionTarget } from './contracts.js';
+import { type EdgeId, type GraphId, type NodeId } from './graph-contract.js';
+import { type JsonValue, type Sha256Digest } from './json.js';
+export interface PermissionDescriptor {
+    readonly name: string;
+    readonly scope: JsonValue;
+}
+export interface ExecutionLaneDescription {
+    readonly id: string;
+    readonly requested: ExecutionTarget;
+    readonly knownSubstitutions: readonly ExecutionTarget[];
+}
+export interface GraphPhaseDescription {
+    readonly id: string;
+    readonly name: string;
+    readonly nodeIds: readonly NodeId[];
+}
+export interface GraphNodeDescription {
+    readonly id: NodeId;
+    readonly phaseId: string;
+    readonly inputContract: JsonValue;
+    readonly outputContract: JsonValue;
+    readonly laneId: string | null;
+}
+export interface GraphEdgeDescription {
+    readonly id: EdgeId;
+    readonly source: NodeId;
+    readonly target: NodeId;
+}
+export type PlanBound = {
+    readonly kind: 'known';
+    readonly value: number;
+} | {
+    readonly kind: 'unknown';
+    readonly reason: string;
+};
+export interface GraphBounds {
+    readonly dispatches: {
+        readonly min: PlanBound;
+        readonly max: PlanBound;
+    };
+    readonly maxConcurrency: PlanBound;
+    readonly maxFanOut: PlanBound;
+}
+export interface GraphPolicyDescription {
+    readonly retry: JsonValue;
+    readonly stop: JsonValue;
+    readonly concurrency: JsonValue;
+    readonly write: JsonValue;
+    readonly budget: JsonValue;
+    readonly action: JsonValue;
+}
+export interface GraphRequirements {
+    readonly memory: 'required' | 'unused';
+}
+export interface GraphDescriptionInput {
+    readonly inputContract: JsonValue;
+    readonly outputContract: JsonValue;
+    readonly phases: readonly GraphPhaseDescription[];
+    readonly nodes: readonly GraphNodeDescription[];
+    readonly policies: GraphPolicyDescription;
+    readonly executionLanes: readonly ExecutionLaneDescription[];
+    readonly requestedPermissions: readonly PermissionDescriptor[];
+    readonly bounds: GraphBounds;
+}
+export interface GraphDescription extends GraphDescriptionInput {
+    readonly schemaVersion: 1;
+    readonly graph: {
+        readonly id: GraphId;
+        readonly definitionVersion: number;
+        readonly kind: string;
+        readonly typeVersion: number;
+        readonly definitionDigest: Sha256Digest;
+    };
+    readonly edges: readonly GraphEdgeDescription[];
+    readonly requirements: GraphRequirements;
+}
+export interface GraphPackageIdentity {
+    readonly source: string;
+    readonly version: string;
+    readonly digest: Sha256Digest;
+}
+export interface GraphPackageAdmission {
+    readonly package: GraphPackageIdentity;
+    readonly permissions: readonly PermissionDescriptor[];
+}
+export interface ExecutionLaneResolution {
+    readonly id: string;
+    readonly effective: ExecutionTarget;
+    readonly fallbacks?: readonly ExecutionTarget[];
+}
+export interface RunPreflightPolicy {
+    readonly timeoutMs: number;
+    readonly lanes: readonly {
+        readonly laneId: string;
+        readonly live: 'required' | 'skip';
+        readonly unsupportedStatic: 'block' | 'allow';
+    }[];
+}
+export interface PlanResolution {
+    readonly package: GraphPackageIdentity;
+    readonly admission: GraphPackageAdmission;
+    readonly executionLanes: readonly ExecutionLaneResolution[];
+    readonly preflight?: RunPreflightPolicy;
+}
+export interface ResolvedExecutionLane extends ExecutionLaneDescription {
+    readonly effective: ExecutionTarget;
+    readonly fallbacks: readonly ExecutionTarget[];
+}
+export interface ResolvedPlan {
+    readonly schemaVersion: 1;
+    readonly graph: GraphDescription['graph'];
+    readonly package: GraphPackageIdentity;
+    readonly inputContract: JsonValue;
+    readonly outputContract: JsonValue;
+    readonly phases: readonly GraphPhaseDescription[];
+    readonly nodes: readonly GraphNodeDescription[];
+    readonly edges: readonly GraphEdgeDescription[];
+    readonly policies: GraphPolicyDescription;
+    readonly executionLanes: readonly ResolvedExecutionLane[];
+    readonly preflight?: RunPreflightPolicy;
+    readonly permissions: {
+        readonly requested: readonly PermissionDescriptor[];
+        readonly admitted: readonly PermissionDescriptor[];
+    };
+    readonly bounds: GraphBounds;
+    readonly requirements: GraphRequirements;
+}
+export interface ResolvedPlanSnapshot {
+    readonly plan: ResolvedPlan;
+    readonly canonicalJson: string;
+    readonly digest: Sha256Digest;
+}
+/** Validate and freeze a resolved plan read from storage. */
+export declare function validateResolvedPlan(value: unknown): ResolvedPlan;
+/** Validate and freeze the stable data returned by a graph type. */
+export declare function validateGraphDescription(value: unknown): GraphDescription;
+/** Bind a pure plan description to host admission and effective engines. */
+export declare function resolveGraphPlan(value: GraphDescription, input: PlanResolution): ResolvedPlanSnapshot;

package/dist/graph-type.d.ts

@@ -0,0 +1,45 @@
+import type { Memory } from './memory-types.js';
+import type { GraphCommand } from './graph-commands.js';
+import type { CompiledGraphDefinition, GraphDefinition, GraphKernel, NodeId, GraphValidationIssue } from './graph-contract.js';
+import type { GraphRequirements, GraphDescriptionInput, GraphDescription } from './graph-plan.js';
+import type { JsonObject, JsonValue } from './json.js';
+export interface GraphEvent<Type extends string = string, Payload extends JsonValue = JsonValue> {
+    readonly type: Type;
+    readonly version: number;
+    readonly payload: Payload;
+}
+export interface GraphEngineIdentity extends JsonObject {
+    readonly adapter: string;
+    readonly provider: string | null;
+    readonly modelFamily: string | null;
+    readonly model: string | null;
+}
+export interface EngineAttemptRecordedPayload extends JsonObject {
+    readonly nodeId: NodeId;
+    readonly position: string;
+    readonly sequence: number;
+    readonly requested: GraphEngineIdentity | null;
+    readonly effective: GraphEngineIdentity | null;
+}
+export type GraphBindings<Requirements extends GraphRequirements> = 'required' extends Requirements['memory'] ? {
+    readonly memory: Memory;
+} : {
+    readonly memory?: never;
+};
+export interface GraphTypeCompilation<State extends JsonValue = JsonValue, Event extends GraphEvent = GraphEvent, Requirements extends GraphRequirements = GraphRequirements> {
+    readonly requirements: Requirements;
+    initialState(): State;
+    reduce(state: State, event: Event): State;
+    decide(state: State): readonly GraphCommand[];
+    describe(): GraphDescriptionInput;
+    validateNodeResult?(nodeId: NodeId, result: JsonValue): GraphValidationIssue | null;
+}
+export interface CompiledGraphType<Definition extends GraphDefinition = GraphDefinition, State extends JsonValue = JsonValue, Event extends GraphEvent = GraphEvent, Requirements extends GraphRequirements = GraphRequirements> extends Omit<GraphTypeCompilation<State, Event, Requirements>, 'describe'> {
+    readonly definition: CompiledGraphDefinition<Definition>;
+    describe(): GraphDescription;
+}
+export interface GraphType<Definition extends GraphDefinition = GraphDefinition, State extends JsonValue = JsonValue, Event extends GraphEvent = GraphEvent, Requirements extends GraphRequirements = GraphRequirements> {
+    readonly kind: string;
+    readonly version: number;
+    compile(definition: Definition, kernel: GraphKernel<Definition>): GraphTypeCompilation<State, Event, Requirements>;
+}

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+export * from './contracts.js';
+export * from './action-decision.js';
+export type { TokenLimitMode, TokenAllowance, AttemptBudgetPolicy, TokenBudgetSnapshot, BudgetReservation, TokenBudget, } from './budget.js';
+export * from './error.js';
+export type { Environment, EnvHandle, EnvironmentWorkspace } from './environment.js';
+export * from './result.js';
+export * from './memory-types.js';
+export * from './graph-contract.js';
+export * from './graph-commands.js';
+export * from './graph-type.js';
+export * from './result-contract.js';
+export * from './node-data-context.js';
+export * from './preflight-result.js';
+export * from './graph-executor.js';
+export { compileGraphDefinition } from './graph-kernel.js';
+export * from './graph-plan.js';
+export * from './json.js';
+export * from './events/envelope.js';
+export * from './events/store.js';
+export * from './artifacts/store.js';
+export * from './storage/error.js';
+export * from './workspace/provider.js';
+export * from './workspace/policy.js';
+export * from './callback/gate.js';
+export * from './callback/client-contract.js';
+export type { NewCallbackHistoryEvent, StoredCallbackClient } from './callback/stored-client.js';
+export { ApprovalSubjectError, approvalSubjectDigest, createApprovalCallbackGate, validateApprovalRecord, validateApprovalSubject, snapshotApprovalSubject, assertApprovalPermissionsAdmitted, type ApprovalSubmission, type ApprovalSubjectInput, type ApprovalResolutionInput, type ApprovalSubject, type ApprovalBinding, type ApprovalRecord, type ApprovalEventPayload, type NewApprovalEvent, type PrepareApprovalRecordInput, } from './callback/approval.js';
+export type { ProofArtifactReference } from './proof/artifact.js';
+export type { CachedProofPacket, ProofCache, ProofCacheCurrentBinding, ProofCacheOptions, ProofJob, ProofPacket, ProofPacketSource, ProofSource, } from './proof/cache.js';
+export { acceptedResultMatches, validateAcceptedResultRecord, type AcceptedResultGraph, type AcceptedResultBindingInput, type AcceptedResultBinding, type AcceptedResultRecord, type AcceptedResultEventPayload, type NewAcceptedResultEvent, type CreateAcceptedResultRecordInput, type AcceptedResultResolution, } from './proof/acceptance.js';
+export { validateRunDefinition, validateRunStartRecord, validateRunStoragePolicy, validateRunStorageRecord, type StorageProviderRecord, type SensitiveContentPolicy, type RunStoragePolicy, type RunStorageRecord, type RunDefinition, type RunStartedPayload, type NewRunStartedEvent, type RunStartRecord, type RunStorageBinding, } from './run-definition.js';
+export { modelIdentity, type ModelIdentity } from './model-identity.js';
+export type { ReasoningEvent, ReasoningMessage, ReasoningOutcome, ReasoningRecorder, } from './reasoning-record-contract.js';