isphere-ai-bridge/docs/msglib-read-sidecar-contract.md

MsgLib read-only sidecar contract

Date: 2026-07-10

Purpose

MsgLibReadSidecar is the bounded 32-bit .NET process used by the Go MCP layer to access copied or operator-local MsgLib.db files through the client-compatible System.Data.SQLite provider.

It exists because C26 proved the database opens with the bundled 32-bit SQLite provider and password 123, while a 64-bit probe fails at provider loading. Go should coordinate the process; the sidecar owns only the narrow Windows/.NET DB read boundary.

Protocol

• Protocol id: isphere.msglib.v1
• Transport: one JSON request on stdin, one JSON response on stdout.
• Process architecture: x86.
• Database mode: read-only only.
• Raw rows: not returned by the first contract.
• Message bodies: not returned by the first contract.
• DB mutation: never allowed.

Request envelope:

{
  "protocol": "isphere.msglib.v1",
  "request_id": "example-1",
  "op": "self_check",
  "args": {}
}

Response envelope:

{
  "protocol": "isphere.msglib.v1",
  "request_id": "example-1",
  "op": "self_check",
  "ok": true,
  "data": {},
  "error": null,
  "warnings": []
}

Operations

self_check

Returns sidecar identity, protocol, runtime, process bitness, and capability flags.

Key response fields:

• sidecar_name
• sidecar_version
• protocol
• runtime
• process_bits
• requires_process_bits
• db_mutation_allowed=false
• message_body_reads_allowed=false

schema_summary

Validates provider load and read-only DB open, then returns schema metadata only.

Required args:

• sqlite_dll_path: path to bundled System.Data.SQLite.dll.
• db_path: path to a copied/operator-local MsgLib.db.

Optional args:

• password: default 123.
• include_counts: default true; returns row counts only for target tables.
• max_tables: default 128, clamped to 1..256.
• target_tables: optional list; defaults to known display/message/file metadata tables.

Returned data:

• metadata_only=true
• read_only=true
• message_body_values_returned=false
• sqlite_version
• tables: table/view names only.
• columns: table column names/types only.
• target_row_counts: safe row counts for target tables only.

display_sources

Same safe provider/DB validation as schema_summary, but additionally maps schema availability to product-facing display source candidates.

Returned data adds:

• display_sources[] entries with:
  • source
  • table
  • available
  • required_columns
  • present_columns

Initial display sources:

• contacts_roster from TD_Roster.
• contacts_effigy from TD_CustomEffigy.
• recent_display from tblRecent.
• person_message_names from tblPersonMsg.
• group_message_names from tblMsgGroupPersonMsg.
• work_group_auth from TD_WorkGroupAuth.
• received_file_metadata from TD_ReceiveFileRecord.
• sent_file_metadata from TD_SendFileRecord.

display_entities

Same safe provider/DB validation as display_sources, but returns bounded normalized contact/group display metadata.

Required args:

• sqlite_dll_path
• db_path
• entity_type: contacts or groups

Optional args:

• password: default 123.
• query: optional string matched against allowlisted jid/name columns.
• limit: bounded to 1..100; default 25.

Returned data adds:

• metadata_only=true
• read_only=true
• message_body_values_returned=false
• raw_rows_returned=false
• entities[] entries with:
  • entity_type
  • source_table
  • jid
  • display_name
  • confidence
  • matched_columns

Initial allowlisted identity sources:

• Contacts: TD_Roster(JId,Nick), TD_CustomEffigy(PersonJid,PersonName), tblRecent(PersonId,PersonName), tblChatLevel(PersonId,PersonName), selected tblPersonMsg id/name pairs only.
• Groups: TD_WorkGroupAuth(GroupJID,GroupName), TD_WorkGroupAuth(ChildGroupJid,GroupName), selected tblMsgGroupPersonMsg group/session id/name pairs only.

Security and scope rules

• The sidecar must open DB files with read-only connection settings.
• db_path must point to a file named MsgLib.db.
• The schema/display-source operations return schema, columns, counts, and display-source availability only.
• display_entities may return bounded contact/group jid and display_name metadata only.
• It does not return message bodies, message text, file paths, attachment contents, or raw row sets.
• It does not implement send, file download, mark-read, login, hooks, injection, or DB writes.
• The Go MCP layer remains the coordinator; this process is a bounded local reader.

Current implementation

Committed C27 implementation:

• Source: native/MsgLibReadSidecar/.
• Build script: scripts/build-msglib-sidecar.ps1.
• Verification script: scripts/verify-msglib-sidecar.ps1.
• Default verification builds an x86 executable and checks self_check.
• Evidence-backed verification with C26 paths checked provider load/read-only DB open and returned 8 display-source candidates.

Go client wrapper

Committed C28 implementation:

• Source: internal/msglib/.
• ConfigFromEnv reads ISPHERE_MSGLIB_SIDECAR_EXE, ISPHERE_MSGLIB_SQLITE_DLL, ISPHERE_MSGLIB_DB, and optional ISPHERE_MSGLIB_PASSWORD.
• NewClient creates a process-backed client for protocol isphere.msglib.v1.
• SelfCheck calls self_check and decodes sidecar identity, protocol, bitness, and read-only/no-mutation flags.
• DisplaySources calls display_sources and decodes display-source availability metadata.
• The client uses stdin/stdout JSON, request ids, context.Context, per-call timeout, stderr capture, and typed SidecarError values.
• Unit tests use a fake sidecar process; normal tests do not require real System.Data.SQLite.dll or copied MsgLib.db.
• C28 does not register a new MCP tool and does not return message bodies, file paths, raw rows, contact row values, or group row values.

Committed C29 implementation:

• Sidecar op: display_entities.
• Go wrapper: DisplayEntities(ctx, DisplayEntitiesOptions).
• Verification script calls display_entities only when copied DB env paths are supplied, and prints only sanitized entity_count plus source_tables summaries.
• Evidence-backed C29 verification against the copied DB returned contact/group entity counts and source-table names without printing entity values.
• C31 adds optional scripts/verify-msglib-mcp-enrichment.ps1 to prove MCP-level contact/group enrichment through the real sidecar while printing only counts and msglib:<source_table> refs.

Verification

Default verification builds and checks self_check only:

powershell -NoProfile -ExecutionPolicy Bypass -File scripts\verify-msglib-sidecar.ps1

Evidence-backed provider verification is opt-in through environment variables and should use copied DB files only. The script also verifies display_sources and sanitized display_entities summaries when these variables are present:

$env:ISPHERE_MSGLIB_SQLITE_DLL = "<path-to-System.Data.SQLite.dll>"
$env:ISPHERE_MSGLIB_DB = "<path-to-copied-MsgLib.db>"
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\verify-msglib-sidecar.ps1