harnery 0.33.0 → 0.34.0

package/dist/core/events/v3/projection.d.ts

@@ -0,0 +1,101 @@
+import type { ReadLedgerV3Result } from "./reader.js";
+export declare const EVENT_V3_SAFETY_REDUCER_BUILD: "event-v3-safety-reducer-v2";
+export type SafetyProjectionDiagnosticCodeV3 = "ledger_incomplete" | "duplicate_session_start" | "terminal_without_start" | "event_after_terminal" | "transition_without_live_subject" | "transition_prior_mismatch" | "authority_attribution_unverified" | "wait_end_without_start" | "claim_acquire_conflict" | "claim_release_without_acquire" | "decision_prior_mismatch" | "delegation_duplicate_start" | "delegation_complete_without_start" | "delegation_identity_mismatch";
+export interface SafetyProjectionDiagnosticV3 {
+    code: SafetyProjectionDiagnosticCodeV3;
+    event_id?: string;
+    generation_id?: string;
+    subject_instance_id?: string;
+    source_code?: string;
+    authority_blocking: boolean;
+}
+export interface WaitProjectionV3 {
+    wait_id: string;
+    kind: string;
+    started_event_id: string;
+    started_at: string;
+    authority_reference?: string;
+    wake_at?: string;
+}
+export interface GenerationSafetyStateV3 {
+    generation_id: string;
+    instance_id: string;
+    session_id: string;
+    started_event_id: string;
+    started_at: string;
+    last_observed_at: string;
+    attestation_id: string;
+    phase: "live" | "terminal";
+    activity: "working" | "needs_input" | "idle" | "terminal";
+    last_event_id: string;
+    last_segment_ordinal: number;
+    last_byte_offset: number;
+    task_state?: string;
+    task_state_updated_at?: string;
+    lifecycle_state?: string;
+    lifecycle_state_updated_at?: string;
+    presence_state?: string;
+    presence_state_updated_at?: string;
+    provisional_termination?: {
+        observation: string;
+        event_id: string;
+        observed_at: string;
+    };
+    terminal?: {
+        event_id: string;
+        observed_at: string;
+        outcome: string;
+        authority: "native" | "approved";
+        reason: string;
+    };
+    waits: Record<string, WaitProjectionV3>;
+    progress_event_ids: string[];
+    last_context_event_id?: string;
+    resume_count: number;
+}
+export interface ClaimProjectionV3 {
+    key: string;
+    subject_instance_id: string;
+    actor_instance_id: string;
+    target_digest: string;
+    target_kind: string;
+    target_display?: string;
+    access: "read" | "write";
+    acquired_event_id: string;
+    transaction_id: string;
+}
+export interface DelegationProjectionV3 {
+    delegation_id: string;
+    parent_generation_id: string;
+    child_generation_id: string;
+    role: string;
+    started_event_id: string;
+    completed_event_id?: string;
+    outcome?: string;
+}
+export interface SafetyProjectionV3 {
+    reducer_build_id: typeof EVENT_V3_SAFETY_REDUCER_BUILD;
+    evidence_complete: boolean;
+    history_complete: boolean;
+    authority_safe: boolean;
+    diagnostics: SafetyProjectionDiagnosticV3[];
+    generations: Record<string, GenerationSafetyStateV3>;
+    current_generation_by_instance: Record<string, string>;
+    claims: Record<string, ClaimProjectionV3>;
+    delegations: Record<string, DelegationProjectionV3>;
+    decisions: Record<string, string>;
+    identities: Record<string, string>;
+    health: Record<string, {
+        severity: string;
+        condition: string;
+        event_id: string;
+    }>;
+}
+/**
+ * Deterministically fold only contract-validated V3 rows. Physical ledger
+ * order is authoritative; wall-clock values are display evidence, never the
+ * conflict-resolution key. An incomplete source makes authority reads fail
+ * closed even when the unaffected portions can still be shown diagnostically.
+ */
+export declare function reduceSafetyProjectionV3(read: ReadLedgerV3Result): SafetyProjectionV3;
+//# sourceMappingURL=projection.d.ts.map

package/dist/core/events/v3/projection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"projection.d.ts","sourceRoot":"","sources":["../../../../src/core/events/v3/projection.ts"],"names":[],"mappings":"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"}

package/dist/core/events/v3/projection.js

@@ -0,0 +1,479 @@
+export const EVENT_V3_SAFETY_REDUCER_BUILD = "event-v3-safety-reducer-v2";
+const MAX_PROJECTION_DIAGNOSTICS = 256;
+/**
+ * Deterministically fold only contract-validated V3 rows. Physical ledger
+ * order is authoritative; wall-clock values are display evidence, never the
+ * conflict-resolution key. An incomplete source makes authority reads fail
+ * closed even when the unaffected portions can still be shown diagnostically.
+ */
+export function reduceSafetyProjectionV3(read) {
+    const projection = {
+        reducer_build_id: EVENT_V3_SAFETY_REDUCER_BUILD,
+        evidence_complete: read.complete,
+        history_complete: true,
+        authority_safe: true,
+        diagnostics: [],
+        generations: {},
+        current_generation_by_instance: {},
+        claims: {},
+        delegations: {},
+        decisions: {},
+        identities: {},
+        health: {},
+    };
+    for (const diagnostic of read.diagnostics) {
+        const authorityBlocking = authorityBlockingLedgerDiagnostic(diagnostic.code);
+        if (authorityBlocking)
+            projection.history_complete = false;
+        projection.diagnostics.push({
+            code: "ledger_incomplete",
+            source_code: diagnostic.code,
+            event_id: diagnostic.event_id,
+            authority_blocking: authorityBlocking,
+        });
+    }
+    for (const positioned of read.events)
+        applyEvent(projection, positioned);
+    projection.authority_safe =
+        projection.history_complete &&
+            !projection.diagnostics.some((diagnostic) => diagnostic.authority_blocking);
+    return projection;
+}
+function applyEvent(projection, positioned) {
+    const event = positioned.event;
+    if (event.event_type === "session.started") {
+        applySessionStart(projection, positioned, event);
+        return;
+    }
+    switch (event.event_type) {
+        case "ledger.genesis":
+        case "ledger.activated":
+        case "ledger.schema_advanced":
+        case "ledger.comparability_advanced":
+            return;
+        case "coord.task_changed":
+            applySubjectTransition(projection, positioned, event, "task_state");
+            return;
+        case "coord.lifecycle_changed":
+            applySubjectTransition(projection, positioned, event, "lifecycle_state");
+            return;
+        case "coord.presence_changed":
+            applySubjectTransition(projection, positioned, event, "presence_state");
+            return;
+        case "coord.claim_changed":
+            applyClaim(projection, event);
+            return;
+        case "decision.state_changed":
+            if (!authorityAttributionVerified(event)) {
+                addDiagnostic(projection, {
+                    code: "authority_attribution_unverified",
+                    event_id: event.event_id,
+                });
+                return;
+            }
+            if (event.payload.prior_state !== undefined &&
+                projection.decisions[event.payload.decision_id] !== event.payload.prior_state) {
+                addDiagnostic(projection, {
+                    code: "decision_prior_mismatch",
+                    event_id: event.event_id,
+                });
+                return;
+            }
+            projection.decisions[event.payload.decision_id] = event.payload.new_state;
+            return;
+        case "coord.identity_attested":
+            if (!authorityAttributionVerified(event, event.payload.subject_instance_id)) {
+                addDiagnostic(projection, {
+                    code: "authority_attribution_unverified",
+                    event_id: event.event_id,
+                    subject_instance_id: event.payload.subject_instance_id,
+                });
+                return;
+            }
+            projection.identities[event.payload.subject_instance_id] = event.payload.identity_id;
+            return;
+        case "health.observed":
+            projection.health[event.payload.subsystem] = {
+                severity: event.payload.severity,
+                condition: event.payload.condition,
+                event_id: event.event_id,
+            };
+            return;
+        case "health.capability_drift":
+            // Emitted after session.ended on purpose (payload.generation_ended).
+            // Must not take the generation-scoped event_after_terminal path, which
+            // fail-closes the whole ledger and blocks every agent from editing files.
+            projection.health[`capability:${event.payload.signal}`] = {
+                severity: "warning",
+                condition: event.payload.signal,
+                event_id: event.event_id,
+            };
+            return;
+        case "session.termination_observed":
+            applyProvisionalTermination(projection, event);
+            return;
+        case "lifecycle.sweep_observed":
+            applySweepObservation(projection, event);
+            return;
+        case "agent.started":
+            applyAgentStarted(projection, event);
+            return;
+        case "agent.completed":
+            applyAgentCompleted(projection, event);
+            return;
+    }
+    const generationId = generationIdOf(event);
+    if (!generationId)
+        return;
+    const state = projection.generations[generationId];
+    if (!state) {
+        if (event.event_type === "session.ended") {
+            addDiagnostic(projection, {
+                code: "terminal_without_start",
+                event_id: event.event_id,
+                generation_id: generationId,
+            });
+        }
+        return;
+    }
+    if (state.phase === "terminal") {
+        addDiagnostic(projection, {
+            code: "event_after_terminal",
+            event_id: event.event_id,
+            generation_id: generationId,
+        });
+        return;
+    }
+    touch(state, positioned);
+    switch (event.event_type) {
+        case "session.ended":
+            if (!authorityAttributionVerified(event, state.instance_id)) {
+                addDiagnostic(projection, {
+                    code: "authority_attribution_unverified",
+                    event_id: event.event_id,
+                    generation_id: generationId,
+                    subject_instance_id: state.instance_id,
+                });
+                return;
+            }
+            state.phase = "terminal";
+            state.activity = "terminal";
+            state.terminal = {
+                event_id: event.event_id,
+                observed_at: event.time.observed_at,
+                outcome: event.payload.outcome,
+                authority: event.payload.authority,
+                reason: event.payload.reason,
+            };
+            state.waits = {};
+            retargetCurrentGeneration(projection, state.instance_id, generationId);
+            return;
+        case "session.resumed":
+            state.provisional_termination = undefined;
+            state.resume_count += 1;
+            state.activity = "working";
+            return;
+        case "session.attestation_changed":
+            state.attestation_id = event.attestation_id;
+            return;
+        case "wait.started":
+            if (!authorityAttributionVerified(event, state.instance_id)) {
+                addDiagnostic(projection, {
+                    code: "authority_attribution_unverified",
+                    event_id: event.event_id,
+                    generation_id: generationId,
+                    subject_instance_id: state.instance_id,
+                });
+                return;
+            }
+            state.waits[event.payload.wait_id] = {
+                wait_id: event.payload.wait_id,
+                kind: event.payload.kind,
+                started_event_id: event.event_id,
+                started_at: event.time.observed_at,
+                authority_reference: event.payload.authority_reference,
+                wake_at: event.payload.wake_at,
+            };
+            state.activity = "needs_input";
+            return;
+        case "wait.ended":
+            if (!authorityAttributionVerified(event, state.instance_id)) {
+                addDiagnostic(projection, {
+                    code: "authority_attribution_unverified",
+                    event_id: event.event_id,
+                    generation_id: generationId,
+                    subject_instance_id: state.instance_id,
+                });
+                return;
+            }
+            if (!state.waits[event.payload.wait_id]) {
+                addDiagnostic(projection, {
+                    code: "wait_end_without_start",
+                    event_id: event.event_id,
+                    generation_id: generationId,
+                });
+                return;
+            }
+            delete state.waits[event.payload.wait_id];
+            state.activity = Object.keys(state.waits).length === 0 ? "working" : "needs_input";
+            return;
+        case "turn.started":
+        case "tool.requested":
+        case "command.started":
+            state.activity = "working";
+            return;
+        case "turn.completed":
+            state.activity = "idle";
+            return;
+        case "progress.observed":
+            state.progress_event_ids.push(event.event_id);
+            return;
+        case "context.observed":
+        case "context.compaction_started":
+        case "context.compaction_completed":
+        case "context.checkpointed":
+        case "context.recovery_injected":
+            state.last_context_event_id = event.event_id;
+            return;
+    }
+}
+function applySessionStart(projection, positioned, event) {
+    const scope = event.scope;
+    const generationId = scope.generation_id;
+    if (projection.generations[generationId]) {
+        addDiagnostic(projection, {
+            code: "duplicate_session_start",
+            event_id: event.event_id,
+            generation_id: generationId,
+        });
+        return;
+    }
+    projection.generations[generationId] = {
+        generation_id: generationId,
+        instance_id: scope.instance_id,
+        session_id: scope.session_id,
+        started_event_id: event.event_id,
+        started_at: event.time.observed_at,
+        last_observed_at: event.time.observed_at,
+        attestation_id: event.attestation_id,
+        phase: "live",
+        activity: "idle",
+        last_event_id: event.event_id,
+        last_segment_ordinal: positioned.position.segment_ordinal,
+        last_byte_offset: positioned.position.byte_offset,
+        waits: {},
+        progress_event_ids: [],
+        resume_count: 0,
+    };
+    projection.current_generation_by_instance[scope.instance_id] = generationId;
+}
+function applySubjectTransition(projection, positioned, event, field) {
+    const subject = event.payload.subject_instance_id;
+    if (!authorityAttributionVerified(event, subject)) {
+        addDiagnostic(projection, {
+            code: "authority_attribution_unverified",
+            event_id: event.event_id,
+            subject_instance_id: subject,
+        });
+        return;
+    }
+    const generationId = projection.current_generation_by_instance[subject];
+    const state = generationId ? projection.generations[generationId] : undefined;
+    if (state?.phase !== "live") {
+        addDiagnostic(projection, {
+            code: "transition_without_live_subject",
+            event_id: event.event_id,
+            subject_instance_id: subject,
+            generation_id: generationId,
+        });
+        return;
+    }
+    if (event.payload.prior_state !== undefined && event.payload.prior_state !== state[field]) {
+        addDiagnostic(projection, {
+            code: "transition_prior_mismatch",
+            event_id: event.event_id,
+            subject_instance_id: subject,
+            generation_id: generationId,
+        });
+        return;
+    }
+    state[field] = event.payload.new_state;
+    if (field === "task_state")
+        state.task_state_updated_at = event.time.observed_at;
+    if (field === "lifecycle_state")
+        state.lifecycle_state_updated_at = event.time.observed_at;
+    if (field === "presence_state")
+        state.presence_state_updated_at = event.time.observed_at;
+    touch(state, positioned);
+}
+function applyClaim(projection, event) {
+    if (event.payload.operation === "denied")
+        return;
+    if (!authorityAttributionVerified(event, event.payload.subject_instance_id)) {
+        addDiagnostic(projection, {
+            code: "authority_attribution_unverified",
+            event_id: event.event_id,
+            subject_instance_id: event.payload.subject_instance_id,
+        });
+        return;
+    }
+    const key = [
+        event.payload.subject_instance_id,
+        event.payload.target.fingerprint.digest,
+        event.payload.access,
+    ].join("\0");
+    if (event.payload.operation === "released") {
+        if (!projection.claims[key]) {
+            addDiagnostic(projection, {
+                code: "claim_release_without_acquire",
+                event_id: event.event_id,
+                subject_instance_id: event.payload.subject_instance_id,
+            });
+            return;
+        }
+        delete projection.claims[key];
+        return;
+    }
+    const generationId = projection.current_generation_by_instance[event.payload.subject_instance_id];
+    const subject = generationId ? projection.generations[generationId] : undefined;
+    if (subject?.phase !== "live") {
+        addDiagnostic(projection, {
+            code: "transition_without_live_subject",
+            event_id: event.event_id,
+            subject_instance_id: event.payload.subject_instance_id,
+            generation_id: generationId,
+        });
+        return;
+    }
+    const held = projection.claims[key];
+    if (held && held.subject_instance_id !== event.payload.subject_instance_id) {
+        addDiagnostic(projection, {
+            code: "claim_acquire_conflict",
+            event_id: event.event_id,
+            subject_instance_id: event.payload.subject_instance_id,
+        });
+        return;
+    }
+    // A re-acquire by the current holder is idempotent (the guard may re-assert
+    // a holding it cannot see across an epoch boundary): refresh, never conflict.
+    projection.claims[key] = {
+        key,
+        subject_instance_id: event.payload.subject_instance_id,
+        actor_instance_id: event.payload.actor_instance_id,
+        target_digest: event.payload.target.fingerprint.digest,
+        target_kind: event.payload.target.kind,
+        target_display: event.payload.target.display,
+        access: event.payload.access,
+        acquired_event_id: event.event_id,
+        transaction_id: event.payload.authority.transaction_id,
+    };
+}
+function applyProvisionalTermination(projection, event) {
+    const generationId = projection.current_generation_by_instance[event.payload.subject_instance_id];
+    const state = generationId ? projection.generations[generationId] : undefined;
+    if (state?.phase !== "live")
+        return;
+    state.provisional_termination = {
+        observation: event.payload.observation,
+        event_id: event.event_id,
+        observed_at: event.time.observed_at,
+    };
+}
+function applySweepObservation(projection, event) {
+    const generationId = projection.current_generation_by_instance[event.payload.subject_instance_id];
+    const state = generationId ? projection.generations[generationId] : undefined;
+    if (state?.phase !== "live")
+        return;
+    state.provisional_termination = {
+        observation: event.payload.observation,
+        event_id: event.event_id,
+        observed_at: event.time.observed_at,
+    };
+}
+function applyAgentStarted(projection, event) {
+    if (projection.delegations[event.payload.delegation_id]) {
+        addDiagnostic(projection, {
+            code: "delegation_duplicate_start",
+            event_id: event.event_id,
+            generation_id: generationIdOf(event),
+        });
+        return;
+    }
+    projection.delegations[event.payload.delegation_id] = {
+        delegation_id: event.payload.delegation_id,
+        parent_generation_id: generationIdOf(event),
+        child_generation_id: event.payload.child_generation_id,
+        role: event.payload.role,
+        started_event_id: event.event_id,
+    };
+}
+function applyAgentCompleted(projection, event) {
+    const delegation = projection.delegations[event.payload.delegation_id];
+    if (!delegation) {
+        addDiagnostic(projection, {
+            code: "delegation_complete_without_start",
+            event_id: event.event_id,
+            generation_id: generationIdOf(event),
+        });
+        return;
+    }
+    if (delegation.child_generation_id !== event.payload.child_generation_id) {
+        addDiagnostic(projection, {
+            code: "delegation_identity_mismatch",
+            event_id: event.event_id,
+            generation_id: generationIdOf(event),
+        });
+        return;
+    }
+    delegation.completed_event_id = event.event_id;
+    delegation.outcome = event.payload.outcome;
+}
+function generationIdOf(event) {
+    return "generation_id" in event.scope ? event.scope.generation_id : undefined;
+}
+function touch(state, positioned) {
+    state.last_event_id = positioned.event.event_id;
+    state.last_observed_at = positioned.event.time.observed_at;
+    state.last_segment_ordinal = positioned.position.segment_ordinal;
+    state.last_byte_offset = positioned.position.byte_offset;
+}
+/**
+ * A superseded twin (same instance, later generation, then session.ended)
+ * must not leave `current_generation_by_instance` pointing at the terminal
+ * row. The surviving live sibling stays the instance's current generation so
+ * whoami/set-task can still see it.
+ */
+function retargetCurrentGeneration(projection, instanceId, endedGenerationId) {
+    if (projection.current_generation_by_instance[instanceId] !== endedGenerationId)
+        return;
+    const survivor = Object.values(projection.generations)
+        .filter((generation) => generation.instance_id === instanceId &&
+        generation.phase === "live" &&
+        generation.generation_id !== endedGenerationId)
+        .sort((left, right) => right.last_observed_at.localeCompare(left.last_observed_at) ||
+        right.generation_id.localeCompare(left.generation_id))[0];
+    if (survivor) {
+        projection.current_generation_by_instance[instanceId] = survivor.generation_id;
+        return;
+    }
+    delete projection.current_generation_by_instance[instanceId];
+}
+function addDiagnostic(projection, diagnostic) {
+    projection.history_complete = false;
+    projection.authority_safe = false;
+    if (projection.diagnostics.length < MAX_PROJECTION_DIAGNOSTICS) {
+        projection.diagnostics.push({ ...diagnostic, authority_blocking: true });
+    }
+}
+function authorityBlockingLedgerDiagnostic(code) {
+    return (code !== "unresolved_attestation" &&
+        code !== "wall_clock_regression_unmarked" &&
+        code !== "monotonic_clock_regression");
+}
+function authorityAttributionVerified(event, subjectInstanceId) {
+    const attribution = event.provenance.attribution;
+    return (attribution.state === "verified" &&
+        (attribution.subject_instance_id === undefined ||
+            subjectInstanceId === undefined ||
+            attribution.subject_instance_id === subjectInstanceId));
+}

package/dist/core/events/v3/reader.d.ts

@@ -0,0 +1,75 @@
+import type { EventV3 } from "./contract.js";
+import { type EventV3RecoveryFailure, type EventV3RecoveryReceipt } from "./recovery-record.js";
+export type LedgerDiagnosticCodeV3 = "malformed_json" | "partial_final_frame" | "unsupported_major" | "invalid_contract" | "unsupported_schema_digest" | "unexpected_schema_digest" | "noncanonical_frame" | "conflicting_event_id" | "causal_parent_missing" | "wall_clock_regression_unmarked" | "monotonic_clock_regression" | "producer_sequence_gap" | "unresolved_attestation" | "missing_genesis" | "multiple_genesis" | "genesis_not_first" | "genesis_digest_mismatch" | "missing_activation" | "activation_genesis_mismatch" | "advance_prior_mismatch" | "advance_reader_incompatible" | "advance_digest_unsupported" | "advance_boundary_invalid" | "advance_boundary_missed" | "cursor_genesis_mismatch" | "cursor_position_missing" | "catalog_invalid" | "missing_segment" | "segment_digest_mismatch" | "manifest_digest_mismatch" | "manifest_segment_mismatch" | "active_replaced" | "recovery_record_invalid";
+export interface LedgerDiagnosticV3 {
+    code: LedgerDiagnosticCodeV3;
+    byte_offset: number;
+    segment_ordinal: number;
+    event_id?: string;
+}
+export interface LedgerFrameV3 {
+    raw: string;
+    position: {
+        segment_ordinal: number;
+        byte_offset: number;
+    };
+}
+export interface PositionedEventV3 {
+    event: EventV3;
+    position: LedgerFrameV3["position"];
+}
+export interface SchemaAdvanceV3 {
+    event_id: string;
+    prior_schema_digest: string;
+    next_schema_digest: string;
+    effective_position: LedgerFrameV3["position"];
+}
+export interface ReadLedgerV3Options {
+    authority?: "candidate" | "active";
+    reader_build?: string;
+    accepted_schema_digests?: readonly string[];
+}
+export interface ReadLedgerV3Result {
+    events: PositionedEventV3[];
+    diagnostics: LedgerDiagnosticV3[];
+    complete: boolean;
+    genesis_id?: string;
+    active_schema_digest?: string;
+    advances: SchemaAdvanceV3[];
+    bytes: number;
+    failed_epochs?: EventV3RecoveryReceipt[];
+}
+export interface LedgerCursorV3 {
+    genesis_id: string;
+    segment_ordinal: number;
+    byte_offset: number;
+    event_id: string;
+}
+export interface ReadLedgerV3SinceResult extends ReadLedgerV3Result {
+    cursor?: LedgerCursorV3;
+    reset_required: boolean;
+}
+/** Inspect one failed active authority without weakening the canonical read boundary. */
+export declare function inspectInvalidActiveAuthorityV3(coordRoot: string, controlReason: string): EventV3RecoveryFailure;
+/** Hash one preserved V3 authority by relative path, byte count, and file digest. */
+export declare function digestEventV3AuthorityDirectoryV3(root: string): `sha256:${string}`;
+export declare const EVENT_V3_LEDGER_RELATIVE_ROOT: ".harnery/ledgers/v3";
+export declare function eventV3Paths(coordRoot: string): {
+    root: string;
+    active: string;
+    catalog: string;
+    segments: string;
+};
+/** Stable file target for change notification only; reads still go through readLedgerV3. */
+export declare function eventV3ActiveWatchPath(coordRoot: string): string;
+/** Read the complete V3 ledger through catalog-bound filesystem discovery. */
+export declare function readLedgerV3(coordRoot: string, options?: ReadLedgerV3Options): ReadLedgerV3Result;
+export declare function readLedgerV3Since(coordRoot: string, cursor?: LedgerCursorV3, options?: ReadLedgerV3Options): ReadLedgerV3SinceResult;
+/**
+ * Validate an already-discovered V3 event stream in exact physical order.
+ * Filesystem/catalog discovery feeds this boundary; every downstream reader
+ * and projection consumes its positioned, authority-checked result.
+ */
+export declare function readLedgerFramesV3(frames: readonly LedgerFrameV3[], options?: ReadLedgerV3Options): ReadLedgerV3Result;
+export declare function readLedgerFramesV3Since(frames: readonly LedgerFrameV3[], cursor?: LedgerCursorV3, options?: ReadLedgerV3Options): ReadLedgerV3SinceResult;
+//# sourceMappingURL=reader.d.ts.map

package/dist/core/events/v3/reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reader.d.ts","sourceRoot":"","sources":["../../../../src/core/events/v3/reader.ts"],"names":[],"mappings":"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"}