# manifest.json

## Function

`manifest.json` is the identity and runtime declaration of the extension package. It tells BT: whether this package is a `.bts` extension, what the extension is called, what backend is used to run it, where is the entry file, what is the minimum BT version, what permissions are required, how many parameters and return values are allowed to be transmitted in a single call, and the extension runtime mode.

## Syntax

 Pure BT extension example:

```json
{
    "format": "bts",
    "format_version": 1,
    "name": "calc",
    "version": "1.0.0",
    "description": "calc extension",
    "author": "",
    "kind": "bt",
    "abi": "bts-bt-1",
    "bt_min_version": "1.1.0",
    "api_version": 1,
    "entry": "src/lib.bt",
    "bindings": "bindings.json",
    "permissions": [],
    "limits": {
        "max_args_bytes": 16777216,
        "max_result_bytes": 16777216
    },
    "runtime": {
        "mode": "thread_local"
    }
}
```

 WASM extension only needs to change the backend related fields to:

```json
{
    "kind": "wasm",
    "abi": "bts-wasi-1",
    "entry": "module.wasm"
}
```

WASM shared runtime Configuration example:

```json
{
    "kind": "wasm",
    "abi": "bts-wasi-1",
    "entry": "module.wasm",
    "runtime": {
        "mode": "shared",
        "workers": 4,
        "queue_limit": 1024,
        "call_timeout_ms": 30000,
        "idle_ttl_ms": 300000,
        "max_objects": 65536,
        "max_worker_objects": 4096,
        "max_inflight_calls": 64
    }
}
```

## Parameters

| Field | Type | Description |
| ------ | ------ | ------ |
| `format` | String | Fixed to `bts`. |
| `format_version` | Number | Package format version, use `1`. |
| `name` | String | Extension package name, only lowercase letters, numbers and underscores can be used, and it starts with a lowercase letter. |
| `version` | String | Extend its own version, using three-stage SemVer, such as `1.0.0`. |
| `description` | String | Optional description text. |
| `author` | String | Optional author text. |
| `kind` | String | Backend type, can only be `bt` or `wasm`. |
| `abi` | String | Backend ABI, must match `kind`. |
| `bt_min_version` | String | Minimum BT version required by the extension. |
| `api_version` | Number | bindings semantic version, use `1`. |
| `entry` | String | The relative path within the package of the backend entry file. |
| `bindings` | String | bindings Relative path within the package describing the file. |
| `permissions` | Array | Array of capability permissions of the extended declaration. Only write the required permissions; do not write the unnecessary permissions. |
| `limits` | Object | The upper limit of the parameter and return value encoding size for a single call. |
| `runtime` | Object | Optional runtime mode configuration; default is equivalent to `mode: "thread_local"`. |

## kind and abi

| kind | abi | meaning |
| ------ | ------ | ------ |
| `bt` | `bts-bt-1` | The entry file is BT source code, and the functions and object methods are executed by pure BT Runner. |
| `wasm` | `bts-wasi-1` | The entry file is the WASM module, and the call is completed through WASI P1 and BtValueBinary. |

If `kind` and `abi` do not match, the extension will report an error during the loading phase.

## runtime runtime configuration

| Field | Type | Default value | Description |
| ------ | ------ | ------ | ------ |
| `mode` | String | `thread_local` | Runtime mode, can only be `thread_local` or `shared`. |
| `workers` | Number | `1` | Shared mode worker number, range `1..=64`. |
| `queue_limit` | Number | `1024` | shared mode waiting queue length, range `1..=65536`. |
| `call_timeout_ms` | Number | `30000` | Shared mode single call timeout, range `1..=300000`. |
| `idle_ttl_ms` | Number | `300000` | Shared mode idle retention time, range `1..=3600000`. |
| `max_objects` | Number | `65536` | The upper limit of the number of shared mode service-level objects, range `1..=65536`. |
| `max_worker_objects` | Number | `4096` | The upper limit of the number of objects in a single worker in shared mode is in the range of `1..=4096` and cannot be greater than `max_objects`. |
| `max_inflight_calls` | Number | `64` | The upper limit of the number of calls in shared mode execution, the range is `1..=4096`. |

When `runtime` is missing, the extension continues to use the current thread's local Runner cache and does not change existing extension behavior. The first version of `mode=shared` only allows `kind=wasm`. Pure BT extension declaration shared will report an error during the manifest verification phase.

The current version has been connected to the project level `ExtensionService`. The WASM extension that declares `mode=shared` will create an independent bounded worker queue. The entry function can return the original value or the extended object through the worker; when returning the extended object, the host will allocate `host_object_id` and route back to the local object ID of the worker who created the object before calling the object method. A Chinese error will be returned when the queue is full, the service is shut down, the call during execution exceeds the upper limit, the number of service-level objects or the number of single worker objects exceeds the upper limit.

`call_timeout_ms` does not just call the thread wait limit. The shared worker will enable the Wasmtime epoch interrupt. After the timeout, the host will mark the target worker, trigger the WASM trap, and rebuild the WASM Store/Instance after the worker returns to avoid timeout calls permanently occupying service capacity. Service statistics will include `workers`, `queued`, `running`, `completed`, `failed`, `timed_out`, `objects` and the number of objects per worker.

## Permission Description

| Permission | Description |
| ------ | ------ |
| `fs_read` | Allows declaration of read file path parameters. |
| `fs_write` | Allows declaration of write file path parameters. |
| `net` | Reserved for network communication capability declaration. |
| `http` | Reserved for HTTP client capability declarations. |
| `process` | Reserved for process capability declarations. |
| `env` | Reserved for environment variable capability declarations. |

`permissions` Only string arrays can be used, such as `["fs_read", "fs_write"]`. The permissions must be allowed at the same time as the permission configuration of the running process. The extension declares a certain permission, but when the running process prohibits this capability, the extension will fail to load.

## Return Value

`manifest.json` is not a script function and has no runtime return value. When the verification is successful, BT will continue to read bindings and entry files; when the verification fails, the loading process returns a Chinese error and stops loading the extension.

## Code Examples

 Correspondence between pure BT extension entry and manifest:

```bt
fn calc(value) {
    value
}
```

`manifest.entry` points to `src/lib.bt` containing this source code, `manifest.kind` writes `bt`, `manifest.abi` writes `bts-bt-1`.

## Notes

- `entry` and `bindings` must be safe relative paths within the package. Absolute paths, backslashes, empty paths, `.`, `..` or paths with drive letters cannot be used.
- `entry` cannot point to the same file as `bindings`.
 - `limits.max_args_bytes` and `limits.max_result_bytes` cannot be `0` or exceed the host hard cap.
- Unknown fields cannot appear in `runtime` to prevent extension authors from mistakenly thinking that unimplemented configurations have taken effect.
- `runtime.mode=shared` does not change the BT request variable lifecycle, nor does it allow normal script global variables to be shared across requests.
 - `runtime.mode=shared` already supports extended object host routing; when `close()` or `dispose()` is marked as `lifecycle: "dispose"` and the call succeeds, the host object handle becomes invalid.
- `call_timeout_ms` of `runtime.mode=shared` will trigger the WASM interrupt and running state reconstruction of the target worker, and cannot be used to accurately cancel the long-term blocking host call.
- Extension names, entry names, parameter names and method names should comply with BT's snake_case naming style.