@obversa/runtime 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jonny Neill
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,192 @@
+# @obversa/runtime
+
+`@obversa/runtime` is a standalone TypeScript runtime. Obversa is one consumer;
+any host can use the public package API. The package also defines a pure graph
+contract for graph types outside this package.
+
+## Requirements
+
+- Node.js 22.12 or later
+
+## Build from the workspace
+
+From the workspace root, run:
+
+```bash
+corepack enable
+pnpm install --frozen-lockfile
+pnpm --filter @obversa/runtime build
+```
+
+## Usage
+
+```ts
+import { agentJob, run } from '@obversa/runtime';
+import { MockEngine } from '@obversa/runtime/testing';
+
+const engine = new MockEngine(() => 'ready');
+
+const result = await run(
+  agentJob({
+    label: 'prepare-item',
+    engine: 'offline',
+    prompt: 'Prepare the item.',
+  }),
+  {
+    engine: 'offline',
+    engines: { offline: engine },
+  },
+);
+
+console.log(result.outcome.status);
+```
+
+Expected output:
+
+```text
+pass
+```
+
+This package exposes the programmatic API. It does not expose a command.
+
+## Memory
+
+Pass a `Memory` instance in the run options when a job uses memory:
+
+```ts
+await run(job, { memory });
+```
+
+The runtime imports the `@obversa/api` memory port. Your program selects the storage
+adapter.
+
+With the Agent SDK engine, passing memory makes its one in-process memory tool
+available and automatically approved. Other tool settings do not change.
+
+## Define an outside graph type
+
+Use `GraphType` with `compileGraph` to define a pure graph type. The graph type
+validates a graph definition, reduces recorded events, returns graph commands,
+and describes a plan. The contract gives it frozen data and graph lookups, not
+file, model, process, clock, or storage services.
+
+An outside graph type is trusted package code. It can import and use effects by
+itself. The public conformance kit checks behavior. It does not stop effects.
+
+The host resolves the description with `resolveGraphPlan`. The host admission
+record must admit the package identity and every requested permission. The
+resolved plan records known bounds or an explicit unknown bound. Its frozen
+snapshot and digest identify the fixed package, permissions, lanes, policies,
+and bounds for one run.
+
+`validateGraphDescription(unknown)` validates a description without compiling
+a graph. It returns a frozen valid description or throws `GraphValidationError`.
+Each node must appear in one phase, and its `phaseId` must name that phase.
+Description nodes preserve definition node declaration order. The compiler
+supplies description edges in definition edge declaration order.
+
+The public conformance kit checks the initial state and command, then every
+event-prefix state and command. It uses separate compiled instances and
+repeated calls. It also checks the declared bounds. The kit counts dispatches
+across the supplied trace and the largest dispatch set in one decision. Known
+dispatch and fan-out maximums cannot be below those observed values. It does
+not infer runtime concurrency from a decision trace.
+Each expected decision contains only new requests. The kit rejects a dispatch
+position reused in a later expected decision. D5 applies the same rule to
+durable dispatch events before execution.
+When the final expected decision is exactly `complete`, the observed total must
+meet a known dispatch minimum; partial, empty, paused, and failed endings do not
+prove a minimum.
+
+A graph decision contains zero or more dispatch commands, or exactly one
+pause, complete, or fail command. Dispatches ask the executor to start new
+work. An empty decision starts no work. D5 accepts it only while a recorded
+attempt remains in flight; otherwise the executor fails instead of spinning.
+Each `position` is the stable logical identity and location of one requested
+node occurrence. Positions must be unique within one decision, so the same
+node can appear more than once at different positions. After an occurrence is
+recorded, the graph does not emit it again. A later event can make the same
+node dispatchable as a new occurrence with its own position.
+
+`run(job, { params })` accepts a JSON object. If `params` is `undefined`, it
+uses a frozen empty object. `null`, arrays, and other invalid roots fail before
+work or environment setup starts. A valid object is cloned and frozen. Every
+child job receives the same frozen object as `ctx.params`. A later caller
+change cannot change that object. JSON nested more than 256 levels fails with
+`JsonValueError`.
+
+Run the checked-in example from the workspace root:
+
+```bash
+pnpm example:graph
+```
+
+The example is `examples/custom-graph.ts`. It uses only public exports
+and runs the public graph conformance kit.
+
+This graph contract does not schedule nodes, store runs, provide built-in
+graph forms, or execute work on another machine.
+
+## Store events and artifacts
+
+Use `EventStore` for small append-only JSON events. Use `ArtifactStore` for
+larger byte content. An event can carry the returned artifact reference instead
+of copying the content into the event stream.
+
+Run the checked-in local-storage example from the workspace root:
+
+```bash
+pnpm example:storage
+```
+
+The example stores a 65 KB synthetic artifact, appends its 194-byte reference,
+reopens the same data through a fresh storage binding, folds the same state,
+and runs both public storage conformance kits. It stays offline and does not
+execute or resume graph work.
+
+Read [Events and artifacts](../../docs/public/storage/events-and-artifacts.mdx)
+for the port contracts, limits, secret rules, conflicts, and integrity checks.
+
+## Run safe node attempts
+
+`GrokCliEngine` and `OpenCodeCliEngine` each run one fresh CLI process for one
+bounded attempt. The checked-in example uses local scripted executables, so it
+does not call a model or the network.
+
+```bash
+pnpm example:attempt
+```
+
+The example validates a native Grok structured result and an OpenCode result
+parsed by the job. It also proves that missing usage remains `unknown`.
+
+Read [Safe node attempts](../../docs/public/runtime/node-attempts.mdx) for the
+public adapter contract and the D5 and D14 boundaries.
+
+## Resume graph attempts
+
+The graph executor records a start marker immediately before node code runs.
+A fresh executor returns `waiting` for a dispatch that has no result.
+
+Call `resume(position, signal)` after the earlier executor process stops. An
+unstarted attempt runs at the same position without a second dispatch event.
+A started attempt runs again only when its saved `retrySafe` rule permits it.
+The executor records a typed pause for all other started attempts.
+
+Read [Graph executor](../../docs/public/graphs/executor.mdx) for the public
+resume contract and the process-lock boundary.
+
+## Documentation
+
+The workspace `docs/public` directory contains the first-run guide, graph
+guides, storage guide, and the production-line bank.
+
+Run the offline production line from the workspace root:
+
+```bash
+pnpm example:offline
+```
+
+## License
+
+[MIT](LICENSE)

package/dist/api.d.ts

@@ -0,0 +1,72 @@
+/** Public programmatic API for the Obversa graph runtime. */
+export { briefFromFile, person, stage, workflow, type BriefSource, type NamedStage, type PersonRole, type WorkflowConfig, type WorkflowOptions, type WorkflowPostContext, type WorkflowRecord, type WorkflowRole, type WorkflowStage, } from './workflow.js';
+export type { TeamSeat } from '@obversa/api';
+export type { JsonPrimitive, JsonObject, JsonValue, RunBrief, Sha256Digest, GraphValidationIssue, } from './graph/value.js';
+export { JsonValueError } from './graph/value.js';
+export { GraphValidationError, type GraphId, type NodeId, type EdgeId, type GraphNode, type GraphEdge, type GraphDefinition, type CompiledGraphDefinition, type GraphKernel, } from './graph/kernel.js';
+export type { DispatchGraphCommand, PauseGraphCommand, CompleteGraphCommand, FailGraphCommand, GraphCommand, } from './graph/commands.js';
+export { compileGraph, type GraphEvent, type GraphEngineIdentity, type EngineAttemptRecordedPayload, type GraphBindings, type GraphTypeCompilation, type CompiledGraphType, type GraphType, } from './graph/type.js';
+export { dag as dagGraphType, type DagDefinition, } from './graph-types/dag.js';
+export { teamGraphType, type TeamNodeData, type TeamRoom, type TeamCommunication, type TeamGraphData, type TeamDefinition, type TeamPost, type TeamTurnResult, type TeamMessage, type TeamGraphResult, } from './graph-types/team.js';
+export { convergence, type ConvergenceDefinition, type ConvergenceEvent, type ConvergenceStatus, } from './graph-types/loop.js';
+export { createCallbackGate, callbackRequestDigest, validateCallbackRequest, validateCallbackResponse, type CallbackGateDefinition, type CallbackRequest, } from './callback/gate.js';
+export { createCallbackClient, replayCallbackClient, directRouter, validateCallbackEvent, type CallbackClient, type CallbackEvent, type ClaimResult, type SubmitResult, type ReleaseResult, type Responder, } from './callback/client.js';
+export { createStoredCallbackClient, type NewCallbackHistoryEvent, type StoredCallbackClient, } from './callback/stored-client.js';
+export { ApprovalSubjectError, approvalSubjectDigest, createApprovalCallbackGate, resolveApproval, validateApprovalRecord, type ApprovalBinding, type ApprovalEventPayload, type ApprovalRecord, type ApprovalResolutionInput, type ApprovalSubject, type ApprovalSubjectInput, type NewApprovalEvent, } from './callback/approval.js';
+export { acceptedResultMatches, createAcceptedResultRecord, resolveAcceptedResult, validateAcceptedResultRecord, type AcceptedResultBinding, type AcceptedResultBindingInput, type AcceptedResultEventPayload, type AcceptedResultGraph, type AcceptedResultRecord, type AcceptedResultResolution, type CreateAcceptedResultRecordInput, type NewAcceptedResultEvent, } from './proof/acceptance.js';
+export { writeProofArtifact, type ProofArtifactReference, } from './proof/artifact.js';
+export { createProofCache, type CachedProofPacket, type ProofCache, type ProofCacheCurrentBinding, type ProofCacheOptions, type ProofJob, type ProofPacket, type ProofPacketSource, type ProofSource, } from './proof/cache.js';
+export { createGraphExecutor, GraphExecutionError, type GraphExecutionErrorCode, type GraphNodeBinding, type GraphEngineBinding, type GraphExecutor, type GraphExecutorOptions, type GraphExecutorResult, } from './runtime/graph-executor.js';
+export { projectTeamRooms } from './runtime/team-rooms.js';
+export { resolveGraphPlan, validateGraphDescription, type PermissionDescriptor, type ExecutionTarget, type ExecutionLaneDescription, type GraphPhaseDescription, type GraphNodeDescription, type GraphEdgeDescription, type PlanBound, type GraphBounds, type GraphPolicyDescription, type GraphRequirements, type GraphDescriptionInput, type GraphDescription, type GraphPackageIdentity, type GraphPackageAdmission, type ExecutionLaneResolution, type RunPreflightPolicy, type PlanResolution, type ResolvedExecutionLane, type ResolvedPlan, type ResolvedPlanSnapshot, } from './graph/plan.js';
+export { StorageError, type StorageErrorCode, } from './storage/error.js';
+export { createGitWorktreeProvider, } from './workspace/git-provider.js';
+export type { WorkspaceProvider, WorkspaceAnchor, WorkspaceHeadDrift, WorkspaceFilesDrift, WorkspaceRepositoryDrift, WorkspaceDrift, VerifyResult, ForkOk, ForkChangedAnchor, ForkExists, ForkIncomplete, ForkUnleased, ForkNoRevision, ForkInvalidChild, ForkResult, LeaseClaimed, LeaseHeld, LeaseIncomplete, AcquireResult, WorkspaceReleaseResult, RecoverResult, } from './workspace/provider.js';
+export { validateDomainEventId, validateNewDomainEvent, validateDomainEventEnvelope, type DomainEventId, type EventStreamId, type StorageNamespace, type StreamRevision, type EventStreamRef, type NewDomainEvent, type DomainEventEnvelope, } from './events/envelope.js';
+export { validateDomainEventBatch, validateEventStreamRef, type DomainEventBatch, type EventStore, } from './events/store.js';
+export { validateArtifactReference, validateArtifactScope, validateNewArtifact, type ArtifactBatch, type ArtifactContentMode, type ArtifactScope, type NewArtifact, type ArtifactReference, type ArtifactStore, } from './artifacts/store.js';
+export { loadRunDefinition, persistRunDefinition, validateRunDefinition, validateRunStartRecord, validateRunStoragePolicy, validateRunStorageRecord, type StorageProviderRecord, type SensitiveContentPolicy, type RunStoragePolicy, type RunStorageRecord, type RunDefinition, type RunStartedPayload, type NewRunStartedEvent, type RunStartRecord, type RunStorageBinding, } from './runtime/run-definition.js';
+export { readRunPreflight, interruptRunPreflight, type RunPreflightState, type PreflightPauseResult, type PreflightFailureResult, } from './runtime/preflight-record.js';
+export type { AttemptBudgetPolicy, TokenBudget, } from './runtime/budget.js';
+export type { ActionDecision, AllowActionDecision, WaitActionDecision, DenyActionDecision, NodeDataContext, } from './runtime/node-lifecycle.js';
+export type { ResultContract } from './runtime/result-contract.js';
+export type { NodeWorkspacePolicy } from './runtime/workspace-policy.js';
+export type { Job, JobMeta, JobContext, Outcome, OutcomeStatus, FeedbackActionSeverity, FeedbackDecision, FeedbackFinding, FeedbackSeverity, RevisionRequest, RevisionRerun, GraphPosition, LimitPolicy, Condition, ConditionInput, ConditionResult, RawPredicate, LoopConfig, RetryPolicy, DagConfig, KickbackBudget, DagNode, LoopEvent, LogLevel, Workspace, ProofKind, ProofArtifact, ProofRecord, UsageTotals, } from './core/types.js';
+export { loop } from './core/loop.js';
+export { dag, sequence, parallel } from './core/dag.js';
+export { pipeline, type PipelineStage } from './core/pipeline.js';
+export { tournament, type TournamentConfig } from './core/tournament.js';
+export { team, type TeamAgent, type TeamAgentResult, type TeamConfig, type TeamResult, type TeamReview, } from './core/team.js';
+export { agentJob, fnJob, type FnJobResult, prove, kickback, revisionRequest, type AgentJobConfig, type AgentRoute, type ProofDescriptor, type ProofProducer, RECORDED_ENGINE_USAGE, type RecordedEngineUsage, } from './core/job.js';
+export { reviewPanel, reviewContext, type ReviewPanelConfig, type ReviewContextConfig, type RevisionRequestInput, } from './core/feedback.js';
+export { copyJobMeta, jobMeta, renderPlan, describeConditions } from './core/describe.js';
+export { assertGraph, type GraphShape, type GraphNodeShape, } from './core/assert-graph.js';
+export { defineAgent, defineSkill, fromFile, type AgentContractSummary, type AgentDef, type AgentFailureMode, type AgentOutputContract, type AgentSkillRef, type AgentTier, type Skill, } from './core/agent.js';
+export { defineAgentFromMarkdown } from './core/agent-md.js';
+export { isolated, type IsolatedOptions } from './core/isolated.js';
+export { confidenceCondition, confidenceFromText, lastDecisionLine, lastGateBrief, type ConfidenceConditionOptions, type LastDecisionLineOptions, type LastGateBriefOptions, } from './core/decision.js';
+export { toCondition, predicate, bodyPassed, minConfidence, commandSucceeds, all, any, not, quorum, always, never, agentCheck, gateJob, commandJob, passed, failed, type AgentCheckConfig, } from './core/condition.js';
+export { approval, type ApprovalAnswer, type ApprovalOptions } from './core/approval-job.js';
+export type { RunCallbacks } from './core/types.js';
+export type { RunMonitor, MonitorState, MonitorNodeState, MonitorNodePhase, MonitorKickback } from './runtime/monitor.js';
+export type { NoProgressConfig, NoProgressInput, StallReport, } from './core/progress.js';
+export { LoopError, type LoopErrorCode } from './core/errors.js';
+export type { BudgetConfig } from './core/budget.js';
+export type { Engine, EngineRef, EngineName, AgentRequest, AgentResult, AgentResultPart, EngineIncompleteResultEvidence, EngineSelectionRecord, EngineTransportFailure, EngineStreamEvent, Usage, UsageReceipt, } from './engines/engine.js';
+export { EngineError, EngineIncompleteResultError } from './engines/engine.js';
+export { finalResultPart, finalResultText, validateAgentResult, } from './runtime/result-parts.js';
+export type { Environment, EnvHandle } from './env/environment.js';
+export { withEnv } from './core/env-overlay.js';
+export { run, exitCodeFor, EXIT_PAUSED, type RunOptions, type RunResult, } from './runtime/runner.js';
+export { RESUME_STAGE_OUTCOMES } from './runtime/runner.js';
+export type { RecordedStage, ResumedStageRecords } from './runtime/persist.js';
+export { formatEvent } from './runtime/supervisor.js';
+export type { StatsSnapshot } from './core/stats.js';
+export { classifyEngineFailure, LANE_DEAD_FAILURES, type EngineFailureKind, } from './engines/failure.js';
+export { fallbackEngine, type FallbackOptions, type FallbackInfo, } from './engines/fallback.js';
+export { preflight, preflightEngine, formatPreflight, type PreflightResult, type PreflightOptions, } from './engines/preflight.js';
+export { costReport, formatCostReport, type PriceTable, type ModelPrice, type ModelCost, type CostReport, } from './core/cost.js';
+export { ratchet, writeScope, sampled, type RatchetOptions, type WriteScopeOptions, type SampledOptions, } from './core/guards.js';
+import type { Job } from './core/types.js';
+/** Preserve the exact `Job` type of a default export. */
+export declare function defineJob(job: Job): Job;