# 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, which backend and entry file it uses, its minimum BT version, its call-size limits, and its runtime mode. Extensions are trusted local program dependencies and do not declare per-package permissions.

## Syntax

 Pure BT extension example:

```json
{
    "format": "bts",
    "format_version": 1,
    "name": "calc",
    "version": "1.0.0",
    "summary": "Calculator extension",
    "description": "calc extension",
    "author": "",
    "developer": {
        "id": "example_team",
        "name": "Example Team",
        "homepage": "https://example.com"
    },
    "repository": "https://github.com/example/calc",
    "license": "MIT",
    "locales": {
        "zh-CN": {
            "summary": "计算器扩展",
            "description": "提供计算功能。",
            "developer_name": "示例团队"
        }
    },
    "kind": "bt",
    "abi": "bts-bt-1",
    "bt_min_version": "1.1.0",
    "api_version": 1,
    "entry": "src/lib.bt",
    "bindings": "bindings.json",
    "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`. |
| `summary` | String | Optional short English catalog summary. |
| `description` | String | Optional description text. |
| `author` | String | Optional author text. |
| `developer` | Object | Optional stable developer identity with `id`, `name`, and optional `homepage`. |
| `repository` | String | Optional public source repository URL. |
| `license` | String | Optional SPDX license expression. |
| `locales` | Object | Optional localized display metadata keyed by canonical BCP 47 tags such as `zh-CN`. |
| `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. |
| `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"`. |

Each `locales.<tag>` object accepts only `summary`, `description`, and `developer_name`. Language keys must use canonical BCP 47 casing; Simplified Chinese is `zh-CN`, matching `README.zh-CN.md`. Localization changes display text only and never changes extension names, API identifiers, configuration fields, or event names.

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

## Return Value

`manifest.json` is not a script function and has no runtime return value. When validation succeeds, BT continues to read bindings and entry files; when validation fails, loading returns an English error and stops.

## 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`.
- The `permissions` field has been removed. A package that still contains it fails manifest validation and must be rebuilt in the new `.bts` format.
- All installed extensions use the same host ABI. Their effective authority follows the BT process-wide policy and operating-system account, not package origin or registry membership.
- Installing an extension means trusting its code. The official catalog reviews only the exact open-source versions it distributes; local, private, modified, and closed-source packages remain unrestricted and outside that review.
- `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.