1export interface SubscriptionNode {
2  userId: number;
3  subscriptions: number[];
4  score?: bigint;
5}
6
7/**
8 * A patch batch fetched from one userId's on-chain BackupStorage history
9 * (spec §15.2: reads directly from BackupStorage.loadActions/loadActionsSince —
10 * no Arweave TX resolution, per O2).
11 *
12 * `raw` decoding is deferred until the web3-sdk / models_v2 / downloader_v2
13 * bundling (spec §16) — per explicit decision, O3 stays unresolved for now and
14 * `raw` is left fully opaque (O3 Option 2). Callers that need the decoded
15 * patch content import their own models_v2 codec against
16 * `raw as { compressedActions: bigint[]; indexes: bigint[]; stringIndexes: string[] }`.
17 */
18export interface Patch {
19  userId: number;
20  fromIndex: number;
21  toIndex: number;
22  raw: unknown;
23}
24
25export interface SubscriptionGraph {
26  rootUserId: number;
27  nodes: Map<number, SubscriptionNode>;
28  truncated: boolean;
29}
30
31export interface SyncResult {
32  patches: Patch[];
33  cursor: SyncCursor;
34  truncated: boolean;
35}
36
37/**
38 * Serializable — safe to persist in IndexedDB between sessions (spec §15.8).
39 * `patchIndex` replaces the original spec's arweaveTxId `Set<string>` with a
40 * per-userId last-delivered-index map, since patches are now on-chain and
41 * index-addressed (BackupStorage.loadActionsSince), not txId-addressed.
42 */
43export interface SyncCursor {
44  rootUserId: number;
45  knownNodes: Map<number, SubscriptionNode>;
46  countSnapshot: Map<number, number>;
47  patchIndex: Map<number, number>;
48}
49
50export interface WalkOptions {
51  maxNodes?: number;
52  maxDepth?: number;
53}
54
55export interface FetchOptions {
56  concurrency?: number;
57}
58
59export interface SyncOptions extends WalkOptions, FetchOptions {
60  cursor?: SyncCursor;
61}
62
63/**
64 * Carried forward from the original spec (§15.5, "unchanged") for API shape
65 * compatibility. Not wired into patch-resolver.ts today — the original
66 * motivation (avoid re-fetching immutable Arweave data by txId) doesn't map
67 * onto index-paginated on-chain reads, which are already cheap to re-issue.
68 * Left available for a future persistent cache if that changes.
69 */
70export interface PatchCacheAdapter {
71  get(key: string): Promise<Patch | undefined>;
72  set(key: string, patch: Patch): Promise<void>;
73}
74