docs: add public API compatibility matrix

[CleanDev-Fix]

Description

Adds a source-backed public API compatibility matrix for Aegis SDK consumers.
It maps the package's root and testing entry points, module/export stability,
companion-contract dependencies and current drift, planned dashboard adapter
targets, and pre-1.0 breaking-change rules. The README now links directly to
the matrix.

This approach keeps the change documentation-only while making cross-repo
assumptions reviewable. It also distinguishes repository contract
specifications from proof of any deployed contract interface.

Files changed:

• docs/public-api-compatibility.md — new compatibility contract, matrices,
  drift snapshot, dashboard target, breaking-change rules, and reviewer list.
• README.md — link and integration guidance for the matrix.

Closes: #152

---

Evidence Checklist

1. Issue Reference

• This PR references a tracked issue (Closes #152).
• The linked issue's acceptance criteria are copied into Section 6 below.

2. Implementation Summary

• A clear description of what changed is provided above.
• The documentation-only, cross-repository rationale is included.
• All modified and added files are listed above.

3. Tests

• No public method or runtime behavior changed, so no unit-test changes are
  applicable.
• The existing full release gate was run to catch build, test, or package
  compatibility regressions.
• Focused checks covered required export/contract terms, relative links,
  Markdown tables, and whitespace.

4. Commands Run

npm ci
npm run check
git diff --check

Command output

> @aegis/sdk@0.1.0 check
> npm run build && npm test -- --runInBand && npm run test:compat

> @aegis/sdk@0.1.0 build
> tsc

> @aegis/sdk@0.1.0 test
> jest --runInBand

PASS tests/client-factory.test.ts
PASS tests/mock-client.test.ts
PASS tests/role.test.ts
PASS tests/investor.test.ts
PASS tests/events-decoder.test.ts
PASS tests/admin-receipts.test.ts
PASS tests/config.test.ts
PASS tests/network-failures.test.ts
PASS tests/events-module.test.ts
PASS tests/mock-client-examples.test.ts
PASS tests/client.test.ts

Test Suites: 11 passed, 11 total
Tests:       117 passed, 117 total
Snapshots:   0 total
Time:        4.401 s
Ran all test suites.

> @aegis/sdk@0.1.0 test:compat
> node scripts/check-compat.mjs

Browser compatibility: bundle resolved without Node-only imports.
Node compatibility: public SDK entrypoint and signer initialized.

git diff --check: PASS
Focused documentation checks: PASS

5. CI Status

• All GitHub Actions checks pass on this PR.
• No CI failure is currently known; this box remains unchecked until the
  hosted checks run.

6. Acceptance Criteria Coverage — Traceability Table

#	Acceptance Criterion	SDK Module(s)	Test(s)	Doc(s)	Behaviour Verification
1	Public API compatibility matrix is added.	Package root and testing entry points	Focused Markdown/link checks	docs/public-api-compatibility.md	New matrix exists and its local link resolves.
2	Major SDK exports are listed.	AegisClient, client factories, six modules, helpers, types, errors, and testing surface	npm run check; source-to-matrix QA	Matrix package/module/export sections	Compared with src/index.ts, src/testing/index.ts, and package.json#exports.
3	Contract dependencies are documented.	Compliance, asset, investor, role, and event modules	Source/contract cross-check QA	Matrix contract dependency column and compatibility snapshot	Entrypoint alignment, partial wiring, and drift/gaps are explicit.
4	Dashboard consumers are referenced.	Planned provider, investor, auth, transaction, and diagnostics adapters	Live dashboard path cross-check QA	Matrix dashboard-target column and integration-target section	Dashboard is accurately labelled as a planned adapter target with no current package dependency.
5	Breaking-change guidance is included.	All public entry points, methods, types, errors, events, and protocol meanings	Reviewer checklist QA	Matrix breaking-change rules	Breaking categories, versioning, migration, tests, and cross-repo review are specified.
6	README links to the matrix.	Documentation entry point	Local-link check	README.md	Link resolves to docs/public-api-compatibility.md.

---

Reviewer Notes

Please pay particular attention to the rows marked Preview, especially the
investor balance entrypoint, role discovery, and event-topic parity. The
matrix documents current drift; this PR does not change runtime behavior or
claim that a repository specification proves a deployed interface.