@victframework/runtime 0.1.0

package/dist/store-validation.js

@@ -0,0 +1,164 @@
+import { canonicalJson, canonicalSemanticForm, canonicalSemanticFormV2, computeActivationVersion, computeCapabilitySetVersion, computeGraphVersion, } from '@victframework/kernel';
+import { VictStoreError } from './store-errors.js';
+/**
+ * Shared store-level identity validation, executed identically by every
+ * conforming adapter (in-memory and SQLite).
+ *
+ * Identity is CONTENT-derived (Stage 02): the three activation identities
+ * are SHA-256 fingerprints computed by the kernel's canonical identity
+ * functions. Stores therefore do not trust top-level strings — they
+ * recompute every identity from the canonical content and reject any
+ * disagreement with a structured, safe error and no partial mutation.
+ */
+function mismatch(operation, message, details) {
+    return new VictStoreError('VICT_STORE_ACTIVATION_MISMATCH', message, {
+        operation,
+        ...details,
+    });
+}
+/**
+ * Publish-time validation: the supplied canonical JSON must be exactly the
+ * canonical representation of the supplied manifest, and every
+ * content-derived identity must be reproducible from that content:
+ *
+ * - `manifest.graph` must already be the canonical semantic form of the
+ *   graph declaration;
+ * - `graphVersion` must equal the canonical fingerprint of that form;
+ * - `capabilitySetVersion` must equal the canonical fingerprint of the
+ *   effective bindings;
+ * - `activationVersion` must equal the canonical combination of the two.
+ *
+ * This catches manifests whose top-level identifiers look valid while the
+ * binding or graph content differs (the identity would not recompute).
+ */
+export function assertPublishableManifest(command) {
+    const manifest = command.manifest;
+    if (typeof command.canonicalManifest !== 'string' || command.canonicalManifest.length === 0) {
+        throw new VictStoreError('VICT_STORE_INVALID_COMMAND', 'A canonical manifest string is required.', { operation: 'catalog.publish' });
+    }
+    let recomputed;
+    try {
+        recomputed = canonicalJson(manifest);
+    }
+    catch {
+        throw new VictStoreError('VICT_STORE_INVALID_COMMAND', 'The manifest is not a persistable canonical value.', { operation: 'catalog.publish' });
+    }
+    if (recomputed !== command.canonicalManifest) {
+        throw mismatch('catalog.publish', 'The supplied canonical manifest is not the canonical representation of the supplied manifest.', { activationVersion: manifest.activationVersion });
+    }
+    const isV2 = manifest.graph?.schema === 'vict.graph@2';
+    let canonicalGraph;
+    try {
+        // canonicalSemanticForm is idempotent on an already-canonical graph;
+        // comparing its JSON against the stored form detects tampering.
+        canonicalGraph = isV2
+            ? canonicalSemanticFormV2(manifest.graph)
+            : canonicalSemanticForm(manifest.graph);
+    }
+    catch {
+        throw mismatch('catalog.publish', 'The manifest graph declaration is not in canonical semantic form.', { activationVersion: manifest.activationVersion });
+    }
+    if (canonicalJson(canonicalGraph) !== canonicalJson(manifest.graph)) {
+        throw mismatch('catalog.publish', 'The manifest graph declaration is not in canonical semantic form.', { activationVersion: manifest.activationVersion });
+    }
+    let graphVersion;
+    try {
+        graphVersion = computeGraphVersion(manifest.graph);
+    }
+    catch {
+        throw mismatch('catalog.publish', 'The graph version could not be recomputed from the manifest content.', { activationVersion: manifest.activationVersion });
+    }
+    if (graphVersion !== manifest.graphVersion) {
+        throw mismatch('catalog.publish', 'The manifest graphVersion does not match its graph content.', { activationVersion: manifest.activationVersion });
+    }
+    let capabilitySetVersion;
+    try {
+        capabilitySetVersion = computeCapabilitySetVersion(manifest.bindings);
+    }
+    catch {
+        throw mismatch('catalog.publish', 'The capability-set version could not be recomputed from the manifest bindings.', { activationVersion: manifest.activationVersion });
+    }
+    if (capabilitySetVersion !== manifest.capabilitySetVersion) {
+        throw mismatch('catalog.publish', 'The manifest capabilitySetVersion does not match its bindings.', { activationVersion: manifest.activationVersion });
+    }
+    const activationVersion = computeActivationVersion(graphVersion, capabilitySetVersion, graphVersion.startsWith('v2_') ? 'vict.activation@2' : 'vict.activation@1');
+    if (activationVersion !== manifest.activationVersion) {
+        throw mismatch('catalog.publish', 'The manifest activationVersion does not match its graph and capability-set versions.', { activationVersion: manifest.activationVersion });
+    }
+}
+/**
+ * Run-creation validation: the run's graph, graph version, capability-set
+ * version, and activation version must describe ONE coherent published
+ * activation — the exact stored one.
+ */
+export function assertRunMatchesActivation(stored, identity, operation) {
+    if (stored.graphId !== identity.graphId ||
+        stored.graphVersion !== identity.graphVersion ||
+        stored.capabilitySetVersion !== identity.capabilitySetVersion ||
+        stored.activationVersion !== identity.activationVersion) {
+        throw mismatch(operation, 'The run identity does not describe the referenced published activation.', {
+            activationVersion: identity.activationVersion,
+            graphId: identity.graphId,
+        });
+    }
+}
+/**
+ * Selection validation: an activation may only be selected for the graph it
+ * belongs to.
+ */
+export function assertActivationBelongsToGraph(stored, graphId, operation) {
+    if (stored.graphId !== graphId) {
+        throw mismatch(operation, 'The activation does not belong to the graph being selected for.', {
+            activationVersion: stored.activationVersion,
+            graphId,
+        });
+    }
+}
+/**
+ * Event-append validation: every appended event must carry exactly its
+ * stored run's identity columns.
+ */
+export function assertEventMatchesRun(event, run) {
+    if (event.runId !== run.runId ||
+        event.graphId !== run.graphId ||
+        event.graphVersion !== run.graphVersion ||
+        event.capabilitySetVersion !== run.capabilitySetVersion ||
+        event.activationVersion !== run.activationVersion) {
+        throw new VictStoreError('VICT_STORE_INVALID_COMMAND', 'An event references a different run or activation identity than the transition targets.', { operation: 'execution.appendEvents', runId: run.runId, eventRunId: event.runId });
+    }
+}
+/**
+ * Read-time validation for a stored activation: recompute every identity
+ * from the persisted canonical manifest and reject corrupt content instead
+ * of silently normalizing it. Used defensively on read paths.
+ */
+export function assertStoredActivationReadable(row) {
+    const fail = () => new VictStoreError('VICT_STORE_INVALID_RECORD', 'A stored activation manifest disagrees with its identity columns.', { operation: 'catalog.readActivation', activationVersion: row.activationVersion });
+    const manifest = row.manifest;
+    if (manifest.activationVersion !== row.activationVersion ||
+        manifest.graphId !== row.graphId ||
+        manifest.graphVersion !== row.graphVersion ||
+        manifest.capabilitySetVersion !== row.capabilitySetVersion) {
+        throw fail();
+    }
+    try {
+        const isV2 = manifest.graph?.schema === 'vict.graph@2';
+        const canonicalGraph = isV2
+            ? canonicalSemanticFormV2(manifest.graph)
+            : canonicalSemanticForm(manifest.graph);
+        if (canonicalJson(canonicalGraph) !== canonicalJson(manifest.graph) ||
+            computeGraphVersion(manifest.graph) !==
+                manifest.graphVersion ||
+            computeCapabilitySetVersion(manifest.bindings) !== manifest.capabilitySetVersion ||
+            computeActivationVersion(manifest.graphVersion, manifest.capabilitySetVersion, manifest.graphVersion.startsWith('v2_') ? 'vict.activation@2' : 'vict.activation@1') !== manifest.activationVersion) {
+            throw fail();
+        }
+    }
+    catch (cause) {
+        if (cause instanceof VictStoreError) {
+            throw cause;
+        }
+        throw fail();
+    }
+}
+//# sourceMappingURL=store-validation.js.map

package/dist/store-validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-validation.js","sourceRoot":"","sources":["../src/store-validation.ts"],"names":[],"mappings":"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"}

package/dist/stream-hub.d.ts

@@ -0,0 +1,151 @@
+import { type AgentStreamEvent } from '@victframework/contracts';
+import type { AgentStreamLedgerStore } from './control-types.js';
+/**
+ * Stage 06B — the neutral agent-stream hub (AI-009).
+ *
+ * One hub owns the per-stream event flow above a durable ledger:
+ *
+ * - every event is validated against the FINAL `vict.agent-stream@1`
+ *   field-level schema (fail closed on unknown kinds/fields);
+ * - sequence numbers are assigned by the durable ledger (strictly
+ *   monotonic per stream, survive restart);
+ * - durable kinds are persisted ledger rows; `text.delta` is transient and
+ *   lives only in the bounded replay buffer;
+ * - delivery is at-least-once in sequence order (clients deduplicate by
+ *   streamId + seq);
+ * - replay and live delivery use ISOLATED copies: no stored/frozen event
+ *   object is ever handed to a subscriber queue or mutated after publish;
+ * - backpressure coalesces CONSECUTIVE pending `text.delta` events for a
+ *   slow subscriber only, and never drops, reorders, or coalesces
+ *   non-delta events; a coalesced delta carries the cursor semantics of
+ *   the COMPLETE coalesced range (its sequence is the LAST combined
+ *   sequence, so a reconnect cannot re-deliver part of its text);
+ * - reconnect replays from a cursor: durable ledger rows plus buffered
+ *   transient deltas, detected against the AUTHORITATIVE ledger
+ *   high-watermark; a cursor older than the replayable transient content
+ *   reports `olderThanBuffer` so completed content is recovered from
+ *   durable state — including after a restart when the memory buffer is
+ *   empty;
+ * - a bounded subscriber queue that overflows follows an EXPLICIT
+ *   recoverable policy: the subscriber is detached through
+ *   `onOverflow()` and MUST reconnect/replay from its last acknowledged
+ *   cursor. Durable, control, and terminal events are never silently
+ *   discarded.
+ *
+ * The hub is transport-free: SSE belongs to `@victframework/server`.
+ */
+/** One hub subscriber (transport-owned delivery mechanism). */
+export interface AgentStreamSubscriber {
+    readonly subscriberId: string;
+    /**
+     * Deliver one event. Returning `false` signals backpressure: the hub
+     * switches this subscriber to buffered mode with delta coalescing until
+     * it drains via `pull()`.
+     */
+    deliver(event: AgentStreamEvent): boolean;
+    /**
+     * Called when the subscriber's bounded pending queue OVERFLOWS, immediately
+     * before the hub detaches the subscriber. The transport MUST recover by
+     * reconnecting/replaying from its last acknowledged cursor — the hub never
+     * silently discards events to fit the bound.
+     */
+    onOverflow?(): void;
+    /** Called when the subscriber is detached (clean completion or overflow). */
+    detach?(): void;
+}
+/** The reconnect cursor: stream identity + last processed sequence. */
+export interface AgentStreamCursor {
+    readonly streamId: string;
+    readonly lastSeq: number;
+}
+/** Replay/status disclosure for a reconnect (bounded-memory computation). */
+export interface AgentStreamReplayStatus {
+    /** The newest sequence the stream has assigned (ledger high-watermark). */
+    readonly newestSeq: number;
+    /**
+     * True when transient content after the cursor is no longer replayable:
+     * at least one sequence in `(lastSeq, newestSeq]` is neither a durable
+     * row nor a buffered transient delta (lost transient interval), so
+     * completed content must be restored from authoritative durable state.
+     * Detected against the ledger high-watermark — a fresh hub over the same
+     * ledger with an EMPTY memory buffer still reports the lost interval.
+     */
+    readonly olderThanBuffer: boolean;
+}
+/** Result of a materialized replay. */
+export interface AgentStreamReplay extends AgentStreamReplayStatus {
+    readonly events: readonly AgentStreamEvent[];
+}
+export interface AgentStreamHubOptions {
+    readonly ledger: AgentStreamLedgerStore;
+    /** Injected clock (epoch ms). */
+    readonly clock?: () => number;
+    /** Bounded transient replay buffer per stream (default 512). */
+    readonly transientBufferSize?: number;
+    /** Hard pending-queue bound per slow subscriber (default 4096 events). */
+    readonly pendingLimit?: number;
+    /** Ledger read page size for bounded-memory replay (default 256). */
+    readonly replayPageSize?: number;
+}
+export declare class AgentStreamHub {
+    #private;
+    constructor(options: AgentStreamHubOptions);
+    /**
+     * Validate and publish one event. Assigns the monotonic sequence via the
+     * durable ledger, persists durable kinds, buffers transient deltas, and
+     * delivers to subscribers. Throws (fail closed) on any schema-invalid
+     * event.
+     */
+    publish(event: Omit<AgentStreamEvent, 'seq'> & {
+        readonly seq?: number;
+    }): Promise<AgentStreamEvent>;
+    /**
+     * Subscribe to a stream and replay everything after the cursor: durable
+     * ledger rows plus buffered transient deltas, in strict sequence order.
+     *
+     * The subscriber is REGISTERED before the ledger is read, so a concurrent
+     * publish can never fall into the gap between the replay read and the
+     * live attachment: events published during the replay read are captured
+     * in the subscriber's private pending queue and delivered in sequence
+     * order as part of the backlog.
+     *
+     * Delivery is at-least-once and CURSOR-DEDUPLICATED. Backpressure NEVER
+     * discards events: the remaining backlog is buffered (bounded) for this
+     * subscriber and delivered through `pull()`. If the bounded pending
+     * queue overflows, the explicit recoverable policy applies: `onOverflow()`
+     * is called and the subscriber is detached (reconnect from the last
+     * acknowledged cursor).
+     */
+    subscribe(streamId: string, subscriber: AgentStreamSubscriber, cursor?: {
+        lastSeq?: number;
+    }): Promise<void>;
+    /** Detach a subscriber (clean completion/cancellation/overflow). */
+    unsubscribe(streamId: string, subscriberId: string): void;
+    /** Latest assigned sequence for a stream (ledger high-watermark). */
+    latestSeq(streamId: string): Promise<number>;
+    /**
+     * Drain the pending queue of a slow subscriber. Consecutive pending
+     * `text.delta` events are coalesced into one delta whose sequence is the
+     * LAST combined sequence (complete-range cursor semantics: a client that
+     * acknowledges the coalesced event acknowledges every delta inside it).
+     * Non-delta events are never dropped, reordered, or coalesced. Returned
+     * events are private copies of this subscriber's queue — coalescing never
+     * mutates any event that another consumer can observe.
+     */
+    pull(streamId: string, subscriberId: string): readonly AgentStreamEvent[];
+    /**
+     * Reconnect status WITHOUT materializing the replay: ledger high-watermark
+     * plus exact transient-gap detection against the durable rows. Bounded
+     * memory: the durable coverage is counted page by page.
+     */
+    replayStatus(cursor: AgentStreamCursor): Promise<AgentStreamReplayStatus>;
+    /**
+     * Materialized replay for reconnect: durable ledger rows plus buffered
+     * transient deltas after the cursor, in strict sequence order. The
+     * returned events are private copies; `olderThanBuffer` is detected
+     * against the authoritative ledger high-watermark (exact, restart-safe).
+     * For arbitrarily large histories prefer `replayIterate`/`replayStatus`,
+     * which never materialize the whole range.
+     */
+    replay(cursor: AgentStreamCursor): Promise<AgentStreamReplay>;
+}