160 lines
5.2 KiB
Markdown
160 lines
5.2 KiB
Markdown
# 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:
|
|
|
|
```json
|
|
{
|
|
"protocol": "isphere.msglib.v1",
|
|
"request_id": "example-1",
|
|
"op": "self_check",
|
|
"args": {}
|
|
}
|
|
```
|
|
|
|
Response envelope:
|
|
|
|
```json
|
|
{
|
|
"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`.
|
|
|
|
## 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 first contract returns schema, columns, counts, and display-source availability only.
|
|
- It does not return message bodies, contact row values, file paths, 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.
|
|
|
|
## Verification
|
|
|
|
Default verification builds and checks `self_check` only:
|
|
|
|
```powershell
|
|
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:
|
|
|
|
```powershell
|
|
$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
|
|
```
|