SDK Contract¶

This page defines the supported SDK contract for application developers.

Contract Scope¶

Applies to:

SDK/lib/p1std
SDK/lib/p1window
SDK/lib/cstd
SDK/template/p1start-app

Supported Today¶

Static user ELF applications (no_std + alloc)
WM client development through p1window/p1std
Syscall/runtime access through cstd
Custom target workflow via SDK/toolchain/x86_64-unknown-p1start.json

Not Supported As Production Contract¶

Dynamic linking (.so, DT_NEEDED, runtime symbol resolution)
General-purpose multithreaded app model as stable SDK behavior
POSIX-grade filesystem permission semantics
Full memory-hardening expectations (ASLR/W^X-style guarantees)

See Dynamic Linking Contract for the phase-by-phase runtime policy, supported relocation list, error codes, and acceptance criteria.
Dynamic linking is currently in phase-1 experimental implementation (including in-QEMU smoke-pass validation), but remains unsupported as production SDK contract.

Compatibility Rules¶

Breaking changes in p1std/p1window public API require:
- migration note,
- template update,
- docs update in the same change set.
Wire-level changes that affect app-facing WM behavior must be documented in:
- reference/wm-v1-platform-roadmap
- this SDK contract page if developer behavior changes.

API Layering Rules¶

Preferred layer for app windows/events/present: p1window (or via p1std re-export).
Raw cstd::p1ui is allowed for unsupported edge-cases, but should not be default app code.
Large graphical buffers should use mmap-backed helpers (p1_alloc_framebuffer path).

Minimal Acceptance Checklist For New SDK Features¶

Every new SDK feature must include:

compile check on target toolchain,
one template or sample usage,
one troubleshooting note,
one docs update in platform-docs/docs/.

Relationship To Canonical Contracts¶

If this page conflicts with newdocs/, follow newdocs/ first, then reconcile this page immediately.