> Canonical guide: https://developers.foxlight.ai/build/sdk/contracts/
> Contract snapshots: Skulk 2.0.0 (b0af39c79b6b7102b2478062904f1d7cc8619975); SDK 0.4.0 (31bb090b8f64689f87514e48385e22b6ad94a6c2). Check the installed runtime when versions differ.

# 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.

[Contracts API reference](https://developers.foxlight.ai/build/sdk/reference/contracts/)