@obversa/runtime 0.1.0

package/dist/graph-types/loop.d.ts

@@ -0,0 +1,194 @@
+/**
+ * The convergence graph type (roadmap D7): fresh-context convergence with
+ * real done checks, narrow repair rounds, and no repeated reviews whose
+ * evidence is still valid.
+ *
+ * Nodes: `generator` (the body), `evaluator` (a data-only done gate), one
+ * node per review seat — seats are separate nodes, one node bound to one
+ * lane — and `repair` (the fixer). The convergence cycle is legal: repair
+ * re-enters the body.
+ *
+ * Terminal mapping (decided with the runtime owner): pass → `complete`;
+ * iterations, review restarts, or a recurring finding exhausted → `fail`
+ * with a typed exhaustion code; `ABORTED` → `pause` with a reason; and
+ * `ENGINE_UNAVAILABLE` skips a declared skippable seat or pauses a required
+ * seat. Other executor failures are not review verdicts: a seat that fails
+ * consumes no repair attempt, reruns within the declared retry cap, then
+ * pauses as unresolved. A skipped seat never weakens the remaining quorum
+ * and provider-diversity rules.
+ *
+ * This is the pure form only: definition validation, state reduction,
+ * decisions, bounds, and the plan description. Panel policy helpers,
+ * review acceptance records, and the source of evaluator fingerprints are
+ * the runtime owner's.
+ *
+ * Event vocabulary (all JSON, recorded into the durable `graph:`
+ * namespace):
+ * - `node-dispatched` / `node-completed` / `node-failed` /
+ *   `node-paused` / `node-resumed` — the standard node events; a seat's
+ *   completed result carries the verdict record: verdict (`pass` |
+ *   `findings` | `low-confidence`), confidence, the reviewed input hashes,
+ *   the workspace fingerprint, and any findings; provider and model-family
+ *   diversity comes from recorded engine reports. The evaluator's
+ *   completed result carries `gateMet` with the same evidence identity; the
+ *   generator's and repair's results carry the work summaries.
+ * - `engine-attempt-recorded` — one reported engine identity per call, or
+ *   unknown. Writer history excludes matching reviewer providers or model
+ *   families, including cached passes. Unknown writer fields count as all
+ *   declared targets for that field. Data-only nodes have no engine identity.
+ * - `seat-invalidated` — a seat's recorded verdict is no longer current
+ *   (watched paths or fingerprints changed): the seat reruns.
+ *
+ * A dispatch, completion, or failure counts only for the node's attempt
+ * currently in flight at that exact position; a stale event from an
+ * earlier attempt is ignored. Positions are minted per recorded dispatch:
+ * `convergence/${iteration}/${node}` for the loop nodes and
+ * `review/${round}/${seat}` for seats, so a retry or a rerun always takes
+ * a fresh position. Retry is graph policy, declared as a per-node cap:
+ * decide offers a fresh dispatch for a failed node while the cap allows,
+ * then a failed body node ends the run while an unresolved seat pauses it.
+ *
+ * Each review decision dispatches every seat that is pending or invalid
+ * and fits the declared seat concurrency, in declaration order. Seats
+ * whose recorded verdicts are still valid are never re-emitted — the D2
+ * rule that a graph does not re-emit an occurrence already recorded in
+ * the folded event history.
+ */
+import type { GraphDefinition, NodeId } from '../graph/kernel.js';
+import type { EngineAttemptRecordedPayload, GraphEvent, GraphType } from '../graph/type.js';
+import { type JsonObject, type JsonValue, type Sha256Digest } from '../graph/value.js';
+type ConvergenceExecutionTargetData = {
+    readonly adapter: string;
+    readonly provider: string;
+    readonly modelFamily: string;
+    readonly model: string;
+    readonly tools: readonly string[];
+};
+type ConvergenceExecutionLaneData = {
+    readonly id: string;
+    readonly requested: ConvergenceExecutionTargetData;
+    readonly knownSubstitutions: readonly ConvergenceExecutionTargetData[];
+};
+export type ConvergenceNodeData = JsonObject & {
+    /** `generator`, `evaluator`, `repair`, or `seat`. */
+    readonly role: 'generator' | 'evaluator' | 'repair' | 'seat';
+    /** Engine lane for this node; omit it for a data-only node. */
+    readonly lane?: ConvergenceExecutionLaneData;
+    /** Input-hash keys reviewed by this seat; omit to review every key. */
+    readonly evidencePaths?: readonly string[];
+};
+export interface ConvergenceEdgeData extends JsonObject {
+}
+export interface ConvergenceFinding extends JsonObject {
+    readonly id: string;
+    readonly kind: 'patch' | 'decision';
+    readonly evidence: string;
+}
+export interface ConvergenceData extends JsonObject {
+    /** Body iterations bound. */
+    readonly maxIterations: number;
+    /** Repair rounds bound. */
+    readonly maxReviewRestarts: number;
+    /** Valid passing seats required to accept. */
+    readonly quorum: number;
+    /** Require distinct providers and model families among accepted seats. */
+    readonly requireDiversity: boolean;
+    /** Seat node ids that may be skipped for exhausted credit. */
+    readonly skippableSeats: readonly string[];
+    /** Review seats dispatchable at once. */
+    readonly seatConcurrency: number;
+    /** Retries offered per failed node before a body failure or unresolved-seat pause. */
+    readonly retryCapPerNode: number;
+}
+export type ConvergenceDefinition = GraphDefinition<ConvergenceNodeData, ConvergenceEdgeData, ConvergenceData>;
+export interface NodeDispatchedPayload extends JsonObject {
+    readonly nodeId: NodeId;
+    readonly position: string;
+}
+export interface NodeCompletedPayload extends JsonObject {
+    readonly nodeId: NodeId;
+    readonly position: string;
+    readonly result: JsonValue;
+}
+export interface NodeFailedPayload extends JsonObject {
+    readonly nodeId: NodeId;
+    readonly position: string;
+    readonly code: string;
+}
+export interface NodePausedPayload extends JsonObject {
+    readonly nodeId: NodeId;
+    readonly position: string;
+    readonly reason: string;
+    readonly request: JsonValue;
+}
+export interface NodeResumedPayload extends JsonObject {
+    readonly nodeId: NodeId;
+    readonly position: string;
+}
+export interface LimitPausedPayload extends JsonObject {
+    readonly reason: string;
+}
+export interface SeatInvalidatedPayload extends JsonObject {
+    readonly seatId: NodeId;
+    readonly reason: string;
+}
+export type ConvergenceEvent = GraphEvent<'node-dispatched', NodeDispatchedPayload> | GraphEvent<'engine-attempt-recorded', EngineAttemptRecordedPayload> | GraphEvent<'node-completed', NodeCompletedPayload> | GraphEvent<'node-failed', NodeFailedPayload> | GraphEvent<'node-paused', NodePausedPayload> | GraphEvent<'node-resumed', NodeResumedPayload> | GraphEvent<'seat-invalidated', SeatInvalidatedPayload> | GraphEvent<'limit-paused', LimitPausedPayload>;
+export type LoopNodeStatus = 'pending' | 'in-flight' | 'paused' | 'passed' | 'failed';
+export interface LoopNodeState extends JsonObject {
+    readonly status: LoopNodeStatus;
+    readonly attempts: number;
+    readonly inFlight: string | null;
+}
+export type SeatOutcome = 'valid' | 'invalid' | 'skipped' | 'non-verdict' | null;
+export interface SeatRecord extends JsonObject {
+    readonly outcome: SeatOutcome;
+    readonly verdict: 'pass' | 'findings' | 'low-confidence' | null;
+    readonly confidence: number | null;
+    readonly provider: string | null;
+    readonly modelFamily: string | null;
+    readonly inputHashes: JsonObject | null;
+    readonly workspaceFingerprint: string | null;
+    readonly proofArtifactDigest: Sha256Digest | null;
+    readonly findings: readonly ConvergenceFinding[];
+    /** Set when the seat was invalidated while its attempt was in flight; the late verdict is discarded. */
+    readonly stale: boolean;
+}
+export interface EngineReceiptRejection extends JsonObject {
+    readonly code: 'INVALID_ENGINE_RECEIPT';
+    readonly nodeId: NodeId;
+    readonly position: string;
+    readonly sequence: number;
+    readonly reason: 'unsupported-version' | 'no-engine-lane' | 'not-in-flight' | 'position-mismatch' | 'sequence-mismatch';
+}
+export type ConvergenceStatus = JsonObject & {
+    readonly phase: 'body' | 'review' | 'settled';
+    readonly iteration: number;
+    readonly restarts: number;
+    readonly nodes: Readonly<Record<NodeId, LoopNodeState>>;
+    readonly seats: Readonly<Record<NodeId, SeatRecord>>;
+    /** Latest engine call at each recorded position. */
+    readonly engineAttempts: Readonly<Record<string, EngineAttemptRecordedPayload>>;
+    /** Scripted engine receipts refused by the reducer; absent until the first rejection. */
+    readonly engineReceiptRejections?: readonly EngineReceiptRejection[];
+    /** All reported writer identities, with declared targets for unknown fields. */
+    readonly writerProviders: readonly string[];
+    readonly writerModelFamilies: readonly string[];
+    readonly reviewEvidence: ConvergenceReviewEvidence | null;
+    /** Times each finding id has been reported across review rounds. */
+    readonly findingRounds: Readonly<Record<string, number>>;
+    /** A typed pause reason set by a limit or credit failure, or null. */
+    readonly pauseReason: string | null;
+};
+export interface ConvergenceReviewEvidence extends JsonObject {
+    readonly inputHashes: JsonObject;
+    readonly workspaceFingerprint: string;
+    readonly proofArtifactDigest: Sha256Digest;
+}
+export type ConvergenceRequirements = {
+    readonly memory: 'unused';
+};
+/**
+ * The convergence graph type. Pure data operations only (the D2 contract).
+ */
+export declare const convergence: GraphType<ConvergenceDefinition, ConvergenceStatus, ConvergenceEvent, ConvergenceRequirements>;
+export {};

package/dist/graph-types/team.d.ts

@@ -0,0 +1,68 @@
+import type { GraphDefinition } from '../graph/kernel.js';
+import type { ExecutionLaneDescription } from '../graph/plan.js';
+import type { GraphEvent, GraphType } from '../graph/type.js';
+import { type JsonObject, type JsonValue } from '../graph/value.js';
+export type TeamNodeData = JsonObject & {
+    role: string;
+    brief: string;
+    initialTurn?: boolean;
+    lane?: ExecutionLaneDescription;
+};
+export interface TeamRoom extends JsonObject {
+    id: string;
+    members: readonly string[];
+}
+export interface TeamCommunication extends JsonObject {
+    rooms: readonly TeamRoom[];
+    tailMessages: number;
+}
+export type TeamGraphData = JsonObject & {
+    task: string;
+    globalConcurrency: number;
+    maxTurnsPerMember: number;
+    communication?: TeamCommunication;
+};
+export type TeamDefinition = GraphDefinition<TeamNodeData, JsonObject, TeamGraphData>;
+export interface TeamPost extends JsonObject {
+    roomId: string;
+    text: string;
+    mentions: readonly string[];
+}
+export type TeamTurnResult = JsonObject & {
+    summary: string;
+    data?: JsonValue;
+    posts?: readonly TeamPost[];
+};
+export interface TeamMessage extends TeamPost {
+    id: string;
+    sender: string;
+    position: string;
+}
+export interface TeamGraphResult extends JsonObject {
+    task: string;
+    agents: readonly {
+        name: string;
+        role: string;
+        result: TeamTurnResult | null;
+    }[];
+}
+interface TeamMemberState extends JsonObject {
+    readonly status: 'idle' | 'in-flight' | 'paused' | 'failed';
+    readonly turns: number;
+    readonly inFlight: string | null;
+    readonly pauseReason: string | null;
+    readonly failureCode: string | null;
+    readonly result: TeamTurnResult | null;
+    readonly queued: boolean;
+    readonly triggers: readonly string[];
+}
+/** Saved messages are the accepted record for host room projections. */
+export interface TeamGraphState extends JsonObject {
+    readonly nodes: Readonly<Record<string, TeamMemberState>>;
+    readonly messages: readonly TeamMessage[];
+}
+/** Pure member turns; only matching saved completions deliver posts. */
+export declare const teamGraphType: GraphType<TeamDefinition, TeamGraphState, GraphEvent, {
+    readonly memory: 'unused';
+}>;
+export {};

package/dist/memory.d.ts

@@ -0,0 +1,82 @@
+import { type Memory, type MemoryError, type MemoryPath } from '@obversa/api';
+type Awaitable<T> = T | Promise<T>;
+export interface MemorySource {
+    readonly path: MemoryPath;
+    readonly optional?: boolean;
+}
+export interface GroundDocument {
+    readonly path: MemoryPath;
+    readonly text: string;
+    readonly truncated: boolean;
+}
+export interface GroundedMemory {
+    readonly documents: readonly GroundDocument[];
+    readonly missing: readonly MemoryPath[];
+    readonly prompt: string;
+}
+export interface GroundLimits {
+    readonly maxFiles: number;
+    readonly maxCharsPerFile: number;
+    readonly maxTotalChars: number;
+}
+export interface GroundOptions {
+    readonly sources: readonly MemorySource[];
+    readonly limits?: Partial<GroundLimits>;
+}
+export interface MechanicError {
+    readonly code: 'read_failed' | 'callback_failed' | 'invalid_callback_result' | 'write_failed';
+    readonly message: string;
+    readonly path?: MemoryPath;
+    readonly cause?: MemoryError;
+}
+export type MechanicResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly error: MechanicError;
+};
+export interface CurateRequest {
+    readonly intent: string;
+    readonly documents: readonly GroundDocument[];
+    readonly prompt: string;
+}
+export interface CurateDecision {
+    readonly brief: string;
+    readonly sources: readonly MemoryPath[];
+}
+export type CuratedMemory = {
+    readonly mode: 'curated';
+    readonly brief: string;
+    readonly sources: readonly MemoryPath[];
+    readonly prompt: string;
+} | {
+    readonly mode: 'grounded';
+    readonly reason: 'callback_failed' | 'invalid_decision';
+    readonly prompt: string;
+};
+export interface CurateOptions {
+    readonly intent: string;
+    readonly decide: (request: CurateRequest) => Awaitable<CurateDecision>;
+    readonly maxBriefChars?: number;
+}
+export interface ConsolidateRequest {
+    readonly prior: string | undefined;
+    readonly documents: readonly GroundDocument[];
+    readonly prompt: string;
+}
+export interface ConsolidatedMemory {
+    readonly target: MemoryPath;
+    readonly text: string;
+    readonly prompt: string;
+}
+export interface ConsolidateOptions {
+    readonly target: MemoryPath;
+    readonly sources: readonly MemorySource[];
+    readonly fold: (request: ConsolidateRequest) => Awaitable<string>;
+    readonly maxOutputChars?: number;
+}
+export declare function ground(memory: Memory, options: GroundOptions): Promise<MechanicResult<GroundedMemory>>;
+export declare function curate(grounded: GroundedMemory, options: CurateOptions): Promise<CuratedMemory>;
+export declare function consolidate(memory: Memory, options: ConsolidateOptions): Promise<MechanicResult<ConsolidatedMemory>>;
+export {};