docs(sdk): add normative invariants to architecture docs

[enyst]

HUMAN: I’ve been thinking for a while that maybe it will help LLMs to

• have a little stricter language in prompts / skills / context; something that avoids “prompting it wrong” : it could be, for example, expressed in or reinforced by constraints in a more formal language
• avoid weird behavior drift when they make PRs: if they have or can have a little better understanding of the relationships between components / classes / packages or intent behind them.

I asked OH to model the first few layers of the SDK (I think it only did the first in-package layer, will come back to that if we want this) and add constraints in both natural language and, if simple enough, in good old OCL.

• I have read and reviewed the documentation changes to the best of my ability.
• If the change is significant, I have run the documentation site locally and confirmed it renders as expected.

——

Summary of changes

• Added "Invariants (Normative)" sections across SDK architecture docs (design, agent, conversation, events, tool system, workspace)

• Included OCL-like invariants where simple and precise natural-language invariants where complex

• Fixed/maintained MDX structure so tables/mermaid blocks render correctly

• closes Analyze the SDK and model it software-agent-sdk#1815

@enyst can click here to continue refining the PR

[openhands-ai]

Looks like there are a few issues preventing this PR from being merged!

• GitHub Actions are failing:
  • .github/workflows/sync-docs-code-blocks.yml
  • .github/workflows/sync-agent-sdk-openapi.yml

If you'd like me to help, just leave a comment, like

@OpenHands please fix the failing actions on PR #274 at branch `openhands/sdk-arch-1815`

Feel free to include any additional details that might help me get this PR into a better state.

_{^{You can manage your notification settings}}