ic-query 0.2.21

Internet Computer query CLI for NNS, SNS, and related public network metadata
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86

# 0.2 Design: Automatic SNS Proposal Cache

## Status

- Status: implemented for the 0.2.5 slice
- Decision style: command behavior and cache boundary
- Primary command: `icq sns proposals <id|root-principal>`

## Summary

SNS proposal listing now treats the complete local proposal snapshot as an
implementation detail for normal list views. If a compatible complete snapshot
exists, `icq sns proposals` reads it and applies view options locally. If the
snapshot is missing, the command visibly refreshes the complete collection,
publishes it only after governance pagination is exhausted, and then renders
the requested view.

Manual commands remain available:

```bash
icq sns proposals refresh 1
icq sns proposals cache list
icq sns proposals cache status 1
```

## Behavior

Automatic cache use applies when the requested view can be reproduced from the
cached proposal rows:

- `--limit`
- `--before`
- `--sort api`
- `--sort id`
- `--sort created`
- `--sort decided`
- `--sort executed`
- `--sort failed`
- `--asc`
- `--desc`
- `--status any`
- `--status open`
- `--status decided`
- `--status executed`
- `--status failed`

The existing bounded live path remains in use when the requested view cannot
yet be reproduced from cached rows without changing semantics:

- `--topic <topic>`
- `--status adopted`
- `--status rejected`

Those live fallbacks should move to cache-backed views once cached proposal
rows carry enough source detail to classify proposal topic and final adopted
versus rejected state locally.

## Cache Contract

The cache key describes the collected data, not the rendered view:

```text
domain: sns
network: ic
entity: <root-principal>
collection: proposals
scope: full
```

View options such as `--limit`, `--before`, `--sort`, `--asc`, `--desc`,
`--status`, `--topic`, `--verbose`, and `--format` do not change snapshot
identity.

Published cache files remain complete-only:

```text
.icq/sns/ic/<root-principal>/proposals/full.json
```

Refresh attempts remain separate:

```text
.icq/sns/ic/<root-principal>/proposals/full.refresh-attempt.json
```

If a refresh fails, the previous complete snapshot remains authoritative.