weflow-cli 1.6.4 → 1.7.0

package/scripts/export_chat_html.py

@@ -124,6 +124,12 @@ VOICE_STATE = {'map': {}, 'cache': None}
 # runs a throwaway formatting pass that only records the URLs (0.1s, no
 # network), fetches them concurrently, then formats for real against a warm
 # cache. Set to a list during that pass; None otherwise.
+# Why the most recent remote fetch produced nothing. The skip counter alone
+# said "not fetched" without saying why, so "no budget left" and "the URL is
+# dead" were indistinguishable in the export - and both looked like a bare
+# placeholder to the reader.
+MEDIA_STATE = {'remote_reason': None}
+
 PREFETCH = {'sink': None, 'active': False}
 PREFETCH_WORKERS = 24
 PREFETCH_MAX_URLS = 800
@@ -752,13 +758,13 @@ def shrink_embedded(image, max_side=720, force=False):
         return image
 
 
-def get_cached_image(image_map, local_id, create_time, content='', resource_md5s=None, server_id=0):
-    """Best local media for a message: by content md5, then by identity.
+def resolve_media(image_map, local_id, create_time, content='', resource_md5s=None, server_id=0):
+    """Best local media for a message, with the identity that matched.
 
-    md5 is the strongest key, but it is not always derivable - a group row can
-    lack the resource mapping that carries it. The conversation cache also
-    indexes by `(local_id, create_time)`, which is identity-aware and was
-    already being stored; reading it recovers media the md5 path alone misses.
+    Returns `(base64, mime, media_key)` or None. `media_key` is the image_map
+    key that produced the hit, which is what the coverage report records - so
+    a report can never claim a match the page itself did not get, because both
+    come from this one function.
 
     Deliberately *not* falling back to a bare `local_id`: that id restarts in
     every message shard, so matching on it alone attaches one conversation's
@@ -769,26 +775,40 @@ def get_cached_image(image_map, local_id, create_time, content='', resource_md5s
     if not image_map:
         return None
     for media_md5 in resource_md5s or []:
-        if image_map.get(f'md5:{media_md5}'):
-            return shrink_embedded(image_map[f'md5:{media_md5}'])
+        key = f'md5:{media_md5}'
+        if image_map.get(key):
+            return shrink_embedded(image_map[key]) + (key,)
     for media_md5 in extract_media_md5s(content):
-        if image_map.get(f'md5:{media_md5}'):
-            return shrink_embedded(image_map[f'md5:{media_md5}'])
+        key = f'md5:{media_md5}'
+        if image_map.get(key):
+            return shrink_embedded(image_map[key]) + (key,)
     try:
         pair_key = f'pair:{int(local_id)}:{int(create_time)}'
     except (TypeError, ValueError):
         return None
     if image_map.get(pair_key):
-        return shrink_embedded(image_map[pair_key])
+        return shrink_embedded(image_map[pair_key]) + (pair_key,)
     try:
         unique_key = f'unique:{int(local_id)}'
     except (TypeError, ValueError):
         return None
     if image_map.get(unique_key):
-        return shrink_embedded(image_map[unique_key])
+        return shrink_embedded(image_map[unique_key]) + (unique_key,)
     return None
 
 
+def get_cached_image(image_map, local_id, create_time, content='', resource_md5s=None, server_id=0):
+    """`resolve_media` without the matched key, for every pre-existing caller.
+
+    md5 is the strongest key, but it is not always derivable - a group row can
+    lack the resource mapping that carries it. The conversation cache also
+    indexes by `(local_id, create_time)`, which is identity-aware and was
+    already being stored; reading it recovers media the md5 path alone misses.
+    """
+    hit = resolve_media(image_map, local_id, create_time, content, resource_md5s, server_id)
+    return (hit[0], hit[1]) if hit else None
+
+
 def detect_mime(filepath):
     """Detect MIME type from file header."""
     try:
@@ -918,12 +938,14 @@ def download_image_as_base64(url, aes_key='', timeout=10, budgeted=True):
     already spent their own budget for this URL.
     """
     if not url or not url.startswith(('http://', 'https://')):
+        MEDIA_STATE['remote_reason'] = 'not-http'
         return None
 
     sink = PREFETCH['sink']
     if sink is not None:
         # Dry pass: record the request, spend no budget, touch no network.
         sink.append(('img', url, aes_key))
+        MEDIA_STATE['remote_reason'] = 'deferred-to-prefetch'
         return None
 
     cache_dir = COVER_STATE.get('dir') or ''
@@ -935,11 +957,13 @@ def download_image_as_base64(url, aes_key='', timeout=10, budgeted=True):
     if cached != 'unknown':
         if budgeted:
             COVER_STATE['thumb_cached'] += 1
+        MEDIA_STATE['remote_reason'] = None
         return cached
 
     if budgeted and not PREFETCH['active']:
         if COVER_STATE.get('thumb_budget', 0) <= 0:
             COVER_STATE['thumb_skipped'] += 1
+            MEDIA_STATE['remote_reason'] = 'budget-exhausted'
             return None
         COVER_STATE['thumb_budget'] -= 1
         COVER_STATE['thumb_fetched'] += 1
@@ -956,6 +980,7 @@ def download_image_as_base64(url, aes_key='', timeout=10, budgeted=True):
             # it so the next export does not pay for the same dead URL.
             if len(data) > MAX_EMBED_SIZE:
                 _cache_media(cache_file, None)
+                MEDIA_STATE['remote_reason'] = 'too-large'
                 return None
             candidates = [data]
             decrypted = _decrypt_aes_cbc(data, aes_key)
@@ -969,10 +994,12 @@ def download_image_as_base64(url, aes_key='', timeout=10, budgeted=True):
                     data, mime = wechat_image.shrink(data, mime, max_side=480)
                 result = (base64.b64encode(data).decode(), mime)
                 _cache_media(cache_file, result)
+                MEDIA_STATE['remote_reason'] = None
                 return result
         except Exception:
             continue
     _cache_media(cache_file, None)
+    MEDIA_STATE['remote_reason'] = 'download-failed'
     return None
 
 
@@ -1891,9 +1918,117 @@ def format_message(row, talker, wx_dir, image_map=None, sender_map=None, display
         'local_type': local_type,
         'display': display,
         'image_b64': image_b64,
+        # Built here rather than accumulated in module state: format_message
+        # runs twice (the prefetch dry sweep and the real pass) and the dry
+        # pass is discarded, so a counter would double-count.
+        'media': build_media_record(
+            local_type, image_b64, image_map, local_id, create_time, content,
+            resource_md5s, metadata_content, bool(server_id)),
     }
 
 
+MEDIA_KIND_BY_TYPE = {
+    3: 'image', 34: 'voice', 43: 'video-thumb', 47: 'emoji', 49: 'link-cover',
+}
+MEDIA_KINDS = {'image', 'emoji', 'voice', 'video-thumb', 'link-cover'}
+
+
+def build_media_report(items, scope, talker, per_page):
+    """Coverage summary plus one entry per media item.
+
+    Written beside the HTML rather than into it: the page is for reading, this
+    is for answering "what is missing and why" without opening the export.
+    Paths, keys and message bodies are not included (D-001/D-002/D-025).
+    """
+    counts = {}
+    for item in items:
+        counts[item['status']] = counts.get(item['status'], 0) + 1
+    counts['total'] = len(items)
+    return {
+        'schema': 'weflow-media-report/v1',
+        'source': 'weflow-cli',
+        'generatedAt': datetime.datetime.now().astimezone().isoformat(timespec='seconds'),
+        'scope': scope,
+        'counts': counts,
+        'budget': {
+            'coversFetched': COVER_STATE.get('fetched', 0),
+            'coversCached': COVER_STATE.get('cached', 0),
+            'coversSkipped': COVER_STATE.get('skipped', 0),
+            'thumbsFetched': COVER_STATE.get('thumb_fetched', 0),
+            'thumbsCached': COVER_STATE.get('thumb_cached', 0),
+            'thumbsSkipped': COVER_STATE.get('thumb_skipped', 0),
+        },
+        'items': [
+            {
+                'mediaKey': item['mediaKey'],
+                'kind': item['kind'],
+                'status': item['status'],
+                'mime': item['mime'],
+                'bytes': item['bytes'],
+                'sha256': item['sha256'],
+                'reason': item['reason'],
+                'locator': {
+                    'part': (item['index'] // per_page + 1) if per_page else 1,
+                    'createTime': None,
+                },
+            }
+            for item in items
+        ],
+    }
+
+
+def build_media_record(local_type, image_b64, image_map, local_id, create_time,
+                       content, resource_md5s, metadata_content, has_server_id):
+    """What happened to this message's media, or None for a non-media message.
+
+    Derived from the same `resolve_media` the page used, so the report cannot
+    claim a match the page did not get (or vice versa). A media-free message
+    returns None: this is a media manifest, not a message manifest.
+    """
+    if local_type not in MEDIA_KIND_BY_TYPE:
+        return None
+    kind = MEDIA_KIND_BY_TYPE[local_type]
+    record = {
+        'mediaKey': None, 'kind': kind, 'status': None,
+        'mime': None, 'bytes': None, 'sha256': None, 'reason': None,
+    }
+
+    if image_b64:
+        hit = resolve_media(image_map, local_id, create_time, metadata_content,
+                            resource_md5s)
+        if hit:
+            # Matched a local key: report which one, so "why this image" is
+            # answerable without re-running the export.
+            record['mediaKey'] = hit[2]
+            record['status'] = 'embedded'
+        else:
+            # Bytes came from somewhere other than the conversation index.
+            if MEDIA_STATE['remote_reason'] is None:
+                record['status'] = 'remote-fetched'
+                record['mediaKey'] = 'remote'
+            else:
+                record['status'] = 'embedded'
+                record['mediaKey'] = 'unindexed-local'
+        raw = base64.b64decode(image_b64)
+        record['bytes'] = len(raw)
+        record['sha256'] = hashlib.sha256(raw).hexdigest()
+        return record
+
+    record['status'] = 'missing'
+    if not has_server_id and not extract_media_md5s(metadata_content) and not resource_md5s:
+        # D-014: with no reliable identity there is nothing safe to match on,
+        # and guessing would attach someone else's media.
+        record['reason'] = 'no-reliable-identity'
+    elif kind == 'voice':
+        record['status'] = 'unsupported'
+        record['reason'] = 'voice-not-in-media-index'
+    elif MEDIA_STATE['remote_reason']:
+        record['reason'] = MEDIA_STATE['remote_reason']
+    else:
+        record['reason'] = 'not-in-local-cache'
+    return record
+
+
 def decode_message_content(value):
     """Decode NT message content, which may be Zstandard compressed."""
     if not value:
@@ -2337,6 +2472,7 @@ def main():
 
     print(f"Formatting {len(messages)} messages...")
     formatted = []
+    media_items = []
     img_hit_count = 0
     article_img_count = 0
     progress_step = max(1, len(messages) // 20)
@@ -2348,6 +2484,12 @@ def main():
             img_hit_count += 1
             if result.get('local_type') == 49:
                 article_img_count += 1
+        record = result.get('media')
+        if record:
+            # Index kept so the report can point back at the page part.
+            record = dict(record)
+            record['index'] = i
+            media_items.append(record)
         formatted.append(result)
     print(f"  Messages with embedded images: {img_hit_count} (including {article_img_count} article thumbnails)")
 
@@ -2367,6 +2509,20 @@ def main():
     # Use display name for filename if provided, otherwise fallback to wxid
     file_prefix = sanitize_filename(display_name) if display_name else args.talker.replace('@', '_').replace('/', '_')
 
+    # Media coverage report. Written beside the HTML parts, under the same
+    # prefix, so it is always found next to what it describes.
+    media_report = None
+    media_report_path = None
+    if media_items:
+        media_report = build_media_report(media_items, display_name, args.talker, per_part)
+        media_report_path = os.path.join(args.out, f'{file_prefix}_media.json')
+        with open(media_report_path, 'w', encoding='utf-8') as handle:
+            json.dump(media_report, handle, ensure_ascii=False, indent=2)
+        summary = media_report['counts']
+        missing = summary.get('missing', 0) + summary.get('unsupported', 0)
+        print(f"Media report: {len(media_items)} item(s), {missing} unavailable "
+              f"-> {os.path.basename(media_report_path)}")
+
     html_files = []
     for i in range(parts):
         start = i * per_part
@@ -2395,12 +2551,20 @@ def main():
     print(f"\nDone! {len(html_files)} HTML files written to {args.out}")
     print(f"Total: {total} messages")
 
-    # Print JSON summary for CLI integration
+    # Print JSON summary for CLI integration.
+    # The four original keys are untouched; `media` is purely additive and the
+    # one existing consumer (src/services/exportService.ts) ignores it.
     print(json.dumps({
         "success": True,
         "total": total,
         "parts": len(html_files),
         "files": html_files,
+        "media": ({
+            "schema": "weflow-media-report/v1",
+            "records": len(media_items),
+            "status": media_report['counts'],
+            "report": os.path.basename(media_report_path) if media_report_path else None,
+        } if media_report else None),
     }))
 
 

package/scripts/nt_decrypt.py

@@ -510,14 +510,24 @@ def derive_database_key(path, fallback_key, fallback_salt, passphrase=''):
         return fallback_key, fallback_salt
 
 
-def connect_message_shards(db_path, key_hex, salt_hex, passphrase=''):
-    """Open the configured database plus every sibling shard.
+def connect_message_shards_detailed(db_path, key_hex, salt_hex, passphrase=''):
+    """Open every shard and report what happened to each one.
 
-    Returns the connections that actually opened. A shard that fails is
-    skipped rather than fatal: a partially readable transcript beats a
-    command that refuses to run at all.
+    Returns (pairs, failures):
+      pairs    [(shard_path, conn)] for the shards that opened
+      failures [{"name": basename, "reason": "KEY_REJECTED" | "OPEN_FAILED"}]
+
+    A shard that fails is still skipped rather than fatal - a partially
+    readable transcript beats a command that refuses to run at all - but the
+    failure stops being invisible. `shardsFailed` is the difference between
+    "read everything" and "read what happened to be reachable", which is the
+    whole point of the coverage report.
+
+    Only the basename is reported: the caller stores this in a state file, and
+    absolute paths must not end up there.
     """
-    opened = []
+    pairs = []
+    failures = []
     for shard in discover_message_shards(db_path):
         derived_key, derived_salt = derive_database_key(
             shard, key_hex, salt_hex, passphrase)
@@ -526,16 +536,60 @@ def connect_message_shards(db_path, key_hex, salt_hex, passphrase=''):
         candidates = [(derived_key, derived_salt)]
         if (derived_key, derived_salt) != (key_hex, salt_hex):
             candidates.append((key_hex, salt_hex))
+        failure_reason = 'OPEN_FAILED'
         for candidate_key, candidate_salt in candidates:
+            conn = None
             try:
                 conn, _ = connect_nt_db(shard, candidate_key, candidate_salt)
                 # PRAGMA key alone never fails; only a read surfaces a bad key.
                 conn.execute('SELECT count(*) FROM sqlite_master').fetchone()
             except Exception:
+                # Reached the database but could not decrypt it: the key is
+                # wrong, not the file. Close before retrying, or the handle
+                # leaks and on Windows the file stays locked.
+                if conn is not None:
+                    try:
+                        conn.close()
+                    except Exception:
+                        pass
+                failure_reason = 'KEY_REJECTED'
                 continue
-            opened.append(conn)
+            pairs.append((shard, conn))
             break
-    return opened
+        else:
+            failures.append({'name': os.path.basename(shard), 'reason': failure_reason})
+    return pairs, failures
+
+
+def connect_message_shards(db_path, key_hex, salt_hex, passphrase=''):
+    """Open the configured database plus every sibling shard.
+
+    Returns the connections that actually opened. A shard that fails is
+    skipped rather than fatal: a partially readable transcript beats a
+    command that refuses to run at all.
+
+    Behaviour-preserving delegate: callers that do not ask for the failure
+    detail get exactly what they got before.
+    """
+    pairs, _failures = connect_message_shards_detailed(
+        db_path, key_hex, salt_hex, passphrase)
+    return [conn for _path, conn in pairs]
+
+
+def count_talker_rows(conn, msg_table):
+    """Rows this conversation has in one shard, or None if it has no table there.
+
+    Distinguishes "this shard holds nothing for the conversation" from "this
+    shard could not be read" - without it both look like zero.
+    """
+    try:
+        cur = conn.execute(
+            "SELECT COUNT(*) FROM sqlite_master WHERE name=?", (msg_table,))
+        if cur.fetchone()[0] == 0:
+            return None
+        return conn.execute('SELECT COUNT(*) FROM "%s"' % msg_table).fetchone()[0]
+    except Exception:
+        return None
 
 
 def msg_tables(conn):
@@ -808,12 +862,17 @@ def _message_dict(row, sender_id_map, name_map, own_wxid, is_group=False):
     }
 
 
-def get_messages(conns, talker, limit=100, offset=0, name_map=None, own_wxid=None):
+def get_messages(conns, talker, limit=100, offset=0, name_map=None, own_wxid=None,
+                 shard_names=None, shard_report=None):
     """Get messages for a specific talker, merged across every shard.
 
     Args:
         name_map: optional {wxid: display_name} dict for resolving sender names
         own_wxid: account owner wxid for self-message detection
+        shard_names: optional basename per connection, parallel to `conns`
+        shard_report: optional list to append one outcome dict per shard to.
+            Purely additive: the returned messages are identical with or
+            without it, which is asserted by test/nt_decrypt_shards_test.py.
     """
     if name_map is None:
         name_map = {}
@@ -821,19 +880,36 @@ def get_messages(conns, talker, limit=100, offset=0, name_map=None, own_wxid=Non
     msg_table = f"Msg_{hashlib.md5(talker.encode()).hexdigest()}"
     is_group = '@chatroom' in talker
 
+    def record(index, opened, has_table, rows_for_talker, reason):
+        if shard_report is None:
+            return
+        name = shard_names[index] if shard_names and index < len(shard_names) else ''
+        shard_report.append({
+            'name': name,
+            'opened': opened,
+            'hasTalkerTable': has_table,
+            'rowsForTalker': rows_for_talker,
+            'reason': reason,
+        })
+
     # Each shard only needs to yield its newest window: once every shard's rows
     # are merged and re-sorted, nothing older than that can reach this page.
     window = 0 if limit <= 0 else limit + offset
     collected = []
     found = False
 
-    for conn in conns:
+    for index, conn in enumerate(conns):
         c = conn.cursor()
         try:
             c.execute("SELECT COUNT(*) FROM sqlite_master WHERE name=?", (msg_table,))
             if c.fetchone()[0] == 0:
+                # The shard is readable and simply holds nothing for this
+                # conversation - distinct from not being readable at all.
+                record(index, True, False, None, None)
                 continue
             found = True
+            rows_for_talker = c.execute(
+                'SELECT COUNT(*) FROM "%s"' % msg_table).fetchone()[0]
 
             sql = f'''
                 SELECT local_id, server_id, local_type, sort_seq, real_sender_id,
@@ -852,7 +928,11 @@ def get_messages(conns, talker, limit=100, offset=0, name_map=None, own_wxid=Non
             c.execute("SELECT rowid, user_name FROM Name2Id")
             sender_id_map = {rowid: uname for rowid, uname in c.fetchall()}
         except Exception:
+            # This shard had the conversation's table but could not be read.
+            # Previously this was indistinguishable from "no rows here".
+            record(index, True, None, None, 'READ_FAILED')
             continue
+        record(index, True, True, rows_for_talker, None)
 
         for row in rows:
             collected.append(_message_dict(row, sender_id_map, name_map, own_wxid, is_group))
@@ -1138,6 +1218,9 @@ def main():
     msg_parser.add_argument('--contact-key', default=os.environ.get('WEFLOW_CONTACT_KEY'), help='Contact DB key hex (64 chars)')
     msg_parser.add_argument('--contact-salt', default=os.environ.get('WEFLOW_CONTACT_SALT'), help='Contact DB salt hex (32 chars)')
     msg_parser.add_argument('--own-wxid', default=os.environ.get('WEFLOW_OWN_WXID'), help='Account owner wxid (for self-message detection)')
+    # Opt-in: without it the JSON is byte-identical to before this flag existed.
+    msg_parser.add_argument('--report-shards', action='store_true',
+                            help='Add a per-shard read report to the result (additive)')
 
     # contacts command
     contacts_parser = sub.add_parser('contacts', help='List contacts')
@@ -1282,12 +1365,37 @@ def main():
             conn.close()
 
     elif args.command == 'messages':
-        conns = connect_message_shards(args.db, args.key, args.salt, getattr(args, 'passphrase', '') or '')
-        if not conns:
-            print(json.dumps({"error": "无法打开消息数据库，请检查密钥"}, ensure_ascii=True))
-            return
+        passphrase = getattr(args, 'passphrase', '') or ''
         own_wxid = getattr(args, 'own_wxid', None)
-        result = get_messages(conns, args.talker, args.limit, args.offset, contact_name_map, own_wxid)
+
+        if getattr(args, 'report_shards', False):
+            pairs, failures = connect_message_shards_detailed(
+                args.db, args.key, args.salt, passphrase)
+            if not pairs:
+                print(json.dumps({"error": "无法打开消息数据库，请检查密钥"}, ensure_ascii=True))
+                return
+            conns = [conn for _path, conn in pairs]
+            names = [os.path.basename(path) for path, _conn in pairs]
+            shard_items = []
+            result = get_messages(conns, args.talker, args.limit, args.offset,
+                                  contact_name_map, own_wxid,
+                                  shard_names=names, shard_report=shard_items)
+            # Failure entries carry no opened connection, so they are not in
+            # `conns` and could not be recorded by get_messages itself.
+            result['shards'] = {
+                'scanned': len(pairs) + len(failures),
+                'opened': len(pairs),
+                'failed': len(failures),
+                'items': failures + shard_items,
+            }
+        else:
+            conns = connect_message_shards(args.db, args.key, args.salt, passphrase)
+            if not conns:
+                print(json.dumps({"error": "无法打开消息数据库，请检查密钥"}, ensure_ascii=True))
+                return
+            result = get_messages(conns, args.talker, args.limit, args.offset,
+                                  contact_name_map, own_wxid)
+
         print(json.dumps(result, ensure_ascii=True))
         for conn in conns:
             conn.close()

package/src/core/ntCore.ts

@@ -30,8 +30,28 @@ export interface NtSessionsResult extends NtResult {
   sessions?: ChatSession[]
 }
 
+/** One shard's outcome, as reported by `nt_decrypt.py --report-shards`. */
+export interface ShardOutcome {
+  /** basename only - the child never reports a full path */
+  name: string
+  opened: boolean
+  /** null when the shard could not be read at all */
+  hasTalkerTable: boolean | null
+  rowsForTalker: number | null
+  /** null | KEY_REJECTED | OPEN_FAILED | READ_FAILED */
+  reason: string | null
+}
+
+export interface ShardReport {
+  scanned: number
+  opened: number
+  failed: number
+  items: ShardOutcome[]
+}
+
 export interface NtMessagesResult extends NtResult {
   messages?: Message[]
+  shards?: ShardReport
 }
 
 export interface NtContactsResult extends NtResult {
@@ -282,6 +302,28 @@ export class NtCore {
     return { success: true, messages: result.messages || [] }
   }
 
+  /**
+   * `getMessages` plus the per-shard read report.
+   *
+   * Separate method rather than a flag on `getMessages`: the extra argv token
+   * changes what the child returns, and every existing caller is better off
+   * with the smaller payload it already parses.
+   */
+  async getMessagesWithShards(talker: string, limit = 100, offset = 0): Promise<NtMessagesResult> {
+    const args: string[] = [
+      'messages',
+      '--limit', String(limit),
+      '--offset', String(offset),
+      '--report-shards',
+    ]
+    const ownWxid = configService.get('wxid')
+    const result = await this.callPython(args, { talker, ownWxid })
+    if (result.error) {
+      return { success: false, error: result.error }
+    }
+    return { success: true, messages: result.messages || [], shards: result.shards }
+  }
+
   async getContacts(keyword?: string, limit = 200): Promise<NtContactsResult> {
     const args: string[] = [
       'contacts',

package/src/services/chatService.ts

@@ -3,6 +3,7 @@ import { existsSync } from 'fs'
 import { WcdbCore } from '../core/wcdbCore.js'
 import { SqlcipherCore } from '../core/sqlcipherCore.js'
 import { NtCore } from '../core/ntCore.js'
+import type { ShardReport } from '../core/ntCore.js'
 import { configService } from './configService.js'
 import type { ChatSession, Message, Contact, DataVersion } from '../types.js'
 import { collectMessagesInRange } from './messageQuery.js'
@@ -239,6 +240,31 @@ export class ChatService {
     return []
   }
 
+  /**
+   * Messages plus a per-shard read report, when the backend can produce one.
+   *
+   * Only the NT path (Python) knows about shards. The legacy 3.x, raw-4.x and
+   * WCDB paths return `shards: undefined`, which callers must read as "this
+   * backend cannot tell you" rather than "everything was read" - see
+   * `coverage: 'unverified'` in docs/SYNC_CONTRACT.md.
+   */
+  async getMessagesWithShards(
+    talker: string,
+    limit = 0,
+    offset = 0
+  ): Promise<{ messages: Message[]; shards?: ShardReport }> {
+    const conn = await this.connect()
+    if (!conn.success) return { messages: [] }
+
+    if (this.ntCore) {
+      const result = await this.ntCore.getMessagesWithShards(talker, limit, offset)
+      if (!result.success || !result.messages) return { messages: [] }
+      return { messages: result.messages, shards: result.shards }
+    }
+
+    return { messages: await this.getMessages(talker, limit, offset) }
+  }
+
   async getMessagesInRange(
     talker: string,
     limit = 0,