Contracts and startup
skulk_capability_sdk.contracts defines the vocabulary your managed child shares with its host. Treat these types as a versioned boundary, rather than application-specific dictionaries.
Describe one operation
A Descriptor declares an id, semantic version, description, initial/final JSON Schemas, and an explicit I/O mode. Client and bidirectional streams require input chunk schemas; server and bidirectional streams require output chunk schemas. Other modes forbid those chunk schemas. A Manifest groups a bounded set of descriptors with package identity and optional configuration. The host checks the manifest digest during startup.
Keep bundle identity, capability-node identity, transport-node identity, and operation identity distinct. The host retains installation identity across restarts. Several operations may share one node’s settings.
Receive host context
Startup carries the installed identity, paths, bounds, configuration context, and an optional serve_host. Read the bounded startup record through storage.read_startup; do not accept an arbitrary caller-supplied substitute.
The child exchanges typed Hello, Health, Invoke, Result, StreamInvoke, and Shutdown messages. Invoke carries a unary operation; Result carries its outcome. StreamInvoke starts a separately authenticated media connection through Startup.stream_socket. The managed host controls lifecycle and concurrency.
Version and digest rules
PROTOCOL is 4. ACCEPTED_PROTOCOLS is (3, 4). accepted_protocol() raises an actionable error when the selected protocol is outside that window. canonical() returns deterministic bytes; manifest_digest() identifies the complete manifest contract.
Changing an operation’s shape changes its descriptor revision. A breaking behavior change requires a new capability version. A discovery digest identifies the interface; it does not grant authority to execute it.
Bounds
| Boundary | Limit |
|---|---|
| Local IPC message | 64 KiB |
| Canonical manifest | 128 KiB |
| Startup record | Manifest limit plus one frame |
| Active invocation | One per child across all four modes |
| Unary deadline | Up to 30 seconds |
| Streaming deadline | Up to 300 seconds, including cleanup |
| Inline streaming media | 1 MiB per packet; raw bytes after the bounded header |
These managed-protocol limits are distinct from Skulk™’s public capability REST payload limits. Use the applicable contract for the path your integration selects.
Denied describes an operation the policy or ownership contract refused. Uncertain describes an effect whose outcome is not known; do not interpret it as permission to retry an external create.