docs(sdk): add normative invariants to architecture docs

[enyst]

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

• 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.
• see stricter language: reinforce intent by constraints in a more formal language. Here, OCL, an invariant-expressions language complementing UML - probably forgotten by humans, but LLMs know it. (and I think maybe it's simple enough to read as English)

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, 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-agent-sdk-openapi.yml
  • .github/workflows/sync-docs-code-blocks.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}}

[enyst]

@OpenHands The trouble with this PR is that it displays our OCL constraints in the user-facing docs, but they are meant for AI agents, not for humans.

I think we have two options:

• either insert them as html comments or something that is invisible to the user, but accessible to LLMs when AI agents read the pages
• or, maybe we can create / modify / fix llms.txt and the full variant of it, so that it includes those sections, but the user-facing docs doesn't. (look up on the net the llms.txt emerging standard to see what it should work like)

WDYT? Answer me directly on github, in a comment you post to this PR. Note that it will be rendered as markdown.

[openhands-ai]

I'm on it! enyst can track my progress at all-hands.dev

[openhands-ai]

I did not make any repository changes in this interaction. I answered the PR comment question by recommending how to handle the OCL constraints so they’re available to AI agents but not shown in user-facing docs:

• Prefer option 1 as the immediate fix: keep the natural-language invariants visible, but move the OCL blocks into HTML comments (non-rendered) with clear sentinels like <!-- AI_INVARIANTS_BEGIN --> ... <!-- AI_INVARIANTS_END --> so agents can reliably extract them.
• Treat llms.txt / llms-full.txt as a potential follow-up packaging step (useful long-term, but adds maintenance/drift considerations), not the primary solution.
• I provided a ready-to-paste Markdown PR comment expressing that recommendation.

No git diff to review, no commits, and nothing to push.